[ai] Improve Codex subagent progress tracking.

.agents/skills/task-think/PROMPTS.md

@@ -9,19 +9,40 @@ Use these templates as Codex subagent messages. Use them as same-session checkli
 - Phase 7 runs in the main session on Windows because it depends on the final local diff and touched-file set.
 - Write each phase prompt to `.ai/<PROJECT>/<LETTER>/logs/phase-<name>.prompt.md` before execution.
 - If you delegate a phase, send the prompt file contents as the initial `spawn_agent` message.
-- When writing the phase prompt file, append the standard compact reply block below so the subagent knows exactly how to report completion.
+- When writing the phase prompt file, append the standard progress file contract and the standard compact reply block below so the subagent knows how to surface progress before the final artifact.
 - After each phase completes, write `.ai/<PROJECT>/<LETTER>/logs/phase-<name>.result.md` summarizing the status, files touched, and any follow-up notes.
 - Use `fork_context: false` by default. If the phase depends on thread-only context or UI attachments, pass that context explicitly or enable `fork_context` only for that phase.
 - Prefer `worker` for phases that write files. Use `default` for plan or review passes if that fits the host better. Use `explorer` only for narrow read-only questions.
 - When supported, request `model: gpt-5.4` and `reasoning_effort: xhigh` for delegated phases.
-- Default wait budget for delegated phases is 15 minutes. Use shorter waits only when the phase is intentionally tiny.
+- Default wait budget for delegated phases is 5 minutes while the phase is clearly still in progress. Successful completion may wake earlier, so this does not delay finished work.
-- A `wait_agent` timeout is not failure. On timeout, inspect expected artifact progress before deciding anything.
+- When a phase appears close to landing, use 1-2 minute waits until it finishes.
+- A `wait_agent` timeout is not failure. On timeout, inspect both the expected artifact and the matching progress file before deciding anything.
 - If the expected artifact exists and shows progress, wait again.
-- If no usable artifact exists yet, send one short follow-up asking the same agent to finish the required artifact and return the standard compact reply block, then wait again.
+- If the expected artifact is not ready but the progress file mtime moved or its heartbeat counter increased since the previous check, wait again. Prefer mtime checks first and avoid rereading the file unless you need detail. Do not count that as a failed wait.
-- If the same agent still produces no usable artifact after two 15-minute waits and one follow-up, close it and retry the phase in a fresh subagent.
+- If neither the expected artifact nor the progress file moved since the previous blocked check, send one short follow-up asking the same agent to refresh the progress file, finish the required artifact, and return the standard compact reply block, then wait again.
+- If the same agent still produces no usable artifact and no meaningful progress-file movement after two full default waits and one follow-up, close it and retry the phase in a fresh subagent.
 - For Phase 1, Phase 2, Phase 3, Phase 4, and Phase 6, if delegated retries still fail, stop and ask the user rather than rerunning the phase locally.
 - Never use `codex exec`, background shell child processes, or JSONL child-session logging from this skill.
 
+## Standard Progress File Contract
+
+Append this verbatim to every delegated phase prompt:
+
+```text
+Before deep work, create or update the matching progress file in `.ai/<PROJECT>/<LETTER>/logs/`.
+
+Use `<phase-name>.progress.md` as a concise heartbeat with:
+- `Heartbeat: <N>` on the first line, incremented on each meaningful update
+- Current step
+- Files being read or edited
+- Concrete findings or decisions so far
+- Blocker or next checkpoint
+
+Update it sparingly: preferably at natural milestones, and otherwise only after a longer quiet stretch such as roughly 5-10 minutes.
+Keep it tiny so the parent can usually rely on file mtime or the heartbeat counter instead of rereading the whole file.
+Do not wait until the final artifact to write progress.
+```
+
 ## Standard Compact Reply Block
 
 Append this verbatim to every delegated phase prompt:
@@ -499,7 +520,7 @@ When all phases, including build verification, code review, and Windows line end
 
 ## Error Handling
 
