@ours.network/fleet 1.2.0-nightly.66 → 1.2.0-nightly.68

package/dist/rooms-tasks/cowork-http.js

@@ -5,6 +5,16 @@ import { CoworkProtocolError, CoworkUnavailableError } from './cowork-adapter.js
 const TRANSPORT_CODES = new Set(['EACCES', 'ENOENT', 'ECONNREFUSED', 'ECONNRESET',
     'ETIMEDOUT', 'ENOTFOUND', 'EAI_AGAIN', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_SOCKET',
     'CERT_HAS_EXPIRED', 'ERR_TLS_CERT_ALTNAME_INVALID']);
+/** Failure kinds a dependency still starting (or restarting) produces. */
+const RETRYABLE_KINDS = new Set(['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN',
+    'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_SOCKET', 'timeout']);
+/** Statuses a reverse proxy answers with while its upstream is not serving. */
+const GATEWAY_UNAVAILABLE = new Set([502, 503, 504]);
+/** Media type only, never parameters; anything unusual collapses to a fixed label. */
+function safeContentType(response) {
+    const value = (response.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase();
+    return /^[a-z0-9.+-]{1,40}\/[a-z0-9.+-]{1,40}$/.test(value) ? value : 'unknown type';
+}
 function safeFailureKind(error, signal) {
     if (signal.aborted)
         return 'timeout';
@@ -22,6 +32,9 @@ function safeFailureKind(error, signal) {
     }
     return 'transport_error';
 }
+function safeOperation(method) {
+    return /^[a-z][a-z0-9_.-]{0,79}$/.test(method) ? method : 'management';
+}
 /** Same RPC protocol as the local socket; never replay a possibly delivered mutation. */
 export async function coworkHttpCall(profile, method, params, timeoutMs) {
     const id = randomUUID();
@@ -67,16 +80,25 @@ export async function coworkHttpCall(profile, method, params, timeoutMs) {
         finally {
             await reader.cancel();
         }
+        // Status and media type, never the body: a proxy page may echo request data.
+        const shape = `HTTP ${response.status}, ${safeContentType(response)}`;
         let rpc;
+        let malformed = false;
         try {
             rpc = JSON.parse(Buffer.concat(chunks).toString('utf8'));
         }
         catch {
-            throw new CoworkProtocolError(method, 'server returned malformed JSON');
+            malformed = true;
+        }
+        if (malformed || !rpc || Array.isArray(rpc) || rpc.version !== 1 || rpc.id !== id
+            || Object.hasOwn(rpc, 'result') === Object.hasOwn(rpc, 'error')) {
+            // A gateway whose Cowork upstream is still starting answers with its own
+            // error page. That is unavailability, not a Cowork protocol violation; a
+            // well-formed RPC error under the same status keeps its meaning below.
+            if (GATEWAY_UNAVAILABLE.has(response.status))
+                throw new CoworkUnavailableError(`Cowork HTTP ${safeOperation(method)} failed: gateway answered ${shape} without an RPC response`, { retryable: true });
+            throw new CoworkProtocolError(method, `server returned ${malformed ? 'malformed JSON' : 'an invalid RPC response'} (${shape})`);
         }
-        if (!rpc || Array.isArray(rpc) || rpc.version !== 1 || rpc.id !== id
-            || Object.hasOwn(rpc, 'result') === Object.hasOwn(rpc, 'error'))
-            throw new CoworkProtocolError(method, 'server returned an invalid RPC response');
         if (Object.hasOwn(rpc, 'error')) {
             const error = rpc.error;
             if (!error || typeof error.code !== 'string' || typeof error.message !== 'string')
@@ -88,11 +110,11 @@ export async function coworkHttpCall(profile, method, params, timeoutMs) {
         return rpc.result;
     }
     catch (error) {
-        if (error instanceof CoworkProtocolError)
+        if (error instanceof CoworkProtocolError || error instanceof CoworkUnavailableError)
             throw error;
         // Durable cleanup records retain only .message. Keep the RPC step and a
         // bounded allowlisted category there, never raw URLs, credentials or cause text.
-        const operation = /^[a-z][a-z0-9_.-]{0,79}$/.test(method) ? method : 'management';
-        throw new CoworkUnavailableError(`Cowork HTTP ${operation} failed during ${stage} (${safeFailureKind(error, signal)})`, { cause: error });
+        const kind = safeFailureKind(error, signal);
+        throw new CoworkUnavailableError(`Cowork HTTP ${safeOperation(method)} failed during ${stage} (${kind})`, { cause: error, retryable: stage !== 'credential read' && RETRYABLE_KINDS.has(kind) });
     }
 }

package/dist/runner.d.ts

@@ -41,6 +41,8 @@ export interface RunnerDeps {
     shouldStop?(): boolean;
     /** Parent shutdown suspends a managed transient member; explicit stop still retires. */
     suspendOnStop?: boolean;
+    /** One-shot timer for the sustained-health check; returns its cancel function. */
+    setTimer?(fn: () => void, ms: number): () => void;
 }
 export declare const SUPERVISOR_RECYCLE_REQUIRED = "OWNER_CHANNEL_SUPERVISOR_RECYCLE_REQUIRED";
 export declare class SupervisorRecycleRequiredError extends Error {
@@ -177,6 +179,8 @@ export interface AttemptResult {
     modelRecovery?: 'advance' | 'hold';
     /** Present only when a temporary-role lifecycle signal ended the session. */
     retirementReason?: 'identity-closed' | 'operator-stop' | 'supervisor-signal' | 'idle-timeout';
+    /** Seconds the session spent up after startup completed; absent if it never came up. */
+    healthySecs?: number;
 }
 /** Continuous authoritative absence required after an identity was observed. */
 export declare const TEMP_IDENTITY_CLOSE_DEBOUNCE_MS = 5000;
@@ -190,6 +194,8 @@ export declare function runOnce(name: string, opts?: {
     configPath?: string;
     allowResumeRotation?: boolean;
     identityLifetime?: 'permanent' | 'temporary';
+    /** Called once when the session is up, so the supervisor can time sustained health. */
+    onHealthy?: () => void;
 }, partialDeps?: Partial<RunnerDeps>): Promise<AttemptResult>;
 /**
  * The persistent supervisor for one permanent role: run child sessions in a
@@ -208,6 +214,7 @@ export declare function runSupervised(name: string, opts?: {
     configPath?: string;
     allowResumeRotation?: boolean;
     temp?: boolean;
+    onHealthy?: () => void;
 }, d: Partial<RunnerDeps>) => Promise<AttemptResult>): Promise<RestartLedger>;
 /** Temp-agent entrypoint: run once, journal why it ended, then archive its evidence. */
 /** The parent uses the same adapter-relative sustained-uptime reset boundary. */

package/dist/runner.js

@@ -328,6 +328,11 @@ const carriedForward = (previous) => ({
     ...(previous.abruptTerminations ? { abruptTerminations: previous.abruptTerminations } : {}),
     ...(previous.supervisorStartedAt ? { supervisorStartedAt: previous.supervisorStartedAt } : {}),
 });
+function unrefTimer(fn, ms) {
+    const timer = setTimeout(fn, ms);
+    timer.unref?.();
+    return () => clearTimeout(timer);
+}
 /** Bounded exponential backoff for the nth consecutive immediate failure. */
 export function backoffFor(consecutiveFailures) {
     if (consecutiveFailures <= 0)
@@ -713,7 +718,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
                 managedOurs: managedHarness.ours,
                 role, prep,
                 launch: { ...launch, argv: wrappedArgv, env: managedHarness.env },
-                cwd: runCwd, stateDir: dir, mode, requireResume, permissions: perms,
+                cwd: runCwd, stateDir: dir, mode, requireResume, deferRecoveredPrompts: true, permissions: perms,
                 permissionMode: effectivePermissionMode(role), log: deps.log,
             }));
             managedService.setFileDelivery?.(agentSession.sendFileToChat?.bind(agentSession));
@@ -841,6 +846,11 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
                     }
                     return event;
                 });
