@coreplane/switchboard 1.256.0 → 1.257.0

package/dist/assets/src/core/plane/findings.ts

@@ -0,0 +1,120 @@
+// The plane's findings (docs/decisions/0064, "Endings and the watches"): a
+// finding is filed when no move applies
+// — it carries the watch's name and the timeline of events that fired it, and
+// two findings on one watch and subject are ONE, their timelines merged. The
+// plane itself calls no model: the bot dispatches a research-tier run over the
+// timeline inside the untrusted fence (`findingResearchRequest`) and files the
+// answer through the path `friction propose` uses (`filePlaneFinding`, the
+// same `IssueTracker` seam). The dedupe half is node-free, like `decide.ts`.
+
+import { wrapUntrusted } from "../untrusted.js";
+
+/** The tracker seam, structurally the `IssueTracker` of
+ *  `src/execution/githubIssues.ts` (the friction proposer's) — declared here
+ *  so this module stays node-free like `decide.ts` and imports nothing the
+ *  Worker's build cannot carry. */
+export interface PlaneIssueRef {
+  number: number;
+  url: string;
+  title: string;
+  body: string;
+}
+
+export interface PlaneIssueTracker {
+  listOpen(repo: string, label: string): Promise<PlaneIssueRef[]>;
+  create(repo: string, issue: { title: string; body: string; labels: string[] }): Promise<PlaneIssueRef>;
+}
+
+/** One event on a finding's timeline: when, and what the watch saw — words
+ *  the bot recorded, never a model's. */
+export interface PlaneFindingEvent {
+  at: number;
+  what: string;
+}
+
+/** A finding: the watch, its subject (the run, pull request or instance the
+ *  watch fired about) and the timeline. Deduplicated by watch and subject —
+ *  `planeFindingKey` — so the same incident observed twice is one finding. */
+export interface PlaneFinding {
+  watch: string;
+  subject: string;
+  timeline: PlaneFindingEvent[];
+  firstAt: number;
+  lastAt: number;
+}
+
+export function planeFindingKey(f: Pick<PlaneFinding, "watch" | "subject">): string {
+  return `${f.watch}#${f.subject}`;
+}
+
+/** A timeline is bounded: a watch that fires forever grows one finding, not
+ *  unbounded storage — the newest events are kept. */
+export const PLANE_FINDING_TIMELINE_CAP = 50;
+
+/** Fold one observation into the set: a finding already standing for the same
+ *  watch and subject absorbs the timeline (two findings on one subject are
+ *  one); a new pair appends. Pure — the object commits the returned set. */
+export function mergePlaneFindings(existing: readonly PlaneFinding[], incoming: PlaneFinding): PlaneFinding[] {
+  const key = planeFindingKey(incoming);
+  const standing = existing.find((f) => planeFindingKey(f) === key);
+  if (!standing) return [...existing, { ...incoming, timeline: incoming.timeline.slice(-PLANE_FINDING_TIMELINE_CAP) }];
+  const timeline = [...standing.timeline, ...incoming.timeline]
+    .sort((a, b) => a.at - b.at)
+    .slice(-PLANE_FINDING_TIMELINE_CAP);
+  const merged: PlaneFinding = {
+    ...standing,
+    timeline,
+    firstAt: Math.min(standing.firstAt, incoming.firstAt),
+    lastAt: Math.max(standing.lastAt, incoming.lastAt),
+  };
+  return existing.map((f) => (planeFindingKey(f) === key ? merged : f));
+}
+
+/** The request text for the research-tier run the bot dispatches over a
+ *  finding (record 0064): the watch and subject are the bot's own words; the
+ *  timeline — recorded run output, GitHub words, whatever the watch saw — is
+ *  data inside the untrusted fence, never instructions. */
+export function findingResearchRequest(finding: PlaneFinding): string {
+  const timeline = finding.timeline.map((e) => `${new Date(e.at).toISOString()} — ${e.what}`).join("\n");
+  return [
+    `The orchestration plane's \`${finding.watch}\` watch fired for \`${finding.subject}\` and no mechanical move applied.`,
+    `Investigate the timeline below and write up what happened, why the watch fired, and what change would prevent it — a report to file as an issue, nothing executed.`,
+    wrapUntrusted(timeline),
+  ].join("\n\n");
+}
+
+/** The issue title a finding files under — also the dedupe key on the tracker:
+ *  an open issue with this exact title is the same finding, not filed twice. */
+export function planeFindingIssueTitle(finding: Pick<PlaneFinding, "watch" | "subject">): string {
+  return `plane finding: ${finding.watch} — ${finding.subject}`;
+}
+
+export const PLANE_FINDING_LABEL = "switchboard-plane";
+
+export type FiledPlaneFinding = { kind: "filed"; issue: PlaneIssueRef } | { kind: "duplicate"; issue: PlaneIssueRef };
+
+/** File one finding's write-up through the path `friction propose` uses — the
+ *  `IssueTracker` seam over the repository's open issues: an open issue with
+ *  the finding's title is a duplicate (the tracker-side half of the dedupe),
+ *  else the report is created under the plane's label. The body is the
+ *  research run's answer with the timeline appended as data. */
+export async function filePlaneFinding(
+  finding: PlaneFinding,
+  report: string,
+  opts: { tracker: PlaneIssueTracker; repo: string; label?: string },
+): Promise<FiledPlaneFinding> {
+  const label = opts.label ?? PLANE_FINDING_LABEL;
+  const title = planeFindingIssueTitle(finding);
+  const open = await opts.tracker.listOpen(opts.repo, label);
+  const existing = open.find((i) => i.title === title);
+  if (existing) return { kind: "duplicate", issue: existing };
+  const timeline = finding.timeline.map((e) => `- ${new Date(e.at).toISOString()} — ${e.what}`).join("\n");
+  return {
+    kind: "filed",
+    issue: await opts.tracker.create(opts.repo, {
+      title,
+      body: `${report}\n\n## Timeline\n\n${timeline}`,
+      labels: [label],
+    }),
+  };
+}

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

