feat: add canonical agent training and declarative container preparation

README.md

@@ -95,6 +95,7 @@ Portability is capability-specific: the compiler reports each feature as **suppo
 | Explore complete projects | [Examples](examples/) |
 | Add an adapter or contribute | [Contributing](CONTRIBUTING.md) |
 | Integrate with deployment tooling | [Target and lifecycle contracts](specs/TARGETS.md) |
+| Plan isolated agent training | [Paideia training handoff](specs/TRAINING.md) |
 | Find a detailed contract | [Specification index](specs/INDEX.md) |
 
 Spawnfile is part of [Noopolis](https://github.com/noopolis). [Moltnet](https://moltnet.dev) supplies messaging; [Daimon](https://github.com/noopolis/daimon) runs individual agents; [Simfile](https://simfile.org) builds simulation worlds around organizations. You can use Spawnfile on its own.

package.json

@@ -18,7 +18,7 @@
   },
   "scripts": {
     "compile:explicit-test-mcp": "node --experimental-strip-types scripts/compile-explicit-test-mcp.ts",
-    "build": "rm -rf dist && tsc --project tsconfig.build.json && chmod +x dist/cli/index.js && node --experimental-strip-types ./src/evidenceExportHelper/copyAssets.ts && node --experimental-strip-types ./src/runtime/copyScaffoldAssets.ts && node --experimental-strip-types ./src/deployment/native/copyArtifacts.ts",
+    "build": "rm -rf dist && tsc --project tsconfig.build.json && chmod +x dist/cli/index.js && node --experimental-strip-types ./src/evidenceExportHelper/copyAssets.ts && node --experimental-strip-types ./src/runtime/copyScaffoldAssets.ts && node --experimental-strip-types ./src/deployment/native/copyArtifacts.ts && node --experimental-strip-types ./src/compiler/training/preparation/copyAssets.ts",
     "build:native": "node --experimental-strip-types ./src/deployment/native/build.ts",
     "clean": "rm -rf coverage dist",
     "coverage": "vitest run --coverage",
@@ -81,5 +81,16 @@
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
   },
-  "packageManager": "pnpm@10.32.1+sha512.a706938f0e89ac1456b6563eab4edf1d1faf3368d1191fc5c59790e96dc918e4456ab2e67d613de1043d2e8c81f87303e6b40d4ffeca9df15ef1ad567348f2be"
+  "packageManager": "pnpm@10.32.1+sha512.a706938f0e89ac1456b6563eab4edf1d1faf3368d1191fc5c59790e96dc918e4456ab2e67d613de1043d2e8c81f87303e6b40d4ffeca9df15ef1ad567348f2be",
+  "exports": {
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.js"
+    },
+    "./*": "./*",
+    "./training": {
+      "types": "./dist/compiler/training/index.d.ts",
+      "import": "./dist/compiler/training/index.js"
+    }
+  }
 }

runtime-images/training/AGENTS.md

@@ -0,0 +1,11 @@
+# Training image
+
+Owns the single-container training dependency recipe. Spawnfile launches and
+stops the outer container; Paideia supervises experiments and native trial child
+processes inside it. No Docker socket or host home is mounted.
+
+Build inputs are explicit package distributions, locked dependency manifests,
+verified native executables and an installed integration entrypoint. Credentials,
+cases and results are runtime mounts, never image contents. Native runtime and
+Python base images must be immutable. Do not download unpinned CLI installers.
+The recipe is opt-in during incubation; no published runtime is implied.

runtime-images/training/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

runtime-images/training/Dockerfile

