spawnfile 0.1.14 → 0.1.18

package/dist/release/runRelease.js

@@ -0,0 +1,218 @@
+import { rm } from "node:fs/promises";
+import { normalizeDeploymentName } from "../deployment/index.js";
+import { controlTargetFor, recoverInterruptedDrain, requestForTarget, resolveControlToken } from "./drainPhase.js";
+import { acquireReleaseLock, appendReleaseLog, postDeployPending, ensureReleaseDirectory, readReleaseLedger, resolveReleasePaths, writeJsonAtomic, writeReleaseLedger } from "./ledger.js";
+import { createNotification } from "./notify.js";
+import { clearDeferral, markDeferralNotified, recordDeferral } from "./pending.js";
+import { releaseImageTag } from "./releaseDocker.js";
+import { DAIMON_CONTROL_TOKEN_ENV } from "./releaseTypes.js";
+import { drainAndSwap, releaseContainerName } from "./swap.js";
+import { ReleaseError, isReleaseError } from "./types.js";
+/**
+ * compile → identity → (unchanged? stop) → build → drain → deploy → settle →
+ * resume → post-deploy → record → prune. The ledger is written last because it claims
+ * "this identity is RUNNING"; written earlier it would claim a container that
+ * never came up, and the next run would see nothing to do.
+ */
+export const runRelease = async (request, deps) => {
+    // One spelling everywhere: storage, the container name, the lock and `up` all normalize it.
+    request.deployment = normalizeDeploymentName(request.deployment);
+    const paths = resolveReleasePaths(request.deployment, request.releaseRoot);
+    const progress = { identity: null, stage: "lock" };
+    let unlock = null;
+    try {
+        await ensureReleaseDirectory(paths);
+        unlock = await acquireReleaseLock(paths);
+        progress.stage = "prepare";
+        Object.assign(request, await deps.prepare(request));
+        progress.stage = "recover";
+        await recoverInterruptedDrain(request, deps, paths);
+        progress.stage = "target";
+        const pinned = requestForTarget(request, await deps.pinTarget(request));
+        return await releaseLocked(pinned, deps, paths, progress);
+    }
+    catch (error) {
+        return fail(request, deps, paths, progress, error);
+    }
+    finally {
+        await unlock?.().catch(() => undefined);
+    }
+};
+const releaseLocked = async (request, deps, paths, progress) => {
+    const started = Date.now();
+    progress.stage = "compile";
+    const compiled = await deps.compile(request).catch((error) => {
+        throw new ReleaseError("build-failed", `compile failed: ${error.message}`, { cause: error });
+    });
+    progress.identity = compiled.identity;
+    const imageTag = releaseImageTag(compiled.repository, compiled.identity);
+    progress.stage = "inspect";
+    const ledger = await readReleaseLedger(paths.ledger);
+    const running = await deps.inspectUnit(request, releaseContainerName(request.deployment));
+    // A post-deploy command that failed (or never finished) leaves its marker: the
+    // running container may be the recorded image, but the release is not done.
+    const hookPending = await postDeployPending(paths.postDeploy);
+    if (!hookPending && isUnchanged(request, ledger, compiled.identity, running)) {
+        await clearDeferral(paths.pending);
+        request.log(`release: ${compiled.identity.slice(0, 19)} is already running as ${ledger.image_tag}; nothing to do`);
+        return { identity: compiled.identity, imageTag: ledger.image_tag, kind: "unchanged" };
+    }
+    if (request.drain && running?.running && resolveControlToken(request) === null) {
+        throw new ReleaseError("blocked", `${DAIMON_CONTROL_TOKEN_ENV} is not set in the env file or environment; a drained release needs the running deployment's control token`);
+    }
+    request.log(ledger
+        ? `release: ${compiled.identity.slice(0, 19)} differs from the released ${ledger.identity.slice(0, 19)} (${ledger.image_tag}); releasing`
+        : `release: nothing recorded as released for ${request.deployment}; releasing ${compiled.identity.slice(0, 19)}`);
+    // The tag about to be built is kept too: a retry after a failed deploy reuses it instead of rebuilding.
+    await pruneQuietly(request, deps, compiled.repository, [imageTag, ledger?.image_tag ?? null, ledger?.previous_image_tag ?? null]);
+    progress.stage = "build";
+    const built = await deps.build(request, compiled, imageTag).catch((error) => {
+        throw new ReleaseError("build-failed", `image build failed: ${error.message}`, { cause: error });
+    });
+    request.log(built.skipped ? `release: ${imageTag} already built; build skipped` : `release: built ${imageTag} in ${Math.round((built.buildMs ?? 0) / 1000)}s`);
+    progress.stage = "deploy";
+    if (request.signal?.aborted)
+        throw new ReleaseError("interrupted", "the release was interrupted before draining; nothing was paused or deployed");
+    // The same home lock `up` takes, held from before the drain until the ledger
+    // names what is running: no concurrent `up` can replace the drained
+    // container, or the candidate before it is recorded.
+    const unlockDeployment = await deps.lockDeployment(request.deployment).catch((error) => {
+        throw new ReleaseError("blocked", `cannot lock the deployment: ${error.message}`);
+    });
+    try {
+        return await swapAndRecord(request, deps, paths, progress, { built, compiled, imageTag, ledger, started });
+    }
+    finally {
+        await unlockDeployment().catch(() => undefined);
+    }
+};
+const swapAndRecord = async (request, deps, paths, progress, { built, compiled, imageTag, ledger, started }) => {
+    const swap = await drainAndSwap(request, deps, paths, imageTag);
+    if (swap.kind === "deferred")
+        return defer(request, deps, paths, compiled.identity);
+    const { deployed, drained } = swap;
+    progress.stage = "settle";
+    const settled = await deps.settle(request, deployed.containerName);
+    if (settled.imageId !== built.imageId) {
+        throw new ReleaseError("deploy-failed", `the settled container runs ${settled.imageId}, not the built ${built.imageId}`);
+    }
+    if (request.drain) {
+        progress.stage = "resume";
+        try {
+            await deps.requestResume(controlTargetFor(request, settled.id, settled.imageId));
+        }
+        catch (error) {
+            throw new ReleaseError("resume-failed", `the new container did not confirm admission: ${error.message}`);
+        }
+    }
+    if (request.postDeploy) {
+        progress.stage = "post-deploy";
+        await writeJsonAtomic(paths.postDeploy, { at: (request.now?.() ?? new Date()).toISOString(), identity: compiled.identity }).catch((error) => {
+            throw new ReleaseError("post-deploy-failed", `cannot record that a post-deploy command is pending, so it was not run: ${error.message}`);
+        });
+        await runPostDeployStep(request, deps, request.postDeploy, {
+            containerName: deployed.containerName, deployment: request.deployment, identity: compiled.identity, imageId: settled.imageId, imageTag
+        });
+    }
+    progress.stage = "record";
+    const timings = {
+        build_ms: built.buildMs,
+        compile_ms: compiled.compileMs,
+        deploy_ms: deployed.deployMs,
+        drain_ms: drained.drainMs,
+        total_ms: Date.now() - started
+    };
+    const next = {
+        compile_fingerprint: compiled.compileResult.report.compile_fingerprint ?? "unknown",
+        deployment: request.deployment,
+        identity: compiled.identity,
+        image_id: settled.imageId,
+        image_tag: imageTag,
+        previous_image_tag: ledger && ledger.image_tag !== imageTag ? ledger.image_tag : ledger?.previous_image_tag ?? null,
+        released_at: (request.now?.() ?? new Date()).toISOString(),
+        timings,
+        version: "spawnfile.release-ledger.v1"
+    };
+    await writeReleaseLedger(paths.ledger, next).catch((error) => {
+        throw new ReleaseError("ledger-failed", `the deployment is running but the release ledger could not be written (every later run will redeploy until it can): ${error.message}`);
+    });
+    await rm(paths.postDeploy, { force: true }).catch((error) => {
+        request.log(`release: cannot clear the post-deploy marker, so the next run releases again: ${error.message}`);
+    });
+    await appendReleaseLog(paths.log, { at: next.released_at, deployment: request.deployment, identity: compiled.identity, image_tag: imageTag, outcome: "released", timings }).catch(() => undefined);
+    await clearDeferral(paths.pending).catch(() => undefined);
+    await pruneQuietly(request, deps, compiled.repository, [imageTag, next.previous_image_tag]);
+    request.log(`release: ${imageTag} deployed, settled and recorded (build ${timings.build_ms === null ? "skipped" : `${Math.round(timings.build_ms / 1000)}s`}, drain ${Math.round((timings.drain_ms ?? 0) / 1000)}s, total ${Math.round(timings.total_ms / 1000)}s)`);
+    return { identity: compiled.identity, imageId: settled.imageId, imageTag, kind: "released", timings };
+};
+/** A failed hook leaves the release unrecorded: the next run deploys again and reruns it. */
+const runPostDeployStep = async (request, deps, hook, context) => {
+    if (request.signal?.aborted)
+        throw new ReleaseError("interrupted", "the release was interrupted after deploying; the post-deploy command did not run and nothing was recorded");
+    let result;
+    try {
+        result = await deps.runPostDeploy(request, hook, context);
+    }
+    catch (error) {
+        throw new ReleaseError("post-deploy-failed", `the post-deploy command could not run: ${error.message}`);
+    }
+    const output = result.output.trim();
+    if (output)
+        request.log(`release: post-deploy output:\n${output}`);
+    if (request.signal?.aborted)
+        throw new ReleaseError("interrupted", "the release was interrupted while the post-deploy command ran; nothing was recorded");
+    if (result.timedOut)
+        throw new ReleaseError("post-deploy-failed", `the post-deploy command did not finish within ${Math.round(hook.timeoutMs / 1000)}s`);
+    if (result.exitCode !== 0)
+        throw new ReleaseError("post-deploy-failed", `the post-deploy command exited ${result.exitCode ?? "by signal"}${output ? `: ${output.slice(-300)}` : ""}`);
+    request.log("release: post-deploy command succeeded");
+};
+/** Unchanged means the recorded identity is the one the container is actually running, not merely the one last built. */
+const isUnchanged = (request, ledger, identity, running) => !request.force && ledger !== null && ledger.identity === identity && running !== null && running.running && running.imageId === ledger.image_id;
+const pruneQuietly = async (request, deps, repository, keep) => {
+    try {
+        const pruned = await deps.prune(request, repository, keep);
+        for (const tag of pruned.removed)
+            request.log(`release: removed old image ${tag}`);
+    }
+    catch (error) {
+        request.log(`release: image prune skipped (${error.message.slice(0, 160)})`);
+    }
+};
+const defer = async (request, deps, paths, identity) => {
+    const decision = await recordDeferral(paths.pending, identity, { notifyAfterMs: request.notifyDeferredAfterMs, ...(request.now ? { now: request.now() } : {}) });
+    const hours = Math.floor(decision.ageMs / 3_600_000);
+    const message = decision.trackingBroken
+        ? `release deferred (running turns did not finish within the drain bound) and ${decision.trackingBroken}`
+        : `release deferred: running turns did not finish within the drain bound; pending ${hours}h`;
+    request.log(`release: ${message}; admission resumed, nothing deployed, retry on the next run`);
+    const at = (request.now?.() ?? new Date()).toISOString();
+    await appendReleaseLog(paths.log, { at, deployment: request.deployment, identity, message, outcome: "deferred", reason: "release-deferred" }).catch(() => undefined);
+    const notified = decision.notify ? await notifyAndLog(request, deps, paths, "release-deferred", message, identity) : false;
+    if (notified && !decision.trackingBroken)
+        await markDeferralNotified(paths.pending, decision.pending).catch(() => undefined);
+    return { identity, kind: "deferred", message, notified };
+};
+const fail = async (request, deps, paths, progress, error) => {
+    const reason = isReleaseError(error) ? error.reason : "blocked";
+    const message = `${reason} at ${progress.stage}: ${error instanceof Error ? error.message : String(error)}`;
+    request.log(`release FAILED: ${message}`);
+    const at = (request.now?.() ?? new Date()).toISOString();
+    await appendReleaseLog(paths.log, { at, deployment: request.deployment, identity: progress.identity, message, outcome: "failed", reason }).catch(() => undefined);
+    const notified = await notifyAndLog(request, deps, paths, reason, message, progress.identity);
+    return { identity: progress.identity, kind: "failed", message, notified, reason };
+};
+const notifyAndLog = async (request, deps, paths, reason, message, identity) => {
+    if (request.notifier.kind === "none")
+        return false;
+    const notification = createNotification({ deployment: request.deployment, identity, message, reason, ...(request.now ? { now: request.now() } : {}) });
+    const result = await deps.notify(request.notifier, notification).catch((error) => ({ channel: request.notifier.kind, delivered: false, error: error.message }));
+    if (!result.delivered)
+        request.log(`release: notifier did not deliver (${result.error ?? "unknown"}); the message is in ${paths.log}`);
+    await appendReleaseLog(paths.log, {
+        at: notification.at, deployment: request.deployment, identity, message: notification.message,
+        notified: { channel: result.channel, delivered: result.delivered, ...(result.error ? { error: result.error } : {}) },
+        outcome: "notified", reason
+    }).catch(() => undefined);
+    return result.delivered;
+};

