@ours.network/fleet 0.9.5 → 0.9.7

package/dist/harness/registry.js

@@ -1,5 +1,14 @@
 const adapters = new Map();
 export function registerAdapter(a) {
+    // Enforced here rather than left to the type system: an adapter that silently
+    // omits the capability is how the neutral-permission warnings ended up with no
+    // caller and no reader.
+    if (typeof a.translatePermissions !== 'function')
+        throw new Error(`harness adapter '${a.id}' must implement translatePermissions(): either translate ` +
+            `neutral permissions or return { supported: false, reason }`);
+    if (typeof a.nativePermissionOverrides !== 'function')
+        throw new Error(`harness adapter '${a.id}' must implement nativePermissionOverrides(): report the ` +
+            `native permission settings a role states in harness_options, or {}`);
     adapters.set(a.id, a);
 }
 export function getAdapter(id) {
@@ -11,3 +20,13 @@ export function getAdapter(id) {
 export function knownAdapters() {
     return [...adapters.keys()];
 }
+/**
+ * The adapters ours-fleet ships. Tests register extras, so "everything in the
+ * registry" is not the same question — this is the set doctor falls back to
+ * when a broken configuration names no harness at all.
+ */
+const PRODUCTION_ADAPTERS = ['claude-code', 'codex'];
+/** Production adapters actually registered in this process. */
+export function productionAdapters() {
+    return PRODUCTION_ADAPTERS.filter(id => adapters.has(id));
+}

package/dist/harness/types.d.ts

@@ -30,11 +30,32 @@ export interface AcpLaunch {
     argv: string[];
     env: Record<string, string>;
 }
-export interface PermissionTranslation {
+/**
+ * The result of expressing neutral `permissions:` in a harness's own terms.
+ *
+ * `supported: false` is a first-class answer, not an absence. The previous
+ * shape made `translatePermissions` optional, so an adapter that simply never
+ * implemented it was indistinguishable from one that had nothing to say — and
+ * the warnings the implementations DID produce had no caller at all.
+ */
+/**
+ * What an unattended agent must actually be able to DO to run its own briefing.
+ * A role that cannot meet this floor does not fail loudly — it silently does
+ * less than it was asked to, because the denial happens inside the harness with
+ * nobody to see it.
+ */
+export type UnattendedCapability = 'read-state' | 'write-state' | 'messaging' | 'monitor' | 'workspace-edit' | 'status-commands';
+export type PermissionTranslation = {
+    supported: true;
     native: Record<string, unknown>;
     exact: boolean;
     warnings: string[];
-}
+    /** What the native settings above actually permit, unattended. */
+    capabilities: UnattendedCapability[];
+} | {
+    supported: false;
+    reason: string;
+};
 /** Harness-correct wording/tool names used to generate briefing.md. */
 export interface BriefingVocab {
     bindTool: string;
@@ -51,6 +72,16 @@ export interface BriefingVocab {
     launchNote(name: string): string;
     restartPrompt(identity: string, worklogPath: string, role?: ResolvedRole): string;
 }
+/**
+ * How a harness's host state splits for sandboxing (5.1). `home` is the
+ * directory the CLI treats as its own and whose RUNTIME state must be per-role;
+ * `shared` are the credential, instruction and configuration paths that stay
+ * shared and become read-only inside the sandbox.
+ */
+export interface HarnessIsolationPaths {
+    home?: string;
+    shared: string[];
+}
 export interface ExitPolicy {
     cleanExitIsFresh: boolean;
     fastFailSecs: number;
@@ -67,7 +98,23 @@ export interface HarnessAdapter {
     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;
+    /**
+     * REQUIRED. Every adapter must either translate neutral permissions or
+     * explicitly declare that it cannot. Enforced at registration.
+     */
+    translatePermissions(permissions: CommonPermissions): PermissionTranslation;
+    /**
+     * The permission settings this role states NATIVELY in `harness_options`,
+     * keyed the same way `translatePermissions().native` is, so the two can be
+     * compared directly. Only keys the operator actually wrote appear.
+     */
+    nativePermissionOverrides(options: unknown): Record<string, unknown>;
+    /**
+     * Host paths this harness needs inside a sandbox, split into a per-role
+     * writable home and shared read-only credentials/config (5.1). Omit for a
+     * harness with no host state of its own.
+     */
+    isolationPaths?(role: ResolvedRole, dirs: RoleDirs): HarnessIsolationPaths;
     vocabulary: BriefingVocab;
     exitPolicy: ExitPolicy;
 }

package/dist/isolation/bubblewrap.js

@@ -8,7 +8,13 @@ import { realExec } from '../exec.js';
 export function unsharesNet(network) {
     return network === 'deny';
 }
-/** Build the `bwrap … -- <argv>` sandbox launcher argv. Pure — no I/O. */
+/**
+ * Build the `bwrap … -- <argv>` sandbox launcher argv. Pure — no I/O.
+ *
+ * Consumes an ALREADY-ENFORCED mount set: `resolveIsolation` has refused
+ * anything that breaches the forbidden-path list, so no forbidden path can
+ * reach this argv. This function must never add a mount of its own.
+ */
 function wrap(argv, policy, ctx) {
     const out = [
         'bwrap',

package/dist/isolation/policy.d.ts

@@ -1,17 +1,46 @@
 import { type IsolationConfig, type ResolvedIsolation, type WrapContext } from './types.js';
+/** A mount that the forbidden-path policy refuses. Raised before any launch. */
+export declare class IsolationPolicyError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve a path to its canonical form, following symlinks as far as the
+ * filesystem allows and normalising the rest. Without this, `~/link-to-ssh`
+ * and `/home/u/.ssh` are different strings for the same directory, and a
+ * string comparison against the forbidden list is trivially side-stepped.
+ */
+export declare function canonicalPath(p: string): string;
+/**
+ * How a canonical mount path collides with a canonical forbidden path.
+ *
+ * `parent` matters as much as the other two: binding `$HOME` does not name
+ * `~/.ssh`, but it exposes it just as completely.
+ */
+export declare function mountConflict(mount: string, forbidden: string): 'exact' | 'descendant' | 'parent' | null;
 /**
  * Validate a raw `isolation:` block. Returns a list of human-readable problems
  * (empty ⇒ valid). Pure; callable from config.ts like adapter.validateOptions.
  */
 export declare function validateIsolationConfig(raw: unknown): string[];
+/**
+ * Where a role's per-role harness runtime state lives (5.1). Under the agent's
+ * own state directory, so it is covered by the state dir's existing lifecycle
+ * and by the forbidden-path exception, and is never shared with a peer.
+ */
+export declare const harnessRuntimeDir: (stateDir: string, harnessId: string) => string;
 /**
  * Resolve a raw (already validated) isolation block against runtime context into
- * a defaults-filled, backend-agnostic policy. Pure — no I/O, no probing.
+ * a defaults-filled, backend-agnostic policy, and REFUSE any mount that would
+ * breach the forbidden-path list.
+ *
+ * The mount model is an allowlist: only the durable set (state dir, cwd, harness
+ * config, declared fs/secrets) plus read-only system dirs are exposed. The
+ * forbidden list — the ours key store, sibling agent state dirs, ~/.ssh, ~/.aws
+ * — is now enforced on top of that, so a role cannot ask its way back in.
  *
- * The mount model is an allowlist: only the durable set (state dir, cwd, Claude
- * config, declared fs/secrets) plus read-only system dirs are exposed; everything
- * else on the host — the ours key store, sibling agent state dirs, ~/.ssh, ~/.aws —
- * is simply never mounted, and thus absent inside the sandbox (§5.2).
+ * Not pure: canonicalising a path reads the filesystem, because symlink aliases
+ * are one of the ways a forbidden path gets requested. Throws
+ * `IsolationPolicyError`; callers surface it against the role.
  */
 export declare function resolveIsolation(cfg: IsolationConfig, ctx: WrapContext): ResolvedIsolation;
 export type { IsolationConfig };

package/dist/isolation/policy.js

@@ -1,5 +1,57 @@
-import { join, dirname } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 import { BACKENDS, ON_UNAVAILABLE, NETWORK_MODES, } from './types.js';
+/** A mount that the forbidden-path policy refuses. Raised before any launch. */
+export class IsolationPolicyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IsolationPolicyError';
+    }
+}
+/**
+ * Resolve a path to its canonical form, following symlinks as far as the
+ * filesystem allows and normalising the rest. Without this, `~/link-to-ssh`
+ * and `/home/u/.ssh` are different strings for the same directory, and a
+ * string comparison against the forbidden list is trivially side-stepped.
+ */
+export function canonicalPath(p) {
+    const abs = resolve(p);
+    let head = abs;
+    let tail = '';
+    for (;;) {
+        try {
+            return tail ? join(realpathSync.native(head), tail) : realpathSync.native(head);
+        }
+        catch {
+            const parent = dirname(head);
+            if (parent === head)
+                return abs; // nothing on this path exists yet
+            tail = tail ? join(basename(head), tail) : basename(head);
+            head = parent;
+        }
+    }
+}
+const within = (child, parent) => child === parent || child.startsWith(parent + sep);
+/**
+ * How a canonical mount path collides with a canonical forbidden path.
+ *
+ * `parent` matters as much as the other two: binding `$HOME` does not name
+ * `~/.ssh`, but it exposes it just as completely.
+ */
+export function mountConflict(mount, forbidden) {
+    if (mount === forbidden)
+        return 'exact';
+    if (within(mount, forbidden))
+        return 'descendant';
+    if (within(forbidden, mount))
+        return 'parent';
+    return null;
+}
+const CONFLICT_WORDING = {
+    exact: 'is',
+    descendant: 'is inside',
+    parent: 'would expose',
+};
 /** Read-only system dirs exposed under the allowlist model. */
 const SYSTEM_RO = ['/usr', '/bin', '/sbin', '/lib', '/lib64', '/etc'];
 /** Ephemeral scratch mounts. */
@@ -52,6 +104,12 @@ export function validateIsolationConfig(raw) {
     }
     return problems;
 }
+/**
+ * Where a role's per-role harness runtime state lives (5.1). Under the agent's
+ * own state directory, so it is covered by the state dir's existing lifecycle
+ * and by the forbidden-path exception, and is never shared with a peer.
+ */
+export const harnessRuntimeDir = (stateDir, harnessId) => join(stateDir, 'harness', harnessId);
 /** Parse a `host:container` secret pair; a bare path maps to itself. */
 function parseSecret(pair) {
     const i = pair.indexOf(':');
@@ -61,12 +119,17 @@ function parseSecret(pair) {
 }
 /**
  * Resolve a raw (already validated) isolation block against runtime context into
- * a defaults-filled, backend-agnostic policy. Pure — no I/O, no probing.
+ * a defaults-filled, backend-agnostic policy, and REFUSE any mount that would
+ * breach the forbidden-path list.
+ *
+ * The mount model is an allowlist: only the durable set (state dir, cwd, harness
+ * config, declared fs/secrets) plus read-only system dirs are exposed. The
+ * forbidden list — the ours key store, sibling agent state dirs, ~/.ssh, ~/.aws
+ * — is now enforced on top of that, so a role cannot ask its way back in.
  *
- * The mount model is an allowlist: only the durable set (state dir, cwd, Claude
- * config, declared fs/secrets) plus read-only system dirs are exposed; everything
- * else on the host — the ours key store, sibling agent state dirs, ~/.ssh, ~/.aws —
- * is simply never mounted, and thus absent inside the sandbox (§5.2).
+ * Not pure: canonicalising a path reads the filesystem, because symlink aliases
+ * are one of the ways a forbidden path gets requested. Throws
+ * `IsolationPolicyError`; callers surface it against the role.
  */
 export function resolveIsolation(cfg, ctx) {
     const { stateDir, runCwd, home } = ctx;
@@ -75,10 +138,26 @@ export function resolveIsolation(cfg, ctx) {
         mounts.push({ src: p, dst: p, mode: 'rw' }); };
     const addRo = (p) => { if (!mounts.some(m => m.src === p))
         mounts.push({ src: p, dst: p, mode: 'ro' }); };
+    /** Writable bind whose destination differs from its source (the per-role home). */
+    const addRw2 = (src, dst) => {
+        if (!mounts.some(m => m.src === src && m.dst === dst))
+            mounts.push({ src, dst, mode: 'rw' });
+    };
     // Durable set: state dir + cwd, then only the active harness's config/auth roots.
     addRw(stateDir);
     addRw(runCwd);
-    if (ctx.harness === 'codex') {
+    if (ctx.harnessHome && ctx.harnessRuntimeDir) {
+        // The harness home is backed by a PER-ROLE directory (5.1): the agent gets a
+        // writable home for its sessions, caches and history, and anything a future
+        // CLI version writes lands there too. The shared credentials, global
+        // instructions and configuration are then layered back read-only, so they
+        // are readable and cannot be rewritten — for this role or for its peers.
+        // Order matters: the writable home must precede the read-only overlays.
+        addRw2(ctx.harnessRuntimeDir, ctx.harnessHome);
+        for (const p of ctx.harnessSharedPaths ?? [])
+            addRo(p);
+    }
+    else if (ctx.harness === 'codex') {
         addRw(join(home, '.codex'));
         addRo(join(home, '.agents'));
     }
@@ -105,6 +184,34 @@ export function resolveIsolation(cfg, ctx) {
         ...SENSITIVE_HOME.map(p => join(home, p)),
         agentsRoot, // sibling agents' state dirs (this agent's own is explicitly mounted)
     ];
+    // ENFORCE the list, before anything builds a backend argv. Until now it was
+    // observational: the allowlist model kept these paths out by default, but a
+    // role that asked for one in `fs.write`, `secrets`, or a Codex `add_dirs` got
+    // it mounted anyway, and the "blocklist" recorded a guarantee it never made.
+    //
+    // The role's OWN state dir is the one legitimate descendant of the agents
+    // root, so it is excepted by exact canonical identity — which does not
+    // exempt its parent, and does not exempt a sibling.
+    const forbidden = blocklist.map(canonicalPath);
+    const ownStateDir = canonicalPath(stateDir);
+    for (const m of mounts) {
+        for (const [role, path] of [['source', m.src], ['destination', m.dst]]) {
+            const canon = canonicalPath(path);
+            // The role's own state dir and anything inside it (its per-role harness
+            // runtime home, 5.1) is the one legitimate descendant of the agents root.
+            // This does not exempt the root above it, nor a sibling beside it.
+            if (within(canon, ownStateDir))
+                continue;
+            for (let i = 0; i < forbidden.length; i++) {
+                const kind = mountConflict(canon, forbidden[i]);
+                if (!kind)
+                    continue;
+                const alias = canon === resolve(path) ? '' : ` (resolves to '${canon}')`;
+                throw new IsolationPolicyError(`isolation: refusing to mount ${role} '${path}'${alias} — it ` +
+                    `${CONFLICT_WORDING[kind]} the forbidden path '${blocklist[i]}'`);
+            }
+        }
+    }
     return {
         backend: cfg.backend ?? 'auto',
         onUnavailable: cfg.on_unavailable ?? 'warn',

package/dist/isolation/resources.d.ts

@@ -5,9 +5,12 @@ export interface ResourceArgs {
 }
 /**
  * Build the `systemd-run --user --scope -p … --` prefix that caps the pane's
- * cgroup-v2 scope. Composed OUTSIDE the sandbox wrap (§5.3/§5.4): because tmux
- * panes are children of the shared tmux server rather than the per-role unit, the
- * only reliable per-agent limit is a transient scope at the pane itself.
+ * cgroup-v2 scope. Composed OUTSIDE the sandbox wrap (§5.3/§5.4): a tmux pane is
+ * a child of a tmux SERVER rather than of the role's own runner process, so the
+ * only reliable per-agent limit is a transient scope at the pane itself. (Since
+ * #32 that server is per role rather than fleet-wide, which is what keeps one
+ * role's `stop` off every other role's pane — the limit still belongs on the
+ * pane.)
  *
  * mem/pids are always enforced (their controllers are delegated to `--user` by
  * default). cpu degrades to a warning when the cpu controller is not delegated.

package/dist/isolation/resources.js

@@ -1,9 +1,12 @@
 import { readFileSync } from 'node:fs';
 /**
  * Build the `systemd-run --user --scope -p … --` prefix that caps the pane's
- * cgroup-v2 scope. Composed OUTSIDE the sandbox wrap (§5.3/§5.4): because tmux
- * panes are children of the shared tmux server rather than the per-role unit, the
- * only reliable per-agent limit is a transient scope at the pane itself.
+ * cgroup-v2 scope. Composed OUTSIDE the sandbox wrap (§5.3/§5.4): a tmux pane is
+ * a child of a tmux SERVER rather than of the role's own runner process, so the
+ * only reliable per-agent limit is a transient scope at the pane itself. (Since
+ * #32 that server is per role rather than fleet-wide, which is what keeps one
+ * role's `stop` off every other role's pane — the limit still belongs on the
+ * pane.)
  *
  * mem/pids are always enforced (their controllers are delegated to `--user` by
  * default). cpu degrades to a warning when the cpu controller is not delegated.

package/dist/isolation/types.d.ts

@@ -50,6 +50,19 @@ export interface WrapContext {
     harness?: string;
     /** Harness-declared writable roots (for example Codex --add-dir). */
     additionalWriteDirs?: string[];
+    /**
+     * The harness's home directory on the host (`~/.claude`, `~/.codex`). Mounted
+     * from `harnessRuntimeDir` so the agent's own runtime state is per-role (5.1).
+     */
+    harnessHome?: string;
+    /** Per-role writable directory backing `harnessHome` inside the sandbox. */
+    harnessRuntimeDir?: string;
+    /**
+     * Shared credentials, global instructions and configuration. Mounted READ-ONLY
+     * on top of the per-role home, so an agent can read them and cannot rewrite
+     * them for itself or for its peers.
+     */
+    harnessSharedPaths?: string[];
     brokerEndpoint?: string;
 }
 /**
@@ -68,7 +81,12 @@ export interface ResolvedIsolation {
     system: string[];
     /** ephemeral scratch tmpfs mounts (/tmp, ~/.cache). */
     tmpfs: string[];
-    /** sensitive host paths guaranteed absent from the sandbox (observability). */
+    /**
+     * Sensitive host paths that are ENFORCED absent from the sandbox: any mount
+     * that is, sits inside, or would expose one of these is refused by
+     * `resolveIsolation` before a backend argv is built. Retained on the resolved
+     * policy for diagnostics — doctor and `config` report what is being enforced.
+     */
     blocklist: string[];
 }
 /** A pluggable isolation backend (bubblewrap, podman, none). */

package/dist/monitor.d.ts

@@ -38,14 +38,27 @@ 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. */
+    /**
+     * Structured prompt delivery used by ACP sessions. Tmux remains the fallback.
+     * `succeeded` is the turn's TERMINAL result, not merely that the session took
+     * the prompt: a refused or cancelled wake was seen and not acted on, and must
+     * not commit the cursor.
+     */
     delivery?: {
         submit(text: string): Promise<{
-            accepted: boolean;
+            succeeded: boolean;
+            outcome: string;
             detail?: string;
         }>;
     };
 }
+/**
+ * Why the monitor is not healthy. Each cause clears on its OWN recovery signal
+ * and nothing else — a successful poll proves the stream works, and proves
+ * nothing whatsoever about whether wakes are being delivered or whether the
+ * turns they trigger keep dying.
+ */
+export type StatusCause = 'connectivity' | 'delivery' | 'modal' | 'offline' | 'turns-failing' | 'auth';
 /** Best-effort daemon config (issue #17): the fields the MCP client reads. */
 interface DaemonConfig {
     apiToken?: string;
@@ -149,6 +162,8 @@ export declare class Monitor {
     private currentAbort;
     private apiErrorStreak;
     private readonly turnFailThreshold;
+    /** Active degradations, keyed by cause. Empty means armed. */
+    private readonly causes;
     constructor(o: MonitorOpts);
     /** Resume the last delivered cursor; only a brand-new monitor primes at stream tip. */
     prime(): Promise<void>;
@@ -190,7 +205,19 @@ export declare class Monitor {
     private readPersistedCursor;
     /** Atomically persist body-free delivery state; restart always resumes from deliveredCursor. */
     private persistState;
-    private setStatus;
+    /** Record a degradation under its own cause and republish the status. */
+    private degrade;
+    /**
+     * Clear exactly the causes this recovery signal speaks to. Anything else
+     * stays: one successful poll must never be able to erase `turns failing`.
+     */
+    private recover;
+    /**
+     * One line per active cause, each dated; `armed` when there are none. Every
+     * line carries an ISO timestamp so an operator can tell a live status from a
+     * stale one left behind by a monitor that stopped writing.
+     */
+    private writeStatus;
 }
 export declare function createMonitor(o: MonitorOpts): Monitor;
 export {};