@ours.network/fleet 1.2.0-nightly.9 → 2.0.0

package/dist/supervisor/manager.js

@@ -0,0 +1,270 @@
+import { spawn } from 'node:child_process';
+import { closeSync, existsSync, openSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { producerConfig } from '../notifications/outbox.js';
+import { TaskNotificationProducer } from '../notifications/task-producer.js';
+import { acquireOwnerBinderLease } from '../owner-channel/binder.js';
+import { stateRoot } from '../paths.js';
+import { readRestartLedger, writeRestartLedger, backoffFor, RESTART_FAIL_THRESHOLD } from '../runner.js';
+import { realExec } from '../exec.js';
+import { listMemberKeys, managedMemberEnvironment, memberPath, memberProcess, readMember, withMemberLock, writeMember } from './catalog.js';
+/** One parent owns process creation for every kind of Fleet member. */
+export async function runFleetManager(entrypoint, deps = {}) {
+    const lease = await acquireOwnerBinderLease(join(stateRoot(), 'supervisor'), 'fleet-manager', 'fleet-manager');
+    const children = new Map();
+    const now = deps.now ?? Date.now;
+    const log = deps.log ?? (message => console.error(message));
+    const exec = deps.exec ?? realExec;
+    const sleep = deps.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+    let stopping = false;
+    const stop = () => { stopping = true; };
+    process.on('SIGTERM', stop);
+    process.on('SIGINT', stop);
+    const spawnChild = deps.spawnChild ?? ((member, generation) => {
+        if (!existsSync(member.dir))
+            throw Error('Fleet member state missing');
+        const fd = openSync(join(member.dir, 'supervisor.log'), 'a', 0o600);
+        try {
+            return spawn(process.execPath, [entrypoint, '_run-managed', member.key, generation], {
+                // A process group permits bounded cleanup of a hung runner and its harness.
+                // IPC couples its lifetime to this parent even if the parent is SIGKILLed.
+                detached: true, stdio: ['ignore', fd, fd, 'ipc'], env: managedMemberEnvironment(member),
+            });
+        }
+        finally {
+            closeSync(fd);
+        }
+    });
+    let notifications;
+    async function reconcile(key) {
+        await withMemberLock(key, async () => {
+            const member = readMember(key);
+            const owned = children.get(key);
+            if (!member) {
+                if (owned && !owned.stoppingAt) {
+                    owned.stoppingAt = Date.now();
+                    owned.child.kill('SIGTERM');
+                }
+                return;
+            }
+            // Our ChildProcess supplies exit notification for steady owned members.
+            // Probe argv only for predecessor discovery or before an actual stop;
+            // macOS otherwise spawned one ps process per member every 250ms.
+            if (owned && owned.generation === member.generation && member.desired === 'running' && !stopping && !owned.stoppingAt)
+                return;
+            const live = await memberProcess(member, exec);
+            if (member.desired === 'stopped' || stopping) {
+                if (live.state === 'running' && live.pid) {
+                    if (owned && owned.generation === member.generation) {
+                        if (!owned.stoppingAt) {
+                            owned.stoppingAt = Date.now();
+                            owned.child.kill('SIGTERM');
+                        }
+                        else if (Date.now() - owned.stoppingAt >= 15_000) {
+                            // Re-check exact generation immediately before a group signal.
+                            try {
+                                process.kill(-live.pid, 'SIGKILL');
+                            }
+                            catch { /* next probe proves absence */ }
+                        }
+                    }
+                    else {
+                        // A predecessor's child has lost IPC and is shutting down. Never adopt
+                        // or launch alongside it; its worker also holds the member lifetime lease.
+                        log(`[fleet] waiting for predecessor ${key}`);
+                    }
+                }
+                return;
+            }
+            if (live.state !== 'stopped' || owned || (member.retryAt ?? 0) > Date.now() || readRestartLedger(member.dir).circuit === 'open')
+                return;
+            const generation = randomUUID();
+            writeMember({ ...member, generation, pid: undefined });
+            let child;
+            try {
+                child = spawnChild(member, generation);
+            }
+            catch {
+                if (!existsSync(member.dir)) {
+                    writeMember({ ...member, generation: undefined, pid: undefined, retryAt: Date.now() + 30_000 });
+                    return;
+                }
+                const ledger = readRestartLedger(member.dir);
+                const failures = ledger.consecutiveImmediateFailures + 1;
+                writeRestartLedger(member.dir, { ...ledger, consecutiveImmediateFailures: failures, circuit: failures >= RESTART_FAIL_THRESHOLD ? 'open' : 'closed', nextDelayMs: backoffFor(failures), lastReason: 'Fleet child spawn failed', updatedAt: new Date().toISOString() });
+                writeMember({ ...member, generation: undefined, pid: undefined, retryAt: Date.now() + backoffFor(failures) });
+                return;
+            }
+            const childState = { child, generation, startedAt: now() };
+            children.set(key, childState);
+            writeMember({ ...member, generation, pid: child.pid });
+            let finished = false;
+            const finish = (failed) => {
+                if (finished)
+                    return;
+                finished = true;
+                if (children.get(key) === childState)
+                    children.delete(key);
+                void withMemberLock(key, async () => {
+                    const current = readMember(key);
+                    if (!current || current.generation !== generation)
+                        return;
+                    if (current.kind === 'temporary' && !existsSync(current.dir)) {
+                        rmSync(memberPath(key));
+                        return;
+                    }
+                    let taskCompleted = false;
+                    if (!failed && !stopping && !childState.stoppingAt && current.kind === 'task') {
+                        try {
+                            taskCompleted = !(await import('../task-supervision.js')).taskSupervisorMayRun(current.name);
+                        }
+                        catch {
+                            failed = true;
+                        } // uncertainty consumes the existing bounded failure budget
+                    }
+                    const ledger = readRestartLedger(current.dir);
+                    let previousFailures = ledger.consecutiveImmediateFailures;
+                    if (failed && !stopping && !childState.stoppingAt) {
+                        const { stableSupervisorWindow } = await import('../runner.js');
+                        if (now() - childState.startedAt >= stableSupervisorWindow(current.name, current.kind !== 'permanent', current.configPath) * 1000)
+                            previousFailures = 0;
+                    }
+                    const failures = failed && !stopping && !childState.stoppingAt ? previousFailures + 1 : ledger.consecutiveImmediateFailures;
+                    if (failed && !stopping && !childState.stoppingAt && existsSync(current.dir))
+                        writeRestartLedger(current.dir, {
+                            ...ledger, consecutiveImmediateFailures: failures, lastReason: 'Fleet member runner exited unexpectedly',
+                            circuit: failures >= RESTART_FAIL_THRESHOLD ? 'open' : 'closed', nextDelayMs: backoffFor(failures),
+                            updatedAt: new Date().toISOString(), ...(failures >= RESTART_FAIL_THRESHOLD ? { openedAt: new Date().toISOString() } : {}),
+                        });
+                    writeMember({ ...current, pid: undefined, generation: undefined,
+                        retryAt: Date.now() + backoffFor(failures),
+                        // A completed task/transient worker must not become an endless launch loop.
+                        desired: !failed && !stopping && !childState.stoppingAt && (current.kind === 'temporary' || taskCompleted) ? 'stopped' : current.desired });
+                }).catch(() => log(`[fleet] child completion record unavailable: ${key}`));
+            };
+            child.once('error', () => finish(true));
+            child.once('exit', (code, signal) => {
+                // The tracked child created this private process group; reclaim any harness
+                // descendants even when the runner itself crashed before cleaning them.
+                if (child.pid) {
+                    try {
+                        process.kill(-child.pid, 'SIGKILL');
+                    }
+                    catch { /* already absent */ }
+                }
+                finish(code !== 0 || signal !== null);
+            });
+        });
+    }
+    try {
+        try {
+            const config = producerConfig(process.env, undefined, log);
+            if (config)
+                notifications = new TaskNotificationProducer(config, log);
+        }
+        catch {
+            log('[fleet] task notifications unavailable; committed events retained');
+        }
+        try {
+            const { resumeFleetTransfers } = await import('./adoption.js');
+            await resumeFleetTransfers(entrypoint, exec);
+        }
+        catch (error) {
+            // Existing catalog members continue; uncertain transfers remain held with
+            // their receipts. Operator init/up reports the same actionable failure.
+            log(`[fleet] transfer pending: ${error instanceof Error ? error.message : 'proof unavailable'}`);
+        }
+        while (!stopping && !deps.shouldStop?.()) {
+            for (const key of listMemberKeys()) {
+                try {
+                    await reconcile(key);
+                }
+                catch {
+                    log(`[fleet] reconciliation held: ${key}`);
+                }
+            }
+            await sleep(250);
+        }
+    }
+    finally {
+        stopping = true;
+        await notifications?.close();
+        // Shutdown preserves desired intent; the successor resumes the same catalog.
+        const deadline = Date.now() + 17_000;
+        while (children.size && Date.now() < deadline) {
+            for (const key of children.keys())
+                await reconcile(key);
+            await sleep(100);
+        }
+        process.off('SIGTERM', stop);
+        process.off('SIGINT', stop);
+        lease.release();
+    }
+}
+/** Workers cannot outlive their parent or overlap another generation of this member. */
+export async function runManagedMember(key, generation) {
+    let stopping = false;
+    const stop = () => { stopping = true; };
+    const disconnected = () => {
+        stopping = true;
+        process.kill(process.pid, 'SIGTERM');
+        setTimeout(() => process.kill(-process.pid, 'SIGKILL'), 15_000).unref();
+    };
+    process.on('SIGTERM', stop);
+    process.on('SIGINT', stop);
+    process.on('disconnect', disconnected);
+    if (!process.connected)
+        throw Error('FLEET_MEMBER_PARENT_MISSING');
+    const lease = await acquireOwnerBinderLease(join(stateRoot(), 'supervisor', 'workers', key), 'fleet-member', key);
+    try {
+        const member = readMember(key);
+        if (!member || member.generation !== generation || member.desired !== 'running' || stopping)
+            return;
+        const { runSupervised } = await import('../runner.js');
+        if (member.kind === 'permanent') {
+            const { waitForRoleDaemon } = await import('../startup-readiness.js');
+            // Waiting for a daemon is readiness, not a failed harness attempt.
+            while (!stopping) {
+                try {
+                    await waitForRoleDaemon(member.name, member.configPath);
+                    break;
+                }
+                catch {
+                    if (!stopping)
+                        await new Promise(resolve => setTimeout(resolve, 5000));
+                }
+            }
+            if (!stopping)
+                await runSupervised(member.name, { configPath: member.configPath }, { shouldStop: () => stopping });
+        }
+        else if (member.kind === 'watchdogs') {
+            const { runScheduler } = await import('../watchdog/scheduler.js');
+            await runScheduler(member.configPath, {
+                now: () => new Date(), sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+                log: message => console.log(message), binPath: process.argv[1], shouldStop: () => stopping,
+            });
+        }
+        else {
+            const { runTempSupervisor } = await import('../temp-supervisor-recovery.js');
+            const { runTemp } = await import('../runner.js');
+            await runTempSupervisor(member.name, process.argv[1], () => runTemp(member.name, {
+                shouldStop: () => stopping, suspendOnStop: true,
+            }), true);
+        }
+    }
+    finally {
+        lease.release();
+        process.off('SIGTERM', stop);
+        process.off('SIGINT', stop);
+        process.off('disconnect', disconnected);
+        if (process.connected)
+            process.disconnect();
+        else if (stopping) {
+            try {
+                process.kill(-process.pid, 'SIGKILL');
+            }
+            catch { /* no private group */ }
+        }
+    }
+}

package/dist/supervisor/registration-refresh.d.ts

@@ -0,0 +1,45 @@
+import { type Exec } from '../exec.js';
+/** The release tree that owns a Fleet CLI script, if it is a packaged one. */
+export declare function releaseRoot(script: string): string | undefined;
+export type RegistrationState = 
+/** No definition installed; refresh never creates one. */
+'absent'
+/** Already runs the invoking release, or a stable launcher outside any release tree. */
+ | 'current'
+/** Pins another release tree. */
+ | 'stale'
+/** Rewritten to the invoking release by this refresh. */
+ | 'refreshed'
+/** Rewritten, but the service manager did not reload it; it still starts the old release. */
+ | 'reload-failed'
+/** Not a definition Fleet generated, or overridden; left untouched. */
+ | 'unrecognized';
+export type RunningState = 'current' | 'stale' | 'stopped' | 'unknown';
+export interface RegistrationReport {
+    service: 'supervisor' | 'web' | 'watchdogs';
+    path: string;
+    state: RegistrationState;
+    /** Release tree the definition pinned before this call. */
+    from?: string;
+    to?: string;
+    /** What the live process runs, which a definition rewrite does not change. */
+    running: RunningState;
+    detail?: string;
+}
+export interface RefreshOptions {
+    /** realpath of the invoking CLI script. */
+    binPath: string;
+    /** Rewrite stale definitions; false only reports. */
+    write: boolean;
+    platform?: NodeJS.Platform;
+    homeDir?: string;
+    exec?: Exec;
+    exists?(path: string): boolean;
+    /** argv of a live process, for comparing what it runs with its definition. */
+    processArgv?(pid: number): string[] | undefined;
+}
+/** Report, and with `write` refresh, each installed Fleet service definition. */
+export declare function refreshServiceRegistrations(options: RefreshOptions): Promise<RegistrationReport[]>;
+/** One operator line per definition, including the restart a refresh cannot do. */
+export declare function describeRegistration(report: RegistrationReport): string;
+export declare const registrationDrift: (reports: RegistrationReport[]) => RegistrationReport[];

package/dist/supervisor/registration-refresh.js

@@ -0,0 +1,266 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { replaceFileAtomically } from '../atomic-file.js';
+import { realExec } from '../exec.js';
+import { home } from '../paths.js';
+import { WATCHDOG_LAUNCHD_LABEL, WATCHDOG_SYSTEMD_UNIT } from '../watchdog/service.js';
+import { WEB_LAUNCHD_LABEL, WEB_SYSTEMD_UNIT } from '../web/service.js';
+import { labelFor } from './launchd.js';
+import { UNIT_TEMPLATE } from './systemd.js';
+/**
+ * Service definitions written by `init`, `web install` and the watchdog
+ * installer pin the realpath of the CLI that wrote them: an immutable,
+ * per-release package tree. An update installs a new tree and moves the
+ * `ours-fleet` command, but a definition is only rewritten when that command
+ * runs again, so after the next reboot the OS starts the previous release's
+ * supervisor while agents, web and CLI run the new one.
+ *
+ * Refresh re-points an existing Fleet-generated definition at the invoking
+ * release and changes nothing else: environment, profile, ports and drop-ins
+ * are kept byte for byte, and no unit is created, enabled, started, stopped
+ * or restarted. A running process keeps its old code until its operator
+ * restarts it, which the report states rather than doing.
+ */
+const PACKAGE_SCRIPT = ['node_modules', '@ours.network', 'fleet', 'dist', 'cli.js'].join(sep);
+/** The release tree that owns a Fleet CLI script, if it is a packaged one. */
+export function releaseRoot(script) {
+    const suffix = sep + PACKAGE_SCRIPT;
+    return script.endsWith(suffix) ? script.slice(0, -suffix.length) : undefined;
+}
+function definitions(platform, homeDir) {
+    if (platform === 'linux') {
+        const dir = join(homeDir, '.config', 'systemd', 'user');
+        return [
+            { service: 'supervisor', unit: UNIT_TEMPLATE, path: join(dir, UNIT_TEMPLATE), entry: '_run-fleet',
+                marker: 'ours-fleet process manager' },
+            { service: 'web', unit: WEB_SYSTEMD_UNIT, path: join(dir, WEB_SYSTEMD_UNIT), entry: 'web',
+                marker: 'ours-fleet localhost web console' },
+            { service: 'watchdogs', unit: WATCHDOG_SYSTEMD_UNIT, path: join(dir, WATCHDOG_SYSTEMD_UNIT), entry: '_run-watchdogs',
+                marker: 'ours-fleet watchdog scheduler' },
+        ];
+    }
+    if (platform === 'darwin') {
+        const dir = join(homeDir, 'Library', 'LaunchAgents');
+        return [
+            { service: 'supervisor', path: join(dir, `${labelFor('fleet')}.plist`), entry: '_run-fleet', marker: labelFor('fleet') },
+            { service: 'web', path: join(dir, `${WEB_LAUNCHD_LABEL}.plist`), entry: 'web', marker: WEB_LAUNCHD_LABEL },
+            { service: 'watchdogs', path: join(dir, `${WATCHDOG_LAUNCHD_LABEL}.plist`), entry: '_run-watchdogs',
+                marker: WATCHDOG_LAUNCHD_LABEL },
+        ];
+    }
+    return [];
+}
+const NODE_RUNTIME = /^node(js)?[0-9.]*$/;
+const systemdQuote = (value) => `"${value.replace(/[%\\"]/g, char => char === '%' ? '%%' : `\\${char}`)}"`;
+const xml = (value) => value.replace(/[&<>"']/g, char => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;',
+}[char]));
+const unxml = (value) => value.replaceAll('&quot;', '"').replaceAll('&apos;', "'")
+    .replaceAll('&lt;', '<').replaceAll('&gt;', '>').replaceAll('&amp;', '&');
+function parseGenerated(text, platform, definition) {
+    if (platform === 'linux') {
+        const lines = text.split('\n');
+        const only = (pattern) => {
+            const found = lines.flatMap((line, index) => pattern.test(line) ? [index] : []);
+            return found.length === 1 ? found[0] : undefined;
+        };
+        if (lines[only(/^Description=/) ?? -1] !== `Description=${definition.marker}`)
+            return undefined;
+        if (lines[only(/^Type=/) ?? -1] !== 'Type=simple')
+            return undefined;
+        const exec = only(/^\s*ExecStart\s*=/);
+        if (exec === undefined || !lines[exec].startsWith('ExecStart="'))
+            return undefined;
+        const args = [...lines[exec].slice('ExecStart='.length).matchAll(/"((?:[^"\\]|\\.)*)"|(\S+)/g)]
+            .map(match => match[1] !== undefined ? match[1].replace(/\\(.)/g, '$1').replaceAll('%%', '%') : match[2]);
+        const [runtime, script, entry] = args;
+        if (!runtime?.startsWith('/') || !NODE_RUNTIME.test(runtime.split('/').at(-1)) || entry !== definition.entry || !script)
+            return undefined;
+        const quoted = `${systemdQuote(runtime)} ${systemdQuote(script)} `;
+        if (!lines[exec].startsWith(`ExecStart=${quoted}`))
+            return undefined;
+        const pathLine = only(/^Environment="PATH=/);
+        return {
+            script,
+            rewrite(next, path) {
+                const out = [...lines];
+                out[exec] = `ExecStart=${systemdQuote(runtime)} ${systemdQuote(next)} ${lines[exec].slice(`ExecStart=${quoted}`.length)}`;
+                if (pathLine !== undefined) {
+                    const value = /^Environment="PATH=((?:[^"\\]|\\.)*)"$/.exec(lines[pathLine])?.[1];
+                    if (value !== undefined && !/[\\%]/.test(value))
+                        out[pathLine] = `Environment="PATH=${value.split(':').map(path).join(':')}"`;
+                }
+                return out.join('\n');
+            },
+        };
+    }
+    if (!new RegExp(`<key>Label</key>\\s*<string>${definition.marker.replaceAll('.', '\\.')}</string>`).test(text))
+        return undefined;
+    const program = /<key>ProgramArguments<\/key>\s*<array>\s*<string>([^<]*)<\/string>\s*<string>([^<]*)<\/string>\s*<string>([^<]*)<\/string>/.exec(text);
+    if (!program)
+        return undefined;
+    const [, runtime, script, entry] = program.map(unxml);
+    if (!runtime.startsWith('/') || !NODE_RUNTIME.test(runtime.split('/').at(-1)) || entry !== definition.entry)
+        return undefined;
+    return {
+        script,
+        rewrite(next, path) {
+            const head = program[0];
+            const moved = head.replace(`<string>${program[2]}</string>`, `<string>${xml(next)}</string>`);
+            let out = text.replace(head, moved);
+            out = out.replace(/(<key>PATH<\/key>\s*<string>)([^<]*)(<\/string>)/, (_all, open, value, close) => `${open}${xml(unxml(value).split(':').map(path).join(':'))}${close}`);
+            return out;
+        },
+    };
+}
+/** A systemd drop-in that sets ExecStart owns the command line; Fleet must not fight it. */
+function overriddenByDropIn(path) {
+    const dir = `${path}.d`;
+    try {
+        return readdirSync(dir).some(name => name.endsWith('.conf')
+            && /^\s*ExecStart\s*=/m.test(readFileSync(join(dir, name), 'utf8')));
+    }
+    catch {
+        return false;
+    }
+}
+const procArgv = (pid) => {
+    try {
+        return readFileSync(`/proc/${pid}/cmdline`, 'utf8').split('\0').filter(Boolean);
+    }
+    catch {
+        return undefined;
+    }
+};
+async function runningState(definition, options, platform) {
+    if (platform !== 'linux' || !definition.unit)
+        return 'unknown';
+    const exec = options.exec ?? realExec;
+    const shown = await exec('systemctl', ['--user', 'show', '-p', 'MainPID', '--value', definition.unit]);
+    if (shown.code !== 0)
+        return 'unknown';
+    const pid = Number(shown.stdout.trim());
+    if (!Number.isSafeInteger(pid) || pid < 0)
+        return 'unknown';
+    if (pid === 0)
+        return 'stopped';
+    const argv = (options.processArgv ?? procArgv)(pid);
+    const script = argv?.[1];
+    if (!script)
+        return 'unknown';
+    // A stable launcher resolves to whichever release it pointed at when started.
+    if (!releaseRoot(script))
+        return 'unknown';
+    return script === options.binPath ? 'current' : 'stale';
+}
+/**
+ * Whether systemd still runs an older load of this unit than the file on disk.
+ * A rewrite whose daemon-reload failed looks current on the next pass; this is
+ * what keeps that pending reload visible instead of losing it.
+ */
+async function reloadPending(definition, options, platform) {
+    if (platform !== 'linux' || !definition.unit)
+        return false;
+    const shown = await (options.exec ?? realExec)('systemctl', ['--user', 'show', '-p', 'NeedDaemonReload', '--value', definition.unit]);
+    return shown.code === 0 && shown.stdout.trim() === 'yes';
+}
+/** Report, and with `write` refresh, each installed Fleet service definition. */
+export async function refreshServiceRegistrations(options) {
+    const platform = options.platform ?? process.platform;
+    const homeDir = options.homeDir ?? home();
+    const exists = options.exists ?? existsSync;
+    const target = releaseRoot(options.binPath);
+    const reports = [];
+    let rewrote = false;
+    for (const definition of definitions(platform, homeDir)) {
+        const base = { service: definition.service, path: definition.path };
+        if (!exists(definition.path)) {
+            reports.push({ ...base, state: 'absent', running: 'stopped' });
+            continue;
+        }
+        const running = await runningState(definition, options, platform);
+        const text = readFileSync(definition.path, 'utf8');
+        const generated = parseGenerated(text, platform, definition);
+        if (!generated) {
+            reports.push({ ...base, state: 'unrecognized', running,
+                detail: 'not the definition Fleet generates for this service; left untouched' });
+            continue;
+        }
+        const from = releaseRoot(generated.script);
+        if (!from || generated.script === options.binPath) {
+            if (await reloadPending(definition, options, platform)) {
+                // Normally an earlier refresh whose daemon-reload failed: the file is
+                // right, the loaded unit is not. Reload now, or keep reporting drift.
+                if (options.write) {
+                    rewrote = true;
+                    reports.push({ ...base, state: 'refreshed', running, ...(from ? { from } : {}),
+                        detail: 'definition on disk was not loaded yet; reloaded' });
+                }
+                else
+                    reports.push({ ...base, state: 'reload-failed', running, ...(from ? { from } : {}),
+                        detail: 'systemd has not loaded the definition on disk; run systemctl --user daemon-reload' });
+                continue;
+            }
+            reports.push({ ...base, state: 'current', running, ...(from ? { from } : {}) });
+            continue;
+        }
+        if (!target) {
+            reports.push({ ...base, state: 'stale', running, from,
+                detail: 'the invoking CLI is not a packaged release; nothing to point the definition at' });
+            continue;
+        }
+        if (platform === 'linux' && overriddenByDropIn(definition.path)) {
+            reports.push({ ...base, state: 'unrecognized', running, from,
+                detail: `a drop-in in ${definition.path}.d sets ExecStart; left untouched` });
+            continue;
+        }
+        if (!options.write) {
+            reports.push({ ...base, state: 'stale', running, from, to: target });
+            continue;
+        }
+        // Only bundled tool directories on PATH follow the release; every other
+        // setting, including a profile or home stored under a release tree, stays.
+        const kept = [];
+        const next = generated.rewrite(options.binPath, entry => {
+            if (!entry.startsWith(from + '/'))
+                return entry;
+            const moved = target + entry.slice(from.length);
+            if (exists(moved))
+                return moved;
+            kept.push(entry);
+            return entry;
+        });
+        if (parseGenerated(next, platform, definition)?.script !== options.binPath) {
+            reports.push({ ...base, state: 'unrecognized', running, from,
+                detail: 'the rewritten definition would not launch the invoking release; left untouched' });
+            continue;
+        }
+        replaceFileAtomically(definition.path, next, statSync(definition.path).mode & 0o777);
+        rewrote = true;
+        reports.push({ ...base, state: 'refreshed', running, from, to: target,
+            ...(kept.length ? { detail: `kept PATH entries absent from the new release: ${kept.join(', ')}` } : {}) });
+    }
+    if (rewrote && platform === 'linux') {
+        const reload = await (options.exec ?? realExec)('systemctl', ['--user', 'daemon-reload']);
+        // The file is rewritten, but systemd keeps the loaded unit until a reload,
+        // so a failed reload is not a refresh.
+        if (reload.code !== 0)
+            for (const report of reports)
+                if (report.state === 'refreshed') {
+                    report.state = 'reload-failed';
+                    report.detail = [report.detail, `systemctl --user daemon-reload failed: ${reload.stderr.trim() || `exit ${reload.code}`}; `
+                            + 'run it, then restart the service when convenient'].filter(Boolean).join('; ');
+                }
+    }
+    return reports;
+}
+/** One operator line per definition, including the restart a refresh cannot do. */
+export function describeRegistration(report) {
+    const what = `${report.service.padEnd(10)} ${report.state}`;
+    const pins = report.from ? ` ${report.from}${report.to ? ` -> ${report.to}` : ''}` : '';
+    const restart = report.running === 'stale'
+        ? `; the running process still uses ${report.state === 'refreshed' ? 'the previous' : 'another'} release until restarted`
+        : '';
+    return `${what}${pins}${restart}${report.detail ? ` (${report.detail})` : ''}`;
+}
+export const registrationDrift = (reports) => reports.filter(report => report.state === 'stale' || report.state === 'reload-failed' || report.running === 'stale');