package/dist/release/swap.d.ts

@@ -0,0 +1,23 @@
+import { type DrainOutcome } from "./drainPhase.js";
+import type { ReleasePaths } from "./ledger.js";
+import type { DeployedRelease, ReleaseDependencies, ReleaseRequest } from "./releaseTypes.js";
+/** Runtimes whose admission a release can pause through a published control contract. */
+export declare const DRAINABLE_RUNTIMES: ReadonlySet<string>;
+/** `up --image` names the deployment's container this way; a release replaces exactly that container. */
+export declare const releaseContainerName: (deployment: string) => string;
+export type SwapOutcome = {
+    deployed: DeployedRelease;
+    drained: DrainOutcome;
+    kind: "deployed";
+} | {
+    drained: DrainOutcome;
+    kind: "deferred";
+};
+/**
+ * Drain and swap. The caller holds the deployment's home lock, so no
+ * concurrent `up` can replace the drained container between the drain and
+ * the deploy. The container is inspected again under the lock (a long build may have outlived
+ * the first inspection) and once more after the drain: a different container,
+ * or one that restarted and therefore admits again, aborts the release.
+ */
+export declare const drainAndSwap: (request: ReleaseRequest, deps: ReleaseDependencies, paths: ReleasePaths, imageTag: string) => Promise<SwapOutcome>;

