spawnfile 0.1.13 → 0.1.14

package/dist/compiler/moltnetArtifacts.js

@@ -1,25 +1,12 @@
+import { resolveNoopolisRunId } from "../runtime/index.js";
 import { SpawnfileError } from "../shared/index.js";
-import { createMoltnetOpenTokenDirectory, createMoltnetNativeServerConfig, createMoltnetNodeConfigPath, createMoltnetServerConfigPath, resolveMoltnetClientAuth, resolveMoltnetBaseUrl, resolveMoltnetStorePersistenceMountPath } from "./moltnetConfigLowering.js";
+import { createMoltnetCausalDirectory, createMoltnetServerConfigPath, createMoltnetOpenTokenDirectory, createMoltnetNativeServerConfig, createMoltnetNodeConfigPath, resolveMoltnetClientAuth, resolveMoltnetStorePersistenceMountPath } from "./moltnetConfigLowering.js";
 import { assertNetworkBindingEnvUniqueness } from "./networkBinding.js";
-import { listConcreteMoltnetRoomMemberIds } from "./moltnetRoomMemberships.js";
-import { assertCompatibleMoltnetNetworkName, assertCompatibleMoltnetRoomPolicy, assertCompatibleMoltnetServer } from "./moltnetRoomPolicyCompatibility.js";
 import { createMoltnetNodeConfigContent } from "./moltnetNodeConfig.js";
-import { createShortHash, slugify } from "./helpers.js";
-const DEFAULT_MOLTNET_PORT = 8787;
-const ROOTFS_PREFIX = "container/rootfs";
+import { createPersistentVolumeName, isNetworkHttpEnabled, toContainerRootfsPath } from "./moltnetArtifactPaths.js";
+import { createMoltnetExternalParticipantArtifactFiles } from "./moltnetExternalParticipantArtifact.js";
+import { resolveMoltnetServerPlans } from "./moltnetServerPlans.js";
 const createServerKey = (networkId) => networkId;
