@ours.network/fleet 0.9.4 → 0.9.5

package/dist/docs.js

@@ -0,0 +1,177 @@
+/**
+ * Stable, AI-friendly CLI and configuration reference.
+ *
+ * Keep this concise enough to place directly in an agent context. Unlike
+ * Commander's per-command help, this describes how the pieces compose.
+ */
+export const AI_DOCS = `# ours-fleet reference
+
+ours-fleet runs persistent or temporary, identity-bound AI roles. A role selects
+a harness independently from its session backend:
+
+- harness: \`claude-code\` or \`codex\`
+- session: \`tmux\` (default) or \`acp\`
+- lifetime: permanent (supervised, restartable) or \`spawn --temp\`
+
+## Discover and validate
+
+\`\`\`sh
+ours-fleet docs                         # this complete reference (\`man\` is an alias)
+ours-fleet help <command>               # exact flags for one command
+ours-fleet config [-c FILE]             # validate and print the merged plan; no changes
+ours-fleet doctor [-c FILE] [--harness codex|claude-code]
+\`\`\`
+
+Default configuration is \`~/fleet.yaml\` plus sorted \`~/fleet.d/*.yaml\` role
+drop-ins. An explicit \`-c FILE\` replaces \`~/fleet.yaml\`; fleet.d still adds
+roles. Validate with \`config\` and \`doctor\` before starting or restarting.
+
+## Lifecycle and console commands
+
+\`\`\`sh
+ours-fleet init
+ours-fleet up|down [Name...]
+ours-fleet restart [Name...]            # preserve/resume harness context
+ours-fleet force-restart [Name...]      # fresh context; briefing is reloaded
+ours-fleet ls
+ours-fleet status|peek|attach|logs Name
+ours-fleet logs -f Name
+ours-fleet send Name "prompt"
+ours-fleet send Name --key Enter        # tmux only
+ours-fleet rm Name
+\`\`\`
+
+\`peek\`, \`attach\`, and text \`send\` work with tmux and ACP. ACP attachment
+also accepts \`/permit <permission-id> <option-id>\`, \`/interrupt\`, and
+\`/detach\`. Raw \`--key\` input is tmux-only.
+
+## Spawn
+
+\`\`\`sh
+ours-fleet spawn [--temp] Name \\
+  --harness codex|claude-code --session tmux|acp \\
+  --mission "one line" --cwd /absolute/path --identity Identity \\
+  --coordinator Coordinator --model MODEL \\
+  --approval ask|allow|deny \\
+  --filesystem read-only|workspace|unrestricted \\
+  --unattended deny|wait \\
+  --bio-file /path/bio.md --persona-file /path/persona.md
+\`\`\`
+
+Permanent spawn writes \`~/fleet.d/Name.yaml\` and starts a supervised role.
+\`--temp\` writes ephemeral state, starts a detached supervisor, and removes the
+role after exit/reboot. Both lifetimes support \`--session acp\`.
+
+Codex-specific spawn flags: \`--sandbox\`, \`--permission-mode\`, \`--launcher\`,
+\`--profile\`, \`--search\`, repeatable \`--codex-config key=value\`, repeatable
+\`--add-dir\`, and \`--monitor\`. Run \`ours-fleet help spawn\` for exact values.
+
+## fleet.yaml
+
+\`\`\`yaml
+vars:
+  work_root: /home/me/work
+start_stagger_ms: 0
+defaults:
+  harness: codex
+  session: acp
+  model: gpt-model-id
+  permissions:
+    approval: ask
+    filesystem: workspace
+    unattended: deny
+  monitor:
+    enabled: true
+roles:
+  Coordinator:
+    harness: codex
+    session: acp
+    identity: Coordinator
+    cwd: \${work_root}/project
+    mission: Coordinate work and delegate implementation.
+    model: gpt-model-id
+    permissions:
+      approval: ask
+      filesystem: workspace
+      unattended: deny
+    session_options:                    # advanced overrides; normally omit
+      # acp:
+      #   command: [/custom/codex-acp, --flag]
+      tmux:
+        boot_grace_ms: 10000
+    monitor:
+      enabled: true
+      wake_sources: [message_received, file_received, local_contact_request, pending_message]
+      batch_ms: 2000
+      inject: notification
+      turn_fail_threshold: 3
+    harness_options:
+      launcher: auto
+      sandbox: workspace-write
+      approval: on-request
+      search: false
+      profile: fleet
+      add_dirs: [/data/shared]
+      config:
+        model_reasoning_effort: high
+    bio: Public role card and when peers should engage it.
+    persona: Local operating contract, boundaries, and escalation policy.
+    briefing_file: /absolute/custom-briefing.md
+    coordinator: AnotherCoordinator
+    env:
+      KEY: value
+    oversee:
+      - { role: Worker, interval: 5m }
+\`\`\`
+
+Role values override defaults. \`\${name}\` substitutes entries from \`vars\`.
+Other role fields include \`max_tokens\`, \`autocompact_pct\`, and \`isolation\`.
+Use README.md for the complete isolation policy and resource-cap schema.
+
+## Permissions
+
+Prefer the harness-neutral \`permissions\` block:
+
+- \`approval: ask|allow|deny\`: whether actions may request or receive approval
+- \`filesystem: read-only|workspace|unrestricted\`: filesystem intent
+- \`unattended: deny|wait\`: what ACP does when no console can answer a request
+
+The backend translates this common intent. Harness-native settings in
+\`harness_options\` take precedence where supplied. Do not choose
+\`allow\`/\`unrestricted\`, Codex \`never\`/\`danger-full-access\`, or Claude
+\`bypassPermissions\` without explicit authorization.
+
+Claude \`harness_options\`: \`permission_mode\` (default, acceptEdits, plan,
+dontAsk, bypassPermissions), \`plugins\`, \`mem_palace\`, and
+\`mem_palace_midsession_autosave\`.
+
+Codex \`harness_options\`: \`launcher\` (auto, ours-codex, codex), \`sandbox\`
+(read-only, workspace-write, danger-full-access), \`approval\` or
+\`permission_mode\` (untrusted, on-request, never), \`profile\`, \`search\`,
+\`config\`, \`add_dirs\`, and \`monitor\`.
+
+## ACP adapters
+
+The maintained \`@agentclientprotocol/codex-acp\` and
+\`@agentclientprotocol/claude-agent-acp\` runtimes are bundled automatically as
+optional ours-fleet dependencies. The supervisor resolves their executable
+entrypoints internally, so default ACP roles do not depend on global PATH.
+The maintained Claude adapter requires Node 22; tmux and Codex ACP continue to
+work on the ours-fleet core minimum of Node 20.
+
+Override an adapter only when necessary with \`session_options.acp.command\`
+(string or argv list). If optional dependencies were deliberately omitted,
+ours-fleet falls back to a compatible globally installed \`codex-acp\` or
+\`claude-agent-acp\`. \`ours-fleet doctor -c FILE\` verifies the resolved adapter.
+
+## Reliable mail wake
+
+The supervisor monitor is enabled by default. It consumes body-free daemon
+events and advances its durable cursor only after delivery is accepted. ACP uses
+a structured \`session/prompt\`; tmux uses verified console injection. Message
+bodies are released only when the role calls the ours \`get_messages\` tool.
+
+Set \`monitor.enabled: false\` only to retain legacy in-session monitoring.
+Inspect \`ours-fleet status Name\`, \`peek Name\`, role logs, and
+\`~/.ours-fleet/agents/Name/.monitor-status\` when diagnosing delivery.
+`;