package/dist/release/swap.js

@@ -0,0 +1,55 @@
+import { clearDrainMarker, drainForRelease, resumeAfterFailedDeploy, resumeDrained } from "./drainPhase.js";
+import { ReleaseError } from "./types.js";
+/** Runtimes whose admission a release can pause through a published control contract. */
+export const DRAINABLE_RUNTIMES = new Set(["daimon"]);
+/** `up --image` names the deployment's container this way; a release replaces exactly that container. */
+export const releaseContainerName = (deployment) => `spawnfile-${deployment}`;
+/**
+ * Drain and swap. The caller holds the deployment's home lock, so no
+ * concurrent `up` can replace the drained container between the drain and
+ * the deploy. The container is inspected again under the lock (a long build may have outlived
+ * the first inspection) and once more after the drain: a different container,
+ * or one that restarted and therefore admits again, aborts the release.
+ */
+export const drainAndSwap = async (request, deps, paths, imageTag) => {
+    const containerName = releaseContainerName(request.deployment);
+    const target = await deps.inspectUnit(request, containerName);
+    if (request.drain && target?.running) {
+        const runtimes = await deps.runtimesOf(request, target.imageId).catch((error) => {
+            throw new ReleaseError("blocked", `cannot read which runtimes the running image holds, so it cannot be shown drainable: ${error.message}`);
+        });
+        const undrainable = [...new Set(runtimes)].filter((runtime) => !DRAINABLE_RUNTIMES.has(runtime));
+        if (runtimes.length === 0 || undrainable.length > 0) {
+            throw new ReleaseError("blocked", `the running container holds runtimes without a drain contract (${undrainable.join(", ") || "none listed"}); draining it could not stop their turns. Use --no-drain to deploy over them deliberately`);
+        }
+    }
+    const drained = await drainForRelease(request, deps, paths, target);
+    if (drained.kind === "timeout")
+        return { drained, kind: "deferred" };
+    if (drained.kind === "drained" && target) {
+        // Anything that stops the release between the drain and the deploy resumes the drained container.
+        try {
+            const now = await deps.inspectUnit(request, containerName);
+            if (now === null || now.id !== target.id || now.restartCount !== target.restartCount || !now.running) {
+                throw new ReleaseError("drain-failed", "the drained container was replaced or restarted before the deploy; a restarted runtime admits again, so nothing was deployed");
+            }
+            if (request.signal?.aborted)
+                throw new ReleaseError("interrupted", "the release was interrupted after draining; admission resumed, nothing deployed");
+        }
+        catch (error) {
+            await resumeDrained(request, deps, paths, target);
+            throw error instanceof ReleaseError ? error : new ReleaseError("drain-failed", `cannot confirm the drained container before deploying: ${error.message}`);
+        }
+    }
+    let deployed;
+    try {
+        deployed = await deps.deploy(request, imageTag);
+    }
+    catch (error) {
+        await resumeAfterFailedDeploy(request, deps, paths, containerName);
+        throw new ReleaseError("deploy-failed", `deploy failed: ${error.message}`, { cause: error });
+    }
+    // The drained container was replaced; its drain ended with its process.
+    await clearDrainMarker(paths);
+    return { deployed, drained, kind: "deployed" };
+};

