dirigence/reliquary
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5092ed87933b2ea1f3618b0bbae364d9ac491e46
reliquary/docs/workpad/plans/2026-10-16-18-gremlins-phase3-contract.md
T
g4borg 5092ed8793 📝 Gremlins Phase 3 contract digest
2026-10-16 18:36:24 +02:00

67 KiB
Raw Blame History

Phase 3 contract digest: spire:gremlins (rename, platform seam, text, release)

Written by: the Athanor, claude-opus-5-5[1m], 2026-10-16 18:31 +0200, at Phase 3 intake. Nothing is built in this turn. What this is: the brief the Phase 3 block owners build against. It pins every point that the build plan, the goal's later decisions and Igor's Phase 3 brief leave open: the rename map, the platform interface, the gate, the N3/N4/flake fixes, the WSL check, the text per file and the release. In the last two phases every Important finding came from a detail a digest left open, so this one tries to leave nothing open. Where a choice was mine, it is marked (choice) and listed again in §12 for Igor's check.

Precedence (highest first):

  1. Igor's Phase 3 brief (2026-10-16, this turn): the six steps, N3, N4, the flaky test, the test cadence, "no push, no merge".
  2. The goal docs/workpad/goals/headless-forks.md as on main (the branch copy is older). Its sections "Decided … naming", "… platforms", "Amended … release gating" and "Decided … platform seam" override the build plan where they conflict.
  3. Build plan docs/workpad/plans/2026-10-16-02-headless-forks-build.md §4, §6 Phase 3, G-text.
  4. Plan docs/workpad/plans/2026-10-16-01-headless-forks.md §4, §7 Phase 3; design docs/workpad/designs/2026-10-16-01-headless-forks.md §2, §7, §8, §9.
  5. The Phase 1 and Phase 2 digests (plans/2026-10-16-12-…-phase1-contract.md, plans/2026-10-16-16-…-phase2-contract.md): they still describe the helper's behaviour, under the old names.
  6. This digest's own choices.

If this digest conflicts with a higher source, follow the higher source and say so in your handoff note.

Standing rules for every child (pass them on verbatim):

  • Read, Write and Edit for files; never cat, sed, awk or heredocs to read or change files, even when auto mode suggests Bash. git mv is allowed for the rename.
  • Do this yourself; do not dispatch further agents.
  • Commits use gitmoji (docs/workpad/specs/commit-conventions.md), stage explicit paths only, and carry no Co-Authored-By or other attribution lines. No push, no merge, no PR.
  • Between blocks: uv run python -m py_compile <file> plus only the test classes the block touched. The full suite runs once, at phase end (block 3.8).
  • No live claude calls in Phase 3 (see §12, choice C17).
  • Leave no processes running. Check by command line (gremlins-test-, _supervise, poscontrol, claude-stub), never by process name.
  • Stamp your exact model id in your handoff note. Append the note to the run log docs/workpad/reports/2026-10-16-08-headless-forks-run.md under "## Phase 3", in the run-log handoff-note format.
  • docs/workpad/goals/ is read-only.

1. Blocks

Block Owner Scope Gate (between blocks) Commit
3.1 Rename fresh, opus §2: forks → gremlins everywhere in the skill, fork command → spawn with method: "fork", env marker, state dir, kinds, JSON fields, templates, tests. Mechanical; no behaviour change. py_compile of both .py files; the test classes PathTests ScrubTests LockTests AtomicTests PidTests ProcessTreeTests InitTests CliTests RuleTests plus LaunchTests.test_train_spawn_continue_end_to_end and LaunchTests.test_refusals; G-where; the residue grep of §2.8 🚚 gremlins: rename spire:forks to spire:gremlins (spawn, SPIRE_GREMLIN_CHILD)
3.2 Platform seam and gate fresh, opus §3: Platform interface, WindowsPlatform, PosixPlatform, the path matrix, the Windows-only gate (§4), JSON shape changes of §3.6. py_compile; PathTests PathMatrixTests GateTests PidTests ProcessTreeTests LockTests CliTests SubprocessTests and LaunchTests.test_kill_tree test_no_visible_window test_detach_failed; G-where; the seam grep of §3.7 ♻️ gremlins: platform seam (WindowsPlatform, PosixPlatform) and path matrix, then 🚩 gremlins: Windows-only gate in where and init (two commits allowed)
3.3 N3, N4, kill flake fresh, opus §5 py_compile; InitTests, the new N4 test, LaunchTests.test_refusals test_kill_tree test_expire_kills_running_jobs 🐛 gremlins: init re-resolves the binary, late rebase of an inactive base, kill verification
3.4 WSL check the Athanor, own Bash (a probe, like Phase 0) §6. Findings to the scratchpad; they feed 3.7. No repo change unless the WSL run finds a seam bug (then a fix commit by a fresh opus, logged). none none (run-log note only)
3.5 Procedure text fresh, opus §7.1–§7.4: gremlins/SKILL.md (new), agents/athanor.md, implementation/SKILL.md, references/run-log.md G-text items 1–4, 6 (§9.2) 🤖 gremlins: SKILL.md, Athanor procedure, implementation skill, run-log template
3.6 Reference rows fresh, sonnet §7.5–§7.6: references/spawning-claude-code.md, references/models.md every new row has one of the four statuses and a date 🤖 implementation references: headless sessions and gremlins
3.7 Platform handoff fresh, opus §8: docs/workpad/reports/<YYYY-MM-DD-hh>-gremlins-platform-handoff.md none 📝 Gremlins platform handoff for Linux and macOS
3.8 README, version, phase tests, release fresh, sonnet; fallout to a fresh opus §9: README row, both manifests 0.3.0, full G-unit once, G-where, G-text in full, the release commit G-text in full, G-unit, G-where 🤖 Spire 0.3.0: trained implementer, gremlins per block (spire:gremlins) with the changelog body

Deviations from the build plan's Phase 3 table (choice C1): the plan had 3.1 text, 3.2 rows, 3.3 release. Igor's brief adds the rename, the seam, the gate, the handoff and three fixes, in that order. Text comes after all code changes, so it is written against the final JSON. 3.3 is split from 3.2 so that the seam refactor lands green on its own before behaviour changes. The full suite runs once, in 3.8, before the release commit. If it is red: one fresh opus fallout agent, then one re-run.

Run-log handoff notes: each block owner appends its own. The Athanor writes the 3.4 note and the Phase 3 close.

2. Rename map (block 3.1)

The goal: a launched worker is a gremlin; the command that creates one is spawn; forking the base's session is one spawn method, recorded as method: "fork"; the trained session stays the base. No compatibility aliases.

The rule for the word "fork" after the rename: "fork" survives only for the Claude Code session mechanism (--fork-session, "a fork of the base's session", "forked") and as the value of method. It never names a command, a job kind, a worker, a field or a file.

2.1 Files and paths

Old New
plugins/spire/skills/forks/ plugins/spire/skills/gremlins/ (git mv, so history follows)
forks.py gremlins.py
tests/test_forks.py tests/test_gremlins.py
templates/fork.md templates/spawn.md (choice C2): templates are named after the command, as train.md and rebase.md are. A later spawn method adds its own template.
templates/train.md, templates/rebase.md, preamble.md same names, text updated (§2.6)
State dir <run log without .md>-forks/ <run log without .md>-gremlins/ (state_dir_for, run_for_state)
Files inside the state dir (registry.json, registry.lock, ledger.jsonl, jobs/, briefs/, notes/, results/, logs/, raw/, mcp-empty.json, .gitignore) unchanged
Gates G-unit uv run plugins/spire/skills/gremlins/tests/test_gremlins.py; G-where uv run plugins/spire/skills/gremlins/gremlins.py where

Delete stale __pycache__/ folders under the old path if git mv leaves them (they are untracked).

2.2 Module identifiers (gremlins.py)