@@ -0,0 +1,51 @@
+ARG NATIVE_IMAGE
+ARG PYTHON_IMAGE
+FROM ${PYTHON_IMAGE} AS python
+FROM ${NATIVE_IMAGE} AS training
+
+# Both parents must use the same architecture and Debian release.
+COPY --from=python /usr/local /opt/python
+COPY --from=python /usr/lib/*-linux-gnu/libsqlite3.so.0* /opt/python/lib/
+# The bridge intentionally clears ambient environment variables. Register native
+# libraries in the image so Python extensions also load in that clean process.
+RUN echo /opt/python/lib > /etc/ld.so.conf.d/training-python.conf && ldconfig
+
+WORKDIR /opt/training/paideia
+COPY paideia/package.json paideia/package-lock.json ./
+RUN npm ci --omit=dev --omit=peer --ignore-scripts \
+ && mkdir -p node_modules/@noopolis \
+ && ln -s /opt/spawnfile/runtime-installs/daimon/node_modules/@noopolis/daimon node_modules/@noopolis/daimon
+
+WORKDIR /opt/training/spawnfile
+COPY spawnfile/package.json spawnfile/package-lock.json ./
+RUN npm ci --omit=dev --ignore-scripts
+
+COPY bridge /opt/training/paideia/bridges/dspy
+RUN /opt/python/bin/python3 -m venv /opt/training/paideia/bridges/dspy/.venv \
+ && /opt/training/paideia/bridges/dspy/.venv/bin/pip install --no-cache-dir -r /opt/training/paideia/bridges/dspy/requirements.lock \
+ && /opt/training/paideia/bridges/dspy/.venv/bin/pip install --no-cache-dir setuptools==80.9.0 \
+ && /opt/training/paideia/bridges/dspy/.venv/bin/pip install --no-deps --no-build-isolation -e /opt/training/paideia/bridges/dspy
+
+COPY claude/package.json claude/package-lock.json /opt/training/claude/
+RUN cd /opt/training/claude && npm ci --omit=dev
+COPY grok /opt/training/bin/grok
+
+COPY paideia/dist /opt/training/paideia/dist
+COPY spawnfile/dist /opt/training/spawnfile/dist
+COPY spawnfile/runtimes.yaml spawnfile/moltnet-releases.json /opt/training/spawnfile/
+COPY integration /opt/training/integration
+COPY bootstrap /opt/training/bootstrap
+COPY train /opt/training/bin/train
+RUN chmod 0555 /opt/training/bin/train /opt/training/bin/grok \
+ && chmod -R a+rX /opt/training/bootstrap /opt/training/integration \
+ && ln -s /opt/training/claude/node_modules/.bin/claude /opt/training/bin/claude \
+ && ln -s /opt/training/paideia/dist/src/cli/main.js /opt/training/bin/paideia \
+ && ln -s /opt/training/spawnfile/dist/cli/index.js /opt/training/bin/spawnfile \
+ && mkdir -p /opt/training/integration/node_modules/@noopolis \
+ && ln -s /opt/training/paideia /opt/training/integration/node_modules/@noopolis/paideia \
+ && ln -s /opt/training/spawnfile /opt/training/integration/node_modules/spawnfile \
+ && ln -s /opt/spawnfile/runtime-installs/daimon/node_modules/@noopolis/daimon /opt/training/integration/node_modules/@noopolis/daimon
+ENV PATH=/opt/training/bin:/opt/training/paideia/bridges/dspy/.venv/bin:/opt/spawnfile/runtime-installs/daimon/bin:/usr/local/bin:/usr/bin:/bin
+ENV HOME=/home/training
+WORKDIR /work
+ENTRYPOINT ["/opt/training/bin/train"]

specs/AGENTS.md

@@ -9,6 +9,8 @@ specs/
 ├── COMPILER.md              # Compiler architecture and internal contracts
 ├── CONTAINERS.md            # Container compilation spec
 ├── RUNTIMES.md              # Runtime registry, version pinning, adapter lifecycle
+├── TRAINING.md              # Canonical source handoff and Paideia CLI delegation
+├── TRAINING_CONTAINERS.md   # Single-container training launch boundary
 ├── CAUSAL.md                # Shared causal wire and Stele read/verify contract
 ├── ECOSYSTEM_RUNTIME_BOUNDARIES.md # Cross-project runtime authority and enforcement gates
 ├── USAGE_ACCOUNTING_DESIGN.md # Daimon turn-usage envelope and Spawnfile aggregation design

specs/INDEX.md

@@ -16,6 +16,8 @@ These are the source of truth. Implementation in `src/` must stay aligned with t
 | [SURFACES.md](SURFACES.md) | evolving | Communication surfaces — platform messaging, HTTP, webhook, runtime support matrix, and lowering notes |
 | [RUNTIMES.md](RUNTIMES.md) | evolving | Runtime registry model — version pinning, status tracking, adapter lifecycle |
 | [STATUS.md](STATUS.md) | evolving | Operational status — static and live status, deployment records, Docker targets, runtime probes, and Moltnet metadata-only diagnostics |
+| [TRAINING.md](TRAINING.md) | implemented handoff; native preparation integration required | Canonical agent selection and versioned Paideia delegation, dry-run and source provenance |
+| [TRAINING_CONTAINERS.md](TRAINING_CONTAINERS.md) | single-container launcher; end-to-end validation pending | Whole-experiment image, declared mounts, native auth staging and verified lifecycle |
 | [DISTRIBUTION.md](DISTRIBUTION.md) | evolving | Image distribution — self-describing images, sourceless run/status, deployment record v2, publish, registry drift, and the network binding contract |
 | [CAUSAL.md](CAUSAL.md) | evolving | Causal event envelope — producer wire rules plus the shared Stele read/verify and reconciliation contract |
 | [TARGETS.md](TARGETS.md) | evolving | Project-neutral target-resource public contracts and staged target-adapter boundary |

specs/SPEC.md

@@ -1749,6 +1749,7 @@ spawnfile model clear-fallbacks [path]
 spawnfile validate [path]
 spawnfile view [path]
 spawnfile compile [path] [--out <dir>]
+spawnfile train [path] [--agent <node-id>] --train <dataset> --test <dataset> --out <dir> [--dry-run]
 spawnfile status [path | <image-ref>] [--out <dir>] [--live] [--deployment <name>] [--image] [--pull] [--pull-check]
 spawnfile up [path | <image-ref>] [--out <dir>] [--auth-profile <name>] [--env-file <file>] [--detach] [--deployment <name>] [--context <name>] [--image] [--pull]
 spawnfile dev up [path] [--out <dir>] [--auth-profile <name>] [--env-file <file>] [--deployment <name>] [--context <name>]
@@ -1762,6 +1763,7 @@ spawnfile publish [path] --tag <image-ref> [--out <dir>]
 ```
 
 See `DISTRIBUTION.md` for `publish`, image-reference `up`/`status`, and the `--image`/`--pull`/`--pull-check` flags.
+See `TRAINING.md` for canonical source handoff, Paideia requirements and delegated training outcomes.
 
 ### Exit Codes
 
@@ -1772,6 +1774,7 @@ All commands share one convention:
 - `1` — runtime failure: a compile, build, Docker, or other operation that failed after input validation passed.
 
 Per-command notes below reference this convention rather than restating exit numbers.
+`train` preserves Paideia's completed failed-check exit 1 and cancellation exits 130/143; empty success receipts fail.
 
 #### `spawnfile init`