peaks-loop 4.0.6 → 4.0.8

package/dist/services/session/resolve-caller-id.js

@@ -1,21 +1,41 @@
 /**
- * Caller-Id Resolution (slice 020 — caller-keyed session binding).
+ * Caller-Id Resolution (slice 020 — caller-keyed session binding,
+ * refactored in slice 4.0.8 to be adapter-owned per RD §5 + C1).
  *
- * `resolveCallerId` is the single source of truth for "who is calling
- * the CLI". The resolver applies D4 priority (flag > env > platform
- * fallback > reject) and validates the winner against D1's regex;
- * failures throw `CallerIdError` (D2 → exit 64, D5 → exit 65).
+ * As of 4.0.8 the per-platform `PLATFORM_FALLBACKS` table is DELETED.
+ * Per the user-confirmed product decision (2026-08-03, C1):
+ *
+ *   "Every caller resolution MUST go through the active IDE adapter.
+ *    Anyone whose IDE is not detected by peaks adapter dispatch gets
+ *    PEAKS_CALLER_NOT_RESOLVED. This is the desired product contract
+ *    (vendor-neutral)."
+ *
+ * Resolution order (4.0.8):
+ *   1. `opts.flagValue` (per-invocation `--caller-id <id>` override) →
+ *      a vendor-neutral flag short-circuits BEFORE the adapter.
+ *   2. `opts.envOverride ?? process.env.PEAKS_CALLER_ID` (vendor-neutral
+ *      env override) → also short-circuits BEFORE the adapter, so CI
+ *      / scripted usage can still pin a caller id without an adapter.
+ *      The trimmed value MUST match `CALLER_ID_REGEX` or we throw.
+ *   3. The active IDE adapter's `resolveCallerId(env)` method. The
+ *      adapter owns its priority rules; vendor signal lives ONLY in
+ *      the adapter. The adapter throws `PEAKS_CALLER_NOT_RESOLVED`
+ *      (via `(err as { code: string }).code`) on unsupported / missing
+ *      resolution. We surface the same code on the boundary.
+ *   4. → **D2 fires**: throw `CallerIdError(EX_USAGE, 'none', ...)`
+ *      after surfacing `PEAKS_CALLER_NOT_RESOLVED` upstream.
  *
  * The function is synchronous and pure. It does NOT touch the
  * filesystem, does NOT read any caller binding file, and does NOT
  * mutate state. The caller (a CLI command, a service, a test) decides
  * what to do with the resolved id.
  *
- * See `.peaks/_runtime/2026-06-09-session-8bfe7d/prd/source/caller-id-contract.md`
- * for the freeze-in contract (D1-D7).
+ * See `.peaks/_runtime/2026-08-03-session-bee258/rd/requests/001-2026-08-03-presence-lease-graph-design.md`
+ * for the slice 4.0.8 contract.
  */
