@coreplane/switchboard 1.205.0 → 1.206.0

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

@@ -0,0 +1,77 @@
+// Reviewed-head guard for the review post-step (docs/reference/specs/agent-review.md item 8).
+//
+// A review may only be posted to a PR when the commit the agent ACTUALLY
+// reviewed is the PR head resolved for the run (`RepoContext.headSha`). The
+// failure this guards against: the agent's own worktree is on the right
+// branch, but it fetches and checks out another PR's branch because the PR
+// body references it, reviews that, calls `submit_verdict approve`, and the
+// deterministic post-step puts `LGTM:` on the PR under review — which an
+// auto-approve workflow then approves. Every layer has done its job except the
+// one that asks "is this review OF this PR?".
+//
+// Two sources for the reviewed head, in authority order:
+//   observed — `git rev-parse HEAD` run by the dispatcher in the run's
+//              workspace AFTER the model finished and BEFORE the workspace is
+//              released (a resident worktree; authoritative). Absent when the
+//              cwd is not a git repo (the cold sandbox's workspace root — the
+//              clone lives in a subdirectory the agent chose).
+//   reported — the `head` the agent passed to `submit_verdict` (it is told to
+//              run `git rev-parse HEAD` in the checkout it reviewed). Consulted
+//              only when nothing was observed; an observed mismatch is never
+//              rescued by a matching report.
+//
+// Fail-closed: unknown PR head, or no head from either source → no post.
+
+export type HeadCheck = { ok: true; head: string; source: "observed" | "reported" } | { ok: false; reason: string };
+
+const FULL_SHA = /^[0-9a-f]{40}$/;
+const SHA_PREFIX = /^[0-9a-f]{7,40}$/;
+
+/** Normalize a reported/observed head: trimmed, lowercased, 7–40 hex; else undefined. */
+export function normalizeHead(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const h = value.trim().toLowerCase();
+  return SHA_PREFIX.test(h) ? h : undefined;
+}
+
+/** The 40-hex commit from `git rev-parse HEAD` output, or undefined when the
+ *  command failed (not a git repo, git missing) or printed nothing usable. */
+export function parseRevParseOutput(output: string): string | undefined {
+  for (const line of output.split(/\r?\n/)) {
+    const t = line.trim().toLowerCase();
+    if (FULL_SHA.test(t)) return t;
+  }
+  return undefined;
+}
+
+/** Two normalized heads name the same commit when one is a ≥7-hex prefix of
+ *  the other (the dispatcher's pre-run attach check reuses this). */
+export function sameCommit(a: string, b: string): boolean {
+  const n = Math.min(a.length, b.length);
+  return n >= 7 && a.slice(0, n) === b.slice(0, n);
+}
+
+/**
+ * Decide whether the reviewed head is the PR head. `expected` is the PR head
+ * from repo resolution; `observed` the dispatcher's own `git rev-parse HEAD`
+ * (40-hex or undefined); `reported` whatever the agent passed to submit_verdict.
+ */
+export function checkReviewedHead(input: { expected?: string; observed?: string; reported?: string }): HeadCheck {
+  const expected = normalizeHead(input.expected);
+  if (!expected) return { ok: false, reason: "PR head unknown at resolution time — cannot verify what was reviewed" };
+  const observed = normalizeHead(input.observed);
+  if (observed) {
+    return sameCommit(observed, expected)
+      ? { ok: true, head: observed, source: "observed" }
+      : { ok: false, reason: `reviewed head ${observed.slice(0, 7)} is not the PR head ${expected.slice(0, 7)}` };
+  }
+  const reported = normalizeHead(input.reported);
+  if (!reported)
+    return {
+      ok: false,
+      reason: "reviewed head unknown — the workspace HEAD could not be read and no head was reported with the verdict",
+    };
+  return sameCommit(reported, expected)
+    ? { ok: true, head: reported, source: "reported" }
+    : { ok: false, reason: `reviewed head ${reported.slice(0, 7)} is not the PR head ${expected.slice(0, 7)}` };
+}

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

