@ours.network/fleet 0.9.5 → 0.9.7

package/dist/spawn.js

@@ -1,11 +1,19 @@
 import { spawn as spawnChild } from 'node:child_process';
-import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { stringify } from 'yaml';
+import { parse, stringify } from 'yaml';
 import { agentDir, fleetDDir } from './paths.js';
+import { validateIsolationConfig } from './isolation/policy.js';
 import { loadConfig, resolveMonitorConfig, resolvePermissions, } from './config.js';
 import { applyRole, up } from './ops.js';
 import { START_STAGGER_FILE } from './runner.js';
+import { buildProvenance, daemonIdentityProvisioner, ensureIdentity, provenanceOf, withCreationTransaction, writeProvenance, writeRoleFile, } from './creation.js';
+import { VERSION } from './version.js';
+/**
+ * The provenance record written by the most recent spawn in this process, so
+ * the CLI can print the same summary it persisted rather than rebuilding it.
+ */
+export let lastProvenance;
 function roleFromOpts(o, defaultHarness) {
     const r = {};
     if (o.harness)
@@ -53,8 +61,35 @@ function roleFromOpts(o, defaultHarness) {
         r.bio = readFileSync(o.bioFile, 'utf8').trim();
     if (o.personaFile)
         r.persona = readFileSync(o.personaFile, 'utf8').trim();
+    if (o.isolationFile)
+        r.isolation = readIsolationFile(o.isolationFile);
     return r;
 }
+/**
+ * Read and validate an `--isolation-file`. The file is the existing
+ * `isolation:` mapping and nothing else — the same schema, the same validator
+ * (`validateIsolationConfig`), so a policy written here cannot mean something
+ * different from the identical block in fleet.yaml.
+ *
+ * Called BEFORE the creation transaction reserves anything: an invalid file
+ * must fail before any artifact exists.
+ */
+export function readIsolationFile(path) {
+    let raw;
+    try {
+        raw = parse(readFileSync(path, 'utf8'));
+    }
+    catch (e) {
+        throw new Error(`--isolation-file ${path}: ${e.message}`);
+    }
+    // A file holding only comments parses to null; treat it as an empty policy,
+    // which is a meaningful request ("sandbox me with defaults").
+    const cfg = (raw ?? {});
+    const problems = validateIsolationConfig(cfg);
+    if (problems.length)
+        throw new Error(`--isolation-file ${path}: ${problems.join('; ')}`);
+    return cfg;
+}
 function validateSpawnOpts(o) {
     if (o.session && !['tmux', 'acp'].includes(o.session))
         throw new Error(`invalid --session '${o.session}'; allowed: tmux, acp`);
@@ -65,6 +100,12 @@ function validateSpawnOpts(o) {
     if (o.unattended && !['deny', 'wait'].includes(o.unattended))
         throw new Error(`invalid --unattended '${o.unattended}'; allowed: deny, wait`);
 }
+/**
+ * Reject names that are already USED. This is a precondition, not a claim: it
+ * runs INSIDE the creation transaction, after both names are reserved, so the
+ * gap between checking and creating that let two spawns both succeed is closed
+ * by the reservation rather than by this function.
+ */
 function assertNameFree(o) {
     const cfg = loadConfig(o.configPath);
     if (cfg.roles.some(r => r.name === o.name))
@@ -72,18 +113,96 @@ function assertNameFree(o) {
     if (existsSync(agentDir(o.name)) || existsSync(agentDir(o.name, true)))
         throw new Error(`agent dir for '${o.name}' already exists — pick another name or 'ours-fleet rm ${o.name}'`);
 }
+/** The ours identity a spawn will bind: explicit, else the role name. */
+export const effectiveIdentity = (o) => o.identity ?? o.name;
+/**
+ * Which settings came from the operator, from fleet defaults, or from a
+ * built-in (6.6). Built while the options are still separable — once they are
+ * merged into a ResolvedRole the distinction is gone.
+ *
+ * `env`, `bio`, `persona` and `harness_options` are deliberately absent: the
+ * record exists to be read, and must not become a place credentials collect.
+ */
+function provenanceSettings(o, defaults) {
+    const perms = (defaults.permissions ?? {});
+    return {
+        harness: provenanceOf(o.harness, defaults.harness, 'claude-code'),
+        session: provenanceOf(o.session, defaults.session, 'tmux'),
+        identity: o.identity
+            ? { value: o.identity, source: 'cli' }
+            : { value: o.name, source: 'built-in' }, // defaults to the role name
+        cwd: provenanceOf(o.cwd, undefined, undefined),
+        model: provenanceOf(o.model?.trim(), defaults.model, undefined),
+        coordinator: provenanceOf(o.coordinator, undefined, undefined),
+        approval: provenanceOf(o.approval, perms.approval, 'ask'),
+        filesystem: provenanceOf(o.filesystem, perms.filesystem, 'workspace'),
+        unattended: provenanceOf(o.unattended, perms.unattended, 'deny'),
+        isolation: o.isolationFile
+            ? { value: 'declared via --isolation-file', source: 'cli' }
+            : { value: defaults.isolation ? 'from fleet defaults' : undefined, source: defaults.isolation ? 'fleet-default' : 'built-in' },
+    };
+}
 /** Permanent spawn: persist to ~/fleet.d/<Name>.yaml, then bring it up. */
-export async function spawnPermanent(o, deps) {
+export async function spawnPermanent(o, deps, creation = {}) {
     validateSpawnOpts(o);
-    assertNameFree(o);
-    const cfg = loadConfig(o.configPath);
-    mkdirSync(fleetDDir(), { recursive: true });
-    const file = join(fleetDDir(), `${o.name}.yaml`);
-    writeFileSync(file, stringify({
-        roles: { [o.name]: roleFromOpts(o, cfg.defaults.harness) },
-    }));
-    await up(loadConfig(o.configPath), [o.name], deps, o.configPath);
-    return file;
+    if (o.isolationFile)
+        readIsolationFile(o.isolationFile); // fail before reserving
+    // Name AND identity reserved together, before anything is written or started
+    // (6.4). A loser of the race creates no config, no state, no service.
+    return withCreationTransaction({ role: o.name, identity: effectiveIdentity(o) }, async (tx) => {
+        assertNameFree(o);
+        const cfg = loadConfig(o.configPath);
+        // Establish the identity BEFORE the service is enabled (7.3), and record
+        // what was actually guaranteed so the briefing can say something true.
+        const guarantee = await ensureIdentity(effectiveIdentity(o), { bio: o.bioFile ? readFileSync(o.bioFile, 'utf8').trim() : undefined,
+            persona: o.personaFile ? readFileSync(o.personaFile, 'utf8').trim() : undefined }, creation.identityProvisioner ?? daemonIdentityProvisioner(), deps.log);
+        if (guarantee.state === 'created')
+            // We minted it; a failed creation must not leave an orphan identity
+            // behind. Only ever removes an identity THIS transaction created.
+            tx.record({
+                stage: `ours identity ${effectiveIdentity(o)}`,
+                undo: async () => {
+                    await creation.identityProvisioner?.remove?.(effectiveIdentity(o));
+                },
+            });
+        mkdirSync(fleetDDir(), { recursive: true });
+        const file = join(fleetDDir(), `${o.name}.yaml`);
+        writeRoleFile(tx, file, stringify({
+            roles: { [o.name]: roleFromOpts(o, cfg.defaults.harness) },
+        }));
+        // `up` materialises the state dir and registers the service. Journal the
+        // dir before it exists so a failure leaves the name genuinely reusable
+        // rather than blocked by a half-built directory.
+        const stateDir = agentDir(o.name);
+        const stateExisted = existsSync(stateDir);
+        tx.record({
+            stage: `state dir ${stateDir}`,
+            undo: () => { if (!stateExisted)
+                rmSync(stateDir, { recursive: true, force: true }); },
+        });
+        // Journal the service registration BEFORE it happens, and undo only the
+        // registrations this transaction actually created (6.2). `registered` is
+        // filled by `up`'s onInstalled hook at the moment each registration is
+        // made — not from its return value, which never arrives when `up` throws
+        // after registering.
+        const registered = [];
+        tx.record({
+            stage: `service registration for ${o.name}`,
+            undo: async () => { for (const n of registered)
+                await deps.backend.uninstall(n); },
+        });
+        // Provenance is written BEFORE the role starts, so a role that fails to
+        // launch still records how it was asked for (6.6).
+        const provenance = buildProvenance({
+            role: o.name, lifetime: 'permanent', fleetVersion: VERSION,
+            settings: provenanceSettings(o, cfg.defaults),
+        });
+        mkdirSync(agentDir(o.name), { recursive: true });
+        writeProvenance(agentDir(o.name), provenance);
+        await up(loadConfig(o.configPath), [o.name], { ...deps, onInstalled: outcome => registered.push(outcome.role) }, o.configPath, guarantee.state);
+        lastProvenance = provenance;
+        return file;
+    }, creation);
 }
 const detachedSupervisor = (binPath, args, dir) => {
     // Log to the temp dir; the fd stays valid even after runTemp removes the dir.
@@ -95,8 +214,19 @@ const detachedSupervisor = (binPath, args, dir) => {
     child.unref();
 };
 /** Temp spawn: state under ~/.ours-fleet/tmp, plain tmux, auto-clean on exit. */
-export async function spawnTemp(o, binPath, launch = detachedSupervisor) {
+export async function spawnTemp(o, binPath, launch = detachedSupervisor, creation = {}) {
     validateSpawnOpts(o);
+    if (o.isolationFile)
+        readIsolationFile(o.isolationFile); // fail before reserving
+    // Temporary roles go through the SAME reservation boundary as permanent ones
+    // (6.4): a temp agent competes for the same names.
+    return withCreationTransaction({ role: o.name, identity: effectiveIdentity(o) }, async (tx) => {
+        const guarantee = await ensureIdentity(effectiveIdentity(o), { bio: o.bioFile ? readFileSync(o.bioFile, 'utf8').trim() : undefined,
+            persona: o.personaFile ? readFileSync(o.personaFile, 'utf8').trim() : undefined }, creation.identityProvisioner ?? daemonIdentityProvisioner(), creation.log);
+        return spawnTempInner(o, binPath, launch, tx, guarantee);
+    }, creation);
+}
+async function spawnTempInner(o, binPath, launch, tx, guarantee) {
     assertNameFree(o);
     const cfg = loadConfig(o.configPath);
     const defaultHarness = cfg.defaults.harness;
@@ -106,7 +236,7 @@ export async function spawnTemp(o, binPath, launch = detachedSupervisor) {
         ...(fromOpts.harness_options ?? {}),
     };
     const role = {
-        ...fromOpts,
+        ...fromOpts, // includes `isolation` when --isolation-file was given
         name: o.name,
         harness: o.harness ?? defaultHarness ?? 'claude-code',
         session: o.session ?? cfg.defaults.session ?? 'tmux',
@@ -114,11 +244,19 @@ export async function spawnTemp(o, binPath, launch = detachedSupervisor) {
         model: o.model?.trim() || cfg.defaults.model,
         harness_options: Object.keys(mergedHarnessOptions).length ? mergedHarnessOptions : undefined,
         permissions: resolvePermissions(cfg.defaults.permissions, fromOpts.permissions),
+        permissionsDeclared: fromOpts.permissions !== undefined || cfg.defaults.permissions !== undefined,
         // Temp agents inherit the fleet-wide monitor defaults via the snapshot (design §2).
         monitor: resolveMonitorConfig(cfg.defaults.monitor, fromOpts.monitor),
         sourceFile: '(temp)',
     };
-    const dir = applyRole(role, { temp: true });
+    const dir = applyRole(role, { temp: true, identityGuarantee: guarantee.state });
+    const provenance = buildProvenance({
+        role: o.name, lifetime: 'temporary', fleetVersion: VERSION,
+        settings: provenanceSettings(o, cfg.defaults),
+    });
+    writeProvenance(dir, provenance);
+    lastProvenance = provenance;
+    tx.record({ stage: `temp state dir ${dir}`, undo: () => rmSync(dir, { recursive: true, force: true }) });
     writeFileSync(join(dir, 'role.yaml'), stringify(role));
     // Snapshot the fleet start-stagger so the detached temp supervisor (no config path
     // threaded through it) honors the same launch gate — a burst of temp spawns spaces

package/dist/supervisor/launchd.d.ts

@@ -1,4 +1,54 @@
 import { type Exec } from '../exec.js';
 import type { SupervisorBackend } from './types.js';
 export declare const labelFor: (name: string) => string;
+/**
+ * What `launchctl print` said about a job, parsed ONCE so that the two questions
+ * asked of it cannot drift apart. They are not the same question:
+ *
+ * - `liveness` asks "does this role's context still exist" — a loaded job counts,
+ *   including one waiting between KeepAlive restarts (1.1);
+ * - `install` asks "did the job I just bootstrapped actually START" — for which a
+ *   job that is loaded, not running, and has already exited once is a failure.
+ *
+ * On systemd one `ActiveState` answers both. Here the answers differ, so what is
+ * shared is the READING of launchd's output, not its classification.
+ */
+export interface LaunchdJob {
+    /** `launchctl print` exited 0 — the job is loaded in the domain. */
+    loaded: boolean;
+    /** launchd's own `state = …`, e.g. `running`, `waiting`, `not running`. */
+    state?: string;
+    /**
+     * `last exit code|status|reason = …`. Present only once the program has RUN
+     * and exited — which is what separates "died" from "has not started yet".
+     */
+    lastExit?: string;
+    /** The domain has no such service: a definite negative, not a failed probe. */
+    notFound: boolean;
+    /** Why the probe itself could not be read, when it could not. */
+    failure?: string;
+}
+/**
+ * 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 declare function classifyStart(job: LaunchdJob): {
+    started: 'yes' | 'no' | 'unknown';
+    detail: string;
+};
 export declare function makeLaunchdBackend(exec?: Exec, uid?: number): SupervisorBackend;

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'])] };
         },