package/dist/release/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The fixed vocabulary a release failure is reported in. A notifier receives
+ * exactly one of these words, so whoever reads the notification learns a small
+ * closed set rather than free text; the detail travels separately.
+ */
+export declare const RELEASE_FAILURE_REASONS: readonly ["blocked", "build-failed", "drain-failed", "deploy-failed", "health-failed", "resume-failed", "post-deploy-failed", "ledger-failed", "interrupted", "release-deferred"];
+export type ReleaseFailureReason = (typeof RELEASE_FAILURE_REASONS)[number];
+/** Carries the reason word with the error so the orchestrator never guesses it. */
+export declare class ReleaseError extends Error {
+    readonly reason: ReleaseFailureReason;
+    constructor(reason: ReleaseFailureReason, message: string, options?: ErrorOptions);
+}
+export declare const isReleaseError: (value: unknown) => value is ReleaseError;
+export interface ReleaseTimings {
+    build_ms: number | null;
+    compile_ms: number;
+    deploy_ms: number | null;
+    drain_ms: number | null;
+    total_ms: number;
+}
+/**
+ * `released`: a new image is running and recorded. `unchanged`: the recorded
+ * identity is the one running, nothing was built or touched. `deferred`: the
+ * running organization did not drain within the bound, the release was
+ * abandoned before deploying and admission resumed. `failed`: see `reason`.
+ */
+export type ReleaseOutcome = {
+    identity: string;
+    imageTag: string;
+    kind: "unchanged";
+} | {
+    identity: string;
+    imageId: string;
+    imageTag: string;
+    kind: "released";
+    timings: ReleaseTimings;
+} | {
+    identity: string;
+    kind: "deferred";
+    message: string;
+    notified: boolean;
+} | {
+    identity: string | null;
+    kind: "failed";
+    message: string;
+    notified: boolean;
+    reason: ReleaseFailureReason;
+};
+/** Exit codes: 0 released/unchanged, 75 (EX_TEMPFAIL) deferred, 1 failed. */
+export declare const releaseExitCode: (outcome: ReleaseOutcome) => number;

