reliquary/docs/workpad/reports/2026-10-16-19-gremlins-phase3-digest-check.md

Pre-build check: Phase 3 contract digest (spire:gremlins)

• Checker model id: claude-opus-5-5[1m]. Fresh: did not write the digest and will not build or review Phase 3.
• Date: 2026-10-16
• Checked: docs/workpad/plans/2026-10-16-18-gremlins-phase3-contract.md at 5092ed8, against the goal on main (docs/workpad/goals/headless-forks.md), build plan §4 and §6 Phase 3, the Phase 2 re-check (N1–N5, the flake), the run log's routed items, the Phase 1 review and re-check, and plugins/spire/skills/forks/forks.py / tests/test_forks.py as they are now. No tests were run and no live calls were made.
• Verdict: 1 BLOCKER, 12 ADJUST, the rest OK. The interface list is complete against the code. The rename map has no gap that breaks state. The gate tests, C16 and the release wording need changes before the build.

BLOCKER

B1. GateTests cannot work on the Windows host as specified (§4 "Tests"). They patch gremlins.PLATFORM to a PosixPlatform. Every path then goes through norm_path → PLATFORM.norm_path → PosixPlatform, and §3.4/C8 makes that refuse drive forms.

• where --binary C:\…\claude-stub.cmd refuses in resolve_binary (forks.py:1004), and so does script_path() (:1067). Today cmd_where does not catch either (:2006, :2023).
• init --run C:\… refuses in state_dir_for (:340) before any gate check.
• What happens:
  • The override half ("where exits 0", "init proceeds") fails on Windows.
  • The closed init case ("exits 2 and creates no state dir") passes for the wrong reason, the path refusal. So it is a test that cannot fail on the gate.
  • The builder has to improvise the fix, which is how earlier digests produced Important findings.
• Fix: the fake platform is a WindowsPlatform subclass, or PLATFORM with supported and describe patched. It has supported = False, is_wsl() = True and describe() = {name: "posix", sys_platform: "linux", wsl: true, …}, so path handling stays Windows. init asserts error == "platform not supported". The gate check is the first thing in init, before state_dir_for and any norm_path. Keep the pure PosixPlatform().supported is False unit tests as written.

ADJUST

A1. The gate leaves launches open when a registry exists (§4, C11; §7.2 intake). "Every other command needs init" is only true for a fresh run. The state dir is committed at phase close (§7.2 commit ownership: everything except raw/ and locks). §7.2 intake says: if the run log has a Gremlins: line, run list and adopt, without where. On Linux, a successor Athanor adopting a run that was started on Windows would then run spawn, rebase, continue and train. wait and tick would launch pings. All of this happens on a closed platform. The sessions are not on that host, so the jobs fail, but each failure costs a launch, and pings keep retrying (Phase 2 Minor 3).

• Fix:
  • Refuse on a closed gate in the dispatcher for train, spawn, continue, rebase and tick, in the same place as the N3 refusal.
  • The tick inside wait and the supervisor launches no pings on a closed gate.
  • The intake runs where first, then adopts.
  • Add one GateTests case: a registry present, gate closed, spawn exits 2.

A2. C16 as written hides real survivors (§5.3). The rule is "a snapshot pid that is gone from the table or now carries another name is dead". It fails in three cases:

• (i) process_table() returns []. On macOS that is always (no /proc); on Windows it happens when Toolhelp fails (:750-752). Every snapshot pid then counts as "gone", so kill reports survivors: [], ok: true.

• (ii) The snapshot name is None. The root's name is names.get(root) (:805), so a root missing from the table gets None, and None never matches a name.

• (iii) On POSIX, comm changes on exec, for example an sh wrapper that execs python or claude. A live process then reads "renamed".

  The defect that is actually observed is narrower: access denied makes pid_alive return True without a creation-time check (:719-721).

• Fix: drop a snapshot pid only if one of these holds:

  • the table is non-empty and lacks the pid;
  • the snapshot name is known, the table name differs, and proc_ctime(pid) is None (the unverifiable case, i.e. class (a)).

  In every other case record_alive decides, as today.

• Read the table through the module-level process_table (ProcessTreeTests patch module names).

• Tests: an empty table keeps the survivor; a snapshot name None keeps it; a name differing while the ctime is verifiable leaves the decision to record_alive.

