spawnfile 0.1.14 → 0.1.18

package/dist/compiler/workspaceGitFetch.js

@@ -0,0 +1,155 @@
+import { execFile } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { SpawnfileError } from "../shared/index.js";
+const run = promisify(execFile);
+const COMMIT = /^[a-f0-9]{40}$/u;
+const fail = (message) => {
+    throw new SpawnfileError("validation_error", message);
+};
+const shellQuote = (value) => `'${value.replace(/'/g, `'"'"'`)}'`;
+/** The remote ref to fetch, and the commit it must equal when the selector already names one. */
+export const gitPinRefspec = (selector) => {
+    if (selector.kind === "branch")
+        return { source: `refs/heads/${selector.value}` };
+    if (selector.kind === "tag")
+        return { source: `refs/tags/${selector.value}` };
+    if (selector.kind === "ref")
+        return COMMIT.test(selector.value) ? { expected: selector.value, source: selector.value } : { source: selector.value };
+    return { source: "HEAD" };
+};
+/**
+ * Runs `use` with the git environment for one fetch. A key held in an env var
+ * is copied to a private 0600 file in a fresh temporary directory that is
+ * removed afterwards; the key only ever reaches git through `GIT_SSH_COMMAND`.
+ */
+export const withGitPinEnvironment = async (auth, use, environment = process.env) => {
+    // Never prompt, never honour replacement refs: an object id must name its own bytes.
+    const base = { ...environment, GIT_NO_REPLACE_OBJECTS: "1", GIT_TERMINAL_PROMPT: "0" };
+    // The key reaches git and ssh only as a file path, never as an inherited variable.
+    if (auth?.sshKeyEnv !== undefined)
+        delete base[auth.sshKeyEnv];
+    if (auth === undefined)
+        return use(base);
+    let temporary;
+    try {
+        let keyPath;
+        if (auth.sshKeyEnv !== undefined) {
+            const material = environment[auth.sshKeyEnv];
+            if (!material?.trim())
+                fail(`git resource auth env ${auth.sshKeyEnv} is not set`);
+            temporary = await mkdtemp(path.join(os.tmpdir(), "spawnfile-git-key-"));
+            keyPath = path.join(temporary, "key");
+            await writeFile(keyPath, material.endsWith("\n") ? material : `${material}\n`, { mode: 0o600 });
+        }
+        else {
+            keyPath = auth.sshKey;
+            const info = await stat(keyPath).catch(() => undefined);
+            if (!info?.isFile())
+                fail(`git resource ssh_key is not a readable file: ${keyPath}`);
+        }
+        const ssh = `ssh -i ${shellQuote(keyPath)} -o IdentitiesOnly=yes -o BatchMode=yes`;
+        return await use({ ...base, GIT_SSH_COMMAND: ssh });
+    }
+    finally {
+        if (temporary !== undefined)
+            await rm(temporary, { force: true, recursive: true });
+    }
+};
+const git = async (repository, args, env) => {
+    const { stdout } = await run("git", ["-C", repository, ...args], { encoding: "utf8", env, maxBuffer: 16_777_216 });
+    return stdout.trim();
+};
+const LOCK_POLL_MS = 100;
+const processAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+};
+/**
+ * Serializes work on one cache repository across processes on this host: git
+ * keeps one repository-wide `shallow` file, so two shallow fetches into the
+ * same repository can fail each other. A lock whose owner process is gone is
+ * taken over.
+ */
+export const withGitPinLock = async (repository, use) => {
+    const lock = `${repository}.lock`, owner = path.join(lock, "owner");
+    for (;;) {
+        try {
+            await mkdir(lock);
+            await writeFile(owner, `${process.pid}\n`);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const pid = Number.parseInt(await readFile(owner, "utf8").catch(() => ""), 10);
+            const age = Date.now() - ((await stat(lock).catch(() => undefined))?.mtimeMs ?? Date.now());
+            // An owner-less lock older than a few polls belongs to a process that died between mkdir and write.
+            if (Number.isInteger(pid) ? !processAlive(pid) : age > LOCK_POLL_MS * 50)
+                await rm(lock, { force: true, recursive: true });
+            else
+                await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_MS));
+        }
+    }
+    try {
+        return await use();
+    }
+    finally {
+        await rm(lock, { force: true, recursive: true });
+    }
+};
+/** One bare object cache per remote URL. Auto-gc is off: a concurrent compile may still be reading a commit. Call under the lock. */
+const ensureGitPinRepository = async (repository) => {
+    if (await stat(path.join(repository, "HEAD")).catch(() => undefined))
+        return;
+    await rm(repository, { force: true, recursive: true });
+    await run("git", ["init", "--bare", "-q", repository]);
+    await run("git", ["-C", repository, "config", "gc.auto", "0"]);
+};
+const hasCommit = (repository, commit, env) => git(repository, ["cat-file", "-e", `${commit}^{commit}`], env).then(() => true, () => false);
+/**
+ * Resolves `selector` on `url` to one commit and fetches its objects into the
+ * cache, shallowly, under the repository lock. A full commit id already in the
+ * cache is not fetched again, so a recorded pin rebuilds offline. Any failure
+ * to resolve refuses the compile: a pinned resource never falls back to stale
+ * or empty content.
+ */
+export const fetchGitPin = async (cacheDirectory, url, selector, env) => {
+    await mkdir(cacheDirectory, { mode: 0o700, recursive: true });
+    const repository = path.join(cacheDirectory, `${createHash("sha256").update(url).digest("hex")}.git`);
+    return withGitPinLock(repository, async () => {
+        await ensureGitPinRepository(repository);
+        const { expected, source } = gitPinRefspec(selector);
+        if (expected !== undefined && await hasCommit(repository, expected, env))
+            return { commit: expected, repository };
+        // A per-process ref, so a lock taken over from a dead owner never reads its half-written result.
+        const local = `refs/spawnfile/pins/${process.pid}-${randomBytes(6).toString("hex")}`;
+        try {
+            await git(repository, ["fetch", "--quiet", "--no-tags", "--depth=1", "--", url, `+${source}:${local}`], env);
+            const commit = await git(repository, ["rev-parse", "--verify", `${local}^{commit}`], env);
+            if (!COMMIT.test(commit))
+                fail(`git resource ${url} ${selector.kind} ${selector.value} did not resolve to a commit`);
+            if (expected !== undefined && commit !== expected)
+                fail(`git resource ${url} ref ${expected} resolved to ${commit}`);
+            return { commit, repository };
+        }
+        catch (error) {
+            if (error instanceof SpawnfileError)
+                throw error;
+            const stderr = String(error.stderr ?? "").trim().split("\n").filter(Boolean).pop();
+            const what = selector.kind === "none" ? "default branch" : `${selector.kind} ${selector.value}`;
+            return fail(`git resource ${url} ${what} could not be resolved to a commit${stderr ? `: ${stderr}` : ""}`);
+        }
+        finally {
+            await git(repository, ["update-ref", "-d", local], env).catch(() => undefined);
+        }
+    });
+};

