@coreplane/switchboard 1.243.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) —
@@ -196,11 +203,34 @@ export type RunNoteKind =
    *  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. */
   | "tool_refused"
+  /** An OpenCode tool settled under a step this loop never saw start and the
+   *  settle was set aside (harness.md item 13): an earlier execution's late
+   *  result — the pinned binary's ordinary shape after a hung call's interrupt
+   *  — or a step lost with the tailer's stream. The summary names the call and
+   *  the step. Information, not a failure of the harness: nothing ran that the
+   *  gate did not decide. Published by the OpenCode bridge in its own mode. */
+  | "settle_set_aside"
+  /** OpenCode's store refill carried a permission over something other than a
+   *  tool (a directory outside the project, a repeating session) for a call
+   *  the record never saw, and the store held no part yet to name the call's
+   *  tool by: the call was opened under the permission's own name. The summary
+   *  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. */
@@ -211,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",
@@ -229,12 +260,16 @@ export const RUN_NOTE_KINDS = [
   "cold_sandbox",
   "rebind_refused",
   "work_left_behind",
+  "workspace_torn_down",
   "pr_not_opened",
   "review_not_posted",
   "compacted",
   "harness_error",
   "policy_refusal",
   "tool_refused",
+  "settle_set_aside",
+  "tool_unnamed",
+  "directory_reached",
   "budget_salvage",
   "stuck_loop",
 ] as const satisfies readonly RunNoteKind[];
@@ -293,7 +328,17 @@ export function sanitizeActor(actor: RunActor): RunActor {
  *  settles a round: caps end the pipeline BETWEEN rounds, visible as the
  *  absence of a next `started` boundary plus the answer's cap report. */
 export type ShipRoundOutcome =
-  "started" | "pr_opened" | "completed" | "approve" | "request_changes" | "no_verdict" | "aborted" | "stopped";
+  | "started"
+  | "pr_opened"
+  | "completed"
+  | "approve"
+  | "request_changes"
+  | "no_verdict"
+  | "aborted"
+  | "stopped"
+  /** The coding round ended at its lease with the unit unfinished and the row
+   *  showing progress, and the grant renewed: the next segment opens (decision 0046). */
+  | "continued";
 
 /**
  * One event in a run's stream. `seq` is stamped by `RunRegistry.publish` — a
@@ -393,10 +438,14 @@ 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; `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" | "pasted";
+ *  the line to paste, nothing invoked; `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";
 
 export type RunEvent =
   /** `callId` is the provider's tool_use id — the explicit pair key between a
@@ -430,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;
@@ -440,6 +494,7 @@ export type RunEvent =
       exitCode?: number;
       output?: string;
       infra?: true;
+      cut?: true;
       spanId?: string;
       logIndex?: number;
       seq?: number;
@@ -561,6 +616,10 @@ export type RunEvent =
        *  the instance's units. A child's instance rides the record's
        *  `parentInstanceId`, never here. */
       instanceId?: string;
+      /** The grant the ship request carried (decision 0046, the renewable
+       *  lease): renewals and a cost cap — what a renewal could spend. Written
+       *  on the pipeline's own record beside `instanceId`; absent elsewhere. */
+      grant?: { renewals: number; costCapUsd?: number };
       seq?: number;
       at?: number;
     }
@@ -691,6 +750,12 @@ export type RunEvent =
    *  start of the loop; a resumed run carries the original. Head material,
    *  like `run_meta`. Additive: unknown → ignored. */
   | { type: "lease"; startedAt: number; endsAt: number; loopEndsAt: number; seq?: number; at?: number }
+  /** A head the run pushed (docs/reference/specs/run-history.md item 2; decision
+   *  0046): the branch and the sha the coding post-step observed on the remote
+   *  (`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 }
   /** 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
@@ -755,8 +820,11 @@ 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; a paste is the typed line that followed, whatever its
-   *  command, `handBackRunId` naming the hand-back's record. */
+   *  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. */
   | {
       type: "route";
       preset: string;

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

@@ -426,7 +426,8 @@ export function analyzeRunFriction(events: readonly RunEvent[], opts: FrictionOp
       ev.type === "ship_round" ||
       ev.type === "route" ||
       ev.type === "reference" ||
-      ev.type === "lease"
+      ev.type === "lease" ||
+      ev.type === "pushed_head"
     ) {
       sideFactEvents++;
       return;

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

@@ -213,6 +213,10 @@ export interface RunRecord {
    *  `lease` event, folded at the assembly. Present only on a run whose
    *  harness started a loop; a record written before the event lacks it. */
   lease?: RunLease;
+  /** The heads the run pushed (item 2; decision 0046): one per branch, the
+   *  last `pushed_head` event's sha winning — the fact a renewal reads to know
+   *  the run made progress. Present only on a run that pushed. */
+  pushed?: PushedHead[];
   /** What the run cost in tokens, per model, summed from its `model.turn`
    *  spans at finish (`usageOfEvents`; docs/reference/specs/costs.md, cost by user).
    *  Every record written since carries it (zero turns included); one written
@@ -238,6 +242,21 @@ export interface RunLease {
   loopEndsAt: number;
 }
 
+/** A head a run pushed, as the record names it (item 2): the branch and the sha. */
+export interface PushedHead {
+  ref: string;
+  sha: string;
+}
+
+/** The heads a run's events say it pushed — one per branch, the last event's
+ *  sha winning, in first-seen order — or nothing when it pushed none. */
+export function pushedHeadsOf(events: readonly RunEvent[]): PushedHead[] | undefined {
+  const byRef = new Map<string, string>();
+  for (const e of events) if (e.type === "pushed_head") byRef.set(e.ref, e.sha);
+  if (byRef.size === 0) return undefined;
+  return [...byRef].map(([ref, sha]) => ({ ref, sha }));
+}
+
 /** The lease a run's events say its harness started — the first `lease`
  *  event; a resumed run's later generations publish none — or nothing. */
 export function leaseOfEvents(events: readonly RunEvent[]): RunLease | undefined {
@@ -272,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). */
@@ -798,6 +851,18 @@ export function isRunRecord(v: unknown): v is RunRecord {
   if (r.profile !== undefined && !isRunProfileRecord(r.profile)) return false;
   // The pull request the run reached (item 2): a positive integer and a URL, or absent.
   if (r.pr !== undefined && !isRunPullRequestShape(r.pr)) return false;
+  if (
+    r.pushed !== undefined &&
+    !(
+      Array.isArray(r.pushed) &&
+      r.pushed.every((h) => {
+        if (typeof h !== "object" || h === null) return false;
+        const { ref, sha } = h as Record<string, unknown>;
+        return typeof ref === "string" && ref.length > 0 && typeof sha === "string" && /^[0-9a-f]{7,40}$/.test(sha);
+      })
+    )
+  )
+    return false;
   // A parent is named by a run id (item 46): the same shape as the record's own.
   if (r.parentRunId !== undefined && (typeof r.parentRunId !== "string" || !RUN_ID_PATTERN.test(r.parentRunId)))
     return false;

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

@@ -431,7 +431,8 @@ function renderFirstInstruction(rebase: ChildContract["rebase"]): string {
     `Push the branch as soon as the change exists and its cheapest proving checks 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.`
+    `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.`
   );
 }