@vibesdotdev/pm 0.0.0-stage → 1.0.0-rc.3

package/dist/utils/bounded-wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-wait.d.ts","sourceRoot":"","sources":["../../src/utils/bounded-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAqB,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAI7F,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;AAE7D,MAAM,WAAW,gBAAgB;IAChC,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,iHAAiH;AACjH,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAE7D;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC9B,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAC7B,OAAO,EAAE,gBAAgB,GACvB,OAAO,CAAC,OAAO,CAAC,CAalB"}

package/dist/utils/bounded-wait.js

@@ -0,0 +1,35 @@
+/**
+ * PM's bounded waits over the runtime lifecycle (RC07).
+ *
+ * A wait awaits the owner's event or readiness promise inside
+ * `runtime.lifecycle.wait`, bounded by a deadline, the invocation's signal and
+ * the runtime's own disposal. Where the owner offers no event, `pollUntil`
+ * re-checks with `runtime.lifecycle.delay` inside that same wait; each caller
+ * names the owner and the missing event beside the call, so the poll is
+ * visible debt, never a hand-rolled sleep.
+ */
+import { isCapabilityError } from '@vibesdotdev/kernel';
+import { attempt } from "./attempt.js";
+import { rethrowFailure } from "../helpers/failure.js";
+/** Whether `error` is the lifecycle's deadline (`TIMEOUT` `wait-timeout`), the one outcome read as "not yet". */
+export function isWaitTimeout(failure) {
+    return failure instanceof Error && isCapabilityError(failure) && failure.code === 'TIMEOUT' && failure.reason === 'wait-timeout';
+}
+/**
+ * Re-check `check` until it answers true (resolves true) or the deadline
+ * passes (resolves false). A check that throws, a caller abort and the
+ * runtime's disposal reject with their own error.
+ */
+export async function pollUntil(runtime, check, options) {
+    const waited = await attempt(() => runtime.lifecycle.wait(async (signal) => {
+        while (!(await check()))
+            await runtime.lifecycle.delay(options.intervalMs, signal);
+        return true;
+    }, { timeoutMs: options.timeoutMs, reason: options.reason, signal: options.signal }));
+    if (waited.ok)
+        return waited.value;
+    if (isWaitTimeout(waited.failure))
+        return false;
+    return rethrowFailure(waited.failure);
+}
+//# sourceMappingURL=bounded-wait.js.map

package/dist/utils/bounded-wait.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-wait.js","sourceRoot":"","sources":["../../src/utils/bounded-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,iBAAiB,EAAuC,MAAM,qBAAqB,CAAC;AAC7F,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAevD,iHAAiH;AACjH,MAAM,UAAU,aAAa,CAAC,OAAsB;IACnD,OAAO,OAAO,YAAY,KAAK,IAAI,iBAAiB,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,cAAc,CAAC;AAClI,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC9B,OAAyB,EACzB,KAA6B,EAC7B,OAAyB;IAEzB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,CACjC,OAAO,CAAC,SAAS,CAAC,IAAI,CACrB,KAAK,EAAE,MAAM,EAAE,EAAE;QAChB,OAAO,CAAC,CAAC,MAAM,KAAK,EAAE,CAAC;YAAE,MAAM,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QACnF,OAAO,IAAI,CAAC;IACb,CAAC,EACD,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAChF,CACD,CAAC;IACF,IAAI,MAAM,CAAC,EAAE;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC;IACnC,IAAI,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAChD,OAAO,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AACvC,CAAC"}

package/dist/utils/command-exists.d.ts

@@ -0,0 +1,5 @@
+/** Command readiness through the supplied runtime's execution owner. */
+import type { RuntimeRef } from '@vibesdotdev/kernel';
+/** Explicit PATH overrides stay exact; otherwise the host uses its captured facts. */
+export declare function commandExists(runtime: RuntimeRef, command: string, pathEnv?: string): Promise<boolean>;
+//# sourceMappingURL=command-exists.d.ts.map

package/dist/utils/command-exists.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-exists.d.ts","sourceRoot":"","sources":["../../src/utils/command-exists.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD,sFAAsF;AACtF,wBAAsB,aAAa,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAI5G"}

package/dist/utils/command-exists.js