package/dist/compiler/workspaceGitPins.d.ts

@@ -0,0 +1,33 @@
+import type { CompileReportWorkspaceGitResource } from "../report/index.js";
+import { type BundleIdentityMode } from "./workspaceBundleFiles.js";
+import type { MoltnetTargetArchitecture } from "./moltnetReleaseAuthority.js";
+import type { CompilePlan } from "./types.js";
+import type { ResolvedWorkspaceResource } from "./workspaceResources.js";
+type GitResource = Extract<ResolvedWorkspaceResource, {
+    kind: "git";
+}>;
+export interface ResolveWorkspaceGitPinsOptions {
+    outputDirectory: string;
+    architecture?: MoltnetTargetArchitecture;
+    /** The workspace bundle cache directory; git objects and archives live beside it under `git-resources/`. */
+    bundleCacheDirectory?: string;
+    identity?: BundleIdentityMode;
+    environment?: NodeJS.ProcessEnv;
+}
+export interface ResolvedWorkspaceGitPins {
+    /** Digest → archive linked into the Docker context, for `stageWorkspaceBundles`. */
+    built: Map<string, string>;
+    report: CompileReportWorkspaceGitResource[];
+}
+export declare const isBuildPinnedGitResource: (resource: ResolvedWorkspaceResource) => resource is GitResource;
+/**
+ * Lowers every `fetch: build` git resource into a pinned read-only bundle:
+ * the declared branch, tag or ref is resolved on the host to one commit, that
+ * commit's tree is archived deterministically (the same writer as built
+ * bundles), and the agent mounts the archive exactly as it mounts a bundle.
+ * No credential, clone or network access reaches the container. The commit
+ * and archive digest are recorded in the compile report; declaring
+ * `ref: <commit>` reproduces the identical archive.
+ */
+export declare const resolveWorkspaceGitPins: (plan: CompilePlan, options: ResolveWorkspaceGitPinsOptions) => Promise<ResolvedWorkspaceGitPins>;
+export {};