Old New
ForksError GremlinsError
cmd_fork cmd_spawn
CHILD_MARKER = "SPIRE_FORKS_CHILD" CHILD_MARKER = "SPIRE_GREMLIN_CHILD"
SCRUB_PINNED = {…, "SPIRE_FORKS_CHILD": "1"} {…, "SPIRE_GREMLIN_CHILD": "1"}
spawn_supervisor detach_supervisor (choice C3): "spawn" now means the command; starting the detached supervisor is "detach". Block 3.2 then moves its body into the platform (§3).
SPAWN_METHOD removed in 3.2 (PLATFORM.detach_method); in 3.1 rename it DETACH_METHOD so 3.1 stays green on its own
CIM carrier env vars SPIRE_FORKS_CMD, SPIRE_FORKS_CWD SPIRE_GREMLIN_DETACH_CMD, SPIRE_GREMLIN_DETACH_CWD (in POWERSHELL_CIM and its caller)
local forks_ in phase_boundary spawned_phases
prog="forks.py", "spire:forks helper …" prog="gremlins.py", "spire:gremlins helper …"
module docstring rewritten for gremlins

2.3 Commands and flags

Old New
fork --base B --block X --brief F [--phase N] [--mode sequential|parallel] [--paths …] [--max-minutes] [--max-budget-usd] [--force] [--delta-note PATH]… spawn with the same flags plus --method fork (choices: fork; default fork) (choice C4). The flag exists so a later method is an additive change.
fork in COMMANDS, HANDLERS, --help's commands list spawn
continue --job J unchanged; J must be a spawn job (error text "continue takes a spawn job")
train, rebase, wait, list, usage, expire, kill, tick, where, init, _supervise unchanged
CHILD_REFUSED contains "fork" contains "spawn"
help texts: "Fork a base for one block.", "fork a base that is not active", "the files this fork may touch", "One more turn in a fork …", "working dir of base and forks", "(the phase whose forks it serves)", "(a fork and its continues)" "Spawn a gremlin from a base for one block.", "spawn from a base that is not active", "the files this gremlin may touch", "One more turn in a gremlin (resume without --fork-session).", "working dir of the base and its gremlins", "(the phase whose gremlins it serves)", "(a spawn and its continues)"

2.4 JSON fields and values

Where Old New
job entry, result, ledger, list jobs kind: "fork" kind: "spawn"
job entry, result, ledger, list job rows (LIST_JOB_KEYS) (none) method: "fork" on spawn jobs, null on every other kind (choice C5). Always present, so result and ledger keep fixed key sets. continue jobs carry null (they resume, they do not fork).
spawn launch return {job, base, base_state, warm_until, rebase_due, retrain_due, reasons} {job, base, method, base_state, warm_until, rebase_due, retrain_due, reasons}
base record, list base rows (LIST_BASE_KEYS) forks: [job…] gremlins: [job…]
CAPPED_KINDS, HIT_KINDS, USAGE_KINDS, REAL_KINDS, kind checks in _conclude, phase_boundary, run_active, Supervisor.run (hit_written), finalize_job (head_at_end) "fork" "spawn"
usage json kinds keys; md phase table Kind cells fork spawn
usage md hit-ratio fallback text "n/a (no fork, continue or rebase call with a verdict)" "n/a (no spawn, continue or rebase call with a verdict)"
N3 refusal "%s is refused inside a fork (%s is set); a fork may only run where, list, usage and wait" "%s is refused inside a gremlin (%s is set); a gremlin may only run where, list, usage and wait"
continue refusals "the fork is still running", "the fork has no session" "the gremlin is still running", "the gremlin has no session"
spawn refusals "--mode parallel needs --paths (the files this fork may touch)", "base is not active (use --force to fork it anyway)" "… (the files this gremlin may touch)", "base is not active (use --force to spawn from it anyway)"
build_launch refusal message "forks never writes settings" "gremlins never writes settings"
preamble.md missing next to forks.py … next to gremlins.py
reasons, flags, statuses, other keys unchanged in 3.1 (3.2 renames spawn_failed and taskkill_rc, §3.6)

SCHEMA stays 1 (nothing released; no registry from before the rename is read again) (choice C6).

2.5 Env vars

Old New
SPIRE_FORKS_CHILD (N3 marker in the child env) SPIRE_GREMLIN_CHILD
SPIRE_FORKS_CMD, SPIRE_FORKS_CWD SPIRE_GREMLIN_DETACH_CMD, SPIRE_GREMLIN_DETACH_CWD
(new in 3.2) SPIRE_GREMLINS_UNSUPPORTED_OK (§4)

2.6 Prompt text in the skill folder

  • preamble.md title # Headless implementer (spire:gremlins). Body: "You run headless under claude -p in a Spire build: first as the trained base, then as gremlins spawned from it once per block (each a fork of the base's session). Any session of yours may later be resumed or forked again." Keep the other rules; "the forks helper (forks.py)" → "the gremlins helper (gremlins.py)"; "only when your brief says this fork commits" → "this gremlin commits".
  • templates/spawn.md: title # Block ${block} (spire:gremlins); "You are a fork of base" → "You are a gremlin spawned from base ${base} (a fork of its session; run log ${run})"; "## Rules for this fork" → "## Rules for this gremlin". The stale-snapshot sentence and every ${…} placeholder stay.
  • templates/train.md: "(spire:gremlins)"; "This session is trained once and then forked, once per block; every fork starts from …" → "This session is trained once; then one gremlin per block is spawned from it by forking it, and every gremlin starts from …"; "Forks write handoff notes" → "Gremlins write handoff notes".
  • templates/rebase.md: "(spire:gremlins)"; "You are a fork of base" → "This session is a fork of base"; "every later fork of this build" → "every later gremlin of this build".
  • commit_rule strings in cmd_spawn: "This gremlin runs in parallel with other gremlins: do NOT commit …" and "This gremlin commits: …".