-const truncateSegment = (value, maxLength) => value.length > maxLength ? value.slice(0, maxLength).replace(/[-_.]+$/u, "") : value;
-const createPersistentVolumeName = (planRoot, id, explicitName) => {
-    if (explicitName && explicitName.trim().length > 0) {
-        return explicitName.trim();
-    }
-    const project = truncateSegment(slugify(planRoot.split("/").slice(-2, -1)[0] ?? "project") || "project", 32);
-    const suffix = truncateSegment(slugify(id) || "state", 48);
-    return `spawnfile-${project}-${suffix}-${createShortHash(`${planRoot}:${id}`)}`;
-};
-const toContainerRootfsPath = (rootfsPath) => `/${rootfsPath.replace(`${ROOTFS_PREFIX}/`, "")}`;
-const isNetworkHttpEnabled = (network) => network.server?.mode === "managed" && network.server.human_ingress === true;
-const resolveNetworkPort = (network, fallbackPort) => network.server?.mode === "managed" ? network.server.listen.port : fallbackPort;
 export const generateMoltnetArtifacts = async (plan) => {
     const teamNodes = plan.nodes
         .filter((node) => node.kind === "team")
@@ -27,80 +14,17 @@ export const generateMoltnetArtifacts = async (plan) => {
     if (teamNodes.length === 0) {
         return null;
     }
-    const serverPlans = new Map();
-    let nextPort = DEFAULT_MOLTNET_PORT;
-    for (const teamNode of teamNodes) {
-        for (const network of teamNode.value.networks ?? []) {
-            const server = network.server;
-            if (!server) {
-                throw new SpawnfileError("validation_error", `Moltnet network ${network.id} must declare server`);
-            }
-            const serverKey = createServerKey(network.id);
-            const existingPlan = serverPlans.get(serverKey);
-            if (existingPlan) {
-                if (existingPlan.baseUrl !== resolveMoltnetBaseUrl(server)) {
-                    throw new SpawnfileError("validation_error", `Duplicate Moltnet network ${network.id} declares conflicting server URL`);
-                }
-                assertCompatibleMoltnetNetworkName(network.id, existingPlan.name, network.name);
-                assertCompatibleMoltnetServer(network.id, existingPlan.server, server);
-                for (const room of network.rooms) {
-                    const concreteMembers = listConcreteMoltnetRoomMemberIds(plan, teamNode.value, network.id, room);
-                    const existingRoom = existingPlan.rooms.find((entry) => entry.id === room.id);
-                    if (existingRoom) {
-                        existingRoom.members = [
-                            ...new Set([...existingRoom.members, ...concreteMembers])
-                        ].sort();
-                        assertCompatibleMoltnetRoomPolicy(network.id, room.id, "visibility", existingRoom.visibility, room.visibility);
-                        assertCompatibleMoltnetRoomPolicy(network.id, room.id, "write_policy", existingRoom.write_policy, room.write_policy);
-                        existingRoom.visibility ??= room.visibility;
-                        existingRoom.write_policy ??= room.write_policy;
-                    }
-                    else {
-                        existingPlan.rooms.push({
-                            id: room.id,
-                            members: concreteMembers,
-                            ...(room.name ? { name: room.name } : {}),
-                            ...(room.visibility ? { visibility: room.visibility } : {}),
-                            ...(room.write_policy ? { write_policy: room.write_policy } : {})
-                        });
-                    }
-                }
-                existingPlan.rooms.sort((left, right) => left.id.localeCompare(right.id));
-            }
-            else {
-                const port = server.mode === "managed" ? resolveNetworkPort(network, nextPort) : undefined;
-                const serverId = `${teamNode.slug}-${network.id}`;
-                serverPlans.set(serverKey, {
-                    baseUrl: resolveMoltnetBaseUrl(server),
-                    ...(server.mode === "managed"
-                        ? { configPath: toContainerRootfsPath(createMoltnetServerConfigPath(serverId)) }
-                        : {}),
-                    id: serverId,
-                    mode: server.mode,
-                    name: network.name,
-                    networkId: network.id,
-                    ...(port ? { port } : {}),
-                    rooms: network.rooms.map((room) => ({
-                        id: room.id,
-                        members: listConcreteMoltnetRoomMemberIds(plan, teamNode.value, network.id, room),
-                        ...(room.name ? { name: room.name } : {}),
-                        ...(room.visibility ? { visibility: room.visibility } : {}),
-                        ...(room.write_policy ? { write_policy: room.write_policy } : {})
-                    })),
-                    server,
-                    secretPatches: [],
-                    teamSource: teamNode.value.source
-                });
-                if (port) {
-                    nextPort = Math.max(nextPort, port + 1);
-                }
-            }
-        }
-    }
+    // 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.
+    const runId = resolveNoopolisRunId(process.env);
+    const serverPlans = resolveMoltnetServerPlans(plan, teamNodes);
     const nodePlans = [];
     const nodePlanKeys = new Set();
     const configFiles = [];
     const persistentMounts = new Map();
+    const external = createMoltnetExternalParticipantArtifactFiles(plan.moltnetExternalParticipantIntents ?? []);
+    configFiles.push(...external.files);
     const addPersistentMount = (mount) => {
         const existing = persistentMounts.get(mount.id);
         if (!existing) {
@@ -127,18 +51,32 @@ export const generateMoltnetArtifacts = async (plan) => {
             mode: 0o600,
             path: createMoltnetServerConfigPath(serverPlan.id)
         });
+        // Always mounted, independent of the network's store.kind/persistence:
+        // this is the causal/social record (message.accepted/message.denied
+        // events), the A5/memetics ground truth for what happened in a run, and
+        // it must survive container teardown even for a purely in-memory
+        // (non-durable) room store — e.g. office-sim's fixture. Lives in its own
+        // `causal/` subdirectory, never the server config's own directory, so
+        // this volume never shadows a rebuilt image's Moltnet.json.
+        const causalMountId = `moltnet-${serverPlan.networkId}-causal`;
+        addPersistentMount({
+            id: causalMountId,
+            mountPath: createMoltnetCausalDirectory(serverPlan.configPath),
+            reason: `managed Moltnet causal event log for ${serverPlan.networkId}`,
+            volumeName: createPersistentVolumeName(plan.root, causalMountId, undefined, runId)
+        });
         const storeMountPath = resolveMoltnetStorePersistenceMountPath(serverPlan.networkId, serverPlan.server.store);
         if (storeMountPath) {
             const mountId = `moltnet-${serverPlan.networkId}-store`;
             const store = serverPlan.server.store;
-            const volumeName = store.kind === "sqlite" || store.kind === "json"
+            const explicitVolumeName = store.kind === "sqlite" || store.kind === "json"
                 ? store.persistence?.name
                 : undefined;
             addPersistentMount({
                 id: mountId,
                 mountPath: storeMountPath,
                 reason: `managed Moltnet ${serverPlan.server.store.kind} store for ${serverPlan.networkId}`,
-                volumeName: createPersistentVolumeName(plan.root, mountId, volumeName)
+                volumeName: createPersistentVolumeName(plan.root, mountId, explicitVolumeName, runId)
             });
         }
     }
@@ -166,12 +104,11 @@ export const generateMoltnetArtifacts = async (plan) => {
             if (!network) {
                 throw new SpawnfileError("validation_error", `Unable to find Moltnet network ${attachment.network} for ${agentNode.name}`);
             }
-            if (network.server?.mode === "managed" && network.server.direct_messages === false && attachment.dms) {
+            if (serverPlan.server.mode === "managed" &&
+                serverPlan.server.direct_messages === false &&
+                attachment.dms) {
                 throw new SpawnfileError("validation_error", `Moltnet network ${attachment.network} disables direct messages but ${agentNode.name} declares dms`);
             }
-            if (!network.server) {
-                throw new SpawnfileError("validation_error", `Moltnet network ${attachment.network} must declare server`);
-            }
             const configPath = createMoltnetNodeConfigPath(teamNode.slug, attachment.network, attachment.memberId);
             const nodePlanKey = `${attachment.network}::${attachment.memberId}`;
             if (nodePlanKeys.has(nodePlanKey)) {
@@ -179,7 +116,7 @@ export const generateMoltnetArtifacts = async (plan) => {
             }
             nodePlanKeys.add(nodePlanKey);
             if (agentNode.runtime.name === "pi") {
-                const clientAuth = resolveMoltnetClientAuth(serverPlan.server, attachment.network, attachment.memberId, node.slug);
+                const clientAuth = resolveMoltnetClientAuth(serverPlan.server, attachment.network, attachment.memberId, node.slug, attachment.auth?.tokenId);
                 const usesPerAttachmentOpenToken = clientAuth.mode === "open" &&
                     clientAuth.staticToken !== true &&
                     Boolean(clientAuth.tokenEnv || clientAuth.tokenPath);
@@ -189,7 +126,7 @@ export const generateMoltnetArtifacts = async (plan) => {
                         id: mountId,
                         mountPath: createMoltnetOpenTokenDirectory(node.slug),
                         reason: `Moltnet open-mode generated agent tokens for ${agentNode.name}`,
-                        volumeName: createPersistentVolumeName(plan.root, mountId)
+                        volumeName: createPersistentVolumeName(plan.root, mountId, undefined, runId)
                     });
                 }
             }
@@ -208,7 +145,7 @@ export const generateMoltnetArtifacts = async (plan) => {
                     id: mountId,
                     mountPath: createMoltnetOpenTokenDirectory(node.slug),
                     reason: `Moltnet open-mode generated agent tokens for ${agentNode.name}`,
-                    volumeName: createPersistentVolumeName(plan.root, mountId)
+                    volumeName: createPersistentVolumeName(plan.root, mountId, undefined, runId)
                 });
             }
             configFiles.push({
@@ -218,6 +155,12 @@ export const generateMoltnetArtifacts = async (plan) => {
             });
             nodePlans.push({
                 configPath: toContainerRootfsPath(configPath),
+                ...(clientAuth.credentialAgentId
+                    ? { credentialAgentId: clientAuth.credentialAgentId }
+                    : {}),
+                ...(clientAuth.credentialId ? { credentialId: clientAuth.credentialId } : {}),
+                ...(clientAuth.tokenEnv ? { credentialSecret: clientAuth.tokenEnv } : {}),
+                memberId: attachment.memberId,
                 networkId: attachment.network
             });
         }
@@ -229,6 +172,9 @@ export const generateMoltnetArtifacts = async (plan) => {
     })));
     return {
         files: configFiles,
+        ...(external.artifacts.length > 0
+            ? { externalParticipantArtifacts: external.artifacts }
+            : {}),
         nodePlans: nodePlans.sort((left, right) => left.configPath.localeCompare(right.configPath)),
         persistentMounts: [...persistentMounts.values()].sort((left, right) => left.id.localeCompare(right.id)),
         ports: [...new Set(managedServerPlans.map((serverPlan) => serverPlan.port).filter((port) => port !== undefined))].sort((left, right) => left - right),

package/dist/compiler/moltnetBinaries.d.ts

@@ -1,7 +1,24 @@
+import { type MoltnetTargetArchitecture } from "./moltnetReleaseAuthority.js";
+/** Explicit operator override for a locally staged, authority-bound release. */
+export declare const MOLTNET_RELEASE_DIR_ENV = "SPAWNFILE_MOLTNET_RELEASE_DIR";
 export declare const MOLTNET_BIN_DIRECTORY = "moltnet-bin";
 export declare const MOLTNET_BINARY_NAMES: readonly ["moltnet"];
-export type MoltnetTargetArchitecture = "amd64" | "arm64";
+export declare const MOLTNET_RELEASE_IDENTITY_VERSION: "spawnfile.moltnet-release-identity.v1";
+export declare const MOLTNET_RELEASE_STAMP_VERSION: "spawnfile.moltnet-release-stamp.v1";
+export type { MoltnetTargetArchitecture } from "./moltnetReleaseAuthority.js";
+export interface MoltnetReleaseIdentity {
+    readonly architecture: MoltnetTargetArchitecture;
+    readonly asset: string;
+    readonly asset_sha256: `sha256:${string}`;
+    readonly capabilities: readonly ["pi-bridge"];
+    readonly release_version: string;
+    readonly source_revision: string;
+    readonly version: typeof MOLTNET_RELEASE_IDENTITY_VERSION;
+}
+export interface MoltnetBinaryStageOptions {
+    readonly architecture?: MoltnetTargetArchitecture;
+    /** Explicit local source directory; bytes remain bound to trusted authority. */
+    readonly releaseDirectory?: string;
+}
 export declare const resolveMoltnetCliCommand: () => Promise<string>;
-export declare const stageMoltnetBinaries: (outputDirectory: string, options?: {
-    architecture?: MoltnetTargetArchitecture;
-}) => Promise<boolean>;
+export declare const stageMoltnetBinaries: (outputDirectory: string, options?: MoltnetBinaryStageOptions) => Promise<MoltnetReleaseIdentity>;

package/dist/compiler/moltnetBinaries.js

@@ -1,17 +1,25 @@
 import { execFile as execFileCallback } from "node:child_process";
+import { createHash } from "node:crypto";
 import path from "node:path";
-import { chmod } from "node:fs/promises";
+import { chmod, readFile } from "node:fs/promises";
 import { promisify } from "node:util";
 import { ensureDirectory, fileExists } from "../filesystem/index.js";
 import { SpawnfileError } from "../shared/index.js";
+import { parseTrustedMoltnetReleaseAuthority, readTrustedMoltnetReleaseAuthority, trustedMoltnetReleaseAsset } from "./moltnetReleaseAuthority.js";
+import { downloadTrustedMoltnetReleaseAsset } from "./moltnetReleaseDownload.js";
 const execFile = promisify(execFileCallback);
 const MOLTNET_CLI_ENV = "SPAWNFILE_MOLTNET_CLI";
-const MOLTNET_RELEASE_DIR_ENV = "SPAWNFILE_MOLTNET_RELEASE_DIR";
+/** Explicit operator override for a locally staged, authority-bound release. */
+export const MOLTNET_RELEASE_DIR_ENV = "SPAWNFILE_MOLTNET_RELEASE_DIR";
 const MOLTNET_TARGET_ARCH_ENV = "SPAWNFILE_MOLTNET_TARGET_ARCH";
-const LOCAL_MOLTNET_CLI_PATH = path.resolve(process.cwd(), "moltnet", "bin", "moltnet");
 const MOLTNET_TARGET_OS = "linux";
 export const MOLTNET_BIN_DIRECTORY = "moltnet-bin";
 export const MOLTNET_BINARY_NAMES = ["moltnet"];
+export const MOLTNET_RELEASE_IDENTITY_VERSION = "spawnfile.moltnet-release-identity.v1";
+export const MOLTNET_RELEASE_STAMP_VERSION = "spawnfile.moltnet-release-stamp.v1";
+const SHA256 = /^[a-f0-9]{64}$/u;
+const REVISION = /^[a-f0-9]{40}$/u;
+const PINNED_VERSION = /^v?\d+\.\d+\.\d+(?:-\d+-g[a-f0-9]{7,40})?$/u;
 const normalizeTargetArchitecture = (architecture) => {
     switch (architecture) {
         case "amd64":
@@ -43,6 +51,101 @@ const resolveTargetArchitecture = (architecture) => {
     }
 };
 const createReleaseAssetName = (architecture) => `moltnet_${MOLTNET_TARGET_OS}_${architecture}.tar.gz`;
+const createReleaseStampName = (architecture) => `moltnet_release_stamp_${architecture}.json`;
+const exactKeys = (value, keys) => Object.keys(value).sort().join("\0") === [...keys].sort().join("\0");
+const parseReleaseStamp = (raw, architecture) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new SpawnfileError("compile_error", "Moltnet release capability stamp is not valid JSON");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new SpawnfileError("compile_error", "Moltnet release capability stamp has an invalid shape");
+    }
+    const value = parsed;
+    const expectedKeys = [
+        "arch", "asset", "built_at", "capabilities", "pi_bridge", "sha256",
+        "source_revision", "stamp_version", "version"
+    ];
+    const capabilities = value.capabilities;
+    if (!exactKeys(value, expectedKeys)
+        || value.stamp_version !== MOLTNET_RELEASE_STAMP_VERSION
+        || value.arch !== architecture
+        || value.asset !== createReleaseAssetName(architecture)
+        || typeof value.built_at !== "string"
+        || !Number.isFinite(Date.parse(value.built_at))
+        || !Array.isArray(capabilities)
+        || capabilities.length !== 1
+        || capabilities[0] !== "pi-bridge"
+        || value.pi_bridge !== true
+        || typeof value.sha256 !== "string"
+        || !SHA256.test(value.sha256)
+        || typeof value.source_revision !== "string"
+        || !REVISION.test(value.source_revision)
+        || typeof value.version !== "string"
+        || !PINNED_VERSION.test(value.version)) {
+        throw new SpawnfileError("compile_error", `Moltnet release capability stamp must be strict, pinned, and assert only the pi-bridge capability for ${architecture}`);
+    }
+    const describedRevision = value.version.match(/-g([a-f0-9]{7,40})$/u)?.[1];
+    if (describedRevision && !value.source_revision.startsWith(describedRevision)) {
+        throw new SpawnfileError("compile_error", "Moltnet release version does not match its source revision");
+    }
+    return value;
+};
+const verifyReleaseIdentity = async (releaseDirectory, architecture, authority) => {
+    const trustedAuthority = parseTrustedMoltnetReleaseAuthority(authority);
+    const trustedAsset = trustedMoltnetReleaseAsset(trustedAuthority, architecture);
+    const asset = createReleaseAssetName(architecture);
+    const assetPath = path.join(releaseDirectory, asset);
+    const stampPath = path.join(releaseDirectory, createReleaseStampName(architecture));
+    if (!(await fileExists(assetPath))) {
+        throw new SpawnfileError("compile_error", `Moltnet release asset ${assetPath} does not exist`);
+    }
+    if (!(await fileExists(stampPath))) {
+        throw new SpawnfileError("compile_error", `Moltnet release asset ${asset} has no required capability stamp ${stampPath}`);
+    }
+    const stamp = parseReleaseStamp((await readFile(stampPath)).toString("utf8"), architecture);
+    const sha256 = createHash("sha256").update(await readFile(assetPath)).digest("hex");
+    if (stamp.sha256 !== sha256) {
+        throw new SpawnfileError("compile_error", `Moltnet release stamp sha256 does not match ${asset} (stale or tampered artifact)`);
+    }
+    if (stamp.version !== trustedAuthority.release_version
+        || stamp.source_revision !== trustedAuthority.source_revision
+        || stamp.asset !== trustedAsset.asset
+        || `sha256:${sha256}` !== trustedAsset.asset_sha256) {
+        throw new SpawnfileError("compile_error", `Moltnet release stamp and asset do not match trusted pinned authority for ${architecture}`);
+    }
+    return Object.freeze({
+        architecture,
+        asset,
+        asset_sha256: `sha256:${sha256}`,
+        capabilities: Object.freeze(["pi-bridge"]),
+        release_version: stamp.version,
+        source_revision: stamp.source_revision,
+        version: MOLTNET_RELEASE_IDENTITY_VERSION
+    });
+};
+const stageMoltnetReleaseAsset = async (outputDirectory, releaseAssetPath, identity) => {
+    const installDirectory = path.join(outputDirectory, MOLTNET_BIN_DIRECTORY);
+    await ensureDirectory(installDirectory);
+    try {
+        await execFile("tar", ["-C", installDirectory, "-xzf", releaseAssetPath]);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new SpawnfileError("compile_error", `Unable to extract Moltnet release asset ${releaseAssetPath}: ${reason}`);
+    }
+    for (const binaryName of MOLTNET_BINARY_NAMES) {
+        const binaryPath = path.join(installDirectory, binaryName);
+        if (!(await fileExists(binaryPath))) {
+            throw new SpawnfileError("compile_error", `Moltnet release asset ${releaseAssetPath} did not contain ${binaryName}`);
+        }
+        await chmod(binaryPath, 0o755);
+    }
+    return identity;
+};
 const isCommandNotFoundError = (error) => typeof error === "object" &&
     error !== null &&
     "code" in error &&
