spawnfile 0.1.17 → 0.1.19

package/dist/compiler/training/rewind/select.js

@@ -0,0 +1,64 @@
+import { compareInstants, normalizeInstant } from "./instant.js";
+import { hasRecordPin, recordActivationErrors, recordForInput, recordPins } from "./recordInput.js";
+/** Shared targets referencing the same role/dataset/example are one trial. */
+export const selectTrainingExample = (plan, selector) => {
+    const match = /^(train|validation|test):(.*)$/u.exec(selector);
+    const role = match?.[1], id = match?.[2] ?? selector;
+    const candidates = new Map();
+    for (const target of plan.targets)
+        for (const candidateRole of ["train", "validation", "test"]) {
+            const dataset = target.datasets[candidateRole];
+            if (!dataset || (role && candidateRole !== role))
+                continue;
+            for (const example of dataset.examples) {
+                if (example.id !== id)
+                    continue;
+                const candidate = { id, role: candidateRole, dataset: dataset.path, sourcePath: dataset.sourcePath, example };
+                candidates.set(JSON.stringify([candidateRole, dataset.sourcePath, id]), candidate);
+            }
+        }
+    const found = [...candidates.values()];
+    if (found.length !== 1)
+        throw new Error(found.length === 0
+            ? `No training example matches ${selector}`
+            : `Ambiguous training example ${selector}; candidates: ${found.map((item) => `${item.role}:${id} (${item.dataset})`).sort().join(", ")}`);
+    return found[0];
+};
+const canonical = (value) => JSON.stringify(value, (_key, item) => item && typeof item === "object" && !Array.isArray(item)
+    ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a.localeCompare(b))) : item);
+export const matchingMomentRecords = (records, agent, at) => records.filter((record) => record.agent === agent && compareInstants(record.wake.at, at) === 0);
+/** Replays can share executionId AND startedAt. Keep every earliest tie for per-input agreement. */
+export const originalMomentRecords = (records) => {
+    const first = records.reduce((earliest, entry) => !earliest || compareInstants(entry.wake.startedAt, earliest.wake.startedAt) < 0 ? entry : earliest, null);
+    return first ? records.filter((entry) => compareInstants(entry.wake.startedAt, first.wake.startedAt) === 0) : [];
+};
+/** Capture time and wake payload are not used to materialize data. Normalize actual used instants. */
+export const selectMomentRecord = (records, agent, at, inputs) => {
+    const matches = originalMomentRecords(matchingMomentRecords(records, agent, at));
+    if (!matches.length)
+        return null;
+    const identities = inputs ?? matches.flatMap((record) => [
+        ...[...record.resources, ...record.feeds, ...record.volumes].map(({ id }) => ({ section: "resources", id, declaredBy: agent })),
+        ...record.memory.map(({ id, declaredBy }) => ({ section: "memory", id, declaredBy })),
+        ...record.moltnet.map(({ network }) => ({ section: "networks", id: network, declaredBy: agent }))
+    ]);
+    for (const input of identities) {
+        if ("overridden" in input && input.overridden)
+            continue;
+        const declaredPin = "declaration" in input && input.section === "resources" && input.declaration.kind === "git"
+            && /^(?:[a-fA-F0-9]{40}|[a-fA-F0-9]{64})$/u.test(input.declaration.ref ?? "");
+        const decision = (record) => {
+            const usable = recordForInput(record, input);
+            const pins = recordPins(usable, input).map((pin) => "landedAt" in pin ? { ...pin, landedAt: normalizeInstant(pin.landedAt) }
+                : "cursor" in pin ? { ...pin, cursor: normalizeInstant(pin.cursor) } : pin);
+            return canonical({ pin: declaredPin ? "declared-pin" : pins.sort((a, b) => canonical(a).localeCompare(canonical(b))),
+                approximateActivation: !declaredPin && pins.some((pin) => "kind" in pin && ["git", "bundle"].includes(pin.kind))
+                    && recordActivationErrors(usable).length > 0,
+                approximateFallback: !record.exact && !hasRecordPin(usable, input) });
+        };
+        if (matches.some((record) => decision(record) !== decision(matches[0]))) {
+            throw new Error(`Conflicting moment records for ${agent} at ${normalizeInstant(at)}: ${input.section} ${input.declaredBy}/${input.id} has different effective pin/fallback decisions`);
+        }
+    }
+    return matches[0];
+};

