@ours.network/fleet 0.5.1 → 0.5.2

package/README.md

@@ -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:
@@ -234,13 +235,29 @@ 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**
 
+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,
@@ -266,8 +283,12 @@ 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.
+**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.
 
 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]);
 }

package/dist/doctor.js

@@ -3,7 +3,7 @@ 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 { 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). */
@@ -53,6 +53,16 @@ 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

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/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.1",
+  "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",