+            // Recovered prompts may run the managed Fleet CLI immediately. Start them
+            // only now that the control socket, audit and spawn handlers are live, and
+            // never for a role being stopped: they stay durable for its next start.
+            if (!deps.shouldStop?.())
+                agentSession.activateRecoveredPrompts?.();
             resolvedMonitorDeps.delivery = {
                 // A wake is only delivered when its turn TERMINATES successfully. A
                 // refusal or a cancellation reached the agent and was not acted on, so
@@ -1049,6 +1059,8 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
             }
         }
         deps.log(`[${name}] up; pid=${pid} cwd=${runCwd} harness=${role.harness} session=${sessionBackend} mode=${mode}`);
+        const healthyAt = deps.now();
+        opts.onHealthy?.();
         // Keep arrivals behind the early prime() cursor; never re-prime at startup.
         // Recoverable cancellation preserves the supervisor, not monitor readiness.
         monitorMayStart = true;
@@ -1256,6 +1268,7 @@ export async function runOnce(name, opts = {}, partialDeps = {}) {
             throw new SupervisorRecycleRequiredError();
         return {
             elapsedSecs: elapsed, exit: exitRecord, rotated, mode, modelRecovery,
+            healthySecs: (deps.now() - healthyAt) / 1000,
             ...(layoutRetiring ? { retirementReason: 'operator-stop' } : retirementReason ? { retirementReason } : {}),
         };
     }
