@sun-asterisk/sungen 3.3.0-alpha.6 → 3.3.0-alpha.8

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

@@ -586,7 +586,7 @@ rules:
     severity: review
     kind: hard
     rationale: "A check on a JS value, API or canvas result is not tied to an element and cannot be compared automatically (DOS-14.6); it always goes to review and is locked at review."
-    fix: "QA reviews the verbatim step and its file:line, then approves."
+    fix: "QA reviews the verbatim step and its file:line (`sungen contract check`), then accepts it as it reads now on a terminal: `sungen contract approve --screen <unit> --scenario <id> --accept-opaque`. A plain re-approve never clears it."
     since: "p0"
     offAllowed: false
   - id: contract.nondeterministic

package/src/harness/gates/audit-report-verification.ts

@@ -58,6 +58,8 @@ function provenanceField(r: Record<string, unknown>, key: 'sungenVersion' | 'cat
 const writtenBy = (r: Record<string, unknown>): string | null => provenanceField(r, 'sungenVersion');
 
 export interface RulesStamp { catalogHash: string | null; rulesHash: string | null }
+/** rulesProblem's answer for a report that records no rules (`provenance.catalogHash` / `rulesHash`): an older sungen wrote it. */
+export const NO_RULES_STAMP = 'audited by an older sungen, which did not record the rules it scored with';
 /** What getProvenance writes when it could not read a catalog — never a match, on either side. */
 const UNKNOWN = 'unknown';
 
@@ -67,7 +69,7 @@ const UNKNOWN = 'unknown';
  * unknown == unknown proves nothing.
  */
 export function rulesProblem(was: RulesStamp, now: RulesStamp): string | null {
-  if (!was.catalogHash || !was.rulesHash) return 'it does not say which rules scored it (no provenance.catalogHash / rulesHash)';
+  if (!was.catalogHash || !was.rulesHash) return NO_RULES_STAMP;
   if ([was.catalogHash, was.rulesHash].includes(UNKNOWN)) return 'the rules that scored it are unknown (provenance says "unknown")';
   if (!now.catalogHash || !now.rulesHash || [now.catalogHash, now.rulesHash].includes(UNKNOWN)) return 'this sungen cannot read its own rules (catalog or rules hash unknown), so it trusts no report';
   if (was.catalogHash === now.catalogHash && was.rulesHash === now.rulesHash) return null;
@@ -162,7 +164,10 @@ export function verifyAuditReport(projectRoot: string, unit: string): AuditVerif
   }
   const stale: AuditVerification['problems'] = [];
   const rules = otherRules(r);
-  if (rules) stale.push({ code: 'rules-changed', message: `${writtenBy(r) ? `written by sungen ${writtenBy(r)}, ` : ''}${rules}` });
+  // A report from before the rules stamp reads in plain words, with the one command that clears it (#966).
+  if (rules) stale.push({ code: 'rules-changed', message: rules === NO_RULES_STAMP
+    ? `audited by an older sungen${writtenBy(r) ? ` (${writtenBy(r)})` : ''} — run \`sungen audit --screen ${unit}\` once`
+    : `${writtenBy(r) ? `written by sungen ${writtenBy(r)}, ` : ''}${rules}` });
   if (r.decisionsHash !== current) stale.push({ code: 'decisions-changed', message: 'the gate-override decisions changed since this audit' });
   if (!unitDir) return result('invalid', [{ code: 'unit-unresolved', message: `"${unit}" does not name exactly one unit, so the audit's inputs cannot be checked` }]);
   if (r.inputsHash !== auditInputsHash(unitDir, unit, r.decisionsHash as string)) {

package/src/harness/gates/delivery-checklist.ts

@@ -50,13 +50,23 @@ async function quietly<T>(fn: () => Promise<T>): Promise<T> {
   try { return await fn(); } finally { Object.assign(console, saved); }
 }
 
+/** Findings a fresh `sungen generate` cures: the spec is out of step with the .feature, not hollow. */
+const REGENERATE_CURES = /^(?:DRIFT|MISSING in spec|EXTRA in spec|Count mismatch)\b/;
+
+/** The first finding's first sentence — its cause after "→" kept (#943) — and, when regenerating cures it, the command. */
+function scriptCheckFailure(u: ChecklistUnit, finding = 'not faithful'): string {
+  const first = finding.split(/\. /)[0].slice(0, 240);
+  const generate = `sungen generate --${u.kind === 'flow' ? 'flow' : u.kind === 'api' ? 'api' : 'screen'} ${u.unitName}`;
+  return `FAIL — ${first}${REGENERATE_CURES.test(finding) ? ` — run \`${generate}\` after fixing the scenario` : ''} (\`sungen script-check\` exits 2)`;
+}
+
 async function scriptCheckBox(u: ChecklistUnit): Promise<ChecklistBox> {
   try {
     const r = await quietly(() => runScriptCheck(u.unitDir, u.unitName, u.kind));
     if (!r.specPath) return box('script-check', 'skipped', 'no compiled spec to compare: nothing was compiled for this unit');
     return r.status === 'OK'
       ? box('script-check', 'pass', `OK — the spec is a 1:1 of the .feature, no drift (${r.automatedScenarios} automated)`)
-      : box('script-check', 'fail', `FAIL — ${(r.findings[0] ?? 'not faithful').split(/ → |\. /)[0].slice(0, 160)} (\`sungen script-check\` exits 2)`);
+      : box('script-check', 'fail', scriptCheckFailure(u, r.findings[0]));
   } catch (e) {
     return box('script-check', 'fail', `could not run: ${why(e)}`);
   }

package/src/harness/gates/in-run-decision-check.ts

@@ -23,7 +23,8 @@
  * `humanConfirmed`, #928) is a claim the entry makes about itself — a script can write one. What backs
  * it is review, so it is in-run while git HEAD does not hold it (and, with no git, always: nothing
  * shows it was reviewed). Judged by HEAD membership only: it is always recorded after the run it
- * judges, so its commit time says nothing.
+ * judges, so its commit time says nothing. Only a test-defect / environment entry that is not
+ * superseded counts — the only kind the reader puts in force on that claim.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -31,6 +32,7 @@ import { DECISION_FILE_PATH } from '../../decisions/decision-file';
 import { DecisionVisibility } from '../../decisions/decision-schema';
 import { gitOutput } from '../../decisions/git-head-trust';
 import { readDecisions } from '../../decisions/read-decisions';
+import { HUMAN_ONLY_TRIAGE, ManualTriageClass, TRIAGE_DECISION_KIND } from '../../graph/manual-triage-decisions';
 import { migratedWaiverReview } from './migrated-waiver-review';
 
 export const IN_RUN_KINDS = ['gate-override', 'waiver', 'contract-approval'] as const;
@@ -64,9 +66,14 @@ export function runStartOf(resultsPath: string | null): string | null {
 }
 
 const isInRunKind = (kind: string): boolean => (IN_RUN_KINDS as readonly string[]).includes(kind);
-/** A triage classification claiming a human typed it (#928): reviewed only once git HEAD holds it. */
-const claimsHumanTriage = (e: { kind: string; payload?: Record<string, unknown> }): boolean =>
-  e.kind === 'triage-classification' && e.payload?.humanConfirmed === true;
+/**
+ * A triage classification claiming a human typed it (#928): reviewed only once git HEAD holds it.
+ * Only what the reader (manual-triage-decisions.ts) can put in force: a superseded entry is never read,
+ * and a product classification needs no human — its claim backs nothing, so it blocks nothing.
+ */
+const claimsHumanTriage = (e: { kind: string; payload?: Record<string, unknown>; superseded_by?: string }): boolean =>
+  e.kind === TRIAGE_DECISION_KIND && !e.superseded_by && e.payload?.humanConfirmed === true
+  && HUMAN_ONLY_TRIAGE.has(e.payload?.class as ManualTriageClass);
 
 /** In-run decisions among `scopes`, judged against one run start (null: HEAD membership only) and the committed set. */
 export function inRunDecisions(projectRoot: string, scopes: string[], runStart: string | null, committed: Set<string> | null): InRunDecision[] {

package/src/harness/journey.ts

@@ -243,6 +243,52 @@ function computeNext(r: JourneyReport, unit: string): string {
  * A read-only checkout gets the same board without throwing.
  */
 export function runJourney(projectRoot: string, unit: string): JourneyReport {
+  const r = reconcileJourney(projectRoot, unit);
+  try {
+    commitWaiverSync(projectRoot, unit, r.slug, r.sync, r.statePath, JSON.stringify(r.next, null, 2));
+  } catch (err) {
+    if (!(err instanceof DecisionConflictError)) throw err;
+    const rel = path.relative(projectRoot, err.path).split(path.sep).join('/');
+    if (!r.decisionFindings.some((f) => f.path === rel)) r.decisionFindings.push({ rule: 'decision.mutated', path: rel, message: err.message });
+  }
+  return finishReport(r, unit);
+}
+
+/** A waiver the board asks a human to give again: its evidence moved (stale), or git HEAD does not hold it (untrusted). */
+export interface WaiverToRedecide { obligation: string; title: string; reason: string; why: 'stale' | 'untrusted' }
+
+/** What the board asks of a human, read without writing anything (`sungen next`'s "Waiting for you", #954). */
+export interface JourneyHumanAsks {
+  report: JourneyReport;
+  redecide: WaiverToRedecide[];
+  /** OB-signoff: `pending` (never given), `stale` (given before the audit changed), `given`. */
+  signoff: { status: 'pending' | 'stale' | 'given'; at?: string };
+  /** `sungen journey --signoff` would be accepted now (assertCanSignOff holds). */
+  canSignOff: boolean;
+}
+
+/** The board's asks, read-only: no import, no dual-write, no state file — the same reconcile `runJourney` commits. */
+export function readJourneyHumanAsks(projectRoot: string, unit: string): JourneyHumanAsks {
+  const r = reconcileJourney(projectRoot, unit);
+  const report = finishReport(r, unit);
+  let canSignOff = report.obligations.some((o) => o.id === SIGNOFF_OBLIGATION);
+  try { assertCanSignOff(report); } catch { canSignOff = false; }
+  return { report, redecide: r.redecide, signoff: r.signoff, canSignOff };
+}
+
+interface Reconciled {
+  report: JourneyReport;
+  slug: string;
+  statePath: string;
+  sync: ReturnType<typeof planWaiverSync>;
+  next: JourneyState;
+  decisionFindings: DecisionGateFinding[];
+  redecide: WaiverToRedecide[];
+  signoff: JourneyHumanAsks['signoff'];
+}
+
+/** Compute fresh, apply the waivers and the sign-off in force — read-only; `runJourney` commits the plan. */
+function reconcileJourney(projectRoot: string, unit: string): Reconciled {
   const slug = reportSlug(unit);
   assertNoPendingMigration(projectRoot, slug);
   const report = computeFresh(projectRoot, unit);
@@ -250,9 +296,11 @@ export function runJourney(projectRoot: string, unit: string): JourneyReport {
   const state = loadState(sp) || { unit, auditHash: '', waivers: {} };
   const curHash = auditHashOf(projectRoot, slug);
   const sync = planWaiverSync(projectRoot, unit, slug, sp, state.waivers);
+  const redecide: WaiverToRedecide[] = [];
   for (const u of sync.untrusted) {
     const title = report.obligations.find((o) => o.id === u.obligation)?.title ?? u.obligation;
     const ignored = unwaivableWhy(u.obligation, unit);
+    if (!ignored) redecide.push({ obligation: u.obligation, title, reason: u.waiver.reason, why: 'untrusted' });
     report.needsYou.unshift({ text: ignored ? ignoredWaiverText(u.obligation, ignored, u.waiver.reason) : untrustedWaiverText(unit, slug, title, u), anchor: { vpId: u.obligation } });
   }
 
@@ -267,30 +315,33 @@ export function runJourney(projectRoot: string, unit: string): JourneyReport {
       ob.waivedReason = w.reason;
       ob.detail = `waived — ${w.reason}`;
     } else {
+      redecide.push({ obligation: ob.id, title: ob.title, reason: w.reason, why: 'stale' });
       report.needsYou.unshift({ text: `⚠️ Waiver on "${ob.title}" is STALE (evidence changed since ${w.at}) — re-decide. Was: ${w.reason}`, anchor: { vpId: ob.id } });
     }
   }
   // S5 — sign-off reconcile: a recorded sign-off satisfies OB-signoff while its evidence holds;
   // if the audit changed since, the sign-off is STALE → re-surface for re-review (anti-amnesia).
   const signoffOb = report.obligations.find((o) => o.id === 'OB-signoff');
+  let signoff: Reconciled['signoff'] = { status: 'pending' };
   if (signoffOb && state.signoff) {
     if (state.signoff.auditHashAtSignoff === curHash) {
+      signoff = { status: 'given', at: state.signoff.at };
       signoffOb.status = 'satisfied';
       signoffOb.detail = `signed off${state.signoff.by ? ' by ' + state.signoff.by : ''}${state.signoff.recordedBy ? ` (recorded by ${state.signoff.recordedBy})` : ''} at ${state.signoff.at}`;
     } else {
+      signoff = { status: 'stale', at: state.signoff.at };
       report.needsYou.unshift({ text: `⚠️ Sign-off is STALE (suite changed since ${state.signoff.at}) — re-review and sign off again.`, anchor: { vpId: 'OB-signoff' } });
     }
   }
   // Phase-03 carry-over: a decision that does not verify is a FINDING the gate blocks on, not a crash.
   const decisionFindings = journeyDecisionFindings(projectRoot, unitOverrides(projectRoot, unit));
   const next: JourneyState = { unit, auditHash: curHash, waivers: sync.stateWaivers, signoff: state.signoff };
-  try {
-    commitWaiverSync(projectRoot, unit, slug, sync, sp, JSON.stringify(next, null, 2));
-  } catch (err) {
-    if (!(err instanceof DecisionConflictError)) throw err;
-    const rel = path.relative(projectRoot, err.path).split(path.sep).join('/');
-    if (!decisionFindings.some((f) => f.path === rel)) decisionFindings.push({ rule: 'decision.mutated', path: rel, message: err.message });
-  }
+  return { report, slug, statePath: sp, sync, next, decisionFindings, redecide, signoff };
+}
+
+/** The decision findings on the board, then the next suggestion — after the waivers and the sign-off. */
+function finishReport(r: Reconciled, unit: string): JourneyReport {
+  const { report, decisionFindings } = r;
   if (decisionFindings.length) {
     report.decisionFindings = decisionFindings;
     for (const f of [...decisionFindings].reverse()) report.needsYou.unshift({ text: decisionFindingText(f), anchor: { file: f.path } });
@@ -408,11 +459,31 @@ export function writeJourneyFileBestEffort(file: string, text: string): string |
 
 const ICON: Record<ObStatus, string> = { satisfied: '✅', 'needs-work': '⚠️ ', pending: '⏳', waived: '🚫', overridden: '🔓' };
 
+/** `ms` as a person reads a duration: `850 ms`, `45 s`, `8 min 40 s`. */
+function elapsedLabel(ms: number): string {
+  if (ms < 1000) return `${ms} ms`;
+  const s = Math.round(ms / 1000);
+  return s < 60 ? `${s} s` : `${Math.floor(s / 60)} min${s % 60 ? ` ${s % 60} s` : ''}`;
+}
+
+/**
+ * A ledger step as the board shows it (#939 item 8). A step recorded with its elapsed milliseconds in the
+ * NAME (`--step "viewpoint 45000"`, the time meant for `--ms`) printed as a bare number; it reads
+ * `viewpoint (45 s)` now, and `timed` says the line needs its legend.
+ */
+function phaseLabel(step: string): { label: string; timed: boolean } {
+  const m = step.match(/^(.*\S)\s+(\d+)$/);
+  return m ? { label: `${m[1]} (${elapsedLabel(Number(m[2]))})`, timed: true } : { label: step, timed: false };
+}
+
 export function renderJourneyBoard(r: JourneyReport): string {
   const L: string[] = [];
   L.push(`# Journey — ${r.unit}`);
   L.push('');
-  L.push(`📍 **You are here:** ${r.youAreHere}` + (r.phasesDone.length ? `  (phases: ${r.phasesDone.join(' → ')})` : ''));
+  const phases = r.phasesDone.map(phaseLabel);
+  const legend = phases.some((p) => p.timed) || phaseLabel(r.youAreHere).timed
+    ? ` — a time is that phase's elapsed time, from the ledger (\`sungen ledger report --screen ${r.unit}\`)` : '';
+  L.push(`📍 **You are here:** ${phaseLabel(r.youAreHere).label}` + (phases.length ? `  (phases: ${phases.map((p) => p.label).join(' → ')})${legend}` : ''));
   if (r.gateStatus) L.push(`   gate: **${r.gateStatus}** · score: ${r.score ?? '—'}/10`);
   L.push('');
   L.push('## What must still be true');

package/src/harness/next-step.ts

@@ -19,7 +19,9 @@ import * as path from 'path';
 import { reportSlug } from './unit-paths';
 import { checkAssetsDrift } from '../orchestrator/assets-drift';
 import type { HeadSnapshot } from '../contract/contract-git';
-import { evaluateGraph, EvaluateOptions } from '../graph/evaluate-graph';
+import { boardHumanActions } from '../graph/board-human-actions';
+import { evaluateGraph, evaluateHumanActions, EvaluateOptions } from '../graph/evaluate-graph';
+import type { HumanAction } from '../graph/human-action';
 import { CORE_NODES } from '../graph/nodes/core-node-catalog';
 import type { TestCaseState } from '../graph/test-case-state-shape';
 import { testCaseStates } from '../graph/test-case-states';
@@ -93,6 +95,19 @@ export interface UnitState {
   /** Which run the results come from and what they are older than (#942); absent without results. Advisory, decides no step. */
   results?: ResultsFreshness;
   steps: NextStep[];
+  /**
+   * Every pending HUMAN-ONLY action ("Waiting for you", #954): the frontier's decisions (deriveHumanActions)
+   * and the board's asks (sign-off, a waiver to give again, a decision recorded during the run). Set by
+   * readUnitState; commands canonical (`sungen …`). An agent presents them and never runs them.
+   */
+  humanActions?: HumanAction[];
+  /**
+   * The title of the blocking step that cut the frontier: past it only actions that do not depend on it
+   * are listed (sign-off, accept-in-run and the first contract approval wait). Absent when nothing cuts.
+   */
+  humanActionsHeldBy?: string;
+  /** The canonical command of that blocking step (#966) — what clears the hold. */
+  humanActionsHeldByCommand?: string;
 }
 
 export interface ReadUnitStateOptions {
@@ -170,6 +185,12 @@ export function readUnitState(
     if (results) state.results = results;
   } catch { /* advisory: results that cannot be dated add nothing */ }
   state.steps = deriveSteps(state);
+  const graph = evaluateHumanActions(CORE_NODES, state, state.testCases);
+  const seen = new Set<string>();
+  state.humanActions = [...graph.actions, ...boardHumanActions(projectRoot, unitDir, state, graph.cut)]
+    .filter((a) => !seen.has(a.command) && Boolean(seen.add(a.command)));
+  if (graph.heldBy) state.humanActionsHeldBy = graph.heldBy;
+  if (graph.heldByCommand) state.humanActionsHeldByCommand = graph.heldByCommand;
   return state;
 }
 
@@ -181,3 +202,8 @@ export function readUnitState(
 export function deriveSteps(s: UnitState, opts: EvaluateOptions = {}): NextStep[] {
   return evaluateGraph(CORE_NODES, s, s.testCases, opts);
 }
+
+/** The human-only actions of the same frontier (#954) — the graph's part of `humanActions`, without the board. */
+export function deriveHumanActions(s: UnitState): HumanAction[] {
+  return evaluateHumanActions(CORE_NODES, s, s.testCases).actions;
+}

package/src/hooks/guard-tty-spoof-rule.ts

@@ -2,8 +2,9 @@
  * Guard rule `tty-spoof` (phase 06, M5): ASK before an agent runs a human-confirmed sungen command
  * through a terminal emulator.
  *
- * `contract approve`, `journey --waive`, `journey --decide`, `journey --signoff` and `triage --as test-defect|environment`
- * (#928: a red classified away from the product-defect path) refuse without a TTY (DOS-13.4), and
+ * `contract approve`, `journey --waive`, `journey --decide`, `journey --signoff`, `triage --as test-defect|environment`
+ * (#928: a red classified away from the product-defect path) and `delivery --accept-in-run` (delivering past
+ * decisions recorded during the run) refuse without a TTY (DOS-13.4), and
  * an agent's Bash has none — unless it borrows one: `script`, `expect`, `unbuffer`, or a pty from
  * Python/Perl/zsh. Then the prompt sees a "terminal" and a piped phrase reads as a human typing it.
  * This rule spots the pair in the raw command (quotes included, so `bash -c "…"` and `expect -c '…'`
@@ -14,7 +15,7 @@
 import type { GuardRule } from './guard-rules';
 
 const TTY_EMULATOR = /\b(?:script|unbuffer|expect|pty|zpty|openpty|forkpty|ptyprocess)\b/i;
-const HUMAN_GATED = /\bsungen\b[\s\S]*?\b(?:contract['",\s]+approve\b|journey\b[\s\S]*?--(?:waive|decide|signoff)\b|triage\b[\s\S]*?--as[\s='",]+(?:test-defect|environment)\b)/i;
+const HUMAN_GATED = /\bsungen\b[\s\S]*?\b(?:contract['",\s]+approve\b|journey\b[\s\S]*?--(?:waive|decide|signoff)\b|triage\b[\s\S]*?--as[\s='",]+(?:test-defect|environment)\b|delivery\b[\s\S]*?--accept-in-run\b)/i;
 
 export const ttySpoof: GuardRule = {
   id: 'tty-spoof',
@@ -25,7 +26,7 @@ export const ttySpoof: GuardRule = {
     return {
       status: 'ask',
       askReason: 'sungen: this runs a human-confirmed sungen action (`contract approve` / `journey --waive|--decide|--signoff` / '
-        + '`triage --as test-defect|environment`) through a terminal '
+        + '`triage --as test-defect|environment` / `delivery --accept-in-run`) through a terminal '
         + 'emulator (script / expect / unbuffer / pty). Those confirmations exist so a PERSON at a terminal decides — allow only if you '
         + 'are that person and asked for exactly this; otherwise run the command yourself in your own terminal.',
     };

package/src/hooks/hand-back-core.ts

@@ -10,7 +10,8 @@
  * commander's preAction, so a usage error — which never reaches an action — and `main().catch`
  * ended in silence. The state now starts the moment parsing does; the action only refines it.
  */
-import { sungenInvocation, withProjectInvocation } from '../cli/project-sungen-invocation';
+import { sungenInvocation, withProjectInvocationInText } from '../cli/project-sungen-invocation';
+import { waitingForYouLines } from '../cli/waiting-for-you-block';
 import { resolveUnitCandidates } from '../cli/resolve-unit';
 import { readUnitState, NextStep, UnitState } from '../harness/next-step';
 import { NO_OP, HookContext, HookInput, HookResult } from './hook-result-contract';
@@ -87,10 +88,14 @@ export function attachCliHandBack(argv: string[], cwd: string): { onAction: (nam
 
 const MARK: Record<NextStep['kind'], string> = { do: '→', blocked: '⛔', optional: '○', decide: '⚖' };
 
-/** `sungen next` rendered compactly for an agent's context; commands as `root` runs sungen. */
+/**
+ * `sungen next` rendered compactly for an agent's context; commands — the step's own and those quoted in
+ * its reason (#966) — as `root` runs sungen, the way `sungen next` prints them.
+ */
 export function formatSteps(steps: NextStep[], max = 4, root?: string): string[] {
+  const asRun = (text: string): string => (root ? withProjectInvocationInText(text, root) : text);
   return steps.slice(0, max).map((st) =>
-    `  ${MARK[st.kind]} ${root ? withProjectInvocation(st.command, root) : st.command}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}\n     ${st.because}`);
+    `  ${MARK[st.kind]} ${asRun(st.command)}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}\n     ${asRun(st.because)}`);
 }
 
 /** The unit a session is on (a named one when it exists, else the nearest) and its derived state. */
@@ -101,12 +106,13 @@ export function locateUnitState(ctx: HookContext, preferred?: string): { root: s
   return unit ? { root, unit, state: readUnitState(root, unit.dir, unit.name, unit.kind) } : null;
 }
 
-/** Hook core: the next steps for the session's unit (input.unit, else the nearest) as context. */
+/** Hook core: the next steps for the session's unit (input.unit, else the nearest) as context, then what waits for a human (#954). */
 export function run(input: HookInput, ctx: HookContext): HookResult {
   const found = locateUnitState(ctx, typeof input.unit === 'string' ? input.unit : undefined);
   if (!found || found.state.steps.length === 0) return NO_OP;
   return {
     status: 'context',
-    output: [`${handBackLine(found.unit.name, sungenInvocation(found.root))} — derived from what the project holds now:`, ...formatSteps(found.state.steps, 4, found.root)].join('\n'),
+    output: [`${handBackLine(found.unit.name, sungenInvocation(found.root))} — derived from what the project holds now:`, ...formatSteps(found.state.steps, 4, found.root),
+      ...waitingForYouLines(found.state.humanActions, found.root, found.state.humanActionsHeldBy, found.state.humanActionsHeldByCommand)].join('\n'),
   };
 }

package/src/hooks/session-start-unit-state-hook.ts

@@ -5,11 +5,13 @@
  * After `/clear` or a context compaction the agent has lost the thread: it re-derives the state
  * from memory, or worse, re-runs work that is already done. This injects what `sungen next`
  * derives for the session's unit (the one cwd sits in, else the most recently active): what the
- * project already holds — stated as "do not redo" — the audit verdict, and the next steps.
+ * project already holds — stated as "do not redo" — the audit verdict, the next steps, and what waits
+ * for a human (#954).
  */
 import { NO_OP, HookMeta, SungenHook } from './hook-result-contract';
 import { formatSteps, locateUnitState } from './hand-back-core';
 import { sungenInvocation } from '../cli/project-sungen-invocation';
+import { waitingForYouLines } from '../cli/waiting-for-you-block';
 import { listUnits } from './sungen-project-root';
 import type { UnitState } from '../harness/next-step';
 
@@ -48,6 +50,7 @@ export const sessionStartUnitStateHook: SungenHook = {
       state.audit ? `Audit: ${state.audit.overall}/10 [${state.audit.gateStatus}] · ${state.audit.findings.length} finding(s).` : '',
       `Next (\`${sungen} next ${unit.name}\`, derived from the project state):`,
       ...formatSteps(state.steps, 4, root),
+      ...waitingForYouLines(state.humanActions, root, state.humanActionsHeldBy, state.humanActionsHeldByCommand),
       input.source === 'compact' ? 'Context was compacted: re-read the unit\'s files before acting on them.' : '',
       others > 0 ? `Working on another unit? Ask \`${sungen} next <unit>\` (or \`${sungen} next\` for all).` : '',
     ];

package/src/hooks/stop-next-step-hook.ts

@@ -30,6 +30,7 @@ export const stopNextStepHook: SungenHook = {
       output: [
         '[sungen] This turn ran sungen work but ended without the next-step hand-back.',
         'Hand back now: present these steps to the user with AskUserQuestion and stop — do not run them yourself.',
+        ...(/Waiting for you/.test(core.output) ? ['Quote the "Waiting for you" block verbatim: the user runs those commands in their own terminal (`! <command>`); never run them.'] : []),
         core.output,
       ].join('\n'),
     };

package/src/orchestrator/templates/ai-src/commands/delivery.md

@@ -237,3 +237,5 @@ sungen delivery [names...]        # matrix (default; needs the map) → XLSX onl
 Outputs: `qa/deliverables/<unit>-testcases.xlsx` (Overview + Auto + Manual + Coverage sheets) by default;
 `--format csv` writes `<unit>-testcases.csv` instead (flat, `Level` column `item|variant`),
 `--format both` writes both. Legacy mode writes the classic files instead.
+
+<!-- include: waiting-for-you -->

package/src/orchestrator/templates/ai-src/commands/review.md

@@ -97,3 +97,5 @@ You are an **independent QA Reviewer** — you did not author these tests. You d
 5. **Trace + next** — `sungen trace --screen ${input:name}` (human-loop focus), then offer:
    - **`/sungen-run-test ${input:name}`** (Recommended) · **`/sungen-delivery ${input:name}`** · **`/sungen-create-test ${input:name}`** · Done.
 {{/cap}}
+
+<!-- include: waiting-for-you -->

package/src/orchestrator/templates/ai-src/partials/waiting-for-you.claude.md

@@ -0,0 +1,11 @@
+<!-- sungen:waiting-for-you v1 -->
+## Waiting for you — the commands only the QA runs
+
+Right before the hand-back question, run `sungen next {{unitArg}}` and quote its **⏳ Waiting for you**
+block **verbatim** — every command exactly as printed, each with its reason. Those commands approve,
+sign off, waive, classify a red, accept in-run decisions or re-run once the environment is up: they are
+the QA's alone, and most refuse without a person typing a confirmation. Tell the QA to run each one in
+their own terminal — in Claude Code, type `! <command>` in the prompt (a `/sungen:…` command is typed
+as is). **Never run them yourself**, and never pipe or type a confirmation into them. When `sungen next`
+prints no such block, say that nothing is waiting for the QA.
+<!-- /sungen:waiting-for-you -->

package/src/orchestrator/templates/ai-src/partials/waiting-for-you.codex.md

@@ -0,0 +1,11 @@
+<!-- sungen:waiting-for-you v1 -->
+## Waiting for you — the commands only the QA runs
+
+Right before the hand-back list, run `sungen next {{unitArg}}` and quote its **⏳ Waiting for you**
+block **verbatim** — every command exactly as printed, each with its reason. Those commands approve,
+sign off, waive, classify a red, accept in-run decisions or re-run once the environment is up: they are
+the QA's alone, and most refuse without a person typing a confirmation. Tell the QA to run each one
+themselves, in their own terminal (a slash command is typed as is). **Never run them yourself**, and
+never pipe or type a confirmation into them. When `sungen next` prints no such block, say that nothing
+is waiting for the QA.
+<!-- /sungen:waiting-for-you -->

package/src/orchestrator/templates/ai-src/partials/waiting-for-you.copilot.md

@@ -0,0 +1,11 @@
+<!-- sungen:waiting-for-you v1 -->
+## Waiting for you — the commands only the QA runs
+
+Right before the hand-back list, run `sungen next {{unitArg}}` and quote its **⏳ Waiting for you**
+block **verbatim** — every command exactly as printed, each with its reason. Those commands approve,
+sign off, waive, classify a red, accept in-run decisions or re-run once the environment is up: they are
+the QA's alone, and most refuse without a person typing a confirmation. Tell the QA to run each one
+themselves, in their own terminal (a slash command is typed as is). **Never run them yourself**, and
+never pipe or type a confirmation into them. When `sungen next` prints no such block, say that nothing
+is waiting for the QA.
+<!-- /sungen:waiting-for-you -->