package/dist/compiler/training/rewind/snapshotManifest.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { type History } from "./history.js";
+/** Daimon's manifest records source identity, not the identity of retained/copied inodes. */
+export declare const snapshotManifestSchema: z.ZodObject<{
+    version: z.ZodLiteral<"noopolis.daimon.wake-moment.v1">;
+    id: z.ZodString;
+    snapshot: z.ZodString;
+    started_at: z.ZodISODateTime;
+    sourcePath: z.ZodString;
+    entries: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            file: "file";
+            directory: "directory";
+            symlink: "symlink";
+        }>;
+        mode: z.ZodNumber;
+        size: z.ZodString;
+        source: z.ZodObject<{
+            dev: z.ZodString;
+            ino: z.ZodString;
+            size: z.ZodString;
+            mtimeNs: z.ZodString;
+            ctimeNs: z.ZodString;
+            mode: z.ZodNumber;
+        }, z.core.$strict>;
+        target: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SnapshotManifest = z.infer<typeof snapshotManifestSchema>;
+export declare const snapshotHistoryPath: (agentSlug: string, id: string, snapshot: string) => string;
+export declare const readSnapshotManifest: (history: History, relative: string, id: string, snapshot: string) => Promise<SnapshotManifest | null>;
+interface TreeInspection {
+    retained?: boolean;
+    readBytes?: (relative: string) => Promise<Buffer>;
+    expectedBytes?: (relative: string) => Promise<Buffer>;
+}
+/** No symlink traversal. A separate call inspects the copied tree, independently of the producer. */
+export declare const snapshotTreeFindings: (root: string, manifest: SnapshotManifest, options?: TreeInspection) => Promise<string[]>;
+export declare const snapshotBytes: (history: History, relative: string, name: string) => Promise<Buffer>;
+/** Retained files may be hard-linked to each other; bundle files are always new copies. */
+export declare const copySnapshotTree: (history: History, relative: string, destination: string, manifest: SnapshotManifest) => Promise<void>;
+export {};

package/dist/compiler/training/rewind/snapshotManifest.js

