spawnfile 0.1.14 → 0.1.17

package/dist/target/evidenceExport.d.ts

@@ -16,7 +16,9 @@ export interface EvidenceExportOperationsOptions {
     readonly context: unknown;
     readonly executor: DockerResourceExecutor;
     readonly exportExecutor: DockerEvidenceExportExecutor;
-    readonly helperArtifactBundle: unknown;
+    readonly helperArtifactBundle?: unknown;
+    /** Spawnfile-owned local config identity. Never a public provider field. */
+    readonly localHelper?: unknown;
     readonly helperArtifactManifestDigest: unknown;
     readonly helperArtifactContract: unknown;
     readonly artifactIdentityStore: DockerArtifactIdentityStore;

package/dist/target/evidenceExport.js

@@ -35,14 +35,21 @@ const options = (raw) => {
         return fail();
     const timeoutMs = typeof raw.timeoutMs === "number" ? raw.timeoutMs : 10_000;
     try {
+        if (typeof raw.helperArtifactManifestDigest !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(raw.helperArtifactManifestDigest) || raw.helperArtifactContract !== EVIDENCE_EXPORT_HELPER_CONTRACT)
+            return fail();
+        const source = raw.localHelper;
+        const localHelper = source === undefined ? undefined : createEvidenceExportHelper({ artifactManifestDigest: source.artifactManifestDigest, imageDigest: source.image_digest, imageReference: source.image_reference, resultHandle: source.result_handle });
+        if (localHelper) {
+            if (raw.helperArtifactBundle !== undefined || localHelper.artifactManifestDigest !== raw.helperArtifactManifestDigest)
+                return fail();
+            return { authorityStore: raw.authorityStore, context: raw.context, executor: raw.executor, exportExecutor: raw.exportExecutor, localHelper, helperArtifactManifestDigest: raw.helperArtifactManifestDigest, helperArtifactContract: EVIDENCE_EXPORT_HELPER_CONTRACT, artifactIdentityStore: raw.artifactIdentityStore, journal: raw.journal, signal: raw.signal, timeoutMs, testHooks: raw.testHooks };
+        }
         const rawBundle = raw.helperArtifactBundle;
         if (!rawBundle || typeof rawBundle !== "object" || Array.isArray(rawBundle) || Object.keys(rawBundle).sort().join("\0") !== "operation_handle\0request_digest\0result_handle")
             return fail();
         const bundle = rawBundle;
         const helperArtifactBundle = Object.freeze({ operationHandle: parseOpaqueTargetHandle(bundle.operation_handle), requestDigest: (() => { if (typeof bundle.request_digest !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(bundle.request_digest))
                 return fail(); return bundle.request_digest; })(), resultHandle: parseOpaqueTargetHandle(bundle.result_handle) });
-        if (typeof raw.helperArtifactManifestDigest !== "string" || !/^sha256:[a-f0-9]{64}$/u.test(raw.helperArtifactManifestDigest) || raw.helperArtifactContract !== EVIDENCE_EXPORT_HELPER_CONTRACT)
-            return fail();
         return { authorityStore: raw.authorityStore, context: raw.context, executor: raw.executor, exportExecutor: raw.exportExecutor, helperArtifactBundle, helperArtifactManifestDigest: raw.helperArtifactManifestDigest, helperArtifactContract: EVIDENCE_EXPORT_HELPER_CONTRACT, artifactIdentityStore: raw.artifactIdentityStore, journal: raw.journal, signal: raw.signal, timeoutMs, testHooks: raw.testHooks };
     }
     catch {
@@ -78,7 +85,9 @@ const inspectAuthority = async (authority, input) => {
         return fail();
 };
 const helperFor = async (value, input) => {
-    const bundle = input.helperArtifactBundle;
+    if (input.localHelper)
+        return input.localHelper;
+    const bundle = input.helperArtifactBundle ?? fail();
     const binding = await input.artifactIdentityStore.resolveOperation(bundle.operationHandle, bundle.requestDigest);
     const journal = await input.journal.read();
     const completed = binding ? await input.journal.resolveCompletedReceipt({ operationHandle: binding.operationHandle, requestDigest: binding.requestDigest }) : null;

package/dist/target/evidenceExportOperationsTestKit.js

@@ -1,7 +1,7 @@
 import { mkdtemp, realpath, rm } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { EVIDENCE_EXPORT_MOUNT, EVIDENCE_EXPORT_HELPER_CMD, EVIDENCE_EXPORT_HELPER_CONTRACT, EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL, EVIDENCE_EXPORT_HELPER_ENTRYPOINT, EVIDENCE_EXPORT_HELPER_USER, createEvidenceExportHelper, parseEvidenceVolumeAuthority } from "./evidenceExportProvider.js";
+import { EVIDENCE_EXPORT_MOUNT, EVIDENCE_EXPORT_HELPER_CMD, EVIDENCE_EXPORT_HELPER_CONTRACT, EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL, EVIDENCE_EXPORT_HELPER_ENTRYPOINT, EVIDENCE_EXPORT_HELPER_ENV, EVIDENCE_EXPORT_HELPER_USER, createEvidenceExportHelper, parseEvidenceVolumeAuthority } from "./evidenceExportProvider.js";
 import { createDockerArtifactSpec, initializeDockerArtifactIdentityStore } from "./dockerArtifactsProvider.js";
 import { initializeEvidenceExportAuthorityStore } from "./evidenceExportStore.js";
 import { createDockerResourceSpec } from "./dockerResourcesProvider.js";
@@ -92,7 +92,7 @@ export const runLifecycleExport = async (input = {}) => {
                 Entrypoint: EVIDENCE_EXPORT_HELPER_ENTRYPOINT,
                 Cmd: EVIDENCE_EXPORT_HELPER_CMD,
                 Labels: { [EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL]: "v1" },
-                Env: null,
+                Env: ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"],
                 ExposedPorts: null,
                 Healthcheck: null,
                 User: EVIDENCE_EXPORT_HELPER_USER,
@@ -268,7 +268,7 @@ export const helperProjection = (args, volumeName, imageLabels, mutate) => {
         Config: {
             Entrypoint: EVIDENCE_EXPORT_HELPER_ENTRYPOINT,
             Cmd: EVIDENCE_EXPORT_HELPER_CMD,
-            Env: null,
+            Env: EVIDENCE_EXPORT_HELPER_ENV,
             ExposedPorts: null,
             Healthcheck: null,
             Image: image,

package/dist/target/evidenceExportProvider.d.ts

@@ -6,6 +6,8 @@ export declare const EVIDENCE_EXPORT_HELPER_CONTRACT_VERSION: "v1";
 export declare const EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL: "spawnfile.target.evidence-export.helper-contract";
 export declare const EVIDENCE_EXPORT_HELPER_ENTRYPOINT: readonly string[];
 export declare const EVIDENCE_EXPORT_HELPER_CMD: readonly string[];
+export declare const EVIDENCE_EXPORT_HELPER_PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+export declare const EVIDENCE_EXPORT_HELPER_ENV: readonly string[];
 export declare const EVIDENCE_EXPORT_HELPER_USER: "65534:65534";
 export interface DockerEvidenceExportExecutor {
     (file: string, args: readonly string[], options: {

package/dist/target/evidenceExportProvider.js

@@ -10,6 +10,10 @@ export const EVIDENCE_EXPORT_HELPER_CONTRACT_VERSION = "v1";
 export const EVIDENCE_EXPORT_HELPER_CONTRACT_LABEL = "spawnfile.target.evidence-export.helper-contract";
 export const EVIDENCE_EXPORT_HELPER_ENTRYPOINT = Object.freeze(["/bin/spawnfile-export-helper"]);
 export const EVIDENCE_EXPORT_HELPER_CMD = Object.freeze([]);
+export const EVIDENCE_EXPORT_HELPER_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+export const EVIDENCE_EXPORT_HELPER_ENV = Object.freeze([
+    `PATH=${EVIDENCE_EXPORT_HELPER_PATH}`,
+]);
 export const EVIDENCE_EXPORT_HELPER_USER = "65534:65534";
 const DIGEST = /^sha256:[a-f0-9]{64}$/u;
 const NAME = /^spfe_[a-f0-9]{58}$/u;
@@ -37,8 +41,11 @@ const json = (raw) => { if (!utf8(raw))
 catch {
     return fail();
 } };
+const exactHelperEnv = (raw) => Array.isArray(raw)
+    && raw.length === 1 && raw[0] === EVIDENCE_EXPORT_HELPER_ENV[0];
 export const createEvidenceExportHelper = (raw) => {
-    if (typeof raw.artifactManifestDigest !== "string" || !DIGEST.test(raw.artifactManifestDigest) || typeof raw.imageDigest !== "string" || !DIGEST.test(raw.imageDigest) || typeof raw.imageReference !== "string" || !isImmutableDockerImageReference(raw.imageReference) || !raw.imageReference.endsWith(`@${raw.imageDigest}`))
+    const localConfig = raw.imageReference === raw.imageDigest;
+    if (typeof raw.artifactManifestDigest !== "string" || !DIGEST.test(raw.artifactManifestDigest) || typeof raw.imageDigest !== "string" || !DIGEST.test(raw.imageDigest) || typeof raw.imageReference !== "string" || !localConfig && (!isImmutableDockerImageReference(raw.imageReference) || !raw.imageReference.endsWith(`@${raw.imageDigest}`)))
         return fail();
     return Object.freeze({ artifactManifestDigest: raw.artifactManifestDigest, image_digest: raw.imageDigest, image_reference: raw.imageReference, result_handle: parseOpaqueTargetHandle(raw.resultHandle) });
 };
@@ -91,7 +98,8 @@ export const parseEvidenceExportImageInspection = (stdout, helper) => {
     if (!Array.isArray(value) || value.length !== 1 || !exact(value[0], ["Config", "RepoDigests"]))
         return fail();
     const image = value[0];
-    if (!Array.isArray(image.RepoDigests) || image.RepoDigests.length < 1 || image.RepoDigests.length > 32 || image.RepoDigests.some((value) => !isImmutableDockerImageReference(value)))
+    const localConfig = prepared.image_reference === prepared.image_digest;
+    if (!localConfig && (!Array.isArray(image.RepoDigests) || image.RepoDigests.length < 1 || image.RepoDigests.length > 32 || image.RepoDigests.some((value) => !isImmutableDockerImageReference(value))))
         return fail();
     if (!exact(image.Config, ["Cmd", "Entrypoint", "Env", "ExposedPorts", "Healthcheck", "Labels", "User", "Volumes"]))
         return fail();
@@ -105,9 +113,10 @@ export const parseEvidenceExportImageInspection = (stdout, helper) => {
         return fail();
     if (config.User !== EVIDENCE_EXPORT_HELPER_USER)
         return fail();
-    if (config.Env !== null || config.ExposedPorts !== null || config.Healthcheck !== null || config.Volumes !== null)
+    if (!exactHelperEnv(config.Env)
+        || config.ExposedPorts !== null || config.Healthcheck !== null || config.Volumes !== null)
         return fail();
-    if (!image.RepoDigests.includes(prepared.image_reference))
+    if (!localConfig && !image.RepoDigests.includes(prepared.image_reference))
         return fail();
     return { labels: Object.freeze({ ...labels }) };
 };
@@ -140,7 +149,8 @@ export const isExpectedEvidenceExportHelper = (stdout, spec) => {
         return item.Name === `/${spec.containerName}` && config.Image === spec.imageReference
             && JSON.stringify(config.Entrypoint) === JSON.stringify(EVIDENCE_EXPORT_HELPER_ENTRYPOINT)
             && (cmd === null || (Array.isArray(cmd) && cmd.length === 0))
-            && config.Env === null && config.ExposedPorts === null && config.Healthcheck === null && config.Volumes === null
+            && exactHelperEnv(config.Env)
+            && config.ExposedPorts === null && config.Healthcheck === null && config.Volumes === null
             && config.User === EVIDENCE_EXPORT_HELPER_USER
             && exact(config.Labels, Object.keys(expectedLabels))
             && Object.entries(expectedLabels).every(([key, value]) => config.Labels !== null && config.Labels[key] === value)

package/dist/target/publicArtifactSnapshot.d.ts

@@ -1,8 +1,10 @@
 import { z } from "zod";
 export declare const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_REQUEST_VERSION: "spawnfile.target-public-artifact-snapshot.request.v1";
 export declare const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION: "spawnfile.target-public-artifact-snapshot.v1";
+export declare const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION: "spawnfile.target-public-artifact-snapshot.not-present.v1";
 export declare const TARGET_PUBLIC_ARTIFACT_ROOT: "/tmp/spawnfile-public";
 export declare const MAX_TARGET_PUBLIC_ARTIFACT_BYTES = 131072;
+export declare const isTargetPublicArtifactPath: (value: unknown) => value is string;
 export declare const targetPublicArtifactSnapshotRequestSchema: z.ZodObject<{
     artifact: z.ZodObject<{
         id: z.ZodString;
@@ -29,13 +31,42 @@ export declare const targetPublicArtifactSnapshotSchema: z.ZodObject<{
     size_bytes: z.ZodNumber;
     version: z.ZodLiteral<"spawnfile.target-public-artifact-snapshot.v1">;
 }, z.core.$strict>;
+export declare const targetPublicArtifactSnapshotNotPresentSchema: z.ZodObject<{
+    artifact_id: z.ZodString;
+    request_digest: z.ZodString;
+    run_id: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").RunId, string>>;
+    status: z.ZodLiteral<"not_present">;
+    version: z.ZodLiteral<"spawnfile.target-public-artifact-snapshot.not-present.v1">;
+}, z.core.$strict>;
+export declare const targetPublicArtifactSnapshotResultSchema: z.ZodUnion<readonly [z.ZodObject<{
+    artifact_id: z.ZodString;
+    content_base64: z.ZodString;
+    content_digest: z.ZodString;
+    media_type: z.ZodString;
+    request_digest: z.ZodString;
+    run_id: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").RunId, string>>;
+    size_bytes: z.ZodNumber;
+    version: z.ZodLiteral<"spawnfile.target-public-artifact-snapshot.v1">;
+}, z.core.$strict>, z.ZodObject<{
+    artifact_id: z.ZodString;
+    request_digest: z.ZodString;
+    run_id: z.ZodPipe<z.ZodString, z.ZodTransform<import("./contracts.js").RunId, string>>;
+    status: z.ZodLiteral<"not_present">;
+    version: z.ZodLiteral<"spawnfile.target-public-artifact-snapshot.not-present.v1">;
+}, z.core.$strict>]>;
 export type TargetPublicArtifactSnapshotRequest = z.infer<typeof targetPublicArtifactSnapshotRequestSchema>;
 export type TargetPublicArtifactSnapshot = z.infer<typeof targetPublicArtifactSnapshotSchema>;
+export type TargetPublicArtifactSnapshotNotPresent = z.infer<typeof targetPublicArtifactSnapshotNotPresentSchema>;
+export type TargetPublicArtifactSnapshotResult = z.infer<typeof targetPublicArtifactSnapshotResultSchema>;
 export declare const parseTargetPublicArtifactSnapshotRequest: (raw: unknown) => TargetPublicArtifactSnapshotRequest;
 export declare const parseTargetPublicArtifactSnapshot: (raw: unknown) => TargetPublicArtifactSnapshot;
+export declare const parseTargetPublicArtifactSnapshotNotPresent: (raw: unknown) => TargetPublicArtifactSnapshotNotPresent;
+export declare const parseTargetPublicArtifactSnapshotResult: (raw: unknown) => TargetPublicArtifactSnapshotResult;
 export declare const createTargetPublicArtifactSnapshotRequestDigest: (raw: unknown) => `sha256:${string}`;
 export declare const createTargetPublicArtifactSnapshot: (input: {
     readonly content: Uint8Array;
     readonly request: TargetPublicArtifactSnapshotRequest;
 }) => TargetPublicArtifactSnapshot;
+export declare const createTargetPublicArtifactSnapshotNotPresent: (raw: unknown) => TargetPublicArtifactSnapshotNotPresent;
 export declare const createCanonicalTargetPublicArtifactSnapshotBytes: (raw: unknown) => string;
+export declare const createCanonicalTargetPublicArtifactSnapshotResultBytes: (raw: unknown) => string;

package/dist/target/publicArtifactSnapshot.js

@@ -5,6 +5,7 @@ import { z } from "zod";
 import { assertOrdinaryJsonGraph, opaqueTargetHandleSchema, runIdSchema, selectedTargetSchema } from "./contracts.js";
 export const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_REQUEST_VERSION = "spawnfile.target-public-artifact-snapshot.request.v1";
 export const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION = "spawnfile.target-public-artifact-snapshot.v1";
+export const TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION = "spawnfile.target-public-artifact-snapshot.not-present.v1";
 export const TARGET_PUBLIC_ARTIFACT_ROOT = "/tmp/spawnfile-public";
 export const MAX_TARGET_PUBLIC_ARTIFACT_BYTES = 131_072;
 const digestSchema = z.string().regex(/^sha256:[0-9a-f]{64}$/u);
@@ -12,10 +13,13 @@ const identifierSchema = z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/u);
 const mediaTypeSchema = z.string()
     .max(127)
     .regex(/^[a-z][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/u);
+const PUBLIC_ARTIFACT_PATH = /^\/tmp\/spawnfile-public\/[A-Za-z0-9][A-Za-z0-9._-]*$/u;
 const publicPathSchema = z.string().max(255)
-    .regex(/^\/tmp\/spawnfile-public\/[A-Za-z0-9][A-Za-z0-9._/-]*$/u)
-    .refine((value) => !value.includes("//") && !value.endsWith("/")
-    && !value.split("/").some((part) => part === "." || part === ".."));
+    // This is intentionally a direct child of the isolated public tmpfs.  A
+    // nested path would require a recursive openat-style resolver to keep every
+    // parent below the mount while an untrusted world is writing its output.
+    .regex(PUBLIC_ARTIFACT_PATH);
+export const isTargetPublicArtifactPath = (value) => typeof value === "string" && value.length <= 255 && PUBLIC_ARTIFACT_PATH.test(value);
 export const targetPublicArtifactSnapshotRequestSchema = z.object({
     artifact: z.object({
         id: identifierSchema,
@@ -53,6 +57,17 @@ export const targetPublicArtifactSnapshotSchema = z.object({
         context.addIssue({ code: z.ZodIssueCode.custom, message: "artifact content mismatch" });
     }
 });
+export const targetPublicArtifactSnapshotNotPresentSchema = z.object({
+    artifact_id: identifierSchema,
+    request_digest: digestSchema,
+    run_id: runIdSchema,
+    status: z.literal("not_present"),
+    version: z.literal(TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION)
+}).strict();
+export const targetPublicArtifactSnapshotResultSchema = z.union([
+    targetPublicArtifactSnapshotSchema,
+    targetPublicArtifactSnapshotNotPresentSchema
+]);
 const canonicalJsonValue = (value) => {
     if (Array.isArray(value))
         return `[${value.map(canonicalJsonValue).join(",")}]`;
@@ -126,6 +141,14 @@ export const parseTargetPublicArtifactSnapshot = (raw) => {
     assertOrdinaryPublicArtifactSnapshot(raw);
     return targetPublicArtifactSnapshotSchema.parse(raw);
 };
+export const parseTargetPublicArtifactSnapshotNotPresent = (raw) => {
+    assertOrdinaryPublicArtifactSnapshot(raw);
+    return targetPublicArtifactSnapshotNotPresentSchema.parse(raw);
+};
+export const parseTargetPublicArtifactSnapshotResult = (raw) => {
+    assertOrdinaryPublicArtifactSnapshot(raw);
+    return targetPublicArtifactSnapshotResultSchema.parse(raw);
+};
 export const createTargetPublicArtifactSnapshotRequestDigest = (raw) => `sha256:${createHash("sha256")
     .update("spawnfile.target-public-artifact-snapshot.request.v1\0", "utf8")
     .update(canonicalJson(parseTargetPublicArtifactSnapshotRequest(raw)), "utf8")
@@ -147,4 +170,15 @@ export const createTargetPublicArtifactSnapshot = (input) => {
         version: TARGET_PUBLIC_ARTIFACT_SNAPSHOT_VERSION
     });
 };
+export const createTargetPublicArtifactSnapshotNotPresent = (raw) => {
+    const request = parseTargetPublicArtifactSnapshotRequest(raw);
+    return parseTargetPublicArtifactSnapshotNotPresent({
+        artifact_id: request.artifact.id,
+        request_digest: createTargetPublicArtifactSnapshotRequestDigest(request),
+        run_id: request.run_id,
+        status: "not_present",
+        version: TARGET_PUBLIC_ARTIFACT_SNAPSHOT_NOT_PRESENT_VERSION
+    });
+};
 export const createCanonicalTargetPublicArtifactSnapshotBytes = (raw) => canonicalJsonValue(parseTargetPublicArtifactSnapshot(raw));
+export const createCanonicalTargetPublicArtifactSnapshotResultBytes = (raw) => canonicalJsonValue(parseTargetPublicArtifactSnapshotResult(raw));

package/examples/README.md

@@ -0,0 +1,45 @@
+# Example and Test Projects
+
+Authored Spawnfile inputs live in two top-level directories:
+
+- `examples/` — showcase org projects meant to be read as reference layouts.
+- `fixtures/` — test-only org projects (and `fixtures/support/` executable
+  test-support code).
+
+They exercise portable compiler contracts and opt-in runtime integration paths;
+product code must not contain fixture-specific behavior.
+
+## Showcase Examples (`examples/`)
+
+| Project | Contract |
+|---|---|
+| `single-agent` | Full agent workspace, docs, skills, MCP, secret, and OpenClaw lowering |
+| `agent-with-subagents` | Canonical subagent graph resolution |
+| `distribution-org` | Source-free image metadata, required/optional secrets, and managed Moltnet distribution |
+| `moltnet-team-chat` | Nested-team representatives communicating through parent and child Moltnet rooms |
+| `daimon-org` | One generated Daimon app with nested agents, shared files, and persistent Mneme recall |
+| `mixed-runtime-org` | Daimon, OpenClaw, and PicoClaw sharing Moltnet and Mneme wiring |
+| `jungian-daimon-org` | Nested council topology, representative routing, and scoped memory bindings |
+
+## Test-Only Fixtures (`fixtures/`)
+
+| Project | Contract |
+|---|---|
+| `multi-runtime-team` | Hierarchical team resolution and mixed runtime capability reporting |
+| `docker-auth-agent` | Single-runtime Docker auth injection |
+| `docker-auth-team` | Mixed OpenClaw/PicoClaw Docker auth injection |
+| `operational-smoke` | Scheduled PicoClaw wake, workspace volume, Moltnet, and live status |
+| `daimon-cli-memory-org` | Codex, Claude, Grok, and Agy CLI engines receiving schedule/dream memory context |
+| `lifecycle-smoke` | Minimal single-agent scripted lifecycle (`up`/`artifacts export`/`down`) receipt smoke |
+| `moltnet-memetics` | Live two-agent Moltnet conversation over real Codex/Grok |
+| `office-sim` | Standalone scripted-engine harness proving the pi adapter's `scripted` engine kind |
+
+Executable test-support helpers (cross-process fork fixtures and the trusted
+Moltnet release stager) live under `fixtures/support/`.
+
+Simulation worlds, transcripts, clocks, and domain-specific orchestration do not
+belong in this suite. They should consume Spawnfile as an external system and
+test their own behavior in their owning project.
+
+Generated output such as `.spawn/`, runtime logs, credentials, and run
+transcripts must remain untracked.

package/examples/agent-with-subagents/AGENTS.md

@@ -0,0 +1,3 @@
+# Operating Instructions
+
+Break work into research, critique, and final editing passes when helpful.

package/examples/agent-with-subagents/Spawnfile

@@ -0,0 +1,30 @@
+spawnfile_version: "0.1"
+kind: agent
+name: editor
+
+runtime:
+  name: picoclaw
+  options:
+    restrict_to_workspace: true
+
+execution:
+  model:
+    primary:
+      provider: openai
+      name: gpt-4o-mini
+  sandbox:
+    mode: workspace
+
+workspace:
+  docs:
+    system: AGENTS.md
+
+subagents:
+  - id: researcher
+    ref: ./subagents/researcher
+  - id: critic
+    ref: ./subagents/critic
+
+policy:
+  mode: warn
+  on_degrade: warn

package/examples/agent-with-subagents/subagents/critic/AGENTS.md

@@ -0,0 +1,3 @@
+# Critic
+
+Look for weak claims, missing evidence, and avoidable ambiguity.

package/examples/agent-with-subagents/subagents/critic/Spawnfile

@@ -0,0 +1,15 @@
+spawnfile_version: "0.1"
+kind: agent
+name: critic
+
+execution:
+  model:
+    primary:
+      provider: openai
+      name: gpt-4o-mini
+  sandbox:
+    mode: sandboxed
+
+workspace:
+  docs:
+    system: AGENTS.md

package/examples/agent-with-subagents/subagents/researcher/AGENTS.md

@@ -0,0 +1,3 @@
+# Researcher
+
+Gather relevant facts quickly and return structured notes instead of full prose.

package/examples/agent-with-subagents/subagents/researcher/Spawnfile

@@ -0,0 +1,17 @@
+spawnfile_version: "0.1"
+kind: agent
+name: researcher
+
+runtime: picoclaw
+
+execution:
+  model:
+    primary:
+      provider: openai
+      name: gpt-4o-mini
+  sandbox:
+    mode: workspace
+
+workspace:
+  docs:
+    system: AGENTS.md

package/examples/daimon-org/Spawnfile

@@ -0,0 +1,68 @@
+spawnfile_version: "0.1"
+kind: team
+name: daimon-org
+description: "Legacy generated-Pi organization fixture with Moltnet and shared resources"
+
+shared:
+  workspace:
+    docs:
+      system: TEAM.md
+    skills:
+      - ref: ./shared/skills/file-note
+    resources:
+      - id: shared-lab
+        kind: volume
+        mount: ./shared-lab
+        mode: mutable
+        sharing: team
+
+members:
+  - id: mapper
+    ref: ./agents/mapper
+  - id: review
+    ref: ./teams/review
+
+memory:
+  - id: shared-recall
+    access:
+      members: [mapper]
+    store:
+      kind: json
+      path: /var/lib/spawnfile/memory/daimon-org/shared-recall.jsonl
+      persistence:
+        mode: durable
+    index:
+      lexical:
+        enabled: true
+        engine: sqlite_fts
+      vector:
+        enabled: true
+        provider: ollama
+        model: qwen3-embedding:0.6b
+        dimensions: 1024
+
+mode: hierarchical
+lead: mapper
+
+networks:
+  - id: daimon_lab
+    name: Daimon Lab
+    provider: moltnet
+    server:
+      mode: managed
+      listen:
+        bind: 0.0.0.0
+        port: 19877
+      store:
+        kind: sqlite
+        path: /var/lib/spawnfile/moltnet/networks/daimon_lab/moltnet.sqlite
+      auth:
+        mode: open
+        public_read: true
+      human_ingress: true
+      direct_messages: false
+    rooms:
+      - id: lab-floor
+        members: [mapper, review]
+        visibility: public
+        write_policy: registered_agents

package/examples/daimon-org/TEAM.md

@@ -0,0 +1,4 @@
+# Daimon Org
+
+This legacy organization verifies that Spawnfile can compile multiple generated Pi agents and
+a nested team into one generated runtime app with shared resources and memory.

package/examples/daimon-org/agents/mapper/AGENTS.md

@@ -0,0 +1,4 @@
+# Mapper
+
+You are Mapper. Keep responses short and use the shared-lab resource when a
+scheduled prompt asks for it.

package/examples/daimon-org/agents/mapper/Spawnfile

@@ -0,0 +1,37 @@
+spawnfile_version: "0.1"
+kind: agent
+name: mapper
+description: "Maps shared workspace state for the Daimon org."
+
+runtime: pi
+
+execution:
+  model:
+    primary:
+      provider: openai
+      name: gpt-5.4-mini
+      auth:
+        method: codex
+  sandbox:
+    mode: workspace
+
+schedule:
+  kind: every
+  every: 1s
+  prompt: "Create ./shared-lab/mapper-note.md with one sentence proving mapper can write to the shared resource."
+
+surfaces:
+  moltnet:
+    - network: daimon_lab
+      rooms:
+        lab-floor:
+          wake: mentions
+
+workspace:
+  docs:
+    system: AGENTS.md
+  resources:
+    - id: mapper-scratch
+      kind: volume
+      mount: ./scratch
+      mode: mutable

package/examples/daimon-org/shared/skills/file-note/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: file-note
+description: "Create short markdown notes in requested workspace paths."
+---
+
+# File Note
+
+When asked to verify filesystem access, create a short markdown note in the
+requested path and mention the exact file path in the response.

package/examples/daimon-org/teams/review/Spawnfile

@@ -0,0 +1,53 @@
+spawnfile_version: "0.1"
+kind: team
+name: daimon-review-team
+description: "Nested review team for the legacy generated-Pi fixture"
+
+members:
+  - id: reviewer
+    ref: ./agents/reviewer
+
+memory:
+  - id: shared-recall
+    access:
+      members: [reviewer]
+    store:
+      kind: json
+      path: /var/lib/spawnfile/memory/daimon-org/shared-recall.jsonl
+      persistence:
+        mode: durable
+    index:
+      lexical:
+        enabled: true
+        engine: sqlite_fts
+      vector:
+        enabled: true
+        provider: ollama
+        model: qwen3-embedding:0.6b
+        dimensions: 1024
+
+mode: hierarchical
+lead: reviewer
+
+networks:
+  - id: daimon_lab
+    name: Daimon Lab
+    provider: moltnet
+    server:
+      mode: managed
+      listen:
+        bind: 0.0.0.0
+        port: 19877
+      store:
+        kind: sqlite
+        path: /var/lib/spawnfile/moltnet/networks/daimon_lab/moltnet.sqlite
+      auth:
+        mode: open
+        public_read: true
+      human_ingress: true
+      direct_messages: false
+    rooms:
+      - id: lab-floor
+        members: [reviewer]
+        visibility: public
+        write_policy: registered_agents

package/examples/daimon-org/teams/review/agents/reviewer/AGENTS.md

@@ -0,0 +1,4 @@
+# Reviewer
+
+You are Reviewer. Keep responses short and use the shared-lab resource when a
+scheduled prompt asks for it.

package/examples/daimon-org/teams/review/agents/reviewer/Spawnfile

@@ -0,0 +1,37 @@
+spawnfile_version: "0.1"
+kind: agent
+name: reviewer
+description: "Reviews generated shared workspace notes."
+
+runtime: pi
+
+execution:
+  model:
+    primary:
+      provider: openai
+      name: gpt-5.4-mini
+      auth:
+        method: codex
+  sandbox:
+    mode: workspace
+
+schedule:
+  kind: every
+  every: 1s
+  prompt: "Create ./shared-lab/reviewer-note.md with one sentence proving reviewer can write to the shared resource."
+
+surfaces:
+  moltnet:
+    - network: daimon_lab
+      rooms:
+        lab-floor:
+          wake: mentions
+
+workspace:
+  docs:
+    system: AGENTS.md
+  resources:
+    - id: reviewer-scratch
+      kind: volume
+      mount: ./scratch
+      mode: mutable

package/examples/daimon-public-host/AGENTS.md

@@ -0,0 +1,3 @@
+# Public Daimon Host
+
+Work only in this agent's workspace and return concise outcomes.

package/examples/daimon-public-host/Spawnfile

@@ -0,0 +1,21 @@
+spawnfile_version: "0.1"
+kind: agent
+name: public-host-agent
+description: "Minimal public Daimon organization-host fixture"
+
+runtime:
+  name: daimon
+  options:
+    engine: codex
+
+execution:
+  model:
+    primary:
+      provider: openai
+      name: gpt-5.4-mini
+      auth:
+        method: codex
+
+workspace:
+  docs:
+    system: AGENTS.md