@cspeach/cli 1.0.0 → 1.1.0

package/dist/commands/plan-resume.js

@@ -38,15 +38,63 @@
 // that survives the session, so losing the write-back breaks the plan.
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
+import chalk from 'chalk';
 import { readProjectFile } from '../projects/status.js';
 import { resolveAtTokenAsync, formatProjectFileList, ensureWorkspace } from '../projects/workspace.js';
-import { parsePlanContent } from '../projects/plan-schema.js';
-import { statusesFromItems, computeNextPhase, renderPlanTracker, buildPlanRevision, isPhaseSatisfied, planCompletionLines, } from '../projects/plan-run.js';
+import { parsePlanContent, phaseWrites } from '../projects/plan-schema.js';
+import { statusesFromItems, computeNextPhase, renderPlanTracker, buildPlanRevision, isPhaseSatisfied, isAuditResolved, planCompletionLines, findServiceBinding, } from '../projects/plan-run.js';
 import { extractPlan } from '../projects/extract-plan.js';
 import { saveProject } from '../projects/save.js';
+import { writePlanHandover } from '../projects/handover-md.js';
+import { acquireRunLease, releaseRunLease } from '../projects/run-lease.js';
 import { validateEnvelope } from '../projects/validate.js';
 import { collectTurnAssistantText } from '../agent/turn-assistant-text.js';
 import { getAuthorIdentity } from '../agent/loop.js';
+import { FLOORPLAN_TO_TEMPLATE } from '../tools/fiori/floorplan-map.js';
+import { getCurrentTransport, setCurrentTransport } from '../repl/current-transport.js';
+/**
+ * Parse and STRIP the per-run chaining-mode (`--guarded` / `--step`) and
+ * audit off-switch (`--audit` / `--no-audit`) flags from a plan-resume body.
+ * Pure; every other token (including `--resume` and `@` tokens) passes through
+ * untouched, so downstream parsing is unchanged.
+ *
+ * Conflict resolution — the SAFER option wins, always:
+ *   - mode:  BOTH `--guarded`+`--step` present ⇒ `--step` (more prompting).
+ *   - audit: BOTH `--audit`+`--no-audit` present ⇒ `--audit`/'on' (more
+ *            checking — a conflicting toggle must never silently disable the
+ *            auditor; mirrors the --step-beats---guarded precedent).
+ */
+export function parsePlanResumeFlags(body) {
+    let guarded = false;
+    let step = false;
+    let auditOn = false;
+    let auditOff = false;
+    const rest = [];
+    for (const tok of body.split(/\s+/)) {
+        if (tok === '--guarded') {
+            guarded = true;
+            continue;
+        }
+        if (tok === '--step') {
+            step = true;
+            continue;
+        }
+        if (tok === '--audit') {
+            auditOn = true;
+            continue;
+        }
+        if (tok === '--no-audit') {
+            auditOff = true;
+            continue;
+        }
+        if (tok.length > 0)
+            rest.push(tok);
+    }
+    const mode = step ? 'step' : guarded ? 'guarded' : undefined;
+    // 'on' wins the conflict (safer — never let a conflicting flag turn audits off).
+    const audit = auditOn ? 'on' : auditOff ? 'off' : undefined;
+    return { mode, audit, body: rest.join(' ') };
+}
 /**
  * A1 (defect D23) — the harness-owned continuation contract, stated to the
  * model verbatim in every resume prompt: the manifest ends the turn; the
@@ -57,8 +105,58 @@ import { getAuthorIdentity } from '../agent/loop.js';
  * a 6-phase run once snowballed to a 3.24M-token context).
  */
 export const PLAN_RESUME_HARNESS_OVERRIDE = 'HARNESS OVERRIDE of the skill\'s Mode 2 step 8: do NOT ask a continuation question, do NOT call dispatch_skill, and NEVER start another phase in this turn. After your manifest is persisted, the CLI itself asks the user whether to run the next phase and dispatches it with the exact saved file in a fresh bounded context. Phase end = turn end.';
