Merge remote-tracking branch 'origin/main' into feat/claw-update-available-image-tag

Author: St0rmz1

.env.test

@@ -79,7 +79,6 @@ STRIPE_KILOCLAW_EARLYBIRD_COUPON_ID=coupon_test_kiloclaw_earlybird
 STRIPE_KILOCLAW_COMMIT_PRICE_ID=price_test_kiloclaw_commit
 STRIPE_KILOCLAW_STANDARD_PRICE_ID=price_test_kiloclaw_standard
 STRIPE_KILOCLAW_STANDARD_FIRST_MONTH_COUPON_ID=coupon_test_kiloclaw_standard_first_month
-STRIPE_KILOCLAW_BILLING_START=
 
 # Stripe publishable key for client-side 3DS authentication
 NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_invalid_mock_key

.specs/kiloclaw-billing.md

@@ -4,6 +4,7 @@
 
 Draft -- generated from branch `jdp/kiloclaw-billing` on 2026-03-13.
 Updated 2026-03-19 -- pricing and trial duration changes.
+Updated 2026-03-20 -- promotional codes and introductory pricing.
 
 ## Conventions
 
@@ -42,6 +43,22 @@ lapses, with email notifications at each stage.
 7. The system MUST fail with an error at checkout time if a required
    plan price identifier is not configured.
 
+### Standard Plan Introductory Pricing
+
+1. New standard plan subscribers who do not have a prior canceled paid
+   subscription MUST receive an introductory price for their first
+   billing period. A canceled trial does not count as a prior paid
+   subscription. Returning subscribers with a previously canceled paid
+   subscription MUST receive the regular standard price.
+2. The system MUST automatically transition introductory-price
+   subscribers to the regular standard price at the end of the
+   introductory billing period.
+3. The automatic price transition MUST be transparent to the user: it
+   MUST NOT appear as a pending plan switch in billing status and MUST
+   NOT prevent the user from initiating a plan switch or canceling.
+4. Failure to set up the automatic price transition during subscription
+   creation MUST NOT block checkout completion.
+
 ### Trial Eligibility and Creation
 
 1. A trial MUST only be created automatically when a user provisions an
@@ -81,21 +98,18 @@ lapses, with email notifications at each stage.
 2. The system MUST allow checkout when the existing subscription status
    is trialing or canceled.
 3. The system MUST verify with the payment provider that no subscription
-   in active or trialing (delayed-billing) status already exists for the
-   customer before creating a new checkout session, to guard against
-   concurrent checkouts. This check does not cover provider-side
-   subscriptions in past-due status.
-4. The system MUST NOT allow promotional codes for either plan.
-5. The system MUST apply a provider-configured first-month discount
-   coupon when creating a standard plan checkout session.
-6. When a configurable billing start date is set and is in the future,
-   the system MUST create the subscription with a delayed billing period
-   that begins on that date.
-7. When the billing start date is unset or is in the past, the system
-   MUST start billing immediately with no delayed period.
-8. The system SHOULD include referral tracking data in checkout sessions
+   in active or trialing status already exists for the customer before
+   creating a new checkout session, to guard against concurrent
+   checkouts. This check does not cover provider-side subscriptions in
+   past-due status.
+4. The system MUST allow promotional codes on checkout for both plans.
+5. For standard plan checkout, the system MUST use the introductory
+   price when the user has no prior canceled paid subscription, and the
+   regular price when the user has a previously canceled paid
+   subscription (see Standard Plan Introductory Pricing).
+6. The system SHOULD include referral tracking data in checkout sessions
    when a referral cookie is present.
