spawnfile 0.1.12 → 0.1.14

package/dist/deployment/lifecycleCompletionRecovery.d.ts

@@ -0,0 +1,21 @@
+import { type LifecycleAdmission, type LifecycleAmbiguousReason, type LifecycleCompletion, type LifecycleInvocation, type LifecycleOwnerCapability } from "./lifecycleCompletionContracts.js";
+interface RecoveryStorage {
+    exactAdmission: (invocation: LifecycleInvocation) => Promise<LifecycleAdmission | null>;
+    exactCompletion: (invocation: LifecycleInvocation) => Promise<LifecycleCompletion | null>;
+    publish: (invocation: LifecycleInvocation, kind: "completion" | "recovery", content: string) => Promise<boolean>;
+    readRecovery: (invocation: LifecycleInvocation) => Promise<string | null>;
+    readHeartbeat: (invocation: LifecycleInvocation) => Promise<{
+        epoch: string;
+        lease_expires_at: number;
+    } | null>;
+}
+export type LifecycleRecoveryClaim = {
+    capability: LifecycleOwnerCapability;
+    status: "owner";
+} | {
+    status: "ambiguous" | "pending" | "replay";
+};
+export declare const materializeDeadRecoveryAmbiguous: (invocation: LifecycleInvocation, publish: RecoveryStorage["publish"]) => Promise<void>;
+export declare const claimLifecycleRecoveryRecord: (invocation: LifecycleInvocation, storage: RecoveryStorage) => Promise<LifecycleRecoveryClaim>;
+export declare const markLifecycleAmbiguousRecord: (invocation: LifecycleInvocation, reasonCode: LifecycleAmbiguousReason, capability: LifecycleOwnerCapability, storage: RecoveryStorage) => Promise<void>;
+export {};

package/dist/deployment/lifecycleCompletionRecovery.js

@@ -0,0 +1,56 @@
+import { canonicalLifecycleJson, lifecycleAmbiguousSchema, lifecycleDigest, LIFECYCLE_TERMINAL_VERSION, } from "./lifecycleCompletionContracts.js";
+import { assertLifecycleOwnerCapability, createLifecycleAdmission, lifecycleOwnerIsAlive, } from "./lifecycleCompletionOwner.js";
+import { parseLifecycleAdmission } from "./lifecycleCompletionParsing.js";
+const ambiguousTerminal = (invocation, reasonCode) => {
+    const ambiguous = lifecycleAmbiguousSchema.parse({
+        invocation_digest: lifecycleDigest(invocation),
+        reason_code: reasonCode,
+        version: "spawnfile.lifecycle-ambiguous.v1",
+    });
+    return `${canonicalLifecycleJson({
+        ambiguous,
+        status: "ambiguous",
+        version: LIFECYCLE_TERMINAL_VERSION,
+    })}\n`;
+};
+export const materializeDeadRecoveryAmbiguous = async (invocation, publish) => {
+    await publish(invocation, "completion", ambiguousTerminal(invocation, "recovery_owner_died"));
+};
+export const claimLifecycleRecoveryRecord = async (invocation, storage) => {
+    const stored = await storage.exactAdmission(invocation);
+    const completion = await storage.exactCompletion(invocation);
+    if (!stored)
+        throw new Error("missing admission");
+    if (completion)
+        return { status: "replay" };
+    if (lifecycleOwnerIsAlive(stored.owner, await storage.readHeartbeat(invocation)))
+        return { status: "pending" };
+    const recovery = createLifecycleAdmission(invocation);
+    if (await storage.publish(invocation, "recovery", `${canonicalLifecycleJson(recovery)}\n`))
+        return {
+            capability: { epoch: recovery.owner.epoch, role: "recovery" },
+            status: "owner",
+        };
+    const text = await storage.readRecovery(invocation);
+    if (text === null)
+        throw new Error("missing recovery owner");
+    const prior = parseLifecycleAdmission(text);
+    if (canonicalLifecycleJson(prior.invocation) !==
+        canonicalLifecycleJson(invocation))
+        throw new Error("invocation id drift");
+    if (lifecycleOwnerIsAlive(prior.owner, await storage.readHeartbeat(invocation)))
+        return { status: "pending" };
+    await materializeDeadRecoveryAmbiguous(invocation, storage.publish);
+    return { status: "ambiguous" };
+};
+export const markLifecycleAmbiguousRecord = async (invocation, reasonCode, capability, storage) => {
+    const admitted = await storage.exactAdmission(invocation);
+    if (!admitted)
+        throw new Error("missing admission");
+    const recoveryText = await storage.readRecovery(invocation);
+    const recovered = recoveryText ? parseLifecycleAdmission(recoveryText) : null;
+    assertLifecycleOwnerCapability(invocation, admitted, recovered, capability);
+    if (capability.role !== "recovery")
+        throw new Error("invalid owner capability");
+    await storage.publish(invocation, "completion", ambiguousTerminal(invocation, reasonCode));
+};

