@chankov/agent-fleet 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,10 +3,10 @@ name: deep-researcher
3
3
  description: Read-only deep reconnaissance for hard, ambiguous, or high-stakes questions — traces cross-cutting call paths, maps unfamiliar subsystems, and synthesizes findings across many files with file:line citations. Never edits or runs commands.
4
4
  tools: read,grep,find,ls
5
5
  kind: research
6
- model: openai-codex/gpt-5.5
6
+ model: openai-codex/gpt-5.6-sol
7
7
  models:
8
- - openai-codex/gpt-5.4
9
- - openai-codex/gpt-5.3-codex-spark
8
+ - openai-codex/gpt-5.6-terra
9
+ - openai-codex/gpt-5.6-luna
10
10
  - ollama/nemotron-3-ultra:cloud
11
11
  - ollama/glm-5.2:cloud
12
12
  thinking: high
@@ -2,8 +2,10 @@
2
2
  name: documenter
3
3
  description: Documentation and README generation
4
4
  tools: read,write,edit,grep,find,ls
5
- model: openai-codex/gpt-5.5
5
+ model: openai-codex/gpt-5.6-terra
6
6
  models:
7
+ - openai-codex/gpt-5.6-luna
8
+ - openai-codex/gpt-5.3-codex-spark
7
9
  - ollama/glm-5.2:cloud
8
10
  - ollama/nemotron-3-ultra:cloud
9
11
  thinking: minimal
@@ -2,8 +2,10 @@
2
2
  name: orchestrator
3
3
  description: Verification-Contract orchestrator — plans, builds, and verifies in small slices, owns the acceptance assertions, and requires runtime proof before "done"; biased to correctness and reversibility, confirms before risky steps.
4
4
  kind: orchestrator
5
- model: openai-codex/gpt-5.5
5
+ model: openai-codex/gpt-5.6-sol
6
6
  models:
7
+ - openai-codex/gpt-5.6-terra
8
+ - openai-codex/gpt-5.6-luna
7
9
  - ollama/minimax-m3:cloud
8
10
  - ollama/nemotron-3-ultra:cloud
9
11
  thinking: xhigh
@@ -30,8 +32,8 @@ Before any non-trivial work, read `skills/orchestration-verification/SKILL.md`
30
32
  - **Recon before action.** When a request touches unfamiliar code, dispatch a researcher to map the terrain before dispatching a builder.
31
33
  - **Plan explicitly.** For anything beyond a trivial change, dispatch a planner (and a plan reviewer if the team has one) before any implementation. Relay document artifacts by path: plans, reviews, inventories, critiques, and evidence reports should be written under the real session path `.pi/agent-sessions/artifacts/<kind>/<agentKey>-run<N>.md` and passed downstream as artifact-relative `artifacts/<kind>/<agentKey>-run<N>.md` paths (while preserving planner PLAN_FILE behavior). Downstream dispatches should receive those paths through `artifacts: [...]` instead of pasted document bodies.
32
34
  - **Gate work through skills.** Before implementation or risky work, require skill discovery via `skills/using-agent-skills/SKILL.md`; unclear requirements go through spec/planning skills first, implementation tasks need plan/review gates, and security-sensitive work includes `security-and-hardening`. Name the selected skills in specialist tasks and ask each specialist to report which skills they followed plus verification evidence. Skills are active workflows, not passive docs.
33
- - **Light research for simple reads.** For low-risk, read-only recon — simple counts, grep/search, docs reading, quick summaries — use `spawn_research(persona: "researcher")` (fast `gpt-5.3-codex-spark`).
34
- - **Deep research for hard reconnaissance.** For ambiguous, cross-cutting, or high-stakes investigation — the parity inventory above, tracing tricky call paths, mapping unfamiliar subsystems, security-relevant reads, or weighing many files before a big change — use `spawn_research(persona: "deep-researcher")` (`gpt-5.5` / xhigh). When evidence is thin, prefer a deep pass over guessing.
35
+ - **Light research for simple reads.** For low-risk, read-only recon — simple counts, grep/search, docs reading, quick summaries — use `spawn_research(persona: "researcher")` (`openai-codex/gpt-5.6-luna` with low thinking for simple, low-risk read-only recon).
36
+ - **Deep research for hard reconnaissance.** For ambiguous, cross-cutting, or high-stakes investigation — the parity inventory above, tracing tricky call paths, mapping unfamiliar subsystems, security-relevant reads, or weighing many files before a big change — use `spawn_research(persona: "deep-researcher")` (`openai-codex/gpt-5.6-sol` with high thinking). When evidence is thin, prefer a deep pass over guessing.
35
37
  - **Escalate non-research complexity by persona.** For architecture planning, complex debugging, security audits, large refactors, or deep code review, dispatch the appropriate specialist — `dispatch_agent` takes no model argument, so routing IS persona selection.
36
38
  - **Personas carry their own model.** Both research personas bring their own model/thinking; any `model` argument is ignored when a `persona` is set. Pick the persona that fits the task — don't pass raw model strings.
37
39
  - **Use advisory dispatch scope for builders.** When dispatching a builder for a planned implementation task, derive `scope: [...]` from that task's file list/path inventory so side-changes are surfaced. Skip `scope` for exploratory, planning, or reconnaissance work where the file set is not known. Scope violations are advisory only: the hub reports `details.scopeViolations` and a warning, but never auto-reverts, auto-escalates, or blocks progress. Concurrent writable dispatches have approximate attribution; treat overlap warnings as "inspect the diff" rather than proof of which agent changed which file.
