@coreplane/switchboard 1.244.0 → 1.245.0

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

@@ -19,19 +19,83 @@
 // a fix round can reference each finding by its stable id and answer it with
 // a typed disposition (`parseDispositionsInput` below). Findings validate
 // fail-closed PER finding — a malformed finding drops with a note, a
-// malformed array drops the whole field — and an `approve` carrying a
-// self-declared `blocking` finding is downgraded to `request_changes`, so the
-// posted body can never begin with `LGTM:` over a defect the reviewer itself
-// called blocking.
+// malformed array drops the whole field.
+//
+// THE SEVERITY GATE (docs/reference/specs/agent-review.md item 5a): an
+// `approve` carrying a finding at or above the severity to address — the
+// level in force for the run, `minor` by default — is downgraded to
+// `request_changes` HERE, where the verdict is parsed, so the posted body can
+// never begin with `LGTM:` over a finding the loop would have to act on. The
+// gate is keyed on the RAW entries' declared severity, so a finding that
+// fails validation for another reason still poisons the approve. The same
+// ladder is what ship's coordinator holds a posted approve to (agent-ship.md
+// item 9) — that check is now defense in depth behind this one.
 
 import { normalizeHead } from "./reviewedHead.js";
 import { redactSecrets } from "./redact.js";
 
 export type ReviewVerdictKind = "approve" | "request_changes";
 
+/** The severity ladder, most to least severe. One list serves the findings a
+ *  reviewer submits and the level the loop addresses: a finding's severity is
+ *  compared to the level in force on this ladder, so nothing outside it can
+ *  reach a gate — the parser drops an entry with any other severity (`fyi`,
+ *  none) with a note. */
 export const FINDING_SEVERITIES = ["blocking", "major", "minor", "nit"] as const;
 export type FindingSeverity = (typeof FINDING_SEVERITIES)[number];
 
+/** The severity to address (the loop's gate on a round): an approve carrying a
+ *  finding at or above this level is not an approve. Resolved once per run —
+ *  the request's `severity:` directive over the user's scope over the
+ *  channel's over the org's `review.addressSeverity` — and handed to the
+ *  verdict parser and ship's coordinator alike. */
+export const ADDRESS_SEVERITIES = FINDING_SEVERITIES;
+export type AddressSeverity = FindingSeverity;
+/** Where the level in force came from, most specific wins: a `severity:`
+ *  directive on the request (`run`), the user's or the channel's config scope,
+ *  the org's `review.addressSeverity` (or its default). */
+export type AddressSeveritySource = "org" | "channel" | "user" | "run";
+export const DEFAULT_ADDRESS_SEVERITY: AddressSeverity = "minor";
+export const isAddressSeverity = (v: unknown): v is AddressSeverity =>
+  (ADDRESS_SEVERITIES as readonly unknown[]).includes(v);
+
+const severityRank = (s: AddressSeverity): number => ADDRESS_SEVERITIES.indexOf(s);
+/** Whether a declared severity sits at or above the level in force on the
+ *  ladder — the one comparison every gate makes. A value outside the ladder is
+ *  never at or above anything. */
+export function severityAtOrAbove(severity: unknown, level: AddressSeverity): severity is AddressSeverity {
+  return isAddressSeverity(severity) && severityRank(severity) <= severityRank(level);
+}
+/** The findings a gate acts on at `level`: at or above it. */
+export function findingsAtOrAbove(findings: readonly Finding[], level: AddressSeverity): Finding[] {
+  return findings.filter((f) => severityAtOrAbove(f.severity, level));
+}
+
+/** The level in force and the layer that set it: the request's
+ *  `severity:` directive wins, then the user's scope, the channel's, the org's
+ *  `review.addressSeverity` — the default counts as the org's. Resolved once
+ *  per run by the dispatcher (every review's verdict parser reads it) and once
+ *  per ship request by the hand-off, which writes it on the instance beside
+ *  `merge` and hands it to each review child as its `severity:` directive. */
+export function resolveAddressSeverity(layers: {
+  org?: AddressSeverity;
+  channel?: AddressSeverity;
+  user?: AddressSeverity;
+  run?: AddressSeverity;
+}): { level: AddressSeverity; source: AddressSeveritySource } {
+  if (layers.run !== undefined) return { level: layers.run, source: "run" };
+  if (layers.user !== undefined) return { level: layers.user, source: "user" };
+  if (layers.channel !== undefined) return { level: layers.channel, source: "channel" };
+  return { level: layers.org ?? DEFAULT_ADDRESS_SEVERITY, source: "org" };
+}
+
+/** The gate's one sentence — `finding(s) <id> (<severity>)[, …] at or above
+ *  <level>, the severity to address` — as the downgraded summary carries it into
+ *  the posted body and the tool's ack repeats it to the model. */
+export function downgradeNote(d: { findings: readonly string[]; level: AddressSeverity }): string {
+  return `finding${d.findings.length === 1 ? "" : "s"} ${d.findings.join(", ")} at or above ${d.level}, the severity to address`;
+}
+
 export interface Finding {
   /** Stable id the reviewer assigned in order ("F1", "F2", …) — dispositions
    *  reference findings by this id. */
@@ -63,50 +127,63 @@ export interface ReviewVerdict {
    *  reasons) — surfaced in the tool ack so the model can resubmit, never
    *  rendered into the posted body. */
   droppedFindings?: string[];
+  /** Parse note: the approve was downgraded by the severity gate — the gated
+   *  findings as `id (severity)` and the level in force. Surfaced in the tool
+   *  ack so the model knows its verdict changed; the summary carries the same
+   *  words into the posted body, so this never rides a record. */
+  downgraded?: { findings: string[]; level: AddressSeverity };
 }
 
 export const LGTM_TOKEN = "LGTM:";
 export const CHANGES_TOKEN = "Changes requested:";
 export const NO_VERDICT_LINE = "No verdict submitted — not approving.";
 
