javi-forge 1.32.0 → 1.34.0

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

@@ -7,15 +7,18 @@
  * 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, readFile } from "node:fs/promises";
+import { lstat, readdir, readFile } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 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, } from "./claude-hook-settings.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;
@@ -200,10 +203,282 @@ 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") {
+        const base = "/Library/Application Support/ClaudeCode";
+        return {
+            file: `${base}/managed-settings.json`,
+            dropInDir: `${base}/managed-settings.d`,
+        };
+    }
+    if (platform === "win32") {
+        const base = "C:\\Program Files\\ClaudeCode";
+        return {
+            file: `${base}\\managed-settings.json`,
+            dropInDir: `${base}\\managed-settings.d`,
+        };
+    }
+    const base = "/etc/claude-code";
+    return {
+        file: `${base}/managed-settings.json`,
+        dropInDir: `${base}/managed-settings.d`,
+    };
+}
+/**
+ * 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 async function probeExecutionSource(target) {
+    const stat = await lstatNoFollow(target);
+    if (stat.kind === "enoent")
+        return { kind: "clear" };
+    if (stat.kind === "symlink")
+        return { kind: "unknown", reason: "symlink" };
+    if (stat.kind === "non-regular") {
+        return { kind: "unknown", reason: "non-regular" };
+    }
+    if (stat.kind === "error")
+        return { kind: "unknown", reason: stat.detail };
+    const read = await safeReadFile(target, READ_OPTS);
+    if (!read.ok) {
+        if (read.reason === "not-found")
+            return { kind: "clear" };
+        return { kind: "unknown", reason: read.reason };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(read.content);
+    }
+    catch {
+        return { kind: "unknown", reason: "invalid-json" };
+    }
+    const flags = scanExecutionFlags(parsed);
+    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.set) {
+        return blocking("allowManagedHooksOnly", flags.allowManagedHooksOnly);
+    }
+    return { kind: "clear" };
+}
+export async function listManagedDropIns(dir, listDir) {
+    let entries;
+    try {
+        entries = listDir ? await listDir(dir) : await readdir(dir);
+    }
+    catch (error) {
+        const code = error.code;
+        // Only a genuinely-absent directory is "no drop-ins"; every other error
+        // (permission/io/loop/etc.) is an unreadable managed source.
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return { entries: [] };
+        return { unreadable: true, reason: code ?? String(error) };
+    }
+    return {
+        entries: entries
+            .filter((name) => name.endsWith(".json"))
+            .sort()
+            .map((name) => path.join(dir, name)),
+    };
+}
+/** CONSTANT honest limits — always rendered, never gate the status. */
+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;
+    if (value === undefined)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized !== "" && normalized !== "0" && normalized !== "false";
+}
+/**
+ * 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 async function probeExecution(projectDir, componentStates, env = {}) {
+    const platform = env.platform ?? process.platform;
+    const homeDir = env.homeDir ?? os.homedir();
+    const processEnv = env.env ?? process.env;
+    const resolved = resolveManagedSettingsPaths(platform);
+    const managedFile = env.managedFile !== undefined ? env.managedFile : resolved.file;
+    const dropInDir = env.managedDropInDir !== undefined
+        ? env.managedDropInDir
+        : resolved.dropInDir;
+    const specs = [
+        {
+            label: "project",
+            target: path.join(projectDir, ".claude", "settings.json"),
+            managed: false,
+        },
+        {
+            label: "local",
+            target: path.join(projectDir, ".claude", "settings.local.json"),
+            managed: false,
+        },
+        {
+            label: "user",
+            target: path.join(homeDir, ".claude", "settings.json"),
+            managed: false,
+        },
+    ];
+    if (managedFile) {
+        specs.push({ label: "managed", target: managedFile, managed: true });
+    }
+    // A present-but-unenumerable drop-in dir is an `unknown` managed source, NOT
+    // "no drop-ins" — fold it into unknownSources so a blocking drop-in policy we
+    // cannot read can never be mistaken for a clear (false `runnable`) verdict.
+    let dropInDirUnknown;
+    if (dropInDir) {
+        const listing = await listManagedDropIns(dropInDir, env.listDir);
+        if (listing.unreadable) {
+            dropInDirUnknown = `managed:${dropInDir} (${listing.reason})`;
+        }
+        else {
+            for (const target of listing.entries) {
+                specs.push({ label: "managed", target, managed: true });
+            }
+        }
+    }
+    const blockers = [];
+    const unknownSources = [];
+    for (const spec of specs) {
+        const probe = await probeExecutionSource(spec.target);
+        if (probe.kind === "clear")
+            continue;
+        if (probe.kind === "unknown") {
+            unknownSources.push(`${spec.label}:${spec.target} (${probe.reason})`);
+            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}${probe.detail ? ` (${probe.detail})` : ""}`);
+    }
+    if (dropInDirUnknown)
+        unknownSources.push(dropInDirUnknown);
+    // Guard-currency: a not-installed / drifted guard cannot fire, so it blocks.
+    if (componentStates.asset !== "managed-current") {
+        blockers.push(`guard:asset=${componentStates.asset}`);
+    }
+    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)) {
+        unknownSources.push("safe-mode:CLAUDE_CODE_SAFE_MODE (observed in doctor process only)");
+    }
+    const status = blockers.length > 0
+        ? "blocked"
+        : unknownSources.length > 0
+            ? "inconclusive"
+            : "runnable";
+    return {
+        status,
+        blockers,
+        unknownSources,
+        residual: [...EXECUTION_RESIDUAL],
+    };
+}
 /**
  * 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 async function doctorClaudePreToolUse(projectDir, options) {
     const manifest = options?.manifest ?? (await readManifest());
@@ -240,6 +515,25 @@ export async function doctorClaudePreToolUse(projectDir, options) {
         signals.matcherExact &&
         signals.commandShapeExact &&
         node.satisfiesMinimum;
+    // 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: {
@@ -261,6 +555,12 @@ export async function doctorClaudePreToolUse(projectDir, options) {
         coverage: COVERAGE,
         hostResidual: HOST_RESIDUAL,
         remediation: [...remediation].sort(),
+        execution,
+        nodeOnPath,
+        installCapability: {
+            acl: aclCapability,
+            ...(aclRemediation ? { remediation: aclRemediation } : {}),
+        },
     };
 }
 async function readManifest() {
@@ -269,6 +569,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}` : ""}`;
@@ -400,7 +718,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 {
@@ -408,6 +737,7 @@ export async function _run(projectDir, mode, options, deps) {
             changed: [],
             backups: [],
             errors: ["windows-secure-object-unavailable"],
+            warnings,
             report: await doctor(),
         };
     }
@@ -430,6 +760,7 @@ export async function _run(projectDir, mode, options, deps) {
             changed: [],
             backups: [],
             errors: [reason],
+            warnings,
             report: await doctor(),
         };
     }
@@ -440,6 +771,7 @@ export async function _run(projectDir, mode, options, deps) {
             changed: [],
             backups: [],
             errors: [],
+            warnings,
             report: await doctor(),
         };
     }
@@ -478,6 +810,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

@@ -40,6 +40,38 @@ export declare function isPlainObject(value: unknown): value is Record<string, u
  * else is malformed.
  */
 export declare function validateSettingsShape(parsed: unknown): boolean;
+/**
+ * The two documented scalar flags a settings source can set that neutralize the
+ * managed hook. `disableAllHooks: true` at ANY source is a blocker; the
+ * source→blocker mapping for `allowManagedHooksOnly` (managed-only) lives in the
+ * manager, which knows each source's provenance.
+ */
+export interface ExecutionFlagScan {
+    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. 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;
 /**
  * Replace the trailing 64-hex asset SHA token in a managed `statusMessage` with
  * the fixed placeholder so settings identity is invariant under asset rotation.

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

@@ -31,6 +31,46 @@ 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. 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: NOT_SET, allowManagedHooksOnly: NOT_SET };
+    }
+    return {
+        disableAllHooks: classifyFlag(parsed.disableAllHooks),
+        allowManagedHooksOnly: classifyFlag(parsed.allowManagedHooksOnly),
+    };
+}
 // Canonical identity (Decision ②)
 const ASSET_SHA_TOKEN = /^[0-9a-f]{64}$/;
 const VERSION_PATTERN = /^javi-forge-global-pretooluse:v(\d+):sha256:/;

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;