@@ -2,20 +2,20 @@
2
2
  name: plan-reviewer
3
3
  description: Plan critic — reviews, challenges, and validates implementation plans
4
4
  tools: read,grep,find,ls
5
- model: openai-codex/gpt-5.5
5
+ model: openai-codex/gpt-5.6-sol
6
6
  models:
7
- - openai-codex/gpt-5.4
8
- - openai-codex/gpt-5.3-codex-spark
7
+ - openai-codex/gpt-5.6-terra
8
+ - openai-codex/gpt-5.6-luna
9
9
  - ollama/nemotron-3-ultra:cloud
10
10
  - ollama/glm-5.2:cloud
11
11
  thinking: high
12
12
  delegate_depth: 1
13
13
  subagents:
14
14
  feasibility:
15
- model: openai-codex/gpt-5.4
15
+ model: openai-codex/gpt-5.6-terra
16
16
  tools: read,grep,find,ls
17
17
  deps:
18
- model: openai-codex/gpt-5.3-codex-spark
18
+ model: openai-codex/gpt-5.6-luna
19
19
  tools: read,grep,find,ls
20
20
  ---
21
21
  You are a plan reviewer agent. Your job is to critically evaluate implementation plans.
package/agents/planner.md CHANGED
@@ -2,23 +2,23 @@
2
2
  name: planner
3
3
  description: Architecture and implementation planning — produces a written PLAN file with dependency-ordered tasks and acceptance criteria. Use when work spans multiple files or needs a task breakdown before building.
4
4
  tools: read,grep,find,ls,bash,write
5
- model: openai-codex/gpt-5.5
5
+ model: openai-codex/gpt-5.6-sol
6
6
  models:
7
- - openai-codex/gpt-5.4
8
- - openai-codex/gpt-5.3-codex-spark
7
+ - openai-codex/gpt-5.6-terra
8
+ - openai-codex/gpt-5.6-luna
9
9
  - ollama/nemotron-3-ultra:cloud
10
10
  - ollama/glm-5.2:cloud
11
11
  thinking: xhigh
12
12
  delegate_depth: 1
13
13
  subagents:
14
14
  scout:
15
- model: openai-codex/gpt-5.3-codex-spark
15
+ model: openai-codex/gpt-5.6-luna
16
16
  tools: read,grep,find,ls
17
17
  rules:
18
- model: openai-codex/gpt-5.3-codex-spark
18
+ model: openai-codex/gpt-5.6-luna
19
19
  tools: read,grep,find,ls
20
20
  risk:
21
- model: openai-codex/gpt-5.4
21
+ model: openai-codex/gpt-5.6-terra
22
22
  tools: read,grep,find,ls
23
23
  ---
24
24
  You are a planner agent. Analyze requirements and produce a clear, actionable implementation plan, delivered as a written plan document.
@@ -2,8 +2,10 @@
2
2
  name: releaser
3
3
  description: Release owner — cuts versions and ships; runs the changeset → version-bump → tag flow on request.
4
4
  color: #059669
5
- model: openai-codex/gpt-5.5
5
+ model: openai-codex/gpt-5.6-terra
6
6
  models:
7
+ - openai-codex/gpt-5.6-sol
8
+ - openai-codex/gpt-5.6-luna
7
9
  - ollama/glm-5.2:cloud
8
10
  - ollama/nemotron-3-ultra:cloud
9
11
  thinking: low
@@ -3,10 +3,10 @@ name: researcher
3
3
  description: Read-only reconnaissance — searches code, reads files and docs, and reports findings with file:line citations. Never edits or runs commands.
4
4
  tools: read,grep,find,ls
5
5
  kind: research
6
- model: openai-codex/gpt-5.3-codex-spark
6
+ model: openai-codex/gpt-5.6-luna
7
7
  models:
8
- - openai-codex/gpt-5.5
9
- - openai-codex/gpt-5.4
8
+ - openai-codex/gpt-5.6-sol
9
+ - openai-codex/gpt-5.6-terra
10
10
  - ollama/nemotron-3-ultra:cloud
11
11
  - ollama/minimax-m3:cloud
12
12
  thinking: low
@@ -2,23 +2,23 @@
2
2
  name: security-auditor
3
3
  description: Security engineer focused on vulnerability detection, threat modeling, and secure coding practices. Use for security-focused code review, threat analysis, or hardening recommendations.
4
4
  tools: read,bash,grep,find,ls
5
- model: openai-codex/gpt-5.5
5
+ model: openai-codex/gpt-5.6-sol
6
6
  models:
7
- - openai-codex/gpt-5.4
8
- - openai-codex/gpt-5.3-codex-spark
7
+ - openai-codex/gpt-5.6-terra
8
+ - openai-codex/gpt-5.6-luna
9
9
  - ollama/nemotron-3-ultra:cloud
10
10
  - ollama/glm-5.2:cloud
11
11
  thinking: xhigh
12
12
  delegate_depth: 1
13
13
  subagents:
14
14
  recon:
15
- model: openai-codex/gpt-5.3-codex-spark
15
+ model: openai-codex/gpt-5.6-luna
16
16
  tools: read,grep,find,ls
17
17
  input-sweep:
18
- model: openai-codex/gpt-5.4
18
+ model: openai-codex/gpt-5.6-terra
19
19
  tools: read,grep,find,ls
20
20
  secrets-sweep:
21
- model: openai-codex/gpt-5.3-codex-spark
21
+ model: openai-codex/gpt-5.6-luna
22
22
  tools: read,grep,find,ls
23
23
  ---
24
24
 
