@vibesdotdev/external 0.0.0-stage → 1.0.0-rc.1

package/dist/launch/consumer/store.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Launch state: one record and an attempt log per launched session, and
+ * exclusive claims that keep one writer per idempotency key and per canonical
+ * workspace. All of it is rows of the declared `external.launch_state` storage
+ * record (see `state-rows.ts`); the handed runtime's filesystem is used only to
+ * canonicalize workspace paths. The owner pid and pid liveness come from its
+ * `runtime/process` service; logging is the runtime's own logger. Malformed
+ * present state refuses with a fixed typed error and native cause; only
+ * genuinely absent state is absent.
+ */
+import { type LoggerImplementation } from '@vibesdotdev/logging';
+import { CapabilityError, type RuntimeRef } from '@vibesdotdev/kernel';
+import { type LaunchAttempt, type LaunchIndexEntry, type LaunchRecord } from '../schemas.ts';
+import { type ExternalFileSystem } from '../../utils/runtime-fs.ts';
+import { type LaunchRows } from './state-rows.ts';
+/** Launch state under one home, bound to the runtime that owns it. */
+export interface LaunchStore {
+    /** The launch state home (the runtime's `paths/roots` activeHome by default). */
+    readonly home: string;
+    readonly fs: ExternalFileSystem;
+    /** The declared launch state record. */
+    readonly rows: LaunchRows;
+    readonly log: LoggerImplementation;
+    /** The pid this host runs as: the owner a claim names. */
+    ownerPid(): number;
+    /** Whether a pid is running, as the runtime's process service sees it. */
+    isAlive(pid: number): Promise<boolean>;
+}
+/** Bind launch state under `home` to `runtime`'s storage, filesystem, process service and logger. */
+export declare function openLaunchStore(runtime: RuntimeRef, home: string): Promise<LaunchStore>;
+export declare function writeLaunchRecord(store: LaunchStore, record: LaunchRecord): Promise<LaunchRecord>;
+export declare function readLaunchRecord(store: LaunchStore, sessionId: string): Promise<LaunchRecord | null>;
+/** The launch index: every record's session, harness and start time, newest first. */
+export declare function readLaunchIndex(store: LaunchStore): Promise<LaunchIndexEntry[]>;
+/** Every launch record, newest first. */
+export declare function listLaunchRecords(store: LaunchStore): Promise<LaunchRecord[]>;
+export declare function findLaunchRecord(store: LaunchStore, ref: string): Promise<LaunchRecord | null>;
+export declare function redactLaunchArgv(argv: readonly string[], secretTexts: readonly string[]): string[];
+export declare function appendLaunchAttempt(store: LaunchStore, attempt: Omit<LaunchAttempt, 'attemptId'> & {
+    attemptId?: string;
+}): Promise<LaunchAttempt>;
+export declare function listLaunchAttempts(store: LaunchStore, sessionId: string): Promise<LaunchAttempt[]>;
+export declare function attemptStillOpen(attempt: LaunchAttempt): boolean;
+/**
+ * The canonical spelling of a workspace path: absolute, with every symlink
+ * resolved through the filesystem's `stat`. A part that does not exist yet
+ * keeps its spelling. More than {@link MAX_SYMLINK_HOPS} links is refused
+ * `INVALID_INPUT` `launch-workspace-symlink-loop`.
+ */
+export declare function canonicalWorkspacePath(store: LaunchStore, cwd: string): Promise<string>;
+export type LaunchClaim = {
+    kind: 'started';
+    attempt: LaunchAttempt;
+} | {
+    kind: 'replay';
+    attemptId: string;
+    sessionId: string;
+    disposition: 'open' | 'completed';
+} | {
+    kind: 'conflict';
+    attemptId: null;
+    reason: string;
+};
+export type LaunchReplay = {
+    kind: 'absent';
+} | {
+    kind: 'record';
+    record: LaunchRecord;
+} | {
+    kind: 'pending';
+    sessionId: string;
+    attemptId: string;
+} | {
+    kind: 'conflict';
+    sessionId: string | null;
+    attemptId: string | null;
+    reason: string;
+};
+/** The workspace already has a writer: refused `CONFLICT` `launch-workspace-claimed`, naming the holder's attempt. */
+export declare function workspaceClaimedRefusal(attemptId: string | null): CapabilityError;
+/** One exclusive file per key and one per canonical workspace. The second caller loses. */
+export declare function claimLaunchWriter(store: LaunchStore, input: Omit<LaunchAttempt, 'attemptId' | 'phase' | 'exitObserved' | 'createdAt' | 'cwd'> & {
+    cwd: string;
+    readOnly?: boolean | undefined;
+}): Promise<LaunchClaim>;
+export interface LaunchReplaySelection {
+    cwd: string;
+    harness: string;
+    toolId?: string;
+    sessionId?: string;
+}
+/** Read a prior key before any session is created. A mismatched authority is a conflict. */
+export declare function lookupLaunchReplay(store: LaunchStore, idempotencyKey: string, selection: LaunchReplaySelection): Promise<LaunchReplay>;
+/** A reservation never reports `absent`: an absent key is what gets reserved. */
+export type LaunchReservation = Exclude<LaunchReplay, {
+    kind: 'absent';
+}> | {
+    kind: 'reserved';
+    attemptId: string;
+};
+/** Reserve the key and workspace before any session exists. The loser does not prepare. */
+export declare function reserveLaunchKey(store: LaunchStore, input: Omit<LaunchAttempt, 'attemptId' | 'phase' | 'exitObserved' | 'createdAt' | 'cwd' | 'sessionId'> & {
+    cwd: string;
+    readOnly?: boolean | undefined;
+}): Promise<LaunchReservation>;
+export declare function bindLaunchSession(store: LaunchStore, idempotencyKey: string, sessionId: string): Promise<void>;
+/** Records an exit the owner observed. A live pid probe is not this record. */
+export declare function recordObservedLaunchExit(store: LaunchStore, input: {
+    sessionId: string;
+    idempotencyKey: string;
+    cwd: string;
+    harness: string;
+    toolId: string;
+    mode: string;
+    command: string;
+    pid: number;
+}): Promise<LaunchAttempt>;
+/**
+ * Records the exit of a supervised launch: PM ran the harness and its exit was
+ * observed by awaiting it, so there is no pid to probe. The attempt is marked
+ * exited, the key claim completed, and the workspace claim released.
+ */
+export declare function completeSupervisedLaunch(store: LaunchStore, input: {
+    attemptId: string;
+    sessionId: string;
+    idempotencyKey: string;
+    cwd: string;
+    harness: string;
+    toolId: string;
+    mode: string;
+    command: string;
+    pid?: number;
+}): Promise<LaunchAttempt>;
+/** An open attempt for this key or workspace must not gain a second writer. */
+export declare function findBlockingLaunchAttempt(store: LaunchStore, input: {
+    idempotencyKey: string;
+    cwd: string;
+}): Promise<LaunchAttempt | null>;
+//# sourceMappingURL=store.d.ts.map