package/dist/deployment/lifecycleCompletionRoot.d.ts

@@ -0,0 +1,21 @@
+import { open } from "node:fs/promises";
+interface PathIdentity {
+    readonly dev: number;
+    readonly ino: number;
+    readonly path: string;
+}
+export interface LifecycleRootAuthority {
+    readonly canonicalHome: string;
+    readonly configuredHome: string;
+    readonly identities: readonly PathIdentity[];
+    readonly root: string;
+}
+export declare const revalidateLifecycleRootAuthority: (authority: LifecycleRootAuthority) => Promise<void>;
+export declare const validateLifecycleRoot: (create: boolean) => Promise<LifecycleRootAuthority | null>;
+export declare const lifecycleRoot: () => Promise<string>;
+export declare const existingLifecycleRoot: () => Promise<string | null>;
+export declare const requireLifecycleRootAuthority: () => Promise<LifecycleRootAuthority>;
+export declare const openLifecycleAuthorityRoot: (authority: LifecycleRootAuthority) => Promise<import("fs/promises").FileHandle>;
+export declare const revalidateHeldLifecycleRoot: (authority: LifecycleRootAuthority, handle: Awaited<ReturnType<typeof open>>) => Promise<void>;
+export declare const syncLifecycleDirectory: (directory: string) => Promise<void>;
+export {};

package/dist/deployment/lifecycleCompletionRoot.js

