@coreplane/switchboard 1.253.0 → 1.254.0

package/dist/assets/config/config.example.yaml

@@ -11,6 +11,13 @@ providers:
   anthropic:
     wire: anthropic-messages
     apiKeyEnv: ANTHROPIC_API_KEY
+    # The biller's invoice for the daily tie-out on the costs page (costs.md item
+    # 4d): each block may name its own invoice API and the env var holding that
+    # API's key — an admin or management key, never the inference key. This is
+    # where `costs.anthropicAdminKeyEnv` moved; the old key under `costs:` is
+    # still accepted for one release.
+    # invoiceApi: anthropic-cost-report   # GET /v1/organizations/cost_report
+    # invoiceKeyEnv: ANTHROPIC_ADMIN_KEY  # sk-ant-admin…
   # OpenAI itself runs on its Responses API (record 0052): every first-party
   # OpenAI card in pi's registry is `openai-responses`, OpenAI recommends the
   # wire for new projects, and its chat route loses tool calling with any
@@ -21,6 +28,8 @@ providers:
     wire: openai-responses
     baseUrl: https://api.openai.com/v1
     apiKeyEnv: OPENAI_API_KEY
+    # invoiceApi: openai-costs            # GET /v1/organization/costs, an admin key
+    # invoiceKeyEnv: OPENAI_ADMIN_KEY
   # groq:
   #   wire: openai-chat
   #   baseUrl: https://api.groq.com/openai/v1
@@ -42,6 +51,10 @@ providers:
     catalog: openrouter
     baseUrl: https://openrouter.ai/api/v1
     apiKeyEnv: OPENROUTER_API_KEY
+    # invoiceApi: openrouter-activity     # GET /api/v1/activity, a management key;
+    #                                     #   its `usage` ties against the summed BYOK
+    #                                     #   fees, `byok_usage_inference` the remainder
+    # invoiceKeyEnv: OPENROUTER_MANAGEMENT_KEY
     # The operator's layer over the registry card: what a run needs that no
     # layer names goes out unvouched (and a note says so on the record) until
     # an override like this pins it. `providers check` (a later unit) reads the
@@ -462,16 +475,17 @@ workspaceDir: ./workspaces
 # `tool` (default) forces a call to the router's `route` tool, whose schema is
 # the answer, so prose cannot occur; `text` is the one-JSON-object text contract
 # alone — set it for a provider or model that cannot take a forced tool call.
-# `operator` is the one door's flag (routing-and-config item 29): `off`
-# (default) — the operator never runs; `shadow` — one operator turn per
-# admitted chat event, ahead of stage A, its decision written beside the
-# routed request in the run store and nothing run from it; `on` — the
-# operator's decision is what runs. `shadow` runs even under `auto: false`.
+# `operator` is the one door's flag (routing-and-config item 29): `on`
+# (default) — the operator's decision is what runs; `shadow` — one operator
+# turn per admitted chat event, ahead of stage A, its decision written beside
+# the routed request in the run store and nothing run from it; `off` — the
+# rollback lever: it turns the operator back off after a bad day, not a choice
+# to make up front. `shadow` and `on` run even under `auto: false`.
 # routing:
 #   auto: false
 #   model: anthropic/claude-haiku-4-5
 #   answer: text
-#   operator: shadow
+#   operator: off
 
 # The thread-reply intake gate (docs/decisions/0058-a-thread-reply-is-read-before-it-is-answered-intake-decides-whether-the-bot-was-addressed.md;
 # docs/reference/specs/routing-and-config.md item 27). How an unmentioned reply
@@ -493,6 +507,19 @@ workspaceDir: ./workspaces
 #   threadReplies: classify
 #   model: anthropic/claude-haiku-4-5
 