package/dist/release/types.js

@@ -0,0 +1,29 @@
+/**
+ * The fixed vocabulary a release failure is reported in. A notifier receives
+ * exactly one of these words, so whoever reads the notification learns a small
+ * closed set rather than free text; the detail travels separately.
+ */
+export const RELEASE_FAILURE_REASONS = Object.freeze([
+    "blocked",
+    "build-failed",
+    "drain-failed",
+    "deploy-failed",
+    "health-failed",
+    "resume-failed",
+    "post-deploy-failed",
+    "ledger-failed",
+    "interrupted",
+    "release-deferred"
+]);
+/** Carries the reason word with the error so the orchestrator never guesses it. */
+export class ReleaseError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.reason = reason;
+        this.name = "ReleaseError";
+    }
+}
+export const isReleaseError = (value) => value instanceof ReleaseError;
+/** Exit codes: 0 released/unchanged, 75 (EX_TEMPFAIL) deferred, 1 failed. */
+export const releaseExitCode = (outcome) => outcome.kind === "failed" ? 1 : outcome.kind === "deferred" ? 75 : 0;

package/dist/report/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./createDiagnostic.js";
 export * from "./createReport.js";
 export * from "./types.js";
+export * from "./recording.js";
 export * from "./writeReport.js";

package/dist/report/index.js

@@ -1,4 +1,5 @@
 export * from "./createDiagnostic.js";
 export * from "./createReport.js";
 export * from "./types.js";
+export * from "./recording.js";
 export * from "./writeReport.js";

