javi-forge 1.35.1 → 1.36.0

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

@@ -0,0 +1,531 @@
+/**
+ * Codex PreToolUse ownership manager (agent-agnostic slice 2). Installs the
+ * SAME shipped SkillGuard `.mjs` asset as a Codex `PreToolUse` hook by writing
+ * `~/.codex/hooks.json` + setting `[features] hooks = true` in
+ * `~/.codex/config.toml`, through the identical secure-fs transaction the Claude
+ * installer uses (no weaker path). It NEVER modifies the guard asset, the pure
+ * `evaluate*` engine, or Claude's observable behavior.
+ *
+ * TRUST (highest-risk surface — engram id 15743, codex-cli 0.147.0, verified
+ * live 2026-08-18): codex hooks are stable + default-ON, but each hook needs a
+ * `trusted_hash` recorded in `config.toml` under
+ * `[hooks.state."<abs-hook-path>:pre_tool_use:0:0"]`; an UNTRUSTED hook is
+ * SILENTLY SKIPPED unless `--dangerously-bypass-hook-trust`. There is NO
+ * `codex hooks trust` subcommand (confirmed: `codex --help` has no `hooks`
+ * command). So we DO NOT compute-and-write a trusted_hash we cannot prove
+ * reproducible (a wrong-but-present hash would leave the hook skipped while
+ * making doctor believe it is trusted — the exact fail-open theater this arc
+ * exists to kill). Instead: install writes the files + REPORTS the trust step,
+ * and the doctor DETECTS the missing trust entry and reports `blocked`
+ * (untrusted = NOT running).
+ *
+ * STALE-HASH INVALIDATION: the trust key path is STABLE across upgrades, so a
+ * rewrite of hooks.json (asset/command/timeout change) leaves the recorded
+ * `trusted_hash` stale — Codex silently skips the hook while the header
+ * persists (doctor would wrongly stay `trusted`). So whenever install/repair
+ * REWRITES the managed hooks.json, it REMOVES our `[hooks.state."<hooksFile>:*"]`
+ * table(s) in the same transactional config write (foreign rows untouched),
+ * reverting the doctor to `untrusted → blocked` until the user re-approves. An
+ * idempotent no-op install (unchanged hook content) never touches the table.
+ */
+import os from "node:os";
+import path from "node:path";
+import { CLAUDE_HOOK_ASSETS_DIR } from "../constants.js";
+import { ASSET_NAME } from "./__fixtures__/claude-hook-ownership.js";
+import { classifyAssetState, detectNode, probeNodeOnPath, } from "./claude-hook-manager.js";
+import { isPlainObject, validateSettingsShape, } 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";
+const NODE_MINIMUM_MAJOR = 22;
+const CODEX_TIMEOUT = 30;
+/**
+ * Matcher covering the two tools the guard must gate under Codex: `Bash`
+ * (sensitive-command protection, drop-in) and `apply_patch` (managed-config
+ * file-write protection, the S1 shim). PreToolUse fires on all tools; the
+ * matcher narrows delivery to what we evaluate. (Confirmed against a real
+ * codex-cli 0.147.0 run during S2.8.)
+ */
+const CODEX_MATCHER = "Bash|apply_patch";
+const READ_OPTS = {
+    maxBytes: 1024 * 1024,
+    hardRejectOverBytes: 1024 * 1024,
+    maxLineLength: Number.POSITIVE_INFINITY,
+};
+/** The shipped, in-package guard asset the Codex hook references by ABSOLUTE path. */
+export const SHIPPED_CODEX_ASSET = path.join(CLAUDE_HOOK_ASSETS_DIR, ASSET_NAME);
+/** Resolve `~/.codex/{hooks.json,config.toml}` for a given home directory. */
+export function codexConfigPaths(homeDir) {
+    const codexDir = path.join(homeDir, ".codex");
+    return {
+        codexDir,
+        hooksFile: path.join(codexDir, "hooks.json"),
+        configFile: path.join(codexDir, "config.toml"),
+    };
+}
+/** The exact `command` string the managed Codex hook runs (single-string form). */
+export function expectedCodexCommand(assetPath) {
+    return `node ${assetPath} --agent=codex`;
+}
+/** The interactive step that establishes hook trust (there is no non-interactive subcommand). */
+export function codexTrustGrantCommand(hooksFile) {
+    return `run codex once and APPROVE the hook when prompted (records trust for ${hooksFile} in ~/.codex/config.toml), or pass --dangerously-bypass-hook-trust for vetted automation`;
+}
+// =============================================================================
+// Pure config.toml helpers (minimal, targeted, fail-closed) — no TOML dep
+// =============================================================================
+const TABLE_HEADER = /^\s*\[([^[\]]+)\]\s*(?:#.*)?$/;
+const HOOKS_LINE = /^\s*hooks\s*=\s*(true|false)\b/;
+/** Read the `[features] hooks` flag: "true" | "false" | "absent". */
+export function parseFeaturesHooks(text) {
+    let inFeatures = false;
+    for (const line of text.split(/\r?\n/)) {
+        const header = TABLE_HEADER.exec(line);
+        if (header) {
+            inFeatures = header[1].trim() === "features";
+            continue;
+        }
+        if (inFeatures) {
+            const m = HOOKS_LINE.exec(line);
+            if (m)
+                return m[1] === "true" ? "true" : "false";
+        }
+    }
+    return "absent";
+}
+/**
+ * True when `config.toml` records a trust table for THIS hook path, i.e. a
+ * `[hooks.state."<hooksFile>:pre_tool_use:0:0"]` header. Fail-closed: a trust
+ * entry for a different path does not count.
+ *
+ * NOTE (fail-open the arc kills): presence of the header is NOT proof the hook
+ * is still trusted — Codex records a `trusted_hash` under it, and a hook whose
+ * content was rewritten (e.g. an asset/command/timeout upgrade) has a STALE hash
+ * → Codex silently skips it and re-prompts. We cannot recompute Codex's hash to
+ * compare here, so instead the installer INVALIDATES this table whenever it
+ * rewrites the managed hooks.json (see `removeCodexTrustEntries`), reverting the
+ * doctor to `untrusted → blocked` until the user re-approves in codex.
+ */
+export function hasCodexTrustEntry(text, hooksFile) {
+    const needle = `${hooksFile}:pre_tool_use:0:0`;
+    for (const line of text.split(/\r?\n/)) {
+        const header = TABLE_HEADER.exec(line);
+        if (!header)
+            continue;
+        const inner = header[1].trim();
+        if (inner.startsWith("hooks.state.") && inner.includes(needle))
+            return true;
+    }
+    return false;
+}
+/**
+ * Remove every `[hooks.state."<hooksFile>:*"]` table (header + body lines) keyed
+ * on OUR managed hooks.json path, preserving all other content — including
+ * FOREIGN `hooks.state` rows for other hooks files. Used to invalidate a now-
+ * stale `trusted_hash` when the managed hooks.json content is rewritten: the
+ * trust-key path is stable across upgrades, so a rewritten hook keeps its old
+ * (now wrong) recorded hash and would be silently skipped by Codex while the
+ * header persisted. Dropping the table forces the doctor back to `untrusted`
+ * until the user re-approves the hook in codex.
+ */
+export function removeCodexTrustEntries(text, hooksFile) {
+    // Match the quoted path prefix so a path that merely has ours as a string
+    // prefix (a different file) is never removed.
+    const needle = `"${hooksFile}:`;
+    const lines = text.split(/\r?\n/);
+    const kept = [];
+    let dropping = false;
+    for (const line of lines) {
+        const header = TABLE_HEADER.exec(line);
+        if (header) {
+            const inner = header[1].trim();
+            dropping = inner.startsWith("hooks.state.") && inner.includes(needle);
+            if (dropping)
+                continue;
+            kept.push(line);
+            continue;
+        }
+        if (dropping)
+            continue;
+        kept.push(line);
+    }
+    return kept.join("\n");
+}
+/**
+ * Ensure `[features] hooks = true`, preserving all other content and idempotent
+ * when already true. Only ever INSERTS a line or flips a `hooks = false` inside
+ * `[features]`, so it can never corrupt unrelated TOML.
+ */
+export function mergeFeaturesHooksTrue(text) {
+    const current = parseFeaturesHooks(text);
+    if (current === "true")
+        return text;
+    const lines = text.split(/\r?\n/);
+    // Flip an existing `hooks = false` inside [features].
+    if (current === "false") {
+        let inFeatures = false;
+        for (let i = 0; i < lines.length; i++) {
+            const header = TABLE_HEADER.exec(lines[i]);
+            if (header) {
+                inFeatures = header[1].trim() === "features";
+                continue;
+            }
+            if (inFeatures && HOOKS_LINE.exec(lines[i])) {
+                lines[i] = "hooks = true";
+                return lines.join("\n");
+            }
+        }
+    }
+    // [features] exists but has no hooks line → insert right after the header.
+    for (let i = 0; i < lines.length; i++) {
+        const header = TABLE_HEADER.exec(lines[i]);
+        if (header && header[1].trim() === "features") {
+            lines.splice(i + 1, 0, "hooks = true");
+            return lines.join("\n");
+        }
+    }
+    // No [features] table at all → append one.
+    const base = text.length === 0 ? "" : text.endsWith("\n") ? text : `${text}\n`;
+    return `${base}[features]\nhooks = true\n`;
+}
+// =============================================================================
+// hooks.json classification (reuses the settings-schema validators)
+// =============================================================================
+const CODEX_CMD_RE = /(?:^|\s)node\s+\S*javi-forge-skillguard-pre-tool-use\.mjs\s+--agent=codex(?:\s|$)/;
+/** Every `PreToolUse` handler across all groups, in order. */
+function preToolUseHandlers(value) {
+    const hooks = isPlainObject(value) ? value.hooks : undefined;
+    const groups = isPlainObject(hooks) && Array.isArray(hooks.PreToolUse)
+        ? hooks.PreToolUse
+        : [];
+    const handlers = [];
+    for (const group of groups) {
+        const list = isPlainObject(group) && Array.isArray(group.hooks) ? group.hooks : [];
+        for (const h of list)
+            if (isPlainObject(h))
+                handlers.push(h);
+    }
+    return handlers;
+}
+/**
+ * Classify `hooks.json`. Reuses `validateSettingsShape` (the SAME settings-schema
+ * validator the Claude classifier uses — the Codex hooks.json schema is
+ * identical) and recognizes our managed handler by its exact command string.
+ *   - malformed        → not a valid hooks container
+ *   - managed-current  → our exact command present
+ *   - released-outdated→ our guard present but at a stale asset path
+ *   - foreign          → other PreToolUse handlers, none of them ours
+ *   - absent           → no PreToolUse handlers at all (installable)
+ */
+export function classifyCodexHooksJson(value, expectedCommand) {
+    if (!validateSettingsShape(value))
+        return { state: "malformed" };
+    const handlers = preToolUseHandlers(value);
+    const ours = handlers.filter((h) => h.type === "command" &&
+        typeof h.command === "string" &&
+        CODEX_CMD_RE.test(h.command));
+    if (ours.some((h) => h.command === expectedCommand)) {
+        return { state: "managed-current" };
+    }
+    if (ours.length > 0)
+        return { state: "released-outdated", detail: "stale-path" };
+    if (handlers.length > 0)
+        return { state: "foreign", detail: "no-managed-hook" };
+    return { state: "absent" };
+}
+/** Build the fresh managed hooks.json container for a given asset path. */
+function buildCodexHooksContainer(assetPath) {
+    return {
+        hooks: {
+            PreToolUse: [
+                {
+                    matcher: CODEX_MATCHER,
+                    hooks: [
+                        {
+                            type: "command",
+                            command: expectedCodexCommand(assetPath),
+                            timeout: CODEX_TIMEOUT,
+                        },
+                    ],
+                },
+            ],
+        },
+    };
+}
+/**
+ * Merge our managed group into an existing container: drop any prior managed
+ * groups (ours, by command regex) and append a fresh one, preserving every
+ * foreign group. A fresh install (no container) yields the clean container.
+ */
+function mergeCodexHooks(existing, assetPath) {
+    if (!isPlainObject(existing))
+        return buildCodexHooksContainer(assetPath);
+    const container = structuredClone(existing);
+    if (!isPlainObject(container.hooks))
+        container.hooks = {};
+    const hooks = container.hooks;
+    const groups = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
+    const kept = groups.filter((group) => {
+        const list = isPlainObject(group) && Array.isArray(group.hooks) ? group.hooks : [];
+        const isOurs = list.some((h) => isPlainObject(h) &&
+            h.type === "command" &&
+            typeof h.command === "string" &&
+            CODEX_CMD_RE.test(h.command));
+        return !isOurs;
+    });
+    const fresh = buildCodexHooksContainer(assetPath).hooks;
+    hooks.PreToolUse = [...kept, ...fresh.PreToolUse];
+    return container;
+}
+const EXECUTION_RESIDUAL = [
+    'the installed hook is command-form (command: "node …"): node is resolved from Codex\'s PATH, which this process cannot observe — the node-on-PATH row is a heuristic proxy, never proof the guard will spawn',
+    "an untrusted hook is silently skipped by Codex unless run with --dangerously-bypass-hook-trust; trust is recorded in ~/.codex/config.toml [hooks.state] and is not settable non-interactively",
+    "a fresh install OR any upgrade that rewrites hooks.json invalidates the recorded trust hash (it would otherwise go stale and be silently skipped) — you MUST re-approve the hook in codex before it runs again",
+];
+async function readText(target) {
+    const read = await safeReadFile(target, READ_OPTS);
+    if (read.ok)
+        return { ok: true, text: read.content };
+    return { ok: false, reason: read.reason };
+}
+async function readManifest() {
+    const read = await safeReadFile(path.join(CLAUDE_HOOK_ASSETS_DIR, "manifest.json"), READ_OPTS);
+    if (!read.ok)
+        throw new Error(`unreadable claude-hooks manifest: ${read.reason}`);
+    return JSON.parse(read.content);
+}
+export async function doctorCodexPreToolUse(homeDir = os.homedir(), options = {}) {
+    const manifest = options.manifest ?? (await readManifest());
+    const assetPath = options.assetPath ?? SHIPPED_CODEX_ASSET;
+    const { hooksFile, configFile } = codexConfigPaths(homeDir);
+    const expectedCommand = expectedCodexCommand(assetPath);
+    // hooks.json registration.
+    const hooksRead = await readText(hooksFile);
+    let hooksJson;
+    if (!hooksRead.ok) {
+        hooksJson =
+            hooksRead.reason === "not-found"
+                ? { state: "absent" }
+                : { state: "non-regular", detail: hooksRead.reason };
+    }
+    else {
+        try {
+            hooksJson = classifyCodexHooksJson(JSON.parse(hooksRead.text), expectedCommand);
+        }
+        catch {
+            hooksJson = { state: "malformed", detail: "invalid-json" };
+        }
+    }
+    // config.toml features + trust.
+    const configRead = await readText(configFile);
+    const configReadable = configRead.ok || configRead.reason === "not-found";
+    const configText = configRead.ok ? configRead.text : "";
+    const featuresHooks = configRead.ok
+        ? parseFeaturesHooks(configText)
+        : "absent";
+    const trusted = configRead.ok && hasCodexTrustEntry(configText, hooksFile);
+    // asset currency (SAME shipped asset, hashed against the manifest).
+    const claudeManifest = {
+        asset: manifest.asset,
+        settingsEntries: { current: null, historical: [] },
+    };
+    const asset = await classifyAssetState(assetPath, claudeManifest);
+    const node = detectNode(options.nodeVersion ?? process.versions.node);
+    const nodeOnPath = await (options.nodeProbe ?? probeNodeOnPath)();
+    const blockers = [];
+    const unknownSources = [];
+    if (!configReadable)
+        blockers.push("config:unreadable");
+    if (featuresHooks === "false")
+        blockers.push("policy:features.hooks=false");
+    // THE fail-open guard: an untrusted hook is silently skipped → NOT running.
+    if (!trusted)
+        blockers.push("trust:untrusted (hook is silently skipped)");
+    if (asset.state !== "managed-current")
+        blockers.push(`guard:asset=${asset.state}`);
+    if (hooksJson.state !== "managed-current") {
+        blockers.push(`registration:hooks.json=${hooksJson.state}`);
+    }
+    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})`);
+    }
+    const status = blockers.length > 0
+        ? "blocked"
+        : unknownSources.length > 0
+            ? "inconclusive"
+            : "runnable";
+    const remediation = [];
+    if (hooksJson.state === "absent" || asset.state !== "managed-current") {
+        remediation.push("install the codex guard with: javi-forge hooks install codex");
+    }
+    if (!trusted)
+        remediation.push(codexTrustGrantCommand(hooksFile));
+    if (featuresHooks === "false") {
+        remediation.push("remove `[features] hooks = false` from ~/.codex/config.toml");
+    }
+    if (!node.satisfiesMinimum)
+        remediation.push("install Node 22 or newer");
+    return {
+        healthy: status === "runnable",
+        hooksJson,
+        config: { featuresHooks, readable: configReadable },
+        asset: { state: asset.state, sha256: asset.sha256 },
+        node,
+        nodeOnPath,
+        execution: {
+            status,
+            blockers,
+            unknownSources,
+            residual: [...EXECUTION_RESIDUAL],
+        },
+        trust: {
+            state: trusted ? "trusted" : "untrusted",
+            grantCommand: codexTrustGrantCommand(hooksFile),
+        },
+        remediation: [...new Set(remediation)],
+    };
+}
+function serialize(container) {
+    return Buffer.from(`${JSON.stringify(container, null, 2)}\n`, "utf8");
+}
+export async function _runCodex(homeDir, _mode, _options, deps) {
+    const manifest = deps.manifest ?? (await readManifest());
+    const platform = deps.platform ?? process.platform;
+    const secureFs = deps.secureFs !== undefined ? deps.secureFs : selectSecureFs(platform);
+    const clock = deps.clock ?? (() => new Date());
+    const nonce = deps.nonce ??
+        (() => Math.random().toString(16).slice(2, 10).padEnd(8, "0"));
+    const assetPath = deps.assetPath ?? SHIPPED_CODEX_ASSET;
+    const { codexDir, hooksFile, configFile } = codexConfigPaths(homeDir);
+    const expectedCommand = expectedCodexCommand(assetPath);
+    const nodeOnPath = await (deps.nodeProbe ?? probeNodeOnPath)();
+    const doctor = () => doctorCodexPreToolUse(homeDir, {
+        manifest,
+        assetPath,
+        nodeProbe: async () => nodeOnPath,
+    });
+    if (!secureFs) {
+        return {
+            ok: false,
+            changed: [],
+            backups: [],
+            errors: ["windows-secure-object-unavailable"],
+            warnings: [],
+            report: await doctor(),
+        };
+    }
+    // Classify current state.
+    const hooksRead = await readText(hooksFile);
+    const hooksExisted = hooksRead.ok;
+    let hooksState;
+    if (!hooksRead.ok) {
+        hooksState =
+            hooksRead.reason === "not-found"
+                ? { state: "absent" }
+                : { state: "non-regular", detail: hooksRead.reason };
+    }
+    else {
+        try {
+            hooksState = classifyCodexHooksJson(JSON.parse(hooksRead.text), expectedCommand);
+        }
+        catch {
+            hooksState = { state: "malformed", detail: "invalid-json" };
+        }
+    }
+    if (hooksState.state === "malformed" || hooksState.state === "non-regular") {
+        return {
+            ok: false,
+            changed: [],
+            backups: [],
+            errors: [
+                `refuse hooks.json in state ${hooksState.state} — manual review`,
+            ],
+            warnings: [],
+            report: await doctor(),
+        };
+    }
+    const configRead = await readText(configFile);
+    const configExisted = configRead.ok;
+    const configText = configRead.ok ? configRead.text : "";
+    // Build desired bytes (null = no change for that component).
+    const hooksDesired = hooksState.state === "managed-current"
+        ? null
+        : serialize(mergeCodexHooks(hooksRead.ok ? JSON.parse(hooksRead.text) : undefined, assetPath));
+    // When the managed hooks.json content changes, any recorded trust hash for
+    // OUR hooks path is now stale — Codex would silently skip the rewritten hook
+    // while the header persisted. Invalidate that trust table in the SAME write
+    // so the doctor honestly reverts to `untrusted → blocked` until re-approval.
+    // An idempotent no-op install (hook content unchanged) leaves trust intact.
+    const hookContentChanged = hooksDesired !== null;
+    let nextConfig = configText;
+    if (hookContentChanged) {
+        nextConfig = removeCodexTrustEntries(nextConfig, hooksFile);
+    }
+    nextConfig = mergeFeaturesHooksTrue(nextConfig);
+    const configDesired = configExisted && nextConfig === configText
+        ? null
+        : Buffer.from(nextConfig, "utf8");
+    // Untrusted-after-install warning (report-the-trust-step).
+    const warnings = [
+        `the codex hook is installed but NOT yet trusted — ${codexTrustGrantCommand(hooksFile)}`,
+    ];
+    if (hooksDesired === null && configDesired === null) {
+        return {
+            ok: true,
+            changed: [],
+            backups: [],
+            errors: [],
+            warnings,
+            report: await doctor(),
+        };
+    }
+    // `repair --force` mirrors Claude's force semantics: replace the managed file
+    // after capturing a persistent backup of its prior content. It only has teeth
+    // on a component that both PRE-EXISTED and is being rewritten this run.
+    const forced = _mode === "repair" && _options.force === true;
+    const components = [
+        {
+            path: hooksFile,
+            desired: hooksDesired,
+            capturePrior: hooksExisted && hooksDesired !== null,
+            forceBackup: forced && hooksExisted && hooksDesired !== null,
+            wasAbsent: !hooksExisted,
+        },
+        {
+            path: configFile,
+            desired: configDesired,
+            capturePrior: configExisted && configDesired !== null,
+            forceBackup: forced && configExisted && configDesired !== null,
+            wasAbsent: !configExisted,
+        },
+    ];
+    const tx = await runTransaction({
+        secureFs,
+        clock,
+        nonce,
+        projectDir: homeDir,
+        layout: { containers: [codexDir], components },
+    });
+    return {
+        ok: tx.ok,
+        changed: tx.committed,
+        backups: tx.backups,
+        errors: tx.errors,
+        warnings,
+        report: await doctor(),
+    };
+}
+export function installCodexPreToolUse(homeDir = os.homedir()) {
+    return _runCodex(homeDir, "install", {}, {});
+}
+export function repairCodexPreToolUse(homeDir = os.homedir(), options) {
+    return _runCodex(homeDir, "repair", options ?? {}, {});
+}
+//# sourceMappingURL=codex-hook-manager.js.map

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

@@ -139,13 +139,33 @@ export interface TransactionComponent {
     /** True when the target did not exist before this op (rollback = unlink). */
     wasAbsent: boolean;
 }
+/**
+ * Optional non-Claude container topology (Codex adapter, agnostic slice 2). When
+ * present it FULLY REPLACES the default `.claude`/`.claude/hooks` + [asset,settings]
+ * wiring; every proof primitive (ancestor gate, managed-container proof,
+ * capture/stage/commit/rollback) runs unchanged over the supplied dirs/components.
+ * When absent, the transaction behaves byte-identically to before this seam.
+ */
+export interface TransactionLayout {
+    /** Managed containers to ensure/prove/create, ordered PARENT-FIRST (absolute). */
+    containers: string[];
+    /** Ordered write components (captured/staged/committed in array order). */
+    components: TransactionComponent[];
+}
 export interface RunTransactionInput extends TransactionDeps {
-    /** Existing project directory; `.claude` / `.claude/hooks` are created under it. */
+    /**
+     * Existing base directory; the ancestor chain root..projectDir is gated. The
+     * default topology creates `.claude` / `.claude/hooks` under it; a `layout`
+     * (Codex) uses it only as the gated ancestor-chain leaf (its containers are
+     * absolute and supplied directly).
+     */
     projectDir: string;
-    /** Committed first. */
-    asset: TransactionComponent;
-    /** Committed second. */
-    settings: TransactionComponent;
+    /** Committed first (default Claude topology; ignored when `layout` is present). */
+    asset?: TransactionComponent;
+    /** Committed second (default Claude topology; ignored when `layout` is present). */
+    settings?: TransactionComponent;
+    /** Non-Claude container topology; overrides `asset`/`settings` when present. */
+    layout?: TransactionLayout;
 }
 export interface TransactionOutcome {
     ok: boolean;

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

@@ -65,14 +65,34 @@ function ancestorChain(leaf) {
  * manual-recovery guidance (never clobbers a concurrent change).
  */
 export async function runTransaction(input) {
+    // Seam validation (fail-closed): the topology is EITHER a `layout` OR the
+    // default Claude pair [asset, settings]. A caller with neither would deref
+    // `undefined.desired` deep in the engine — refuse up front with a clear error.
+    if (!input.layout && !(input.asset && input.settings)) {
+        throw new TxAbort("validate", "runTransaction requires `layout` or both `asset` and `settings`");
+    }
     const { secureFs, clock, nonce, projectDir } = input;
-    const claudeDir = path.join(projectDir, ".claude");
-    const hooksDir = path.join(claudeDir, "hooks");
+    // Container topology + write components. The default (no `layout`) is the exact
+    // Claude `.claude` → `.claude/hooks` nesting with [asset, settings]; a `layout`
+    // (Codex) supplies absolute containers parent-first and an ordered component
+    // list. Either way the proof primitives below are identical.
+    const containers = input.layout
+        ? input.layout.containers
+        : [
+            path.join(projectDir, ".claude"),
+            path.join(projectDir, ".claude", "hooks"),
+        ];
+    const components = input.layout
+        ? input.layout.components
+        : [
+            input.asset,
+            input.settings,
+        ];
     // The dirs the tool OWNS: their children include the executed asset and the
     // settings it is referenced from. Fixed and known to the core regardless of
     // the per-run write plan; each existing member is proved on EVERY anyWrite run
     // (Round-4/5 / JDA-401 + JDB5-001).
-    const managedContainers = new Set([claudeDir, hooksDir]);
+    const managedContainers = new Set(containers);
     const heldByPath = new Map();
     const heldOrder = [];
     const createdDirs = [];
@@ -80,7 +100,12 @@ export async function runTransaction(input) {
     const committed = [];
     const backups = [];
     const needsWrite = (c) => c.desired !== null;
-    const anyWrite = needsWrite(input.asset) || needsWrite(input.settings);
+    const anyWrite = components.some(needsWrite);
+    // A component writes into `container` when its parent dir IS the container or a
+    // descendant of it — used to decide which absent containers to create.
+    const writesInto = (container) => components.some((c) => needsWrite(c) &&
+        (path.dirname(c.path) === container ||
+            path.dirname(c.path).startsWith(`${container}${path.sep}`)));
     // The uniform per-held-dir gate. It runs the LENIENT ancestor ACL predicate on
     // EVERY held dir — including managed containers, which are ALSO proved strict by
     // `proveManagedContainer` right after they are gated (in ensureManagedContainer)
@@ -168,23 +193,23 @@ export async function runTransaction(input) {
         // pre-commit); one that is absent is CREATED only when a child is written
         // into it this run, else left alone (nothing to secure).
         if (anyWrite) {
-            const projectHandle = heldByPath.get(projectDir);
-            // .claude always ensured on anyWrite (holds settings; grandparent of
-            // the asset). createIfAbsent=true never returns null (opens, creates, or
-            // throws) → narrow non-null before passing as parent (JDA6-003).
-            const claudeHandle = await ensureManagedContainer(projectHandle, claudeDir, 
-            /* createIfAbsent */ true);
-            if (!claudeHandle) {
-                throw new TxAbort(`container ${claudeDir}`, "unexpected null handle");
+            // Ensure every managed container PARENT-FIRST. Each container's parent is
+            // already held (its dirname was gated in preflight or ensured by an earlier
+            // iteration). A container is CREATED only when a component writes into it
+            // or a descendant container this run; otherwise it is proved IF present,
+            // else left alone (JDB5-001). This generalizes the former hardcoded
+            // `.claude` → `.claude/hooks` pair without changing any proof primitive.
+            for (const container of containers) {
+                const parentHandle = heldByPath.get(path.dirname(container));
+                if (!parentHandle) {
+                    throw new TxAbort(`container ${container}`, "parent chain not held");
+                }
+                await ensureManagedContainer(parentHandle, container, 
+                /* createIfAbsent */ writesInto(container));
             }
-            // .claude/hooks: create when the asset writes into it; otherwise prove
-            // IF it exists (settings-only repair must still secure the hook's
-            // container — JDB5-001).
-            await ensureManagedContainer(claudeHandle, hooksDir, 
-            /* createIfAbsent */ needsWrite(input.asset));
         }
-        // --- CAPTURE + (FORCED) BACKUP + STAGE, asset then settings ---
-        for (const component of [input.asset, input.settings]) {
+        // --- CAPTURE + (FORCED) BACKUP + STAGE, in component order ---
+        for (const component of components) {
             if (!needsWrite(component))
                 continue;
             const parentPath = path.dirname(component.path);

package/package.json

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