@@ -2,10 +2,10 @@
2
2
  name: test-engineer
3
3
  description: QA engineer specialized in test strategy, test writing, and coverage analysis. Use for designing test suites, writing tests for existing code, or evaluating test quality.
4
4
  tools: read,write,edit,bash,grep,find,ls
5
- model: openai-codex/gpt-5.5
5
+ model: openai-codex/gpt-5.6-terra
6
6
  models:
7
- - openai-codex/gpt-5.4
8
- - openai-codex/gpt-5.3-codex-spark
7
+ - openai-codex/gpt-5.6-sol
8
+ - openai-codex/gpt-5.6-luna
9
9
  - ollama/kimi-k2.7-code:cloud
10
10
  - ollama/glm-5.2:cloud
11
11
  - ollama/nemotron-3-ultra:cloud
@@ -13,10 +13,10 @@ thinking: medium
13
13
  delegate_depth: 1
14
14
  subagents:
15
15
  coverage-scout:
16
- model: openai-codex/gpt-5.3-codex-spark
16
+ model: openai-codex/gpt-5.6-luna
17
17
  tools: read,grep,find,ls
18
18
  conventions:
19
- model: openai-codex/gpt-5.3-codex-spark
19
+ model: openai-codex/gpt-5.6-luna
20
20
  tools: read,grep,find,ls
21
21
  ---
22
22
 
@@ -1,10 +1,10 @@
1
1
  ---
2
2
  name: web-debugger
3
3
  description: Interactive headful Chrome debugging via Chrome DevTools MCP — live DOM snapshots, console, network, and performance traces. Use when you need runtime-UI verification in a real browser, network/console inspection, or performance profiling with a human in the loop. Runs as a coms peer that loads the chrome-devtools-mcp extension. Keywords - chrome, devtools, headful, debug, network, console, performance, runtime-ui, profiling.
4
- model: openai-codex/gpt-5.5
4
+ model: openai-codex/gpt-5.6-terra
5
5
  models:
6
- - openai-codex/gpt-5.4
7
- - openai-codex/gpt-5.3-codex-spark
6
+ - openai-codex/gpt-5.6-sol
7
+ - openai-codex/gpt-5.6-luna
8
8
  - ollama/glm-5.2:cloud
9
9
  color: cyan
10
10
  skills:
@@ -2,10 +2,10 @@
2
2
  name: web-performance-auditor
3
3
  description: Web performance engineer focused on Core Web Vitals, loading, rendering, and network optimization. Use for performance-focused audits, CWV analysis, and identifying structural performance anti-patterns in web applications.
4
4
  tools: read,bash,grep,find,ls
5
- model: openai-codex/gpt-5.5
5
+ model: openai-codex/gpt-5.6-terra
6
6
  models:
7
- - openai-codex/gpt-5.4
8
- - openai-codex/gpt-5.3-codex-spark
7
+ - openai-codex/gpt-5.6-sol
8
+ - openai-codex/gpt-5.6-luna
9
9
  - ollama/nemotron-3-ultra:cloud
10
10
  - ollama/glm-5.2:cloud
11
11
  thinking: high
@@ -173,10 +173,26 @@ The `justfile` sets `dotenv-load`, so a `.env` file at the repo root is auto-loa
173
173
  | `AZURE_SPEECH_KEY` | `pi-voice-stt` (azure backend) | Azure Speech resource key |
174
174
  | `AZURE_SPEECH_ENDPOINT` | `pi-voice-stt` (azure backend) | Azure resource endpoint, used when `provider.endpoint` is unset |
175
175
  | `PI_STT_CONFIG` / `PI_STT_KEYBIND` | `pi-voice-stt` | Override config (inline JSON or path) / the record hotkey (default `alt+s`) |
176
+ | `AGENT_FLEET_SPAWN_DELAY` | `_peer` / `_peer-plus` recipes | Seconds to sleep before launching pi in a fleet pane (set per pane by `team-up`/`team-resume`, see below) |
176
177
 
177
178
  The `chrome-devtools-mcp` server starts once at extension load, so changing its vars needs a pi
178
179
  restart / `/reload` to take effect.
179
180
 
181
+ ### Spawn pre-warm/stagger
182
+
183
+ pi loads its credential store (`~/.pi/agent/auth.json`) once at boot under a short-retry
184
+ file lock. When the stored OAuth token is stale, the first pi to boot refreshes it over
185
+ the network *while holding that lock*; sibling panes spawned in the same instant (as
186
+ `just team-up` / `just hub-team` / `just team-resume` do) lose the lock race and come up
187
+ with every provider showing **unconfigured**. To dodge this, the team scripts check
188
+ `auth.json` before spawning (only `type`/`expires` are read — values never leave the
189
+ process): if any OAuth credential is expired or about to expire, one pi pane (the hub
190
+ when present, else the first pi peer) starts immediately and refreshes the token, and
191
+ every other pi pane gets `AGENT_FLEET_SPAWN_DELAY` in its pane env — the `_peer` /
192
+ `_peer-plus` recipes sleep that many seconds before launching pi. Fresh tokens mean zero
193
+ delay everywhere; `claude-code` runner panes never wait. Pure logic in
194
+ `scripts/lib/spawn-stagger.ts` (under `node --test`).
195
+
180
196
  ---
181
197
 
182
198
  ## Supporting data
package/justfile CHANGED
@@ -67,15 +67,18 @@ hub-solo *args:
67
67
  # Internal helper for team-up: launch a reusable coms peer (coms + compact-and-continue + a persona).
68
68
  # Prints a colored identity banner (peer name + persona purpose) before pi starts,
