@coreplane/switchboard 1.229.0 → 1.231.0

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

@@ -363,6 +363,16 @@ workspaceDir: ./workspaces
 #   model: anthropic/claude-haiku-4-5
 #   answer: text
 
+# 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
+# member of is quoted onto the request turn as an untrusted block — text only,
+# at most three per request, never a private channel from elsewhere, never a
+# DM or a Slack Connect channel — and the run's record and page show what was
+# quoted. A bot older than 1.228.0 refuses a config that carries this key.
+# references:
+#   enabled: true
+
 # Spend reporting: GET /costs (Access-gated). Optional. See docs/reference/specs/costs.md.
 # costs:
 #   cloudflareAccountId: <32-hex account id>

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

@@ -51,6 +51,7 @@ import {
   planSessionTrim,
   roleOfStoredRow,
   rowKind,
+  SEARCH_MAX_HITS,
   sessionsToDrop,
   tailCut,
   textOfStoredRow,
@@ -148,7 +149,7 @@ const traceSinks = [workerLogSink((line) => console.log(line))];
 // keeps the 512 KB one.
 //   POST /runs/put    {storeKey, record, policy?, policyUpdatedAt?} → {ok, retained, stored, rewritten}
 //   POST /runs/get    {storeKey, id} → {record: RunRecord | null}      (unknown/expired: null, 200)
-//   POST /runs/list   {storeKey, limit?, before?, beforeId?, sinceMs?, agent?, channel?, threadKey?}
+//   POST /runs/list   {storeKey, limit?, before?, beforeId?, sinceMs?, agent?, channel?, threadKey?, parentRunId?}
 //                       → {items: RunListItem[], nextBefore?: {finishedAt, id}}   (cursor = the last row's list key)
 //   POST /runs/events {storeKey, id, afterSeq?, limit?} → {events: (RunEvent & {seq})[] | null, nextAfterSeq?}
 //                       (`events: null` when the run is unknown or hidden by retention; `seq` is the registry's stamp)
@@ -225,7 +226,6 @@ const MAX_MATCH_TOKENS = 24;
 /** A `recall` query's size and the most hits one answers (session-log item 10):
  *  a query is a few words, and the tool's default is five. */
 const MAX_SEARCH_QUERY_BYTES = 1_024;
-const MAX_SEARCH_HITS = 50;
 /** Request body ceiling, checked against Content-Length before parsing. A full
  *  batch (50 × 4000-char texts + keywords + envelope) fits comfortably. */
 const MAX_BODY_BYTES = 512 * 1024;
@@ -1152,31 +1152,16 @@ export class RunHistoryDO extends DurableObject<Env> {
         value TEXT NOT NULL
       );
     `);
-    // The one column migration this DO has (the run-visibility stamp): a table
-    // created before the visibility stamp gains the column with `unknown` for
-    // every existing row — so a run written before the stamp is never public.
-    // Then the indexes the visibility predicate's leaves walk (`channel_id IN`,
-    // `channel_visibility IN`, `user_id =`), each ordered like the page.
-    const columns = new Set(
-      this.sql
-        .exec<{ name: string }>(`PRAGMA table_info(runs)`)
-        .toArray()
-        .map((c) => c.name),
-    );
-    if (!columns.has("channel_visibility"))
-      this.sql.exec(`ALTER TABLE runs ADD COLUMN channel_visibility TEXT NOT NULL DEFAULT 'unknown'`);
-    // The session a run was a range of (session-log item 7), so the sweep can
-    // tell which sessions still have a kept run; null for a record without one.
-    if (!columns.has("session_key")) this.sql.exec(`ALTER TABLE runs ADD COLUMN session_key TEXT`);
-    // What the run cost in tokens (costs.md, cost by user): the record's `usage`
-    // as JSON; NULL for a record written before the field existed, until the
-    // by-user aggregate fills it in from the run's stored events.
-    if (!columns.has("usage_json")) this.sql.exec(`ALTER TABLE runs ADD COLUMN usage_json TEXT`);
+    this.migrateRunsTable();
+    // The indexes the visibility predicate's leaves walk (`channel_id IN`,
+    // `channel_visibility IN`, `user_id =`), each ordered like the page; the
+    // session the sweep asks about; the parent a children listing filters on.
     this.sql.exec(`
       CREATE INDEX IF NOT EXISTS runs_channel_finished ON runs(channel_id, finished_at DESC, run_id DESC);
       CREATE INDEX IF NOT EXISTS runs_visibility_finished ON runs(channel_visibility, finished_at DESC, run_id DESC);
       CREATE INDEX IF NOT EXISTS runs_user_finished ON runs(user_id, finished_at DESC, run_id DESC);
       CREATE INDEX IF NOT EXISTS runs_session ON runs(session_key);
+      CREATE INDEX IF NOT EXISTS runs_parent ON runs(parent_run_id, finished_at DESC, run_id DESC);
     `);
     // The sessions registry (session-log item 7): every session log a run of
     // this store claimed, with its thread — the sweep cannot enumerate the
@@ -1333,6 +1318,37 @@ export class RunHistoryDO extends DurableObject<Env> {
     return r ? rowToLive(r) : undefined;
   }
 
+  /** The `runs` table's column migrations, run at every construction and
+   *  idempotent: a table created before a column existed gains it, with the
+   *  value a row written back then should read. The run-visibility stamp: a
+   *  run written before the stamp is `unknown`, never public. The session a
+   *  run was a range of (session-log item 7), so the sweep can tell which
+   *  sessions still have a kept run; null for a record without one. What the
+   *  run cost in tokens (costs.md, cost by user), NULL until the by-user
+   *  aggregate fills it from the run's stored events. The parent a child names
+   *  (run-history item 46), the column a children listing filters on: the
+   *  record already carries it in `summary_json`, so existing rows are filled
+   *  from there once, and every later `put` writes it beside the row. */
+  migrateRunsTable(): void {
+    const columns = new Set(
+      this.sql
+        .exec<{ name: string }>(`PRAGMA table_info(runs)`)
+        .toArray()
+        .map((c) => c.name),
+    );
+    if (!columns.has("channel_visibility"))
+      this.sql.exec(`ALTER TABLE runs ADD COLUMN channel_visibility TEXT NOT NULL DEFAULT 'unknown'`);
+    if (!columns.has("session_key")) this.sql.exec(`ALTER TABLE runs ADD COLUMN session_key TEXT`);
+    if (!columns.has("usage_json")) this.sql.exec(`ALTER TABLE runs ADD COLUMN usage_json TEXT`);
+    if (!columns.has("parent_run_id")) {
+      this.sql.exec(`ALTER TABLE runs ADD COLUMN parent_run_id TEXT`);
+      this.sql.exec(
+        `UPDATE runs SET parent_run_id = json_extract(summary_json, '$.parentRunId')
+         WHERE json_type(summary_json, '$.parentRunId') = 'text'`,
+      );
+    }
+  }
+
   private liveByThread(threadKey: string): LiveRunRow | undefined {
     const r = this.sql.exec<LiveRow>(`SELECT * FROM live_runs WHERE thread_key = ?`, threadKey).toArray()[0];
     return r ? rowToLive(r) : undefined;
@@ -1832,8 +1848,8 @@ export class RunHistoryDO extends DurableObject<Env> {
         );
       this.sql.exec(
         `INSERT INTO runs (run_id, label, agent, model, channel_id, user_id, thread_key, channel_visibility, repo, started_at, finished_at, stored_at, status,
-                           event_count, stored_event_count, truncated, bytes, diagnosis_json, summary_json, session_key, usage_json)
-         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                           event_count, stored_event_count, truncated, bytes, diagnosis_json, summary_json, session_key, usage_json, parent_run_id)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
          ON CONFLICT(run_id) DO UPDATE SET
            label = excluded.label, agent = excluded.agent, model = excluded.model, channel_id = excluded.channel_id,
            user_id = excluded.user_id, thread_key = excluded.thread_key, channel_visibility = excluded.channel_visibility,
