spawnfile 0.1.14 → 0.1.18

package/dist/compiler/containerWorkspaceResourceRender.js

@@ -1,11 +1,17 @@
+import { VOLUME_BOOTSTRAP_MARKER, VOLUME_BOOTSTRAP_MARKER_CONTENT } from "./containerVolumeBootstrap.js";
 const shellQuote = (value) => `'${value.replace(/'/g, `'\"'\"'`)}'`;
 export const createWorkspaceResourceCommands = (plan) => (plan.resources ?? []).flatMap((resource) => {
     const readonlyFlag = resource.mode === "readonly" ? "readonly" : "mutable";
     if (resource.kind === "volume") {
+        const resolved = resource;
         return [
-            `prepare_volume_resource ${shellQuote(resource.id)} ${shellQuote(resource.linkPath)} ${shellQuote(resource.backingPath)} ${shellQuote(readonlyFlag)}`
+            `prepare_volume_resource ${shellQuote(resource.id)} ${shellQuote(resource.linkPath)} ${shellQuote(resource.backingPath)} ${shellQuote(readonlyFlag)} ${shellQuote(resolved.resolvedIdentity ?? "")}`
         ];
     }
+    if (resource.kind === "bundle")
+        return [
+            `prepare_bundle_resource ${shellQuote(resource.id)} ${shellQuote(resource.linkPath)} ${shellQuote(resource.backingPath)} ${shellQuote(resource.archivePath ?? "")} ${shellQuote(resource.sha256 ?? "")}`
+        ];
     const selectorKind = resource.branch
         ? "branch"
         : resource.tag
@@ -58,15 +64,60 @@ export const createWorkspaceResourceShellFunctions = () => [
     '  local link_path="$2"',
     '  local backing_path="$3"',
     '  local mode="$4"',
+    '  local identity="$5"',
     '  mkdir -p "$backing_path"',
     '  if [ ! -d "$backing_path" ]; then',
     '    echo "Workspace volume resource $id backing path is not a directory: $backing_path" >&2',
     "    exit 1",
     "  fi",
+    '  local sentinel="$backing_path/.spawnfile-resource-identity"',
+    '  if [ -f "$sentinel" ]; then',
+    '    if [ "$(cat "$sentinel")" != "$identity" ]; then',
+    '      echo "Workspace volume resource $id replacement sentinel mismatch" >&2',
+    "      exit 1",
+    "    fi",
+    "  else",
+    `    local bootstrap="$backing_path/${VOLUME_BOOTSTRAP_MARKER}"`,
+    `    local bootstrap_claim="$backing_path/${VOLUME_BOOTSTRAP_MARKER}.claim"`,
+    '    local first_entry',
+    '    first_entry="$(find "$backing_path" -mindepth 1 -maxdepth 1 -print -quit)"',
+    '    if [ -n "$first_entry" ]; then',
+    '      if [ "$first_entry" = "$bootstrap" ]; then',
+    '        mv -T --no-clobber -- "$bootstrap" "$bootstrap_claim"',
+    '      elif [ "$first_entry" != "$bootstrap_claim" ]; then',
+    '      echo "Workspace volume resource $id is nonempty without an authenticated replacement sentinel" >&2',
+    "      exit 1",
+    "      fi",
+    '      if [ "$(find "$backing_path" -mindepth 1 -maxdepth 1 ! -name ' + `'${VOLUME_BOOTSTRAP_MARKER}.claim'` + ' -print -quit)" != "" ] || [ -L "$bootstrap_claim" ] || [ ! -f "$bootstrap_claim" ] || [ "$(stat -c "%u:%g:%a:%h" "$bootstrap_claim")" != "${volume_bootstrap_uid}:${volume_bootstrap_gid}:600:1" ] || [ "$(cat "$bootstrap_claim")" != "' + VOLUME_BOOTSTRAP_MARKER_CONTENT + '" ]; then',
+    '        echo "Workspace volume resource $id bootstrap marker mismatch" >&2',
+    "        exit 1",
+    "      fi",
+    '      rm -- "$bootstrap_claim"',
+    "    fi",
+    '    printf "%s\\n" "$identity" > "$sentinel"',
+    "  fi",
     '  mark_readonly_resource "$backing_path" "$mode"',
     '  prepare_resource_link "$id" "$link_path" "$backing_path"',
     "}",
     "",
+    "prepare_bundle_resource() {",
+    '  local id="$1" link_path="$2" backing_path="$3" archive="$4" identity="$5"',
+    '  [ -f "$archive" ] || { echo "Workspace bundle $id archive missing" >&2; exit 1; }',
+    '  local sentinel="$backing_path/.spawnfile-bundle-identity"',
+    // An empty directory is not a materialized bundle: the Grok broker preflight starts before this runs and
+    // needs every worker deny target to exist, so the Daimon entrypoint pre-creates missing resource backings
+    // empty. Anything with content still has to attest its identity, exactly as a git backing does above.
+    '  if [ -e "$backing_path" ] && { [ ! -d "$backing_path" ] || [ -L "$backing_path" ] || ! directory_is_empty "$backing_path"; }; then',
+    '    [ -f "$sentinel" ] && [ "$(cat "$sentinel")" = "$identity" ] || { echo "Workspace bundle $id identity mismatch" >&2; exit 1; }',
+    "  else",
+    '    mkdir -p "$backing_path"',
+    '    tar --no-same-owner --no-same-permissions -xf "$archive" -C "$backing_path"',
+    '    printf %s "$identity" > "$sentinel"',
+    "  fi",
+    '  mark_readonly_resource "$backing_path" readonly',
+    '  prepare_resource_link "$id" "$link_path" "$backing_path"',
+    "}",
+    "",
     "prepare_git_resource() {",
     '  local id="$1"',
     '  local link_path="$2"',

package/dist/compiler/daimonTelemetryArtifacts.d.ts

@@ -2,7 +2,7 @@ import type { ContainerPersistentMountReport } from "../report/index.js";
 import type { CompiledNodeArtifact, RuntimeTargetPlan } from "./containerArtifactsTypes.js";
 import type { CompilePlan } from "./types.js";
 export interface DaimonTelemetryArtifactBundle {
-    /** One durable volume per pi/daimon agent, mounted onto its telemetry directory. */
+    /** One durable volume per legacy Pi agent, mounted onto its telemetry directory. */
     mounts: ContainerPersistentMountReport[];
     /** Runtime target plan id (e.g. "pi-app") -> { node id -> telemetry persistent mount id
      * }, so `containerArtifacts.ts` can stamp `runtime_instances[].telemetry_mount_ids` and
@@ -11,7 +11,7 @@ export interface DaimonTelemetryArtifactBundle {
     telemetryMountIdsByInstance: Map<string, Record<string, string>>;
 }
 /**
- * Registers one run-scoped durable volume per pi/daimon agent for its daimon turn/wake
+ * Registers one run-scoped durable volume per legacy Pi agent for its daimon turn/wake
  * causal telemetry directory (`<instanceRoot>/runtime/agents/<slug>/telemetry` — the parent
  * of `causal.jsonl`, see `appCoreSource.ts`'s `runtimeHomePath`/`instanceRoot`), mirroring
  * exactly how `moltnetArtifacts.ts` mounts the Moltnet causal directory (Piece 4b,

package/dist/compiler/daimonTelemetryArtifacts.js

@@ -1,16 +1,11 @@
 import path from "node:path/posix";
 import { resolveNoopolisRunId } from "../runtime/index.js";
 import { createPersistentVolumeName } from "./moltnetArtifactPaths.js";
-/** Runtime names whose generated app is `src/runtime/pi/appCoreSource.ts` (the pi harness
- * and its `daimonAdapter` alias — see `src/runtime/pi/adapter.ts`'s
- * `export const daimonAdapter: RuntimeAdapter = { ...piAdapter, name: "daimon" }`, which
- * shares `piAdapter.container`/`createContainerTargets` byte-for-byte). Both write daimon
- * turn/wake causal telemetry the same way, under `runtimeHomePath` (appCoreSource.ts:189),
- * so both need the telemetry mount, not just the literal "pi" runtime name. */
-const DAIMON_TELEMETRY_RUNTIME_NAMES = new Set(["daimon", "pi"]);
+/** Only the legacy generated Pi application writes this telemetry layout. */
+const PI_TELEMETRY_RUNTIME_NAMES = new Set(["pi"]);
 const createTelemetryMountId = (agentSlug) => `agent-${agentSlug}-daimon-telemetry`;
 /**
- * Registers one run-scoped durable volume per pi/daimon agent for its daimon turn/wake
+ * Registers one run-scoped durable volume per legacy Pi agent for its daimon turn/wake
  * causal telemetry directory (`<instanceRoot>/runtime/agents/<slug>/telemetry` — the parent
  * of `causal.jsonl`, see `appCoreSource.ts`'s `runtimeHomePath`/`instanceRoot`), mirroring
  * exactly how `moltnetArtifacts.ts` mounts the Moltnet causal directory (Piece 4b,
@@ -31,7 +26,7 @@ export const createDaimonTelemetryArtifacts = (plan, runtimePlans, compiledNodes
     const mounts = [];
     const telemetryMountIdsByInstance = new Map();
     for (const runtimePlan of runtimePlans) {
-        if (!DAIMON_TELEMETRY_RUNTIME_NAMES.has(runtimePlan.runtimeName) || !runtimePlan.instancePaths.homePath) {
+        if (!PI_TELEMETRY_RUNTIME_NAMES.has(runtimePlan.runtimeName) || !runtimePlan.instancePaths.homePath) {
             continue;
         }
         const instanceRoot = runtimePlan.instancePaths.instanceRoot ?? path.dirname(runtimePlan.instancePaths.homePath);
@@ -46,7 +41,7 @@ export const createDaimonTelemetryArtifacts = (plan, runtimePlans, compiledNodes
                 id: mountId,
                 mount_path: path.join(instanceRoot, "runtime", "agents", agentSlug, "telemetry"),
                 reason: `daimon turn/wake causal telemetry for ${agentSlug}`,
-                volume_name: createPersistentVolumeName(plan.root, mountId, undefined, runId)
+                volume_name: createPersistentVolumeName(plan.root, mountId, runId)
             });
             mountIdsByNodeId[nodeId] = mountId;
         }

package/dist/compiler/deploymentLineage.d.ts

@@ -0,0 +1,40 @@
+import type { ContainerPersistentMountReport } from "../report/types.js";
+/**
+ * Lineage namespace for `spawnfile dev up`.
+ *
+ * A derived `exclusive-reattach` volume name folds in the deployment lineage,
+ * and `dev up` used to delegate straight to `up` with no distinguishing
+ * identity — so both defaulted to the lineage `default` and resolved to the
+ * SAME host volumes. A dev deployment started while production was stopped
+ * therefore attached production's volumes and wrote into live state. That is
+ * strictly worse than the loss this branch set out to fix: loss is recoverable
+ * from a backup, a dev agent editing production's message store is not.
+ *
+ * The namespace applies to the lineage only, never to the deployment name, so
+ * deployment records, labels, and `spawnfile dev stop --deployment <name>` are
+ * unchanged. It also applies regardless of `--deployment`, so `dev up
+ * --deployment blue` and `up --deployment blue` still cannot collide.
+ */
+export declare const DEV_DEPLOYMENT_LINEAGE_NAMESPACE = "dev";
+/**
+ * Combines a lineage namespace with a deployment name. The result is only ever
+ * a hash input (`createExclusiveReattachVolumeName`), so any injective
+ * encoding works; `\0` cannot occur in a deployment name and therefore cannot
+ * be used to forge a collision with a production lineage.
+ */
+export declare const resolveDeploymentLineage: (deploymentName: string, namespace?: string) => string;
+/**
+ * An author-declared volume name carries no lineage — that is the point of
+ * declaring it, and it is what lets an operator pre-create or migrate the
+ * volume. It also means the namespace above cannot protect a declared volume:
+ * `dev up` would attach production's `clank-newsroom-store` by that exact name.
+ *
+ * "I declared a stable host volume name" and "this is a throwaway dev
+ * deployment" are contradictory intentions, and the branch's established
+ * posture for that situation is to fail closed with a named, explicit
+ * override rather than to warn into a scrolling log. So `dev up` refuses,
+ * listing the exact volumes it would have attached, and `--allow-declared-volumes`
+ * is how an operator says they meant it (a scratch clone of the project, or a
+ * deliberate read of real state).
+ */
+export declare const assertNoDeclaredVolumeNames: (mounts: readonly ContainerPersistentMountReport[]) => void;

package/dist/compiler/deploymentLineage.js

@@ -0,0 +1,50 @@
+import { SpawnfileError } from "../shared/index.js";
+/**
+ * Lineage namespace for `spawnfile dev up`.
+ *
+ * A derived `exclusive-reattach` volume name folds in the deployment lineage,
+ * and `dev up` used to delegate straight to `up` with no distinguishing
+ * identity — so both defaulted to the lineage `default` and resolved to the
+ * SAME host volumes. A dev deployment started while production was stopped
+ * therefore attached production's volumes and wrote into live state. That is
+ * strictly worse than the loss this branch set out to fix: loss is recoverable
+ * from a backup, a dev agent editing production's message store is not.
+ *
+ * The namespace applies to the lineage only, never to the deployment name, so
+ * deployment records, labels, and `spawnfile dev stop --deployment <name>` are
+ * unchanged. It also applies regardless of `--deployment`, so `dev up
+ * --deployment blue` and `up --deployment blue` still cannot collide.
+ */
+export const DEV_DEPLOYMENT_LINEAGE_NAMESPACE = "dev";
+/**
+ * Combines a lineage namespace with a deployment name. The result is only ever
+ * a hash input (`createExclusiveReattachVolumeName`), so any injective
+ * encoding works; `\0` cannot occur in a deployment name and therefore cannot
+ * be used to forge a collision with a production lineage.
+ */
+export const resolveDeploymentLineage = (deploymentName, namespace) => namespace ? `${namespace}\0${deploymentName}` : deploymentName;
+/**
+ * An author-declared volume name carries no lineage — that is the point of
+ * declaring it, and it is what lets an operator pre-create or migrate the
+ * volume. It also means the namespace above cannot protect a declared volume:
+ * `dev up` would attach production's `clank-newsroom-store` by that exact name.
+ *
+ * "I declared a stable host volume name" and "this is a throwaway dev
+ * deployment" are contradictory intentions, and the branch's established
+ * posture for that situation is to fail closed with a named, explicit
+ * override rather than to warn into a scrolling log. So `dev up` refuses,
+ * listing the exact volumes it would have attached, and `--allow-declared-volumes`
+ * is how an operator says they meant it (a scratch clone of the project, or a
+ * deliberate read of real state).
+ */
+export const assertNoDeclaredVolumeNames = (mounts) => {
+    const declared = [...new Set(mounts.flatMap((mount) => mount.declared_volume_name ? [mount.declared_volume_name] : []))].sort();
+    if (declared.length === 0)
+        return;
+    throw new SpawnfileError("validation_error", `This dev deployment would attach ${declared.length} author-declared volume`
+        + `${declared.length === 1 ? "" : "s"} by name, which a production deployment of `
+        + `this project uses too: ${declared.join(", ")}. A declared name carries no `
+        + "deployment identity, so dev would write into that live state. Remove the "
+        + "declared name, run dev against a copy of the project, or pass "
+        + "--allow-declared-volumes to attach them deliberately.");
+};

package/dist/compiler/index.d.ts

@@ -4,10 +4,13 @@ export * from "./buildProject.js";
 export * from "./publishProject.js";
 export * from "./upProject.js";
 export * from "./compileProject.js";
+export * from "./containerBackedMountRender.js";
+export * from "./deploymentLineage.js";
 export * from "./dockerBuildContext.js";
 export * from "./dockerBuildSkip.js";
 export * from "./initProject.js";
 export * from "./moltnetRoomMemberships.js";
+export * from "./preflightCompilePlan.js";
 export * from "./runProject.js";
 export * from "./syncProjectAuth.js";
 export * from "./types.js";
@@ -17,3 +20,5 @@ export * from "./updateProjectSurfaces.js";
 export * from "./upReceipt.js";
 export * from "./worldBindings.js";
 export * from "./view/index.js";
+export * from "./training/index.js";
+export * from "./recordingReport.js";

package/dist/compiler/index.js

@@ -4,10 +4,13 @@ export * from "./buildProject.js";
 export * from "./publishProject.js";
 export * from "./upProject.js";
 export * from "./compileProject.js";
+export * from "./containerBackedMountRender.js";
+export * from "./deploymentLineage.js";
 export * from "./dockerBuildContext.js";
 export * from "./dockerBuildSkip.js";
 export * from "./initProject.js";
 export * from "./moltnetRoomMemberships.js";
+export * from "./preflightCompilePlan.js";
 export * from "./runProject.js";
 export * from "./syncProjectAuth.js";
 export * from "./types.js";
@@ -17,3 +20,5 @@ export * from "./updateProjectSurfaces.js";
 export * from "./upReceipt.js";
 export * from "./worldBindings.js";
 export * from "./view/index.js";
+export * from "./training/index.js";
+export * from "./recordingReport.js";

package/dist/compiler/initProject.d.ts

@@ -2,7 +2,9 @@ export interface InitProjectOptions {
     directory?: string;
     runtime?: string;
     team?: boolean;
+    template?: string;
 }
+export declare const listInitTemplates: () => Promise<string[]>;
 export declare const initProject: (options?: InitProjectOptions) => Promise<{
     createdFiles: string[];
     directory: string;

package/dist/compiler/initProject.js

@@ -1,9 +1,22 @@
 import path from "node:path";
-import { ensureDirectory, ensureGitignoreEntry, fileExists, writeUtf8File } from "../filesystem/index.js";
+import { readdir } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { copyDirectory, ensureDirectory, ensureGitignoreEntry, fileExists, writeUtf8File } from "../filesystem/index.js";
 import { createTeamScaffoldManifest, renderSpawnfile } from "../manifest/index.js";
 import { getRuntimeAdapter } from "../runtime/index.js";
 import { DEFAULT_OUTPUT_DIRECTORY, SpawnfileError } from "../shared/index.js";
 const DEFAULT_AGENT_RUNTIME = "openclaw";
+// Bundled example org projects double as `init --template` starting points.
+// Resolves to the package's examples/ dir in both dev (src/) and the published
+// package (dist/), so examples/ must ship in package.json "files".
+const EXAMPLES_ROOT = fileURLToPath(new URL("../../examples", import.meta.url));
+export const listInitTemplates = async () => {
+    const entries = await readdir(EXAMPLES_ROOT, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort();
+};
 export const initProject = async (options = {}) => {
     const directory = path.resolve(options.directory ?? process.cwd());
     const manifestPath = path.join(directory, "Spawnfile");
@@ -11,10 +24,35 @@ export const initProject = async (options = {}) => {
     if (await fileExists(manifestPath)) {
         throw new SpawnfileError("io_error", `Refusing to overwrite existing Spawnfile at ${manifestPath}`);
     }
+    if (options.template && (options.team || options.runtime)) {
+        throw new SpawnfileError("validation_error", "--template cannot be combined with --team or --runtime");
+    }
     if (options.team && options.runtime) {
         throw new SpawnfileError("validation_error", "Team scaffolds do not accept --runtime");
     }
+    // Resolve and validate the template before creating anything, so an unknown
+    // template name never leaves an empty directory behind.
+    let templateSource;
+    if (options.template) {
+        const templates = await listInitTemplates();
+        if (!templates.includes(options.template)) {
+            throw new SpawnfileError("validation_error", `Unknown template "${options.template}". Available templates: ${templates.join(", ")}`);
+        }
+        templateSource = path.join(EXAMPLES_ROOT, options.template);
+    }
     await ensureDirectory(directory);
+    if (templateSource) {
+        await copyDirectory(templateSource, directory);
+        await ensureGitignoreEntry(directory, `${DEFAULT_OUTPUT_DIRECTORY}/`);
+        // Report only the files this template contributed — never pre-existing
+        // contents of the target directory.
+        const sourceEntries = await readdir(templateSource, { recursive: true, withFileTypes: true });
+        const createdFiles = sourceEntries
+            .filter((entry) => entry.isFile())
+            .map((entry) => path.join(directory, path.relative(templateSource, path.join(entry.parentPath, entry.name))))
+            .sort();
+        return { createdFiles, directory };
+    }
     const createdFiles = [manifestPath];
     const gitignorePath = path.join(directory, ".gitignore");
     const hadGitignore = await fileExists(gitignorePath);

package/dist/compiler/localMoltnetAuthority.d.ts

@@ -0,0 +1,64 @@
+import type { MoltnetTargetArchitecture } from "./moltnetReleaseAuthority.js";
+export interface LocalMoltnetReleaseIdentity {
+    readonly architecture: MoltnetTargetArchitecture;
+    readonly asset: string;
+    readonly asset_sha256: `sha256:${string}`;
+    readonly capabilities: readonly ["daimon-bridge", "pi-bridge"];
+    readonly development: Readonly<{
+        mode: "local-development";
+        non_production: true;
+        unsigned: true;
+        unpublished: true;
+    }>;
+    readonly source_sha256: `sha256:${string}`;
+    readonly source_inputs?: Readonly<{
+        dependencies_sha256: `sha256:${string}`;
+        mode: "source-bundle";
+        source_sha256: `sha256:${string}`;
+        toolchain: string;
+    }>;
+    readonly version: "spawnfile.moltnet-release-identity.v1";
+}
+interface LocalMoltnetReleaseStamp {
+    readonly arch: MoltnetTargetArchitecture;
+    readonly asset: string;
+    readonly capabilities: readonly ["daimon-bridge", "pi-bridge"];
+    readonly development: LocalMoltnetReleaseIdentity["development"];
+    readonly sha256: string;
+    readonly source_sha256: `sha256:${string}`;
+    readonly source_inputs?: LocalMoltnetReleaseIdentity["source_inputs"];
+    readonly stamp_version: "spawnfile.local-moltnet-release-stamp.v1";
+}
+/** @internal Complete synthetic bridge contract used by local artifact verification. */
+export declare const createLocalMoltnetBridgeProbeConfig: (kind: "daimon" | "pi", directory: string) => string;
+/** @internal Strict parser shared with provenance regression tests. */
+export declare const parseLocalReleaseStamp: (raw: string, architecture: MoltnetTargetArchitecture) => LocalMoltnetReleaseStamp;
+/**
+ * The platform actually executing this compile -- never the build target.
+ *
+ * `architecture` is absent when the host CPU is one Spawnfile cannot name as a
+ * Moltnet target (so it can never accidentally equal one), and `platform` is a
+ * raw `process.platform`.
+ */
+export interface MoltnetExecutionHost {
+    readonly architecture?: MoltnetTargetArchitecture;
+    readonly platform: NodeJS.Platform;
+}
+/**
+ * Whether this host can run the built binary directly, deciding between the
+ * direct-exec probe and the Docker cross-platform probe below.
+ *
+ * A local Moltnet build is ALWAYS `GOOS=linux` (the asset is
+ * `moltnet_linux_<arch>.tar.gz`), so matching the architecture alone is not
+ * enough: a darwin/arm64 host and a linux/arm64 binary share a CPU
+ * architecture and share nothing else. Executing that ELF on macOS fails with
+ * ENOEXEC and the probe reports the binary as unprovable, rejecting a
+ * perfectly good build. The host must therefore match on OS *and*
+ * architecture; everything else goes through Docker, which can run a
+ * linux/<arch> image anywhere.
+ *
+ * @internal Exported for the branch-selection tests.
+ */
+export declare const moltnetBinaryIsDirectlyExecutable: (architecture: MoltnetTargetArchitecture, host: MoltnetExecutionHost) => boolean;
+export declare const readLocalMoltnetReleaseIdentity: (releaseDirectory: string, architecture: MoltnetTargetArchitecture, host: MoltnetExecutionHost) => Promise<LocalMoltnetReleaseIdentity>;
+export {};

package/dist/compiler/localMoltnetAuthority.js

@@ -0,0 +1,177 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { chmod, readFile, rm, writeFile } from "node:fs/promises";
+import { promisify } from "node:util";
+import { ensureDirectory, fileExists } from "../filesystem/index.js";
+import { SpawnfileError } from "../shared/index.js";
+const execFile = promisify(execFileCallback);
+const SHA256 = /^[a-f0-9]{64}$/u;
+const exactKeys = (value, keys) => Object.keys(value).sort().join("\0") === [...keys].sort().join("\0");
+const assetName = (architecture) => `moltnet_linux_${architecture}.tar.gz`;
+/** @internal Complete synthetic bridge contract used by local artifact verification. */
+export const createLocalMoltnetBridgeProbeConfig = (kind, directory) => JSON.stringify({
+    attachments: [{
+            agent: { id: `${kind}-capability-probe`, name: `${kind} capability probe` },
+            runtime: kind === "daimon"
+                ? {
+                    control_url: "http://127.0.0.1:9",
+                    kind,
+                    receipt_store_path: path.join(directory, "daimon-receipts", "daimon-capability-probe.json"),
+                    token_env: "SPAWNFILE_DAIMON_CONTROL_TOKEN"
+                }
+                : { control_url: "http://127.0.0.1:9/agents/pi-capability-probe/wake", kind }
+        }],
+    moltnet: { base_url: "http://127.0.0.1:9", network_id: "capability-probe" },
+    version: "moltnet.node.v1"
+});
+const assertBridgeCapability = async (binaryPath, directory, kind) => {
+    const configPath = path.join(directory, `${kind}-bridge-probe.json`);
+    const receiptDirectory = path.join(directory, "daimon-receipts");
+    await ensureDirectory(receiptDirectory);
+    await chmod(receiptDirectory, 0o700);
+    await writeFile(configPath, createLocalMoltnetBridgeProbeConfig(kind, directory), { mode: 0o600 });
+    try {
+        await execFile(binaryPath, ["node", configPath], {
+            env: { ...process.env, SPAWNFILE_DAIMON_CONTROL_TOKEN: "capability-probe" },
+            timeout: 1_000
+        });
+        throw new SpawnfileError("compile_error", `Local Moltnet binary exited before proving its ${kind}-bridge capability`);
+    }
+    catch (error) {
+        if (error instanceof SpawnfileError)
+            throw error;
+        const execution = error;
+        const output = `${String(execution.stdout ?? "")}\n${String(execution.stderr ?? "")}`;
+        if (/unsupported|only supported|required|invalid|unknown runtime/i.test(output)) {
+            throw new SpawnfileError("compile_error", `Local Moltnet binary does not accept ${kind}-bridge configuration`);
+        }
+        if (execution.killed === true || execution.signal === "SIGTERM" || execution.code === "ETIMEDOUT")
+            return;
+        if (/connection refused|connect:|dial tcp|network is unreachable/i.test(output))
+            return;
+        throw new SpawnfileError("compile_error", `Local Moltnet binary could not prove its ${kind}-bridge capability`);
+    }
+};
+/** @internal Strict parser shared with provenance regression tests. */
+export const parseLocalReleaseStamp = (raw, architecture) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new SpawnfileError("compile_error", "Local Moltnet release stamp is not valid JSON");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new SpawnfileError("compile_error", "Local Moltnet release stamp has an invalid shape");
+    }
+    const value = parsed;
+    const development = value.development;
+    const sourceInputs = value.source_inputs;
+    if (!exactKeys(value, ["arch", "asset", "capabilities", "development", "sha256", "source_sha256", "stamp_version", ...(sourceInputs ? ["source_inputs"] : [])])
+        || value.stamp_version !== "spawnfile.local-moltnet-release-stamp.v1"
+        || value.arch !== architecture
+        || value.asset !== assetName(architecture)
+        || !Array.isArray(value.capabilities)
+        || value.capabilities.join("\0") !== "daimon-bridge\0pi-bridge"
+        || !development
+        || !exactKeys(development, ["mode", "non_production", "unsigned", "unpublished"])
+        || development.mode !== "local-development"
+        || development.non_production !== true
+        || development.unsigned !== true
+        || development.unpublished !== true
+        || typeof value.sha256 !== "string"
+        || !SHA256.test(value.sha256)
+        || typeof value.source_sha256 !== "string"
+        || !/^sha256:[a-f0-9]{64}$/u.test(value.source_sha256)
+        || (sourceInputs && (!exactKeys(sourceInputs, ["dependencies_sha256", "mode", "source_sha256", "toolchain"]) || sourceInputs.mode !== "source-bundle" || !/^sha256:[a-f0-9]{64}$/u.test(String(sourceInputs.dependencies_sha256)) || sourceInputs.source_sha256 !== value.source_sha256 || sourceInputs.toolchain !== "golang:1.24-bookworm@sha256:1a6d4452c65dea36aac2e2d606b01b4a029ec90cc1ae53890540ce6173ea77ac"))) {
+        throw new SpawnfileError("compile_error", "Local Moltnet release stamp must be a complete development-only dual-bridge identity");
+    }
+    return value;
+};
+/**
+ * Whether this host can run the built binary directly, deciding between the
+ * direct-exec probe and the Docker cross-platform probe below.
+ *
+ * A local Moltnet build is ALWAYS `GOOS=linux` (the asset is
+ * `moltnet_linux_<arch>.tar.gz`), so matching the architecture alone is not
+ * enough: a darwin/arm64 host and a linux/arm64 binary share a CPU
+ * architecture and share nothing else. Executing that ELF on macOS fails with
+ * ENOEXEC and the probe reports the binary as unprovable, rejecting a
+ * perfectly good build. The host must therefore match on OS *and*
+ * architecture; everything else goes through Docker, which can run a
+ * linux/<arch> image anywhere.
+ *
+ * @internal Exported for the branch-selection tests.
+ */
+export const moltnetBinaryIsDirectlyExecutable = (architecture, host) => host.platform === "linux" && host.architecture === architecture;
+const verifyBuiltMoltnetArchive = async (releaseAssetPath, architecture, host) => {
+    const temporaryDirectory = path.join(path.dirname(releaseAssetPath), `.spawnfile-moltnet-verify-${process.pid}-${Date.now()}`);
+    try {
+        await ensureDirectory(temporaryDirectory);
+        await execFile("tar", ["-C", temporaryDirectory, "-xzf", releaseAssetPath]);
+        const binaryPath = path.join(temporaryDirectory, "moltnet");
+        if (!(await fileExists(binaryPath))) {
+            throw new SpawnfileError("compile_error", "Local Moltnet archive does not contain its moltnet binary");
+        }
+        await chmod(binaryPath, 0o755);
+        if (moltnetBinaryIsDirectlyExecutable(architecture, host)) {
+            const { stdout } = await execFile(binaryPath, ["version"]);
+            if (!stdout.trim())
+                throw new SpawnfileError("compile_error", "Local Moltnet binary did not produce a bounded version identity");
+            await assertBridgeCapability(binaryPath, temporaryDirectory, "pi");
+            await assertBridgeCapability(binaryPath, temporaryDirectory, "daimon");
+        }
+        else {
+            for (const kind of ["pi", "daimon"]) {
+                const configPath = path.join(temporaryDirectory, `${kind}-docker-probe.json`);
+                await writeFile(configPath, createLocalMoltnetBridgeProbeConfig(kind, "/receipts"));
+                const { stdout: rawId } = await execFile("docker", ["create", "--platform", `linux/${architecture}`, "--env", "SPAWNFILE_DAIMON_CONTROL_TOKEN=probe", "node:24-bookworm-slim@sha256:a9f5f7c91a432850b2a8a7797adf5eadb6c733ceed61167806cee7ea7fbc29df", "timeout", "2", "/moltnet", "node", "/config.json"]);
+                const id = rawId.trim();
+                try {
+                    await execFile("docker", ["cp", binaryPath, `${id}:/moltnet`]);
+                    await execFile("docker", ["cp", configPath, `${id}:/config.json`]);
+                    try {
+                        await execFile("docker", ["start", "--attach", id]);
+                    }
+                    catch (error) {
+                        const result = error;
+                        const output = `${String(result.stdout ?? "")}\n${String(result.stderr ?? "")}`;
+                        if (result.code !== 124 && !/connection refused|connect:|dial tcp|network is unreachable/iu.test(output))
+                            throw new SpawnfileError("compile_error", `Local Moltnet cross-host ${kind} capability probe failed`);
+                    }
+                }
+                finally {
+                    await execFile("docker", ["rm", "--force", id]);
+                }
+            }
+        }
+    }
+    finally {
+        await rm(temporaryDirectory, { force: true, recursive: true });
+    }
+};
+export const readLocalMoltnetReleaseIdentity = async (releaseDirectory, architecture, host) => {
+    const asset = assetName(architecture);
+    const assetPath = path.join(releaseDirectory, asset);
+    const stampPath = path.join(releaseDirectory, `local_moltnet_release_stamp_${architecture}.json`);
+    if (!(await fileExists(assetPath)) || !(await fileExists(stampPath))) {
+        throw new SpawnfileError("compile_error", "Local Moltnet release requires its exact archive and development identity stamp");
+    }
+    const stamp = parseLocalReleaseStamp(await readFile(stampPath, "utf8"), architecture);
+    const sha256 = createHash("sha256").update(await readFile(assetPath)).digest("hex");
+    if (stamp.sha256 !== sha256) {
+        throw new SpawnfileError("compile_error", "Local Moltnet development stamp does not match its archive bytes");
+    }
+    await verifyBuiltMoltnetArchive(assetPath, architecture, host);
+    return Object.freeze({
+        architecture,
+        asset,
+        asset_sha256: `sha256:${sha256}`,
+        capabilities: Object.freeze(["daimon-bridge", "pi-bridge"]),
+        development: Object.freeze({ mode: "local-development", non_production: true, unsigned: true, unpublished: true }),
+        source_sha256: stamp.source_sha256,
+        ...(stamp.source_inputs ? { source_inputs: Object.freeze(stamp.source_inputs) } : {}),
+        version: "spawnfile.moltnet-release-identity.v1"
+    });
+};

package/dist/compiler/mcpPlaceholders.d.ts

@@ -0,0 +1,11 @@
+import type { McpServer } from "../manifest/index.js";
+import type { CompilePlanNode } from "./types.js";
+export interface McpPlaceholderContext {
+    agentId: string;
+    agentName: string;
+    /** Lazy: only runtimes whose servers use `${workspace}` need a resolvable path. */
+    workspace: () => string;
+}
+export declare const resolveMcpServerPlaceholders: (servers: McpServer[], context: McpPlaceholderContext) => McpServer[];
+/** Resolves every agent node's MCP placeholders in place, once node ids and slugs exist. */
+export declare const resolvePlanMcpPlaceholders: (nodes: CompilePlanNode[]) => void;