@@ -319,8 +319,10 @@ export type RunEvent =
       text: string;
       /** Where the request came from, for the Request block: the channel and
        *  user display names and a link back to the triggering message —
-       *  whatever the adapter supplied (all optional). */
-      source?: { url?: string; channel?: string; user?: string };
+       *  whatever the adapter supplied (all optional) — and, for a follow-up a
+       *  run sent rather than a person (a parent's `send_to_run`), that run's
+       *  id (docs/reference/specs/agent-conductor.md item 8). */
+      source?: { url?: string; channel?: string; user?: string; run?: string };
       seq?: number;
       at?: number;
     }

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

@@ -9,7 +9,7 @@ import type { ClaimResult, FenceResult, LivePhase } from "./types.js";
  *  after a lost response), anything else is refused with what the steer
  *  message needs. */
 export function decideClaim(
-  existing: { runId: string; agent?: string; startedAt: number; ownerGen: string } | undefined,
+  existing: { runId: string; agent?: string; startedAt: number; ownerGen: string; idempotencyKey?: string } | undefined,
   req: { runId: string; gen: string },
 ): ClaimResult {
   if (!existing) return { ok: true };
@@ -21,6 +21,7 @@ export function decideClaim(
       runId: existing.runId,
       ...(existing.agent !== undefined ? { agent: existing.agent } : {}),
       startedAt: existing.startedAt,
+      ...(existing.idempotencyKey !== undefined ? { idempotencyKey: existing.idempotencyKey } : {}),
     },
   };
 }

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

