feat: add AGENT_DEV_CMD / AGENT_REVIEW_CMD per-side overrides (INV-37)

[zxkane]

Summary

Adds two operator knobs in lib-agent.sh that let dev and review wrappers run on different agent CLIs in the same project:

• AGENT_DEV_CMD — defaults to ${AGENT_CMD:-claude}
• AGENT_REVIEW_CMD — defaults to ${AGENT_CMD:-claude}

Each wrapper sets AGENT_CMD to its side's value immediately after sourcing lib-agent.sh. The AGENT_LAUNCHER claude-only guard generalizes to reject any non-claude side (strictly more permissive than the old single-side check — never rejects a config that previously passed).

The motivating use case: a downstream consumer project wants AGENT_CMD="claude" for heavy dev and AGENT_REVIEW_CMD="agy" for cheaper review.

What's in the PR

• skills/autonomous-dispatcher/scripts/lib-agent.sh — 7-line init + guard rewrite
• skills/autonomous-dispatcher/scripts/autonomous-dev.sh — 4-line override block after source lib-agent.sh
• skills/autonomous-dispatcher/scripts/autonomous-review.sh — 5-line override block (symmetric)
• skills/autonomous-dispatcher/scripts/autonomous.conf.example — operator-facing comment block with worked example
• tests/unit/test-lib-agent-per-side-cmd.sh — 14 assertions (PSC-S1..S11): defaults, single-side override, both-side, empty-string, launcher guard ×4, wrapper structural placement
• docs/pipeline/per-side-agent-cmd.md — spec
• docs/pipeline/invariants.md — INV-37
• docs/pipeline/README.md — index entry
• docs/superpowers/plans/2026-05-25-per-side-agent-cmd.md — implementation plan (kept for traceability)

Backwards compatibility

Existing deployments don't set the new vars. Defaults make both equal to $AGENT_CMD, so behavior is byte-for-byte identical pre/post. Verified: all 7 peer test-lib-agent-*.sh suites still pass.

Spec & invariant

• docs/pipeline/per-side-agent-cmd.md
• INV-37 in docs/pipeline/invariants.md

Pipeline-docs gate

Touches lib-agent.sh (watched path), so docs/pipeline/ must also change. Satisfied:

• docs/pipeline/per-side-agent-cmd.md
• docs/pipeline/invariants.md (INV-37)
• docs/pipeline/README.md

Test plan

• bash tests/unit/test-lib-agent-per-side-cmd.sh — 14/14 PASS
• All existing tests/unit/test-lib-agent-*.sh regression tests PASS
• shellcheck -S error on lib-agent.sh + both wrappers + new test
• bash -n autonomous.conf.example syntax OK
• CI: unit-tests + shellcheck + pipeline-docs-gate green

Review process

The PR went through /pr-review-toolkit:review-pr with four specialized agents (code-reviewer, pr-test-analyzer, silent-failure-hunter, comment-analyzer). Findings addressed inline:

• C1 (Critical): stripped podcast-curation private-repo refs from two committed docs (CLAUDE.md "No Private Repo Refs" rule)
• H1, H2 (High): removed stale lib-agent.sh line numbers from the spec doc (referenced by name instead — survives churn better)
• M1, M2, M3 (Medium): fixed spec-vs-implementation drift in operator-block placement and PSC-S9/S10 line-window descriptions (+4 / +5 reflecting the actual WHY-rationale comment sizes)

Silent-failure-hunter found 0 critical issues; 2 cosmetic observations (no fix recommended). Test analyzer noted 3 improvement opportunities (rated 5-7) deferred to follow-up.

Future work (filed as suggestions in review, NOT blocking this PR)

• _LIB_AGENT_AGY_MODEL_WARNED-style WARN-once gate for the (rare) inverse pattern (agy-dev / claude-review with conflicting permission needs) — currently the AGENT_PERMISSION_MODE value is silently dropped on agy side, which is fine for the common pattern but not for the inverse
• Behavioral test that exercises the AGENT_CMD rebinding actually steers case "$AGENT_CMD" dispatch (PSC-S9/S10 are structural-only)
• env -i isolation in test sandboxes (mitigates hypothetical dev-box AUTONOMOUS_CONF ambient export)

[zxkane]

agy CLI review (Antigravity 2.0, v1.0.2)

I ran the local agy CLI to review this PR (using the same flag set lib-agent.sh uses for AGENT_CMD=agy: agy -p --dangerously-skip-permissions --print-timeout 30m --log-file <path>). agy returned 3 findings; I verified each against the codebase. Two are real regressions this PR enables; one is a pre-existing bug.

---

