@ours.network/fleet 0.2.0 → 0.5.0

package/README.md

@@ -49,10 +49,19 @@ roles:
 ```
 
 Each role gets a state dir (`~/.ours-fleet/agents/<Name>/`) holding its briefing,
-WORKLOG, and session markers. On boot the agent reads its briefing: bind identity,
-publish bio/persona, arm a mail monitor (`ours-mcp watch`), announce to its
-coordinator, work. On crash the supervisor relaunches it and the harness resumes
-the same session.
+logs, routines, and session markers. On boot the agent reads its briefing: bind
+identity, publish bio/persona, arm a mail monitor (`ours-mcp watch`), announce to
+its coordinator, work. On crash the supervisor relaunches it and the harness
+resumes the same session.
+
+The state dir contract:
+
+| File | Owner | Lifecycle |
+|---|---|---|
+| `briefing.md` | generated | rewritten on every `up`/`restart`; never hand-edit |
+| `WORKLOG.md` | the agent | seeded empty, agent-appended; survives restarts |
+| `ROUTINES.md` | operator / agent | **optional** recurring-work instructions; re-read at the start of every wake, hot-editable **without a restart**; absence means "no routines" |
+| `.identity`, `.cwd`, `.session-id`, `.booted`, `.exit-status` | supervisor | dot-marker state — session resume and boot bookkeeping |
 
 ## Prerequisites
 
@@ -167,6 +176,8 @@ roles:
     harness_options:                    # adapter-owned, adapter-validated
       plugins: { "name@marketplace": false }   # claude-code: plugin overrides
       # mem_palace: false                      # claude-code: disable memory plugin
+      # permission_mode: dontAsk               # claude-code: launch permission mode —
+      #   one of default | acceptEdits | plan | dontAsk | bypassPermissions
 ```
 
 Merge order: `fleet.yaml` ← `fleet.d/*.yaml`; a duplicate role name is a hard

package/dist/briefing.d.ts

@@ -3,6 +3,7 @@ import type { BriefingVocab } from './harness/types.js';
 export interface BriefingOpts {
     stateDir: string;
     worklogPath: string;
+    routinesPath: string;
     /** Curated body (from briefing_file) replacing the narrative sections. */
     briefingBody?: string;
 }

package/dist/briefing.js