@@ -61,6 +61,14 @@ export interface LiveRunMeta {
    *  budget instead of re-reading the preset's. Absent on rows written before
    *  profiles existed. */
   profile?: RunProfile;
+  /** 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 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. */
+  parentInstanceId?: string;
+  idempotencyKey?: string;
   /** Which executor the run attached: what `makeExecutor` chose. */
   selection?: "resident" | "sandbox" | "local" | "none";
   /** The worktree path the system prompt names. */
@@ -143,8 +151,16 @@ export interface ClaimRequest {
   phase?: "attaching" | "live";
 }
 
+/** A refused claim names the run holding the thread — and the coordinator key
+ *  its row carries (item 48), so a retried spawn can tell its own child from
+ *  a busy thread. */
 export type ClaimResult =
-  { ok: true } | { ok: false; reason: "thread-live"; live: { runId: string; agent?: string; startedAt: number } };
+  | { ok: true }
+  | {
+      ok: false;
+      reason: "thread-live";
+      live: { runId: string; agent?: string; startedAt: number; idempotencyKey?: string };
+    };
 
 export type FenceResult = { ok: true } | { ok: false; reason: "fenced" | "unknown-run" };
 

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

@@ -3,6 +3,13 @@ import type { BoundaryScope, Identity, MachineClass, RunProfile } from "../confi
 import type { RunEvent } from "./runEvents.js";
 import { isHeadMaterial, isSpanRecord } from "./runEvents.js";
 import { isHandoffShape, type Handoff } from "./ship/handoff.js";
+import {
+  isFindingDispositionsShape,
+  isReviewVerdictShape,
+  type FindingDisposition,
+  type ReviewVerdict,
+} from "./reviewVerdict.js";
+import { IDEMPOTENCY_KEY_PATTERN, INSTANCE_ID_PATTERN } from "./coordinator/contract.js";
 import {
   FRICTION_CATEGORIES,
   type CategoryTotals,
@@ -32,6 +39,8 @@ const RUN_STATUSES: readonly RunStatus[] = ["completed", "stopped_soft", "stoppe
 
 /** Every `runs.*` id: checked before any store call. */
 export const RUN_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/** A reviewed head as the record stores it: the normalized sha (`normalizeHead`), 7 to 40 lowercase hex. */
+const REVIEW_HEAD_PATTERN = /^[0-9a-f]{7,40}$/;
 
 /** One finished run as the store keeps it. Events are already redacted and
  *  capped upstream (`runEvents.ts`); this layer adds no data. */
@@ -98,12 +107,36 @@ export interface RunRecord {
    *  three empty lists, distinguishable from none); absent on every other run
    *  and on records written before it existed. */
   handoff?: Handoff;
+  /** The verdict a review run submitted through `submit_verdict` (docs/reference/specs/agent-review.md),
+   *  redacted like every stored string — what a coordinator's `read-record`
+   *  answers for a review child. Present only on a run that submitted one. */
+  verdict?: ReviewVerdict;
+  /** The head a review run reviewed and posted against (7 to 40 lowercase hex),
+   *  after the settle; present only on a review run that pinned one. */
+  reviewHead?: string;
+  /** The dispositions a fix round submitted through `submit_dispositions`
+   *  (docs/reference/specs/agent-ship.md item 6), the last call's set, redacted;
+   *  present only on a coding run dispatched as a fix round that submitted one. */
+  dispositions?: FindingDisposition[];
   /** The effective profile the run was admitted with (docs/decisions/0026-capability-profiles-and-request-routing.md):
    *  the preset, its machine class and identity, the minutes it ran on and —
    *  when a boundary clipped the budget — the scope that did, so a reader can
    *  tell a clipped budget from a declared one. Absent on records written
    *  before profiles existed. */
   profile?: RunProfileRecord;
+  /** The run that spawned this one (item 46): a child started through
+   *  `spawnChild()` names its parent, so a listing can draw the tree. Absent
+   *  on every run a person or a schedule started. */
+  parentRunId?: string;
+  /** The coordinator instance this run is a child of (item 48): the state
+   *  Worker's finish sends that instance `run finished:<id>` for a record
+   *  carrying it, and `read-record` answers only for a matching instance.
+   *  Absent on every run no coordinator spawned. */
+  parentInstanceId?: string;
+  /** The key the coordinator's spawn carried (`<parentInstanceId>:<step>`,
+   *  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 profile as the record stores it: the run's effective profile plus the preset it came from. */
@@ -124,6 +157,7 @@ const BOUNDARY_SCOPES_IN_RECORD: Record<BoundaryScope, true> = {
   channel: true,
   user: true,
   directive: true,
+  parent: true,
 };
 
 /** Structural check on a stored profile (item 3's rule for the field). */
@@ -462,7 +496,29 @@ export function isRunRecord(v: unknown): v is RunRecord {
   // The handoff is checked for shape, not bounds (docs/reference/specs/agent-ship.md
   // item 14): redaction may lengthen a stored string past the tool's limit.
   if (r.handoff !== undefined && !isHandoffShape(r.handoff)) return false;
+  // The review's verdict and head and the fix round's dispositions (item 2):
+  // shape only, like the handoff — redaction may lengthen a stored string.
+  if (r.verdict !== undefined && !isReviewVerdictShape(r.verdict)) return false;
+  if (r.reviewHead !== undefined && (typeof r.reviewHead !== "string" || !REVIEW_HEAD_PATTERN.test(r.reviewHead)))
+    return false;
+  if (r.dispositions !== undefined && !isFindingDispositionsShape(r.dispositions)) return false;
   if (r.profile !== undefined && !isRunProfileRecord(r.profile)) 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;
+  // A coordinator's child (item 48): the instance id in the platform's alphabet
+  // and the key `<instance>:<step>` — both or neither; one alone is no tag.
+  if ((r.parentInstanceId === undefined) !== (r.idempotencyKey === undefined)) return false;
+  if (
+    r.parentInstanceId !== undefined &&
+    (typeof r.parentInstanceId !== "string" || !INSTANCE_ID_PATTERN.test(r.parentInstanceId))
+  )
+    return false;
+  if (
+    r.idempotencyKey !== undefined &&
+    (typeof r.idempotencyKey !== "string" || !IDEMPOTENCY_KEY_PATTERN.test(r.idempotencyKey))
+  )
+    return false;
   if (typeof r.channelId !== "string" || typeof r.userId !== "string" || typeof r.threadKey !== "string") return false;
   // Absent on records written before the stamp existed (read as `unknown`); present → a known value.
   if (r.channelVisibility !== undefined && !CHANNEL_VISIBILITIES.includes(r.channelVisibility as ChannelVisibility))