@ours.network/fleet 1.2.0-nightly.53 → 1.2.0-nightly.55

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,9 +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
@@ -22,16 +23,17 @@ const xml = (value) => value
     .replaceAll('"', '"')
     .replaceAll("'", ''');
 function plist(name, binPath) {
-    const log = join(logsRoot(), `${name}.log`);
+    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>
@@ -80,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)
@@ -97,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 () => {
@@ -154,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()}`);
@@ -203,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 });
@@ -211,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 {};