+# The orchestration plane (docs/decisions/0064-the-plane-owns-every-runs-state-a-refusal-becomes-a-queue-position-an-ending-is-judged-by-the-ledger-that-saw-it-and-a-release-is-a-quiet-window-a-person-closes.md;
+# docs/reference/specs/routing-and-config.md item 31; orchestration-plane.md).
+# `admission` gates the ledger object's queue decider: `off` (default) — the
+# plane hears of no dispatch and nothing is posted; `shadow` — the bot posts
+# its own outcome per dispatch (`proceeded`, `refused:<code>`) to the ledger
+# object, which logs its decider's decision beside it — nothing runs from the
+# decider; `on` — a later release's flip (the decider's answer is what runs).
+# `reaskMinutes` (default 2) is the plane's one re-ask cadence, used only while
+# something waits on a reporter that fell silent; nothing reads it yet.
+# plane:
+#   admission: shadow
+#   reaskMinutes: 2
+
 # Linked threads (docs/decisions/0037-a-linked-thread-is-quoted-not-joined.md;
 # docs/reference/specs/routing-and-config.md item 22). Off by default. On, a
 # permalink in a request to a thread in another PUBLIC channel the bot is a
@@ -508,7 +535,8 @@ workspaceDir: ./workspaces
 #   cloudflareAccountId: <32-hex account id>
 #   cloudflareAccountName: acme-infra              # optional: how the page names the account beside its share (else the id's first hex)
 #   cloudflareTokenEnv: CF_ANALYTICS_TOKEN     # token with Account Analytics:Read
-#   anthropicAdminKeyEnv: ANTHROPIC_ADMIN_KEY  # optional: sk-ant-admin… for LLM spend
+#   anthropicAdminKeyEnv: ANTHROPIC_ADMIN_KEY  # legacy (one release): moved to providers.anthropic.invoiceKeyEnv
+#                                              #   (invoiceApi: anthropic-cost-report); still feeds the LLM line here
 #   snapshot:                                  # the page serves a snapshot of both billing sources, never a live read;
 #     everyHours: 24                           #   how often the bot reads them (1–168, default 24). `costs snapshot`
 #                                              #   takes one now. Kept on the state Worker any `*.worker` block names
@@ -536,12 +564,13 @@ workspaceDir: ./workspaces
 # Run metrics (docs/reference/specs/run-metrics.md). Optional. The Analytics Engine
 # dataset every finished run's point lands in — the SAME name the deployment
 # profile's `metrics.dataset` binds on the state Worker as RUN_METRICS (the bot
-# warns at boot when the two differ; neither side refuses to start). The reader
-# over the dataset — `metrics trend` and the /metrics page, behind the `metrics`
-# capability — is later work of the same decision; until it lands, only `dataset`
-# is read, for that boot comparison.
+# warns at boot when the two differ; neither side refuses to start). With the
+# `costs` block's Cloudflare account and analytics token this turns the `metrics`
+# capability on: `metrics trend` reads the trend report from the dataset over the
+# Analytics Engine SQL API, weighted for sampling.
 # metrics:
 #   dataset: switchboard_runs
+#   days: 30                                  # optional: the default report range in whole UTC days, 1..90
 
 # Delivery indicators: GET /delivery and `delivery report` (docs/reference/specs/delivery.md).
 # Optional. Needs a GitHub credential (the App triple or GH_TOKEN); read-only on GitHub.

package/dist/assets/deploy/cloudflare-memory/worker.ts

@@ -78,6 +78,18 @@ import {
   selectReclaim,
 } from "../../src/core/runLedger/decisions.ts";
 import { intakeReceiptRetentionMs } from "../../src/core/budgets.ts";
