javi-forge 1.30.0 → 1.31.0

package/assets/claude-hooks/manifest.json

@@ -1 +1 @@
-{"schemaVersion":1,"asset":{"name":"javi-forge-skillguard-pre-tool-use.mjs","version":1,"policyVersion":1,"sha256":"78be7e6613c012280b7ad17886462ba166b63ebd031e34565d757b3a0796d7cc","historical":[]},"settingsEntries":{"current":{"version":1,"canonicalSha256":"038c59a91bf8967f6908afed74c465f1e7030254e11e4f8738975d6d708424d4"},"historical":[]},"installerHelpers":{"windowsSecureObject":null}}
+{"schemaVersion":1,"asset":{"name":"javi-forge-skillguard-pre-tool-use.mjs","version":1,"policyVersion":1,"sha256":"78be7e6613c012280b7ad17886462ba166b63ebd031e34565d757b3a0796d7cc","historical":[]},"settingsEntries":{"current":{"version":1,"canonicalSha256":"038c59a91bf8967f6908afed74c465f1e7030254e11e4f8738975d6d708424d4"},"historical":[]},"installerHelpers":{"windowsSecureObject":{"name":"javi-forge-windows-secure-object.ps1","sha256":"2289ef6ac6b039ec74dc3ea0894413e243ff9bea963f04008a356b3838f9b8dd"}}}

package/dist/lib/__fixtures__/fake-helper-transport.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Host-independent fake `HelperTransport` for the win32 `PlatformSecureFs`
+ * adapter tests. It returns canned framed responses per op so every adapter
+ * branch — request build, response parse, refusal mapping, opaque identity,
+ * notFound discrimination, directory-attribute assertion, and
+ * transport-error → fail-closed — is exercisable on Linux with NO real Windows
+ * host and NO PowerShell. The `.ps1` (Phase 3) computes Predicate A/B verdicts;
+ * this fake stands in for those already-decided verdicts.
+ */
+import type { HelperOp, HelperRequest, HelperResponse, HelperTransport } from "../secure-fs-windows.js";
+/** A responder decides the framed response for a single request of an op. */
+export type FakeResponder = (req: HelperRequest) => HelperResponse;
+export interface FakeHelperTransport extends HelperTransport {
+    /** Every request the adapter sent, in order (for request-build assertions). */
+    readonly requests: HelperRequest[];
+    /** True once close() ran. */
+    readonly closed: boolean;
+    /** Register the canned responder for an op (last registration wins). */
+    on(op: HelperOp, responder: FakeResponder): void;
+    /** Make the NEXT request reject with a transport error (session death). */
+    failNext(error: Error): void;
+}
+/** Build a programmable fake transport with no default behavior. */
+export declare function makeFakeHelperTransport(): FakeHelperTransport;
+/** A void-success verdict (proveOwner/proveDacl/proveContainer/write/etc. ok). */
+export declare const okVoid: () => HelperResponse;
+/** A win32 DACL refusal (Predicate A/B verdict from the .ps1). */
+export declare const daclRefuse: (detail: string) => HelperResponse;
+/** Named Predicate-A refuse postures (ground-truth + design fixtures). */
+export declare const foreignWrite: () => HelperResponse;
+export declare const deleteChild: () => HelperResponse;
+export declare const genericWrite: () => HelperResponse;
+export declare const genericAll: () => HelperResponse;
+export declare const nullDacl: () => HelperResponse;
+export declare const foreignOwner: () => HelperResponse;
+/** proveContainer-only add-child refusal (CREATE_PARENT_DIR). */
+export declare const addChild: () => HelperResponse;
+/** A successful openDir/createDir value carrying handle, identity, attributes. */
+export declare const openOk: (handleId: string, opaque: string, attributes: number) => HelperResponse;
+/** A genuine not-found openDir failure (ENOENT / ERROR_FILE/PATH_NOT_FOUND). */
+export declare const openNotFound: (status: number) => HelperResponse;
+/** A present-but-unopenable openDir failure (reparse/EACCES/transient). */
+export declare const openUnopenable: (detail: string, status?: number) => HelperResponse;
+/** A successful capture value; bytes are base64 in the JSON body. */
+export declare const captureOk: (bytes: Buffer, opaque: string) => HelperResponse;
+//# sourceMappingURL=fake-helper-transport.d.ts.map

