@ours.network/fleet-codex 0.3.4 → 0.3.7

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ours-fleet",
-  "version": "0.3.4",
+  "version": "0.3.7",
   "description": "Spawn, configure, and oversee ours-fleet roles from OpenAI Codex.",
   "author": {
     "name": "Adapt Framework Solutions Ltd",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/fleet-codex",
-  "version": "0.3.4",
+  "version": "0.3.7",
   "description": "Native Codex plugin for spawning, configuring, and overseeing ours-fleet agents.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",

package/skills/oversee-agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oversee-agents
-description: Inspect, monitor, and unstick ours-fleet agents from Codex using their tmux consoles and supervisor state. Use when the user asks to keep an eye on agents, oversee spawned roles, check agent status, babysit a subagent, resolve a fleet prompt, or when Codex has just spawned a role and should verify its progress.
+description: Inspect, monitor, and unstick ours-fleet agents from Codex using their tmux or ACP session controls and supervisor state. Use when the user asks to keep an eye on agents, oversee spawned roles, check agent status, babysit a subagent, resolve a fleet prompt, or when Codex has just spawned a role and should verify its progress.
 ---
 
 # Oversee ours-fleet agents
@@ -8,6 +8,7 @@ description: Inspect, monitor, and unstick ours-fleet agents from Codex using th
 Use fleet state and console output as evidence:
 
 ```sh
+ours-fleet docs
 ours-fleet ls
 ours-fleet peek <Name> [lines]
 ours-fleet status <Name>
@@ -16,27 +17,54 @@ ours-fleet send <Name> "<text>"
 ours-fleet send <Name> --key <key>
 ```
 
+Text `send`, `peek`, and `attach` work for tmux and ACP. Raw `send --key` is
+tmux-only; use the `/permit` control shown by ACP `attach` for ACP permissions.
+
 ## Establish scope
 
 Identify wards from the user's request, the current role briefing, or agents
 just spawned. Confirm the desired check interval when ongoing oversight is
 requested; default to five minutes only after the user agrees.
 
-This plugin does not add a timer or Claude Code's generic scheduled background
-monitor. Before promising recurring checks, identify an explicit timer/recurring
-monitor tool that is actually available in the current Codex session. The ours
-mail monitor is event-driven and does not provide five-minute timer wakeups. If
-no real timer tool is present, say that the interval cannot be armed: offer
-active foreground observation or manual checks instead. Never say “I created a
+This plugin does not add a timer or a generic scheduled background monitor.
+Before promising recurring checks, identify an explicit timer/recurring monitor
+tool that is actually available in the current Codex session. The ours mail
+monitor is event-driven and does not provide five-minute timer wakeups. If no
+real timer tool is present, say that the interval cannot be armed: offer active
+foreground observation or manual checks instead. Never say “I created a
 recurring monitor” based only on this skill. For durable operation, recommend a
 supervised coordinator role and message-driven wake through `ours-codex`, while
 remaining clear that messages—not elapsed time—wake it.
 
-## On each check
+## One console command is not a liveness verdict
+
+This is the mistake that gets busy agents killed. `peek` and `send` tell you what
+happened to YOUR REQUEST. Only one of their outcomes is evidence that the agent
+is gone. On each check run BOTH — they answer different questions:
+
+```sh
+ours-fleet status <Name>     # is the role supervised and alive?
+ours-fleet peek <Name>       # what is on its console right now?
+```
+
+Read the result you actually got:
+
+- **queued** — the session accepted the prompt for '<Name>'; a turn already running is not a failure. → Nothing. Do not resend, and do not read the absence of a reply as a stall — check progress with: ours-fleet peek <Name>
+- **timeout** — '<Name>' did not answer in time; a busy agent looks exactly like this. Check: ours-fleet status <Name> → Treat delivery as UNCERTAIN — the request may already have been acted on, so do not resend it blindly.
+- **rejected** — '<Name>' is running and refused the request. → Fix the request, not the agent. A refusal is proof of life.
+- **control-unavailable** — this says nothing about whether '<Name>' is alive — its control plane did not answer; check: ours-fleet status <Name> → Read the role logs as well. The control plane and the agent are separate things, and one being unreachable is not evidence about the other.
+- **backend** — this is a transport failure, not evidence that '<Name>' is gone; check: ours-fleet status <Name> → Investigate the transport, not the agent.
+- **offline** — '<Name>' is confirmed offline. → This is the ONLY result that justifies a restart on its own: ours-fleet restart <Name> for a permanent role. Read the logs first.
+
+Never translate any other result into "dead". `ours-fleet` prints the same
+liveness note the CLI derived the result from, so quote what it said rather than
+paraphrasing it as "not running".
+
+## Judge the console content
 
-Peek once and classify the evidence:
+Once you know the role is alive, classify the evidence:
 
-- **Active and progressing:** leave it alone.
+- **Active and progressing:** leave it alone. A long turn is not a stall.
 - **Codex MCP authorization prompt:** surface the requested tool and scope.
   Session-only approval is safer for tests; persistent approval requires the
   user's explicit authorization.
@@ -46,8 +74,8 @@ Peek once and classify the evidence:
   context; otherwise escalate.
 - **Idle with unfinished work:** ask for status and direct it to continue or
   declare `BLOCKED`.
-- **Crash or shell prompt:** inspect logs, diagnose, then restart permanent
-  roles with `ours-fleet restart <Name>` when safe.
+- **Crash or shell prompt:** inspect logs and diagnose. Restart a permanent role
+  with `ours-fleet restart <Name>` only once `status` confirms it is offline.
 - **Completed temporary role:** report the result and let its supervisor clean
   up; stop checking it.
 

package/skills/spawn-ours-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spawn-ours-agent
-description: Spawn and configure a new ours-fleet agent from Codex, either as a supervised persistent role or a temporary tmux agent. Use when the user asks to spawn an agent, create a fleet role, start a background agent, delegate work to another Codex session, choose its model or permissions, or create a subagent that should have its own ours identity and console.
+description: Spawn and configure a new ours-fleet agent from Codex, with a permanent or temporary lifetime and a tmux or ACP session. Use when the user asks to spawn an agent, create a fleet role, start a background agent, delegate work to another Codex session, choose its model, session, or permissions, or create a subagent with its own ours identity and console.
 ---
 
 # Spawn an ours-fleet agent
@@ -8,23 +8,89 @@ description: Spawn and configure a new ours-fleet agent from Codex, either as a
 Use the `ours-fleet` CLI to create the role. Do not simulate a subagent inside
 the current conversation.
 
-## 1. Check the host
-
-Run:
+## 1. Read the installed CLI reference — this step is not optional
 
 ```sh
+ours-fleet docs
 ours-fleet doctor --harness codex
 ```
 
-Stop at a failed required check. Explain that `ours-codex` is preferred for
-background mail wake and native `codex` is the supported fallback.
-
-## 2. Resolve the role design
+`ours-fleet docs` from the INSTALLED CLI is authoritative for supported session
+backends, permissions, and flags. This skill ships with a plugin and the CLI is
+upgraded separately, so where the two differ the installed reference wins. Stop
+at a failed required doctor check.
+
+## 2. Understand the two permission traps before you choose anything
+
+Both traps produce the same symptom: an agent that does less than its briefing
+told it to and reports no error, because the refusal happened inside the harness
+with no console attached to see it.
+
+**Trap 1 — a mode that suppresses the prompt without granting the action.** On
+Claude Code this is `dontAsk`, which hides the permission prompt and still
+refuses the action; it is why neutral `--approval allow` maps to
+`bypassPermissions` rather than to the mode whose name sounds milder. On Codex
+the same shape applies to native approval: only `never` reaches the tools
+without a console, and `on-request` becomes a refusal when nobody can answer.
+Judge a native mode by what it grants, not by how permissive its name sounds.
+
+**Trap 2 — the unattended capability floor.** A role with no console cannot
+answer a permission request, so the request is refused. `ours-fleet` checks each
+role's resolved permissions against a fixed floor before launch:
+
+- `read-state` — read its briefing, ROUTINES.md, and WORKLOG.md
+- `write-state` — append its WORKLOG and its own state files
+- `messaging` — bind its identity, send and receive ours mail
+- `monitor` — arm and observe its mail monitor
+- `workspace-edit` — edit and test files in its working directory
+- `status-commands` — run the inspection commands its briefing prescribes
+
+`ours-fleet config` and `ours-fleet doctor` report this per role as
+`unattended floor: <Name>`. Under `--unattended deny` a shortfall FAILS doctor,
+because those requests will be denied silently. Under `--unattended wait` it
+warns, because a human can still attach and answer.
+
+What this means in practice, on this harness:
+
+| Neutral intent | Native settings | Meets the floor? |
+| --- | --- | --- |
+| `--approval allow --filesystem workspace` | `approval=never sandbox=workspace-write` | yes |
+| `--approval allow --filesystem read-only` | `approval=never sandbox=read-only` | no — no `write-state`, no `workspace-edit` |
+| `--approval ask` | `approval=on-request` | no — `read-state` only |
+| `--approval deny` | `approval=on-request` | no — `read-state` only |
+
+## 3. Choose permissions from the job, not from a default
+
+There is no safe blanket default. Ask what the role has to do and whether the
+user authorizes it, then pick:
+
+- **It must work with nobody watching** (the usual reason to spawn a fleet
+  role): it needs `--approval allow --filesystem workspace`. That is a real
+  grant, so get the user's explicit authorization for it, and confine the role
+  with `--isolation-file` rather than by withholding permissions it needs.
+  Use `--unattended deny` so the role never blocks on an unanswerable request.
+- **A human will attach and answer prompts**: `--approval ask --filesystem
+  workspace --unattended wait`. Doctor warns that the floor is unmet — that
+  warning is correct and expected; the role will block until someone answers.
+- **The user will not authorize `allow`, and nobody will attend it**: say so
+  plainly. That role cannot do its job, and doctor will fail it. Reduce the job
+  or get the authorization; do not paper over it with a mode that only hides
+  the prompt.
+
+Never choose `--filesystem unrestricted`, `--sandbox danger-full-access`, or a
+native `--permission-mode` override without the user asking for it by name and
+understanding what it grants. `harness_options` wins over the neutral block at
+launch, so stating intent in both places and disagreeing is how a role runs on
+settings nobody chose — `ours-fleet config` and `doctor` print a
+`permission conflict: <Name>` line when that happens.
+
+## 4. Resolve the rest of the role design
 
 Ask only for choices not already supplied:
 
 - **Lifetime:** permanent (supervised, restartable, survives reboot) or
-  temporary (one tmux session, removed on exit).
+  temporary (detached supervisor, removed on exit/reboot).
+- **Session:** `tmux` or `acp`; both lifetimes support both.
 - **Name:** `[A-Za-z0-9_-]+`; confirm it is absent from `ours-fleet config` and
   `ours-fleet ls`.
 - **Mission and working directory.**
@@ -36,64 +102,100 @@ Ask only for choices not already supplied:
 - **Mail monitoring:** explicitly ask whether to arm it. Pass `--monitor` only
   after a clear yes. This consent persists in the role configuration.
 
-Offer Codex controls when relevant; otherwise use safe defaults:
+Codex-native controls, offered when relevant:
 
 - model: launcher default or `--model <id>`
-- approval: `untrusted`, `on-request`, or `never`
-- sandbox: `read-only`, `workspace-write`, or `danger-full-access`
+- native approval: `--permission-mode untrusted|on-request|never`
+- native sandbox: `--sandbox read-only|workspace-write|danger-full-access`
 - launcher: `auto` (preferred), `ours-codex`, or `codex`
 - profile: `--profile <name>`
 - search: `--search`
 - arbitrary config: repeatable `--codex-config key=value`
 - additional writable roots: repeatable `--add-dir <path>`
 
-Default to `--harness codex --launcher auto --sandbox workspace-write
---permission-mode on-request`. Never select `danger-full-access` or `never`
-without explicit user direction.
-
-## 3. Materialize approved profile text
+## 5. Materialize approved profile text
 
 Use `apply_patch` to write the approved bio and persona to uniquely named files
 under `/tmp`. Do not interpolate untrusted text into a shell heredoc.
 
-## 4. Spawn
+## 6. Confine the role at creation, not later
 
-Build an argument array from the approved choices. Permanent example:
+`--isolation-file <path>` supplies the role's sandbox policy at creation, so the
+FIRST launch is already confined. A role that only gains `isolation:` on a later
+`up` ran unsandboxed until then. The file holds exactly the `isolation:` mapping
+documented in `ours-fleet docs` and nothing else:
+
+```yaml
+network: deny
+fs:
+  read: [/opt/reference]
+resources:
+  mem: 2G
+```
+
+An invalid file is rejected before anything is created — no config, no state
+directory, no identity reservation. This is the right control for a role that
+needs `--approval allow`: isolation is the outer boundary a permission mode
+cannot cross.
+
+## 7. Spawn
+
+Build an argument array from the approved choices. Permanent, unattended:
 
 ```sh
 ours-fleet spawn Worker --harness codex --launcher auto \
+  --session <tmux|acp> \
   --mission "Own the worker implementation" --cwd /absolute/project \
   --bio-file /tmp/worker-bio.md --persona-file /tmp/worker-persona.md \
-  --sandbox workspace-write --permission-mode on-request \
+  --approval allow --filesystem workspace --unattended deny \
+  --isolation-file /tmp/worker-isolation.yaml \
   --coordinator Coordinator
 ```
 
-Add `--temp` for a temporary role and `--monitor` only after monitoring consent.
+Permanent, attended — a human will answer its prompts:
+
+```sh
+ours-fleet spawn Worker --harness codex --launcher auto \
+  --session <tmux|acp> \
+  --mission "Own the worker implementation" --cwd /absolute/project \
+  --bio-file /tmp/worker-bio.md --persona-file /tmp/worker-persona.md \
+  --approval ask --filesystem workspace --unattended wait
+```
+
+Add `--temp` for a temporary role; it can also use `--session acp`.
+Pass `--monitor` only after monitoring consent.
 Pass model, profile, search, config, and additional directories exactly as
 approved. Do not persist secrets in `--codex-config` or fleet YAML; use the
 role's `env` configuration for environment-based credentials.
 
-## 5. Verify the real session
-
-Run:
+## 8. Verify the real session
 
 ```sh
+ours-fleet doctor --harness codex
 ours-fleet peek <Name> 60
 ours-fleet status <Name>
 ```
 
-For a temporary role, status may not have a system service; the tmux console is
-authoritative. Confirm that Codex loaded its briefing and reached identity
-binding. First use can display Codex authorization prompts for ours MCP tools.
+Read doctor's `permissions: <Name>` and `unattended floor: <Name>` lines for the
+role you just created. `permissions:` shows the neutral intent and the native
+settings it translated to; the floor line lists what the role actually grants,
+or names what is missing. A failure there means the role will silently do less
+than its briefing says — fix the permissions rather than starting it.
+
+For ACP, `status` must report `backend: acp`, `alive: true`, and a running/idle
+readiness. For a temporary tmux role, the pane is authoritative. Confirm that
+Codex loaded its briefing and reached identity binding. First use can display
+Codex authorization prompts for ours MCP tools.
 Surface those prompts to the user; do not grant persistent trust without their
-explicit approval. Use `ours-fleet send <Name> --key <choice>` only for the
-authorization scope the user approved.
+explicit approval. Use `ours-fleet send <Name> --key <choice>` only for tmux and
+only for the authorization scope the user approved; ACP permissions are answered
+through `ours-fleet attach`.
 
 If monitoring was approved, confirm the console reports `arm_monitor` success.
 Under native Codex, expect the role to surface the `ours-codex` recommendation
 before offering the blocking foreground fallback.
 
-## 6. Hand off oversight
+## 9. Hand off oversight
 
 Treat the spawned role as a ward. Use the `oversee-agents` skill for immediate
 checks and interventions. State clearly whether ongoing timed oversight is