@@ -0,0 +1,243 @@
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath } from "node:fs/promises";
+import path from "node:path";
+import { resolveSpawnfileHome } from "../auth/index.js";
+import { failLifecycleStore } from "./lifecycleCompletionPaths.js";
+const OWNER = process.getuid?.() ?? -1;
+const authorities = new Map();
+const chain = (value) => {
+    const parsed = path.parse(value);
+    const result = [parsed.root];
+    let current = parsed.root;
+    for (const part of value.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        result.push(current);
+    }
+    return result;
+};
+const isKnownDarwinAlias = async (value) => {
+    if (process.platform !== "darwin" || (value !== "/var" && value !== "/tmp"))
+        return false;
+    const resolved = await realpath(value).catch(() => "");
+    return resolved === (value === "/var" ? "/private/var" : "/private/tmp");
+};
+const validateConfiguredAliases = async (configuredHome, canonicalHome) => {
+    for (const value of chain(configuredHome)) {
+        const info = await lstat(value).catch(() => failLifecycleStore("unsafe root"));
+        if (info.isSymbolicLink()) {
+            if (info.uid !== 0 || (info.mode & 0o022) !== 0 || !(await isKnownDarwinAlias(value))) {
+                failLifecycleStore("unsafe root");
+            }
+        }
+        else if (!info.isDirectory()) {
+            failLifecycleStore("unsafe root");
+        }
+    }
+    if ((await realpath(configuredHome).catch(() => "")) !== canonicalHome) {
+        failLifecycleStore("root changed");
+    }
+};
+const captureCanonicalChain = async (canonicalHome, root) => {
+    const identities = [];
+    for (const value of chain(root)) {
+        const info = await lstat(value).catch(() => failLifecycleStore("unsafe root"));
+        const writable = (info.mode & 0o022) !== 0;
+        const stickyRootTemp = info.uid === 0 && writable && (info.mode & 0o1000) !== 0;
+        if (!info.isDirectory() ||
+            info.isSymbolicLink() ||
+            (info.uid !== OWNER && info.uid !== 0) ||
+            (writable && !stickyRootTemp))
+            failLifecycleStore("unsafe root");
+        if ((value === canonicalHome || value === root) &&
+            (info.uid !== OWNER || (info.mode & 0o777) !== 0o700))
+            failLifecycleStore("unsafe root");
+        identities.push({ dev: info.dev, ino: info.ino, path: value });
+    }
+    return identities;
+};
+const revalidateIdentities = async (identities) => {
+    for (const expected of identities) {
+        const current = await lstat(expected.path).catch(() => failLifecycleStore("root changed"));
+        const writable = (current.mode & 0o022) !== 0;
+        const stickyRootTemp = current.uid === 0 && writable && (current.mode & 0o1000) !== 0;
+        if (!current.isDirectory() ||
+            current.isSymbolicLink() ||
+            (current.uid !== OWNER && current.uid !== 0) ||
+            (writable && !stickyRootTemp))
+            failLifecycleStore("unsafe root");
+        if (current.dev !== expected.dev || current.ino !== expected.ino) {
+            failLifecycleStore("root changed");
+        }
+    }
+};
+const captureSafeExistingChain = async (value) => {
+    const identities = [];
+    for (const current of chain(value)) {
+        const info = await lstat(current).catch(() => failLifecycleStore("unsafe root"));
+        const writable = (info.mode & 0o022) !== 0;
+        const stickyRootTemp = info.uid === 0 && writable && (info.mode & 0o1000) !== 0;
+        if (!info.isDirectory() ||
+            info.isSymbolicLink() ||
+            (info.uid !== OWNER && info.uid !== 0) ||
+            (writable && !stickyRootTemp))
+            failLifecycleStore("unsafe root");
+        identities.push({ dev: info.dev, ino: info.ino, path: current });
+    }
+    return identities;
+};
+const resolveOrCreateConfiguredHome = async (configuredHome, create) => {
+    const logical = chain(configuredHome);
+    let existing = logical[0];
+    let missingAt = logical.length;
+    for (let index = 0; index < logical.length; index += 1) {
+        const current = logical[index];
+        let info;
+        try {
+            info = await lstat(current);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                failLifecycleStore("unsafe root");
+            missingAt = index;
+            break;
+        }
+        if (info.isSymbolicLink()) {
+            if (info.uid !== 0 || (info.mode & 0o022) !== 0 || !(await isKnownDarwinAlias(current))) {
+                failLifecycleStore("unsafe root");
+            }
+        }
+        else if (!info.isDirectory()) {
+            failLifecycleStore("unsafe root");
+        }
+        existing = current;
+    }
+    if (missingAt === logical.length) {
+        return realpath(configuredHome).catch(() => failLifecycleStore("unsafe root"));
+    }
+    if (!create)
+        return null;
+    let canonicalParent = await realpath(existing).catch(() => failLifecycleStore("unsafe root"));
+    let identities = await captureSafeExistingChain(canonicalParent);
+    for (let index = missingAt; index < logical.length; index += 1) {
+        const name = path.basename(logical[index]);
+        const next = path.join(canonicalParent, name);
+        await revalidateIdentities(identities);
+        await mkdir(next, { mode: 0o700 }).catch((error) => {
+            if (error.code !== "EEXIST")
+                failLifecycleStore("unsafe root");
+        });
+        await revalidateIdentities(identities);
+        const created = await lstat(next).catch(() => failLifecycleStore("unsafe root"));
+        if (!created.isDirectory() ||
+            created.isSymbolicLink() ||
+            created.uid !== OWNER ||
+            (created.mode & 0o777) !== 0o700)
+            failLifecycleStore("unsafe root");
+        canonicalParent = next;
+        identities = [...identities, { dev: created.dev, ino: created.ino, path: next }];
+    }
+    return canonicalParent;
+};
+export const revalidateLifecycleRootAuthority = async (authority) => {
+    await validateConfiguredAliases(authority.configuredHome, authority.canonicalHome);
+    for (const expected of authority.identities) {
+        const current = await lstat(expected.path).catch(() => failLifecycleStore("root changed"));
+        const writable = (current.mode & 0o022) !== 0;
+        const stickyRootTemp = current.uid === 0 && writable && (current.mode & 0o1000) !== 0;
+        if (!current.isDirectory() ||
+            current.isSymbolicLink() ||
+            (current.uid !== OWNER && current.uid !== 0) ||
+            (writable && !stickyRootTemp) ||
+            ((expected.path === authority.canonicalHome || expected.path === authority.root) &&
+                (current.uid !== OWNER || (current.mode & 0o777) !== 0o700)))
+            failLifecycleStore("unsafe root");
+        if (current.dev !== expected.dev || current.ino !== expected.ino) {
+            failLifecycleStore("root changed");
+        }
+    }
+};
+export const validateLifecycleRoot = async (create) => {
+    const configuredHome = resolveSpawnfileHome();
+    const cached = authorities.get(configuredHome);
+    if (cached) {
+        await revalidateLifecycleRootAuthority(cached);
+        return cached;
+    }
+    const canonicalHome = await resolveOrCreateConfiguredHome(configuredHome, create);
+    if (canonicalHome === null)
+        return null;
+    await validateConfiguredAliases(configuredHome, canonicalHome);
+    const homeIdentities = await captureSafeExistingChain(canonicalHome);
+    const homeInfo = await lstat(canonicalHome).catch(() => failLifecycleStore("unsafe root"));
+    if (homeInfo.uid !== OWNER || (homeInfo.mode & 0o777) !== 0o700) {
+        failLifecycleStore("unsafe root");
+    }
+    const root = path.join(canonicalHome, "lifecycle-completions");
+    if (create) {
+        await revalidateIdentities(homeIdentities);
+        await mkdir(root, { mode: 0o700 }).catch((error) => {
+            if (error.code !== "EEXIST")
+                failLifecycleStore("unsafe root");
+        });
+        await revalidateIdentities(homeIdentities);
+    }
+    else {
+        try {
+            await lstat(root);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            failLifecycleStore("unsafe root");
+        }
+    }
+    const authority = {
+        canonicalHome,
+        configuredHome,
+        identities: await captureCanonicalChain(canonicalHome, root),
+        root
+    };
+    const prior = authorities.get(configuredHome);
+    if (prior) {
+        await revalidateLifecycleRootAuthority(prior);
+        return prior;
+    }
+    authorities.set(configuredHome, authority);
+    return authority;
+};
+export const lifecycleRoot = async () => (await validateLifecycleRoot(true))?.root ?? failLifecycleStore("unsafe root");
+export const existingLifecycleRoot = async () => (await validateLifecycleRoot(false))?.root ?? null;
+export const requireLifecycleRootAuthority = async () => (await validateLifecycleRoot(true)) ?? failLifecycleStore("unsafe root");
+export const openLifecycleAuthorityRoot = async (authority) => {
+    await revalidateLifecycleRootAuthority(authority);
+    const handle = await open(authority.root, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW).catch(() => failLifecycleStore("root changed"));
+    const expected = authority.identities.at(-1);
+    const info = await handle.stat();
+    if (info.dev !== expected.dev || info.ino !== expected.ino) {
+        await handle.close().catch(() => undefined);
+        failLifecycleStore("root changed");
+    }
+    return handle;
+};
+export const revalidateHeldLifecycleRoot = async (authority, handle) => {
+    const expected = authority.identities.at(-1);
+    const info = await handle.stat();
+    if (info.dev !== expected.dev || info.ino !== expected.ino)
+        failLifecycleStore("root changed");
+    await revalidateLifecycleRootAuthority(authority);
+};
+export const syncLifecycleDirectory = async (directory) => {
+    const authority = await requireLifecycleRootAuthority();
+    if (path.resolve(directory) !== authority.root)
+        failLifecycleStore("unsafe root");
+    const handle = await openLifecycleAuthorityRoot(authority);
+    try {
+        await revalidateHeldLifecycleRoot(authority, handle);
+        await handle.sync();
+        await revalidateHeldLifecycleRoot(authority, handle);
+    }
+    finally {
+        await handle.close();
+    }
+    await revalidateLifecycleRootAuthority(authority);
+};