package/dist/supervisor/scope.d.ts

@@ -0,0 +1,4 @@
+import { type Exec } from '../exec.js';
+/** OS user services have one namespace. Isolated homes must not hijack it.
+ * Injected executors exercise isolated definitions without touching a user manager. */
+export declare function assertNativeFleetScope(exec: Exec): void;

package/dist/supervisor/scope.js

@@ -0,0 +1,10 @@
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { home } from '../paths.js';
+import { realExec } from '../exec.js';
+/** OS user services have one namespace. Isolated homes must not hijack it.
+ * Injected executors exercise isolated definitions without touching a user manager. */
+export function assertNativeFleetScope(exec) {
+    if (exec === realExec && resolve(home()) !== resolve(homedir()))
+        throw Error('FLEET_SERVICE_HOME_CONFLICT: managed OS supervision requires the OS user home; use OURS_FLEET_SUPERVISOR=none for isolated fleets');
+}

package/dist/supervisor/systemd.d.ts

@@ -1,6 +1,6 @@
 import { type Exec } from '../exec.js';
 import type { LivenessState, SupervisorBackend } from './types.js';
-export declare const UNIT_TEMPLATE = "ours-fleet-agent@.service";
+export declare const UNIT_TEMPLATE = "ours-fleet.service";
 /**
  * Actionable hint when systemctl cannot reach the user bus. After the cli.ts
  * XDG_RUNTIME_DIR fallback this branch stays reachable only when
@@ -8,7 +8,7 @@ export declare const UNIT_TEMPLATE = "ours-fleet-agent@.service";
  * 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 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.