task-recreate-worker launches through lib/agents (#239, step 1 of 2)

[martin-conur]

Part of #239 — the task-recreate-worker step. Per the spec this is one PR per script; task-reviewer follows in its own PR, so this one deliberately does not close the issue.

Reviewer: the spec issue is #239. There is no Closes line, so pass it explicitly: task-reviewer <this PR> 239.

What changed

The sidecar half is already done: #240 (PR #251) reads the ref with aw_tracker_info_key and builds the payload with aw_tracker_worker_prompt. This PR moves the rest of the command's agent handling onto the agent module:

• bin/task-recreate-worker now sources lib/agents/<agent>.sh, resolving both modules before sourcing them, the way task-work does.
• build_agent_cmd is gone. A fresh launch now uses aw_agent_launch_cmd.
• The direct aw_require_kiro_agent call is gone. The preflight now goes through aw_agent_preflight.
• The case "$AGENT" --resume gate is gone. A resume now goes through a new hook, aw_agent_resume_cmd <session-id>:
  • claude returns claude [--permission-mode auto ]--resume [<id>];
  • kiro refuses with the same message the inline gate printed.

About the new hook: this is the one hook #236/#237 did not define. task-work never resumes anything, so the module API is not missing something it should have had. A resume hook simply has no place in task-work.

What stays in the script: it still mines the session id from radio's log, because that is radio-log knowledge rather than agent knowledge.

Declared behaviour changes

• A refusal now comes before anything is written. The launch line, the kiro --resume refusal and the kiro preflight are now resolved before the report and the sidecar rewrite. Before, a kiro --resume printed the recovery report and stripped TAB_ID from the sidecar, and only then refused.
• A recovered kiro worker still gets kiro-cli's defaults. Composing kiro's aw_agent_init_flags would read task-work's TASK_WORK_MODEL / TASK_WORK_TRUST_ALL from the environment. A recovery could then relaunch a worker with --trust-all-tools that the original task-work run never gave it. Both variables are scrubbed for that one call.

Launch lines are otherwise byte-identical on every loadout. The existing per-tracker sidecar-ref rows from #240 pass unchanged. The unquoted MODEL in kiro's aw_agent_launch_cmd is #157's and is not touched here.

Tests

bats --count: 1306 at 735138f (main) → 1311. All 1311 pass under ./run_tests.sh.

New tests:

• task_recreate_worker.bats:
  • a kiro --resume refusal leaves the sidecar byte-identical;
  • TASK_WORK_MODEL=… TASK_WORK_TRUST_ALL=1 does not reach the kiro launch line;
  • --auto --resume keeps --permission-mode auto.
• loadout_modules.bats:
  • every impl's agent module defines aw_agent_resume_cmd;
  • deleting any tracker or agent module stops task-recreate-worker with a named error, not shell noise and not "no worktree".

Each new test was checked against a broken tree and went red:

• the old bin/task-recreate-worker fails the sidecar test and the missing-module test;

• removing the env scrub fails the trust-all test;

• renaming kiro's aw_agent_resume_cmd fails the hook-presence test.

• dropping mode_prefix from claude's aw_agent_resume_cmd fails the --auto --resume test. The old code produced the same line, so that test pins existing behaviour rather than a change.

Also green: tools/check-drift.sh (15 groups) and shellcheck -x on the three changed shell files.

No task-init re-run needed. The CHANGELOG entry is under [Unreleased] → Changed.

🤖 Generated with Claude Code

[martin-conur]

Spec compliance

PR #252 is step 1 of 2 per the #239 plan ("one PR per script"). It delivers everything the spec required for the task-recreate-worker leg:

• build_agent_cmd replaced by aw_agent_launch_cmd ✓
• aw_require_kiro_agent replaced by aw_agent_preflight ✓
• Inline --resume gate replaced by new aw_agent_resume_cmd hook in both agent modules ✓
• TASK_WORK_MODEL / TASK_WORK_TRUST_ALL scrubbed before aw_agent_init_flags ✓
• task-reviewer explicitly deferred to its own PR, as the spec's "one PR per script" plan allows ✓
• CHANGELOG updated under [Unreleased] ✓
• 5 new tests, all verified against broken trees per the mutation-check discipline ✓
• CI passed (run confirmed at fc4d87b) ✓

No spec deliverables are missing or off-spec for the declared step.

Code-review findings

The "refusal before state change" fix is correct and well-placed.

Tracing execution order confirms the behavioral improvement: the launch line block now sits at line 338 (after arg parsing at 136, before report at 412 and sidecar rewrite at 456). For kiro --resume, aw_agent_resume_cmd exits 1 at line 338, and the report, sidecar touch, and tab spawn never run. The test captures the sidecar before and after and asserts they are byte-identical — solid.

The TASK_WORK_MODEL="" TASK_WORK_TRUST_ALL="" aw_agent_init_flags scrub is correct.

In bash, prefix assignments on a shell function call are permanent in the current shell (unlike external commands). After the call, both vars are "" for the rest of the script. This is fine here: neither is read again after aw_agent_init_flags, and the scrub is the entire point. Worth a brief comment that the double-quoted-style persistence is intentional, but not a bug.

The kiro session-ID lookup runs before the refusal.

_resume_session_id (a file grep) is called unconditionally when RESUME is set, even for kiro where aw_agent_resume_cmd will refuse. The PR description acknowledges this: "On kiro the lookup is wasted, and harmless." Confirmed harmless — the function is read-only and exits cleanly regardless.

Module-loading order is correct.

_default.sh → tracker module → agent module, then aw_agent_init_flags, then arg parsing. AUTO_MODE is parsed in the arg-parsing section (line 136–160) and is already set by the time the launch block runs (line 338). aw_agent_launch_cmd / aw_agent_resume_cmd read AUTO_MODE at call time, so --auto --resume correctly produces claude --permission-mode auto --resume. The test pins this.

PLAN_MODE is set to "" by aw_agent_init_flags but never parsed.

For claude, aw_agent_init_flags sets PLAN_MODE="". task-recreate-worker's arg-parsing loop does not call aw_agent_parse_flag, and unknown flags return an error, so PLAN_MODE stays "" throughout. aw_agent_launch_cmd will never enter the plan branch. No issue; noting it for clarity.

loadout_modules.bats refactor is clean.

_tw_fakeroot_without gains a script="${3:-task-work}" parameter and a parameterized fakeroot dir name (fakeroot-$script-$1-$2 was tw-fakeroot-$1-$2). The new test confirms that task-recreate-worker names the missing module, not the absent worktree — exactly the "named error, not shell noise" property the spec asked for.

No issues with the aw_agent_preflight guard.

It's inside if [[ -z "$NO_LAUNCH" ]]; then, matching the old inline guard. A --resume --no-launch kiro run skips both the refusal and the preflight — same as before.

Verdict: clean

The implementation is correct across all loadouts. The behavioral improvement (kiro refusal before report and sidecar) is verified by test. Tests are well-targeted and were all mutation-checked. CI passed on the head commit. No blocking findings; the one wasteful kiro lookup is documented and harmless.

Ready to merge once task-reviewer (step 2) is in review and this branch has no outstanding merge conflicts.