@@ -1339,6 +1352,51 @@ export async function runSupervised(name, opts = {}, partialDeps = {}, attempt =
             }
             if (taskMember && (shouldStop() || !taskSupervisorMayRun(name)))
                 break;
+            if (attempt === runOnce && taskMember) {
+                // Cowork can come up after the daemon on boot. Wait read-only so a
+                // gateway still starting its upstream does not spend the failure budget.
+                const { waitForTaskRoomManagement } = await import('./startup-readiness.js');
+                await waitForTaskRoomManagement(name, { shouldStop });
+            }
+            if (taskMember && (shouldStop() || !taskSupervisorMayRun(name)))
+                break;
+            const fastFailSecs = taskMember ? tempFastFailSecs(name) : fastFailSecsFor(name, opts.configPath);
+            // The fast-fail boundary starts a recovery episode; it must not also be
+            // the boundary that declares recovery successful. Otherwise alternating
+            // 19s and 20s deaths erase one another forever. Require the configured
+            // number of fast-fail windows to survive before closing an active streak.
+            // This hysteresis stays adapter-relative (100s for the current 20s/5-attempt
+            // policy) and still lets a genuinely sustained session reset the breaker.
+            const stableRecoverySecs = fastFailSecs * RESTART_FAIL_THRESHOLD;
+            // A session that stays up that long has recovered, even if it never
+            // returns: a host reset or OOM-kill ends it without reaching the
+            // post-attempt reset below, and a stale streak would then hold the role
+            // down after a few transient boot failures spread over days.
+            const streakAtStart = ledger;
+            const clearSustainedStreak = () => {
+                if (streakAtStart.consecutiveImmediateFailures === 0)
+                    return;
+                const current = readRestartLedger(dir);
+                // Never overwrite an operator reset, an open circuit or a successor's state.
+                if (current.circuit === 'open' || current.updatedAt !== streakAtStart.updatedAt
+                    || current.consecutiveImmediateFailures !== streakAtStart.consecutiveImmediateFailures
+                    || readRunMarker(dir)?.startedAt !== startedAt)
+                    return;
+                writeRestartLedger(dir, {
+                    ...emptyLedger(),
+                    ...carriedForward(current),
+                    lastReason: `sustained healthy session (${stableRecoverySecs}s)`,
+                    updatedAt: stamp(),
+                });
+                deps.log(`[${name}] healthy for ${stableRecoverySecs}s; cleared `
+                    + `${current.consecutiveImmediateFailures} earlier immediate failure(s)`);
+            };
+            let cancelStabilityTimer;
+            const onHealthy = () => {
+                if (cancelStabilityTimer || streakAtStart.consecutiveImmediateFailures === 0)
+                    return;
+                cancelStabilityTimer = (deps.setTimer ?? unrefTimer)(clearSustainedStreak, stableRecoverySecs * 1000);
+            };
             let result;
             try {
                 // Service-manager boot and automatic retry bypass the operator-facing
@@ -1351,9 +1409,10 @@ export async function runSupervised(name, opts = {}, partialDeps = {}, attempt =
                     await reconcilePermanentRoleIdentities(role, undefined, deps.log);
                 }
                 result = await attempt(name, { configPath: opts.configPath, ...(taskMember ? { temp: true } : {}),
-                    allowResumeRotation: taskMember ? false : !ledger.resumeDiscarded }, deps);
+                    allowResumeRotation: taskMember ? false : !ledger.resumeDiscarded, onHealthy }, deps);
             }
             catch (e) {
+                cancelStabilityTimer?.();
                 if (e instanceof SupervisorRecycleRequiredError) {
                     writeRestartLedger(dir, {
                         ...ledger,
@@ -1373,8 +1432,14 @@ export async function runSupervised(name, opts = {}, partialDeps = {}, attempt =
                     mode: 'fresh',
                 };
             }
-            if (stopping || (taskMember && (shouldStop() || result.retirementReason)))
+            cancelStabilityTimer?.();
+            if (stopping || (taskMember && (shouldStop() || result.retirementReason))) {
+                // An orderly stop of a session that was healthy long enough is a
+                // recovery too; only the timer's race with the stop is decided here.
+                if ((result.healthySecs ?? 0) >= stableRecoverySecs)
+                    clearSustainedStreak();
                 break;
+            }
             // Re-read: the attempt itself may have taken minutes, and an operator may
             // have reset the ledger meanwhile.
             ledger = readRestartLedger(dir);
@@ -1391,15 +1456,6 @@ export async function runSupervised(name, opts = {}, partialDeps = {}, attempt =
                 await deps.sleep(HELD_DOWN_POLL_MS);
                 continue;
             }
-            const fastFailSecs = taskMember ? getAdapter(loadTempRole(name).harness).exitPolicy.fastFailSecs
-                : fastFailSecsFor(name, opts.configPath);
-            // The fast-fail boundary starts a recovery episode; it must not also be
-            // the boundary that declares recovery successful. Otherwise alternating
-            // 19s and 20s deaths erase one another forever. Require the configured
-            // number of fast-fail windows to survive before closing an active streak.
-            // This hysteresis stays adapter-relative (100s for the current 20s/5-attempt
-            // policy) and still lets a genuinely sustained session reset the breaker.
-            const stableRecoverySecs = fastFailSecs * RESTART_FAIL_THRESHOLD;
             const recoveryFailed = result.elapsedSecs < fastFailSecs
                 || (ledger.consecutiveImmediateFailures > 0 && result.elapsedSecs < stableRecoverySecs);
             if (!recoveryFailed) {
@@ -1463,6 +1519,14 @@ function fastFailSecsFor(name, configPath) {
         return 20;
     }
 }
+function tempFastFailSecs(name) {
+    try {
+        return getAdapter(loadTempRole(name).harness).exitPolicy.fastFailSecs;
+    }
+    catch {
+        return 20;
+    }
+}
 /** Temp-agent entrypoint: run once, journal why it ended, then archive its evidence. */
 /** The parent uses the same adapter-relative sustained-uptime reset boundary. */
 export function stableSupervisorWindow(name, temp, configPath) {

package/dist/session/acp.d.ts

@@ -64,6 +64,11 @@ export interface AcpSessionOptions {
     stateDir: string;
     mode: 'fresh' | 'resume';
     requireResume?: boolean;
+    /**
+     * Hold never-started prompts recovered from a prior generation until the
+     * caller's control plane is listening; see activateRecoveredPrompts().
+     */
+    deferRecoveredPrompts?: boolean;
     permissions: CommonPermissions;
     /** Native permission-mode id to request via session/set_mode; undefined keeps the agent default. */
     modeId?: string;
@@ -159,6 +164,7 @@ export declare class AcpSession implements AgentSession {
     private advertisedCommands;
     private presentedCommands;
     private queueDepth;
+    private readonly deferredRecovered;
     private readonly observation;
     private exit;
     private steeringSupported;
@@ -209,6 +215,14 @@ export declare class AcpSession implements AgentSession {
      * never silently replayed.
      */
     private recoverOpenPrompts;
+    /**
+     * Dispatch recovered prompts held by deferRecoveredPrompts. A recovered turn
+     * can run tools at once, including the managed Fleet CLI, so it must not
+     * start before the supervisor's control socket accepts connections. Prompts
+     * never activated stay admitted-unstarted and recover again on next start.
+     */
+    activateRecoveredPrompts(): void;
+    private dispatchRecovered;
     isAlive(): boolean;
     /**
      * Take the occupancy lease for a turn the adapter started on its own behalf.

package/dist/session/acp.js

@@ -284,6 +284,7 @@ export class AcpSession {
     advertisedCommands = new Set();
     presentedCommands = [];
     queueDepth = 0;
+    deferredRecovered = [];
     observation = new ConversationObservation(() => this.captureObservation());
     exit = null;
     steeringSupported = false;
@@ -457,14 +458,29 @@ export class AcpSession {
                 });
                 continue;
             }
-            const text = open.text;
-            const promptId = open.promptId;
-            this.queueDepth++;
-            const run = this.enqueue(promptId, text, undefined);
-            this.observation.publish();
-            void run.finally(() => { this.queueDepth = Math.max(0, this.queueDepth - 1); this.observation.publish(); });
+            const recovered = { promptId: open.promptId, text: open.text };
+            if (this.options.deferRecoveredPrompts)
+                this.deferredRecovered.push(recovered);
+            else
+                this.dispatchRecovered(recovered);
         }
     }
+    /**
+     * Dispatch recovered prompts held by deferRecoveredPrompts. A recovered turn
+     * can run tools at once, including the managed Fleet CLI, so it must not
+     * start before the supervisor's control socket accepts connections. Prompts
+     * never activated stay admitted-unstarted and recover again on next start.
+     */
+    activateRecoveredPrompts() {
+        for (const recovered of this.deferredRecovered.splice(0))
+            this.dispatchRecovered(recovered);
+    }
+    dispatchRecovered({ promptId, text }) {
+        this.queueDepth++;
+        const run = this.enqueue(promptId, text, undefined);
+        this.observation.publish();
+        void run.finally(() => { this.queueDepth = Math.max(0, this.queueDepth - 1); this.observation.publish(); });
+    }
     isAlive() {
         // child.killed only means kill() successfully SENT a signal. A process may
         // ignore SIGTERM and remain alive. exitCode or signalCode is the actual

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

@@ -13,6 +13,8 @@ export interface CodexAppServerSessionOptions {
     stateDir: string;
     mode: 'fresh' | 'resume';
     requireResume?: boolean;
+    /** Hold recovered never-started prompts until activateRecoveredPrompts(). */
+    deferRecoveredPrompts?: boolean;
     permissions: CommonPermissions;
     permissionMode: NonNullable<SessionSnapshot['permissionMode']>;
     model?: string | null;
@@ -66,6 +68,7 @@ export declare class CodexAppServerSession implements AgentSession {
     private lastError?;
     private exit;
     private queueDepth;
+    private readonly deferredRecovered;
     private readonly observation;
     private promptTail;
     /** Admitted prompts not yet handed to the app-server, in admission order. */
@@ -123,6 +126,9 @@ export declare class CodexAppServerSession implements AgentSession {
     submitPromptBrowser(command: SubmitPromptCommand): Promise<PromptReceipt>;
     private initialize;
     private recoverOpenPrompts;
+    /** Dispatch recovered prompts once the caller's control plane is listening. */
+    activateRecoveredPrompts(): void;
+    private dispatchRecovered;
     private admit;
     private runPrompt;
     private steer;

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

@@ -150,6 +150,7 @@ export class CodexAppServerSession {
     lastError;
     exit = null;
     queueDepth = 0;
+    deferredRecovered = [];
     observation = new ConversationObservation(() => this.captureObservation());
     promptTail = Promise.resolve();
     /** Admitted prompts not yet handed to the app-server, in admission order. */
@@ -586,15 +587,27 @@ export class CodexAppServerSession {
                 });
                 continue;
             }
-            this.queueDepth++;
             const origin = open.commandId
                 ? { kind: 'owner-admin-console', commandId: open.commandId }
                 : undefined;
-            const run = this.enqueue(open.promptId, open.text, origin);
-            this.observation.publish();
-            void run.finally(() => { this.queueDepth = Math.max(0, this.queueDepth - 1); this.observation.publish(); });
+            const recovered = { promptId: open.promptId, text: open.text, ...(origin ? { origin } : {}) };
+            if (this.options.deferRecoveredPrompts)
+                this.deferredRecovered.push(recovered);
+            else
+                this.dispatchRecovered(recovered);
         }
     }
+    /** Dispatch recovered prompts once the caller's control plane is listening. */
+    activateRecoveredPrompts() {
+        for (const recovered of this.deferredRecovered.splice(0))
+            this.dispatchRecovered(recovered);
+    }
+    dispatchRecovered({ promptId, text, origin }) {
+        this.queueDepth++;
+        const run = this.enqueue(promptId, text, origin);
+        this.observation.publish();
+        void run.finally(() => { this.queueDepth = Math.max(0, this.queueDepth - 1); this.observation.publish(); });
+    }
     admit(promptId, text, queuedBehind, options) {
         const { source, persistBody } = sourceFor(options.origin);
         const bytes = Buffer.byteLength(text);

package/dist/session/types.d.ts

@@ -304,6 +304,12 @@ export interface AgentSession {
     readonly pid: number;
     /** Live capabilities; optional only for source compatibility with external adapters. */
     readonly capabilities?: AgentSessionCapabilities;
+    /**
+     * Start never-started prompts recovered from a prior generation. Sessions
+     * started with deferRecoveredPrompts hold them until the supervisor's
+     * control plane is listening, so recovered work cannot reach a stale socket.
+     */
+    activateRecoveredPrompts?(): void;
     isAlive(): boolean;
     snapshot(): SessionSnapshot;
     taskNoticeBinding?(): TaskNoticeBinding | undefined;

package/dist/startup-readiness.d.ts

@@ -1,6 +1,8 @@
 import { type DaemonGenerationProbe } from './daemon-recovery.js';
 export declare const STARTUP_WAIT_MS = 240000;
 export declare const STARTUP_RETRY_MS = 5000;
+/** Upper bound for one read-only Cowork room probe during the startup wait. */
+export declare const ROOM_PROBE_TIMEOUT_MS = 10000;
 interface ReadinessDeps {
     probe(env: NodeJS.ProcessEnv): Promise<DaemonGenerationProbe>;
     now(): number;
@@ -10,4 +12,21 @@ interface ReadinessDeps {
 }
 /** Read-only preflight: never binds identities, starts a harness or edits its ledger. */
 export declare function waitForRoleDaemon(name: string, configPath?: string, partial?: Partial<ReadinessDeps>, temp?: boolean): Promise<void>;
+interface RoomManagementDeps {
+    /** Read-only room observation; production uses Cowork `room.show`. */
+    showRoom(roomId: string, env: NodeJS.ProcessEnv, timeoutMs: number): Promise<unknown>;
+    now(): number;
+    sleep(ms: number): Promise<void>;
+    log(message: string): void;
+    env: NodeJS.ProcessEnv;
+    shouldStop(): boolean;
+}
+/**
+ * Read-only preflight for a room member: wait while Cowork management is still
+ * starting behind the gateway. Only a retryable `CoworkUnavailableError` waits;
+ * success, any other error and the deadline all return so the real attempt
+ * decides, fails closed and counts. Never redeems invites, binds identities or
+ * judges room/seat identity — that remains the attempt's admission check.
+ */
+export declare function waitForTaskRoomManagement(name: string, partial?: Partial<RoomManagementDeps>): Promise<'ready' | 'not-required' | 'unavailable' | 'deferred'>;
 export {};

package/dist/startup-readiness.js

@@ -4,6 +4,8 @@ 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;
+/** Upper bound for one read-only Cowork room probe during the startup wait. */
+export const ROOM_PROBE_TIMEOUT_MS = 10_000;
 /** Read-only preflight: never binds identities, starts a harness or edits its ledger. */
 export async function waitForRoleDaemon(name, configPath, partial = {}, temp = false) {
     const deps = {
@@ -36,3 +38,64 @@ export async function waitForRoleDaemon(name, configPath, partial = {}, temp = f
     }
     throw new Error(`Daemon not ready (${lastReason}); service manager will retry startup`);
 }
+/**
+ * Read-only preflight for a room member: wait while Cowork management is still
+ * starting behind the gateway. Only a retryable `CoworkUnavailableError` waits;
+ * success, any other error and the deadline all return so the real attempt
+ * decides, fails closed and counts. Never redeems invites, binds identities or
+ * judges room/seat identity — that remains the attempt's admission check.
+ */
+export async function waitForTaskRoomManagement(name, partial = {}) {
+    let role;
+    // An unreadable snapshot is the attempt's failure to report, not this wait's.
+    try {
+        role = loadTempRole(name);
+    }
+    catch {
+        return 'deferred';
+    }
+    const startup = role.roomMemberStartup;
+    if (!startup)
+        return 'not-required';
+    const { createCoworkAdapter, CoworkUnavailableError } = await import('./rooms-tasks/cowork-adapter.js');
+    const deps = {
+        showRoom: (roomId, env, timeoutMs) => createCoworkAdapter({ env, timeoutMs }).getRoom(roomId),
+        now: Date.now,
+        sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+        log: message => process.stderr.write(message + '\n'),
+        env: process.env,
+        shouldStop: () => false,
+        ...partial,
+    };
+    const env = { ...deps.env, ...role.env };
+    const started = deps.now();
+    const deadline = started + STARTUP_WAIT_MS;
+    let waited = false;
+    for (;;) {
+        // Each probe fits in what is left of the wait, so the wait itself is bounded.
+        const timeoutMs = Math.min(ROOM_PROBE_TIMEOUT_MS, Math.max(1, deadline - deps.now()));
+        try {
+            await deps.showRoom(startup.room_id, env, timeoutMs);
+            if (waited)
+                deps.log(`[${name}] cowork room management ready after ${deps.now() - started}ms`);
+            return 'ready';
+        }
+        catch (error) {
+            if (!(error instanceof CoworkUnavailableError) || !error.retryable)
+                return 'deferred';
+            if (!waited)
+                deps.log(`[${name}] waiting for cowork room management: ${error.message}`);
+            waited = true;
+            if (deps.shouldStop())
+                return 'unavailable';
+            if (deps.now() + STARTUP_RETRY_MS >= deadline) {
+                deps.log(`[${name}] cowork room management still unavailable after ${STARTUP_WAIT_MS}ms: `
+                    + `${error.message}; starting the attempt so the restart budget applies`);
+                return 'unavailable';
+            }
+            await deps.sleep(STARTUP_RETRY_MS);
+            if (deps.shouldStop())
+                return 'unavailable';
+        }
+    }
+}

package/dist/supervisor/registration-refresh.d.ts

@@ -0,0 +1,45 @@
+import { type Exec } from '../exec.js';
+/** The release tree that owns a Fleet CLI script, if it is a packaged one. */
+export declare function releaseRoot(script: string): string | undefined;
+export type RegistrationState = 
+/** No definition installed; refresh never creates one. */
+'absent'
+/** Already runs the invoking release, or a stable launcher outside any release tree. */
+ | 'current'
+/** Pins another release tree. */
+ | 'stale'
+/** Rewritten to the invoking release by this refresh. */
+ | 'refreshed'
+/** Rewritten, but the service manager did not reload it; it still starts the old release. */
+ | 'reload-failed'
+/** Not a definition Fleet generated, or overridden; left untouched. */
+ | 'unrecognized';
+export type RunningState = 'current' | 'stale' | 'stopped' | 'unknown';
+export interface RegistrationReport {
+    service: 'supervisor' | 'web' | 'watchdogs';
+    path: string;
+    state: RegistrationState;
+    /** Release tree the definition pinned before this call. */
+    from?: string;
+    to?: string;
+    /** What the live process runs, which a definition rewrite does not change. */
+    running: RunningState;
+    detail?: string;
+}
+export interface RefreshOptions {
+    /** realpath of the invoking CLI script. */
+    binPath: string;
+    /** Rewrite stale definitions; false only reports. */
+    write: boolean;
+    platform?: NodeJS.Platform;
+    homeDir?: string;
+    exec?: Exec;
+    exists?(path: string): boolean;
+    /** argv of a live process, for comparing what it runs with its definition. */
+    processArgv?(pid: number): string[] | undefined;
+}
+/** Report, and with `write` refresh, each installed Fleet service definition. */
+export declare function refreshServiceRegistrations(options: RefreshOptions): Promise<RegistrationReport[]>;
+/** One operator line per definition, including the restart a refresh cannot do. */
+export declare function describeRegistration(report: RegistrationReport): string;
+export declare const registrationDrift: (reports: RegistrationReport[]) => RegistrationReport[];