@@ -93,6 +93,11 @@ export type RunNoteKind =
    *  note says that loop's settlement instead: the executor waited for the
    *  wake and the run went on. */
   | "sandbox_restarted"
+  /** The run was admitted onto a drained fleet (docs/reference/specs/resident-repos.md
+   *  item 69) and waited at its attach for the deploy to finish: the summary
+   *  names the wait. Published by the dispatcher after the attach, so `runs
+   *  friction` reads the drain as the wait's category instead of "none". */
+  | "drain_wait"
   | "stop_requested"
   | "stopped"
   /** A stop the loop or turn had to ask pi for again reached it: the series a
@@ -317,6 +322,7 @@ export const RUN_NOTE_KINDS = [
   "sandbox_dead",
   "fleet_busy",
   "sandbox_restarted",
+  "drain_wait",
   "stop_requested",
   "stopped",
   "stop_landed",
@@ -537,15 +543,16 @@ export type RouteInputObject3 = { readonly [key: string]: RouteInputLeafOrList |
 export type RouteInputValue = RouteInputLeafOrList | RouteInputObject3;
 
 /** How a door decision about a state change ended (docs/decisions/0044-a-routed-write-is-confirmed-in-proportion-to-its-blast-radius.md):
- *  `hand_back` — the router bound a state-changing command and the door answered
- *  the line to paste, nothing invoked; `offered` — the same decision on a
+ *  `hand_back` — the door held a state-changing command and ran nothing: a
+ *  typed surface's refusal naming the typed form, or a chat surface's refusal
+ *  naming why the click could not mint; `offered` — the same decision on a
  *  channel that can show a confirmation: the line, its risk and a button, a
  *  row stored in the config object, nothing invoked; `confirmed` — the stored
- *  input ran at the click, as the requester, through the typed line's path;
- *  `pasted` — the typed line that followed a hand-back in its thread, with the
- *  same receipt, ran. A routed read carries no outcome: it is not a decision
- *  about a state change. */
-export type RouteOutcome = "hand_back" | "offered" | "confirmed" | "pasted" | "refused";
+ *  input ran at the click, as the requester, through the typed line's path.
+ *  A routed read carries no outcome: it is not a decision about a state
+ *  change. (A record from before the hand-back retired from chat may carry
+ *  `pasted`; nothing writes or reads it now.) */
+export type RouteOutcome = "hand_back" | "offered" | "confirmed" | "refused";
 
 export type RunEvent =
   /** `callId` is the provider's tool_use id — the explicit pair key between a
@@ -895,7 +902,17 @@ export type RunEvent =
    *  (`by: "push"`), or the budget-end salvage pushed (`by: "salvage"`),
    *  whether or not a pull request follows — the fact renewal reads. Published
    *  straight to the registry like `pr_opened`. Additive: unknown → ignored. */
