spawnfile 0.1.14 → 0.1.18

package/dist/compiler/mcpPlaceholders.js

@@ -0,0 +1,58 @@
+import { getRuntimeAdapter } from "../runtime/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { expandSourceWorkspacePathTemplate } from "./containerTargetResources.js";
+/**
+ * Compiler-owned placeholders an MCP server may use in `command`, `args` and
+ * `env` values. They are resolved per agent after the compile plan assigns
+ * node ids, so one `shared.environment.mcp_servers` entry serves every member:
+ *
+ * - `${workspace}`  the agent's workspace path inside its runtime target
+ *                   (the same path `./` workspace resource mounts link under)
+ * - `${agent.id}`   the agent's compile-plan node id, e.g. `agent:writer`
+ * - `${agent.name}` the agent manifest name
+ *
+ * `${workspace}` and anything under `${agent.` are reserved: an unknown name
+ * fails the compile instead of reaching a runtime as a literal string. Other
+ * `${...}` text is left untouched.
+ */
+const RESERVED_PLACEHOLDER = /\$\{(workspace|agent\.[^}]*)\}/gu;
+const SUPPORTED = "${workspace}, ${agent.id}, ${agent.name}";
+const fail = (context, server, detail) => {
+    throw new SpawnfileError("validation_error", `Agent ${context.agentName} MCP server ${server.name}: ${detail}`);
+};
+const resolveValue = (value, server, context) => value.replace(RESERVED_PLACEHOLDER, (match, name) => {
+    if (name === "workspace")
+        return context.workspace();
+    if (name === "agent.id")
+        return context.agentId;
+    if (name === "agent.name")
+        return context.agentName;
+    return fail(context, server, `unknown placeholder ${match}; supported placeholders are ${SUPPORTED}`);
+});
+const hasReservedPlaceholder = (value) => value !== undefined && new RegExp(RESERVED_PLACEHOLDER.source, "u").test(value);
+export const resolveMcpServerPlaceholders = (servers, context) => servers.map((server) => {
+    if (hasReservedPlaceholder(server.url) || hasReservedPlaceholder(server.auth?.secret)) {
+        fail(context, server, `placeholders (${SUPPORTED}) are only supported in command, args and env values`);
+    }
+    return {
+        ...server,
+        ...(server.command === undefined ? {} : { command: resolveValue(server.command, server, context) }),
+        ...(server.args === undefined ? {} : { args: server.args.map((arg) => resolveValue(arg, server, context)) }),
+        ...(server.env === undefined ? {} : {
+            env: Object.fromEntries(Object.entries(server.env).map(([key, value]) => [key, resolveValue(value, server, context)]))
+        })
+    };
+});
+/** Resolves every agent node's MCP placeholders in place, once node ids and slugs exist. */
+export const resolvePlanMcpPlaceholders = (nodes) => {
+    for (const node of nodes) {
+        if (node.value.kind !== "agent" || node.value.mcpServers.length === 0)
+            continue;
+        const agent = node.value;
+        agent.mcpServers = resolveMcpServerPlaceholders(agent.mcpServers, {
+            agentId: node.id,
+            agentName: agent.name,
+            workspace: () => expandSourceWorkspacePathTemplate(getRuntimeAdapter(node.runtimeName ?? agent.runtime.name).container, { agentName: agent.name, slug: node.slug })
+        });
+    }
+};

package/dist/compiler/mcpServerInheritance.d.ts

@@ -0,0 +1,18 @@
+import { type McpServer, type McpServerEntry, type SharedMcpServer } from "../manifest/index.js";
+/**
+ * Resolves an agent's effective MCP servers from its team's
+ * `shared.environment.mcp_servers` and its own entries.
+ *
+ * - A local entry that declares `transport` is a complete server and replaces
+ *   any inherited server of the same name (SPEC §4.4: member-local wins).
+ * - A local entry without `transport` narrows the inherited server of the same
+ *   name: `tools` replaces the inherited allowlist, `env` merges key by key
+ *   with local keys winning. Every other field stays inherited.
+ * - A bare `{ name }` takes the inherited server unchanged.
+ * - A shared server marked `opt_in: true` is inherited only by members that
+ *   list its name (bare or narrowing). Members never remove an inherited
+ *   server (SPEC §4.4); an opt-in server is simply not offered by default.
+ * - An override with no shared server to narrow is a compile error naming
+ *   the agent, because there is nothing to complete it from.
+ */
+export declare const resolveInheritedMcpServers: (agentName: string, sharedServers?: SharedMcpServer[], localEntries?: McpServerEntry[]) => McpServer[];

package/dist/compiler/mcpServerInheritance.js

