javi-forge 1.32.0 → 1.34.0

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.d.ts

@@ -4,11 +4,14 @@
  * three lib fns to human output + exit codes; it adds NO new security logic and
  * never touches `runTransaction`/secure-fs directly.
  *
- * Honest-execution constraint (spec Requirement "…never fabricates execution
- * status"): the doctor renderer reports effective execution as `inconclusive`
- * only. It MUST NOT print, imply, or default to `RUNNABLE` — real host-probing
- * is Slice 4b. Exit 2 (INCONCLUSIVE gate semantics) is likewise reserved for 4b
- * and never emitted here.
+ * Honest-execution gate (Slice 4b): the doctor renderer prints the real
+ * `execution` verdict computed by the library — `runnable`, `blocked`, or
+ * `inconclusive` — plus its `blockers`, `unknownSources`, and the constant
+ * `residual` caveats, in committed stable order. The doctor exit code follows
+ * `execution.status` (runnable → 0, blocked → 1, inconclusive → 2), independent
+ * of `report.healthy`. The renderer never fabricates `runnable`: the library
+ * only reports it when every relevant local source read clear and the guard is
+ * current.
  */
 import { doctorClaudePreToolUse, installClaudePreToolUse, repairClaudePreToolUse } from "../lib/claude-hook-manager.js";
 export type ClaudeHookSub = "install" | "doctor" | "repair";
@@ -24,7 +27,8 @@ export interface ClaudeHookCmdDeps {
  * Run one Claude-hook subcommand against `projectDir`. Returns the process exit
  * code (the dispatcher calls `process.exit`, not this fn):
  *   - install/repair: 0 when `ok`, 1 on refusal/failure.
- *   - doctor: always 0 (informational).
+ *   - doctor: follows `execution.status` — runnable → 0, blocked → 1,
+ *     inconclusive → 2.
  */
 export declare function runClaudeHookCommand(sub: ClaudeHookSub, projectDir: string, opts: {
     force?: boolean;

package/dist/commands/claude-hooks.js

@@ -4,13 +4,28 @@
  * three lib fns to human output + exit codes; it adds NO new security logic and
  * never touches `runTransaction`/secure-fs directly.
  *
- * Honest-execution constraint (spec Requirement "…never fabricates execution
- * status"): the doctor renderer reports effective execution as `inconclusive`
- * only. It MUST NOT print, imply, or default to `RUNNABLE` — real host-probing
- * is Slice 4b. Exit 2 (INCONCLUSIVE gate semantics) is likewise reserved for 4b
- * and never emitted here.
+ * Honest-execution gate (Slice 4b): the doctor renderer prints the real
+ * `execution` verdict computed by the library — `runnable`, `blocked`, or
+ * `inconclusive` — plus its `blockers`, `unknownSources`, and the constant
+ * `residual` caveats, in committed stable order. The doctor exit code follows
+ * `execution.status` (runnable → 0, blocked → 1, inconclusive → 2), independent
+ * of `report.healthy`. The renderer never fabricates `runnable`: the library
+ * only reports it when every relevant local source read clear and the guard is
+ * 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`);
@@ -27,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) {
@@ -39,23 +62,62 @@ 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})`);
-    // Honest stub: 4a cannot confirm the guard is live. Never RUNNABLE.
-    log("  execution: inconclusive (effective-execution probe deferred to 4b)");
+    // 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) {
+        log("  blockers:");
+        for (const b of execution.blockers)
+            log(`    - ${b}`);
+    }
+    if (execution.unknownSources.length > 0) {
+        log("  unknown-sources:");
+        for (const u of execution.unknownSources)
+            log(`    - ${u}`);
+    }
+    if (execution.residual.length > 0) {
+        log("  execution-residual:");
+        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:");
         for (const r of report.remediation)
             log(`    - ${r}`);
     }
-    // Doctor is informational, not a gate — always exit 0 (spec Scenario
-    // "Doctor reports component health").
+    // The doctor exit code follows the effective-execution verdict, independent
+    // of component health: runnable → 0, blocked → 1, inconclusive → 2.
+    if (execution.status === "blocked")
+        return 1;
+    if (execution.status === "inconclusive")
+        return 2;
     return 0;
 }
 /**
  * Run one Claude-hook subcommand against `projectDir`. Returns the process exit
  * code (the dispatcher calls `process.exit`, not this fn):
  *   - install/repair: 0 when `ok`, 1 on refusal/failure.
- *   - doctor: always 0 (informational).
+ *   - doctor: follows `execution.status` — runnable → 0, blocked → 1,
+ *     inconclusive → 2.
  */
 export async function runClaudeHookCommand(sub, projectDir, opts, deps = {}) {
     const log = deps.log ?? ((m) => console.log(m));

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/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 {
@@ -51,6 +52,24 @@ export interface ClaudeHookDoctorReport {
     coverage: typeof COVERAGE;
     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
@@ -66,14 +85,128 @@ export declare function detectNode(nodeVersion: string | undefined): {
     version?: string;
     satisfiesMinimum: boolean;
 };
+/**
+ * The honest effective-execution verdict. `status` is derived by precedence
+ * (blocked > inconclusive > runnable); `runnable` is reached only when every
+ * relevant local source read clear AND the managed guard is current. `residual`
+ * carries CONSTANT honest caveats (server-delivered policy, session safe-mode)
+ * that are always shown but never gate the status — otherwise `runnable` would
+ * be unreachable.
+ */
+export interface ExecutionReport {
+    status: "runnable" | "blocked" | "inconclusive";
+    blockers: string[];
+    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;
+    homeDir?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Override the managed OS file (null → no managed file at all). */
+    managedFile?: string | null;
+    /** Override the managed drop-in dir (null → no drop-ins). */
+    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 = {
+    kind: "clear";
+} | {
+    kind: "blocking";
+    flag: "disableAllHooks" | "allowManagedHooksOnly";
+    /** Present only for a PRESENT-but-INVALID value; names the observed shape. */
+    detail?: string;
+} | {
+    kind: "unknown";
+    reason: string;
+};
+/** The already-computed component states the guard-currency check consumes. */
+export interface ExecutionComponentStates {
+    asset: ClaudeHookComponentState;
+    settings: ClaudeHookComponentState;
+}
+export interface ManagedSettingsPaths {
+    file: string;
+    dropInDir: string;
+}
+/** Static managed-settings locations per OS (no fs). WSL reports `linux`. */
+export declare function resolveManagedSettingsPaths(platform: NodeJS.Platform): ManagedSettingsPaths;
+/**
+ * Probe one settings source path for the two documented hook-neutralizing
+ * flags. Fail-closed: only a genuinely-absent path or a cleanly-parsed source
+ * with no flag is `clear`; a symlink, non-regular path, permission/io error,
+ * oversized/binary content, or malformed JSON is `unknown` (unreadable ≠
+ * absent), never `clear`. `disableAllHooks` is preferred over
+ * `allowManagedHooksOnly` when both are set (the former blocks at any source).
+ */
+export declare function probeExecutionSource(target: string): Promise<ExecutionSourceProbe>;
+/**
+ * Confined readdir result of the managed drop-in dir, fail-closed and mirroring
+ * `probeExecutionSource`'s errno classification: a genuinely-absent directory
+ * (ENOENT/ENOTDIR) is the ONLY empty/clear case, so it yields `{ entries: [] }`
+ * (no drop-ins). ANY other readdir failure (EACCES/EIO/ELOOP/…) means the
+ * directory is present-but-unenumerable and MUST NOT be treated as empty — it
+ * yields `{ unreadable: true }` so the caller can degrade the verdict, never
+ * silently report "no drop-ins" (a false `runnable`).
+ */
+export type ManagedDropInListing = {
+    unreadable?: false;
+    entries: string[];
+} | {
+    unreadable: true;
+    reason: string;
+};
+export declare function listManagedDropIns(dir: string, listDir?: (dir: string) => Promise<string[]>): Promise<ManagedDropInListing>;
+/**
+ * The fail-closed effective-execution verdict. Gathers all sources in stable
+ * order (project, local, user, managed OS file, drop-ins sorted), classifies
+ * each with `probeExecutionSource`, applies the managed-only inertness of
+ * `allowManagedHooksOnly` (blocks only from a managed source — hooks MERGE
+ * elsewhere), folds in the guard-currency blocker and the doctor-process
+ * safe-mode observation, then resolves by precedence
+ * (`blockers` first, then `unknownSources`, else `runnable`). An `unknown` is
+ * NEVER promoted to `runnable`.
+ */
+export declare function probeExecution(projectDir: string, componentStates: ExecutionComponentStates, env?: ExecutionProbeEnv): Promise<ExecutionReport>;
 /**
  * Assemble the read-only component-level doctor report (no writes). `healthy` is
  * exactly: both components `managed-current`, matcher and command shape exact,
  * Node `>=22`. `assetSettingsConsistent` is a reported advisory, NOT part of it.
+ * The `execution` verdict is INDEPENDENT of `healthy`.
  */
 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;
@@ -81,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 {
@@ -89,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: {