-- If any phase fails or gets stuck, follow the timeout and retry rules above. For Phase 1, Phase 2, Phase 3, Phase 4, and Phase 6, do not rerun locally after a timeout; ask the user if delegated retries fail.
+- If any phase fails or gets stuck, follow the timeout and retry rules above. Do not close an agent solely because the final artifact is missing while its progress file is still advancing. For Phase 1, Phase 2, Phase 3, Phase 4, and Phase 6, do not rerun locally after delegated retries fail; ask the user instead.
 - If `context.md` or `plan.md` is not written properly by a phase, rerun that phase in a fresh subagent with more specific instructions.
 - If build errors persist after the build phase's attempts, report the remaining errors to the user.
 - If a review-fix phase introduces new build errors that it cannot resolve, report to the user.
@@ -509,7 +530,8 @@ When all phases, including build verification, code review, and Windows line end
 For each phase:
 1. Write the full prompt to `.ai/<PROJECT>/<LETTER>/logs/phase-<name>.prompt.md`
 2. Delegate by sending that prompt text to a fresh subagent, or use it as a same-session checklist only for the designated main-session phases or when delegation was unavailable from the start
-3. Save a concise completion note to `.ai/<PROJECT>/<LETTER>/logs/phase-<name>.result.md`
+3. For delegated phases, expect a matching `.ai/<PROJECT>/<LETTER>/logs/phase-<name>.progress.md` heartbeat while work is in flight
+4. Save a concise completion note to `.ai/<PROJECT>/<LETTER>/logs/phase-<name>.result.md`
 
 For review iterations, include the iteration in the file name, for example:
 - `phase-6a-review-1.prompt.md`
@@ -523,9 +545,12 @@ Use this pattern conceptually for delegated phases:
 
 1. Write the phase prompt file.
 2. Spawn a fresh subagent with the phase prompt, usually with `fork_context: false`.
-3. Wait in 15-minute intervals when the next step is blocked on that phase, checking artifact progress on timeout.
+3. Require the agent to create the matching progress file early and refresh it sparingly: at natural milestones when possible, otherwise only after a longer quiet stretch such as roughly 5-10 minutes.
-4. If needed, send one short follow-up to the same agent, then retry once with a fresh subagent before involving the user.
+4. Wait in 5-minute intervals when the next step is blocked on that phase, checking both the final artifact and the progress file on timeout.
-5. Validate the expected artifact or code changes with small shell summaries and the completion checks above.
+5. When the phase looks close to finishing, switch to 1-2 minute waits.
-6. Write the result log from the validated outcome and the compact reply block.
+6. Prefer filesystem mtime checks on the progress file first. If its mtime moved or the heartbeat counter increased, keep waiting; do not treat that as a stall.
+7. If neither the artifact nor the progress file moves, send one short follow-up to the same agent, then retry once with a fresh subagent before involving the user.
+8. Validate the expected artifact or code changes with small shell summaries and the completion checks above.
+9. Write the result log from the validated outcome and the compact reply block.
 
 Do not replace this pattern with shell-launched `codex exec`.

.agents/skills/task-think/SKILL.md

@@ -33,6 +33,7 @@ Project structure:
     review3.md
     logs/
       phase-*.prompt.md
+      phase-*.progress.md
       phase-*.result.md
   b/                    # Follow-up task
     context.md
@@ -55,9 +56,11 @@ Create and maintain:
 - `.ai/<project-name>/<letter>/plan.md`
 - `.ai/<project-name>/<letter>/review<R>.md` (up to 3 review iterations)
 - `.ai/<project-name>/<letter>/logs/phase-<name>.prompt.md`
+- `.ai/<project-name>/<letter>/logs/phase-<name>.progress.md` for delegated phases
 - `.ai/<project-name>/<letter>/logs/phase-<name>.result.md`
 
 Each `phase-<name>.result.md` should capture a concise outcome summary: whether the phase completed, which files it touched, and any follow-up notes or blockers.
+Each delegated `phase-<name>.progress.md` should act as a heartbeat: a tiny monotonic counter plus current step, files being read or edited, concrete findings so far, and the next checkpoint. It is not a final artifact; it exists so the parent can distinguish active research from a truly stuck subagent without rereading large context.
 
 ## Phases
 
