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

package/dist/session/arbiter.d.ts

@@ -54,6 +54,11 @@ export declare class RoleTurnArbiter implements AgentSession {
      */
     retireStalledAdmission(): void;
     queuePrompt(text: string, options?: SubmitPromptOptions): Promise<QueuedPrompt>;
+    /** Inbox traffic must not cancel or steer an active human console/voice turn.
+     * Queue it once; the monitor commits its cursor after that turn succeeds.
+     * Other origins retain their configured monitor policy.
+     */
+    private monitorAdmissionOptions;
     submitPrompt(text: string, options?: SubmitPromptOptions): Promise<TurnResult>;
     /**
      * Do not hold `exclusive` while ACP waits for a tool boundary: permission

package/dist/session/arbiter.js

@@ -90,8 +90,20 @@ export class RoleTurnArbiter {
         retired.retire();
     }
     queuePrompt(text, options = {}) {
-        return this.exclusive(async () => { if (this.retiring)
-            throw new Error('Chat is closing'); return this.track(await this.session.queuePrompt(text, options)); });
+        return this.exclusive(async () => {
+            if (this.retiring)
+                throw new Error('Chat is closing');
+            return this.track(await this.session.queuePrompt(text, this.monitorAdmissionOptions(options)));
+        });
+    }
+    /** Inbox traffic must not cancel or steer an active human console/voice turn.
+     * Queue it once; the monitor commits its cursor after that turn succeeds.
+     * Other origins retain their configured monitor policy.
+     */
+    monitorAdmissionOptions(options) {
+        return options.origin?.kind === 'fleet-monitor'
+            && this.session.snapshot().activePromptSource === 'owner-admin-console'
+            ? { ...options, interrupt: false, steer: false } : options;
     }
     async submitPrompt(text, options = {}) {
         return (await this.queuePrompt(text, options)).completion;
@@ -103,6 +115,8 @@ export class RoleTurnArbiter {
     submitPromptAfterTool(text, options = {}) {
         if (this.retiring)
             return Promise.reject(new Error('Chat is closing'));
+        if (this.monitorAdmissionOptions(options) !== options)
+            return this.submitPrompt(text, options);
         return this.session.submitPromptAfterTool?.(text, options)
             ?? this.session.submitPrompt(text, { ...options, interrupt: false, steer: false });
     }

package/dist/session/codex-app-server.d.ts

@@ -11,6 +11,7 @@ export interface CodexAppServerSessionOptions {
     env: Record<string, string>;
     stateDir: string;
     mode: 'fresh' | 'resume';
+    requireResume?: boolean;
     permissions: CommonPermissions;
     permissionMode: NonNullable<SessionSnapshot['permissionMode']>;
     model?: string | null;

package/dist/session/codex-app-server.js

@@ -173,6 +173,7 @@ export class CodexAppServerSession {
             alive: this.isAlive(),
             readiness: this.readiness,
             sessionId: this.threadId,
+            ...(this.activeTurn?.origin ? { activePromptSource: this.activeTurn.origin.kind } : {}),
             lastError: this.lastError,
             pendingPermissionId: this.pendingPermissions.keys().next().value,
             runtimeModel: this.runtimeModel,
@@ -406,6 +407,8 @@ export class CodexAppServerSession {
         this.transport.notify('initialized');
         const persisted = this.options.mode === 'resume' && existsSync(this.threadFile)
             ? readFileSync(this.threadFile, 'utf8').trim() : '';
+        if (this.options.requireResume && !persisted)
+            throw new Error('TASK_CONTEXT_RESUME_UNAVAILABLE');
         const common = {
             cwd: this.options.cwd,
             approvalPolicy: this.options.approvalPolicy,
@@ -425,6 +428,8 @@ export class CodexAppServerSession {
         this.threadId = string(thread?.id);
         if (!this.threadId)
             throw new Error('Codex app-server did not return a thread id');
+        if (this.options.requireResume && this.threadId !== persisted)
+            throw new Error('TASK_CONTEXT_RESUME_MISMATCH');
         writeFileSync(this.threadFile, this.threadId + '\n', { mode: 0o600 });
         const model = string(response.model) ?? this.options.model ?? undefined;
         if (model)

package/dist/session/conversation-types.d.ts

@@ -8,7 +8,7 @@ import type { PromptOrigin, TurnCancellationSource, TurnOutcome } from './types.
  * file touches the wire: transport updates are reduced into these shapes by a
  * session adapter, and the store assigns `seq`/`eventId`/timestamps.
  */
-export type ConversationEventKind = 'prompt.admitted' | 'prompt.started' | 'prompt.interrupt_requested' | 'message.chunk' | 'message.replace' | 'thought.chunk' | 'thought.replace' | 'plan.replace' | 'tool.upsert' | 'tool.content_chunk' | 'permission.requested' | 'permission.resolved' | 'fleet.task_created' | 'monitor.delivery' | 'usage.updated' | 'turn.state' | 'turn.completed' | 'session.state' | 'session.info' | 'capabilities.updated' | 'error'
+export type ConversationEventKind = 'prompt.admitted' | 'prompt.started' | 'prompt.interrupt_requested' | 'message.chunk' | 'message.replace' | 'thought.chunk' | 'thought.replace' | 'plan.replace' | 'tool.upsert' | 'tool.content_chunk' | 'permission.requested' | 'permission.resolved' | 'file.attached' | 'fleet.task_created' | 'monitor.delivery' | 'usage.updated' | 'turn.state' | 'turn.completed' | 'session.state' | 'session.info' | 'capabilities.updated' | 'error'
 /** A well-formed transport update this version cannot represent. Bounded, never a crash. */
  | 'unsupported';
 /** Where a conversation record came from. Typed provenance, never prompt text. */
@@ -228,7 +228,9 @@ export interface BoundedJson {
     digest?: string;
     redacted?: true;
 }
-export type ConversationPayload = MessageChunkPayload | ThoughtChunkPayload | PlanReplacePayload | ToolUpsertPayload | UsageUpdatedPayload | SessionStatePayload | SessionInfoPayload | CapabilitiesUpdatedPayload | UnsupportedPayload | PromptAdmittedPayload | PromptStartedPayload | PromptInterruptRequestedPayload | PermissionRequestedPayload | PermissionResolvedPayload | TurnStatePayload | TurnCompletedPayload | MonitorDeliveryPayload | SessionLifecyclePayload | ErrorPayload | TaskCreatedNotice;
+export type ConversationPayload = {
+    attachment: import('../file-delivery/types.js').DeliveredFile;
+} | MessageChunkPayload | ThoughtChunkPayload | PlanReplacePayload | ToolUpsertPayload | UsageUpdatedPayload | SessionStatePayload | SessionInfoPayload | CapabilitiesUpdatedPayload | UnsupportedPayload | PromptAdmittedPayload | PromptStartedPayload | PromptInterruptRequestedPayload | PermissionRequestedPayload | PermissionResolvedPayload | TurnStatePayload | TurnCompletedPayload | MonitorDeliveryPayload | SessionLifecyclePayload | ErrorPayload | TaskCreatedNotice;
 export interface ConversationEventV1 {
     schemaVersion: 1;
     roleId: string;

package/dist/session/types.d.ts

@@ -186,6 +186,8 @@ export interface SessionSnapshot {
     backend: SessionBackendId;
     alive: boolean;
     readiness: SessionReadiness;
+    /** Typed source of the active prompt; excludes prompt bodies and command IDs. */
+    activePromptSource?: PromptOrigin['kind'];
     sessionId?: string;
     lastError?: string;
     pendingPermissionId?: string;
@@ -284,6 +286,7 @@ export interface ConversationHandlePage {
  * on any concrete transport which implements it.
  */
 export interface AgentSession {
+    sendFileToChat?: (input: import('../file-delivery/types.js').FileDeliveryInput, signal: AbortSignal, copy: import('../file-delivery/types.js').CopyChatFile, policy: import('../config.js').CommonPermissions) => Promise<import('../file-delivery/types.js').DeliveredFile>;
     readonly backend: SessionBackendId;
     readonly pid: number;
     /** Live capabilities; optional only for source compatibility with external adapters. */

package/dist/spawn.d.ts

@@ -6,7 +6,7 @@ import { type CreationDeps, type CreationProvenance } from './creation.js';
 import './harness/claude-code.js';
 import './harness/codex.js';
 import './harness/hermes.js';
-import { type SupervisorLauncher } from './temp-lifecycle.js';
+import { type SupervisorLauncher, type TaskSupervisorOwner } from './temp-lifecycle.js';
 /**
  * The provenance record written by the most recent spawn in this process, so
  * the CLI can print the same summary it persisted rather than rebuilding it.
@@ -15,6 +15,8 @@ export declare let lastProvenance: CreationProvenance | undefined;
 export interface SpawnOpts {
     name: string;
     temp?: boolean;
+    /** Internal exact task-layout ownership, never a standalone manifest entry. */
+    taskOwner?: TaskSupervisorOwner;
     brain?: AgentSelection;
     role?: AgentSelection;
     /** Trusted canonical definition used by room provisioning; never a second schema. */
@@ -85,3 +87,5 @@ export declare function spawnPermanent(o: SpawnOpts, deps: OpsDeps, creation?: C
 export type { SupervisorLauncher } from './temp-lifecycle.js';
 /** Temp spawn: live state under ~/.ours-fleet/tmp, independent transient supervision. */
 export declare function spawnTemp(o: SpawnOpts, binPath: string, launch?: SupervisorLauncher, creation?: CreationDeps): Promise<string>;
+/** Resume the exact durable task launch; no creation, invite issuance or state rotation. */
+export declare function resumeTaskSupervisor(name: string, binPath: string): Promise<void>;

package/dist/spawn.js

@@ -1,3 +1,4 @@
+import { taskSupervisorMayRun } from './task-supervision.js';
 import { randomUUID } from 'node:crypto';
 import { storeRoomSecret, storeTemporaryLaunch, preparePermanentAssignment } from './agent-ours/service.js';
 import { ensureWorkspace } from './rooms-tasks/workspace.js';
@@ -16,7 +17,8 @@ import { recordGeneratedAgentSource } from './generated-agent-source.js';
 import './harness/claude-code.js';
 import './harness/codex.js';
 import './harness/hermes.js';
-import { archiveTempState, makeTempSupervisorLauncher, prepareTempSupervisor, reclaimStaleTempState, } from './temp-lifecycle.js';
+import { getAdapter } from './harness/registry.js';
+import { archiveTempState, makeTempSupervisorLauncher, prepareTempSupervisor, reclaimStaleTempState, stopTempSupervisor, secureStoppedTempArchive, readTempSupervisor, requestedTempStopReason, } from './temp-lifecycle.js';
 /**
  * The provenance record written by the most recent spawn in this process, so
  * the CLI can print the same summary it persisted rather than rebuilding it.
@@ -322,6 +324,8 @@ export async function spawnTemp(o, binPath, launch = independentSupervisor, crea
     if (o.isolationFile)
         readIsolationFile(o.isolationFile); // fail before reserving
     const prepared = resolvedSpawn(o); // canonical validation before mutation
+    if ((o.taskOwner || o.roomMemberStartup?.task_id) && !getAdapter(prepared.role.harness).supportsResume)
+        throw Error('TASK_HARNESS_RESUME_UNSUPPORTED: task agents require a resumable harness');
     if (o.roomMemberStartup?.workspace) {
         const workspace = o.roomMemberStartup.workspace;
         if (prepared.role.cwd !== workspace.path)
@@ -368,7 +372,14 @@ async function spawnTempInner(o, preparedRole, binPath, launch, tx, onStage) {
     lastProvenance = provenance;
     tx.record({
         stage: `temp state dir ${dir}`,
-        undo: () => {
+        undo: async () => {
+            if (o.taskOwner || role.roomMemberStartup?.task_id) {
+                await stopTempSupervisor(o.name);
+                const supervisor = readTempSupervisor(dir);
+                if (supervisor)
+                    await secureStoppedTempArchive(o.name, supervisor.launchId);
+                return;
+            }
             // A failed launch is still lifecycle evidence: briefing, provenance,
             // metadata and supervisor output explain what happened. Remove it from
             // the live roster by atomic archive, never recursive deletion.
@@ -381,7 +392,14 @@ async function spawnTempInner(o, preparedRole, binPath, launch, tx, onStage) {
     // out; a lone temp spawn still waits zero (time-based gate).
     if (cfg.startStaggerMs > 0)
         writeFileSync(join(dir, START_STAGGER_FILE), String(cfg.startStaggerMs));
-    prepareTempSupervisor(dir, o.name);
+    prepareTempSupervisor(dir, o.name, o.taskOwner ?? (o.roomMemberStartup?.task_id ? {
+        taskId: o.roomMemberStartup.task_id,
+        roomId: o.roomMemberStartup.room_id,
+        roomIdentityCid: o.roomMemberStartup.room_identity_cid,
+        creationActionId: o.creationActionId,
+    } : undefined));
+    if (o.taskOwner || o.roomMemberStartup?.task_id)
+        taskSupervisorMayRun(o.name);
     // Run the supervisor independently. On a service-managed host the temp
     // runner gets its own transient unit/job, so stopping the coordinator's unit
     // cannot kill a live worker in the coordinator's cgroup.
@@ -389,3 +407,14 @@ async function spawnTempInner(o, preparedRole, binPath, launch, tx, onStage) {
     await launch(binPath, ['_run-temp', o.name], dir);
     return dir;
 }
+/** Resume the exact durable task launch; no creation, invite issuance or state rotation. */
+export async function resumeTaskSupervisor(name, binPath) {
+    if (!taskSupervisorMayRun(name))
+        throw Error('TASK_SUPERVISOR_RETIRED');
+    const dir = agentDir(name, true);
+    if (requestedTempStopReason(dir))
+        throw Error('TASK_SUPERVISOR_STOP_REQUESTED');
+    const launcher = readTempSupervisor(dir)?.kind === 'detached'
+        ? makeTempSupervisorLauncher({ spawnDetached, supervisor: 'none' }) : independentSupervisor;
+    await launcher(binPath, ['_run-temp', name], dir);
+}

package/dist/startup-readiness.d.ts

@@ -9,5 +9,5 @@ interface ReadinessDeps {
     env: NodeJS.ProcessEnv;
 }
 /** Read-only preflight: never binds identities, starts a harness or edits its ledger. */
-export declare function waitForRoleDaemon(name: string, configPath?: string, partial?: Partial<ReadinessDeps>): Promise<void>;
+export declare function waitForRoleDaemon(name: string, configPath?: string, partial?: Partial<ReadinessDeps>, temp?: boolean): Promise<void>;
 export {};

package/dist/startup-readiness.js

@@ -1,11 +1,11 @@
 import { agentDir } from './paths.js';
 import { findRole, loadConfig } from './config.js';
-import { resolveConfigPath } from './runner.js';
+import { resolveConfigPath, loadTempRole } from './runner.js';
 import { probeDaemonGeneration } from './daemon-recovery.js';
 export const STARTUP_WAIT_MS = 240_000;
 export const STARTUP_RETRY_MS = 5_000;
 /** Read-only preflight: never binds identities, starts a harness or edits its ledger. */
-export async function waitForRoleDaemon(name, configPath, partial = {}) {
+export async function waitForRoleDaemon(name, configPath, partial = {}, temp = false) {
     const deps = {
         probe: env => probeDaemonGeneration(((url, init) => globalThis.fetch(url, {
             ...init, signal: AbortSignal.timeout(10_000),
@@ -17,7 +17,7 @@ export async function waitForRoleDaemon(name, configPath, partial = {}) {
         ...partial,
     };
     const path = resolveConfigPath(agentDir(name), configPath);
-    const role = findRole(loadConfig(path), name);
+    const role = temp ? loadTempRole(name) : findRole(loadConfig(path), name);
     const env = { ...deps.env, ...role.env };
     const deadline = deps.now() + STARTUP_WAIT_MS;
     let lastReason = '';

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