@ours.network/fleet 1.2.0-nightly.8 → 1.2.0-nightly.81

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

@@ -1,4 +1,5 @@
-import type { PromptOrigin, TurnCancellationSource, TurnOutcome } from './types.js';
+import type { TaskCreatedNotice } from './task-notice.js';
+import type { PromptOrigin, SessionSnapshot, TurnCancellationSource, TurnOutcome } from './types.js';
 /**
  * Durable conversation domain schema for managed-session consoles.
  *
@@ -7,11 +8,11 @@ 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' | '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. */
-export type ConversationSource = 'owner_admin_console' | 'owner_channel' | 'fleet_monitor' | 'scheduled_loop' | 'startup' | 'local_console' | 'agent' | 'agent_replay';
+export type ConversationSource = 'owner_admin_console' | 'owner_channel' | 'fleet_monitor' | 'scheduled_loop' | 'startup' | 'local_console' | 'agent' | 'agent_replay' | 'fleet_lifecycle';
 export interface NormalizedText {
     type: 'text';
     text: string;
@@ -175,6 +176,12 @@ export interface PromptAdmittedPayload {
 }
 export interface PromptStartedPayload {
     queuedBehind?: number;
+    /** Present when one adapter turn carries several admitted prompts; `turnId` is the shared turn. */
+    batch?: {
+        turnId: string;
+        index: number;
+        size: number;
+    };
 }
 export interface PromptInterruptRequestedPayload {
     commandId?: string;
@@ -227,7 +234,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;
+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;
@@ -262,6 +271,9 @@ export interface ConversationEventV1 {
     adapterMeta?: AdapterMeta[];
 }
 export interface SubmitPromptCommand {
+    expectedSessionGeneration?: string;
+    /** Live speech must not silently queue behind an unrelated turn. */
+    requireIdle?: boolean;
     /** Idempotency-Key / clientRequestId. Reuse with a different body is a conflict. */
     commandId: string;
     text: string;
@@ -270,6 +282,8 @@ export interface SubmitPromptCommand {
 }
 export interface PromptReceipt {
     commandId: string;
+    /** Original durable admission generation; absent when historical provenance is unknown. */
+    sessionGeneration?: string;
     promptId: string;
     state: 'queued' | 'starting';
     queuedBehind: number;
@@ -283,12 +297,51 @@ export interface PermissionDecisionCommand {
     sessionGeneration: string;
     optionId: string;
 }
+/** One admitted prompt not yet handed to the agent, as reported by the queue that owns it. */
+export interface PendingPromptSummary {
+    promptId: string;
+    source: ConversationSource;
+    admittedAt: string;
+    bytes: number;
+    /** A bounded preview, present only for a body the ledger already holds. */
+    text?: string;
+    textTruncated?: boolean;
+}
 export interface ConversationSnapshot {
     sessionGeneration: string;
     readiness: 'starting' | 'idle' | 'running' | 'awaiting_permission' | 'failed' | 'offline';
     queueDepth: number;
     pendingPermissionIds: string[];
     historyDegraded?: boolean;
+    /** Live observation is unavailable; REST may still serve canonical durable data. */
+    observationFailure?: 'capture_failed';
+    /** Every waiting prompt, in delivery order; `pendingPromptCount` equals its length. */
+    pendingPrompts?: PendingPromptSummary[];
+    pendingPromptCount?: number;
+}
+/** Position captured synchronously with the owning backend's complete live state. */
+export interface ObservationPosition {
+    sessionGeneration: string;
+    stateRevision: number;
+    ledgerBarrier: number;
+}
+export interface ConversationObservationState extends ConversationSnapshot, ObservationPosition {
+    alive: boolean;
+    activePromptIds: string[];
+    pendingPrompts: PendingPromptSummary[];
+    pendingPromptCount: number;
+    /** Already presented and sanitized by the backend; never reconstructed from raw options. */
+    pendingPermissions: Array<PermissionRequestedPayload & {
+        permissionId: string;
+    }>;
+    commands: NonNullable<CapabilitiesUpdatedPayload['commands']>;
+    runtimeModel?: SessionSnapshot['runtimeModel'];
+    reasoningEffort?: SessionSnapshot['reasoningEffort'];
+    permissionMode?: SessionSnapshot['permissionMode'];
+}
+export interface ConversationObservation {
+    snapshot: ConversationObservationState;
+    unsubscribe(): void;
 }
 export interface ConversationPage {
     events: ConversationEventV1[];

package/dist/session/prompt-batch.d.ts

@@ -0,0 +1,79 @@
+import type { ConversationSource, PendingPromptSummary } from './conversation-types.js';
+import type { PromptOrigin, TurnResult } from './types.js';
+/**
+ * A prompt the session has admitted and not yet handed to the adapter.
+ *
+ * Every admitted prompt keeps its own id, ledger records and completion. What
+ * changes at a turn boundary is how many of them one adapter turn carries.
+ */
+export interface PendingPrompt {
+    promptId: string;
+    text: string;
+    origin?: PromptOrigin;
+    source: ConversationSource;
+    /** Whether the ledger already holds this body; an external body is never copied out of the queue. */
+    persistBody: boolean;
+    admittedAt: string;
+    /** Whether the session recognised the text, at admission, as one of its own control operations. */
+    command?: boolean;
+    /** Set when a release takes this prompt; every member of that turn shares it. */
+    released?: Promise<TurnResult>;
+    /** Last-moment validity check for an internal prompt; see `refuseAtRelease`. */
+    releaseGuard?: () => boolean;
+}
+/**
+ * How a waiting prompt takes part in a release.
+ *
+ *  - `message`: something a person or a peer route submitted for the agent to
+ *    read — the paired console, the owner channel, the local console, a
+ *    monitor wake. Every waiting message is delivered at one boundary, in
+ *    admission order, whatever its route.
+ *  - `command`: a control operation the session itself supports — the native
+ *    `/compact`, a command the ACP adapter advertised. It must reach the
+ *    adapter as the entire prompt, so it is its own turn and a boundary
+ *    between the messages before and after it. The session decides this at
+ *    admission; text that merely starts with a slash is an ordinary message.
+ *  - `internal`: startup, scheduled-loop, self-reminder and stall-watchdog prompts. They own
+ *    their turn's lifecycle (and, for a loop, the redaction of its whole
+ *    transcript), run alone, and never split the messages around them.
+ */
+export type PromptClass = 'message' | 'command' | 'internal';
+export declare function promptClass(prompt: Pick<PendingPrompt, 'origin' | 'command'>): PromptClass;
+/** The command name a prompt invokes, when its whole text has the shape of one. */
+export declare function commandName(text: string): string | undefined;
+/**
+ * Detach, in admission order, every pending prompt that is delivered with
+ * `head`. Synchronous on purpose: this is the snapshot boundary, and a prompt
+ * admitted after it returns belongs to the next release.
+ */
+export declare function takeBatch(pending: PendingPrompt[], head: PendingPrompt): PendingPrompt[];
+/**
+ * The release-time fence for a guarded internal prompt. A prompt can wait in
+ * the queue long after it was admitted; whatever it was about may have been
+ * cancelled, revised or expired meanwhile, or the role may be stopping. The
+ * guard answers at the one moment that matters — the prompt is about to reach
+ * the model — and a refusal removes it unsent.
+ *
+ * The guard runs only when the session is live: an offline session fails the
+ * turn without handing it to the adapter, so consuming the guard there would
+ * record a dispatch that never happened. Returns the refused result, or
+ * undefined when the release should proceed.
+ */
+export declare function refuseAtRelease(pending: PendingPrompt[], entry: PendingPrompt, online: boolean): TurnResult | undefined;
+export declare const RELEASE_GUARD_REFUSED = "release-guard-refused";
+/** Exact, server-computed identity of one member's body inside a shared turn. */
+export interface MemberBinding {
+    index: number;
+    of: number;
+    source: ConversationSource;
+    bytes: number;
+    sha256: string;
+}
+export declare function memberBindings(members: ReadonlyArray<Pick<PendingPrompt, 'text' | 'origin'>>, sourceOf: (origin: PromptOrigin | undefined) => ConversationSource): MemberBinding[];
+/** What the server asserts about a member's route; never derived from the member's text. */
+export declare function memberAuthority(source: ConversationSource): string;
+/** What a client may show for prompts still waiting: all of them, in order, and never an unpersisted body. */
+export declare function pendingInventory(pending: readonly PendingPrompt[]): {
+    pendingPrompts: PendingPromptSummary[];
+    pendingPromptCount: number;
+};

package/dist/session/prompt-batch.js

@@ -0,0 +1,120 @@
+import { createHash } from 'node:crypto';
+/**
+ * The inventory names every waiting prompt — a client must be able to show the
+ * whole queue, not a count of what it could not see. What keeps a snapshot
+ * small is the body: each entry carries a short preview, not the prompt.
+ */
+const INVENTORY_TEXT_CHARS = 200;
+const INTERNAL = new Set(['startup', 'scheduled-loop', 'stall-watchdog', 'self-reminder']);
+export function promptClass(prompt) {
+    if (INTERNAL.has(prompt.origin?.kind ?? 'local-console'))
+        return 'internal';
+    return prompt.command ? 'command' : 'message';
+}
+/** The command name a prompt invokes, when its whole text has the shape of one. */
+export function commandName(text) {
+    return /^\/([a-z][a-z0-9_-]*)(?:\s|$)/i.exec(text.trim())?.[1];
+}
+/**
+ * Detach, in admission order, every pending prompt that is delivered with
+ * `head`. Synchronous on purpose: this is the snapshot boundary, and a prompt
+ * admitted after it returns belongs to the next release.
+ */
+export function takeBatch(pending, head) {
+    const members = [];
+    if (promptClass(head) !== 'message')
+        members.push(head);
+    else {
+        for (const prompt of pending) {
+            const kind = promptClass(prompt);
+            if (kind === 'command')
+                break;
+            if (kind === 'message')
+                members.push(prompt);
+        }
+        if (!members.includes(head))
+            members.unshift(head);
+    }
+    for (const member of members) {
+        const at = pending.indexOf(member);
+        if (at >= 0)
+            pending.splice(at, 1);
+    }
+    return members;
+}
+/**
+ * The release-time fence for a guarded internal prompt. A prompt can wait in
+ * the queue long after it was admitted; whatever it was about may have been
+ * cancelled, revised or expired meanwhile, or the role may be stopping. The
+ * guard answers at the one moment that matters — the prompt is about to reach
+ * the model — and a refusal removes it unsent.
+ *
+ * The guard runs only when the session is live: an offline session fails the
+ * turn without handing it to the adapter, so consuming the guard there would
+ * record a dispatch that never happened. Returns the refused result, or
+ * undefined when the release should proceed.
+ */
+export function refuseAtRelease(pending, entry, online) {
+    if (!entry.releaseGuard || !online)
+        return undefined;
+    // Only an internal prompt is guaranteed to be its own release; any other
+    // class could be carried by another prompt's batch past this fence, so a
+    // guarded prompt of that kind is refused rather than sent unchecked.
+    let allowed = false;
+    if (promptClass(entry) === 'internal')
+        try {
+            allowed = entry.releaseGuard() === true;
+        }
+        catch {
+            allowed = false;
+        }
+    if (allowed)
+        return undefined;
+    const at = pending.indexOf(entry);
+    if (at >= 0)
+        pending.splice(at, 1);
+    return { accepted: false, outcome: 'cancelled', succeeded: false, detail: RELEASE_GUARD_REFUSED };
+}
+export const RELEASE_GUARD_REFUSED = 'release-guard-refused';
+export function memberBindings(members, sourceOf) {
+    return members.map((member, at) => ({
+        index: at + 1,
+        of: members.length,
+        source: sourceOf(member.origin),
+        bytes: Buffer.byteLength(member.text),
+        sha256: createHash('sha256').update(member.text).digest('hex'),
+    }));
+}
+/** What the server asserts about a member's route; never derived from the member's text. */
+export function memberAuthority(source) {
+    switch (source) {
+        case 'owner_admin_console':
+            return 'direct owner input from the server-authenticated paired console';
+        case 'owner_channel':
+            return 'admitted through the authenticated Fleet owner channel';
+        case 'fleet_monitor':
+            return 'a Fleet monitor notification, not owner input';
+        default:
+            return 'local console input, not authenticated owner-console or owner-channel input';
+    }
+}
+/** What a client may show for prompts still waiting: all of them, in order, and never an unpersisted body. */
+export function pendingInventory(pending) {
+    return {
+        pendingPromptCount: pending.length,
+        pendingPrompts: pending.map(prompt => {
+            const display = prompt.origin?.kind === 'owner' ? prompt.origin.displayText
+                : prompt.persistBody ? prompt.text : undefined;
+            return {
+                promptId: prompt.promptId,
+                source: prompt.source,
+                admittedAt: prompt.admittedAt,
+                bytes: Buffer.byteLength(prompt.text),
+                ...(display === undefined ? {} : {
+                    text: display.slice(0, INVENTORY_TEXT_CHARS),
+                    ...(display.length > INVENTORY_TEXT_CHARS ? { textTruncated: true } : {}),
+                }),
+            };
+        }),
+    };
+}

package/dist/session/task-notice.d.ts

@@ -0,0 +1,14 @@
+import type { ConversationEventStore } from './conversation-store.js';
+export interface TaskNoticeBinding {
+    sessionGeneration: string;
+    acpSessionId: string;
+    promptId: string;
+}
+export interface TaskCreatedNotice {
+    operationId: string;
+    taskId: string;
+    title: string;
+    state: string;
+}
+/** Only the trusted Fleet audit completion calls this, never model output. */
+export declare function appendTaskCreated(store: ConversationEventStore, binding: TaskNoticeBinding, notice: TaskCreatedNotice): void;

package/dist/session/task-notice.js

@@ -0,0 +1,13 @@
+/** Only the trusted Fleet audit completion calls this, never model output. */
+export function appendTaskCreated(store, binding, notice) {
+    let after;
+    do {
+        const page = store.page({ after, limit: 1000 });
+        if (page.events.some(e => e.kind === 'fleet.task_created' && e.payload.operationId === notice.operationId))
+            return;
+        if (!page.hasMore)
+            break;
+        after = page.nextCursor;
+    } while (after);
+    store.append({ kind: 'fleet.task_created', source: 'fleet_lifecycle', ...binding, turnId: binding.promptId, payload: notice });
+}

package/dist/session/types.d.ts

@@ -1,3 +1,4 @@
+import type { TaskCreatedNotice, TaskNoticeBinding } from './task-notice.js';
 import type { SessionBackendId } from '../config.js';
 import type { ConversationEventV1, ConversationSnapshot, PromptReceipt, SubmitPromptCommand } from './conversation-types.js';
 /**
@@ -13,7 +14,9 @@ import type { ConversationEventV1, ConversationSnapshot, PromptReceipt, SubmitPr
  */
 export type SessionReadiness = 'starting' | 'idle' | 'running' | 'awaiting_permission' | 'failed';
 export type TurnOutcome = 'completed' | 'refused' | 'cancelled' | 'failed' | 'inconclusive';
-export type TurnCancellationSource = 'owner' | 'local-console' | 'fleet-monitor' | 'scheduled-loop' | 'shutdown' | 'stall-watchdog';
+export type TurnCancellationSource = 'owner' | 'local-console' | 'fleet-monitor' | 'scheduled-loop' | 'shutdown' | 'stall-watchdog'
+/** An urgent self-reminder of the same agent asked its current turn to stop. */
+ | 'self-reminder';
 export type PromptOrigin = {
     kind: 'startup';
 } | {
@@ -30,6 +33,13 @@ export type PromptOrigin = {
     kind: 'scheduled-loop';
     loop: string;
     runId: string;
+}
+/** A due self-reminder wake; the agent's own stored reminder, never owner input. */
+ | {
+    kind: 'self-reminder';
+    eventId: string;
+    reminderId: string;
+    revision: number;
 } | {
     kind: 'owner-admin-console';
     commandId: string;
@@ -180,11 +190,19 @@ export interface SubmitPromptOptions {
     actor?: {
         browserSession?: string;
     };
+    /**
+     * Checked synchronously at the turn boundary, immediately before the prompt
+     * would be handed to a live model. False drops the prompt unsent. Only
+     * honoured for internal prompts, which always run alone.
+     */
+    releaseGuard?: () => boolean;
 }
 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;
@@ -283,17 +301,32 @@ 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. */
     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;
+    recordTaskCreated?(binding: TaskNoticeBinding, notice: TaskCreatedNotice): void;
     conversationPage?(request: {
         after?: string;
         limit?: number;
     }): ConversationHandlePage;
     conversationSnapshot?(): ConversationSnapshot;
+    /** Side-effect-free current-generation durability eligibility; does not certify a historical range. */
+    conversationReplayAvailable?(expectedGeneration: string): boolean;
+    replayConversation?(request: import('./conversation-replay.js').ConversationReplayRequest): AsyncIterable<import('./conversation-replay.js').ConversationReplayPage>;
+    /** Passive: registering never attaches a controller or acknowledges activity. */
+    observeConversation?(listener: (state: import('./conversation-types.js').ConversationObservationState) => void): import('./conversation-types.js').ConversationObservation;
+    subscribeConversationFailure?(listener: (generation: string) => void): () => void;
     subscribeConversation?(listener: (event: ConversationEventV1) => void): () => void;
     /** Durably admit an idempotent browser prompt; resolves on admission. */
     submitPromptBrowser?(command: SubmitPromptCommand): Promise<PromptReceipt>;
@@ -301,6 +334,11 @@ export interface AgentSession {
      * Hand the session a prompt and return as soon as it has accepted
      * responsibility for it. Throws `SessionControlError` if it cannot.
      */
+    /**
+     * The turn that carries an admitted prompt when one adapter turn delivered
+     * several; absent means the prompt's own id is its turn id.
+     */
+    sharedTurnId?(promptId: string): string | undefined;
     queuePrompt(text: string, options?: SubmitPromptOptions): Promise<QueuedPrompt>;
     /** Queue a prompt and wait for its terminal result. */
     submitPrompt(text: string, options?: SubmitPromptOptions): Promise<TurnResult>;
@@ -316,6 +354,9 @@ export interface AgentSession {
      * keep compiling. Read it through `interruptOutcome`, never directly.
      */
     interrupt(source?: TurnCancellationSource): Promise<InterruptResult>;
+    /** Atomically bind cancellation to one voice-owned turn. */
+    readonly liveVoiceSupported?: boolean;
+    interruptPrompt?(generation: string, promptId: string): Promise<InterruptResult>;
     respondPermission(permissionId: string, optionId: string): boolean;
     /** Generation-bound browser decision; stale/settled/invalid all fail closed. */
     respondPermissionV2?(permissionId: string, optionId: string, sessionGeneration: string): 'accepted' | 'stale';

package/dist/setup-tunnel-preflight.d.ts

@@ -0,0 +1,34 @@
+import { type Exec } from './exec.js';
+import type { WorkspacePayload } from './workspace-enrollment.js';
+/**
+ * Check what the steps after the one-time root proof depend on, before that
+ * proof is sent: a failure afterwards cannot be retried with a fresh command.
+ */
+export declare function setupTunnelPreflight({ exec, platform, node }?: {
+    exec?: Exec;
+    platform?: NodeJS.Platform;
+    node?: string;
+}): Promise<void>;
+/** What the steps after the proof need, kept so they can be finished without a new command. */
+export interface PendingTunnelSetup {
+    appOrigin: string;
+    origin: string;
+    hostWorkspaceId: string;
+    rootCid: string;
+    challenge: WorkspacePayload['challenge'];
+    /** Fleet configuration the setup started with; a resume must use the same one. */
+    configuration: string;
+    /** Every port sent to the account as the tunnel target. Without confirmedPort, the remote target may be any of these or the default. */
+    requestedPorts?: number[];
+    /** Last positively confirmed target; cleared before any new retarget request. */
+    confirmedPort?: number;
+}
+export declare function savePendingTunnelSetup(pending: PendingTunnelSetup): void;
+export declare function clearPendingTunnelSetup(): void;
+export declare function readPendingTunnelSetup(): PendingTunnelSetup;
+export declare const DEFAULT_TUNNEL_PORT = 49271;
+/**
+ * The port the web service must bind when the account can no longer retarget
+ * the tunnel. Unknown when a different port was requested and never confirmed.
+ */
+export declare function requiredPortAfterExpiry(pending: PendingTunnelSetup): number;

package/dist/setup-tunnel-preflight.js

@@ -0,0 +1,62 @@
+import { existsSync, lstatSync, readFileSync, rmSync } from 'node:fs';
+import { userInfo } from 'node:os';
+import { join } from 'node:path';
+import { replaceFileAtomically } from './atomic-file.js';
+import { realExec } from './exec.js';
+import { stateRoot } from './paths.js';
+const UNCHANGED = 'Nothing was changed and this host was not bound.';
+/**
+ * Check what the steps after the one-time root proof depend on, before that
+ * proof is sent: a failure afterwards cannot be retried with a fresh command.
+ */
+export async function setupTunnelPreflight({ exec = realExec, platform = process.platform, node = process.versions.node } = {}) {
+    const [major, minor] = node.split('.').map(Number);
+    if (major < 22 || (major === 22 && minor < 13))
+        throw Error(`Tunnel setup requires Node.js 22.13 or newer; this is ${node}. Update Node.js, then run a fresh tunnel setup command. ${UNCHANGED}`);
+    if (platform === 'linux') {
+        const manager = await exec('systemctl', ['--user', 'show-environment'], { timeout: 10_000 });
+        if (manager.code !== 0)
+            throw Error(`The user service manager is not reachable from this shell (${manager.stderr.trim().split('\n')[0] || `systemctl --user exited ${manager.code}`}). `
+                + `Log in directly as ${userInfo().username} (not through su or sudo), or run: sudo loginctl enable-linger ${userInfo().username} && export XDG_RUNTIME_DIR=/run/user/${process.getuid?.()} `
+                + `Then run a fresh tunnel setup command. ${UNCHANGED}`);
+    }
+    const help = await exec('cloudflared', ['tunnel', 'run', '--help'], { timeout: 10_000 });
+    if (help.code === 127)
+        throw Error(`cloudflared is not installed or not on PATH. Install it, then run a fresh tunnel setup command. ${UNCHANGED}`);
+    if (help.code !== 0 || !`${help.stdout}\n${help.stderr}`.includes('--token-file'))
+        throw Error(`This cloudflared is too old for tunnel setup (no --token-file support). Update cloudflared, then run a fresh tunnel setup command. ${UNCHANGED}`);
+}
+const pendingPath = () => join(stateRoot(), 'workspace', 'pending-setup.json');
+export function savePendingTunnelSetup(pending) {
+    replaceFileAtomically(pendingPath(), JSON.stringify(pending) + '\n', 0o600);
+}
+export function clearPendingTunnelSetup() { rmSync(pendingPath(), { force: true }); }
+export function readPendingTunnelSetup() {
+    const path = pendingPath();
+    if (!existsSync(path))
+        throw Error('No unfinished tunnel setup on this host. Run the tunnel setup command from the App.');
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0)
+        throw Error('Unfinished tunnel setup record must be an owned private file');
+    const pending = JSON.parse(readFileSync(path, 'utf8'));
+    if (typeof pending?.appOrigin !== 'string' || typeof pending.origin !== 'string' || typeof pending.hostWorkspaceId !== 'string'
+        || typeof pending.rootCid !== 'string' || !pending.challenge || !Number.isSafeInteger(pending.challenge.expiresAt) || typeof pending.configuration !== 'string'
+        || (pending.requestedPorts !== undefined && (!Array.isArray(pending.requestedPorts) || !pending.requestedPorts.every(Number.isInteger))))
+        throw Error('Unfinished tunnel setup record is invalid');
+    if (pending.confirmedPort !== undefined && (!Number.isInteger(pending.confirmedPort) || pending.confirmedPort < 1024 || pending.confirmedPort > 65535))
+        throw Error('Unfinished tunnel setup record is invalid');
+    return pending;
+}
+export const DEFAULT_TUNNEL_PORT = 49_271;
+/**
+ * The port the web service must bind when the account can no longer retarget
+ * the tunnel. Unknown when a different port was requested and never confirmed.
+ */
+export function requiredPortAfterExpiry(pending) {
+    if (pending.confirmedPort !== undefined)
+        return pending.confirmedPort;
+    const other = [...new Set(pending.requestedPorts ?? [])].filter(port => port !== DEFAULT_TUNNEL_PORT);
+    if (!other.length)
+        return DEFAULT_TUNNEL_PORT;
+    throw Error(`The setup window has expired and it is unknown whether the tunnel points at port ${[...other, DEFAULT_TUNNEL_PORT].join(' or ')}: the account's answer to a port request was not received. This setup cannot be finished automatically`);
+}

package/dist/socket-path.d.ts

@@ -0,0 +1,2 @@
+/** Optional private socket directory for deeply nested, isolated Fleet homes. */
+export declare function socketPath(logicalPath: string): string;

package/dist/socket-path.js

@@ -0,0 +1,22 @@
+import { createHash } from 'node:crypto';
+import { lstatSync, mkdirSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+/** Optional private socket directory for deeply nested, isolated Fleet homes. */
+export function socketPath(logicalPath) {
+    const root = process.env.OURS_FLEET_SOCKET_ROOT;
+    if (!root) {
+        if (Buffer.byteLength(logicalPath) > 103)
+            throw new Error('Unix socket path is too long; configure a short private OURS_FLEET_SOCKET_ROOT');
+        return logicalPath;
+    }
+    if (!isAbsolute(root) || resolve(root) !== root)
+        throw new Error('OURS_FLEET_SOCKET_ROOT must be an absolute normalized path');
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    const stat = lstatSync(root);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.() || (stat.mode & 0o777) !== 0o700)
+        throw new Error('OURS_FLEET_SOCKET_ROOT must be an owner-only 0700 directory');
+    const path = join(root, createHash('sha256').update(resolve(logicalPath)).digest('hex').slice(0, 24) + '.sock');
+    if (Buffer.byteLength(path) > 103)
+        throw new Error('OURS_FLEET_SOCKET_ROOT is too long');
+    return path;
+}

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