javi-forge 1.33.0 → 1.34.1

package/README.md

@@ -375,6 +375,8 @@ npx javi-forge doctor
 ## Requirements
 
 - **Node.js** >= 22 (required by ink 7; previous versions ran on >= 18)
+- **Linux only** — the `acl` package (provides `getfacl`) is required to install or repair the Claude PreToolUse guard: the transactional installer proves every controlling directory carries no extended ACL, and refuses fail-closed when `getfacl` is unresolvable. Install with `apt install acl`, `apk add acl`, or `dnf install acl` (slim container images usually omit it). An already-installed guard keeps working without it — `javi-forge hooks doctor claude` reports the capability as its own row.
+- **`node` on `PATH`** — Claude Code spawns the guard in exec form, so `node` must resolve on the `PATH` Claude Code itself uses, not only inside javi-forge.
 
 ## Ecosystem
 

package/dist/cli/help.d.ts

@@ -19,7 +19,7 @@ export declare const CI_HELP_TEXT = "\n  Usage\n    $ javi-forge ci [subcommand]
  * Per-command help for `hooks`, shown by `javi-forge hooks --help` (or when
  * `hooks` is given an unknown subcommand). Whitespace is significant.
  */
-export declare const HOOKS_HELP_TEXT = "\n  Usage\n    $ javi-forge hooks run <pre-commit|pre-push>\n    $ javi-forge hooks <install|doctor|repair> claude [--force]\n\n    Run the sections enabled under hooks: in .javi-forge/ci.yaml, in a fixed\n    cheap\u2192expensive order, fail-fast. With no hooks: config the default is the\n    quick native CI gate (setup + lint + compile + gates \u2014 no tests, no coverage).\n\n  Subcommands\n    run pre-commit    Run the composed pre-commit sections\n    run pre-push      Run the composed pre-push sections\n    install claude    Install the managed Claude PreToolUse guard (.claude/)\n    doctor claude     Report Claude PreToolUse guard health (informational)\n    repair claude     Repair the managed guard; --force overwrites edited assets\n\n  Notes\n    A blocking section failure exits non-zero and blocks the commit/push.\n    A broken .javi-forge/ci.yaml exits 1 (fail-closed \u2014 never skips a gate).\n    To skip: git commit --no-verify   (pre-push: git push --no-verify)\n    doctor claude is informational (always exits 0); install/repair exit 0 on\n    success, non-zero on refusal/failure. Use repair claude --force to overwrite\n    a locally edited managed asset.\n\n  Examples\n    $ javi-forge hooks run pre-commit\n    $ javi-forge hooks run pre-push\n    $ javi-forge hooks install claude\n    $ javi-forge hooks doctor claude\n    $ javi-forge hooks repair claude --force\n";
+export declare const HOOKS_HELP_TEXT = "\n  Usage\n    $ javi-forge hooks run <pre-commit|pre-push>\n    $ javi-forge hooks <install|doctor|repair> claude [--force]\n\n    Run the sections enabled under hooks: in .javi-forge/ci.yaml, in a fixed\n    cheap\u2192expensive order, fail-fast. With no hooks: config the default is the\n    quick native CI gate (setup + lint + compile + gates \u2014 no tests, no coverage).\n\n  Subcommands\n    run pre-commit    Run the composed pre-commit sections\n    run pre-push      Run the composed pre-push sections\n    install claude    Install the managed Claude PreToolUse guard (.claude/)\n    doctor claude     Report Claude PreToolUse guard health (informational)\n    repair claude     Repair the managed guard; --force overwrites edited assets\n\n  Notes\n    A blocking section failure exits non-zero and blocks the commit/push.\n    A broken .javi-forge/ci.yaml exits 1 (fail-closed \u2014 never skips a gate).\n    To skip: git commit --no-verify   (pre-push: git push --no-verify)\n    doctor claude is informational (always exits 0); install/repair exit 0 on\n    success, non-zero on refusal/failure. Use repair claude --force to overwrite\n    a locally edited managed asset.\n    Linux: install/repair claude need the acl package (getfacl) to prove the\n    parent chain \u2014 apt install acl / apk add acl / dnf install acl. Without it\n    they refuse fail-closed; an already-installed guard keeps firing, and\n    doctor claude reports the acl capability as its own row.\n    Claude Code spawns the guard with node from ITS path, so node must resolve\n    there, not only inside javi-forge.\n\n  Examples\n    $ javi-forge hooks run pre-commit\n    $ javi-forge hooks run pre-push\n    $ javi-forge hooks install claude\n    $ javi-forge hooks doctor claude\n    $ javi-forge hooks repair claude --force\n";
 export declare const FLAGS_SCHEMA: {
     readonly help: {
         readonly type: "boolean";

package/dist/cli/help.js

@@ -186,6 +186,12 @@ export const HOOKS_HELP_TEXT = `
     doctor claude is informational (always exits 0); install/repair exit 0 on
     success, non-zero on refusal/failure. Use repair claude --force to overwrite
     a locally edited managed asset.
+    Linux: install/repair claude need the acl package (getfacl) to prove the
+    parent chain — apt install acl / apk add acl / dnf install acl. Without it
+    they refuse fail-closed; an already-installed guard keeps firing, and
+    doctor claude reports the acl capability as its own row.
+    Claude Code spawns the guard with node from ITS path, so node must resolve
+    there, not only inside javi-forge.
 
   Examples
     $ javi-forge hooks run pre-commit

package/dist/commands/claude-hooks.js

@@ -14,6 +14,18 @@
  * current.
  */
 import { doctorClaudePreToolUse, installClaudePreToolUse, repairClaudePreToolUse, } from "../lib/claude-hook-manager.js";
+import { remediationForMessage } from "../lib/secure-refusal-remediation.js";
+/**
+ * Warnings are NON-BLOCKING notices, so they go to stdout under their own
+ * heading — never to the error stream and never into the exit code.
+ */
+function renderWarnings(warnings, log) {
+    if (warnings.length === 0)
+        return;
+    log("warnings:");
+    for (const w of warnings)
+        log(`  ${w}`);
+}
 function renderMutation(verb, result, log, logError) {
     if (result.ok) {
         log(`${verb} claude: ok`);
@@ -30,11 +42,19 @@ function renderMutation(verb, result, log, logError) {
             for (const p of result.backups)
                 log(`  ${p}`);
         }
+        renderWarnings(result.warnings, log);
         return 0;
     }
     logError(`${verb} claude: refused`);
-    for (const e of result.errors)
+    // A refusal whose detail maps to a remediation is never rendered bare: the
+    // mapping is a CLI-layer lookup, so the adapter's refusal codes stay stable.
+    for (const e of result.errors) {
         logError(`  ${e}`);
+        const remediation = remediationForMessage(e);
+        if (remediation)
+            logError(`    → ${remediation}`);
+    }
+    renderWarnings(result.warnings, log);
     return 1;
 }
 function renderDoctor(report, log) {
@@ -42,6 +62,16 @@ function renderDoctor(report, log) {
     log(`  settings: ${report.settings.state} — ${report.settings.detail}`);
     log(`  asset:    ${report.asset.state} — ${report.asset.detail}`);
     log(`  node:     ${report.node.version ?? "unavailable"} (min-satisfied: ${report.node.satisfiesMinimum})`);
+    // The node-on-PATH row is ALWAYS printed (satisfied included) and is always
+    // labelled a heuristic: this process' PATH only proxies the PATH Claude Code
+    // will use to spawn the exec-form handler.
+    const onPath = report.nodeOnPath;
+    const onPathDetail = onPath.status === "resolved"
+        ? ` ${onPath.version}`
+        : onPath.status === "unknown"
+            ? ` — ${onPath.detail}`
+            : "";
+    log(`  node-on-PATH: ${onPath.status}${onPathDetail} (heuristic: this process' PATH)`);
     const execution = report.execution;
     log(`  execution: ${execution.status}`);
     if (execution.blockers.length > 0) {
@@ -59,6 +89,15 @@ function renderDoctor(report, log) {
         for (const r of execution.residual)
             log(`    - ${r}`);
     }
+    // Install-capability is its OWN section, always printed so an absent adapter
+    // is never silent — and it never changes the exit code, which follows
+    // `execution.status` alone.
+    const acl = report.installCapability.acl;
+    const aclDetail = "detail" in acl ? ` — ${acl.detail}` : "";
+    log(`  acl-capability: ${acl.status} (${acl.tool})${aclDetail}`);
+    if (report.installCapability.remediation) {
+        log(`    → ${report.installCapability.remediation}`);
+    }
     log(`  host-residual: ${report.hostResidual}`);
     if (report.remediation.length > 0) {
         log("  remediation:");

package/dist/commands/init/steps/security.d.ts

@@ -10,6 +10,8 @@ import type { StepFn } from "../types.js";
  *      `claude-settings-security.json` scaffold is RETIRED — the managed
  *      installer owns `.claude/settings.json` + the hook asset with proper
  *      ownership markers.
+ *      A guard refusal/failure is REPORTED but does NOT abort the step: the
+ *      profile merge below is an independent outcome (Linux hardening Slice A).
  *   2. Merges the `hooks:` security sections for the selected reliability
  *      profile into `.javi-forge/ci.yaml` via `setHookFeature` (creating a
  *      minimal `version: 2` config when absent). The dispatcher composes these

package/dist/commands/init/steps/security.js

@@ -1,5 +1,6 @@
 import { setHookFeature } from "../../../lib/ci-config.js";
 import { installClaudePreToolUse } from "../../../lib/claude-hook-manager.js";
+import { remediationForMessage } from "../../../lib/secure-refusal-remediation.js";
 import { report } from "../report.js";
 /**
  * Hook-feature preset per reliability profile (hook-consolidation S4).
@@ -28,6 +29,8 @@ const PROFILE_PRESET = {
  *      `claude-settings-security.json` scaffold is RETIRED — the managed
  *      installer owns `.claude/settings.json` + the hook asset with proper
  *      ownership markers.
+ *      A guard refusal/failure is REPORTED but does NOT abort the step: the
+ *      profile merge below is an independent outcome (Linux hardening Slice A).
  *   2. Merges the `hooks:` security sections for the selected reliability
  *      profile into `.javi-forge/ci.yaml` via `setHookFeature` (creating a
  *      minimal `version: 2` config when absent). The dispatcher composes these
@@ -41,6 +44,11 @@ export const stepSecurityHooks = async (ctx) => {
     const { securityHooks, hookProfile, claudePreToolUseGuard } = options;
     const stepId = "security-hooks";
     report(onStep, stepId, "Scaffold security hooks", "running");
+    // Declared OUTSIDE the try so a throw from the profile merge below cannot
+    // swallow a guard refusal that already happened: the outer catch reports
+    // BOTH failures (Linux hardening Slice A — a captured refusal and its
+    // remediation are never silently lost).
+    let guardError;
     try {
         if (!securityHooks) {
             report(onStep, stepId, "Scaffold security hooks", "skipped", "not selected");
@@ -57,14 +65,30 @@ export const stepSecurityHooks = async (ctx) => {
         }
         // 1. Install the managed Claude PreToolUse guard (transactional; owns
         //    .claude/settings.json + the hook asset). Retires the legacy copy.
+        //    A refusal (or a throw) is CAPTURED, not returned on: the guard and
+        //    the hook-profile merge below are independent outcomes, so a host
+        //    that cannot install the guard must not silently lose its
+        //    secrets/permissions/deps wiring. The captured failure still drives a
+        //    terminal status of "error" — visibility is never downgraded.
         let guardNote = "";
         if (claudePreToolUseGuard) {
-            const result = await installClaudePreToolUse(projectDir);
-            if (!result.ok) {
-                report(onStep, stepId, "Scaffold security hooks", "error", `Claude guard install refused: ${result.errors.join("; ")}`);
-                return;
+            try {
+                const result = await installClaudePreToolUse(projectDir);
+                if (result.ok) {
+                    guardNote = "; Claude guard installed";
+                }
+                else {
+                    guardError = `Claude guard install refused: ${result.errors.join("; ")}`;
+                    const remediation = result.errors
+                        .map((e) => remediationForMessage(e))
+                        .find((line) => line !== undefined);
+                    if (remediation)
+                        guardError += ` → ${remediation}`;
+                }
+            }
+            catch (e) {
+                guardError = `Claude guard install failed: ${String(e)}`;
             }
-            guardNote = "; Claude guard installed";
         }
         // 2. Merge the profile's security sections into .javi-forge/ci.yaml.
         for (const feature of preset.preCommit) {
@@ -80,10 +104,16 @@ export const stepSecurityHooks = async (ctx) => {
         const presetNote = merged.length > 0
             ? `${profile} preset: ${merged.join(", ")}`
             : `${profile} preset: CI gate only (no security sections)`;
-        report(onStep, stepId, "Scaffold security hooks", "done", `${presetNote}${guardNote}`);
+        // ONE terminal report. On a captured guard failure the status stays
+        // "error" and the detail names BOTH the refusal (+ remediation) AND the
+        // preset that WAS merged, so a refused guard is never read as installed
+        // and a merged profile is never read as lost.
+        report(onStep, stepId, "Scaffold security hooks", guardError ? "error" : "done", guardError
+            ? `${guardError}; ${presetNote} merged`
+            : `${presetNote}${guardNote}`);
     }
     catch (e) {
-        report(onStep, stepId, "Scaffold security hooks", "error", String(e));
+        report(onStep, stepId, "Scaffold security hooks", "error", guardError ? `${guardError}; ${String(e)}` : String(e));
     }
 };
 //# sourceMappingURL=security.js.map

package/dist/lib/__fixtures__/fake-secure-fs.d.ts

@@ -27,6 +27,11 @@ export interface FakeFaults {
     writeRefuse?: (name: string, callIndex: number) => boolean;
     /** Refuse renameInDir when the destination base name matches. */
     renameRefuse?: (to: string) => boolean;
+    /**
+     * Refuse applyExactMode for a target (chmod fault). Lets a test drive the
+     * rollback's prior-mode restore into failure without touching the bytes.
+     */
+    applyModeRefuse?: (target: string) => boolean;
     /**
      * Refuse proveManagedContainer for a path on its Nth call (a foreign
      * add/delete-child ACE on a managed container we own — the win32 CREATE_PARENT_DIR

package/dist/lib/__fixtures__/fake-secure-fs.js

@@ -152,6 +152,8 @@ export function makeFakeSecureFs() {
             return ok();
         },
         async applyExactMode(target, mode) {
+            if (fake.faults.applyModeRefuse?.(target))
+                return unsafe(`applyMode ${target}`);
             const file = files.get(target);
             if (!file)
                 return unsafe(`applyMode enoent ${target}`);

package/dist/lib/claude-hook-manager.d.ts

@@ -8,6 +8,7 @@
  * Slice-3 seams — Slice 3 GROWS this file, it does not relocate this code.
  */
 import { type ClaudeHookComponentState, type SettingsClassification, type SettingsIdentityManifest } from "./claude-hook-settings.js";
+import { type AclCapability, type SpawnFn } from "./secure-fs-posix.js";
 import { type PlatformSecureFs } from "./secure-fs-transaction.js";
 declare const COVERAGE: readonly ["Bash", "PowerShell", "Read", "Write", "Edit"];
 export interface AssetManifestEntry {
@@ -52,6 +53,23 @@ export interface ClaudeHookDoctorReport {
     hostResidual: string;
     remediation: readonly string[];
     execution: ExecutionReport;
+    /**
+     * Host INSTALL-capability, reported as its own section. It answers "could
+     * install/repair run here?", NOT "will the installed guard fire?" — so it
+     * never feeds `execution`, `healthy`, or the exit code. A current, firing
+     * guard on an image without `getfacl` stays `runnable`.
+     */
+    installCapability: {
+        acl: AclCapability;
+        remediation?: string;
+    };
+    /**
+     * The node-on-PATH HEURISTIC row, always present so an absence is never
+     * silent. It is DISTINCT from `node` (which measures this process'
+     * `process.versions.node`) and it never inflates confidence: a `resolved`
+     * row clears no blocker and no unknown source.
+     */
+    nodeOnPath: NodeOnPathProbe;
 }
 /**
  * Classify the asset into one of nine states from observed bytes only. Never
@@ -81,6 +99,28 @@ export interface ExecutionReport {
     unknownSources: string[];
     residual: string[];
 }
+/**
+ * Whether a `node` executable resolves on THIS process' PATH, independently of
+ * `process.versions.node`. It is a HEURISTIC proxy for the PATH Claude Code will
+ * use to spawn the exec-form handler — never proof of it.
+ */
+export type NodeOnPathProbe = {
+    status: "resolved";
+    version: string;
+    major: number;
+} | {
+    status: "absent";
+} | {
+    status: "unknown";
+    detail: string;
+};
+/**
+ * Resolve and run `node --version` from this process' PATH. A spawn ENOENT is
+ * `absent` (near-certainly a dead exec-form guard); a timeout, non-zero exit, or
+ * unparseable banner is honest ignorance (`unknown`) and NEVER a fabricated
+ * version.
+ */
+export declare function probeNodeOnPath(spawn?: SpawnFn): Promise<NodeOnPathProbe>;
 /** Injectable seams so units never hard-read real `/etc` or `/Library`. */
 export interface ExecutionProbeEnv {
     platform?: NodeJS.Platform;
@@ -92,6 +132,8 @@ export interface ExecutionProbeEnv {
     managedDropInDir?: string | null;
     /** Override the drop-in directory listing (defaults to a confined readdir). */
     listDir?: (dir: string) => Promise<string[]>;
+    /** Injectable node-on-PATH heuristic (defaults to the real bounded probe). */
+    nodeProbe?: () => Promise<NodeOnPathProbe>;
 }
 /** Per-source read outcome; never promotes an unobservable source to clear. */
 export type ExecutionSourceProbe = {
@@ -99,6 +141,8 @@ export type ExecutionSourceProbe = {
 } | {
     kind: "blocking";
     flag: "disableAllHooks" | "allowManagedHooksOnly";
+    /** Present only for a PRESENT-but-INVALID value; names the observed shape. */
+    detail?: string;
 } | {
     kind: "unknown";
     reason: string;
@@ -161,6 +205,8 @@ export declare function doctorClaudePreToolUse(projectDir: string, options?: {
     manifest?: Manifest;
     nodeVersion?: string;
     execution?: ExecutionProbeEnv;
+    /** Injectable read-only ACL capability probe (defaults to the real one). */
+    aclProbe?: () => Promise<AclCapability>;
 }): Promise<ClaudeHookDoctorReport>;
 export interface ClaudeHookMutationResult {
     ok: boolean;
@@ -168,6 +214,12 @@ export interface ClaudeHookMutationResult {
     backups: string[];
     report: ClaudeHookDoctorReport;
     errors: string[];
+    /**
+     * NON-BLOCKING operator notices. A warning never changes `ok`: refusing to
+     * install because `node` may not resolve would leave the host with NO guard,
+     * which is strictly worse than an exec-form guard that may not resolve.
+     */
+    warnings: string[];
 }
 /** Injectable deps so tests drive `_run` with a fake `PlatformSecureFs`. */
 export interface ClaudeHookRunDeps {
@@ -176,6 +228,14 @@ export interface ClaudeHookRunDeps {
     nonce?: () => string;
     manifest?: Manifest;
     platform?: NodeJS.Platform;
+    /**
+     * Injectable read-only ACL capability probe, forwarded to the doctor report
+     * this run embeds. Same seam as `secureFs`/`clock`: it keeps unit tests from
+     * spawning the real `getfacl` (defaults to the real probe in production).
+     */
+    aclProbe?: () => Promise<AclCapability>;
+    /** Injectable node-on-PATH heuristic, shared by the warning and the report. */
+    nodeProbe?: () => Promise<NodeOnPathProbe>;
 }
 /** Internal deps-taking entry; tests drive it with a fake `PlatformSecureFs`. */
 export declare function _run(projectDir: string, mode: "install" | "repair", options: {

package/dist/lib/claude-hook-manager.js

@@ -7,6 +7,7 @@
  * and the component-level doctor. Install/repair are declared but unimplemented
  * Slice-3 seams — Slice 3 GROWS this file, it does not relocate this code.
  */
+import { execFile } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { lstat, readdir, readFile } from "node:fs/promises";
 import os from "node:os";
@@ -15,8 +16,9 @@ import { CLAUDE_HOOK_ASSETS_DIR } from "../constants.js";
 import { ASSET_MANAGED_MARKER, ASSET_NAME, } from "./__fixtures__/claude-hook-ownership.js";
 import { buildManagedContainer, classifySettingsEntry, isPlainObject, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, planForceReplace, planLegacyCohortExcision, planManagedClaudeHookMerge, scanExecutionFlags, } from "./claude-hook-settings.js";
 import { safeReadFile } from "./safe-read.js";
-import { selectSecureFs } from "./secure-fs-posix.js";
+import { ACL_DETAIL, probeAclCapability, selectSecureFs, } from "./secure-fs-posix.js";
 import { runTransaction, } from "./secure-fs-transaction.js";
+import { remediationForRefusal } from "./secure-refusal-remediation.js";
 /** 1 MiB read budget, shared with the runtime's stdin envelope. */
 const ASSET_MAX_BYTES = 1024 * 1024;
 const NODE_MINIMUM_MAJOR = 22;
@@ -189,10 +191,12 @@ function settingsSignals(value, classification, currentAssetSha) {
     };
 }
 const REMEDIATION = {
-    absent: "install the managed $ (Slice 3)",
-    "released-outdated": "upgrade the managed $ (Slice 3)",
-    "exact-legacy": "migrate the legacy $ (Slice 3)",
-    "edited-managed": "repair the managed $ with --force (Slice 3)",
+    // User-facing remediation: name the exact command to run, never an internal
+    // SDD slice number (which means nothing outside this repo's planning docs).
+    absent: "install the managed $ with: javi-forge hooks install claude",
+    "released-outdated": "upgrade the managed $ with: javi-forge hooks install claude",
+    "exact-legacy": "migrate the legacy $ with: javi-forge hooks install claude",
+    "edited-managed": "repair the managed $ with: javi-forge hooks repair claude --force",
     foreign: "manually review the $",
     symlink: "manually review the $",
     "non-regular": "manually review the $",
@@ -201,6 +205,57 @@ const REMEDIATION = {
 function remediationFor(state, component) {
     return REMEDIATION[state]?.replace("$", component);
 }
+const NODE_PROBE_TIMEOUT_MS = 2000;
+const NODE_PROBE_MAX_BUFFER = 64 * 1024;
+const NODE_VERSION_LINE = /^v(\d+)\.\d+\.\d+/;
+/**
+ * Bounded `node --version` spawn. argv only (never a shell string), `LC_ALL=C`,
+ * and a hard timeout — mirroring the ACL adapter's spawn discipline. It is
+ * read-only: it starts a process and reads its stdout, and touches no path.
+ */
+const defaultNodeSpawn = (cmd, args) => new Promise((resolve) => {
+    execFile(cmd, args, {
+        timeout: NODE_PROBE_TIMEOUT_MS,
+        maxBuffer: NODE_PROBE_MAX_BUFFER,
+        encoding: "utf8",
+        env: { ...process.env, LC_ALL: "C", LANG: "C" },
+    }, (error, stdout) => {
+        if (!error)
+            return resolve({ code: 0, stdout: stdout ?? "" });
+        const e = error;
+        if (e.code === "ENOENT") {
+            return resolve({ spawnError: true, code: null, stdout: "" });
+        }
+        if (e.killed || e.signal === "SIGTERM") {
+            return resolve({ timedOut: true, code: null, stdout: stdout ?? "" });
+        }
+        const code = typeof e.code === "number" ? e.code : 1;
+        return resolve({ code, stdout: stdout ?? "" });
+    });
+});
+/**
+ * Resolve and run `node --version` from this process' PATH. A spawn ENOENT is
+ * `absent` (near-certainly a dead exec-form guard); a timeout, non-zero exit, or
+ * unparseable banner is honest ignorance (`unknown`) and NEVER a fabricated
+ * version.
+ */
+export async function probeNodeOnPath(spawn = defaultNodeSpawn) {
+    const res = await spawn("node", ["--version"]);
+    if (res.spawnError)
+        return { status: "absent" };
+    if (res.timedOut) {
+        return { status: "unknown", detail: "node --version timeout" };
+    }
+    if (res.code !== 0) {
+        return { status: "unknown", detail: `node --version exit ${res.code}` };
+    }
+    const banner = res.stdout.trim();
+    const match = NODE_VERSION_LINE.exec(banner);
+    if (!match) {
+        return { status: "unknown", detail: "node --version output unparseable" };
+    }
+    return { status: "resolved", version: banner, major: Number(match[1]) };
+}
 /** Static managed-settings locations per OS (no fs). WSL reports `linux`. */
 export function resolveManagedSettingsPaths(platform) {
     if (platform === "darwin") {
@@ -256,11 +311,21 @@ export async function probeExecutionSource(target) {
         return { kind: "unknown", reason: "invalid-json" };
     }
     const flags = scanExecutionFlags(parsed);
-    if (flags.disableAllHooks) {
-        return { kind: "blocking", flag: "disableAllHooks" };
+    const blocking = (flag, verdict) => ({
+        kind: "blocking",
+        flag,
+        // An INVALID value is blocking per the documented "invalid ⇒ true"
+        // semantics; the shape is surfaced so an operator can see why (say) the
+        // string "false" did not clear the flag.
+        ...(verdict.set && verdict.reason === "invalid"
+            ? { detail: `invalid value: ${verdict.shape} → treated as true` }
+            : {}),
+    });
+    if (flags.disableAllHooks.set) {
+        return blocking("disableAllHooks", flags.disableAllHooks);
     }
-    if (flags.allowManagedHooksOnly) {
-        return { kind: "blocking", flag: "allowManagedHooksOnly" };
+    if (flags.allowManagedHooksOnly.set) {
+        return blocking("allowManagedHooksOnly", flags.allowManagedHooksOnly);
     }
     return { kind: "clear" };
 }
@@ -288,6 +353,7 @@ export async function listManagedDropIns(dir, listDir) {
 const EXECUTION_RESIDUAL = [
     "server-delivered managed policy can disable hooks and is not observable from local files",
     "session safe-mode (--safe-mode / CLAUDE_CODE_SAFE_MODE) in the diagnosed session is not observable from this process",
+    'the installed hook is exec-form (command: "node"): node is resolved from Claude Code\'s PATH, which this process cannot observe — the node-on-PATH row is a heuristic proxy, never proof the guard will spawn',
 ];
 function isSafeModeTruthy(env) {
     const value = env.CLAUDE_CODE_SAFE_MODE;
@@ -361,9 +427,11 @@ export async function probeExecution(projectDir, componentStates, env = {}) {
             continue;
         }
         // `allowManagedHooksOnly` is inert outside a managed source (hooks merge).
+        // An INVALID value there is inert for the same reason: the flag has no
+        // authority outside a managed source, so it gains none by being malformed.
         if (probe.flag === "allowManagedHooksOnly" && !spec.managed)
             continue;
-        blockers.push(`policy:${probe.flag}@${spec.label}`);
+        blockers.push(`policy:${probe.flag}@${spec.label}${probe.detail ? ` (${probe.detail})` : ""}`);
     }
     if (dropInDirUnknown)
         unknownSources.push(dropInDirUnknown);
@@ -374,6 +442,23 @@ export async function probeExecution(projectDir, componentStates, env = {}) {
     if (componentStates.settings !== "managed-current") {
         blockers.push(`guard:settings=${componentStates.settings}`);
     }
+    // node-on-PATH heuristic (design Decision 2). The installed handler is
+    // exec-form (`command: "node"`), so a `node` that does not resolve means the
+    // guard NEVER fires — fail-closed, with the heuristic labelled in the entry.
+    // A SUCCESSFUL probe contributes NOTHING: it clears no blocker, removes no
+    // unknown source, and adds no confidence, because this process' PATH only
+    // proxies the PATH Claude Code will use.
+    const nodeOnPath = await (env.nodeProbe ?? probeNodeOnPath)();
+    if (nodeOnPath.status === "absent") {
+        blockers.push("runtime:node-not-on-PATH (heuristic: this process' PATH)");
+    }
+    else if (nodeOnPath.status === "resolved" &&
+        nodeOnPath.major < NODE_MINIMUM_MAJOR) {
+        blockers.push(`runtime:node-on-PATH v${nodeOnPath.major} (<${NODE_MINIMUM_MAJOR}, heuristic)`);
+    }
+    else if (nodeOnPath.status === "unknown") {
+        unknownSources.push(`runtime:node-on-PATH (heuristic: ${nodeOnPath.detail})`);
+    }
     // Safe-mode observed in THIS doctor process is a real per-run unknown (the
     // diagnosed session's own safe-mode remains a constant residual).
     if (isSafeModeTruthy(processEnv)) {
@@ -432,7 +517,25 @@ export async function doctorClaudePreToolUse(projectDir, options) {
         signals.matcherExact &&
         signals.commandShapeExact &&
         node.satisfiesMinimum;
-    const execution = await probeExecution(projectDir, { asset: asset.state, settings: settings.state }, options?.execution ?? {});
+    // Probe node ONCE and share the outcome between the always-present report row
+    // and the execution matrix, so the doctor never spawns `node` twice per run.
+    const executionEnv = options?.execution ?? {};
+    const nodeOnPath = await (executionEnv.nodeProbe ?? probeNodeOnPath)();
+    const execution = await probeExecution(projectDir, { asset: asset.state, settings: settings.state }, { ...executionEnv, nodeProbe: async () => nodeOnPath });
+    // Install-capability section. Read-only, and deliberately OUTSIDE the
+    // execution matrix (design Decision 1): the installed `.mjs` guard never
+    // spawns `getfacl`, so an absent adapter cannot stop a current guard from
+    // firing. Only when a guard-currency blocker ALREADY exists does the
+    // remediation join `report.remediation` — there the user must install and
+    // cannot.
+    const aclCapability = await (options?.aclProbe ?? probeAclCapability)();
+    const aclRemediation = aclCapability.status === "absent" && aclCapability.tool === "getfacl"
+        ? remediationForRefusal("unsupported-posix-acl", ACL_DETAIL.getfaclAbsent)
+        : undefined;
+    if (aclRemediation &&
+        execution.blockers.some((blocker) => blocker.startsWith("guard:"))) {
+        remediation.add(aclRemediation);
+    }
     return {
         healthy,
         settings: {
@@ -455,6 +558,11 @@ export async function doctorClaudePreToolUse(projectDir, options) {
         hostResidual: HOST_RESIDUAL,
         remediation: [...remediation].sort(),
         execution,
+        nodeOnPath,
+        installCapability: {
+            acl: aclCapability,
+            ...(aclRemediation ? { remediation: aclRemediation } : {}),
+        },
     };
 }
 async function readManifest() {
@@ -463,6 +571,24 @@ async function readManifest() {
         throw new Error(`unreadable claude-hooks manifest: ${read.reason}`);
     return JSON.parse(read.content);
 }
+/**
+ * The non-blocking install/repair warning for the exec-form guard's runtime.
+ * Mirrors the doctor's heuristic wording: this process' PATH only PROXIES the
+ * PATH Claude Code will use to spawn the handler.
+ */
+function nodeOnPathWarnings(probe) {
+    if (probe.status === "absent") {
+        return [
+            `node did not resolve on this process' PATH (heuristic): the installed guard is exec-form (command: "node") and will not fire if Claude Code's PATH also lacks it — install Node ${NODE_MINIMUM_MAJOR}+ on PATH`,
+        ];
+    }
+    if (probe.status === "resolved" && probe.major < NODE_MINIMUM_MAJOR) {
+        return [
+            `node on PATH is ${probe.version} (<${NODE_MINIMUM_MAJOR}, heuristic): the installed guard may fail to run — install Node ${NODE_MINIMUM_MAJOR}+ on PATH`,
+        ];
+    }
+    return [];
+}
 function refuseMessage(component, state) {
     const remedy = remediationFor(state, component);
     return `refuse ${component} in state ${state}${remedy ? ` — ${remedy}` : ""}`;
@@ -594,7 +720,18 @@ export async function _run(projectDir, mode, options, deps) {
     const assetDestPath = path.join(projectDir, ".claude", "hooks", ASSET_NAME);
     const settingsPath = path.join(projectDir, ".claude", "settings.json");
     const assetSrcPath = path.join(CLAUDE_HOOK_ASSETS_DIR, ASSET_NAME);
-    const doctor = () => doctorClaudePreToolUse(projectDir, { manifest });
+    // Probe node ONCE per `_run` and share the sample with the embedded doctor
+    // report, so the run never spawns `node --version` twice and the warning, the
+    // report row and the verdict can never disagree about the same PATH.
+    const nodeOnPath = await (deps.nodeProbe ?? probeNodeOnPath)();
+    const doctor = () => doctorClaudePreToolUse(projectDir, {
+        manifest,
+        aclProbe: deps.aclProbe,
+        execution: { nodeProbe: async () => nodeOnPath },
+    });
+    // Non-blocking runtime notice, computed once and carried by EVERY outcome
+    // (success, no-op and refusal alike) — it never gates the mutation.
+    const warnings = nodeOnPathWarnings(nodeOnPath);
     // Windows (or any platform without an adapter) refuses with zero mutation.
     if (!secureFs) {
         return {
@@ -602,6 +739,7 @@ export async function _run(projectDir, mode, options, deps) {
             changed: [],
             backups: [],
             errors: ["windows-secure-object-unavailable"],
+            warnings,
             report: await doctor(),
         };
     }
@@ -624,6 +762,7 @@ export async function _run(projectDir, mode, options, deps) {
             changed: [],
             backups: [],
             errors: [reason],
+            warnings,
             report: await doctor(),
         };
     }
@@ -634,6 +773,7 @@ export async function _run(projectDir, mode, options, deps) {
             changed: [],
             backups: [],
             errors: [],
+            warnings,
             report: await doctor(),
         };
     }
@@ -672,6 +812,7 @@ export async function _run(projectDir, mode, options, deps) {
         changed: tx.committed,
         backups: tx.backups,
         errors: tx.errors,
+        warnings,
         report: await doctor(),
     };
 }

package/dist/lib/claude-hook-settings.d.ts

@@ -47,15 +47,29 @@ export declare function validateSettingsShape(parsed: unknown): boolean;
  * manager, which knows each source's provenance.
  */
 export interface ExecutionFlagScan {
-    disableAllHooks: boolean;
-    allowManagedHooksOnly: boolean;
+    disableAllHooks: FlagVerdict;
+    allowManagedHooksOnly: FlagVerdict;
 }
+/**
+ * One flag's verdict for one source. `set` answers "does this source neutralize
+ * the hook?"; `reason` says whether that came from a documented boolean or from
+ * the documented fallback for an INVALID value.
+ */
+export type FlagVerdict = {
+    set: false;
+} | {
+    set: true;
+    reason: "explicit";
+} | {
+    set: true;
+    reason: "invalid";
+    shape: string;
+};
 /**
  * Classify an already-parsed settings container for the two documented
- * hook-neutralizing flags. Strict `=== true` only: a truthy-but-not-`true`
- * value (`"true"`, `1`), a missing key, or a non-object input is NOT a flag.
- * A false here is a definitive "this source does not set the flag", never an
- * "unknown" — unreadability is decided upstream by the fs probe, not here.
+ * hook-neutralizing flags. A `{ set: false }` here is a definitive "this source
+ * does not set the flag", never an "unknown" — unreadability is decided upstream
+ * by the fs probe, not here, so a non-object input is "not a flag".
  */
 export declare function scanExecutionFlags(parsed: unknown): ExecutionFlagScan;
 /**

package/dist/lib/claude-hook-settings.js

@@ -31,20 +31,44 @@ export function validateSettingsShape(parsed) {
         return false;
     return true;
 }
+const NOT_SET = { set: false };
+const EXPLICIT = { set: true, reason: "explicit" };
+/** Name the observed JSON shape for the operator-facing blocker detail. */
+function shapeOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+/**
+ * Classify one present value per the documented Claude Code semantics: a
+ * boolean `true` sets the flag, a boolean `false` (or an absent/`undefined` key)
+ * definitively clears it, and ANY other present value is INVALID — which Claude
+ * Code treats as `true`, so it sets the flag with the shape named. That includes
+ * the counterintuitive string `"false"`: it is not a boolean, so it does not
+ * clear.
+ */
+function classifyFlag(value) {
+    if (value === undefined || value === false)
+        return NOT_SET;
+    if (value === true)
+        return EXPLICIT;
+    return { set: true, reason: "invalid", shape: shapeOf(value) };
+}
 /**
  * Classify an already-parsed settings container for the two documented
- * hook-neutralizing flags. Strict `=== true` only: a truthy-but-not-`true`
- * value (`"true"`, `1`), a missing key, or a non-object input is NOT a flag.
- * A false here is a definitive "this source does not set the flag", never an
- * "unknown" — unreadability is decided upstream by the fs probe, not here.
+ * hook-neutralizing flags. A `{ set: false }` here is a definitive "this source
+ * does not set the flag", never an "unknown" — unreadability is decided upstream
+ * by the fs probe, not here, so a non-object input is "not a flag".
  */
 export function scanExecutionFlags(parsed) {
     if (!isPlainObject(parsed)) {
-        return { disableAllHooks: false, allowManagedHooksOnly: false };
+        return { disableAllHooks: NOT_SET, allowManagedHooksOnly: NOT_SET };
     }
     return {
-        disableAllHooks: parsed.disableAllHooks === true,
-        allowManagedHooksOnly: parsed.allowManagedHooksOnly === true,
+        disableAllHooks: classifyFlag(parsed.disableAllHooks),
+        allowManagedHooksOnly: classifyFlag(parsed.allowManagedHooksOnly),
     };
 }
 // Canonical identity (Decision ②)

package/dist/lib/secure-fs-posix.d.ts

@@ -24,8 +24,51 @@ export interface PosixAclAdapter {
     /** Run the bounded, LC_ALL=C ACL tool and decide clean|extended|inconclusive. */
     proveClean(target: string): Promise<SecureResult<void>>;
 }
+/**
+ * The EXACT detail strings the POSIX adapters emit, exported so consumers (the
+ * CLI remediation table) can key off a token instead of string-matching prose.
+ * These values are frozen: changing one changes an observable refusal detail.
+ */
+export declare const ACL_DETAIL: {
+    readonly getfaclAbsent: "getfacl absent";
+    readonly getfaclTimeout: "getfacl timeout";
+    readonly extendedAclEntry: "extended ACL entry";
+    readonly macosLsAbsent: "/bin/ls absent";
+    readonly macosLsTimeout: "ls timeout";
+    readonly macosAclFlag: "ACL present (+ flag)";
+    readonly macosAceListed: "ACE listed";
+};
 export declare function createLinuxAclAdapter(spawn?: SpawnFn): PosixAclAdapter;
 export declare function createMacosAclAdapter(spawn?: SpawnFn): PosixAclAdapter;
+/**
+ * Whether the host's ACL adapter is RESOLVABLE — an install-time capability
+ * question, deliberately separate from the per-target prover above. It never
+ * decides whether a target is safe and never gates a mutation.
+ */
+export type AclCapability = {
+    status: "available";
+    tool: "getfacl" | "/bin/ls";
+} | {
+    status: "absent";
+    tool: "getfacl" | "/bin/ls";
+} | {
+    status: "unknown";
+    tool: string;
+    detail: string;
+} | {
+    status: "not-applicable";
+    tool: "windows-secure-object";
+};
+/**
+ * Probe the ACL adapter READ-ONLY: it resolves and runs a version/list argv and
+ * inspects nothing on disk. It creates, modifies and removes nothing, and its
+ * result NEVER feeds the transactional gate — the prover (`proveClean`) is the
+ * only authority on whether a path is safe, and it stays fail-closed.
+ *
+ * `unknown` (timeout, non-zero exit, unparseable output, unsupported platform)
+ * is honest ignorance: the caller reports it, it never becomes `available`.
+ */
+export declare function probeAclCapability(spawn?: SpawnFn, platform?: NodeJS.Platform): Promise<AclCapability>;
 export declare function createPosixSecureFs(acl: PosixAclAdapter): PlatformSecureFs;
 /**
  * Select the secure filesystem for the host platform. Linux uses the `getfacl`

package/dist/lib/secure-fs-posix.js

@@ -47,6 +47,21 @@ const defaultSpawn = (cmd, args) => new Promise((resolve) => {
         return resolve({ code, stdout: stdout ?? "" });
     });
 });
+// --- stable refusal-detail tokens --------------------------------------------
+/**
+ * The EXACT detail strings the POSIX adapters emit, exported so consumers (the
+ * CLI remediation table) can key off a token instead of string-matching prose.
+ * These values are frozen: changing one changes an observable refusal detail.
+ */
+export const ACL_DETAIL = {
+    getfaclAbsent: "getfacl absent",
+    getfaclTimeout: "getfacl timeout",
+    extendedAclEntry: "extended ACL entry",
+    macosLsAbsent: "/bin/ls absent",
+    macosLsTimeout: "ls timeout",
+    macosAclFlag: "ACL present (+ flag)",
+    macosAceListed: "ACE listed",
+};
 // --- Linux getfacl adapter (Algorithm D) -------------------------------------
 const LINUX_BASE_ENTRY = /^(user|group|other)::/;
 export function createLinuxAclAdapter(spawn = defaultSpawn) {
@@ -60,9 +75,9 @@ export function createLinuxAclAdapter(spawn = defaultSpawn) {
                 target,
             ]);
             if (res.spawnError)
-                return refuse("unsupported-posix-acl", "getfacl absent");
+                return refuse("unsupported-posix-acl", ACL_DETAIL.getfaclAbsent);
             if (res.timedOut)
-                return refuse("unsupported-posix-acl", "getfacl timeout");
+                return refuse("unsupported-posix-acl", ACL_DETAIL.getfaclTimeout);
             if (res.code !== 0) {
                 return refuse("unsupported-posix-acl", `getfacl exit ${res.code}`);
             }
@@ -72,7 +87,7 @@ export function createLinuxAclAdapter(spawn = defaultSpawn) {
                     continue;
                 if (LINUX_BASE_ENTRY.test(line))
                     continue;
-                return refuse("unsupported-posix-acl", "extended ACL entry");
+                return refuse("unsupported-posix-acl", ACL_DETAIL.extendedAclEntry);
             }
             return ok();
         },
@@ -85,24 +100,68 @@ export function createMacosAclAdapter(spawn = defaultSpawn) {
         async proveClean(target) {
             const res = await spawn("/bin/ls", ["-lde", "--", target]);
             if (res.spawnError)
-                return refuse("unsupported-posix-acl", "/bin/ls absent");
+                return refuse("unsupported-posix-acl", ACL_DETAIL.macosLsAbsent);
             if (res.timedOut)
-                return refuse("unsupported-posix-acl", "ls timeout");
+                return refuse("unsupported-posix-acl", ACL_DETAIL.macosLsTimeout);
             if (res.code !== 0) {
                 return refuse("unsupported-posix-acl", `ls exit ${res.code}`);
             }
             const lines = res.stdout.split("\n");
             const modeLine = lines[0] ?? "";
             if (modeLine[10] === "+") {
-                return refuse("unsupported-posix-acl", "ACL present (+ flag)");
+                return refuse("unsupported-posix-acl", ACL_DETAIL.macosAclFlag);
             }
             if (lines.some((line) => MACOS_ACE_LINE.test(line))) {
-                return refuse("unsupported-posix-acl", "ACE listed");
+                return refuse("unsupported-posix-acl", ACL_DETAIL.macosAceListed);
             }
             return ok();
         },
     };
 }
+/**
+ * Probe the ACL adapter READ-ONLY: it resolves and runs a version/list argv and
+ * inspects nothing on disk. It creates, modifies and removes nothing, and its
+ * result NEVER feeds the transactional gate — the prover (`proveClean`) is the
+ * only authority on whether a path is safe, and it stays fail-closed.
+ *
+ * `unknown` (timeout, non-zero exit, unparseable output, unsupported platform)
+ * is honest ignorance: the caller reports it, it never becomes `available`.
+ */
+export async function probeAclCapability(spawn = defaultSpawn, platform = process.platform) {
+    if (platform === "win32") {
+        return { status: "not-applicable", tool: "windows-secure-object" };
+    }
+    if (platform !== "linux" && platform !== "darwin") {
+        return {
+            status: "unknown",
+            tool: platform,
+            detail: `no POSIX ACL adapter for platform ${platform}`,
+        };
+    }
+    const tool = platform === "linux" ? "getfacl" : "/bin/ls";
+    const args = platform === "linux" ? ["--version"] : ["-ld", "/"];
+    const res = await spawn(tool, args);
+    if (res.spawnError)
+        return { status: "absent", tool };
+    if (res.timedOut) {
+        // The argv differs per platform (`getfacl --version` on linux, `/bin/ls -ld /`
+        // on darwin), so the detail names the probe, not a hardcoded flag.
+        return { status: "unknown", tool, detail: `${tool} probe timeout` };
+    }
+    if (res.code !== 0) {
+        return { status: "unknown", tool, detail: `${tool} exit ${res.code}` };
+    }
+    // Linux only: a zero exit whose banner does not name getfacl is a foreign
+    // binary on PATH, not proof of the adapter — report ignorance, not success.
+    if (platform === "linux" && !res.stdout.toLowerCase().includes("getfacl")) {
+        return {
+            status: "unknown",
+            tool,
+            detail: `${tool} --version output unparseable`,
+        };
+    }
+    return { status: "available", tool };
+}
 // --- the POSIX secure filesystem --------------------------------------------
 const DIR_FLAGS = FS.O_DIRECTORY | FS.O_NOFOLLOW | FS.O_RDONLY;
 const CAPTURE_FLAGS = FS.O_NOFOLLOW | FS.O_RDONLY;

package/dist/lib/secure-fs-transaction.js

@@ -286,7 +286,16 @@ export async function runTransaction(input) {
                     errors.push(`STOP: cannot stage rollback for ${entry.path}`);
                     return;
                 }
-                await secureFs.applyExactMode(path.join(entry.dir.path, rName), entry.prior.mode);
+                // Prior-mode restore is BEST-EFFORT (JD-B-003): a chmod miss fails
+                // toward MORE restrictive perms (the 0600 staging mode), so it is not
+                // a security regression and must not halt the rollback — restoring the
+                // prior BYTES matters more than the prior mode. Record an
+                // INFORMATIONAL note (never `STOP:`, which signals a halted rollback)
+                // and continue to the rename.
+                const remoded = await secureFs.applyExactMode(path.join(entry.dir.path, rName), entry.prior.mode);
+                if (!remoded.ok) {
+                    errors.push(`note: restored ${entry.path}; prior-mode restore failed, verify permissions (${remoded.detail ?? remoded.refusal ?? "unknown"})`);
+                }
                 const restored = await secureFs.renameInDir(entry.dir, rName, base);
                 if (!restored.ok) {
                     errors.push(`STOP: cannot restore ${entry.path}; prior payload staged at ${path.join(entry.dir.path, rName)} for manual recovery`);

package/dist/lib/secure-refusal-remediation.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Pure refusal → remediation table for the CLI layer (Linux hardening, Slice A).
+ *
+ * The secure-fs adapters stay PROVERS: they emit stable `SecureRefusal` codes
+ * plus a stable detail token and carry ZERO user copy. This module is the only
+ * place that turns one of those tokens into an actionable next step, so the
+ * proof algorithms and their refusal identities never move when the copy does.
+ *
+ * The table is deliberately narrow. A remediation is emitted ONLY when the user
+ * can actually fix the cause: an unresolvable `getfacl` is fixed by installing
+ * the `acl` package, while a REAL extended ACL (the adapter ran and found a
+ * named-user entry) is not — suggesting a package install there would be
+ * actively misleading. No I/O, no rendering, no Ink.
+ */
+import type { SecureRefusal } from "./secure-fs-transaction.js";
+/** The one actionable line for a host whose POSIX ACL adapter is missing. */
+export declare const ACL_PACKAGE_REMEDIATION = "install the acl package (provides getfacl): apt install acl \u00B7 apk add acl \u00B7 dnf install acl";
+/**
+ * The actionable line for a refusal + detail pair, or `undefined` when nothing
+ * the user can do would change the outcome.
+ */
+export declare function remediationForRefusal(refusal: SecureRefusal, detail?: string): string | undefined;
+/**
+ * The same lookup for an already-rendered refusal MESSAGE (the transaction
+ * flattens `refusal`/`detail` into strings such as `acl /path: getfacl absent`).
+ * Matching is anchored to the message TAIL so prose that merely mentions the
+ * token never triggers a wrong hint.
+ */
+export declare function remediationForMessage(message: string): string | undefined;
+//# sourceMappingURL=secure-refusal-remediation.d.ts.map

package/dist/lib/secure-refusal-remediation.js

@@ -0,0 +1,48 @@
+/**
+ * Pure refusal → remediation table for the CLI layer (Linux hardening, Slice A).
+ *
+ * The secure-fs adapters stay PROVERS: they emit stable `SecureRefusal` codes
+ * plus a stable detail token and carry ZERO user copy. This module is the only
+ * place that turns one of those tokens into an actionable next step, so the
+ * proof algorithms and their refusal identities never move when the copy does.
+ *
+ * The table is deliberately narrow. A remediation is emitted ONLY when the user
+ * can actually fix the cause: an unresolvable `getfacl` is fixed by installing
+ * the `acl` package, while a REAL extended ACL (the adapter ran and found a
+ * named-user entry) is not — suggesting a package install there would be
+ * actively misleading. No I/O, no rendering, no Ink.
+ */
+import { ACL_DETAIL } from "./secure-fs-posix.js";
+/** The one actionable line for a host whose POSIX ACL adapter is missing. */
+export const ACL_PACKAGE_REMEDIATION = "install the acl package (provides getfacl): apt install acl · apk add acl · dnf install acl";
+/** Detail tokens that map to a remediation, keyed by refusal code. */
+const REMEDIATION_TABLE = {
+    "unsupported-posix-acl": {
+        [ACL_DETAIL.getfaclAbsent]: ACL_PACKAGE_REMEDIATION,
+    },
+};
+/**
+ * The actionable line for a refusal + detail pair, or `undefined` when nothing
+ * the user can do would change the outcome.
+ */
+export function remediationForRefusal(refusal, detail) {
+    if (detail === undefined)
+        return undefined;
+    return REMEDIATION_TABLE[refusal]?.[detail];
+}
+/**
+ * The same lookup for an already-rendered refusal MESSAGE (the transaction
+ * flattens `refusal`/`detail` into strings such as `acl /path: getfacl absent`).
+ * Matching is anchored to the message TAIL so prose that merely mentions the
+ * token never triggers a wrong hint.
+ */
+export function remediationForMessage(message) {
+    for (const details of Object.values(REMEDIATION_TABLE)) {
+        for (const [detail, line] of Object.entries(details)) {
+            if (message.endsWith(detail))
+                return line;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=secure-refusal-remediation.js.map

package/dist/ui/App.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { Box } from "ink";
 import React, { useState } from "react";
 import { initProject } from "../commands/init.js";
+import { buildInitOptions } from "./build-init-options.js";
 import CISelector from "./CISelector.js";
 import Header from "./Header.js";
 import HookProfileSelector from "./HookProfileSelector.js";
@@ -80,29 +81,15 @@ export default function App({ dryRun = false, presetStack, presetCI, presetMemor
     };
     const runInit = async (opts) => {
         setStage("running");
-        await initProject({
+        await initProject(buildInitOptions(opts, {
             projectName,
             projectDir,
             stack,
             ciProvider,
             memory,
-            aiSync: opts.aiSync,
-            sdd: opts.sdd,
-            ghagga: opts.ghagga,
-            contextDir: opts.contextDir,
-            claudeMd: opts.claudeMd,
-            securityHooks: opts.securityHooks,
-            hookProfile: opts.hookProfile,
-            // Derived from securityHooks alone — ALL profiles incl. Minimal
-            // install the managed guard when security hooks are enabled.
-            claudePreToolUseGuard: opts.securityHooks,
-            codeGraph: opts.codeGraph,
-            localAi: opts.localAi,
-            dockerDeploy: false,
-            dockerServiceName: "app",
             mock: presetMock,
             dryRun,
-        }, (step) => setSteps((prev) => {
+        }), (step) => setSteps((prev) => {
             const idx = prev.findIndex((s) => s.id === step.id);
             if (idx >= 0) {
                 const next = [...prev];

package/dist/ui/build-init-options.d.ts

@@ -0,0 +1,44 @@
+import type { CIProvider, HookProfile, InitOptions, MemoryOption, Stack } from "../types/index.js";
+/**
+ * Wizard-collected toggles for an init run — the subset the user answers
+ * interactively (or via presets). Mirrors the `runInit` opts parameter.
+ */
+export interface InitOptionsWizardResult {
+    aiSync: boolean;
+    sdd: boolean;
+    contextDir: boolean;
+    claudeMd: boolean;
+    ghagga: boolean;
+    securityHooks: boolean;
+    codeGraph: boolean;
+    localAi: boolean;
+    hookProfile: HookProfile;
+}
+/**
+ * Surrounding context resolved before the wizard finishes — project identity,
+ * stack/CI/memory choices, and run flags (mock/dryRun).
+ */
+export interface InitOptionsContext {
+    projectName: string;
+    projectDir: string;
+    stack: Stack;
+    ciProvider: CIProvider;
+    memory: MemoryOption;
+    mock: boolean;
+    dryRun: boolean;
+}
+/**
+ * Pure mapping from wizard result + surrounding context to the full
+ * {@link InitOptions} contract passed to `initProject`.
+ *
+ * Extracted from the single inline object literal in `App.tsx#runInit` so the
+ * derivation is unit-testable. Behavior-identical: field values must match the
+ * previous inline literal exactly.
+ *
+ * Notably, `claudePreToolUseGuard` is derived from `securityHooks` alone — ALL
+ * hook profiles (including "minimal") install the managed guard when security
+ * hooks are enabled. A regression here silently disables managed-guard
+ * installation, so it is pinned by build-init-options.test.ts.
+ */
+export declare function buildInitOptions(opts: InitOptionsWizardResult, ctx: InitOptionsContext): InitOptions;
+//# sourceMappingURL=build-init-options.d.ts.map

package/dist/ui/build-init-options.js

@@ -0,0 +1,39 @@
+/**
+ * Pure mapping from wizard result + surrounding context to the full
+ * {@link InitOptions} contract passed to `initProject`.
+ *
+ * Extracted from the single inline object literal in `App.tsx#runInit` so the
+ * derivation is unit-testable. Behavior-identical: field values must match the
+ * previous inline literal exactly.
+ *
+ * Notably, `claudePreToolUseGuard` is derived from `securityHooks` alone — ALL
+ * hook profiles (including "minimal") install the managed guard when security
+ * hooks are enabled. A regression here silently disables managed-guard
+ * installation, so it is pinned by build-init-options.test.ts.
+ */
+export function buildInitOptions(opts, ctx) {
+    return {
+        projectName: ctx.projectName,
+        projectDir: ctx.projectDir,
+        stack: ctx.stack,
+        ciProvider: ctx.ciProvider,
+        memory: ctx.memory,
+        aiSync: opts.aiSync,
+        sdd: opts.sdd,
+        ghagga: opts.ghagga,
+        contextDir: opts.contextDir,
+        claudeMd: opts.claudeMd,
+        securityHooks: opts.securityHooks,
+        hookProfile: opts.hookProfile,
+        // Derived from securityHooks alone — ALL profiles incl. Minimal
+        // install the managed guard when security hooks are enabled.
+        claudePreToolUseGuard: opts.securityHooks,
+        codeGraph: opts.codeGraph,
+        localAi: opts.localAi,
+        dockerDeploy: false,
+        dockerServiceName: "app",
+        mock: ctx.mock,
+        dryRun: ctx.dryRun,
+    };
+}
+//# sourceMappingURL=build-init-options.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "javi-forge",
-	"version": "1.33.0",
+	"version": "1.34.1",
 	"description": "Project scaffolding and AI-ready CI bootstrap",
 	"type": "module",
 	"bin": {