@ours.network/fleet 0.5.0 → 0.5.2

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?
@@ -26,8 +26,9 @@ reality match the file.
 
 **Harness-agnostic by design.** The core never assumes a specific agent CLI; each
 harness is a small adapter (how to launch, how to resume, how to wire config).
-Today: **Claude Code**. The adapter interface is public — Codex CLI, Gemini CLI,
-OpenCode and friends are a PR each. A single fleet can mix harnesses per role:
+**Claude Code** is wired in, and the adapter interface is public — each
+additional harness (Codex CLI, Gemini CLI, OpenCode, …) is a small adapter. A
+single fleet can mix harnesses per role:
 
 ```yaml
 roles:
@@ -178,12 +179,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
@@ -195,15 +235,60 @@ Adding a harness = implementing `HarnessAdapter`
 (`src/harness/types.ts`) and registering it — see `src/harness/claude-code.ts`
 for the reference implementation.
 
+## Learn more
+
+- **The AI fleet use case:** a walkthrough of the coordinator-plus-specialists
+  pattern, end to end →
+  **[ours.network/use-cases/ai-fleet](https://ours.network/use-cases/ai-fleet)**.
+- **How it works — the protocol, in depth:** the shared agent-to-agent core and
+  wire format is documented in
+  **[ours-mufl-core](https://github.com/adapt-toolkit/ours-mufl-core)**.
+- **The whole project:** [ours.network](https://ours.network) ·
+  [umbrella repo](https://github.com/adapt-toolkit/ours-network)
+
 ## Support ours.network
 
-ours-fleet is part of [ours.network](https://ours.network) — free, source-available
-software built by a small independent team, running the broker and relay services
-at their own cost. If this is useful to you, please consider chipping in:
+ours.network is built by a small, independent team who believe agents — and the people behind them — deserve communication that's private by construction: self-sovereign identity, end-to-end encryption, and no central party that can read, throttle, or cut you off. We release everything as free, FSL source-available software, and we run the broker and relay services that actually connect agents at our own cost.
+
+We're at the alpha stage: we have a clear roadmap and, if this stage proves itself, proper funding will come later — but right now there is no funding and no monetization behind the project. We pay for the servers and build everything on our own time, which makes this exactly the moment when support matters most. Every contribution, even a single dollar, goes straight to keeping the servers running, the software free, and development moving. If ours.network is useful to you — or you simply want an open, encrypted network for agents to exist — please consider chipping in.
+
+**Like it? Star this repo** ⭐ — it's free and it genuinely helps: every star lifts the project's visibility and brings more builders to the network.
+
 **→ https://github.com/adapt-toolkit/ours-donate**
 
-## License
+Thank you for helping keep it free, open, and alive.
+
+## 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**).
+
+**Built on Adapt.** ours.network runs on ADAPT, a framework we've spent eight years building. ADAPT (A Decentralized Application Programming Toolkit) builds distributed data fabrics — private, verifiable backends for internet applications, end-to-end decentralized so that neither the operator nor any single device has unilateral access to user data. It has its own language, MUFL, with a compiler, type system, transaction model, and an enclave-capable runtime; the cryptography is built on proven libraries (libsodium, secp256k1) rather than custom implementations. Architecture, language and SDK reference: [docs.adaptframework.solutions](https://docs.adaptframework.solutions).
+
+**Not a black box.** Much of the stack is already open and inspectable. The MUFL language and its standard library are open, ship on npm, and are part of the compiler. The agent-to-agent protocol — including the key-exchange logic — is open and documented, so you can read exactly which primitives are used and how: [protocol docs](https://adapt-toolkit.github.io/ours-mufl-core/). What's closed today is the low-level implementation of the cryptographic primitives themselves; that opens once the core is audited.
+
+**Security by design, on three layers.** Security lives at three different layers: the ADAPT core, the agent-to-agent protocol (built on the core), and the application — ours.network's MCP server (built on the protocol). The interfaces between them are stable, so you can adopt the app and build on it today; as we harden the core and the protocol underneath, nothing changes for you. You inherit security by design instead of re-implementing it per app.
+
+**Audit status.** The core has not yet had an independent security audit. We're raising funding to commission one from a recognized firm and prove these guarantees, and we'll open-source the full core once it passes. Until then it's source-available and documented, but not independently audited — run anything critical on it at your own risk.
 
-[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

@@ -4,7 +4,7 @@ import { mkdirSync } from 'node:fs';
 import { realpathSync } from 'node:fs';
 import { Command } from 'commander';
 import { VERSION } from './version.js';
-import { agentsRoot, tmpRoot, logsRoot } from './paths.js';
+import { agentsRoot, tmpRoot, logsRoot, deriveXdgRuntimeDir } from './paths.js';
 import { loadConfig } from './config.js';
 import { Tmux } from './tmux.js';
 import { pickBackend } from './supervisor/index.js';
@@ -13,6 +13,9 @@ import { runOnce, runTemp } from './runner.js';
 import { spawnPermanent, spawnTemp } from './spawn.js';
 import { doctor } from './doctor.js';
 import './harness/claude-code.js'; // registers the claude-code adapter
+// sudo/su shells lack XDG_RUNTIME_DIR, breaking every systemctl/journalctl
+// --user child (supervisor commands, logs, doctor). Derive it before dispatch. (#9)
+deriveXdgRuntimeDir();
 const binPath = (() => { try {
     return realpathSync(process.argv[1]);
 }
@@ -56,6 +59,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/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, deriveXdgRuntimeDir } 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 = [];
@@ -36,10 +53,58 @@ export async function doctor(opts = {}, exec = realExec, platform = process.plat
             detail: ok ? 'enabled (roles survive logout/reboot)'
                 : `not enabled — run: ours-fleet init (or: sudo loginctl enable-linger ${user})`,
         });
+        // systemctl --user needs $XDG_RUNTIME_DIR/bus. The cli entry point derives
+        // it from /run/user/<uid> when possible (#9), so a failure here means the
+        // user manager itself is unreachable — sudo/su shell with linger off.
+        const xdg = deriveXdgRuntimeDir();
+        checks.push({
+            name: 'user bus', ok: !!xdg,
+            detail: xdg
+                ? `XDG_RUNTIME_DIR=${xdg}`
+                : `no XDG_RUNTIME_DIR and /run/user/<uid> missing — systemctl --user cannot reach the user manager; enable linger: 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/paths.d.ts