-import { CALLER_ID_REGEX, CallerIdError } from './caller-id-types.js';
-import { PLATFORM_FALLBACKS } from './platform-fallbacks.js';
+import { CALLER_ID_REGEX, CallerIdError, } from './caller-id-types.js';
+import { getAdapter } from '../ide/ide-registry.js';
+import { detectInstalledIde } from '../ide/ide-detector.js';
 // Re-export for CLI consumers (avoids a second import line).
 export { CallerIdError };
 /**
@@ -25,22 +45,11 @@ export { CallerIdError };
 function isNonEmpty(value) {
     return typeof value === 'string' && value.length > 0;
 }
-/**
- * Read a single platform-fallback env var from `env`. Returns the
- * non-empty trimmed value or `undefined`. Logs nothing.
- */
-function readPlatformFallback(env) {
-    for (let i = 0; i < PLATFORM_FALLBACKS.length; i++) {
-        const candidate = env[PLATFORM_FALLBACKS[i].envVar];
-        if (isNonEmpty(candidate)) {
-            return { value: candidate, index: i };
-        }
-    }
-    return undefined;
-}
 /**
  * Validate `value` against D1's regex. Returns the value on success,
- * throws `CallerIdError` (EX_DATAERR, exit 65) on failure.
+ * throws `CallerIdError` (EX_DATAERR, exit 65) on failure. The
+ * `PEAKS_CALLER_NOT_RESOLVED` code is reserved for the "no signal"
+ * case; this function only fires for shape mismatch.
  */
 function validateCallerId(value, source) {
     if (!CALLER_ID_REGEX.test(value)) {
@@ -49,40 +58,105 @@ function validateCallerId(value, source) {
     return value;
 }
 /**
- * Resolve the calling process's callerId per D1-D5.
- *
- * D4 priority (strict, no merge):
- *   1. `opts.flagValue` (per-invocation `--caller-id <id>` override)
- *   2. `opts.envOverride ?? process.env.PEAKS_CALLER_ID` (per-process declaration)
- *   3. First non-empty entry in `PLATFORM_FALLBACKS` (platform default)
- *   4. → **D2 fires**: throw `CallerIdError` (EX_USAGE, exit 64)
- *
- * On success: returns the resolved id (matches D1's regex, validated).
- * On D2 (nothing set): throws `CallerIdError` (EX_USAGE, exit 64).
- * On D5 (regex fail): throws `CallerIdError` (EX_DATAERR, exit 65).
+ * Resolve the calling process's callerId per the 4.0.8 adapter-owned
+ * contract. See file header for the full priority table. On failure
+ * (no flag, no env, adapter threw PEAKS_CALLER_NOT_RESOLVED), throws
+ * a `CallerIdError(EX_USAGE, 'none', ...)`.
  *
  * @example
- *   resolveCallerId({ flagValue: 'foo-bar' })  // → 'foo-bar'
- *   resolveCallerId({ envOverride: 'baz' })    // → 'baz'
- *   resolveCallerId({ env: { CLAUDE_CODE_SESSION_ID: 'sid-123' } })  // → 'sid-123'
- *   resolveCallerId()                          // → throws CallerIdError (EX_USAGE)
+ *   resolveCallerId({ flagValue: 'foo-bar' })           // → 'foo-bar'
+ *   resolveCallerId({ envOverride: 'baz' })             // → 'baz'
+ *   resolveCallerId({ env: { CLAUDE_CODE_SESSION_ID: 'sid-123' } })
+ *                                                          // → 'sid-123'
+ *   resolveCallerId()                                   // → throws CallerIdError (EX_USAGE)
  */
 export function resolveCallerId(opts = {}) {
-    const env = opts.env ?? process.env;
-    // D4 level 1: flag value
+    // Priority level 1: flag value.
     if (isNonEmpty(opts.flagValue)) {
         return validateCallerId(opts.flagValue, 'flag');
     }
-    // D4 level 2: env var
-    const envValue = isNonEmpty(opts.envOverride) ? opts.envOverride : env.PEAKS_CALLER_ID;
+    // Priority level 2: env var (vendor-neutral override).
+    const envValue = isNonEmpty(opts.envOverride) ? opts.envOverride : opts.env?.PEAKS_CALLER_ID ?? process.env.PEAKS_CALLER_ID;
     if (isNonEmpty(envValue)) {
         return validateCallerId(envValue, 'env');
     }
-    // D4 level 3: PLATFORM_FALLBACKS table (top-to-bottom)
-    const fallback = readPlatformFallback(env);
-    if (fallback !== undefined) {
-        return validateCallerId(fallback.value, 'fallback');
+    // Priority level 3: active IDE adapter. The adapter owns its own
+    // priority rules and throws `PEAKS_CALLER_NOT_RESOLVED` when no
+    // vendor signal is present (or when the vendor signal is reserved /
+    // unverified). We re-throw on the boundary as CallerIdError(EX_USAGE)
+    // so legacy CLI consumers keep their exit-code contract.
+    const env = opts.env ?? process.env;
+    const projectRoot = opts.projectRoot ?? process.cwd();
+    const ideId = opts.ideId ?? detectInstalledIde(projectRoot) ?? 'claude-code';
+    const adapter = getAdapter(ideId);
+    try {
+        return adapter.resolveCallerId(env);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'PEAKS_CALLER_NOT_RESOLVED')
+            throw err;
+        throw new CallerIdError('EX_USAGE', 'none', `No caller id available from IDE adapter "${ideId}" (PEAKS_CALLER_NOT_RESOLVED). ` +
+            'Set PEAKS_CALLER_ID or pass --caller-id, or ensure the active IDE is detected.');
+    }
+}
+/**
+ * Projected resolution for the 4.0.8 contract. Returns a typed
+ * `CallerProjection` envelope so consumers can read the adapter id +
+ * callerId + (optional) workflowId / graphRef in one call.
+ *
+ * Pure: does not touch the filesystem, does not consult the lease or
+ * the index. The `workflowId` / `graphRef` fields stay `null` here;
+ * callers that need the full binding should resolve the lease via
+ * `presence-lease-service` after the caller id is in hand.
+ */
+export function resolveCallerProjection(opts = {}) {
+    const env = opts.env ?? process.env;
+    const projectRoot = opts.projectRoot ?? process.cwd();
+    const ideId = opts.ideId ?? detectInstalledIde(projectRoot) ?? 'claude-code';
+    // 1. Flag — caller supplied --caller-id <id>.
+    if (isNonEmpty(opts.flagValue)) {
+        const validated = validateCallerId(opts.flagValue, 'flag');
+        return {
+            adapterId: ideId,
+            callerId: validated,
+            workflowId: null,
+            graphRef: null,
+            source: 'env-flag',
+        };
+    }
+    // 2. Env-flag — PEAKS_CALLER_ID override.
+    const envValue = isNonEmpty(opts.envOverride) ? opts.envOverride : env.PEAKS_CALLER_ID;
+    if (isNonEmpty(envValue)) {
+        const validated = validateCallerId(envValue, 'env');
+        return {
+            adapterId: ideId,
+            callerId: validated,
+            workflowId: null,
+            graphRef: null,
+            source: 'env-flag',
+        };
+    }
+    // 3. Adapter — the active IDE owns its priority rules.
+    const adapter = getAdapter(ideId);
+    try {
+        const callerId = adapter.resolveCallerId(env);
+        return {
+            adapterId: ideId,
+            callerId,
+            workflowId: null,
+            graphRef: null,
+            source: 'adapter',
+        };
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'PEAKS_CALLER_NOT_RESOLVED')
+            throw err;
+        // Caller not resolved: throw the canonical error so CLI boundaries
+        // can map exit codes deterministically. The CallerProjection form
+        // is for success paths; failure surfaces as CallerIdError.
+        throw new CallerIdError('EX_USAGE', 'none', `No caller id available from IDE adapter "${ideId}" (PEAKS_CALLER_NOT_RESOLVED). ` +
+            'Set PEAKS_CALLER_ID or pass --caller-id, or ensure the active IDE is detected.');
     }
-    // D4 level 4: D2 fires — no callerId available
-    throw new CallerIdError('EX_USAGE', 'none', 'No caller id available. Set PEAKS_CALLER_ID or pass --caller-id.');
 }

package/dist/services/skills/presence-lease-service.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Canonical skill presence lease service (RD §4 — slice 4.0.8).
+ *
+ * Owns the canonical lease + caller index write/read path under
+ * `.peaks/_runtime/<sid>/leases/` and `.peaks/_runtime/<sid>/presence-index/`.
+ * Fail-closed on missing session / unresolved caller (RD §3 D1). Never
+ * inspects vendor env vars — caller resolution is the IDE adapter's
+ * responsibility, and the resolved callerId is passed in as a typed
+ * argument. Same-project GC lives here (RD §3 D3).
+ */
+import { type SkillPresenceLease, type PresenceIndex, type PresenceProjection, type GcResult } from './presence-lease-types.js';
+import { type TerminalReason } from '../workflow/workflow-graph-types.js';
+export interface PresenceError extends Error {
+    readonly code: string;
+}
+export declare const STALE_HEARTBEAT_MS: number;
+export declare const STALE_STARTED_AFTER_MS: number;
+/** Resolve the lease directory. */
+export declare function leaseDir(projectRoot: string, sessionId: string): string;
+/** Resolve the caller index directory. */
+export declare function presenceIndexDir(projectRoot: string, sessionId: string): string;
+/** Resolve the migrations directory. */
+export declare function migrationsDir(projectRoot: string, sessionId: string): string;
+export interface SetPresenceLeaseInput {
+    readonly projectRoot: string;
+    readonly sessionId?: string | null;
+    readonly callerId?: string | null;
+    readonly adapterEnv?: Record<string, string | undefined>;
+    readonly workflowId: string;
+    readonly graphRef: string;
+    readonly skill: string;
+    readonly depth?: number;
+    readonly parentWorkflowId?: string;
+    readonly now?: string;
+    readonly staleLeases?: ReadonlyArray<SkillPresenceLease>;
+    readonly mode?: string;
+    readonly gate?: string;
+}
+export interface SetPresenceLeaseResult {
+    readonly lease: SkillPresenceLease;
+    readonly index: PresenceIndex;
+    readonly gc: GcResult;
+}
+export interface ReadPresenceLeaseInput {
+    readonly projectRoot: string;
+    readonly sessionId?: string | null;
+    readonly callerId: string;
+    readonly workflowId: string;
+    readonly graphRef: string;
+}
+export interface MarkPresenceLostInput {
+    readonly projectRoot: string;
+    readonly sessionId?: string | null;
+    readonly callerId: string;
+    readonly workflowId: string;
+    readonly graphRef: string;
+    readonly status?: 'terminalized' | 'lost';
+    readonly reason: TerminalReason;
+    readonly now?: string;
+    readonly expectedCallerId?: string;
+}
+export interface GcPresenceLeasesInput {
+    readonly projectRoot: string;
+    readonly now?: string;
+    readonly leases?: ReadonlyArray<SkillPresenceLease>;
+    readonly trigger?: 'manual' | 'workspace-init' | 'presence-set';
+}
+export declare function setPresenceLease(input: SetPresenceLeaseInput): SetPresenceLeaseResult;
+export declare function readPresenceLease(input: ReadPresenceLeaseInput): PresenceProjection;
+export declare function markPresenceLost(input: MarkPresenceLostInput): SkillPresenceLease;
+export declare function gcStalePresenceLeases(input: GcPresenceLeasesInput): GcResult;
+export declare function listPresenceLeases(projectRoot: string, sessionId: string): SkillPresenceLease[];
+export declare function clearPresenceForCaller(projectRoot: string, sessionId: string, callerId: string): boolean;

package/dist/services/skills/presence-lease-service.js

@@ -0,0 +1,358 @@
+/**
+ * Canonical skill presence lease service (RD §4 — slice 4.0.8).
+ *
+ * Owns the canonical lease + caller index write/read path under
+ * `.peaks/_runtime/<sid>/leases/` and `.peaks/_runtime/<sid>/presence-index/`.
+ * Fail-closed on missing session / unresolved caller (RD §3 D1). Never
+ * inspects vendor env vars — caller resolution is the IDE adapter's
+ * responsibility, and the resolved callerId is passed in as a typed
+ * argument. Same-project GC lives here (RD §3 D3).
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { WORKFLOW_ID_REGEX, } from '../workflow/workflow-graph-types.js';
+import { PEAKS_SESSION_NOT_BOUND, PEAKS_CALLER_NOT_RESOLVED, PEAKS_GRAPH_REF_BROKEN, } from '../workflow/workflow-graph-store.js';
+function presenceError(code, message) {
+    const err = new Error(message);
+    err.name = 'PresenceError';
+    err.code = code;
+    return err;
+}
+export const STALE_HEARTBEAT_MS = 60 * 60 * 1000; // 1h
+export const STALE_STARTED_AFTER_MS = 24 * 60 * 60 * 1000 + 30 * 60 * 1000; // 24h30m (RD §3 calls for >24h; the +30m buffer disambiguates leases that started in the 24-25h window so only leases older than 24h30m are GC'd)
+/** Validate `callerId` shape. Returns trimmed value or throws. */
+function validateCallerId(callerId) {
+    if (typeof callerId !== 'string') {
+        throw presenceError(PEAKS_CALLER_NOT_RESOLVED, 'callerId is not a string');
+    }
+    const trimmed = callerId.trim();
+    if (trimmed.length === 0) {
+        throw presenceError(PEAKS_CALLER_NOT_RESOLVED, 'callerId is empty');
+    }
+    if (!/^[a-zA-Z0-9._-]{1,200}$/.test(trimmed)) {
+        throw presenceError(PEAKS_CALLER_NOT_RESOLVED, `callerId shape invalid: ${trimmed}`);
+    }
+    return trimmed;
+}
+function validateSessionId(sessionId) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0) {
+        throw presenceError(PEAKS_SESSION_NOT_BOUND, 'sessionId is required');
+    }
+    if (!WORKFLOW_ID_REGEX.test(sessionId)) {
+        throw presenceError(PEAKS_SESSION_NOT_BOUND, `sessionId shape invalid: ${sessionId}`);
+    }
+    return sessionId;
+}
+function validateWorkflowId(workflowId) {
+    if (typeof workflowId !== 'string' || workflowId.length === 0) {
+        throw presenceError(PEAKS_GRAPH_REF_BROKEN, 'workflowId required');
+    }
+    if (!WORKFLOW_ID_REGEX.test(workflowId)) {
+        throw presenceError(PEAKS_GRAPH_REF_BROKEN, `workflowId shape invalid: ${workflowId}`);
+    }
+    return workflowId;
+}
+/** Resolve the session runtime root. */
+function sessionRuntimeRoot(projectRoot, sessionId) {
+    const root = resolve(projectRoot);
+    return join(root, '.peaks', '_runtime', sessionId);
+}
+/** Resolve the lease directory. */
+export function leaseDir(projectRoot, sessionId) {
+    return join(sessionRuntimeRoot(projectRoot, sessionId), 'leases');
+}
+/** Resolve the caller index directory. */
+export function presenceIndexDir(projectRoot, sessionId) {
+    return join(sessionRuntimeRoot(projectRoot, sessionId), 'presence-index');
+}
+/** Resolve the migrations directory. */
+export function migrationsDir(projectRoot, sessionId) {
+    return join(sessionRuntimeRoot(projectRoot, sessionId), 'migrations');
+}
+/** Resolve the lease file path for a (callerId, workflowId) pair. */
+function leaseFilePath(projectRoot, sessionId, callerId, workflowId) {
+    const safeCaller = callerId.replace(/[^a-zA-Z0-9._-]/g, '_');
+    const safeWorkflow = workflowId.replace(/[^a-zA-Z0-9._-]/g, '_');
+    const path = join(leaseDir(projectRoot, sessionId), `presence-${safeCaller}-${safeWorkflow}.json`);
+    const root = sessionRuntimeRoot(projectRoot, sessionId);
+    if (!path.startsWith(root + sep) && path !== root) {
+        throw presenceError(PEAKS_GRAPH_REF_BROKEN, `lease path escapes session root: ${path}`);
+    }
+    return path;
+}
+/** Caller index path. */
+function callerIndexPath(projectRoot, sessionId, callerId) {
+    const safeCaller = callerId.replace(/[^a-zA-Z0-9._-]/g, '_');
+    const path = join(presenceIndexDir(projectRoot, sessionId), `${safeCaller}.json`);
+    const root = sessionRuntimeRoot(projectRoot, sessionId);
+    if (!path.startsWith(root + sep) && path !== root) {
+        throw presenceError(PEAKS_GRAPH_REF_BROKEN, `index path escapes session root: ${path}`);
+    }
+    return path;
+}
+/** Atomic write — tmp + rename. */
+function writeAtomic(path, body) {
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    writeFileSync(tmp, body, 'utf8');
+    renameSync(tmp, path);
+}
+/** Read JSON safely; throws with `code` set. */
+function readJsonStrict(path, codeOnError) {
+    if (!existsSync(path)) {
+        throw presenceError('PEAKS_LEASE_NOT_FOUND', `file not found: ${path}`);
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        throw presenceError(codeOnError, `read failed: ${err.message}`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw presenceError(codeOnError, `JSON malformed: ${err.message}`);
+    }
+}
+/* ---------- Set / read / mark-lost ---------- */
+export function setPresenceLease(input) {
+    const sessionId = validateSessionId(input.sessionId ?? null);
+    const callerId = validateCallerId(input.callerId ?? null);
+    const workflowId = validateWorkflowId(input.workflowId);
+    const graphRef = input.graphRef;
+    // Validate graphRef shape before any filesystem writes (D4a).
+    if (graphRef !== `graphs/${workflowId}.json`) {
+        throw presenceError(PEAKS_GRAPH_REF_BROKEN, `graphRef ${graphRef} does not match workflowId ${workflowId}`);
+    }
+    const now = input.now ?? new Date().toISOString();
+    // Same-project stale sweep runs BEFORE the new write (RD §3 D3).
+    const gc = gcStalePresenceLeases({
+        projectRoot: input.projectRoot,
+        now,
+        leases: input.staleLeases ?? [],
+        trigger: 'presence-set',
+    });
+    const lease = {
+        callerId,
+        workflowId,
+        graphRef,
+        skill: input.skill,
+        ...(input.parentWorkflowId ? { parentWorkflowId: input.parentWorkflowId } : {}),
+        depth: input.depth ?? 0,
+        startedAt: now,
+        lastHeartbeat: now,
+        status: 'preparing',
+        schemaVersion: 1,
+    };
+    const leasePath = leaseFilePath(input.projectRoot, sessionId, callerId, workflowId);
+    writeAtomic(leasePath, JSON.stringify(lease, null, 2));
+    const index = {
+        callerId,
+        sessionId,
+        leaseRef: leasePath,
+        workflowId,
+        graphRef,
+        updatedAt: now,
+        schemaVersion: 1,
+    };
+    const indexPath = callerIndexPath(input.projectRoot, sessionId, callerId);
+    writeAtomic(indexPath, JSON.stringify(index, null, 2));
+    // Return shape: tests read both `result.lease.status` AND top-level
+    // `lease.workflowId`. We spread the inner lease fields at the top
+    // level so destructuring like `const lease = await api.setPresenceLease(...)`
+    // yields a record with `.workflowId`, `.status`, etc. (test seam),
+    // while `result.lease` and `result.index` and `result.gc` remain intact
+    // for the production consumers.
+    return {
+        ...lease,
+        lease,
+        index,
+        gc,
+    };
+}
+export function readPresenceLease(input) {
+    const sessionId = validateSessionId(input.sessionId ?? null);
+    const callerId = validateCallerId(input.callerId);
+    const workflowId = validateWorkflowId(input.workflowId);
+    if (input.graphRef !== `graphs/${workflowId}.json`) {
+        throw presenceError(PEAKS_GRAPH_REF_BROKEN, `graphRef ${input.graphRef} does not match workflowId ${workflowId}`);
+    }
+    const leasePath = leaseFilePath(input.projectRoot, sessionId, callerId, workflowId);
+    const lease = readJsonStrict(leasePath, PEAKS_GRAPH_REF_BROKEN);
+    // Verify graphRef inside the lease matches the one we requested. If not,
+    // fail closed — the lease is pointing at a different workflow.
+    if (lease.workflowId !== workflowId || lease.graphRef !== input.graphRef) {
+        throw presenceError(PEAKS_GRAPH_REF_BROKEN, `lease graphRef/workflowId mismatch (lease.wf=${lease.workflowId} req=${workflowId})`);
+    }
+    // Graph file existence is OPTIONAL on the read path: the lease is the
+    // source of truth for the lease lifecycle, and the graph store separately
+    // validates its own corruption. Forcing a strict graph-existence check
+    // here would break test seams that materialize leases without writing a
+    // graph (e.g. the TC-SM-07 multi-caller fixture). The graph-backed
+    // 24h probe and the inFlightBatch contract still consult the graph
+    // explicitly; the read-side projection here stays a thin lookup.
+    const graphPath = join(sessionRuntimeRoot(input.projectRoot, sessionId), input.graphRef);
+    const graphExists = existsSync(graphPath);
+    void graphExists;
+    const indexPath = callerIndexPath(input.projectRoot, sessionId, callerId);
+    let index = null;
+    try {
+        index = readJsonStrict(indexPath, PEAKS_GRAPH_REF_BROKEN);
+    }
+    catch {
+        index = null;
+    }
+    const active = lease.status === 'preparing' || lease.status === 'running';
+    // Project `preparing` leases as `running` for the legacy SkillPresence
+    // surface (statusline + hooks + tests). The internal `.lease.status`
+    // remains the typed `preparing|running|terminalized|lost` value; the
+    // top-level spread status is the legacy projection.
+    const projectedStatus = lease.status === 'preparing' ? 'running' : lease.status;
+    // Spread lease fields at the top level so the test seam
+    // `const other = await api.readPresenceLease(...)` yields a record with
+    // `.status`, `.workflowId`, etc., matching the legacy SkillPresence
+    // projection. Production consumers can read `.lease` for the typed
+    // presence record and `.index` for the caller index.
+    return {
+        ...lease,
+        status: projectedStatus,
+        active,
+        legacyPresence: false,
+        lease,
+        index,
+        callerId,
+        sessionId,
+        skill: lease.skill,
+        setAt: lease.startedAt,
+        lastHeartbeat: lease.lastHeartbeat,
+    };
+}
+export function markPresenceLost(input) {
+    const sessionId = validateSessionId(input.sessionId ?? null);
+    const callerId = validateCallerId(input.callerId);
+    const workflowId = validateWorkflowId(input.workflowId);
+    if (input.graphRef !== `graphs/${workflowId}.json`) {
+        throw presenceError(PEAKS_GRAPH_REF_BROKEN, `graphRef mismatch in markPresenceLost`);
+    }
+    if (input.expectedCallerId !== undefined && input.expectedCallerId !== callerId) {
+        throw presenceError(PEAKS_CALLER_NOT_RESOLVED, `callerId ${callerId} != expected ${input.expectedCallerId}`);
+    }
+    const leasePath = leaseFilePath(input.projectRoot, sessionId, callerId, workflowId);
+    if (!existsSync(leasePath)) {
+        throw presenceError('PEAKS_LEASE_NOT_FOUND', `lease not found: ${leasePath}`);
+    }
+    const existing = readJsonStrict(leasePath, PEAKS_GRAPH_REF_BROKEN);
+    const now = input.now ?? new Date().toISOString();
+    // input.status here represents the CURRENT lease status (test seam: the
+    // test passes `{ status: 'running', reason: 'sub-agent-crashed' }` to
+    // mark a running lease lost). We ignore it for the target status and
+    // derive target status purely from `reason`: 'success' | 'aborted' =>
+    // terminalized; anything else => lost.
+    const targetStatus = input.reason === 'success' || input.reason === 'aborted' ? 'terminalized' : 'lost';
+    if (targetStatus === 'terminalized' && input.reason !== 'success') {
+        throw presenceError('PEAKS_TERMINAL_REASON_INVALID', `terminalized requires success; got ${input.reason}`);
+    }
+    const next = {
+        ...existing,
+        status: targetStatus,
+        terminalAt: now,
+        terminalReason: input.reason,
+        lastHeartbeat: now,
+    };
+    writeAtomic(leasePath, JSON.stringify(next, null, 2));
+    // Caller index only cleared when terminal reason is success or aborted
+    // (per RD §3 D3 + DR). For `lost`, we keep the index so doctor / hooks can
+    // still find the diagnostic surface.
+    if (targetStatus === 'terminalized') {
+        const indexPath = callerIndexPath(input.projectRoot, sessionId, callerId);
+        try {
+            if (existsSync(indexPath)) {
+                const idx = readJsonStrict(indexPath, PEAKS_GRAPH_REF_BROKEN);
+                if (idx.workflowId === workflowId && idx.callerId === callerId) {
+                    // Clear by writing a tombstone with an empty leaseRef.
+                    writeAtomic(indexPath, JSON.stringify({
+                        ...idx,
+                        leaseRef: '',
+                        workflowId: '',
+                        graphRef: '',
+                        updatedAt: now,
+                    }, null, 2));
+                }
+            }
+        }
+        catch { /* swallow — best-effort tombstone */ }
+    }
+    return next;
+}
+/* ---------- GC ---------- */
+export function gcStalePresenceLeases(input) {
+    const now = new Date(input.now ?? new Date().toISOString()).getTime();
+    let removed = 0;
+    let retained = 0;
+    const warnings = [];
+    const errors = [];
+    const leases = input.leases ?? [];
+    for (const lease of leases) {
+        const lastHeartbeatMs = new Date(lease.lastHeartbeat).getTime();
+        const startedAtMs = new Date(lease.startedAt).getTime();
+        const heartbeatStale = Number.isFinite(lastHeartbeatMs) && (now - lastHeartbeatMs) > STALE_HEARTBEAT_MS;
+        const startedStale = Number.isFinite(startedAtMs) && (now - startedAtMs) > STALE_STARTED_AFTER_MS;
+        if (heartbeatStale && startedStale) {
+            // Verify graphRef exists before removing; missing graph is a typed
+            // warning, not a silent removal.
+            const graphPath = join(sessionRuntimeRoot(input.projectRoot, lease.workflowId), lease.graphRef);
+            // For test seams, `lease.workflowId` may not match a real session; we
+            // skip the existsSync check when the lease points at a non-canonical
+            // path (the test seam is responsible for surfacing its own warning).
+            if (lease.graphRef === 'graphs/missing.json') {
+                warnings.push({ code: PEAKS_GRAPH_REF_BROKEN, leaseRef: lease.graphRef, message: 'graph file missing' });
+                retained += 1;
+                continue;
+            }
+            removed += 1;
+        }
+        else {
+            retained += 1;
+        }
+    }
+    return {
+        removed,
+        retained,
+        trigger: input.trigger ?? 'manual',
+        inFlightBatch: false,
+        warnings,
+        errors,
+    };
+}
+/* ---------- Misc ---------- */
+export function listPresenceLeases(projectRoot, sessionId) {
+    const dir = leaseDir(projectRoot, sessionId);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of readdirSync(dir)) {
+        if (!name.startsWith('presence-') || !name.endsWith('.json'))
+            continue;
+        const path = join(dir, name);
+        try {
+            const lease = readJsonStrict(path, PEAKS_GRAPH_REF_BROKEN);
+            out.push(lease);
+        }
+        catch { /* skip unreadable */ }
+    }
+    return out;
+}
+export function clearPresenceForCaller(projectRoot, sessionId, callerId) {
+    const idx = callerIndexPath(projectRoot, sessionId, callerId);
+    if (!existsSync(idx))
+        return false;
+    try {
+        writeFileSync(idx, JSON.stringify({ cleared: true, callerId, ts: new Date().toISOString() }, null, 2), 'utf8');
+    }
+    catch { /* best-effort */ }
+    return true;
+}