@@ -1842,7 +1858,8 @@ export class RunHistoryDO extends DurableObject<Env> {
            event_count = excluded.event_count, stored_event_count = excluded.stored_event_count, truncated = excluded.truncated,
            bytes = excluded.bytes, diagnosis_json = excluded.diagnosis_json, summary_json = excluded.summary_json,
            session_key = excluded.session_key,
-           usage_json = COALESCE(excluded.usage_json, runs.usage_json)`,
+           usage_json = COALESCE(excluded.usage_json, runs.usage_json),
+           parent_run_id = excluded.parent_run_id`,
         stored.id,
         stored.label ?? null,
         stored.agent ?? null,
@@ -1864,6 +1881,7 @@ export class RunHistoryDO extends DurableObject<Env> {
         JSON.stringify(summary),
         stored.session?.key ?? null,
         stored.usage ? JSON.stringify(stored.usage) : null,
+        stored.parentRunId ?? null,
       );
       // The session's registry row learns its newest finish (session-log item
       // 7); a record that reaches the store without a claim (the plain put
@@ -2199,6 +2217,10 @@ export class RunHistoryDO extends DurableObject<Env> {
       where.push(`thread_key = ?`);
       params.push(q.threadKey);
     }
+    if (q.parentRunId !== undefined) {
+      where.push(`parent_run_id = ?`);
+      params.push(q.parentRunId);
+    }
     if (q.visibleTo !== undefined && q.visibleTo.kind !== "all") where.push(visibilitySql(q.visibleTo, params));
     const select = `SELECT run_id, agent, channel_id, finished_at, bytes, event_count, summary_json FROM runs WHERE ${where.join(" AND ")} ORDER BY finished_at DESC, run_id DESC`;
     // `LIMIT` holds on the over-bound path too: the kept set is the newest
@@ -2441,6 +2463,11 @@ function parseRunList(body: unknown): Validated<{ storeKey: string; query: RunLi
       return invalid(`${field} must be a string of at most ${MAX_KEY_CHARS} characters`);
     query[field] = v;
   }
+  if (b.parentRunId !== undefined) {
+    const id = parseRunId(b.parentRunId);
+    if (!id.ok) return invalid("parentRunId must match ^[A-Za-z0-9_-]{1,64}$");
+    query.parentRunId = id.value;
+  }
   if (b.visibleTo !== undefined) {
     // A malformed filter is a 400, never "all": the bot degrades to live rows
     // rather than the DO widening what an actor may see.
@@ -2453,8 +2480,8 @@ function parseRunList(body: unknown): Validated<{ storeKey: string; query: RunLi
 }
 
 /** Parameters the page query binds before any filter: the cursor pair (3) and the age floor (1),
- *  plus `agent`, `channel`, `threadKey`, and the LIMIT at most — the headroom `visibleTo` must fit under. */
-const RUN_LIST_BASE_PARAMETERS = 8;
+ *  plus `agent`, `channel`, `threadKey`, `parentRunId`, and the LIMIT at most — the headroom `visibleTo` must fit under. */
+const RUN_LIST_BASE_PARAMETERS = 9;
 
 /** How many `?` a filter binds (one per id, one per user). */
 function boundParameters(f: RunVisibilityFilter): number {
@@ -3400,8 +3427,8 @@ async function handleLedger(pathname: string, body: unknown, env: Env): Promise<
       )
         return json({ error: `query must be a non-empty string of at most ${MAX_SEARCH_QUERY_BYTES} bytes` }, 400);
       const limit = b.limit;
-      if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > MAX_SEARCH_HITS)
-        return json({ error: `limit must be an integer in 1..${MAX_SEARCH_HITS}` }, 400);
+      if (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > SEARCH_MAX_HITS)
+        return json({ error: `limit must be an integer in 1..${SEARCH_MAX_HITS}` }, 400);
       const hits = await stub.search(b.query, limit);
       const gaps =
         hits.length > 1

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

@@ -1110,7 +1110,9 @@ const NO_REF_HINT_REASON: RefHintReason = { ownPr: null, refByDefault: false };
 type RebindOutcome =
   | { kind: "none"; binding: ThreadBinding }
   | { kind: "refuse"; refused: RebindRefused }
-  | { kind: "rebound"; moved: ThreadBinding; rebound: Rebound };
+  /** `note`: the move was the record alone — a dirty tree already on the
+   *  branch, no checkout run — in the verdict's words, for the log line. */
+  | { kind: "rebound"; moved: ThreadBinding; rebound: Rebound; note?: string };
 
 /** Result of one /op test/build execution. `ok` is the command's
  *  verdict — a failing test run is a RESULT with ok:false, never an error. */
@@ -4654,29 +4656,44 @@ export class ResidentDO extends Sandbox<Env> {
             );
             tree.readable = status.exitCode === 0;
             if (tree.readable) tree.dirty = status.stdout.trim() !== "";
+            if (tree.dirty) {
+              // A dirty tree is refused unless its HEAD is already the branch
+              // (the run made it here and left an edit after pushing): the
+              // one fact that tells the two apart, measured only when it
+              // decides anything.
+              const head = await this.threadRun(
+                current.user,
+                wt,
+                "git rev-parse --abbrev-ref HEAD",
+                DEFAULT_EXEC_TIMEOUT_MS,
+              );
+              if (head.exitCode === 0) tree.head = head.stdout.trim();
+            }
           }
           // Judged on the re-read plan: it carries whether the branch is the
           // thread's own, which the pre-lock plan lacks when it was a recreate.
           const verdict = rebindVerdict(again, tree);
           if (verdict.kind === "recreate") return this.recreateAtOwnBranch(current, again, fetchToken);
           if (verdict.kind !== "rebind") return verdict;