A3. The third N3 test in §5.1 contradicts itself. "Stored file deleted, env unset, PATH without claude → stored path kept with the 'could not re-resolve' warning (then build_launch refuses…)". build_init_config calls build_launch → binary_info, which raises claude binary not found (:2162, :1025-1026). The warning can never appear in the output.

• Fix: split it into two tests.
  • Stored file present, env unset, PATH without claude: path kept, warning shown, exit 0.
  • Stored file deleted: exit 2, claude binary not found (today's loud failure).

A4. C14 can switch installs silently. If the stored binary_resolved_by is CLAUDE_CODE_EXECPATH and a re-run comes from a shell without it, resolve_binary(None) falls through to the PATH claude (:1005-1010). That can be another install, with another version or auth. A warning is given, but it still crosses sources.

• Fix: re-resolve only through the stored source (EXECPATH from EXECPATH, PATH from PATH). If that source gives nothing, keep the stored path and warn.

A5. Path matrix row 3 (C:, C:x) contradicts "as today" (§3.4). On today's Windows branch, ntpath.join(base, "C:x") returns C:x. Its rest does not start with \, so the result is ForksError("cannot normalise path") (:322-332). C: goes the same way. Also, "assert absolute with drive C:" cannot be pure string logic on a POSIX host (WSL runs the matrix), because ntpath has no per-drive cwd there.

• Fix: row 3 on Windows is refused, as today.

A6. The C18 wording fails G-text 1 (§7.2 vs §9.2.1). §7.2 proposes "A fresh agent reads the code the phase touches and writes the trunk notes". G-text 1 requires that phrase to be absent from athanor.md.

• Fix: reword, for example "a fresh agent reads the code the blocks change and writes the trunk notes".

A7. "Windows-only in 0.3.0" contradicts the goal's "Amended … release gating". 0.3.0 is merged and released only after the Linux and macOS Igors lift their gates, so the 0.3.0 that ships is not Windows-only. The phrase is in four places:

• the SKILL.md description (§7.1);

• the README row (§9.1);

• the gate reason (§4, "spire:gremlins 0.3.0 runs on Windows only");

• the release commit body (§9.4).

  Porters can change the first three. They cannot change a commit body without rewriting a pushed history.

• Fix: use version-free wording.

  • Text: "Windows-tested; other platforms fail closed until tested (see Platforms)".
  • Gate reason: "spire:gremlins is not tested on <sys_platform><, WSL> yet; …".
  • Changelog: "tested on Windows; Linux and macOS gated pending the platform handoff".
  • Handoff §8.8 lists every place the porter updates.

A8. Three routed text items are missing from §7.7.

• (a) preamble.md:9 points gremlins at plugins/spire/skills/implementation/references/run-log.md. The Phase 1 review ("Two extra preamble lines" row) says this does not resolve in other projects, because the plugin lives in the cache. Phase 3 should give the format inline or by an absolute path. §2.6 says "keep the other rules", so this would ship broken.
  • Fix: inline the handoff-note format in preamble.md. Or have the helper put the absolute path into the templates (it knows script_path()). The preamble hash changes in 3.1 anyway.
• (b) stalled together with clock_jump is not a hung gremlin (Phase 1 re-check, M3 builder flag).
• (c) The remedy depends on the reason. Only model_refused points at availableModels. usage_limit, overloaded, api_error and prompt_too_long are not a settings problem (Phase 1 review, the 429 → model_refused finding). SKILL §6 lists the reasons but no action for each.

A9. Vacuous negative tests if the rename misses them (§2.7). test_forks.py:155, :934, :1011 and :1079 assert assertFalse(os.path.exists(… "-forks")). After the rename the state dir is -gremlins, so any line left unchanged can never fail. The residue grep shows them, but nothing in §2.8 says they are wrong.

• Fix: name these lines in §2.7 and derive the path from gremlins.state_dir_for(run), not a literal suffix.

A10. The §2.8 residue categories miss legitimate hits outside the skill. These are:

• igor/SKILL.md:66 (the D4 follow-up, out of scope);
• igor/references/mindset.md:11 and igor/references/harness-notes.md:3;
• implementation/references/superpowers.md:36 (repository forks).
• Fix: add a category "Igor text (D4) and non-session meanings: leave untouched", so 3.1 neither edits these lines nor reports them as residue.

A11. A closed-gate where does not always "still fill everything else" (§4). cmd_where (:2006) does not catch a path refusal from resolve_binary. On WSL with a Windows CLAUDE_CODE_EXECPATH (via WSLENV), or with --binary C:\…, §3.4 now refuses. The output is then exit 2 with a path error, without the gate reason and without the report the porters need.

• Fix: catch GremlinsError from resolve_binary into binary.error and reasons.

A12. platform.override is undefined while the env is set on a supported platform. C13 sets the env for every test, so the question comes up in every test. §4 says that with the override, where reports override: true.

• Fix:
  • Define override = env set and not PLATFORM.supported. Windows CliTests then assert override: false even with the env set.
  • PosixPlatform.describe() reads self.supported instead of a literal False, so lifting the gate is one change (§4 "Lifting the gate").
  • platform_gate() reads PLATFORM.describe(), never sys.platform, so it passes the §3.7 seam grep.

OK, with notes

• Interface (§3.2): complete against the code. These are every OS-specific site in forks.py, and §3.1–§3.3 places each one:

  • IS_WINDOWS/SPAWN_METHOD/_NOWIN :47-52;
  • cygpath :276-296;
  • the lock restore :500-503;
  • the ctypes block :630-664;
  • proc_ctime/epoch_to_ctime/pid_alive/process_table/terminate :667-853;
  • _taskkill/kill_tree :856-895;
  • _run :901;
  • _powershell/spawn_supervisor :1421-1460;
  • where :2028-2030;
  • Supervisor.run :3223-3224.

  The transcript_path slug and the scrub lists are neutral code that was only observed on Windows. They belong in the handoff, where §8 puts them. Do not name any local variable platform: the module imports platform (:2003).

• Rename map: no gap that breaks state. No -forks state dir is tracked in git, and nothing outside the skill references skills/forks. The base key "forks" has three writers (:1637, :2716, :2782) plus LIST_BASE_KEYS :3431; all are covered by §2.4. run_for_state :2935 is covered by §2.1. The preamble text change alters the append_system_prompt hash (a defining field). That is harmless, because no base from before the rename is reused (C6).

• C1–C7, C9, C10, C19, C20: OK. For C20, see the A7 wording.

• C8: OK. The POSIX refusal of a backslash is a behaviour change, and the handoff (§8.4) already lists it.

• C11: OK in itself. It is not enough on its own: see A1.

• C12: OK. Naming: SPIRE_GREMLINS_UNSUPPORTED_OK has a plural prefix, SPIRE_GREMLIN_CHILD and SPIRE_GREMLIN_DETACH_* have a singular one. Pick one before 3.2 writes them.

• C13: OK. It also means that a green suite on Linux says nothing about the gate; only GateTests cover it. The handoff should say so.

• C15: OK.

  • rebase refuses a base that is not active, at launch and again under the lock (:2873, :2893).
  • Only one rebase per base runs at a time (:2901).
  • So "not active at finalise" can only mean "changed during the run".
  • _conclude runs inside finalize_job's lock with the same registry read as _rebase_succeeded (:1656-1665, :1607). Computing parent_inactive there is therefore consistent.
  • Set the flag only when NEW is actually created, not on the rebase_conflict early return (:1622-1624).

• C16 (b): raising KILL_VERIFY_S to 30 s is fine for kill. expire kills its jobs one after another, though, so several stuck jobs × 30 s can pass the Bash tool's default 2 min. The tool then backgrounds the call (P0.1(d)). The SKILL text should give kill/expire a long Bash timeout.

• C17: acceptable. The stub tests exercise the real CIM detach after the rename and the seam refactor. The release commit is not a merge. Phase 4 must smoke the renamed helper before anything ships.

• C18: a reasonable reading of "the 0.2.2 shape" against "the Athanor does not read code". Wording: see A6.

• Push: the goal says the branch "gets pushed". The digest says no push, which follows Igor's brief (precedence 1). Pushing is a post-build user step.

• The two flagged risks (an ! injection exiting 2 on a closed platform; installing uv in WSL only through the permission prompt): correctly flagged, nothing to add.

• The flake plan (§5.3): the bounded investigation and "never two suites at once" are right. Only the C16 rule needs A2.