reliquary/docs/workpad/goals/headless-forks.md

Goal: Trained implementer, forked per block — headless forks inside Spire (version TBD)

Set: 2026-10-16, Igor session 2026-10-15-21-grotto-work Relates to: lean-athanor-0.2.1 — its "Trunk and forks is tested, not assumed" criterion. This goal restores the user's original shape, which 0.2.0 lost (see provenance report below). Inputs:

• Athanor trunk/fork provenance
• Headless fork sessions: mechanics + follow-up
• Spire vs. superpowers experiment, §5 (accounting gaps, inline blocks)

Intent (user, 2026-10-15/16)

The Athanor learns plans, design and implementer reports, not code. For hard work it trains one implementer early with background information, then forks that implementer once per block or subsection. The forks need only a small "you are continuing" brief. Bookkeeping (cache lifetime, which base is warm, tokens) is deterministic, done by a tool and not by agent attention. Solve it inside Spire now, without waiting for Dirigent. A Dirigent harness or MCP tool can come later and take this over.

Success criteria

Mechanism

• Spire ships a small deterministic helper (a script in the skill; MCP is a later option) that owns the claude -p command line. It covers: train a base, fork the base with a brief, update the base, report usage, and list or expire bases.
• Each base is stored with its full launch fingerprint: binary path, full model id, flags, permission mode and tools, cwd, agent file. Every fork reuses that fingerprint exactly, because any difference loses the prompt cache (research F-table).
• The environment is scrubbed of Desktop-host variables before launch; auth works without --bare or with an explicit key (user's choice).
• Per call, the helper returns the real model (modelUsage, not the init event), the tokens per usage column, and the per-fork delta cost. It writes them to the run log, so per-block cost is known, including for work the Athanor would previously have done inline.

Bookkeeping

• The registry records the last cache hit per base. "Keep warm / let expire / re-train" is computed from the cache lifetime (1 h on a subscription within plan usage, otherwise 5 min; a hit resets it) and the base's training cost. It is not left to the agent's judgment.

Process

• The Athanor procedure (athanor.md, implementation SKILL.md) describes the trained-implementer shape. In it, the Athanor holds the plan, design, trunk notes and reports, and does not read code itself.
• Forks don't see each other's work. The procedure says who keeps the base current: re-basing it with a summary of what changed between blocks, or a delta brief for each fork. It also says when each applies.
• A project agent file can specialize the trained implementer (--agent / --agents).
• The spawning reference gets the verified rows from today's research (Agent-tool fork copies the caller only; forks can't fork; fork mode makes everything background; headless fork mechanics; nested-process depth is per process and fails silently).

Proven, not assumed

• Trial on a real multi-block plan comparing the trained-implementer forks against the current shape on quality, tokens (all four columns, priced) and wall time, with every orchestrator counted, including the root.

Open decisions (user)

• Where the helper lives: the implementation skill (assumed from "inside the skill"), or its own Spire skill.
• Update the base vs. delta brief per fork as the default.
• Auth: OAuth with a scrubbed env vs. --bare + API key.
• Whether headless forks replace Agent-tool fork options in athanor.md or sit beside them.
• Plan mode upgrades Haiku to Sonnet silently: accept as a floor, or always pass an explicit model.

Decided 2026-10-16 (user, session 2026-10-15-21-grotto-work)

• Location: its own Spire skill, which the implementation skill references. This makes it easier to lift into Dirigent later.
• Fork sync: by default each fork gets a delta brief (what changed since the base). At phase boundaries, or when the delta grows, the Athanor updates the base and forks from the new one.
• Auth: OAuth with a scrubbed env (subscription → 1 h cache lifetime). No --bare.
• Agent-tool forks: replaced. Complex blocks go to forks of the trained implementer, and fresh Agent-tool agents stay for mechanical or distant blocks. The Agent-tool fork path is dropped from athanor.md.
• Model: always an explicit full model id. The fingerprint requires it anyway, which also sidesteps plan mode's silent Haiku→Sonnet upgrade. (Igor's default, not asked; user may override.)

Decided 2026-10-16, naming (user)

• A headless worker launched by the helper is a gremlin. The skill becomes spire:gremlins and the helper gremlins.py; the env marker, state folder and ledger names follow.
• The command that creates one is spawn. Forking the base (--resume <base> --fork-session) is one way to spawn. Keeping spawn separate from fork leaves room for other spawn methods later.
• The trained session stays the base. "Mogwai" was considered and dropped (trademark-adjacent, a second invented word).
• When: a mechanical rename block at the start of Phase 3, before the skill and procedure text is written, so the release ships with the final names.

Decided 2026-10-16, platforms (user)

• 0.3.0 ships Windows-only. On any other platform, where fails closed (ok: false with a clear reason), and the Athanor falls back to the 0.2.2 shape (fresh agents, no gremlins). SKILL.md says so.
• Linux testing is a follow-up (WSL Ubuntu and Docker are available on the dev host). macOS stays unsupported until someone can test it.

Amended 2026-10-16, release gating (user)

• 0.3.0 is not released from Windows alone. The work stays on the headless-forks branch, which gets pushed but not merged. When the Windows phases are done, an Igor on a native Linux machine and one on a Mac check out the branch, test, fix their platform and lift the fail-closed gate for it. Only then is the branch merged and released. WSL is fine for development.
• The Windows build still ends with a handoff document for those Igors (what to test, known POSIX gaps M14 and the /proc tree walk, the smoke recipe).
• Strongly suggested by the user: pick this up as Rust work right away as well (see reports/2026-10-16-01-session-harness-app-forms.md). Not started yet.

Decided 2026-10-16, platform seam (user)

• Phase 3 adds a refactor block. All platform-specific code (detached spawn, process table, tree kill, liveness, locks, path normalisation) moves behind one interface, with WindowsPlatform and PosixPlatform implementations. No scattered IS_WINDOWS branches stay outside it. The green Windows suite guards the refactor.
• Plus: a path-form test matrix (C:\…, C:/…, MINGW /c/…, /tmp/…, UNC, WSL /mnt/c/…) and a WSL check: does the helper run under WSL Ubuntu, and does PATH interop wrongly resolve claude to the Windows exe? Findings feed the Linux and Mac handoff. WSL stays fail-closed unless it passes.

Later

• Dirigent harness / MCP tool takes over the helper's job ("stable for the constables").
• Token-count access for agents beyond the helper's per-call returns.