task-work silently writes no TAB_ID when the tab lookup misses: report and log the miss at launch (#242)

[martin-conur]

Closes #242

What changed

Part 1: the miss is loud, logged, and never fatal. aw_record_tab_id in lib/zellij-tab.sh replaces the silent capture block in:

• all seven task-work copies (the drift-guarded info-tab-id region)
• both task-reviewer copies and task-recreate-worker, which had the same three lines

When the lookup misses, it prints on stderr why, names the slug it searched for, and appends a line to ~/.task-force/radio/log (tab-id: <caller> capture missed slug=… reason=… info=… detail=…). The reasons it tells apart:

• no-zellij-bin: zellij is not on PATH
• not-in-zellij: $ZELLIJ is unset
• no-jq: jq is not on PATH
• list-tabs-empty: zellij listed nothing
• race: the tab is listed by the time the diagnosis re-queries
• no-match: carries the slug's length and every tab name zellij reported, JSON-quoted, so a byte-level mismatch shows in the line itself

A successful capture prints nothing, so output is unchanged (regression test included). A miss still lets the worker launch.

The two ends are linked. task-done's Skipping zellij close-tab (no tab id captured …) line gains a second line naming which source was empty:

• $ZELLIJ unset
• no sidecar at the path it derived from the branch
• a sidecar with no TAB_ID=, with the exact grep 'tab-id:.*slug=<slug> ' …/radio/log that finds the launch-time line

The reason is worked out when the id is read, because the sidecar is deleted before the close step reports it. task-done still never falls back to the unscoped close-tab (#107 / #108).

Part 2: the trigger was not reproduced

I could not reproduce the trigger. The issue's evidence turns out to have a simpler explanation:

• All nine sidecars without a TAB_ID (gdi-chatbot) have mtimes of 2026-05-12 to 2026-05-14. The capture was added by Fix #117: preserve TAB_ID across re-register; persist TAB_ID in $INFO_FILE #118 on 2026-05-24, so they predate the feature. Every sidecar on this machine written since has its TAB_ID.
• I checked both suspected shapes against a real zellij 0.44.2 in a detached session (zellij attach --create-background, not the live one). The 50-character bug-model-renders-table-but-the-chat-already-outpu, its 56-character collision form …-hu1s5, and add-readme-7qegu all came back byte-equal from list-tabs --json, matched right after new-tab.

So the intermittent reports come from a condition those artifacts do not record. The next one will name itself in one line. That also covers misses on task-done's side, which are not capture failures at all: a branch switched away from task/<slug> (no sidecar found), or task-done run outside zellij.

Sequencing: #237

This change lives in task-work's info-tab-id region, which #237 (the tracker × agent split from #122 Phase 2) deletes and relocates. #237 must carry this forward into its new modules, not reinvent it. The behaviour lives in lib/zellij-tab.sh (aw_record_tab_id), so in practice the relocated code just needs to call it.

Docs

• A new "When radio misbehaves" row in the README, the seven steering templates and the dogfood .claude/gh-workflow.md.
• A runbook test that checks the documented grep string is one lib/zellij-tab.sh actually logs.
• A CHANGELOG entry. Upgrading needs no task-init re-run: the scripts reach machines through symlinks. A re-run only adds the new runbook row to an installed workflow doc.

Verification

• ./run_tests.sh: 1393/1393 (baseline 1380 + 13 new). Most are in tests/tab_id_capture.bats; it covers each reason code, a miss with zero exit and a log line, a silent hit, the kiro-gh loadout, and the three task-done reasons. One more is in tests/radio_runbook.bats.
• tools/check-drift.sh: 35 groups clean.
• shellcheck -x: clean on every changed shell file.

🤖 Generated with Claude Code

[martin-conur]

Spec compliance

Issue #242 specified two parts:

Part 1 — loud, logged, non-fatal capture. ✅ Fully delivered. aw_record_tab_id in lib/zellij-tab.sh replaces the silent three-line block in all seven task-work copies (drift-guarded info-tab-id region), both task-reviewer copies, and task-recreate-worker. On a miss it prints to stderr with the reason and slug, appends a tab-id: line to radio's log with six structured fields, and still lets the launch succeed. A hit prints nothing (regression-pinned in tests). All six reason codes (no-zellij-bin, not-in-zellij, no-jq, list-tabs-empty, race, no-match) are wired through from aw_zellij_tab_id_miss_reason.

Part 2 — find the trigger. ✅ Honestly assessed. The PR provides a solid analysis: all nine sidecars without TAB_ID predate the feature (mtimes 2026-05-12/14 vs. feature landing 2026-05-24), and both suspected shapes (50-char truncation, collision suffixes) were verified byte-equal against real zellij 0.44.2. The trigger remains unknown, and the PR is transparent about that rather than overclaiming.

task-done linking. ✅ The skip message now adds a second line that distinguishes $ZELLIJ unset, no sidecar, and sidecar-with-no-TAB_ID= (with the exact grep string to find the launch-time log line). The $INFO_FILE is deleted before that step runs — the code correctly pre-computes which source is empty before deletion.

Constraints respected. ✅ No fallback to unscoped close-tab (#107/#108). Drift guard covers all seven info-tab-id region files (check-drift.sh line 32). Docs updated in README, .claude/gh-workflow.md, all five steering templates, and CHANGELOG. Runbook test pins the grep 'tab-id:' string against the function that emits it.

CI. ✅ Green, 1 run for head commit 1cda772 (gh run list -c <sha> returns databaseId: 37008325950, conclusion: success). 1393/1393 tests (baseline 1380 + 13 new).

---

Code-review findings

Nit 1 — no-zellij-bin undocumented in runbook rows and untested

lib/zellij-tab.sh:61 defines the no-zellij-bin code, the PR description lists all six codes, but every runbook table row added in this PR (README, .claude/gh-workflow.md, five steering templates) lists only five: not-in-zellij, no-jq, list-tabs-empty, race, no-match. A user grepping a log line with reason=no-zellij-bin would find it undocumented. There is also no direct test for this code path — the no-jq test places a zellij stub on PATH, so zellij is always present; removing the stub would exercise no-zellij-bin.

Fix: add no-zellij-bin to the reason-code list in the runbook rows (seven files), and add one test case:

@test "miss reason: no-zellij-bin when zellij is not on PATH" {
  NOJQ_BIN=$(make_nojq_bin)   # temp dir with no binaries
  run env PATH="$NOJQ_BIN" bash -c 'source "$1"; aw_zellij_tab_id_miss_reason "$2"' \
      _ "$REPO_ROOT_REAL/lib/zellij-tab.sh" my-feature
  assert_success
  assert_output --regexp '^no-zellij-bin '
}

Nit 2 — no direct tests for task-reviewer / task-recreate-worker callers

tests/tab_id_capture.bats covers the task-work caller and the kiro-gh loadout. bin/task-reviewer, claude-gh/bin/task-reviewer, kiro-gh/bin/task-reviewer, and bin/task-recreate-worker were each changed from the inline three-line block to aw_record_tab_id, but none has a test that checks the log line names caller=task-reviewer or caller=task-recreate-worker. A future refactor that accidentally passes the wrong caller string would be invisible to the test suite.

Not a blocker — the shared function path is well-covered — but worth adding a brief cross-loadout smoke test similar to the kiro-gh test for at least task-reviewer.

Nit 3 — triple list-tabs --json round-trip on the miss path

aw_record_tab_id calls aw_zellij_tab_id_by_name (one list-tabs call), then aw_zellij_tab_id_miss_reason immediately calls list-tabs again for the names array, then calls aw_zellij_tab_id_by_name a third time for the race-detection re-query. The data from the first call is discarded rather than passed through. Three synchronous zellij IPC round-trips on every miss.

This is the correct trade-off for now — the race re-query genuinely needs to be a fresh call, and the diagnostic function's clean interface matters more than micro-optimising a failure path. Noting it because the no-match detail line includes the full tab-names JSON, so any future reader wondering why it runs list-tabs twice in the miss branch will want this context.

---

Pre-existing issues observed (out of this PR's scope)

The code-review scan surfaced two classes of pre-existing issue in files not touched by this PR:

1. Indented heredoc terminators in command prompts. claude-gh/commands/reviewer.md (and worker.md, planner.md, pm.md) show heredoc terminators with leading spaces in their code examples, which contradicts the prose rule this PR's reviewer prompt teaches. A model agent copying the example literally would emit an unterminated heredoc. These files were not changed here; worth a separate issue.

2. Model-filled slot in a double-quoted --body string. claude-local/commands/planner.md has --body "spec written into tasks/NNN-slug.md, ready to dispatch" where NNN-slug is model-filled — if a task slug ever contained a backtick or $, the shell would silently execute or drop it. Pre-existing, out of scope here.

---

Verdict

clean-with-nits

The spec is fully satisfied, CI is green, the failure shape is correctly diagnosed and fixed, and the approach (loud-at-launch, logged, non-fatal) is right. The nits above are all fixable in this PR: the no-zellij-bin documentation gap is a one-liner across seven files, the missing test is small, and the triple-call note needs no code change (just a comment or a future follow-up). None blocks merge — PM's call on whether to loop the worker for the doc/test nits before landing.