package/dist/lib/__fixtures__/fake-helper-transport.js

@@ -0,0 +1,90 @@
+/**
+ * Host-independent fake `HelperTransport` for the win32 `PlatformSecureFs`
+ * adapter tests. It returns canned framed responses per op so every adapter
+ * branch — request build, response parse, refusal mapping, opaque identity,
+ * notFound discrimination, directory-attribute assertion, and
+ * transport-error → fail-closed — is exercisable on Linux with NO real Windows
+ * host and NO PowerShell. The `.ps1` (Phase 3) computes Predicate A/B verdicts;
+ * this fake stands in for those already-decided verdicts.
+ */
+/** Build a programmable fake transport with no default behavior. */
+export function makeFakeHelperTransport() {
+    const requests = [];
+    const responders = new Map();
+    let closed = false;
+    let pendingError = null;
+    const fake = {
+        get requests() {
+            return requests;
+        },
+        get closed() {
+            return closed;
+        },
+        on(op, responder) {
+            responders.set(op, responder);
+        },
+        failNext(error) {
+            pendingError = error;
+        },
+        async request(req) {
+            requests.push(req);
+            if (pendingError) {
+                const err = pendingError;
+                pendingError = null;
+                throw err;
+            }
+            const responder = responders.get(req.op);
+            if (!responder) {
+                throw new Error(`fake transport: no responder for op ${req.op}`);
+            }
+            return responder(req);
+        },
+        async close() {
+            closed = true;
+        },
+    };
+    return fake;
+}
+// --- canned response builders (the .ps1 verdicts, pre-decided) --------------
+/** A void-success verdict (proveOwner/proveDacl/proveContainer/write/etc. ok). */
+export const okVoid = () => ({ ok: true });
+/** A win32 DACL refusal (Predicate A/B verdict from the .ps1). */
+export const daclRefuse = (detail) => ({
+    ok: false,
+    refusal: "unsafe-windows-dacl",
+    detail,
+});
+/** Named Predicate-A refuse postures (ground-truth + design fixtures). */
+export const foreignWrite = () => daclRefuse("foreign trustee S-1-5-11 path-endangering");
+export const deleteChild = () => daclRefuse("foreign trustee S-1-1-0 path-endangering");
+export const genericWrite = () => daclRefuse("foreign trustee S-1-1-0 path-endangering");
+export const genericAll = () => daclRefuse("foreign trustee S-1-1-0 path-endangering");
+export const nullDacl = () => daclRefuse("null DACL");
+export const foreignOwner = () => daclRefuse("foreign owner S-1-5-21-1-2-3-1001");
+/** proveContainer-only add-child refusal (CREATE_PARENT_DIR). */
+export const addChild = () => daclRefuse("foreign trustee S-1-1-0 add-child");
+/** A successful openDir/createDir value carrying handle, identity, attributes. */
+export const openOk = (handleId, opaque, attributes) => ({
+    ok: true,
+    value: { handleId, opaque, attributes },
+});
+/** A genuine not-found openDir failure (ENOENT / ERROR_FILE/PATH_NOT_FOUND). */
+export const openNotFound = (status) => ({
+    ok: false,
+    refusal: "unsafe-parent-chain",
+    detail: "not found",
+    status,
+});
+/** A present-but-unopenable openDir failure (reparse/EACCES/transient). */
+export const openUnopenable = (detail, status = 5) => ({
+    ok: false,
+    refusal: "unsafe-parent-chain",
+    detail,
+    status,
+});
+/** A successful capture value; bytes are base64 in the JSON body. */
+export const captureOk = (bytes, opaque) => ({
+    ok: true,
+    value: { bytes: bytes.toString("base64"), opaque },
+});
+//# sourceMappingURL=fake-helper-transport.js.map

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

