@sun-asterisk/sungen 3.3.0-alpha.1 → 3.3.0-alpha.3

package/src/contract/trace/read-file-once.ts

@@ -0,0 +1,95 @@
+/**
+ * Read trace evidence (a run record, a JSON report, a trace.zip) by opening it ONCE and checking what
+ * was opened (#926) — never "check the path, then read the path", which leaves a window in which the
+ * file can be swapped for a link to anything outside the project.
+ *
+ *   readFileOnce(file)                     a regular file, read from its descriptor; O_NONBLOCK so a
+ *                                          FIFO swapped in cannot hang the guard; size checked on the
+ *                                          descriptor before a byte is read
+ *   readInsideProject(root, file)          the same for a path from untrusted input:
+ *                                            1. its real path must sit inside the project's real root
+ *                                            2. that real path is opened with O_NOFOLLOW (a link put
+ *                                               there in the meantime fails the open)
+ *                                            3. AFTER the open the path is resolved again: still inside,
+ *                                               and the same file (device + inode) as the descriptor —
+ *                                               a swap made before the open and undone after it is caught
+ *
+ * A file truncated or grown while it is read gives the bytes the descriptor had; the caller hashes
+ * those bytes, so nothing unread is ever vouched for.
+ *
+ * Windows has no O_NOFOLLOW (the constant is 0 there): the open follows a link swapped in, and the
+ * device + inode re-check after the open is what refuses it.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export type FileRead =
+  | { status: 'read'; real: string; bytes: Buffer }
+  | { status: 'missing' }
+  | { status: 'outside'; why: string }
+  | { status: 'not-a-file' }
+  | { status: 'too-large'; size: number };
+
+const { O_RDONLY } = fs.constants;
+const O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+const O_NONBLOCK = fs.constants.O_NONBLOCK ?? 0;
+
+function readFd(fd: number, size: number): Buffer {
+  const buf = Buffer.alloc(size);
+  let off = 0;
+  while (off < size) {
+    const n = fs.readSync(fd, buf, off, size - off, off);
+    if (n === 0) break;
+    off += n;
+  }
+  return off === size ? buf : buf.subarray(0, off);
+}
+
+function openAndRead(file: string, flags: number, maxBytes: number, recheck?: (opened: fs.Stats) => string | null): FileRead {
+  let fd: number;
+  try { fd = fs.openSync(file, flags); } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') return { status: 'missing' };
+    // O_NOFOLLOW on a link: ELOOP (Linux, macOS) or EMLINK (FreeBSD).
+    if (code === 'ELOOP' || code === 'EMLINK') return { status: 'outside', why: 'it became a link while it was opened' };
+    throw e;
+  }
+  try {
+    const st = fs.fstatSync(fd);
+    if (!st.isFile()) return { status: 'not-a-file' };
+    if (st.size > maxBytes) return { status: 'too-large', size: st.size };
+    const moved = recheck?.(st);
+    if (moved) return { status: 'outside', why: moved };
+    return { status: 'read', real: file, bytes: readFd(fd, st.size) };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/** A regular file, opened once and read from that descriptor. */
+export const readFileOnce = (file: string, maxBytes = Number.POSITIVE_INFINITY): FileRead =>
+  openAndRead(file, O_RDONLY | O_NONBLOCK, maxBytes);
+
+/** A regular file INSIDE the project (symlinks resolved), opened once; see the header for the checks. */
+export function readInsideProject(projectRoot: string, file: string, maxBytes = Number.POSITIVE_INFINITY): FileRead {
+  let root: string;
+  let real: string;
+  try {
+    root = fs.realpathSync(projectRoot);
+    real = fs.realpathSync(file);
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code === 'ENOENT' ? { status: 'missing' } : { status: 'outside', why: 'its real path cannot be resolved' };
+  }
+  const within = (p: string): boolean => p.startsWith(root + path.sep);
+  if (!within(real)) return { status: 'outside', why: 'its real path is outside the project' };
+  return openAndRead(real, O_RDONLY | O_NOFOLLOW | O_NONBLOCK, maxBytes, (opened) => {
+    try {
+      const again = fs.realpathSync(file);
+      if (!within(again)) return 'it was swapped for a link outside the project while it was opened';
+      const now = fs.statSync(again);
+      return now.dev === opened.dev && now.ino === opened.ino ? null : 'it was swapped for another file while it was opened';
+    } catch {
+      return 'it moved while it was opened';
+    }
+  });
+}

package/src/contract/trace/select-final-attempt.ts

@@ -32,10 +32,10 @@ function resultOf(r: unknown): ReportResult | null {
   return { retry: r.retry as number, status: r.status, startTime: String(r.startTime ?? ''), duration: Number(r.duration) || 0, tracePath: trace?.path ?? null };
 }
 