@@ -0,0 +1,43 @@
+import { isMcpServerDeclaration } from "../manifest/index.js";
+import { SpawnfileError } from "../shared/index.js";
+/**
+ * Resolves an agent's effective MCP servers from its team's
+ * `shared.environment.mcp_servers` and its own entries.
+ *
+ * - A local entry that declares `transport` is a complete server and replaces
+ *   any inherited server of the same name (SPEC §4.4: member-local wins).
+ * - A local entry without `transport` narrows the inherited server of the same
+ *   name: `tools` replaces the inherited allowlist, `env` merges key by key
+ *   with local keys winning. Every other field stays inherited.
+ * - A bare `{ name }` takes the inherited server unchanged.
+ * - A shared server marked `opt_in: true` is inherited only by members that
+ *   list its name (bare or narrowing). Members never remove an inherited
+ *   server (SPEC §4.4); an opt-in server is simply not offered by default.
+ * - An override with no shared server to narrow is a compile error naming
+ *   the agent, because there is nothing to complete it from.
+ */
+export const resolveInheritedMcpServers = (agentName, sharedServers = [], localEntries = []) => {
+    const inherited = new Map();
+    const resolved = new Map();
+    for (const { opt_in: optIn, ...server } of sharedServers) {
+        inherited.set(server.name, server);
+        if (optIn !== true)
+            resolved.set(server.name, server);
+    }
+    for (const entry of localEntries) {
+        if (isMcpServerDeclaration(entry)) {
+            resolved.set(entry.name, entry);
+            continue;
+        }
+        const base = inherited.get(entry.name);
+        if (!base) {
+            throw new SpawnfileError("validation_error", `Agent ${agentName} overrides MCP server ${entry.name}, but its team declares no shared.environment.mcp_servers entry named ${entry.name}; declare transport to define the server locally`);
+        }
+        resolved.set(entry.name, {
+            ...base,
+            ...(entry.tools === undefined ? {} : { tools: entry.tools }),
+            ...(entry.env === undefined ? {} : { env: { ...base.env, ...entry.env } })
+        });
+    }
+    return [...resolved.values()];
+};

package/dist/compiler/memoryArtifacts.d.ts

@@ -22,5 +22,5 @@ export interface MemoryArtifactBundle {
     mounts: ContainerPersistentMountReport[];
     memories: MemoryArtifactSummary[];
 }
-export declare const createMemoryArtifactBundle: (plan: CompilePlan) => MemoryArtifactBundle;
+export declare const createMemoryArtifactBundle: (plan: CompilePlan, deploymentLineage?: string) => MemoryArtifactBundle;
 export {};

package/dist/compiler/memoryArtifacts.js

@@ -1,8 +1,6 @@
-import path from "node:path/posix";
-import { resolveNoopolisRunId } from "../runtime/index.js";
+import { resolveMnemeDurableMemoryMountPath } from "../runtime/mnemeMcp.js";
+import { createExclusiveReattachVolumeName, SpawnfileError } from "../shared/index.js";
 import { slugify } from "./helpers.js";
-import { createPersistentVolumeName } from "./moltnetArtifactPaths.js";
-const normalizePosixPath = (value) => path.normalize(value).replace(/\/+$/u, "") || "/";
 const safeSlug = (value) => slugify(value).trim() || "memory";
 const createMountId = (mountPath) => `memory-${safeSlug(mountPath)}`;
 const isFileBackedMemoryStore = (bank) => bank.store.kind === "sqlite" || bank.store.kind === "json";
