@sun-asterisk/sungen 3.3.0-alpha.5 → 3.3.0-alpha.7

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';
@@ -27,6 +29,7 @@ import {
   countFailedResults, countScenarios, hasDeliverableFor, hasResolvedSelector, isCompiled, readIfExists, unitResultFiles,
 } from '../graph/unit-artifact-probes';
 import { AuditNotCounted, ContractFacts, ContractSummary, readContractFacts, readTrustedAudit } from '../graph/unit-state-facts';
+import { ResultsFreshness, resultsFreshness } from '../graph/unit-results-freshness';
 
 export interface NextStep {
   /** The command to run, as the operator would type it. */
@@ -89,7 +92,20 @@ export interface UnitState {
   contract?: ContractSummary;
   /** Per-test-case state (DOS-11.1); absent when not read from disk or unreadable. */
   testCases?: TestCaseState[];
+  /** 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;
 }
 
 export interface ReadUnitStateOptions {
@@ -162,7 +178,16 @@ export function readUnitState(
     state.testCases = testCaseStates(projectRoot, unit, { unitDir, auditFindings: state.audit?.findings ?? [] })
       .map((tc) => (contract?.cases.has(tc.id) ? { ...tc, contract: contract.cases.get(tc.id) } : tc));
   } catch { /* an unparseable .feature — the unit-level nodes still answer, as before test-case state */ }
+  try {
+    const results = resultsFreshness(projectRoot, unitDir, unit);
+    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;
   return state;
 }
 
@@ -174,3 +199,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/harness/triage-manual-classification.ts

@@ -0,0 +1,76 @@
+/**
+ * `sungen triage --screen <u> --case <id> --as product|test-defect|environment --reason "…"` (#928):
+ * classify one red by hand — the one `sungen triage` left unclassified, or one it got wrong — as a
+ * `triage-classification` decision in the unit's `decisions/` (read back by graph/manual-triage-decisions.ts).
+ *
+ *   validated first   the class, a reason, a case that exists, is red and is not exempt — before any
+ *                     prompt, so a human never confirms something that is then rejected
+ *   product           stricter than any automatic class (it leads to a QA decision): anyone may record it
+ *   test-defect,      can hide a product defect behind "fix the test" / "re-run": a human types a
+ *   environment       confirmation on a terminal (DOS-13.4); without one it is refused, nothing is
+ *                     written and the exact command is printed. Only after the typed phrase does the
+ *                     entry carry `humanConfirmed: true`, and a reader ignores one without it
+ *   bound             evidence_hash = the case's red as it reads now; a re-run voids the classification
+ */
+import type { AppendResult } from '../decisions/append-decision';
+import { appendDecision } from '../decisions/append-decision';
+import type { DecisionDraft } from '../decisions/decision-schema';
+import { gitUserName } from '../decisions/decision-source';
+import { ConfirmationIO, formatCommand, requireTypedConfirmation } from '../decisions/human-confirmation';
+import { resolveUnitCandidates } from '../cli/resolve-unit';
+import { HUMAN_ONLY_TRIAGE, MANUAL_TRIAGE_AS, ManualTriageClass, TRIAGE_DECISION_KIND } from '../graph/manual-triage-decisions';
+import { exemptionOf } from '../graph/test-case-satisfied';
+import { testCaseStates } from '../graph/test-case-states';
+import { unitScopeOfDir } from './gates/unit-gate-overrides';
+
+export interface ClassifyRedCaseInput {
+  projectRoot: string;
+  unit: string;
+  caseId: string;
+  /** product | test-defect | environment */
+  as: string;
+  reason?: string;
+  io: ConfirmationIO;
+}
+
+export interface ClassifyRedCaseResult extends AppendResult { caseId: string; class: ManualTriageClass }
+
+export async function classifyRedCase(i: ClassifyRedCaseInput): Promise<ClassifyRedCaseResult> {
+  const cls = Object.prototype.hasOwnProperty.call(MANUAL_TRIAGE_AS, i.as) ? MANUAL_TRIAGE_AS[i.as] : undefined;
+  if (!cls) throw new Error(`--as must be one of ${Object.keys(MANUAL_TRIAGE_AS).join(', ')} (got "${i.as}")`);
+  const reason = (i.reason ?? '').trim();
+  if (!reason) throw new Error('--reason is required: a classification records WHY this red is what you say it is');
+  const found = resolveUnitCandidates(i.unit, i.projectRoot);
+  if (found.length !== 1) throw new Error(`"${i.unit}" does not name exactly one unit under qa/screens, qa/flows or qa/api`);
+  const unitDir = found[0].dir;
+  const scope = unitScopeOfDir(i.projectRoot, unitDir);
+  if (!scope) throw new Error(`"${i.unit}" has no decisions scope`);
+  const cases = testCaseStates(i.projectRoot, i.unit, { unitDir, auditFindings: [] });
+  const tc = cases.find((c) => c.id === i.caseId);
+  if (!tc) {
+    const known = cases.slice(0, 8).map((c) => c.id).join(', ');
+    throw new Error(`no test case "${i.caseId}" in ${i.unit}${known ? ` — known: ${known}${cases.length > 8 ? ', …' : ''}` : ''}`);
+  }
+  if (tc.result !== 'failed' || !tc.evidence) throw new Error(`${tc.id} has no red result to classify (result: ${tc.result})`);
+  const exempt = exemptionOf(tc);
+  if (exempt) throw new Error(`${tc.id} is exempt (${exempt}) — it needs no classification`);
+
+  const human = HUMAN_ONLY_TRIAGE.has(cls);
+  if (human) {
+    await requireTypedConfirmation({
+      what: `classify the red ${tc.id} of ${i.unit} as ${cls}`,
+      phrase: tc.id,
+      command: formatCommand(['sungen', 'triage', found[0].kind === 'api' ? '--api' : '--screen', i.unit, '--case', tc.id, '--as', i.as, '--reason', reason]),
+      summary: [`case: ${tc.title}`, `automatic triage: ${tc.triage ? `${tc.triage.class} (${tc.triage.ruleId})` : 'none current'}`, `reason: ${reason}`,
+        `recorded by: ${gitUserName(i.projectRoot)}`, `as ${cls} it leaves the product-defect path — confirm only after reading its evidence (trace, error)`,
+        'it stops counting as soon as the case runs again'],
+      io: i.io,
+    });
+  }
+  const draft: DecisionDraft = {
+    kind: TRIAGE_DECISION_KIND, anchors: [], text: `${tc.id} is ${cls}: ${tc.title}`, reason,
+    payload: { case: tc.id, class: cls, ...(human ? { humanConfirmed: true } : {}) },
+    source: { by: gitUserName(i.projectRoot), where: 'cli' }, valid_from: new Date().toISOString(), visibility: 'internal', evidence_hash: tc.evidence,
+  };
+  return { ...appendDecision(i.projectRoot, scope, draft), caseId: tc.id, class: cls };
+}

package/src/harness/unit-paths.ts

@@ -49,3 +49,22 @@ export function featureFilesFor(unitDir: string, unit: string): string[] {
     ...names.filter((n) => n !== canonicalName),
   ].map((n) => path.join(dir, n));
 }