-          const startedAt = systemClock();
-          const checkout = await this.threadRun(
-            current.user,
-            wt,
-            `git checkout --quiet ${shellQuote(again.to)}`,
-            DEFAULT_EXEC_TIMEOUT_MS,
-          );
-          this.stepTrace.getStore()?.record("rebind-checkout", {
-            startedAt,
-            endedAt: systemClock(),
-            exitCode: checkout.exitCode,
-            timedOut: checkout.timedOut,
-          });
-          if (checkout.exitCode !== 0) {
-            const detail =
-              checkout.stderr.trim().split("\n")[0]?.slice(0, 200) || `git checkout exited ${checkout.exitCode}`;
-            return { kind: "refuse", refused: rebindRefused(again, "checkout-failed", detail) };
+          if (verdict.checkout) {
+            const startedAt = systemClock();
+            const checkout = await this.threadRun(
+              current.user,
+              wt,
+              `git checkout --quiet ${shellQuote(again.to)}`,
+              DEFAULT_EXEC_TIMEOUT_MS,
+            );
+            this.stepTrace.getStore()?.record("rebind-checkout", {
+              startedAt,
+              endedAt: systemClock(),
+              exitCode: checkout.exitCode,
+              timedOut: checkout.timedOut,
+            });
+            if (checkout.exitCode !== 0) {
+              const detail =
+                checkout.stderr.trim().split("\n")[0]?.slice(0, 200) || `git checkout exited ${checkout.exitCode}`;
+              return { kind: "refuse", refused: rebindRefused(again, "checkout-failed", detail) };
+            }
           }
           const rebound: Rebound = {
             from: current.ref,
@@ -4686,7 +4703,9 @@ export class ResidentDO extends Sandbox<Env> {
           };
           const moved: ThreadBinding = { ...current, ref: again.to, rebound };
           await this.ctx.storage.put(key, moved);
-          return { kind: "rebound", moved, rebound };
+          return verdict.checkout
+            ? { kind: "rebound", moved, rebound }
+            : { kind: "rebound", moved, rebound, note: verdict.note };
         }, ATTACH_MUTEX_WAIT_MS)
       ).value;
     } catch (err) {
@@ -4705,7 +4724,7 @@ export class ResidentDO extends Sandbox<Env> {
     }
     const { moved, rebound } = outcome;
     console.log(
-      `attach ${prior.threadKey}: rebound ${rebound.from} → ${rebound.to} (the thread's own pull request #${rebound.pr})`,
+      `attach ${prior.threadKey}: rebound ${rebound.from} → ${rebound.to} (the thread's own pull request #${rebound.pr})${outcome.note ? ` — ${outcome.note}` : ""}`,
     );
     return { binding: moved, rebound };
   }

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "switchboard",
-  "version": "1.229.0",
+  "version": "1.231.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "switchboard",
-      "version": "1.229.0",
+      "version": "1.231.0",
       "license": "Apache-2.0",
       "workspaces": [
         "web",
@@ -40,6 +40,7 @@
         "eslint-plugin-vue": "^10.11.0",
         "globals": "^17.12.0",
         "prettier": "^3.9.6",
+        "semver": "^7.8.5",
         "tsx": "^4.23.13",
         "typescript": "^5.9.3",
         "typescript-eslint": "^8.70.0",
@@ -652,6 +653,8 @@
     },
     "deploy/cloudflare-memory/node_modules/vitest": {
       "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.11.tgz",
+      "integrity": "sha512-fhACrNXUidIbGSBr5FlbuBkO7VWC1ZyLl0DO4CU2DrQoAPxX84Ysxs+HeGQpii5lZWV1Q4gBZTTu49mF+A6Edw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -20029,7 +20032,7 @@
     },
     "packages/switchboard": {
       "name": "@coreplane/switchboard",
-      "version": "1.229.0",
+      "version": "1.231.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.229.0",
+  "version": "1.231.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",
@@ -97,6 +97,7 @@
     "eslint-plugin-vue": "^10.11.0",
     "globals": "^17.12.0",
     "prettier": "^3.9.6",
+    "semver": "^7.8.5",
     "tsx": "^4.23.13",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.70.0",

package/dist/assets/source.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.229.0",
-  "commit": "ab0a0726ab1471eb99f55ea986c542195ccad495",
-  "builtAt": "2026-09-15T22:07:49.544Z"
+  "version": "1.231.0",
+  "commit": "1cade13414f48f68e82675b961909eae72531b59",
+  "builtAt": "2026-09-16T00:12:48.252Z"
 }

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