@@ -10,7 +8,33 @@ const transportFromRuntime = (runtimeName, bank) => {
     switch (runtimeName) {
         case "pi":
         case "daimon":
-            return "direct";
+            // Mneme runs in-process for these runtimes (no MCP subprocess), but
+            // whether that in-process runtime is reachable -- and whether it
+            // persists anything -- depends on the store:
+            //   - sqlite/json WITH a durable mount: a real runtime home backed by
+            //     a persistent volume this same module emits.
+            //   - sqlite/json WITHOUT one (persistence.mode "ephemeral", or no
+            //     resolvable path at all): no volume is mounted and Daimon emits no
+            //     memory block, so recall lasts at most the container's lifetime --
+            //     exactly the "memory" kind's situation, and reported the same way.
+            //   - memory: Mneme still runs in-process against a synthesized runtime
+            //     home path, but no persistent volume is emitted for this kind.
+            //   - postgres: no runtime home path at all; the in-process runtime
+            //     gets no memory whatsoever.
+            //
+            // The durable/ephemeral half of that decision is NOT re-derived here:
+            // it comes from resolveMnemeDurableMemoryMountPath, the same authority
+            // that decides the mount below, so the report cannot disagree with what
+            // was actually emitted.
+            switch (bank.store.kind) {
+                case "sqlite":
+                case "json":
+                    return resolveMnemeDurableMemoryMountPath(bank) === null ? "degraded" : "direct";
+                case "memory":
+                    return "degraded";
+                default:
+                    return "unsupported";
+            }
         case "picoclaw":
         case "openclaw":
             return isFileBackedMemoryStore(bank) ? "mcp" : "degraded_mcp";
@@ -18,20 +42,10 @@ const transportFromRuntime = (runtimeName, bank) => {
             return "unsupported";
     }
 };
-const memoryMountPath = (bank) => {
-    if (bank.store.kind !== "sqlite" && bank.store.kind !== "json") {
-        return null;
-    }
-    if (bank.store.persistence?.mode === "ephemeral") {
-        return null;
-    }
-    if (bank.store.persistence?.mount) {
-        return normalizePosixPath(bank.store.persistence.mount);
-    }
-    return bank.store.path
-        ? path.dirname(normalizePosixPath(bank.store.path))
-        : null;
-};
+// The mount decision itself lives in runtime/mnemeMcp.ts so that runtime config
+// emitters (which must only point an in-process Mneme runtime at a path this
+// module actually mounts) and this module cannot drift apart.
+const memoryMountPath = resolveMnemeDurableMemoryMountPath;
 const summarizeMemoryStore = (bank, mountId) => {
     const persistenceMode = bank.store.kind === "sqlite" || bank.store.kind === "json"
         ? (bank.store.persistence?.mode ?? "durable")
@@ -44,13 +58,69 @@ const summarizeMemoryStore = (bank, mountId) => {
         ...(bank.store.kind === "postgres" ? { dsn_secret: bank.store.dsn_secret } : {})
     };
 };
-export const createMemoryArtifactBundle = (plan) => {
-    // Run-scoping key for every derived volume name below (see
-    // createPersistentVolumeName's doc comment in moltnetArtifactPaths.ts):
-    // present whenever this compile was driven by `spawnfile run`/`up`
-    // (which always call ensureNoopolisRunId() first), absent for a bare
-    // `spawnfile compile`/`spawnfile build`.
-    const runId = resolveNoopolisRunId(process.env);
+/**
+ * The identity of the PHYSICAL store a declared bank resolves to.
+ *
+ * Mneme addresses a store by its runtime home directory and then discards the
+ * declared filename: `JsonlMemoryStore` always writes `<home>/memory/events.jsonl`
+ * and `SQLiteMemoryIndex` always opens `<home>/memory/<default>.db`
+ * (mneme/src/store/store.ts, mneme/src/store/sqliteIndex.ts). Spawnfile resolves
+ * that home as `dirname(store.path)` unless `persistence.mount` overrides it, so
+ * `/data/mem/a.jsonl` and `/data/mem/b.jsonl` are ONE physical store wearing two
+ * declared names — two concurrent MemoryRuntimes appending to one file and
+ * opening one SQLite database.
+ *
+ * Two declarations may therefore share a durable directory only when they are
+ * the same bank said twice (the legitimate case: one bank declared in an org
+ * scope and again in a nested team scope so both sides can access it). Anything
+ * that differs — a different id, a different declared file, a different index
+ * intent — means the author believes they have two stores and the runtime will
+ * silently give them one.
+ */
+const physicalStoreIdentity = (bank) => JSON.stringify({
+    consolidation: bank.consolidation,
+    id: bank.id,
+    index: bank.index,
+    retention: bank.retention,
+    store: {
+        kind: bank.store.kind,
+        mount: bank.store.persistence?.mount ?? null,
+        name: bank.store.persistence?.name ?? null,
+        path: bank.store.path ?? null
+    }
+});
+const collidingBankMessage = (mountPath, prior, next) => `Memory banks ${prior.bankId} (declared in ${prior.source}) and ${next.bankId} `
+    + `(declared in ${next.source}) both resolve to the durable memory directory ${mountPath}, `
+    + "but do not declare the same store. Mneme keys a store by that directory and ignores the "
+    + "declared filename, so these two banks would silently become one physical store with two "
+    + "runtimes writing it. Give each bank its own directory (a distinct store.path parent or "
+    + "persistence.mount), or declare them identically if one shared bank is what you meant.";
+/**
+ * The docker volume name for a durable memory directory.
+ *
+ * Deliberately NOT run-scoped. `createPersistentVolumeName` folds NOOPOLIS_RUN_ID
+ * into the name, and `ensureNoopolisRunId` mints a fresh id on every `spawnfile
+ * run`/`up`, so a run-scoped memory volume means the organization you redeploy
+ * tomorrow starts with an empty memory bank. There is no working escape hatch
+ * today either: `spawnfile product-state clone` refuses SQLite paths, and reusing
+ * yesterday's NOOPOLIS_RUN_ID to reproduce the volume name would collapse two
+ * distinct causal runs onto one run_id in the ledger (specs/CAUSAL.md).
+ *
+ * `exclusive-reattach` is the existing lifecycle for exactly this: a host-stable
+ * name derived from the project root plus the deployment lineage, with a
+ * daemon-side reservation that refuses to start when another live container
+ * already holds the volume (src/compiler/runProjectDockerReservation.ts). That
+ * mutual exclusion is a requirement here rather than a cost — Mneme's append-only
+ * JSONL plus its SQLite index are single-writer — and it is why an organization
+ * with durable memory cannot use the concurrent blue/green canary workflow and
+ * must stop-and-reattach instead (specs/CONTAINERS.md).
+ *
+ * An author-declared `persistence.name` is honored verbatim: naming a volume is
+ * precisely a request for a host-stable identity.
+ */
+const durableMemoryVolumeName = (planRoot, mountId, declaredName, deploymentLineage) => declaredName?.trim()
+    || createExclusiveReattachVolumeName(`${planRoot}\0${deploymentLineage}`, mountId);
+export const createMemoryArtifactBundle = (plan, deploymentLineage = "compile") => {
     const sourceToNode = new Map(plan.nodes.map((node) => [node.value.source, node]));
     const groupedMemory = new Map();
     for (const access of plan.memoryAccess ?? []) {
@@ -66,6 +136,7 @@ export const createMemoryArtifactBundle = (plan) => {
     const mounts = [];
     const mountPathMemoryMap = new Map();
     const mountByPath = new Map();
+    const claimantByPath = new Map();
     const memories = [...groupedMemory.entries()]
         .sort(([left], [right]) => left.localeCompare(right))
         .map(([, entry]) => {
@@ -89,18 +160,23 @@ export const createMemoryArtifactBundle = (plan) => {
         let persistentMountId;
         if (mountPath !== null) {
             const mountId = createMountId(mountPath);
-            // createPersistentVolumeName also folds in plan.root (previously
-            // missing here entirely), so two different projects that happen to
-            // share a mount-path convention no longer derive the same volume
-            // name — the same isolation moltnet's own persistent mounts already
-            // had before this change.
-            const volumeName = createPersistentVolumeName(plan.root, mountId, entry.bank.store.persistence?.name, runId);
+            const declaredVolumeName = entry.bank.store.persistence?.name?.trim();
+            const volumeName = durableMemoryVolumeName(plan.root, mountId, entry.bank.store.persistence?.name, deploymentLineage);
+            const identity = physicalStoreIdentity(entry.bank);
+            const claimant = { bankId: entry.bank.id, identity, source: entry.source };
+            const priorClaimant = claimantByPath.get(mountPath);
+            if (priorClaimant && priorClaimant.identity !== identity) {
+                throw new SpawnfileError("validation_error", collidingBankMessage(mountPath, priorClaimant, claimant));
+            }
+            claimantByPath.set(mountPath, claimant);
             const existingMount = mountByPath.get(mountPath);
             if (existingMount && existingMount.volume_name !== volumeName) {
                 throw new Error(`Memory store mount ${mountPath} resolves to conflicting volume names`);
             }
             const mount = existingMount ?? {
+                ...(declaredVolumeName ? { declared_volume_name: declaredVolumeName } : {}),
                 id: mountId,
+                lifecycle: "exclusive-reattach",
                 mount_path: mountPath,
                 reason: `durable memory stores under ${mountPath}`,
                 volume_name: volumeName

package/dist/compiler/modelEnv.d.ts

@@ -2,6 +2,11 @@ import type { ExecutionBlock, ModelTarget } from "../manifest/index.js";
 import { type ModelAuthMethod } from "../shared/index.js";
 import type { EffectiveModelTarget } from "./types.js";
 export declare const CLI_CREDENTIAL_SECRET_NAME = "SPAWNFILE_CLI_AUTH_JSON";
+/**
+ * Only the host-imported CLI logins travel as `SPAWNFILE_CLI_AUTH_JSON`. `grok`
+ * is a Daimon-owned subscription: its credential is the broker's bootstrap
+ * slot (`runtime/daimon/runAuth.ts`), never this secret.
+ */
 export declare const modelAuthMethodNeedsCliCredential: (method: ModelAuthMethod) => boolean;
 export declare const resolveModelProviderEnvName: (provider: string) => string;
 export declare const listExecutionModelTargets: (execution: ExecutionBlock | undefined) => ModelTarget[];

package/dist/compiler/modelEnv.js

@@ -9,7 +9,12 @@ const MODEL_PROVIDER_ENV_VARS = new Map([
     ["xai", "XAI_API_KEY"]
 ]);
 export const CLI_CREDENTIAL_SECRET_NAME = "SPAWNFILE_CLI_AUTH_JSON";
-export const modelAuthMethodNeedsCliCredential = (method) => method !== "api_key" && method !== "none";
+/**
+ * Only the host-imported CLI logins travel as `SPAWNFILE_CLI_AUTH_JSON`. `grok`
+ * is a Daimon-owned subscription: its credential is the broker's bootstrap
+ * slot (`runtime/daimon/runAuth.ts`), never this secret.
+ */
+export const modelAuthMethodNeedsCliCredential = (method) => method === "claude-code" || method === "codex";
 const resolveLegacyModelAuthMethod = (execution, provider) => {
     const auth = execution?.model?.auth;
     if (!auth) {
@@ -68,7 +73,8 @@ export const resolveEffectiveModelTarget = (target, execution) => {
         },
         ...(target.endpoint ? { endpoint: target.endpoint } : {}),
         name: target.name,
-        provider: target.provider
+        provider: target.provider,
+        ...(target.reasoning_effort ? { reasoningEffort: target.reasoning_effort } : {})
     };
 };
 export const listEffectiveExecutionModelTargets = (execution) => listExecutionModelTargets(execution).map((target) => resolveEffectiveModelTarget(target, execution));

package/dist/compiler/moltnetArtifactPaths.d.ts

@@ -1,26 +1,31 @@
 import type { ResolvedTeamNode } from "./types.js";
 export declare const createMoltnetExternalParticipantArtifactPath: (networkId: string, memberId: string) => string;
 /**
- * Derives the host-mounted docker volume name for a durable mount.
+ * Derives the host-mounted docker volume name for a **run-scoped** durable
+ * mount — state whose whole point is to be fresh per run (today: the Moltnet
+ * causal event log, Daimon telemetry, per-network Moltnet runtime state).
  *
  * `runId` (the compiling process's resolved NOOPOLIS_RUN_ID, see
  * src/runtime/common.ts) is the run-scoping key: `spawnfile run`/`spawnfile
  * up` always call `ensureNoopolisRunId()` before compiling, so a fresh
  * invocation with no host-pinned run id gets a fresh generated one and
  * therefore a fresh volume — two concurrent/successive runs (e.g. two
- * memetics replicates) never share durable state. A cold restart that wants
- * to recall the same run's memory sets the SAME `NOOPOLIS_RUN_ID` before
- * re-running, which reproduces this same volume name and remounts it.
- * Omitted (a bare `spawnfile compile`/`spawnfile build` with no run id in
- * the host env) reproduces the pre-run-scoping name exactly, so standard
- * compiles stay byte-identical.
+ * memetics replicates) never share it. A cold restart that wants the same
+ * run's state sets the SAME `NOOPOLIS_RUN_ID` before re-running, which
+ * reproduces this name and remounts it. Omitted (a bare `spawnfile
+ * compile`/`spawnfile build` with no run id in the host env) reproduces the
+ * pre-run-scoping name exactly, so standard compiles stay byte-identical.
  *
- * `explicitName` (an author-declared `persistence.name`) always wins over
- * both project/id and run scoping — an explicit name is opt-in shared/
- * reused state by author intent, not something this helper should silently
- * fragment across runs.
+ * State that must SURVIVE a redeploy — workspace `kind: volume` resources,
+ * durable Moltnet stores, open-mode agent token directories, durable memory
+ * banks, the Daimon usage ledger — must NEVER be named here. Those are
+ * `lifecycle: "exclusive-reattach"` and are named by
+ * `createExclusiveReattachVolumeName` from the plan root and the deployment
+ * lineage, honouring an author-declared name verbatim. This function
+ * deliberately takes no author-declared name: a run-scoped volume is never
+ * the thing an author names.
  */
-export declare const createPersistentVolumeName: (planRoot: string, id: string, explicitName?: string, runId?: string) => string;
+export declare const createPersistentVolumeName: (planRoot: string, id: string, runId?: string) => string;
 export declare const toContainerRootfsPath: (rootfsPath: string) => string;
 export declare const isNetworkHttpEnabled: (network: NonNullable<ResolvedTeamNode["networks"]>[number]) => boolean;
 export declare const resolveNetworkPort: (network: NonNullable<ResolvedTeamNode["networks"]>[number], fallbackPort: number) => number;

package/dist/compiler/moltnetArtifactPaths.js

@@ -12,29 +12,31 @@ export const createMoltnetExternalParticipantArtifactPath = (networkId, memberId
 };
 const truncateSegment = (value, maxLength) => value.length > maxLength ? value.slice(0, maxLength).replace(/[-_.]+$/u, "") : value;
 /**
- * Derives the host-mounted docker volume name for a durable mount.
+ * Derives the host-mounted docker volume name for a **run-scoped** durable
+ * mount — state whose whole point is to be fresh per run (today: the Moltnet
+ * causal event log, Daimon telemetry, per-network Moltnet runtime state).
  *
  * `runId` (the compiling process's resolved NOOPOLIS_RUN_ID, see
  * src/runtime/common.ts) is the run-scoping key: `spawnfile run`/`spawnfile
  * up` always call `ensureNoopolisRunId()` before compiling, so a fresh
  * invocation with no host-pinned run id gets a fresh generated one and
  * therefore a fresh volume — two concurrent/successive runs (e.g. two
- * memetics replicates) never share durable state. A cold restart that wants
- * to recall the same run's memory sets the SAME `NOOPOLIS_RUN_ID` before
- * re-running, which reproduces this same volume name and remounts it.
- * Omitted (a bare `spawnfile compile`/`spawnfile build` with no run id in
- * the host env) reproduces the pre-run-scoping name exactly, so standard
- * compiles stay byte-identical.
+ * memetics replicates) never share it. A cold restart that wants the same
+ * run's state sets the SAME `NOOPOLIS_RUN_ID` before re-running, which
+ * reproduces this name and remounts it. Omitted (a bare `spawnfile
+ * compile`/`spawnfile build` with no run id in the host env) reproduces the
+ * pre-run-scoping name exactly, so standard compiles stay byte-identical.
  *
- * `explicitName` (an author-declared `persistence.name`) always wins over
- * both project/id and run scoping — an explicit name is opt-in shared/
- * reused state by author intent, not something this helper should silently
- * fragment across runs.
+ * State that must SURVIVE a redeploy — workspace `kind: volume` resources,
+ * durable Moltnet stores, open-mode agent token directories, durable memory
+ * banks, the Daimon usage ledger — must NEVER be named here. Those are
+ * `lifecycle: "exclusive-reattach"` and are named by
+ * `createExclusiveReattachVolumeName` from the plan root and the deployment
+ * lineage, honouring an author-declared name verbatim. This function
+ * deliberately takes no author-declared name: a run-scoped volume is never
+ * the thing an author names.
  */
-export const createPersistentVolumeName = (planRoot, id, explicitName, runId) => {
-    if (explicitName && explicitName.trim().length > 0) {
-        return explicitName.trim();
-    }
+export const createPersistentVolumeName = (planRoot, id, runId) => {
     const project = truncateSegment(slugify(planRoot.split("/").slice(-2, -1)[0] ?? "project") || "project", 32);
     const suffix = truncateSegment(slugify(id) || "state", 48);
     const trimmedRunId = runId?.trim();

package/dist/compiler/moltnetArtifactTypes.d.ts

@@ -11,6 +11,7 @@ export interface MoltnetServerPlan {
     networkId: string;
     port?: number;
     rooms: Array<{
+        federation?: "all" | "none" | string[];
         id: string;
         members: string[];
         name?: string;
@@ -22,15 +23,25 @@ export interface MoltnetServerPlan {
     teamSource: string;
 }
 export interface MoltnetNodePlan {
+    sourceNodeId?: string;
     configPath: string;
     credentialAgentId?: string;
     credentialId?: string;
     credentialSecret?: string;
     memberId?: string;
     networkId: string;
+    receiptStorePath?: string;
 }
 export interface MoltnetPersistentMount {
+    /** The author's `store.persistence.name`, when declared. */
+    declaredVolumeName?: string;
     id: string;
+    /**
+     * `exclusive-reattach` marks state that MUST survive container replacement
+     * and redeploy: its volume name is deployment-stable (never run-scoped) and
+     * only one live container may hold it at a time.
+     */
+    lifecycle?: "exclusive-reattach";
     mountPath: string;
     reason: string;
     volumeName: string;

package/dist/compiler/moltnetArtifacts.d.ts

@@ -1,4 +1,4 @@
 import type { MoltnetArtifacts } from "./moltnetArtifactTypes.js";
 import type { CompilePlan } from "./types.js";
 export type { MoltnetArtifacts, MoltnetNodePlan, MoltnetPersistentMount, MoltnetServerPlan } from "./moltnetArtifactTypes.js";
-export declare const generateMoltnetArtifacts: (plan: CompilePlan) => Promise<MoltnetArtifacts | null>;
+export declare const generateMoltnetArtifacts: (plan: CompilePlan, deploymentLineage?: string) => Promise<MoltnetArtifacts | null>;

package/dist/compiler/moltnetArtifacts.js

@@ -1,29 +1,44 @@
 import { resolveNoopolisRunId } from "../runtime/index.js";
-import { SpawnfileError } from "../shared/index.js";
-import { createMoltnetCausalDirectory, createMoltnetServerConfigPath, createMoltnetOpenTokenDirectory, createMoltnetNativeServerConfig, createMoltnetNodeConfigPath, resolveMoltnetClientAuth, resolveMoltnetStorePersistenceMountPath } from "./moltnetConfigLowering.js";
+import { createExclusiveReattachVolumeName, SpawnfileError } from "../shared/index.js";
+import { createMoltnetCausalDirectory, createMoltnetDaimonReceiptStorePath, createMoltnetNetworkStateDirectory, createMoltnetServerConfigPath, createMoltnetOpenTokenDirectory, createMoltnetNativeServerConfig, createMoltnetNodeConfigPath, resolveMoltnetClientAuth, resolveMoltnetStorePersistenceMountPath } from "./moltnetConfigLowering.js";
 import { assertNetworkBindingEnvUniqueness } from "./networkBinding.js";
 import { createMoltnetNodeConfigContent } from "./moltnetNodeConfig.js";
 import { createPersistentVolumeName, isNetworkHttpEnabled, toContainerRootfsPath } from "./moltnetArtifactPaths.js";
 import { createMoltnetExternalParticipantArtifactFiles } from "./moltnetExternalParticipantArtifact.js";
 import { resolveMoltnetServerPlans } from "./moltnetServerPlans.js";
 const createServerKey = (networkId) => networkId;
-export const generateMoltnetArtifacts = async (plan) => {
+export const generateMoltnetArtifacts = async (plan, deploymentLineage = "compile") => {
     const teamNodes = plan.nodes
         .filter((node) => node.kind === "team")
         .filter((node) => (node.value.networks?.length ?? 0) > 0);
     if (teamNodes.length === 0) {
         return null;
     }
-    // Run-scoping key for every persistent volume name derived below (see
-    // createPersistentVolumeName's doc comment). Read once per compile so
-    // every mount in this compile agrees on the same value.
+    // Run-scoping key for the RUN-SCOPED mounts derived below — the causal
+    // event log and per-network Moltnet runtime state (see
+    // createPersistentVolumeName's doc comment). Read once per compile so every
+    // such mount in this compile agrees on the same value. Durable stores and
+    // token directories deliberately do NOT use it; see durableVolumeName.
     const runId = resolveNoopolisRunId(process.env);
+    /**
+     * Deployment-stable name for state that must be REATTACHED across a
+     * redeploy, never recreated empty: durable Moltnet `sqlite`/`json` stores
+     * and the open-mode agent token directories. An author-declared name
+     * (`server.store.persistence.name`) is honoured verbatim so an operator can
+     * pre-create or migrate the volume under that exact name; otherwise the
+     * name comes from the plan root plus the deployment lineage, exactly as
+     * durable memory banks are named (`memoryArtifacts.ts`'s
+     * `durableMemoryVolumeName`).
+     */
+    const durableVolumeName = (mountId, declaredName) => declaredName?.trim()
+        || createExclusiveReattachVolumeName(`${plan.root}\0${deploymentLineage}`, mountId);
     const serverPlans = resolveMoltnetServerPlans(plan, teamNodes);
     const nodePlans = [];
     const nodePlanKeys = new Set();
     const configFiles = [];
     const persistentMounts = new Map();
     const external = createMoltnetExternalParticipantArtifactFiles(plan.moltnetExternalParticipantIntents ?? []);
+    const receiptStoreOwners = new Map();
     configFiles.push(...external.files);
     const addPersistentMount = (mount) => {
         const existing = persistentMounts.get(mount.id);
@@ -31,7 +46,10 @@ export const generateMoltnetArtifacts = async (plan) => {
             persistentMounts.set(mount.id, mount);
             return;
         }
-        if (existing.mountPath !== mount.mountPath || existing.volumeName !== mount.volumeName) {
+        if (existing.mountPath !== mount.mountPath ||
+            existing.volumeName !== mount.volumeName ||
+            existing.lifecycle !== mount.lifecycle ||
+            existing.declaredVolumeName !== mount.declaredVolumeName) {
             throw new SpawnfileError("validation_error", `Moltnet persistent mount ${mount.id} resolves to conflicting targets`);
         }
     };
@@ -63,7 +81,7 @@ export const generateMoltnetArtifacts = async (plan) => {
             id: causalMountId,
             mountPath: createMoltnetCausalDirectory(serverPlan.configPath),
             reason: `managed Moltnet causal event log for ${serverPlan.networkId}`,
-            volumeName: createPersistentVolumeName(plan.root, causalMountId, undefined, runId)
+            volumeName: createPersistentVolumeName(plan.root, causalMountId, runId)
         });
         const storeMountPath = resolveMoltnetStorePersistenceMountPath(serverPlan.networkId, serverPlan.server.store);
         if (storeMountPath) {
@@ -73,10 +91,12 @@ export const generateMoltnetArtifacts = async (plan) => {
                 ? store.persistence?.name
                 : undefined;
             addPersistentMount({
+                ...(explicitVolumeName?.trim() ? { declaredVolumeName: explicitVolumeName.trim() } : {}),
                 id: mountId,
+                lifecycle: "exclusive-reattach",
                 mountPath: storeMountPath,
                 reason: `managed Moltnet ${serverPlan.server.store.kind} store for ${serverPlan.networkId}`,
-                volumeName: createPersistentVolumeName(plan.root, mountId, explicitVolumeName, runId)
+                volumeName: durableVolumeName(mountId, explicitVolumeName)
             });
         }
     }
@@ -110,6 +130,23 @@ export const generateMoltnetArtifacts = async (plan) => {
                 throw new SpawnfileError("validation_error", `Moltnet network ${attachment.network} disables direct messages but ${agentNode.name} declares dms`);
             }
             const configPath = createMoltnetNodeConfigPath(teamNode.slug, attachment.network, attachment.memberId);
+            const receiptStorePath = agentNode.runtime.name === "daimon"
+                ? createMoltnetDaimonReceiptStorePath(attachment.network, attachment.memberId)
+                : undefined;
+            if (receiptStorePath) {
+                const owner = `${attachment.network}\u0000${attachment.memberId}`;
+                const existingOwner = receiptStoreOwners.get(receiptStorePath);
+                if (existingOwner !== undefined && existingOwner !== owner) {
+                    throw new SpawnfileError("validation_error", "Daimon receipt-store paths collide");
+                }
+                receiptStoreOwners.set(receiptStorePath, owner);
+                const networkRoot = createMoltnetNetworkStateDirectory(attachment.network);
+                const covered = [...persistentMounts.values()].some((mount) => networkRoot === mount.mountPath || networkRoot.startsWith(`${mount.mountPath}/`));
+                if (!covered) {
+                    const mountId = `moltnet-${attachment.network}-runtime-state`;
+                    addPersistentMount({ id: mountId, mountPath: networkRoot, reason: `Moltnet runtime state for ${attachment.network}`, volumeName: createPersistentVolumeName(plan.root, mountId, runId) });
+                }
+            }
             const nodePlanKey = `${attachment.network}::${attachment.memberId}`;
             if (nodePlanKeys.has(nodePlanKey)) {
                 throw new SpawnfileError("validation_error", `Duplicate Moltnet node attachment for ${attachment.network}/${attachment.memberId}`);
@@ -124,9 +161,10 @@ export const generateMoltnetArtifacts = async (plan) => {
                     const mountId = `agent-${node.slug}-moltnet-tokens`;
                     addPersistentMount({
                         id: mountId,
+                        lifecycle: "exclusive-reattach",
                         mountPath: createMoltnetOpenTokenDirectory(node.slug),
                         reason: `Moltnet open-mode generated agent tokens for ${agentNode.name}`,
-                        volumeName: createPersistentVolumeName(plan.root, mountId, undefined, runId)
+                        volumeName: durableVolumeName(mountId)
                     });
                 }
             }
@@ -143,9 +181,10 @@ export const generateMoltnetArtifacts = async (plan) => {
                 const mountId = `agent-${node.slug}-moltnet-tokens`;
                 addPersistentMount({
                     id: mountId,
+                    lifecycle: "exclusive-reattach",
                     mountPath: createMoltnetOpenTokenDirectory(node.slug),
                     reason: `Moltnet open-mode generated agent tokens for ${agentNode.name}`,
-                    volumeName: createPersistentVolumeName(plan.root, mountId, undefined, runId)
+                    volumeName: durableVolumeName(mountId)
                 });
             }
             configFiles.push({
@@ -154,6 +193,7 @@ export const generateMoltnetArtifacts = async (plan) => {
                 path: configPath
             });
             nodePlans.push({
+                sourceNodeId: node.id,
                 configPath: toContainerRootfsPath(configPath),
                 ...(clientAuth.credentialAgentId
                     ? { credentialAgentId: clientAuth.credentialAgentId }
@@ -161,7 +201,8 @@ export const generateMoltnetArtifacts = async (plan) => {
                 ...(clientAuth.credentialId ? { credentialId: clientAuth.credentialId } : {}),
                 ...(clientAuth.tokenEnv ? { credentialSecret: clientAuth.tokenEnv } : {}),
                 memberId: attachment.memberId,
-                networkId: attachment.network
+                networkId: attachment.network,
+                ...(receiptStorePath ? { receiptStorePath } : {})
             });
         }
     }