@ours.network/fleet 1.2.0-nightly.54 → 1.2.0-nightly.56

package/dist/supervisor/manager.js

@@ -0,0 +1,258 @@
+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 { 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);
+        }
+    });
+    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 { 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;
+        // 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/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.

package/dist/supervisor/systemd.js

@@ -1,10 +1,11 @@
+import { assertNativeFleetScope } from './scope.js';
 import { clientConfigPath } from '../client-profile.js';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { delimiter, dirname, join } from 'node:path';
 import { userInfo } from 'node:os';
 import { home } from '../paths.js';
 import { realExec } from '../exec.js';
-export const UNIT_TEMPLATE = 'ours-fleet-agent@.service';
+export 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
@@ -15,7 +16,7 @@ export const busHint = (stderr) => /user scope bus|XDG_RUNTIME_DIR/.test(stderr)
     ? `\nhint: no user runtime dir — enable linger: sudo loginctl enable-linger ${userInfo().username}` +
         `\n      (if linger is already on: export XDG_RUNTIME_DIR=/run/user/$(id -u))`
     : '';
-export const unitFor = (name) => `ours-fleet-agent@${name}.service`;
+export const unitFor = (_name) => UNIT_TEMPLATE;
 /** Quote a systemd unit argument and escape its specifier marker. */
 const unitArg = (value) => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%')}"`;
 /**
@@ -57,10 +58,11 @@ async function probeLiveness(ctl, name) {
     };
 }
 export function makeSystemdBackend(exec = realExec) {
-    const ctl = (...args) => exec('systemctl', ['--user', ...args]);
+    const ctl = (...args) => { assertNativeFleetScope(exec); return exec('systemctl', ['--user', ...args]); };
     return {
         id: 'systemd',
         async init(binPath) {
+            assertNativeFleetScope(exec);
             const msgs = [];
             const unitDir = join(home(), '.config', 'systemd', 'user');
             // Lingering user units often start before a login shell imports its PATH.
@@ -74,30 +76,28 @@ export function makeSystemdBackend(exec = realExec) {
             // are picked up by every fresh process, including lingering user services.
             const unitEnv = ['PATH=' + servicePath];
             unitEnv.push('OURS_CONFIG=' + clientConfigPath(process.env));
+            for (const key of ['OURS_FLEET_HOME', 'OURS_FLEET_SOCKET_ROOT', 'CODEX_HOME', 'CODEX_PATH']) {
+                if (process.env[key] !== undefined)
+                    unitEnv.push(key + '=' + process.env[key]);
+            }
             const environmentLines = unitEnv
                 .map(value => `Environment="${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%')}"`)
                 .join('\n');
             mkdirSync(unitDir, { recursive: true });
             writeFileSync(join(unitDir, UNIT_TEMPLATE), `[Unit]
-Description=ours-fleet agent %i
+Description=ours-fleet process manager
 After=default.target
 StartLimitIntervalSec=0
 
 [Service]
 Type=simple
 ${environmentLines}
-# Wait outside the runner so boot-time daemon unavailability cannot consume
-# the agent crash budget. Selection comes from the same role and profile.
-ExecStartPre=${unitArg(process.execPath)} ${unitArg(binPath)} _wait-daemon %i
-TimeoutStartSec=270
-ExecStart=${unitArg(process.execPath)} ${unitArg(binPath)} _run %i
-# The RUNNER owns the child-session restart loop, with a counted, backed-off
-# circuit breaker. systemd must only recover the runner PROCESS crashing —
-# Restart=always here would resume the uncounted two-second relaunch loop, and
-# would also restart a runner that is deliberately holding a failing agent down.
+ExecStart=${unitArg(process.execPath)} ${unitArg(binPath)} _run-fleet
+# Fleet owns agent startup and restart; the OS recovers only the Fleet parent.
+KillMode=control-group
 Restart=on-failure
 RestartSec=5
-TimeoutStopSec=15
+TimeoutStopSec=25
 
 [Install]
 WantedBy=default.target

package/dist/task-supervision.d.ts

@@ -0,0 +1,9 @@
+/** Read-only ownership fence: absence/mismatch never permits a new identity or launch. */
+export declare function taskSupervisorMayRun(name: string): boolean;
+/** Resolve the externally recorded CID/action for explicit terminal retirement.
+ * Run only after the same launch passed taskSupervisorMayRun's ownership fence.
+ * An unpublished failed launch stays for its seat's retry/retirement saga. */
+export declare function taskMemberRetirementProof(name: string): {
+    cid: string;
+    action: string;
+};

package/dist/task-supervision.js

@@ -0,0 +1,145 @@
+import { readFileSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'yaml';
+import { agentDir, stateRoot } from './paths.js';
+import { readTempSupervisor } from './temp-lifecycle.js';
+import { createHash } from 'node:crypto';
+import { readProvenance } from './creation.js';
+import { getTask } from './rooms-tasks/task-state.js';
+import { getRoomRecord } from './rooms-tasks/room-state.js';
+import { assertWorkspacePresent } from './rooms-tasks/workspace.js';
+import { privateRuntimeRoot } from './agent-ours/service.js';
+import { binderKey, RuntimeJournal } from './agent-ours/state.js';
+import { assertMemberNotPermanent } from './rooms-tasks/member-ownership.js';
+import { readClientProfile } from './client-profile.js';
+import { firstManagedSessionMayStart } from './managed-recovery.js';
+function readProof(path) {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 256 * 1024)
+        throw Error('TASK_SUPERVISOR_UNSAFE_PROOF');
+    return readFileSync(path, 'utf8');
+}
+/** An admitted task member must resume its retained instance, never allocate a successor. */
+function assertRetainedRuntime(role, action, cid, launch, session) {
+    const profile = readClientProfile({ ...process.env, ...role.env });
+    if (!profile)
+        throw Error('TASK_RUNTIME_PROFILE_MISSING');
+    const dir = join(privateRuntimeRoot(), binderKey(profile.expectedInstanceId, role.identity));
+    const instance = JSON.parse(readProof(join(dir, 'instance.json')));
+    const owner = JSON.parse(readProof(join(dir, 'owner.json')));
+    const pin = JSON.parse(readProof(join(dir, 'identity-pin.json')));
+    readProof(join(dir, 'state.json'));
+    const state = new RuntimeJournal(dir).read();
+    const creation = JSON.parse(readProof(join(privateRuntimeRoot(), 'launches', binderKey('temporary', role.name) + '.json')));
+    const sessionDir = agentDir(role.name, true);
+    let retainedSession = '';
+    try {
+        retainedSession = readProof(join(sessionDir, role.session === 'codex-app-server' ? '.session-id' : '.acp-session-id')).trim();
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT' || session || !firstManagedSessionMayStart(sessionDir))
+            throw error;
+    }
+    readProof(join(sessionDir, '.booted')); // presence is the runner's resume marker, including legacy empty files
+    if (creation.role !== role.name || creation.identity !== role.identity || creation.action !== action
+        || !state || instance.role !== role.name || instance.temporary !== true || !instance.instance
+        || owner.instance !== instance.instance || typeof owner.token !== 'string' || !owner.token
+        || pin.daemon !== profile.expectedInstanceId || pin.name !== role.identity || pin.cid !== cid
+        || state.daemon !== profile.expectedInstanceId || state.name !== role.identity || state.cid !== cid
+        || state.instance !== instance.instance || state.lifetime !== 'temporary' || state.action !== action
+        || ['QUIESCING', 'TERMINAL_INTENT', 'RELEASED', 'CLEANUP_PENDING', 'FAILED'].includes(state.phase)
+        || (!retainedSession && !firstManagedSessionMayStart(sessionDir)) || (launch && launch !== instance.instance) || (session && session !== retainedSession))
+        throw Error('TASK_RETAINED_RUNTIME_MISMATCH');
+}
+/** Read-only ownership fence: absence/mismatch never permits a new identity or launch. */
+export function taskSupervisorMayRun(name) {
+    assertMemberNotPermanent(name);
+    const dir = agentDir(name, true);
+    readProof(join(dir, '.temp-supervisor.json'));
+    readProof(join(dir, 'creation.json'));
+    const supervisor = readTempSupervisor(dir), owner = supervisor?.taskOwner;
+    if (!owner || supervisor.role !== name || !owner.taskId || !owner.creationActionId)
+        throw Error('TASK_SUPERVISOR_OWNER_MISSING');
+    const role = parse(readProof(join(dir, 'role.yaml')));
+    const startup = role.roomMemberStartup, provenance = readProvenance(dir);
+    const task = getTask(owner.taskId);
+    if (role.name !== name || role.identity !== name || provenance?.role !== name
+        || provenance.creationActionId !== owner.creationActionId)
+        throw Error('TASK_SUPERVISOR_OWNERSHIP_MISMATCH');
+    if (!task.deletion && !task.terminal_intent && ['provisioning', 'active', 'review'].includes(task.state) && task.workspace) {
+        if (role.cwd !== task.workspace.path)
+            throw Error('TASK_WORKSPACE_MISMATCH');
+        assertWorkspacePresent(task.workspace, 'task', task.task_id);
+    }
+    if (owner.layout) {
+        const { runId, participant } = owner.layout;
+        const expectedName = `layout-${createHash('sha256').update(runId + ':' + participant).digest('hex').slice(0, 16)}`;
+        if (!task.layout || task.layout.run_id !== runId || runId !== `task-${owner.taskId}`
+            || !/^[A-Za-z0-9_-]+$/.test(runId) || expectedName !== name
+            || owner.creationActionId !== `${runId}:${participant}`)
+            throw Error('TASK_LAYOUT_OWNER_MISMATCH');
+        const state = JSON.parse(readProof(join(stateRoot(), 'layouts', `${runId}.json`)));
+        const member = state.participants[participant];
+        if (!member?.owned || member.instance?.remote || (member.instance?.agent && member.instance.agent !== name)
+            || (member.instance && member.instance.temporary !== true))
+            throw Error('TASK_LAYOUT_PARTICIPANT_MISMATCH');
+        if (task.deletion || task.terminal_intent || state.closed || state.closing || member.retired
+            || !['provisioning', 'active', 'review'].includes(task.state))
+            return false;
+        if (member.instance)
+            assertRetainedRuntime(role, owner.creationActionId, member.instance.cid, member.instance.launch, member.instance.session);
+        return true;
+    }
+    if (!owner.roomId || !owner.roomIdentityCid)
+        throw Error('TASK_SUPERVISOR_OWNER_MISSING');
+    const room = getRoomRecord(owner.roomId);
+    const seat = room?.member_seats.find(member => member.role_name === name);
+    if (!task || !room || room.task_id !== task.task_id || room.room_identity_cid !== owner.roomIdentityCid
+        || (task.room_id !== undefined && task.room_id !== owner.roomId)
+        || (task.room_identity_cid !== undefined && task.room_identity_cid !== owner.roomIdentityCid)
+        || role.name !== name || role.identity !== name || startup?.task_id !== owner.taskId
+        || startup.room_id !== owner.roomId || startup.room_identity_cid !== owner.roomIdentityCid
+        || startup.identity_name !== name || !seat || seat.invite_id !== startup.invite_id
+        || seat.cowork_role !== startup.role || provenance?.role !== name
+        || provenance.creationActionId !== owner.creationActionId
+        || seat.launch?.action_id !== owner.creationActionId
+        || (seat.launch.launch_id !== undefined && seat.launch.launch_id !== supervisor.launchId))
+        throw Error('TASK_SUPERVISOR_OWNERSHIP_MISMATCH');
+    if (task.deletion || task.terminal_intent || room.close || seat.retirement
+        || !['provisioning', 'active', 'review'].includes(task.state)
+        || !['provisioning', 'active'].includes(room.state))
+        return false;
+    if (task.workspace && (role.cwd !== task.workspace.path
+        || JSON.stringify(startup.workspace) !== JSON.stringify(task.workspace)
+        || JSON.stringify(room.workspace) !== JSON.stringify(task.workspace)))
+        throw Error('TASK_WORKSPACE_MISMATCH');
+    if (seat.identity_cid)
+        assertRetainedRuntime(role, owner.creationActionId, seat.identity_cid);
+    return true;
+}
+/** Resolve the externally recorded CID/action for explicit terminal retirement.
+ * Run only after the same launch passed taskSupervisorMayRun's ownership fence.
+ * An unpublished failed launch stays for its seat's retry/retirement saga. */
+export function taskMemberRetirementProof(name) {
+    const dir = agentDir(name, true), metadata = readTempSupervisor(dir), owner = metadata?.taskOwner;
+    if (!owner || metadata.role !== name)
+        throw Error('TASK_SUPERVISOR_OWNER_MISSING');
+    let cid;
+    if (owner.layout) {
+        const state = JSON.parse(readProof(join(stateRoot(), 'layouts', `${owner.layout.runId}.json`)));
+        const participant = state.participants[owner.layout.participant];
+        if (!participant?.owned || participant.instance?.agent !== name || participant.instance?.remote
+            || participant.instance?.temporary !== true)
+            throw Error('TASK_LAYOUT_PARTICIPANT_MISMATCH');
+        cid = participant.instance.cid;
+    }
+    else {
+        const seat = owner.roomId && getRoomRecord(owner.roomId)?.member_seats.find(member => member.role_name === name);
+        if (!seat || seat.launch?.action_id !== owner.creationActionId || seat.launch.launch_id !== metadata.launchId)
+            throw Error('TASK_SUPERVISOR_OWNERSHIP_MISMATCH');
+        cid = seat.identity_cid;
+    }
+    if (!cid)
+        throw Error('TASK_MEMBER_RETIREMENT_CID_MISSING');
+    return { cid, action: owner.creationActionId };
+}

package/dist/temp-lifecycle.d.ts

@@ -4,8 +4,18 @@ export declare const TEMP_TERMINATION_FILE = "termination.jsonl";
 export declare const TEMP_STOP_REQUEST_FILE = ".temp-stop-request.json";
 export declare const TEMP_RECLAIM_BATCH = 32;
 export declare const TEMP_LAUNCH_GRACE_MS = 60000;
-export type TempSupervisorKind = 'systemd-transient' | 'launchd-transient' | 'detached';
+export type TempSupervisorKind = 'fleet-managed' | 'systemd-transient' | 'launchd-transient' | 'detached';
 export type TempTerminationReason = 'idle-timeout' | 'identity-closed' | 'session-ended' | 'operator-stop' | 'supervisor-signal' | 'supervisor-recycle' | 'startup-failure' | 'stale-supervisor';
+export interface TaskSupervisorOwner {
+    taskId: string;
+    roomId?: string;
+    roomIdentityCid?: string;
+    layout?: {
+        runId: string;
+        participant: string;
+    };
+    creationActionId: string;
+}
 export interface TempSupervisorRecord {
     version: 1;
     role: string;
@@ -16,6 +26,7 @@ export interface TempSupervisorRecord {
     target?: string;
     pid?: number;
     binPath?: string;
+    taskOwner?: TaskSupervisorOwner;
 }
 export interface TempTerminationRecord {
     version: 1;
@@ -29,13 +40,12 @@ export interface TempTerminationRecord {
 export type SupervisorLauncher = (binPath: string, args: string[], dir: string) => void | Promise<void>;
 export declare const tempSystemdUnit: (name: string) => string;
 export declare const tempLaunchdLabel: (name: string) => string;
-export declare function prepareTempSupervisor(dir: string, role: string): TempSupervisorRecord;
+export declare function prepareTempSupervisor(dir: string, role: string, taskOwner?: TaskSupervisorOwner): TempSupervisorRecord;
 export declare function readTempSupervisor(dir: string): TempSupervisorRecord | undefined;
-/**
- * Launch a temp supervisor outside the caller's service-manager ownership
- * boundary. `detached: true` creates a new process group but does not escape a
- * systemd cgroup; a transient unit does, and is not enabled across reboot.
- */
+/** Broad scans retain unsupported entries instead of blocking other members. */
+export declare function readTempSupervisorForScan(dir: string): TempSupervisorRecord | undefined;
+export declare function updateTempSupervisor(dir: string, update: Partial<Omit<TempSupervisorRecord, 'version' | 'role' | 'launchId' | 'createdAt'>>): Promise<TempSupervisorRecord | undefined>;
+/** Register managed members under Fleet; explicit manual mode uses a detached child. */
 export declare function makeTempSupervisorLauncher(options?: {
     exec?: Exec;
     platform?: NodeJS.Platform;