@coreplane/switchboard 1.249.1 → 1.251.0

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

@@ -59,6 +59,14 @@ export interface LiveRunMeta {
   /** The app that relayed the request for the person (authorization.md item 14): a resume or restart keeps app ∩ person at the gates. */
   postedBy?: string;
   effort?: string;
+  /** A ship pipeline's parent (record 0060): claimed under the host key
+   *  (`hostKey.ts`) while `threadKey` here names the thread itself, so every
+   *  record, notice and rebuilt handle files by the metadata's thread and the
+   *  occupancy readers that key on the ledger's key column never see it. */
+  hosted?: true;
+  /** The run's index label (the registry sets it at create): on the row so a
+   *  hosted run listed from the ledger reads as its registry view does. */
+  label?: string;
   ref?: string;
   headSha?: string;
   pr?: number;
@@ -96,10 +104,10 @@ export interface LiveRunMeta {
   request?: Record<string, unknown>;
   /** The router's decision when it chose the run's preset (routing-and-config
    *  item 21) — the same fields the record's `route` event carries. On the row
-   *  so a resume repaints the card as it was (` · routed: <reason>`, the
-   *  parts, the override footer on the close) and a reclaim closing the run
-   *  knows it was routed without reading the events. Absent for a preset a
-   *  person, a scope or the default chose. */
+   *  so a resume repaints the card as it was (the `route reason:` note at
+   *  debug, the parts) and a record built from the row knows it was routed
+   *  without reading the events. Absent for a preset a person, a scope or the
+   *  default chose. */
   route?: {
     preset: string;
     reason: string;
@@ -250,7 +258,65 @@ export interface CompactionEntry {
 
 /** The rows a step write carries, each at its log index: the previous step's
  *  results and this step's assistant turn as messages, and pi's compaction
- *  entry as a row of its own between them. */
-export type TranscriptTurn = { idx: number; message: ChatMessage } | { idx: number; compaction: CompactionEntry };
+ *  entry as a row of its own between them. The optional `actor` on a message
+ *  turn is the platform-namespaced id of the person who authored it (record
+ *  0057); absent for machine turns, compaction rows and pre-0057 rows. */
+export type TranscriptTurn =
+  { idx: number; message: ChatMessage; actor?: string } | { idx: number; compaction: CompactionEntry };
 
 export type AppendableEvent = RunEvent & { seq: number };
+
+/** One intake verdict as the ledger stores it (docs/reference/specs/run-history.md item
+ *  59; docs/decisions/0058): keyed by the message (`<channel>:<ts>`), written
+ *  first-writer-wins so one unmentioned thread reply is decided once across
+ *  processes and the reconnect catch-up reads the verdict instead of deciding
+ *  again. The shape is the intake seam's (`src/core/intake.ts` re-exports it);
+ *  spelled out here because this file is shared with the state Worker. */
+export interface IntakeReceipt {
+  verdict: "addressed" | "silent";
+  reason: string;
+  source: "model" | "mode" | "error" | "timeout";
+  mode: "mention" | "classify";
+  /** The `<provider>/<model>` ref the verdict ran on. */
+  model: string;
+  /** The deciding process's generation counter, for telling a retried write's
+   *  own landed row from another writer's. */
+  gen: number;
+  threadKey: string;
+  /** Epoch ms. */
+  decidedAt: number;
+}
+
+/** What an intake write answers: whether THIS write landed, and the row that
+ *  stands — the first writer's, whoever that was. */
+export interface IntakeWriteResult {
+  inserted: boolean;
+  stored: IntakeReceipt;
+}
+
+/** `listIntake`'s filters: a thread's rows, rows since an instant, or both. */
+export interface IntakeQuery {
+  threadKey?: string;
+  since?: number;
+}
+
+/** The receipt as the Worker route validates it: every field present and of
+ *  its type, the enums closed — a malformed receipt is 400, never stored. */
+export function isIntakeReceipt(v: unknown): v is IntakeReceipt {
+  if (typeof v !== "object" || v === null) return false;
+  const r = v as Record<string, unknown>;
+  return (
+    (r.verdict === "addressed" || r.verdict === "silent") &&
+    typeof r.reason === "string" &&
+    (r.source === "model" || r.source === "mode" || r.source === "error" || r.source === "timeout") &&
+    (r.mode === "mention" || r.mode === "classify") &&
+    typeof r.model === "string" &&
+    typeof r.gen === "number" &&
+    Number.isFinite(r.gen) &&
+    typeof r.threadKey === "string" &&
+    r.threadKey.length > 0 &&
+    r.threadKey.length <= 256 &&
+    typeof r.decidedAt === "number" &&
+    Number.isFinite(r.decidedAt)
+  );
+}

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

@@ -39,6 +39,12 @@ import {
 // reached `finish`.
 export type RunStatus = "completed" | "stopped_soft" | "stopped_hard" | "failed" | "interrupted";
 
+/** How every store-only reader renders a record still in its provisional
+ *  window (run-history.md item 27's third state): not `interrupted` (a real
+ *  terminal state) and not `running` (the store cannot know). One string for
+ *  the CLI's `runs list`/`runs get` and the web's index row and run page. */
+export const PROVISIONAL_LABEL = "unfinished — no finish recorded";
+
 const RUN_STATUSES: readonly RunStatus[] = ["completed", "stopped_soft", "stopped_hard", "failed", "interrupted"];
 
 /** Every `runs.*` id: checked before any store call. */
@@ -115,6 +121,13 @@ export interface RunRecord {
   stepCount?: number;
   schema?: number;
   status: RunStatus;
+  /** Present on a tombstone record still in its provisional window — the
+   *  start-of-run `interrupted` or the drain-deadline upgrade — before the
+   *  run's final write lands. Absent on every final (finished) record. A
+   *  store-only reader must render a provisional record as "unfinished — no
+   *  finish recorded" rather than as `interrupted`, because the run may still
+   *  be live in a registry the reader cannot see (run-history.md item 27). */
+  provisional?: true;
   /** The failure by name, when a `failed` run has one (item 57):
    *  `policy_refusal`, the provider refused the run's model call under its
    *  usage policy. Absent on a run that did not fail, on one that failed for
@@ -190,6 +203,11 @@ export interface RunRecord {
    *  item 48), stored at the claim so a retried spawn finds its run. Present
    *  exactly when `parentInstanceId` is — both or neither, never one alone. */
   idempotencyKey?: string;
+  /** The plan runner instance this run's hand-off created (record 0051 R2;
+   *  item 2): the last `ship_handoff` event, folded at the assembly like the
+   *  coordinator tag. Present only on a ship run whose hand-off succeeded;
+   *  a record written before the event has none. */
+  instanceId?: string;
   /** Where the run's conversation started (item 52): `channel` — its own
    *  thread's history, as for every run a person, a schedule or a coordinator
    *  started — or `parent` — a spawned child seeded from its parent's text
@@ -266,6 +284,16 @@ export function leaseOfEvents(events: readonly RunEvent[]): RunLease | undefined
   return undefined;
 }
 
+/** The plan runner instance a ship run's events say its hand-off created —
+ *  the last `ship_handoff` wins — or nothing (record 0051 R2): projected onto
+ *  `RunRecord.instanceId` the way `coordinator_tag` rides the record, so the
+ *  thread's owner rule finds the instance from the page's ship run. */
+export function instanceIdOfEvents(events: readonly RunEvent[]): string | undefined {
+  let id: string | undefined;
+  for (const e of events) if (e.type === "ship_handoff") id = e.instanceId;
+  return id;
+}
+
 /** The pull request a run's events say it opened or edited — the last
  *  `pr_opened` wins, as an edit after an open names the same PR — or nothing. */
 export function prOfEvents(events: readonly RunEvent[]): RunPullRequest | undefined {
@@ -908,6 +936,9 @@ export function isRunRecord(v: unknown): v is RunRecord {
     (typeof r.idempotencyKey !== "string" || !IDEMPOTENCY_KEY_PATTERN.test(r.idempotencyKey))
   )
     return false;
+  // The instance a ship run's hand-off created (record 0051 R2; item 2).
+  if (r.instanceId !== undefined && (typeof r.instanceId !== "string" || !INSTANCE_ID_PATTERN.test(r.instanceId)))
+    return false;
   if (typeof r.channelId !== "string" || typeof r.userId !== "string" || typeof r.threadKey !== "string") return false;
   if (r.relayedBy !== undefined && typeof r.relayedBy !== "string") return false;
   if (r.authenticatedAs !== undefined && typeof r.authenticatedAs !== "string") return false;
@@ -926,6 +957,9 @@ export function isRunRecord(v: unknown): v is RunRecord {
       return false;
   }
   if (!RUN_STATUSES.includes(r.status as RunStatus)) return false;
+  // A provisional tombstone carries `provisional: true`; any other value (false,
+  // a string, etc.) is a malformed record — only the presence of the flag matters.
+  if (r.provisional !== undefined && r.provisional !== true) return false;
   if (!isFiniteNumber(r.eventCount) || !isFiniteNumber(r.storedEventCount)) return false;
   if (typeof r.truncated !== "boolean") return false;
   if (!Array.isArray(r.events)) return false;

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

@@ -439,17 +439,30 @@ export const TIMEOUT_ON_LONG_COMMANDS =
   "State a timeout on any command you expect to run longer than a minute: a timeout that reaches past the loop's " +
   "end is refused before the command runs, never cut midway.";
 
+/** The fast gates a plan child runs before every push, named one by one
+ *  (agent-ship item 13; agent-coding item 9). "Its cheapest proving checks"
+ *  left the choice to the child, and children chose wrong: prettier was
+ *  reported clean while `format:check` was red, and hygiene imprints reached
+ *  CI that `hygiene:check` would have caught locally. Naming the commands
+ *  makes each gate a receipt — the exit line goes into the handoff's verified
+ *  list, and a gate the child could not run is unproven, never claimed clean. */
+export const FAST_GATES_BEFORE_PUSH =
+  "The fast gates, before every push: `npx prettier --check` on the changed files, `npm run hygiene:check`, " +
+  "`npm run specs:check`, and `tsc --noEmit` on the touched project under `NODE_OPTIONS=--max-old-space-size=6144`. " +
+  "Paste each command's exit line into the handoff's verified list; a gate you could not run goes under unproven " +
+  "and is never claimed clean.";
+
 function renderFirstInstruction(rebase: ChildContract["rebase"]): string {
   const branch = rebase.branch ? `\`${rebase.branch}\`` : "the unit's branch";
   const onto = rebase.onto ? `\`${rebase.onto}\`` : "the merged parent";
   return (
     `Rebase ${branch} onto ${onto} before any other work — the parent unit has merged and the base has moved; ` +
     `the only writes are your own on that branch. A conflict ends the unit: report it as the handoff and stop. ` +
-    `Push the branch as soon as the change exists and its cheapest proving checks pass — before the project's ` +
+    `Push the branch as soon as the change exists and the fast gates pass — before the project's ` +
     `full verification, which runs after that push with any fix as a further commit; an unpushed tree does not ` +
-    `survive the run's end. Right before each push, fetch ${onto} again and rebase once more if it moved while ` +
-    `you worked, so the pull request is not born conflicting. At the wind-down note, commit and push what compiles, ` +
-    `say what does not, then answer. ${TIMEOUT_ON_LONG_COMMANDS}`
+    `survive the run's end. ${FAST_GATES_BEFORE_PUSH} Right before each push, fetch ${onto} again and rebase ` +
+    `once more if it moved while you worked, so the pull request is not born conflicting. At the wind-down note, ` +
+    `commit and push what compiles, say what does not, then answer. ${TIMEOUT_ON_LONG_COMMANDS}`
   );
 }
 

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

@@ -453,6 +453,13 @@ export type CoordinatorAction =
        *  submitted description when the record holds one) instead of answering
        *  `none` over stranded work. */
       recover?: { runId: string };
+      /** The pull request the machine has adopted (`state.pr`), when it holds
+       *  one: the child may have worked that pull request's own head branch,
+       *  not the unit's (issue 1799), so when nothing heads the unit's branch
+       *  the bot follows this number and answers the pull request's LIVE state
+       *  — open at a fresh head, merged, or closed (`prClosed`) — never `none`
+       *  over a record fact written minutes earlier. */
+      pr?: number;
     }
   | { type: "merge"; step: string; prNumber: number; headSha: string }
   /** Wait for the intake's checks-settled event at the approved head, bounded as the fallback. */
@@ -509,6 +516,10 @@ export type PrCheck =
        *  naming where the scope landed is the `already_landed` ending
        *  (agent-ship item 12); absent, the fact is unknown and never claimed. */
       aheadOfBase?: number;
+      /** The action's followed pull request (`pr`) was verified CLOSED
+       *  unmerged: the machine must not brief a review round on it. Absent when
+       *  nothing was followed or the follow could not read the pull request. */
+      prClosed?: boolean;
     }
   | {
       state: "open";
@@ -704,6 +715,10 @@ export interface UnitPipelineInput {
    *  pre-check finds the open pull request still at exactly this head, there is
    *  nothing to code and the attempt starts at the review round. */
   lastPush?: string;
+  /** The runs page base (`<PUBLIC_BASE_URL>/runs`), the plan route's answer:
+   *  the report's pointer at a child's write-up links its run page with it and
+   *  names the run id without it — the machine never reads an environment. */
+  runPageBase?: string;
 }
 
 type Phase =
@@ -935,6 +950,9 @@ export function nextAction(s: UnitPipelineState): CoordinatorAction {
         type: "pr-check",
         step: `${roundStep(s, p.round)}/pr-check`,
         ...(p.dead !== undefined ? { recover: { runId: p.runId } } : {}),
+        // The adopted pull request rides the check so the bot can follow it
+        // when nothing heads the unit's branch (issue 1799).
+        ...(s.pr !== undefined ? { pr: s.pr.number } : {}),
       };
     case "merge":
       return { type: "merge", step: `${unit}/merge/${p.n}`, prNumber: p.pr.number, headSha: p.headSha };
@@ -1286,6 +1304,22 @@ function settlePrCheck(s: UnitPipelineState, phase: Extract<Phase, { at: "pr-che
         [roundNote(round, "aborted")],
       );
     }
+    // Nothing heads the unit's branch, but the machine holds the round's pull
+    // request (`pr_opened` off the child's record, or an earlier round's
+    // adoption): the child worked on that pull request's own head branch, not
+    // the unit's — a re-issued task in the thread of an existing pull request
+    // (issue 1799). The round HAS its pull request — at round 0 and after a
+    // findings step alike, since the same child keeps repushing that branch
+    // through every later round — so it carries on to the (re-)review at the
+    // head the child pushed through the shared open settle (a findings step
+    // that repushed nothing keeps its abort, item 7), instead of the unit
+    // ending "no pull request" or "closed out from under" over work that
+    // stands. Never over a followed answer that VERIFIED the pull request
+    // closed (`prClosed`): a review briefed on a closed pull request reviews
+    // nothing, so the endings below stand — and are then truthful. Dead
+    // children never reach here: their endings are above.
+    if (s.pr !== undefined && pr.prClosed !== true)
+      return roundOnOpenPr(s, phase, { prNumber: s.pr.number, url: s.pr.url });
     if (round.index === 0) {
       // The scope already landed (agent-ship item 12): the child's handoff
       // names where, and the branch carries no commits over the base — two
@@ -1370,6 +1404,18 @@ function settlePrCheck(s: UnitPipelineState, phase: Extract<Phase, { at: "pr-che
       [roundNote(round, "aborted")],
     );
   }
+  return roundOnOpenPr(s, phase, pr);
+}
+
+/** The round carried on its open pull request: the pr-check's `open` answer,
+ *  or — when nothing heads the unit's branch — the pull request the machine
+ *  already holds (issue 1799), at the head the child pushed. */
+function roundOnOpenPr(
+  s: UnitPipelineState,
+  phase: Extract<Phase, { at: "pr-check" }>,
+  pr: { prNumber: number; url: string; headSha?: string },
+): Transition {
+  const { round } = phase;
   const head = pr.headSha ?? phase.childHead;
   const next: UnitPipelineState = { ...s, pr: { number: pr.prNumber, url: pr.url } };
   if (round.kind === "findings") {
@@ -1647,6 +1693,18 @@ function dispositionFor(s: UnitPipelineState, finding: Finding, round: number):
   return undefined;
 }
 
+/** Where a child's write-up lives, for the report's pointer (agent-ship item
+ *  12): the child's own message in the thread is the single copy of the detail
+ *  — posted moments before the unit-end — so the report points at it instead
+ *  of repeating it: the run page when the plan named the base, the run id
+ *  otherwise. Undefined when no run is known to point at. */
+function writeUpPointer(s: UnitPipelineState, kind: RoundKind, runId: string | undefined): string | undefined {
+  if (runId === undefined) return undefined;
+  const base = s.input.runPageBase;
+  const at = base !== undefined ? `${base.replace(/\/+$/, "")}/${encodeURIComponent(runId)}` : `run ${runId}`;
+  return `The ${presetOf(kind)} child's write-up is its own message above in this thread — the single copy of the detail (${at}).`;
+}
+
 /** How the budget went, in the card's words: coding, review, waiting minutes. */
 function budgetSplitLine(spent: ShipBudgetSpent, maxMinutes: number): string {
   const min = (ms: number) => Math.round(ms / MIN);
@@ -1815,7 +1873,11 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
     case "stopped":
       return join([
         `${e.mode === "hard" ? "⛔" : "⏹"} Ship stopped by operator (${e.mode} stop) after ${rounds}.${prLine}`,
-        e.finalReply,
+        writeUpPointer(
+          s,
+          e.round.kind,
+          e.round.kind === "review" ? s.reviewRunByRound[e.round.index] : s.lastCodingRunId,
+        ),
         e.postedReview
           ? "ℹ️ A changes-requested review was posted this round before the stop — its findings stand on the PR."
           : undefined,
@@ -1823,22 +1885,26 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
       ]);
     case "aborted":
       return join([
-        e.finalReply,
         e.reason,
+        writeUpPointer(
+          s,
+          e.round?.kind ?? "coding",
+          e.round?.kind === "review" ? s.reviewRunByRound[e.round.index] : s.lastCodingRunId,
+        ),
         e.renewal !== undefined ? `🔁 Not renewed: ${e.renewal.line}.` : undefined,
         `⚠️ Ship aborted after ${rounds}.`,
         reissue,
       ]);
     case "continued":
       return join([
-        e.finalReply,
+        writeUpPointer(s, e.round.kind, e.runId),
         `🔁 Segment ${e.segment - 1} ended at its lease with the unit unfinished — ${e.line}. Segment ${e.segment} opens in this thread${e.from !== undefined ? ` from \`${e.from.slice(0, 7)}\`` : ""} under a fresh ${s.input.caps.maxMinutes}-minute lease, with this segment's write-up as its request; ${e.renewalsLeft} renewal${e.renewalsLeft === 1 ? "" : "s"} remain${e.spendUsd !== null ? `, $${e.spendUsd.toFixed(2)} spent so far` : ""}.`,
         budgetSplitLine(e.spent, s.input.caps.maxMinutes),
       ]);
     case "no_verdict":
       return join([
         `⚠️ Review round ${e.round.index} ended without a submitted verdict (budget, refusal, or stop) — ship never converts that into a request for changes, so no findings step ran.`,
-        e.finalReply ? `Review round's final message:\n\n${e.finalReply}` : undefined,
+        writeUpPointer(s, e.round.kind, s.reviewRunByRound[e.round.index]),
         `⚠️ Ship aborted after ${rounds}.`,
         reissue,
       ]);

package/dist/assets/src/core/trace/attrs.ts

@@ -22,8 +22,16 @@ export interface AttrDomain {
   caughtUp: boolean;
   files: number;
   dedupe: "fresh" | "duplicate";
-  /** How the requester was found (slack-channel.md item 13): the sender, the relay footer's thread, the thread's parent, or the app itself. */
-  requester: "message" | "relay-footer" | "thread-parent" | "bot";
+  /** How the requester was found (slack-channel.md item 13): the sender, the configured relay app's footer, or the app itself. */
+  requester: "message" | "relay-footer" | "bot";
+  /** The intake verdict on an unmentioned thread reply (routing-and-config.md
+   *  item 27, record 0058); the reason is free text and lives on the receipt
+   *  row and the log line, never on a span. */
+  intake: "addressed" | "silent";
+  /** How the verdict was reached (`IntakeSource`). */
+  intakeSource: "model" | "mode" | "error" | "timeout";
+  /** What became of the receipt (`IntakeReceiptOutcome`). */
+  intakeReceipt: "inserted" | "existing" | "failed" | "absent";
   // dispatch.* / run.* / post.*
   outcome: string;
   /** The refusal's code (src/core/refusal.ts) — on the `dispatch.refuse` span
@@ -169,6 +177,9 @@ const ATTR_TYPE: Record<SpanAttrKey, "string" | "number" | "boolean"> = {
   files: "number",
   dedupe: "string",
   requester: "string",
+  intake: "string",
+  intakeSource: "string",
+  intakeReceipt: "string",
   outcome: "string",
   refusal: "string",
   cause: "string",

package/dist/assets/src/core/trace/workerTrace.ts

@@ -54,9 +54,10 @@ export function shimRoute(pathname: string): string | undefined {
   if (pathname.startsWith("/admin/")) return "admin";
   // The artifact copy (deploy/cloudflare/artifactsCopy.ts): the shim's own route, a 1 GB stream.
   if (pathname === "/artifacts/copy") return "artifacts";
-  // The model proxy's two routes (docs/reference/specs/model-proxy.md): a bounded
+  // The model proxy's three routes (docs/reference/specs/model-proxy.md): a bounded
   // request per model call, forwarded to the container like everything else.
-  if (pathname === "/v1/messages" || pathname === "/v1/chat/completions") return "model-proxy";
+  if (pathname === "/v1/messages" || pathname === "/v1/chat/completions" || pathname === "/v1/responses")
+    return "model-proxy";
   // The pi harness's four routes (docs/reference/specs/harness-pi.md item 7): a
   // run's extension asking for its tools, a verdict, a relayed tool's result,
   // how a compaction is written.

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

@@ -146,6 +146,9 @@ export interface HistoryItem {
   images?: ImageAttachment[];
   /** Non-image files attached to this turn, if any (user turns only in practice). */
   documents?: DocumentAttachment[];
+  /** The platform-namespaced id of the author (e.g. `slack:U…`); absent for
+   *  bot turns and channels that do not stamp user ids (record 0057). */
+  user?: string;
 }
 
 /** What the run is doing right now, typed so each channel draws it in its