-  | { type: "pushed_head"; ref: string; sha: string; by: "push" | "salvage"; seq?: number; at?: number }
+  | {
+      type: "pushed_head";
+      ref: string;
+      sha: string;
+      by: "push" | "salvage";
+      /** No uncommitted or unpushed work at the push (record 0064): the fact
+       *  the plane's soft stop reads. Absent where the measure was missing. */
+      clean?: boolean;
+      seq?: number;
+      at?: number;
+    }
   /** The coordinator tag as a fact of the run (docs/reference/specs/run-history.md
    *  item 48a): the instance the run is a child of, the unit its idempotency
    *  key named, and the base branch its pull request targets — published by
@@ -1014,11 +1031,10 @@ export type RunEvent =
    *  how the invoke ended is the run's own status and `answer`. A door
    *  decision about a state change (record 0044) is a command run too, with
    *  `outcome` saying which: a hand-back invoked nothing and its `answer` is
-   *  the line to paste; an offer invoked nothing and its `answer` is the offer
-   *  as the channel shows it; a confirmation is the stored input run at the
-   *  click, its `answer` the command's own text as a routed read's is; a paste is
-   *  the typed line that followed a hand-back, whatever its command,
-   *  `handBackRunId` naming the hand-back's record. */
+   *  the refusal the surface was shown (the typed form on a typed surface);
+   *  an offer invoked nothing and its `answer` is the offer as the channel
+   *  shows it; a confirmation is the stored input run at the click, its
+   *  `answer` the command's own text as a routed read's is. */
   | {
       type: "route";
       preset: string;
@@ -1038,7 +1054,6 @@ export type RunEvent =
        *  (record 0054): a refusal after a command was bound is a run
        *  record, and the door report counts it by cause and code. */
       refusalCode?: string;
-      handBackRunId?: string;
       seq?: number;
       at?: number;
     }
@@ -1060,6 +1075,11 @@ export type RunEvent =
       mode: "shadow" | "on";
       outcome: "binds" | "question" | "refusal" | "non_decision";
       reason: string;
+      /** The decision was the loop's floor (record 0069, as amended): a turn
+       *  that ended with no tool call, or the bounded re-asks ran out — the
+       *  readers' route ran the person's own request, and the event never
+       *  re-enters the loop. Additive: unknown → ignored. */
+      floored?: true;
       /** A bind marked `confirmed` is a pending question's confirmed proposal
        *  (`bindFromAnswer`): the line itself carries the task — the person's
        *  message was the word "yes" — so a confirmed preset line routes its
@@ -1069,6 +1089,13 @@ export type RunEvent =
       /** A question's proposed line, redacted and cut like the receipt — what
        *  the next turn's "yes" binds (`bindFromAnswer`). */
       proposal?: string;
+      /** A question's original ask, redacted and capped: the request the
+       *  question interrupted, kept so the person's next words in the thread
+       *  join back onto it (`joinedAnswerRequest` —
+       *  `<request> — <question>: <answer>`) and bind as the request would
+       *  have been, never routed as a bare fragment. Set on `question`
+       *  outcomes alone. Additive: unknown → ignored. */
+      request?: string;
       refusalCause?: string;
       refusalText?: string;
       attempts?: ReadonlyArray<{ outcome: "accepted" | "violation"; violation?: string }>;

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