-/** Parse an arbitrary tool input into a verdict, or null when it is not one. */
-export function parseVerdictInput(input: Record<string, unknown>): ReviewVerdict | null {
+/** Parse an arbitrary tool input into a verdict, or null when it is not one.
+ *  `addressSeverity` is the level in force for the run (default `minor`): an
+ *  approve carrying a finding at or above it is parsed as `request_changes`. */
+export function parseVerdictInput(
+  input: Record<string, unknown>,
+  opts: { addressSeverity?: AddressSeverity } = {},
+): ReviewVerdict | null {
   const verdict = input.verdict;
   if (verdict !== "approve" && verdict !== "request_changes") return null;
+  const level = opts.addressSeverity ?? DEFAULT_ADDRESS_SEVERITY;
   const summary = typeof input.summary === "string" ? oneLine(input.summary) : "";
   const head = normalizeHead(input.head);
   const out: ReviewVerdict = { verdict, summary };
   if (head) out.head = head;
   if (input.findings !== undefined) {
-    const parsed = parseFindings(input.findings);
+    const parsed = parseFindings(input.findings, level);
     if (parsed.findings) out.findings = parsed.findings;
     if (parsed.dropped.length) out.droppedFindings = parsed.dropped;
-    // Verdict/severity consistency, fail-closed: an approve carrying a
-    // blocking finding downgrades so the posted body can never start with
-    // `LGTM:` over a self-declared blocking defect. Keyed on the RAW entries'
-    // declared severity, not the validated survivors — a blocking entry that
-    // itself failed validation and dropped still poisons the approve.
-    if (out.verdict === "approve" && parsed.blocking.length > 0) {
+    // The severity gate, fail-closed: an approve carrying a finding at or
+    // above the level in force downgrades, so the posted body can never start
+    // with `LGTM:` over a finding the loop has to address. Keyed on the RAW
+    // entries' declared severity, not the validated survivors — a gated entry
+    // that itself failed validation and dropped still poisons the approve.
+    if (out.verdict === "approve" && parsed.gated.length > 0) {
       out.verdict = "request_changes";
-      out.summary = oneLine(
-        `${out.summary} [downgraded from approve: blocking finding${parsed.blocking.length === 1 ? "" : "s"} ${parsed.blocking.join(", ")}]`,
-      );
+      out.downgraded = { findings: parsed.gated, level };
+      out.summary = oneLine(`${out.summary} [downgraded from approve: ${downgradeNote(out.downgraded)}]`);
     }
   }
   return out;
 }
 
 /** Fail-closed per finding: each malformed entry drops with a note naming its
- *  index (and id when readable); a non-array drops the whole field.
- *  `blocking` labels every raw entry that declared severity "blocking" —
- *  valid or not — for the approve downgrade above. */
-function parseFindings(value: unknown): { findings?: Finding[]; dropped: string[]; blocking: string[] } {
+ *  index (and id when readable); a non-array drops the whole field. `gated`
+ *  labels every raw entry whose declared severity sits at or above `level` —
+ *  valid or not — as `id (severity)`, for the approve downgrade above. */
+function parseFindings(
+  value: unknown,
+  level: AddressSeverity,
+): { findings?: Finding[]; dropped: string[]; gated: string[] } {
   if (!Array.isArray(value)) {
-    return { dropped: ["findings: dropped — not an array"], blocking: [] };
+    return { dropped: ["findings: dropped — not an array"], gated: [] };
   }
   const findings: Finding[] = [];
   const dropped: string[] = [];
-  const blocking: string[] = [];
+  const gated: string[] = [];
   value.forEach((raw, i) => {
     const parsed = parseFinding(raw);
     if (parsed.finding) {
@@ -116,9 +193,9 @@ function parseFindings(value: unknown): { findings?: Finding[]; dropped: string[
     }
     const label = parsed.finding?.id ?? parsed.id ?? `findings[${i}]`;
     const r = typeof raw === "object" && raw !== null ? (raw as Record<string, unknown>) : undefined;
-    if (r?.severity === "blocking") blocking.push(label);
+    if (severityAtOrAbove(r?.severity, level)) gated.push(`${label} (${r?.severity})`);
   });
-  return { findings, dropped, blocking };
+  return { findings, dropped, gated };
 }
 
 function parseFinding(

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

@@ -158,6 +158,13 @@ export type RunNoteKind =
    *  after the model's last turn — the release itself runs after the record
    *  is sealed — and set on the card's label too, so the loss is never silent. */
   | "work_left_behind"
+  /** The run's ending may have left a command running in its workspace — a
+   *  call cut by the ending's abort or interrupt, or open when the run failed —
+   *  so the release tears the workspace down rather than pair it for the
+   *  thread's next run (harness.md item 13). The summary names the calls.
+   *  Written by the run loop once the harness session has ended and before the
+   *  record is sealed; the release itself runs after. */
+  | "workspace_torn_down"
   /** A coding run submitted a PR description but the post-step opened no
    *  pull request because the branch it observed IS the base the pull
    *  request would target (docs/reference/specs/pr-description.md item 5) —
@@ -210,11 +217,20 @@ export type RunNoteKind =
    *  names the call and the step. Information, not a failure: the tool ran
    *  under the gate's decision either way. Published by the OpenCode bridge. */
   | "tool_unnamed"
+  /** An `external_directory` ask answered once its call's line was already on
+   *  the record (harness.md item 13): the line cannot be amended, so the
+   *  directory the call reached is said here, naming the call. Published by
+   *  the OpenCode bridge. */
+  | "directory_reached"
   /** A ship coding child's budget ended with work still in the tree: the run
    *  loop committed and pushed it to the unit's branch (or says plainly that
    *  there was nothing to push), so a re-issue starts from the partial work
    *  (docs/reference/specs/agent-ship.md item 8). */
   | "budget_salvage"
+  /** The loop's end found a tool call in flight and ended it, so the write-up
+   *  keeps its allowance (decision 0046, unit seven; harness-pi item 6). The
+   *  summary names the tools. Published by the harness beside the budget note. */
+  | "tool_cut"
   /** The native loop's stuck-loop guard: the same tool call failed identically
    *  six times in a row and the run was forced into its write-up. Written by
    *  no loop since that loop's deletion; a record from before it may carry it. */
@@ -225,6 +241,7 @@ export type RunNoteKind =
 export const RUN_NOTE_KINDS = [
   "wrap_up",
   "time_budget_exhausted",
+  "tool_cut",
   "turn_budget_exhausted",
   "sandbox_dead",
   "fleet_busy",
@@ -243,6 +260,7 @@ export const RUN_NOTE_KINDS = [
   "cold_sandbox",
   "rebind_refused",
   "work_left_behind",
+  "workspace_torn_down",
   "pr_not_opened",
   "review_not_posted",
   "compacted",
@@ -251,6 +269,7 @@ export const RUN_NOTE_KINDS = [
   "tool_refused",
   "settle_set_aside",
   "tool_unnamed",
+  "directory_reached",
   "budget_salvage",
   "stuck_loop",
 ] as const satisfies readonly RunNoteKind[];
@@ -460,7 +479,12 @@ export type RunEvent =
    *  executors' shared `exit N:` prefix, 0 for a clean run; absent when the code
    *  was not numeric). `output` is the tool's text — control-stripped, redacted,
    *  capped at TOOL_OUTPUT_CAP — for the run page's expandable card; the status
-   *  card and the friction analyzer keep reading `summary`. */
+   *  card and the friction analyzer keep reading `summary`. `cut` marks the
+   *  result of a call the run's ending cut rather than settled — pi's abort (the
+   *  tool's own end after it), OpenCode's interrupt (a call still open when its
+   *  loop left), a session's end (`closeOpenSpans`): the command behind it may
+   *  still be running, and the workspace's release reads it so (`callsInFlight`,
+   *  harness.md item 13). */
   | {
       type: "tool_result";
       tool: string;
@@ -470,6 +494,7 @@ export type RunEvent =
       exitCode?: number;
       output?: string;
       infra?: true;
+      cut?: true;
       spanId?: string;
       logIndex?: number;
       seq?: number;

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

@@ -291,6 +291,40 @@ export function pushedBranchesOf(events: readonly RunEvent[]): PushedBranch[] {
   return [...byRef].map(([ref, pr]) => ({ ref, pr }));
 }
 
+/** The tool calls a run's ending may have left running in its workspace, in
+ *  the record's order — what the workspace's release reads to tear the
+ *  workspace down rather than wait for an idle the command would refuse, and
+ *  what its note names (harness.md item 13). A call whose result is marked
+ *  `cut` — pi's abort, OpenCode's interrupt, a session's end — was ended, not
+ *  settled, whatever the run's status, and stays cut whatever lands for it
+ *  later — an unmarked result (a post-turn's bridge reads the earlier
+ *  execution's aborted settle as its own), or the call announced again under
+ *  the same id; a call with no result at
+ *  all was left open by a run that failed, was interrupted or hard-stopped,
+ *  while on a run that completed or stopped softly it is a relayed tool that
+ *  ran in the bot or a result lost to a transport gap, nothing running. Calls
+ *  and results pair by id; a result for a call the record never opened counts
+ *  for nothing. */
+export function callsInFlight(
+  events: readonly RunEvent[],
+  status: RunStatus,
+): Extract<RunEvent, { type: "tool_call" }>[] {
+  const calls = new Map<
+    string,
+    { call: Extract<RunEvent, { type: "tool_call" }>; state: "open" | "cut" | "settled" }
+  >();
+  for (const e of events) {
+    if (e.type === "tool_call" && e.callId !== undefined) {
+      if (calls.get(e.callId)?.state !== "cut") calls.set(e.callId, { call: e, state: "open" });
+    } else if (e.type === "tool_result" && e.callId !== undefined) {
+      const seen = calls.get(e.callId);
+      if (seen !== undefined && seen.state !== "cut") seen.state = e.cut === true ? "cut" : "settled";
+    }
+  }
+  const orderly = status === "completed" || status === "stopped_soft";
+  return [...calls.values()].filter((c) => c.state === "cut" || (c.state === "open" && !orderly)).map((c) => c.call);
+}
+
 /** The router's decision as a record carries it — the same fields the
  *  `route` event and the ledger row's `meta.route` carry (routing-and-config
  *  item 21). */

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

@@ -34,7 +34,18 @@ import type { Handoff } from "./handoff.js";
 import { progressOf, renderRenewal, renewalDecision, type PushedHeadFact, type RenewalDecision } from "./renewal.js";
 import type { RunStatus } from "../runRecord.js";
 import { normalizeHead, sameCommit } from "../reviewedHead.js";
-import { formatFinding, type Finding, type FindingDisposition, type ReviewVerdictKind } from "../reviewVerdict.js";
+import {
+  ADDRESS_SEVERITIES,
+  DEFAULT_ADDRESS_SEVERITY,
+  findingsAtOrAbove,
+  formatFinding,
+  isAddressSeverity,
+  type AddressSeverity,
+  type AddressSeveritySource,
+  type Finding,
+  type FindingDisposition,
+  type ReviewVerdictKind,
+} from "../reviewVerdict.js";
 import { parsePlanUnit, planUnitIds } from "./contract.js";
 import {
   carve,
@@ -598,26 +609,19 @@ export type CoordinatorNote =
  *  person can see whether the cap or the child is the problem. */
 export type ShipBudgetSpent = Readonly<Record<"coding" | "review" | "waiting", number>>;
 
-/** The severity ship must address before an approve stands (agent-ship item
- *  9's gate): an approve carrying a finding at or above this level continues
- *  into the findings step exactly as a request_changes does. Ordered most to
- *  least severe. */
-export const ADDRESS_SEVERITIES = ["blocking", "major", "minor", "nit"] as const;
-export type AddressSeverity = (typeof ADDRESS_SEVERITIES)[number];
-/** Where the level in force came from, most specific wins: a `severity:` directive on the request (`run`), the user's or the channel's config scope, the org's `ship.addressSeverity` (or its default). */
-export type AddressSeveritySource = "org" | "channel" | "user" | "run";
-export const DEFAULT_ADDRESS_SEVERITY: AddressSeverity = "minor";
-export const isAddressSeverity = (v: unknown): v is AddressSeverity =>
-  (ADDRESS_SEVERITIES as readonly unknown[]).includes(v);
-
-const severityRank = (s: AddressSeverity): number => ADDRESS_SEVERITIES.indexOf(s);
-/** The findings the gate acts on at `level`: at or above it. Every parsed
- *  finding carries one of the ladder's four levels — the verdict parser
- *  (`parseVerdictInput`) drops an entry with any other severity, `fyi` or none,
- *  with a note — so nothing outside the ladder ever reaches the gate. */
-export function findingsAtOrAbove(findings: readonly Finding[], level: AddressSeverity): Finding[] {
-  return findings.filter((f) => severityRank(f.severity) <= severityRank(level));
-}
+// The severity to address (agent-ship item 9's gate) is the verdict parser's
+// ladder (src/core/reviewVerdict.ts): the same level the parser holds a
+// submitted approve to, so a posted approve can carry a gated finding only
+// when it was parsed at a different level — the check below is defense in
+// depth behind the parser's. Re-exported here for the runner's callers.
+export {
+  ADDRESS_SEVERITIES,
+  DEFAULT_ADDRESS_SEVERITY,
+  findingsAtOrAbove,
+  isAddressSeverity,
+  type AddressSeverity,
+  type AddressSeveritySource,
+};
 
 export interface UnitSession {
   segment: number;

package/dist/assets/src/execution/residentRefresh.ts

@@ -241,14 +241,17 @@ export function fetchFailureIsMirrors(message: string): boolean {
 export const RUNTIME_MOVED_WORDING =
   /previous runtime incarnation|interrupted because the runtime changed|runtime identity is no longer active|sandbox lifetime is no longer current|platform was updating the sandbox runtime|no longer identifies pid/i;
 /** The platform's words for a container that is down under a command (see
- *  `RUNTIME_MOVED_WORDING`): the spawn refusal of a stopped container and the
- *  binding's not-running refusal, anchored to the full phrase so a genuine
+ *  `RUNTIME_MOVED_WORDING`): the spawn refusal of a stopped container, the
+ *  binding's not-running refusal, and the SDK's "The container just exited"
+ *  for a container that died under a live exec (a roll landing mid-step; the
+ *  bot side reads the same words as a roll, residentWake's
+ *  CONTAINER_GONE_WORDING), each anchored to the full phrase so a genuine
  *  crash ("container exited with unexpected exit code") and the readiness
  *  probe ("the container is not listening") never match. The harness's
  *  container seam reads the same two as a container down under its one more
  *  command — a wait, never a judgement (harness.md item 6). */
 export const STOPPED_CONTAINER_WORDING =
-  /process supervisor is closed|container is not running, consider calling start/i;
+  /process supervisor is closed|container is not running, consider calling start|the container just exited/i;
 export const RUNTIME_REPLACEMENT_WORDING = new RegExp(
   `${RUNTIME_MOVED_WORDING.source}|${STOPPED_CONTAINER_WORDING.source}`,
   "i",
@@ -358,12 +361,28 @@ export const SDK_RUNTIME_RECORD_KEY = "currentRuntimeIdentity";
 /** The DOMException the SDK's connect abort raises — `fetchUpgradeAttempt`
  *  calls `controller.abort()` with no reason when `DEFAULT_CONNECT_TIMEOUT_MS`
  *  passes, so the runtime's own `AbortError` with the message exactly `The
- *  operation was aborted`. Anchored on the WHOLE message, so a command's own
- *  `Aborted (core dumped)` never matches and neither does a `TimeoutError`'s
+ *  operation was aborted`. Anchored on the WHOLE message: a command's own
+ *  `Aborted (core dumped)` never matches, and neither does a `TimeoutError`'s
  *  `The operation was aborted due to timeout` — the text `AbortSignal.timeout`
- *  raises, a route's own bound on a slow GitHub, not a silent runtime. */
+ *  raises, a route's own bound on a slow GitHub, not a silent runtime. A
+ *  wrapper is read by its `cause`, where the DOMException rides whole; a
+ *  wrapper that only pasted the sentence into a longer message is not the
+ *  signal. */
 export const RUNTIME_UNREACHABLE_WORDING = /^The operation was aborted\.?$/;
 
+/** `err` and its `cause` chain, bounded like the SDK's own `selfAndCauses`
+ *  walker: the SDK wraps platform errors, so the telling message can sit one or
+ *  two links down. The one walker for every reader of a throw's chain — the
+ *  resident Worker's classifiers and its thread-error builders, the sandbox
+ *  Worker's — so the depth bound and the shape are decided once. */
+export function* selfAndCauses(err: unknown): Generator<unknown> {
+  let current = err;
+  for (let depth = 0; depth < 8 && current != null; depth++) {
+    yield current;
+    current = typeof current === "object" ? (current as { cause?: unknown }).cause : undefined;
+  }
+}
+
 /** Is this one link of an error's cause chain the SDK's connect abort? By
  *  name first (the DOMException's `AbortError`), by the DOMException's message
  *  when a wrapper copied only that. Applied by the Worker to the SPAWN-phase