package/dist/launch/consumer/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/launch/consumer/store.ts"],"names":[],"mappings":"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"}

package/dist/launch/consumer/store.js

@@ -0,0 +1,495 @@
+/**
+ * Launch state: one record and an attempt log per launched session, and
+ * exclusive claims that keep one writer per idempotency key and per canonical
+ * workspace. All of it is rows of the declared `external.launch_state` storage
+ * record (see `state-rows.ts`); the handed runtime's filesystem is used only to
+ * canonicalize workspace paths. The owner pid and pid liveness come from its
+ * `runtime/process` service; logging is the runtime's own logger. Malformed
+ * present state refuses with a fixed typed error and native cause; only
+ * genuinely absent state is absent.
+ */
+import * as z from 'zod/v4';
+import { dirname, isAbsolute, join, resolve } from '@vibesdotdev/filesystem';
+import { getLogger } from '@vibesdotdev/logging';
+import { CapabilityError, CaughtFailureSchema, isCapabilityError, valueFreeFailure } from '@vibesdotdev/kernel';
+import { JsonValueSchema } from '@vibesdotdev/kernel/schemas/json';
+import { getRuntimeProcessService } from '@vibesdotdev/kernel/process';
+import { launchAttemptSchema, launchIndexEntrySchema, launchRecordSchema } from "../schemas.js";
+import { externalFileSystem, externalPathStatRefusal } from "../../utils/runtime-fs.js";
+import { resolveLaunchRows } from "./state-rows.js";
+/** The most symlinks one canonical workspace path may follow. */
+const MAX_SYMLINK_HOPS = 40;
+/** Bind launch state under `home` to `runtime`'s storage, filesystem, process service and logger. */
+export async function openLaunchStore(runtime, home) {
+    const fs = await externalFileSystem(runtime);
+    const rows = await resolveLaunchRows(runtime);
+    const processes = await getRuntimeProcessService(runtime);
+    return {
+        home,
+        fs,
+        rows,
+        log: getLogger('external.launch.store', runtime),
+        ownerPid() {
+            const pid = processes.currentPid?.();
+            if (pid === undefined) {
+                throw new CapabilityError('The runtime process service declares no current pid.', 'UNAVAILABLE', {
+                    reason: 'launch-owner-pid-undeclared',
+                    retryable: false
+                });
+            }
+            return pid;
+        },
+        isAlive: (pid) => processes.isRunning(pid)
+    };
+}
+/** Any JSON value, as a state file holds it. */
+const StoredJsonSchema = JsonValueSchema;
+/** Admit present persisted state; corrupt text or shape must never become absence. */
+function parseStored(schema, text) {
+    try {
+        return schema.parse(JSON.parse(text));
+    }
+    catch (error) {
+        throw new CapabilityError('The stored launch state is invalid.', 'INTERNAL', {
+            reason: 'launch-state-invalid', cause: CaughtFailureSchema.parse(error), retryable: false
+        });
+    }
+}
+async function readStored(store, schema, id) {
+    const row = await store.rows.get(id);
+    return row === null ? undefined : parseStored(schema, row.body);
+}
+function rowOf(id, kind, sessionId, value) {
+    return { id, kind, sessionId, body: JSON.stringify(value) };
+}
+/** Write a row, replacing any earlier value. */
+async function writeRow(store, id, kind, sessionId, value) {
+    await store.rows.put(rowOf(id, kind, sessionId, value));
+}
+/** Create the row only when nothing holds `id`; `false` when another writer already published it. */
+function createExclusiveRow(store, id, kind, sessionId, value) {
+    return store.rows.createExclusive(rowOf(id, kind, sessionId, value));
+}
+/** Remove the row; a row already gone is already removed. */
+async function removeIfPresent(store, id) {
+    await store.rows.remove(id);
+}
+const LaunchIndexSchema = z.array(launchIndexEntrySchema);
+const recordRowId = (sessionId) => `record:${sessionId}`;
+export async function writeLaunchRecord(store, record) {
+    const parsed = launchRecordSchema.parse(record);
+    await writeRow(store, recordRowId(parsed.sessionId), 'record', parsed.sessionId, parsed);
+    return parsed;
+}
+export async function readLaunchRecord(store, sessionId) {
+    return (await readStored(store, launchRecordSchema, recordRowId(sessionId))) ?? null;
+}
+/** The launch index: every record's session, harness and start time, newest first. */
+export async function readLaunchIndex(store) {
+    const records = await listLaunchRecords(store);
+    return LaunchIndexSchema.parse(records.map((r) => ({ sessionId: r.sessionId, harness: r.harness, startedAt: r.startedAt })));
+}
+function newestFirst(left, right) {
+    return left.startedAt < right.startedAt ? 1 : left.startedAt > right.startedAt ? -1 : 0;
+}
+/** Every launch record, newest first. */
+export async function listLaunchRecords(store) {
+    const rows = await store.rows.list('record');
+    return rows.map((row) => parseStored(launchRecordSchema, row.body)).sort(newestFirst);
+}
+export async function findLaunchRecord(store, ref) {
+    const records = await listLaunchRecords(store);
+    const exact = records.find((record) => record.sessionId === ref);
+    if (exact)
+        return exact;
+    const prefix = records.filter((record) => record.sessionId.startsWith(ref));
+    if (prefix.length === 1)
+        return prefix[0] ?? null;
+    const pid = Number(ref);
+    if (Number.isInteger(pid) && pid > 0)
+        return records.find((record) => record.pid === pid) ?? null;
+    return null;
+}
+export function redactLaunchArgv(argv, secretTexts) {
+    const secrets = secretTexts.map((value) => value.trim()).filter((value) => value.length > 0);
+    return argv.map((arg) => (secrets.some((secret) => arg.includes(secret)) ? '[redacted]' : arg));
+}
+export async function appendLaunchAttempt(store, attempt) {
+    const parsed = launchAttemptSchema.parse({ ...attempt, attemptId: attempt.attemptId ?? crypto.randomUUID() });
+    const stamp = parsed.createdAt.replace(/[:.]/g, '-');
+    const id = `attempt:${parsed.attemptId}.${parsed.phase}.${stamp}`;
+    if (!(await createExclusiveRow(store, id, 'attempt', parsed.sessionId, parsed))) {
+        throw new CapabilityError('A launch attempt with this identity already exists.', 'CONFLICT', {
+            reason: 'launch-attempt-exists',
+            retryable: false
+        });
+    }
+    return parsed;
+}
+function oldestFirst(left, right) {
+    return left.createdAt < right.createdAt ? -1 : left.createdAt > right.createdAt ? 1 : 0;
+}
+export async function listLaunchAttempts(store, sessionId) {
+    const rows = await store.rows.list('attempt', sessionId);
+    return rows.map((row) => parseStored(launchAttemptSchema, row.body)).sort(oldestFirst);
+}
+async function listAllLaunchAttempts(store) {
+    return (await store.rows.list('attempt')).map((row) => parseStored(launchAttemptSchema, row.body));
+}
+function latestByKey(attempts) {
+    const latest = new Map();
+    for (const attempt of attempts) {
+        const current = latest.get(attempt.idempotencyKey);
+        if (!current || current.createdAt <= attempt.createdAt)
+            latest.set(attempt.idempotencyKey, attempt);
+    }
+    return [...latest.values()];
+}
+export function attemptStillOpen(attempt) {
+    return !attempt.exitObserved || attempt.phase !== 'exited';
+}
+/**
+ * The canonical spelling of a workspace path: absolute, with every symlink
+ * resolved through the filesystem's `stat`. A part that does not exist yet
+ * keeps its spelling. More than {@link MAX_SYMLINK_HOPS} links is refused
+ * `INVALID_INPUT` `launch-workspace-symlink-loop`.
+ */
+export async function canonicalWorkspacePath(store, cwd) {
+    const pending = resolve('/', cwd).split('/').filter(Boolean);
+    let current = '/';
+    let hops = 0;
+    while (pending.length > 0) {
+        const part = pending.shift() ?? '';
+        if (part === '.')
+            continue;
+        if (part === '..') {
+            current = dirname(current);
+            continue;
+        }
+        const candidate = join(current, part);
+        let stat;
+        try {
+            stat = await store.fs.stat(candidate);
+        }
+        catch (error) {
+            const cause = CaughtFailureSchema.parse(error);
+            const failure = valueFreeFailure(cause);
+            if (failure.code === 'ENOENT')
+                return join(candidate, ...pending);
+            if (failure.code === 'ELOOP') {
+                throw new CapabilityError('The workspace path has too many symbolic links to resolve.', 'INVALID_INPUT', {
+                    reason: 'launch-workspace-symlink-loop',
+                    retryable: false,
+                    cause
+                });
+            }
+            if (isCapabilityError(cause))
+                throw cause;
+            const refusal = externalPathStatRefusal(cause);
+            throw new CapabilityError(refusal.message, refusal.code, { reason: refusal.reason, cause });
+        }
+        if (stat.kind !== 'symlink' || stat.symlinkTarget === undefined) {
+            current = candidate;
+            continue;
+        }
+        hops += 1;
+        if (hops > MAX_SYMLINK_HOPS) {
+            throw new CapabilityError('The workspace path has too many symbolic links to resolve.', 'INVALID_INPUT', {
+                reason: 'launch-workspace-symlink-loop',
+                retryable: false
+            });
+        }
+        pending.unshift(...stat.symlinkTarget.split('/').filter(Boolean));
+        if (isAbsolute(stat.symlinkTarget))
+            current = '/';
+    }
+    return current;
+}
+function claimDigest(value) {
+    let high = 0x811c9dc5;
+    let low = 0x01000193;
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        high ^= code;
+        high = Math.imul(high, 0x01000193);
+        low ^= code + index;
+        low = Math.imul(low, 0x01000193);
+    }
+    return `${(high >>> 0).toString(16)}-${(low >>> 0).toString(16)}-${value.length.toString(16)}`;
+}
+/** The row id of the claim for an idempotency key or a canonical workspace. */
+function claimPath(_home, kind, value) {
+    return `claim:${kind}-${claimDigest(value)}`;
+}
+const LaunchClaimFileSchema = z.object({
+    attemptId: z.string(),
+    sessionId: z.string(),
+    idempotencyKey: z.string(),
+    cwd: z.string(),
+    harness: z.string(),
+    toolId: z.string(),
+    principalId: z.string(),
+    disposition: z.enum(['open', 'completed']).catch('open'),
+    ownerPid: z.number()
+});
+async function readClaim(store, path) {
+    return (await readStored(store, LaunchClaimFileSchema, path)) ?? null;
+}
+/** The workspace already has a writer: refused `CONFLICT` `launch-workspace-claimed`, naming the holder's attempt. */
+export function workspaceClaimedRefusal(attemptId) {
+    return new CapabilityError('This workspace already has a writer.', 'CONFLICT', {
+        reason: 'launch-workspace-claimed',
+        retryable: false,
+        details: { attemptId },
+        recoveryHint: attemptId
+            ? `Open attempt ${attemptId} already owns this workspace. Not returning another session's state.`
+            : 'Wait until that attempt records an observed exit.'
+    });
+}
+/** One exclusive file per key and one per canonical workspace. The second caller loses. */
+export async function claimLaunchWriter(store, input) {
+    const cwd = await canonicalWorkspacePath(store, input.cwd);
+    const keyPath = claimPath(store.home, 'key', input.idempotencyKey);
+    const replay = (claim) => claim && claim.idempotencyKey === input.idempotencyKey
+        ? { kind: 'replay', attemptId: claim.attemptId, sessionId: claim.sessionId, disposition: claim.disposition }
+        : { kind: 'conflict', attemptId: null, reason: 'Launch key claim is unreadable.' };
+    const existing = await readClaim(store, keyPath);
+    if (existing) {
+        if (existing.idempotencyKey !== input.idempotencyKey) {
+            return { kind: 'conflict', attemptId: null, reason: 'Launch key claim does not match its path.' };
+        }
+        return replay(existing);
+    }
+    const attemptId = crypto.randomUUID();
+    const claim = {
+        attemptId,
+        sessionId: input.sessionId,
+        idempotencyKey: input.idempotencyKey,
+        cwd,
+        harness: input.harness,
+        toolId: input.toolId,
+        principalId: `participant-launch-${input.harness}`,
+        disposition: 'open',
+        ownerPid: store.ownerPid()
+    };
+    if (!(await createExclusiveRow(store, keyPath, 'claim', input.sessionId, claim)))
+        return replay(await readClaim(store, keyPath));
+    const workspacePath = claimPath(store.home, 'workspace', cwd);
+    const publish = () => createExclusiveRow(store, workspacePath, 'claim', input.sessionId, claim);
+    // A read-only participant writes nothing, so it takes no workspace writer claim.
+    const claimed = input.readOnly === true || (await publish()) || ((await releaseStaleWorkspaceClaim(store, workspacePath)) && (await publish()));
+    if (!claimed) {
+        // Roll back the key this call just created; the workspace's holder keeps it.
+        await removeIfPresent(store, keyPath);
+        throw workspaceClaimedRefusal((await readClaim(store, workspacePath))?.attemptId ?? null);
+    }
+    return {
+        kind: 'started',
+        attempt: await appendLaunchAttempt(store, {
+            ...input,
+            attemptId,
+            cwd,
+            phase: 'intent',
+            exitObserved: false,
+            createdAt: new Date().toISOString()
+        })
+    };
+}
+function selectionConflict(claim, selection, cwd) {
+    if (cwd !== claim.cwd)
+        return 'Launch workspace does not match the original attempt.';
+    if (selection.harness !== claim.harness)
+        return 'Launch harness does not match the original attempt.';
+    // principalId on the claim is only a launch-participant label. It is not a human or team principal.
+    if (!selection.toolId || selection.toolId !== claim.toolId)
+        return 'Launch host does not match the original attempt.';
+    if (selection.sessionId && selection.sessionId !== claim.sessionId) {
+        return 'Launch session does not match the original attempt.';
+    }
+    return undefined;
+}
+/** Read a prior key before any session is created. A mismatched authority is a conflict. */
+export async function lookupLaunchReplay(store, idempotencyKey, selection) {
+    const path = claimPath(store.home, 'key', idempotencyKey);
+    const claim = await readClaim(store, path);
+    if (claim === null)
+        return { kind: 'absent' };
+    if (claim.idempotencyKey !== idempotencyKey) {
+        return { kind: 'conflict', sessionId: null, attemptId: null, reason: 'Launch key claim is unreadable.' };
+    }
+    const conflict = selectionConflict(claim, selection, await canonicalWorkspacePath(store, selection.cwd));
+    if (conflict)
+        return { kind: 'conflict', sessionId: claim.sessionId, attemptId: claim.attemptId, reason: conflict };
+    if (!claim.sessionId) {
+        return {
+            kind: 'conflict',
+            sessionId: null,
+            attemptId: claim.attemptId,
+            reason: (await store.isAlive(claim.ownerPid))
+                ? 'Launch reservation is in progress.'
+                : 'Launch reservation has no bound session; recovery is required before retry.'
+        };
+    }
+    const record = await readLaunchRecord(store, claim.sessionId);
+    if (record?.attemptId === claim.attemptId)
+        return { kind: 'record', record };
+    return { kind: 'pending', sessionId: claim.sessionId, attemptId: claim.attemptId };
+}
+/** Reserve the key and workspace before any session exists. The loser does not prepare. */
+export async function reserveLaunchKey(store, input) {
+    const selection = { cwd: input.cwd, harness: input.harness, toolId: input.toolId };
+    const existing = await lookupLaunchReplay(store, input.idempotencyKey, selection);
+    const keyPath = claimPath(store.home, 'key', input.idempotencyKey);
+    if (existing.kind === 'absent') {
+        const cwd = await canonicalWorkspacePath(store, input.cwd);
+        const attemptId = crypto.randomUUID();
+        const claim = {
+            attemptId,
+            sessionId: '',
+            idempotencyKey: input.idempotencyKey,
+            cwd,
+            harness: input.harness,
+            toolId: input.toolId,
+            principalId: `participant-launch-${input.harness}`,
+            disposition: 'open',
+            ownerPid: store.ownerPid()
+        };
+        if (await createExclusiveRow(store, keyPath, 'claim', '', claim)) {
+            if (input.readOnly === true || (await createExclusiveRow(store, claimPath(store.home, 'workspace', cwd), 'claim', '', claim))) {
+                return { kind: 'reserved', attemptId };
+            }
+            // The workspace has another writer: roll back the key this call created.
+            await removeIfPresent(store, keyPath);
+        }
+    }
+    const claim = await readClaim(store, keyPath);
+    // A dead owner is not proof that createSession did not commit before the
+    // reservation could be bound. Keep both claims until recovery can reconcile
+    // the Session; retrying here could create a second, orphaned Session.
+    if (claim && !claim.sessionId && !(await store.isAlive(claim.ownerPid))) {
+        return {
+            kind: 'conflict',
+            sessionId: null,
+            attemptId: claim.attemptId,
+            reason: 'Launch reservation has no bound session; recovery is required before retry.'
+        };
+    }
+    return existing.kind === 'absent'
+        ? { kind: 'conflict', sessionId: null, attemptId: claim?.attemptId ?? null, reason: 'Launch reservation is in progress.' }
+        : existing;
+}
+export async function bindLaunchSession(store, idempotencyKey, sessionId) {
+    const path = claimPath(store.home, 'key', idempotencyKey);
+    const claim = await readClaim(store, path);
+    if (!claim || claim.idempotencyKey !== idempotencyKey)
+        return;
+    await writeRow(store, path, 'claim', sessionId, { ...claim, sessionId });
+    // A read-only reservation took no workspace claim; only bind one this key holds.
+    const workspacePath = claimPath(store.home, 'workspace', claim.cwd);
+    if ((await readClaim(store, workspacePath))?.idempotencyKey === idempotencyKey) {
+        await writeRow(store, workspacePath, 'claim', sessionId, { ...claim, sessionId });
+    }
+}
+/** Records an exit the owner observed. A live pid probe is not this record. */
+export async function recordObservedLaunchExit(store, input) {
+    const cwd = await canonicalWorkspacePath(store, input.cwd);
+    const dispatched = (await listLaunchAttempts(store, input.sessionId)).find((attempt) => attempt.idempotencyKey === input.idempotencyKey && attempt.phase === 'dispatched' && attempt.pid === input.pid);
+    if (!dispatched) {
+        throw new CapabilityError('No dispatched launch attempt matches that pid.', 'NOT_FOUND', {
+            reason: 'launch-attempt-not-dispatched',
+            retryable: false
+        });
+    }
+    if (await store.isAlive(input.pid)) {
+        throw new CapabilityError('The launched process is still alive.', 'CONFLICT', {
+            reason: 'launch-process-alive',
+            retryable: true
+        });
+    }
+    const keyPath = claimPath(store.home, 'key', input.idempotencyKey);
+    const claim = await readClaim(store, keyPath);
+    const recorded = await appendLaunchAttempt(store, {
+        ...input,
+        attemptId: claim?.attemptId ?? dispatched.attemptId,
+        cwd,
+        phase: 'exited',
+        exitObserved: true,
+        createdAt: new Date().toISOString()
+    });
+    if (claim && claim.idempotencyKey === input.idempotencyKey) {
+        await writeRow(store, keyPath, 'claim', claim.sessionId, { ...claim, disposition: 'completed', cwd });
+    }
+    await releaseWorkspaceClaim(store, claimPath(store.home, 'workspace', cwd), input.idempotencyKey);
+    return recorded;
+}
+/**
+ * Records the exit of a supervised launch: PM ran the harness and its exit was
+ * observed by awaiting it, so there is no pid to probe. The attempt is marked
+ * exited, the key claim completed, and the workspace claim released.
+ */
+export async function completeSupervisedLaunch(store, input) {
+    const cwd = await canonicalWorkspacePath(store, input.cwd);
+    const recorded = await appendLaunchAttempt(store, {
+        ...input,
+        cwd,
+        phase: 'exited',
+        exitObserved: true,
+        createdAt: new Date().toISOString()
+    });
+    const keyPath = claimPath(store.home, 'key', input.idempotencyKey);
+    const claim = await readClaim(store, keyPath);
+    if (claim && claim.idempotencyKey === input.idempotencyKey) {
+        await writeRow(store, keyPath, 'claim', claim.sessionId, { ...claim, disposition: 'completed', cwd });
+    }
+    await releaseWorkspaceClaim(store, claimPath(store.home, 'workspace', cwd), input.idempotencyKey);
+    return recorded;
+}
+/**
+ * A workspace claim whose holder no longer writes is released so the next
+ * launch can claim the workspace: its latest attempt observed its exit; or it
+ * was dispatched and its pid is no longer running (that exit is recorded); or
+ * it never dispatched and the process that claimed it is gone. A live holder
+ * keeps its claim. Answers whether the claim was released.
+ */
+async function releaseStaleWorkspaceClaim(store, workspacePath) {
+    const holder = await readClaim(store, workspacePath);
+    if (!holder)
+        return true;
+    const latest = latestByKey(await listLaunchAttempts(store, holder.sessionId)).find((attempt) => attempt.idempotencyKey === holder.idempotencyKey);
+    if (latest && !attemptStillOpen(latest)) {
+        await releaseWorkspaceClaim(store, workspacePath, holder.idempotencyKey);
+        return true;
+    }
+    if (latest?.phase === 'dispatched' && latest.pid !== undefined) {
+        if (await store.isAlive(latest.pid))
+            return false;
+        await recordObservedLaunchExit(store, {
+            sessionId: latest.sessionId,
+            idempotencyKey: latest.idempotencyKey,
+            cwd: latest.cwd,
+            harness: latest.harness,
+            toolId: latest.toolId,
+            mode: latest.mode,
+            command: latest.command,
+            pid: latest.pid
+        });
+        return true;
+    }
+    if (await store.isAlive(holder.ownerPid))
+        return false;
+    await releaseWorkspaceClaim(store, workspacePath, holder.idempotencyKey);
+    return true;
+}
+/** Release the workspace claim this key holds; another key's claim, or none, is left alone. */
+async function releaseWorkspaceClaim(store, path, idempotencyKey) {
+    const claim = await readClaim(store, path);
+    if (claim?.idempotencyKey !== idempotencyKey)
+        return;
+    await removeIfPresent(store, path);
+}
+/** An open attempt for this key or workspace must not gain a second writer. */
+export async function findBlockingLaunchAttempt(store, input) {
+    const latest = latestByKey(await listAllLaunchAttempts(store));
+    return (latest.find((attempt) => attemptStillOpen(attempt) && (attempt.idempotencyKey === input.idempotencyKey || attempt.cwd === input.cwd)) ?? null);
+}
+//# sourceMappingURL=store.js.map