@@ -39,6 +39,7 @@ export type FrictionCategory =
   | "wrap_up"
   | "budget_hit"
   | "infra_failure"
+  | "drain_wait"
   | "unkept_promise";
 
 export const FRICTION_CATEGORIES: readonly FrictionCategory[] = [
@@ -50,6 +51,7 @@ export const FRICTION_CATEGORIES: readonly FrictionCategory[] = [
   "wrap_up",
   "budget_hit",
   "infra_failure",
+  "drain_wait",
   "unkept_promise",
 ];
 
@@ -63,6 +65,7 @@ export const CATEGORY_LABEL: Record<FrictionCategory, string> = {
   wrap_up: "agent wind-down",
   budget_hit: "budget hits",
   infra_failure: "infra failures",
+  drain_wait: "the fleet drain",
   unkept_promise: "unkept promises",
 };
 
@@ -78,6 +81,7 @@ export const DENOMINATOR_OF: Record<FrictionCategory, "tool" | "run"> = {
   wrap_up: "run",
   budget_hit: "run",
   infra_failure: "run",
+  drain_wait: "run",
   unkept_promise: "run",
 };
 
@@ -574,6 +578,18 @@ export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOp
           eventIndex: index,
         });
         return;
+      case "drain_wait":
+        // The run was admitted onto a drained fleet (resident-repos item 69;
+        // issue 2044): the wait is the deploy's, its own category — a verdict
+        // of "none" over a run that sat half an hour at the drain was the
+        // incident's shape. No extent: the wait precedes the loop's spans.
+        findings.push({
+          category: "drain_wait",
+          severity: "medium",
+          summary: `fleet drained: ${ev.summary}`,
+          eventIndex: index,
+        });
+        return;
       case "sandbox_restarted":
         // 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

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