69
69
  # so every pane announces who lives in it — works in any terminal, herdr or not.
70
+ # AGENT_FLEET_SPAWN_DELAY (set per pane by team-up when the stored pi OAuth token
71
+ # is stale) delays this pi's boot so a sibling pane can refresh the token first —
72
+ # simultaneous boots race on the auth.json lock and lose their logins.
70
73
  # Hidden from `just --list` because recipes prefixed with `_` are private.
71
74
  _peer persona name="" model="" session="" project="default":
72
- node --experimental-strip-types scripts/peer-banner.ts {{persona}} {{name}} 2>/dev/null || true; persona_path="agents/{{persona}}.md"; if [ ! -f "$persona_path" ]; then persona_path=".pi/agents/{{persona}}.md"; fi; pi -e .pi/harnesses/coms/index.ts -e .pi/extensions/compact-and-continue/index.ts --project {{project}} --append-system-prompt "$persona_path" {{ if name != "" { "--name " + name } else { "" } }} {{ if model != "" { "--model " + model } else { "" } }} {{ if session != "" { "--session " + session } else { "" } }}
75
+ d="${AGENT_FLEET_SPAWN_DELAY:-0}"; if [ "$d" != "0" ]; then echo "⏳ waiting ${d}s for the pi auth pre-warm (stale OAuth token)"; sleep "$d"; fi; node --experimental-strip-types scripts/peer-banner.ts {{persona}} {{name}} 2>/dev/null || true; persona_path="agents/{{persona}}.md"; if [ ! -f "$persona_path" ]; then persona_path=".pi/agents/{{persona}}.md"; fi; pi -e .pi/harnesses/coms/index.ts -e .pi/extensions/compact-and-continue/index.ts --project {{project}} --append-system-prompt "$persona_path" {{ if name != "" { "--name " + name } else { "" } }} {{ if model != "" { "--model " + model } else { "" } }} {{ if session != "" { "--session " + session } else { "" } }}
73
76
 
74
77
  # Like _peer, but also loads extra always-on extensions (comma-separated names under
75
78
  # .pi/extensions/) into the peer process — e.g. a chrome-devtools-mcp browser-debug peer
76
79
  # whose `chrome_devtools__*` tools a normal --no-extensions subagent could not get.
77
80
  _peer-plus extensions persona name="" model="" session="" project="default":
78
- node --experimental-strip-types scripts/peer-banner.ts {{persona}} {{name}} 2>/dev/null || true; persona_path="agents/{{persona}}.md"; if [ ! -f "$persona_path" ]; then persona_path=".pi/agents/{{persona}}.md"; fi; extra=""; old_ifs="$IFS"; IFS=','; for x in {{extensions}}; do x="$(echo "$x" | xargs)"; if [ -n "$x" ]; then extra="$extra -e .pi/extensions/$x/index.ts"; fi; done; IFS="$old_ifs"; pi -e .pi/harnesses/coms/index.ts -e .pi/extensions/compact-and-continue/index.ts $extra --project {{project}} --append-system-prompt "$persona_path" {{ if name != "" { "--name " + name } else { "" } }} {{ if model != "" { "--model " + model } else { "" } }} {{ if session != "" { "--session " + session } else { "" } }}
81
+ d="${AGENT_FLEET_SPAWN_DELAY:-0}"; if [ "$d" != "0" ]; then echo "⏳ waiting ${d}s for the pi auth pre-warm (stale OAuth token)"; sleep "$d"; fi; node --experimental-strip-types scripts/peer-banner.ts {{persona}} {{name}} 2>/dev/null || true; persona_path="agents/{{persona}}.md"; if [ ! -f "$persona_path" ]; then persona_path=".pi/agents/{{persona}}.md"; fi; extra=""; old_ifs="$IFS"; IFS=','; for x in {{extensions}}; do x="$(echo "$x" | xargs)"; if [ -n "$x" ]; then extra="$extra -e .pi/extensions/$x/index.ts"; fi; done; IFS="$old_ifs"; pi -e .pi/harnesses/coms/index.ts -e .pi/extensions/compact-and-continue/index.ts $extra --project {{project}} --append-system-prompt "$persona_path" {{ if name != "" { "--name " + name } else { "" } }} {{ if model != "" { "--model " + model } else { "" } }} {{ if session != "" { "--session " + session } else { "" } }}
79
82
 
80
83
  # Internal helper for team-up: a `runner: claude-code` peer — interactive
81
84
  # Claude Code plus its coms bridge (scripts/coms-claude-bridge.ts) in ONE pane.
@@ -84,46 +87,73 @@ _peer-plus extensions persona name="" model="" session="" project="default":
84
87
  _claude-peer name model="" session="" project="default":
85
88
  node --experimental-strip-types scripts/coms-claude-bridge.ts --name {{name}} --project {{project}} & bridge_pid=$!; trap 'kill $bridge_pid 2>/dev/null' EXIT; claude {{ if model != "" { "--model " + model } else { "" } }} {{ if session != "" { "--resume " + session } else { "" } }}
86
89
 
