@ours.network/fleet 0.4.0 → 0.5.1

package/LICENSE

@@ -6,7 +6,7 @@ FSL-1.1-Apache-2.0
 
 ## Notice
 
-Copyright 2026 ours.network contributors
+Copyright 2026 Adapt Framework Solutions Ltd
 
 ## Terms and Conditions
 

package/README.md

@@ -1,6 +1,6 @@
 # ours-fleet
 
-**Run a fleet of persistent, identity-bound AI agents — across different agent
+**Run a fleet of persistent, securely isolated, identity-bound AI agents — across different agent
 harnesses — from one declarative file.**
 
 ## What is this?
@@ -178,12 +178,51 @@ roles:
       # mem_palace: false                      # claude-code: disable memory plugin
       # permission_mode: dontAsk               # claude-code: launch permission mode —
       #   one of default | acceptEdits | plan | dontAsk | bypassPermissions
+    isolation:                          # OS-level sandbox (additive; omit = today's behavior)
+      backend: auto                     # auto | bubblewrap | podman | none   (default auto)
+      on_unavailable: warn              # warn (un-isolated + marker) | strict (refuse)   (default warn)
+      network: broker                   # broker | deny | allow | allowlist   (default broker)
+      fs: { read: [/opt/toolchains], write: [] }   # extra binds (state dir + cwd always included)
+      resources: { mem: 2G, cpu: "1.5", pids: 512 }
+      secrets: ["/host/tok:/run/secrets/tok"]      # host:container, mounted read-only
 ```
 
 Merge order: `fleet.yaml` ← `fleet.d/*.yaml`; a duplicate role name is a hard
 error naming both files. Identities and roles are decoupled — removing a role
 never deletes an identity.
 
+## Agent isolation
+
+Each role can be sandboxed at the environment level via an `isolation:` block —
+**fully additive: a role with no block behaves exactly as before.** The agent's
+tmux-pane process is wrapped in [bubblewrap](https://github.com/containers/bubblewrap)
+(rootless, no setuid), resource-limited by `systemd-run --user --scope`.
+
+An empty `isolation: {}` gives a sensible default posture: filesystem-confined to
+the state dir + `cwd`, the ours key store / other agents' state / `~/.ssh` / `~/.aws`
+all invisible, ours messaging still works, no hard resource caps.
+
+- **`backend`** — `auto` (bubblewrap if usable, else degrade per `on_unavailable`),
+  or force `bubblewrap` / `none`. (`podman` is planned.)
+- **`on_unavailable`** — `warn` (default, fail-open: run un-isolated, log, and drop a
+  `.isolation-degraded` marker in the state dir) or `strict` (fail closed: refuse to launch).
+- **`network`** — `broker` (default; ours messaging works), `deny` (no network),
+  `allow` (unrestricted), `allowlist` (planned). *Current status:* `deny` fully
+  unshares the network; `broker` keeps host networking so the loopback ours daemon
+  stays reachable — full broker egress-hardening is a follow-up.
+- **`fs.read` / `fs.write`** — extra read-only / read-write binds on top of the durable set.
+- **`resources`** — `mem` (→ `MemoryMax` + `MemorySwapMax=0`, a hard OOM bound),
+  `cpu` cores (→ `CPUQuota`), `pids` (→ `TasksMax`). CPU degrades to a warning if the
+  cpu cgroup controller isn't delegated (mem/pids still enforced).
+- **`secrets`** — `host:container` pairs, mounted read-only; the only way host files
+  enter the sandbox.
+
+`ours-fleet doctor` reports bubblewrap availability, cgroup delegation, and each
+role's effective isolation; `ours-fleet config` prints a per-role isolation summary.
+Isolation composes with `model`, `permission_mode`, and `ROUTINES.md`. See
+[SECURITY.md](SECURITY.md#agent-isolation-sandboxing) for the threat model and the
+rootless prerequisites.
+
 ## Development
 
 ```sh
@@ -202,8 +241,33 @@ software built by a small independent team, running the broker and relay service
 at their own cost. If this is useful to you, please consider chipping in:
 **→ https://github.com/adapt-toolkit/ours-donate**
 
-## License
+## Licence, status & warranty
+
+> **Alpha software.** ours-fleet is part of **ours.network**, which is early,
+> experimental, **alpha-stage** software. It is under active development, its
+> behaviour and interfaces may change without notice, and it is **not
+> production-ready**.
+
+> **No warranty / not security-audited.** ours.network has **not** been
+> independently security-audited. It is provided **"as is", without warranty of
+> any kind**, and you use it **at your own risk**. See [`LICENSE`](LICENSE) and
+> [`SECURITY.md`](SECURITY.md).
+
+**ours.network** is owned and licensed by **Adapt Framework Solutions Ltd**. It
+is released under the **Functional Source License, Version 1.1
+([FSL-1.1-Apache-2.0](LICENSE))** — **source-available, not open source** during
+the FSL period. Each release **converts to Apache 2.0 two years after it is
+published**.
+
+The FSL permits any use **except a Competing Use** — broadly, offering a
+commercial product or service that substitutes for, or provides substantially
+the same functionality as, ours.network. Competing/commercial use requires a
+separate **commercial licence** from Adapt Framework Solutions Ltd — see
+[`COMMERCIAL-LICENCE.md`](COMMERCIAL-LICENCE.md) (contact:
+**license@adaptframework.solutions**).
+
+ours.network builds on Adapt Framework Solutions Ltd's own FSL-licensed core (the
+`@adapt-toolkit` packages); **Adapt itself is not part of this release** and is
+licensed separately.
 
-[FSL-1.1-Apache-2.0](LICENSE) — Functional Source License, converting to
-Apache-2.0 two years after each release. Free for any use except offering a
-competing product or service. Copyright 2026 ours.network contributors.
+Copyright 2026 Adapt Framework Solutions Ltd.

package/dist/cli.js

@@ -56,6 +56,16 @@ cOpt(program.command('config').description('validate + print the merged plan (no
                 console.log(`    mission:     ${r.mission.split('\n')[0]}`);
             if (r.oversee?.length)
                 console.log(`    oversees:    ${r.oversee.map(o => `${o.role}@${o.interval}`).join(', ')}`);
+            if (r.isolation) {
+                const iso = r.isolation;
+                const caps = [
+                    iso.resources?.mem && `mem=${iso.resources.mem}`,
+                    iso.resources?.cpu && `cpu=${iso.resources.cpu}`,
+                    iso.resources?.pids !== undefined && `pids=${iso.resources.pids}`,
+                ].filter(Boolean).join(',') || 'none';
+                console.log(`    isolation:   backend=${iso.backend ?? 'auto'} net=${iso.network ?? 'broker'} `
+                    + `on_unavailable=${iso.on_unavailable ?? 'warn'} caps=${caps}`);
+            }
         }
     }
     catch (e) {

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/doctor.js

@@ -1,7 +1,24 @@
 import { userInfo } from 'node:os';
+import { readFileSync } from 'node:fs';
 import { realExec } from './exec.js';
 import { loadConfig } from './config.js';
 import { getAdapter } from './harness/registry.js';
+import { agentDir, home } from './paths.js';
+import { resolveIsolation } from './isolation/policy.js';
+import { makeBubblewrapBackend } from './isolation/bubblewrap.js';
+/** Which cgroup-v2 controllers are delegated to this user manager (advisory). */
+function cgroupDelegationDetail() {
+    try {
+        const uid = process.getuid?.() ?? 0;
+        const c = readFileSync(`/sys/fs/cgroup/user.slice/user-${uid}.slice/cgroup.controllers`, 'utf8').split(/\s+/);
+        const has = (n) => (c.includes(n) ? 'yes' : 'no');
+        return `memory=${has('memory')} pids=${has('pids')} cpu=${has('cpu')}` +
+            (c.includes('cpu') ? '' : ' — cpu caps degrade to a warning (one-time: Delegate=cpu)');
+    }
+    catch {
+        return 'unknown (not cgroup-v2 or no delegation info)';
+    }
+}
 /** Host-level + per-harness prerequisite report with actionable messages. */
 export async function doctor(opts = {}, exec = realExec, platform = process.platform) {
     const checks = [];
@@ -37,9 +54,47 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
                 : `not enabled — run: ours-fleet init (or: sudo loginctl enable-linger ${user})`,
         });
     }
