@ours.network/fleet 1.2.0-nightly.7 → 1.2.0-nightly.70

package/dist/subscriptions/store.js

@@ -0,0 +1,140 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, symlinkSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { replaceFileAtomically, withFileLock } from '../atomic-file.js';
+import { FleetError } from '../application/errors.js';
+import { homedir } from 'node:os';
+import { stateRoot } from '../paths.js';
+export const SUBSCRIPTION_PROVIDERS = ['claude', 'codex'];
+export const DEFAULT_PROFILE_ID = 'default';
+export const PIN_FILE = '.subscription-pin.json';
+export const OBSERVED_USAGE_FILE = '.subscription-usage.json';
+/** Non-history configuration shared from the base home into each new profile. */
+const SHARED_CONFIG = {
+    claude: ['settings.json', 'CLAUDE.md', 'plugins', 'skills', 'agents', 'commands'],
+    codex: ['config.toml', 'AGENTS.md', 'plugins', 'skills', 'rules'],
+};
+export const PROFILE_ID_RE = /^[a-z0-9][a-z0-9-]{0,40}$/;
+export const subscriptionsRoot = () => join(stateRoot(), 'subscriptions');
+const stateFile = () => join(subscriptionsRoot(), 'state.json');
+const lockPath = () => join(subscriptionsRoot(), '.lock');
+/**
+ * The CLI's own default home, adopted as the `default` profile. This follows
+ * `$HOME` like the CLIs do, not OURS_FLEET_HOME (which may relocate Fleet state).
+ */
+export const baseHome = (provider) => join(homedir(), provider === 'claude' ? '.claude' : '.codex');
+export function isProvider(value) {
+    return value === 'claude' || value === 'codex';
+}
+export function profileHome(provider, profileId) {
+    if (profileId === DEFAULT_PROFILE_ID)
+        return baseHome(provider);
+    if (!PROFILE_ID_RE.test(profileId))
+        throw new FleetError('invalid_request', 'invalid profile id');
+    return join(subscriptionsRoot(), provider, profileId);
+}
+function initialState() {
+    const provider = () => ({
+        activeProfileId: DEFAULT_PROFILE_ID,
+        profiles: [{ id: DEFAULT_PROFILE_ID, label: 'Default (existing login)', createdAt: new Date(0).toISOString() }],
+    });
+    return { version: 1, providers: { claude: provider(), codex: provider() } };
+}
+/**
+ * Read the state. The file is only ever replaced by an atomic rename, so a
+ * reader (including a launching agent) sees either the old or the new active
+ * profile, never a torn write.
+ */
+export function readSubscriptionState() {
+    let text;
+    try {
+        text = readFileSync(stateFile(), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return initialState();
+        throw unreadable();
+    }
+    // Fail closed: a damaged state file must not silently move launches to another account.
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw unreadable();
+    }
+    const state = initialState();
+    const providers = raw?.providers;
+    if (!providers || typeof providers !== 'object')
+        throw unreadable();
+    for (const provider of SUBSCRIPTION_PROVIDERS) {
+        const p = providers[provider];
+        if (!p || !Array.isArray(p.profiles) || typeof p.activeProfileId !== 'string')
+            throw unreadable();
+        const profiles = p.profiles;
+        if (profiles.some(x => !x || typeof x.id !== 'string' || (x.id !== DEFAULT_PROFILE_ID && !PROFILE_ID_RE.test(x.id))))
+            throw unreadable();
+        if (!profiles.some(x => x.id === DEFAULT_PROFILE_ID))
+            profiles.unshift(state.providers[provider].profiles[0]);
+        if (!profiles.some(x => x.id === p.activeProfileId))
+            throw unreadable();
+        const active = p.activeProfileId;
+        state.providers[provider] = {
+            activeProfileId: active,
+            profiles: profiles.map(x => ({ id: x.id, label: String(x.label ?? x.id).slice(0, 80), createdAt: String(x.createdAt ?? '') })),
+        };
+    }
+    return state;
+}
+const unreadable = () => new FleetError('prerequisite_unavailable', `subscription state ${stateFile()} is unreadable or invalid; fix or remove it before starting agents`);
+/** Serialised read-modify-write of the state under a cross-process lock. */
+export async function updateSubscriptionState(fn) {
+    mkdirSync(subscriptionsRoot(), { recursive: true, mode: 0o700 });
+    return withFileLock(lockPath(), () => {
+        const state = readSubscriptionState();
+        const result = fn(state);
+        replaceFileAtomically(stateFile(), `${JSON.stringify(state, null, 2)}\n`, 0o600);
+        return result;
+    });
+}
+/**
+ * Create an empty profile home (not yet registered). Shared, non-history
+ * configuration is symlinked from the base home; credentials and session
+ * history stay per profile.
+ */
+export function createProfileHome(provider) {
+    const id = `p-${randomBytes(6).toString('hex')}`;
+    const dir = profileHome(provider, id);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const base = baseHome(provider);
+    for (const name of SHARED_CONFIG[provider]) {
+        const src = join(base, name);
+        if (existsSync(src)) {
+            try {
+                symlinkSync(src, join(dir, name));
+            }
+            catch { /* optional convenience */ }
+        }
+    }
+    return { id, home: dir };
+}
+/** Remove a non-default profile home. Never touches the adopted default. */
+export function removeProfileHome(provider, profileId) {
+    if (profileId === DEFAULT_PROFILE_ID)
+        return;
+    rmSync(profileHome(provider, profileId), { recursive: true, force: true });
+}
+export function readPin(stateDir, provider) {
+    try {
+        const pin = JSON.parse(readFileSync(join(stateDir, PIN_FILE), 'utf8'));
+        if (provider)
+            return pin[provider];
+        return Object.values(pin)[0];
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writePin(stateDir, pin) {
+    replaceFileAtomically(join(stateDir, PIN_FILE), `${JSON.stringify({ [pin.provider]: pin })}\n`, 0o600);
+}

package/dist/supervisor/adoption.d.ts

@@ -0,0 +1,8 @@
+import { type Exec } from '../exec.js';
+export declare function adoptConfiguredFleet(binPath: string, exec: Exec, platform: NodeJS.Platform, configPath?: string, selectedRole?: string): Promise<void>;
+/** Boot resumes recorded transfers only. It does not rediscover removed agents
+ * or decide that every configured role should be started. */
+export declare function resumeFleetTransfers(binPath: string, exec?: Exec, platform?: NodeJS.Platform): Promise<void>;
+/** A remove racing the native-retired → registered seam must not be undone by
+ * boot receipt recovery. Serialize with that seam and close its cursor first. */
+export declare function retirePermanentRegistration(name: string, exec: Exec): Promise<boolean>;

package/dist/supervisor/adoption.js

@@ -0,0 +1,78 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { agentDir, defaultConfigPath, stateRoot } from '../paths.js';
+import { replaceFileAtomically, withFileLock } from '../atomic-file.js';
+import { loadConfig, findRole } from '../config.js';
+import { realExec } from '../exec.js';
+import { readMember, memberKey, unregisterMember, registerMember } from './catalog.js';
+import { migrateLegacyPermanentMembers } from './legacy.js';
+import { ensureFleetParent } from './fleet.js';
+export async function adoptConfiguredFleet(binPath, exec, platform, configPath, selectedRole) {
+    const path = configPath || defaultConfigPath();
+    if (existsSync(path)) {
+        const config = loadConfig(path);
+        await migrateLegacyPermanentMembers({
+            roles: selectedRole ? [findRole(config, selectedRole)] : config.roles, binPath, configPath: path, exec, platform,
+            prepareParent: () => ensureFleetParent(exec, platform),
+            register: async (name, desired, selectedConfig) => {
+                await registerMember({ name, kind: 'permanent', dir: agentDir(name), configPath: selectedConfig }, { initialDesired: desired, preserveExisting: true });
+            },
+        });
+    }
+    else
+        await ensureFleetParent(exec, platform);
+}
+/** Boot resumes recorded transfers only. It does not rediscover removed agents
+ * or decide that every configured role should be started. */
+export async function resumeFleetTransfers(binPath, exec = realExec, platform = process.platform) {
+    const root = join(stateRoot(), 'supervisor/legacy-permanent');
+    let names;
+    try {
+        names = readdirSync(root).filter(name => name.endsWith('.json'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            names = [];
+        else
+            throw error;
+    }
+    for (const name of names) {
+        const path = join(root, name), stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 256 * 1024)
+            throw Error('LEGACY_PERMANENT_UNSAFE_PROOF');
+        const receipt = JSON.parse(readFileSync(path, 'utf8'));
+        if (receipt.phase === 'registered')
+            continue;
+        if (name !== receipt.name + '.json')
+            throw Error('LEGACY_PERMANENT_RECEIPT_MISMATCH');
+        const configPath = receipt.configPath || defaultConfigPath();
+        const role = findRole(loadConfig(configPath), receipt.name);
+        await migrateLegacyPermanentMembers({
+            roles: [role], binPath, configPath, exec, platform,
+            // This runs inside the parent. No recursive OS start, unit writes or reload.
+            prepareParent: async () => { },
+            register: async (name, desired, selectedConfig) => {
+                await registerMember({ name, kind: 'permanent', dir: agentDir(name), configPath: selectedConfig }, { initialDesired: desired, preserveExisting: true });
+            },
+        });
+    }
+}
+/** A remove racing the native-retired → registered seam must not be undone by
+ * boot receipt recovery. Serialize with that seam and close its cursor first. */
+export async function retirePermanentRegistration(name, exec) {
+    memberKey(name, 'permanent');
+    return withFileLock(join(stateRoot(), 'locks/legacy-permanent', name), async () => {
+        const member = readMember(memberKey(name, 'permanent'));
+        const path = join(stateRoot(), 'supervisor/legacy-permanent', name + '.json');
+        if (member && existsSync(path)) {
+            const stat = lstatSync(path);
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 256 * 1024)
+                throw Error('LEGACY_PERMANENT_UNSAFE_PROOF');
+            const receipt = JSON.parse(readFileSync(path, 'utf8'));
+            if (receipt.version !== 1 || receipt.name !== name || !['native-retired', 'registered'].includes(receipt.phase))
+                throw Error('LEGACY_PERMANENT_RECEIPT_MISMATCH');
+            replaceFileAtomically(path, JSON.stringify({ ...receipt, phase: 'registered' }) + '\n');
+        }
+        return unregisterMember(memberKey(name, 'permanent'), { exec });
+    });
+}

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)`);
 }