90
+ # The team recipes below take the team as a positional arg (defaults to "full")
91
+ # and pass everything after it straight to the script.
92
+ #
93
+ # Herdr workspace labels are auto-scoped to the CHECKOUT: <worktree-tag>-<mode>-<team>
94
+ # where the tag is the last dot-segment of this directory's basename (main.wt2 →
95
+ # wt2, ringithub.end2 → end2, plain agent-fleet → agent-fleet). So the same team
96
+ # launched from different repos/worktrees gets its own workspace (wt2-hub-plan vs
97
+ # end2-hub-plan) instead of colliding on a shared label.
98
+ #
99
+ # `--project <name>` is a SEPARATE axis: it scopes the coms peer POOL. Without it
100
+ # every peer lands in the shared "default" pool, where teams launched from OTHER
101
+ # repos collide (name suffixing like code-reviewer2, dispatches routed to the
102
+ # wrong repo's pane). IMPORTANT: the flag form is `--project af`; `project=af` is
103
+ # NOT a flag — just treats bare key=value args as variable overrides, so it is
104
+ # silently ignored and the team still joins the "default" pool.
105
+
87
106
  # Team up: spawn every peer of a team from .pi/agents/peers.yaml into a herdr
88
107
  # workspace (one tiled pane per peer). Requires a running herdr server.
89
- # Positional arg: team (defaults to "full"). e.g. just team-up full
108
+ # e.g. just team-up full
109
+ # just team-up review --project af
90
110
  team-up team="full" *args:
91
111
  node --experimental-strip-types scripts/team-up.ts --team {{team}} {{args}}
92
112
 
93
113
  # Team up (dry run): print the resolved layout + per-peer commands without touching herdr.
94
- # e.g. just team-up-dry team="full"
114
+ # e.g. just team-up-dry full
115
+ # just team-up-dry review --project af
95
116
  team-up-dry team="full" *args:
96
117
  node --experimental-strip-types scripts/team-up.ts --team {{team}} --dry-run {{args}}
97
118
 
98
119
  # Hub + team in ONE herdr workspace: the guarded hub (`just hub`) in a larger
99
- # main pane, the team's peers tiled beside it. e.g. just hub-team docs
120
+ # main pane, the team's peers tiled beside it.
121
+ # e.g. just hub-team docs
122
+ # just hub-team review --project af
100
123
  hub-team team="full" *args:
101
124
  node --experimental-strip-types scripts/team-up.ts --team {{team}} --hub {{args}}
102
125
 
103
126
  # Hub + team (dry run): print the combined layout without touching herdr.
127
+ # e.g. just hub-team-dry review --project af
104
128
  hub-team-dry team="full" *args:
105
129
  node --experimental-strip-types scripts/team-up.ts --team {{team}} --hub --dry-run {{args}}
106
130
 
107
131
  # Hermes conductor + team in ONE herdr workspace: Hermes dev profile in a conductor pane,
108
132
  # the team's peers tiled beside it. Hermes delegates via coms-cli and never drives herdr.
133
+ # e.g. just conductor docs --project af
109
134
  conductor team="full" *args:
110
135
  node --experimental-strip-types scripts/team-up.ts --team {{team}} --conductor {{args}}
111
136
 
112
137
  # Hermes conductor + team (dry run): print the combined layout without touching herdr.
138
+ # e.g. just conductor-dry docs --project af
113
139
  conductor-dry team="full" *args:
114
140
  node --experimental-strip-types scripts/team-up.ts --team {{team}} --conductor --dry-run {{args}}
115
141
 
116
142
  # Snapshot a RUNNING team's session refs to ~/.pi/team-snapshots/<team>.json
117
143
  # (team keeps running — take one proactively so a crash is resumable).
144
+ # A team launched with --project must snapshot with the same --project.
145
+ # e.g. just team-snapshot review --project af
118
146
  team-snapshot team="full" *args:
119
147
  node --experimental-strip-types scripts/team-snapshot.ts snapshot {{team}} {{args}}
120
148
 
121
149
  # Snapshot, then close the team workspace cleanly (peers get SIGTERM).
150
+ # e.g. just team-down review --project af
122
151
  team-down team="full" *args:
123
152
  node --experimental-strip-types scripts/team-snapshot.ts down {{team}} {{args}}
124
153
 
125
154
  # Rebuild a team from its snapshot — each pi peer resumes its previous
126
155
  # conversation (`pi --session <ref>`); peers whose ref is gone start fresh.
156
+ # e.g. just team-resume review --project af
127
157
  team-resume team="full" *args:
128
158
  node --experimental-strip-types scripts/team-snapshot.ts resume {{team}} {{args}}
129
159
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chankov/agent-fleet",
3
- "version": "0.0.1",
3
+ "version": "0.0.2",
4
4
  "description": "Multi-agent fleet orchestration for coding agents. Pi as the primary runtime, Herdr as the workspace control plane, coms as the peer data plane, and Hermes for remote control — plus skills, personas, harnesses, and a guided setup CLI.",
5
5
  "keywords": [
6
6
  "ai",
@@ -88,7 +88,7 @@
88
88
  "access": "public"
89
89
  },
