@cspeach/cli 0.9.0 → 1.1.0

package/dist/skills/promotion-dispatch.js

@@ -1,3 +1,5 @@
+import { basename } from 'node:path';
+import { isAttachableFilename } from '../projects/workspace.js';
 /**
  * Parse `--from @<path>` from a slash-command argument string. The leading `@`
  * is the file-attach convention used elsewhere in the CLI; supports
@@ -22,3 +24,24 @@ export function parseFromFlag(args) {
     const rest = (before + after).replace(/^\s+|\s+$/g, '');
     return { fromPath, rest };
 }
+/**
+ * Forgiveness for the common `--from @<document>` slip.
+ *
+ * `--from` chains a saved `.cspeach.json` envelope into a downstream skill, but
+ * users naturally type it to point at a Word/PDF/text spec ("use this file") —
+ * which used to error with a cryptic "unknown target skill" and cancel the
+ * whole turn. A document is NEVER a valid `--from` source, so when the token is
+ * an attachable doc/text file we silently rewrite `--from @<file>` to a plain
+ * `@<file>` attachment (handled by expandTextFileAttachments) and let the turn
+ * proceed.
+ *
+ * Returns the rewritten message + filename, or null when `--from` should run
+ * normally (no flag, or the token is a bare envelope fragment / *.cspeach.json).
+ */
+export function coerceDocFromFlagToAttachment(message) {
+    const { fromPath } = parseFromFlag(message);
+    if (!fromPath || !isAttachableFilename(fromPath))
+        return null;
+    const rewritten = message.replace(/--from\s+(@(?:"[^"]+"|\S+))/, '$1');
+    return { rewritten, filename: basename(fromPath) };
+}

package/dist/tools/_command-shared.js

@@ -52,23 +52,47 @@ export async function loadSafelist() {
         return new Set(DEFAULT_SAFELIST);
     }
 }
+/**
+ * Build the ordered list of filename extensions to probe for a given
+ * platform. On Windows, PATHEXT extensions (.EXE, .CMD, .BAT, ...) come
+ * BEFORE the bare name — npm drops an extensionless Unix shim next to
+ * `pnpm.cmd` (e.g. ...\npm\pnpm) that is NOT spawnable with shell:false,
+ * so preferring the real .cmd/.exe makes the existence check report a
+ * launchable binary. On Unix, only the bare name (shebang scripts and
+ * ELF binaries spawn directly).
+ *
+ * Exported for tests so the ordering invariant can be asserted without
+ * touching the filesystem.
+ */
+export function executableExtensions(platform, pathextRaw) {
+    if (platform === 'win32') {
+        const pathext = (pathextRaw ?? '.COM;.EXE;.BAT;.CMD')
+            .toLowerCase()
+            .split(';')
+            .filter((e) => e.length > 0);
+        // PATHEXT extensions FIRST, bare name LAST. The bare name still gets
+        // probed (commands that ship only an extensionless binary remain
+        // findable) but loses to a co-located .exe/.cmd.
+        return [...pathext, ''];
+    }
+    return [''];
+}
 /**
  * Resolve a bare command name to an absolute executable path by walking
- * PATH. Tries the bare name + PATHEXT extensions on Windows. Returns
- * null if nothing matches anywhere on PATH. Identical to Chunk 3B's
- * inlined function — extracted verbatim.
+ * PATH. Tries PATHEXT extensions before the bare name on Windows. Returns
+ * null if nothing matches anywhere on PATH.
+ *
+ * This is used ONLY as a pre-flight "is it installed?" existence check so
+ * the tool can return a friendly "not installed" error. The ACTUAL spawn
+ * goes through cross-spawn with the bare command name — cross-spawn does
+ * its own PATH + PATHEXT resolution and invokes .cmd via cmd.exe with
+ * correct per-arg escaping (which Node's spawn(shell:false) refuses to do
+ * since CVE-2024-27980). `platform`/`pathext` overridable for tests.
  */
-export async function resolveExecutable(name) {
+export async function resolveExecutable(name, platform = process.platform, pathext = process.env.PATHEXT) {
     const PATH = process.env.PATH ?? process.env.Path ?? '';
     const dirs = PATH.split(path.delimiter).filter((d) => d.length > 0);
-    let extensions;
-    if (process.platform === 'win32') {
-        const pathext = (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').toLowerCase().split(';');
-        extensions = ['', ...pathext];
-    }
-    else {
-        extensions = [''];
-    }
+    const extensions = executableExtensions(platform, pathext);
     for (const dir of dirs) {
         for (const ext of extensions) {
             const candidate = path.join(dir, name + ext);

package/dist/tools/_filesystem-shared.js

@@ -9,11 +9,125 @@
  */
 import * as path from 'node:path';
 import { promises as fsPromises } from 'node:fs';
-/** Phase 3 sensitive in-root paths — refused by all filesystem tools. */
-export const BLOCKED_PREFIXES = ['.cspeach', '.env', '.git', '.cspeach-design'];
 /**
- * True if `realAbsPath` falls under one of BLOCKED_PREFIXES relative to root.
- * Caller should refuse the operation when `blocked` is true.
+ * Phase 3 sensitive in-root directory prefixes — refused by all filesystem
+ * tools. Matched as `rel === prefix` or `rel` starts with `prefix + '/'`.
+ *
+ * NOTE: the `.env` family is handled separately (by BASENAME, see
+ * BLOCKED_BASENAME_RE) so that `.env.local`, `.env.production`, etc. — the
+ * files that actually hold secrets in JS projects — are caught too. It is
+ * NOT in this list.
+ */
+export const BLOCKED_PREFIXES = ['.cspeach', '.git', '.cspeach-design'];
+/**
+ * Skill working subdirectories under `.cspeach/` that are CARVED OUT of the
+ * denylist so the upgrade/cca/modernize/test skills can read AND write their
+ * own detail files (e.g. `.cspeach/upgrades/ZTEST_..._.json`). The namespace
+ * cleanup that moved working files from `.abapforge/<domain>/` to
+ * `.cspeach/<domain>/` would otherwise be defeated by the `.cspeach` prefix
+ * block. See the carve-out in isDenylistedPath for the exact predicate.
+ */
+export const CSPEACH_WORK_SUBDIRS = ['cca', 'upgrades', 'modernize', 'tests'];
+/**
+ * Phase 3 sensitive BASENAMES — refused regardless of directory depth.
+ *
+ * Matches `.env` exactly or `.env.<suffix>` (e.g. `.env.local`,
+ * `.env.production`, `.env.development`, `.env.test`). The `(\.|$)` boundary
+ * means `.environment` / `.envrc` are NOT caught — only the real dotenv
+ * family. Case-insensitive (NTFS/APFS resolve `.ENV` to the same inode).
+ */
+export const BLOCKED_BASENAME_RE = /^\.env(\.|$)/i;
+/**
+ * Human-readable summary of the denylist for error messages.
+ * Note: `.cspeach/{cca,upgrades,modernize,tests}/` working files are permitted
+ * (skill detail files) — only the rest of `.cspeach/` is blocked.
+ */
+export const DENYLIST_DESCRIPTION = [...BLOCKED_PREFIXES, '.env*'].join(', ');
+/**
+ * Executable / script file extensions the filesystem write tools refuse to
+ * create. Defense-in-depth: shell_exec / background_run only run a safelisted
+ * set of commands, but cross-spawn resolves bare names cwd-first on Windows.
+ * If the model could write `<safelisted>.cmd` (e.g. git.cmd) into the project
+ * tree it could shadow a real PATH binary. Spawning the absolute PATH-resolved
+ * path already neutralizes that at the spawn site; this denylist independently
+ * stops the executable shim from ever being planted in the first place — see
+ * blockedExecutableExtension, which normalizes Windows filename quirks (trailing
+ * dots/spaces, alternate data streams) so a name like `git.cmd ` or `git.cmd::$DATA`
+ * cannot slip a real `git.cmd` onto disk past the extension check.
+ *
+ * Legitimate project scaffolding (Fiori writes .js/.json/.xml/.properties/
+ * .yaml/.ts) never needs these, so the block does not impede normal work.
+ *
+ * Case-insensitive — NTFS/APFS resolve `.CMD` to the same file as `.cmd`.
+ */
+export const BLOCKED_EXECUTABLE_EXTS = new Set([
+    '.cmd', '.bat', '.com', '.exe', '.ps1', '.sh', '.msi', '.scr',
+]);
+/** Human-readable summary of the executable-extension block for error messages. */
+export const EXECUTABLE_EXT_DESCRIPTION = [...BLOCKED_EXECUTABLE_EXTS].join(', ');
+/** Sentinel ext returned when the basename carries a `:` (ADS / drive-relative). */
+const BLOCKED_STREAM_SENTINEL = ':stream';
+/**
+ * Normalize a Windows basename the way the filesystem does on access:
+ *   - strip ALL trailing dots and spaces (`git.cmd `, `git.cmd.`, `git.cmd...`
+ *     all open the file `git.cmd`).
+ * Returns the normalized basename. A name that is entirely dots/spaces
+ * collapses to '' (which extname() then reports as no extension — safe).
+ */
+function normalizeWindowsBasename(base) {
+    return base.replace(/[. ]+$/, '');
+}
+/**
+ * Returns the offending extension (lowercased, with leading dot) if `targetPath`
+ * names a file the write tools must refuse, else null. Used by file_write /
+ * file_edit to refuse planting an executable shim.
+ *
+ * Accepts a full path or a bare basename (both call sites pass a resolved
+ * absolute path; the directory part is irrelevant — only the basename decides).
+ *
+ * Two pre-extname normalizations close Windows filename-normalization bypasses
+ * that would otherwise land an executable-named file on disk while slipping
+ * past a naive `path.extname` check:
+ *
+ *   1. Trailing dots/spaces — Windows strips these on access, so `git.cmd `
+ *      and `git.cmd.` / `git.cmd...` all resolve to `git.cmd`. We strip them
+ *      from the basename before taking the extension.
+ *
+ *   2. A `:` anywhere in the basename — alternate data stream (`git.cmd:foo`,
+ *      `git.cmd::$DATA`) or drive-relative path. Either way the on-disk file
+ *      is executable-named; reject outright. (A drive letter's `:` lives in
+ *      the DIRECTORY part — e.g. basename of `C:\proj\foo.js` is `foo.js` —
+ *      so legit absolute paths never false-positive here.)
+ */
+export function blockedExecutableExtension(targetPath) {
+    const rawBase = path.basename(targetPath);
+    // (2) Alternate data stream / drive-relative — the basename must never carry ':'.
+    if (rawBase.includes(':'))
+        return BLOCKED_STREAM_SENTINEL;
+    // (1) Strip trailing dots/spaces the way Windows does on access, THEN take ext.
+    const base = normalizeWindowsBasename(rawBase);
+    const ext = path.extname(base).toLowerCase();
+    return BLOCKED_EXECUTABLE_EXTS.has(ext) ? ext : null;
+}
+/**
+ * True if `realAbsPath` is denylisted relative to root — either it falls under
+ * one of BLOCKED_PREFIXES (directory prefixes) or its basename is in the
+ * `.env` family. Caller should refuse the operation when `blocked` is true.
+ *
+ * CARVE-OUT — the four skill working subdirectories under `.cspeach/`
+ * (CSPEACH_WORK_SUBDIRS = cca/upgrades/modernize/tests) are ALLOWED so skills
+ * can read+write their own detail files. A path is carved out (NOT blocked)
+ * iff ALL hold:
+ *   1. its root-relative path (lowercased, '/'-separated) starts with
+ *      `.cspeach/<sub>/` for some <sub> in CSPEACH_WORK_SUBDIRS — i.e. it is
+ *      STRICTLY INSIDE one of those subdirs (the subdir entry itself is not
+ *      carved out), AND
+ *   2. its basename does NOT end with `.cspeach.json` (those envelopes are
+ *      CLI-owned — direct writes stay blocked), AND
+ *   3. its basename is NOT in the `.env` secret family (BLOCKED_BASENAME_RE).
+ * The carve-out short-circuits ONLY the `.cspeach` prefix. `.git`,
+ * `.cspeach-design`, the `.cspeach` root, non-work subdirs, and `.env*`
+ * everywhere else remain blocked.
  */
 export function isDenylistedPath(realAbsPath, root) {
     const relFromRoot = path.relative(path.resolve(root), realAbsPath).replace(/\\/g, '/');
@@ -24,12 +138,33 @@ export function isDenylistedPath(realAbsPath, root) {
     // `relFromRoot` keeps its ORIGINAL case so callers can log what the model
     // actually requested.
     const relLower = relFromRoot.toLowerCase();
+    const base = path.basename(relFromRoot);
+    const baseLower = base.toLowerCase();
+    // ── CARVE-OUT: .cspeach/<work-subdir>/… — short-circuits ONLY .cspeach. ──
+    // Must be strictly INSIDE a work subdir, not a CLI-owned envelope, and not
+    // an .env secret. Placed before the prefix loop so it can return early, but
+    // gated so it can never bypass .git / .cspeach-design / the .env block.
+    for (const sub of CSPEACH_WORK_SUBDIRS) {
+        if (relLower.startsWith('.cspeach/' + sub + '/')) {
+            if (!baseLower.endsWith('.cspeach.json') && !BLOCKED_BASENAME_RE.test(base)) {
+                return { blocked: false, relFromRoot };
+            }
+            break; // inside a work subdir but failed an exclusion → fall through to block
+        }
+    }
+    // Directory-prefix denylist (.cspeach, .git, .cspeach-design).
     for (const prefix of BLOCKED_PREFIXES) {
         const prefixLower = prefix.toLowerCase();
         if (relLower === prefixLower || relLower.startsWith(prefixLower + '/')) {
             return { blocked: true, relFromRoot };
         }
     }
+    // Basename denylist — the .env family at ANY depth (.env, .env.local, …).
+    // Using the basename (not a prefix) is what catches `.env.production` while
+    // still excluding `.environment-notes.md` and `.envrc`.
+    if (BLOCKED_BASENAME_RE.test(base)) {
+        return { blocked: true, relFromRoot };
+    }
     return { blocked: false, relFromRoot };
 }
 export class PathOutsideRootError extends Error {

package/dist/tools/_flag.js

@@ -15,7 +15,32 @@
 export const TOOL_FLAG_PREFIX = 'CSPEACH_TOOL_';
 /** One-shot per process — set of flag-names we've already warned about. */
 const warnedFlags = new Set();
+/**
+ * In-memory force-enable set, mirroring renderer/tty.ts's headless-override
+ * pattern: consulted BEFORE env detection. A startup hook (REPL + one-shot)
+ * calls `enableToolFlags([...])` when the persisted `local_files` config key
+ * is true, so the flag-gated filesystem tools become visible to listTools()
+ * without the user exporting CSPEACH_TOOL_* env vars.
+ *
+ * Stored by lowercase tool name (the same name listTools()/registerTool use),
+ * so `enableToolFlags(['file_read'])` and `isToolFlagOn('FILE_READ')` agree.
+ */
+const overrideEnabled = new Set();
+/** Force-enable the named tools' flags for this process (override beats env). */
+export function enableToolFlags(toolNames) {
+    for (const name of toolNames)
+        overrideEnabled.add(name.toLowerCase());
+}
+/** Clear all in-memory flag overrides. Test-resettable; safe at runtime too. */
+export function clearToolFlagOverrides() {
+    overrideEnabled.clear();
+}
 export function isToolFlagOn(toolName) {
+    // Override wins: a startup-applied force-enable makes the tool visible
+    // regardless of env. The env path below still runs for un-overridden tools,
+    // preserving the CSPEACH_TOOL_<NAME>=on dogfood mechanism + misconfig warn.
+    if (overrideEnabled.has(toolName.toLowerCase()))
+        return true;
     const flag = `${TOOL_FLAG_PREFIX}${toolName.toUpperCase()}`;
     const raw = process.env[flag];
     if (raw === undefined)

package/dist/tools/approval.js

@@ -1,12 +1,19 @@
+import chalk from 'chalk';
 import { registerTool } from './index.js';
+import { isHeadless } from '../renderer/tty.js';
 import { effectiveRisk } from '../approvals/risk-floor.js';
-import { mintApprovalId } from '../approvals/jwt.js';
+import { mintChangeApproval } from '../approvals/jwt.js';
+import { canonicalApprovalObject } from '../approvals/canonical.js';
 import { renderPlanGate, renderPerChangeApprovalV3 } from '../approvals/render.js';
 import { loadConfig } from '../config/loader.js';
 import { maybeShowAutoApproveNag } from '../approvals/approval-prompt.js';
 import { renderAdvisoryProposal, } from '../approvals/advisory-render.js';
 import { promptAdvisory } from '../approvals/advisory-prompt.js';
 import { markPlanGateApproved } from '../repl/rule8-detector.js';
+import { getEffectiveWriteMode } from '../repl/mode-cycle.js';
+import { getCurrentTransport } from '../repl/current-transport.js';
+import { displayTransport } from '../approvals/op-labels.js';
+import { isGuardedRunActive, getCurrentPhaseWrites, notePlanDeviation, PLAN_DEVIATION_DETAIL, } from '../commands/plan-gate.js';
 /**
  * Advisory-only replacement for the per-change approval gauntlet.
  *
@@ -20,6 +27,22 @@ import { markPlanGateApproved } from '../repl/rule8-detector.js';
  */
 export async function handleAdvisoryApproval(args, _ctx) {
     const render = renderAdvisoryProposal(args);
+    // B5 (2026-06-11) — headless: the advisory prompt blocks on stdin that
+    // will never answer. Render the proposal (it IS the run's deliverable —
+    // the developer reads the captured output and applies manually), skip
+    // the prompt, and report a headless-specific directive. NEVER 'applied':
+    // nobody confirmed anything.
+    if (isHeadless()) {
+        console.log(render.displayText);
+        console.error(chalk.dim('headless: advisory proposal recorded in output — no prompt, developer applies manually'));
+        return {
+            content: JSON.stringify({
+                advisory_outcome: 'skipped',
+                headless: true,
+                ai_directive: 'Advisory mode (headless run): the proposal has been rendered into the run output for the developer to review and apply manually later. Nobody confirmed it. Do not attempt any write operations. Summarise what you proposed and continue.',
+            }),
+        };
+    }
     const outcome = await promptAdvisory({
         displayText: render.displayText,
         clipboardText: render.clipboardText,
@@ -46,6 +69,42 @@ export async function handleAdvisoryApproval(args, _ctx) {
         }),
     };
 }
+/**
+ * §6 escalation exception — the infra base-object TYPE CODES a no-write/design
+ * phase (writes:false) may self-create under abap-plan rule 4a. These are the
+ * ADT type codes the model puts in `request_approval` `changes[].type`:
+ *   - DEVC — package   (sap_create_object type DEVC)
+ *   - CTS  — transport (sap_transport_create surfaces as {op:'create',type:'CTS'})
+ *
+ * §6's third member — number range — is intentionally ABSENT: the
+ * sap_number_range_intervals tool is a STUB (registered as "do not call", no
+ * ADT write), so a number-range op never reaches request_approval. Adding a
+ * marker for it would be dead code. Add its type code here if/when that tool
+ * ships and starts flowing through the approval gate.
+ *
+ * DUPLICATION NOTE (deliberate, for a follow-up): the AUDIT side enforces the
+ * SAME set in plan-audit.ts (PLAN_AUDIT_PROMPT_CONTRACT §6) — but as PROSE in
+ * an LLM prompt ("DEVC (package), transport, or number range"), not code. There
+ * is no clean seam to share a predicate because one enforcement layer is a
+ * natural-language contract and the other is TypeScript. The two must be kept
+ * in sync by hand; this comment and the audit prose both name the same set.
+ */
+const INFRA_BASE_OBJECT_TYPES = new Set(['DEVC', 'CTS']);
+/**
+ * TRUE iff EVERY change is a pure infra base-object CREATE — the sanctioned 4a
+ * self-create escalation (§6/§7.2). Tightness is the safety property: a single
+ * non-infra change (a CLAS/DDLS/… deliverable), any non-create op, or an empty
+ * set makes this FALSE, so the writes:false backstop denies it (the correct
+ * out-of-lane B3 case). Type is normalized (trim + upper) to match how the
+ * model may spell it; op is restricted to 'create' because 4a sanctions
+ * self-CREATE only (a transport release / package delete is not an escalation).
+ */
+function isPureInfraEscalation(changes) {
+    return (!!changes &&
+        changes.length > 0 &&
+        changes.every((c) => c.op === 'create' &&
+            INFRA_BASE_OBJECT_TYPES.has((c.type ?? '').trim().toUpperCase())));
+}
 registerTool({
     name: 'request_approval',
     description: 'Request user approval for one or more SAP mutations. Returns approval_ids (one per change) to be passed as approval_id on matching mutating tool calls.',
@@ -64,7 +123,8 @@ registerTool({
                         op: { type: 'string', enum: ['create', 'modify', 'delete', 'activate', 'release'] },
                         object: { type: 'string' },
                         type: { type: 'string' },
-                        diff: { type: 'string', description: 'Unified diff for modify/create ops (optional)' },
+                        diff: { type: 'string', description: 'For a CREATE op this MUST be the exact, complete source that will be written — verbatim, character-for-character, NOT a description, summary, or paraphrase. It is shown to the developer in the approval box as the exact thing they are approving, so a one-line summary here means they approve a write they cannot inspect. For a MODIFY op, the real unified diff of the change (again verbatim, not a description).' },
+                        package: { type: 'string', description: 'Target package (development class) for the object, if known — shown on the approval box' },
                     },
                     required: ['op', 'object', 'type'],
                 },
@@ -73,11 +133,52 @@ registerTool({
         required: ['summary', 'risk', 'changes'],
     },
     handler: async (args, ctx) => {
+        // Task 10 (agentic-flow, 2026-07-03) — deviation backstop, BEFORE the
+        // approval flow renders anything (including the advisory prompt, which
+        // would hang an unattended chain just the same). In guarded mode the
+        // write-phase stops are computed from the plan's DECLARED writes field;
+        // a phase that declared writes:false and requests a write approval
+        // anyway is a plan deviation: DENY without prompting, raise the flag
+        // the post-turn chain (plan-chain.ts) turns into blocked + STOPPED.
+        // Same error mechanism as the headless fail-fast below: a structured
+        // error RESULT so the model wraps up gracefully instead of writing.
+        // Guarded-gated: step mode / outside phases are byte-identical.
+        //
+        // §6/§7.2 escalation exception (audit redesign, Task 4): a PURE infra
+        // base-object create (DEVC / transport) under writes:false is the
+        // sanctioned rule-4a self-create. The very act of routing through
+        // request_approval IS the user-consent gate, so it must NOT be denied here
+        // — fall through to the normal approval flow (which prompts the user, whose
+        // approval is the 4a consent). Guarded-mode clients could otherwise never
+        // run 4a: this backstop blocks it BEFORE the audit even runs. TIGHT: the
+        // exception fires only when EVERY change is infra; a deliverable
+        // (CLAS/DDLS/…) or a mixed set still denies (correct out-of-lane B3).
+        if (isGuardedRunActive() &&
+            getCurrentPhaseWrites() === false &&
+            !isPureInfraEscalation(args.changes)) {
+            const detail = PLAN_DEVIATION_DETAIL;
+            notePlanDeviation(detail);
+            console.error(chalk.red('plan deviation: this phase declared writes:false but requested a write approval — ' +
+                'the write is denied and the guarded chain will stop.'));
+            return {
+                content: JSON.stringify({
+                    error: 'plan_deviation',
+                    detail,
+                }),
+                is_error: true,
+            };
+        }
         let cfg = await loadConfig();
+        // Task 2 (ux-wave1) — the approval flow reads the EFFECTIVE write mode:
+        // config overlaid by the session override, clamped to the active alias's
+        // role ceiling (prd pins advisory-only; qas caps at approval-gated). With
+        // no role configured and no session override this is exactly
+        // cfg.write_mode — byte-identical behavior.
+        const role = cfg.sap[ctx.sapAlias]?.role;
         // Advisory-only short-circuit — never mint approval_ids.
         // The developer applies the change manually in ADT; the AI gets an
         // ai_directive telling it not to attempt any SAP write tools.
-        if (cfg.write_mode === 'advisory-only') {
+        if (getEffectiveWriteMode(cfg.write_mode, role) === 'advisory-only') {
             return handleAdvisoryApproval(args, { sapAlias: ctx.sapAlias });
         }
         let sapCfg = cfg.sap[ctx.sapAlias];
@@ -88,24 +189,51 @@ registerTool({
         const changes = args.changes;
         const declared = args.risk;
         const eff = effectiveRisk(declared, changes, riskCtx);
-        // Progressive-disclosure: offer to upgrade never→low on first low-risk encounter.
-        await maybeShowAutoApproveNag({ sapAlias: ctx.sapAlias, effectiveRisk: eff.level });
-        // Refresh cfg so this approval benefits from a just-enabled auto_approve.
-        cfg = await loadConfig();
-        sapCfg = cfg.sap[ctx.sapAlias];
-        riskCtx.autoApprovePolicy = sapCfg?.auto_approve ?? 'never';
+        // Transport shown on the approval surfaces — resolved PER OP to mirror
+        // what the write tools will actually do (I2, 2026-07-05 review):
+        // create-family tools fall back to the session transport, so the box may
+        // show it; modify/delete tools do NOT (resolveWriteTransport uses args
+        // only + owning-TR override), so those boxes show only an explicit
+        // request transport; activate/release take no transport at all. See
+        // displayTransport in approvals/op-labels.ts. The plan gate is a batch
+        // summary: session fallback applies only when the batch contains a
+        // create (the only op it is true for).
+        const sessionTransport = getCurrentTransport();
+        const planGateTransport = args.transport
+            ?? (changes.some((c) => c.op === 'create') ? sessionTransport ?? undefined : undefined);
+        // Task 6 (agentic-flow, 2026-07-03) — guarded plan chains disable
+        // auto-approve entirely: the user's auto_approve consent was given for
+        // hand-driven turns, not for phases the harness auto-dispatched. When the
+        // flag is active, skip the nag (it only advertises auto-approve) and fall
+        // through to the interactive prompts below. Flag off ⇒ this whole block
+        // is a no-op and behaviour stays byte-identical (skill-mode compat).
+        const guardedRun = isGuardedRunActive();
+        // Task 3 (ux-wave1) — qas systems never auto-approve: the role's promise
+        // is "no unattended writes", and a pre-configured auto_approve would mint
+        // silently. Treat auto_approve as 'never' on a qas alias — composes with
+        // the guarded-run skip above, same skip points, ladder order unchanged.
+        // (prd needs nothing here: the advisory clamp already prevents minting.)
+        const qasNoAutoApprove = role === 'qas';
+        // Progressive-disclosure: offer to upgrade never→low on first low-risk
+        // encounter. B5: skipped in headless — the nag's raw-mode keypress wait
+        // would hang on piped/closed stdin just like any other prompt. Skipped on
+        // qas too: the nag only advertises auto-approve, which qas disables.
+        if (!isHeadless() && !guardedRun && !qasNoAutoApprove) {
+            await maybeShowAutoApproveNag({ sapAlias: ctx.sapAlias, effectiveRisk: eff.level });
+            // Refresh cfg so this approval benefits from a just-enabled auto_approve.
+            cfg = await loadConfig();
+            sapCfg = cfg.sap[ctx.sapAlias];
+            riskCtx.autoApprovePolicy = sapCfg?.auto_approve ?? 'never';
+        }
         // Auto-approve caps — never auto-approve at high, cap change count per risk level.
-        const autoApproveAllowed = ((sapCfg?.auto_approve === 'low' && eff.level === 'low' && changes.length <= 5) ||
+        const autoApproveAllowed = !guardedRun && !qasNoAutoApprove && ((sapCfg?.auto_approve === 'low' && eff.level === 'low' && changes.length <= 5) ||
             (sapCfg?.auto_approve === 'medium' && (eff.level === 'low' || eff.level === 'medium') && changes.length <= 2));
         if (autoApproveAllowed) {
             const ids = [];
             for (const c of changes) {
-                ids.push(await mintApprovalId({
-                    object: c.object,
-                    type: c.type,
-                    op: c.op,
-                    session_id: ctx.session.id,
-                }));
+                // Task A3: mint via the canonical path — the JWT stores the same
+                // object string the write tools' validators will compare against.
+                ids.push(await mintChangeApproval(c, ctx.session.id));
             }
             // Tell Rule 8 the user has already covered this batch — they
             // configured auto-approve, so no per-dispatch re-prompts.
@@ -120,6 +248,29 @@ registerTool({
                 }),
             };
         }
+        // B5 (2026-06-11) — headless fail-fast. Everything below this point
+        // prompts on stdin (plan gate, per-change approvals) and would hang a
+        // headless run forever. The headless policy NEVER auto-approves writes:
+        // the only non-interactive approval path is the user's own pre-configured
+        // auto_approve (handled above — it asks nothing). Return an error RESULT
+        // so the model can wrap up gracefully instead of the process hanging.
+        if (isHeadless()) {
+            console.error(chalk.red('headless: approval requested but headless runs cannot approve writes — ' +
+                'use advisory mode (write_mode = "advisory-only") or run interactively.'));
+            return {
+                content: JSON.stringify({
+                    approved: false,
+                    headless: true,
+                    reason: 'headless_no_approval',
+                    message: 'Headless run: writes cannot be approved without a user at the terminal, and headless runs never auto-approve. ' +
+                        'No approval IDs were minted — do not attempt any write operations. ' +
+                        'Summarise the proposed changes so the user can re-run interactively or switch write_mode to "advisory-only".',
+                    effective_risk: eff.level,
+                    raised_by: eff.raisedBy,
+                }),
+                is_error: true,
+            };
+        }
         // Plan-gate: for multi-change requests, ask once whether to apply all,
         // review each, or cancel. Apply-all is the default and the happy path —
         // it skips the redundant per-change prompts that produced the "3 prompts
@@ -127,7 +278,7 @@ registerTool({
         // gate. Cancel rejects the whole plan.
         let skipPerChangeGates = false;
         if (changes.length > 1) {
-            const mode = await renderPlanGate(args.summary, changes, args.transport, eff);
+            const mode = await renderPlanGate(args.summary, changes, planGateTransport, eff);
             if (mode === 'cancel') {
                 return {
                     content: JSON.stringify({
@@ -159,13 +310,16 @@ registerTool({
         const rejections = [];
         const autoApproveActivateFor = new Set();
         const autoSkipActivateFor = new Set();
+        // Sibling matching keys are canonicalized (Task A3) so a decorated modify
+        // row ("ZBP_FOO (testclasses include)") still pairs with its bare-named
+        // activate sibling ("ZBP_FOO").
         const writeKeys = new Set();
         for (const c of changes) {
             if (c.op === 'modify' || c.op === 'create')
-                writeKeys.add(`${c.type}:${c.object}`);
+                writeKeys.add(`${c.type}:${canonicalApprovalObject(c.object)}`);
         }
         for (const c of changes) {
-            const objKey = `${c.type}:${c.object}`;
+            const objKey = `${c.type}:${canonicalApprovalObject(c.object)}`;
             let outcome;
             if (skipPerChangeGates) {
                 outcome = { approved: true };
@@ -177,17 +331,14 @@ registerTool({
                 outcome = { approved: false, reason: 'sibling_write_skipped' };
             }
             else {
-                outcome = await renderPerChangeApprovalV3(c, eff, args.transport);
+                outcome = await renderPerChangeApprovalV3(c, eff, displayTransport(c.op, args.transport, sessionTransport));
             }
             if (outcome.approved) {
                 if (c.op === 'modify' || c.op === 'create')
                     autoApproveActivateFor.add(objKey);
-                approvalIds.push(await mintApprovalId({
-                    object: c.object,
-                    type: c.type,
-                    op: c.op,
-                    session_id: ctx.session.id,
-                }));
+                // Task A3: mint via the canonical path (same code path the write
+                // tools' validators compare against).
+                approvalIds.push(await mintChangeApproval(c, ctx.session.id));
             }
             else {
                 if (outcome.reason === '__cancel_turn__') {