+
+/**
+ * The catalog-resolution id for a unit dir (relative to qa/): screen · flows/<flow> · api/<area> ·
+ * api/flows/<flow>; a bare screen is its basename. Shared by the audit, which scores and links the
+ * unit under this id, and its inputsHash, which reads what the audit reads under the same id.
+ */
+export function catalogIdFromScreenDir(screenDir: string): string {
+  const parts = screenDir.split(path.sep);
+  const qa = parts.lastIndexOf('qa');
+  if (qa >= 0) {
+    if (parts[qa + 1] === 'api' && parts[qa + 2] === 'flows' && parts[qa + 3]) return `api/flows/${parts[qa + 3]}`;
+    if (parts[qa + 1] === 'api' && parts[qa + 2]) return `api/${parts[qa + 2]}`;
+    if (parts[qa + 1] === 'flows' && parts[qa + 2]) return `flows/${parts[qa + 2]}`;
+  }
+  return path.basename(screenDir);
+}
+
+/** A screen unit — the only kind a sibling flow credits (TQ-4); flows and api units are not. */
+export const isScreenUnitId = (catalogId: string): boolean => !/^(flows|api)\//.test(catalogId);

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

@@ -2,7 +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` and `journey --signoff` 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 '…'`
@@ -13,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)/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',
@@ -23,7 +25,8 @@ export const ttySpoof: GuardRule = {
     if (!cmd || !TTY_EMULATOR.test(cmd) || !HUMAN_GATED.test(cmd)) return null;
     return {
       status: 'ask',
-      askReason: 'sungen: this runs a human-confirmed sungen action (`contract approve` / `journey --waive|--decide|--signoff`) through a terminal '
+      askReason: 'sungen: this runs a human-confirmed sungen action (`contract approve` / `journey --waive|--decide|--signoff` / '
+        + '`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

@@ -11,6 +11,7 @@
  * 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 { 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';
@@ -101,12 +102,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)].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),
       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 -->