javi-forge 1.32.0 → 1.33.0

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,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";
 function renderMutation(verb, result, log, logError) {
@@ -39,23 +42,43 @@ 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)");
+    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}`);
+    }
     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/lib/claude-hook-manager.d.ts

@@ -51,6 +51,7 @@ export interface ClaudeHookDoctorReport {
     coverage: typeof COVERAGE;
     hostResidual: string;
     remediation: readonly string[];
+    execution: ExecutionReport;
 }
 /**
  * Classify the asset into one of nine states from observed bytes only. Never
@@ -66,14 +67,100 @@ 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[];
+}
+/** 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[]>;
+}
+/** Per-source read outcome; never promotes an unobservable source to clear. */
+export type ExecutionSourceProbe = {
+    kind: "clear";
+} | {
+    kind: "blocking";
+    flag: "disableAllHooks" | "allowManagedHooksOnly";
+} | {
+    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;
 }): Promise<ClaudeHookDoctorReport>;
 export interface ClaudeHookMutationResult {
     ok: boolean;

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

@@ -8,11 +8,12 @@
  * Slice-3 seams — Slice 3 GROWS this file, it does not relocate this code.
  */
 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 { runTransaction, } from "./secure-fs-transaction.js";
@@ -200,10 +201,201 @@ const REMEDIATION = {
 function remediationFor(state, component) {
     return REMEDIATION[state]?.replace("$", component);
 }
+/** 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);
+    if (flags.disableAllHooks) {
+        return { kind: "blocking", flag: "disableAllHooks" };
+    }
+    if (flags.allowManagedHooksOnly) {
+        return { kind: "blocking", flag: "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",
+];
+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).
+        if (probe.flag === "allowManagedHooksOnly" && !spec.managed)
+            continue;
+        blockers.push(`policy:${probe.flag}@${spec.label}`);
+    }
+    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}`);
+    }
+    // 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 +432,7 @@ 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 ?? {});
     return {
         healthy,
         settings: {
@@ -261,6 +454,7 @@ export async function doctorClaudePreToolUse(projectDir, options) {
         coverage: COVERAGE,
         hostResidual: HOST_RESIDUAL,
         remediation: [...remediation].sort(),
+        execution,
     };
 }
 async function readManifest() {

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

@@ -40,6 +40,24 @@ 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: boolean;
+    allowManagedHooksOnly: boolean;
+}
+/**
+ * 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.
+ */
+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,22 @@ export function validateSettingsShape(parsed) {
         return false;
     return true;
 }
+/**
+ * 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.
+ */
+export function scanExecutionFlags(parsed) {
+    if (!isPlainObject(parsed)) {
+        return { disableAllHooks: false, allowManagedHooksOnly: false };
+    }
+    return {
+        disableAllHooks: parsed.disableAllHooks === true,
+        allowManagedHooksOnly: parsed.allowManagedHooksOnly === true,
+    };
+}
 // Canonical identity (Decision ②)
 const ASSET_SHA_TOKEN = /^[0-9a-f]{64}$/;
 const VERSION_PATTERN = /^javi-forge-global-pretooluse:v(\d+):sha256:/;

package/package.json

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