+import {
+  decide,
+  planeAskWordOf,
+  type PlaneAckOutcome,
+  type PlaneEffect,
+  type PlaneEvent,
+  type PlaneOutcomePost,
+  type PlaneQueueRow,
+  type PlaneStage,
+  type PlaneState,
+  type PlaneWrite,
+} from "../../src/core/plane/decide.ts";
 import {
   IDEMPOTENCY_KEY_PATTERN,
   capThreadEvent,
@@ -1206,13 +1218,16 @@ export class CostsSnapshotDO extends DurableObject<Env> {
     `);
   }
 
-  /** Replace the snapshot whole: every part rewritten in one transaction. */
+  /** Replace the snapshot whole: every part rewritten in one transaction. Each
+   *  logical part is its own named row — `invoices` included, never a rest-spread
+   *  into the meta row that would silently absorb future fields. */
   async put(snapshot: CostsSnapshot): Promise<void> {
-    const { usage, llm, runUsage, ...meta } = snapshot;
+    const { usage, llm, invoices, runUsage, ...meta } = snapshot;
     const rows: Array<[string, unknown]> = [
       ["meta", meta],
       ...USAGE_PARTS.map((name): [string, unknown] => [`usage.${name}`, usage[name]]),
       ["llm", llm],
+      ...(invoices !== undefined ? [["invoices", invoices] as [string, unknown]] : []),
       ["runUsage", runUsage],
     ];
     this.ctx.storage.transactionSync(() => {
@@ -1237,10 +1252,12 @@ export class CostsSnapshotDO extends DurableObject<Env> {
       return body === undefined ? undefined : (JSON.parse(body) as unknown);
     };
     const usage = Object.fromEntries(USAGE_PARTS.map((name) => [name, read(`usage.${name}`)]));
+    const invoices = read("invoices");
     const snapshot = {
       ...(JSON.parse(meta) as Record<string, unknown>),
       usage,
       llm: read("llm"),
+      ...(invoices !== undefined ? { invoices } : {}),
       runUsage: read("runUsage"),
     };
     return isCostsSnapshot(snapshot) ? snapshot : null;
@@ -1514,7 +1531,20 @@ function rowToLive(r: LiveRow): LiveRunRow {
   };
 }
 
-type HeartbeatAnswer = FenceResult & { stop?: StopMode | null; phase?: LivePhase };
+type HeartbeatAnswer = FenceResult & { stop?: StopMode | null; phase?: LivePhase; effects?: PlaneEffect[] };
+
+/** Whether the bot's outcome and the decider's word agree (orchestration-plane item 8): `proceeded`
+ *  beside `proceed`, and a thread-live refusal beside `queued` — the refusal
+ *  IS the queue position the plane would hold. `null` for a pair the decider
+ *  does not model yet: logged, never counted. */
+function planeAgreementOf(outcome: string, decider: "proceed" | "queued"): boolean | null {
+  if (outcome === "proceeded") return decider === "proceed";
+  if (outcome === "refused:thread-live") return decider === "queued";
+  return null;
+}
+
+/** The most effects one answer carries (record 0064; orchestration-plane item 7): the rest ride the next heartbeat. */
+const PLANE_EFFECTS_PER_ANSWER = 32;
 
 export class RunHistoryDO extends DurableObject<Env> {
   private readonly sql: SqlStorage;
@@ -1681,6 +1711,215 @@ export class RunHistoryDO extends DurableObject<Env> {
         PRIMARY KEY (instance_id, unit, seq)
       );
     `);
+    // The orchestration plane's tables (record 0064; orchestration-plane.md item 7):
+    // the queue with its conditions, the reservations, the quiet and pressure
+    // windows, the watches' findings, the offered effects and the residents'
+    // levels. This unit opens them all so a later Worker and an earlier one agree on
+    // the schema; only the queue and the effects are written yet.
+    this.sql.exec(`
+      CREATE TABLE IF NOT EXISTS plane_queue (
+        run_id TEXT PRIMARY KEY,
+        requester TEXT NOT NULL,
+        thread_key TEXT NOT NULL,
+        stage TEXT NOT NULL,
+        request_json TEXT NOT NULL,
+        conditions_json TEXT NOT NULL,
+        position_at INTEGER NOT NULL,
+        queued_at INTEGER NOT NULL,
+        state TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS plane_queue_waiting ON plane_queue(state, queued_at);
+      CREATE TABLE IF NOT EXISTS plane_reservations (
+        kind TEXT NOT NULL,
+        key TEXT NOT NULL,
+        run_id TEXT NOT NULL,
+        at INTEGER NOT NULL,
+        PRIMARY KEY (kind, key)
+      );
+      CREATE TABLE IF NOT EXISTS plane_windows (
+        kind TEXT NOT NULL,
+        key TEXT NOT NULL,
+        phase TEXT NOT NULL,
+        opened_at INTEGER NOT NULL,
+        reason_json TEXT NOT NULL,
+        PRIMARY KEY (kind, key)
+      );
+      CREATE TABLE IF NOT EXISTS plane_findings (
+        id TEXT PRIMARY KEY,
+        watch TEXT NOT NULL,
+        subject TEXT NOT NULL,
+        timeline_json TEXT NOT NULL,
+        filed_at INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS plane_effects (
+        id TEXT PRIMARY KEY,
+        body_json TEXT NOT NULL,
+        offered_at INTEGER NOT NULL,
+        acked_at INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS plane_effects_open ON plane_effects(acked_at, offered_at);
+      CREATE TABLE IF NOT EXISTS plane_levels (
+        resident TEXT NOT NULL,
+        name TEXT NOT NULL,
+        side TEXT NOT NULL,
+        reported_at INTEGER NOT NULL,
+        generation TEXT NOT NULL,
+        PRIMARY KEY (resident, name)
+      );
+    `);
+  }
+
+  // ---- the orchestration plane (record 0064; orchestration-plane.md) ----------
+
+  /** The decider's state, read inside the caller's `transactionSync`: the
+   *  queue oldest first and the threads a live row holds. `excludeRunId` drops
+   *  that run's own live row from the view — a shadow post judged after the
+   *  dispatch it describes claimed the thread must not read its own claim as
+   *  "thread live" (orchestration-plane item 8). */
+  private planeState(excludeRunId?: string): PlaneState {
+    const queue = this.sql
+      .exec<{
+        run_id: string;
+        requester: string;
+        thread_key: string;
+        stage: string;
+        request_json: string;
+        conditions_json: string;
+        position_at: number;
+        queued_at: number;
+        state: string;
+      }>(`SELECT * FROM plane_queue ORDER BY queued_at ASC, run_id ASC`)
+      .toArray()
+      .map((r): PlaneQueueRow => ({
+        runId: r.run_id,
+        requester: r.requester,
+        threadKey: r.thread_key,
+        stage: r.stage as PlaneStage,
+        request: JSON.parse(r.request_json) as Record<string, unknown>,
+        conditions: JSON.parse(r.conditions_json) as PlaneQueueRow["conditions"],
+        position: r.position_at,
+        queuedAt: r.queued_at,
+        state: r.state as PlaneQueueRow["state"],
+      }));
+    const liveThreads = this.sql
+      .exec<{ thread_key: string }>(`SELECT thread_key FROM live_runs WHERE run_id IS NOT ?`, excludeRunId ?? null)
+      .toArray()
+      .map((r) => r.thread_key);
+    return { queue, liveThreads };
+  }
+
+  /** The decider's writes, applied inside the same `transactionSync` that read
+   *  the state — the decision and its consequences land together (orchestration-plane item 6). */
+  private applyPlaneWrites(writes: PlaneWrite[]): void {
+    for (const w of writes) {
+      if (w.table === "plane_queue" && w.op === "put") {
+        this.sql.exec(
+          `INSERT OR REPLACE INTO plane_queue
+             (run_id, requester, thread_key, stage, request_json, conditions_json, position_at, queued_at, state)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+          w.row.runId,
+          w.row.requester,
+          w.row.threadKey,
+          w.row.stage,
+          JSON.stringify(w.row.request),
+          JSON.stringify(w.row.conditions),
+          w.row.position,
+          w.row.queuedAt,
+          w.row.state,
+        );
+      } else if (w.table === "plane_queue" && w.op === "state") {
+        this.sql.exec(`UPDATE plane_queue SET state = ? WHERE run_id = ?`, w.state, w.runId);
+      } else {
+        // An offer keeps its first `offered_at`: a re-decided admit after a
+        // roll is the same effect, not a younger one.
+        this.sql.exec(
+          `INSERT OR IGNORE INTO plane_effects (id, body_json, offered_at, acked_at) VALUES (?, ?, ?, NULL)`,
+          w.effect.id,
+          JSON.stringify(w.effect),
+          w.at,
+        );
+      }
+    }
+  }
+
+  /** Apply one plane event: state read, decider, writes and effects in ONE
+   *  `transactionSync` (orchestration-plane item 6). The transport unit's routes feed it; the tests pin the atomicity. */
+  planeApply(event: PlaneEvent): { effects: PlaneEffect[] } {
+    let effects: PlaneEffect[] = [];
+    this.ctx.storage.transactionSync(() => {
+      const decision = decide(this.planeState(), event);
+      this.applyPlaneWrites(decision.writes);
+      effects = decision.effects;
+    });
+    return { effects };
+  }
+
+  /** The unacknowledged effects, oldest first, at most `PLANE_EFFECTS_PER_ANSWER`
+   *  (orchestration-plane item 7) — what every heartbeat and reclaim answer carries. Public: the
+   *  reclaim route composes it beside the runs it took. */
+  openPlaneEffects(): PlaneEffect[] {
+    return this.sql
+      .exec<{ body_json: string }>(
+        `SELECT body_json FROM plane_effects WHERE acked_at IS NULL ORDER BY offered_at ASC, id ASC LIMIT ?`,
+        PLANE_EFFECTS_PER_ANSWER,
+      )
+      .toArray()
+      .map((r) => JSON.parse(r.body_json) as PlaneEffect);
+  }
+
+  /** Shadow (orchestration-plane item 8): the bot's own outcome for one dispatch, judged beside the
+   *  decider's word for the same ask. Nothing runs and nothing queues from
+   *  the decider here — the comparison is logged, and a disagreement bumps a
+   *  per-condition counter in `meta` for the `plane disagreements` line. An
+   *  outcome the decider does not model yet (an allowlist refusal, a cold
+   *  fall) is logged uncounted. The post is fired without an await, so it can
+   *  arrive AFTER the dispatch it describes claimed this thread's `live_runs`
+   *  row; a post carrying the run's own id excludes that row from the live
+   *  view so the run's own claim never reads as a false disagreement. */
+  planeOutcome(
+    post: PlaneOutcomePost,
+    now: number,
+  ): { ok: true; decider: "proceed" | "queued"; agreed: boolean | null } {
+    let decider: "proceed" | "queued" = "proceed";
+    let agreed: boolean | null = null;
+    this.ctx.storage.transactionSync(() => {
+      const ask: PlaneEvent = {
+        kind: "ask",
+        at: now,
+        runId: post.runId ?? `ask:${post.threadKey}:${now}`,
+        requester: post.requester,
+        threadKey: post.threadKey,
+        stage: post.stage,
+        request: {},
+      };
+      decider = planeAskWordOf(decide(this.planeState(post.runId), ask), ask.runId);
+      agreed = planeAgreementOf(post.outcome, decider);
+      if (agreed === false) this.bumpPlaneDisagreement("thread_free");
+    });
+    console.log(
+      `[plane/outcome] ${post.threadKey} ${post.stage} bot=${post.outcome} decider=${decider} agreed=${agreed ?? "uncompared"}`,
+    );
+    return { ok: true, decider, agreed };
+  }
+
+  /** The per-condition disagreement counts (orchestration-plane item 8), kept in `meta` so the table's
+   *  later `plane disagreements` line can read them. */
+  private bumpPlaneDisagreement(condition: string): void {
+    const row = this.sql
+      .exec<{ value: string }>(`SELECT value FROM meta WHERE key = 'plane_disagreements'`)
+      .toArray()[0];
+    const counts = row ? (JSON.parse(row.value) as Record<string, number>) : {};
+    counts[condition] = (counts[condition] ?? 0) + 1;
+    this.sql.exec(`INSERT OR REPLACE INTO meta (key, value) VALUES ('plane_disagreements', ?)`, JSON.stringify(counts));
+  }
+
+  /** An effect's acknowledgement by id (orchestration-plane item 7): `done` and `skipped` close it,
+   *  `deferred` leaves it offered for the next answer. An unknown id is a
+   *  no-op — the bot may ack an effect an older table never held. */
+  planeAck(id: string, outcome: PlaneAckOutcome, now: number): { ok: true } {
+    if (outcome !== "deferred")
+      this.sql.exec(`UPDATE plane_effects SET acked_at = ? WHERE id = ? AND acked_at IS NULL`, now, id);
+    return { ok: true };
   }
 
   // ---- the coordinator's parent records (run-history item 49) -----------------
@@ -1969,7 +2208,10 @@ export class RunHistoryDO extends DurableObject<Env> {
         return;
       }
       this.sql.exec(`UPDATE live_runs SET lease_until = ? WHERE run_id = ?`, now + leaseMs, runId);
-      out = { ok: true, stop: row.stop, phase: row.phase };
+      // The plane's open effects ride every owner's heartbeat answer (record
+      // 0064; orchestration-plane item 7) — empty until a unit writes them, but always present, so the
+      // client's ack loop needs no version probe.
+      out = { ok: true, stop: row.stop, phase: row.phase, effects: this.openPlaneEffects() };
     });
     return out;
   }
@@ -3931,6 +4173,60 @@ const LEDGER_ROUTES = new Set([
   "/runs/session/notepad/write",
 ]);
 
+/** The plane's routes (record 0064; orchestration-plane items 7 and 8): the shadow outcome post and the
+ *  effect acknowledgement. Both land on the ledger object of the given store
+ *  key, like every `/runs/*` route. */
+const PLANE_ROUTES = new Set(["/plane/outcome", "/plane/ack"]);
+
+const PLANE_STAGES = new Set(["admission", "runner", "resident"]);
+const PLANE_OUTCOME = /^(proceeded|refused:[a-z0-9-]+|fell_cold:[a-z0-9_-]+)$/;
+const PLANE_ACK_OUTCOMES = new Set(["done", "skipped", "deferred"]);
+
+/** The `/plane/*` routes: validated before any object call, ids and words
+ *  only on the log lines. */
+async function handlePlane(pathname: string, body: unknown, env: Env): Promise<Response> {
+  if (typeof body !== "object" || body === null) return json({ error: "body must be a JSON object" }, 400);
+  const b = body as Record<string, unknown>;
+  const key = parseStoreKey(b);
+  if (!key.ok) return json({ error: key.error }, 400);
+  const stub = env.RUNS.get(env.RUNS.idFromName(key.value));
+  const now = systemClock();
+  if (pathname === "/plane/outcome") {
+    if (typeof b.threadKey !== "string" || b.threadKey.length === 0)
+      return json({ error: "threadKey must be a non-empty string" }, 400);
+    if (typeof b.requester !== "string" || b.requester.length === 0)
+      return json({ error: "requester must be a non-empty string" }, 400);
+    if (typeof b.stage !== "string" || !PLANE_STAGES.has(b.stage))
+      return json({ error: "stage must be admission, runner or resident" }, 400);
+    if (typeof b.outcome !== "string" || !PLANE_OUTCOME.test(b.outcome))
+      return json({ error: "outcome must be proceeded, refused:<code> or fell_cold:<token>" }, 400);
+    let runId: string | undefined;
+    if (b.runId !== undefined) {
+      const parsed = parseRunId(b.runId);
+      if (!parsed.ok) return json({ error: parsed.error }, 400);
+      runId = parsed.value;
+    }
+    const r = await stub.planeOutcome(
+      {
+        ...(runId !== undefined ? { runId } : {}),
+        requester: b.requester,
+        threadKey: b.threadKey,
+        stage: b.stage as PlaneStage,
+        outcome: b.outcome,
+      },
+      now,
+    );
+    return json(r);
+  }
+  if (pathname === "/plane/ack") {
+    if (typeof b.id !== "string" || b.id.length === 0) return json({ error: "id must be a non-empty string" }, 400);
+    if (typeof b.outcome !== "string" || !PLANE_ACK_OUTCOMES.has(b.outcome))
+      return json({ error: "outcome must be done, skipped or deferred" }, 400);
+    return json(await stub.planeAck(b.id, b.outcome as PlaneAckOutcome, now));
+  }
+  return json({ error: "not found" }, 404);
+}
+
 /** Routes whose bodies may carry a record, a transcript chunk, or an event batch. */
 const WIDE_BODY_ROUTES = new Set([
   "/runs/put",
@@ -4237,7 +4533,9 @@ async function handleLedger(pathname: string, body: unknown, env: Env): Promise<
     // declared shape.
     const runs = (await stub.reclaim(g.value, at, lease.value)) as unknown as ReclaimedRun[];
     console.log(`[runs/reclaim] ${key.value} ${g.value} took ${runs.length} run(s)`);
-    return json({ runs });
+    // The reclaim sweep's answer carries the plane's open effects like every
+    // heartbeat answer does (record 0064; orchestration-plane item 7) — empty until a unit writes them.
+    return json({ runs, effects: await stub.openPlaneEffects() });
   }
   if (pathname === "/runs/handoff") {
     const g = gen(b.gen);
@@ -4372,7 +4670,10 @@ async function handleLedger(pathname: string, body: unknown, env: Env): Promise<
   if (pathname === "/runs/heartbeat") {
     const lease = parseLeaseMs(b.leaseMs);
     if (!lease.ok) return json({ error: lease.error }, 400);
-    const r = await stub.heartbeat(runId.value, g.value, lease.value, now);
+    // The RPC type mapping reads the effects' open-ended `request` JSON as
+    // unserializable; the values are plain JSON, so the cast only restores the
+    // declared shape (as the reclaim route's does).
+    const r = (await stub.heartbeat(runId.value, g.value, lease.value, now)) as unknown as HeartbeatAnswer;
     return r.ok ? json(r) : json(r, 409);
   }
   if (pathname === "/runs/append") {
@@ -4504,6 +4805,7 @@ const ROUTES = new Set([
   "/runs/usage",
   "/runs/delete",
   ...LEDGER_ROUTES,
+  ...PLANE_ROUTES,
 ]);
 
 /** The two decisions `fetch` makes once and hands down: is the path one of
@@ -4519,7 +4821,7 @@ interface Admission {
  *  dataset (run-metrics.md item 5) — the name from the `RUN_METRICS_DATASET`
  *  var rendered beside the binding, so the probe can compare it to the bot's. */
 export function featuresOf(env: Pick<Env, "RUN_METRICS" | "RUN_METRICS_DATASET">): string[] {
-  const features = ["memory", "schedules", "runs", "config", "delivery", "costs"];
+  const features = ["memory", "schedules", "runs", "config", "delivery", "costs", "plane"];
   if (env.RUN_METRICS !== undefined) features.push(`runMetrics:${env.RUN_METRICS_DATASET ?? "unknown"}`);
   return features;
 }
@@ -4578,6 +4880,7 @@ async function handleRequest(request: Request, env: Env, admission: Admission):
     return json({ firings });
   }
   if (url.pathname.startsWith("/runs/")) return handleRuns(url.pathname, body, env);
+  if (url.pathname.startsWith("/plane/")) return handlePlane(url.pathname, body, env);
   if (url.pathname.startsWith("/config/")) return handleConfig(url.pathname, body, env);
   if (url.pathname.startsWith("/delivery/")) return handleDelivery(url.pathname, body, env);
   if (url.pathname.startsWith("/costs/")) return handleCosts(url.pathname, body, env);

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "switchboard",
-  "version": "1.253.0",
+  "version": "1.254.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "switchboard",
-      "version": "1.253.0",
+      "version": "1.254.0",
       "license": "Apache-2.0",
       "workspaces": [
         "web",
@@ -20445,7 +20445,7 @@
     },
     "packages/switchboard": {
       "name": "@coreplane/switchboard",
-      "version": "1.253.0",
+      "version": "1.254.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@earendil-works/pi-ai": "0.85.1",

package/dist/assets/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchboard",
-  "version": "1.253.0",
+  "version": "1.254.0",
   "private": true,
   "description": "Mention it in Slack and an agent reviews the PR, ships the fix, or answers the question — on the model you choose, with its tools running where you decide.",
   "license": "Apache-2.0",

package/dist/assets/source.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.253.0",
-  "commit": "c96eda5a0bced3e6e6347180846163cc19b28c49",
-  "builtAt": "2026-09-19T15:36:27.120Z"
+  "version": "1.254.0",
+  "commit": "c554204338614ad3882f8e59654806c2a5a61aa9",
+  "builtAt": "2026-09-19T19:46:00.046Z"
 }

package/dist/assets/src/core/authz/grants.ts

@@ -60,6 +60,12 @@ export const CHAT_OPEN_ACTIONS: readonly string[] = [
   "schedule:read",
   "memory:write",
   "mcp:write",
+  // `steer.run` (chat-only): the door admits every chat user because the real
+  // fence is the steer OWNER rule at the wired sender — the named run's
+  // requester, an id their identity record links, or a `runs:write` grant
+  // (authorization item 16a) — which the command door cannot see. Never held
+  // by a token: the machine surfaces have `send_to_run` and the ingress.
+  "steer:write",
 ];
 
 /** The two writes a browser session holds beside its reads (record 0043): the

package/dist/assets/src/core/authz/policy.ts

@@ -58,6 +58,11 @@ export const POLICY: readonly Rule[] = [
   // List-shaped `runs.*`: the grant admits the command; the store predicate narrows the rows.
   { action: "runs:read", resource: "command", when: [grant("runs:read")] },
   { action: "runs:write", resource: "command", when: [grant("runs:write")] },
+  // `steer.run`: every chat user holds the grant (CHAT_OPEN_ACTIONS) because
+  // the fence is the steer owner rule at the wired sender, decided against the
+  // NAMED run (`authorizeSteerOwner`, authorization item 16a) — the requester,
+  // a linked id, or `runs:write` — which no command-door row can see.
+  { action: "steer:write", resource: "command", when: [grant("steer:write")] },
 
   // ── conversations ────────────────────────────────────────────────────────
   // Who may point the bot at another thread (record 0037). Asked for a
@@ -91,6 +96,12 @@ export const POLICY: readonly Rule[] = [
   // `all` and a named `grants` entry hold it).
   { action: "costs:write", resource: "command", when: [grant("costs:write")] },
 
+  // ── metrics ──────────────────────────────────────────────────────────────
+  // `metrics trend` reads the run-metrics dataset's report: the `costs:read`
+  // shape — a browser session's baseline, a grant for a Slack user or a token,
+  // never a chat baseline.
+  { action: "metrics:read", resource: "command", when: [grant("metrics:read")] },
+
   // ── providers ────────────────────────────────────────────────────────────
   // `providers check` reads the provider's own endpoints on request: a browser
   // session's read baseline, a grant everywhere else — an on-request provider

package/dist/assets/src/core/budgets.ts

@@ -38,6 +38,14 @@ export const WEEK_MS = 7 * DAY_MS;
  *  which stamps the expiry on its own clock. */
 export const CONFIRMATION_TTL_MS = 10 * MINUTE_MS;
 
+/** How long a question's Yes stays pending (docs/decisions/0054, as amended;
+ *  docs/reference/specs/routing-and-config.md item 25): one day. A Yes only
+ *  re-dispatches the corrected message, which is then routed, authorized and,
+ *  for a write, offered its own graded button — the write's ten-minute
+ *  freshness is enforced downstream, so a short window here protects nothing
+ *  and only loses answers. People answer a question in minutes to hours. */
+export const QUESTION_TTL_MS = DAY_MS;
+
 /** How long a dispatch's FIRST attach to a resident — a fresh run's, or a
  *  resumed run's re-attach to its recorded worktree — waits for the resident
  *  to wake when the Worker typed its refusal as the platform's transient

package/dist/assets/src/core/coordinator/driver.ts

@@ -390,6 +390,11 @@ function prCheckReturn(step: string, a: BotAnswer): StepReturn {
         prNumber,
         url,
         ...(typeof headSha === "string" ? { headSha } : {}),
+        // The entry facts (issue 1689): the branch's own tip and whether the
+        // bot's approval stands at the head, read at the unit-start's pre-check
+        // so a re-issued plan resumes at review or at the merge decision.
+        ...(typeof a.body.branchHead === "string" ? { branchHead: a.body.branchHead } : {}),
+        ...(typeof a.body.approved === "boolean" ? { approved: a.body.approved } : {}),
         ...(typeof a.body.autoMergeEnabled === "boolean" ? { autoMergeEnabled: a.body.autoMergeEnabled } : {}),
         ...(isCommitChecks(a.body.checks) ? { checks: a.body.checks } : {}),
         // The ready-state facts beside the checks (agent-ship item 9): the
@@ -584,6 +589,10 @@ async function perform(
           await step.do(action.step, STEP_CONFIG, () =>
             call(bot, "pr-check", {
               ...tag,
+              // `entry` is the unit-start's pre-check (issue 1689): the bot
+              // reads the branch's tip, the approval and the checks beside the
+              // listing, so a re-issued plan's unit resumes instead of recoding.
+              ...(action.entry === true ? { entry: true } : {}),
               ...(action.recover !== undefined ? { recover: action.recover } : {}),
               ...(action.pr !== undefined ? { pr: action.pr } : {}),
             }),