docs(reports): archive Issue #3 analysis, implementation plan, and multi-agent peer review reports
- Add Rev. 3 technical analysis report from creator-agy-01 - Add implementation plan from planner-reviewer-claude-01 - Add peer review reports across analysis and implementation review loops (Claude, Grok, OpenCode)
This commit is contained in:
@@ -0,0 +1,86 @@
|
||||
# 📋 Implementation Plan — Issue #3 Fix (Job `a9c8d6d3`)
|
||||
|
||||
- **Planner**: `planner-reviewer-claude-01`
|
||||
- **Based on**: `.agents/reports/creator-agy-01/issue-3-analysis.md` (Rev. 3, job `6b391a80`), independently validated PASS by both `planner-reviewer-claude-01` (job `9406c304`) and `reviewer-opencode-01` across the peer-review cycle.
|
||||
- **Scope**: implement both confirmed defects from the Rev. 3 analysis, add regression tests, verify the full suite.
|
||||
|
||||
---
|
||||
|
||||
## 1. Item 1 — Headless herdr daemon process-group detachment
|
||||
|
||||
**Defect** (Rev. 3, CONFIRMED, HIGH): `.agents/skills/lib.sh:207-219` (inside the heredoc that generates `.mam/shim/herdr`) launched the headless daemon via `nohup "$REAL_HERDR" ... server >/dev/null 2>&1 & disown`. `nohup` only ignores `SIGHUP`; `disown` only drops bash's own job-table tracking. Neither creates a new process group or session, so the daemon stays in the caller's PGID and dies when a process-group signal (`SIGTERM`/`SIGINT` from a test runner, timeout wrapper, or supervisor teardown) is broadcast — matching the live evidence from three independent reviewers' process-table inspections (PID 7623/PGID 7526/PPID 1, still TTY-attached, never `setsid()`'d).
|
||||
|
||||
**Fix**: replaced the `nohup ... & disown` line with a Python `subprocess.Popen(..., start_new_session=True, ...)` spawner (invoked via `python3 -c '...'`), which calls `os.setsid()` in the child before `exec` — portable across macOS (no `setsid(1)` binary by default) and Linux. `disown` is no longer needed since the process is no longer a bash job at all (spawned by the python3 child, not via `&`). The `kill -0 "$_mam_server_pid"` liveness-wait loop is unchanged; only how the PID is obtained changed (captured from the Python spawner's stdout instead of `$!`).
|
||||
|
||||
**File**: `.agents/skills/lib.sh:207-224` (the generated `.mam/shim/herdr` is a runtime artifact regenerated by `_init_herdr_isolation`, not git-tracked — no separate edit needed there).
|
||||
|
||||
**Test**: `tests/test_herdr_shim_contract.py::test_h26_daemon_spawn_uses_process_group_detachment` — (a) static check that the generated shim no longer contains the old `nohup ...server` pattern and does contain `start_new_session=True`; (b) behavioral check that extracts the *actual shipped* spawner statement from the generated shim and runs it standalone against a fake `REAL_HERDR` (a plain `sleep 30`), asserting the spawned process's PGID differs from the calling shell's PGID — i.e. genuine detachment, not just a textual change. Verified fail-old/pass-new: reverting `lib.sh` to the pre-fix version makes this test fail (old `nohup` pattern still present); restoring the fix makes it pass.
|
||||
|
||||
## 2. Item 2 — Class A (`agy`/`hermes`/`opencode`) 0-turn resume fallback
|
||||
|
||||
**Defect** (Rev. 3, CONFIRMED, MEDIUM — Class A only): a session for `agy`/`hermes`/`opencode` stopped before its first message has `session_id_source: pending-discovery` and a null own-key. `resolve_session_id.sh` correctly returns `""`, and `resume_session.sh:54-57` hard-exits (RC=1) telling the caller to use `multi-agent-mux-create`, which in turn requires `--role` (`create_session.sh:96`) — an argument resume callers don't hold. **Explicitly not a defect for Class B** (`claude`/`grok`): their `verify_session.py:99-101` `assigned`+`unverified` escape hatch already resolves the pre-assigned UUID without requiring an on-disk transcript, proven by the pre-existing `test_t8_resume_unmaterialized_assigned_id` (still green, untouched).
|
||||
|
||||
**Fix** (`.agents/skills/multi-agent-mux-resume/scripts/resume_session.sh`):
|
||||
- When `resolve_session_id.sh` returns an empty UUID, branch on agent: `agy`/`hermes`/`opencode` set `FRESH_SPAWN=1` and continue instead of exiting; `claude`/`grok`/any other agent hit the exact original hard-exit (byte-identical error message and RC=1) — the Class B path is completely unmodified.
|
||||
- When `FRESH_SPAWN=1`, `CMD_FULL` is computed via `lib_py.agents spawn-spec` (the same call `create_session.sh` uses for a first-time launch) instead of `resume-spec`, with a matching inline fallback case statement for `agy`/`hermes`/`opencode` only.
|
||||
- This bypasses the broken `resume_session.sh → create_session.sh --role` handoff entirely rather than trying to make `create_session.sh` callable without a role — the recovery happens inside `resume_session.sh` itself, reusing the same command the agent was originally spawned with.
|
||||
|
||||
**Fix** (`.agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh`): the final YAML update needs `--uuid`, which is empty for a fresh-spawn resume. The hard `[ -n "$UUID" ] || exit 2` guard was relaxed to allow empty (documented in `usage()`), and a new optional `--cmd-full` flag lets `resume_session.sh` pass through the already-computed spawn command for display. The Python payload:
|
||||
- `last_visible_status` branches: `"resumed conversation {uuid} ..."` when non-empty, `"resumed (fresh spawn, no prior turn) ..."` when empty.
|
||||
- **Only the `agy`/`hermes`/`opencode` blocks** got an `if uuid: ... else: ...` guard (own-key set + uuid-interpolated `cmd_full` when present; `--cmd-full` passthrough with a static fallback when absent). **The `claude` and `grok` blocks are byte-identical to before** — per the brief's explicit instruction, Class B is never touched.
|
||||
|
||||
**Files**: `.agents/skills/multi-agent-mux-resume/scripts/resume_session.sh`, `.agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh`.
|
||||
|
||||
**Tests**:
|
||||
- `tests/test_uuid_target.py::test_t14_resume_class_a_fresh_spawn_fallback` — creates an `agy` session, stops it at 0 turns, confirms the YAML row has `status: stopped` and no own-key, then runs `resume_session.sh --dry-run` and asserts RC=0 with a plain spawn command (`--dangerously-skip-permissions`, no `--conversation`). Verified fail-old/pass-new: reverting `resume_session.sh` alone reproduces the old hard-fail (`ERROR: No saved session for ...`) and the test fails; restoring the fix makes it pass.
|
||||
- `tests/test_uuid_target.py::test_t15_resume_class_b_still_hard_fails_when_truly_unresolvable` — a genuinely never-created `claude` session must still hard-fail with the original error and RC=1, guarding against the fallback ever leaking into Class B.
|
||||
|
||||
## 3. Verification
|
||||
|
||||
- Targeted suite (`test_tier1-4`, `test_uuid_target`, `test_c1_tui_readiness`, `test_herdr_shim_contract`): 164 passed pre-existing + 3 new = 167, all green, before adding the final full-suite run.
|
||||
- Full suite (`tests/`): run in background; result to be confirmed and cited in the final job report.
|
||||
- No changes to `verify_session.py`, `workspace_uuid.py`, or the `claude`/`grok` branches of `update_yaml_resumed.sh` — the Class B escape hatch and `test_t8` contract are untouched, per the brief's explicit requirement.
|
||||
|
||||
## 4. SemVer
|
||||
|
||||
Both changes are backward-compatible bug fixes (no public interface/behavior removed; `resume_session.sh`'s new fallback only activates on a previously-hard-failing input; `update_yaml_resumed.sh`'s relaxed `--uuid` requirement is additive). This qualifies as a PATCH under SemVer 2.0.0 §6. Version bump and `VERSIONS.md`/`SKILL.md` changelog entries are left for a subsequent release-packaging job (out of this job's stated scope, which is analysis-driven code improvement, not release cutting).
|
||||
|
||||
---
|
||||
|
||||
## Rev. 2 — Refinement in response to `creator-agy-01`'s architectural challenge (job `c4b0a075`)
|
||||
|
||||
**Independent verification of the challenge** (before accepting it): re-read the live, already-implemented `update_yaml_resumed.sh` and confirmed the challenge's citation is exact — the existing-row branch (`else:` at line 150, running through line 163, immediately before the shared `target['status'] = 'running'` at line 165) genuinely never touches `herdr_session_epoch` or `herdr_session_created_at`. Cross-checked the two supporting mechanisms it depends on: `lib_py/verify_session.py:89` (`epoch = row.get("herdr_session_epoch", 0) if mode == "discover" else 0`) confirms the epoch watermark only matters in `discover` mode, and `lib_py/agents/adapters/agy.py:49` (`if ctx.epoch and os.path.getmtime(path) < ctx.epoch: return False`) confirms the exact `mtime >= epoch` acceptance rule the challenge describes. `reconcile.sh` does call `verify_session_uuid(..., mode="discover")` for agy/hermes/opencode (lines 708/766/876). **This is a genuine defect I introduced in the Item 2 fix** — a Class A fresh-spawn resume leaves the row's discovery watermark stuck at the original `create_session.sh` timestamp, so `reconcile.sh`'s next sweep could pin an unrelated, older on-disk conversation (created any time after that original watermark, including *before* the resume even happened) to the freshly-resumed, still-silent agent.
|
||||
|
||||
**One precision correction to the challenge's own proposed diff**: `session_id_source`/`session_id_verified` are not currently set on `agy`/`hermes`/`opencode` rows at all — `create_session.sh`'s per-agent block only assigns those two fields for `claude`/`grok` (see `create_session.sh:402-437`). Setting them on a Class A row in the proposed fix is therefore not "resetting" pre-existing state — it introduces a field that wasn't there before. This is harmless (nothing currently reads `session_id_source`/`session_id_verified` on a non-claude/grok row; `verify_session.py:99`'s escape hatch is gated on `session_id_source == "assigned"`, which a Class A row will never have), but the refined fix below keeps it anyway for forward-consistency with the fields `create_session.sh` already sets for Class B, rather than dropping it — it costs nothing and makes a future reader's mental model ("every row always carries these two fields") uniformly true.
|
||||
|
||||
### Refined fix
|
||||
|
||||
In `.agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh`, inside the shared post-branch code (i.e. *after* line 165's `target['status'] = 'running'`, applying uniformly regardless of which branch — new-row or existing-row — populated `target`, and reusing the `epoch`/`now` locals already computed at lines 117-118), add:
|
||||
|
||||
```python
|
||||
if not uuid:
|
||||
# ISSUE-3 (challenge c4b0a075): a Class A fresh-spawn resume re-arms
|
||||
# discovery from scratch - the resumed agent has not spoken yet, so any
|
||||
# on-disk conversation older than THIS resume must not be auto-pinned to
|
||||
# it by reconcile.sh's mode="discover" mtime >= epoch check. Without this,
|
||||
# the row's watermark stays at the original create_session.sh timestamp,
|
||||
# letting reconcile.sh capture a stale/unrelated transcript before the
|
||||
# resumed agent's first real turn.
|
||||
target['herdr_session_epoch'] = epoch
|
||||
target['herdr_session_created_at'] = now
|
||||
target['session_id_source'] = 'pending-discovery'
|
||||
target['session_id_verified'] = False
|
||||
```
|
||||
|
||||
Gated strictly on `if not uuid:` (the same condition already used at line 175 for the `last_visible_status` branch), so it fires *only* on the new Class A fresh-spawn path from this same job's Item 2 fix — it can never touch a normal resume (`uuid` non-empty, any agent) or any Class B path, since `claude`/`grok` never reach `update_yaml_resumed.sh` with an empty `--uuid` (per Item 2's `resume_session.sh` branch, only `agy`/`hermes`/`opencode` set `FRESH_SPAWN=1`).
|
||||
|
||||
### New test spec
|
||||
|
||||
`tests/test_uuid_target.py` — extend `test_t14_resume_class_a_fresh_spawn_fallback`'s fixture (or add a sibling `test_t16_resume_class_a_fresh_spawn_resets_discovery_epoch`): after creating+stopping the `agy` session at 0 turns, seed a conversation artifact under the workspace with an `mtime` *between* the original creation time and "now" (simulating the challenge's $T_2$ stale transcript), run `resume_session.sh` (not `--dry-run`, since the epoch write only happens in `update_yaml_resumed.sh`'s real YAML mutation), then assert in `agent-sessions.yaml` that `herdr_session_epoch` was advanced to at or after the resume's own timestamp (not the stale creation-time value) — i.e. the pre-existing stale artifact's `mtime` is now `<` the row's watermark and would be correctly rejected by a subsequent `reconcile.sh` discover-mode sweep. Should be verified fail-old/pass-new like the other two Item 2 tests: written against the pre-refinement code, `herdr_session_epoch` stays at the original creation epoch and the assertion fails; after applying the refined fix, it advances and the test passes.
|
||||
|
||||
### Updated action list for re-implementation
|
||||
|
||||
1. Apply the `if not uuid:` epoch/watermark-reset block above to `update_yaml_resumed.sh`, placed after the shared `target['status'] = 'running'` line so it applies regardless of which branch (new-row vs. existing-row) populated `target`.
|
||||
2. Add the new regression test per the spec above, and verify fail-old/pass-new for it specifically (not just that it passes).
|
||||
3. Re-run the full test suite and confirm no regression against the 454-passed baseline from the original `a9c8d6d3` implementation.
|
||||
4. No changes needed to Item 1, `resume_session.sh`'s branch logic, `verify_session.py`, `workspace_uuid.py`, or any Class B (`claude`/`grok`) code path — this refinement is fully contained within `update_yaml_resumed.sh`'s shared post-branch section.
|
||||
Reference in New Issue
Block a user