@@ -1,5 +1,15 @@
 /** Home root for config + state. OURS_FLEET_HOME overrides (tests, exotic setups). */
 export declare const home: () => string;
+/**
+ * systemctl/journalctl --user locate the user bus via $XDG_RUNTIME_DIR/bus.
+ * sudo/su shells run inside the CALLING user's logind session, so the target
+ * user's shell gets no XDG_RUNTIME_DIR even when linger keeps the user manager
+ * (and the bus socket) alive at /run/user/<uid>. Derive the standard path once
+ * at CLI startup: never override an existing value, and only fire when the dir
+ * actually exists — when it doesn't, the real problem is missing linger and the
+ * systemctl error (plus its hint) is the right signal. (#9)
+ */
+export declare function deriveXdgRuntimeDir(env?: NodeJS.ProcessEnv, uid?: number | undefined, exists?: (p: string) => boolean): string | undefined;
 export declare const stateRoot: () => string;
 export declare const agentsRoot: () => string;
 export declare const tmpRoot: () => string;

package/dist/paths.js

@@ -1,7 +1,25 @@
+import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 /** Home root for config + state. OURS_FLEET_HOME overrides (tests, exotic setups). */
 export const home = () => process.env.OURS_FLEET_HOME ?? homedir();
+/**
+ * systemctl/journalctl --user locate the user bus via $XDG_RUNTIME_DIR/bus.
+ * sudo/su shells run inside the CALLING user's logind session, so the target
+ * user's shell gets no XDG_RUNTIME_DIR even when linger keeps the user manager
+ * (and the bus socket) alive at /run/user/<uid>. Derive the standard path once
+ * at CLI startup: never override an existing value, and only fire when the dir
+ * actually exists — when it doesn't, the real problem is missing linger and the
+ * systemctl error (plus its hint) is the right signal. (#9)
+ */
+export function deriveXdgRuntimeDir(env = process.env, uid = process.getuid?.(), exists = existsSync) {
+    if (!env.XDG_RUNTIME_DIR && uid !== undefined) {
+        const runDir = `/run/user/${uid}`;
+        if (exists(runDir))
+            env.XDG_RUNTIME_DIR = runDir;
+    }
+    return env.XDG_RUNTIME_DIR;
+}
 export const stateRoot = () => join(home(), '.ours-fleet');
 export const agentsRoot = () => join(stateRoot(), 'agents');
 export const tmpRoot = () => join(stateRoot(), 'tmp');

