@ours.network/fleet 0.9.4 → 0.9.7

package/dist/supervisor/systemd.js

@@ -15,6 +15,44 @@ export const busHint = (stderr) => /user scope bus|XDG_RUNTIME_DIR/.test(stderr)
         `\n      (if linger is already on: export XDG_RUNTIME_DIR=/run/user/$(id -u))`
     : '';
 export const unitFor = (name) => `ours-fleet-agent@${name}.service`;
+/**
+ * systemd's own ActiveState vocabulary, classified. `activating` covers
+ * `auto-restart` — the unit is mid-restart, not stopped, so its context stands.
+ * `deactivating`/`reloading` still have a process. Only `inactive` and `failed`
+ * are definite stops. Anything systemd did not report is `unknown`.
+ */
+export function classifyActiveState(activeState) {
+    switch (activeState) {
+        case 'active':
+        case 'activating':
+        case 'reloading':
+        case 'deactivating': return 'running';
+        case 'inactive':
+        case 'failed': return 'stopped';
+        default: return 'unknown';
+    }
+}
+/**
+ * Ask the unit what state it is actually in.
+ *
+ * `show --value` is machine-readable and stable across versions; `status`
+ * prose is not, and neither — as it turns out — is an exit code. Shared by
+ * `liveness` and by `install`'s start verification so the two cannot disagree
+ * about what "running" means.
+ */
+async function probeLiveness(ctl, name) {
+    const r = await ctl('show', '-p', 'ActiveState', '-p', 'SubState', '--value', unitFor(name));
+    const [activeState = '', subState = ''] = r.stdout.trim().split('\n').map(l => l.trim());
+    if (!activeState)
+        return {
+            state: 'unknown',
+            detail: `systemctl show ${unitFor(name)} failed: ${r.stderr.trim() || `exit ${r.code}`}${busHint(r.stderr)}`,
+        };
+    return {
+        state: classifyActiveState(activeState),
+        detail: subState ? `${activeState} (${subState})` : activeState,
+    };
+}
 export function makeSystemdBackend(exec = realExec) {
     const ctl = (...args) => exec('systemctl', ['--user', ...args]);
     return {
@@ -30,8 +68,12 @@ After=default.target
 [Service]
 Type=simple
 ExecStart=${binPath} _run %i
-Restart=always
-RestartSec=2
+# The RUNNER owns the child-session restart loop, with a counted, backed-off
+# circuit breaker (3.2). systemd must only recover the runner PROCESS crashing —
+# Restart=always here would resume the uncounted two-second relaunch loop, and
+# would also restart a runner that is deliberately holding a failing agent down.
+Restart=on-failure
+RestartSec=5
 TimeoutStopSec=15
 
 [Install]
@@ -46,9 +88,49 @@ WantedBy=default.target
             return msgs;
         },
         async install(name) {
+            // Ask FIRST whether this unit was already enabled, so a rollback can tell
+            // "we registered this" from "it was already here" (6.2).
+            const before = await ctl('is-enabled', unitFor(name));
+            const alreadyEnabled = before.stdout.trim() === 'enabled';
             const r = await ctl('enable', '--now', unitFor(name));
-            if (r.code !== 0)
+            // Undo only what WE enabled. A unit that was already enabled belongs to
+            // whoever enabled it, and rollback may never remove that (6.2).
+            const undo = async () => { if (!alreadyEnabled)
+                await ctl('disable', '--now', unitFor(name)); };
+            if (r.code !== 0) {
+                // `enable --now` is enable THEN start, so a non-zero result can arrive
+                // with the symlink already written. Throwing then means `install` never
+                // returns `{created: true}`, the creation transaction records nothing,
+                // and a spawn that failed at registration leaves an enabled unit behind.
+                await undo();
                 throw new Error(`systemctl enable --now ${unitFor(name)} failed: ${r.stderr.trim()}${busHint(r.stderr)}`);
+            }
+            // THE EXIT CODE IS NOT THE SIGNAL, so the start is verified rather than
+            // assumed.
+            //
+            // Measured on systemd 255: `systemctl --user enable --now` whose START
+            // half fails returns **0** and reports the failed job only as prose on
+            // stderr, while a bare `start` of the same unit returns 1. Trusting the
+            // code there means a spawn reports success while the role's unit sits
+            // enabled and dead — the exact failure this release exists to remove,
+            // inside the command that creates the role.
+            //
+            // Asking the unit its own ActiveState is version-independent: it does not
+            // care whether this systemd propagates a start failure into the exit
+            // code, so it is correct both on versions that do and versions that do
+            // not. Only a DEFINITE stop counts. An unanswerable probe is `unknown`
+            // and must never be read as a failed start (1.1) — the unit may be
+            // perfectly fine and the bus merely unreachable.
+            const live = await probeLiveness(ctl, name);
+            if (live.state === 'stopped') {
+                await undo();
+                throw new Error(`systemctl enable --now ${unitFor(name)} reported success but the unit is not running `
+                    + `(${live.detail}); systemctl exited 0, which on this version does not report a failed `
+                    + `start. Check: systemctl --user status ${unitFor(name)}`);
+            }
+            return alreadyEnabled
+                ? { created: false, detail: `${unitFor(name)} was already enabled (${live.detail})` }
+                : { created: true, detail: `enabled ${unitFor(name)} (${live.detail})` };
         },
         async start(name) { await ctl('start', unitFor(name)); },
         async stop(name) {
@@ -65,7 +147,15 @@ WantedBy=default.target
             const r = await ctl('status', unitFor(name), '--no-pager');
             return r.stdout || r.stderr;
         },
-        async uninstall(name) { await ctl('disable', '--now', unitFor(name)); },
+        liveness(name) { return probeLiveness(ctl, name); },
+        async uninstall(name) {
+            const before = await ctl('is-enabled', unitFor(name));
+            const wasEnabled = before.stdout.trim() === 'enabled';
+            await ctl('disable', '--now', unitFor(name)); // idempotent
+            return wasEnabled
+                ? { removed: true, detail: `disabled ${unitFor(name)}` }
+                : { removed: false, detail: `${unitFor(name)} was not enabled` };
+        },
         logsArgs(name, follow) {
             return { cmd: 'journalctl', args: ['--user', '-u', unitFor(name), ...(follow ? ['-f'] : ['-n', '200'])] };
         },

package/dist/supervisor/types.d.ts

@@ -1,14 +1,47 @@
+/**
+ * Typed liveness verdict. `stopped` is a *definite* stop — the only state that
+ * lets a caller discard session context. `unknown` means the probe itself did
+ * not answer (bus unreachable, missing binary, unrecognised state) and must be
+ * treated as "may still be running".
+ */
+export type LivenessState = 'running' | 'stopped' | 'unknown';
+export interface Liveness {
+    state: LivenessState;
+    /** The backend's own words: native state tokens, or the probe failure. */
+    detail: string;
+}
+/** Whether `install` had to create the registration, or found it already there. */
+export interface InstallOutcome {
+    created: boolean;
+    detail: string;
+}
+export interface UninstallOutcome {
+    removed: boolean;
+    detail: string;
+}
 export interface SupervisorBackend {
     id: 'systemd' | 'launchd' | 'none';
     /** One-time host setup (unit template / dirs / linger). Returns human-readable messages. */
     init(binPath: string): Promise<string[]>;
-    /** Ensure the role's unit exists and is enabled + started. */
-    install(name: string, binPath: string): Promise<void>;
+    /**
+     * Ensure the role's unit exists and is enabled + started. Idempotent, and
+     * EXPLICIT about whether it created the registration: rollback may only
+     * remove what this transaction made, so "did I create this?" has to be
+     * answerable rather than assumed (6.2).
+     */
+    install(name: string, binPath: string): Promise<InstallOutcome>;
     start(name: string): Promise<void>;
     stop(name: string): Promise<void>;
     restart(name: string): Promise<void>;
     status(name: string): Promise<string>;
-    uninstall(name: string): Promise<void>;
+    /**
+     * Classify the role's liveness from the backend's own native result — never
+     * by matching prose in `status()`. Implementations must not throw: a failed
+     * probe is `unknown` with the failure in `detail`.
+     */
+    liveness(name: string): Promise<Liveness>;
+    /** Remove the registration. Idempotent; reports whether anything was there. */
+    uninstall(name: string): Promise<UninstallOutcome>;
     /** Command the CLI execs (stdio inherited) to show logs. */
     logsArgs(name: string, follow: boolean): {
         cmd: string;

package/dist/tmux.d.ts

@@ -1,14 +1,46 @@
 import { type Exec } from './exec.js';
+/** Socket-name prefix for every tmux server this fleet starts. */
+export declare const TMUX_SOCKET_PREFIX = "ours-fleet-";
+/**
+ * The tmux socket a session lives on — ONE SERVER PER SESSION (#32).
+ *
+ * Without `-L`, every role's pane lands on the single default tmux server. That
+ * server is a child of whichever role happened to start it first, so it sits in
+ * that role's unit cgroup: stopping that one unit takes down every other role's
+ * pane with it. A per-session socket puts each role's server in its own unit,
+ * which is what makes `stop` local to the role being stopped.
+ *
+ * Role names are `[A-Za-z0-9_-]+` (config.ts), so this is always a usable
+ * socket filename.
+ */
+export declare const tmuxSocket: (session: string) => string;
+/**
+ * Address a tmux command at that session's own server. EVERY tmux invocation in
+ * this repository must go through here — one that forgets `-L` silently talks to
+ * the shared default server and re-creates #32.
+ */
+export declare const tmuxArgs: (session: string, args: string[]) => string[];
 /** Thin tmux wrapper; all session handling in the core goes through this. */
 export declare class Tmux {
     private exec;
     constructor(exec?: Exec);
     has(name: string): Promise<boolean>;
     newSession(name: string, cwd: string, shellCommand: string): Promise<void>;
-    kill(name: string): Promise<void>;
+    /**
+     * Best-effort kill. Returns whether a session was actually there to destroy —
+     * the caller needs that to tell "we tore this session down" apart from "the
+     * program inside it exited on its own".
+     */
+    kill(name: string): Promise<boolean>;
     capture(name: string, lines?: number): Promise<string>;
     panePid(name: string): Promise<number | null>;
-    list(): Promise<string>;
+    /**
+     * List the live sessions among `names`, asking each server in turn.
+     * There is no fleet-wide `tmux ls` any more: a session per server means the
+     * caller says which sessions to ask about. A server that is not running
+     * answers non-zero and contributes nothing.
+     */
+    list(names: readonly string[]): Promise<string>;
     sendText(name: string, text: string): Promise<void>;
     sendKey(name: string, key: string): Promise<void>;
 }

package/dist/tmux.js

@@ -1,4 +1,25 @@
 import { realExec } from './exec.js';
+/** Socket-name prefix for every tmux server this fleet starts. */
+export const TMUX_SOCKET_PREFIX = 'ours-fleet-';
+/**
+ * The tmux socket a session lives on — ONE SERVER PER SESSION (#32).
+ *
+ * Without `-L`, every role's pane lands on the single default tmux server. That
+ * server is a child of whichever role happened to start it first, so it sits in
+ * that role's unit cgroup: stopping that one unit takes down every other role's
+ * pane with it. A per-session socket puts each role's server in its own unit,
+ * which is what makes `stop` local to the role being stopped.
+ *
+ * Role names are `[A-Za-z0-9_-]+` (config.ts), so this is always a usable
+ * socket filename.
+ */
+export const tmuxSocket = (session) => `${TMUX_SOCKET_PREFIX}${session}`;
+/**
+ * Address a tmux command at that session's own server. EVERY tmux invocation in
+ * this repository must go through here — one that forgets `-L` silently talks to
+ * the shared default server and re-creates #32.
+ */
+export const tmuxArgs = (session, args) => ['-L', tmuxSocket(session), ...args];
 /** Thin tmux wrapper; all session handling in the core goes through this. */
 export class Tmux {
     exec;
@@ -6,44 +27,60 @@ export class Tmux {
         this.exec = exec;
     }
     async has(name) {
-        return (await this.exec('tmux', ['has-session', '-t', name])).code === 0;
+        return (await this.exec('tmux', tmuxArgs(name, ['has-session', '-t', name]))).code === 0;
     }
     async newSession(name, cwd, shellCommand) {
-        const r = await this.exec('tmux', ['new-session', '-d', '-s', name, '-c', cwd, shellCommand]);
+        const r = await this.exec('tmux', tmuxArgs(name, ['new-session', '-d', '-s', name, '-c', cwd, shellCommand]));
         if (r.code !== 0)
             throw new Error(`tmux new-session '${name}' failed (${r.code}): ${r.stderr.trim()}`);
     }
+    /**
+     * Best-effort kill. Returns whether a session was actually there to destroy —
+     * the caller needs that to tell "we tore this session down" apart from "the
+     * program inside it exited on its own".
+     */
     async kill(name) {
-        await this.exec('tmux', ['kill-session', '-t', name]); // best-effort
+        return (await this.exec('tmux', tmuxArgs(name, ['kill-session', '-t', name]))).code === 0;
     }
     async capture(name, lines = 40) {
-        const r = await this.exec('tmux', ['capture-pane', '-t', name, '-p']);
+        const r = await this.exec('tmux', tmuxArgs(name, ['capture-pane', '-t', name, '-p']));
         if (r.code !== 0)
             throw new Error(`tmux capture-pane '${name}' failed: ${r.stderr.trim()}`);
         const all = r.stdout.replace(/\n+$/, '').split('\n');
         return all.slice(-lines).join('\n');
     }
     async panePid(name) {
-        const r = await this.exec('tmux', ['list-panes', '-t', name, '-F', '#{pane_pid}']);
+        const r = await this.exec('tmux', tmuxArgs(name, ['list-panes', '-t', name, '-F', '#{pane_pid}']));
         if (r.code !== 0)
             return null;
         const pid = parseInt(r.stdout.trim().split('\n')[0], 10);
         return Number.isFinite(pid) ? pid : null;
     }
-    async list() {
-        const r = await this.exec('tmux', ['ls']);
-        return r.code === 0 ? r.stdout.trimEnd() : '';
+    /**
+     * List the live sessions among `names`, asking each server in turn.
+     * There is no fleet-wide `tmux ls` any more: a session per server means the
+     * caller says which sessions to ask about. A server that is not running
+     * answers non-zero and contributes nothing.
+     */
+    async list(names) {
+        const lines = [];
+        for (const name of names) {
+            const r = await this.exec('tmux', tmuxArgs(name, ['ls']));
+            if (r.code === 0 && r.stdout.trim())
+                lines.push(r.stdout.trimEnd());
+        }
+        return lines.join('\n');
     }
     async sendText(name, text) {
-        let r = await this.exec('tmux', ['send-keys', '-t', name, '-l', text]);
+        let r = await this.exec('tmux', tmuxArgs(name, ['send-keys', '-t', name, '-l', text]));
         if (r.code !== 0)
             throw new Error(`tmux send-keys '${name}' failed: ${r.stderr.trim()}`);
-        r = await this.exec('tmux', ['send-keys', '-t', name, 'Enter']);
+        r = await this.exec('tmux', tmuxArgs(name, ['send-keys', '-t', name, 'Enter']));
         if (r.code !== 0)
             throw new Error(`tmux send-keys Enter '${name}' failed: ${r.stderr.trim()}`);
     }
     async sendKey(name, key) {
-        const r = await this.exec('tmux', ['send-keys', '-t', name, key]);
+        const r = await this.exec('tmux', tmuxArgs(name, ['send-keys', '-t', name, key]));
         if (r.code !== 0)
             throw new Error(`tmux send-keys '${name}' failed: ${r.stderr.trim()}`);
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ours.network/fleet",
-  "version": "0.9.4",
-  "description": "Harness-agnostic fleet of persistent, identity-bound AI agents. Declarative fleet.yaml, tmux consoles, systemd/launchd supervision, ours.network messaging.",
+  "version": "0.9.7",
+  "description": "Harness-agnostic fleet of persistent, identity-bound AI agents. Declarative fleet.yaml, tmux or ACP sessions, supervision, and ours.network messaging.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",
   "repository": {
@@ -26,9 +26,14 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
+    "@agentclientprotocol/sdk": "^1.3.0",
     "commander": "^12.1.0",
     "yaml": "^2.5.0"
   },
+  "optionalDependencies": {
+    "@agentclientprotocol/claude-agent-acp": "^0.63.0",
+    "@agentclientprotocol/codex-acp": "^1.1.7"
+  },
   "devDependencies": {
     "@types/node": "^20.14.0",
     "typescript": "^5.5.0",