-/** Every test of a report; throws when the file is not a Playwright JSON report at all. */
-export function readPlaywrightReport(file: string): ReportTest[] {
+/** Every test of a report (`text`: its bytes, already read once by the caller); throws when it is not a Playwright JSON report at all. */
+export function readPlaywrightReport(file: string, text?: string): ReportTest[] {
   let doc: unknown;
-  try { doc = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { throw new Error(`the JSON report ${file} is not readable (${(e as Error).message.split('\n')[0]})`); }
+  try { doc = JSON.parse(text ?? fs.readFileSync(file, 'utf8')); } catch (e) { throw new Error(`the JSON report ${file} is not readable (${(e as Error).message.split('\n')[0]})`); }
   if (!isObj(doc) || !Array.isArray(doc.suites)) throw new Error(`${file} is not a Playwright JSON report (no suites)`);
   const out: ReportTest[] = [];
   for (const top of doc.suites) {

package/src/contract/trace/test-step-join.ts

@@ -1,7 +1,8 @@
 /**
  * Join the test runner's steps (test.trace) with the browser calls (<N>-trace.trace) — phase 07
- * criterion 2, proven 114/114 on a real app. A library call's `stepId` is the runner step's
- * `callId`; walking the runner's `parentId` chain says where the call ran:
+ * criterion 2, proven 114/114 on a real app. Up to format 9 a library call's `stepId` is the runner
+ * step's `callId`; from format 10 (Playwright 1.64) the two share ONE id and `stepId` is gone, so the
+ * call's own `callId` is the step. Walking the runner's `parentId` chain says where the call ran:
  *
  *   body       the test function itself, with the path of enclosing `test.step` titles
  *   hook       a user `beforeEach` / `afterEach` (stage setup | teardown)
@@ -26,7 +27,7 @@ export type CallPhase =
   | { phase: 'unjoined' };
 
 export interface JoinedCall {
-  part: string; callId: string; callNumber: number; class: string; method: string;
+  part: string; callId: string; class: string; method: string;
   params: Record<string, unknown>; stepId?: string; where: CallPhase; failed: boolean; startTime: number;
 }
 
@@ -90,9 +91,9 @@ export function joinCalls(trace: ParsedTrace): { steps: Map<string, RunnerStep>;
     for (const e of part.events) {
       if (e.type !== 'before') continue;
       const callId = str(e.callId);
-      const stepId = str(e.stepId) || undefined;
+      const stepId = str(e.stepId) || (part.version >= 10 ? callId : '') || undefined;
       calls.push({
-        part: part.name, callId, callNumber: Number(callId.replace(/^call@/, '')) || 0, class: str(e.class), method: str(e.method),
+        part: part.name, callId, class: str(e.class), method: str(e.method),
         params: (e.params && typeof e.params === 'object' ? e.params : {}) as Record<string, unknown>,
         stepId, where: stepId ? classifyStep(steps, stepId) : { phase: 'unjoined' }, failed: failed.has(callId), startTime: Number(e.startTime) || 0,
       });

package/src/contract/trace/trace-file-reader.ts

@@ -5,20 +5,25 @@
  *   test.trace            the test runner's steps (test.step, hooks, fixtures, expect, pw:api)
  *   <N>-trace.trace       a library part: the browser calls, frame snapshots, logs
  *   <N>-trace.network     resources (stylesheets inlined into a replayed snapshot come from here)
- *   <N>-trace.stacks      call number → source frames (`file:line` of an opaque step)
+ *   <N>-trace.stacks      call id → source frames (`file:line` of an opaque step)
  *   resources/<sha1>      resource bodies
  *
  * Every part that has a header (test.trace and each library part) must declare a supported version;
  * a part without one is refused. Every JSONL line must parse — a line that does not is never skipped.
  */
 import { createHash } from 'crypto';
-import * as fs from 'fs';
+import { FileRead, readFileOnce } from './read-file-once';
 import { openZip, ZipArchive } from './trace-zip-reader';
 import { SUPPORTED_TRACE_VERSIONS, traceZipLimits, TraceRejected, TraceZipLimits } from './trace-zip-limits';
 
 export type TraceEvent = { type: string } & Record<string, unknown>;
 export interface StackFrame { file: string; line: number; column: number }
-export interface LibraryPart { name: string; events: TraceEvent[]; network: TraceEvent[]; stacks: Map<number, StackFrame[]> }
+/**
+ * One library part. `version` is its declared format (already accepted by the gate); `stacks` is
+ * keyed by call id — v8/v9 wrote a call NUMBER (`11` → `call@11`, Playwright's legacy id), v10 the
+ * call id itself, which it shares with the runner step (`ulgt@50`).
+ */
+export interface LibraryPart { name: string; version: number; events: TraceEvent[]; network: TraceEvent[]; stacks: Map<string, StackFrame[]> }
 
 export interface ParsedTrace {
   label: string;
@@ -56,19 +61,21 @@ function parseJsonl(zip: ZipArchive, name: string): TraceEvent[] {
   return out;
 }
 
-function parseStacks(zip: ZipArchive, name: string): Map<number, StackFrame[]> {
-  const out = new Map<number, StackFrame[]>();
+function parseStacks(zip: ZipArchive, name: string): Map<string, StackFrame[]> {
+  const out = new Map<string, StackFrame[]>();
   if (!zip.has(name)) return out;
   let doc: { files?: unknown; stacks?: unknown };
   try { doc = JSON.parse(zip.readText(name)); } catch { throw new TraceRejected('trace.malformed', `${name} is not JSON`); }
   const files = Array.isArray(doc.files) ? doc.files.map(String) : [];
   for (const row of Array.isArray(doc.stacks) ? doc.stacks : []) {
-    if (!Array.isArray(row) || typeof row[0] !== 'number' || !Array.isArray(row[1])) continue;
+    if (!Array.isArray(row) || !Array.isArray(row[1])) continue;
+    const id = typeof row[0] === 'number' ? `call@${row[0]}` : row[0];
+    if (typeof id !== 'string' || !CALL_ID.test(id)) continue;
     const frames = (row[1] as unknown[]).filter(Array.isArray).map((f) => {
       const [fileIdx, line, column] = f as number[];
       return { file: files[fileIdx] ?? '', line: Number(line) || 0, column: Number(column) || 0 };
     });
-    out.set(row[0], frames);
+    out.set(id, frames);
   }
   return out;
 }
@@ -81,9 +88,12 @@ export function readTraceBuffer(buf: Buffer, label: string, limits: TraceZipLimi
   const runner = parseJsonl(zip, 'test.trace');
   const library: LibraryPart[] = zip.names().filter((n) => /^\d+-trace\.trace$/.test(n)).sort().map((n) => {
     const base = n.replace(/\.trace$/, '');
+    const events = parseJsonl(zip, n);
+    const version = headerOf(events)?.version;
     return {
       name: n,
-      events: parseJsonl(zip, n),
+      version: typeof version === 'number' ? version : NaN, // a non-number is refused just below
+      events,
       network: zip.has(`${base}.network`) ? parseJsonl(zip, `${base}.network`) : [],
       stacks: parseStacks(zip, `${base}.stacks`),
     };
@@ -114,10 +124,21 @@ export function readTraceBuffer(buf: Buffer, label: string, limits: TraceZipLimi
   };
 }
 
-/** Read a trace from disk: a regular file, size-checked BEFORE it is read into memory. */
+/**
+ * A trace opened once (read-file-once.ts) → parsed: the size was checked on the descriptor BEFORE it
+ * was read into memory. `missing` / `outside` are the caller's to report; here they throw.
+ */
+export function traceFromRead(read: FileRead, label: string, limits: TraceZipLimits = traceZipLimits()): ParsedTrace {
+  switch (read.status) {
+    case 'read': return readTraceBuffer(read.bytes, read.real, limits);
+    case 'too-large': throw new TraceRejected('zip.too-large', `${read.size} B > ${limits.maxZipBytes}`);
+    case 'not-a-file': throw new TraceRejected('zip.malformed', `${label} is not a regular file`);
+    case 'missing': throw new TraceRejected('zip.malformed', `${label} does not exist`);
+    default: throw new TraceRejected('zip.malformed', `${label} was not read: ${read.why}`);
+  }
+}
+
+/** Read a trace from a trusted path (a fixture, a test): a regular file, opened once. */
 export function readTraceFile(file: string, limits: TraceZipLimits = traceZipLimits()): ParsedTrace {
-  const st = fs.statSync(file);
-  if (!st.isFile()) throw new TraceRejected('zip.malformed', `${file} is not a regular file`);
-  if (st.size > limits.maxZipBytes) throw new TraceRejected('zip.too-large', `${st.size} B > ${limits.maxZipBytes}`);
-  return readTraceBuffer(fs.readFileSync(file), file, limits);
+  return traceFromRead(readFileOnce(file, limits.maxZipBytes), file, limits);
 }

package/src/contract/trace/trace-run-record.ts

@@ -4,9 +4,10 @@
  * the code that produced it live, so an unknown key, a wrong type or a malformed hash means the
  * record is not trusted at all (every trace it would vouch for is unbound).
  *
- * Found by convention: `<project>/test-results/sungen-run-record*.json` (one per run or shard).
- * Playwright wipes `test-results/` at the start of every run, so a record and its traces share a
- * lifetime.
+ * Found by convention: `<project>/test-results-free/sungen-run-record*.json` — the free-test config's
+ * own outputDir (#941) — or `<project>/test-results/sungen-run-record*.json` (one per run or shard).
+ * Playwright wipes its outputDir at the start of every run, so a record and its traces share a
+ * lifetime; the free run has its own so the compiled suite's next run cannot delete its traces.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -31,13 +32,18 @@ const ATTEMPT = new Set(['testId', 'file', 'title', 'retry', 'status', 'startTim
 const SHA = /^[0-9a-f]{64}$/;
 const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
 
-export const RUN_RECORD_DIR = 'test-results';
+/** The free / impl:code run's own outputDir (the documented free-test config); compiled runs clear `test-results/`. */
+export const FREE_RUN_DIR = 'test-results-free';
+/** Where run records are read, in this order: the free run's dir, then Playwright's default (older configs). */
+export const RUN_RECORD_DIRS: readonly string[] = [FREE_RUN_DIR, 'test-results'];
 
 export function findRunRecords(projectRoot: string): string[] {
-  const dir = path.join(projectRoot, RUN_RECORD_DIR);
-  let names: string[];
-  try { names = fs.readdirSync(dir); } catch { return []; }
-  return names.filter((n) => /^sungen-run-record(?:\.[A-Za-z0-9._-]+)?\.json$/.test(n)).sort().map((n) => path.join(dir, n));
+  return RUN_RECORD_DIRS.flatMap((rel) => {
+    const dir = path.join(projectRoot, rel);
+    let names: string[];
+    try { names = fs.readdirSync(dir); } catch { return []; }
+    return names.filter((n) => /^sungen-run-record(?:\.[A-Za-z0-9._-]+)?\.json$/.test(n)).sort().map((n) => path.join(dir, n));
+  });
 }
 
 function attemptOf(raw: unknown, i: number): RunRecordAttempt {
@@ -54,10 +60,10 @@ function attemptOf(raw: unknown, i: number): RunRecordAttempt {
   return { testId, file, title, retry: retry as number, status, startTime, duration, trace: trace as RunRecordAttempt['trace'] };
 }
 
-/** Read and check one record; throws an Error naming what is wrong. */
-export function readRunRecord(file: string): RunRecord {
+/** Read and check one record (`text`: its bytes, already read once by the caller); throws an Error naming what is wrong. */
+export function readRunRecord(file: string, text?: string): RunRecord {
   let raw: unknown;
-  try { raw = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { throw new Error(`not readable JSON (${(e as Error).message.split('\n')[0]})`); }
+  try { raw = JSON.parse(text ?? fs.readFileSync(file, 'utf8')); } catch (e) { throw new Error(`not readable JSON (${(e as Error).message.split('\n')[0]})`); }
   if (!isObj(raw)) throw new Error('not an object');
   const extra = Object.keys(raw).find((k) => !TOP.has(k));
   if (extra) throw new Error(`unknown key "${extra}"`);

package/src/contract/trace/trace-steps.ts

@@ -70,7 +70,7 @@ export function traceIntentSteps(trace: ParsedTrace): IntentStep[] {
     const runner = c.stepId ? steps.get(c.stepId) : undefined;
     out.push({
       kind, method: c.method, callId: c.callId, params: c.params, group: groupOf(steps, c.stepId),
-      location: firstFrame(runner?.stack) ?? firstFrame(stacks.get(c.part)?.get(c.callNumber)),
+      location: firstFrame(runner?.stack) ?? firstFrame(stacks.get(c.part)?.get(c.callId)),
       ...(verbatim ? { verbatim } : {}), startTime: c.startTime,
     });
   }

package/src/contract/trace/trace-zip-limits.ts

@@ -50,8 +50,12 @@ export function traceZipLimits(env: Record<string, string | undefined> = process
   };
 }
 
-/** Trace format versions this reader was verified against: 8 = Playwright 1.57, 9 = 1.63. */
-export const SUPPORTED_TRACE_VERSIONS: ReadonlySet<number> = new Set([8, 9]);
+/**
+ * Trace format versions this reader was verified against: 8 = Playwright 1.57, 9 = 1.63, 10 = 1.64
+ * (one shared call id for a library call and its runner step; stacks keyed by that id). Anything
+ * else — a newer format included — is refused until it has been checked the same way.
+ */
+export const SUPPORTED_TRACE_VERSIONS: ReadonlySet<number> = new Set([8, 9, 10]);
 
 export type TraceRejectCode =
   | 'zip.too-large' | 'zip.too-many-entries' | 'zip.entry-too-large' | 'zip.total-too-large' | 'zip.ratio'

package/src/contract/verify-approval-decisions.ts

@@ -2,9 +2,10 @@
  * Every approved lock entry must be vouched for by its decision (DOS-13.2, DOS-14.4, review M1):
  * `qa/<kind>/<unit>/decisions/<decisionId>.yaml`, COMMITTED in git HEAD (outside git: on disk),
  * intact (schema, id = content, entry_hash = entry), of kind `contract-approval`, whose payload lists
- * this scenario at this hash, and whose `valid_from` is the entry's `approvedAt`. A lock line copied
- * from elsewhere, re-pointed at another decision, or backdated fails here — `unverified`, reported
- * under contract.lock-uncommitted (hard).
+ * this scenario at this hash — with exactly the opaque steps the entry says QA accepted (#923) — and
+ * whose `valid_from` is the entry's `approvedAt`. A lock line copied from elsewhere, re-pointed at
+ * another decision, backdated, or given an acceptance nobody recorded fails here — `unverified`,
+ * reported under contract.lock-uncommitted (hard).
  *
  * Only entries that are otherwise identical to HEAD are checked: an entry already added, changed or
  * tampered is a hard finding on its own.
@@ -14,6 +15,7 @@ import { computeDecisionId, computeEntryHash } from '../decisions/decision-ident
 import { DecisionEntry, storedEntryErrors } from '../decisions/decision-schema';
 import { safeYamlParse } from '../utils/safe-yaml-parse';
 import { HeadSnapshot, headFileText, posixRel, readTextOrNull } from './contract-git';
+import { sameJson } from './contract-hash';
 import { ContractLock, isHumanApproved, LockEntry } from './contract-schema';
 import type { UncommittedEntry } from './lock-vs-git-head';
 
@@ -38,8 +40,10 @@ function loadDecision(projectRoot: string, unitDir: string, id: string, snap: He
 
 function mismatch(scenario: string, lockEntry: LockEntry, d: DecisionEntry): string | null {
   if (d.kind !== 'contract-approval') return `decision ${d.id} is a ${d.kind}, not a contract-approval`;
-  const listed = Array.isArray(d.payload?.scenarios) ? d.payload!.scenarios as Array<{ id?: unknown; hash?: unknown }> : [];
-  if (!listed.some((s) => s && s.id === scenario && s.hash === lockEntry.hash)) return `decision ${d.id} does not approve ${scenario} at hash ${lockEntry.hash}`;
+  const listed = Array.isArray(d.payload?.scenarios) ? d.payload!.scenarios as Array<{ id?: unknown; hash?: unknown; acceptedOpaque?: unknown }> : [];
+  const item = listed.find((s) => s && s.id === scenario && s.hash === lockEntry.hash);
+  if (!item) return `decision ${d.id} does not approve ${scenario} at hash ${lockEntry.hash}`;
+  if (!sameJson(item.acceptedOpaque ?? [], lockEntry.acceptedOpaque ?? [])) return `decision ${d.id} does not accept the opaque step(s) the lock entry of ${scenario} lists (acceptedOpaque)`;
   if (Date.parse(lockEntry.approvedAt) !== Date.parse(d.valid_from)) return `approvedAt ${lockEntry.approvedAt} is not decision ${d.id}'s valid_from ${d.valid_from}`;
   return null;
 }

package/src/decisions/confirmed-decision-commands.ts

@@ -3,6 +3,7 @@
  * CLI runs on process.stdin/stderr is the code a test drives with a simulated TTY.
  *
  *   waive      `sungen journey --screen <u> --waive <OB> --reason …`                         phrase: the obligation id
+ *   signoff    `sungen journey --screen <u> --signoff [--by <name>]`                          phrase: SIGN-OFF (review W3)
  *   decide     `sungen journey [--screen <u>] --decide <kind> --text … --reason … [--anchor …]` phrase: the kind
  *   migration  a leftover write-ahead sentinel → REVERT or KEEP                                 (takumi T6)
  *
@@ -16,13 +17,13 @@
 import * as path from 'path';
 import { assertNoPendingMigration, pendingMigrationState, PendingMigration, readPendingMigration, resolvePendingMigration, sentinelPath } from '../basis/migration-sentinel';
 import { parseAnchorId } from '../basis/anchor-grammar';
-import { JourneyReport, runJourney, waive } from '../harness/journey';
+import { assertCanSignOff, assertWaivable, JourneyReport, runJourney, signoff, signoffSigner, waive } from '../harness/journey';
 import { reportSlug } from '../harness/unit-paths';
 import { appendDecision, AppendResult } from './append-decision';
 import { PROJECT_SCOPE, unitDecisionScope } from './decision-file';
 import { DecisionDraft, DecisionKind, draftErrors, JsonValue } from './decision-schema';
 import { gitUserName } from './decision-source';
-import { askMigrationChoice, ConfirmationIO, formatCommand, requireTypedConfirmation } from './human-confirmation';
+import { askMigrationChoice, ConfirmationIO, formatCommand, requireInteractive, requireTypedConfirmation } from './human-confirmation';
 import { readDecisions } from './read-decisions';
 import { overridePayloadErrors } from '../harness/gates/gate-override-validation';
 
@@ -30,8 +31,7 @@ export interface WaiveInput { projectRoot: string; unit: string; obligation: str
 
 export async function waiveWithConfirmation(i: WaiveInput): Promise<JourneyReport> {
   if (!i.reason || !i.reason.trim()) throw new Error('A reason is required to waive (anti-amnesia: a waiver must record WHY). Use --reason "...".');
-  const valid = runJourney(i.projectRoot, i.unit).obligations.map((o) => o.id);
-  if (!valid.includes(i.obligation)) throw new Error(`Unknown obligation "${i.obligation}". Valid: ${valid.join(', ')}`);
+  assertWaivable(runJourney(i.projectRoot, i.unit), i.unit, i.obligation);
   await requireTypedConfirmation({
     what: `waive ${i.obligation} for ${i.unit}`,
     phrase: i.obligation,
@@ -42,6 +42,27 @@ export async function waiveWithConfirmation(i: WaiveInput): Promise<JourneyRepor
   return waive(i.projectRoot, i.unit, i.obligation, i.reason);
 }
 
+export interface SignoffInput { projectRoot: string; unit: string; by?: string; io: ConfirmationIO }
+
+/**
+ * The single human gate (DOS §3.4, S5), typed by a person on a terminal: the gate suggests it, so an
+ * agent must not be able to give it. Refused before the prompt when the board cannot be signed off.
+ */
+export async function signoffWithConfirmation(i: SignoffInput): Promise<JourneyReport> {
+  const what = `sign off ${i.unit} (the single human gate before delivery)`;
+  const command = formatCommand(['sungen', 'journey', '--screen', i.unit, '--signoff', ...(i.by ? ['--by', i.by] : [])]);
+  requireInteractive(i.io, what, command);   // before the board is read: a refused sign-off writes nothing
+  const { signer, gitUser } = signoffSigner(i.projectRoot, i.unit, i.by);   // nobody to name → refused, no prompt
+  const before = runJourney(i.projectRoot, i.unit);
+  assertCanSignOff(before);
+  await requireTypedConfirmation({
+    what, phrase: 'SIGN-OFF', command,
+    summary: [`by: ${signer}${signer !== gitUser ? ` (recorded by git user ${gitUser})` : ''}`, `${before.needsYou.length} item(s) in the review queue — you have reviewed them`, 'it goes stale as soon as the audit changes (sign off again then)'],
+    io: i.io,
+  });
+  return signoff(i.projectRoot, i.unit, i.by);
+}
+
 /** Kinds `--decide` records. The others have a command of their own that computes their payload. */
 export const DECIDE_KINDS: readonly DecisionKind[] = ['gate-override', 'clarification'];
 const OWN_COMMAND: Partial<Record<DecisionKind, string>> = {

package/src/decisions/human-confirmation.ts

@@ -79,6 +79,11 @@ function refuseWithoutTty(what: string, command: string): HumanConfirmationRefus
   );
 }
 
+/** Refuse up front, before any state is read or written, when no human is at a terminal. */
+export function requireInteractive(io: ConfirmationIO, what: string, command: string): void {
+  if (!isInteractive(io)) throw refuseWithoutTty(what, command);
+}
+
 /** A fresh, hard-to-guess suffix for one prompt. */
 export const confirmationNonce = (): string => randomBytes(3).toString('hex').toUpperCase();
 

package/src/exporters/matrix/xlsx-cells.ts

@@ -49,7 +49,7 @@ export function draftBanner(ws: ExcelJS.Worksheet, model: MatrixModel): void {
   if (model.manifest.approvalState !== 'draft') return;
   ws.mergeCells('A5:H5');
   const c = ws.getCell('A5');
-  c.value = 'DRAFT — NOT APPROVED FOR OFFICIAL DELIVERY (review-required findings or proposed groups remain)';
+  c.value = 'DRAFT — NOT APPROVED FOR OFFICIAL DELIVERY (review-required findings, proposed groups, or an audit that does not pass)';
   c.font = { bold: true, size: 11, name: ARIAL_FONT, color: { argb: 'FFFFFFFF' } };
   c.fill = { type: 'pattern', pattern: 'solid', fgColor: DRAFT_RED };
   c.alignment = { horizontal: 'center', vertical: 'middle' };

package/src/graph/evaluate-graph.ts

@@ -4,7 +4,9 @@
  *
  *   open       active ∧ ¬satisfied (a test-case node is open when at least one case is)
  *   frontier   open ∧ (every `requires` satisfied ∨ ¬blocking)
- *   cut        an open blocking node ends the walk — nothing ranked after it is offered
+ *   cut        an open blocking node ends the walk — nothing ranked after it is offered, except a
+ *              node's instances that `surfacesPastCut` (a hard contract verdict, #940), which follow
+ *              the cutting step and never cut themselves
  *
  * `--case <id>` (`testCase` option): the frontier is that case's test-case nodes plus the blocking
  * unit nodes before them; non-blocking unit advice is left to the unit view. A `caseOnly` test-case
@@ -41,22 +43,24 @@ export function evaluateGraph(
   const ordered = [...nodes].sort((a, b) => a.rank - b.rank);
   const open = new Set<string>();
   const out: NextStep[] = [];
+  let cut = false;
   for (const node of ordered) {
     if (!node.appliesTo.includes(s.kind) || (node.granularity === 'test-case' && node.caseOnly && !opts.testCase)) continue;
+    if (cut && !node.surfacesPastCut) continue;
     let step: NextStep | null = null;
     if (node.granularity === 'unit') {
-      if (!node.active(s) || node.satisfied(s)) continue;
+      if (!node.active(s) || node.satisfied(s) || (cut && !node.surfacesPastCut!(s))) continue;
       if (!opts.testCase || node.blocking) step = withMeta(node, node.step(s));
     } else {
-      const cases = openCases(node, s, tcStates, opts.testCase);
+      const cases = openCases(node, s, tcStates, opts.testCase).filter((tc) => !cut || node.surfacesPastCut!(s, tc));
       if (!cases.length) continue;
       const single = Boolean(opts.testCase);
       step = withMeta(node, node.step(s, cases, single), single ? cases[0].id : undefined);
     }
     open.add(node.id);
     const ready = node.requires.every((r) => !open.has(r));
-    if (step && (ready || !node.blocking)) out.push(step);
-    if (node.blocking) break;
+    if (step && (cut || ready || !node.blocking)) out.push(step);
+    if (node.blocking && !cut) cut = true;
   }
   return out;
 }

package/src/graph/node-decl.ts

@@ -42,6 +42,11 @@ export interface UnitNodeDecl extends NodeDeclBase {
   active(s: UnitState): boolean;
   satisfied(s: UnitState): boolean;
   step(s: UnitState): StepCore;
+  /**
+   * Offered even when a blocking node ranked before it cut the walk — only while this holds (#940: a
+   * hard contract verdict must not hide behind a stale or failing audit). It never cuts by itself.
+   */
+  surfacesPastCut?(s: UnitState): boolean;
 }
 
 export interface TestCaseNodeDecl extends NodeDeclBase {
@@ -55,6 +60,8 @@ export interface TestCaseNodeDecl extends NodeDeclBase {
   satisfied(s: UnitState, tc: TestCaseState): boolean;
   /** One step for `cases` (all open at this node): a unit-level fold, or exactly one case when `single`. */
   step(s: UnitState, cases: TestCaseState[], single: boolean): StepCore;
+  /** The cases offered even past a cut (see UnitNodeDecl.surfacesPastCut). */
+  surfacesPastCut?(s: UnitState, tc: TestCaseState): boolean;
 }
 
 export type NodeDecl = UnitNodeDecl | TestCaseNodeDecl;

package/src/graph/nodes/test-case-contract-nodes.ts

@@ -11,7 +11,9 @@
  *   tc.conformance       its trace is in review: a `low` target identity  do       contract check --trace
  *                        · its final attempt did not pass (inconclusive)  do       run-test --ids
  *                        · a step no code can compare (opaque)            decide   contract check
- * Exempt cases (DOS-11.2) open nothing. A proposed case (never approved) asks nothing of its own: a
+ * tc.contract-check (a weaker / retargeted / lost check, or an uncommitted lock entry) and tc.unproven
+ * are hard verdicts: they are offered past a stale or failing audit (the cut at unit.audit-stale /
+ * unit.gate-fail), #940; tc.contract-approve (changed, not weaker) is review and waits behind it. Exempt cases (DOS-11.2) open nothing. A proposed case (never approved) asks nothing of its own: a
  * compiled test without a lock is never blocked, and the unit view offers the approval.
  */
 import { ALL_KINDS, StepCore, TestCaseNodeDecl } from '../node-decl';
@@ -29,13 +31,14 @@ const withDetail = (cases: TestCaseState[]): string =>
 const check = (s: UnitState, trace = false): string => `sungen contract check --screen ${s.unit}${trace ? ' --trace' : ''}`;
 
 function contractNode(id: string, rank: number, title: string, actor: TestCaseNodeDecl['actor'], gates: string[], caseOnly: boolean,
-  active: (tc: TestCaseState) => boolean, step: Step): TestCaseNodeDecl {
+  active: (tc: TestCaseState) => boolean, step: Step, hard?: (tc: TestCaseState) => boolean): TestCaseNodeDecl {
   return {
     id, title, actor, granularity: 'test-case', appliesTo: ALL_KINDS, blocking: false, rank, gates, step,
     requires: caseOnly ? ['unit.gate-fail'] : ['unit.run'], produces: ['contracts.lock.yaml', 'decisions/<id>.yaml'],
     ...(caseOnly ? { caseOnly: true as const } : {}),
     active: (_s, tc) => active(tc),
     satisfied: (_s, tc) => exemptionOf(tc) !== null,
+    ...(hard ? { surfacesPastCut: (_s: UnitState, tc: TestCaseState) => hard(tc) } : {}),
   };
 }
 
@@ -60,10 +63,12 @@ export const TEST_CASE_CONTRACT_NODES: readonly TestCaseNodeDecl[] = [
     (tc) => Boolean(tc.contract?.uncommitted) || HARD_LADDER.has(classOf(tc) ?? ''),
     (s, [c]) => ({ kind: 'blocked', command: check(s), because: c.contract?.uncommitted
       ? `its lock entry is not what QA approved and committed (contract.lock-uncommitted) — \`sungen next ${s.unit}\` names the repair; \`sungen delivery\` is blocked until then`
-      : `this case breaks its approved contract (${c.contract?.class}${c.contract?.detail ? `: ${c.contract.detail}` : ''}) — restore the approved check (in the .feature, or in the hand-written test of a free / impl:code case), or a QA approves the change on a terminal (\`sungen contract approve --screen ${s.unit} --scenario ${c.id}\`). \`sungen delivery\` is blocked until then; never weaken an expected value to go green` })),
+      : `this case breaks its approved contract (${c.contract?.class}${c.contract?.detail ? `: ${c.contract.detail}` : ''}) — restore the approved check (in the .feature, or in the hand-written test of a free / impl:code case), or a QA approves the change on a terminal (\`sungen contract approve --screen ${s.unit} --scenario ${c.id}\`). \`sungen delivery\` is blocked until then; never weaken an expected value to go green` }),
+    (tc) => Boolean(tc.contract?.uncommitted) || HARD_LADDER.has(classOf(tc) ?? '')),
   contractNode('tc.unproven', 136, 'Prove the approved free cases with a trace', 'ai', ['contract.unproven'], false,
     (tc) => classOf(tc) === 'unproven',
-    (s, cases) => ({ kind: 'do', command: `/sungen:run-test ${s.unit}${idsArg(cases)}`, because: `${cases.length} approved free / impl:code test case(s) have no trace that proves them (${withDetail(cases)}) — run them again with trace: 'on' and the sungen run-record reporter (run-test Phase 4 does), then \`${check(s, true)}\`. Until then \`sungen contract check\` fails (contract.unproven) and \`sungen delivery\` is blocked; re-approving or editing the .feature cannot prove them` })),
+    (s, cases) => ({ kind: 'do', command: `/sungen:run-test ${s.unit}${idsArg(cases)}`, because: `${cases.length} approved free / impl:code test case(s) have no trace that proves them (${withDetail(cases)}) — run them again with trace: 'on' and the sungen run-record reporter (run-test Phase 4 does), then \`${check(s, true)}\`. Until then \`sungen contract check\` fails (contract.unproven) and \`sungen delivery\` is blocked; re-approving or editing the .feature cannot prove them` }),
+    (tc) => classOf(tc) === 'unproven'),
   contractNode('tc.conformance', 138, 'Settle the traces in review', 'ai', ['contract.opaque-step', 'contract.inconclusive'], false,
     (tc) => classOf(tc) === 'opaque' || classOf(tc) === 'inconclusive', conformanceStep),
 ];

package/src/graph/nodes/unit-contract-node.ts

@@ -3,7 +3,8 @@
  * verdict `sungen contract check` and the delivery guard rebuild (buildContractVerdict), so the three
  * never disagree. Always `decide`: an agent presents it and never approves its own edit.
  *
- *   unit.contract-approve  (rank 105, after the audit gate, before the first run)
+ *   unit.contract-approve  (rank 105, after the audit gate, before the first run; a hard verdict —
+ *                          hard or uncommitted — is offered past a stale or failing audit too, #940)
  *     error        the verdict could not be built → check it on a terminal
  *     uncommitted  by kind: tampered → re-approve or restore · untracked → commit after review ·
  *                  edited → review and commit, or `git checkout --` the lock · unverified → commit the
@@ -66,6 +67,12 @@ export const UNIT_CONTRACT_NODES: readonly UnitNodeDecl[] = [
     active: (s) => Boolean(s.contract),
     satisfied: nothingToDecide,
     step: contractStep,
+    // A hard verdict must not wait behind a re-audit (#940): the audit's PASS says nothing about it —
+    // a broken approved check, or a lock that is not what QA approved and committed (contract.lock-
+    // uncommitted, hard in `contract check`; the step names that repair first). What stays behind the
+    // cut: a changed-not-weaker contract (review — QA re-approves after the design is fixed) and a
+    // verdict that could not be built (not a verdict; `contract check` names the error).
+    surfacesPastCut: (s) => !s.contract!.error && (s.contract!.uncommitted > 0 || s.contract!.hard > 0),
   },
   {
     id: 'unit.contract-proposed', title: 'Approve the Test Contract', actor: 'human', granularity: 'unit',

package/src/graph/nodes/unit-design-nodes.ts

@@ -10,6 +10,7 @@
  *   6 unit.flow-inventory    a flow contract without `flows:` → add it, re-audit
  */
 import { ALL_KINDS, UnitNodeDecl, unitKindDir } from '../node-decl';
+import { updateChannelFlag } from '../../cli/project-sungen-invocation';
 
 const design = (unit: string): string => `/sungen:create-test ${unit}`;
 
@@ -34,7 +35,7 @@ export const UNIT_DESIGN_NODES: readonly UnitNodeDecl[] = [
     satisfied: (s) => !s.assetsDrift,
     step: (s) => ({
       kind: 'do',
-      command: 'sungen update',
+      command: `sungen update${updateChannelFlag(s.assetsDrift!.runningVersion)}`,   // keep the channel (#939)
       because: `this project's AI commands/skills were written by sungen ${s.assetsDrift!.recordedVersion} and you are running ${s.assetsDrift!.runningVersion} — upgrading the package does NOT refresh them, so any rule added since ${s.assetsDrift!.recordedVersion} is not in effect for the next run`,
     }),
   },

package/src/harness/catalog/gate-rules.yaml

@@ -535,8 +535,8 @@ rules:
     stage: deliver
     severity: error
     kind: soft
-    rationale: "Pre-delivery halt: everything automated plus the single human sign-off must be satisfied or waived with a reason."
-    fix: "Close the open obligations and sign off, or waive with a reason."
+    rationale: "Pre-delivery halt: everything automated must be satisfied or waived with a reason, plus the single human sign-off, which is given (sungen journey --signoff), never waived."
+    fix: "Close or waive the open obligations, then a human signs off: sungen journey --screen <unit> --signoff --by <name>."
     since: "<=3.2.34"
     offAllowed: false