@ours.network/fleet 1.2.0-nightly.6 → 1.2.0-nightly.61

package/dist/temp-lifecycle.d.ts

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

package/dist/temp-lifecycle.js

@@ -1,8 +1,11 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, } from 'node:fs';
+import { parse } from 'yaml';
 import { randomUUID } from 'node:crypto';
 import { basename, join } from 'node:path';
-import { replaceFileAtomically, withFileLock } from './atomic-file.js';
+import { replaceFileAtomically, withFileLock, withSynchronousFileLock } from './atomic-file.js';
 import { realExec } from './exec.js';
+import { captureMemberEnvironment, catalogLiveness, memberKey, readMember, registerMember, unregisterMember, unregisterTaskMember } from './supervisor/catalog.js';
+import { ensureFleetParent } from './supervisor/fleet.js';
 import { stateRoot, tmpRoot } from './paths.js';
 export const TEMP_SUPERVISOR_FILE = '.temp-supervisor.json';
 export const TEMP_TERMINATION_FILE = 'termination.jsonl';
@@ -13,26 +16,40 @@ export const TEMP_LAUNCH_GRACE_MS = 60_000;
 const metadataPath = (dir) => join(dir, TEMP_SUPERVISOR_FILE);
 export const tempSystemdUnit = (name) => `ours-fleet-temp-${name}.service`;
 export const tempLaunchdLabel = (name) => `network.ours.fleet.temp.${name}`;
-export function prepareTempSupervisor(dir, role) {
+export function prepareTempSupervisor(dir, role, taskOwner) {
     const record = {
-        version: 1, role, launchId: randomUUID(), createdAt: new Date().toISOString(), phase: 'launching',
+        version: 1, role, launchId: randomUUID(), createdAt: new Date().toISOString(), phase: 'launching', ...(taskOwner ? { taskOwner } : {}),
     };
     replaceFileAtomically(metadataPath(dir), JSON.stringify(record, null, 2) + '\n');
     return record;
 }
 export function readTempSupervisor(dir) {
+    let value;
     try {
-        const value = JSON.parse(readFileSync(metadataPath(dir), 'utf8'));
-        if (value.version !== 1 || typeof value.role !== 'string' || typeof value.launchId !== 'string')
-            return undefined;
-        return value;
+        value = JSON.parse(readFileSync(metadataPath(dir), 'utf8'));
     }
     catch {
         return undefined;
     }
+    if (!value || typeof value !== 'object' || value.version !== 1 || typeof value.role !== 'string' || typeof value.launchId !== 'string')
+        return undefined;
+    if (value.kind !== undefined && !['fleet-managed', 'systemd-transient', 'launchd-transient', 'detached'].includes(value.kind))
+        throw Error('TEMP_SUPERVISOR_KIND_UNSUPPORTED');
+    return value;
+}
+/** Broad scans retain unsupported entries instead of blocking other members. */
+export function readTempSupervisorForScan(dir) {
+    try {
+        return readTempSupervisor(dir);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'TEMP_SUPERVISOR_KIND_UNSUPPORTED')
+            return undefined;
+        throw error;
+    }
 }
 const metadataLockPath = (dir) => join(stateRoot(), 'locks', 'temp-supervisors', encodeURIComponent(basename(dir)));
-async function updateTempSupervisor(dir, update) {
+export async function updateTempSupervisor(dir, update) {
     // The launcher and the just-started supervisor are separate processes. Lock
     // their read/merge/write updates so neither can discard the other's kind,
     // target, pid or phase. The lock lives outside the role directory so an
@@ -48,54 +65,22 @@ async function updateTempSupervisor(dir, update) {
         return next;
     });
 }