90
90
  "scripts": {
91
- "test": "node bin/cli.js --version && node bin/cli.js --help && node bin/cli.js transform-persona --list --agent claude-code && node --test \"bin/test/*.test.js\" \".pi/harnesses/lib/herdr-client.test.ts\" \".pi/harnesses/lib/herdr-presence.test.ts\" \"scripts/lib/team-project.test.ts\" \"scripts/lib/herdr-layout.test.ts\" \"scripts/lib/fleet-extras.test.ts\" \"scripts/lib/team-snapshot.test.ts\" \"scripts/lib/coms-envelope.test.ts\" \"scripts/lib/claude-bridge-core.test.ts\" \"scripts/lib/hermes-bridge-core.test.ts\" \"scripts/coms-hermes-bridge.test.ts\" \".pi/harnesses/ask-user-remote/race-core.test.js\" \".pi/harnesses/ask-user-remote/index.test.ts\" \".pi/extensions/btw/state.test.js\" \".pi/harnesses/agent-hub/return-contract.test.js\" \".pi/harnesses/agent-hub/backend-policy.test.js\" \".pi/harnesses/agent-hub/artifacts.test.js\" \".pi/harnesses/agent-hub/scope-gate.test.js\" \".pi/harnesses/agent-hub/evidence-rules.test.js\" \".pi/harnesses/damage-control/shared.test.js\" \".pi/harnesses/damage-control/herdr-rules.test.js\" \".pi/harnesses/damage-control-continue/exemptions.test.js\"",
91
+ "test": "node bin/cli.js --version && node bin/cli.js --help && node bin/cli.js transform-persona --list --agent claude-code && node --test \"bin/test/*.test.js\" \".pi/harnesses/lib/herdr-client.test.ts\" \".pi/harnesses/lib/herdr-presence.test.ts\" \"scripts/lib/team-project.test.ts\" \"scripts/lib/herdr-layout.test.ts\" \"scripts/lib/spawn-stagger.test.ts\" \"scripts/lib/fleet-extras.test.ts\" \"scripts/lib/team-snapshot.test.ts\" \"scripts/lib/coms-envelope.test.ts\" \"scripts/lib/claude-bridge-core.test.ts\" \"scripts/lib/hermes-bridge-core.test.ts\" \"scripts/coms-hermes-bridge.test.ts\" \".pi/harnesses/ask-user-remote/race-core.test.js\" \".pi/harnesses/ask-user-remote/index.test.ts\" \".pi/extensions/btw/state.test.js\" \".pi/harnesses/agent-hub/return-contract.test.js\" \".pi/harnesses/agent-hub/backend-policy.test.js\" \".pi/harnesses/agent-hub/artifacts.test.js\" \".pi/harnesses/agent-hub/scope-gate.test.js\" \".pi/harnesses/agent-hub/evidence-rules.test.js\" \".pi/harnesses/damage-control/shared.test.js\" \".pi/harnesses/damage-control/herdr-rules.test.js\" \".pi/harnesses/damage-control-continue/exemptions.test.js\"",
92
92
  "pack:dry": "npm pack --dry-run",
93
93
  "changeset": "changeset",
94
94
  "version:changeset": "node bin/force-patch-changesets.js && changeset version && npm install --package-lock-only --ignore-scripts --no-audit --no-fund && node bin/snapshot-version.js",
@@ -369,8 +369,6 @@ async function main(): Promise<void> {
369
369
  }
370
370
  }),
371
371
  );
372
- writeRegistryAtomic(registryEntry(), project);
373
- console.error(`coms-hermes-bridge: ${uniqueName}@${project} listening (${to})`);
374
372
 