-9. The system SHOULD attempt to expire open checkout sessions tagged as
+7. The system SHOULD attempt to expire open checkout sessions tagged as
    KiloClaw before creating a new checkout session, so users who
    abandoned a previous checkout can start fresh. Expiration is
    best-effort: errors from the payment provider (e.g. the session was
@@ -111,9 +125,8 @@ lapses, with email notifications at each stage.
    the subscription to the standard plan.
 2. When a commit subscription is created, the system MUST record a
    commit-period end date six calendar months from the billing start.
-   When a delayed-billing period is configured, the six months MUST
-   start from the delayed-billing end date, not from subscription
-   creation.
+   For pre-launch subscriptions that had a delayed-billing trial_end,
+   the six months starts from that trial boundary.
 3. When a subscription update is received and the commit-period end
    date is in the past, the system MUST extend it by six calendar
    months from the previous boundary, keeping the subscription on the
@@ -145,21 +158,35 @@ lapses, with email notifications at each stage.
    the commit-period end date to six calendar months from the
    transition date.
 8. The system MUST allow cancellation of user-initiated plan switches.
+9. The system MUST reject a plan switch if a user-initiated plan switch
+   is already pending.
+10. If an automatic price transition is pending when the user requests a
+    plan switch, the system MUST replace the automatic transition with
+    the user's requested switch.
+11. After canceling a user-initiated plan switch, if the subscription is
+    still on the introductory price, the system MUST restore the
+    automatic price transition. Failure to restore the transition MUST
+    NOT prevent the switch cancellation from succeeding.
 
 ### Cancellation and Reactivation
 
 1. The system MUST reject a cancellation request if no active
    subscription with a payment provider ID exists.
 2. The system MUST reject a cancellation request if cancellation is
    already pending.
-3. When canceling a subscription that has a pending schedule, the system
-   MUST release the schedule before setting the cancel-at-period-end
-   flag.
+3. When canceling a subscription that has a pending schedule — whether
+   a user-initiated plan switch or an automatic price transition — the
+   system MUST release the schedule before setting the
+   cancel-at-period-end flag.
 4. Cancellation MUST NOT terminate access immediately; access MUST
    continue until the current billing period ends.
 5. The system MUST allow reactivation of a subscription that is pending
    cancellation.
 6. On reactivation, the system MUST clear the cancel-at-period-end flag.
+7. On reactivation, if the subscription is still on the introductory
+   price, the system MUST restore the automatic price transition.
+   Failure to restore the transition MUST NOT prevent the reactivation
+   from succeeding.
 
 ### Billing Lifecycle Background Job
 
@@ -169,6 +196,9 @@ lapses, with email notifications at each stage.
 2. Each sweep in the background job MUST process users independently;
    a failure for one user MUST NOT prevent processing of other users.
 3. All errors during sweep processing MUST be captured for monitoring.
+4. The background job MUST detect active subscriptions on the
+   introductory price that have no automatic price transition pending
+   and MUST set up the missing transition.
 
 ### Trial Expiry Warnings
 
@@ -258,8 +288,9 @@ lapses, with email notifications at each stage.
 ### Payment Provider Status Mapping
 
 1. When the payment provider reports a subscription as "trialing"
-   (delayed billing), the system MUST map this to active status
-   internally, since delayed billing is not a product-level trial.
+   (e.g. pre-launch delayed billing), the system MUST map this to
+   active status internally, since delayed billing is not a
+   product-level trial.
 2. When the payment provider reports "incomplete" or "paused" status,
    the system MUST map these to terminal statuses (unpaid or canceled
    respectively).
@@ -299,6 +330,28 @@ lapses, with email notifications at each stage.
 
 ### Changelog
 
+#### 2026-03-21 -- Remove delayed-billing start date
+
+- Removed configurable billing start date (`STRIPE_KILOCLAW_BILLING_START`)
+  and associated checkout rules (former rules 6–7). New subscriptions now
+  always bill immediately.
+- Pre-launch subscriptions created with a delayed `trial_end` are still
+  handled correctly; the trialing→active status mapping remains until those
+  subscriptions transition.
+
+#### 2026-03-20 -- Promotional codes and introductory pricing
+
+Previous values:
+
+- Standard plan first-month discount: coupon applied at checkout
+- Promotional codes: not allowed on either plan
+
+New values:
+
+- Standard plan first-month discount: introductory price with automatic
+  transition to regular price at period end
+- Promotional codes: allowed on both plans at checkout
+
 #### 2026-03-19 -- Pricing and trial changes
 
 Previous values:

AGENTS.md

@@ -52,3 +52,7 @@ When creating or updating a pull request, you **must** follow the PR template in
 - Do not leave HTML comments from the template in the final description — replace them with actual content.
 - PR descriptions must be accurate and valuable to reviewers. Generic or boilerplate descriptions waste reviewer time.
 - Review all commits on the branch (not just the latest) when writing the summary.
+
+## KiloClaw Billing
+
+Before making **any** changes related to KiloClaw billing — including bug fixes, new features, refactors, or reviews — you **must** first read the billing spec at `.specs/kiloclaw-billing.md`. This applies to all code paths that touch billing logic, pricing, invoicing, usage metering, or payment flows.

cloud-agent-next/wrapper/src/connection.ts

@@ -273,6 +273,28 @@ export function createConnectionManager(
     return false;
   }
 
+  function getTerminalErrorText(eventType: string, properties: Record<string, unknown>): string {
+    const error = properties.error;
+    if (typeof error === 'string') {
+      return error;
+    }
+
+    if (isRecord(error)) {
+      if (typeof error.message === 'string') {
+        return error.message;
+      }
+
+      const data = error.data;
+      if (isRecord(data) && typeof data.message === 'string') {
+        return data.message;
+      }
+
+      return JSON.stringify(error);
+    }
+
+    return `Insufficient credits: ${eventType}`;
+  }
+
   /**
    * Start the SDK event subscription. Runs in the background.
    * Replaces the old SSE consumer with a typed event stream from the SDK.
@@ -367,7 +389,7 @@ export function createConnectionManager(
 
           // Terminal error detection
           if (isTerminalError(eventType, properties)) {
-            callbacks.onTerminalError(eventType);
+            callbacks.onTerminalError(getTerminalErrorText(eventType, properties));
             return;
           }
 

cloudflare-gastown/container/src/process-manager.ts

@@ -368,12 +368,20 @@ async function handleIdleEvent(agent: ManagedAgent, onExit: () => void): Promise
     return;
   }
 
-  // No nudges (or fetch error) — (re)start the idle timeout
+  // No nudges (or fetch error) — (re)start the idle timeout.
+  // Refineries get a longer timeout because their workflow is multi-step
+  // (diff → analyze → decide → merge/rework). The 2-min default kills the
+  // session between LLM turns when the refinery responds with text before
+  // issuing a tool call. See #1342.
   clearIdleTimer(agentId);
   const timeoutMs =
-    process.env.AGENT_IDLE_TIMEOUT_MS !== undefined
-      ? Number(process.env.AGENT_IDLE_TIMEOUT_MS)
-      : 120_000;
+    agent.role === 'refinery'
+      ? process.env.REFINERY_IDLE_TIMEOUT_MS !== undefined
+        ? Number(process.env.REFINERY_IDLE_TIMEOUT_MS)
+        : 600_000
+      : process.env.AGENT_IDLE_TIMEOUT_MS !== undefined
+        ? Number(process.env.AGENT_IDLE_TIMEOUT_MS)
+        : 120_000;
 
   console.log(
     `${MANAGER_LOG} handleIdleEvent: no nudges for ${agentId}, idle timeout in ${timeoutMs}ms`

cloudflare-gastown/src/dos/Town.do.ts

@@ -1103,6 +1103,24 @@ export class TownDO extends DurableObject<Env> {
     this.broadcastAgentStatus(agentId, message);
   }
 
+  /** Test-only: directly set dispatch_attempts (and optionally last_activity_at) for an agent. */
+  async setAgentDispatchAttempts(
+    agentId: string,
+    attempts: number,
+    lastActivityAt?: string
+  ): Promise<void> {
+    query(
+      this.sql,
+      /* sql */ `
+        UPDATE ${agent_metadata}
+        SET ${agent_metadata.columns.dispatch_attempts} = ?,
+            ${agent_metadata.columns.last_activity_at} = COALESCE(?, ${agent_metadata.columns.last_activity_at})
+        WHERE ${agent_metadata.bead_id} = ?
+      `,
+      [attempts, lastActivityAt ?? null, agentId]
+    );
+  }
+
   // ══════════════════════════════════════════════════════════════════
   // Mail
   // ══════════════════════════════════════════════════════════════════

cloudflare-gastown/src/dos/town/reconciler.ts

@@ -969,6 +969,27 @@ export function reconcileReviewQueue(sql: SqlStorage): Action[] {
   for (const ref of idleRefineries) {
     if (!ref.current_hook_bead_id) continue;
 
+    // Cooldown: skip if last activity is too recent (#1342)
+    if (!staleMs(ref.last_activity_at, DISPATCH_COOLDOWN_MS)) continue;
+
+    // Circuit-breaker: fail the MR bead after too many attempts (#1342)
+    if (ref.dispatch_attempts >= MAX_DISPATCH_ATTEMPTS) {
+      actions.push({
+        type: 'transition_bead',
+        bead_id: ref.current_hook_bead_id,
+        from: null,
+        to: 'failed',
+        reason: 'refinery max dispatch attempts exceeded',
+        actor: 'system',
+      });
+      actions.push({
+        type: 'unhook_agent',
+        agent_id: ref.bead_id,
+        reason: 'max dispatch attempts',
+      });
+      continue;
+    }
+
     const mrRows = z
       .object({ status: z.string(), type: z.string(), rig_id: z.string().nullable() })
       .array()

cloudflare-gastown/src/dos/town/review-queue.ts

@@ -722,13 +722,20 @@ export function agentCompleted(
     }
   }
 
-  // Mark agent idle
+  // Mark agent idle.
+  // For refineries, preserve dispatch_attempts so Rule 6's circuit-breaker
+  // can track cumulative re-dispatch attempts across idle→dispatch cycles.
+  // Resetting to 0 here was enabling infinite loops (#1342). Non-refineries
+  // reset to 0 because they unhook above and get a fresh counter on hookBead.
   query(
     sql,
     /* sql */ `
       UPDATE ${agent_metadata}
       SET ${agent_metadata.columns.status} = 'idle',
-          ${agent_metadata.columns.dispatch_attempts} = 0
+          ${agent_metadata.columns.dispatch_attempts} = CASE
+            WHEN ${agent_metadata.columns.role} = 'refinery' THEN ${agent_metadata.columns.dispatch_attempts}
+            ELSE 0
+          END
       WHERE ${agent_metadata.bead_id} = ?
     `,
     [agentId]

cloudflare-gastown/src/dos/town/scheduling.ts

@@ -133,16 +133,21 @@ export async function dispatchAgent(
     });
 
     if (started) {
-      // Best-effort: may be dropped if I/O gate is closed
-      query(
-        ctx.sql,
-        /* sql */ `
-          UPDATE ${agent_metadata}
-          SET ${agent_metadata.columns.dispatch_attempts} = 0
-          WHERE ${agent_metadata.bead_id} = ?
-        `,
-        [agent.id]
-      );
+      // Reset dispatch_attempts on successful start — but NOT for refineries.
+      // Refineries can loop (idle-timeout → re-dispatch) many times on the
+      // same MR bead, so we keep the counter monotonically increasing until
+      // the bead is closed or the agent hooks a new bead (#1342).
+      if (agent.role !== 'refinery') {
+        query(
+          ctx.sql,
+          /* sql */ `
+            UPDATE ${agent_metadata}
+            SET ${agent_metadata.columns.dispatch_attempts} = 0
+            WHERE ${agent_metadata.bead_id} = ?
+          `,
+          [agent.id]
+        );
+      }
       console.log(`${LOG} dispatchAgent: started agent=${agent.name}(${agent.id})`);
       ctx.emitEvent({
         event: 'agent.spawned',