package/dist/doctor.js

@@ -3,6 +3,7 @@ import { readFileSync } from 'node:fs';
 import { realExec } from './exec.js';
 import { loadConfig } from './config.js';
 import { getAdapter } from './harness/registry.js';
+import { resolveBundledAcpAgent } from './harness/acp-agent.js';
 import { agentDir, home, deriveXdgRuntimeDir } from './paths.js';
 import { resolveIsolation } from './isolation/policy.js';
 import { makeBubblewrapBackend } from './isolation/bubblewrap.js';
@@ -43,11 +44,14 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
         name: 'node', ok: major >= 20,
         detail: major >= 20 ? `v${process.versions.node}` : `v${process.versions.node} — need >= 20`,
     });
-    const tmux = await exec('tmux', ['-V']);
-    checks.push({
-        name: 'tmux', ok: tmux.code === 0,
-        detail: tmux.code === 0 ? tmux.stdout.trim() : 'not found — apt install tmux / brew install tmux',
-    });
+    const roles = loadConfigSafe(opts.configPath);
+    if (roles.length === 0 || roles.some(role => (role.session ?? 'tmux') === 'tmux')) {
+        const tmux = await exec('tmux', ['-V']);
+        checks.push({
+            name: 'tmux', ok: tmux.code === 0,
+            detail: tmux.code === 0 ? tmux.stdout.trim() : 'not found — apt install tmux / brew install tmux',
+        });
+    }
     const mcp = await exec('ours-mcp', ['--version']);
     checks.push({
         name: 'ours-mcp', ok: mcp.code === 0,
@@ -84,7 +88,6 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
     // opt-in per role (OQ-1), so a missing bwrap must not fail doctor for fleets that
     // don't use it. Only a role that DECLARES isolation and cannot get it under
     // `strict` is a hard failure.
-    const roles = loadConfigSafe(opts.configPath);
     const bw = await makeBubblewrapBackend(exec).available();
     checks.push({
         name: 'isolation: bubblewrap', ok: true,
@@ -169,6 +172,47 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
             checks.push({ name: h, ok: false, detail: e.message });
         }
     }
+    for (const role of roles.filter(role => role.session === 'acp')) {
+        const configured = role.session_options?.acp?.command;
+        const bundled = configured == null
+            ? role.harness === 'codex'
+                ? resolveBundledAcpAgent('@agentclientprotocol/codex-acp', 'codex-acp', 'codex-acp')
+                : role.harness === 'claude-code'
+                    ? resolveBundledAcpAgent('@agentclientprotocol/claude-agent-acp', 'claude-agent-acp', 'claude-agent-acp')
+                    : undefined
+            : undefined;
+        const command = Array.isArray(configured)
+            ? configured[0]
+            : typeof configured === 'string'
+                ? configured.trim().split(/\s+/)[0]
+                : role.harness === 'codex'
+                    ? 'codex-acp'
+                    : role.harness === 'claude-code'
+                        ? 'claude-agent-acp'
+                        : '';
+        if (!command) {
+            checks.push({
+                name: `acp: ${role.name}`, ok: false,
+                detail: `harness '${role.harness}' has no default ACP agent; set session_options.acp.command`,
+            });
+            continue;
+        }
+        if (bundled?.bundled) {
+            checks.push({
+                name: `acp: ${role.name}`, ok: true,
+                detail: `${command} bundled with ours-fleet`,
+            });
+            continue;
+        }
+        const result = await exec('sh', ['-c', 'command -v "$1" >/dev/null 2>&1', 'sh', command]);
+        checks.push({
+            name: `acp: ${role.name}`,
+            ok: result.code === 0,
+            detail: result.code === 0
+                ? `${command} available`
+                : `${command} not found or failed — install the ACP adapter or set session_options.acp.command`,
+        });
+    }
     return { ok: checks.every(c => c.ok), checks };
 }
 function loadConfigSafe(configPath) {

package/dist/harness/acp-agent.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolve an ACP agent shipped as an ours-fleet dependency. Running the JS
+ * entrypoint through this process's Node avoids depending on npm exposing a
+ * transitive dependency's bin on the user's global PATH.
+ */
+export interface AcpAgentResolution {
+    argv: string[];
+    bundled: boolean;
+}
+export declare function resolveBundledAcpAgent(packageName: string, binName: string, fallbackCommand: string): AcpAgentResolution;
+export declare function bundledAcpAgent(packageName: string, binName: string, fallbackCommand: string): string[];

package/dist/harness/acp-agent.js

@@ -0,0 +1,27 @@
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+const require = createRequire(import.meta.url);
+export function resolveBundledAcpAgent(packageName, binName, fallbackCommand) {
+    try {
+        const manifestPath = require.resolve(`${packageName}/package.json`);
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        const relative = typeof manifest.bin === 'string'
+            ? manifest.bin
+            : manifest.bin?.[binName];
+        if (!relative)
+            return { argv: [fallbackCommand], bundled: false };
+        const entrypoint = resolve(dirname(manifestPath), relative);
+        if (!existsSync(entrypoint))
+            return { argv: [fallbackCommand], bundled: false };
+        return { argv: [process.execPath, entrypoint], bundled: true };
+    }
+    catch {
+        // Supports development installs that intentionally omit optional
+        // dependencies and existing hosts with a globally installed adapter.
+        return { argv: [fallbackCommand], bundled: false };
+    }
+}
+export function bundledAcpAgent(packageName, binName, fallbackCommand) {
+    return resolveBundledAcpAgent(packageName, binName, fallbackCommand).argv;
+}

package/dist/harness/claude-code.js

@@ -3,14 +3,20 @@ import { join } from 'node:path';
 import { home } from '../paths.js';
 import { realExec } from '../exec.js';
 import { registerAdapter } from './registry.js';
+import { bundledAcpAgent } from './acp-agent.js';
 const OPTION_KEYS = ['plugins', 'mem_palace', 'mem_palace_midsession_autosave', 'permission_mode'];
 /** Claude Code's accepted --permission-mode values. */
 const PERMISSION_MODES = ['default', 'acceptEdits', 'plan', 'dontAsk', 'bypassPermissions'];
 /** Resolve & validate the per-role permission mode, throwing on an unknown value. */
 function permissionMode(role) {
     const pm = role.harness_options?.permission_mode;
-    if (pm == null)
+    if (pm == null) {
+        if (role.permissions?.approval === 'allow')
+            return 'dontAsk';
+        if (role.permissions?.approval === 'deny')
+            return 'plan';
         return undefined;
+    }
     if (!PERMISSION_MODES.includes(pm))
         throw new Error(`invalid harness_options.permission_mode "${pm}"; allowed: ${PERMISSION_MODES.join(', ')}`);
     return pm;
@@ -108,6 +114,30 @@ export function makeClaudeCodeAdapter(exec = realExec) {
                     this.vocabulary.restartPrompt(role.identity, join(stateDir, 'WORKLOG.md'), role)];
             return { argv, env: prep.env };
         },
+        buildAcpLaunch(role, prep) {
+            const configured = role.session_options?.acp?.command;
+            const argv = Array.isArray(configured)
+                ? [...configured]
+                : typeof configured === 'string'
+                    ? ['sh', '-c', configured]
+                    : bundledAcpAgent('@agentclientprotocol/claude-agent-acp', 'claude-agent-acp', 'claude-agent-acp');
+            return { argv, env: prep.env };
+        },
+        translatePermissions(permissions) {
+            const native = permissions.approval === 'allow'
+                ? 'dontAsk'
+                : permissions.approval === 'deny'
+                    ? 'plan'
+                    : 'default';
+            const exact = permissions.filesystem === 'workspace' && permissions.approval === 'ask';
+            return {
+                native: { permission_mode: native },
+                exact,
+                warnings: exact ? [] : [
+                    'Claude permission modes do not exactly represent independent approval and filesystem intent; fleet isolation remains the outer boundary',
+                ],
+            };
+        },
         vocabulary: {
             bindTool: 'choose_identity',
             createTool: 'create_identity',

package/dist/harness/codex.js

@@ -2,6 +2,7 @@ import { join } from 'node:path';
 import { agentDir } from '../paths.js';
 import { realExec } from '../exec.js';
 import { registerAdapter } from './registry.js';
+import { bundledAcpAgent } from './acp-agent.js';
 const OPTION_KEYS = [
     'launcher', 'sandbox', 'approval', 'permission_mode', 'search', 'profile', 'config', 'add_dirs',
     'monitor',
@@ -14,8 +15,16 @@ const APPROVAL_POLICIES = ['untrusted', 'on-request', 'never'];
 /** Resolve & validate the per-role sandbox mode, throwing on an unknown value. */
 function sandboxMode(role) {
     const s = role.harness_options?.sandbox;
-    if (s == null)
+    if (s == null) {
+        const filesystem = role.permissions?.filesystem;
+        if (filesystem === 'read-only')
+            return 'read-only';
+        if (filesystem === 'unrestricted')
+            return 'danger-full-access';
+        if (filesystem === 'workspace')
+            return 'workspace-write';
         return undefined;
+    }
     if (!SANDBOX_MODES.includes(s))
         throw new Error(`invalid harness_options.sandbox "${s}"; allowed: ${SANDBOX_MODES.join(', ')}`);
     return s;
@@ -24,8 +33,14 @@ function sandboxMode(role) {
 function approvalPolicy(role) {
     const o = role.harness_options;
     const a = o?.approval ?? o?.permission_mode;
-    if (a == null)
+    if (a == null) {
+        const approval = role.permissions?.approval;
+        if (approval === 'allow')
+            return 'never';
+        if (approval === 'ask' || approval === 'deny')
+            return 'on-request';
         return undefined;
+    }
     if (!APPROVAL_POLICIES.includes(a))
         throw new Error(`invalid harness_options.approval "${a}"; allowed: ${APPROVAL_POLICIES.join(', ')}`);
     return a;
@@ -173,6 +188,29 @@ export function makeCodexAdapter(exec = realExec) {
                     this.vocabulary.restartPrompt(role.identity, join(stateDir, 'WORKLOG.md'), role)];
             return { argv, env: prep.env };
         },
+        buildAcpLaunch(role, prep) {
+            const configured = role.session_options?.acp?.command;
+            const argv = Array.isArray(configured)
+                ? [...configured]
+                : typeof configured === 'string'
+                    ? ['sh', '-c', configured]
+                    : bundledAcpAgent('@agentclientprotocol/codex-acp', 'codex-acp', 'codex-acp');
+            return { argv, env: prep.env };
+        },
+        translatePermissions(permissions) {
+            return {
+                native: {
+                    approval: permissions.approval === 'allow' ? 'never' : 'on-request',
+                    sandbox: permissions.filesystem === 'read-only'
+                        ? 'read-only'
+                        : permissions.filesystem === 'unrestricted'
+                            ? 'danger-full-access'
+                            : 'workspace-write',
+                },
+                exact: true,
+                warnings: [],
+            };
+        },
         vocabulary: {
             bindTool: 'choose_identity',
             createTool: 'create_identity',

package/dist/harness/types.d.ts

@@ -1,4 +1,4 @@
-import type { ResolvedRole } from '../config.js';
+import type { CommonPermissions, ResolvedRole } from '../config.js';
 export interface PrereqCheck {
     name: string;
     ok: boolean;
@@ -26,6 +26,15 @@ export interface Launch {
     argv: string[];
     env: Record<string, string>;
 }
+export interface AcpLaunch {
+    argv: string[];
+    env: Record<string, string>;
+}
+export interface PermissionTranslation {
+    native: Record<string, unknown>;
+    exact: boolean;
+    warnings: string[];
+}
 /** Harness-correct wording/tool names used to generate briefing.md. */
 export interface BriefingVocab {
     bindTool: string;
@@ -57,6 +66,8 @@ export interface HarnessAdapter {
     validateOptions(opts: unknown): ValidationError[];
     prepareSession(role: ResolvedRole, dirs: RoleDirs): Promise<SessionPrep>;
     buildLaunch(role: ResolvedRole, mode: 'fresh' | 'resume', s: SessionState, prep: SessionPrep): Launch;
+    buildAcpLaunch?(role: ResolvedRole, prep: SessionPrep): AcpLaunch;
+    translatePermissions?(permissions: CommonPermissions): PermissionTranslation;
     vocabulary: BriefingVocab;
     exitPolicy: ExitPolicy;
 }

package/dist/index.d.ts

@@ -1,6 +1,9 @@
-export { loadConfig, findRole, ConfigError } from './config.js';
-export type { FleetConfig, ResolvedRole, RoleConfig, OverseeEntry } from './config.js';
-export type { HarnessAdapter, BriefingVocab, ExitPolicy, PrereqReport, PrereqCheck, SessionPrep, SessionState, Launch, RoleDirs, ValidationError, } from './harness/types.js';
+export { loadConfig, findRole, resolvePermissions, ConfigError } from './config.js';
+export type { FleetConfig, ResolvedRole, RoleConfig, OverseeEntry, SessionBackendId, CommonPermissions, SessionOptions, } from './config.js';
+export type { HarnessAdapter, BriefingVocab, ExitPolicy, PrereqReport, PrereqCheck, SessionPrep, SessionState, Launch, AcpLaunch, PermissionTranslation, RoleDirs, ValidationError, } from './harness/types.js';
+export type { SessionHandle, SessionSnapshot, SessionEvent, TurnResult, } from './session/types.js';
+export { AcpSession } from './session/acp.js';
+export { TmuxSession } from './session/tmux.js';
 export { registerAdapter, getAdapter, knownAdapters } from './harness/registry.js';
 export { claudeCodeAdapter, makeClaudeCodeAdapter } from './harness/claude-code.js';
 export { codexAdapter, makeCodexAdapter } from './harness/codex.js';

package/dist/index.js

@@ -1,4 +1,6 @@
-export { loadConfig, findRole, ConfigError } from './config.js';
+export { loadConfig, findRole, resolvePermissions, ConfigError } from './config.js';
+export { AcpSession } from './session/acp.js';
+export { TmuxSession } from './session/tmux.js';
 export { registerAdapter, getAdapter, knownAdapters } from './harness/registry.js';
 export { claudeCodeAdapter, makeClaudeCodeAdapter } from './harness/claude-code.js';
 export { codexAdapter, makeCodexAdapter } from './harness/codex.js';

package/dist/monitor.d.ts

@@ -38,6 +38,13 @@ export interface MonitorDeps {
         set(fn: () => void, ms: number): ReturnType<typeof setTimeout>;
         clear(t: ReturnType<typeof setTimeout>): void;
     };
+    /** Structured prompt delivery used by ACP sessions. Tmux remains the fallback. */
+    delivery?: {
+        submit(text: string): Promise<{
+            accepted: boolean;
+            detail?: string;
+        }>;
+    };
 }
 /** Best-effort daemon config (issue #17): the fields the MCP client reads. */
 interface DaemonConfig {
@@ -112,6 +119,8 @@ export declare function looksApiError(pane: string): boolean;
 export declare function looksRunning(pane: string): boolean;
 export interface MonitorOpts {
     name: string;
+    /** Ours identity whose notification stream is authoritative (may differ from role name). */
+    identity?: string;
     agentDir: string;
     cfg: MonitorConfig;
     deps: MonitorDeps;
@@ -124,12 +133,16 @@ export interface MonitorHandle {
 }
 export declare class Monitor {
     private readonly name;
+    private readonly identity;
     private readonly cfg;
     private readonly deps;
     private readonly ep;
     private readonly statusPath;
     private readonly cursorPath;
+    private readonly statePath;
     private cursor;
+    private deliveredCursor;
+    private pendingState;
     private fatal;
     private stopped;
     private bootDeadline;
@@ -137,7 +150,7 @@ export declare class Monitor {
     private apiErrorStreak;
     private readonly turnFailThreshold;
     constructor(o: MonitorOpts);
-    /** Prime at the stream tip (or resume a persisted cursor if the daemon is down). */
+    /** Resume the last delivered cursor; only a brand-new monitor primes at stream tip. */
     prime(): Promise<void>;
     /** Long-poll → filter → coalesce → inject, until the pane pid dies or stop(). */
     run(pid: number): Promise<void>;
@@ -175,6 +188,8 @@ export declare class Monitor {
     private advance;
     private persistCursor;
     private readPersistedCursor;
+    /** Atomically persist body-free delivery state; restart always resumes from deliveredCursor. */
+    private persistState;
     private setStatus;
 }
 export declare function createMonitor(o: MonitorOpts): Monitor;