-/**
- * Launch a temp supervisor outside the caller's service-manager ownership
- * boundary. `detached: true` creates a new process group but does not escape a
- * systemd cgroup; a transient unit does, and is not enabled across reboot.
- */
+/** Register managed members under Fleet; explicit manual mode uses a detached child. */
 export function makeTempSupervisorLauncher(options = {}) {
     const exec = options.exec ?? realExec;
     const platform = options.platform ?? process.platform;
     const supervisor = options.supervisor ?? process.env.OURS_FLEET_SUPERVISOR;
     return async (binPath, args, dir) => {
-        const inherited = [
-            'HOME', 'PATH', 'XDG_RUNTIME_DIR', 'OURS_FLEET_HOME', 'CODEX_HOME',
-            // Preserve runtime selection across the service-manager boundary, including
-            // an explicit empty value which selects the bundle over manager defaults.
-            'CODEX_PATH',
-            // The child supervisor performs daemon identity and wake probes itself;
-            // it must resolve the same ours profile as the spawning supervisor.
-            'OURS_PORT', 'OURS_STATE_DIR', 'OURS_API_TOKEN', 'OURS_CONFIG',
-        ]
-            .flatMap(key => process.env[key] !== undefined ? [`${key}=${process.env[key]}`] : []);
         const role = args.at(-1);
         if (!role)
             throw new Error('temporary supervisor launch requires a role name');
-        const log = join(dir, 'supervisor.log');
-        if (supervisor !== 'none' && platform === 'linux') {
-            const target = tempSystemdUnit(role);
-            await updateTempSupervisor(dir, { phase: 'launching', kind: 'systemd-transient', target, binPath });
-            const result = await exec('systemd-run', [
-                '--user', '--quiet', '--collect', `--unit=${target}`,
-                '--property=Type=exec', '--property=KillMode=control-group', '--property=TimeoutStopSec=15s',
-                `--property=StandardOutput=append:${log}`, `--property=StandardError=append:${log}`,
-                ...inherited.map(value => `--setenv=${value}`),
-                process.execPath, binPath, ...args,
-            ]);
-            if (result.code !== 0)
-                throw new Error(`systemd-run ${target} failed: ${result.stderr.trim() || `exit ${result.code}`}`);
-            await updateTempSupervisor(dir, { phase: 'active' });
-            return;
-        }
-        if (supervisor !== 'none' && platform === 'darwin') {
-            const target = tempLaunchdLabel(role);
-            await updateTempSupervisor(dir, { phase: 'launching', kind: 'launchd-transient', target, binPath });
-            const result = await exec('launchctl', [
-                'submit', '-l', target, '-o', log, '-e', log, '--',
-                '/usr/bin/env', ...inherited, process.execPath, binPath, ...args,
-            ]);
-            if (result.code !== 0)
-                throw new Error(`launchctl submit ${target} failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+        const metadata = readTempSupervisor(dir);
+        if (supervisor !== 'none') {
+            const kind = metadata?.taskOwner ? 'task' : 'temporary';
+            await updateTempSupervisor(dir, { phase: 'launching', kind: 'fleet-managed', target: memberKey(role, kind), binPath });
+            await ensureFleetParent(exec, platform);
+            await registerMember({ name: role, kind, dir, environment: await captureMemberEnvironment(),
+                ...(metadata?.taskOwner ? { taskOwner: metadata.taskOwner, launchId: metadata.launchId } : {}) });
             await updateTempSupervisor(dir, { phase: 'active' });
             return;
         }
@@ -133,18 +118,34 @@ function appendTermination(dir, record) {
     replaceFileAtomically(join(dir, TEMP_GLOBAL_TERMINATION_MARKER), line);
 }
 function appendGlobalTermination(line, checkExisting = false) {
-    mkdirSync(archiveRoot(), { recursive: true, mode: 0o700 });
-    const path = join(archiveRoot(), 'terminations.jsonl');
-    // Recovery may revisit a .retiring directory after a crash between the
-    // global append and final rename. Avoid duplicating that exact event.
-    if (checkExisting) {
-        try {
-            if (readFileSync(path, 'utf8').split('\n').includes(line.trimEnd()))
-                return;
+    withSynchronousFileLock(join(stateRoot(), 'locks', 'termination-journal'), () => {
+        mkdirSync(archiveRoot(), { recursive: true, mode: 0o700 });
+        const path = join(archiveRoot(), 'terminations.jsonl');
+        // Recovery may revisit a .retiring directory after a crash between the
+        // global append and final rename. Avoid duplicating that exact event.
+        if (checkExisting) {
+            try {
+                if (readFileSync(path, 'utf8').split('\n').includes(line.trimEnd()))
+                    return;
+            }
+            catch { /* the journal does not exist yet */ }
         }
-        catch { /* the journal does not exist yet */ }
-    }
-    appendFileSync(path, line, { mode: 0o600 });
+        appendFileSync(path, line, { mode: 0o600 });
+    });
+}
+/** Explicit erasure removes only exact retired role/launch events. */
+export function eraseTerminationEvents(launches) {
+    withSynchronousFileLock(join(stateRoot(), 'locks', 'termination-journal'), () => {
+        const path = join(archiveRoot(), 'terminations.jsonl');
+        if (!existsSync(path))
+            return;
+        const lines = readFileSync(path, 'utf8').split('\n').filter(Boolean);
+        const kept = lines.filter(line => {
+            const row = JSON.parse(line);
+            return !launches.some(launch => launch.role === row.role && launch.launchId === row.launchId);
+        });
+        replaceFileAtomically(path, kept.length ? kept.join('\n') + '\n' : '');
+    });
 }
 /** Pick a sibling path without overwriting evidence from an earlier attempt. */
 function collisionSafeArchivePaths(targetBase, retiringBase) {
@@ -195,7 +196,7 @@ export function archiveTempState(role, reason, outcome, detail, now = new Date()
     return paths.target;
 }
 function isArchiveForLaunch(path, role, launchId) {
-    const supervisor = readTempSupervisor(path);
+    const supervisor = readTempSupervisorForScan(path);
     if (supervisor?.role !== role || supervisor.launchId !== launchId)
         return false;
     try {
@@ -240,7 +241,7 @@ export function tempArchiveForCreationAction(role, creationActionId) {
         return undefined;
     }
     const matches = entries.flatMap(path => {
-        const supervisor = readTempSupervisor(path);
+        const supervisor = readTempSupervisorForScan(path);
         if (!supervisor || supervisor.role !== role || !isArchiveForLaunch(path, role, supervisor.launchId))
             return [];
         try {
@@ -301,7 +302,15 @@ function recoverInterruptedArchives(now) {
     const recovered = [];
     for (const name of names) {
         const source = join(archiveRoot(), name);
-        const supervisor = readTempSupervisor(source);
+        let supervisor;
+        try {
+            supervisor = readTempSupervisor(source);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === 'TEMP_SUPERVISOR_KIND_UNSUPPORTED')
+                continue;
+            throw error;
+        }
         let line;
         try {
             line = readFileSync(join(source, TEMP_TERMINATION_FILE), 'utf8')
@@ -377,11 +386,13 @@ export async function tempSupervisorLiveness(dir, deps = {}) {
     // A concurrent spawn writes the target before systemd-run/launchctl has
     // registered it. A not-yet-created unit looks exactly like an inactive one,
     // so launch phase plus its bounded grace is not cleanup authority.
-    if (record.phase === 'launching'
+    if (record.phase === 'launching' && !requestedTempStopReason(dir)
         && (!Number.isFinite(age) || age < TEMP_LAUNCH_GRACE_MS))
         return 'unknown';
     // Older writers could lose `kind` in an unlocked metadata RMW while retaining
     // the supervisor pid. Exact argv ownership is stronger than the missing tag.
+    if (record.kind === 'fleet-managed')
+        return (await catalogLiveness(record.target ?? memberKey(record.role, record.taskOwner ? 'task' : 'temporary'), exec)).state;
     if (record.pid && (!record.kind || record.kind === 'detached'))
         return detachedProcessLiveness(record, deps);
     if (record.kind === 'systemd-transient' && record.target) {
@@ -445,6 +456,13 @@ export async function stopTempSupervisor(role, deps = {}) {
     replaceFileAtomically(join(dir, TEMP_STOP_REQUEST_FILE), JSON.stringify({
         version: 1, role, reason: 'operator-stop', requestedAt: new Date().toISOString(),
     }) + '\n');
+    if (record.kind === 'fleet-managed') {
+        if (record.taskOwner)
+            await unregisterTaskMember(role, { ...record.taskOwner, launchId: record.launchId }, { exec, sleep: deps.sleep });
+        else
+            await unregisterMember(record.target ?? memberKey(role, 'temporary'), { exec, sleep: deps.sleep });
+        return 'stopped';
+    }
     if (record.kind === 'systemd-transient' && record.target) {
         const result = await exec('systemctl', ['--user', 'stop', record.target]);
         if (result.code !== 0
@@ -495,6 +513,26 @@ export async function stopTempSupervisor(role, deps = {}) {
     (deps.kill ?? process.kill)(record.pid, 'SIGTERM');
     return 'stopped';
 }
+/** Legacy task snapshots remain recovery evidence even before explicit migration. */
+function hasRetainedTaskReference(dir) {
+    try {
+        if (basename(dir).startsWith('layout-')) {
+            const provenance = JSON.parse(readFileSync(join(dir, 'creation.json'), 'utf8'));
+            if (typeof provenance.creationActionId === 'string' && provenance.creationActionId.startsWith('task-'))
+                return true;
+        }
+        const startup = parse(readFileSync(join(dir, 'role.yaml'), 'utf8'))?.roomMemberStartup;
+        if (!startup?.room_id || !/^[A-Za-z0-9_-]{1,120}$/.test(startup.room_id))
+            return false;
+        const room = JSON.parse(readFileSync(join(stateRoot(), 'rooms', `${startup.room_id}.json`), 'utf8'));
+        return typeof room.task_id === 'string'
+            && room.member_seats.some((seat) => seat.role_name === basename(dir));
+    }
+    catch (error) {
+        // An unreadable role/room is uncertain ownership, never permission to reclaim.
+        return error.code !== 'ENOENT';
+    }
+}
 /**
  * Move a bounded batch of definitely-dead temp state into the evidence archive.
  * Unknown/legacy/live entries are preserved; absence of proof is never cleanup authority.
@@ -516,8 +554,18 @@ export async function reclaimStaleTempState(deps = {}) {
     const archived = [...recovered];
     for (const entry of entries) {
         const dir = join(tmpRoot(), entry.name);
-        if (!readTempSupervisor(dir))
-            continue; // legacy evidence has no safe ownership proof
+        const supervisor = readTempSupervisorForScan(dir);
+        if (!supervisor || supervisor.taskOwner || hasRetainedTaskReference(dir))
+            continue;
+        if (supervisor?.kind === 'fleet-managed' && supervisor.target) {
+            try {
+                if (readMember(supervisor.target)?.desired === 'running')
+                    continue;
+            }
+            catch {
+                continue;
+            } // uncertain catalog intent is never reclamation authority
+        }
         if (await tempSupervisorLiveness(dir, deps) !== 'stopped')
             continue;
         const target = archiveTempState(entry.name, 'stale-supervisor', 'reclaimed', 'supervisor is definitively stopped; state moved from the live roster without deletion', now);

package/dist/temp-supervisor-recovery.d.ts

@@ -1,3 +1,3 @@
 export declare const TEMP_RECYCLE_EXIT = 75;
 /** Keep the service's main process alive while replacing a PID-scoped worker. */
-export declare function runTempSupervisor(name: string, entrypoint: string, initial?: () => Promise<void>): Promise<void>;
+export declare function runTempSupervisor(name: string, entrypoint: string, initial?: () => Promise<void>, suspendOnStop?: boolean): Promise<void>;

package/dist/temp-supervisor-recovery.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { runTemp, SupervisorRecycleRequiredError } from './runner.js';
 export const TEMP_RECYCLE_EXIT = 75;
 /** Keep the service's main process alive while replacing a PID-scoped worker. */
-export async function runTempSupervisor(name, entrypoint, initial = () => runTemp(name)) {
+export async function runTempSupervisor(name, entrypoint, initial = () => runTemp(name), suspendOnStop = false) {
     try {
         await initial();
         return;
@@ -12,7 +12,7 @@ export async function runTempSupervisor(name, entrypoint, initial = () => runTem
             throw error;
     }
     for (let attempt = 0; attempt < 3; attempt++) {
-        const child = spawn(process.execPath, [entrypoint, '_run-temp-worker', name], {
+        const child = spawn(process.execPath, [entrypoint, '_run-temp-worker', name, ...(suspendOnStop ? ['--suspend-on-stop'] : [])], {
             stdio: 'inherit',
             env: process.env,
         });

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

@@ -0,0 +1,7 @@
+/** Keep the resumable record until both the QR and ordinary connection code were emitted. */
+export declare function completeTunnelSetup(effects: {
+    link: () => Promise<unknown>;
+    qr: (code: string) => Promise<string>;
+    write: (text: string) => unknown;
+    clear: () => void;
+}): Promise<void>;

package/dist/tunnel-setup-completion.js

@@ -0,0 +1,13 @@
+/** Keep the resumable record until both the QR and ordinary connection code were emitted. */
+export async function completeTunnelSetup(effects) {
+    try {
+        const link = await effects.link();
+        const code = Buffer.from(JSON.stringify(link)).toString('base64url');
+        const qr = await effects.qr(code);
+        await effects.write('Tunnel configured. Scan the QR or paste this private single-use connection code into the App.\n' + qr + '\n' + code + '\n');
+        effects.clear();
+    }
+    catch {
+        throw Error('Tunnel is configured but its connection code could not be printed. Run ours-fleet setup-tunnel --resume to retry.');
+    }
+}

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

@@ -0,0 +1,19 @@
+import { type WorkspacePayload } from './workspace-enrollment.js';
+/** Read the same private-file transport as enrollment, without consuming the grant. */
+export declare function readTunnelSetupFile(file: string): string;
+export declare function readTunnelSetupStdin(input?: AsyncIterable<Buffer | string>): Promise<string>;
+/** Only a minimal one-use v2 grant is allowed in shell arguments. */
+export declare function readTunnelSetupArgument(input: string): string;
+/** Redeem the grant by HTTPS POST; long-lived connector credentials remain off argv and URLs. */
+export declare function redeemTunnelSetup(input: string, request?: typeof fetch): Promise<WorkspacePayload>;
+/** Inspect only public destination metadata; this never consumes a one-use grant. */
+export declare function inspectTunnelSetup(input: string, request?: typeof fetch): Promise<{
+    workspaceId: string;
+    serverCid: string;
+    appOrigin: string;
+} | undefined>;
+export declare function verifyTunnelSetupTarget(target: {
+    workspaceId: string;
+    serverCid: string;
+    appOrigin: string;
+} | undefined, payload: WorkspacePayload): void;

package/dist/tunnel-setup-input.js

@@ -0,0 +1,124 @@
+import { lstatSync, readFileSync } from 'node:fs';
+import { decodeWorkspacePayload } from './workspace-enrollment.js';
+/** Read the same private-file transport as enrollment, without consuming the grant. */
+export function readTunnelSetupFile(file) {
+    const stat = lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0 || stat.size > 32768)
+        throw Error('Setup payload requires an owned private regular file (chmod 600)');
+    return readFileSync(file, 'utf8');
+}
+export async function readTunnelSetupStdin(input = process.stdin) {
+    let value = '';
+    for await (const chunk of input) {
+        value += chunk.toString();
+        if (Buffer.byteLength(value) > 32768)
+            throw Error('Tunnel setup payload is too large');
+    }
+    return value;
+}
+/** Only a minimal one-use v2 grant is allowed in shell arguments. */
+export function readTunnelSetupArgument(input) {
+    decodeTunnelSetupGrant(input);
+    return input;
+}
+function decodeTunnelSetupGrant(input) {
+    if (!/^[A-Za-z0-9_-]{1,32768}$/.test(input.trim()))
+        throw Error('Invalid tunnel setup payload');
+    let grant;
+    try {
+        grant = JSON.parse(Buffer.from(input.trim(), 'base64url').toString());
+    }
+    catch {
+        throw Error('Invalid tunnel setup payload');
+    }
+    if (grant?.version !== 2 || Object.keys(grant).sort().join(',') !== 'appOrigin,code,expiresAt,version'
+        || !['https://app.ours.network', 'https://app.ours-tunnel.com'].includes(grant.appOrigin)
+        || !/^[A-Za-z0-9_-]{43}$/.test(grant.code) || !Number.isSafeInteger(grant.expiresAt)
+        || grant.expiresAt <= Date.now() || grant.expiresAt > Date.now() + 16 * 60000)
+        throw Error('Tunnel setup grant is invalid or expired; get a fresh command from the App');
+    return grant;
+}
+/** Redeem the grant by HTTPS POST; long-lived connector credentials remain off argv and URLs. */
+export async function redeemTunnelSetup(input, request = fetch) {
+    if (!/^[A-Za-z0-9_-]{1,32768}$/.test(input.trim()))
+        throw Error('Invalid tunnel setup payload');
+    // v1 remains supported exclusively by the private file/stdin CLI transports.
+    let version;
+    try {
+        version = JSON.parse(Buffer.from(input.trim(), 'base64url').toString())?.version;
+    }
+    catch { }
+    if (version === 1)
+        return decodeWorkspacePayload(input);
+    const grant = decodeTunnelSetupGrant(input);
+    let response;
+    try {
+        response = await request(grant.appOrigin + '/account-api/workspace-install-redeem', {
+            method: 'POST', redirect: 'error', credentials: 'omit', signal: AbortSignal.timeout(30000),
+            headers: { 'Content-Type': 'application/json', Origin: grant.appOrigin }, body: JSON.stringify({ code: grant.code }),
+        });
+    }
+    catch {
+        throw Error('Could not reach the account service; setup grant redemption may be unconfirmed. Check the App before requesting a fresh command');
+    }
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw Error(response.status === 410 ? 'Tunnel setup grant expired or was already used; get a fresh command from the App'
+            : `Tunnel setup grant redemption failed (HTTP ${response.status}); check the App before retrying`);
+    }
+    let result;
+    try {
+        result = await response.json();
+    }
+    catch {
+        throw Error('Invalid tunnel setup response');
+    }
+    if (typeof result?.payload !== 'string' || !/^[A-Za-z0-9_-]{1,32768}$/.test(result.payload))
+        throw Error('Invalid tunnel setup response');
+    const payload = decodeWorkspacePayload(result.payload);
+    if (payload.appOrigin !== grant.appOrigin)
+        throw Error('Tunnel setup response origin mismatch');
+    return payload;
+}
+/** Inspect only public destination metadata; this never consumes a one-use grant. */
+export async function inspectTunnelSetup(input, request = fetch) {
+    let version;
+    try {
+        version = JSON.parse(Buffer.from(input.trim(), 'base64url').toString()).version;
+    }
+    catch { }
+    if (version === 1) {
+        const p = decodeWorkspacePayload(input);
+        return { workspaceId: p.challenge.workspaceId, serverCid: p.serverCid, appOrigin: p.appOrigin };
+    }
+    const grant = decodeTunnelSetupGrant(input);
+    let response;
+    try {
+        response = await request(grant.appOrigin + '/account-api/workspace-install-inspect', { method: 'POST', redirect: 'error', credentials: 'omit', signal: AbortSignal.timeout(15000), headers: { Origin: grant.appOrigin, 'Content-Type': 'application/json' }, body: JSON.stringify({ code: grant.code }) });
+    }
+    catch {
+        throw Error('Could not inspect the account setup command; existing setup and grant preserved');
+    }
+    if (response.status === 404 || response.status === 405) {
+        await response.body?.cancel();
+        return;
+    }
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw Error('Setup command inspection failed; existing setup and grant preserved');
+    }
+    let target;
+    try {
+        target = await response.json();
+    }
+    catch {
+        throw Error('Invalid setup command inspection response');
+    }
+    if (!target || Object.keys(target).sort().join(',') !== 'serverCid,workspaceId' || typeof target.workspaceId !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(target.workspaceId) || typeof target.serverCid !== 'string' || !/^[a-f0-9]{64}$/i.test(target.serverCid))
+        throw Error('Invalid setup command inspection response');
+    return { ...target, appOrigin: grant.appOrigin };
+}
+export function verifyTunnelSetupTarget(target, payload) {
+    if (target && (target.workspaceId !== payload.challenge.workspaceId || target.serverCid.toUpperCase() !== payload.serverCid.toUpperCase() || target.appOrigin !== payload.appOrigin))
+        throw Error('Redeemed setup command differs from inspected destination; existing setup preserved');
+}

package/dist/web/agent-attachments.d.ts

@@ -0,0 +1,29 @@
+export declare const MAX_ATTACHMENT_BYTES: number;
+export declare const MAX_ATTACHMENT_BODY: number;
+export interface AgentAttachment {
+    id: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    sha256: string;
+    generation: string;
+}
+export declare function storeAgentAttachment(stateDir: string, generation: string, input: unknown): AgentAttachment;
+export declare function attachmentPrompt(stateDir: string, generation: string, ids: unknown, text: string): string;
+export declare function readAgentAttachment(stateDir: string, id: string): {
+    record: AgentAttachment;
+    bytes: Buffer;
+};
+interface AttachmentPresentation {
+    generation: string;
+    commandId: string;
+    text: string;
+    transportDigest: string;
+    ids: string[];
+}
+/** Written before admission so a lost HTTP response cannot lose the visible message. */
+export declare function storeAttachmentPresentation(stateDir: string, value: AttachmentPresentation): void;
+export declare function prepareAttachmentPresentation(stateDir: string, generation: string, commandId: string, ids: string[], text: string, transport: string): void;
+/** Never infer attachments by stripping user text or interpreting a marker. */
+export declare function presentAttachmentEvent<T>(stateDir: string | undefined, roleId: string, event: T): T;
+export {};