2.7 Tests (test_gremlins.py)

  • Module variable forks → gremlins, _load_forks → _load_gremlins, FORKS_PY → GREMLINS_PY, sys.modules["gremlins"].
  • Temp prefix forks-test- → gremlins-test- (Base.setUp, tearDownModule's PowerShell filter 'gremlins' + '-test-', the M8 marker gremlins-test-poscontrol-%d).
  • Helpers: fork → spawn, fork_marked → spawn_marked, fake_fork → fake_spawn, FORK_RESULT → SPAWN_RESULT, SESS_FORK → SESS_SPAWN.
  • Test names: test_train_fork_continue_end_to_end → test_train_spawn_continue_end_to_end, test_usage_rule_real_fork → test_usage_rule_real_spawn, test_allowed_inside_a_fork → test_allowed_inside_a_gremlin; any other test name with fork the same way.
  • Assertions on strings change with the code ("inside a fork" → "inside a gremlin", "fork" kinds → "spawn", forks key → gremlins). No assertion is dropped or loosened; every changed assertion line is listed in the handoff note (old → new).
  • Add one assertion each for method: the spawn launch return has method == "fork"; its result and ledger line have method == "fork"; a train/continue result has method is None.
  • The stub (STUB_PY) keeps --fork-session handling (it is the claude flag).

2.8 Residue check (3.1 gate)

git grep -n -i "fork" -- plugins/spire/ after the block. Every remaining hit must fall in one of: the claude flag --fork-session; method values "fork" and the --method choices; prose about the session mechanism ("fork of the base's session", "forked"); the Agent-tool fork rows in implementation/references/spawning-claude-code.md and athanor.md/implementation/SKILL.md (those are Phase 3.5/3.6 text, untouched in 3.1). List the remaining hits in the handoff note with their category. git grep -n "spire:forks\|forks\.py\|SPIRE_FORKS\|skills/forks" -- plugins/ must be empty.

Workpad documents (docs/workpad/…) are history: none of them is renamed or edited, including this run log's title.

3. Platform seam (block 3.2)

All platform-specific code moves behind one interface in gremlins.py (one file stays the rule: stdlib only, PEP 723). It lives in one section between the markers # --- platform seam: begin --- and # --- platform seam: end ---.

3.1 Selection

def select_platform() -> "Platform":
    return WindowsPlatform() if os.name == "nt" else PosixPlatform()

PLATFORM = select_platform()

This is the only os.name test in the file. IS_WINDOWS, CREATE_NO_WINDOW/_NOWIN at module level, the module-level ctypes block, _taskkill, _powershell, find_cygpath, cygpath_w, _GITBASH_DRIVE and POWERSHELL_CIM all move into the classes. WSL is PosixPlatform (it is Linux).

3.2 The interface

class Platform:
    name: str            # "windows" | "posix"
    detach_method: str   # "cim-hidden" | "setsid"
    supported: bool      # WindowsPlatform: True. PosixPlatform: False (the 0.3.0 gate, §4)

    def describe(self) -> dict
    def is_wsl(self) -> bool
    @staticmethod
    def norm_path(p: str, cwd: str | None = None) -> str
    def popen_kwargs(self, new_group: bool = False) -> dict
    def detach(self, argv: list[str], cwd: str, log_path: str) -> dict
    def proc_ctime(self, pid: int) -> int | None
    def epoch_to_ctime(self, t: float | None) -> int | None
    def pid_alive(self, pid: int, ctime: int | None = None) -> bool
    def process_table(self) -> list[tuple[int, int, str]]
    def terminate(self, pid: int) -> bool
    def tree_kill(self, pid: int) -> int | None
    def restore_no_replace(self, src: str, dst: str) -> bool
    def visible_windows(self) -> list[tuple[int, int, str, str]] | None

Semantics, per method. "As today" means the current body of the named function, moved without behaviour change.

Method WindowsPlatform PosixPlatform
describe() {"name": "windows", "sys_platform": sys.platform, "wsl": False, "supported": True, "detach": "cim-hidden"} {"name": "posix", "sys_platform": sys.platform, "wsl": self.is_wsl(), "supported": False, "detach": "setsid"}
is_wsl() False True if WSL_DISTRO_NAME is set, or /proc/sys/kernel/osrelease contains microsoft (case-insensitive); unreadable → False
norm_path(p, cwd) the current Windows branch of norm_path, including M13's cygpath -w for Git Bash rooted non-drive paths, plus the WSL refusal of §3.4. Pure string logic except the cygpath call; must run on any host. find_cygpath() and cygpath_w() become static methods of this class. the current POSIX branch, plus the refusals of §3.4. Pure; runs on any host.
popen_kwargs(new_group) {"creationflags": 0x08000000} (CREATE_NO_WINDOW), new_group ignored {"start_new_session": new_group}
detach(argv, cwd, log_path) as today's CIM branch of spawn_supervisor (powershell with CREATE_NO_WINDOW, Win32_ProcessStartup.ShowWindow=0, command line and cwd through SPIRE_GREMLIN_DETACH_CMD/_CWD); log_path unused (the supervisor redirects itself) as today's POSIX branch (Popen(argv, cwd=cwd, stdin=DEVNULL, stdout/stderr=log file, start_new_session=True, close_fds=True))
return of detach {"ok": True, "method": self.detach_method, "pid", "ctime"} or {"ok": False, "method", "detail"} same
proc_ctime(pid) OpenProcess + GetProcessTimes (FILETIME ticks), as today /proc/<pid>/stat field 22, as today; None without /proc
epoch_to_ctime(t) FILETIME conversion, as today /proc/stat btime × SC_CLK_TCK, as today; None without /proc
pid_alive(pid, ctime) as today (access denied → alive, creation time unverifiable) as today (os.kill(pid, 0); PermissionError → alive)
process_table() Toolhelp32 snapshot, as today /proc walk, as today; [] without /proc (macOS: the known gap, §8)
terminate(pid) OpenProcess(PROCESS_TERMINATE …) + TerminateProcess, as today os.kill(pid, SIGKILL), as today
tree_kill(pid) taskkill /T /F /PID <pid> (System32 path), returns its exit code; OSError/SubprocessError → logged, None os.killpg(pid, SIGKILL) with OSError suppressed; returns None
restore_no_replace(src, dst) _retry(lambda: os.rename(src, dst)) (Windows rename never overwrites) os.link(src, dst) then os.remove(src)
visible_windows() EnumWindows + IsWindowVisible + GetWindowThreadProcessId + class and title, i.e. the test helper visible_windows() moved into the helper (choice C7): the user named "the window checks" as part of the seam None (not applicable)

ctypes is loaded lazily inside WindowsPlatform (on first use by a process method or visible_windows), never at import or in __init__. So WindowsPlatform() and PosixPlatform() can both be constructed on any host, and the path matrix and the gate tests run everywhere.

3.3 Module-level functions that stay (neutral code calls these)

These keep their names and signatures, so the cross-platform logic and the existing tests' mock.patch.object(gremlins, …) keep working. Each is a thin delegate with no platform branch:

  • norm_path(p, cwd=None, windows=None): windows=True → WindowsPlatform.norm_path, False → PosixPlatform.norm_path, None → PLATFORM.norm_path. (The parameter is a selector the tests use; it is not a platform check.)
  • proc_ctime, epoch_to_ctime, pid_alive, process_table → PLATFORM.<same>.
  • pid_record, record_alive unchanged (they call the delegates).
  • terminate(rec): if not record_alive(rec): return True, then PLATFORM.terminate(int(rec["pid"])).
  • process_tree(rec, alive_until): unchanged logic; it must call the module-level process_table, proc_ctime, pid_alive, epoch_to_ctime, never PLATFORM. directly (ProcessTreeTests patch the module names).
  • kill_tree(rec, extra, alive_until): unchanged logic; the one OS step becomes rc = PLATFORM.tree_kill(int(r["pid"])).
  • _run(...): **PLATFORM.popen_kwargs() instead of creationflags=_NOWIN.
  • detach_supervisor(state, run, job): builds argv = [supervisor_interpreter(), "-I", script_path(), "_supervise", "--run", run, "--job", job] and returns PLATFORM.detach(argv, cwd=state, log_path=raw_file(state, job, ".sup.log")). Tests patch gremlins.detach_supervisor.
  • Supervisor.run: the claude Popen takes **PLATFORM.popen_kwargs(new_group=True) (keeps today's POSIX start_new_session=True exactly; M14 is documented, not fixed).
  • RegistryLock._restore(aside): return PLATFORM.restore_no_replace(aside, self.path).

Neutral already, and staying outside the seam: _retry/PermissionError retries (harmless on POSIX), RegistryLock._try_create's getattr(os, "O_BINARY", 0), scrubbed_env (os.pathsep), _venv_prefixes, supervisor_interpreter, transcript_path.

3.4 Path-form matrix

New test class PathMatrixTests: every row × both classes, pure (no filesystem), WindowsPlatform.find_cygpath patched. Windows cwd G:\dev\proj; POSIX cwd /home/u/proj.

# Input WindowsPlatform.norm_path PosixPlatform.norm_path
1 C:\x\y.md C:\x\y.md refused (choice C8)
2 c:/x/y.md C:\x\y.md refused
3 C: / C:x (drive-relative) as today (cwd-of-drive semantics via ntpath; record what it gives, assert it is absolute with drive C:) refused
4 /c/x/y.md (MINGW) C:\x\y.md /c/x/y.md
5 /c C:\ /c
6 /tmp/x with a fake cygpath: its -w output (C:\Fake\tmp\x); without cygpath: refused (M13) /tmp/x
7 \\srv\share\x\y.md (UNC) \\srv\share\x\y.md refused
8 //srv/share/x/y.md \\srv\share\x\y.md //srv/share/x/y.md (posixpath.normpath keeps exactly two leading slashes)
9 /mnt/c/x/y.md (WSL) refused (choice C9): "WSL path form on Windows; pass C:\… or /c/…" /mnt/c/x/y.md
10 docs/a.md G:\dev\proj\docs\a.md /home/u/proj/docs/a.md
11 docs\a.md G:\dev\proj\docs\a.md refused (a backslash on POSIX is almost always a Windows path)
12 \rooted\a G:\rooted\a (the cwd's drive, as today) refused
13 ../z G:\dev\z /home/u/z
14 G:/x/y.md G:\x\y.md refused
15 "" / " " refused refused

"Refused" = GremlinsError, exit code 2, payload["error"] a sentence naming the form, payload["path"] the input. The POSIX refusals are: a drive form (^[A-Za-z]:), or any backslash. That is the only POSIX behaviour change in this phase, and it exists because the matrix needs a defined answer (a drive path silently joined onto the cwd is today's behaviour and is wrong).

The existing PathTests stay (some become redundant; keep them, they are cheap).

3.5 Tests that move or change

  • visible_windows()/console_windows() in the tests call gremlins.PLATFORM.visible_windows(); test_no_visible_window skips when it returns None or an empty list.
  • Tests that patch find_cygpath patch gremlins.WindowsPlatform.find_cygpath (a staticmethod).
  • test_spawn_failed becomes test_detach_failed (the reason is renamed, §3.6). It patches detach_supervisor; the fake return uses "method": gremlins.PLATFORM.detach_method, and it asserts reason == "detach_failed".
  • CliTests/SubprocessTests where assertions: out["platform"]["detach"] == "cim-hidden" on Windows (replaces out["spawn"]).
  • Tests may still branch on the platform where they test platform behaviour; they use gremlins.PLATFORM.name == "windows" instead of their own os.name check, except the generated stub wrappers (.cmd vs sh) and tearDownModule's PowerShell sweep, which may keep os.name (test-only code).

3.6 JSON shape changes in 3.2

Where Old New Why
where "spawn": "cim-hidden" removed; platform.detach carries it "spawn" is now a command
where "platform": "win32" "platform": {name, sys_platform, wsl, supported, detach, override} (override per §4) the gate needs a structured answer
kill, expire.killed[] taskkill_rc tree_kill_rc platform-neutral key (choice C10)
reason vocabulary spawn_failed detach_failed (choice C10): the supervisor's detach failed, for any kind; spawn_failed would read as "the spawn command failed"

3.7 Seam check (3.2 gate)

git grep -n -E "os\.name|sys\.platform|IS_WINDOWS|ctypes|_k32|taskkill|powershell|killpg|setsid|start_new_session|creationflags|cygpath|/proc" -- plugins/spire/skills/gremlins/gremlins.py: every hit lies between the seam markers, except sys.platform inside describe() (also inside) and string mentions in docstrings/comments outside, which the handoff note lists. The green Windows suite is the refactor's guard (goal).

4. Windows-only gate (block 3.2, second commit)

  • Rule: PLATFORM.supported is True only for WindowsPlatform. Linux, WSL (it is Linux) and macOS are PosixPlatform, which is supported = False in 0.3.0.
  • Neutral helper platform_gate() -> str | None: None when supported or overridden; else the reason: "spire:gremlins 0.3.0 runs on Windows only; this is <sys_platform><, WSL>. Use fresh agents for every block (the 0.2.2 shape); see SKILL.md, Platforms."
  • where: on a closed gate, ok: false, the reason joined into reason/error like the other reasons, exit 2. Everything else in the report is still filled (binary, uv, git, scrub), because the porting Igors need it.
  • init: refuses with exit 2, {"error": "platform not supported", "reason": <the gate reason>, "platform": PLATFORM.describe()} before any write (choice C11). The goal names only where; refusing init makes "fail closed" mean the helper cannot be used, not only that it says so. Every other command needs init, so nothing launches on a closed platform.
  • Override (porting aid) (choice C12): env SPIRE_GREMLINS_UNSUPPORTED_OK=1 opens the gate for that call. where then reports platform.override: true, stays ok: true if nothing else fails, and adds a warnings entry ("platform gate overridden …; this platform is untested"). It exists so the Linux and macOS Igors (and the WSL check) can run the suite and the smoke before they lift the gate in code. It is documented in the handoff report, not in SKILL.md.
  • Lifting the gate is a code change: PosixPlatform.supported returns True for the tested sys.platform values (the handoff report says how).
  • Tests (GateTests): WindowsPlatform().supported is True; PosixPlatform().supported is False with sys.platform patched to linux and to darwin; with gremlins.PLATFORM patched to a PosixPlatform whose is_wsl returns True and with the override env removed: where --binary <stub> exits 2, ok: false, reason names "Windows only" and "WSL", platform.supported false; init exits 2 and creates no state dir; with the override env: where exits 0 with the warning, init proceeds. On the real Windows host: where has platform.supported: true, override: false.
  • Base.setUp sets SPIRE_GREMLINS_UNSUPPORTED_OK=1 in its patched os.environ for every test (choice C13), so the same suite exercises the POSIX code on WSL and on the porting hosts; GateTests remove it. On Windows the variable changes nothing.

5. N3, N4 and the flaky kill test (block 3.3)

5.1 N3: init re-run and the binary

  • On a re-run without --binary: if the stored binary_resolved_by is "--binary", keep the stored path (an explicit pin). Otherwise re-resolve with resolve_binary(None) ($CLAUDE_CODE_EXECPATH, else PATH) (choice C14). If re-resolution finds nothing, keep the stored path.
  • init output always carries warnings: []. It gets one entry when the binary path changes ("binary changed: → (resolved by ); existing bases keep their own binary record, new trainings use the new one") and one when re-resolution failed and the stored path was kept.
  • The change shows in changed_fields as launch.binary.* (it already would). Existing bases are untouched: they keep their own launch.binary, so a still-present old binary gives no drift and a vanished one gives binary_missing as today.
  • Tests (InitTests): a first init via $CLAUDE_CODE_EXECPATH = stub A, a re-run with the env pointing at stub B and only --pings off → path B, warning, launch.binary.path in changed_fields; a first init with --binary A, a re-run with the env at B → path A kept, no warning; the stored file deleted and the env unset, PATH without claude → stored path kept with the "could not re-resolve" warning (then build_launch refuses the missing file with exit 2, as today, which is loud).
  • where is unchanged (it takes no --run).

5.2 N4: a rebase that ends after its base stopped being active

  • In _rebase_succeeded: when the old base's status is not active at finalise (a train --supersedes ended first; or an expire raced the kill), create NEW with the old base's status (superseded with the old base's superseded_by and superseded_at = this end time; or retired with retired_at), not active (choice C15). The old base is left untouched (its superseded_by is not overwritten). The job entry records rebase_inactive_parent: "<old> was <status> when the rebase ended".
  • The rebase result keeps status: ok (the call worked) and gets the new flag parent_inactive. Compute it in _conclude before the result is built (the base's status is known there).
  • So NEW gets no pings (status gate) and needs --force to spawn from, like any superseded base.
  • Test (LaunchTests): train B1; start rebase --base B1 --as B1r with a stub sleep; train --base B3 --supersedes B1 that ends ok first; when the rebase ends: its result ok with parent_inactive; B1r superseded, superseded_by == "B3"; B1 superseded_by == "B3" unchanged; ping_decision for B1r reads status:superseded; spawn from B1r without --force exits 2.

5.3 The flaky LaunchTests.test_refusals (kill returned ok: false under full-suite load)

Investigation (bounded: about 15 minutes of wall time):

  1. First make the failure speak: out = self.cmd("kill", "--job", j); self.assertTrue(out["ok"], out). (The assertion today discards the survivors.) This adds information, it loosens nothing.
  2. Try to reproduce under load: run LaunchTests.test_refusals alone 10 times while a CPU load runs (a handful of scratch-dir Python busy loops, recorded by pid and killed afterwards). Never run two copies of the suite at once: each tearDownModule kills every gremlins-test- process, including the other copy's.
  3. Classify each survivor from the kill output and a follow-up check of its pid:
    • (a) pid reuse: the pid now belongs to a process that OpenProcess refuses (ERROR_ACCESS_DENIED), so pid_alive reports it alive with an unverifiable creation time. This is a product defect.
    • (b) slow exit: the same pid and creation time is still alive after KILL_VERIFY_S and gone a little later (exit stalled under load). Timing.
    • (c) unkillable member: TerminateProcess keeps failing for a real tree member. A product defect.

Fixes, decided now:

  • Always (whether or not it reproduces) fix (a) in the neutral kill_tree verification: each sweep iteration takes one process_table(); a snapshot entry counts as a survivor only if record_alive(p) and the table still has that pid with the same name as in the snapshot. A pid that is gone from the table or now carries another name is dead (choice C16). Reading the code shows (a) is a real false positive, rare or not. Test: a kill_tree unit test on a fake table (ProcessTreeTests style) where a snapshot pid reports alive (access denied) but the table shows another name → no survivor; same name → survivor.
  • If (b) is observed: raise KILL_VERIFY_S from 10 to 30 s (the loop exits as soon as everything is dead, so the normal case costs nothing). Keep the test assertion strict.
  • If (c) is observed: fix in WindowsPlatform.terminate/tree_kill with a failing test first, and flag it.
  • Record in the handoff note: reproduced or not, the class, the survivors' names, and which fix landed. If nothing reproduces, say so and say that only the (a) guard landed.

6. WSL check (block 3.4; the Athanor's own Bash)

Purpose (goal): does the helper run under WSL Ubuntu, and does PATH interop resolve claude to the Windows exe? WSL stays fail-closed regardless. Findings feed the handoff (3.7). No live claude calls; no WSL login is needed.

Traps: Git Bash rewrites /mnt/… arguments, so every wsl call from Git Bash is prefixed MSYS_NO_PATHCONV=1. Never wsl --shutdown or --terminate (other WSL work on the host would die); the distro was Stopped at intake and idles back down by itself. Raw output goes to the session scratchpad …\scratchpad\gremlins-wsl\ (not in git).

Steps:

  1. Inventory: wsl -d Ubuntu-20.04 -- bash -lc 'uname -a; head -3 /etc/os-release; command -v uv python3 python3.10 python3.11 python3.12 git; python3 --version; ls ~/.local/bin ~/.cargo/bin 2>/dev/null'.
  2. PATH interop: bash -lc 'type -a claude claude.exe; echo "$PATH" | tr : "\n" | grep -c ^/mnt/; cat /etc/wsl.conf 2>/dev/null; echo EXECPATH=${CLAUDE_CODE_EXECPATH-unset} WSL_DISTRO_NAME=$WSL_DISTRO_NAME'. Record what claude resolves to (a /mnt/c/… Windows shim or .exe, a Linux install, or nothing) and whether $CLAUDE_CODE_EXECPATH crosses (it should not, without WSLENV).
  3. uv / Python ≥ 3.10: if uv is present, use it. Else, if a python3.10+ is present, run the files with it directly (the PEP 723 header has no dependencies). Else install uv with the official installer (curl -LsSf https://astral.sh/uv/install.sh | sh, to ~/.local/bin) only if the Bash permission system lets the call through. That is a download and execute, so it needs the user's approval through the permission prompt. If it is denied or blocked, record "not run: no Python ≥ 3.10 or uv in WSL; installing needs user approval", and the WSL check ends with steps 1–2.
  4. Copy to ext4: cp -r /mnt/g/dev/projects/reliquary/.claude/worktrees/headless-forks/plugins/spire/skills/gremlins ~/gremlins-wsl-check/ (drvfs has different chmod, lock and rename semantics; the copy isolates the helper from them).
  5. Runs, each to a log file under /mnt/c/Users/g4b/AppData/Local/Temp/claude/G--dev-projects-reliquary/42c87f82-5542-46aa-8d01-4166e3f0bcfe/scratchpad/gremlins-wsl/:
    • uv run ~/gremlins-wsl-check/gremlins.py where: expect exit 2, ok: false, the gate reason with "WSL", platform.wsl: true. Record the binary block (did it resolve the Windows claude, and does --version of it run through interop?).
    • The same with SPIRE_GREMLINS_UNSUPPORTED_OK=1.
    • where once from the drvfs path (/mnt/g/…/gremlins.py), to record any difference.
    • The unit suite: timeout 1200 uv run ~/gremlins-wsl-check/tests/test_gremlins.py -v. Then PathMatrixTests and GateTests alone. Record pass/fail/error/skip per class and the first line of each failure, grouped by cause (/proc, setsid detach, killpg/M14, stub wrapper, git missing, chmod, locks, path refusals, timing).
  6. Leftovers: ps -eo pid,args | grep -E "gremlins|_supervise|claude-stub" | grep -v grep; kill only our own by pid. Then rm -rf ~/gremlins-wsl-check (our scratch copy).
  7. Findings → …\scratchpad\gremlins-wsl\findings.md (inventory, interop answer, where outputs, suite table, failure causes, what would need fixing). The Athanor writes the 3.4 run-log note; 3.7 cites the findings.

If the WSL run shows a seam bug that also matters on Windows, or a crash in neutral code, a fresh opus fixes it with a test before 3.5 (logged as a deviation). POSIX-only failures are not fixed (the brief: "don't fix POSIX beyond what the seam needs"); they go into the handoff.

7. Text changes per file (blocks 3.5 and 3.6)

Write against the helper's real output: run where, <command> --help (one JSON object each) and read _conclude, cmd_wait, cmd_list, kill_job. The result fields and vocabularies listed in §7.1 are as built after 3.1–3.3; if the code differs, the code wins and the note says so.

7.1 plugins/spire/skills/gremlins/SKILL.md (new; 3.5)

Frontmatter (design §2 pattern, renamed):

---
name: gremlins
description: Trains one headless implementer (the base) per build and spawns gremlins from it, one per complex block, by forking the base's session (`claude -p --resume --fork-session`). Owns the command line, the prompt-cache bookkeeping and the usage ledger. Windows-only in 0.3.0. Loaded by the Athanor.
allowed-tools: Bash(uv:*)
---
!`uv run "${CLAUDE_SKILL_DIR}/gremlins.py" where`

Body, short (target 120–180 lines; the design says "Short"). Sections and the facts each must carry:

  1. What and when. The Athanor's build path for complex blocks: one base per build (trained early, reads the code, writes the trunk notes), one gremlin per complex block, fresh Agent-tool agents for mechanical or distant blocks. Claude Code only (Codex loads this skill too; it does not apply there). Words: base, gremlin, spawn (method fork), continue, rebase, ping.
  2. Platforms. Windows-tested. On any other platform (Linux, WSL, macOS) where reports ok: false with the reason and init refuses; then use fresh agents for every block (the 0.2.2 shape). Do not try to work around it.
  3. Setup. The injected where gives script (use that absolute path in every call) and ok. If ok is false, see Platforms or the reason. Projects need an allow rule Bash(uv run:*) (or Bash(uv:*)): the skill's allowed-tools did not pre-approve calls in a subagent (P0.8, untrusted dir; Phase 4 re-checks). $SCRIPTS_UV only on hosts without uv on PATH (A15). init once per run, with a full model id. A successor never re-runs init to "reset": list and adopt. A re-run changes only the flags given, except that it re-resolves the binary unless it was pinned with --binary (N3). --warm-margin-s must stay below the TTL (at 1 h, at most 1800 takes effect). Pass --allowed-tools together with --tools (Minor 12).
  4. Commands table, first column exactly | `<name>` | for: where, init, train, spawn, continue, rebase, wait, list, usage, expire, kill, tick (G-text 6 compares this set with --help's commands). One line each: key flags and the return shape (spawn returns {job, base, method, base_state, warm_until, rebase_due, retrain_due, reasons}; train and rebase return {job, base, session_id} (+ parent for rebase); continue returns {job}). Every command except where takes --run <run log .md>. Exit codes 0 / 2 / 3 / 4. stdout is one JSON object (usage --format md: one markdown fragment).
  5. Waiting. Call wait from Bash with timeout: 600000; never omit it (C2). The Bash tool backgrounds a call that passes its timeout instead of killing it (P0.1). Loop wait --all until exit 0 or 4. Exit 3 means "call again", and done may already hold finished (also failed) results (C4). Pings come back in pings, never in done. running[] rows count messages; results and the ledger count turns (M16). A failed detach (detach_failed) shows up in the next wait, not in the launch return.
  6. Results. The result fields (job, kind, method, base, block, phase, status, flags, fingerprint, session, parent_session, models_used, tokens{input, output, cache_creation, cache_creation_1h, cache_creation_5m, cache_read}, cost_delta_usd, cache, base_state, wall_s, turns, denials, note, raw, paths, reason, model_requested). Statuses ok|failed|timeout|killed|lost. Reasons: model_refused, usage_limit, overloaded, prompt_too_long, api_error, is_error, exit_code, no_result, detach_failed, launch_error, supervisor_error (failed); kill, expire, orphaned (killed); supervisor_dead (lost); null otherwise (timeout too). Flags: stalled, needs_attention, usage_mismatch, ttl_downgrade, cold_start, clock_jump, ping_missed, orphaned, expired, parent_inactive. A cold base usually shows partial, because the shared system prefix stays warm (C5).
  7. Rules (flags, not judgment).
    • rebase_due → rebase --as <new> --phase <n> before the next spawn; always pass --phase; rebase counts toward parallel_cap. retrain_due → train a new base with --supersedes <old>, else the old base keeps getting pings. binary_missing → launches refuse; train with the new binary. A cold base is still spawnable; coldness never triggers a re-train.
    • Delta: attach handoff notes with spawn --delta-note PATH (repeatable). A ## Changes since base section in a brief holds this gremlin's delta only; no line in it may start with # (also not inside fenced code: it ends the section, N1). When rebasing, attach every note written since the base's trained_at (shown by list), because a note older than that counts as known to the base whether or not it was given to it (N2).
    • continue sends the brief without a frame: put the commit rule and the note path into it (M16).
    • Sequential gremlins one at a time (Minor 13). Parallel only for disjoint blocks, with --mode parallel --paths … (N2); parallel gremlins never commit; the Athanor commits each block by the paths its note lists, one at a time.
    • Nothing running at hand-back: list shows no running job other than pings (kind ping; a ping ends within 300 s and is not a leak, Minor 7). Otherwise kill it and flag it.
    • kill: key on ok and status, not on killed or the exit code (M12). killed: true, status: ok means the job finished first; ok: false lists survivors (exit still 0): flag it.
    • The orphan watchdog (N1): a gremlin is killed (orphaned) after orphan_after (default 1200 s) without an orchestrator call (wait, spawn, continue, train, rebase, list, usage). kill and expire do not count (Phase 1 M3), and a gremlin's own calls never do. So keep looping wait while gremlins run.
    • Inside a gremlin, SPIRE_GREMLIN_CHILD=1 is set and train, spawn, continue, rebase, kill, expire, init, tick refuse (N3); where, list, usage, wait work.
    • Models: full ids only; spawn takes the base's model (no --model). Admission is "permissive at init, enforced at runtime" (M15): a substituted model ends failed/model_refused.
    • After claude exits, its leftover descendants are killed, including daemons a commit may have started (gpg-agent, git fsmonitor--daemon); they restart on demand (M16).
    • A re-train that supersedes a base while a rebase of it is running: the rebase's new base arrives superseded and its result carries parent_inactive (N4). Re-train first, or let the rebase finish.
    • Never resume or fork a headless session by hand; never call claude -p yourself; never SendMessage or TaskStop a gremlin (continue and kill cover it).
  8. State. <run log without .md>-gremlins/ next to the run log: what is committed at phase close (everything but raw/ and lock files) and what the Athanor reads (notes/, results/, logs/).

7.2 plugins/spire/agents/athanor.md (3.5)

Design §8.4 plus build plan A7, A13, A23, plus the goal's decisions:

  • Frontmatter description: keep the furnace sentences and trigger phrases ("Fire up the Athanor", "into the Athanor with it"), the Opus pin, "may use the Agent (Task) tool", "does not plan, attack plans, or review its own output", and the non-build line. Replace "blocks in the foreground" with: "trains a headless base and spawns gremlins for complex blocks, fresh agents for mechanical ones, a cheap gate between blocks, tests once, a run log with usage — and hands back".
  • skills: add spire:gremlins (G-text 2).
  • Line 23: "otherwise orient via direct file reads" → "otherwise orient by reading plans, designs, reports and notes, not code".
  • Intake (step 1): read the build plan, design, run log, trunk notes and the last review; check the branch. Remove "the code the phase touches. That reading is your trunk" (G-text 1). Then:
    • If the run log header has a Gremlins: line, run list and adopt the active base. Never re-init, never re-train an active base (A7).
    • Else run where. If ok: init (full model id = the plan's owner model for complex blocks; effort; the project's agent file if any), then train the base with a brief naming the plan, design, the phase's blocks, the areas to read and the trunk-notes path. The base writes the trunk notes. Add Gremlins: <state dir> to the run log header.
    • If not ok (any non-Windows host): fresh agents for every block. A fresh agent reads the code the phase touches and writes the trunk notes (choice C18); the Athanor still does not read code.
    • Later phases: rebase --as B<n+1> --phase <n> with the delta (handoff notes, review findings, commit range).
  • Step 2 (build the blocks): complex block in the trained area → spawn from the current base with a delta brief (block id and plan section, the handoff notes since the base as --delta-note, open review flags touching the block, the mode, the gate and test commands); then wait until done; read notes/<block>.md and the result. Mechanical or distant block → fresh Agent-tool agent in the foreground with the trunk notes. A complex block whose owner model differs from the base: a gremlin anyway (logged deviation) or its own base; never a model override (refused). Remove "a fork of yourself …" and the fork-behaviour sentence (G-text 1). Obey rebase_due/retrain_due as SKILL.md says.
  • Step 3 (gate): the plan's command, output to a .txt under the state dir's logs/. Red → continue --job <gremlin> once with the log path; still red → flag it and go on per "what may stay broken".
  • Mechanical check after each block (replaces "read the fix's diff for loosened assertions"; G-text 1): commit present (git log --oneline); the evidence log exists and is not empty; git diff --numstat <range> -- <test paths>; removed assertion lines git diff <range> -- <test paths> | grep -c '^-.*assert' (pattern assert by default, A23). A non-zero count goes to the block's note as a question and into the reviewer flags.
  • Step 4 (tests once): the Athanor runs the test command to a file under logs/ (never through tail; the first run after a fresh worktree is a warm-up, rerun once). Fallout → a gremlin from the current base (or continue of the block that caused it) with the failing log as the delta. Parallel test runs are off unless the project says they are safe (A23 default).
  • Step 5 (run log): block rows from usage --block <id> --format md; notes appended from notes/; phase close with usage --phase <n> --format md (per-kind table, cold starts, hit ratio, priced total) and every flag.
  • Step 6 (hand back): list shows nothing running except pings. Do not expire the base: a review and fix pass within the TTL finds it warm, and later it is cold but still spawnable.
  • Fix pass: gremlins of the current base with the findings as the delta; rebase_due decides whether to rebase first.
  • Dispatching: add "You call gremlins.py from your own Bash, with the script path where printed; every wait with timeout: 600000." Keep the SendMessage and model rules. Add "never SendMessage or TaskStop a gremlin".
  • Keepers, new:
    • "You do not read code; the base and its gremlins do. You read plans, notes, helper JSON, git log --oneline, git diff --stat/--numstat and gate summaries."
    • "Nothing running at hand-back."
    • Commit ownership (plan §4.4 / design §8.3): a sequential gremlin commits its block by explicit paths after its gate passes; parallel gremlins never commit, and the Athanor commits each block by the paths its note lists, one at a time; a fresh agent commits like a sequential gremlin; the Athanor commits the run log and the state dir (except raw/ and locks) at phase close as 📝. One committer at a time.
  • "Tools, not the loop" (line 60, A13): the fail-first test and the look one layer up become things the Athanor writes into briefs, not things it does.
  • Deliverable: add the priced usage totals and the base state (list: the active base, its warmth).
  • Remove every remaining mention of Agent-tool forks.

7.3 plugins/spire/skills/implementation/SKILL.md (3.5)

  • Line 40 "Each block commits and adds a short handoff note to the run log" → "Each block commits, and its owner writes a short handoff note (template: references/run-log.md): a gremlin writes notes/<block>.md and the Athanor appends it to the run log; a fresh agent writes into the run log directly."
  • "Context: fresh, fork, or keep" (lines 45–49) → heading "Context: fresh, trained, or keep"; keep the first paragraph ("Both extremes have failed …"). Replace "One option is trunk and forks …" with "trained implementer and gremlins": one base per build, trained early (it reads the code and writes the trunk notes), one gremlin per complex block spawned from it with a delta brief, the base rebased at phase boundaries or when the helper says so, fresh agents for mechanical or distant blocks. Mechanics in spire:gremlins. Windows-only in 0.3.0; elsewhere fresh agents throughout. No "a fork of the builder" (G-text 3).
  • "Spawning and models" (line 65ff): add "Gremlins run on the base's full model id; spawn takes no model override."
  • Line 12 (the inline rule) stays.

7.4 references/run-log.md (3.5)

  • Header block gains - Gremlins: <state dir> (or "none: <reason>"). A successor finds the state dir there and adopts it (A7).
  • Per-phase block table → | Block | Owner (model id from modelUsage) | Session | Commit | in | out | cache write | cache read | cost Δ |, filled from usage --block <id> --format md for gremlin blocks. For a fresh-agent block: owner = the stamped model id, Session —, the usage cells —, and the harness's token total in the handoff note (choice C19).
  • Phase close gains the usage --phase <n> --format md table and its three lines (cold starts, hit ratio, priced total), plus the base state from list.
  • Handoff note: same format for everyone. Gremlins write it to notes/<block>.md; the Athanor appends it.
  • "Trunk notes (written by the Athanor at intake)" → "Trunk notes (written by the base at training; by a fresh agent where gremlins are unavailable)".

7.5 references/spawning-claude-code.md (3.6)

Statuses only verified, observed, assumed, unknown, each with a date (build plan §2). Use the research doc docs/workpad/research/2026-10-16-00-claude-headless-fork-sessions.md for claim ids and the preflight report docs/workpad/reports/2026-10-16-09-headless-forks-preflight.md for Phase 0.

  • Rules of thumb: add "Complex blocks go to gremlins via spire:gremlins; never resume or fork a headless session by hand."
  • Fork section (Agent tool): the rows of design §9's table, with its statuses and dates; the "unverified" row is replaced (that word is outside the vocabulary). Add a lead line: Spire no longer uses Agent-tool forks (goal decision 2026-10-16).
  • Models: add "Headless --model takes full ids, so gremlins pin by full id" (observed 2026-10-16, P0.5).
  • New section "Headless sessions (claude -p)": every bullet of design §9's list as a row with its research id and date 2026-10-16. Plus, observed 2026-10-16 (preflight report):
    • P0.0: uv run adds VIRTUAL_ENV and a venv Scripts PATH head entry and no UV_*; stdout stays clean.
    • P0.1: no job objects on this host; the Bash tool's stop kills by process tree; a supervisor created through CIM Win32_Process.Create survives the Bash call and the subagent's turn; an unhidden CIM spawn opens a visible Windows Terminal window (fix: ShowWindow=0 plus CREATE_NO_WINDOW on every child); CIM children get the registry default user env, not the caller's.
    • P0.1(d): the Bash tool backgrounds a call that passes its timeout, it does not kill it.
    • P0.5: an unlisted model is substituted silently, with a system/informational warning.
    • P0.8: an ! injection runs in an Agent-tool subagent's skill preload; the skill's allowed-tools did not pre-approve later calls (untrusted dir; Phase 4 re-checks in a trusted project).

7.6 references/models.md (3.6)

Dated notes (2026-10-16), nothing removed:

  • "Context and block size": below the "trunk read at intake of about 100k–250k" line (kept), add that with gremlins the trunk read is the base's training (P0.2 base 182k; smoke base 23.7k), not the Athanor's context (A13).
  • "Future work": gremlins report per-call usage (usage); Agent-tool subagents still do not.
  • Plan mode upgrades Haiku to Sonnet silently; aliases map to versions per CLI release (research F2a–F2c).
  • Opus 5.5 may refuse a bare "run this blocking command" brief as pointless; say why it is wanted (observed 2026-10-16, Phase 0 trunk notes).

7.7 Routed items checklist (the text owner ticks each one in the handoff note)

Item Source Lands in
wait with timeout: 600000; the Bash tool backgrounds past its timeout C2, P0.1 SKILL §5, athanor dispatching
kill: key on ok and status Phase 1 M12 SKILL §7
Windows-tested; POSIX closed M14, goal SKILL §2, athanor intake
C8 permissive at init, enforced at runtime M15 SKILL §7
Post-exit sweep kills daemons M16 SKILL §7
continue needs commit rule and note path in its brief M16 SKILL §7
kill/expire do not refresh the orchestrator stamp Phase 1 M3 SKILL §7
Never re-run init to reset; re-run changes only given flags; margin < TTL (≤ 1800 at 1 h) Phase 2 Minor 8, Minor 2 SKILL §3, athanor intake
Always --phase on rebase; rebase counts toward the cap flag 23, flag 1a SKILL §7
--delta-note; ## Changes since base is this gremlin's delta only I1 SKILL §7
No # lines inside the changes section, fenced code included N1 SKILL §7
Attach every note since trained_at to a rebase N2 SKILL §7
train --supersedes on a re-train Minor 1 SKILL §7
Pings carry their base's latest phase; a ping at hand-back is not a leak I2, Minor 7 SKILL §5, §7
Sequential gremlins one at a time Minor 13 SKILL §7
--allowed-tools with --tools Minor 12 SKILL §3
messages vs turns M16 SKILL §5
Bash(uv run:*) allow rule P0.8 SKILL §3
detach_failed only visible in wait Phase 1 review SKILL §5
N3 binary re-resolution; N4 parent_inactive this phase SKILL §3, §7

8. Platform handoff report (block 3.7)

File: docs/workpad/reports/<YYYY-MM-DD-hh>-gremlins-platform-handoff.md (stamp from date when written). Audience: an Igor on native Linux and one on macOS, each starting from a checkout of headless-forks (goal "release gating"). Sections:

  1. Status: 0.3.0 is Windows-tested; the gate (where ok:false, init refuses) is closed on every other platform; the branch is not merged until each platform is tested and its gate lifted. Branch, head, how to check it out.
  2. The seam: the Platform interface (method list from §3.2), where it lives, what PosixPlatform does today per method, and the delegates.
  3. Running the gates there: uv install, G-unit, G-where, the override env SPIRE_GREMLINS_UNSUPPORTED_OK=1 (what it does, and that it is a porting aid only), and that the suite sets it itself.
  4. Known POSIX gaps (with code references):
    • M14: claude runs in its own session (popen_kwargs(new_group=True) → start_new_session), so tree_kill (killpg(<supervisor>)) misses it; only the per-pid sweep catches it, and the sweep needs process_table().
    • The /proc tree walk: process_table, proc_ctime and epoch_to_ctime read /proc. On macOS all three come back empty or None, so kill kills only the supervisor and leaves claude running, lost cannot kill a leftover tree, and pid-reuse checks are pid-only.
    • Dead-root claims (I2): a dead root claims children only when epoch_to_ctime works (/proc/stat btime); without it, it claims nothing (safe, but leftovers survive).
    • Locks: restore_no_replace uses os.link (needs hard links on the state dir's filesystem).
    • Detach by setsid: survival across the Bash call and the subagent's turn is untested on POSIX (the Windows answer was CIM).
    • The supervisor interpreter under a uv venv (sys._base_executable on POSIX), untested.
    • Path refusals of §3.4 on POSIX.
    • The env scrub list was built from the Windows Desktop host's vars.
    • The transcript slug rule (transcript_path) was observed on Windows only.
  5. WSL findings (from 3.4): inventory, the interop answer (does claude resolve to the Windows binary, does CLAUDE_CODE_EXECPATH cross), where outputs, the suite table, failure causes.
  6. What to test: the unit suite; the path matrix; a live smoke in a scratch clone (the recipe of 7); kill with a hanging gremlin and a grandchild, checked by pid + start time; the orphan watchdog; lost; supervisor survival across the end of the Igor's or Athanor's turn; no stray terminal windows (macOS: none expected).
  7. Smoke recipe: Phase 1 and 2 smoke steps under the new names, as commands: init → train B1 --phase 1 → wait → spawn P1 --phase 1 (commits) → wait → continue → spawn K1 + kill → spawn P2a --phase 2 (expect rebase_due: phase_boundary) → rebase --base B1 --as B2 --phase 2 → spawn P2b from B2 (expect hit against B2's context) → init --warm-margin-s 1800 + wait for expiring and a ping (or skip) → usage --phase 1 --format md → list (nothing running). What each step must show; every wait with Bash timeout: 600000; expected spend about $0.5–1 on a small base.
  8. How to lift the gate: make PosixPlatform.supported true for the tested sys.platform (linux, darwin) with a test; fix the gaps that the smoke shows (at minimum M14 for the platform: run claude in the supervisor's process group, or kill both groups; a ps-based process_table on macOS); update SKILL.md's Platforms line, the handoff report and the changelog; run the full suite and the smoke; record it in a run log. Do not merge until both platforms are done (goal).
  9. Not covered: Docker (available on the dev host, not used); Rust follow-up (goal "Amended" note, not started).

9. Release (block 3.8)

9.1 Changes

  • plugins/spire/README.md skills table: one new row gremlins: "Trained headless implementer forked per block: the base, its gremlins, cache and usage bookkeeping. Windows-only in 0.3.0. Loaded by the Athanor." Nothing else in the README (A22).
  • plugins/spire/.claude-plugin/plugin.json and plugins/spire/.codex-plugin/plugin.json: "version": "0.3.0". .codex-plugin gets only the bump (plan §5).

9.2 G-text (updated for the new names)

  1. git grep -n "fork of yourself\|That reading is your trunk\|read the fix's diff\|the code the phase touches" -- plugins/spire/agents/athanor.md returns nothing.
  2. spire:gremlins is in athanor.md's frontmatter skills:.
  3. git grep -n "a fork of the builder" -- plugins/spire/skills/implementation/SKILL.md returns nothing.
  4. gremlins/SKILL.md contains 600000, SPIRE_GREMLIN_CHILD and --paths.
  5. Both manifests read 0.3.0.
  6. The set of command names in SKILL.md's Commands table (rows starting | `<name>` |) equals --help's commands list (which excludes _supervise). Checked with a short Python one-off from the scratchpad, output pasted in the note.
  7. G-unit and G-where pass.
  8. New: git grep -n "spire:forks\|forks\.py\|SPIRE_FORKS\|skills/forks" -- plugins/ is empty (rename residue).
  9. New: the seam grep of §3.7.

9.3 Phase-end tests

Full G-unit once (about 150 s), to a log file in the scratchpad; then G-where. Red → one fresh opus fallout agent, then one re-run. Leftover-process check by command line afterwards.

9.4 Release commit

Message 🤖 Spire 0.3.0: trained implementer, gremlins per block (spire:gremlins) (choice C20): the build plan's title with the goal's names. Staged: README, both manifests (and nothing else). Body = the changelog, bullet style as 7c1ed39, no attribution:

  • New skill spire:gremlins (gremlins.py, uv, stdlib only): train one headless base per build, spawn a gremlin per complex block by forking the base's session; full launch fingerprint; scrubbed env; per-call usage, priced cost delta and ledger; warmth and keep-warm pings; rebase / re-train flags; orphan watchdog; Windows CIM detach with no visible window.
  • Windows-only: where and init fail closed elsewhere; the Athanor falls back to fresh agents. Platform seam (WindowsPlatform, PosixPlatform) for the Linux and macOS ports; handoff report path.
  • Athanor procedure: plan-level Athanor (no code reads), base writes the trunk notes, gremlins for complex blocks, fresh agents for mechanical ones, mechanical diff checks, usage in the run log; the Agent-tool fork path is dropped.
  • implementation skill and references: trained implementer and gremlins; run-log table with usage columns; spawning reference rows for headless sessions and the Phase 0 observations; dated model notes.
  • Preflight report path; run log path.
  • Known follow-ups: Linux/macOS testing and gate lift (handoff report); Igor text (D4: igor/SKILL.md:66, :112); ## Build keys (A23); README and project.md drift (A22); root AGENTS.md; Phase 4 install smoke and Phase 5 trial.

Then a 📝 run-log commit with the 3.8 note and the Phase 3 close. No merge, no push. Fix-pass commits after the release commit stay 0.3.0 (A21).

10. Test cadence and gates per block (summary)

After Run
3.1 py_compile ×2; the classes listed in §1; G-where; residue grep
3.2 py_compile; the classes listed in §1; G-where; seam grep
3.3 py_compile; the classes listed in §1
3.4 WSL procedure (no Windows test run)
3.5, 3.6, 3.7 G-text items of their files; no test run (no code change)
3.8 full G-unit once; G-where; G-text in full

Between blocks the Athanor also reads each child's diff stat on the test file and counts removed assertion lines (git diff <range> -- …/tests/ | grep -c '^-.*assert'); every removed line must be explained in the note as a rename or a specified change.

11. Not in Phase 3

Fixing POSIX beyond the seam (M14, a macOS process table, POSIX survival): handoff only. The Igor follow-ups (D4). ## Build project keys (A23). README drift beyond the gremlins row and .claude/spire/project.md (A22). Live smokes (Phase 4, after install). Merge and push (post-build, user). The deferred Phase 2 Minors 3, 4, 5, 6, 14 (trial tuning).

12. Open choices made in this digest (for Igor's check)

Id Choice Alternative
C1 Eight blocks: rename, seam+gate, fixes, WSL, text, references, handoff, release; text after all code the build plan's three blocks with the new work folded in
C2 templates/fork.md → templates/spawn.md spawn-fork.md (per method), or keep fork.md
C3 spawn_supervisor → detach_supervisor; "detach" for starting the supervisor keep "spawn" for both
C4 spawn --method fork flag (only choice, default) no flag until a second method exists
C5 method on every job, result, ledger line (null except spawn); job kind spawn kind gremlin, or method only on spawn jobs
C6 Registry SCHEMA stays 1 bump to 2
C7 visible_windows() moves into the platform (the user listed "the window checks") keep it test-only
C8 POSIX norm_path refuses drive forms and any backslash silently join (today), or map via wslpath on WSL
C9 Windows norm_path refuses /mnt/<d>/… map it to <D>:\…
C10 taskkill_rc → tree_kill_rc; reason spawn_failed → detach_failed; where.spawn → where.platform.detach keep the old names
C11 init also refuses on a closed platform gate in where only (the goal's letter)
C12 Porting override SPIRE_GREMLINS_UNSUPPORTED_OK=1 (documented in the handoff, not SKILL.md) none; porters edit the code to test
C13 The suite sets the override for every test; GateTests remove it run the gated suite as-is on WSL (most tests would fail at init)
C14 N3: an init re-run re-resolves the binary unless it was pinned with --binary; a warning when it changes where --run warns instead
C15 N4: the late rebase's new base takes the old base's inactive status; result flag parent_inactive create nothing; or text only
C16 Kill verification drops snapshot pids whose table entry is gone or renamed (fixes access-denied pid reuse), applied even if the flake does not reproduce change only the test
C17 No live claude calls in Phase 3 (the stub covers argv, env and the real CIM detach; the live smoke is Phase 4) one small live smoke at phase end (about $0.3)
C18 Fallback where where is not ok: a fresh agent writes the trunk notes; the Athanor still reads no code the Athanor reads code itself (the literal 0.2.2 shape)
C19 Run-log block rows for fresh agents: usage cells —, harness token total in the note a second table for fresh agents
C20 Release title 🤖 Spire 0.3.0: trained implementer, gremlins per block (spire:gremlins) the build plan's title with the old name
— An ! injection whose command exits 2 (where on a closed platform) is untested: it may fail the skill load on Linux/macOS. Flagged for Phase 4 and the porting Igors; the text keeps the plain form (design §2). … where || true (may break the Bash(uv:*) allow match)
— WSL uv install only through the permission prompt (download and execute); otherwise the WSL check stops at inventory and interop install without asking (not allowed)
Reference in New Issue View Git Blame Copy Permalink