package/dist/report/recording.d.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+/** Portable compiled facts, persisted with the deployment so sync never recompiles. */
+export declare const recordingAgentSchema: z.ZodObject<{
+    node_id: z.ZodString;
+    slug: z.ZodString;
+    directory: z.ZodString;
+    keep_ms: z.ZodNumber;
+    networks: z.ZodArray<z.ZodString>;
+    memory: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        declared_by: z.ZodString;
+        ledger_path: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    feeds: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        volume_name: z.ZodString;
+    }, z.core.$strict>>;
+    resources: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            git: "git";
+            bundle: "bundle";
+        }>;
+    }, z.core.$strict>>;
+    snapshots: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type RecordingAgentReport = z.infer<typeof recordingAgentSchema>;
+/** Optional members preserve S1 records; sync requires the compiled agents member. */
+export declare const recordingReportSchema: z.ZodObject<{
+    keep_ms: z.ZodNumber;
+    memory_mount_ids: z.ZodArray<z.ZodString>;
+    recording_mount_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    agents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        node_id: z.ZodString;
+        slug: z.ZodString;
+        directory: z.ZodString;
+        keep_ms: z.ZodNumber;
+        networks: z.ZodArray<z.ZodString>;
+        memory: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            declared_by: z.ZodString;
+            ledger_path: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>>;
+        feeds: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            volume_name: z.ZodString;
+        }, z.core.$strict>>;
+        resources: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<{
+                git: "git";
+                bundle: "bundle";
+            }>;
+        }, z.core.$strict>>;
+        snapshots: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;

package/dist/report/recording.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+const text = z.string().min(1);
+const mountId = text.regex(/^[A-Za-z0-9][A-Za-z0-9_.-]*$/u).refine((value) => !value.includes(".."));
+const containerPath = text.startsWith("/").refine((value) => !value.includes("\0"));
+const keepMs = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+/** Portable compiled facts, persisted with the deployment so sync never recompiles. */
+export const recordingAgentSchema = z.object({
+    node_id: text,
+    slug: text.regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u),
+    directory: containerPath,
+    keep_ms: keepMs,
+    networks: z.array(text),
+    memory: z.array(z.object({ id: text, declared_by: text, ledger_path: containerPath.nullable() }).strict()),
+    feeds: z.array(z.object({ id: text, volume_name: text }).strict()),
+    resources: z.array(z.object({ id: text, kind: z.enum(["git", "bundle"]) }).strict()),
+    snapshots: z.array(text)
+}).strict().refine((value) => value.directory === `/var/lib/spawnfile/recording/${value.slug}`, {
+    message: "Recording directory must match the compiled agent slug"
+});
+/** Optional members preserve S1 records; sync requires the compiled agents member. */
+export const recordingReportSchema = z.object({
+    keep_ms: keepMs,
+    memory_mount_ids: z.array(mountId),
+    recording_mount_ids: z.array(mountId).optional(),
+    agents: z.array(recordingAgentSchema).optional()
+}).strict();

package/dist/report/types.d.ts

@@ -1,5 +1,6 @@
 import type { RuntimeLifecycleStatus } from "../shared/index.js";
 import type { ModelAuthMethod } from "../shared/index.js";