@@ -89,12 +89,30 @@ const CHAT_SURFACES: Readonly<Record<string, ActorSurface>> = {
  *  A namespace this module does not know stays a `user` with the id as given —
  *  its grants are whatever config names for that id, never a guess. */
 export function resolveChatActor(
-  msg: { userId: string; channelId: string; threadKey: string },
+  msg: { userId: string; channelId: string; threadKey: string; postedBy?: string },
   grantsFor: GrantsLookup,
 ): Actor {
-  const colon = msg.userId.indexOf(":");
-  const surface = colon > 0 ? CHAT_SURFACES[msg.userId.slice(0, colon)] : undefined;
-  const origin = { channelId: msg.channelId, threadKey: msg.threadKey };
-  if (surface === undefined) return { kind: "user", id: msg.userId, grants: grantsFor(msg.userId), origin };
-  return resolveActor({ surface, subjectId: msg.userId.slice(colon + 1), ...origin }, grantsFor);
+  const person = resolveNamespacedActor(msg.userId, msg, grantsFor);
+  if (msg.postedBy === undefined) return person;
+  // A request an app posted for a person (slack-channel.md item 13): the
+  // message text named the person, and text is forgeable, so the person's
+  // grants alone must never govern. The actor is the app, acting on the
+  // person's behalf — `effectiveGrants` is the intersection, so the run holds
+  // no more than the app holds (the surface baseline, plus whatever config
+  // grants that app id by name) and no more than the person holds. Identity
+  // (`userId`, the record, the costs page) is still the person's.
+  const app = resolveNamespacedActor(msg.postedBy, msg, grantsFor);
+  return { ...app, kind: "agent", onBehalfOf: person };
+}
+
+function resolveNamespacedActor(
+  userId: string,
+  origin: { channelId: string; threadKey: string },
+  grantsFor: GrantsLookup,
+): Actor {
+  const colon = userId.indexOf(":");
+  const surface = colon > 0 ? CHAT_SURFACES[userId.slice(0, colon)] : undefined;
+  const at = { channelId: origin.channelId, threadKey: origin.threadKey };
+  if (surface === undefined) return { kind: "user", id: userId, grants: grantsFor(userId), origin: at };
+  return resolveActor({ surface, subjectId: userId.slice(colon + 1), ...at }, grantsFor);
 }

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

@@ -36,6 +36,25 @@ export function idempotencyKeyFor(parentInstanceId: string, step: string): strin
   return `${parentInstanceId}:${step}`;
 }
 
