Merge branch 'main' into florian/chore/event-log

Author: pandemicsyn

.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/src/dos/Town.do.ts

@@ -240,7 +240,11 @@ export class TownDO extends DurableObject<Env> {
   }
 
   private emitEvent(data: Omit<GastownEventData, 'userId' | 'delivery'>): void {
-    writeEvent(this.env, { ...data, delivery: 'internal', userId: this._ownerUserId });
+    writeEvent(this.env, {
+      ...data,
+      delivery: 'internal',
+      userId: this._ownerUserId,
+    });
   }
 
   /** Build the context object used by the scheduling sub-module. */
@@ -290,7 +294,9 @@ export class TownDO extends DurableObject<Env> {
           });
         }
 
-        return scheduling.dispatchAgent(schedulingCtx, agent, bead, { systemPromptOverride });
+        return scheduling.dispatchAgent(schedulingCtx, agent, bead, {
+          systemPromptOverride,
+        });
       },
       stopAgent: async agentId => {
         await dispatch.stopAgentInContainer(this.env, this.townId, agentId);
@@ -677,7 +683,9 @@ export class TownDO extends DurableObject<Env> {
       const townConfig = await this.getTownConfig();
       if (!townConfig.kilocode_token || townConfig.kilocode_token !== rigConfig.kilocodeToken) {
         console.log(`${TOWN_LOG} configureRig: propagating kilocodeToken to town config`);
-        await this.updateTownConfig({ kilocode_token: rigConfig.kilocodeToken });
+        await this.updateTownConfig({
+          kilocode_token: rigConfig.kilocodeToken,
+        });
       }
     }
 
@@ -1214,10 +1222,14 @@ export class TownDO extends DurableObject<Env> {
    * Return undelivered, non-expired nudges for an agent.
    * Urgent nudges are returned first, then FIFO within same priority.
    */
-  async getPendingNudges(
-    agentId: string
-  ): Promise<
-    { nudge_id: string; message: string; mode: string; priority: string; source: string }[]
+  async getPendingNudges(agentId: string): Promise<
+    {
+      nudge_id: string;
+      message: string;
+      mode: string;
+      priority: string;
+      source: string;
+    }[]
   > {
     const rows = [
       ...query(
@@ -1768,7 +1780,12 @@ export class TownDO extends DurableObject<Env> {
 
   /** Build the rig list for mayor agent startup (browse worktree setup on fresh containers). */
   private async rigListForMayor(): Promise<
-    Array<{ rigId: string; gitUrl: string; defaultBranch: string; platformIntegrationId?: string }>
+    Array<{
+      rigId: string;
+      gitUrl: string;
+      defaultBranch: string;
+      platformIntegrationId?: string;
+    }>
   > {
     const rigRecords = rigs.listRigs(this.sql);
     return Promise.all(
@@ -1792,7 +1809,10 @@ export class TownDO extends DurableObject<Env> {
     message: string,
     _model?: string,
     uiContext?: string
-  ): Promise<{ agentId: string; sessionStatus: 'idle' | 'active' | 'starting' }> {
+  ): Promise<{
+    agentId: string;
+    sessionStatus: 'idle' | 'active' | 'starting';
+  }> {
     const townId = this.townId;
 
     let mayor = agents.listAgents(this.sql, { role: 'mayor' })[0] ?? null;
@@ -1876,7 +1896,10 @@ export class TownDO extends DurableObject<Env> {
    * Called eagerly on page load so the terminal is available immediately
    * without requiring the user to send a message first.
    */
-  async ensureMayor(): Promise<{ agentId: string; sessionStatus: 'idle' | 'active' | 'starting' }> {
+  async ensureMayor(): Promise<{
+    agentId: string;
+    sessionStatus: 'idle' | 'active' | 'starting';
+  }> {
     const townId = this.townId;
 
     let mayor = agents.listAgents(this.sql, { role: 'mayor' })[0] ?? null;
@@ -2250,7 +2273,10 @@ export class TownDO extends DurableObject<Env> {
     tasks: Array<{ title: string; body?: string; depends_on?: number[] }>;
     merge_mode?: 'review-then-land' | 'review-and-merge';
     staged?: boolean;
-  }): Promise<{ convoy: ConvoyEntry; beads: Array<{ bead: Bead; agent: Agent | null }> }> {
+  }): Promise<{
+    convoy: ConvoyEntry;
+    beads: Array<{ bead: Bead; agent: Agent | null }>;
+  }> {
     // Resolve staged: explicit request wins, otherwise fall back to town config default.
     const townConfig = await this.getTownConfig();
     const isStaged = input.staged ?? townConfig.staged_convoys_default;
@@ -2449,9 +2475,10 @@ export class TownDO extends DurableObject<Env> {
   /**
    * Transition a staged convoy to active: hook agents and begin dispatch.
    */
-  async startConvoy(
-    convoyId: string
-  ): Promise<{ convoy: ConvoyEntry; beads: Array<{ bead: Bead; agent: Agent | null }> }> {
+  async startConvoy(convoyId: string): Promise<{
+    convoy: ConvoyEntry;
+    beads: Array<{ bead: Bead; agent: Agent | null }>;
+  }> {
     const convoy = this.getConvoy(convoyId);
     if (!convoy) throw new Error(`Convoy not found: ${convoyId}`);
     if (!convoy.staged) throw new Error(`Convoy is not staged: ${convoyId}`);
@@ -2994,9 +3021,14 @@ export class TownDO extends DurableObject<Env> {
       const violations = reconciler.checkInvariants(this.sql);
       metrics.invariantViolations = violations.length;
       if (violations.length > 0) {
-        console.error(
-          `${TOWN_LOG} [reconciler:invariants] town=${townId} ${violations.length} violation(s): ${JSON.stringify(violations)}`
-        );
+        // Emit as an analytics event for observability dashboards instead
+        // of console.error (which spams Workers logs every 5s per town).
+        this.emitEvent({
+          event: 'reconciler.invariant_violations',
+          townId,
+          label: violations.map(v => `[${v.invariant}] ${v.message}`).join('; '),
+          value: violations.length,
+        });
       }
     } catch (err) {
       console.warn(`${TOWN_LOG} [reconciler:invariants] town=${townId} check failed`, err);
@@ -3575,7 +3607,13 @@ export class TownDO extends DurableObject<Env> {
         []
       ),
     ];
-    const beadCounts = { open: 0, inProgress: 0, inReview: 0, failed: 0, triageRequests: 0 };
+    const beadCounts = {
+      open: 0,
+      inProgress: 0,
+      inReview: 0,
+      failed: 0,
+      triageRequests: 0,
+    };
     for (const row of beadRows) {
       const s = `${row.status as string}`;
       const c = Number(row.cnt);

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

@@ -546,11 +546,20 @@ export function touchAgent(
     activeTools?: string[];
   }
 ): void {
+  // A heartbeat is proof the agent is alive in the container.
+  // If the agent's status is 'idle' (e.g. due to a dispatch timeout
+  // race — see #1358), restore it to 'working'. This prevents the
+  // reconciler from treating the agent as lost while it's actively
+  // sending heartbeats.
   query(
     sql,
     /* sql */ `
       UPDATE ${agent_metadata}
       SET ${agent_metadata.columns.last_activity_at} = ?,
+          ${agent_metadata.columns.status} = CASE
+            WHEN ${agent_metadata.columns.status} = 'idle' THEN 'working'
+            ELSE ${agent_metadata.columns.status}
+          END,
           ${agent_metadata.columns.last_event_type} = COALESCE(?, ${agent_metadata.columns.last_event_type}),
           ${agent_metadata.columns.last_event_at} = COALESCE(?, ${agent_metadata.columns.last_event_at}),
           ${agent_metadata.columns.active_tools} = COALESCE(?, ${agent_metadata.columns.active_tools})