+import type { RecordingAgentReport } from "./recording.js";
 export type CapabilityOutcome = "degraded" | "supported" | "unsupported";
 export interface CapabilityReport {
     key: string;
@@ -11,6 +12,12 @@ export interface DiagnosticReport {
     message: string;
 }
 export interface ContainerRuntimeInstanceReport {
+    /** Per-agent paths for shared runtime instances; all paths are container absolute. */
+    agent_paths?: Record<string, {
+        workspace_path: string;
+        home_path: string | null;
+        skill_roots: string[];
+    }>;
     config_path: string;
     /** Per pi/daimon agent (keyed by node id, e.g. "agent:eleanor"): the resolved pi
      * engine kind (see `PI_ENGINE_KINDS` in `src/runtime/pi/appTemplate.ts`, e.g.
@@ -35,14 +42,32 @@ export interface ContainerRuntimeInstanceReport {
 export interface ContainerWorkspaceResourceReport {
     backing_path: string;
     id: string;
-    kind: "git" | "volume";
+    kind: "bundle" | "git" | "volume";
     link_path: string;
     mode: "mutable" | "readonly";
     mount: string;
+    mount_path: string;
+    replacement_sentinel?: {
+        path: string;
+        result: "verified_on_startup";
+    };
+    resolved_identity: string;
     sharing: "per_agent" | "team";
+    volume_name: string | null;
 }
 export interface ContainerPersistentMountReport {
+    /**
+     * The author's own volume name, when one was declared (a workspace resource
+     * `name`, a `store.persistence.name`, a memory bank's `persistence.name`).
+     * Present only when declared; `volume_name` equals it in that case. It is
+     * carried separately because it is the one part of the resolved name that is
+     * portable: it belongs to the declaration, not to the creator's plan root or
+     * deployment lineage, so a published image can honour it verbatim while a
+     * derived name must be re-derived per deployment.
+     */
+    declared_volume_name?: string;
     id: string;
+    lifecycle?: "exclusive-reattach";
     mount_path: string;
     reason: string;
     volume_name: string;
@@ -155,6 +180,7 @@ export interface ContainerPortMappingReport {
     published_port: number;
 }
 export interface ContainerMoltnetNodePlanSummary {
+    node_id?: string;
     config_path: string;
     credential_agent_id?: string;
     credential_id?: string;
@@ -200,9 +226,16 @@ export interface ContainerMoltnetPlanSummary {
         architecture: "amd64" | "arm64";
         asset: string;
         asset_sha256: `sha256:${string}`;
-        capabilities: readonly ["pi-bridge"];
-        release_version: string;
-        source_revision: string;
+        capabilities: readonly ["pi-bridge"] | readonly ["daimon-bridge", "pi-bridge"];
+        development?: {
+            mode: "local-development";
+            non_production: true;
+            unsigned: true;
+            unpublished: true;
+        };
+        release_version?: string;
+        source_revision?: string;
+        source_sha256?: `sha256:${string}`;
         version: "spawnfile.moltnet-release-identity.v1";
     };
     server_plans: ContainerMoltnetServerPlanSummary[];
@@ -224,6 +257,11 @@ export interface ContainerReport {
     entrypoint: string;
     env_example: string;
     internal_ports?: number[];
+    local_daimon_runtime?: {
+        capability_receipt_sha256: string;
+        image_reference: string;
+        registry_authority: string;
+    };
     model_secrets_required: string[];
     moltnet?: ContainerMoltnetPlanSummary;
     memory?: ContainerMemoryReport[];
@@ -238,6 +276,53 @@ export interface ContainerReport {
     persistent_mounts?: ContainerPersistentMountReport[];
     workspace_resources?: ContainerWorkspaceResourceReport[];
 }
+/** Association captured while walking the resolved compile graph. */
+export interface WorkspaceResourceOwnership {
+    agent_node_ids: string[];
+    declared_by?: string;
+}
+/** One workspace bundle archive the compile staged, with the digest Spawnfile built or verified. */
+export interface CompileReportWorkspaceBundle extends Partial<WorkspaceResourceOwnership> {
+    cache_key?: string;
+    content_bytes?: number;
+    file_count?: number;
+    id: string;
+    identity?: "dev" | "release";
+    /** Input kind of a built bundle. */
+    input?: "dependencies" | "files" | "generated";
+    origin: "built" | "prebuilt";
+    platform?: string;
+    sha256: string;
+}
+/** A `fetch: build` git resource: the commit its selector resolved to and the archive cut from that commit. */
+export interface CompileReportWorkspaceGitResource extends Partial<WorkspaceResourceOwnership> {
+    auth: "none" | "ssh_key" | "ssh_key_env";
+    cache_key: string;
+    commit: string;
+    content_bytes: number;
+    file_count: number;
+    id: string;
+    identity: "dev" | "release";
+    platform: string;
+    selector: {
+        kind: "branch" | "ref" | "tag";
+        value: string;
+    } | {
+        kind: "default_branch";
+    };
+    sha256: string;
+    url: string;
+}
+/** Present only when at least one effective compiled agent enables recording. */
+export interface RecordingReport {
+    agents?: RecordingAgentReport[];
+    /** Maximum recording window across agents, including the 30-day default. */
+    keep_ms: number;
+    /** Durable memory mounts accessible to any recording agent, including team banks. */
+    memory_mount_ids: string[];
+    /** Per-agent recording stores protected by the same destructive-volume guard. */
+    recording_mount_ids?: string[];
+}
 export interface CompileReport {
     compile_fingerprint?: string;
     container?: ContainerReport;
@@ -246,7 +331,10 @@ export interface CompileReport {
     nodes: NodeReport[];
     output_directory?: string;
     project_name?: string;
+    recording?: RecordingReport;
     root: string;
     spawnfile_version: "0.1";
+    workspace_bundles?: CompileReportWorkspaceBundle[];
+    workspace_git_resources?: CompileReportWorkspaceGitResource[];
 }
 export {};