@deftai/directive-core 0.100.0 → 0.102.0

package/dist/authz/classify.js

@@ -204,11 +204,52 @@ const DOWNLOADER_DECODER_BINS = new Set([
     "fetch",
     "socat",
     "lftp",
+    // #3288 residual after #3245: crypto / alt-download / pipe / archive bins.
+    "gpg",
+    "age",
+    "zstd",
+    "unzstd",
+    "sftp",
+    "wget2",
+    "http",
+    "https",
+    "yt-dlp",
+    "ytdlp",
+    "aria2",
+    "mbuffer",
+    "cpio",
+    // #3311 residual after #3288: versioned / alternate write bins.
+    "gpg2",
+    "gpg1",
+    "rage",
+    "xh",
+    "httpie",
+    "wcurl",
+    "curlie",
+    "uudecode",
+    "iconv",
+    "gtar",
+    "star",
+    "gnutar",
+    "pax",
+    // #3336 residual after #3311: further write bins (oras/ncat/patch peers).
+    "oras",
+    "lwp-download",
+    "ncat",
+    "patch",
+    "base32",
+    "lrzip",
+    "unar",
+    "cabextract",
+    "ditto",
+    "dpkg-deb",
+    "hg",
+    "msguniq",
 ]);
 /**
  * Archive extractors / alt writers that can plant via pathish operands without
- * shell redirects (#3245). Used for pathish authz/kill scans (prefer deny) and
- * write-shape residual under UAT — not bare curl-class URL fetches.
+ * shell redirects (#3245 / #3288 / #3311 / #3336). Used for pathish authz/kill scans (prefer deny)
+ * and write-shape residual under UAT — not bare curl-class URL fetches.
  */
 const ARCHIVE_ALT_WRITE_BINS = new Set([
     "tar",
@@ -222,7 +263,106 @@ const ARCHIVE_ALT_WRITE_BINS = new Set([
     "fetch",
     "socat",
     "lftp",
+    // #3288 residual after #3245.
+    "gpg",
+    "age",
+    "zstd",
+    "unzstd",
+    "sftp",
+    "wget2",
+    "http",
+    "https",
+    "yt-dlp",
+    "ytdlp",
+    "aria2",
+    "mbuffer",
+    "cpio",
+    // #3311 residual after #3288.
+    "gpg2",
+    "gpg1",
+    "rage",
+    "xh",
+    "httpie",
+    "wcurl",
+    "curlie",
+    "uudecode",
+    "iconv",
+    "gtar",
+    "star",
+    "gnutar",
+    "pax",
+    // #3336 residual after #3311.
+    "oras",
+    "lwp-download",
+    "ncat",
+    "patch",
+    "base32",
+    "lrzip",
+    "unar",
+    "cabextract",
+    "ditto",
+    "dpkg-deb",
+    "hg",
+    "msguniq",
+]);
+/**
+ * Bins whose pathish operands are scanned for authz/kill destinations (#3213 / #3245 / #3288 / #3311 / #3336).
+ * Prefer a Set over a long `||` chain so coverage counts one membership check, not N branches.
+ */
+const PROTECTED_POSITIONAL_BINS = new Set([
+    "scp",
+    "certutil",
+    "rclone",
+    "tar",
+    "bsdtar",
+    "unzip",
+    "7z",
+    "7za",
+    "7zr",
+    "socat",
+    "lftp",
+    // #3288 residual.
+    "sftp",
+    "cpio",
+    "gpg",
+    "age",
+    "zstd",
+    "unzstd",
+    "mbuffer",
+    // #3311 residual: versioned crypto + archive/decoder peers.
+    "gpg2",
+    "gpg1",
+    "rage",
+    "uudecode",
+    "iconv",
+    "gtar",
+    "star",
+    "gnutar",
+    "pax",
+    // #3336 residual: positional dest writers (ditto/dpkg-deb/hg/lwp-download).
+    "oras",
+    "lwp-download",
+    "ncat",
+    "patch",
+    "base32",
+    "lrzip",
+    "unar",
+    "cabextract",
+    "ditto",
+    "dpkg-deb",
+    "hg",
+    "msguniq",
 ]);
+/** wget family (directory-prefix dest flags). */
+const WGET_FAMILY_BINS = new Set(["wget", "wget2"]);
+/** aria2 family (dir dest flags). */
+const ARIA2_FAMILY_BINS = new Set(["aria2c", "aria2"]);
+/** 7z family (attached -oDIR only). */
+const SEVEN_Z_FAMILY_BINS = new Set(["7z", "7za", "7zr"]);
+/** tar family (chdir -C / --directory). Includes GNU/Schily aliases (#3311). */
+const TAR_FAMILY_BINS = new Set(["tar", "bsdtar", "gtar", "star", "gnutar"]);
+/** xh / httpie family (download-dir dest flags) (#3311). */
+const XH_FAMILY_BINS = new Set(["xh", "httpie"]);
 /**
  * File destination flags for downloaders/decoders (#3206).
  * normalizeToken lowercases, so wget `-O` and curl `-o` share `-o`.
@@ -233,8 +373,13 @@ const DOWNLOADER_FILE_DEST_FLAGS = new Set([
     "-o",
     "--output",
     "--output-document",
+    "--output-file",
     "-out",
     "--out",
+    "--outfile",
+    // unar single-dash long form; GNU/others use --output-directory.
+    "-output-directory",
+    "--output-directory",
 ]);
 /** Directory destination flags (curl --output-dir / wget -P / aria2c -d); bin-scoped below. */
 const CURL_DIR_DEST_FLAGS = new Set(["--output-dir"]);
@@ -246,8 +391,18 @@ const ARIA2C_DIR_DEST_FLAGS = new Set(["-d", "--dir"]);
  */
 const TAR_DIR_DEST_FLAGS_EXACT = new Set(["-C"]);
 const TAR_DIR_DEST_FLAGS_LOWER = new Set(["--directory"]);
-/** unzip extract directory (#3245). */
+/** unzip / cabextract extract directory (#3245 / #3336). */
 const UNZIP_DIR_DEST_FLAGS = new Set(["-d"]);
+const UNZIP_DIR_DEST_BINS = new Set(["unzip", "cabextract"]);
+/** xh / httpie download directory (#3311). */
+const XH_DIR_DEST_FLAGS = new Set(["--download-dir"]);
+/**
+ * cpio chdir before extract/create (#3288).
+ * Case-sensitive short form: POSIX cpio uses capital `-D`; lower `-d` is a create option bit.
+ * Long form `--directory` is accepted lowercased.
+ */
+const CPIO_DIR_DEST_FLAGS_EXACT = new Set(["-D"]);
+const CPIO_DIR_DEST_FLAGS_LOWER = new Set(["--directory"]);
 /**
  * Symlink / hard-link plant bins (#3213). Absent from prior killWriteBins →
  * `ln -sf … .deft-directive-disable` classified empty → UAT fail-open.
@@ -285,18 +440,27 @@ function isDownloaderDestFlag(flag, bin, rawFlag) {
     if (bin === "scp")
         return false;
     // 7z family: only attached `-oDIR` (parsed in attached-short branch), not separate `-o PATH`.
-    if (bin === "7z" || bin === "7za" || bin === "7zr") {
+    if (SEVEN_Z_FAMILY_BINS.has(bin)) {
+        return false;
+    }
+    // #3288: cpio `-o` is copy-out (create archive), not a file dest; dest is `-D` / `--directory`.
+    if (bin === "cpio") {
+        if (rawFlag !== undefined && CPIO_DIR_DEST_FLAGS_EXACT.has(rawFlag))
+            return true;
+        // Long form is case-insensitive via normalizeToken (`flag` already lowercased).
+        if (CPIO_DIR_DEST_FLAGS_LOWER.has(flag))
+            return true;
         return false;
     }
     if (DOWNLOADER_FILE_DEST_FLAGS.has(flag))
         return true;
     if (bin === "curl" && CURL_DIR_DEST_FLAGS.has(flag))
         return true;
-    if (bin === "wget" && WGET_DIR_DEST_FLAGS.has(flag))
+    if (WGET_FAMILY_BINS.has(bin) && WGET_DIR_DEST_FLAGS.has(flag))
         return true;
-    if (bin === "aria2c" && ARIA2C_DIR_DEST_FLAGS.has(flag))
+    if (ARIA2_FAMILY_BINS.has(bin) && ARIA2C_DIR_DEST_FLAGS.has(flag))
         return true;
-    if (bin === "tar" || bin === "bsdtar") {
+    if (TAR_FAMILY_BINS.has(bin)) {
         if (rawFlag !== undefined && TAR_DIR_DEST_FLAGS_EXACT.has(rawFlag))
             return true;
         if (TAR_DIR_DEST_FLAGS_LOWER.has(flag))
@@ -306,7 +470,9 @@ function isDownloaderDestFlag(flag, bin, rawFlag) {
             return true;
         return false;
     }
-    if (bin === "unzip" && UNZIP_DIR_DEST_FLAGS.has(flag))
+    if (UNZIP_DIR_DEST_BINS.has(bin) && UNZIP_DIR_DEST_FLAGS.has(flag))
+        return true;
+    if (XH_FAMILY_BINS.has(bin) && XH_DIR_DEST_FLAGS.has(flag))
         return true;
     return false;
 }
@@ -386,17 +552,7 @@ function downloaderDecoderDestinations(tokens) {
         // Segment breaks (`;`/`\n`/glued ops) prevent following-command overwrite.
         let lastPositionalPath = null;
         const protectedPathish = [];
-        const collectsProtectedPositionals = bin === "scp" ||
-            bin === "certutil" ||
-            bin === "rclone" ||
-            bin === "tar" ||
-            bin === "bsdtar" ||
-            bin === "unzip" ||
-            bin === "7z" ||
-            bin === "7za" ||
-            bin === "7zr" ||
-            bin === "socat" ||
-            bin === "lftp";
+        const collectsProtectedPositionals = PROTECTED_POSITIONAL_BINS.has(bin);
         while (i < tokens.length) {
             const raw = tokens[i];
             const n = normalizeToken(raw);
@@ -463,31 +619,41 @@ function downloaderDecoderDestinations(tokens) {
                     i++;
                     continue;
                 }
-                if (n.startsWith("-o") && !n.startsWith("-out") && n.length > 2) {
+                // cpio `-o` is copy-out create mode, not a file dest (#3288).
+                if (bin !== "cpio" && n.startsWith("-o") && !n.startsWith("-out") && n.length > 2) {
                     dests.push(pathishToken(raw.slice(2)));
                     i++;
                     continue;
                 }
-                // wget attached -Pdir
-                if (bin === "wget" && n.startsWith("-p") && n.length > 2 && !n.startsWith("-proxy")) {
+                // wget / wget2 attached -Pdir
+                if (WGET_FAMILY_BINS.has(bin) &&
+                    n.startsWith("-p") &&
+                    n.length > 2 &&
+                    !n.startsWith("-proxy")) {
                     dests.push(pathishToken(raw.slice(2)));
                     i++;
                     continue;
                 }
-                // aria2c attached -dDIR (#3213)
-                if (bin === "aria2c" && n.startsWith("-d") && n.length > 2) {
+                // aria2c / aria2 attached -dDIR (#3213 / #3288)
+                if (ARIA2_FAMILY_BINS.has(bin) && n.startsWith("-d") && n.length > 2) {
                     dests.push(pathishToken(raw.slice(2)));
                     i++;
                     continue;
                 }
-                // unzip attached -dDIR (#3245)
-                if (bin === "unzip" && n.startsWith("-d") && n.length > 2) {
+                // unzip / cabextract attached -dDIR (#3245 / #3336)
+                if (UNZIP_DIR_DEST_BINS.has(bin) && n.startsWith("-d") && n.length > 2) {
                     dests.push(pathishToken(raw.slice(2)));
                     i++;
                     continue;
                 }
                 // tar attached -CDIR (rare; capital C required)
-                if ((bin === "tar" || bin === "bsdtar") && raw.startsWith("-C") && raw.length > 2) {
+                if (TAR_FAMILY_BINS.has(bin) && raw.startsWith("-C") && raw.length > 2) {
+                    dests.push(pathishToken(raw.slice(2)));
+                    i++;
+                    continue;
+                }
+                // cpio attached -DDIR (#3288; capital D required)
+                if (bin === "cpio" && raw.startsWith("-D") && raw.length > 2) {
                     dests.push(pathishToken(raw.slice(2)));
                     i++;
                     continue;

package/dist/authz/decompose-apply.d.ts

@@ -34,6 +34,20 @@ export interface EvaluateDecomposeStructuralApplyInput {
 export declare function sha256Hex(data: Buffer | string): string;
 /** SHA-256 hex of file bytes at path (exact on-disk digest). */
 export declare function sha256FileHex(path: string): string;
+/**
+ * Exact operator CLI mint command for a structural decompose apply grant (#3291).
+ * Paths are project-relative POSIX when inside projectRoot; otherwise as provided.
+ * Parent / draft / repo tokens are shell-quoted when they contain whitespace or
+ * shell metacharacters. When POSIX and PowerShell apostrophe escapes differ,
+ * both forms are emitted on separate labeled lines (`bash:` / `pwsh:`) so each
+ * is independently copy-pasteable. Paths containing newline or NUL are refused
+ * (no rewritten fake path) so the operator renames before minting. Does not
+ * include agent/CI/TTY gates — those remain on the CLI multi-factor path.
+ */
+export declare function formatDecomposeStructuralMintCommand(parentPath: string, draftPath: string, options?: {
+    readonly projectRoot?: string;
+    readonly repo?: string | null;
+}): string;
 /**
  * Normalize a path to project-relative POSIX form for grant binding compare.
  * Returns null when the path escapes the project root.

package/dist/authz/decompose-apply.js

@@ -23,6 +23,69 @@ export function sha256Hex(data) {
 export function sha256FileHex(path) {
     return sha256Hex(readFileSync(path));
 }
+/**
+ * Quote a CLI token for operator copy-paste when it has whitespace or shell
+ * metacharacters (Greptile #3291 / PR #3300). Safe bare tokens stay unquoted
+ * so deny-reason mint hints match the common path shape.
+ *
+ * Single quotes keep `$()`, backticks, and `!` inert. Apostrophe escape differs
+ * by shell: POSIX uses `'\''`; PowerShell uses `''`. Callers that need both
+ * pass dialect `"posix"` or `"pwsh"`. Does not rewrite path bytes (no newline
+ * flattening) — callers must refuse control chars before quoting.
+ */
+function shellQuoteCliArg(value, dialect) {
+    // Allowlist: alnum + common path/repo chars without whitespace or shell meta.
+    if (value.length > 0 && /^[A-Za-z0-9_./:@+=,-]+$/.test(value)) {
+        return value;
+    }
+    if (dialect === "pwsh") {
+        // PowerShell single-quoted string: only ' is special, doubled as ''.
+        return `'${value.replace(/'/g, "''")}'`;
+    }
+    // POSIX single-quote; only ' needs escaping as '\''
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function mintCommandWithDialect(parent, draft, repo, dialect) {
+    return (`deft authz:grant -- --parent ${shellQuoteCliArg(parent, dialect)} --draft ${shellQuoteCliArg(draft, dialect)}` +
+        (repo ? ` --repo ${shellQuoteCliArg(repo, dialect)}` : "") +
+        " --confirm");
+}
+/** True when a path/repo token cannot be represented as an exact shell mint arg. */
+function hasUnsafeMintControlChars(value) {
+    return /[\r\n\0]/.test(value);
+}
+/**
+ * Exact operator CLI mint command for a structural decompose apply grant (#3291).
+ * Paths are project-relative POSIX when inside projectRoot; otherwise as provided.
+ * Parent / draft / repo tokens are shell-quoted when they contain whitespace or
+ * shell metacharacters. When POSIX and PowerShell apostrophe escapes differ,
+ * both forms are emitted on separate labeled lines (`bash:` / `pwsh:`) so each
+ * is independently copy-pasteable. Paths containing newline or NUL are refused
+ * (no rewritten fake path) so the operator renames before minting. Does not
+ * include agent/CI/TTY gates — those remain on the CLI multi-factor path.
+ */
+export function formatDecomposeStructuralMintCommand(parentPath, draftPath, options) {
+    let parent = parentPath.replace(/\\/g, "/");
+    let draft = draftPath.replace(/\\/g, "/");
+    const root = options?.projectRoot;
+    if (root) {
+        parent = toProjectRelativePosix(root, parentPath) ?? parent;
+        draft = toProjectRelativePosix(root, draftPath) ?? draft;
+    }
+    const repo = (options?.repo ?? "").trim();
+    if (hasUnsafeMintControlChars(parent) ||
+        hasUnsafeMintControlChars(draft) ||
+        hasUnsafeMintControlChars(repo)) {
+        return ("rename parent/draft/repo to remove newline or NUL characters, then run: " +
+            "deft authz:grant -- --parent <parent.xbrief.json> --draft <draft.json> [--repo owner/name] --confirm");
+    }
+    const posix = mintCommandWithDialect(parent, draft, repo, "posix");
+    const pwsh = mintCommandWithDialect(parent, draft, repo, "pwsh");
+    // Labels on their own lines so the executable command is independently pasteable.
+    if (posix === pwsh)
+        return posix;
+    return `bash:\n${posix}\npwsh:\n${pwsh}`;
+}
 /**
  * Normalize a path to project-relative POSIX form for grant binding compare.
  * Returns null when the path escapes the project root.
@@ -56,7 +119,7 @@ function normalizeDigest(raw) {
 function pathsEqual(a, b) {
     return a.replace(/\\/g, "/") === b.replace(/\\/g, "/");
 }
-function grantValidity(grant, now) {
+function grantValidity(grant, now, mintHint) {
     if (!isHumanOriginGrant(grant)) {
         const kind = grant.origin.kind;
         if (isRejectedOriginKind(kind)) {
@@ -65,14 +128,14 @@ function grantValidity(grant, now) {
                 code: "authz-grant-origin-reject",
                 reason: `Directive denied scope:decompose apply: grant ${grant.id} origin.kind=${kind} is ` +
                     "agent/self-authored and cannot approve a decomposition draft. " +
-                    "Human action required: mint via `deft authz:grant` (operator-cli) bound to the draft digest.",
+                    `Human action required: \`${mintHint}\`.`,
             };
         }
         return {
             ok: false,
             code: "authz-grant-origin-reject",
             reason: `Directive denied scope:decompose apply: grant ${grant.id} lacks human-origin provenance. ` +
-                "Human action required: `deft authz:grant` with operator-cli origin.",
+                `Human action required: \`${mintHint}\`.`,
         };
     }
     if (grant.semantics.revokedAt !== null) {
@@ -86,7 +149,8 @@ function grantValidity(grant, now) {
         return {
             ok: false,
             code: "authz-grant-single-use-spent",
-            reason: `Directive denied scope:decompose apply: single-use grant ${grant.id} already spent at ${grant.semantics.usedAt}.`,
+            reason: `Directive denied scope:decompose apply: single-use grant ${grant.id} already spent at ${grant.semantics.usedAt}. ` +
+                `Human action required: \`${mintHint}\`.`,
         };
     }
     if (grant.semantics.expiresAt !== null) {
@@ -96,7 +160,7 @@ function grantValidity(grant, now) {
                 ok: false,
                 code: "authz-grant-expired",
                 reason: `Directive denied scope:decompose apply: grant ${grant.id} expired at ${grant.semantics.expiresAt}. ` +
-                    "Human action required: re-mint a grant for the current draft digest.",
+                    `Human action required: \`${mintHint}\`.`,
             };
         }
     }
@@ -116,11 +180,16 @@ export function evaluateDecomposeStructuralApply(input) {
     const targetRel = toProjectRelativePosix(input.projectRoot, input.draftPath);
     const projectAbs = resolve(input.projectRoot);
     const grants = input.grants ?? listGrants(input.projectRoot);
+    const mintHint = formatDecomposeStructuralMintCommand(input.parentPath, input.draftPath, {
+        projectRoot: input.projectRoot,
+        repo: input.repo,
+    });
     if (parentRel === null || targetRel === null) {
         return {
             allowed: false,
             code: "authz-grant-scope-deny",
-            reason: "Directive denied scope:decompose apply: parent or draft path is outside the project root.",
+            reason: "Directive denied scope:decompose apply: parent or draft path is outside the project root. " +
+                `Human action required: \`${mintHint}\` with paths inside the project root.`,
             humanApprovalRef: null,
             draftDigest: digest,
         };
@@ -128,7 +197,7 @@ export function evaluateDecomposeStructuralApply(input) {
     let lastReject = null;
     for (const grant of grants) {
         if (!evidenceSatisfiesImplementationApproval({ grant })) {
-            const validity = grantValidity(grant, now);
+            const validity = grantValidity(grant, now, mintHint);
             if (!validity.ok) {
                 lastReject = { code: validity.code, reason: validity.reason, grantId: grant.id };
                 continue;
@@ -136,12 +205,12 @@ export function evaluateDecomposeStructuralApply(input) {
             lastReject = {
                 code: "authz-grant-origin-reject",
                 reason: `Directive denied scope:decompose apply: grant ${grant.id} does not satisfy ` +
-                    "human-origin implementation approval. Human action required: `deft authz:grant`.",
+                    `human-origin implementation approval. Human action required: \`${mintHint}\`.`,
                 grantId: grant.id,
             };
             continue;
         }
-        const validity = grantValidity(grant, now);
+        const validity = grantValidity(grant, now, mintHint);
         if (!validity.ok) {
             lastReject = { code: validity.code, reason: validity.reason, grantId: grant.id };
             continue;
@@ -150,7 +219,7 @@ export function evaluateDecomposeStructuralApply(input) {
             lastReject = {
                 code: "authz-grant-scope-deny",
                 reason: `Directive denied scope:decompose apply: grant ${grant.id} does not include operation ` +
-                    `'${SCOPE_DECOMPOSE_APPLY_STRUCTURAL}'. Human action required: mint with that operation.`,
+                    `'${SCOPE_DECOMPOSE_APPLY_STRUCTURAL}'. Human action required: \`${mintHint}\`.`,
                 grantId: grant.id,
             };
             continue;
@@ -165,7 +234,7 @@ export function evaluateDecomposeStructuralApply(input) {
                 code: "authz-grant-binding-incomplete",
                 reason: `Directive denied scope:decompose apply: grant ${grant.id} is missing required ` +
                     "structural bindings (contentDigest, parentPath, targetPath). " +
-                    "Human action required: re-mint bound to the exact draft.",
+                    `Human action required: \`${mintHint}\`.`,
                 grantId: grant.id,
             };
             continue;
@@ -174,7 +243,8 @@ export function evaluateDecomposeStructuralApply(input) {
             lastReject = {
                 code: "authz-grant-binding-incomplete",
                 reason: `Directive denied scope:decompose apply: grant ${grant.id} does not bind project ` +
-                    "identity (repo and/or worktree). Human action required: re-mint with --repo or worktree.",
+                    "identity (repo and/or worktree). " +
+                    `Human action required: \`${mintHint}\`.`,
                 grantId: grant.id,
             };
             continue;
@@ -184,7 +254,8 @@ export function evaluateDecomposeStructuralApply(input) {
                 code: "authz-grant-digest-mismatch",
                 reason: `Directive denied scope:decompose apply: grant ${grant.id} is bound to draft digest ` +
                     `${boundDigest.slice(0, 12)}… but the draft bytes hash to ${digest.slice(0, 12)}…. ` +
-                    "Any content change after approval invalidates the grant. Re-mint for the current draft.",
+                    "Any content change after approval invalidates the grant. " +
+                    `Human action required: \`${mintHint}\`.`,
                 grantId: grant.id,
             };
             continue;
@@ -193,7 +264,8 @@ export function evaluateDecomposeStructuralApply(input) {
             lastReject = {
                 code: "authz-grant-parent-mismatch",
                 reason: `Directive denied scope:decompose apply: grant ${grant.id} is bound to parent ` +
-                    `'${boundParent}' but apply targets '${parentRel}'.`,
+                    `'${boundParent}' but apply targets '${parentRel}'. ` +
+                    `Human action required: \`${mintHint}\`.`,
                 grantId: grant.id,
             };
             continue;
@@ -202,7 +274,8 @@ export function evaluateDecomposeStructuralApply(input) {
             lastReject = {
                 code: "authz-grant-target-mismatch",
                 reason: `Directive denied scope:decompose apply: grant ${grant.id} is bound to draft path ` +
-                    `'${boundTarget}' but apply uses '${targetRel}'.`,
+                    `'${boundTarget}' but apply uses '${targetRel}'. ` +
+                    `Human action required: \`${mintHint}\`.`,
                 grantId: grant.id,
             };
             continue;
@@ -214,7 +287,8 @@ export function evaluateDecomposeStructuralApply(input) {
                 lastReject = {
                     code: "authz-grant-project-mismatch",
                     reason: `Directive denied scope:decompose apply: grant ${grant.id} is bound to repo ` +
-                        `'${boundRepo}' which does not match the apply context.`,
+                        `'${boundRepo}' which does not match the apply context. ` +
+                        `Human action required: \`${mintHint}\`.`,
                     grantId: grant.id,
                 };
                 continue;
@@ -228,7 +302,8 @@ export function evaluateDecomposeStructuralApply(input) {
                 lastReject = {
                     code: "authz-grant-project-mismatch",
                     reason: `Directive denied scope:decompose apply: grant ${grant.id} is bound to worktree ` +
-                        `'${boundWorktree}' which does not match project root '${projectAbs}'.`,
+                        `'${boundWorktree}' which does not match project root '${projectAbs}'. ` +
+                        `Human action required: \`${mintHint}\`.`,
                     grantId: grant.id,
                 };
                 continue;
@@ -257,7 +332,7 @@ export function evaluateDecomposeStructuralApply(input) {
         code: "authz-grant-missing",
         reason: "Directive denied scope:decompose apply: no human-origin grant covers " +
             `'${SCOPE_DECOMPOSE_APPLY_STRUCTURAL}' for this draft digest. ` +
-            "Human action required: mint a grant bound to the exact draft SHA-256 " +
+            `Human action required: \`${mintHint}\` ` +
             "(self-authored lifecycle/dispatch tokens do not count). --check remains ungated.",
         humanApprovalRef: null,
         draftDigest: digest,

package/dist/check/cached-orchestrator.d.ts

@@ -1,4 +1,5 @@
 import type { TaskRunResult } from "../cache/task-cache/types.js";
+import { type ToolchainPreflightResult } from "../session/toolchain-preflight.js";
 import { type CheckOrchestratorSeams } from "./context.js";
 export interface CachedCheckOptions extends CheckOrchestratorSeams {
     readonly onGateStart?: (gateId: string) => void;
@@ -6,16 +7,40 @@ export interface CachedCheckOptions extends CheckOrchestratorSeams {
     readonly gateSpawnFn?: (gateId: string, taskBin: string, taskArgs: string[], opts: {
         cwd: string;
         env?: NodeJS.ProcessEnv;
-    }) => Pick<TaskRunResult, "exitCode" | "stdout" | "stderr">;
+    }) => Pick<TaskRunResult, "exitCode" | "stdout" | "stderr"> & {
+        spawnError?: string;
+    };
+    /**
+     * #3282: inject preflight (tests). When omitted, runs live toolchain preflight.
+     * Pass `null` to skip preflight entirely (legacy test paths).
+     */
+    readonly preflight?: ToolchainPreflightResult | null;
+    /** #3282: session id for run-summary lines (default: new UUID). */
+    readonly sessionId?: string;
+    /** #3282: disable run-summary emission (tests). */
+    readonly emitRunSummary?: boolean;
+    /** PATH lookup seam (tests). */
+    readonly which?: (name: string) => string | null;
+    /** Override global CLI binary when dispatching CLI-native gates (#3335). */
+    readonly cliBin?: string | null;
 }
 /**
  * Run check gates sequentially with content-hash caching (#1713).
  * Falls back to fail-open execution for undeclared / non-cacheable gates.
  *
- * Gate order is fast-before-slow (#3188): non-suite gates complete (or fail)
- * before any suite gate (`ts:check-lane` / vitest+coverage) is started. A
- * non-zero exit aborts the loop immediately — the suite never starts after a
- * fast-gate failure (observable via `onGateStart` / suite start log).
+ * Gate order (#3284 / #3188):
+ *  1. Product AC (`verify:ac`) first — fail-fast; never skippable when commands exist
+ *  2. Hygiene preflight (may be advisory under pressure / degraded)
+ *  3. Suite last (`ts:check-lane`)
+ *
+ * Modes (env / ceremony dial / hard budget — see resolveProductFirstCheckMode):
+ *  - full: AC hard → hygiene hard → suite
+ *  - pressure: AC hard → hygiene advisory → suite
+ *  - rapid: AC only (ceremony dial rapid/minimal positive content)
+ *
+ * #3282: toolchain preflight enables degraded skip report when go-task/pnpm
+ * are missing; gate failures print named cause + remedy; run-summary JSONL
+ * is appended when DEFT_RUN_SUMMARY_PATH is set (fail-open).
  */
 export declare function dispatchCachedTaskCheck(frameworkRoot: string, projectRoot: string, options?: CachedCheckOptions): number;
 //# sourceMappingURL=cached-orchestrator.d.ts.map