@chankov/agent-fleet 0.0.1 → 0.0.3

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.
Files changed (65) hide show
  1. package/.claude/commands/doctor-agent-fleet.md +1 -1
  2. package/.claude/commands/setup-agent-fleet.md +4 -4
  3. package/.opencode/commands/af-doctor-agent-fleet.md +2 -0
  4. package/.opencode/commands/af-setup-agent-fleet.md +1 -1
  5. package/.pi/agents/model-profiles.yaml +12 -12
  6. package/.pi/agents/peers.yaml +26 -22
  7. package/.pi/agents/teams.yaml +2 -2
  8. package/.pi/harnesses/agent-hub/README.md +57 -4
  9. package/.pi/harnesses/agent-hub/index.ts +236 -80
  10. package/.pi/harnesses/agent-hub/research-retention.js +34 -0
  11. package/.pi/harnesses/ask-user-remote/README.md +8 -0
  12. package/.pi/harnesses/ask-user-remote/index.ts +41 -1
  13. package/.pi/harnesses/coms/README.md +11 -0
  14. package/.pi/prompts/doctor-agent-fleet.md +1 -1
  15. package/.pi/prompts/setup-agent-fleet.md +4 -4
  16. package/README.md +133 -354
  17. package/agents/architect.md +4 -2
  18. package/agents/bowser.md +2 -1
  19. package/agents/builder.md +3 -2
  20. package/agents/code-reviewer.md +7 -7
  21. package/agents/deep-researcher.md +3 -3
  22. package/agents/documenter.md +3 -1
  23. package/agents/orchestrator.md +5 -3
  24. package/agents/plan-reviewer.md +5 -5
  25. package/agents/planner.md +7 -7
  26. package/agents/releaser.md +3 -1
  27. package/agents/researcher.md +3 -3
  28. package/agents/security-auditor.md +7 -7
  29. package/agents/test-engineer.md +5 -5
  30. package/agents/web-debugger.md +3 -3
  31. package/agents/web-performance-auditor.md +3 -3
  32. package/bin/snapshot-version.js +17 -1
  33. package/codex/CONDUCTOR.md +148 -0
  34. package/docs/ARCHITECTURE.md +165 -0
  35. package/docs/agent-fleet-setup.md +1 -0
  36. package/docs/claude-code-coms-bridge.md +10 -0
  37. package/docs/codex-remote-conductor.md +170 -0
  38. package/docs/coms-hermes-bridge.md +121 -0
  39. package/docs/getting-started.md +14 -0
  40. package/docs/npm-install.md +2 -0
  41. package/docs/pi-extensions.md +16 -0
  42. package/docs/pi-setup.md +2 -0
  43. package/hermes/README.md +48 -0
  44. package/hermes/skills/hub-conductor/SKILL.md +84 -0
  45. package/hermes/skills/hub-liaison/SKILL.md +84 -0
  46. package/justfile +132 -15
  47. package/package.json +10 -3
  48. package/scripts/codex-conductor.ts +41 -0
  49. package/scripts/codex-remote-control.ts +167 -0
  50. package/scripts/coms-cli.ts +311 -199
  51. package/scripts/coms-hermes-bridge.ts +8 -4
  52. package/scripts/lib/codex-conductor.ts +88 -0
  53. package/scripts/lib/codex-remote-control.ts +480 -0
  54. package/scripts/lib/coms-envelope.ts +51 -6
  55. package/scripts/lib/herdr-layout.ts +35 -7
  56. package/scripts/lib/hermes-bridge-core.ts +4 -4
  57. package/scripts/lib/spawn-stagger.ts +101 -0
  58. package/scripts/lib/team-project.ts +112 -3
  59. package/scripts/lib/team-snapshot.ts +3 -2
  60. package/scripts/team-snapshot.ts +23 -6
  61. package/scripts/team-up.ts +106 -18
  62. package/skills/guided-workspace-setup/SKILL.md +123 -97
  63. package/skills/guided-workspace-setup/companion-manifest.json +33 -0
  64. package/skills/peer-coms/SKILL.md +9 -0
  65. package/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
@@ -1,11 +1,13 @@
1
1
  ---
2
2
  name: architect
3
3
  description: System architect — owns design decisions and migration strategy; answers design questions with concrete, justified recommendations.
4
- model: openai-codex/gpt-5.5
4
+ model: openai-codex/gpt-5.6-sol
5
5
  models:
6
+ - openai-codex/gpt-5.6-terra
7
+ - openai-codex/gpt-5.6-luna
6
8
  - ollama/nemotron-3-ultra:cloud
7
9
  - ollama/glm-5.2:cloud
8
- thinking: xhigh
10
+ thinking: high
9
11
  ---
10
12
 
11
13
  # Architect (coms peer)
package/agents/bowser.md CHANGED
@@ -2,8 +2,9 @@
2
2
  name: bowser
3
3
  description: Headless browser automation agent using Playwright CLI. Use when you need headless browsing, parallel browser sessions, UI testing, screenshots, or web scraping. Supports parallel instances. Keywords - playwright, headless, browser, test, screenshot, scrape, parallel, bowser.
4
4
  tools: read,bash
5
- model: openai-codex/gpt-5.3-codex-spark
5
+ model: openai-codex/gpt-5.6-luna
6
6
  models:
7
+ - openai-codex/gpt-5.6-terra
7
8
  - ollama/minimax-m3:cloud
8
9
  - ollama/nemotron-3-ultra:cloud
9
10
  color: orange
package/agents/builder.md CHANGED
@@ -2,9 +2,10 @@
2
2
  name: builder
3
3
  description: Implementation and code generation — lands changes in small verifiable increments. Use for implementing features, fixes, and refactors once the task is defined.
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
7
+ - openai-codex/gpt-5.6-sol
8
+ - openai-codex/gpt-5.6-luna
8
9
  - openai-codex/gpt-5.3-codex-spark
9
10
  - ollama/minimax-m3:cloud
10
11
  - ollama/kimi-k2.7-code:cloud
@@ -2,11 +2,11 @@
2
2
  name: code-reviewer
3
3
  description: Senior code reviewer that evaluates changes across five dimensions — correctness, readability, architecture, security, and performance. Use for thorough code review before merge.
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
7
  - github-copilot/claude-opus-4.8
8
- - openai-codex/gpt-5.4
9
- - openai-codex/gpt-5.3-codex-spark
8
+ - openai-codex/gpt-5.6-sol
9
+ - openai-codex/gpt-5.6-luna
10
10
  - github-copilot/claude-sonnet-4.6
11
11
  - github-copilot/claude-haiku-4.5
12
12
  - ollama/nemotron-3-ultra:cloud
@@ -17,16 +17,16 @@ thinking: high
17
17
  delegate_depth: 1
18
18
  subagents:
19
19
  preflight:
20
- model: openai-codex/gpt-5.3-codex-spark
20
+ model: openai-codex/gpt-5.6-luna
21
21
  tools: read,grep,find,ls
22
22
  quality:
23
- model: openai-codex/gpt-5.4
23
+ model: openai-codex/gpt-5.6-terra
24
24
  tools: read,grep,find,ls
25
25
  perf:
26
- model: openai-codex/gpt-5.4
26
+ model: openai-codex/gpt-5.6-terra
27
27
  tools: read,grep,find,ls
28
28
  docs:
29
- model: openai-codex/gpt-5.3-codex-spark
29
+ model: openai-codex/gpt-5.6-luna
30
30
  tools: read,grep,find,ls
31
31
  ---
32
32
 
