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.)

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.