package/dist/compiler/workspaceGitPins.js

@@ -0,0 +1,127 @@
+import os from "node:os";
+import path from "node:path";
+import { SpawnfileError } from "../shared/index.js";
+import { linkBuiltBundle } from "./workspaceBundleArtifacts.js";
+import { lookupCachedBundle, pruneBundleCache, resolveWorkspaceBundleCacheDirectory, storeBuiltBundle } from "./workspaceBundleCache.js";
+import { listCommittedTree } from "./workspaceBundleGit.js";
+import { compileExcludePatterns, writeBundleFiles } from "./workspaceBundleFiles.js";
+import { computeWorkspaceBundleKey, resolveBundleArchitecture } from "./workspaceBundleResolve.js";
+import { normalizeBundleMode } from "./workspaceBundleTar.js";
+import { fetchGitPin, withGitPinEnvironment } from "./workspaceGitFetch.js";
+const SYMLINK = 0o120000, GITLINK = 0o160000;
+const fail = (message) => {
+    throw new SpawnfileError("validation_error", message);
+};
+export const isBuildPinnedGitResource = (resource) => resource.kind === "git" && resource.fetch === "build";
+const selectorOf = (resource) => resource.branch ? { kind: "branch", value: resource.branch.trim() }
+    : resource.tag ? { kind: "tag", value: resource.tag.trim() }
+        : resource.ref ? { kind: "ref", value: resource.ref.trim() }
+            : { kind: "none", value: "" };
+const expandPath = (value, base) => value === "~" || value.startsWith("~/") ? path.join(os.homedir(), value.slice(1)) : path.resolve(base, value);
+const authOf = (resource) => {
+    if (!resource.auth)
+        return undefined;
+    return resource.auth.ssh_key !== undefined
+        ? { sshKey: expandPath(resource.auth.ssh_key, path.dirname(resource.scope.key)) }
+        : { sshKeyEnv: resource.auth.ssh_key_env };
+};
+const declarationKey = (resource) => JSON.stringify({
+    auth: authOf(resource) ?? null, exclude: resource.exclude ?? null, selector: selectorOf(resource), url: resource.url.trim()
+});
+/** The committed tree as bundle entries: blob ids and modes only, under the same safety rules as built bundles. */
+const treeEntries = async (resource, repository, commit) => {
+    const excluded = compileExcludePatterns(resource.exclude);
+    const entries = [];
+    for (const entry of await listCommittedTree(repository, commit)) {
+        if (excluded(entry.path))
+            continue;
+        if (entry.mode === SYMLINK)
+            fail(`Workspace git resource ${resource.id} contains a symlink; exclude it: ${entry.path}`);
+        if (entry.mode === GITLINK)
+            fail(`Workspace git resource ${resource.id} contains a submodule; exclude it: ${entry.path}`);
+        if (entry.type !== "blob")
+            fail(`Workspace git resource ${resource.id} has unsupported git type ${entry.type}: ${entry.path}`);
+        if (!entry.path || entry.path.includes("\\") || entry.path.split("/").some((part) => !part || part === "." || part === "..")) {
+            fail(`Workspace git resource ${resource.id} path cannot be archived safely: ${entry.path}`);
+        }
+        entries.push({ identity: `git:${entry.objectId}`, mode: normalizeBundleMode(entry.mode), objectId: entry.objectId, path: entry.path });
+    }
+    if (entries.length === 0)
+        fail(`Workspace git resource ${resource.id} has no files at ${commit}`);
+    return entries.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
+};
+/**
+ * Lowers every `fetch: build` git resource into a pinned read-only bundle:
+ * the declared branch, tag or ref is resolved on the host to one commit, that
+ * commit's tree is archived deterministically (the same writer as built
+ * bundles), and the agent mounts the archive exactly as it mounts a bundle.
+ * No credential, clone or network access reaches the container. The commit
+ * and archive digest are recorded in the compile report; declaring
+ * `ref: <commit>` reproduces the identical archive.
+ */
+export const resolveWorkspaceGitPins = async (plan, options) => {
+    const result = { built: new Map(), report: [] };
+    const recording = plan.nodes.some((node) => node.kind === "agent" && node.value.training?.record !== undefined);
+    const pinned = plan.nodes.flatMap((node) => node.kind === "agent" ? (node.value.workspaceResources ?? []).filter(isBuildPinnedGitResource) : []);
+    if (pinned.length === 0)
+        return result;
+    const root = path.join(path.dirname(resolveWorkspaceBundleCacheDirectory(options.bundleCacheDirectory)), "git-resources");
+    const objects = path.join(root, "objects"), archives = path.join(root, "archives");
+    const platform = `linux/${resolveBundleArchitecture(options.architecture)}`, identity = options.identity ?? "dev";
+    const resolved = new Map(), usedKeys = new Set();
+    for (const resource of pinned) {
+        const memoKey = declarationKey(resource);
+        if (resolved.has(memoKey))
+            continue;
+        const selector = selectorOf(resource), auth = authOf(resource), url = resource.url.trim();
+        const { commit, repository } = await withGitPinEnvironment(auth, (env) => fetchGitPin(objects, url, selector, env), options.environment);
+        const entries = await treeEntries(resource, repository, commit);
+        const key = computeWorkspaceBundleKey({ entries }, platform);
+        usedKeys.add(key);
+        let cached = await lookupCachedBundle(archives, key), staged = cached && await linkBuiltBundle(cached.tarPath, options.outputDirectory, cached.sha256);
+        if (!cached || !staged) {
+            cached = await storeBuiltBundle(archives, key, (temporaryPath) => writeBundleFiles({ directory: repository, entries, mode: "release" }, temporaryPath));
+            staged = await linkBuiltBundle(cached.tarPath, options.outputDirectory, cached.sha256);
+            if (!staged)
+                throw new SpawnfileError("compile_error", `Workspace git resource archive vanished from the cache while it was staged: ${key}`);
+        }
+        result.built.set(cached.sha256, staged);
+        resolved.set(memoKey, {
+            commit,
+            facts: {
+                auth: auth === undefined ? "none" : auth.sshKey !== undefined ? "ssh_key" : "ssh_key_env",
+                cache_key: key, commit, content_bytes: cached.contentBytes, file_count: cached.fileCount, id: resource.id, identity,
+                platform, selector: selector.kind === "none" ? { kind: "default_branch" } : { kind: selector.kind, value: selector.value },
+                sha256: cached.sha256, url
+            }
+        });
+    }
+    for (const node of plan.nodes) {
+        if (node.kind !== "agent" || !node.value.workspaceResources?.some(isBuildPinnedGitResource))
+            continue;
+        node.value.workspaceResources = node.value.workspaceResources.map((resource) => {
+            if (!isBuildPinnedGitResource(resource))
+                return resource;
+            const { facts } = resolved.get(declarationKey(resource));
+            const same = (existing) => existing.id === resource.id && existing.url === facts.url && existing.commit === facts.commit && existing.sha256 === facts.sha256 && JSON.stringify(existing.selector) === JSON.stringify(facts.selector);
+            if (recording) {
+                const declared_by = plan.nodes.find((entry) => entry.value.source === resource.scope.key)?.id;
+                let pin = result.report.find((entry) => same(entry) && entry.declared_by === declared_by);
+                if (!pin) {
+                    pin = { ...facts, id: resource.id, agent_node_ids: [], ...(declared_by ? { declared_by } : {}) };
+                    result.report.push(pin);
+                }
+                if (!pin.agent_node_ids.includes(node.id))
+                    pin.agent_node_ids.push(node.id);
+                pin.agent_node_ids.sort();
+            }
+            else if (!result.report.some(same))
+                result.report.push({ ...facts, id: resource.id });
+            // From here on it is a bundle: same staging, same identity-checked read-only mount, no auth fields.
+            return { id: resource.id, kind: "bundle", mode: "readonly", mount: resource.mount, scope: resource.scope, sha256: facts.sha256, sharing: "per_agent" };
+        });
+    }
+    await pruneBundleCache(archives, usedKeys);
+    result.report.sort((left, right) => left.id.localeCompare(right.id) || left.url.localeCompare(right.url) || left.commit.localeCompare(right.commit) || left.sha256.localeCompare(right.sha256));
+    return result;
+};