package/dist/deployment/lifecycleCompletionStore.d.ts

@@ -0,0 +1,6 @@
+export { admissionPath, evidencePath, failLifecycleStore, heartbeatPath, lifecycleRecordName, planPath, recoveryPath, resolveLifecycleCompletionDirectory, resolveLifecycleCompletionPath } from "./lifecycleCompletionPaths.js";
+export { existingLifecycleRoot, lifecycleRoot, syncLifecycleDirectory } from "./lifecycleCompletionRoot.js";
+export type LifecycleStoreTestHookPoint = "before_missing_return" | "before_record_open" | "before_publish_link" | "before_publish_temp_open" | "before_publish_unlink";
+export declare const setLifecycleStoreTestHook: (hook: ((point: LifecycleStoreTestHookPoint) => Promise<void> | void) | null) => void;
+export declare const readLifecycleRecord: (file: string, links?: readonly number[]) => Promise<string | null>;
+export declare const publishLifecycleRecord: (directory: string, file: string, content: string, existing?: "ignore" | "match") => Promise<boolean>;

package/dist/deployment/lifecycleCompletionStore.js

@@ -0,0 +1,151 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { link, lstat, open, unlink } from "node:fs/promises";
+import path from "node:path";
+import { LIFECYCLE_RECORD_MAX_BYTES } from "./lifecycleCompletionContracts.js";
+import { failLifecycleStore, resolveLifecycleCompletionDirectory } from "./lifecycleCompletionPaths.js";
+import { openLifecycleAuthorityRoot, requireLifecycleRootAuthority, revalidateHeldLifecycleRoot, revalidateLifecycleRootAuthority, syncLifecycleDirectory, validateLifecycleRoot } from "./lifecycleCompletionRoot.js";
+import { matchesSettledLifecyclePublication, readSettledLifecycleRecord } from "./lifecycleCompletionPublication.js";
+export { admissionPath, evidencePath, failLifecycleStore, heartbeatPath, lifecycleRecordName, planPath, recoveryPath, resolveLifecycleCompletionDirectory, resolveLifecycleCompletionPath } from "./lifecycleCompletionPaths.js";
+export { existingLifecycleRoot, lifecycleRoot, syncLifecycleDirectory } from "./lifecycleCompletionRoot.js";
+const OWNER = process.getuid?.() ?? -1;
+let testHook = null;
+export const setLifecycleStoreTestHook = (hook) => {
+    testHook = hook;
+};
+const runTestHook = async (point) => {
+    await testHook?.(point);
+};
+const canonicalRecordPath = (file, authority) => {
+    const directory = path.dirname(path.resolve(file));
+    const configuredRoot = resolveLifecycleCompletionDirectory();
+    if (directory !== authority.root && directory !== configuredRoot) {
+        failLifecycleStore("unsafe record");
+    }
+    const base = path.basename(file);
+    if (base.includes(path.sep) || base === "." || base === "..") {
+        failLifecycleStore("unsafe record");
+    }
+    return path.join(authority.root, base);
+};
+export const readLifecycleRecord = async (file, links = [1]) => {
+    const authority = await validateLifecycleRoot(false);
+    if (!authority)
+        return null;
+    await revalidateLifecycleRootAuthority(authority);
+    const exactFile = canonicalRecordPath(file, authority);
+    let before;
+    try {
+        before = await lstat(exactFile);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            await runTestHook("before_missing_return");
+            await revalidateLifecycleRootAuthority(authority);
+            return null;
+        }
+        failLifecycleStore("unsafe record");
+    }
+    if (!before.isFile() || before.isSymbolicLink() || before.uid !== OWNER ||
+        before.size > LIFECYCLE_RECORD_MAX_BYTES || (before.mode & 0o777) !== 0o600 ||
+        !links.includes(before.nlink)) {
+        failLifecycleStore("unsafe record");
+    }
+    await runTestHook("before_record_open");
+    await revalidateLifecycleRootAuthority(authority);
+    const handle = await open(exactFile, constants.O_RDONLY | constants.O_NOFOLLOW)
+        .catch(() => failLifecycleStore("unsafe record"));
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.uid !== OWNER || info.size > LIFECYCLE_RECORD_MAX_BYTES ||
+            (info.mode & 0o777) !== 0o600 || !links.includes(info.nlink)) {
+            failLifecycleStore("unsafe record");
+        }
+        if (before.dev !== info.dev || before.ino !== info.ino)
+            failLifecycleStore("record changed");
+        const content = await handle.readFile({ encoding: "utf8" });
+        const after = await lstat(exactFile).catch(() => failLifecycleStore("record changed"));
+        if (after.dev !== info.dev || after.ino !== info.ino)
+            failLifecycleStore("record changed");
+        await revalidateLifecycleRootAuthority(authority);
+        return content;
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+};
+export const publishLifecycleRecord = async (directory, file, content, existing = "match") => {
+    const authority = await requireLifecycleRootAuthority();
+    if (path.resolve(directory) !== authority.root)
+        failLifecycleStore("unsafe root");
+    const rootHandle = await openLifecycleAuthorityRoot(authority);
+    try {
+        if (Buffer.byteLength(content) > LIFECYCLE_RECORD_MAX_BYTES) {
+            failLifecycleStore("oversize record");
+        }
+        const final = path.join(authority.root, file);
+        if (existing === "match") {
+            if (await matchesSettledLifecyclePublication(final, content, readLifecycleRecord))
+                return false;
+        }
+        else if ((await readSettledLifecycleRecord(final, readLifecycleRecord)) !== null) {
+            return false;
+        }
+        const temp = path.join(authority.root, `.${file}.${process.pid}.${randomUUID()}.tmp`);
+        let handle;
+        let linked = false;
+        try {
+            await runTestHook("before_publish_temp_open");
+            await revalidateHeldLifecycleRoot(authority, rootHandle);
+            handle = await open(temp, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+            await handle.chmod(0o600);
+            await handle.writeFile(content, "utf8");
+            await handle.sync();
+            await handle.close();
+            handle = undefined;
+            try {
+                await runTestHook("before_publish_link");
+                await revalidateHeldLifecycleRoot(authority, rootHandle);
+                await link(temp, final);
+                linked = true;
+                await syncLifecycleDirectory(authority.root);
+            }
+            catch (error) {
+                if (error.code !== "EEXIST") {
+                    failLifecycleStore("publication failed");
+                }
+            }
+        }
+        finally {
+            if (handle)
+                await handle.close().catch(() => undefined);
+            await runTestHook("before_publish_unlink");
+            await revalidateHeldLifecycleRoot(authority, rootHandle);
+            await unlink(temp).catch((error) => {
+                if (error.code !== "ENOENT")
+                    failLifecycleStore("publication cleanup failed");
+            });
+            await syncLifecycleDirectory(authority.root);
+        }
+        if (!linked && existing === "ignore") {
+            if ((await readSettledLifecycleRecord(final, readLifecycleRecord)) === null) {
+                failLifecycleStore("publication changed");
+            }
+            return false;
+        }
+        for (let attempt = 0; attempt < 16; attempt += 1) {
+            const exact = await readLifecycleRecord(final, [1, 2]);
+            if (exact !== content)
+                failLifecycleStore("publication changed");
+            if ((await lstat(final).catch(() => null))?.nlink === 1) {
+                await revalidateHeldLifecycleRoot(authority, rootHandle);
+                return linked;
+            }
+            await new Promise((resolve) => setImmediate(resolve));
+        }
+        return failLifecycleStore("publication did not settle");
+    }
+    finally {
+        await rootHandle.close().catch(() => undefined);
+    }
+};

package/dist/deployment/organizationHandoffAuthorityFsClient.d.ts

@@ -0,0 +1,17 @@
+import { type ChildProcess } from "node:child_process";
+export interface OrganizationHandoffAuthorityFsClientOptions {
+    readonly cwd: string;
+    readonly dev: number;
+    readonly ino: number;
+    readonly parentPid?: number;
+    readonly uid?: number;
+    readonly workerPath?: string;
+    readonly testOnChildStarted?: (child: ChildProcess) => void;
+}
+export interface OrganizationHandoffAuthorityFsClient {
+    create(name: string, content: string): Promise<boolean>;
+    dispose(): Promise<void>;
+    read(name: string): Promise<string | null>;
+    write(name: string, content: string): Promise<void>;
+}
+export declare const initializeOrganizationHandoffAuthorityFsClient: (options: OrganizationHandoffAuthorityFsClientOptions) => Promise<OrganizationHandoffAuthorityFsClient>;

package/dist/deployment/organizationHandoffAuthorityFsClient.js

@@ -0,0 +1,132 @@
+import { fork } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+const VERSION = "spawnfile.organization-handoff-fs-worker.v1";
+const MAX_BYTES = 32_768;
+const fail = () => { throw new Error("Organization handoff authority failed"); };
+const bytes = (value) => Buffer.byteLength(value, "utf8");
+const name = (value) => typeof value === "string" && /^(?:[a-f0-9]{128}|[a-f0-9]{142})\.json$/u.test(value) ? value : fail();
+class Client {
+    #child;
+    #closed = false;
+    #next = 1;
+    #exited;
+    #pending = new Map();
+    constructor(child) {
+        this.#child = child;
+        let settleExit;
+        this.#exited = new Promise((resolve) => { settleExit = resolve; });
+        const settle = () => { this.rejectPending(); settleExit(); };
+        child.on("message", (raw) => this.message(raw));
+        child.on("error", () => this.rejectPending());
+        child.on("disconnect", () => this.rejectPending());
+        child.once("exit", settle);
+        if (child.exitCode !== null || child.signalCode !== null)
+            settle();
+        // `fork(..., { silent: true })` creates pipes. Consume them so a failing
+        // helper cannot block on a full pipe or accumulate stream listeners.
+        child.stdout?.resume();
+        child.stderr?.resume();
+    }
+    terminal() { return this.#child.exitCode !== null || this.#child.signalCode !== null; }
+    rejectPending() { for (const pending of this.#pending.values())
+        pending.reject(); this.#pending.clear(); }
+    message(raw) {
+        if (!raw || typeof raw !== "object")
+            return;
+        const value = raw;
+        if (value.version !== VERSION)
+            return;
+        if (value.ready === true)
+            return;
+        if (!Number.isSafeInteger(value.id) || typeof value.ok !== "boolean")
+            return;
+        const pending = this.#pending.get(value.id);
+        if (!pending)
+            return;
+        this.#pending.delete(value.id);
+        if (value.ok !== true || value.content !== undefined && typeof value.content !== "string"
+            || value.created !== undefined && typeof value.created !== "boolean")
+            pending.reject();
+        else
+            pending.resolve(value);
+    }
+    request(op, file, content) {
+        if (this.#closed || content !== undefined && bytes(content) > MAX_BYTES)
+            return Promise.reject(new Error("Organization handoff authority failed"));
+        const id = this.#next++;
+        const packet = { version: VERSION, id, op, name: name(file), ...(content === undefined ? {} : { content }) };
+        if (bytes(JSON.stringify(packet)) > MAX_BYTES)
+            return Promise.reject(new Error("Organization handoff authority failed"));
+        return new Promise((resolve, reject) => { const timer = setTimeout(() => { this.#pending.delete(id); reject(new Error("Organization handoff authority failed")); }, 3_000); this.#pending.set(id, { resolve: (value) => { clearTimeout(timer); resolve(value); }, reject: () => { clearTimeout(timer); reject(new Error("Organization handoff authority failed")); } }); if (!this.#child.send(packet)) {
+            clearTimeout(timer);
+            this.#pending.delete(id);
+            reject(new Error("Organization handoff authority failed"));
+        } });
+    }
+    async create(file, content) {
+        const result = await this.request("create", file, content);
+        return result.created === true;
+    }
+    async read(file) { return (await this.request("read", file)).content ?? null; }
+    async write(file, content) { await this.request("write", file, content); }
+    async dispose() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.rejectPending();
+        if (!this.terminal()) {
+            if (this.#child.connected) {
+                try {
+                    this.#child.disconnect();
+                }
+                catch { /* already disconnected */ }
+            }
+            this.#child.kill();
+        }
+        let clear;
+        const graceful = await Promise.race([this.#exited.then(() => true), new Promise((resolve) => {
+                const timer = setTimeout(() => resolve(false), 1_000);
+                clear = () => clearTimeout(timer);
+            })]);
+        clear?.();
+        if (!graceful && !this.terminal())
+            this.#child.kill("SIGKILL");
+        await this.#exited;
+        this.#child.stdout?.destroy();
+        this.#child.stderr?.destroy();
+    }
+}
+export const initializeOrganizationHandoffAuthorityFsClient = async (options) => {
+    const source = import.meta.url.endsWith(".ts");
+    const workerPath = options.workerPath ?? fileURLToPath(new URL(source ? "./organizationHandoffAuthorityFsWorker.ts" : "./organizationHandoffAuthorityFsWorker.js", import.meta.url));
+    const tsWorker = workerPath.endsWith(".ts");
+    // The helper's cwd is the protected state directory, which is intentionally
+    // outside the repository. Resolve the source loader before changing cwd so
+    // source-mode tests do not depend on module lookup from that directory.
+    const tsxLoader = tsWorker ? createRequire(import.meta.url).resolve("tsx") : undefined;
+    const child = fork(workerPath, [], { cwd: options.cwd, env: { SPAWNFILE_AUTHORITY_FS_ANCHOR: JSON.stringify({ dev: options.dev, ino: options.ino, uid: options.uid, parent_pid: options.parentPid ?? process.pid }) }, silent: true, ...(tsxLoader === undefined ? {} : { execArgv: ["--import", tsxLoader] }) });
+    const client = new Client(child);
+    options.testOnChildStarted?.(child);
+    try {
+        await new Promise((resolve, reject) => {
+            let timer;
+            const message = (raw) => { if (typeof raw === "object" && raw !== null && raw.ready === true)
+                doneResolve(); };
+            const exited = () => doneReject();
+            const errored = () => doneReject();
+            const clean = () => { clearTimeout(timer); child.off("message", message); child.off("exit", exited); child.off("error", errored); };
+            function doneResolve() { clean(); resolve(); }
+            function doneReject() { clean(); reject(new Error("Organization handoff authority failed")); }
+            timer = setTimeout(doneReject, 3_000);
+            child.on("message", message);
+            child.once("exit", exited);
+            child.once("error", errored);
+        });
+        return client;
+    }
+    catch {
+        await client.dispose();
+        return fail();
+    }
+};

package/dist/deployment/organizationHandoffAuthorityFsWorker.d.ts

@@ -0,0 +1 @@
+export {};