+/** A unit's id as the plan spells it (`U16`) or `task` — the `unit` field of a unit row. */
+export const UNIT_PATTERN = /^[A-Za-z0-9_-]{1,32}$/;
+/** `<instanceId>:<unit>` — the one name a unit has outside its instance: the
+ *  prefix every child's idempotency key carries before its `/<round>/<kind>`
+ *  step, so a unit is addressed by the same words its runs are stamped with.
+ *  An instance id has no colon, so the first colon splits the two halves. */
+export const UNIT_KEY_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9_-]{0,99}:[A-Za-z0-9_-]{1,32}$/;
+
+export function unitKeyOf(unit: { instanceId: string; unit: string }): string {
+  return `${unit.instanceId}:${unit.unit}`;
+}
+
+/** The two halves of a unit key, or undefined for anything that is not one. */
+export function parseUnitKey(key: string): { instanceId: string; unit: string } | undefined {
+  if (!UNIT_KEY_PATTERN.test(key)) return undefined;
+  const at = key.indexOf(":");
+  return { instanceId: key.slice(0, at), unit: key.slice(at + 1) };
+}
+
 /** The event a child's terminal record sends its parent: the type carries the
  *  run id, so each `waitForEvent` matches its own child and a duplicate is
  *  buffered harmlessly. An event type is the platform's alphabet — letters,
@@ -98,20 +117,23 @@ export interface CoordinatorInstance {
   userName?: string;
   channelId: string;
   channelName?: string;
-  /** The requesting thread: where the card lives and where a task-string
-   *  instance's one unit runs; a plan's units each open a thread of their own. */
+  /** The requesting thread: where the card lives and where a generated plan's
+   *  one unit runs; a seeded plan's units each open a thread of their own. */
   threadKey: string;
   sourceUrl?: string;