@@ -79,6 +79,12 @@ export interface LiveRunMeta {
   /** The run that spawned this one (item 46), so a reclaimed child's record
    *  still names its parent. Absent on every run a person or a schedule started. */
   parentRunId?: string;
+  /** The run this claim restarts (record 0064; run-history item 54): set by
+   *  the restart-from-request dispatch, so the plane knows the claim continues
+   *  a run it saw end `restarting` — the object sends the waiting parent
+   *  `child-resumed-<runId>` from it, and a `restartOf` ask passes the windows
+   *  and the memory line. Absent on every fresh request. */
+  restartOf?: string;
   /** The coordinator instance this run is a child of, and the key its spawn
    *  carried (item 48) — stored at the claim, so a reclaimed child's record
    *  still sends the parent its event and a retried spawn finds its run. */
@@ -150,10 +156,13 @@ export interface LiveRunRow {
   state: RunState;
 }
 
-/** One tool call the step dispatched; `tool` decides how a resume settles it. */
+/** One tool call the step dispatched; `tool` decides how a resume settles it.
+ *  `boundMs` is the bound the call declared (a bash `timeout`), when it stated
+ *  one — what the plane judges a `long_call` steer against (record 0064). */
 export interface InFlightCall {
   callId: string;
   tool: string;
+  boundMs?: number;
 }
 
 /** Written BEFORE a step's tools run (after its transcript turns landed). */
@@ -286,7 +295,7 @@ export type AppendableEvent = RunEvent & { seq: number };
 export interface IntakeReceipt {
   verdict: "addressed" | "silent";
   reason: string;
-  source: "model" | "mode" | "error" | "timeout";
+  source: "model" | "mode" | "question" | "error" | "timeout";
   /** The structured seam's attempts (docs/decisions/0067): what each answer
    *  violated, or that it was accepted; absent when no model was asked. */
   attempts?: ReadonlyArray<{ outcome: "accepted" | "violation"; violation?: string }>;
@@ -322,7 +331,11 @@ export function isIntakeReceipt(v: unknown): v is IntakeReceipt {
   return (
     (r.verdict === "addressed" || r.verdict === "silent") &&
     typeof r.reason === "string" &&
-    (r.source === "model" || r.source === "mode" || r.source === "error" || r.source === "timeout") &&
+    (r.source === "model" ||
+      r.source === "mode" ||
+      r.source === "question" ||
+      r.source === "error" ||
+      r.source === "timeout") &&
     (r.mode === "mention" || r.mode === "classify") &&
     typeof r.model === "string" &&
     typeof r.gen === "number" &&

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

@@ -225,6 +225,12 @@ export interface RunRecord {
    *  carried onto the record at the seal, so a history reader draws the run as
    *  a pipeline. Absent on every other run and on older records. */
   hosted?: true;
+  /** The reattach path restarted this run from its request when its workspace
+   *  could not be re-attached (record 0064; item 47a): the `interrupted` close
+   *  is not the run's end — the same id carries on — so a waiting parent keeps
+   *  waiting for `child_resumed` instead of ending its unit on this record.
+   *  Absent on every ending that is final. */
+  restarting?: true;
   /** 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
@@ -432,6 +438,9 @@ export interface RunOperatorDecision {
   question?: string;
   /** A question's proposed line — what the next turn's "yes" binds. */
   proposal?: string;
+  /** A question's original ask — what the person's next words join back onto
+   *  (`joinedAnswerRequest`). */
+  request?: string;
   refusalCause?: string;
   refusalText?: string;
   /** The structured seam's attempts (record 0067): what each answer violated,
@@ -456,6 +465,7 @@ export function operatorOfEvents(events: readonly RunEvent[]): RunOperatorDecisi
     ...(e.binds ? { binds: e.binds.map((b) => ({ line: b.line, reason: b.reason })) } : {}),
     ...(e.question !== undefined ? { question: e.question } : {}),
     ...(e.proposal !== undefined ? { proposal: e.proposal } : {}),
+    ...(e.request !== undefined ? { request: e.request } : {}),
     ...(e.refusalCause !== undefined ? { refusalCause: e.refusalCause } : {}),
     ...(e.refusalText !== undefined ? { refusalText: e.refusalText } : {}),
     ...(e.attempts
@@ -1017,6 +1027,8 @@ export function isRunRecord(v: unknown): v is RunRecord {
   // marker, like `provisional`, is the literal `true` or absent.
   if (r.pipeline !== undefined && !isPipelineSummaryShape(r.pipeline)) return false;
   if (r.hosted !== undefined && r.hosted !== true) return false;
+  // A restarting close carries the literal `true` or nothing (record 0064).
+  if (r.restarting !== undefined && r.restarting !== true) 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;

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

@@ -461,6 +461,19 @@ export const GATE_RECEIPTS =
   "Paste each command's exit line into the PR description's validation table as the row's proof; a gate you " +
   "could not run goes under the handoff's unproven list and is never claimed clean.";
 
+/** The rebase before every push lives in the coding preset's own instructions
+ *  (`REBASE_BEFORE_PUSH`, src/agents/registry.ts — agent-coding item 13;
+ *  record 0071 mechanism one): the base fetched, the branch rebased onto it,
+ *  the fast gates re-run on the rebased tree, then the push — always, never
+ *  configurable. The contract used to carry the conditional form ("rebase once
+ *  more if it moved while you worked"); now the first instruction points at
+ *  the preset's paragraph, the same shape as the fast-gates pointer above, so
+ *  the child reads the rule once and cannot read a softer one here. */
+export const REBASE_POINTER =
+  "The rebase before every push is your preset instructions' rule (REBASE BEFORE EVERY PUSH): it holds before " +
+  "each push here — always, not configurable — so every head you push is current with its base and the pull " +
+  "request is never born conflicting.";
+
 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";
@@ -470,8 +483,7 @@ function renderFirstInstruction(rebase: ChildContract["rebase"]): string {
     `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 the fast gates pass — the project's full verification ` +
     `is CI's gate, run there after the push with any fix as a further commit; an unpushed tree does not ` +
-    `survive the run's end. ${gates} 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, ` +
+    `survive the run's end. ${gates} ${REBASE_POINTER} At the wind-down note, ` +
     `commit and push what compiles, say what does not, then answer. ${TIMEOUT_ON_LONG_COMMANDS}`
   );
 }