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

package/dist/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/dist/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 -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.3.0-alpha.6",
+  "version": "3.3.0-alpha.7",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -40,8 +40,8 @@
     "@babel/types": "^7.28.5",
     "@cucumber/gherkin": "^37.0.0",
     "@cucumber/messages": "^31.0.0",
-    "@sungen/driver-data-factory": "3.3.0-alpha.6",
-    "@sungen/driver-ui": "3.3.0-alpha.6",
+    "@sungen/driver-data-factory": "3.3.0-alpha.7",
+    "@sungen/driver-ui": "3.3.0-alpha.7",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
     "dotenv": "^17.2.3",

package/src/cli/commands/contract-derive-command.ts

@@ -19,6 +19,7 @@ function print(r: DeriveResult, unit: string): void {
   L(`━━━ Contract derive: ${unit} — free tests' traces → ${rel} ━━━`);
   L('');
   if (r.note) L(`  ⚠ ${r.note}`);
+  for (const w of r.warnings ?? []) L(`  ⚠ ${w}`);
   for (const s of r.scenarios) L(`  + ${s.title}  (${s.steps} steps${s.low ? `, ${s.low} low identity` : ''}${s.opaque ? `, ${s.opaque} opaque` : ''})`);
   for (const s of r.skipped) L(`  - ${s.id}  skipped: ${s.reason}`);
   if (r.refused?.length) {

package/src/cli/commands/delivery.ts

@@ -41,6 +41,7 @@ import { MatrixFinding } from '../../exporters/matrix/types';
 import { applyManualCarry, ManualCarryReport, PriorManualResults, readPriorManualResults } from '../../exporters/matrix/carry-manual-results';
 import { formatTestOutcome, resultTotals } from '../../exporters/matrix/result-totals';
 import { readCapabilities } from '../../harness/capability';
+import { splitFeatureBlocks } from '../../contract/free-feature-blocks';
 import { processIO } from '../../decisions/human-confirmation';
 import { DeliveryDecisionGate } from '../../harness/gates/delivery-decision-gate';
 import { runDeliveryDecisionStep } from '../../harness/gates/delivery-decision-step';
@@ -101,14 +102,30 @@ function makeTarget(screen: string, featureBaseName: string, kind: UnitKind): De
 }
 
 /**
- * List all `.feature` files inside a screen/flow/api unit as separate targets.
- * Returns empty array when the directory has no features yet.
+ * A derived `*.free.feature` none of whose scenarios QA has approved yet (every one still `@proposed`):
+ * a proposal, not a delivery unit — counted as one, it ended in "Not exported" (#939). Approving a
+ * scenario drops its tag (`contract approve`), and from then on the file is a unit like any other.
+ */
+function proposalOnly(featureFile: string): boolean {
+  if (!featureFile.endsWith('.free.feature')) return false;
+  try {
+    // No scenario block at all (empty, or not Gherkin) is not a proposal: it stays listed and the preflight names it.
+    const blocks = splitFeatureBlocks(fs.readFileSync(featureFile, 'utf8'));
+    return blocks.length > 0 && blocks.every((b) => b.proposed);
+  } catch {
+    return false;   // unreadable: listed, so the preflight names the problem
+  }
+}
+
+/**
+ * List all `.feature` files inside a screen/flow/api unit as separate targets — a proposal-only
+ * free feature excepted. Returns empty array when the directory has no features yet.
  */
 function listFeatureTargets(cwd: string, screen: string, kind: UnitKind): DeliveryTarget[] {
   const featuresDir = path.join(cwd, 'qa', qaParent(kind), screen, 'features');
   if (!fs.existsSync(featuresDir)) return [];
   return fs.readdirSync(featuresDir)
-    .filter((f) => f.endsWith('.feature'))
+    .filter((f) => f.endsWith('.feature') && !proposalOnly(path.join(featuresDir, f)))
     .map((f) => makeTarget(screen, f.slice(0, -'.feature'.length), kind))
     .sort((a, b) => a.featureBaseName.localeCompare(b.featureBaseName));
 }

package/src/cli/commands/generate.ts

@@ -255,7 +255,9 @@ export function registerGenerateCommand(program: Command): void {
           if (shown.length < ddWarnings.length) console.log(`   … and ${ddWarnings.length - shown.length} more (run with -v to list all)`);
         }
 
-        const nextStep = platform === 'mobile' ? 'npm run test:mobile' : 'npx playwright test --ui';
+        // Never the interactive `--ui` (#939): an agent cannot drive it, and run-test is what records the results.
+        const unit = screenName || flowName || apiName;
+        const nextStep = platform === 'mobile' ? 'npm run test:mobile' : unit ? `/sungen:run-test ${unit}   (or the plain run: npx playwright test)` : 'npx playwright test';
         console.log(`Next step: ${nextStep}\n`);
       } catch (error) {
         console.error('Error:', error instanceof Error ? error.message : error);

package/src/cli/commands/next.ts

@@ -9,9 +9,11 @@
  *   sungen next <unit> --case <id>    one test case: its state, and its steps after the blocking
  *                                     unit steps before them (OES-10.3)
  *   --json                            the same, machine-readable; steps add nodeId, granularity,
- *                                     testCase?, gates?; the unit adds `results` (#942); every older
+ *                                     testCase?, gates?; the unit adds `results` (#942) and
+ *                                     `humanActions: [{command, reason, kind}]` (#954); every older
  *                                     field is kept. stdout is the payload alone (#660, #836)
- * The text names the run the results come from and warns when they are older than the suite (#942).
+ * The text names the run the results come from and warns when they are older than the suite (#942),
+ * and ends with "Waiting for you": every pending human-only command, with why (#954).
  */
 import { Command } from 'commander';
 import * as fs from 'fs';
@@ -23,6 +25,7 @@ import { describeResultsRun } from '../../graph/unit-results-freshness';
 import { deriveSteps, NextStep, readUnitState, UnitState } from '../../harness/next-step';
 import { resolveUnit, resolveUnitCandidates, AmbiguousUnitError } from '../resolve-unit';
 import { withProjectInvocation } from '../project-sungen-invocation';
+import { waitingForYouLines } from '../waiting-for-you-block';
 
 /** Every unit the project holds, so `sungen next` with no argument still answers. */
 function allUnits(cwd: string): Array<{ name: string; kind: UnitState['kind']; dir: string }> {
@@ -69,6 +72,8 @@ function render(s: UnitState, cwd: string): void {
   L('');
   renderSteps(s.steps, cwd);
   L('');
+  const waiting = waitingForYouLines(s.humanActions, cwd, s.humanActionsHeldBy);
+  if (waiting.length) { for (const line of waiting) L(line); L(''); }
 }
 
 /** `--case <id>`: the case's state and its frontier. Exits 1 when the case cannot be found. */

package/src/cli/commands/update.ts

@@ -26,7 +26,9 @@ import { syncProjectSungenDeps } from '../../orchestrator/project-deps-sync';
  *
  * The public `--skip-npm-install` flag is still available for users who
  * already installed the binary by other means (CI pipelines, corporate
- * mirror, manual download) and only want to refresh the project AI assets.
+ * mirror, manual download). It skips only step 1: the project sync still
+ * re-pins package.json (security overrides included) and runs `npm install`
+ * there — `--skip-project` skips that (#939).
  */
 
 const SKIP_NPM_ENV = 'SUNGEN_UPDATE_SKIP_NPM';
@@ -70,9 +72,11 @@ export function registerUpdateCommand(program: Command): void {
       '--tag <dist-tag>',
       'Install a specific npm dist-tag (e.g. latest, beta, alpha, next). Overrides --beta / --alpha.',
     )
+    // #939: it skips only the GLOBAL install — the project is still synced, so the help says so.
     .option(
       '--skip-npm-install',
-      'Skip the global npm install step (refresh project AI assets only)',
+      'Skip the global npm install step. The project is still synced: its sungen packages are re-pinned in package.json '
+        + '(security `overrides` included) and `npm install` runs in the project — add --skip-project to skip that too',
       false,
     )
     .option(

package/src/cli/index.ts

@@ -45,6 +45,7 @@ import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 import { warnAssetsDrift } from '../orchestrator/assets-drift';
 import { attachCliHandBack } from '../hooks/hand-back-core';
+import { attachJsonErrorOnExit, commandSupportsJson } from './json-error-on-exit';
 import { registerHookCommand } from '../hooks/hook-cli-command';
 
 // Read version from package.json so `--version` never drifts from the released version.
@@ -60,6 +61,8 @@ async function main() {
   // those rules live in the hook core (src/hooks/hand-back-core.ts) — this file only wires it.
   const handBack = attachCliHandBack(process.argv, process.cwd());
   const program = new Command();
+  // #939: a failed `--json` command prints {"error":{code,message}} on stdout (json-error-on-exit.ts).
+  const jsonErrors = attachJsonErrorOnExit(process.argv, (args) => commandSupportsJson(program, args));
 
   program
     .name('sungen')
@@ -130,6 +133,7 @@ registerSetupMobileEnvCommand(program);
   // The action knows its unit and output mode; the hand-back default above is refined here.
   program.hook('preAction', (_thisCommand, actionCommand) => {
     handBack.onAction(actionCommand.name(), actionCommand.opts() as Record<string, unknown>, actionCommand.args);
+    jsonErrors.onAction();
   });
 
   await program.parseAsync(process.argv);

package/src/cli/json-error-on-exit.ts

@@ -0,0 +1,72 @@
+/**
+ * `--json` failures speak JSON too (#939 item 7). A command that supports `--json` and fails used to
+ * print its error on stderr and NOTHING on stdout, so a caller parsing stdout got an empty string. Now,
+ * when such a command exits non-zero without having written stdout, the exit prints one object:
+ *
+ *   {"error":{"code":"command-failed" | "usage-error","message":"<the error it printed>"}}
+ *
+ *   command-failed  the action ran and failed (`next nope --json`)
+ *   usage-error     commander refused the arguments before any action ran (`audit --json --bogus`)
+ * The human error stays on stderr, unchanged. A command that printed its own JSON keeps it, whatever
+ * its exit code (`contract check --json` exits 2 with the verdict); a command without `--json` is never
+ * touched — commander's own "unknown option '--json'" is its usage error, not a JSON caller's.
+ * Like the hand-back, it hangs off process exit: commands exit from inside their actions.
+ */
+import type { Command } from 'commander';
+
+export type JsonErrorCode = 'command-failed' | 'usage-error';
+export interface JsonError { error: { code: JsonErrorCode; message: string } }
+
+const ANSI = /\u001b\[[0-9;]*m/g;
+const ERROR_LINE = /^(?:Error|error|Fatal error|❌[^:]*):\s*/;
+const MAX_CAPTURE = 64 * 1024;
+
+/** The error object for what the command printed on stderr: from its first error line on, the hand-back dropped. */
+export function jsonErrorPayload(stderr: string, actionRan: boolean, exitCode: number): JsonError {
+  const lines = stderr.replace(ANSI, '').split('\n').map((l) => l.trimEnd()).filter((l) => l && !/^Next: /.test(l));
+  const at = lines.findIndex((l) => ERROR_LINE.test(l));
+  const picked = at >= 0 ? lines.slice(at) : lines.slice(-1);
+  const message = picked.join('\n').replace(ERROR_LINE, '').trim() || `exited with code ${exitCode}`;
+  return { error: { code: actionRan ? 'command-failed' : 'usage-error', message } };
+}
+
+/** The (sub)command `args` name, walked down from `program`, defines `--json`. */
+export function commandSupportsJson(program: Command, args: string[]): boolean {
+  let cmd: Command = program;
+  for (const a of args) {
+    if (a.startsWith('-')) continue;
+    const sub = cmd.commands.find((c) => c.name() === a || c.aliases().includes(a));
+    if (!sub) break;
+    cmd = sub;
+  }
+  return cmd !== program && cmd.options.some((o) => o.long === '--json');
+}
+
+/**
+ * Wire it to process exit for `argv` (a no-op without `--json`). `supportsJson` is asked at exit, once
+ * every command is registered; `onAction` marks that an action ran (a failure then is not a usage error).
+ */
+export function attachJsonErrorOnExit(argv: string[], supportsJson: (args: string[]) => boolean): { onAction: () => void } {
+  const args = argv.slice(2);
+  if (!args.includes('--json')) return { onAction: () => undefined };
+  let wroteStdout = false;
+  let stderr = '';
+  let actionRan = false;
+  const writeOut = process.stdout.write.bind(process.stdout);
+  const writeErr = process.stderr.write.bind(process.stderr);
+  process.stdout.write = ((chunk: unknown, ...rest: unknown[]) => {
+    if (String(chunk).length) wroteStdout = true;
+    return (writeOut as (...a: unknown[]) => boolean)(chunk, ...rest);
+  }) as typeof process.stdout.write;
+  process.stderr.write = ((chunk: unknown, ...rest: unknown[]) => {
+    if (stderr.length < MAX_CAPTURE) stderr += String(chunk);
+    return (writeErr as (...a: unknown[]) => boolean)(chunk, ...rest);
+  }) as typeof process.stderr.write;
+  process.on('exit', (code) => {
+    try {
+      if (code === 0 || wroteStdout || !supportsJson(args)) return;
+      writeOut(`${JSON.stringify(jsonErrorPayload(stderr, actionRan, code))}\n`);
+    } catch { /* the exit code is the contract; this object is a courtesy */ }
+  });
+  return { onAction: () => { actionRan = true; } };
+}

package/src/cli/waiting-for-you-block.ts

@@ -0,0 +1,23 @@
+/**
+ * The "Waiting for you" block (#954) — every pending human-only action of a unit, as ready-to-copy
+ * commands with the reason under each. One renderer for the three places that show it: `sungen next`
+ * (text) and the Stop / SessionStart hook context. Commands as the project runs sungen (`npx sungen`
+ * with a local install, #939); `--json` keeps them canonical in `humanActions`. An instruction (a commit
+ * through review, a `git checkout --`) is marked `✎ … (by hand, not a command)`, never shown as one to copy.
+ */
+import type { HumanAction } from '../graph/human-action';
+import { withProjectInvocation } from './project-sungen-invocation';
+
+export const WAITING_FOR_YOU_HEAD = '⏳ Waiting for you — a human runs these in their own terminal (in Claude Code: ! <command>); an agent never runs them:';
+
+/**
+ * The block's lines (indented two spaces), or none when nothing waits for a human. `heldBy`: the title
+ * of the blocking step that cut the frontier — the block is not exhaustive then, and says what holds the rest.
+ */
+export function waitingForYouLines(actions: readonly HumanAction[] | undefined, projectRoot: string, heldBy?: string): string[] {
+  if (!actions?.length) return [];
+  return [`  ${WAITING_FOR_YOU_HEAD}`, ...actions.flatMap((a) => [
+    a.instruction ? `     ✎ ${a.command}   (by hand, not a command)` : `     ${withProjectInvocation(a.command, projectRoot)}`,
+    `       ${a.reason}`,
+  ]), ...(heldBy ? [`     More appear once "${heldBy}" clears.`] : [])];
+}

package/src/contract/derive-free-feature.ts

@@ -22,6 +22,7 @@ import { scrubKnownSecrets, scrubMachinePaths, secretScanHits, SecretHit } from
 import { idOfTitle, splitFeatureBlocks } from './free-feature-blocks';
 import { sensitiveLiteralHits } from './lock-secret-guard';
 import { scenariosOfFeatureFile } from './normalize-feature-steps';
+import { featureFilesFor } from '../harness/unit-paths';
 import { CONTROL_CHARS, freeFeatureText, renderTraceSteps, scenarioBlockText } from './render-free-gherkin';
 import { collectRuns, TraceRun } from './trace/collect-trace-evidence';
 import { readIdentityCache } from './trace/identity-cache';
@@ -39,6 +40,8 @@ export interface DeriveResult {
   skipped: Array<{ id: string; reason: string; approved?: true }>;
   refused?: SecretHit[];
   note?: string;
+  /** A derived id another `.feature` of the unit already uses (#939) — `contract check` and approve would trip on it later. */
+  warnings?: string[];
 }
 
 const MACHINE_PATH = /(?:\/Users|\/home)\/[^/\s"'`]+\/|[A-Za-z]:\\Users\\/;
@@ -59,6 +62,22 @@ function semanticHits(text: string, label: string): SecretHit[] {
   } finally { fs.rmSync(dir, { recursive: true, force: true }); }
 }
 
+/**
+ * The derived ids another `.feature` of the unit already carries (#939): `contract check` reports an id
+ * used twice and approve refuses it, so say it now — when it is still one rename away — not at check.
+ */
+function reusedIdWarnings(unit: { name: string; dir: string }, freeFile: string, ids: string[]): string[] {
+  const owners = new Map<string, string>();
+  for (const f of featureFilesFor(unit.dir, unit.name)) {
+    if (path.resolve(f) === path.resolve(freeFile) || !fs.existsSync(f)) continue;
+    try {
+      for (const sc of scenariosOfFeatureFile(f)) if (!owners.has(sc.id)) owners.set(sc.id, path.basename(f));
+    } catch { /* an unparseable sibling is `contract check`'s to report */ }
+  }
+  return ids.filter((id) => owners.has(id)).map((id) =>
+    `${id} is already the ID of a scenario in ${owners.get(id)} — the derived scenario reuses it; give the free test (its title's leading ID) or that scenario its own ID, or \`sungen contract check\` reports it twice and approval refuses it`);
+}
+
 /**
  * Nothing was derived and nothing explains it away: no test of the unit left an admissible trace
  * (#932). Not when the scenarios are approved (derive leaves those alone by design), up to date,
@@ -108,6 +127,8 @@ export async function deriveFreeFeature(i: DeriveInput): Promise<DeriveResult> {
     result.scenarios.push({ id, title, steps: rendered[0].length, low: rendered[0].filter((s) => s.low).length, opaque: rendered[0].filter((s) => s.opaque).length });
   }
   if (!result.scenarios.length) return result;
+  const reused = reusedIdWarnings(i.unit, file, result.scenarios.map((x) => x.id));
+  if (reused.length) result.warnings = reused;
 
   const text = freeFeatureText(unitBase, [...blocks.values()]);
   const label = path.basename(file);

package/src/decisions/legacy-waiver-migration.ts

@@ -80,9 +80,13 @@ export function planWaiverSync(projectRoot: string, unit: string, slug: string,
   return { scope, waivers, untrusted, stateWaivers, imports, markDone: !!scope && untrusted.length === 0 };
 }
 
+/** The command a human types to give (or confirm) a waiver — the board's line and `sungen next`'s "Waiting for you" (#954). */
+export const waiveCommand = (unit: string, obligation: string, reason: string): string =>
+  formatCommand(['sungen', 'journey', '--screen', unit, '--waive', obligation, '--reason', reason]);
+
 /** The needs-you line for a waiver that is not in git HEAD: not counted, and how a human confirms it. */
 export function untrustedWaiverText(unit: string, slug: string, title: string, u: UntrustedWaiver): string {
-  const confirm = formatCommand(['sungen', 'journey', '--screen', unit, '--waive', u.obligation, '--reason', u.waiver.reason]);
+  const confirm = waiveCommand(unit, u.obligation, u.waiver.reason);
   return `⚠️ Waiver on "${title}" is UNTRUSTED — not counted (decision.in-run: it is in .sungen/journey/${slug}.state.json `
     + `but not in git HEAD). If it is yours, confirm it on a terminal: ${confirm}`;
 }

package/src/graph/board-human-actions.ts

@@ -0,0 +1,80 @@
+/**
+ * The human-only actions the graph does not hold ("Waiting for you", #954) — asked by the journey
+ * board and the delivery's decision check, read through THEIR functions (never restated here):
+ *
+ *   waive          a waiver the board re-surfaces: stale (the audit changed since) or untrusted (not
+ *                  in git HEAD) — readJourneyHumanAsks, the reconcile `runJourney` commits
+ *   decide         a gate-override that relaxes nothing because no human confirmed it (ineffective) —
+ *                  re-recorded with `journey --decide`, superseding it (loadUnitGateOverrides)
+ *   signoff        every other obligation holds — assertCanSignOff, as `journey --signoff` checks it
+ *   accept-in-run  a decision recorded during the run — evaluateDeliveryDecisions, as `delivery` runs it
+ * The sign-off and accept-in-run only once the frontier was not cut (the unit has run and nothing
+ * blocks before it). Read-only and advisory: whatever cannot be read adds nothing.
+ */
+import { formatCommand } from '../decisions/human-confirmation';
+import { waiveCommand } from '../decisions/legacy-waiver-migration';
+import { evaluateDeliveryDecisions } from '../harness/gates/delivery-decision-gate';
+import { IN_RUN_RULE } from '../harness/gates/in-run-decision-check';
+import { loadUnitGateOverrides, unitScopeOfDir } from '../harness/gates/unit-gate-overrides';
+import { readJourneyHumanAsks, signoffCommand } from '../harness/journey';
+import type { UnitState } from '../harness/next-step';
+import type { HumanAction } from './human-action';
+import { unitResultFiles } from './unit-artifact-probes';
+
+function journeyActions(projectRoot: string, s: UnitState, cut: boolean): HumanAction[] {
+  const asks = readJourneyHumanAsks(projectRoot, s.unit);
+  const out: HumanAction[] = asks.redecide.map((w) => ({
+    kind: 'waive',
+    command: waiveCommand(s.unit, w.obligation, w.reason),
+    reason: w.why === 'stale'
+      ? `the waiver on "${w.title}" is stale — the evidence changed since it was given, so it no longer counts; if it still holds, a human gives it again on a terminal (or repair the obligation)`
+      : `the waiver on "${w.title}" is not in git HEAD (decision.in-run), so it is not counted — if it is yours, confirm it on a terminal`,
+  }));
+  if (!cut && asks.canSignOff && asks.signoff.status !== 'given') {
+    out.push({
+      kind: 'signoff',
+      command: signoffCommand(s.unit),
+      reason: asks.signoff.status === 'stale'
+        ? `the sign-off of ${asks.signoff.at} is stale — the suite changed since; review the queue (\`sungen journey --screen ${s.unit}\`) and sign off again`
+        : `every other obligation is satisfied or waived — the human sign-off is the one gate \`sungen gate --phase deliver\` still waits on; review the queue (\`sungen journey --screen ${s.unit}\`, ${asks.report.needsYou.length} item(s)), then sign`,
+    });
+  }
+  return out;
+}
+
+function unconfirmedOverrides(projectRoot: string, unitDir: string, s: UnitState): HumanAction[] {
+  return loadUnitGateOverrides(projectRoot, unitScopeOfDir(projectRoot, unitDir)).ineffective.map((o) => {
+    const { humanAccepted: _ignored, ...payload } = o.entry.payload ?? {};
+    return {
+      kind: 'decide',
+      command: formatCommand(['sungen', 'journey', '--screen', s.unit, '--decide', 'gate-override', '--text', o.entry.text, '--reason', o.entry.reason,
+        '--payload', JSON.stringify(payload), '--supersedes', o.decisionId]),
+      reason: `the gate-override ${o.decisionId}${o.rule ? ` (${o.rule})` : ''} relaxes nothing: ${o.reason} — if it is meant, a human records it again on a terminal, superseding it`,
+    };
+  });
+}
+
+function inRunActions(projectRoot: string, unitDir: string, s: UnitState): HumanAction[] {
+  const files = unitResultFiles(projectRoot, s.unit);
+  const refs = (files.length ? files : [null]).map((resultsPath) => ({ label: s.unit, unitName: s.unit, unitDir, resultsPath }));
+  const inRun = evaluateDeliveryDecisions(projectRoot, refs).inRun;
+  if (!inRun.length) return [];
+  const which = inRun.slice(0, 3).map((d) => `${d.kind} ${d.id}`).join(', ');
+  return [{
+    kind: 'accept-in-run',
+    command: formatCommand(['sungen', 'delivery', s.unit, '--accept-in-run']),
+    reason: `${inRun.length} decision(s) recorded during the run (${IN_RUN_RULE}): ${which}${inRun.length > 3 ? ', …' : ''} — \`sungen delivery\` refuses them until they are committed through review and the tests re-run, or a human accepts them on a terminal`,
+  }];
+}
+
+/** The board's and the delivery's asks of a human for this unit. `cut`: the frontier stopped at a blocking node. */
+export function boardHumanActions(projectRoot: string, unitDir: string, s: UnitState, cut: boolean): HumanAction[] {
+  const out: HumanAction[] = [];
+  const add = (read: () => HumanAction[]): void => {
+    try { out.push(...read()); } catch { /* advisory: an unreadable board or decision adds nothing */ }
+  };
+  add(() => journeyActions(projectRoot, s, cut));
+  add(() => unconfirmedOverrides(projectRoot, unitDir, s));
+  if (!cut) add(() => inRunActions(projectRoot, unitDir, s));
+  return out;
+}

package/src/graph/evaluate-graph.ts

@@ -11,8 +11,12 @@
  * `--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
  * node speaks only there (its unit-level decision is in the unit view already).
+ *
+ * evaluateHumanActions reads the SAME walk for "Waiting for you" (#954): the human-only actions behind
+ * the offered steps, and whether the walk was cut.
  */
 import type { NextStep, UnitState } from '../harness/next-step';
+import type { HumanAction } from './human-action';
 import type { NodeDecl, StepCore } from './node-decl';
 import type { TestCaseState } from './test-case-state-shape';
 
@@ -37,30 +41,55 @@ function openCases(node: NodeDecl, s: UnitState, tcStates: TestCaseState[] | und
   return tcStates.filter((tc) => (!only || tc.id === only) && node.active(s, tc) && !node.satisfied(s, tc));
 }
 
-export function evaluateGraph(
-  nodes: readonly NodeDecl[], s: UnitState, tcStates?: TestCaseState[], opts: EvaluateOptions = {},
-): NextStep[] {
+/** One offered step and what produced it: the node, and the cases open at it (test-case nodes). */
+interface Offered { node: NodeDecl; step: NextStep; cases: TestCaseState[] }
+
+/** The walk both answers share: the offered steps in rank order, and whether an open blocking node cut it. */
+function walkFrontier(nodes: readonly NodeDecl[], s: UnitState, tcStates: TestCaseState[] | undefined, opts: EvaluateOptions): { offered: Offered[]; cut: boolean; cutBy?: NodeDecl } {
   const ordered = [...nodes].sort((a, b) => a.rank - b.rank);
   const open = new Set<string>();
-  const out: NextStep[] = [];
+  const offered: Offered[] = [];
   let cut = false;
+  let cutBy: NodeDecl | undefined;
   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;
+    let cases: TestCaseState[] = [];
     if (node.granularity === 'unit') {
       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).filter((tc) => !cut || node.surfacesPastCut!(s, tc));
+      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 && (cut || ready || !node.blocking)) out.push(step);
-    if (node.blocking && !cut) cut = true;
+    if (step && (cut || ready || !node.blocking)) offered.push({ node, step, cases });
+    if (node.blocking && !cut) { cut = true; cutBy = node; }
   }
-  return out;
+  return { offered, cut, ...(cutBy ? { cutBy } : {}) };
+}
+
+export function evaluateGraph(
+  nodes: readonly NodeDecl[], s: UnitState, tcStates?: TestCaseState[], opts: EvaluateOptions = {},
+): NextStep[] {
+  return walkFrontier(nodes, s, tcStates, opts).offered.map((o) => o.step);
+}
+
+/**
+ * The HUMAN-ONLY actions of the same frontier ("Waiting for you", #954) — never a second walk with
+ * rules of its own: each offered step's node says what a person runs (its `human` hook), and a decide
+ * step without one is its own command. `cut`: an open blocking node ended the walk, so only what does
+ * not depend on it is offered (a hard verdict that surfaces past the cut), and the board's asks that
+ * need the unit past it (sign-off, accept-in-run) wait; `heldBy` is that node's title.
+ */
+export function evaluateHumanActions(nodes: readonly NodeDecl[], s: UnitState, tcStates?: TestCaseState[]): { actions: HumanAction[]; cut: boolean; heldBy?: string } {
+  const { offered, cut, cutBy } = walkFrontier(nodes, s, tcStates, {});
+  const actions = offered.flatMap(({ node, step, cases }) => (node.human
+    ? node.human(s, step, cases)
+    : step.kind === 'decide' ? [{ command: step.command, reason: step.because, kind: 'decide' as const }] : []));
+  return { actions, cut, ...(cutBy ? { heldBy: cutBy.title } : {}) };
 }

package/src/graph/human-action.ts

@@ -0,0 +1,33 @@
+/**
+ * A HUMAN-ONLY action of a unit — what `sungen next` lists under "Waiting for you" (#954) and `--json`
+ * carries as `humanActions`. An agent presents these and never runs them: they approve, sign, waive,
+ * classify or accept something on a person's behalf, and most refuse without a typed confirmation.
+ *
+ * `command` is canonical (`sungen …`, or a slash command); the text renders it as the project runs
+ * sungen (`npx sungen` with a local install). Placeholders a human fills are quoted (`"<name>"`, `"…"`)
+ * so a copied command never turns into a shell redirection.
+ */
+export type HumanActionKind =
+  | 'contract-approve'   // approve (or re-approve) the Test Contract — `sungen contract approve`
+  | 'accept-opaque'      // accept a reviewed opaque trace step — `contract approve --scenario <id> --accept-opaque`
+  | 'contract-commit'    // commit, or restore, a lock / approval decision through review
+  | 'contract-review'    // read the contract verdict on a terminal (it could not be built)
+  | 'accept-viewpoint'   // accept the changed viewpoint baseline — `sungen audit --accept-viewpoint`
+  | 'defect-draft'       // decide whether a product-defect candidate is a defect — `sungen defect draft`
+  | 'rerun-environment'  // re-run the reds the environment caused, once a human confirms it is up
+  | 'triage-classify'    // classify a red by hand as test-defect / environment — `sungen triage --case --as`
+  | 'signoff'            // the single human gate — `sungen journey --signoff`
+  | 'waive'              // give a waiver again — `sungen journey --waive`
+  | 'decide'             // record a decision — `sungen journey --decide`
+  | 'accept-in-run';     // deliver despite decisions recorded during the run — `sungen delivery --accept-in-run`
+
+export interface HumanAction {
+  command: string;
+  reason: string;
+  kind: HumanActionKind;
+  /**
+   * `command` is an instruction a person carries out by hand (commit through review, restore from git),
+   * not a command line to copy — the block marks it so, and never renders it as one.
+   */
+  instruction?: true;
+}

package/src/graph/node-decl.ts

@@ -11,6 +11,7 @@
  * `sungen next <unit> --case <id>`).
  */
 import type { NextStep, UnitState } from '../harness/next-step';
+import type { HumanAction, HumanActionKind } from './human-action';
 import type { TestCaseState } from './test-case-state-shape';
 
 export type NodeActor = 'ai' | 'human' | 'deterministic';
@@ -35,8 +36,18 @@ interface NodeDeclBase {
   gates: readonly string[];
   /** Artifacts the step produces, for a reader of the graph. */
   produces: readonly string[];
+  /**
+   * The HUMAN-ONLY actions behind an offered step ("Waiting for you", #954): what a person runs, with
+   * why. Without it a `decide` step is one action of kind `decide` and any other step is none. `cases`
+   * are the cases open at a test-case node (none for a unit node).
+   */
+  human?(s: UnitState, step: StepCore, cases: TestCaseState[]): HumanAction[];
 }
 
+/** The `human` hook of a node whose decide step IS the human action: its command and reason, under `kind`. */
+export const humanStep = (kind: HumanActionKind) => (_s: UnitState, step: StepCore): HumanAction[] =>
+  [{ command: step.command, reason: step.because, kind }];
+
 export interface UnitNodeDecl extends NodeDeclBase {
   granularity: 'unit';
   active(s: UnitState): boolean;