@ours.network/fleet-codex 0.10.0-nightly.4 → 0.11.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ours-fleet",
-  "version": "0.10.0-nightly.4",
+  "version": "0.11.0",
   "description": "Spawn, configure, and oversee ours-fleet roles from OpenAI Codex.",
   "author": {
     "name": "Adapt Framework Solutions Ltd",
@@ -9,14 +9,7 @@
   "homepage": "https://github.com/adapt-toolkit/ours-fleet/tree/main/integrations/codex/ours-fleet",
   "repository": "https://github.com/adapt-toolkit/ours-fleet",
   "license": "FSL-1.1-Apache-2.0",
-  "keywords": [
-    "codex",
-    "ours.network",
-    "fleet",
-    "agents",
-    "spawn",
-    "oversight"
-  ],
+  "keywords": ["codex", "ours.network", "fleet", "agents", "spawn", "oversight"],
   "skills": "./skills/",
   "interface": {
     "displayName": "ours.network Fleet",
@@ -24,11 +17,7 @@
     "longDescription": "Create temporary or supervised ours-fleet roles, configure Codex models and permissions, and keep spawned agents healthy from inside Codex.",
     "developerName": "Adapt Framework Solutions Ltd",
     "category": "Productivity",
-    "capabilities": [
-      "Interactive",
-      "Read",
-      "Write"
-    ],
+    "capabilities": ["Interactive", "Read", "Write"],
     "websiteURL": "https://ours.network",
     "defaultPrompt": [
       "Spawn a new Codex fleet agent for this task.",

package/README.md

@@ -19,6 +19,8 @@ Then ask Codex to “spawn an ours agent”, “create a persistent Codex role
 “keep an eye on my fleet agents”.
 
 Codex may ask for one-time authorization before individual ours MCP tools run.
-Mail wake is consent-first: a spawned role receives `--monitor` only when the
-user explicitly requests it. `ours-codex` supplies background wake; native
-`codex` remains the supported foreground-monitor fallback.
+Native Codex mail wake is consent-first: a spawned role receives the legacy
+`--monitor` consent flag only when the user explicitly requests it.
+In fleet YAML, `monitor.mode: fleet|native` separately chooses whether
+ours-fleet or the harness owns wake delivery. `ours-codex` supplies native
+background wake; plain `codex` remains the supported native foreground fallback.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/fleet-codex",
-  "version": "0.10.0-nightly.4",
+  "version": "0.11.0",
   "description": "Native Codex plugin for spawning, configuring, and overseeing ours-fleet agents.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",
@@ -11,32 +11,13 @@
     "url": "git+https://github.com/adapt-toolkit/ours-fleet.git",
     "directory": "integrations/codex/ours-fleet"
   },
-  "keywords": [
-    "codex",
-    "openai",
-    "plugin",
-    "fleet",
-    "agents",
-    "spawn",
-    "oversight",
-    "ours.network"
-  ],
-  "files": [
-    ".codex-plugin",
-    "skills",
-    "bin",
-    "README.md",
-    "LICENSE"
-  ],
+  "keywords": ["codex", "openai", "plugin", "fleet", "agents", "spawn", "oversight", "ours.network"],
+  "files": [".codex-plugin", "skills", "bin", "README.md", "LICENSE"],
   "bin": {
     "ours-fleet-codex-install": "bin/ours-fleet-codex-install.mjs"
   },
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
+  "engines": { "node": ">=20" },
+  "publishConfig": { "access": "public" },
   "scripts": {
     "test": "node --test"
   }

package/skills/oversee-agents/SKILL.md

@@ -26,21 +26,45 @@ 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
 
-Peek once and classify the evidence:
+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:
 
-- **Active and progressing:** leave it alone.
+```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
+
+Once you know the role is alive, classify the evidence:
+
+- **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.
@@ -50,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

@@ -8,26 +8,89 @@ description: Spawn and configure a new ours-fleet agent from Codex, with a perma
 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
 ```
 
-Treat `ours-fleet docs` from the installed CLI as authoritative for supported
-session backends, common permissions, and flags. Stop at a failed required
-doctor check.
-
-## 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 (detached supervisor, removed on exit/reboot).
-- **Session:** `tmux` or `acp`; both permanent and temporary roles support both.
+- **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,16 +99,11 @@ Ask only for choices not already supplied:
 - **Persona:** local operating contract covering mandate, quality bar,
   boundaries, and escalation. Use the writing-agent-bios skill when available.
 - **Coordinator:** optionally announce readiness to an existing ours identity.
-- **Mail monitoring:** explicitly ask whether to arm it. Pass `--monitor` only
-  after a clear yes. This consent persists in the role configuration.
-
-Prefer common permission intent:
+- **Native Codex mail monitoring:** explicitly ask whether to arm it. Pass the
+  legacy `--monitor` consent flag only after a clear yes. This is distinct from
+  fleet YAML `monitor.mode: fleet|native`, which chooses the wake owner.
 
-- approval: `--approval ask|allow|deny`
-- filesystem: `--filesystem read-only|workspace|unrestricted`
-- unattended ACP behavior: `--unattended deny|wait`
-
-Offer Codex-native controls when relevant:
+Codex-native controls, offered when relevant:
 
 - model: launcher default or `--model <id>`
 - native approval: `--permission-mode untrusted|on-request|never`
@@ -56,43 +114,76 @@ Offer Codex-native controls when relevant:
 - arbitrary config: repeatable `--codex-config key=value`
 - additional writable roots: repeatable `--add-dir <path>`
 
-Default to `--harness codex --session tmux --launcher auto --approval ask
---filesystem workspace --unattended deny`. Never select unrestricted access,
-`danger-full-access`, `never`, or common `allow` 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 \
-  --approval ask --filesystem workspace --unattended deny \
+  --approval allow --filesystem workspace --unattended deny \
+  --isolation-file /tmp/worker-isolation.yaml \
   --coordinator Coordinator
 ```
 
+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 the legacy `--monitor` flag only after consent to arm Codex's native
+monitor. It does not select the wake owner; `monitor.mode` does that in YAML.
 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>
 ```
 
+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
@@ -106,7 +197,7 @@ 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