-  /** `owner/name`, and the head branch the pipeline works on (a task string's
-   *  deterministic ship branch; for a plan, the first unit's — each unit row names its own). */
+  /** `owner/name`, and the head branch the pipeline works on (the first unit's
+   *  — each unit row names its own). */
   repo: string;
   branch: string;
   /** The pull request's base branch, when the creator knew it. */
   base?: string;
   /** Epoch ms. */
   createdAt: number;
-  /** The plan the instance runs, when it runs one: its id (the file's name) and its path in the repository. */
-  plan?: { id: string; path: string };
+  /** The plan the instance runs: its id and, for a seeded plan, its path in
+   *  the repository. A `plan` without a `path` is the generated one-unit plan a
+   *  task request becomes — the mark that keeps its unit in the requesting
+   *  thread (agent-ship item 16). */
+  plan?: { id: string; path?: string };
   /** Who merges the units' pull requests: `runner` for a seeded plan (the
    *  `merge` step under `plan:merge`), `person` for a task. Written by the
    *  hand-off, answered by the plan route, checked at the merge door; absent
@@ -131,20 +153,21 @@ export interface CoordinatorInstance {
   attempt?: number;
 }
 
-/** One unit of the plan an instance runs (a task string is a plan of one unit,
- *  `task`): its branch, the units it waits on, and — as the runner reaches it —
- *  its thread, its pull request, the round boundaries the card drew and how it
- *  ended. One row a person can read for "what happened to this unit". */
+/** One unit of the plan an instance runs (a task string is a generated plan of
+ *  one unit, `U1`): its branch, the units it waits on, and — as the runner
+ *  reaches it — its thread, its pull request, the round boundaries the card
+ *  drew and how it ended. One row a person can read for "what happened to this
+ *  unit". */
 export interface CoordinatorUnit {
   instanceId: string;
-  /** `U<n>` as the plan spells it, or `task`. */
+  /** `U<n>` as the plan spells it. */
   unit: string;
   slug: string;
   title?: string;
-  /** `plan/<plan-id>/<unit-slug>`, or the task string's ship branch. */
+  /** `plan/<plan-id>/<unit-slug>` (a resume's is the pull request's own head branch). */
   branch: string;
   dependsOn: string[];
-  /** The unit's thread, once opened; a task's is the requesting thread from the start. */
+  /** The unit's thread, once opened; a generated plan's is the requesting thread from the start. */
   threadKey?: string;
   sourceUrl?: string;
   /** The unit's review thread, opened once beside the unit's thread: every
@@ -195,7 +218,11 @@ export function isCoordinatorInstance(v: unknown): v is CoordinatorInstance {
   if (typeof r.repo !== "string" || !REPO_SLUG.test(r.repo)) return false;
   if (!isText(r.branch) || !isOptionalText(r.base)) return false;
   if (!isFinite(r.createdAt)) return false;
-  if (r.plan !== undefined && !(isObject(r.plan) && isText(r.plan.id) && isText(r.plan.path, 1024))) return false;
+  if (
+    r.plan !== undefined &&
+    !(isObject(r.plan) && isText(r.plan.id) && (r.plan.path === undefined || isText(r.plan.path, 1024)))
+  )
+    return false;
   if (r.merge !== undefined && r.merge !== "runner" && r.merge !== "person") return false;
   if (r.caps !== undefined && !(isObject(r.caps) && isFinite(r.caps.maxRounds) && isFinite(r.caps.maxMinutes)))
     return false;

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

@@ -158,6 +158,8 @@ interface PlanFacts {
   planId?: string;
   /** Who merges, as the instance's field has it: the plan route answers it, `person` when absent. */
   merge: "runner" | "person";
+  /** The instance's mark as the plan route answers it: a generated one-unit plan (a `plan` with no `path`). */
+  generated: boolean;
   repo: string;
   base: string;
   caps: ShipCaps;
@@ -186,6 +188,7 @@ function readPlan(a: BotAnswer): PlanFacts {
   return {
     ...(typeof b.planId === "string" ? { planId: b.planId } : {}),
     merge: b.merge === "runner" ? "runner" : "person",
+    generated: b.generated === true,
     repo: b.repo,
     base: b.base,
     caps: { maxRounds: b.caps.maxRounds, maxMinutes: b.caps.maxMinutes },
@@ -429,6 +432,7 @@ async function runUnit(
       // seeded plan and `person` on a task, and the door re-checks it — the
       // branch's name never decides.
       merge: plan.merge,
+      generated: plan.generated,
       ...(resume !== undefined ? { resume } : {}),
     },
     start.at,

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

@@ -76,11 +76,13 @@ export type RunNoteKind =
    *  wait had refused; on pi the container is provisioned before pi starts, so
    *  the note is a record fact from before the loop's deletion. */
   | "fleet_busy"
-  /** The sandbox restarted under the run and came back (docs/reference/specs/
-   *  resident-repos.md item 65): the executor waited for the resident's wake
-   *  and re-attached. The native loop settled the interrupted call and went
-   *  on; the pi harness has no such settlement yet (harness-pi.md, the item 19
-   *  gap), so the note is a record fact from before the loop's deletion. */
+  /** The container the run's pi ran in was replaced under the live run
+   *  (docs/reference/specs/harness-pi.md item 16; the resident's roll,
+   *  resident-repos.md item 65): the harness settled the call in flight with
+   *  the restart note, the summary names both containers, and the run ends
+   *  `interrupted` for a restart from its request. On a record from before the
+   *  native loop's deletion the note says that loop's settlement instead: the
+   *  executor waited for the wake and the run went on. */
   | "sandbox_restarted"
   | "stop_requested"
   | "stopped"
@@ -114,6 +116,11 @@ export type RunNoteKind =
    *  bounded extra model turn to submit it (docs/reference/specs/pr-description.md
    *  item 5). Published by the dispatcher before that turn. */
   | "description_turn"
+  /** A review run's loop ended on a pull request without `submit_verdict`, and
+   *  the same run is being given one bounded extra model turn to call it
+   *  (docs/reference/specs/agent-review.md item 5; verdictTurn.ts). Published by
+   *  the dispatcher before that turn. */
+  | "verdict_turn"
   /** The run is on a cold per-thread sandbox instead of a warm resident, and
    *  the summary says why — the resident attach failed (its steps so far are
    *  grafted under the attach span), the resident was unreachable or not
@@ -156,6 +163,14 @@ export type RunNoteKind =
    *  know — named, so a pi bump is visible in the first run's record. Published
    *  by the pi bridge. */
   | "harness_error"
+  /** The model provider refused the run's call under its usage policy — the
+   *  stop reason its wire names for a classifier's refusal, never the words
+   *  (harness-pi.md item 6): the summary carries the provider's explanation
+   *  for the run page; the run fails by name, its record says
+   *  `failure: policy_refusal` (run-history.md item 57), the thread reads one
+   *  sentence on how to go on, and the session's next seed leaves the refused
+   *  request out (session-log.md item 9). Published by the pi harness. */
+  | "policy_refusal"
   /** The harness's gate refused a tool call the model asked for (harness-pi.md
    *  item 7): the summary names the tool and the rule; the model read the same
    *  reason as the tool's result. Published by the bot's authorize route. */
@@ -183,12 +198,14 @@ export const RUN_NOTE_KINDS = [
   "resumed",
   "seed",
   "description_turn",
+  "verdict_turn",
   "cold_sandbox",
   "rebind_refused",
   "pr_not_opened",
   "review_not_posted",
   "compacted",
   "harness_error",
+  "policy_refusal",
   "tool_refused",
   "stuck_loop",
 ] as const satisfies readonly RunNoteKind[];

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

@@ -564,9 +564,10 @@ export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOp
         });
         return;
       case "sandbox_restarted":
-        // The container rolled under the run and came back: the run went on,
-        // but the minutes spent waiting for the wake are friction the deploy
-        // window owns.
+        // The container rolled under the run: on pi the run ends here and its
+        // request starts over (harness-pi item 16); on the deleted native loop
+        // it went on after the wake. Either way the roll's cost is friction the
+        // deploy window owns.
         findings.push({
           category: "infra_failure",
           severity: "medium",

package/dist/assets/src/core/runLedger/sessionLog.ts

@@ -15,6 +15,19 @@ export { isRunSession, SESSION_KEY_PATTERN, type RunSession } from "../runRecord
 /** The byte policy's default: `RetentionPolicy.sessionLogMaxBytes`. */
 export const DEFAULT_SESSION_LOG_MAX_BYTES = DEFAULT_RETENTION_POLICY.sessionLogMaxBytes;
 
+/** How much of a hit's text a search answers with (item 10): one line, at most this many characters. */
+export const SNIPPET_CHARS = 300;
+/** The most hits one search answers — the object's cap, `recall`'s and the search route's alike. */
+export const SEARCH_MAX_HITS = 50;
+
+/** A hit's text as one line of at most `SNIPPET_CHARS` — what `recall` and
+ *  the session search route answer beside the turn, so a reader sees where
+ *  the words fell without the turn's whole body. */
+export function snippetOf(text: string): string {
+  const line = text.replace(/\s+/g, " ").trim();
+  return line.length > SNIPPET_CHARS ? `${line.slice(0, SNIPPET_CHARS - 1)}…` : line;
+}
+
 /** The object's name: the thread and the agent, the pair record 0034 calls a
  *  session. A run without a resolved agent keys on a dash so the name still
  *  has both halves. */