package/dist/runner.js

@@ -75,10 +75,15 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
         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)
+        const degradedMarker = join(dir, '.isolation-degraded');
+        if (sel.degraded) {
             deps.log(`[${name}] WARNING isolation requested but unavailable -> running UN-ISOLATED: ${sel.detail}`);
-        else
+            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.

package/dist/supervisor/systemd.d.ts

@@ -1,5 +1,12 @@
 import { type Exec } from '../exec.js';
 import type { SupervisorBackend } from './types.js';
 export declare const UNIT_TEMPLATE = "ours-fleet-agent@.service";
+/**
+ * Actionable hint when systemctl cannot reach the user bus. After the cli.ts
+ * XDG_RUNTIME_DIR fallback this branch stays reachable only when
+ * /run/user/<uid> itself is missing — i.e. linger is off and no session is
+ * active — so pointing at linger is the correct first hint. (#9)
+ */
+export declare const busHint: (stderr: string) => string;
 export declare const unitFor: (name: string) => string;
 export declare function makeSystemdBackend(exec?: Exec): SupervisorBackend;

package/dist/supervisor/systemd.js

@@ -4,6 +4,16 @@ import { userInfo } from 'node:os';
 import { home } from '../paths.js';
 import { realExec } from '../exec.js';
 export const UNIT_TEMPLATE = 'ours-fleet-agent@.service';
+/**
+ * Actionable hint when systemctl cannot reach the user bus. After the cli.ts
+ * XDG_RUNTIME_DIR fallback this branch stays reachable only when
+ * /run/user/<uid> itself is missing — i.e. linger is off and no session is
+ * active — so pointing at linger is the correct first hint. (#9)
+ */
+export const busHint = (stderr) => /user scope bus|XDG_RUNTIME_DIR/.test(stderr)
+    ? `\nhint: no user runtime dir — enable linger: sudo loginctl enable-linger ${userInfo().username}` +
+        `\n      (if linger is already on: export XDG_RUNTIME_DIR=/run/user/$(id -u))`
+    : '';
 export const unitFor = (name) => `ours-fleet-agent@${name}.service`;
 export function makeSystemdBackend(exec = realExec) {
     const ctl = (...args) => exec('systemctl', ['--user', ...args]);
@@ -38,18 +48,18 @@ WantedBy=default.target
         async install(name) {
             const r = await ctl('enable', '--now', unitFor(name));
             if (r.code !== 0)
-                throw new Error(`systemctl enable --now ${unitFor(name)} failed: ${r.stderr.trim()}`);
+                throw new Error(`systemctl enable --now ${unitFor(name)} failed: ${r.stderr.trim()}${busHint(r.stderr)}`);
         },
         async start(name) { await ctl('start', unitFor(name)); },
         async stop(name) {
             const r = await ctl('stop', unitFor(name));
             if (r.code !== 0)
-                throw new Error(`systemctl stop ${unitFor(name)} failed: ${r.stderr.trim()}`);
+                throw new Error(`systemctl stop ${unitFor(name)} failed: ${r.stderr.trim()}${busHint(r.stderr)}`);
         },
         async restart(name) {
             const r = await ctl('restart', unitFor(name));
             if (r.code !== 0)
-                throw new Error(`systemctl restart ${unitFor(name)} failed: ${r.stderr.trim()}`);
+                throw new Error(`systemctl restart ${unitFor(name)} failed: ${r.stderr.trim()}${busHint(r.stderr)}`);
         },
         async status(name) {
             const r = await ctl('status', unitFor(name), '--no-pager');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/fleet",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "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",