@@ -0,0 +1,8 @@
+import { getRuntimeExecution } from '@vibesdotdev/kernel/execution';
+/** Explicit PATH overrides stay exact; otherwise the host uses its captured facts. */
+export async function commandExists(runtime, command, pathEnv) {
+    const execution = await getRuntimeExecution(runtime);
+    const options = pathEnv === undefined ? undefined : { env: { PATH: pathEnv } };
+    return (await execution.resolveCommand(command, options)) !== null;
+}
+//# sourceMappingURL=command-exists.js.map

package/dist/utils/command-exists.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-exists.js","sourceRoot":"","sources":["../../src/utils/command-exists.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEpE,sFAAsF;AACtF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAmB,EAAE,OAAe,EAAE,OAAgB;IACzF,MAAM,SAAS,GAAG,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC;IAC/E,OAAO,CAAC,MAAM,SAAS,CAAC,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,KAAK,IAAI,CAAC;AACpE,CAAC"}

package/dist/utils/daemon-launch-lock.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Daemon Launch Lock
+ *
+ * PM's launch custody over the filesystem owner's lease queue
+ * (`@vibesdotdev/filesystem` `acquireLease`, moved here from PM on
+ * 2026-10-11, decision D): immutable uniquely named claims, bakery admission,
+ * exact-path release. What stays PM's own:
+ *
+ * - Launch guards: once custody is held, a launch reserves an `unresolved`
+ *   claim of its generation before spawning, and a `child` receipt once it
+ *   owns a child. They are generation claims of the queue
+ *   (`publishGenerationClaim`) whose staleness is PM's policy
+ *   ({@link pmLaunchClaimStaleness}).
+ * - Staleness policy: an `unresolved` guard is retained until its
+ *   generation's `child` receipt is gone; a `child` receipt is stale once its
+ *   child is gone; an ordinary claim is stale when its owner is gone OR its
+ *   heartbeat is older than 30 s. That last rule is PM's recovery policy
+ *   (stalled launchers), not exclusion-safe: it can retire a live owner
+ *   (SPEC).
+ * - The heartbeat that feeds that age: the lifecycle `touch` of the claim
+ *   every 5 s while waiting and holding, started through the queue's
+ *   `onClaim` and stopped with the claim. `touch` never creates, so a beat
+ *   that finishes after release cannot bring the claim back.
+ * - Bare-PID lockfiles from the pre-lease implementation stay visible and
+ *   recoverable during the cutover (the queue's `admissible` gate).
+ *
+ * Timers are the handed runtime's (RC07).
+ */
+import { type PMPathOptions, type VibesHomeResolverOptions } from './vibes-home.ts';
+import { type CaughtFailure, type Disposer, type RuntimeRef } from '@vibesdotdev/kernel';
+import { type LeaseClaimObservation, type LeaseQueueLease } from '@vibesdotdev/filesystem';
+/**
+ * What the lock uses from the runtime it is handed: its filesystem, process
+ * service, lifecycle timers and waits, and its Logging for a heartbeat that
+ * fails (C083a).
+ */
+export type LaunchLockRuntime = RuntimeRef;
+export declare const PM_DAEMON_LAUNCH_HEADROOM_MS = 10000;
+export interface DaemonLaunchLockLease {
+    lockFile: string;
+    claimFile: string;
+    ownerPid: number;
+    token: string;
+    order: string;
+    /** The runtime whose filesystem holds this lease's files. */
+    runtime: LaunchLockRuntime;
+    /** The queue lease this launch custody is. */
+    queueLease: LeaseQueueLease;
+    /** Stops this lease's heartbeat (a lifecycle timer); idempotent. */
+    stopHeartbeat: Disposer;
+    /** Set when the lease is released: a heartbeat still in flight then ends instead of beating again. */
+    released?: boolean;
+    /** Set before spawning; cleared only when failure is known to leave no child. */
+    preserveOnFailure: boolean;
+    /** A new immutable claim that protects the child independently of this launcher. */
+    childClaimFile?: string;
+    unresolvedClaimFile?: string;
+}
+export interface DaemonLaunchLockState {
+    exists: boolean;
+    holderPid: number | null;
+    ageMs: number | null;
+    stale: boolean;
+    guard?: 'unresolved' | 'child';
+    claimFile?: string;
+}
+/**
+ * PM's launch-claim staleness over the lease queue. An `unresolved` guard is
+ * retained until its generation's `child` receipt is gone (retention: always
+ * exclusion-safe); a `child` receipt is stale once its child is gone; an
+ * ordinary claim is stale when its owner is gone, or when its heartbeat is
+ * older than 30 s. That age rule is PM's declared recovery policy for stalled
+ * launchers and is NOT exclusion-safe: it can retire a live owner (SPEC).
+ */
+export declare function pmLaunchClaimStaleness(claim: LeaseClaimObservation, generation: readonly LeaseClaimObservation[]): boolean;
+/** Read current launch custody through `runtime`'s filesystem without mutating or waiting on it. */
+export declare function readDaemonLaunchLockState(runtime: LaunchLockRuntime, lockFile: string, nowMs?: number): Promise<DaemonLaunchLockState>;
+/**
+ * The launch lock of a workspace's PM daemon, by its admitted workspace's
+ * tooling id, under the handed roots' active home; there is no default.
+ */
+export declare function getDaemonLaunchLockPath(toolingId: string, options: PMPathOptions | VibesHomeResolverOptions): string;
+export interface AcquireLockOptions {
+    timeoutMs: number;
+    /** Override the PID stamped into the claim. Tests use this. */
+    ownerPid?: number;
+    /** Override `Date.now`. Tests use this. */
+    now?: () => number;
+    /** The claim's heartbeat period; defaults to 5s. Tests shorten it. */
+    heartbeatMs?: number;
+    /** PM daemon launches reserve a fail-closed outcome before any child can exist. */
+    unresolvedLaunch?: boolean;
+}
+export declare function resolvePMDaemonStartTimeoutMs(value: string | number | null | undefined): number;
+export declare function getPMDaemonLaunchLockTimeoutMs(startTimeoutMs: number): number;
+/** The reason of the launch-lock acquisition timeout (a possibly orphaned guard, not a crash). */
+export declare const LAUNCH_LOCK_TIMEOUT_REASON = "pm-daemon-launch-lock-timeout";
+/** Whether `failure` is a launch-lock acquisition timeout (a possibly orphaned guard, not a crash). */
+export declare function isLaunchLockTimeoutError(failure: CaughtFailure): boolean;
+export declare function withDaemonLaunchLock<T>(runtime: LaunchLockRuntime, lockFile: string, timeoutMs: number, action: (lease: DaemonLaunchLockLease) => Promise<T>, options?: {
+    unresolvedLaunch?: boolean;
+}): Promise<T>;
+/**
+ * Acquire launch custody: the queue lease under PM's staleness policy, the
+ * claim heartbeat started with the claim, and the pre-lease lockfile as an
+ * extra admission gate. With `unresolvedLaunch`, an `unresolved` guard of the
+ * generation is published before the lease is handed over.
+ */
+export declare function acquireDaemonLaunchLock(runtime: LaunchLockRuntime, lockFile: string, opts: AcquireLockOptions): Promise<DaemonLaunchLockLease | null>;
+export declare function releaseDaemonLaunchLock(lease: DaemonLaunchLockLease): Promise<void>;
+/**
+ * The queue's oldest generation, when it holds an unresolved launch guard: the
+ * only generation orphan recovery may consider. A younger unresolved guard
+ * behind a live head is not blocking anyone; a stale ordinary corpse ahead of
+ * an orphan clears on the next acquire poll, and recovery runs again after it.
+ */
+export interface OldestUnresolvedLaunchGeneration {
+    order: string;
+    token: string;
+    /** The launcher pid from the unresolved record (never the guarded child's). */
+    holderPid: number;
+    /** Age of the unresolved guard file: the launch failed this long ago. */
+    ageMs: number;
+    unresolvedClaimFile: string;
+    /** A published child receipt for this exact generation (a known child). */
+    hasChildGuard: boolean;
+    childPid: number | null;
+}
+export declare function inspectOldestUnresolvedGeneration(runtime: LaunchLockRuntime, lockFile: string, nowMs?: number): Promise<OldestUnresolvedLaunchGeneration | null>;
+/**
+ * Remove exactly the claim files whose parsed record matches (`order`, `token`):
+ * the orphaned generation and nothing else. Unparseable files are never
+ * touched, and removal is idempotent under concurrent removers.
+ */
+export declare function removeLaunchClaimGeneration(runtime: LaunchLockRuntime, lockFile: string, order: string, token: string): Promise<string[]>;
+/**
+ * Retain the same queue position for the exact child the launch owns. Write a
+ * new immutable claim before removing anything; a failed write leaves the
+ * unresolved original intact. A live/reused/unreadable pid blocks rather than
+ * granting another launch. This never signals or adopts a process.
+ */
+export declare function guardDaemonLaunchChild(lease: DaemonLaunchLockLease, childPid: number): Promise<void>;
+//# sourceMappingURL=daemon-launch-lock.d.ts.map

package/dist/utils/daemon-launch-lock.d.ts.map

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

package/dist/utils/daemon-launch-lock.js

@@ -0,0 +1,420 @@
+/**
+ * Daemon Launch Lock
+ *
+ * PM's launch custody over the filesystem owner's lease queue
+ * (`@vibesdotdev/filesystem` `acquireLease`, moved here from PM on
+ * 2026-10-11, decision D): immutable uniquely named claims, bakery admission,
+ * exact-path release. What stays PM's own:
+ *
+ * - Launch guards: once custody is held, a launch reserves an `unresolved`
+ *   claim of its generation before spawning, and a `child` receipt once it
+ *   owns a child. They are generation claims of the queue
+ *   (`publishGenerationClaim`) whose staleness is PM's policy
+ *   ({@link pmLaunchClaimStaleness}).
+ * - Staleness policy: an `unresolved` guard is retained until its
+ *   generation's `child` receipt is gone; a `child` receipt is stale once its
+ *   child is gone; an ordinary claim is stale when its owner is gone OR its
+ *   heartbeat is older than 30 s. That last rule is PM's recovery policy
+ *   (stalled launchers), not exclusion-safe: it can retire a live owner
+ *   (SPEC).
+ * - The heartbeat that feeds that age: the lifecycle `touch` of the claim
+ *   every 5 s while waiting and holding, started through the queue's
+ *   `onClaim` and stopped with the claim. `touch` never creates, so a beat
+ *   that finishes after release cannot bring the claim back.
+ * - Bare-PID lockfiles from the pre-lease implementation stay visible and
+ *   recoverable during the cutover (the queue's `admissible` gate).
+ *
+ * Timers are the handed runtime's (RC07).
+ */
+import { getVibesDir } from "./vibes-home.js";
+import { CapabilityError, getRuntimeHostIdentity, isCapabilityError } from '@vibesdotdev/kernel';
+import { getRuntimeProcessService } from '@vibesdotdev/kernel/process';
+import { getLogger } from '@vibesdotdev/logging';
+import { acquireLease, LeaseClaimRecordSchema, publishGenerationClaim, readLeaseQueue, releaseLease, removeLeaseGeneration } from '@vibesdotdev/filesystem';
+import { touchChecked } from '@vibesdotdev/filesystem/core';
+import { attempt, attemptSync, failureLabel } from "./attempt.js";
+import { hasErrno, rethrowFailure } from "../helpers/failure.js";
+import { pmFileSystem, readTextFileIfPresent } from "../helpers/runtime-files.js";
+import { joinUnder } from "./path-under.js";
+const STALE_MTIME_MS = 30_000;
+const HEARTBEAT_INTERVAL_MS = 5_000;
+export const PM_DAEMON_LAUNCH_HEADROOM_MS = 10_000;
+/**
+ * PM's launch-claim staleness over the lease queue. An `unresolved` guard is
+ * retained until its generation's `child` receipt is gone (retention: always
+ * exclusion-safe); a `child` receipt is stale once its child is gone; an
+ * ordinary claim is stale when its owner is gone, or when its heartbeat is
+ * older than 30 s. That age rule is PM's declared recovery policy for stalled
+ * launchers and is NOT exclusion-safe: it can retire a live owner (SPEC).
+ */
+export function pmLaunchClaimStaleness(claim, generation) {
+    if (claim.record.guard === 'unresolved') {
+        const child = generation.find((candidate) => candidate.record.guard === 'child');
+        return child ? child.ownerGone : false;
+    }
+    if (claim.record.guard === 'child')
+        return claim.ownerGone;
+    return claim.ownerGone || claim.ageMs > STALE_MTIME_MS;
+}
+/** The pid a pre-lease lockfile's text names, if it names one. */
+function parseLegacyHolderPid(text) {
+    const trimmed = text.trim();
+    if (!/^[1-9]\d*$/.test(trimmed))
+        return undefined;
+    const pid = Number(trimmed);
+    return Number.isSafeInteger(pid) ? pid : undefined;
+}
+/** A pre-lease lockfile's state, from its mtime and the pid its text names. */
+function legacyState(mtimeMs, holderPid, nowMs, alive) {
+    if (mtimeMs === undefined)
+        return { exists: false, holderPid: null, ageMs: null, stale: false };
+    const ageMs = Math.max(0, nowMs - mtimeMs);
+    return {
+        exists: true,
+        holderPid: holderPid ?? null,
+        ageMs,
+        stale: (holderPid !== undefined && !alive(holderPid)) || ageMs > STALE_MTIME_MS
+    };
+}
+/** The lock state a queue's oldest claim describes. */
+function queueState(claims) {
+    const first = claims[0];
+    if (!first)
+        return { exists: false, holderPid: null, ageMs: null, stale: false };
+    const state = {
+        exists: true,
+        holderPid: first.record.pid,
+        ageMs: first.ageMs,
+        stale: first.stale
+    };
+    const guard = first.record.guard;
+    if (guard === 'unresolved' || guard === 'child') {
+        state.guard = guard;
+        state.claimFile = first.claimFile;
+    }
+    return state;
+}
+/** Whether a mtime string off the filesystem kind is usable: ms since epoch, or `undefined` when it carries none. */
+function mtimeMsOf(mtime) {
+    const ms = Date.parse(mtime ?? '');
+    return Number.isNaN(ms) ? undefined : ms;
+}
+/** Read current launch custody through `runtime`'s filesystem without mutating or waiting on it. */
+export async function readDaemonLaunchLockState(runtime, lockFile, nowMs = Date.now()) {
+    const io = await openLockIO(runtime);
+    const legacy = await inspectLegacyLock(io, lockFile, nowMs);
+    if (legacy.exists)
+        return legacy;
+    return queueState(await readLeaseQueue(runtime, lockFile, { staleness: pmLaunchClaimStaleness, nowMs }));
+}
+/**
+ * The launch lock of a workspace's PM daemon, by its admitted workspace's
+ * tooling id, under the handed roots' active home; there is no default.
+ */
+export function getDaemonLaunchLockPath(toolingId, options) {
+    return joinUnder(options, getVibesDir(options), 'pm', `daemon-launch-${toolingId}.lock`);
+}
+export function resolvePMDaemonStartTimeoutMs(value) {
+    const configured = Number(value ?? '');
+    return Number.isFinite(configured) && configured > 0 ? configured : 30_000;
+}
+export function getPMDaemonLaunchLockTimeoutMs(startTimeoutMs) {
+    return startTimeoutMs + PM_DAEMON_LAUNCH_HEADROOM_MS;
+}
+/** The reason of the launch-lock acquisition timeout (a possibly orphaned guard, not a crash). */
+export const LAUNCH_LOCK_TIMEOUT_REASON = 'pm-daemon-launch-lock-timeout';
+/** Whether `failure` is a launch-lock acquisition timeout (a possibly orphaned guard, not a crash). */
+export function isLaunchLockTimeoutError(failure) {
+    return isCapabilityError(failure) && failure.reason === LAUNCH_LOCK_TIMEOUT_REASON;
+}
+export async function withDaemonLaunchLock(runtime, lockFile, timeoutMs, action, options = {}) {
+    const lease = await acquireDaemonLaunchLock(runtime, lockFile, { timeoutMs, ...options });
+    if (!lease) {
+        throw new CapabilityError(`Failed to acquire daemon launch lock (timeout ${timeoutMs}ms)`, 'TIMEOUT', {
+            reason: LAUNCH_LOCK_TIMEOUT_REASON,
+            retryable: true,
+            details: { timeoutMs, lockFile }
+        });
+    }
+    let completed = false;
+    try {
+        const result = await action(lease);
+        completed = true;
+        return result;
+    }
+    finally {
+        if (!completed && lease.preserveOnFailure) {
+            lease.stopHeartbeat();
+            const files = await pmFileSystem(runtime);
+            // Guards keep the acquired queue position without turning a crashed
+            // waiting contender into permanent custody.
+            if (lease.childClaimFile || lease.unresolvedClaimFile)
+                await releaseLease(lease.queueLease);
+            if (lease.childClaimFile && lease.unresolvedClaimFile)
+                await removeIfPresent(files, lease.unresolvedClaimFile);
+        }
+        else {
+            await releaseDaemonLaunchLock(lease);
+        }
+    }
+}
+/** Admit the supplied host's default owner without consulting it for an explicit owner. */
+async function hostPid(runtime) {
+    const pid = (await getRuntimeHostIdentity(runtime)).currentPid();
+    if (!Number.isSafeInteger(pid) || pid <= 0) {
+        throw new CapabilityError('The selected host supplied an invalid process identity.', 'INVALID_INPUT', {
+            reason: 'pm-host-pid-invalid', retryable: false
+        });
+    }
+    return pid;
+}
+/**
+ * Acquire launch custody: the queue lease under PM's staleness policy, the
+ * claim heartbeat started with the claim, and the pre-lease lockfile as an
+ * extra admission gate. With `unresolvedLaunch`, an `unresolved` guard of the
+ * generation is published before the lease is handed over.
+ */
+export async function acquireDaemonLaunchLock(runtime, lockFile, opts) {
+    const ownerPid = opts.ownerPid ?? await hostPid(runtime);
+    const now = opts.now ?? preciseWallClockMs;
+    const heartbeatMs = opts.heartbeatMs ?? HEARTBEAT_INTERVAL_MS;
+    const io = await openLockIO(runtime);
+    const leases = new Map();
+    const queueLease = await acquireLease(runtime, lockFile, {
+        timeoutMs: opts.timeoutMs,
+        reason: 'pm-daemon-launch-lock',
+        ownerPid,
+        now,
+        staleness: pmLaunchClaimStaleness,
+        // A pre-lease lockfile still holds custody; a stale one is reclaimed and re-checked next pass.
+        admissible: async () => !(await reclaimLegacyLock(io, lockFile, now())) && !(await inspectLegacyLock(io, lockFile, now())).exists,
+        onClaim: (claim) => {
+            const lease = {
+                lockFile: claim.lockFile,
+                claimFile: claim.claimFile,
+                ownerPid: claim.ownerPid,
+                token: claim.token,
+                order: claim.order,
+                runtime,
+                queueLease: claim,
+                stopHeartbeat: () => { },
+                preserveOnFailure: false
+            };
+            lease.stopHeartbeat = startHeartbeat(runtime, io.files, lease, heartbeatMs);
+            leases.set(claim, lease);
+            return () => lease.stopHeartbeat();
+        }
+    });
+    if (!queueLease)
+        return null;
+    const held = leases.get(queueLease);
+    if (!held)
+        throw new CapabilityError('The launch lease was granted without its claim.', 'INTERNAL', { reason: 'pm-launch-lease-unbound' });
+    if (opts.unresolvedLaunch) {
+        const unresolvedClaimFile = `${held.claimFile}.unresolved.claim`;
+        const written = await attempt(() => publishGenerationClaim(queueLease, unresolvedClaimFile, 'unresolved', ownerPid));
+        if (!written.ok) {
+            // No action has run: this exact generation cannot own a child. A guard
+            // that cannot be withdrawn either is kept beside the primary failure.
+            const withdrawn = await attempt(() => removeIfPresent(io.files, unresolvedClaimFile));
+            const failure = withdrawn.ok
+                ? written.failure
+                : new AggregateError([written.failure, withdrawn.failure], 'The unresolved launch guard failed and could not be withdrawn');
+            return releaseThenRethrow(held, failure);
+        }
+        held.unresolvedClaimFile = unresolvedClaimFile;
+    }
+    return held;
+}
+/** Release `lease`, then fail with `failure`; a release that fails too is kept beside it. */
+async function releaseThenRethrow(lease, failure) {
+    const released = await attempt(() => releaseDaemonLaunchLock(lease));
+    if (!released.ok)
+        throw new AggregateError([failure, released.failure], 'The launch claim failed and could not be released');
+    return rethrowFailure(failure);
+}
+export async function releaseDaemonLaunchLock(lease) {
+    lease.released = true;
+    lease.stopHeartbeat();
+    const files = await pmFileSystem(lease.runtime);
+    // Claim paths include a UUID and are never reused. Removing this exact path
+    // is generation-aware in one filesystem operation; no token/delete gap exists.
+    await releaseLease(lease.queueLease);
+    if (lease.childClaimFile)
+        await removeIfPresent(files, lease.childClaimFile);
+    if (lease.unresolvedClaimFile)
+        await removeIfPresent(files, lease.unresolvedClaimFile);
+}
+export async function inspectOldestUnresolvedGeneration(runtime, lockFile, nowMs = Date.now()) {
+    const claims = await readLeaseQueue(runtime, lockFile, { staleness: pmLaunchClaimStaleness, nowMs });
+    const oldest = claims[0];
+    if (!oldest)
+        return null;
+    const generation = claims.filter((candidate) => candidate.record.order === oldest.record.order && candidate.record.token === oldest.record.token);
+    const unresolved = generation.find((candidate) => candidate.record.guard === 'unresolved');
+    if (!unresolved)
+        return null;
+    const child = generation.find((candidate) => candidate.record.guard === 'child');
+    return {
+        order: unresolved.record.order,
+        token: unresolved.record.token,
+        holderPid: unresolved.record.pid,
+        ageMs: unresolved.ageMs,
+        unresolvedClaimFile: unresolved.claimFile,
+        hasChildGuard: child !== undefined,
+        childPid: child?.record.pid ?? null
+    };
+}
+/**
+ * Remove exactly the claim files whose parsed record matches (`order`, `token`):
+ * the orphaned generation and nothing else. Unparseable files are never
+ * touched, and removal is idempotent under concurrent removers.
+ */
+export async function removeLaunchClaimGeneration(runtime, lockFile, order, token) {
+    return removeLeaseGeneration(runtime, lockFile, order, token);
+}
+/**
+ * Retain the same queue position for the exact child the launch owns. Write a
+ * new immutable claim before removing anything; a failed write leaves the
+ * unresolved original intact. A live/reused/unreadable pid blocks rather than
+ * granting another launch. This never signals or adopts a process.
+ */
+export async function guardDaemonLaunchChild(lease, childPid) {
+    if (!Number.isSafeInteger(childPid) || childPid <= 0) {
+        throw new CapabilityError('A daemon launch guard requires its owned child pid', 'INVALID_INPUT', {
+            reason: 'pm-daemon-launch-guard-pid-invalid',
+            details: { childPid }
+        });
+    }
+    const files = await pmFileSystem(lease.runtime);
+    const childClaimFile = `${lease.lockFile}.${lease.order}-${childPid}-${lease.token}.child.claim`;
+    await publishGenerationClaim(lease.queueLease, childClaimFile, 'child', childPid);
+    lease.childClaimFile = childClaimFile;
+    // Publication hands uncertainty to the observable child. Do not leave an
+    // immortal unresolved guard if this launcher dies before its finally block.
+    if (lease.unresolvedClaimFile) {
+        await removeIfPresent(files, lease.unresolvedClaimFile);
+        lease.unresolvedClaimFile = undefined;
+    }
+}
+/** Remove `path`; a path that is already gone (`ENOENT`) is the goal, any other failure propagates. */
+async function removeIfPresent(files, path) {
+    const removed = await attempt(() => files.remove(path));
+    if (!removed.ok && !hasErrno(removed.failure, 'ENOENT'))
+        rethrowFailure(removed.failure);
+}
+async function openLockIO(runtime) {
+    const service = await getRuntimeProcessService(runtime);
+    return { files: await pmFileSystem(runtime), isRunning: (pid) => service.isRunning(pid) };
+}
+/** Which of `pids` are running, read once each. */
+async function livenessOf(io, pids) {
+    const running = new Map();
+    for (const pid of new Set(pids))
+        running.set(pid, await io.isRunning(pid));
+    return (pid) => running.get(pid) ?? false;
+}
+/** A claim's record; `undefined` when the claim is gone (`ENOENT`: released) or is not a claim record. Any other read failure propagates. */
+async function readClaimRecord(files, claimFile) {
+    const text = await readTextFileIfPresent(files, claimFile);
+    if (text === undefined)
+        return undefined;
+    const json = attemptSync(() => JSON.parse(text));
+    if (!json.ok) {
+        if (json.failure instanceof SyntaxError)
+            return undefined;
+        return rethrowFailure(json.failure);
+    }
+    const record = LeaseClaimRecordSchema.safeParse(json.value);
+    return record.success ? record.data : undefined;
+}
+/** A path's mtime in ms; `undefined` when the path is gone (`ENOENT`). Any other failure propagates. */
+async function readMtimeMs(files, path) {
+    const read = await attempt(() => files.stat(path));
+    if (read.ok)
+        return mtimeMsOf(read.value.mtime);
+    if (hasErrno(read.failure, 'ENOENT'))
+        return undefined;
+    return rethrowFailure(read.failure);
+}
+/** A pre-lease lockfile's mtime and the pid its text names. */
+async function readLegacyLock(io, lockFile) {
+    const mtimeMs = await readMtimeMs(io.files, lockFile);
+    if (mtimeMs === undefined)
+        return { mtimeMs, holderPid: undefined };
+    const text = await readTextFileIfPresent(io.files, lockFile);
+    return { mtimeMs, holderPid: text === undefined ? undefined : parseLegacyHolderPid(text) };
+}
+async function inspectLegacyLock(io, lockFile, nowMs) {
+    const { mtimeMs, holderPid } = await readLegacyLock(io, lockFile);
+    const alive = await livenessOf(io, holderPid === undefined ? [] : [holderPid]);
+    return legacyState(mtimeMs, holderPid, nowMs, alive);
+}
+async function reclaimLegacyLock(io, lockFile, nowMs) {
+    const legacy = await inspectLegacyLock(io, lockFile, nowMs);
+    if (!legacy.exists || !legacy.stale)
+        return false;
+    // This path exists only for pre-lease binaries during cutover. New binaries
+    // never recreate it; all permanent generations use immutable claim paths.
+    await removeIfPresent(io.files, lockFile);
+    return true;
+}
+/**
+ * Touch the claim every `heartbeatMs` (default 5s) while the lease lives: a chain of
+ * lifecycle one-shots, each arming the next. It stops when the returned
+ * disposer runs, when the claim is no longer this lease's, or when the touch
+ * fails; the runtime's disposal clears the pending one.
+ */
+function startHeartbeat(runtime, files, lease, heartbeatMs) {
+    let cancel;
+    let stopped = false;
+    /** Touch this lease's own claim; false when the claim is gone or is not this lease's. */
+    const republish = async () => {
+        // The disposer is synchronous and the touch is not: a beat that has not
+        // touched yet ends here, so a stopped heartbeat never advances (or
+        // revives) the claim's mtime.
+        if (stopped)
+            return false;
+        const record = await readClaimRecord(files, lease.claimFile);
+        if (!record || record.pid !== lease.ownerPid || record.token !== lease.token)
+            return false;
+        // Re-read after the awaits: the heartbeat may have been stopped (or the
+        // lease released) while the read was in flight.
+        if (stopped)
+            return false;
+        // `touch` advances the mtime and never creates: it answers `false` when the claim is gone,
+        // so a release that ran while this beat was in flight is never undone.
+        return (await touchChecked(files, lease.claimFile)) && !lease.released;
+    };
+    const beat = async () => {
+        cancel = undefined;
+        if (stopped)
+            return;
+        const beaten = await attempt(republish);
+        if (!beaten.ok) {
+            // The claim is gone (ENOENT: released or reclaimed) or unwritable:
+            // this lease's heartbeat ends; an unwritable claim is reported, and
+            // goes stale for other launchers exactly as a dead owner's would.
+            if (!hasErrno(beaten.failure, 'ENOENT')) {
+                getLogger('pm:daemon-launch-lock', runtime).warn('daemon launch claim heartbeat failed', {
+                    claimFile: lease.claimFile,
+                    reason: failureLabel(beaten.failure)
+                });
+            }
+            return;
+        }
+        if (!beaten.value || stopped)
+            return;
+        cancel = runtime.lifecycle.timeout(() => void beat(), heartbeatMs);
+    };
+    cancel = runtime.lifecycle.timeout(() => void beat(), heartbeatMs);
+    return () => {
+        stopped = true;
+        cancel?.();
+        cancel = undefined;
+    };
+}
+function preciseWallClockMs() {
+    return performance.timeOrigin + performance.now();
+}
+//# sourceMappingURL=daemon-launch-lock.js.map