@ours.network/fleet 0.9.5 → 0.9.8

package/dist/supervisor/launchd.js

@@ -1,8 +1,17 @@
-import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { home, logsRoot } from '../paths.js';
 import { realExec } from '../exec.js';
 export const labelFor = (name) => `network.ours.fleet.${name}`;
+/**
+ * The spelling of the last-exit line is not stable across macOS releases
+ * (`last exit code`, `last exit status`, `last exit reason`), so match the
+ * family rather than one member. This is the load-bearing signal in
+ * `classifyStart`, so it errs towards NOT matching: an unrecognised spelling
+ * yields `unknown`, never a false failure.
+ */
+const LAST_EXIT_RE = /^\s*last exit (?:code|status|reason)\s*=\s*(.+?)\s*$/mi;
+const STATE_RE = /^\s*state\s*=\s*(.+?)\s*$/m;
 const agentsDir = () => join(home(), 'Library', 'LaunchAgents');
 const plistPath = (name) => join(agentsDir(), `${labelFor(name)}.plist`);
 function plist(name, binPath) {
@@ -14,7 +23,10 @@ function plist(name, binPath) {
   <key>Label</key><string>${labelFor(name)}</string>
   <key>ProgramArguments</key>
   <array><string>${binPath}</string><string>_run</string><string>${name}</string></array>
-  <key>KeepAlive</key><true/>
+  <!-- The runner owns the child-session restart loop (3.2). launchd must only
+       recover the runner PROCESS crashing: a bare KeepAlive would resume the
+       uncounted relaunch loop and restart a deliberately held-down agent. -->
+  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
   <key>RunAtLoad</key><true/>
   <key>StandardOutPath</key><string>${log}</string>
   <key>StandardErrorPath</key><string>${log}</string>
@@ -22,8 +34,59 @@ function plist(name, binPath) {
 </plist>
 `;
 }
+/**
+ * Did the job we just bootstrapped actually start?
+ *
+ * `launchctl bootstrap` exits 0 once the job is LOADED. With `RunAtLoad` the
+ * program then starts asynchronously, so a zero exit is a statement about the
+ * load, not about the program — the same shape of lie that `systemctl enable
+ * --now` tells on systemd 255, where the exit code is 0 and the unit is dead.
+ *
+ * Only a DEFINITE stop counts as a failed start, exactly as on systemd:
+ *
+ * - not loaded at all, though bootstrap said it worked → definite;
+ * - loaded, `state` is not running, AND launchd already has an exit status for
+ *   it → it ran and died → definite;
+ * - loaded and running, or waiting for a KeepAlive restart, or not running with
+ *   nothing exited yet (it simply has not been spawned yet — the asynchrony
+ *   RunAtLoad introduces) → NOT a failure;
+ * - an unreadable probe → `unknown`, never a failure (1.1). launchd may be fine
+ *   and the tool merely unable to answer.
+ */
+export function classifyStart(job) {
+    if (job.notFound)
+        return { started: 'no', detail: 'the service is not loaded in the domain' };
+    if (!job.loaded)
+        return { started: 'unknown', detail: job.failure ?? 'launchctl print could not be read' };
+    // Deliberately narrow: only launchd's own `not running` is read as stopped.
+    // Any state this does not recognise falls through to "started", because a
+    // wrong guess here rolls back a role that is in fact fine.
+    const stopped = job.state !== undefined && /^not running$/i.test(job.state.trim());
+    if (stopped && job.lastExit !== undefined)
+        return { started: 'no', detail: `state = ${job.state}, last exit = ${job.lastExit}` };
+    if (stopped)
+        return { started: 'unknown', detail: `state = ${job.state}, but nothing has exited yet` };
+    return { started: 'yes', detail: job.state ? `state = ${job.state}` : 'loaded' };
+}
 export function makeLaunchdBackend(exec = realExec, uid = process.getuid?.() ?? 501) {
     const domain = `gui/${uid}`;
+    /** Read `launchctl print` once; both callers classify it for their own question. */
+    const printJob = async (name) => {
+        const r = await exec('launchctl', ['print', `${domain}/${labelFor(name)}`]);
+        const out = `${r.stdout}\n${r.stderr}`;
+        if (r.code !== 0)
+            return {
+                loaded: false,
+                notFound: /could not find service|no such process/i.test(out),
+                failure: `launchctl print ${labelFor(name)} failed: ${r.stderr.trim() || r.stdout.trim() || `exit ${r.code}`}`,
+            };
+        return {
+            loaded: true,
+            notFound: false,
+            state: STATE_RE.exec(r.stdout)?.[1],
+            lastExit: LAST_EXIT_RE.exec(r.stdout)?.[1],
+        };
+    };
     return {
         id: 'launchd',
         async init() {
@@ -37,11 +100,50 @@ export function makeLaunchdBackend(exec = realExec, uid = process.getuid?.() ??
         async install(name, binPath) {
             mkdirSync(agentsDir(), { recursive: true });
             mkdirSync(logsRoot(), { recursive: true });
+            // The plist's prior existence is the record of whether we created this.
+            const existed = existsSync(plistPath(name));
             writeFileSync(plistPath(name), plist(name, binPath));
             await exec('launchctl', ['bootout', `${domain}/${labelFor(name)}`]); // best-effort refresh
+            // Undo only what WE wrote. A plist that was already there belongs to
+            // whoever put it there, and rollback may never remove it (6.2).
+            const undo = async () => {
+                if (existed)
+                    return;
+                await exec('launchctl', ['bootout', `${domain}/${labelFor(name)}`]);
+                rmSync(plistPath(name), { force: true });
+            };
             const r = await exec('launchctl', ['bootstrap', domain, plistPath(name)]);
-            if (r.code !== 0)
+            if (r.code !== 0) {
+                // The plist is already on disk, carrying RunAtLoad. Throwing here means
+                // `install` never returns `{created: true}`, so the creation transaction
+                // records nothing and its rollback removes nothing — and a spawn that
+                // failed at registration leaves a launch artifact behind (6.2). Undo our
+                // own partial write before throwing, and only when WE wrote it.
+                await undo();
                 throw new Error(`launchctl bootstrap ${labelFor(name)} failed: ${r.stderr.trim()}`);
+            }
+            // THE EXIT CODE IS NOT THE SIGNAL — the launchd half of the same fix made
+            // for systemd in 4023e72.
+            //
+            // `bootstrap` exits 0 when the job is LOADED. `RunAtLoad` then starts the
+            // program asynchronously, so a zero exit says nothing about whether the
+            // program ran: "bootstrap exits 0, job immediately dead" is available on
+            // macOS for the same reason "enable --now exits 0, unit dead" is on
+            // systemd 255. Trusting it means `ours-fleet spawn` reports a created role
+            // whose job is loaded and not running.
+            //
+            // A failed start takes the SAME rollback path as a failed bootstrap, so
+            // nothing is left behind either way.
+            const start = classifyStart(await printJob(name));
+            if (start.started === 'no') {
+                await undo();
+                throw new Error(`launchctl bootstrap ${labelFor(name)} reported success but the job is not running `
+                    + `(${start.detail}); bootstrap exits 0 once the job is loaded, which does not report a `
+                    + `failed start. Check: launchctl print ${domain}/${labelFor(name)}`);
+            }
+            return existed
+                ? { created: false, detail: `${labelFor(name)} was already installed (${start.detail})` }
+                : { created: true, detail: `installed ${labelFor(name)} (${start.detail})` };
         },
         async start(name) {
             const r = await exec('launchctl', ['bootstrap', domain, plistPath(name)]);
@@ -64,9 +166,24 @@ export function makeLaunchdBackend(exec = realExec, uid = process.getuid?.() ??
                 return `not loaded (${labelFor(name)})`;
             return r.stdout.split('\n').slice(0, 12).join('\n');
         },
+        async liveness(name) {
+            const job = await printJob(name);
+            // Loaded. `state = waiting` is a KeepAlive service between restarts —
+            // still supervised, so its context stands. Unchanged by the install-time
+            // start check above, which asks a different question of the same output.
+            if (job.loaded)
+                return { state: 'running', detail: job.state ? `loaded (state = ${job.state})` : 'loaded' };
+            if (job.notFound)
+                return { state: 'stopped', detail: `not loaded (${labelFor(name)})` };
+            return { state: 'unknown', detail: job.failure ?? `launchctl print ${labelFor(name)} failed` };
+        },
         async uninstall(name) {
-            await exec('launchctl', ['bootout', `${domain}/${labelFor(name)}`]);
+            const existed = existsSync(plistPath(name));
+            await exec('launchctl', ['bootout', `${domain}/${labelFor(name)}`]); // idempotent
             rmSync(plistPath(name), { force: true });
+            return existed
+                ? { removed: true, detail: `removed ${labelFor(name)}` }
+                : { removed: false, detail: `${labelFor(name)} was not installed` };
         },
         logsArgs(name, follow) {
             const log = join(logsRoot(), `${name}.log`);

package/dist/supervisor/none.js

@@ -1,4 +1,4 @@
-import { Tmux } from '../tmux.js';
+import { Tmux, tmuxArgs } from '../tmux.js';
 import { realExec, shq } from '../exec.js';
 /**
  * No supervision: sessions are plain tmux, nothing survives a reboot and
@@ -11,14 +11,32 @@ export function makeNoneBackend(exec = realExec) {
         id: 'none',
         async init() { return ['no supervisor: sessions are plain tmux (no reboot survival)']; },
         async install(name, binPath) {
-            await tmux.kill(name);
+            const existed = await tmux.kill(name); // true when a session was there
             await tmux.newSession(name, process.cwd(), `${shq(binPath)} _run ${shq(name)}`);
+            return existed
+                ? { created: false, detail: `replaced the existing tmux session '${name}'` }
+                : { created: true, detail: `created tmux session '${name}'` };
         },
         async start(name) { throw new Error(`'${name}' has no unit under the none backend — use install/spawn`); },
         async stop(name) { await tmux.kill(name); },
         async restart(name) { throw new Error(`restart unsupported under the none backend — stop + install '${name}'`); },
         async status(name) { return (await tmux.has(name)) ? `tmux session '${name}' running` : `'${name}' not running`; },
-        async uninstall(name) { await tmux.kill(name); },
-        logsArgs(name) { return { cmd: 'tmux', args: ['capture-pane', '-t', name, '-p'] }; },
+        async liveness(name) {
+            // Report the tmux probe directly: 0 = session exists, 1 = it does not.
+            // Any other code (127 = no tmux binary) is a failed probe, not a stop.
+            const r = await exec('tmux', tmuxArgs(name, ['has-session', '-t', name]));
+            if (r.code === 0)
+                return { state: 'running', detail: `tmux session '${name}' exists` };
+            if (r.code === 1)
+                return { state: 'stopped', detail: `no tmux session '${name}'` };
+            return { state: 'unknown', detail: `tmux has-session '${name}' failed (${r.code}): ${r.stderr.trim() || 'no output'}` };
+        },
+        async uninstall(name) {
+            const killed = await tmux.kill(name); // idempotent
+            return killed
+                ? { removed: true, detail: `killed tmux session '${name}'` }
+                : { removed: false, detail: `no tmux session '${name}'` };
+        },
+        logsArgs(name) { return { cmd: 'tmux', args: tmuxArgs(name, ['capture-pane', '-t', name, '-p']) }; },
     };
 }

package/dist/supervisor/systemd.d.ts

@@ -1,5 +1,5 @@
 import { type Exec } from '../exec.js';
-import type { SupervisorBackend } from './types.js';
+import type { LivenessState, 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
@@ -9,4 +9,11 @@ export declare const UNIT_TEMPLATE = "ours-fleet-agent@.service";
  */
 export declare const busHint: (stderr: string) => string;
 export declare const unitFor: (name: string) => string;
+/**
+ * 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 declare function classifyActiveState(activeState: string): LivenessState;
 export declare function makeSystemdBackend(exec?: Exec): SupervisorBackend;

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