Finding 1: AGENT_DEV_EXTRA_ARGS / AGENT_REVIEW_EXTRA_ARGS mapped by stage, not side (HIGH, pre-existing on origin/main, NOT introduced by this PR)

Location: skills/autonomous-dispatcher/scripts/lib-agent.sh:590 (run_agent) and :803 (resume_agent).

# run_agent line 590:
_parse_extra_args AGENT_DEV_EXTRA_ARGS extra_args

# resume_agent line 803:
_parse_extra_args AGENT_REVIEW_EXTRA_ARGS extra_args

Why it's a bug: the variables are named per-side (DEV / REVIEW) but consumed per-stage (run / resume). Call-site reality:

• autonomous-dev.sh calls both run_agent (lines 337, 531) AND resume_agent (line 447) → dev side picks up AGENT_DEV_EXTRA_ARGS on first run, but AGENT_REVIEW_EXTRA_ARGS on resume
• autonomous-review.sh calls only run_agent (line 546) → review side picks up AGENT_DEV_EXTRA_ARGS (wrong name)

Status: NOT introduced by this PR — the misnaming exists on origin/main. This PR doesn't touch _parse_extra_args or its call sites. But the misnaming becomes more visible now that per-side CLIs are possible (operators may set AGENT_REVIEW_EXTRA_ARGS=... for an agy review wrapper and find it ignored).

Recommended fix (separate PR): pass an AGENT_SIDE argument to run_agent/resume_agent and select the EXTRA_ARGS variable dynamically. Or rename the vars to AGENT_RUN_EXTRA_ARGS / AGENT_RESUME_EXTRA_ARGS to match what they actually do (with backwards-compat aliases). File as a separate issue.

---

Finding 2: _pgid_has_agent_process reads shared $AGENT_CMD — false-negative liveness under split config (HIGH, newly enabled by this PR)

Location: skills/autonomous-dispatcher/scripts/lib-dispatch.sh:1276

_pgid_has_agent_process() {
  ...
  local agent_cmd="${AGENT_CMD:-claude}"
  ...
  if [[ "$comm" == *"$agent_cmd"* ]]; then
    return 0
  fi
  ...
}

Why it's a regression: the helper is shared by dev_near_success (caller at line 1234) and review_near_success (caller at line 1371). When the dispatcher tick runs with the project's default AGENT_CMD=claude, but the review wrapper has been spawned with AGENT_CMD=agy (via the new AGENT_REVIEW_CMD=agy override), the substring match *claude* against the agy process's comm fails, falsely classifying the live wrapper as DEAD.

Pre-PR: impossible — there was no way for dev and review to run different CLIs.
Post-PR: real failure mode for any project that adopts AGENT_REVIEW_CMD ≠ AGENT_DEV_CMD.

Recommended fix: callers know which side they're checking. Pass the per-side CLI as an argument:

# In dev_near_success:
_pgid_has_agent_process "$pid" "${AGENT_DEV_CMD:-${AGENT_CMD:-claude}}"

# In review_near_success:
_pgid_has_agent_process "$pid" "${AGENT_REVIEW_CMD:-${AGENT_CMD:-claude}}"

# In _pgid_has_agent_process:
_pgid_has_agent_process() {
  local pgid="$1"
  local agent_cmd="${2:-${AGENT_CMD:-claude}}"
  ...
}

---

Finding 3: is_session_completed AGENT_CMD-gate reads shared var — wrong CLI under split config (MEDIUM, newly enabled by this PR)

Location: skills/autonomous-dispatcher/scripts/lib-dispatch.sh:530

is_session_completed() {
  ...
  [ "${AGENT_CMD:-claude}" = "claude" ] || return 1
  ...
}

Why it's a regression: the function only handles claude's JSON log format (documented at lines 503-528). The gate at line 530 conservatively returns 1 (false) for non-claude CLIs so the dispatcher falls through to normal stale-detection. Under split config (AGENT_CMD=claude AGENT_DEV_CMD=codex):

• Dispatcher's $AGENT_CMD is still claude (the project default)
• Gate passes (claude == claude)
• Function tries to parse /tmp/agent-${PROJECT_ID}-issue-N.log
• But the dev wrapper actually ran codex → log is codex JSONL, not claude JSON
• Parser misinterprets

Recommended fix: gate on the dev-side CLI:

local dev_cmd="${AGENT_DEV_CMD:-${AGENT_CMD:-claude}}"
[ "$dev_cmd" = "claude" ] || return 1

