@ours.network/fleet 1.2.0-nightly.6 → 1.2.0-nightly.61

package/dist/supervisor/catalog.d.ts

@@ -0,0 +1,62 @@
+import { type Exec } from '../exec.js';
+import type { TaskSupervisorOwner } from '../temp-lifecycle.js';
+import type { Liveness } from './types.js';
+export interface FleetMember {
+    version: 1;
+    key: string;
+    name: string;
+    kind: 'permanent' | 'task' | 'temporary' | 'watchdogs';
+    dir: string;
+    desired: 'running' | 'stopped';
+    retiring?: boolean;
+    incarnation: string;
+    taskOwner?: TaskSupervisorOwner;
+    launchId?: string;
+    configPath?: string;
+    environment?: Record<string, string>;
+    generation?: string;
+    pid?: number;
+    retryAt?: number;
+}
+/** Private 0600 member state retains exactly the creator's profile selection.
+ * Pin the resolved profile path even when the caller relied on HOME defaults. */
+export declare function captureMemberEnvironment(env?: NodeJS.ProcessEnv): Promise<Record<string, string>>;
+export declare function managedMemberEnvironment(member: FleetMember, parent?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare const catalogRoot: () => string;
+export declare function memberKey(name: string, kind: FleetMember['kind']): string;
+export declare function memberPath(key: string): string;
+export declare const withMemberLock: <T>(key: string, work: () => T | Promise<T>) => Promise<T>;
+export declare function readMember(key: string): FleetMember | undefined;
+export declare function writeMember(record: FleetMember): void;
+export declare function listMemberKeys(): string[];
+export declare function listMembers(): FleetMember[];
+export type MemberRegistration = Pick<FleetMember, 'name' | 'kind' | 'dir' | 'taskOwner' | 'launchId' | 'configPath' | 'environment'>;
+/** Persist intent before starting anything. The parent never discovers members from tmp directories. */
+export declare function registerMember(input: MemberRegistration, options?: {
+    initialDesired?: FleetMember['desired'];
+    preserveExisting?: boolean;
+}): Promise<{
+    created: boolean;
+    member: FleetMember;
+}>;
+export interface CatalogDeps {
+    exec?: Exec;
+    sleep?(ms: number): Promise<void>;
+    timeoutMs?: number;
+}
+/** A unique generation in argv fences PID reuse, including the spawn-to-pid-write crash seam. */
+export declare function memberProcess(record: FleetMember, exec?: Exec): Promise<Liveness & {
+    pid?: number;
+}>;
+export declare function catalogLiveness(key: string, exec?: Exec): Promise<Liveness>;
+export declare function waitMember(key: string, desired: 'running' | 'stopped', deps?: CatalogDeps): Promise<void>;
+export declare function stopMember(key: string, deps?: CatalogDeps): Promise<void>;
+export declare function unregisterMember(key: string, deps?: CatalogDeps): Promise<boolean>;
+export declare function unregisterTaskMember(role: string, expected: {
+    taskId: string;
+    creationActionId?: string;
+    launchId?: string;
+}, deps?: CatalogDeps): Promise<void>;
+export declare function hasTaskMemberRegistration(role: string): boolean;
+export declare function assertTaskRegistrationsAbsent(taskId: string): void;
+export declare const permanentRegistration: (name: string) => MemberRegistration;

package/dist/supervisor/catalog.js

@@ -0,0 +1,254 @@
+import { chmodSync, mkdirSync, lstatSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { replaceFileAtomically, withFileLock } from '../atomic-file.js';
+import { agentDir, stateRoot, watchdogsRoot } from '../paths.js';
+import { realExec } from '../exec.js';
+import { assertSafeAncestors } from '../rooms-tasks/workspace.js';
+const MEMBER_ENV_KEYS = ['HOME', 'PATH', 'XDG_RUNTIME_DIR', 'CODEX_HOME', 'CODEX_PATH', 'OURS_PORT', 'OURS_STATE_DIR', 'OURS_API_TOKEN', 'OURS_CONFIG'];
+/** Private 0600 member state retains exactly the creator's profile selection.
+ * Pin the resolved profile path even when the caller relied on HOME defaults. */
+export async function captureMemberEnvironment(env = process.env) {
+    const { clientConfigPath } = await import('../client-profile.js');
+    return Object.fromEntries([...MEMBER_ENV_KEYS.flatMap(key => env[key] === undefined ? [] : [[key, env[key]]]), ['OURS_CONFIG', clientConfigPath(env)]]);
+}
+export function managedMemberEnvironment(member, parent = process.env) {
+    const env = { ...parent };
+    if (member.environment) {
+        for (const key of MEMBER_ENV_KEYS)
+            delete env[key];
+        Object.assign(env, member.environment);
+    }
+    return env;
+}
+export const catalogRoot = () => join(stateRoot(), 'supervisor', 'members');
+export function memberKey(name, kind) {
+    if (!/^[A-Za-z0-9_-]{1,160}$/.test(name))
+        throw Error('FLEET_MEMBER_INVALID_NAME');
+    return `${kind}-${name}`;
+}
+export function memberPath(key) {
+    if (!/^(permanent|task|temporary|watchdogs)-[A-Za-z0-9_-]{1,160}$/.test(key))
+        throw Error('FLEET_MEMBER_INVALID_KEY');
+    return join(catalogRoot(), `${key}.json`);
+}
+export const withMemberLock = (key, work) => withFileLock(join(stateRoot(), 'locks', 'fleet-members', memberKeyFromValidatedKey(key)), work);
+function memberKeyFromValidatedKey(key) { memberPath(key); return key; }
+export function readMember(key) {
+    const path = memberPath(key);
+    assertSafeAncestors(catalogRoot());
+    let stat;
+    try {
+        stat = lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 256 * 1024)
+        throw Error('FLEET_MEMBER_UNSAFE_RECORD');
+    const record = JSON.parse(readFileSync(path, 'utf8'));
+    validateMember(record, key);
+    return record;
+}
+function validateMember(record, key) {
+    const expectedDir = record.kind === 'watchdogs' ? watchdogsRoot()
+        : agentDir(record.name, record.kind !== 'permanent');
+    if (record.version !== 1 || !['permanent', 'task', 'temporary', 'watchdogs'].includes(record.kind)
+        || memberKey(record.name, record.kind) !== key || record.key !== key
+        || !['running', 'stopped'].includes(record.desired)
+        || !/^[a-f0-9-]{36}$/.test(record.incarnation)
+        || record.dir !== resolve(record.dir) || record.dir !== expectedDir
+        || (record.environment !== undefined && (typeof record.environment !== 'object' || record.environment === null
+            || Object.entries(record.environment).some(([key, value]) => !MEMBER_ENV_KEYS.includes(key) || typeof value !== 'string' || value.includes('\0'))))
+        || (record.pid !== undefined && (!Number.isSafeInteger(record.pid) || record.pid <= 0))
+        || (record.retryAt !== undefined && (!Number.isFinite(record.retryAt) || record.retryAt < 0))
+        || (record.kind === 'task' && (!record.taskOwner?.taskId || !record.taskOwner.creationActionId || !record.launchId)))
+        throw Error('FLEET_MEMBER_INVALID_RECORD');
+}
+export function writeMember(record) {
+    validateMember(record, record.key);
+    assertSafeAncestors(catalogRoot());
+    mkdirSync(catalogRoot(), { recursive: true, mode: 0o700 });
+    chmodSync(catalogRoot(), 0o700);
+    replaceFileAtomically(memberPath(record.key), JSON.stringify(record) + '\n');
+}
+export function listMemberKeys() {
+    try {
+        return readdirSync(catalogRoot()).filter(name => name.endsWith('.json')).map(name => name.slice(0, -5));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+export function listMembers() {
+    let entries;
+    try {
+        entries = readdirSync(catalogRoot(), { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    return entries.filter(entry => entry.name.endsWith('.json')).map(entry => {
+        const value = readMember(entry.name.slice(0, -5));
+        if (!value)
+            throw Error('FLEET_MEMBER_DISAPPEARED');
+        return value;
+    });
+}
+/** Persist intent before starting anything. The parent never discovers members from tmp directories. */
+export async function registerMember(input, options = {}) {
+    const key = memberKey(input.name, input.kind);
+    return withMemberLock(key, () => {
+        const previous = readMember(key);
+        if (previous && (previous.dir !== input.dir || previous.launchId !== input.launchId
+            || JSON.stringify(previous.taskOwner) !== JSON.stringify(input.taskOwner)))
+            throw Error('FLEET_MEMBER_OWNER_COLLISION');
+        if (previous && options.preserveExisting)
+            return { created: false, member: previous };
+        if (previous?.retiring)
+            throw Error('FLEET_MEMBER_RETIRING');
+        const desired = options.initialDesired ?? 'running';
+        const member = previous
+            ? { ...previous, desired, configPath: input.configPath ?? previous.configPath,
+                environment: previous.kind === 'task' ? previous.environment : input.environment ?? previous.environment, retryAt: 0 }
+            : { ...input, version: 1, key, desired, incarnation: randomUUID() };
+        writeMember(member);
+        return { created: !previous, member };
+    });
+}
+/** A unique generation in argv fences PID reuse, including the spawn-to-pid-write crash seam. */
+export async function memberProcess(record, exec = realExec) {
+    if (!record.generation)
+        return { state: 'stopped', detail: 'no child generation' };
+    if (!/^[a-f0-9-]{36}$/.test(record.generation))
+        return { state: 'unknown', detail: 'invalid child generation' };
+    const matches = (command) => command.split(/\s+/).some((part, index, words) => part === '_run-managed' && words[index + 1] === record.key && words[index + 2] === record.generation);
+    if (record.pid) {
+        try {
+            process.kill(record.pid, 0);
+        }
+        catch (error) {
+            return error.code === 'ESRCH'
+                ? { state: 'stopped', detail: 'child pid absent' }
+                : { state: 'unknown', detail: 'child pid probe failed' };
+        }
+        try {
+            const command = readFileSync(`/proc/${record.pid}/cmdline`, 'utf8').split('\0').join(' ');
+            return matches(command) ? { state: 'running', detail: 'exact child generation', pid: record.pid }
+                : { state: 'stopped', detail: 'pid belongs to another generation' };
+        }
+        catch { /* non-/proc hosts use ps */ }
+    }
+    const result = await exec('ps', record.pid ? ['-p', String(record.pid), '-o', 'pid=', '-o', 'command=']
+        : ['-ax', '-o', 'pid=', '-o', 'command=']);
+    if (result.code !== 0)
+        return result.code === 1 && record.pid
+            ? { state: 'stopped', detail: 'child absent' } : { state: 'unknown', detail: 'process probe unavailable' };
+    const pids = result.stdout.split('\n').flatMap(line => {
+        const row = /^\s*(\d+)\s+(.*)$/.exec(line);
+        return row && matches(row[2]) ? [Number(row[1])] : [];
+    });
+    if (pids.length > 1)
+        return { state: 'unknown', detail: 'ambiguous child generation' };
+    return pids.length ? { state: 'running', detail: 'exact child generation', pid: pids[0] }
+        : { state: 'stopped', detail: 'child generation absent' };
+}
+export async function catalogLiveness(key, exec = realExec) {
+    try {
+        const record = readMember(key);
+        if (!record)
+            return { state: 'stopped', detail: 'member unregistered' };
+        const live = await memberProcess(record, exec);
+        if (live.state === 'stopped' && record.desired === 'running') {
+            const { readRestartLedger } = await import('../runner.js');
+            const ledger = readRestartLedger(record.dir);
+            if (ledger.circuit === 'open')
+                return { ...live, detail: `held after ${ledger.consecutiveImmediateFailures} failures: ${ledger.lastReason}; use up/restart or task recovery to reset` };
+        }
+        return live;
+    }
+    catch {
+        return { state: 'unknown', detail: 'member record unavailable' };
+    }
+}
+export async function waitMember(key, desired, deps = {}) {
+    const deadline = Date.now() + (deps.timeoutMs ?? 30_000);
+    do {
+        const live = await catalogLiveness(key, deps.exec);
+        if (live.state === desired)
+            return;
+        await (deps.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms))))(100);
+    } while (Date.now() < deadline);
+    throw Error(desired === 'stopped' ? 'FLEET_MEMBER_STOP_UNPROVEN' : 'FLEET_MEMBER_START_UNPROVEN');
+}
+export async function stopMember(key, deps = {}) {
+    await withMemberLock(key, () => {
+        const record = readMember(key);
+        if (record)
+            writeMember({ ...record, desired: 'stopped' });
+    });
+    // A stopped parent cannot consume intent, but its IPC children stop on disconnect.
+    // Never signal an arbitrary recorded pid or erase a record on timeout.
+    await waitMember(key, 'stopped', deps);
+}
+export async function unregisterMember(key, deps = {}) {
+    const original = readMember(key);
+    if (!original)
+        return false;
+    await withMemberLock(key, () => {
+        const current = readMember(key);
+        if (!current || current.incarnation !== original.incarnation)
+            throw Error('FLEET_MEMBER_RETIREMENT_CONFLICT');
+        writeMember({ ...current, desired: 'stopped', retiring: true });
+    });
+    await waitMember(key, 'stopped', deps);
+    return withMemberLock(key, async () => {
+        const current = readMember(key);
+        if (!current)
+            return false;
+        if (current.incarnation !== original.incarnation || current.desired !== 'stopped')
+            throw Error('FLEET_MEMBER_RETIREMENT_CONFLICT');
+        if ((await memberProcess(current, deps.exec)).state !== 'stopped')
+            throw Error('FLEET_MEMBER_STOP_UNPROVEN');
+        rmSync(memberPath(key));
+        return true;
+    });
+}
+export async function unregisterTaskMember(role, expected, deps = {}) {
+    const key = memberKey(role, 'task');
+    await withMemberLock(key, () => {
+        const current = readMember(key);
+        if (!current)
+            return;
+        if (current.kind !== 'task' || current.taskOwner?.taskId !== expected.taskId
+            || (!expected.creationActionId && !expected.launchId)
+            || (expected.creationActionId !== undefined && current.taskOwner.creationActionId !== expected.creationActionId)
+            || (expected.launchId !== undefined && current.launchId !== expected.launchId))
+            throw Error('TASK_SERVICE_OWNER_MISMATCH');
+        writeMember({ ...current, desired: 'stopped', retiring: true });
+    });
+    await unregisterMember(key, deps);
+}
+export function hasTaskMemberRegistration(role) {
+    const path = memberPath(memberKey(role, 'task'));
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+export function assertTaskRegistrationsAbsent(taskId) {
+    if (listMembers().some(record => record.taskOwner?.taskId === taskId))
+        throw Error('TASK_SERVICES_REMAIN');
+}
+export const permanentRegistration = (name) => ({ name, kind: 'permanent', dir: agentDir(name) });

package/dist/supervisor/fleet.d.ts

@@ -0,0 +1,8 @@
+import { type Exec } from '../exec.js';
+import type { SupervisorBackend } from './types.js';
+export declare function fleetHostBackend(exec?: Exec, platform?: NodeJS.Platform): SupervisorBackend;
+/** Registration only starts an explicitly installed parent; it cannot repoint
+ * the fleet at the invoking task/development binary or rewrite user settings. */
+export declare function ensureFleetParent(exec?: Exec, platform?: NodeJS.Platform): Promise<void>;
+/** OS operations refer only to the Fleet parent; member operations refer only to its catalog. */
+export declare function makeFleetBackend(exec?: Exec, platform?: NodeJS.Platform): SupervisorBackend;

package/dist/supervisor/fleet.js

@@ -0,0 +1,89 @@
+import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { agentDir } from '../paths.js';
+import { realExec } from '../exec.js';
+import { home } from '../paths.js';
+import { makeSystemdBackend } from './systemd.js';
+import { makeLaunchdBackend } from './launchd.js';
+import { catalogLiveness, memberKey, readMember, registerMember, stopMember, unregisterMember, waitMember } from './catalog.js';
+export function fleetHostBackend(exec = realExec, platform = process.platform) {
+    if (platform === 'linux')
+        return makeSystemdBackend(exec);
+    if (platform === 'darwin')
+        return makeLaunchdBackend(exec);
+    throw Error('Fleet service requires Linux or macOS');
+}
+/** Registration only starts an explicitly installed parent; it cannot repoint
+ * the fleet at the invoking task/development binary or rewrite user settings. */
+export async function ensureFleetParent(exec = realExec, platform = process.platform) {
+    const host = fleetHostBackend(exec, platform);
+    const path = platform === 'linux' ? join(home(), '.config/systemd/user/ours-fleet.service')
+        : join(home(), 'Library/LaunchAgents/network.ours.fleet.plist');
+    if (!existsSync(path))
+        throw Error('FLEET_SERVICE_NOT_INSTALLED: run ours-fleet init');
+    const live = await host.liveness('fleet');
+    if (live.state === 'unknown')
+        throw Error('FLEET_SERVICE_LIVENESS_UNKNOWN');
+    if (live.state === 'stopped')
+        await host.install('fleet', '');
+}
+/** OS operations refer only to the Fleet parent; member operations refer only to its catalog. */
+export function makeFleetBackend(exec = realExec, platform = process.platform) {
+    const host = fleetHostBackend(exec, platform);
+    return {
+        id: host.id,
+        async init(binPath) {
+            const messages = await host.init(binPath);
+            const { adoptConfiguredFleet } = await import('./adoption.js');
+            await adoptConfiguredFleet(binPath, exec, platform);
+            return messages;
+        },
+        async install(name, binPath) {
+            const { adoptConfiguredFleet } = await import('./adoption.js');
+            let configPath;
+            try {
+                configPath = readFileSync(join(agentDir(name), '.config-path'), 'utf8').trim() || undefined;
+            }
+            catch { /* a new state directory may not carry a config marker yet */ }
+            await adoptConfiguredFleet(binPath, exec, platform, configPath, name);
+            const result = await registerMember({ name, kind: 'permanent', dir: agentDir(name) });
+            try {
+                await waitMember(result.member.key, 'running', { exec });
+            }
+            catch (error) {
+                // Preserve existing intent. New registration rollback is exact and waits
+                // for process quiescence before its creation evidence can be discarded.
+                if (result.created)
+                    await unregisterMember(result.member.key, { exec });
+                throw error;
+            }
+            return { created: result.created, detail: `Fleet member ${name} registered` };
+        },
+        async start(name) {
+            const key = memberKey(name, 'permanent'), member = readMember(key);
+            if (!member)
+                throw Error('Fleet member not registered; use up');
+            await registerMember(member);
+            await ensureFleetParent(exec, platform);
+            await waitMember(key, 'running', { exec });
+        },
+        async stop(name) { await stopMember(memberKey(name, 'permanent'), { exec }); },
+        async restart(name) {
+            await this.stop(name);
+            await this.start(name);
+        },
+        async status(name) { return (await this.liveness(name)).detail; },
+        liveness(name) {
+            const key = memberKey(name, 'permanent');
+            if (!readMember(key) && existsSync(agentDir(name)))
+                return Promise.resolve({ state: 'unknown', detail: 'unmigrated member; preserving context until legacy inspection' });
+            return catalogLiveness(key, exec);
+        },
+        async inspect(name) { return { backend: host.id, ...await this.liveness(name), nativeState: 'fleet-member' }; },
+        async uninstall(name) {
+            const { retirePermanentRegistration } = await import('./adoption.js');
+            return { removed: await retirePermanentRegistration(name, exec), detail: `Fleet member ${name} unregistered` };
+        },
+        logsArgs(name, follow) { return { cmd: 'tail', args: [follow ? '-f' : '-n', ...(follow ? [] : ['200']), join(agentDir(name), 'supervisor.log')] }; },
+    };
+}

package/dist/supervisor/index.js

@@ -1,6 +1,5 @@
 import { realExec } from '../exec.js';
-import { makeSystemdBackend } from './systemd.js';
-import { makeLaunchdBackend } from './launchd.js';
+import { makeFleetBackend } from './fleet.js';
 import { makeNoneBackend } from './none.js';
 export { makeSystemdBackend, unitFor } from './systemd.js';
 export { makeLaunchdBackend, labelFor } from './launchd.js';
@@ -8,9 +7,7 @@ export { makeNoneBackend } from './none.js';
 export function pickBackend(exec = realExec, platform = process.platform) {
     if (process.env.OURS_FLEET_SUPERVISOR === 'none')
         return makeNoneBackend(exec);
-    if (platform === 'darwin')
-        return makeLaunchdBackend(exec);
-    if (platform === 'linux')
-        return makeSystemdBackend(exec);
+    if (platform === 'darwin' || platform === 'linux')
+        return makeFleetBackend(exec, platform);
     throw new Error(`unsupported platform '${platform}' (linux and darwin only)`);
 }

package/dist/supervisor/launchd.d.ts

@@ -1,6 +1,6 @@
 import { type Exec } from '../exec.js';
 import type { SupervisorBackend } from './types.js';
-export declare const labelFor: (name: string) => string;
+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:

package/dist/supervisor/launchd.js

@@ -1,8 +1,10 @@
+import { assertNativeFleetScope } from './scope.js';
+import { clientConfigPath } from '../client-profile.js';
 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}`;
+export const labelFor = (_name) => 'network.ours.fleet';
 /**
  * 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
@@ -21,16 +23,17 @@ const xml = (value) => value
     .replaceAll('"', '"')
     .replaceAll("'", ''');
 function plist(name, binPath) {
-    const log = join(logsRoot(), `${name}.log`);
-    const config = process.env.OURS_CONFIG;
+    const log = join(logsRoot(), 'fleet.log');
+    const config = clientConfigPath(process.env);
+    const env = { OURS_CONFIG: config, ...Object.fromEntries(['PATH', 'OURS_FLEET_HOME', 'OURS_FLEET_SOCKET_ROOT', 'CODEX_HOME', 'CODEX_PATH'].flatMap(key => process.env[key] !== undefined ? [[key, process.env[key]]] : [])) };
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
   <key>Label</key><string>${labelFor(name)}</string>
   <key>ProgramArguments</key>
-  <array><string>${binPath}</string><string>_run</string><string>${name}</string></array>
-${config ? `  <key>EnvironmentVariables</key><dict><key>OURS_CONFIG</key><string>${xml(config)}</string></dict>\n` : ''}  <!-- The runner owns the child-session restart loop. launchd must only
+  <array><string>${xml(process.execPath)}</string><string>${xml(binPath)}</string><string>_run-fleet</string></array>
+${`  <key>EnvironmentVariables</key><dict>${Object.entries(env).map(([key, value]) => `<key>${key}</key><string>${xml(value)}</string>`).join('')}</dict>\n`}  <!-- The runner owns the child-session restart loop. 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>
@@ -79,6 +82,7 @@ export function makeLaunchdBackend(exec = realExec, uid = process.getuid?.() ??
     const domain = `gui/${uid}`;
     /** Read `launchctl print` once; both callers classify it for their own question. */
     const printJob = async (name) => {
+        assertNativeFleetScope(exec);
         const r = await exec('launchctl', ['print', `${domain}/${labelFor(name)}`]);
         const out = `${r.stdout}\n${r.stderr}`;
         if (r.code !== 0)
@@ -96,21 +100,26 @@ export function makeLaunchdBackend(exec = realExec, uid = process.getuid?.() ??
     };
     return {
         id: 'launchd',
-        async init() {
+        async init(binPath) {
+            assertNativeFleetScope(exec);
             mkdirSync(agentsDir(), { recursive: true });
             mkdirSync(logsRoot(), { recursive: true });
+            writeFileSync(plistPath('fleet'), plist('fleet', binPath));
             return [
                 `LaunchAgents dir ready: ${agentsDir()}`,
                 'note: launchd agents start at login (macOS has no linger equivalent)',
             ];
         },
         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
+            assertNativeFleetScope(exec);
+            if (!existsSync(plistPath(name)))
+                throw Error('FLEET_SERVICE_NOT_INSTALLED: run ours-fleet init');
+            const existed = true;
+            const loaded = await printJob(name);
+            if (loaded.loaded)
+                return { created: !existed, detail: 'Fleet service already loaded' };
+            if (!loaded.notFound)
+                throw new Error('Fleet launchd liveness unknown');
             // Undo only what WE wrote. A plist that was already there belongs to
             // whoever put it there, and rollback may never remove it.
             const undo = async () => {
@@ -153,16 +162,19 @@ export function makeLaunchdBackend(exec = realExec, uid = process.getuid?.() ??
                 : { created: true, detail: `installed ${labelFor(name)} (${start.detail})` };
         },
         async start(name) {
+            assertNativeFleetScope(exec);
             const r = await exec('launchctl', ['bootstrap', domain, plistPath(name)]);
             if (r.code !== 0)
                 await exec('launchctl', ['kickstart', `${domain}/${labelFor(name)}`]);
         },
         async stop(name) {
+            assertNativeFleetScope(exec);
             const r = await exec('launchctl', ['bootout', `${domain}/${labelFor(name)}`]);
             if (r.code !== 0)
                 throw new Error(`launchctl bootout ${labelFor(name)} failed: ${r.stderr.trim()}`);
         },
         async restart(name) {
+            assertNativeFleetScope(exec);
             const r = await exec('launchctl', ['kickstart', '-k', `${domain}/${labelFor(name)}`]);
             if (r.code !== 0)
                 throw new Error(`launchctl kickstart ${labelFor(name)} failed: ${r.stderr.trim()}`);
@@ -202,6 +214,7 @@ export function makeLaunchdBackend(exec = realExec, uid = process.getuid?.() ??
             };
         },
         async uninstall(name) {
+            assertNativeFleetScope(exec);
             const existed = existsSync(plistPath(name));
             await exec('launchctl', ['bootout', `${domain}/${labelFor(name)}`]); // idempotent
             rmSync(plistPath(name), { force: true });
@@ -210,7 +223,7 @@ export function makeLaunchdBackend(exec = realExec, uid = process.getuid?.() ??
                 : { removed: false, detail: `${labelFor(name)} was not installed` };
         },
         logsArgs(name, follow) {
-            const log = join(logsRoot(), `${name}.log`);
+            const log = join(logsRoot(), 'fleet.log');
             return { cmd: 'tail', args: follow ? ['-f', log] : ['-n', '200', log] };
         },
     };

package/dist/supervisor/legacy.d.ts

@@ -0,0 +1,35 @@
+import { type Exec } from '../exec.js';
+import type { ResolvedRole } from '../config.js';
+type Desired = 'running' | 'stopped';
+export interface LegacyReadinessGate {
+    path: string;
+    argv: string[];
+    timeoutStartSec: number;
+    restartSec: number;
+}
+export interface LegacyPermanentMigrationInput {
+    roles: Pick<ResolvedRole, 'name' | 'identity'>[];
+    binPath: string;
+    platform: NodeJS.Platform;
+    configPath?: string;
+    exec?: Exec;
+    /** All-role preflight precedes this hook. Ensure the singleton is running and
+     * preserves every gate before returning; failure prevents native retirement. */
+    prepareParent(gates: LegacyReadinessGate[]): Promise<void>;
+    /** Isolated process-environment seam; production reads only OURS_FLEET_HOME. */
+    processHome?(pid: number): string;
+    /** Create if absent; an existing registration's desired state must survive retry. */
+    register(name: string, desired: Desired, configPath?: string): Promise<void>;
+}
+export interface LegacyPermanentMigrationResult {
+    name: string;
+    status: 'migrated' | 'already-migrated' | 'not-installed' | 'disabled';
+}
+/** Start the common parent after all-role preflight and before retirement. Only configured,
+ * identity-proven legacy registrations transfer; no identity/session writes.
+ * A receipt survives removal of the old native job and preserves its original
+ * running/stopped intent across retries. Native services are never inferred
+ * from role names alone. Uncertain or conflicting proof fails closed.
+ */
+export declare function migrateLegacyPermanentMembers(input: LegacyPermanentMigrationInput): Promise<LegacyPermanentMigrationResult[]>;
+export {};