package/dist/compiler/workspaceResources.d.ts

@@ -1,4 +1,4 @@
-import type { TeamWorkspaceResource } from "../manifest/index.js";
+import type { TeamWorkspaceResource, WorkspaceBundleBuild } from "../manifest/index.js";
 export type WorkspaceResourceSharing = "per_agent" | "team";
 export interface WorkspaceResourceScope {
     kind: "agent" | "team";
@@ -10,19 +10,26 @@ export type ResolvedWorkspaceResource = TeamWorkspaceResource & {
     sharing: WorkspaceResourceSharing;
 };
 export interface WorkspaceResourcePlan {
+    archivePath?: string;
     backingPath: string;
     branch?: string;
     id: string;
-    kind: "git" | "volume";
+    kind: "bundle" | "git" | "volume";
     linkPath: string;
     mode: "mutable" | "readonly";
     mount: string;
     name?: string;
     ref?: string;
     sharing: WorkspaceResourceSharing;
+    sha256?: string;
+    source?: string;
     tag?: string;
     url?: string;
 }
+/** Multi-agent runtime targets retain one resource identity per source agent. */
+export declare const workspaceResourceTargetId: (targetId: string, sourceId: string, sourceCount: number) => string;
+/** A bundle build declaration with every relative path resolved against the declaring manifest's directory. */
+export declare const resolveBundleBuildPaths: (build: WorkspaceBundleBuild, base: string) => WorkspaceBundleBuild;
 export declare const mergeWorkspaceResources: (inherited: ResolvedWorkspaceResource[] | undefined, local: TeamWorkspaceResource[] | undefined, ownerName: string, ownerScope: WorkspaceResourceScope) => ResolvedWorkspaceResource[];
 export declare const toWorkspaceResourcePlan: (resource: ResolvedWorkspaceResource, context: {
     targetId: string;

package/dist/compiler/workspaceResources.js

@@ -1,6 +1,8 @@
 import path from "node:path";
 import { SpawnfileError } from "../shared/index.js";
 import { createShortHash, slugify } from "./helpers.js";
+/** Multi-agent runtime targets retain one resource identity per source agent. */
+export const workspaceResourceTargetId = (targetId, sourceId, sourceCount) => sourceCount > 1 ? `${targetId}:${sourceId}` : targetId;
 const normalizeMount = (value) => {
     const trimmed = value.trim();
     const workspaceRelative = trimmed.startsWith("${workspace}/")
@@ -13,10 +15,29 @@ const normalizeMount = (value) => {
     }
     return collapsed.length > 1 ? collapsed.replace(/\/+$/u, "") : "/";
 };
+/** A bundle build declaration with every relative path resolved against the declaring manifest's directory. */
+export const resolveBundleBuildPaths = (build, base) => {
+    const files = (input) => ({ ...input, root: path.resolve(base, input.root) });
+    if (build.files)
+        return { files: files(build.files) };
+    if (build.dependencies)
+        return { dependencies: { ...build.dependencies, directory: path.resolve(base, build.dependencies.directory) } };
+    const generated = build.generated;
+    return { generated: { ...generated, cwd: path.resolve(base, generated.cwd ?? "."), inputs: generated.inputs.map(files) } };
+};
 const normalizeResourceIdentity = (resource) => {
+    if (resource.kind === "bundle") {
+        // Relative paths compare as resolved against their declaring manifest: the same text in two directories is two inputs.
+        const base = path.dirname(resource.scope.key);
+        const build = resource.build && resolveBundleBuildPaths(resource.build, base);
+        return JSON.stringify({ build: build ?? null, kind: resource.kind, mode: resource.mode, mount: normalizeMount(resource.mount), sha256: resource.sha256 ?? null, source: resource.source === undefined ? null : path.resolve(base, resource.source), sharing: resource.sharing });
+    }
     if (resource.kind === "git") {
         return JSON.stringify({
+            auth: resource.auth ?? null,
             branch: resource.branch?.trim() ?? "",
+            exclude: resource.exclude ?? null,
+            fetch: resource.fetch ?? "start",
             kind: "git",
             mode: resource.mode,
             mount: normalizeMount(resource.mount),
@@ -27,6 +48,8 @@ const normalizeResourceIdentity = (resource) => {
         });
     }
     return JSON.stringify({
+        // Feed paths resolve against the declaring manifest, like bundle inputs.
+        ...(resource.feed ? { feed: { ...resource.feed, base: path.dirname(resource.scope.key) } } : {}),
         kind: "volume",
         mode: resource.mode,
         mount: normalizeMount(resource.mount),
@@ -39,12 +62,9 @@ const mountsOverlap = (left, right) => left === right ||
     left.startsWith(`${right}/`) ||
     right.startsWith(`${left}/`);
 const resolveSharing = (resource) => resource.sharing ?? "per_agent";
-const toResolvedResource = (resource, scope) => ({
-    ...resource,
-    mount: normalizeMount(resource.mount),
-    scope,
-    sharing: resolveSharing(resource)
-});
+const toResolvedResource = (resource, scope) => resource.kind === "bundle"
+    ? { ...resource, mount: normalizeMount(resource.mount), scope, sharing: "per_agent" }
+    : { ...resource, mount: normalizeMount(resource.mount), scope, sharing: resolveSharing(resource) };
 const createPathSegment = (value) => {
     const slug = slugify(value);
     const hash = createShortHash(value);
@@ -89,6 +109,12 @@ export const mergeWorkspaceResources = (inherited = [], local = [], ownerName, o
     }
     return merged.sort((left, right) => left.id.localeCompare(right.id));
 };
+/** A bundle's digest exists only after `resolveWorkspaceBundles` built or hashed it. */
+const resolvedBundleDigest = (resource) => {
+    if (resource.sha256 === undefined)
+        throw new SpawnfileError("compile_error", `Workspace bundle ${resource.id} has not been built`);
+    return resource.sha256;
+};
 export const toWorkspaceResourcePlan = (resource, context) => resource.kind === "git"
     ? {
         backingPath: resolveBackingPath(resource, context.targetId),
@@ -103,7 +129,13 @@ export const toWorkspaceResourcePlan = (resource, context) => resource.kind ===
         ...(resource.tag ? { tag: resource.tag } : {}),
         url: resource.url
     }
-    : {
+    : resource.kind === "bundle" ? {
+        archivePath: `/opt/spawnfile/workspace-bundles/${resolvedBundleDigest(resource).slice(7)}.tar`,
+        backingPath: resolveBackingPath(resource, context.targetId), id: resource.id, kind: "bundle",
+        linkPath: resolveLinkPath(normalizeMount(resource.mount), context.workspacePath), mode: resource.mode,
+        mount: normalizeMount(resource.mount), sharing: resource.sharing, sha256: resolvedBundleDigest(resource),
+        ...(resource.source !== undefined ? { source: path.resolve(path.dirname(resource.scope.key), resource.source) } : {})
+    } : {
         backingPath: resolveBackingPath(resource, context.targetId),
         id: resource.id,
         kind: "volume",

package/dist/deployment/activation.d.ts

@@ -0,0 +1,3 @@
+import type { DeploymentActivation } from "./resourceLog.js";
+/** Strictly later than the stopped observation, even at millisecond clock resolution. */
+export declare const activationBeforeStart: (stoppedAt: number | undefined, now?: () => Date) => Promise<DeploymentActivation>;

package/dist/deployment/activation.js

@@ -0,0 +1,12 @@
+import { setTimeout } from "node:timers/promises";
+/** Strictly later than the stopped observation, even at millisecond clock resolution. */
+export const activationBeforeStart = async (stoppedAt, now = () => new Date()) => {
+    for (let attempt = 0; attempt < 1_000; attempt += 1) {
+        const instant = now();
+        if (stoppedAt === undefined || instant.getTime() > stoppedAt) {
+            return { activated_at: instant.toISOString(), activation_exact: true };
+        }
+        await setTimeout(1);
+    }
+    throw new Error("Host clock did not advance after the previous container stopped");
+};

package/dist/deployment/artifactsExportPlan.js

@@ -1,4 +1,5 @@
 import path from "node:path/posix";
+import { DAIMON_GROK_TURN_USAGE_LEDGER } from "../runtime/daimon/contractManifest.js";
 const AGENT_NODE_ID_PREFIX = "agent:";
 const TEAM_NODE_ID_PREFIX = "team:";
 /** Strips the compiler's `agent:` node-id prefix down to the generated runtime slug, the
@@ -122,6 +123,54 @@ const planDaimonFiles = (report, mounts) => (report.container?.runtime_instances
             }
         }];
 }));
+/** The persistent-mount id the Daimon adapter gives the per-turn engine usage ledger
+ * (`src/runtime/daimon/config.ts`). Deliberately still says `grok` now that AGY writes
+ * there too: the id is the volume's identity, and renaming it orphans every existing
+ * deployment's accumulated ledger. */
+const DAIMON_USAGE_MOUNT_ID = "daimon-grok-usage-ledger";
+/** Daimon usage: the organization-wide per-turn engine token ledger.
+ *
+ * Unlike the causal streams above this is NOT per agent -- one exclusive-reattach volume
+ * carries every metered turn for the whole Daimon host -- so it exports flat under
+ * `raw/daimon/`, the way a single managed Moltnet network exports flat under
+ * `raw/moltnet/`. Flat also keeps it clear of the `raw/daimon/<slug>/` directories the
+ * per-agent causal files use.
+ *
+ * BOTH generations ship. The broker rotates by size at
+ * `DAIMON_GROK_TURN_USAGE_LEDGER.rotateBytes`, so a long-lived deployment's earlier turns
+ * live in `usage.jsonl.1`; exporting only the live file would silently truncate history
+ * for exactly the runs expensive enough to care about. This is the same rotation the read
+ * path already handles (`src/runtime/usageLedgerRead.ts` reads both generations).
+ *
+ * The mount root IS the ledger directory (`mountPath` is
+ * `DAIMON_GROK_TURN_USAGE_LEDGER.directoryPath`), so both names are resolved as
+ * mount-relative paths off the pinned contract constants rather than written out here --
+ * if the contract ever moves the ledger, this follows it instead of silently exporting
+ * nothing.
+ *
+ * Optional, because absent must stay distinguishable from empty: a codex-only
+ * organization is never provisioned this volume and writes no ledger at all, which is
+ * legitimate, and the mount is absent from the report entirely in that case. Where the
+ * volume exists but a generation does not (no rotation yet, or no metered turn yet), the
+ * executor records it under `missingOptionalFiles` rather than as an exported empty file
+ * (`artifactsExport.ts`). */
+const planDaimonUsageFiles = (mounts) => {
+    const mount = mounts.get(DAIMON_USAGE_MOUNT_ID);
+    if (!mount) {
+        return [];
+    }
+    return [
+        DAIMON_GROK_TURN_USAGE_LEDGER.filePath,
+        DAIMON_GROK_TURN_USAGE_LEDGER.rotatedFilePath
+    ].map((absolutePath) => {
+        const volumePath = path.relative(DAIMON_GROK_TURN_USAGE_LEDGER.directoryPath, absolutePath);
+        return {
+            optional: true,
+            relativePath: `raw/daimon/${volumePath}`,
+            source: { kind: "volume", volumeName: mount.volume_name, volumePath }
+        };
+    });
+};
 /** Resolves every durable artifact file this run's compile report declares, and where each
  * one is read from. Pure function of the compile report alone (no deployment record, no
  * Docker) — `artifactsExport.ts` supplies the live container name at execution time. */
@@ -130,6 +179,7 @@ export const planArtifactExports = (report) => {
     return [
         ...planMoltnetFiles(report, mounts),
         ...planMnemeFiles(report, mounts),
-        ...planDaimonFiles(report, mounts)
+        ...planDaimonFiles(report, mounts),
+        ...planDaimonUsageFiles(mounts)
     ];
 };

package/dist/deployment/canaryCutover.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+export declare const deploymentIdentitySchema: z.ZodObject<{
+    version: z.ZodLiteral<"spawnfile.deployment-identity.v1">;
+    run_id: z.ZodString;
+    fingerprint: z.ZodString;
+    deployment_name: z.ZodString;
+    deployment_mode: z.ZodEnum<{
+        image: "image";
+        project: "project";
+    }>;
+    image_id: z.ZodString;
+    organization_unit_id: z.ZodString;
+    organization_compile_fingerprint: z.ZodString;
+    organization_world_binding_digest: z.ZodNullable<z.ZodString>;
+    topology_sha256: z.ZodString;
+}, z.core.$strict>;
+type Execute = (command: string, args: string[]) => Promise<string | void>;
+type Inspect = (command: string, args: string[]) => Promise<string>;
+export declare const verifyCandidatePortIsolation: (liveReport: unknown, candidateReport: unknown) => number[];
+export declare const issueDeploymentIdentity: (readinessPath: string, deploymentMode: "project" | "image", dockerCommand: string, imageInspect?: Inspect) => Promise<Record<string, unknown>>;
+export declare const runCanaryCutover: (input: {
+    liveReportPath: string;
+    candidateReportPath: string;
+    readinessPath: string;
+    expectedIdentity: unknown;
+    dockerCommand: string;
+    nonce: string;
+    transactionPath: string;
+    ingressCommand: string;
+    ingressArgs: string[];
+    ingressReceiptPath: string;
+    teardownCommand: string;
+    teardownArgs: string[];
+    teardownPolicy: "export" | "force";
+    teardownProjectPath: string;
+    teardownCompiledPath: string;
+    decisionReceiptPath: string;
+    fromDeployment: string;
+    toDeployment: string;
+}, runner?: Execute, imageInspect?: Inspect) => Promise<Record<string, unknown>>;
+export declare const verifyEquivalentRollbackReadiness: (rollbackReadinessPath: string, expectedIdentity: unknown) => Promise<void>;
+export {};