@@ -62,6 +62,10 @@ export function generateBriefing(role, v, opts) {
     L.push('', '## Durable log');
     L.push(`Append important commands / decisions / results to \`${opts.worklogPath}\` as you go —`);
     L.push('it survives restarts.');
+    L.push('', '## Routines');
+    L.push(`If \`${opts.routinesPath}\` exists, re-read it at the START of every wake — before acting`);
+    L.push('on messages, timers, or prompts — and follow it for recurring or scheduled work. It may');
+    L.push('change between wakes without a restart; treat the file, not your memory of it, as current.');
     L.push('', '## On restart (you run under a supervised launcher)');
     L.push(`On restart, WITHOUT asking: re-bind (**${v.bindTool}** name "${id}" force=true),`);
     L.push(`re-arm the \`${v.watchCommand(id)}\` monitor, then continue from your WORKLOG.`);

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import type { IsolationConfig } from './isolation/types.js';
 export interface OverseeEntry {
     role: string;
     interval: string;
@@ -17,6 +18,7 @@ export interface RoleConfig {
     env?: Record<string, string>;
     oversee?: OverseeEntry[];
     harness_options?: Record<string, unknown>;
+    isolation?: IsolationConfig;
 }
 export interface ResolvedRole extends RoleConfig {
     name: string;

package/dist/config.js

@@ -2,12 +2,14 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { parse } from 'yaml';
 import { defaultConfigPath, fleetDDir } from './paths.js';
+import { validateIsolationConfig } from './isolation/policy.js';
 export class ConfigError extends Error {
 }
 const NAME_RE = /^[A-Za-z0-9_-]+$/;
 const ROLE_KEYS = [
     'harness', 'identity', 'cwd', 'coordinator', 'mission', 'persona', 'bio',
     'briefing_file', 'model', 'max_tokens', 'autocompact_pct', 'env', 'oversee', 'harness_options',
+    'isolation',
 ];
 function deepSub(v, vars) {
     if (typeof v === 'string')
@@ -59,6 +61,12 @@ export function loadConfig(configPath) {
             const bad = Object.keys(r).filter(k => !ROLE_KEYS.includes(k));
             if (bad.length)
                 throw new ConfigError(`${file}: role '${name}' has unknown key(s) ${bad.join(', ')}; allowed: ${ROLE_KEYS.join(', ')}`);
+            const isolation = r.isolation ?? defaults.isolation;
+            if (isolation !== undefined) {
+                const problems = validateIsolationConfig(isolation);
+                if (problems.length)
+                    throw new ConfigError(`${file}: role '${name}' ${problems.join('; ')}`);
+            }
             roles.push({
                 ...r,
                 name,
@@ -67,6 +75,7 @@ export function loadConfig(configPath) {
                 identity: r.identity ?? name,
                 model: r.model ?? defaults.model,
                 max_tokens: r.max_tokens ?? defaults.max_tokens,
+                isolation,
             });
         }
     }

package/dist/harness/claude-code.js

@@ -3,7 +3,18 @@ import { join } from 'node:path';
 import { home } from '../paths.js';
 import { realExec } from '../exec.js';
 import { registerAdapter } from './registry.js';
-const OPTION_KEYS = ['plugins', 'mem_palace', 'mem_palace_midsession_autosave'];
+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)
+        return undefined;
+    if (!PERMISSION_MODES.includes(pm))
+        throw new Error(`invalid harness_options.permission_mode "${pm}"; allowed: ${PERMISSION_MODES.join(', ')}`);
+    return pm;
+}
 /** Context window of the fleet model (1M); max_tokens → % of this. */
 const WINDOW = 1_000_000;
 export function autocompactPct(role) {
@@ -78,7 +89,9 @@ export function makeClaudeCodeAdapter(exec = realExec) {
         },
         buildLaunch(role, mode, s, prep) {
             const stateDir = roleStateDir(role);
+            const pm = permissionMode(role);
             const base = ['claude', ...(role.model ? ['--model', role.model] : []),
+                ...(pm ? ['--permission-mode', pm] : []),
                 ...prep.argv, '--remote-control', role.name];
             const argv = mode === 'fresh'
                 ? [...base, '--session-id', s.sessionId, `Read and follow ${join(stateDir, 'briefing.md')} now.`]

package/dist/isolation/bubblewrap.d.ts

@@ -0,0 +1,10 @@
+import { type Exec } from '../exec.js';
+import type { IsolationBackend, NetworkMode } from './types.js';
+/**
+ * Phase 2 network policy: only `deny` unshares the network namespace. `broker`
+ * keeps the host network so ours messaging (a loopback TCP daemon on this host —
+ * see the Phase-0 spike) keeps working; hardening `broker` to `--unshare-net` +
+ * a loopback forwarder is Phase 4. `allow`/`allowlist` also keep host net.
+ */
+export declare function unsharesNet(network: NetworkMode): boolean;
+export declare function makeBubblewrapBackend(exec?: Exec): IsolationBackend;

package/dist/isolation/bubblewrap.js

@@ -0,0 +1,57 @@
+import { realExec } from '../exec.js';
+/**
+ * Phase 2 network policy: only `deny` unshares the network namespace. `broker`
+ * keeps the host network so ours messaging (a loopback TCP daemon on this host —
+ * see the Phase-0 spike) keeps working; hardening `broker` to `--unshare-net` +
+ * a loopback forwarder is Phase 4. `allow`/`allowlist` also keep host net.
+ */
+export function unsharesNet(network) {
+    return network === 'deny';
+}
+/** Build the `bwrap … -- <argv>` sandbox launcher argv. Pure — no I/O. */
+function wrap(argv, policy, ctx) {
+    const out = [
+        'bwrap',
+        '--die-with-parent',
+        '--unshare-user', '--unshare-ipc', '--unshare-uts', '--unshare-pid',
+        '--proc', '/proc',
+        '--dev', '/dev',
+        '--chdir', ctx.runCwd,
+    ];
+    // Read-only system dirs (allowlist model): best-effort so a missing /lib64 etc.
+    // does not abort the launch.
+    for (const s of policy.system)
+        out.push('--ro-bind-try', s, s);
+    // Ephemeral scratch.
+    for (const t of policy.tmpfs)
+        out.push('--tmpfs', t);
+    // Durable + declared binds. State dir and cwd are runner-guaranteed → hard binds
+    // (fail loud if absent); everything else is best-effort.
+    for (const m of policy.mounts) {
+        const hard = m.src === ctx.stateDir || m.src === ctx.runCwd;
+        const flag = m.mode === 'rw'
+            ? (hard ? '--bind' : '--bind-try')
+            : (hard ? '--ro-bind' : '--ro-bind-try');
+        out.push(flag, m.src, m.dst);
+    }
+    if (unsharesNet(policy.network))
+        out.push('--unshare-net');
+    out.push('--', ...argv);
+    return out;
+}
+export function makeBubblewrapBackend(exec = realExec) {
+    return {
+        id: 'bubblewrap',
+        async available() {
+            const v = await exec('bwrap', ['--version']);
+            if (v.code !== 0)
+                return { ok: false, detail: 'bubblewrap (bwrap) not found on PATH' };
+            // userns smoke test: a no-op sandbox that actually creates the namespaces.
+            const smoke = await exec('bwrap', ['--ro-bind', '/', '/', '--unshare-user', '--unshare-net', '--', 'true']);
+            if (smoke.code !== 0)
+                return { ok: false, detail: `bwrap userns smoke test failed: ${smoke.stderr.trim() || `exit ${smoke.code}`}` };
+            return { ok: true, detail: v.stdout.trim() };
+        },
+        wrap,
+    };
+}

package/dist/isolation/none.d.ts

@@ -0,0 +1,4 @@
+import type { IsolationBackend } from './types.js';
+/** The identity backend: no sandbox. wrap() returns the argv unchanged. Used for
+ *  `backend: none` and as the fail-open target when `on_unavailable: warn`. */
+export declare function makeNoneBackend(): IsolationBackend;

package/dist/isolation/none.js

@@ -0,0 +1,9 @@
+/** The identity backend: no sandbox. wrap() returns the argv unchanged. Used for
+ *  `backend: none` and as the fail-open target when `on_unavailable: warn`. */
+export function makeNoneBackend() {
+    return {
+        id: 'none',
+        async available() { return { ok: true, detail: 'no isolation (identity backend)' }; },
+        wrap(argv) { return argv; },
+    };
+}

package/dist/isolation/policy.d.ts

@@ -0,0 +1,17 @@
+import { type IsolationConfig, type ResolvedIsolation, type WrapContext } from './types.js';
+/**
+ * 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[];
+/**
+ * Resolve a raw (already validated) isolation block against runtime context into
+ * a defaults-filled, backend-agnostic policy. Pure — no I/O, no probing.
+ *
+ * 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).
+ */
+export declare function resolveIsolation(cfg: IsolationConfig, ctx: WrapContext): ResolvedIsolation;
+export type { IsolationConfig };

package/dist/isolation/policy.js

@@ -0,0 +1,110 @@
+import { join, dirname } from 'node:path';
+import { BACKENDS, ON_UNAVAILABLE, NETWORK_MODES, } from './types.js';
+/** Read-only system dirs exposed under the allowlist model. */
+const SYSTEM_RO = ['/usr', '/bin', '/sbin', '/lib', '/lib64', '/etc'];
+/** Ephemeral scratch mounts. */
+const scratchTmpfs = (home) => ['/tmp', join(home, '.cache')];
+/** Home-relative sensitive paths never exposed (the blocklist's teeth). */
+const SENSITIVE_HOME = ['.ssh', '.aws', '.docker', '.gnupg', '.ours', 'fleet.yaml', 'fleet.d'];
+const ISOLATION_KEYS = ['backend', 'on_unavailable', 'fs', 'network', 'allow_hosts', 'resources', 'secrets'];
+const FS_KEYS = ['read', 'write'];
+const RESOURCE_KEYS = ['cpu', 'mem', 'pids'];
+const unknownKeys = (obj, allowed) => Object.keys(obj).filter(k => !allowed.includes(k));
+const enumProblem = (label, value, allowed) => value === undefined || allowed.includes(value)
+    ? null
+    : `${label}: invalid value '${value}'; allowed: ${allowed.join(', ')}`;
+/**
+ * Validate a raw `isolation:` block. Returns a list of human-readable problems
+ * (empty ⇒ valid). Pure; callable from config.ts like adapter.validateOptions.
+ */
+export function validateIsolationConfig(raw) {
+    const problems = [];
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return ['isolation: must be a mapping'];
+    const iso = raw;
+    const bad = unknownKeys(iso, ISOLATION_KEYS);
+    if (bad.length)
+        problems.push(`isolation: unknown key(s) ${bad.join(', ')}; allowed: ${ISOLATION_KEYS.join(', ')}`);
+    for (const p of [
+        enumProblem('isolation.backend', iso.backend, BACKENDS),
+        enumProblem('isolation.on_unavailable', iso.on_unavailable, ON_UNAVAILABLE),
+        enumProblem('isolation.network', iso.network, NETWORK_MODES),
+    ])
+        if (p)
+            problems.push(p);
+    if (iso.fs !== undefined) {
+        if (typeof iso.fs !== 'object' || iso.fs === null || Array.isArray(iso.fs))
+            problems.push('isolation.fs: must be a mapping');
+        else {
+            const fsBad = unknownKeys(iso.fs, FS_KEYS);
+            if (fsBad.length)
+                problems.push(`isolation.fs: unknown key(s) ${fsBad.join(', ')}; allowed: ${FS_KEYS.join(', ')}`);
+        }
+    }
+    if (iso.resources !== undefined) {
+        if (typeof iso.resources !== 'object' || iso.resources === null || Array.isArray(iso.resources))
+            problems.push('isolation.resources: must be a mapping');
+        else {
+            const rBad = unknownKeys(iso.resources, RESOURCE_KEYS);
+            if (rBad.length)
+                problems.push(`isolation.resources: unknown key(s) ${rBad.join(', ')}; allowed: ${RESOURCE_KEYS.join(', ')}`);
+        }
+    }
+    return problems;
+}
+/** Parse a `host:container` secret pair; a bare path maps to itself. */
+function parseSecret(pair) {
+    const i = pair.indexOf(':');
+    const src = i === -1 ? pair : pair.slice(0, i);
+    const dst = i === -1 ? pair : pair.slice(i + 1);
+    return { src, dst, mode: 'ro' };
+}
+/**
+ * Resolve a raw (already validated) isolation block against runtime context into
+ * a defaults-filled, backend-agnostic policy. Pure — no I/O, no probing.
+ *
+ * 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).
+ */
+export function resolveIsolation(cfg, ctx) {
+    const { stateDir, runCwd, home } = ctx;
+    const mounts = [];
+    const addRw = (p) => { if (!mounts.some(m => m.src === p))
+        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' }); };
+    // Durable set (always present, rw): state dir, cwd, Claude config.
+    addRw(stateDir);
+    addRw(runCwd);
+    addRw(join(home, '.claude'));
+    addRw(join(home, '.claude.json'));
+    // Declared fs extras.
+    for (const p of cfg.fs?.write ?? [])
+        addRw(p);
+    for (const p of cfg.fs?.read ?? [])
+        addRo(p);
+    // Declared secrets (ro, host:container).
+    for (const pair of cfg.secrets ?? []) {
+        const m = parseSecret(pair);
+        if (!mounts.some(x => x.src === m.src && x.dst === m.dst))
+            mounts.push(m);
+    }
+    const agentsRoot = dirname(stateDir);
+    const blocklist = [
+        ...SENSITIVE_HOME.map(p => join(home, p)),
+        agentsRoot, // sibling agents' state dirs (this agent's own is explicitly mounted)
+    ];
+    return {
+        backend: cfg.backend ?? 'auto',
+        onUnavailable: cfg.on_unavailable ?? 'warn',
+        network: cfg.network ?? 'broker',
+        allowHosts: cfg.allow_hosts ?? [],
+        resources: cfg.resources ?? {},
+        mounts,
+        system: SYSTEM_RO,
+        tmpfs: scratchTmpfs(home),
+        blocklist,
+    };
+}

package/dist/isolation/registry.d.ts

@@ -0,0 +1,24 @@
+import { type Exec } from '../exec.js';
+import type { IsolationBackend, ResolvedIsolation } from './types.js';
+export type { IsolationBackend } from './types.js';
+export { makeBubblewrapBackend, unsharesNet } from './bubblewrap.js';
+export { makeNoneBackend } from './none.js';
+/** Outcome of resolving a policy's `backend:` (incl. `auto`) against host reality. */
+export interface Selection {
+    backend: IsolationBackend;
+    /** True when the requested backend was unavailable and we fell back to none. */
+    degraded: boolean;
+    detail: string;
+}
+/**
+ * Pick the isolation backend for a resolved policy, honouring `auto` (bwrap-first,
+ * rootless — OQ-5) and the `on_unavailable` degradation policy.
+ *
+ * - `none`         → the identity backend.
+ * - `bubblewrap`   → bwrap if available, else degrade/refuse per on_unavailable.
+ * - `podman`       → not implemented yet (Phase 6) ⇒ treated as unavailable.
+ * - `auto`         → bwrap if available, else degrade/refuse.
+ *
+ * On `on_unavailable: strict` with nothing available, throws (fail closed).
+ */
+export declare function selectIsolationBackend(policy: ResolvedIsolation, exec?: Exec): Promise<Selection>;

package/dist/isolation/registry.js

@@ -0,0 +1,36 @@
+import { realExec } from '../exec.js';
+import { makeBubblewrapBackend } from './bubblewrap.js';
+import { makeNoneBackend } from './none.js';
+export { makeBubblewrapBackend, unsharesNet } from './bubblewrap.js';
+export { makeNoneBackend } from './none.js';
+/**
+ * Pick the isolation backend for a resolved policy, honouring `auto` (bwrap-first,
+ * rootless — OQ-5) and the `on_unavailable` degradation policy.
+ *
+ * - `none`         → the identity backend.
+ * - `bubblewrap`   → bwrap if available, else degrade/refuse per on_unavailable.
+ * - `podman`       → not implemented yet (Phase 6) ⇒ treated as unavailable.
+ * - `auto`         → bwrap if available, else degrade/refuse.
+ *
+ * On `on_unavailable: strict` with nothing available, throws (fail closed).
+ */
+export async function selectIsolationBackend(policy, exec = realExec) {
+    if (policy.backend === 'none')
+        return { backend: makeNoneBackend(), degraded: false, detail: 'backend: none' };
+    const candidates = [];
+    if (policy.backend === 'auto' || policy.backend === 'bubblewrap')
+        candidates.push(makeBubblewrapBackend(exec));
+    // podman: Phase 6 — no candidate yet, so it falls through to on_unavailable.
+    let lastDetail = policy.backend === 'podman'
+        ? 'podman backend not implemented yet (Phase 6)'
+        : 'no isolation backend available';
+    for (const b of candidates) {
+        const a = await b.available();
+        if (a.ok)
+            return { backend: b, degraded: false, detail: a.detail };
+        lastDetail = `${b.id} unavailable: ${a.detail}`;
+    }
+    if (policy.onUnavailable === 'strict')
+        throw new Error(`isolation strict mode: refusing to launch un-isolated — ${lastDetail}`);
+    return { backend: makeNoneBackend(), degraded: true, detail: lastDetail };
+}

package/dist/isolation/resources.d.ts

@@ -0,0 +1,17 @@
+import type { IsolationResources } from './types.js';
+export interface ResourceArgs {
+    argv: string[];
+    warnings: string[];
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function resourceArgs(res: IsolationResources, cpuDelegated: boolean): ResourceArgs;
+/** Whether the cpu cgroup-v2 controller is delegated to this user manager. */
+export declare function cpuControllerDelegated(read?: (p: string) => string): boolean;

package/dist/isolation/resources.js

@@ -0,0 +1,58 @@
+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.
+ *
+ * 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.
+ */
+export function resourceArgs(res, cpuDelegated) {
+    const props = [];
+    const warnings = [];
+    // MemorySwapMax=0 makes MemoryMax a hard OOM bound: without it, on a host with
+    // swap the overflow spills to swap instead of being killed, so the cap is soft
+    // and a rogue agent could exhaust host swap.
+    if (res.mem)
+        props.push(`MemoryMax=${res.mem}`, `MemorySwapMax=0`);
+    if (res.pids !== undefined)
+        props.push(`TasksMax=${res.pids}`);
+    if (res.cpu) {
+        const pct = Math.round(parseFloat(res.cpu) * 100);
+        if (!Number.isFinite(pct)) {
+            warnings.push(`ignoring unparseable cpu value '${res.cpu}'`);
+        }
+        else if (!cpuDelegated) {
+            warnings.push(`cpu cap '${res.cpu}' cores requested but the cpu cgroup controller is not delegated; ` +
+                `enforcing mem/pids only (see doctor: one-time Delegate=cpu). CPUQuota skipped.`);
+        }
+        else {
+            props.push(`CPUQuota=${pct}%`);
+        }
+    }
+    if (props.length === 0)
+        return { argv: [], warnings };
+    const argv = ['systemd-run', '--user', '--scope'];
+    for (const p of props)
+        argv.push('-p', p);
+    argv.push('--');
+    return { argv, warnings };
+}
+/** Whether the cpu cgroup-v2 controller is delegated to this user manager. */
+export function cpuControllerDelegated(read = p => readFileSync(p, 'utf8')) {
+    // The user manager's own cgroup lists the controllers delegated to it.
+    const uid = process.getuid?.() ?? 0;
+    const candidates = [
+        `/sys/fs/cgroup/user.slice/user-${uid}.slice/cgroup.controllers`,
+        `/sys/fs/cgroup/user.slice/user-${uid}.slice/user@${uid}.service/cgroup.controllers`,
+    ];
+    for (const p of candidates) {
+        try {
+            if (read(p).split(/\s+/).includes('cpu'))
+                return true;
+        }
+        catch { /* try next */ }
+    }
+    return false;
+}

package/dist/isolation/types.d.ts

@@ -0,0 +1,80 @@
+/** Isolation backend selector. `auto` probes bubblewrap then podman; `none` disables wrapping. */
+export type IsolationBackendId = 'auto' | 'bubblewrap' | 'podman' | 'none';
+/** What to do when the requested backend is unavailable. */
+export type OnUnavailable = 'warn' | 'strict';
+/** Network posture inside the sandbox. */
+export type NetworkMode = 'broker' | 'deny' | 'allow' | 'allowlist';
+export declare const BACKENDS: IsolationBackendId[];
+export declare const ON_UNAVAILABLE: OnUnavailable[];
+export declare const NETWORK_MODES: NetworkMode[];
+export interface IsolationFs {
+    /** Extra read-only bind mounts (host paths). */
+    read?: string[];
+    /** Extra read-write bind mounts (host paths). */
+    write?: string[];
+}
+export interface IsolationResources {
+    /** Cores, e.g. "1.5" → CPUQuota=150%. */
+    cpu?: string;
+    /** Memory, e.g. "2G" → MemoryMax=2G. */
+    mem?: string;
+    /** Max processes → TasksMax. */
+    pids?: number;
+}
+/** Raw `isolation:` block as it appears in fleet.yaml (all fields optional). */
+export interface IsolationConfig {
+    backend?: IsolationBackendId;
+    on_unavailable?: OnUnavailable;
+    fs?: IsolationFs;
+    network?: NetworkMode;
+    allow_hosts?: string[];
+    resources?: IsolationResources;
+    secrets?: string[];
+}
+/** A single bind mount in the resolved sandbox. */
+export interface Mount {
+    src: string;
+    dst: string;
+    mode: 'ro' | 'rw';
+}
+/**
+ * Runtime facts the pure resolver needs to compute the durable mount set (§5.2):
+ * the agent's state dir, its working dir, the fleet user's home, and (if the ours
+ * broker exposes one) a unix-socket endpoint to bind in.
+ */
+export interface WrapContext {
+    stateDir: string;
+    runCwd: string;
+    home: string;
+    brokerEndpoint?: string;
+}
+/**
+ * The validated, defaults-filled isolation policy consumed by a backend's wrap().
+ * Pure output of resolveIsolation — no I/O, no backend probing.
+ */
+export interface ResolvedIsolation {
+    backend: IsolationBackendId;
+    onUnavailable: OnUnavailable;
+    network: NetworkMode;
+    allowHosts: string[];
+    resources: IsolationResources;
+    /** rw + ro bind mounts: durable set, fs.* extras, secrets. */
+    mounts: Mount[];
+    /** read-only system dirs exposed under the allowlist model (/usr, /bin, …). */
+    system: string[];
+    /** ephemeral scratch tmpfs mounts (/tmp, ~/.cache). */
+    tmpfs: string[];
+    /** sensitive host paths guaranteed absent from the sandbox (observability). */
+    blocklist: string[];
+}
+/** A pluggable isolation backend (bubblewrap, podman, none). */
+export interface IsolationBackend {
+    id: 'bubblewrap' | 'podman' | 'none';
+    /** Probe host support; feeds `doctor` and `auto` selection. */
+    available(): Promise<{
+        ok: boolean;
+        detail: string;
+    }>;
+    /** Wrap the agent argv into a sandbox-launcher argv given the resolved policy. */
+    wrap(argv: string[], policy: ResolvedIsolation, ctx: WrapContext): string[];
+}

package/dist/isolation/types.js

@@ -0,0 +1,3 @@
+export const BACKENDS = ['auto', 'bubblewrap', 'podman', 'none'];
+export const ON_UNAVAILABLE = ['warn', 'strict'];
+export const NETWORK_MODES = ['broker', 'deny', 'allow', 'allowlist'];

package/dist/ops.js

@@ -23,7 +23,8 @@ export function applyRole(role, opts = {}) {
         writeFileSync(join(dir, 'WORKLOG.md'), '');
     const briefingBody = role.briefing_file ? readFileSync(role.briefing_file, 'utf8') : undefined;
     writeFileSync(join(dir, 'briefing.md'), generateBriefing(role, adapter.vocabulary, {
-        stateDir: dir, worklogPath: join(dir, 'WORKLOG.md'), briefingBody,
+        stateDir: dir, worklogPath: join(dir, 'WORKLOG.md'),
+        routinesPath: join(dir, 'ROUTINES.md'), briefingBody,
     }));
     if (opts.fresh)
         for (const f of ['.booted', '.session-id', '.exit-status'])

package/dist/runner.d.ts

@@ -1,15 +1,24 @@
 import { type ResolvedRole } from './config.js';
 import type { Launch } from './harness/types.js';
 import { Tmux } from './tmux.js';
+import { type Exec } from './exec.js';
 export interface RunnerDeps {
     tmux: Tmux;
+    exec: Exec;
+    cpuDelegated(): boolean;
     isAlive(pid: number): boolean;
     sleep(ms: number): Promise<void>;
     now(): number;
     log(line: string): void;
 }
-/** Compose the tmux pane shell command: env prefix + argv + exit-status capture. */
-export declare function buildPaneCommand(launch: Launch, roleEnv: Record<string, string> | undefined, exitStatusPath: string): string;
+/**
+ * Compose the tmux pane shell command: env prefix + argv + exit-status capture.
+ * `paneArgv` defaults to `launch.argv`; when isolation is active the caller passes
+ * the sandbox-wrapped argv (e.g. `bwrap … -- claude …`). The `env` prefix and the
+ * `echo $? > exitfile` capture stay host-side, outside the sandbox, so the runner
+ * still sees the real exit code.
+ */
+export declare function buildPaneCommand(launch: Launch, roleEnv: Record<string, string> | undefined, exitStatusPath: string, paneArgv?: string[]): string;
 /** Read a temp role's config snapshot written by spawnTemp. */
 export declare function loadTempRole(name: string): ResolvedRole;
 /** One supervised session lifecycle. The supervisor re-invokes us after we return. */

package/dist/runner.js

@@ -2,13 +2,18 @@ import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync } from 'node
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { parse } from 'yaml';
-import { agentDir } from './paths.js';
+import { agentDir, home } from './paths.js';
 import { loadConfig, findRole } from './config.js';
 import { getAdapter } from './harness/registry.js';
 import { Tmux } from './tmux.js';
-import { shq } from './exec.js';
+import { realExec, shq } from './exec.js';
+import { resolveIsolation } from './isolation/policy.js';
+import { selectIsolationBackend } from './isolation/registry.js';
+import { resourceArgs, cpuControllerDelegated } from './isolation/resources.js';
 const defaultDeps = () => ({
     tmux: new Tmux(),
+    exec: realExec,
+    cpuDelegated: () => cpuControllerDelegated(),
     isAlive: pid => { try {
         process.kill(pid, 0);
         return true;
@@ -20,11 +25,17 @@ const defaultDeps = () => ({
     now: () => Date.now(),
     log: line => process.stderr.write(line + '\n'),
 });
-/** Compose the tmux pane shell command: env prefix + argv + exit-status capture. */
-export function buildPaneCommand(launch, roleEnv, exitStatusPath) {
+/**
+ * Compose the tmux pane shell command: env prefix + argv + exit-status capture.
+ * `paneArgv` defaults to `launch.argv`; when isolation is active the caller passes
+ * the sandbox-wrapped argv (e.g. `bwrap … -- claude …`). The `env` prefix and the
+ * `echo $? > exitfile` capture stay host-side, outside the sandbox, so the runner
+ * still sees the real exit code.
+ */
+export function buildPaneCommand(launch, roleEnv, exitStatusPath, paneArgv = launch.argv) {
     const env = { PATH: process.env.PATH ?? '', ...launch.env, ...(roleEnv ?? {}) };
     const envPfx = 'env ' + Object.entries(env).map(([k, v]) => `${k}=${shq(v)}`).join(' ');
-    const cmd = launch.argv.map(shq).join(' ');
+    const cmd = paneArgv.map(shq).join(' ');
     return `${envPfx} ${cmd}; echo $? > ${shq(exitStatusPath)}`;
 }
 /** Read a temp role's config snapshot written by spawnTemp. */
@@ -57,9 +68,29 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
     const runCwd = role.cwd && existsSync(role.cwd) ? role.cwd : dir;
     const prep = await adapter.prepareSession(role, { stateDir: dir, runCwd });
     const launch = adapter.buildLaunch(role, mode, { sessionId }, prep);
+    // Isolation is additive: only roles that declare `isolation:` are wrapped. The
+    // env prefix + exit capture in buildPaneCommand stay host-side (see §5.3).
+    let paneArgv = launch.argv;
+    if (role.isolation) {
+        const ctx = { stateDir: dir, runCwd, home: home() };
+        const policy = resolveIsolation(role.isolation, ctx);
+        const sel = await selectIsolationBackend(policy, deps.exec); // throws on strict + unavailable
+        if (sel.degraded)
+            deps.log(`[${name}] WARNING isolation requested but unavailable -> running UN-ISOLATED: ${sel.detail}`);
+        else
+            deps.log(`[${name}] isolation: ${sel.backend.id} (net=${policy.network}) ${sel.detail}`);
+        paneArgv = sel.backend.wrap(launch.argv, policy, ctx);
+        // Resource caps wrap the sandbox from OUTSIDE, at the pane's own cgroup scope
+        // (§5.4). Applies even when the sandbox degraded to none.
+        const { argv: rprefix, warnings } = resourceArgs(policy.resources, deps.cpuDelegated());
+        for (const w of warnings)
+            deps.log(`[${name}] WARNING ${w}`);
+        if (rprefix.length)
+            paneArgv = [...rprefix, ...paneArgv];
+    }
     rmSync(exitFile, { force: true });
     await deps.tmux.kill(name);
-    await deps.tmux.newSession(name, runCwd, buildPaneCommand(launch, role.env, exitFile));
+    await deps.tmux.newSession(name, runCwd, buildPaneCommand(launch, role.env, exitFile, paneArgv));
     let pid = null;
     for (let i = 0; i < 40 && pid === null; i++) {
         pid = await deps.tmux.panePid(name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/fleet",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Harness-agnostic fleet of persistent, identity-bound AI agents. Declarative fleet.yaml, tmux consoles, systemd/launchd supervision, ours.network messaging.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",