@@ -0,0 +1,134 @@
+import { createHash } from "node:crypto";
+import { chmod, lstat, mkdir, readFile, readdir, readlink, symlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { trainingInstantSchema } from "../../../manifest/index.js";
+import { inside, safeSegment } from "./history.js";
+const unsigned = z.string().regex(/^(?:0|[1-9][0-9]*)$/u);
+const nanos = z.string().regex(/^-?(?:0|[1-9][0-9]*)$/u);
+const mode = z.number().int().min(0).max(0xffff);
+const relativePath = z.string().min(1).refine((value) => !value.includes("\\") && !value.includes("\0")
+    && !path.posix.isAbsolute(value) && !value.split("/").some((part) => !part || part === "." || part === ".."), "Snapshot paths must be normalized relative POSIX paths");
+const sourceIdentity = z.object({ dev: unsigned, ino: unsigned, size: unsigned, mtimeNs: nanos, ctimeNs: nanos, mode }).strict();
+const entrySchema = z.object({ type: z.enum(["file", "directory", "symlink"]), mode, size: unsigned,
+    source: sourceIdentity, target: z.string().refine((value) => !value.includes("\0")).optional() }).strict().superRefine((entry, ctx) => {
+    if ((entry.type === "symlink") !== (entry.target !== undefined))
+        ctx.addIssue({ code: "custom", message: "Only snapshot symlinks require a target" });
+    if (entry.mode !== entry.source.mode || entry.size !== entry.source.size)
+        ctx.addIssue({ code: "custom", message: "Snapshot source identity disagrees with entry metadata" });
+    const typeMode = { file: 0o100000, directory: 0o040000, symlink: 0o120000 }[entry.type];
+    if ((entry.mode & 0o170000) !== typeMode)
+        ctx.addIssue({ code: "custom", message: "Snapshot mode disagrees with entry type" });
+});
+/** Daimon's manifest records source identity, not the identity of retained/copied inodes. */
+export const snapshotManifestSchema = z.object({ version: z.literal("noopolis.daimon.wake-moment.v1"), id: z.string().min(1),
+    snapshot: z.string().min(1), started_at: trainingInstantSchema,
+    sourcePath: z.string().refine((value) => path.posix.isAbsolute(value) && !value.includes("\0"), "Expected an absolute snapshot sourcePath"),
+    entries: z.record(relativePath, entrySchema) }).strict().superRefine((manifest, ctx) => {
+    for (const name of Object.keys(manifest.entries)) {
+        for (let parent = path.posix.dirname(name); parent !== "."; parent = path.posix.dirname(parent)) {
+            if (manifest.entries[parent]?.type !== "directory")
+                ctx.addIssue({ code: "custom", message: `Snapshot parent ${parent} must be a recorded directory` });
+        }
+    }
+});
+export const snapshotHistoryPath = (agentSlug, id, snapshot) => `recording/${safeSegment(agentSlug)}/snapshots/${safeSegment(id === "." || id === ".." ? id.replaceAll(".", "%2E") : id)}/${safeSegment(snapshot)}`;
+export const readSnapshotManifest = async (history, relative, id, snapshot) => {
+    // Daimon publishes this marker only after the tree and manifest are durable.
+    if (await history.bytes(`${relative}.complete`) === null)
+        return null;
+    const bytes = await history.text(`${relative}.manifest.json`);
+    if (bytes === null)
+        return null;
+    let manifest;
+    try {
+        manifest = snapshotManifestSchema.parse(JSON.parse(bytes));
+    }
+    catch (error) {
+        throw new Error(`Invalid snapshot manifest ${relative}.manifest.json: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (manifest.id !== id || manifest.snapshot !== snapshot)
+        throw new Error(`Snapshot manifest identity mismatch at ${relative}.manifest.json`);
+    return manifest;
+};
+/** No symlink traversal. A separate call inspects the copied tree, independently of the producer. */
+export const snapshotTreeFindings = async (root, manifest, options = {}) => {
+    if (!(await lstat(root)).isDirectory())
+        throw new Error("Snapshot tree must be a real directory");
+    const findings = [], found = new Set();
+    const visit = async (relative) => {
+        for (const leaf of (await readdir(path.join(root, relative))).sort()) {
+            const name = relative ? `${relative}/${leaf}` : leaf, file = path.join(root, name);
+            const stat = await lstat(file, { bigint: true }), expected = manifest.entries[name];
+            found.add(name);
+            const type = stat.isFile() ? "file" : stat.isDirectory() ? "directory" : stat.isSymbolicLink() ? "symlink" : "special";
+            if (!expected)
+                findings.push(`Unexpected snapshot entry ${name}`);
+            else if (type !== expected.type)
+                findings.push(`Snapshot type mismatch for ${name}`);
+            else {
+                // Recorder directories are deliberately 0700. Restore source modes while copying.
+                const wantedMode = options.retained && type === "file" ? expected.mode & 0o777 : expected.mode & 0o7777;
+                if (!(options.retained && type === "directory") && (Number(stat.mode) & 0o7777) !== wantedMode)
+                    findings.push(`Snapshot mode mismatch for ${name}`);
+                // Directory inode sizes describe source filesystem bookkeeping, not tree content.
+                if (type !== "directory" && stat.size.toString() !== expected.size)
+                    findings.push(`Snapshot size mismatch for ${name}`);
+                if (type === "symlink" && await readlink(file) !== expected.target)
+                    findings.push(`Snapshot symlink target mismatch for ${name}`);
+                if (type === "file" && options.expectedBytes) {
+                    const actual = options.readBytes ? await options.readBytes(name) : await readFile(file);
+                    const original = await options.expectedBytes(name);
+                    const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+                    if (digest(actual) !== digest(original))
+                        findings.push(`Snapshot digest mismatch for ${name}`);
+                }
+            }
+            if (type === "directory")
+                await visit(name);
+        }
+    };
+    await visit("");
+    for (const name of Object.keys(manifest.entries))
+        if (!found.has(name))
+            findings.push(`Missing snapshot entry ${name}`);
+    return findings;
+};
+export const snapshotBytes = async (history, relative, name) => {
+    const bytes = await history.bytes(`${relative}/${name}`);
+    if (bytes === null)
+        throw new Error(`Missing snapshot entry ${name}`);
+    return bytes;
+};
+/** Retained files may be hard-linked to each other; bundle files are always new copies. */
+export const copySnapshotTree = async (history, relative, destination, manifest) => {
+    const source = await history.path(relative);
+    if (!source)
+        throw new Error(`Missing snapshot tree ${relative}`);
+    const findings = await snapshotTreeFindings(source, manifest, { retained: true });
+    if (findings.length)
+        throw new Error(findings.join("; "));
+    await mkdir(destination, { recursive: true, mode: 0o700 });
+    const entries = Object.entries(manifest.entries).sort(([a], [b]) => a.split("/").length - b.split("/").length || a.localeCompare(b));
+    for (const [name, entry] of entries) {
+        const target = path.join(destination, name);
+        if (entry.type === "directory")
+            await mkdir(target, { mode: 0o700 });
+        else if (entry.type === "symlink") {
+            if (path.isAbsolute(entry.target) || !inside(destination, path.resolve(path.dirname(target), entry.target))) {
+                throw new Error(`Snapshot symlink escapes root: ${name}`);
+            }
+            await symlink(entry.target, target);
+        }
+        else {
+            await writeFile(target, await snapshotBytes(history, relative, name), { flag: "wx" });
+            await chmod(target, entry.mode & 0o7777);
+        }
+    }
+    for (const [name, entry] of entries.reverse())
+        if (entry.type === "directory")
+            await chmod(path.join(destination, name), entry.mode & 0o7777);
+    const copied = await snapshotTreeFindings(destination, manifest, { expectedBytes: (name) => snapshotBytes(history, relative, name) });
+    if (copied.length)
+        throw new Error(copied.join("; "));
+};

package/dist/compiler/training/rewind/taskClock.d.ts

@@ -0,0 +1,12 @@
+/** Shared ecosystem range applies to trial instants, not historical source timestamps. */
+export declare const assertTaskClockInstant: (instant: string) => void;
+export declare const createTaskClock: (origin: string) => {
+    version: "spawnfile.task-clock.v1";
+    origin: string;
+};
+/** Top-level Daimon only: its clock stays real and it derives each child's clock environment. */
+export declare const harnessTaskClockEnvironment: (origin: string, anchorEpochMs: number) => Record<string, string>;
+/** Child/tool wall clock. Trial preparation supplies libfaketime LD_PRELOAD and a dot-decimal locale. */
+export declare const processClockEnvironment: (origin: string, anchorEpochMs: number) => Record<string, string>;
+/** Clock-aware child (e.g. Mneme) without libfaketime: apply the offset inside the process exactly once. */
+export declare const clockAwareEnvironment: (origin: string, anchorEpochMs: number) => Record<string, string>;

package/dist/compiler/training/rewind/taskClock.js

@@ -0,0 +1,40 @@
+import { instantNanos, normalizeInstant } from "./instant.js";
+import { taskClockSchema } from "./contract.js";
+/** Shared ecosystem range applies to trial instants, not historical source timestamps. */
+export const assertTaskClockInstant = (instant) => {
+    const nanos = instantNanos(instant);
+    if (nanos < 0n || nanos > 253402300799999000000n) {
+        throw new Error(`Trial instant ${instant} must be within 1970-01-01T00:00:00Z .. 9999-12-31T23:59:59.999Z`);
+    }
+};
+const taskOrigin = (origin) => {
+    assertTaskClockInstant(origin);
+    return normalizeInstant(origin);
+};
+export const createTaskClock = (origin) => taskClockSchema.parse({
+    version: "spawnfile.task-clock.v1", origin: taskOrigin(origin)
+});
+const clockOrigin = (origin, anchorEpochMs) => {
+    if (!Number.isSafeInteger(anchorEpochMs))
+        throw new Error("Task clock anchorEpochMs must be a safe integer");
+    return taskOrigin(origin);
+};
+/** Top-level Daimon only: its clock stays real and it derives each child's clock environment. */
+export const harnessTaskClockEnvironment = (origin, anchorEpochMs) => ({
+    NOOPOLIS_TASK_CLOCK: JSON.stringify({ version: "noopolis.task-clock.v1", origin: clockOrigin(origin, anchorEpochMs), anchorEpochMs })
+});
+/** Child/tool wall clock. Trial preparation supplies libfaketime LD_PRELOAD and a dot-decimal locale. */
+export const processClockEnvironment = (origin, anchorEpochMs) => {
+    const normalized = clockOrigin(origin, anchorEpochMs);
+    const offsetMs = BigInt(Date.parse(normalized)) - BigInt(anchorEpochMs);
+    const magnitude = offsetMs < 0n ? -offsetMs : offsetMs;
+    const fraction = magnitude % 1000n;
+    return {
+        FAKETIME: `${offsetMs < 0n ? "-" : "+"}${magnitude / 1000n}${fraction ? `.${String(fraction).padStart(3, "0")}` : ""}`,
+        FAKETIME_DONT_FAKE_MONOTONIC: "1"
+    };
+};
+/** Clock-aware child (e.g. Mneme) without libfaketime: apply the offset inside the process exactly once. */
+export const clockAwareEnvironment = (origin, anchorEpochMs) => ({
+    MNEME_CLOCK_ORIGIN: clockOrigin(origin, anchorEpochMs), MNEME_CLOCK_ANCHOR_MS: String(anchorEpochMs)
+});

package/dist/compiler/training/rewind/timestamps.d.ts

@@ -0,0 +1,4 @@
+/** Round down to milliseconds so filesystem precision cannot put a stamp after the instant. */
+export declare const stampTree: (root: string, instant: string, at: string) => Promise<void>;
+/** Disk verification reads may update atime. Restore access time without changing verified mtimes. */
+export declare const restoreAccessTimes: (root: string, at: string) => Promise<void>;

package/dist/compiler/training/rewind/timestamps.js

@@ -0,0 +1,26 @@
+import { lstat, lutimes, readdir, utimes } from "node:fs/promises";
+import path from "node:path";
+import { compareInstants } from "./instant.js";
+/** Round down to milliseconds so filesystem precision cannot put a stamp after the instant. */
+export const stampTree = async (root, instant, at) => {
+    const stamp = new Date(compareInstants(instant, at) > 0 ? at : instant);
+    const visit = async (file) => {
+        const stats = await lstat(file);
+        if (stats.isDirectory())
+            for (const name of await readdir(file))
+                await visit(path.join(file, name));
+        await (stats.isSymbolicLink() ? lutimes : utimes)(file, stamp, stamp);
+    };
+    await visit(root);
+};
+/** Disk verification reads may update atime. Restore access time without changing verified mtimes. */
+export const restoreAccessTimes = async (root, at) => {
+    const visit = async (file) => {
+        const stats = await lstat(file);
+        if (stats.isDirectory())
+            for (const name of await readdir(file))
+                await visit(path.join(file, name));
+        await (stats.isSymbolicLink() ? lutimes : utimes)(file, new Date(Math.min(stats.mtimeMs, Date.parse(at))), new Date(stats.mtimeMs));
+    };
+    await visit(root);
+};

package/dist/compiler/training/rewind/types.d.ts

@@ -0,0 +1,43 @@
+import type { MemoryBank, TeamNetwork, TeamWorkspaceResource } from "../../../manifest/index.js";
+import type { ResolvedMemoryBank } from "../../types.js";
+import type { MaterializedInput } from "./contract.js";
+import type { MomentRecord } from "../../../recording/index.js";
+import type { History } from "./history.js";
+export interface InputIdentity {
+    section: "resources" | "memory" | "networks";
+    id: string;
+    declaredBy: string;
+}
+interface InputBase extends InputIdentity {
+    overridden: boolean;
+    declarationBase: string;
+}
+export type RewindInput = InputBase & ({
+    section: "resources";
+    declaration: TeamWorkspaceResource;
+} | {
+    section: "memory";
+    declaration: MemoryBank | ResolvedMemoryBank;
+} | {
+    section: "networks";
+    declaration: TeamNetwork;
+});
+export interface InputContext {
+    input: RewindInput;
+    at: string;
+    agentSlug?: string;
+    agentId?: string;
+    record: MomentRecord | null;
+    candidateRecords?: readonly MomentRecord[];
+    history: History | undefined;
+    destination: string;
+}
+export interface InputResult {
+    fidelity: "exact" | "approximate" | "overridden";
+    basis: string;
+    source: MaterializedInput["source"];
+    notes: string[];
+    instant: string;
+    build?: "deferred";
+}
+export {};

package/dist/compiler/training/rewind/types.js

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

package/dist/compiler/training/rewind/volumes.d.ts

@@ -0,0 +1,12 @@
+import { type History } from "./history.js";
+import { type SnapshotManifest } from "./snapshotManifest.js";
+import type { InputContext, InputResult } from "./types.js";
+export interface SelectedVolumeSnapshot {
+    snapshot: string;
+    startedAt: string;
+    manifest: SnapshotManifest;
+    relative: string;
+}
+/** A published row plus retained directory and manifest is complete; never infer time from its name. */
+export declare const selectVolumeSnapshot: (history: History, agentSlug: string, agentId: string, id: string, at: string, recordId?: string) => Promise<SelectedVolumeSnapshot>;
+export declare const materializeVolume: (context: InputContext) => Promise<InputResult>;

package/dist/compiler/training/rewind/volumes.js

@@ -0,0 +1,58 @@
+import { lstat, mkdir } from "node:fs/promises";
+import { safeSegment } from "./history.js";
+import { compareInstants } from "./instant.js";
+import { copySnapshotTree, readSnapshotManifest, snapshotHistoryPath } from "./snapshotManifest.js";
+/** A published row plus retained directory and manifest is complete; never infer time from its name. */
+export const selectVolumeSnapshot = async (history, agentSlug, agentId, id, at, recordId) => {
+    const rowsPath = `recording/${safeSegment(agentSlug)}/wake-moments.jsonl`;
+    const rows = await history.wakeMoments(rowsPath);
+    if (!rows)
+        throw new Error(`Missing volume snapshot history ${rowsPath}`);
+    const candidates = rows.flatMap((row, index) => row.agent_id !== agentId ? [] : row.snapshots.filter((entry) => entry.id === id)
+        .map((entry) => ({ row, entry, index })))
+        .filter(({ row, entry }) => recordId === undefined ? compareInstants(row.started_at, at) <= 0 : entry.snapshot === recordId)
+        .sort((a, b) => compareInstants(b.row.started_at, a.row.started_at) || b.index - a.index);
+    for (const { row, entry } of candidates) {
+        if (entry.snapshot.endsWith(".partial")) {
+            if (recordId !== undefined)
+                throw new Error(`Recorded volume snapshot ${recordId} is partial`);
+            continue;
+        }
+        if (compareInstants(row.started_at, at) > 0)
+            throw new Error(`Recorded volume snapshot ${entry.snapshot} is later than the moment`);
+        const relative = snapshotHistoryPath(agentSlug, id, entry.snapshot), tree = await history.path(relative);
+        const manifest = await readSnapshotManifest(history, relative, id, entry.snapshot);
+        if (!tree || !manifest) {
+            if (recordId !== undefined)
+                throw new Error(`Recorded volume snapshot ${recordId} is incomplete`);
+            continue;
+        }
+        if (!(await lstat(tree)).isDirectory())
+            throw new Error(`Snapshot tree must be a real directory: ${relative}`);
+        if (compareInstants(manifest.started_at, row.started_at) !== 0)
+            throw new Error(`Snapshot manifest started_at disagrees with its wake row: ${relative}`);
+        return { snapshot: entry.snapshot, startedAt: row.started_at, manifest, relative };
+    }
+    if (recordId !== undefined)
+        throw new Error(`Recorded volume snapshot ${recordId} is absent from ${rowsPath}`);
+    throw new Error("No complete volume snapshot was taken at or before the moment");
+};
+export const materializeVolume = async (context) => {
+    const { input, at, record, history, destination } = context;
+    if (input.section !== "resources" || input.declaration.kind !== "volume" || input.declaration.feed) {
+        throw new Error("Volume materialization requires an unfed volume input");
+    }
+    if (input.overridden) {
+        await mkdir(destination, { recursive: true });
+        return { fidelity: "overridden", basis: "override", source: {}, notes: [], instant: at };
+    }
+    if (!history)
+        throw new Error(`Volume ${input.id} requires --history or an override`);
+    if (!context.agentSlug || !context.agentId)
+        throw new Error("Volume snapshots require the compiled agent slug and identity");
+    const pin = record?.volumes.find((entry) => entry.id === input.id);
+    const selected = await selectVolumeSnapshot(history, context.agentSlug, context.agentId, input.id, at, pin?.snapshot);
+    await copySnapshotTree(history, selected.relative, destination, selected.manifest);
+    return { fidelity: pin ? "exact" : "approximate", basis: pin ? "record" : "snapshot-at",
+        source: { snapshot: selected.snapshot, agentSlug: context.agentSlug }, notes: [], instant: selected.startedAt };
+};

package/dist/compiler/training/selection.d.ts

@@ -0,0 +1,7 @@
+/** Exact IDs win; a short authored name must identify exactly one graph node. */
+export declare const selectTrainingAgent: <T extends {
+    id: string;
+    value: {
+        name: string;
+    };
+}>(agents: readonly T[], selector: string | undefined) => T;

package/dist/compiler/training/selection.js

@@ -0,0 +1,15 @@
+import { SpawnfileError } from "../../shared/index.js";
+/** Exact IDs win; a short authored name must identify exactly one graph node. */
+export const selectTrainingAgent = (agents, selector) => {
+    const exact = agents.find(agent => agent.id === selector);
+    if (exact)
+        return exact;
+    const matches = selector === undefined ? agents : selector.includes(":") ? []
+        : agents.filter(agent => agent.value.name === selector || agent.id.slice("agent:".length) === selector);
+    if (matches.length === 1)
+        return matches[0];
+    throw new SpawnfileError("validation_error", selector === undefined
+        ? "Training requires --agent when the project does not contain exactly one agent"
+        : matches.length > 1 ? `Ambiguous training agent ${selector}; use an exact node id: ${matches.map(agent => agent.id).sort().join(", ")}`
+            : `No canonical agent matches ${selector}`);
+};

package/dist/compiler/types.d.ts

@@ -1,6 +1,7 @@
-import { AgentSchedule, ExecutionBlock, McpServer, MemoryConsolidation, MemoryRetention, ModelEndpoint, Secret, TeamNetworkServer, type ExternalParticipantService } from "../manifest/index.js";
+import { AgentSchedule, ExecutionBlock, McpServer, SharedMcpServer, MemoryConsolidation, MemoryRetention, ModelEndpoint, ModelTarget, Secret, TeamNetworkServer, type ExternalParticipantService } from "../manifest/index.js";
 import { ModelAuthMethod, StringMap } from "../shared/index.js";
 import type { ResolvedWorkspaceResource } from "./workspaceResources.js";
+import type { ResolvedTraining } from "./training/resolution.js";
 import type { ResolvedExternalParticipant, ResolvedOrganizationIdentity } from "./organizationIdentity.js";
 export interface ResolvedDocument {
     content: string;
@@ -198,7 +199,7 @@ export interface EffectiveModelTarget {
     endpoint?: ModelEndpoint;
     name: string;
     provider: string;
-    reasoningEffort?: "high" | "low" | "medium";
+    reasoningEffort?: ModelTarget["reasoning_effort"];
 }
 export interface ResolvedSubagentRef {
     id: string;
@@ -232,6 +233,7 @@ export interface ResolvedAgentNode {
     subagents: ResolvedSubagentRef[];
     memory?: ResolvedMemoryBank[];
     memoryAccess?: ResolvedMemoryAccess[];
+    training?: ResolvedTraining;
     workspaceResources?: ResolvedWorkspaceResource[];
 }
 export interface ResolvedTeamNode {
@@ -251,12 +253,13 @@ export interface ResolvedTeamNode {
     workspaceResources?: ResolvedWorkspaceResource[];
     shared: {
         env: StringMap;
-        mcpServers: McpServer[];
+        mcpServers: SharedMcpServer[];
         secrets: Secret[];
         skills: ResolvedSkill[];
         packages?: ResolvedPackage[];
     };
     memory?: ResolvedMemoryBank[];
+    training?: ResolvedTraining;
     source: string;
 }
 export interface CompilePlanEdge {

package/dist/compiler/upProject.d.ts

@@ -27,6 +27,7 @@ export interface UpProjectOptions extends CompileProjectOptions {
     imageTag?: string;
     lifecycleRecovery?: UpLifecycleRecovery;
     runRunner?: DockerRunRunner;
+    now?: () => Date;
     onDetachedReservation?: (authority: {
         containerName: string;
         deploymentLabels: Readonly<Record<string, string>>;

package/dist/compiler/upProject.js

@@ -1,6 +1,6 @@
 import path from "node:path";
-import { rm } from "node:fs/promises";
-import { createOrganizationReadinessPending, createDockerDeploymentRecord, probeDockerOrganizationReadiness, readDeploymentRecord, resolveDockerDeploymentTarget, resolveDeploymentRecordPath, writeDeploymentRecord, writeDockerDeploymentRecordForRun, } from "../deployment/index.js";
+import { readFile, rm } from "node:fs/promises";
+import { createOrganizationReadinessPending, createDockerDeploymentRecord, probeDockerOrganizationReadiness, readDeploymentRecord, recordDeploymentRollback, resolveDockerDeploymentTarget, resolveDeploymentRecordPath, writeDeploymentRecord, writeDockerDeploymentRecordForRun, } from "../deployment/index.js";
 import { buildProject } from "./buildProject.js";
 import { createDockerRunInvocation, resolveDetachedDeploymentOptions, runDockerContainer } from "./runProject.js";
 import { executeDockerRunWithSupportCleanup } from "./runProjectLifecycle.js";
@@ -13,7 +13,7 @@ import { resolveHostCliCredential } from "./runProjectAuth.js";
 import { defaultDockerTargetExecFile } from "../target/dockerTargetExecFile.js";
 import { compileOrganizationHandoff, executeOrganizationHandoff, organizationHandoffInputError, resolveRequestedOrganizationHandoff, verifyRequestedOrganizationHandoffTarget, } from "./upProjectHandoff.js";
 const stableRecord = (record) => {
-    const { created_at: _createdAt, export_index: _exportIndex, organization_ready: _organizationReady, ...stable } = record;
+    const { created_at: _createdAt, export_index: _exportIndex, organization_ready: _organizationReady, activated_at: _activatedAt, activation_exact: _activationExact, activation_note: _activationNote, resource_snapshot: _snapshot, recording: _recording, ...stable } = record;
     return stable;
 };
 const canonicalJson = (value) => {
@@ -102,6 +102,15 @@ export const upProject = async (inputPath, options = {}) => {
             await started({ ...result, containerId: result.containerId, containerName: result.containerName, imageId: result.imageId, deploymentLabels: result.deploymentLabels });
         };
     }
+    let activation = {};
+    const recordingRunner = async (runInvocation) => {
+        if (buildResult.report.recording && invocation.detach && invocation.deploymentName) {
+            const hasPredecessor = await fileExists(resolveDeploymentRecordPath(buildResult.outputDirectory, invocation.deploymentName));
+            activation = { activated_at: (options.now ?? (() => new Date()))().toISOString(), activation_exact: !hasPredecessor,
+                ...(hasPredecessor ? { activation_note: "Project up does not stop or drain the previous container; turns may overlap" } : {}) };
+        }
+        return (options.runRunner ?? runDockerContainer)(runInvocation);
+    };
     let deploymentRecordPath;
     if (handoff) {
         const executed = await executeOrganizationHandoff({
@@ -110,7 +119,7 @@ export const upProject = async (inputPath, options = {}) => {
             invocation,
             lifecycleRecovery: options.lifecycleRecovery,
             onDetachedReservation: options.onDetachedReservation,
-            runRunner: options.runRunner ?? runDockerContainer,
+            runRunner: recordingRunner,
             targetExecFile: options.targetExecFile,
         });
         const { organizationHandoffHandle, runMetadata } = executed;
@@ -152,6 +161,8 @@ export const upProject = async (inputPath, options = {}) => {
         else {
             deploymentRecordPath = invocation.detach && invocation.deploymentName
                 ? await writeDockerDeploymentRecordForRun({
+                    previousRecord: resolvedOptions.previousRecord,
+                    ...activation,
                     authProfileName: authProfile?.name ?? null,
                     envFilePath: resolvedOptions.envFilePath,
                     imageTag,
@@ -181,9 +192,11 @@ export const upProject = async (inputPath, options = {}) => {
                 });
             }
             dockerLifecycleInvoked = true;
-            const runMetadata = await executeDockerRunWithSupportCleanup(invocation, options.runRunner ?? runDockerContainer);
+            const runMetadata = await executeDockerRunWithSupportCleanup(invocation, recordingRunner);
             deploymentRecordPath = invocation.detach && invocation.deploymentName
                 ? await writeDockerDeploymentRecordForRun({
+                    previousRecord: resolvedOptions.previousRecord,
+                    ...activation,
                     authProfileName: authProfile?.name ?? null,
                     envFilePath: resolvedOptions.envFilePath,
                     imageTag,
@@ -227,6 +240,9 @@ export const upProject = async (inputPath, options = {}) => {
                     : invocation.dockerHost ? ["--host", invocation.dockerHost] : [];
                 await (options.targetExecFile ?? defaultDockerTargetExecFile)(invocation.command, [...prefix, "container", "rm", "--force", reference], { timeout: 30_000 });
             }
+            if (buildResult.report.recording) {
+                await recordDeploymentRollback(deploymentRecordPath, record, buildResult.report, record.resource_snapshot ? "" : await readFile(buildResult.reportPath, "utf8"), (options.now ?? (() => new Date()))().toISOString());
+            }
             await rm(invocation.supportDirectory, { recursive: true, force: true });
             await rm(deploymentRecordPath, { force: true });
             throw new SpawnfileError("runtime_error", "Detached deployment failed organization readiness and was rolled back");

package/dist/compiler/workspaceBundleArtifacts.d.ts

@@ -1,3 +1,18 @@
 import type { CompilePlan } from "./types.js";
 export declare const validateWorkspaceBundleTar: (bytes: Buffer) => void;
-export declare const stageWorkspaceBundles: (outputDirectory: string, plan: CompilePlan) => Promise<boolean>;
+export declare const workspaceBundleContextPath: (outputDirectory: string, identity: string) => string;
+/**
+ * Hard-links a read-only cached archive into the Docker context (cloning or
+ * copying across filesystems). Never writes through an existing name: with
+ * `clean: false` it may already be a link into the cache. Returns the staged
+ * path, or undefined when the cached archive no longer exists.
+ */
+export declare const linkBuiltBundle: (archive: string, outputDirectory: string, identity: string) => Promise<string | undefined>;
+/**
+ * Completes the bundle archives in the Docker context. Built bundles were
+ * already linked by `resolveWorkspaceBundles` (`built` maps their digests to
+ * the staged path). Every `source` tar is hashed, validated and staged from
+ * the exact bytes that were verified, even when a built bundle shares its
+ * digest; distinct source paths with identical bytes stage once.
+ */
+export declare const stageWorkspaceBundles: (outputDirectory: string, plan: CompilePlan, built?: ReadonlyMap<string, string>) => Promise<boolean>;