+    // Isolation reporting (AC-9). Backend availability is advisory — isolation is
+    // 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,
+        detail: bw.ok
+            ? `available — ${bw.detail}`
+            : `not available: ${bw.detail} (only needed for roles declaring isolation:)`,
+    });
+    if (platform === 'linux')
+        checks.push({ name: 'isolation: cgroup delegation', ok: true, detail: cgroupDelegationDetail() });
+    for (const r of roles.filter(r => r.isolation)) {
+        const stateDir = agentDir(r.name);
+        const policy = resolveIsolation(r.isolation, { stateDir, runCwd: r.cwd ?? stateDir, home: home() });
+        const caps = [
+            policy.resources.mem && `mem=${policy.resources.mem}`,
+            policy.resources.cpu && `cpu=${policy.resources.cpu}`,
+            policy.resources.pids !== undefined && `pids=${policy.resources.pids}`,
+        ].filter(Boolean).join(',') || 'none';
+        const wantsBwrap = policy.backend === 'auto' || policy.backend === 'bubblewrap';
+        let ok = true, detail;
+        if (policy.backend === 'none')
+            detail = 'backend=none (explicitly un-sandboxed)';
+        else if (wantsBwrap && bw.ok)
+            detail = `backend=bubblewrap net=${policy.network} caps=${caps}`;
+        else if (wantsBwrap && policy.onUnavailable === 'strict') {
+            ok = false;
+            detail = 'WILL REFUSE to launch (strict): bubblewrap unavailable';
+        }
+        else if (wantsBwrap)
+            detail = `degraded->un-isolated (warn): bubblewrap unavailable; caps=${caps} still apply`;
+        else
+            detail = `backend=${policy.backend} (not yet implemented)`;
+        checks.push({ name: `isolation: ${r.name}`, ok, detail });
+    }
     const harnesses = opts.harness
         ? [opts.harness]
-        : [...new Set(loadConfigSafe(opts.configPath).map(r => r.harness))];
+        : [...new Set(roles.map(r => r.harness))];
     for (const h of harnesses) {
         try {
             const rep = await getAdapter(h).checkPrereqs();

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/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,34 @@ 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
+        const degradedMarker = join(dir, '.isolation-degraded');
+        if (sel.degraded) {
+            deps.log(`[${name}] WARNING isolation requested but unavailable -> running UN-ISOLATED: ${sel.detail}`);
+            writeFileSync(degradedMarker, `${new Date().toISOString()} ${sel.detail}\n`);
+        }
+        else {
+            deps.log(`[${name}] isolation: ${sel.backend.id} (net=${policy.network}) ${sel.detail}`);
+            rmSync(degradedMarker, { force: true });
+        }
+        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.4.0",
+  "version": "0.5.1",
   "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",