@@ -89,36 +192,40 @@ export const resolveMoltnetCliCommand = async () => {
     if (pathCli) {
         return pathCli;
     }
-    if (await fileExists(LOCAL_MOLTNET_CLI_PATH)) {
-        return validateMoltnetCli(LOCAL_MOLTNET_CLI_PATH, LOCAL_MOLTNET_CLI_PATH);
-    }
     return validateMoltnetCli("moltnet", "PATH");
 };
-export const stageMoltnetBinaries = async (outputDirectory, options = {}) => {
-    const releaseDirectory = await resolveConfiguredReleaseDirectory();
-    if (!releaseDirectory) {
-        return false;
+const stageMoltnetBinariesAtReleaseDirectory = async (outputDirectory, releaseDirectory, options = {}) => {
+    if (!path.isAbsolute(releaseDirectory) || !(await fileExists(releaseDirectory))) {
+        throw new SpawnfileError("compile_error", "Trusted Moltnet release directory is invalid");
     }
     const architecture = resolveTargetArchitecture(options.architecture);
+    const authority = await readTrustedMoltnetReleaseAuthority();
+    const identity = await verifyReleaseIdentity(releaseDirectory, architecture, authority);
     const releaseAssetPath = path.join(releaseDirectory, createReleaseAssetName(architecture));
-    if (!(await fileExists(releaseAssetPath))) {
-        throw new SpawnfileError("compile_error", `Moltnet release asset ${releaseAssetPath} does not exist. Build it with \`cd moltnet && make release-assets\` or set ${MOLTNET_RELEASE_DIR_ENV}.`);
+    return stageMoltnetReleaseAsset(outputDirectory, releaseAssetPath, identity);
+};
+export const stageMoltnetBinaries = async (outputDirectory, options = {}) => {
+    const releaseDirectory = options.releaseDirectory
+        ?? await resolveConfiguredReleaseDirectory();
+    if (releaseDirectory) {
+        return stageMoltnetBinariesAtReleaseDirectory(outputDirectory, releaseDirectory, { architecture: options.architecture });
     }
-    const installDirectory = path.join(outputDirectory, MOLTNET_BIN_DIRECTORY);
-    await ensureDirectory(installDirectory);
+    const architecture = resolveTargetArchitecture(options.architecture);
+    const authority = await readTrustedMoltnetReleaseAuthority();
+    const trustedAsset = trustedMoltnetReleaseAsset(authority, architecture);
+    const downloaded = await downloadTrustedMoltnetReleaseAsset(authority, architecture);
     try {
-        await execFile("tar", ["-C", installDirectory, "-xzf", releaseAssetPath]);
-    }
-    catch (error) {
-        const reason = error instanceof Error ? error.message : String(error);
-        throw new SpawnfileError("compile_error", `Unable to extract Moltnet release asset ${releaseAssetPath}: ${reason}`);
-    }
-    for (const binaryName of MOLTNET_BINARY_NAMES) {
-        const binaryPath = path.join(installDirectory, binaryName);
-        if (!(await fileExists(binaryPath))) {
-            throw new SpawnfileError("compile_error", `Moltnet release asset ${releaseAssetPath} did not contain ${binaryName}`);
-        }
-        await chmod(binaryPath, 0o755);
+        return await stageMoltnetReleaseAsset(outputDirectory, downloaded.assetPath, Object.freeze({
+            architecture,
+            asset: trustedAsset.asset,
+            asset_sha256: trustedAsset.asset_sha256,
+            capabilities: Object.freeze(["pi-bridge"]),
+            release_version: authority.release_version,
+            source_revision: authority.source_revision,
+            version: MOLTNET_RELEASE_IDENTITY_VERSION
+        }));
+    }
+    finally {
+        await downloaded.cleanup();
     }
-    return true;
 };

package/dist/compiler/moltnetClientConfig.js

@@ -24,7 +24,7 @@ const createAttachmentConfig = (node, artifacts, attachment, agentSlug) => {
         throw new SpawnfileError("compile_error", `Moltnet client config requires a resolved member id for ${node.name}`);
     }
     const serverPlan = findServerPlan(artifacts, attachment);
-    const auth = resolveMoltnetClientAuth(serverPlan.server, attachment.network, attachment.memberId, agentSlug);
+    const auth = resolveMoltnetClientAuth(serverPlan.server, attachment.network, attachment.memberId, agentSlug, attachment.auth?.tokenId);
     return {
         agent_name: node.name,
         auth: {
@@ -38,7 +38,12 @@ const createAttachmentConfig = (node, artifacts, attachment, agentSlug) => {
             ? {
                 dms: {
                     enabled: attachment.dms.enabled,
-                    ...(attachment.dms.wake ? { wake: attachment.dms.wake } : {})
+                    ...(attachment.dms.wake ? { wake: attachment.dms.wake } : {}),
+                    ...(attachment.dms.allowedWakeSenders !== undefined
+                        ? {
+                            allowed_wake_senders: [...attachment.dms.allowedWakeSenders]
+                        }
+                        : {})
                 }
             }
             : {}),

package/dist/compiler/moltnetConfigLowering.d.ts

@@ -4,6 +4,8 @@ export interface MoltnetSecretPatch {
     jsonPath: string;
 }
 export interface MoltnetClientAuthPlan {
+    credentialAgentId?: string;
+    credentialId?: string;
     mode: "bearer" | "none" | "open";
     registration?: "disabled" | "open" | "token";
     staticToken?: boolean;
@@ -35,12 +37,25 @@ export declare const createDefaultMoltnetStorePath: (networkId: string, kind: "j
 export declare const resolveMoltnetStorePath: (networkId: string, store: ManagedMoltnetStore) => string | null;
 export declare const resolveMoltnetStorePersistenceMountPath: (networkId: string, store: ManagedMoltnetStore) => string | null;
 export declare const createMoltnetServerConfigPath: (serverId: string) => string;
+/**
+ * Dedicated causal-log subdirectory, a SIBLING of (never the same directory
+ * as) the server's own Moltnet.json config file. Deliberately kept separate
+ * so a persistent volume mounted here (to survive container teardown/
+ * restart, see moltnetArtifacts.ts's causal persistent mount) never masks a
+ * rebuilt image's freshly-baked Moltnet.json — which carries secrets
+ * patched in at container start via secretPatches — with a stale copy left
+ * over in a prior run's volume. Takes the already-container-absolute
+ * `configPath` (MoltnetServerPlan.configPath, post toContainerRootfsPath),
+ * not the rootfs-prefixed emit path.
+ */
+export declare const createMoltnetCausalDirectory: (configPath: string) => string;
+export declare const createMoltnetCausalEventsPath: (configPath: string) => string;
 export declare const createMoltnetNodeConfigPath: (teamSlug: string, networkId: string, agentId: string) => string;
 export declare const renderMoltnetListenAddr: (server: Extract<TeamNetworkServer, {
     mode: "managed";
 }>) => string;
 export declare const resolveMoltnetBaseUrl: (server: TeamNetworkServer) => string;
-export declare const resolveMoltnetClientAuth: (server: TeamNetworkServer, networkId: string, memberId: string, agentSlug?: string) => MoltnetClientAuthPlan;
+export declare const resolveMoltnetClientAuth: (server: TeamNetworkServer, networkId: string, memberId: string, agentSlug?: string, attachmentTokenId?: string) => MoltnetClientAuthPlan;
 export declare const createMoltnetNativeServerConfig: ({ networkId, networkName, rooms, server }: MoltnetNativeServerConfigInput) => {
     config: Record<string, unknown>;
     secretPatches: MoltnetSecretPatch[];

package/dist/compiler/moltnetConfigLowering.js

@@ -1,3 +1,4 @@
+import { SpawnfileError } from "../shared/index.js";
 const pathSafeSegment = (value) => value.replace(/[^A-Za-z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "") || "item";
 const isIpv6Literal = (value) => value.includes(":");
 const normalizePosixPath = (value) => value.replace(/\/+/g, "/").replace(/\/+$/u, "") || "/";
@@ -30,6 +31,19 @@ export const resolveMoltnetStorePersistenceMountPath = (networkId, store) => {
     return storePath ? storePath.slice(0, storePath.lastIndexOf("/")) || "/" : null;
 };
 export const createMoltnetServerConfigPath = (serverId) => `container/rootfs/var/lib/spawnfile/moltnet/servers/${pathSafeSegment(serverId)}/Moltnet.json`;
+/**
+ * Dedicated causal-log subdirectory, a SIBLING of (never the same directory
+ * as) the server's own Moltnet.json config file. Deliberately kept separate
+ * so a persistent volume mounted here (to survive container teardown/
+ * restart, see moltnetArtifacts.ts's causal persistent mount) never masks a
+ * rebuilt image's freshly-baked Moltnet.json — which carries secrets
+ * patched in at container start via secretPatches — with a stale copy left
+ * over in a prior run's volume. Takes the already-container-absolute
+ * `configPath` (MoltnetServerPlan.configPath, post toContainerRootfsPath),
+ * not the rootfs-prefixed emit path.
+ */
+export const createMoltnetCausalDirectory = (configPath) => `${configPath.slice(0, configPath.lastIndexOf("/")) || "/"}/causal`;
+export const createMoltnetCausalEventsPath = (configPath) => `${createMoltnetCausalDirectory(configPath)}/causal.jsonl`;
 export const createMoltnetNodeConfigPath = (teamSlug, networkId, agentId) => `container/rootfs/var/lib/spawnfile/moltnet/nodes/${pathSafeSegment(teamSlug)}-${pathSafeSegment(networkId)}-${pathSafeSegment(agentId)}.json`;
 export const renderMoltnetListenAddr = (server) => {
     const bind = server.listen.bind;
@@ -50,10 +64,41 @@ export const resolveMoltnetBaseUrl = (server) => {
             : bind;
     return `http://${host}:${server.listen.port}`;
 };
-export const resolveMoltnetClientAuth = (server, networkId, memberId, agentSlug) => {
+export const resolveMoltnetClientAuth = (server, networkId, memberId, agentSlug, attachmentTokenId) => {
     if (server.auth.mode === "none") {
+        if (attachmentTokenId !== undefined) {
+            throw new SpawnfileError("validation_error", `Moltnet attachment ${networkId}/${memberId} cannot select token ${attachmentTokenId} when auth.mode is none`);
+        }
         return { mode: "none" };
     }
+    if (attachmentTokenId !== undefined) {
+        if (server.mode !== "managed" || server.auth.mode !== "bearer") {
+            throw new SpawnfileError("validation_error", `invalid Moltnet actor token ${attachmentTokenId} for ${memberId}: token_id is supported only for managed bearer servers`);
+        }
+        const tokens = server.auth.tokens?.filter((candidate) => candidate.id === attachmentTokenId) ?? [];
+        const token = tokens[0];
+        if (tokens.length === 0 || !token) {
+            throw new SpawnfileError("validation_error", `invalid Moltnet actor token ${attachmentTokenId} for ${memberId}: attachment ${networkId}/${memberId} references unknown token ${attachmentTokenId}`);
+        }
+        if (tokens.length !== 1) {
+            throw new SpawnfileError("validation_error", `invalid Moltnet actor token ${attachmentTokenId} for ${memberId}: token id must exist exactly once`);
+        }
+        if (token.scopes.length !== 2
+            || token.scopes[0] !== "attach"
+            || token.scopes[1] !== "write") {
+            throw new SpawnfileError("validation_error", `invalid Moltnet actor token ${attachmentTokenId} for ${memberId}: token must include attach and write scopes exactly`);
+        }
+        if (token.agents?.length !== 1 || token.agents[0] !== memberId) {
+            throw new SpawnfileError("validation_error", `invalid Moltnet actor token ${attachmentTokenId} for ${memberId}: token must declare exactly agents: [${memberId}]`);
+        }
+        return {
+            credentialAgentId: memberId,
+            credentialId: token.id,
+            mode: "bearer",
+            ...(server.auth.agent_registration ? { registration: server.auth.agent_registration } : {}),
+            tokenEnv: token.secret
+        };
+    }
     const client = server.auth.client;
     const registrationOpen = server.auth.mode === "open" || server.auth.agent_registration === "open";
     if (registrationOpen && !client) {
@@ -69,11 +114,28 @@ export const resolveMoltnetClientAuth = (server, networkId, memberId, agentSlug)
             ...(server.auth.agent_registration ? { registration: server.auth.agent_registration } : {})
         };
     }
-    const tokenEnv = client.token_env
-        ?? (client.token_id && server.mode === "managed"
-            ? server.auth.tokens?.find((token) => token.id === client.token_id)?.secret
-            : undefined);
+    const selectedManagedToken = client.token_id && server.mode === "managed"
+        ? server.auth.tokens?.find((token) => token.id === client.token_id)
+        : undefined;
+    if (server.mode === "managed"
+        && server.auth.mode === "bearer"
+        && selectedManagedToken
+        && (!selectedManagedToken.scopes.includes("attach")
+            || !selectedManagedToken.scopes.includes("write"))) {
+        throw new SpawnfileError("validation_error", `Moltnet attachment ${networkId}/${memberId} must select its own attach+write token; auth.client token ${selectedManagedToken.id} is operator-only`);
+    }
+    if (selectedManagedToken
+        && (selectedManagedToken.agents?.length ?? 0) > 0
+        && !selectedManagedToken.agents?.includes(memberId)) {
+        throw new SpawnfileError("validation_error", `Moltnet attachment ${networkId}/${memberId} is not allowed by auth.client token ${selectedManagedToken.id}`);
+    }
+    const tokenEnv = client.token_env ?? selectedManagedToken?.secret;
+    const selectedAgents = selectedManagedToken
+        ? [...new Set((selectedManagedToken.agents ?? []).map((agent) => agent.trim()))].filter(Boolean)
+        : [];
     return {
+        ...(selectedAgents.length === 1 ? { credentialAgentId: selectedAgents[0] } : {}),
+        ...(client.token_id ? { credentialId: client.token_id } : {}),
         mode: server.auth.mode,
         ...(server.auth.agent_registration ? { registration: server.auth.agent_registration } : {}),
         ...(client.static_token ? { staticToken: true } : {}),

package/dist/compiler/moltnetExternalParticipantArtifact.d.ts

@@ -0,0 +1,38 @@
+import type { ResolvedExternalParticipant } from "./organizationIdentity.js";
+import type { EmittedFile } from "../runtime/index.js";
+import type { MoltnetExternalParticipantIntent } from "./types.js";
+export declare const MOLTNET_EXTERNAL_PARTICIPANT_ARTIFACT_VERSION: "spawnfile.moltnet-external-participant.v1";
+export interface MoltnetExternalParticipantArtifactV1 {
+    readonly version: typeof MOLTNET_EXTERNAL_PARTICIPANT_ARTIFACT_VERSION;
+    readonly participant: {
+        readonly authored_key: string;
+        readonly kind: "service";
+        readonly member_id: string;
+        readonly principal_id: string;
+    };
+    readonly network: {
+        readonly id: string;
+    };
+    readonly auth: {
+        readonly mode: "bearer";
+        readonly token_id: string;
+        readonly token_env: string;
+    };
+    readonly direct_messages: readonly {
+        readonly members: readonly [string, string];
+    }[];
+}
+export interface BuildMoltnetExternalParticipantArtifactInput {
+    readonly participant: ResolvedExternalParticipant;
+    readonly networkId: string;
+    readonly tokenId: string;
+    readonly tokenEnv: string;
+    readonly directMessagePeers: readonly string[];
+}
+export declare const buildMoltnetExternalParticipantArtifact: (input: BuildMoltnetExternalParticipantArtifactInput) => MoltnetExternalParticipantArtifactV1;
+export declare const parseMoltnetExternalParticipantArtifact: (raw: unknown) => MoltnetExternalParticipantArtifactV1;
+export declare const renderMoltnetExternalParticipantArtifact: (artifact: MoltnetExternalParticipantArtifactV1) => string;
+export declare const createMoltnetExternalParticipantArtifactFiles: (intents: readonly MoltnetExternalParticipantIntent[]) => {
+    artifacts: MoltnetExternalParticipantArtifactV1[];
+    files: EmittedFile[];
+};