375
373
  const keepalive = setInterval(() => {
376
374
  try { writeRegistryAtomic(registryEntry(), project); } catch { /* best-effort */ }
@@ -393,6 +391,12 @@ async function main(): Promise<void> {
393
391
  }
394
392
  process.on("SIGTERM", shutdown);
395
393
  process.on("SIGINT", shutdown);
394
+
395
+ // Publish readiness only after shutdown handlers are installed. A caller may
396
+ // terminate the bridge as soon as its registry entry appears; publishing
397
+ // earlier can bypass cleanup and leave both the entry and socket behind.
398
+ writeRegistryAtomic(registryEntry(), project);
399
+ console.error(`coms-hermes-bridge: ${uniqueName}@${project} listening (${to})`);
396
400
  }
397
401
 
398
402
  const isEntry = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
@@ -10,6 +10,7 @@
10
10
  import { resolve as resolvePath } from "node:path";
11
11
 
12
12
  import type { LayoutNode } from "../../.pi/harnesses/lib/herdr-client.ts";
13
+ import { STAGGER_ENV_VAR } from "./spawn-stagger.ts";
13
14
  import { DEFAULT_PROJECT, validateProject } from "./team-project.ts";
14
15
 
15
16
  export type { LayoutNode };
@@ -175,6 +176,10 @@ export interface TeamLayoutOptions {
175
176
  // B5 hook: resume ref (pi session path) for a peer being restored from a
176
177
  // team snapshot. Returning undefined starts the peer fresh.
177
178
  resumeForPeer?: (peer: Peer) => string | undefined;
179
+ // Pre-warm/stagger hook (see spawn-stagger.ts): seconds this pane should
180
+ // sleep before launching pi, injected as AGENT_FLEET_SPAWN_DELAY in the
181
+ // pane env. undefined or 0 launches immediately.
182
+ delayForPeer?: (peer: Peer) => number | undefined;
178
183
  // B2 hook: when set, the hub occupies a larger root pane (ratio of the
179
184
  // horizontal split) and the team tiles in the remaining space.
180
185
  // Coms project scope shared by all panes in this layout. The default keeps
@@ -191,15 +196,23 @@ function paneNode(
191
196
  envForPeer?: TeamLayoutOptions["envForPeer"],
192
197
  resumeForPeer?: TeamLayoutOptions["resumeForPeer"],
193
198
  project = DEFAULT_PROJECT,
199
+ delayForPeer?: TeamLayoutOptions["delayForPeer"],
194
200
  ): LayoutNode {
195
201
  validateProject(project);
196
- const env = envForPeer?.(peer);
202
+ const env = { ...envForPeer?.(peer) };
203
+ const delay = delayForPeer?.(peer);
204
+ if (delay !== undefined) {
205
+ if (!Number.isFinite(delay) || delay < 0) {
206
+ throw new Error(`Invalid spawn delay for peer "${peer.name}": ${delay}`);
207
+ }
208
+ if (delay > 0) env[STAGGER_ENV_VAR] = String(Math.round(delay));
209
+ }
197
210
  return {
198
211
  type: "pane",
199
212
  command: peerCommand(peer, team, resumeForPeer?.(peer), project),
200
213
  cwd: repoRoot,
201
214
  label: peer.name as string,
202
- ...(env && Object.keys(env).length > 0 ? { env } : {}),
215
+ ...(Object.keys(env).length > 0 ? { env } : {}),
203
216
  };
204
217
  }
205
218
 
@@ -219,10 +232,10 @@ function bsp(nodes: LayoutNode[], depth: number): LayoutNode {
219
232
 
220
233
  // peers.yaml team → herdr layout tree for layout.apply.
221
234
  export function buildTeamLayout(opts: TeamLayoutOptions): LayoutNode {
222
- const { team, peers, repoRoot, envForPeer, resumeForPeer, hub, project = DEFAULT_PROJECT } = opts;
235
+ const { team, peers, repoRoot, envForPeer, resumeForPeer, delayForPeer, hub, project = DEFAULT_PROJECT } = opts;
223
236
  validateProject(project);
224
237
  if (peers.length === 0) throw new Error(`Team "${team}" has no peers.`);
225
- const panes = peers.map((p) => paneNode(p, team, repoRoot, envForPeer, resumeForPeer, project));
238
+ const panes = peers.map((p) => paneNode(p, team, repoRoot, envForPeer, resumeForPeer, project, delayForPeer));
226
239
  const grid = bsp(panes, hub ? 1 : 0);
227
240
  if (!hub) return grid;
228
241
  return {
@@ -0,0 +1,101 @@
1
+ // scripts/lib/spawn-stagger.ts
2
+ //
3
+ // Pre-warm/stagger for simultaneous pi pane spawns (team-up, hub-team,
4
+ // team-resume). pi's credential store (~/.pi/agent/auth.json) is loaded once
5
+ // at boot under a short-retry file lock; when a stale OAuth token forces one
6
+ // pane to refresh it over the network WHILE holding that lock, sibling panes
7
+ // booting in the same instant lose the lock race and come up with an empty
8
+ // credential store — every provider shows "unconfigured". The fix is local:
9
+ // when a stale OAuth credential is detected, one pi pane starts immediately
10
+ // (the warmer — it refreshes the token) and every other pi pane sleeps a few
11
+ // seconds before launching. Fresh tokens mean zero delay everywhere.
12
+ //
13
+ // Pure logic only — no fs, no sockets, no process.exit. Callers read
14
+ // auth.json themselves (lock-free, same as pi's readStoredCredential) and
15
+ // inject delays into pane env; the `_peer`/`_peer-plus` recipes honor
16
+ // AGENT_FLEET_SPAWN_DELAY with a plain `sleep`.
17
+
18
+ /** Env var the justfile peer recipes read: seconds to sleep before launching pi. */
19
+ export const STAGGER_ENV_VAR = "AGENT_FLEET_SPAWN_DELAY";
20
+
21
+ /** Delay for the first staggered pane — long enough for the warmer's token refresh round-trip. */
22
+ export const WARMUP_SECONDS = 4;
23
+
24
+ /** Extra spacing between subsequent staggered panes. */
25
+ export const STEP_SECONDS = 1;
26
+
27
+ /** Treat tokens expiring within this window as stale — pane boot takes seconds. */
28
+ export const EXPIRY_MARGIN_MS = 60_000;
29
+
30
+ /**
31
+ * Does auth.json hold an OAuth credential that a booting pi would refresh?
32
+ * `raw` is the file's contents (undefined when unreadable/absent). Missing or
33
+ * malformed files never stagger: with no stored credential there is nothing
34
+ * to refresh, so there is no long lock hold to dodge.
35
+ */
36
+ export function oauthNeedsWarmup(raw: string | undefined, now = Date.now()): boolean {
37
+ if (!raw) return false;
38
+ let data: unknown;
39
+ try {
40
+ data = JSON.parse(raw);
41
+ } catch {
42
+ return false;
43
+ }
44
+ if (typeof data !== "object" || data === null) return false;
45
+ for (const credential of Object.values(data)) {
46
+ if (typeof credential !== "object" || credential === null) continue;
47
+ const { type, expires } = credential as { type?: unknown; expires?: unknown };
48
+ if (type !== "oauth" || typeof expires !== "number") continue;
49
+ if (expires <= now + EXPIRY_MARGIN_MS) return true;
50
+ }
51
+ return false;
52
+ }
53
+
54
+ export interface StaggerOptions {
55
+ /** Per-peer flag, in spawn order: does this pane boot a pi process? */
56
+ peerIsPi: boolean[];
57
+ /** Does the root pane (hub) boot a pi process? The hub warms when present. */
58
+ rootIsPi: boolean;
59
+ /** Result of oauthNeedsWarmup — false short-circuits to all-zero delays. */
60
+ needed: boolean;
61
+ warmupSeconds?: number;
62
+ stepSeconds?: number;
63
+ }
64
+
65
+ /**
66
+ * Per-peer delay seconds (spawn order). Exactly one pi process — the hub when
67
+ * present, otherwise the first pi peer — starts at 0 and refreshes the stale
68
+ * token; every other pi peer starts after the warm-up window. Non-pi panes
69
+ * (runner: claude-code) never wait: they do not touch pi's credential store.
70
+ */
71
+ export function staggerDelays(opts: StaggerOptions): number[] {
72
+ const { peerIsPi, rootIsPi, needed, warmupSeconds = WARMUP_SECONDS, stepSeconds = STEP_SECONDS } = opts;
73
+ if (!needed) return peerIsPi.map(() => 0);
74
+ let staggered = 0;
75
+ let warmerAssigned = rootIsPi;
76
+ return peerIsPi.map((isPi) => {
77
+ if (!isPi) return 0;
78
+ if (!warmerAssigned) {
79
+ warmerAssigned = true;
80
+ return 0;
81
+ }
82
+ return warmupSeconds + staggered++ * stepSeconds;
83
+ });
84
+ }
85
+
86
+ /**
87
+ * Convenience for the team entrypoints: auth.json contents + peers → a
88
+ * `delayForPeer` hook for buildTeamLayout. Structural peer type avoids a
89
+ * circular import with herdr-layout.ts.
90
+ */
91
+ export function planSpawnDelays<P extends { runner?: string }>(
92
+ peers: P[],
93
+ rootIsPi: boolean,
94
+ authJsonRaw: string | undefined,
95
+ now = Date.now(),
96
+ ): { needed: boolean; delayForPeer: (peer: P) => number | undefined } {
97
+ const needed = oauthNeedsWarmup(authJsonRaw, now);
98
+ const delays = staggerDelays({ peerIsPi: peers.map((p) => p.runner !== "claude-code"), rootIsPi, needed });
99
+ const byPeer = new Map<P, number>(peers.map((p, i) => [p, delays[i]]));
100
+ return { needed, delayForPeer: (peer) => byPeer.get(peer) };
101
+ }
@@ -35,6 +35,20 @@ export function validateTeamName(team: string): string {
35
35
  return team;
36
36
  }
37
37
 
38
+ // The worktree/repo identity that scopes a workspace label so the same team
39
+ // launched from different checkouts never collides. It is the LAST dot-segment
40
+ // of the checkout directory's basename — the convention the fleet uses for
41
+ // git worktrees: `main.wt2` → `wt2`, `ringithub.end2` → `end2`, a plain
42
+ // `agent-fleet` checkout → `agent-fleet`. Sanitized to the label-safe charset;
43
+ // falls back to "repo" when nothing usable remains.
44
+ export function worktreeTag(repoRoot: string): string {
45
+ const base = path.basename(repoRoot);
46
+ const dot = base.lastIndexOf(".");
47
+ const seg = dot > 0 ? base.slice(dot + 1) : base;
48
+ const safe = seg.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
49
+ return safe || "repo";
50
+ }
51
+
38
52
  export function parseProjectFlag(argv: string[]): string {
39
53
  let project = DEFAULT_PROJECT;
40
54
  let seen = false;
@@ -50,11 +64,22 @@ export function parseProjectFlag(argv: string[]): string {
50
64
  return validateProject(project);
51
65
  }
52
66
 
53
- export function teamWorkspaceLabel(kind: "peers" | "hub" | "conductor", team: string, project = DEFAULT_PROJECT): string {
67
+ // Workspace label = <worktree-tag>-<mode>-<team>, with a `--project.<name>`
68
+ // suffix when the coms project is non-default. The worktree tag keys the label
69
+ // to the checkout, so `just hub-team <team>` from two repos/worktrees yields
70
+ // distinct labels (e.g. `wt2-hub-plan` vs `end2-hub-plan`) instead of colliding
71
+ // on a shared `pi-hub-<team>`. Pass `tag` from worktreeTag(REPO_ROOT); it
72
+ // defaults to "repo" only for callers that have no checkout in hand.
73
+ export function teamWorkspaceLabel(
74
+ kind: "peers" | "hub" | "conductor",
75
+ team: string,
76
+ project = DEFAULT_PROJECT,
77
+ tag = "repo",
78
+ ): string {
54
79
  validateTeamName(team);
55
80
  validateProject(project);
56
- const prefix = kind === "hub" ? "pi-hub" : kind === "conductor" ? "pi-conductor" : "pi-peers";
57
- return project === DEFAULT_PROJECT ? `${prefix}-${team}` : `${prefix}-${team}--project.${project}`;
81
+ const base = `${tag}-${kind}-${team}`;
82
+ return project === DEFAULT_PROJECT ? base : `${base}--project.${project}`;
58
83
  }
59
84
 
60
85
  export function hubCommand(project = DEFAULT_PROJECT): string[] {
@@ -58,8 +58,9 @@ export function buildSnapshot(opts: {
58
58
  agents: AgentLite[];
59
59
  now?: Date;
60
60
  project?: string;
61
+ tag?: string;
61
62
  }): TeamSnapshot {
62
- const { team, hub, peers, panes, agents, project = DEFAULT_PROJECT } = opts;
63
+ const { team, hub, peers, panes, agents, project = DEFAULT_PROJECT, tag } = opts;
63
64
  validateTeamName(team);
64
65
  validateProject(project);
65
66
  const paneByLabel = new Map<string, string>();
@@ -78,7 +79,7 @@ export function buildSnapshot(opts: {
78
79
  team,
79
80
  project,
80
81
  hub,
81
- workspace_label: teamWorkspaceLabel(hub ? "hub" : "peers", team, project),
82
+ workspace_label: teamWorkspaceLabel(hub ? "hub" : "peers", team, project, tag),
82
83
  taken_at: (opts.now ?? new Date()).toISOString(),
83
84
  peers: peers.map((peer) => {
84
85
  const paneId = peer.name ? paneByLabel.get(peer.name) : undefined;