@@ -85,12 +88,17 @@ Use Codex subagents as the primary orchestration mechanism.
 - Keep `fork_context` off by default. Pass the phase prompt and explicit file paths instead of the whole thread unless the phase truly needs prior conversational context or thread-only attachments.
 - When the platform supports it, request `model: gpt-5.4` and `reasoning_effort: xhigh` for spawned phase agents. If overrides are unavailable, inherit the current session settings.
 - Write the exact phase prompt to the matching `logs/phase-<name>.prompt.md` file before you delegate. Use the same prompt file as a checklist if you later need to fall back to same-session execution.
+- For delegated phases, require an early `logs/phase-<name>.progress.md` heartbeat before deep work. The subagent should create or update it early, keep it tiny, and refresh it sparingly: preferably at natural milestones, and otherwise only after a longer quiet stretch such as roughly 5-10 minutes.
 - In every delegated prompt, require a compact final reply with only status, artifact paths, touched files, and blocker or `none`. Detailed reasoning belongs in `.ai/` artifacts, not in the chat reply.
 - After a subagent finishes, verify that the expected artifacts or code changes exist, then write a short result log in `logs/phase-<name>.result.md`.
-- For delegated phases, use `wait_agent` with a 15-minute timeout by default. A timeout is not a failure; it only means no final status arrived yet.
+- For delegated phases, use `wait_agent` with a 5-minute timeout by default while a phase is still clearly in progress. Successful completion may wake earlier, so this does not add latency to finished phases.
-- On timeout, inspect the expected artifact and worktree for progress first. If progress exists, wait again.
+- When a phase looks close to completion — for example the final artifact has appeared, a build is in its final pass, or the agent said it is wrapping up — switch to 1-2 minute waits until it lands.
-- If no usable artifact exists yet, send one short follow-up asking the same subagent to finish writing the artifact and return the compact status block, then wait again.
+- A timeout is not a failure; it only means no final status arrived yet. Do not treat short waits as stall detection for research-heavy phases.
-- If the same subagent still produces no usable artifact after two 15-minute waits and one follow-up, close it and rerun that phase in a fresh subagent.
+- On timeout, inspect the expected artifact, the phase progress file mtime, and the worktree for movement. Prefer mtime checks first; only reread the progress file when you need detail.
+- If the progress file mtime moved or its heartbeat counter increased since the previous check, treat that as active progress and wait again.
+- If no usable final artifact exists yet but the progress file is appearing or advancing, keep the same subagent alive. Progress-file movement does not count toward the retry limit.
+- If no usable final artifact exists yet and neither the expected artifact nor the progress file has moved since the previous blocked check, send one short follow-up asking the same subagent to refresh the progress file, finish the artifact, and return the compact status block, then wait again.
+- Only if the same subagent still shows no meaningful movement in either the expected artifact or the progress file after two full default waits and one follow-up should you close it and rerun that phase in a fresh subagent.
 - Use `wait_agent` only when the next step is blocked on the result. While the delegated phase runs, do small non-overlapping local tasks such as validating directory structure or preparing the next prompt file.
 - Build verification is critical-path work. Prefer running the build in the main session, and only delegate a bounded build-fix phase when there is a concrete reason.
 - If subagents are unavailable in the current environment, or current policy does not allow delegation from the start, run the phase in the main session using the same prompt files. Otherwise, do not switch a pre-build phase to same-session midstream. Never fall back to shell-spawned `codex exec` child processes from this skill.
@@ -117,7 +125,7 @@ Mark complete only when:
 
 ## Error Handling
 
-- If any phase fails, times out, or gets stuck, follow the retry ladder from Execution Mode. After two delegated attempts remain blocked, report the issue to the user. Do not absorb the phase into the main session before build unless delegation was unavailable from the start.
+- If any phase fails, times out, or gets stuck, follow the retry ladder from Execution Mode. Do not close an agent solely because the final artifact is missing while its progress file is still moving. After two delegated attempts remain blocked with no meaningful progress, report the issue to the user. Do not absorb the phase into the main session before build unless delegation was unavailable from the start.
 - If `context.md` or `plan.md` is not written properly by a phase, rerun that phase in a fresh subagent with more specific instructions. Do not repair it locally before build unless delegation was unavailable from the start.
 - If build errors persist after the build phase's attempts, report the remaining errors to the user.
 - If a review-fix phase introduces new build errors that it cannot resolve, report to the user.