@@ -27,6 +27,18 @@ export interface FakeFaults {
     writeRefuse?: (name: string, callIndex: number) => boolean;
     /** Refuse renameInDir when the destination base name matches. */
     renameRefuse?: (to: string) => boolean;
+    /**
+     * Refuse proveManagedContainer for a path on its Nth call (a foreign
+     * add/delete-child ACE on a managed container we own — the win32 CREATE_PARENT_DIR
+     * strictness that the lenient ancestor gate deliberately tolerates).
+     */
+    managedContainerRefuse?: (dirPath: string, callIndex: number) => boolean;
+    /**
+     * Make openDirNoFollow return a PRESENT-BUT-UNOPENABLE refusal (a reparse
+     * point/junction, EACCES, ENOTDIR, or transient) — a refusal with `notFound`
+     * absent, so ensureManagedContainer must fail closed, never skip (JDA6-001).
+     */
+    openDirUnopenable?: (dirPath: string) => boolean;
 }
 export interface FakeSecureFs extends PlatformSecureFs {
     readonly dirs: Set<string>;

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

@@ -15,6 +15,13 @@ const unsafe = (detail) => ({
     refusal: "unsafe-parent-chain",
     detail,
 });
+/** A GENUINE not-found refusal (the only state ensureManagedContainer may skip/create on). */
+const notFound = (detail) => ({
+    ok: false,
+    refusal: "unsafe-parent-chain",
+    detail,
+    notFound: true,
+});
 export function makeFakeSecureFs() {
     const dirs = new Set();
     const files = new Map();
@@ -25,6 +32,7 @@ export function makeFakeSecureFs() {
     const ownershipCounts = new Map();
     const aclCounts = new Map();
     const writeCounts = new Map();
+    const managedCounts = new Map();
     const inoFor = (p) => {
         let ino = inos.get(p);
         if (ino === undefined) {
@@ -76,8 +84,12 @@ export function makeFakeSecureFs() {
             return false;
         },
         async openDirNoFollow(dirPath) {
+            if (fake.faults.openDirUnopenable?.(dirPath)) {
+                // PRESENT-but-unopenable-no-follow: refusal WITHOUT notFound.
+                return unsafe(`openDir unopenable ${dirPath}`);
+            }
             if (!dirs.has(dirPath))
-                return unsafe(`openDir enoent ${dirPath}`);
+                return notFound(`openDir enoent ${dirPath}`);
             return okValue(handleFor(dirPath));
         },
         async revalidateIdentity(target, held) {
@@ -177,6 +189,19 @@ export function makeFakeSecureFs() {
             dirs.delete(handle.path);
             return ok();
         },
+        async proveManagedContainer(dirPath) {
+            const idx = bump(managedCounts, dirPath);
+            if (fake.faults.managedContainerRefuse?.(dirPath, idx)) {
+                return {
+                    ok: false,
+                    refusal: "unsafe-windows-dacl",
+                    detail: `add-child ${dirPath}`,
+                };
+            }
+            if (!dirs.has(dirPath))
+                return unsafe(`container enoent ${dirPath}`);
+            return ok();
+        },
     };
     return fake;
 }

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

@@ -28,10 +28,19 @@ export declare function createLinuxAclAdapter(spawn?: SpawnFn): PosixAclAdapter;
 export declare function createMacosAclAdapter(spawn?: SpawnFn): PosixAclAdapter;
 export declare function createPosixSecureFs(acl: PosixAclAdapter): PlatformSecureFs;
 /**
- * Select the POSIX secure filesystem for the host platform. Linux uses the
- * `getfacl` adapter, macOS uses `/bin/ls -lde`; Windows and every other platform
- * return `null` so the manager refuses with `windows-secure-object-unavailable`
- * and mutates nothing (Slice 3b implements Windows).
+ * Select the secure filesystem for the host platform. Linux uses the `getfacl`
+ * adapter, macOS uses `/bin/ls -lde`, and win32 uses the digest-bound PowerShell
+ * helper over a lazily-spawned session (Slice 3b). Every other platform returns
+ * `null` so the manager refuses with `windows-secure-object-unavailable` and
+ * mutates nothing.
+ *
+ * The win32 branch is host-independent to CONSTRUCT: `createPs1Session` spawns
+ * nothing until the first request, and it verifies the on-disk `.ps1` sha256
+ * against the manifest binding before spawning. If the binding is absent or the
+ * digest mismatches, the transport refuses every op (`refusingTransport`), so
+ * the adapter fails closed exactly like the pre-3b `null` did — but a real,
+ * matching helper now drives Windows installs. The `.ps1`'s runtime behavior is
+ * validated by the `windows-latest` CI job (Phase 5), never on the dev box.
  */
 export declare function selectSecureFs(platform?: NodeJS.Platform): PlatformSecureFs | null;
 //# sourceMappingURL=secure-fs-posix.d.ts.map

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

@@ -12,6 +12,7 @@ import { createHash } from "node:crypto";
 import { constants as FS } from "node:fs";
 import { chmod, lstat, mkdir, open, rename, rmdir, unlink, } from "node:fs/promises";
 import path from "node:path";
+import { createPs1Session, createWindowsSecureFs, } from "./secure-fs-windows.js";
 /** Bounded time budget for a single ACL inspection. */
 const ACL_TIMEOUT_MS = 2000;
 /** Read budget for the ACL tool output (defensive; ACLs are tiny). */
@@ -142,7 +143,14 @@ export function createPosixSecureFs(acl) {
                 }
             }
             catch (error) {
-                return refuse("unsafe-parent-chain", `openDir ${dirPath}: ${errCode(error) ?? "error"}`);
+                const code = errCode(error);
+                const result = refuse("unsafe-parent-chain", `openDir ${dirPath}: ${code ?? "error"}`);
+                // Genuine not-found ONLY on ENOENT (Round-6 / JDA6-001). Every other
+                // errno — ELOOP/reparse, EACCES, ENOTDIR, transient — leaves notFound
+                // absent so a present-but-unopenable managed container fails closed.
+                if (code === "ENOENT")
+                    result.notFound = true;
+                return result;
             }
         },
         async revalidateIdentity(target, held) {
@@ -198,6 +206,9 @@ export function createPosixSecureFs(acl) {
                 const handle = await open(target, CAPTURE_FLAGS);
                 try {
                     const stats = await handle.stat();
+                    if (!stats.isFile()) {
+                        return refuse("unsafe-parent-chain", `capture ${target}: not a regular file`);
+                    }
                     const bytes = await handle.readFile();
                     const sha256 = createHash("sha256").update(bytes).digest("hex");
                     return okValue({
@@ -283,20 +294,40 @@ export function createPosixSecureFs(acl) {
                 return refuse("unsafe-parent-chain", `rmdir ${handle.path}: ${errCode(error) ?? "error"}`);
             }
         },
+        // On POSIX, permission to ADD a child to a directory IS the directory's
+        // write bit; proveOwnershipAndMode already refuses any group/other write
+        // (stats.mode & 0o022). So the managed-container check is definitionally the
+        // same predicate gate() just ran on this path — idempotent, no new refusal
+        // surface. The seam has teeth only on win32, where Predicate A tolerates
+        // add-child on high ancestors (Round-4 / JDA-401).
+        proveManagedContainer(dirPath) {
+            return secureFs.proveOwnershipAndMode(dirPath);
+        },
     };
     return secureFs;
 }
 /**
- * Select the POSIX secure filesystem for the host platform. Linux uses the
- * `getfacl` adapter, macOS uses `/bin/ls -lde`; Windows and every other platform
- * return `null` so the manager refuses with `windows-secure-object-unavailable`
- * and mutates nothing (Slice 3b implements Windows).
+ * Select the secure filesystem for the host platform. Linux uses the `getfacl`
+ * adapter, macOS uses `/bin/ls -lde`, and win32 uses the digest-bound PowerShell
+ * helper over a lazily-spawned session (Slice 3b). Every other platform returns
+ * `null` so the manager refuses with `windows-secure-object-unavailable` and
+ * mutates nothing.
+ *
+ * The win32 branch is host-independent to CONSTRUCT: `createPs1Session` spawns
+ * nothing until the first request, and it verifies the on-disk `.ps1` sha256
+ * against the manifest binding before spawning. If the binding is absent or the
+ * digest mismatches, the transport refuses every op (`refusingTransport`), so
+ * the adapter fails closed exactly like the pre-3b `null` did — but a real,
+ * matching helper now drives Windows installs. The `.ps1`'s runtime behavior is
+ * validated by the `windows-latest` CI job (Phase 5), never on the dev box.
  */
 export function selectSecureFs(platform = process.platform) {
     if (platform === "linux")
         return createPosixSecureFs(createLinuxAclAdapter());
     if (platform === "darwin")
         return createPosixSecureFs(createMacosAclAdapter());
+    if (platform === "win32")
+        return createWindowsSecureFs(createPs1Session());
     return null;
 }
 //# sourceMappingURL=secure-fs-posix.js.map

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

@@ -13,6 +13,14 @@
 export interface SecureIdentity {
     dev: number;
     ino: number;
+    /**
+     * Full-precision, platform-opaque identity token. POSIX leaves this undefined
+     * (identity is `dev`+`ino`). win32 sets `"<volumeSerialHex>:<fileIdHex>"` and
+     * compares ONLY on this — an absent/zero token is a hard refusal there, never
+     * a fallback to the truncated `dev`/`ino` (Decision 1b). Additive: the core
+     * passes it back to the adapter opaquely and never interprets it.
+     */
+    opaque?: string;
 }
 /** A held, no-follow directory handle plus its captured identity and path. */
 export interface SecureDirHandle {
@@ -27,12 +35,21 @@ export interface CapturedFile {
     identity: SecureIdentity;
     sha256: string;
 }
-export type SecureRefusal = "unsafe-parent-chain" | "unsupported-posix-acl" | "windows-secure-object-unavailable";
+export type SecureRefusal = "unsafe-parent-chain" | "unsupported-posix-acl" | "unsafe-windows-dacl" | "windows-secure-object-unavailable";
 export interface SecureResult<T> {
     ok: boolean;
     value?: T;
     refusal?: SecureRefusal;
     detail?: string;
+    /**
+     * Set ONLY by `openDirNoFollow` on a refusal, and ONLY for a GENUINE
+     * not-found (POSIX ENOENT / win32 `ERROR_FILE_NOT_FOUND`|`ERROR_PATH_NOT_FOUND`).
+     * Every other refusal — a reparse point/junction, EACCES, ENOTDIR, a transient
+     * error, or any non-open proof — leaves this absent/false so a managed
+     * container that is PRESENT-but-unopenable fails the transaction closed rather
+     * than being silently skipped (Round-6 / JDA6-001). Additive.
+     */
+    notFound?: boolean;
 }
 /**
  * The whole platform boundary. Every host-dependent operation is a method here;
@@ -74,6 +91,17 @@ export interface PlatformSecureFs {
     unlinkIfIdentity(dir: SecureDirHandle, name: string, held: SecureIdentity): Promise<SecureResult<void>>;
     /** Remove an identity-matched EMPTY directory (rollback of a created segment). */
     rmdirIfIdentityEmpty(handle: SecureDirHandle): Promise<SecureResult<void>>;
+    /**
+     * Prove a directory the tool OWNS as a MANAGED CONTAINER (`.claude`,
+     * `.claude/hooks`): refuse ALL foreign add/delete-child rights — strictly more
+     * than the lenient ancestor `gate()`, which tolerates harmless add-child on
+     * high traversal ancestors (Round-4 / JDA-401). The core calls this ONLY on the
+     * dirs it constructs, expressing the managed-container role by WHICH method it
+     * invokes — no `process.platform` ever enters the engine. POSIX delegates to its
+     * existing strict ownership/mode check (group/other write IS add-child on a
+     * directory), so POSIX behavior is unchanged; the seam has teeth only on win32.
+     */
+    proveManagedContainer(dirPath: string): Promise<SecureResult<void>>;
 }
 /** Injected seams making the engine deterministic and host-independent. */
 export interface TransactionDeps {

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

@@ -68,6 +68,11 @@ export async function runTransaction(input) {
     const { secureFs, clock, nonce, projectDir } = input;
     const claudeDir = path.join(projectDir, ".claude");
     const hooksDir = path.join(claudeDir, "hooks");
+    // 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 heldByPath = new Map();
     const heldOrder = [];
     const createdDirs = [];
@@ -82,17 +87,44 @@ export async function runTransaction(input) {
         heldByPath.set(dirPath, handle);
         heldOrder.push(handle);
     }
-    async function ensureDir(parent, fullPath) {
+    /**
+     * Ensure a MANAGED CONTAINER (`.claude`/`.claude/hooks`): an existing one is
+     * ALWAYS gated + proveManagedContainer'd (→ heldOrder → re-proved pre-commit);
+     * an absent one is created Predicate-B strict ONLY when `createIfAbsent` (a
+     * child is written into it this run), else left alone. Four fail-closed
+     * branches (Round-4/5/6 / JDA-401 + JDB5-001 + JDA6-001):
+     *   (1) present + openable    → gate + proveManagedContainer, return handle
+     *   (2) notFound + create     → createDirExclusive + gate + proveManagedContainer
+     *   (3) notFound + !create    → return null (nothing to secure)
+     *   (4) any non-notFound !ok  → FAIL CLOSED explicitly (present-but-unopenable:
+     *                               junction/reparse/EACCES) regardless of create.
+     */
+    async function ensureManagedContainer(parent, fullPath, createIfAbsent) {
         const opened = await secureFs.openDirNoFollow(fullPath);
+        // (1) PRESENT + openable no-follow.
         if (opened.ok && opened.value) {
             await gate(fullPath, opened.value);
+            must(`container ${fullPath}`, await secureFs.proveManagedContainer(fullPath));
             return opened.value;
         }
+        // (4) ANY non-notFound refusal → fail the whole transaction closed,
+        // regardless of createIfAbsent. Refuse EXPLICITLY (JDB7-002): do not rely
+        // on a later must() throwing — propagate the refusal here so a
+        // present-but-unopenable managed container is never silently skipped.
+        if (!opened.notFound) {
+            throw new TxAbort(`container ${fullPath}`, opened.detail ?? opened.refusal ?? "present-but-unopenable");
+        }
+        // GENUINELY ABSENT (notFound === true) — the ONLY safe skip/create path.
+        // (3) absent + no child written this run → nothing to secure.
+        if (!createIfAbsent)
+            return null;
+        // (2) absent + a child IS written into it this run → create + prove.
         const created = must(`create ${fullPath}`, await secureFs.createDirExclusive(parent, path.basename(fullPath), 0o700));
         // Post-create identity revalidation + full gate on the new segment.
         must(`revalidate-created ${fullPath}`, await secureFs.revalidateIdentity(fullPath, created.identity));
         createdDirs.push(created);
         await gate(fullPath, created);
+        must(`container ${fullPath}`, await secureFs.proveManagedContainer(fullPath));
         return created;
     }
     async function gateStillValid() {
@@ -104,6 +136,13 @@ export async function runTransaction(input) {
                 return false;
             if (!(await secureFs.proveNoExtendedAcl(handle.path)).ok)
                 return false;
+            // Re-check the container add/delete-child dimension on the rollback path
+            // too, for full symmetry with the pre-commit re-prove (JDB5-002).
+            if (managedContainers.has(handle.path)) {
+                if (!(await secureFs.proveManagedContainer(handle.path)).ok) {
+                    return false;
+                }
+            }
         }
         return true;
     }
@@ -113,12 +152,27 @@ export async function runTransaction(input) {
             const handle = must(`openDir ${dirPath}`, await secureFs.openDirNoFollow(dirPath));
             await gate(dirPath, handle);
         }
-        // --- SEGMENT CREATION: .claude then .claude/hooks, one at a time ---
+        // --- SEGMENT CREATION + MANAGED-CONTAINER PROOF ---
+        // Prove the COMPLETE managed set {claudeDir, hooksDir} on every anyWrite run,
+        // decoupled from which child is written. A managed container that EXISTS is
+        // always gate()d + proveManagedContainer'd (→ heldOrder → re-proved
+        // 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);
-            const claudeHandle = await ensureDir(projectHandle, claudeDir);
-            if (needsWrite(input.asset))
-                await ensureDir(claudeHandle, hooksDir);
+            // .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");
+            }
+            // .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]) {
@@ -148,6 +202,12 @@ export async function runTransaction(input) {
             must(`recheck-id ${handle.path}`, await secureFs.revalidateIdentity(handle.path, handle.identity));
             must(`recheck-own ${handle.path}`, await secureFs.proveOwnershipAndMode(handle.path));
             must(`recheck-acl ${handle.path}`, await secureFs.proveNoExtendedAcl(handle.path));
+            // Re-prove the managed-container add/delete-child dimension for held
+            // handles that ARE managed containers, closing the TOCTOU window between
+            // ensure time and commit (JDB7-003; parity with 3a Decision 6 / JD-007).
+            if (managedContainers.has(handle.path)) {
+                must(`recheck-container ${handle.path}`, await secureFs.proveManagedContainer(handle.path));
+            }
         }
         // --- COMMIT: asset first, settings second ---
         for (const entry of staged) {
@@ -227,7 +287,11 @@ export async function runTransaction(input) {
                     return;
                 }
                 await secureFs.applyExactMode(path.join(entry.dir.path, rName), entry.prior.mode);
-                await secureFs.renameInDir(entry.dir, rName, base);
+                const restored = await secureFs.renameInDir(entry.dir, rName, base);
+                if (!restored.ok) {
+                    errors.push(`STOP: cannot restore ${entry.path}; prior payload staged at ${path.join(entry.dir.path, rName)} for manual recovery`);
+                    return;
+                }
             }
         }
         // Remove only tx-created, identity-matched, still-empty segments, child-first.

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

@@ -0,0 +1,124 @@
+/**
+ * Windows `PlatformSecureFs` adapter for the SkillGuard transactional installer
+ * (Slice 3b). It is the win32 analog of the POSIX adapter: the ONLY place a
+ * Windows security decision is requested, delegated across an injectable
+ * `HelperTransport` seam to a bundled, digest-bound PowerShell helper (Phase 3)
+ * that owns the real OS handles and computes Predicate A/B verdicts.
+ *
+ * This module is host-independent and fully testable on Linux via a fake
+ * transport: `createWindowsSecureFs` builds framed requests and maps framed
+ * responses to `SecureResult`s; it enforces the TS-side invariants the design
+ * pins to the adapter (never the `.ps1`):
+ *   - C1 (Decision 1a): `mode` is a sentinel, NOT POSIX bits. `captureFile`
+ *     returns `WIN32_MODE_SENTINEL`; `applyExactMode` refuses any other mode.
+ *   - C4 (Decision 1b): identity is the full-precision `volumeSerial:FileId`
+ *     `opaque` token; an absent/zero/malformed token is a HARD REFUSAL, never a
+ *     fallback to the truncated `dev`/`ino` (display-only).
+ *   - JDA6-001 (Round-6): `openDir` maps ONLY `ERROR_FILE_NOT_FOUND` (2) /
+ *     `ERROR_PATH_NOT_FOUND` (3) to `notFound:true`; every other failure leaves
+ *     it absent so a present-but-unopenable container fails the transaction closed.
+ *   - JDA7-001 (Round-7): `openDir` asserts `FILE_ATTRIBUTE_DIRECTORY` and
+ *     refuses a non-directory with `notFound:false` (POSIX `O_DIRECTORY` parity).
+ * Every transport error (spawn failure, dead session, bad frame, timeout) maps
+ * to a fail-closed refusal — Windows is never a weaker tier than POSIX.
+ */
+import type { PlatformSecureFs, SecureRefusal } from "./secure-fs-transaction.js";
+/**
+ * The mode `captureFile` returns and `applyExactMode` demands on win32 (C1).
+ * NTFS has no POSIX bits; the value only has to survive the core's opaque
+ * round-trip, and `0o600` is the private-file mode the core already threads.
+ */
+export declare const WIN32_MODE_SENTINEL = 384;
+/** Reject any frame whose declared length exceeds this (hook assets are tiny). */
+export declare const HELPER_FRAME_LIMIT: number;
+/**
+ * R4-001 (Phase-4 hard gate): the per-request / handshake deadline. A timer is
+ * armed when a frame is written to the child (and while awaiting the startup
+ * handshake) and cleared the instant its response arrives. If it fires, the
+ * child is killed and every pending/subsequent op fails closed — a hung or
+ * non-responding `.ps1` can no longer hang the installer transaction forever.
+ */
+export declare const HELPER_OP_TIMEOUT_MS = 30000;
+export type HelperOp = "openDir" | "revalidate" | "proveOwner" | "proveDacl" | "proveContainer" | "createDir" | "capture" | "writeExcl" | "applyMode" | "rename" | "unlink" | "rmdir" | "releaseHandle";
+export interface HelperRequest {
+    op: HelperOp;
+    args: Record<string, unknown>;
+}
+export interface HelperResponse {
+    ok: boolean;
+    value?: unknown;
+    refusal?: SecureRefusal;
+    detail?: string;
+    /** win32 error code on an openDir failure; drives the notFound mapping. */
+    status?: number;
+}
+export interface HelperTransport {
+    /** Strictly serial: exactly one outstanding request at a time. */
+    request(req: HelperRequest): Promise<HelperResponse>;
+    /** Idempotent; kills the child. */
+    close(): Promise<void>;
+}
+/** Encode a JSON body as `[uint32 BE byteLength][UTF-8 JSON]`. */
+export declare function encodeFrame(body: unknown): Buffer;
+/**
+ * Decode as many complete frames as `buf` holds, returning them plus the
+ * unconsumed remainder. Throws on a declared length past `HELPER_FRAME_LIMIT`
+ * (the caller kills the session and fails closed).
+ */
+export declare function decodeFrames(buf: Buffer): {
+    frames: unknown[];
+    rest: Buffer;
+};
+export declare function createWindowsSecureFs(transport: HelperTransport): PlatformSecureFs;
+/**
+ * A transport that refuses EVERY op — used when the `.ps1` digest does not match
+ * the manifest binding (or the binding is absent). No PowerShell is spawned.
+ */
+export declare function refusingTransport(detail: string): HelperTransport;
+/** The subset of a spawned child process this session drives. */
+export interface Ps1Child {
+    stdin: {
+        write(chunk: Buffer): void;
+    };
+    stdout: {
+        on(event: "data", cb: (chunk: Buffer) => void): void;
+    };
+    stderr?: {
+        on(event: "data", cb: (chunk: Buffer) => void): void;
+    };
+    on(event: "exit" | "error", cb: (...args: unknown[]) => void): void;
+    kill(): void;
+    unref?(): void;
+}
+export interface WindowsHelperBinding {
+    name: string;
+    sha256: string;
+}
+export interface WindowsHelperManifest {
+    installerHelpers?: {
+        windowsSecureObject?: WindowsHelperBinding | null;
+    };
+}
+export interface Ps1SessionOptions {
+    assetsDir?: string;
+    manifest?: WindowsHelperManifest | null;
+    readFile?: (filePath: string) => Buffer;
+    spawn?: (cmd: string, args: string[]) => Ps1Child;
+    idleMs?: number;
+    opTimeoutMs?: number;
+    setTimer?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimer?: (handle: ReturnType<typeof setTimeout>) => void;
+    registerExitHook?: (fn: () => void) => void;
+}
+/**
+ * The real transport: verify the on-disk `.ps1` sha256 against the manifest
+ * binding BEFORE spawning (tamper-evident, symmetric with the `.mjs`); on a
+ * mismatch/absent binding return `refusingTransport` and spawn nothing. On a
+ * match, spawn `powershell.exe` lazily on the first request, complete the
+ * handshake, and exchange strictly-serial length-prefixed frames. Any oversized
+ * frame, bad handshake, child exit, or session error kills the child and fails
+ * every pending/subsequent op closed. The idle watchdog only arms when ZERO
+ * directory handles are outstanding (W1) so it never kills a live transaction.
+ */
+export declare function createPs1Session(opts?: Ps1SessionOptions): HelperTransport;
+//# sourceMappingURL=secure-fs-windows.d.ts.map