Note: this function is dev-side-only (it parses the dev wrapper's log, called from Step 4 of dispatcher-tick). Review-side has no analogous parsing path.

---

Verdict

This PR's lib-agent.sh + wrapper changes are correct for the typical (no-override) deployment. But Findings 2 + 3 are dispatcher-side coupling points that the PR's per-side feature exposes. Without fixing them, the first project to adopt AGENT_REVIEW_CMD=agy will hit false-negative liveness checks (Finding 2) and may hit log-parser misinterpretation under AGENT_DEV_CMD=codex (Finding 3).

Recommendation: hold this PR; address Findings 2+3 in this same PR (estimated +30 lines code, +2 test cases, ~30 minutes). Finding 1 is pre-existing and out of scope here — file as a separate issue.

agy conversation id: 56746887-b20e-4b6c-accb-c54fc3dd441b (for resume).

[zxkane]

Findings 2 + 3 addressed in commit 7675a90

Pushed a fix commit to this branch addressing Findings 2 + 3 from the agy review above.

What changed

Finding 2 — _pgid_has_agent_process now accepts an optional 2nd argument (per-side CLI override). Empty/missing falls back to $AGENT_CMD for back-compat.

• dev_near_success calls with ${AGENT_DEV_CMD:-${AGENT_CMD:-claude}}
• review_near_success calls with ${AGENT_REVIEW_CMD:-${AGENT_CMD:-claude}}

Finding 3 — is_session_completed gates on ${AGENT_DEV_CMD:-${AGENT_CMD:-claude}} (function parses the dev wrapper's log).

Tests:

• New tests/unit/test-pgid-has-agent-process.sh — 9 assertions (TC-PSC-COUP-01a..d). Spawns a controlled child via cp /bin/sleep $TMPDIR/fake-agy && setsid so its comm matches the test name.
• Extended tests/unit/test-is-session-completed.sh with TC-WH-005b — 3 assertions for split-CLI config.
• All peer tests still pass.

Spec/doc:

• docs/pipeline/per-side-agent-cmd.md — new §Dispatcher-side coupling section
• docs/pipeline/invariants.md — INV-37 Consumer field extended to name both dispatcher-side reads
• New test-cases doc at docs/test-cases/dispatcher-per-side-cmd-coupling.md

Finding 1 (pre-existing AGENT_*_EXTRA_ARGS mapped by stage not side) is NOT addressed in this PR — it's a pre-existing bug on origin/main with a different fix shape (likely AGENT_SIDE parameter to run_agent/resume_agent). Will file as a separate issue.

Verification

• bash tests/unit/test-pgid-has-agent-process.sh — 9/9 PASS
• bash tests/unit/test-is-session-completed.sh — 17/17 PASS
• Full unit suite — all PASS, zero regressions
• shellcheck -S error clean on lib-dispatch.sh + new test file

[zxkane]

agy re-review (after commit 7675a90)

Re-ran the local agy CLI to re-review after pushing the fix commit. agy resumed the prior conversation (56746887-b20e-4b6c-accb-c54fc3dd441b) and returned:

Verdict: CLEARED

The fixes in commit 7675a90 are correct and complete. They successfully resolve Findings 2 + 3 without introducing regressions.

Verified by agy:

1. Finding 2 resolved cleanly at lib-dispatch.sh:1290 (local agent_cmd="${2:-${AGENT_CMD:-claude}}"); callers dev_near_success / review_near_success correctly pass ${AGENT_DEV_CMD:-...} / ${AGENT_REVIEW_CMD:-...}.
2. Finding 3 resolved cleanly at lib-dispatch.sh:534 (local _dev_cmd="${AGENT_DEV_CMD:-${AGENT_CMD:-claude}}").
3. Back-compat: 1-arg calls to _pgid_has_agent_process and unset AGENT_DEV_CMD configs fall back to $AGENT_CMD / claude as expected.
4. Sweep check: agy grepped lib-dispatch.sh + dispatcher-tick.sh for $AGENT_CMD references and confirms no other dispatcher-side reads exist. (dispatcher-tick.sh has zero AGENT_CMD references; all reads in lib-dispatch.sh are now per-side.)
5. Test coverage: TC-PSC-COUP-01a..d and TC-WH-005b correctly exercise the new behaviors. All unit tests pass.
6. Shellcheck: clean.
7. Comments: accurately mirror new behavior.

Finding 1 (AGENT_*_EXTRA_ARGS mapped by stage not side) remains flagged as pre-existing on origin/main. As noted in the prior comment, that's out of scope for this PR — different fix shape (likely an AGENT_SIDE parameter to run_agent/resume_agent). Will file as a separate issue.

PR is ready for merge from agy's perspective. CI green (Unit Tests + ShellCheck + pipeline-docs gate all pass).