#5 - First Real Team — bounded retry, task_status, charter rewrite - Homelab/pi-extensions

aaron commented

2026-07-08 02:01:04 +00:00

Owner

First Real Team — bounded retry, `task_status`, charter rewrite

Reframes build-order step 3 off long-lived pull-claiming and onto the shipped assigned-claim/queue machinery, delivering the two things genuinely missing for a trustworthy team. Design: docs/2026-07-07-first-real-team-design.md; plan: docs/plans/2026-07-07-first-real-team.md.

Why the reframe

The in-memory queue + global semaphore already drains N tasks across M concurrent workers, and at the system's ≤20-agent design scale long-lived pullers save little; their real payoff (a cross-process delivery channel) is gated behind the deferred execution: process milestone. So pullers stay deferred and step 3 ships reliability + observability instead — all of it on-path for pull-claiming later, nothing thrown away.

What's in it

Bounded automatic retry in the runSwarm fan-out. A worker that hangs (lease-expired) or hits a transient error is re-spawned up to taskMaxAttempts (default 2); the best attempt per item is rendered. Contract violations and user aborts are never retried. Retries are exempt from a lead's max_team_size budget but still respect the global concurrency semaphore; maxAttempts bounds the loop (no infinite retry).
Explicit retriable classification set at every terminal path (AgentRecord → ChildResult), plus attempt/retryOf lineage on spec.json for post-mortem.
task_status — a read-only tool over the durable store (states, attempts, claim owners).
team-lead.md charter rewrite so the lead doesn't double-retry hangs, + a README note.

Known limitation (documented, not a regression)

Retry-on-hang relies on the root-only reconciler. Under a nested lead (depth ≥ 1) a genuinely hung worker blocks the lead's allTerminal — this is pre-existing (the prior single-pass fan-out awaited the same way) and is closed by step-4's spawn-health-check. Retry-on-transient-error works at every depth. Until step 4: drive teams from the root session, not autonomous nested leads.

Verification

Suite 316/316 green (was 295; +21 new tests), tsc --noEmit clean.
Built subagent-driven (TDD, fresh implementer + reviewer per task); every task review clean.
Final whole-branch review (opus): Ready to merge — Yes, 0 Critical / 0 Important defects.

Commits

7 implementation (c4bd1d7 → 1abf904) + design/plan + review-driven doc clarification.

🤖 Generated with Claude Code

https://claude.ai/code/session_015MWFoW4hyPkHYkC4AtgLhE

## First Real Team — bounded retry, `task_status`, charter rewrite Reframes build-order **step 3** off long-lived pull-claiming and onto the shipped assigned-claim/queue machinery, delivering the two things genuinely missing for a trustworthy team. Design: `docs/2026-07-07-first-real-team-design.md`; plan: `docs/plans/2026-07-07-first-real-team.md`. ### Why the reframe The in-memory queue + global semaphore already drains N tasks across M concurrent workers, and at the system's ≤20-agent design scale long-lived pullers save little; their real payoff (a cross-process delivery channel) is gated behind the deferred `execution: process` milestone. So pullers stay deferred and step 3 ships reliability + observability instead — all of it on-path for pull-claiming later, nothing thrown away. ### What's in it - **Bounded automatic retry** in the `runSwarm` fan-out. A worker that **hangs** (lease-expired) or hits a **transient error** is re-spawned up to `taskMaxAttempts` (default 2); the best attempt per item is rendered. **Contract violations and user aborts are never retried.** Retries are exempt from a lead's `max_team_size` budget but still respect the global concurrency semaphore; `maxAttempts` bounds the loop (no infinite retry). - Explicit `retriable` classification set at every terminal path (`AgentRecord` → `ChildResult`), plus `attempt`/`retryOf` lineage on `spec.json` for post-mortem. - **`task_status`** — a read-only tool over the durable store (states, attempts, claim owners). - **`team-lead.md`** charter rewrite so the lead doesn't double-retry hangs, + a README note. ### Known limitation (documented, not a regression) Retry-on-*hang* relies on the root-only reconciler. Under a nested lead (depth ≥ 1) a genuinely hung worker blocks the lead's `allTerminal` — this is **pre-existing** (the prior single-pass fan-out awaited the same way) and is closed by step-4's spawn-health-check. Retry-on-*transient-error* works at every depth. Until step 4: drive teams from the root session, not autonomous nested leads. ### Verification - Suite **316/316** green (was 295; +21 new tests), `tsc --noEmit` clean. - Built subagent-driven (TDD, fresh implementer + reviewer per task); every task review clean. - Final whole-branch review (opus): **Ready to merge — Yes**, 0 Critical / 0 Important defects. ### Commits 7 implementation (`c4bd1d7 → 1abf904`) + design/plan + review-driven doc clarification. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_015MWFoW4hyPkHYkC4AtgLhE

aaron added 10 commits

2026-07-08 02:01:05 +00:00

docs(team): first-real-team design — reframe step 3 off pull-claiming c0a747c86b

Bounded retry + task_status + team-lead charter rewrite on the shipped
assigned-claim/queue machinery. Defers long-lived pullers to execution:process
(step 5). Revises the task-store handoff's 'next: pull-claiming' priority.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015MWFoW4hyPkHYkC4AtgLhE

docs(team): first-real-team implementation plan (8 tasks, TDD) e29cfe80ef

Bounded retry (Tasks 1-5), task_status tool (Task 6), team-lead charter
rewrite (Task 7), green gate (Task 8). Full code + tests per step.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015MWFoW4hyPkHYkC4AtgLhE

feat(retry): classify records retriable at every terminal path c4bd1d78fd

feat(retry): isRetry budget bypass + attempt/retryOf spec lineage 8da75007f8

feat(retry): taskMaxAttempts setting (default 2) 6ce8731314

feat(retry): surface retriable on ChildResult d775657f1d

feat(retry): bounded retry attempt-loop in runSwarm f0a4287e38

feat(tasks): task_status read-only store observability tool f7c35b3172

docs(team): charter rewrite for auto-retry + task_status; README note 1abf904e87

docs(team): sharpen nested-lead hang limitation per final review ef9119d5fb

Final whole-branch review found the design understated the consequence: a
genuinely hung worker under a depth>=1 lead blocks the lead's allTerminal
forever (not merely un-retried), because the reconciler is root-only. This is
pre-existing (no regression) and closed by step-4's spawn-health-check; until
then drive teams from the root session. No code change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015MWFoW4hyPkHYkC4AtgLhE