+/** Harness-owned ui-phase context (Track 1). Same principle as
+ * buildResumeCommand (D23): the model must never have to recall the
+ * binding name, flavor, or app dir from a prior session — the envelope
+ * knows. app/service are recorded by ui.build but consumed by ui.deploy,
+ * so resolution scans ALL ui phases, last-written wins. */
+export function buildUiPhaseContext(phases, next) {
+    if (next.layer !== 'ui')
+        return [];
+    const binding = findServiceBinding(phases);
+    const uiPhases = phases.filter(p => p.layer === 'ui');
+    const appDir = [...uiPhases].reverse().map(p => p.work?.app?.dir).find(Boolean);
+    const service = [...uiPhases].reverse().map(p => p.work?.service).find(s => s && (s.url || s.path));
+    const lines = ['UI phase context (harness-provided — authoritative, do not re-derive):'];
+    lines.push(binding
+        ? `- Published service binding: ${binding}`
+        : '- Published service binding: NOT RECORDED in any service phase work.binding — resolve it live (sap_search_object) before building, and record it in this phase\'s work.');
+    if (next.ui) {
+        lines.push(`- Flavor: ${next.ui.flavor}`);
+        if (next.ui.floorplan)
+            lines.push(`- Floorplan: ${next.ui.floorplan} (tool template: ${FLOORPLAN_TO_TEMPLATE[next.ui.floorplan]})`);
+        if (next.ui.appId)
+            lines.push(`- App id: ${next.ui.appId}`);
+        if (next.ui.appTitle)
+            lines.push(`- App title: ${next.ui.appTitle}`);
+    }
+    if (appDir)
+        lines.push(`- App directory (recorded by ui.build): ${appDir}`);
+    if (service)
+        lines.push(`- Service URL: ${service.url ?? ''}${service.path ?? ''} (OData ${service.version ?? '?'})`);
+    return lines;
+}
+/** Compact-example work keys for ui phases — the write-back contract
+ * (review C3). Returns an OBJECT fragment because compactExample renders
+ * via JSON.stringify: it is spread into the `work` object exactly like the
+ * existing service-phase `binding` conditional (a string-array spread there
+ * would render numeric keys — cycle-2 N-1). */
+export function buildUiWorkExample(next) {
+    if (next.layer !== 'ui')
+        return {};
+    return {
+        app: { dir: '<app directory ui.build created — ui.build only, omit on deploy>' },
+        service: { url: '<https://host:port — ui.build only>', path: '</sap/opu/odata4/...>', version: '4.0' },
+        deployedUrl: '<BSP index.html URL — ui.deploy only>',
+    };
+}
 export async function preparePlanResume(args) {
-    const tokens = args.body
+    // Agentic-flow: pull the per-run --guarded/--step mode override out of the
+    // body BEFORE the @-token filter so the flags never collide with token
+    // resolution (they wouldn't match the @ filter anyway, but stripping keeps
+    // the invariant explicit and the flags out of any downstream body use).
+    const flags = parsePlanResumeFlags(args.body);
+    const tokens = flags.body
         .split(/\s+/)
         .filter((tok) => tok.startsWith('@'))
         .map((tok) => tok.slice(1))
@@ -126,22 +224,184 @@ export async function preparePlanResume(args) {
             args.log(`  ${e}`);
         return null;
     }
-    const content = pc.content;
-    const statuses = statusesFromItems(envelope.interaction.items, content.phases);
-    const next = computeNextPhase(content.phases, statuses);
+    let content = pc.content;
+    // Transport display on resume (2026-07-09) — adopt the plan's dedicated
+    // transport into the session so the `tr <TRKORR>` status segment shows it.
+    // A fresh process resuming mid-plan runs no sap_transport_create (the
+    // transport already exists), so setCurrentTransport was never called and the
+    // status read `tr none` even while the phase resolves + writes to the
+    // recorded transport. Runs on EVERY resume, BEFORE the phase (or re-audit)
+    // executes. No-clobber (an explicit /transport or a create earlier THIS
+    // session wins) and null-safe (no recorded transport yet ⇒ leave it,
+    // `tr none` is then correct) are both handled inside the helper. Rule 9
+    // bonus: the tool-handler 3-tier fallback can now use it too.
+    adoptPlanTransportOnResume(content.phases);
+    // Task 9 — run lease: refuse a SECOND session resuming the same plan
+    // family concurrently (double-resume forks sibling envelope versions
+    // silently: saveProject appends collision suffixes and the newest-version
+    // redirect above tie-breaks on mtime). Taken HERE — after the redirect and
+    // validation — so the lease targets the file actually resumed; keyed on
+    // the FAMILY base (leasePathFor strips the -vN suffix) so the v3→v4
+    // rotation every phase save performs keeps the lease. Same-session
+    // re-acquire is idempotent, so the queueDispatch re-entry on every chained
+    // phase never blocks itself. Best-effort: fs errors inside acquireRunLease
+    // log one line and proceed as acquired (courtesy guard, availability over
+    // strictness). Only a LIVE other-session holder stops us — and even then
+    // the user may take over interactively.
+    if (args.sessionId) {
+        const lease = acquireRunLease(path, args.sessionId, { log: (line) => args.log(line) });
+        if (!lease.acquired && lease.holder) {
+            const holder = lease.holder;
+            args.log(`⚠ another session is already resuming this plan — session ${holder.sessionId} (pid ${holder.pid}${holder.at ? `, since ${holder.at}` : ''}).`);
+            const answer = args.prompt
+                ? (await args.prompt('Take over its run lease and resume here anyway? [y/N]: ')).trim().toLowerCase()
+                : '';
+            if (answer !== 'y' && answer !== 'yes') {
+                args.log('Resume refused — the other session keeps the lease. Re-run when it finishes (a dead session\'s lease is taken over automatically).');
+                return null;
+            }
+            acquireRunLease(path, args.sessionId, { force: true, log: (line) => args.log(line) });
+            args.log('Run lease taken over — resuming in this session.');
+        }
+    }
+    const effectiveMode = flags.mode ?? args.configMode ?? 'step';
+    // Audit off-switch (2026-07-06, owner): per-run flag > config default > 'on'.
+    const effectiveAudit = flags.audit ?? args.configAudit ?? 'on';
+    // Explicit --no-audit is a strong, deliberate signal — it is the ONLY thing
+    // that WAIVES persisted unresolved audits (below). A config-level off never
+    // waives: a pending/infra record was created under ON and gets its honest
+    // verdict re-run (config-off governs only NEW phases).
+    const auditsExplicitlyOff = flags.audit === 'off';
+    let statuses = statusesFromItems(envelope.interaction.items, content.phases);
+    // Audit off-switch — explicit `--no-audit` cleanup. A pending/infra_failed
+    // (or died-at-menu 'failed'-on-satisfied) record left by an earlier ON run
+    // would block eligibility forever if left unresolved and never re-audited.
+    // Under an explicit --no-audit the user has said "no audits now": resolve
+    // them as waived('audits turned off') — NO audit turn runs — so the plan
+    // can proceed. (Config-level off deliberately does NOT do this; see above.)
+    if (auditsExplicitlyOff) {
+        const unresolved = content.phases.filter((p) => {
+            const st = p.audit?.state;
+            return st === 'pending' || st === 'infra_failed'
+                || (st === 'failed' && isPhaseSatisfied(statuses[p.id]));
+        });
+        if (unresolved.length > 0) {
+            for (const p of unresolved) {
+                path = await applyAuditResult(path, p.id, { state: 'waived', waivedReason: 'audits turned off' }, { log: (...lines) => args.log(...lines) });
+            }
+            envelope = readProjectFile(path);
+            const rc = parsePlanContent(envelope.content);
+            if (rc.ok)
+                content = rc.content;
+            statuses = statusesFromItems(envelope.interaction.items, content.phases);
+            // M5 — name every waived phase, and flag a FAILED-with-findings record
+            // loudly: waiving a recorded failure is a bigger call than waiving a
+            // never-judged pending, and the user must see which one they made.
+            const names = unresolved.map((p) => p.audit?.state === 'failed'
+                ? `${p.id} (FAILED audit — ${p.audit.findings?.length ?? 0} finding${(p.audit.findings?.length ?? 0) === 1 ? '' : 's'} waived)`
+                : `${p.id} (${p.audit?.state ?? 'unresolved'})`);
+            args.log(`↪ audits off (--no-audit): waived ${unresolved.length} unresolved audit${unresolved.length === 1 ? '' : 's'} from an earlier run — ${names.join(', ')} (reason: audits turned off).`);
+        }
+    }
+    // Task 6 — hand-edit detection: the newest history entry was NOT authored
+    // by this harness (getAuthorIdentity), so its "validated" claims were never
+    // earned through the audited flow. Downgrade satisfied phases whose audit
+    // is absent-or-passed to not_audited_hand_edited IN MEMORY ONLY — the file
+    // is never rewritten, and eligibility (computeNextPhase below) still uses
+    // the REAL content, or every hand-touched legacy plan would deadlock.
+    // Step mode: the tracker glyph is the whole effect. Guarded mode: the chain
+    // stops to re-audit EVERY hand-touched satisfied phase (I-2 pass, below).
+    const lastHistory = envelope.history[envelope.history.length - 1];
+    const handEdited = lastHistory !== undefined && lastHistory.by?.name !== getAuthorIdentity().name;
+    const handEditDowngraded = (p) => isPhaseSatisfied(statuses[p.id]) && (p.audit === undefined || p.audit.state === 'passed');
+    let trackerContent = content;
+    if (handEdited) {
+        trackerContent = {
+            ...content,
+            phases: content.phases.map((p) => handEditDowngraded(p)
+                ? { ...p, audit: { ...(p.audit ?? {}), state: 'not_audited_hand_edited' } }
+                : p),
+        };
+        args.log(`⚠ envelope was last edited outside this harness (by ${lastHistory?.by?.name ?? 'unknown'}) — satisfied phases without a harness audit are shown as hand-edited (file not rewritten).`);
+    }
+    // Task 6 — re-audit-on-resume: an unresolved persisted audit (a crash
+    // between phase save and verdict save leaves 'pending'; an auditor outage
+    // leaves 'infra_failed') is re-run FIRST — no new phase executes this
+    // dispatch. Scan newest-last so the most recent execution is re-judged.
+    // Fix-wave (item 10a): a persisted 'failed' on a phase that still CLAIMS
+    // satisfied means the session died AT the failure menu (the verdict wrote,
+    // the resolution never did) — re-audit it and re-offer the menu instead of
+    // dead-ending in the "resolve by hand" message. A failed audit on a
+    // non-satisfied phase (forced block / user chose re-run) was already
+    // resolved and is NOT picked up.
+    // Audit off-switch: under an explicit --no-audit the persisted unresolved
+    // records were already waived above, so this scan finds nothing anyway; the
+    // guard keeps the intent explicit. Under config-off the persisted scan STILL
+    // runs (a stuck pending must resolve — config-off governs only NEW phases),
+    // but the guarded HAND-EDIT re-verification (itself an audit pass) does not.
+    let reauditPhaseIds = [];
+    if (!auditsExplicitlyOff) {
+        for (let i = content.phases.length - 1; i >= 0; i--) {
+            const p = content.phases[i];
+            const st = p.audit?.state;
+            // audit-infra-continue (2026-07-09): 'infra_failed' is NO LONGER scanned
+            // for re-audit — it is a RESOLVED state (the audit could not run; the
+            // chain already continued past it). Re-auditing it here would wall an
+            // already-continued phase on a later resume. Only a crash-left 'pending'
+            // or a died-at-menu 'failed' on a still-satisfied phase re-audits.
+            if (st === 'pending'
+                || (st === 'failed' && isPhaseSatisfied(statuses[p.id]))) {
+                reauditPhaseIds = [p.id];
+                break;
+            }
+        }
+        // Guarded hand-edit re-verification (review I-2): no persisted unresolved
+        // audit, but the envelope was hand-touched — re-audit EVERY satisfied phase
+        // the hand edit invalidated (plan order: dependencies first), in one pass
+        // via runReauditPass, before chaining anything. Skipped when audits are off
+        // (config or flag): a hand-edit re-verification IS an audit pass.
+        if (reauditPhaseIds.length === 0 && handEdited && effectiveMode === 'guarded'
+            && effectiveAudit === 'on') {
+            reauditPhaseIds = content.phases.filter(handEditDowngraded).map((p) => p.id);
+        }
+    }
+    const reauditPhaseId = reauditPhaseIds[0];
+    const next = reauditPhaseId ? null : computeNextPhase(content.phases, statuses);
     args.log('');
     args.log(renderPlanTracker({
         title: envelope.title,
         version: envelope.version,
-        content,
+        content: trackerContent,
         statuses,
-        currentId: next?.id ?? null,
+        currentId: reauditPhaseId ?? next?.id ?? null,
+        auditsOff: effectiveAudit === 'off',
     }));
     args.log('');
+    if (reauditPhaseId) {
+        const reauditPhase = content.phases.find((p) => p.id === reauditPhaseId);
+        const st = reauditPhase.audit?.state;
+        args.log(st === 'failed'
+            ? `Phase ${reauditPhaseId} has a failed audit with no recorded resolution — re-running the audit, then offering re-run / waive / block.`
+            : st === 'pending'
+                ? `Phase ${reauditPhaseId} has an unresolved audit (${st}) — re-running the audit before executing anything.`
+                : `Guarded mode: re-auditing ${reauditPhaseIds.length} hand-edited phase${reauditPhaseIds.length === 1 ? '' : 's'} (${reauditPhaseIds.join(', ')}) before chaining.`);
+        return {
+            path, envelope, statuses,
+            nextPhaseId: reauditPhaseId,
+            nextDelegateTo: reauditPhase.delegateTo,
+            llmPrompt: '',
+            mode: flags.mode,
+            effectiveMode,
+            auditFlag: flags.audit,
+            auditMode: effectiveAudit,
+            reauditPhaseId,
+            reauditPhaseIds,
+        };
+    }
     if (!next) {
         // C1 (D30 waiver): 'validated-with-waiver' is satisfied — a plan whose
         // last gate was explicitly waived is complete, not stuck.
-        const allValidated = content.phases.every((p) => isPhaseSatisfied(statuses[p.id]));
+        const allValidated = content.phases.every((p) => isPhaseSatisfied(statuses[p.id], p.audit));
         if (allValidated) {
             // C2 (D24): a finished UI-less backend stack chains to /abap-fiori-build
             // with the exact binding name — the marketed idea→app story must not
@@ -150,9 +410,25 @@ export async function preparePlanResume(args) {
         }
         else {
             const blocked = content.phases.filter((p) => statuses[p.id] === 'blocked').map((p) => p.id);
-            args.log(`No eligible phase. Blocked: ${blocked.join(', ') || '(none)'} — remaining phases wait on them.`);
-            args.log('Unblock (fix + edit the envelope status back to todo) and resume again.');
+            // Task 2 review carry-over: a validated-but-audit-unresolved phase used
+            // to surface as "Blocked: (none)" — name the real block reason. Rarely
+            // reached since the fix-wave: pending/infra_failed AND satisfied-but-
+            // failed audits are all re-audited above; what remains is a hand-
+            // authored state (e.g. a user writing 'not_audited_hand_edited').
+            const unresolved = content.phases
+                .filter((p) => isPhaseSatisfied(statuses[p.id]) && !isAuditResolved(p.audit))
+                .map((p) => `${p.id} (audit ${p.audit?.state ?? 'unknown'})`);
+            const unresolvedNote = unresolved.length > 0 ? ` Unresolved audits: ${unresolved.join(', ')}.` : '';
+            args.log(`No eligible phase. Blocked: ${blocked.join(', ') || '(none)'}.${unresolvedNote} Remaining phases wait on them.`);
+            args.log(unresolved.length > 0
+                ? 'Resolve the unresolved audit (waive it or set the phase status back to todo for a re-run) and resume again.'
+                : 'Unblock (fix + edit the envelope status back to todo) and resume again.');
         }
+        // Task 9 — terminal state: nothing will run this dispatch, so don't
+        // leave a lease behind (a completed/deadlocked plan must be freely
+        // resumable by any session).
+        if (args.sessionId)
+            releaseRunLease(path);
         return null;
     }
     // Inline the phase's declared rule files (coarse v1: whole files).
@@ -176,6 +452,10 @@ export async function preparePlanResume(args) {
     // statuses + a `changed` entry for the executed phase only; extractPlan
     // merges it into the prior content. The example is built with the REAL
     // phase ids and current statuses so the model copies, not reconstructs.
+    // Task 11 (2026-07-03): deliberately NO `writes` here — the guarded-mode
+    // `writes` flag is authored once at plan CREATION (abap-plan SKILL.md
+    // Mode 1, item 7a); resume's `changed.work` merge never re-authors it and
+    // extractPlan preserves existing phase fields.
     const compactExample = [
         '<!-- csforge:plan-manifest',
         JSON.stringify({
@@ -192,6 +472,7 @@ export async function preparePlanResume(args) {
                         ...(next.layer === 'service'
                             ? { binding: '<published service binding name, e.g. ZUI_MAINTREQ_O4>' }
                             : {}),
+                        ...buildUiWorkExample(next),
                         notes: '<decisions, substitutions, blocker details worth keeping — omit if none>',
                     },
                 },
@@ -199,6 +480,11 @@ export async function preparePlanResume(args) {
         }, null, 2),
         '-->',
     ].join('\n');
+    // Track 1 (cosmetic F4): hoist the single evaluation — the double call plus
+    // the leading '' below produced a DOUBLE blank line on ui turns (line 520's
+    // '' already ends the prior element). Spread the blank AFTER the block so
+    // context keeps single-blank separation on both sides.
+    const uiContext = buildUiPhaseContext(content.phases, next);
     const llmPrompt = [
         `Resume execution of the project plan "${envelope.title}" (envelope v${envelope.version}).`,
         '',
@@ -218,7 +504,7 @@ export async function preparePlanResume(args) {
         // ended. The manifest now ENDS the turn; the harness owns continuation
         // (offerNextPhaseAutoRun) and dispatches the next phase itself with
         // the exact saved path, in reset context.
-        'CRITICAL — the write-back ENDS the turn: emit ONE COMPACT <!-- csforge:plan-manifest --> block as the LAST thing in your output, then END THE TURN. Compact shape = "title" + a "statuses" entry for EVERY phase + a "changed" map carrying ONLY the phase(s) you touched this turn (normally exactly this one). Each "changed" entry holds the phase\'s COMPLETE updated "work" (generated / transport / snapshot / notes — put the compact decision register in work.notes when the phase produced decisions rather than SAP objects); it replaces that phase\'s prior work wholesale. Do NOT re-emit "content" or the full phase list — the CLI already holds the full plan, merges your "changed" entries into it, and recomputes the summary. Exact shape for this turn:',
+        'CRITICAL — the write-back ENDS the turn: emit ONE COMPACT <!-- csforge:plan-manifest --> block as the LAST thing in your output, then END THE TURN. Compact shape = "title" + a "statuses" entry for EVERY phase + a "changed" map carrying ONLY the phase(s) you touched this turn (normally exactly this one). Each "changed" entry holds the phase\'s COMPLETE updated "work" (generated / transport / snapshot / notes — plus, on ui phases: app.dir + service{url,path,version} (ui.build) and deployedUrl (ui.deploy) — put the compact decision register in work.notes when the phase produced decisions rather than SAP objects); it replaces that phase\'s prior work wholesale. Do NOT re-emit "content" or the full phase list — the CLI already holds the full plan, merges your "changed" entries into it, and recomputes the summary. Exact shape for this turn:',
         '',
         compactExample,
         '',
@@ -229,9 +515,53 @@ export async function preparePlanResume(args) {
         '',
         'Only if the plan itself must change structurally (a phase added, removed, or re-sequenced) fall back to the full shape with "content" — the CLI accepts both. The manifest block is how the result is persisted; a turn that ends without it LOSES the phase.',
         '',
+        ...(uiContext.length ? [...uiContext, ''] : []),
         PLAN_RESUME_HARNESS_OVERRIDE,
     ].join('\n');
-    return { path, envelope, statuses, nextPhaseId: next.id, nextDelegateTo: next.delegateTo, llmPrompt };
+    return {
+        path, envelope, statuses,
+        nextPhaseId: next.id,
+        nextDelegateTo: next.delegateTo,
+        // Task 10 — the executing phase's writes declaration for the deviation
+        // backstop (fail-safe: undeclared ⇒ true, backstop never fires).
+        nextPhaseWrites: phaseWrites(next),
+        llmPrompt, mode: flags.mode, effectiveMode,
+        auditFlag: flags.audit, auditMode: effectiveAudit,
+    };
+}
+/**
+ * Pick the plan's dedicated session transport from the phases' recorded work.
+ * All phases share the ONE dedicated transport (Rule 9), so latest-wins — the
+ * last phase in plan order carrying a non-empty `work.transport` — reflects
+ * what the NEXT write will use and settles the rare divergent case. Returns
+ * null when no phase has recorded one yet (the design phase that creates the
+ * transport hasn't run), in which case `tr none` is correct. Pure.
+ */
+export function recordedPlanTransport(phases) {
+    let found = null;
+    for (const p of phases) {
+        const t = p.work?.transport;
+        if (typeof t === 'string' && t.trim().length > 0)
+            found = t;
+    }
+    return found;
+}
+/**
+ * On a plan resume, adopt the envelope's recorded dedicated transport into the
+ * session so the `tr <TRKORR>` status segment shows it (setCurrentTransport
+ * pushes to globalStore.transport, which the statusline reads). No-clobber: an
+ * explicit `/transport` or a `sap_transport_create` earlier THIS session set a
+ * transport already and must win, so adopt ONLY when the session has none.
+ * Null-safe: when the plan has recorded no transport yet, leave the session
+ * untouched (`tr none` is then the honest state). Does not touch
+ * current-transport's setter semantics — it is purely a new caller.
+ */
+export function adoptPlanTransportOnResume(phases) {
+    if (getCurrentTransport() !== null)
+        return; // explicit/session transport wins
+    const recorded = recordedPlanTransport(phases);
+    if (recorded)
+        setCurrentTransport(recorded);
 }
 /**
  * Given a set of candidate file paths (e.g. the matches from an ambiguous
@@ -305,6 +635,11 @@ export async function offerNextPhaseAutoRun(args) {
     if (!args.outcome.nextPhaseId)
         return false;
     const delegate = args.outcome.nextDelegateTo ? ` (${args.outcome.nextDelegateTo})` : '';
+    if (args.gate?.action === 'auto') {
+        args.log(`▶ auto-running next phase ${args.outcome.nextPhaseId}${delegate} — guarded mode: declared non-write phase, prior audit clean.`);
+        args.queueDispatch(args.outcome.resumeCommand);
+        return true;
+    }
     const answer = (await args.prompt(`Run next phase ${args.outcome.nextPhaseId}${delegate} now in a fresh context? [y/N]: `)).trim().toLowerCase();
     if (answer !== 'y' && answer !== 'yes') {
         args.log(`Exiting — resume later with: ${args.outcome.resumeCommand}`);
@@ -386,7 +721,50 @@ export async function finishPlanResume(args) {
         args.log(`[plan] re-run: /abap-plan --resume @${basename(args.prepared.path)}`);
         return null;
     }
-    const revision = buildPlanRevision(args.prepared.envelope, extract, getAuthorIdentity(), new Date().toISOString());
+    const nowIso = new Date().toISOString();
+    const statuses = extract.statuses;
+    const executedId = args.prepared.nextPhaseId;
+    // Task 6 — the provisional next phase is computed BEFORE the pending-audit
+    // injection below (as-if the audit will resolve): the injected 'pending'
+    // makes the executed phase unsatisfied on disk (crash-safety), but the
+    // post-turn messages and the outcome's nextPhaseId describe the happy path;
+    // the post-phase chain (plan-chain.ts) recomputes from the real verdict.
+    const provisionalPhases = extract.content.phases.map((p) => p.id === executedId ? { ...p, audit: undefined } : p);
+    const next = computeNextPhase(provisionalPhases, statuses);
+    // Task 6 — persist the executed phase WITH audit:'pending' in the SAME
+    // revision that records its result. Ordering is the crash-safety design:
+    // a crash between this save and the verdict save leaves 'pending', which
+    // eligibility treats as unsatisfied — resume re-offers the audit, never
+    // skips it. Only success claims are audited: a phase that ended 'blocked'
+    // (or died in progress) claims nothing to verify.
+    //
+    // Audit off-switch (2026-07-06, owner): when auditMode is 'off' we inject NO
+    // pending audit — the phase ends with no audit field, which isPhaseSatisfied
+    // treats as legacy-satisfied. runPostPhaseChain then skips the audit step and
+    // the board renders straight below (no "audit pending…" holdback). This is
+    // the ONLY behavioural change when off; the ON path is byte-identical.
+    const auditEnabled = (args.auditMode ?? 'on') !== 'off';
+    const executedStatus = statuses[executedId];
+    if (auditEnabled && (executedStatus === 'validated' || executedStatus === 'validated-with-waiver')) {
+        const executed = extract.content.phases.find((p) => p.id === executedId);
+        if (executed) {
+            const carried = executed.audit; // prior audit from the merged content
+            executed.audit = {
+                state: 'pending',
+                at: nowIso,
+                ...(args.sessionId ? { sessionId: args.sessionId } : {}),
+                // D-B item 1 — the attempt window for re-audits (fresh-session
+                // re-audit of a multi-attempt JSONL must see only THIS attempt).
+                ...(args.attemptStartedAt ? { attemptStartedAt: args.attemptStartedAt } : {}),
+                // A re-run after a failed audit carries the failure counter through
+                // 'pending' so the NEXT failed verdict counts as consecutive.
+                ...(carried?.state === 'failed' && carried.consecutiveFailures
+                    ? { consecutiveFailures: carried.consecutiveFailures }
+                    : {}),
+            };
+        }
+    }
+    const revision = buildPlanRevision(args.prepared.envelope, extract, getAuthorIdentity(), nowIso);
     // JSON round-trip simulates disk serialization for the validator.
     const check = validateEnvelope(JSON.parse(JSON.stringify(revision)));
     if (!check.ok) {
@@ -402,29 +780,52 @@ export async function finishPlanResume(args) {
         outDir = process.cwd();
     }
     const savedPath = await saveProject(revision, { cwd: outDir });
-    const statuses = extract.statuses;
-    const next = computeNextPhase(extract.content.phases, statuses);
+    // Task 8 — regenerate the write-only markdown handover projection beside
+    // the envelope. Best-effort: a failed projection write logs one dim line
+    // and never blocks the run (the envelope is the source of truth).
+    writePlanHandover(savedPath, args.log);
     args.log('');
     args.log(`Plan updated: ${savedPath}`);
-    args.log('');
-    args.log(renderPlanTracker({
-        title: revision.title,
-        version: revision.version,
-        content: extract.content,
-        statuses,
-        currentId: null,
-    }));
-    args.log('');
-    if (next) {
-        args.log(`Next: ${next.id} (${next.delegateTo}) — run /abap-plan --resume @${basename(savedPath)} in a fresh session.`);
-    }
-    else if (extract.content.phases.every((p) => isPhaseSatisfied(statuses[p.id]))) {
-        // C2 (D24): same chain as preparePlanResume — single source in plan-run.ts.
-        args.log(...planCompletionLines(extract.content.phases));
+    // D-E — DON'T render the progress board / tally / "Next:" line here when an
+    // audit is pending. Doing so used the PROVISIONAL (audit-erased) view, which
+    // counted the just-run phase as done ("2/3") and printed "Next: …" as if the
+    // gate had held — moments before the auditor could FAIL and block it, which
+    // the product owner watched happen. The referee rules first: print only a
+    // neutral one-liner; the post-phase chain (plan-chain.ts) renders the board
+    // with an audit-AWARE tally after the verdict lands (a validated phase with a
+    // pending audit is NOT satisfied, so the honest tally is "1/3", not "2/3").
+    // Off-switch: with no pending injected, there is no verdict to contradict a
+    // board — so an off-run renders the board here exactly like a blocked/no-audit
+    // phase (honest: the phase IS satisfied, no audit is coming).
+    const auditPending = auditEnabled
+        && (executedStatus === 'validated' || executedStatus === 'validated-with-waiver');
+    if (auditPending) {
+        args.log(chalk.dim('Phase result recorded — audit pending…'));
     }
     else {
-        const blocked = extract.content.phases.filter((p) => statuses[p.id] === 'blocked').map((p) => p.id);
-        args.log(`No eligible next phase. Blocked: ${blocked.join(', ')}. Unblock, then resume again.`);
+        // A blocked / no-audit phase claims nothing to verify, so no verdict will
+        // contradict a board here — render it (and the next-step / completion hint).
+        args.log('');
+        args.log(renderPlanTracker({
+            title: revision.title,
+            version: revision.version,
+            content: { ...extract.content, phases: provisionalPhases },
+            statuses,
+            currentId: null,
+            auditsOff: !auditEnabled,
+        }));
+        args.log('');
+        if (next) {
+            args.log(`Next: ${next.id} (${next.delegateTo}) — run /abap-plan --resume @${basename(savedPath)} in a fresh session.`);
+        }
+        else if (provisionalPhases.every((p) => isPhaseSatisfied(statuses[p.id], p.audit))) {
+            // C2 (D24): same chain as preparePlanResume — single source in plan-run.ts.
+            args.log(...planCompletionLines(provisionalPhases));
+        }
+        else {
+            const blocked = provisionalPhases.filter((p) => statuses[p.id] === 'blocked').map((p) => p.id);
+            args.log(`No eligible next phase. Blocked: ${blocked.join(', ')}. Unblock, then resume again.`);
+        }
     }
     return {
         savedPath,
@@ -433,3 +834,157 @@ export async function finishPlanResume(args) {
         nextDelegateTo: next?.delegateTo ?? null,
     };
 }
+/**
+ * Shared revision writer for audit verdicts and chain-stop records: load the
+ * envelope, patch ONE phase (audit and/or status) + content.lastStop,
+ * recompute the summary audit-aware, and save version N+1. Throws on
+ * structural problems (invalid envelope, unknown phase, failed validation) —
+ * callers surface the error; the unresolved on-disk audit state ('pending')
+ * then guarantees a re-audit on the next resume.
+ */
+async function savePlanPatch(envelopePath, phaseId, patch, log) {
+    const envelope = readProjectFile(envelopePath);
+    if (envelope.artefactType !== 'plan') {
+        throw new Error(`expected a plan envelope, got '${envelope.artefactType}'`);
+    }
+    const pc = parsePlanContent(envelope.content);
+    if (!pc.ok) {
+        throw new Error(`plan content failed validation: ${pc.errors.join('; ')}`);
+    }
+    // Deep clone — never mutate the parsed content of the source envelope.
+    const content = JSON.parse(JSON.stringify(pc.content));
+    const phase = content.phases.find((p) => p.id === phaseId);
+    if (!phase) {
+        throw new Error(`phase '${phaseId}' not found in plan envelope '${envelope.title}'`);
+    }
+    if (patch.audit === 'clear')
+        delete phase.audit;
+    else if (patch.audit !== 'keep')
+        phase.audit = patch.audit;
+    const statuses = statusesFromItems(envelope.interaction.items, content.phases);
+    if (patch.status)
+        statuses[phaseId] = patch.status;
+    if (patch.lastStop === 'clear')
+        delete content.lastStop;
+    else if (patch.lastStop)
+        content.lastStop = patch.lastStop;
+    // Recompute the summary audit-aware (same predicates as the DAG).
+    const nextPhase = computeNextPhase(content.phases, statuses);
+    content.summary = {
+        total: content.phases.length,
+        validated: content.phases.filter((p) => isPhaseSatisfied(statuses[p.id], p.audit)).length,
+        blocked: content.phases.filter((p) => statuses[p.id] === 'blocked').length,
+        next: nextPhase?.id ?? null,
+    };
+    const items = content.phases.map((p) => ({
+        id: p.id,
+        status: statuses[p.id],
+        answer: null,
+        answeredBy: null,
+        answeredAt: null,
+        comments: [],
+    }));
+    const revision = buildPlanRevision(envelope, { title: envelope.title, content, items, statuses }, getAuthorIdentity(), new Date().toISOString(), patch.summary);
+    const check = validateEnvelope(JSON.parse(JSON.stringify(revision)));
+    if (!check.ok) {
+        throw new Error(`audit revision failed validation: ${check.error.message}`);
+    }
+    let outDir;
+    try {
+        outDir = await ensureWorkspace();
+    }
+    catch {
+        outDir = dirname(envelopePath);
+    }
+    const saved = await saveProject(revision, { cwd: outDir });
+    // Task 8 — every envelope save in the plan flow regenerates the markdown
+    // handover. This is the single chokepoint for ALL chain writes:
+    // applyAuditResult and applyPhaseResolution both route through here.
+    // Fix-wave (item 4): the caller's log fn is threaded through so the
+    // best-effort failure notice lands in the REPL stream, not bare console.
+    writePlanHandover(saved, log);
+    return saved;
+}
+/**
+ * Persist an audit verdict (or a user waiver) for one phase as revision N+1.
+ * Returns the saved path. Counter semantics (documented choice — dedicated
+ * field over findings-history parsing): 'failed' increments
+ * audit.consecutiveFailures (prior value survives the re-run's 'pending'
+ * state via finishPlanResume's carry-over); 'passed'/'warn'/'waived' clear it
+ * (a warn is NOT a failure — it neither increments nor carries a streak);
+ * 'infra_failed' carries it unchanged (an auditor outage is not a code
+ * verdict and must not break the consecutive count in either direction).
+ */
+export async function applyAuditResult(envelopePath, phaseId, verdict, opts) {
+    const envelope = readProjectFile(envelopePath);
+    const pc = parsePlanContent(envelope.content);
+    const prior = pc.ok
+        ? pc.content.phases.find((p) => p.id === phaseId)?.audit
+        : undefined;
+    const audit = { state: verdict.state, at: new Date().toISOString() };
+    if (verdict.findings && verdict.findings.length > 0)
+        audit.findings = verdict.findings;
+    if (verdict.state === 'waived') {
+        audit.waivedReason = verdict.waivedReason ?? 'waived by user';
+        // §10 Q2 — EVERY waive lands a category so the FP-rate query has a complete
+        // denominator. Conservative default: a waive with no explicit category
+        // (headless, off-switch bulk-waive, legacy caller) is 'accepted-risk',
+        // never a 'false-positive' the human didn't assert.
+        audit.waiveCategory = verdict.waiveCategory ?? 'accepted-risk';
+    }
+    if (prior?.sessionId)
+        audit.sessionId = prior.sessionId;
+    // D-B item 1 — carry the attempt window alongside the evidence pointer: a
+    // died-at-menu 'failed' (or an interleaved infra_failed) is re-audited
+    // against the SAME attempt, so its window must survive the verdict write.
+    if (prior?.attemptStartedAt)
+        audit.attemptStartedAt = prior.attemptStartedAt;
+    if (verdict.state === 'failed') {
+        // Fix-wave (item 10a): a re-confirmed failure (re-audit of an already-
+        // 'failed' phase after a menu-death resume) holds the counter — the
+        // phase never re-ran, so this is the SAME failure re-judged, not a new
+        // consecutive one. Floor 1: a failed verdict always counts at least once.
+        audit.consecutiveFailures = opts?.reconfirmedFailure
+            ? Math.max(prior?.consecutiveFailures ?? 0, 1)
+            : (prior?.consecutiveFailures ?? 0) + 1;
+    }
+    else if (verdict.state === 'infra_failed' && prior?.consecutiveFailures) {
+        audit.consecutiveFailures = prior.consecutiveFailures;
+    }
+    const findingsNote = audit.findings?.length
+        ? ` (${audit.findings.length} finding${audit.findings.length === 1 ? '' : 's'})`
+        : '';
+    const statusNote = opts?.statusOverride ? `; status → ${opts.statusOverride}` : '';
+    // Review M-5: a RESOLVED verdict means the chain continues — any recorded
+    // stop (audit-failed from the earlier verdict, audit-infra from an outage, a
+    // write-phase consent) no longer describes an outstanding stop, so clear it
+    // instead of leaving a stale record. 'warn' is non-blocking, so it clears a
+    // stale stop exactly like a pass. 'infra_failed' (audit-infra-continue,
+    // 2026-07-09) is also non-blocking now — the audit could not run but the
+    // chain continues, so it too clears any stale stop.
+    const lastStop = opts?.lastStop
+        ?? (audit.state === 'passed' || audit.state === 'waived'
+            || audit.state === 'warn' || audit.state === 'infra_failed'
+            ? 'clear'
+            : undefined);
+    return savePlanPatch(envelopePath, phaseId, {
+        audit,
+        status: opts?.statusOverride,
+        lastStop,
+        summary: `audit ${phaseId}: ${audit.state}${findingsNote}${statusNote}`,
+    }, opts?.log);
+}
+/**
+ * Persist a chain resolution that does NOT change the audit verdict: the
+ * user chose re-run (status → 'todo'; the failed audit + counter stay so the
+ * next verdict counts as consecutive), chose Mark blocked, or a guarded stop
+ * needs its lastStop recorded. Returns the saved path.
+ */
+export async function applyPhaseResolution(envelopePath, phaseId, opts) {
+    return savePlanPatch(envelopePath, phaseId, {
+        audit: opts.clearAudit ? 'clear' : 'keep',
+        status: opts.status,
+        lastStop: opts.lastStop,
+        summary: opts.summary,
+    }, opts.log);
+}