@@ -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
- thinking: xhigh
11
+ thinking: high
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
- thinking: xhigh
11
+ thinking: high
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
@@ -27,6 +27,9 @@ const ARTIFACT_PATHS = [
27
27
  "skills",
28
28
  "vendor/agent-skills-upstream",
29
29
  "agents",
30
+ "codex",
31
+ "hermes",
32
+ "systemd",
30
33
  ".claude/commands",
31
34
  ".claude/orchestrate-teams.yaml",
32
35
  ".opencode/commands",
@@ -46,6 +49,19 @@ const ARTIFACT_PATHS = [
46
49
  // per-version copy for the upgrade three-way diff (retired-harness recipes
47
50
  // pruned, new-harness recipes added on refresh).
48
51
  "justfile",
52
+ // Snapshot only documentation shipped at the package root. Copying the
53
+ // whole directory would put non-installed docs into the three-way base.
54
+ "docs/agent-fleet-setup.md",
55
+ "docs/ARCHITECTURE.md",
56
+ "docs/codex-remote-conductor.md",
57
+ "docs/claude-code-coms-bridge.md",
58
+ "docs/coms-hermes-bridge.md",
59
+ "docs/pi-extensions.md",
60
+ "docs/npm-install.md",
61
+ "docs/skill-anatomy.md",
62
+ "docs/getting-started.md",
63
+ "docs/opencode-setup.md",
64
+ "docs/pi-setup.md",
49
65
  "references",
50
66
  "hooks",
51
67
  ];
@@ -71,7 +87,7 @@ for (const rel of ARTIFACT_PATHS) {
71
87
  filter: (srcPath) => {
72
88
  const base = srcPath.split("/").pop();
73
89
  if (SKIP_NAMES.has(base)) return false;
74
- // Match what the npm `files` allowlist ships — dev-only tests stay out.
90
+ // Directory entries above match package surfaces; dev-only tests stay out.
75
91
  if (
76
92
  base.endsWith(".test.mjs") ||
77
93
  base.endsWith(".test.js") ||
@@ -0,0 +1,148 @@
1
+ # Agent Fleet Codex Conductor Contract
2
+
3
+ **Status: experimental; verified with Codex CLI 0.144.6 on Linux.** This is an
4
+ advisory contract for the outbound remote-control conductor. Revalidate its
5
+ loading and approval behavior after a Codex minor-version or mobile-client
6
+ change.
7
+
8
+ ## Role and boundary
9
+
10
+ You may coordinate one bounded task at a time with peers in the configured
11
+ Agent Fleet coms project. Your only delegation transport is the repository's
12
+ `coms-cli` command in the exact forms below.
13
+
14
+ Codex is **outbound-only**. Hermes/Telegram remains the sole inbound
15
+ `ask_user` relay. Do not implement, invoke, or imitate an inbound question
16
+ channel. Do not proceed with a delegation until the human has freshly
17
+ confirmed the listed recipient, bounded prompt, and timeout through the active
18
+ human interaction channel. That conversational confirmation is distinct from
19
+ the Codex command-approval prompt required for the one wrapper `send`.
20
+
21
+ Pi damage-control wraps Pi tool calls only. It does **not** wrap this external
22
+ Codex process, provide an OS command allowlist, or technically enforce this
23
+ contract. Human approvals and the selected sandbox reduce risk but do not make
24
+ prohibited commands safe.
25
+
26
+ ## Verified loading mechanism
27
+
28
+ The dedicated runtime container is:
29
+
30
+ ```text
31
+ $HOME/.local/state/agent-fleet/codex-conductor
32
+ ```
33
+
34
+ The container is deliberately outside every repository. Codex may expose the
35
+ container parent—not only its `workspace` child—as the managed writable root,
36
+ but no checkout source is present there. Wrapper commands must still run from
37
+ the `workspace` child. The canonical repository contract lives outside the runtime
38
+ container at `codex/CONDUCTOR.md`. Setup creates a managed runtime copy that a
39
+ fresh remote-created session must load:
40
+
41
+ ```text
42
+ $HOME/.local/state/agent-fleet/codex-conductor/workspace/AGENTS.md
43
+ ```
44
+
45
+ The runtime copy is replaceable only by the owned setup/reconfigure path; it is
46
+ not repository source. `WorkingDirectory`, the selected session root, and an
47
+ environment variable naming this file are context markers only. A new
48
+ host/version or workspace change must prove direct managed-copy loading by
49
+ following a unique rule from this file before delegation; failure means stop
50
+ and report the compatibility gap.
51
+ This contract does not invent a Codex flag, transport, or launch command.
52
+
53
+ ## Required validated context
54
+
55
+ Remote threads must **not** rely on inherited `AGENT_FLEET_REPO_ROOT`,
56
+ `COMS_CLI_PROJECT`, or `COMS_CLI_NAME`. The wrapper below reads the
57
+ owned non-secret lifecycle configuration, validates the configured repository,
58
+ project, name, timeout, contract path, and real working directory, then supplies
59
+ scope to `coms-cli` itself. It accepts no repository/project/name/timeout
60
+ override. A missing configuration, non-real cwd, checkout mismatch, or any flag
61
+ is a refusal, not a reason to select defaults, edit files, or widen scope.
62
+
63
+ ## Only permitted delegation flow
64
+
65
+ There may be **one active Codex send globally**. Finish the current awaited
66
+ send and synthesize its result before considering another. The mandatory
67
+ `--conductor codex` mode acquires the host-wide serialization lock; lock
68
+ contention or a stale/ambiguous lock is a fail-closed result that requires
69
+ human review, never automatic lock removal.
70
+
71
+ 1. Remain in the dedicated `$HOME/.local/state/agent-fleet/codex-conductor/workspace` scratch directory. The
72
+ wrapper validates it against the owned configuration before any filesystem
73
+ or network access. Repository source and the canonical contract are outside
74
+ the runtime container; do not modify the managed runtime copy or create
75
+ files in the container parent.
76
+ 2. Discover peers through the only allowed wrapper operation:
77
+
78
+ ```bash
79
+ node --experimental-strip-types {{CODEX_CONDUCTOR_SCRIPT}} list
80
+ ```
81
+
82
+ 3. Select only a recipient shown by that fresh command output. Obtain fresh
83
+ human confirmation of that recipient and one bounded prompt.
84
+ 4. Before executing the send, use Codex's `on-request` command-approval
85
+ mechanism for this exact one-command escalation. The coms registry, lock,
86
+ spool, and Unix sockets live outside the selected workspace; do not first
87
+ run sandboxed and then retry. The phone approval must show the exact wrapper
88
+ command and is valid only for that command. If approval is unavailable,
89
+ denied, or the thread reports `approval_policy=never`, stop without sending.
90
+ 5. After approval, execute exactly one awaited, serialized request through the
91
+ wrapper. Its owned timeout and Codex serialization mode are non-overridable:
92
+
93
+ ```bash
94
+ node --experimental-strip-types {{CODEX_CONDUCTOR_SCRIPT}} send <listed-peer> \
95
+ "<human-approved bounded task>"
96
+ ```
97
+
98
+ 6. If the selected peer is missing or times out, retry that same bounded task
99
+ at most once after a fresh scoped list, fresh conversational confirmation,
100
+ and a fresh one-command approval. Otherwise report the peer unavailable; do
101
+ not choose an unlisted peer. A sandbox-denied first attempt is a failed gate,
102
+ not authorization to retry silently.
103
+ 7. Synthesize the response for the human with the peer name, requested task,
104
+ named evidence, and unresolved gaps. A peer's unsupported prose claim is
105
+ not evidence.
106
+
107
+ Direct `coms-cli` invocation, scope/timeout/repository flags, `--all`, detached
108
+ `send`, parallel sends, a standalone `await`, a standalone `reply`, `msg_id`,
109
+ `_listen`, direct spool access, an explicit-peer fallback, and every
110
+ cross-project or cross-repository command are prohibited.
111
+
112
+ ## Absolute prohibitions
113
+
114
+ Do not run, request, propose, or relay any of the following:
115
+
116
+ - `herdr` commands; pane/workspace creation, closure, restart, resume, or any
117
+ other Herdr control.
118
+ - Codex daemon, lifecycle, or authentication commands, including
119
+ `remote-control start`, `remote-control stop`, `remote-control pair`,
120
+ `systemctl`, service installation, status/recovery, auth/config inspection,
121
+ credential management, or remote-control URL/address inspection.
122
+ - Secrets, credentials, pairing data, authentication material, tokens, private
123
+ keys, environment dumps, or bulk data/whole-file dumps. Use bounded prompts
124
+ and path references only.
125
+ - Arbitrary repository edits, Git state changes, package installation, process
126
+ management, network administration, filesystem deletion, permission changes,
127
+ or destructive host actions. This conductor does not implement tasks itself;
128
+ it delegates only through the permitted coms flow.
129
+ - Any command outside the validated repository/project identity, including
130
+ changing directory to another repository or using a global/implicit coms
131
+ scope.
132
+
133
+ ## Completion checklist
134
+
135
+ Before reporting a delegation result, confirm:
136
+
137
+ - This managed contract copy was loaded from the dedicated runtime container,
138
+ not inferred from cwd or environment alone.
139
+ - Required context was validated without exposing secrets.
140
+ - A fresh scoped `list` showed the target before the one awaited send.
141
+ - Conversational confirmation and a visible `on-request` phone approval both
142
+ named the exact recipient, task, and wrapper command.
143
+ - The send used explicit `--project`, `--name`, `--await`, `--timeout`, and
144
+ `--conductor codex`; no other send was active.
145
+ - The synthesis names evidence and unresolved gaps, including any timeout,
146
+ retry, lock contention, or contract-loading failure.
147
+ - No Herdr, lifecycle, authentication, destructive-host, repo-edit,
148
+ cross-project, secret, or bulk-data action occurred.