peaks-loop 4.0.7 → 4.0.9

package/dist/services/skills/hooks-settings-service.js

@@ -57,14 +57,6 @@ function resolveIde(options) {
 function resolveSkipProgress(options) {
     return options?.skipProgress === true;
 }
-/** Slice 4.0.7-PR-meta-5: read the withEditEnforcement opt-in flag. */
-function resolveWithEditEnforcement(options) {
-    return options?.withEditEnforcement === true;
-}
-/** Slice 4.0.7-PR-meta-5: read the withScopeCounter opt-in flag. */
-function resolveWithScopeCounter(options) {
-    return options?.withScopeCounter === true;
-}
 /** Resolve settings root dir for a scope. */
 function resolveSettingsRoot(scope, projectRoot) {
     if (scope === 'global')
@@ -173,32 +165,6 @@ export function readInstalledEntriesFromSettings(settings, ide) {
     }
     return result;
 }
-/**
- * Slice 4.0.7-PR-meta-1: the Edit-enforcement hook entry. Off by
- * default; opt in via `peaks hooks install --with-edit-enforcement`
- * (or `PEAKS_INSTALL_EDIT_ENFORCEMENT=1` env). The entry points at
- * the new `pre-tool-edit-enforcement.sh` script in
- * `src/services/hooks/`. The matcher targets Edit / Write / MultiEdit
- * / NotebookEdit (Claude Code: "Edit|Write|MultiEdit|NotebookEdit";
- * Trae: same). When the hook fires, the script blocks src/** edits
- * without an RD artifact on disk (per slice 4.0.7-PR-meta-1 design).
- */
-export const EDIT_ENFORCEMENT_HOOK_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit';
-export const EDIT_ENFORCEMENT_HOOK_SENTINEL = 'peaks edit enforcement';
-export const EDIT_ENFORCEMENT_HOOK_EVENT = 'PreToolUse';
-/**
- * Slice 4.0.7-PR-meta-3: the scope-counter hook entry. Off by
- * default. Tracks cumulative application-source edits in the
- * active session and emits a fail-LOUD reflection reminder at
- * thresholds 5, 10, 20. The LLM cannot continue without writing
- * to `.peaks/_runtime/<sid>/scope-reflection.md` once a threshold
- * is hit. Different from the harness-side SCOPE WARNING (which
- * is informational noise); the meta-3 hook surfaces a checkpoint
- * the LLM must reference in its next turn.
- */
-export const SCOPE_COUNTER_HOOK_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit';
-export const SCOPE_COUNTER_HOOK_SENTINEL = 'peaks scope counter';
-export const SCOPE_COUNTER_HOOK_EVENT = 'PreToolUse';
 /**
  * Compute the per-IDE peaks hook entries to merge into the settings file.
  * Replaces the slice #1 hardcoded `PEAKS_HOOK_ENTRIES` constant; the constant
@@ -216,33 +182,11 @@ export const SCOPE_COUNTER_HOOK_EVENT = 'PreToolUse';
  * can find + remove any stale progress-start entry that an older
  * `peaks hooks install` may have written before this slice.
  */
-function resolveHookEntries(ide, options = {}) {
+function resolveHookEntries(ide, _skipProgress = false) {
     const spec = resolveHookSpec(ide);
-    const entries = [
+    return [
         { sentinel: spec.hookEnforceSentinel, matcher: spec.hookEnforceMatcher, command: spec.hookEnforceCommand, event: spec.hookEnforceEvent }
     ];
-    // Slice 4.0.7-PR-meta-1: opt-in Edit enforcement. Default false
-    // to preserve the existing `peaks hooks install` behavior; users
-    // who want the LLM Edit layer enforced call install with the
-    // opt-in flag or env var.
-    if ('withEditEnforcement' in options && options.withEditEnforcement === true) {
-        entries.push({
-            sentinel: EDIT_ENFORCEMENT_HOOK_SENTINEL,
-            matcher: EDIT_ENFORCEMENT_HOOK_MATCHER,
-            command: 'peaks edit-enforcement',
-            event: EDIT_ENFORCEMENT_HOOK_EVENT
-        });
-    }
-    // Slice 4.0.7-PR-meta-3: opt-in scope counter. Default false.
-    if ('withScopeCounter' in options && options.withScopeCounter === true) {
-        entries.push({
-            sentinel: SCOPE_COUNTER_HOOK_SENTINEL,
-            matcher: SCOPE_COUNTER_HOOK_MATCHER,
-            command: 'peaks scope-counter',
-            event: SCOPE_COUNTER_HOOK_EVENT
-        });
-    }
-    return entries;
 }
 /**
  * Legacy sentinel set used by uninstall + status to find and remove stale
@@ -449,7 +393,7 @@ export function planHookInstall(scope, projectRoot, options) {
     };
 }
 /** Merge all peaks-managed hook entries into settings, preserving all other keys and hooks. */
-function withHooksInstalledForIde(settings, ide, options = {}) {
+function withHooksInstalledForIde(settings, ide, _skipProgress = false) {
     const existingHooks = (settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks))
         ? settings.hooks
         : {};
@@ -457,7 +401,7 @@ function withHooksInstalledForIde(settings, ide, options = {}) {
     // beforeToolCall; Claude: gate-enforce on PreToolUse). Group by event
     // so each event array is independently merged.
     const ourByEvent = new Map();
-    for (const spec of resolveHookEntries(ide, options)) {
+    for (const spec of resolveHookEntries(ide)) {
         const list = ourByEvent.get(spec.event) ?? [];
         list.push(spec);
         ourByEvent.set(spec.event, list);
@@ -530,7 +474,7 @@ export function applyHookInstall(scope, projectRoot, options) {
     // entry. The chain cannot run raw `git worktree add` (or
     // `podman run`) without an explicit `peaks hooks uninstall`
     // first. Both helpers are pure + idempotent.
-    const merged = withTriggeredDenyList(withSuperpowersSkillDenylist(withHooksInstalledForIde(settings, ide, { withEditEnforcement: resolveWithEditEnforcement(options), withScopeCounter: resolveWithScopeCounter(options) })));
+    const merged = withTriggeredDenyList(withSuperpowersSkillDenylist(withHooksInstalledForIde(settings, ide)));
     atomicWriteJson(settingsPath, merged);
     return { ...baseResult, alreadyInstalled: false, applied: true };
 }

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

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

@@ -0,0 +1,75 @@
+/**
+ * Skill presence lease types (RD §2 — slice 4.0.8 presence-lease-graph).
+ *
+ * Pure type definitions for the canonical lease + caller index shapes.
+ * These types are the contract for `.peaks/_runtime/<sid>/leases/...` and
+ * `.peaks/_runtime/<sid>/presence-index/...` writes. No vendor env
+ * lookups; no filesystem I/O.
+ */
+import type { LeaseStatus, TerminalReason } from '../workflow/workflow-graph-types.js';
+export interface SkillPresenceLease {
+    readonly callerId: string;
+    readonly workflowId: string;
+    readonly graphRef: string;
+    readonly skill: string;
+    readonly parentWorkflowId?: string;
+    readonly depth: number;
+    readonly startedAt: string;
+    readonly lastHeartbeat: string;
+    readonly terminalAt?: string;
+    readonly terminalReason?: TerminalReason;
+    readonly status: LeaseStatus;
+    readonly schemaVersion: 1;
+}
+/**
+ * `PresenceIndex` — additive read index at
+ * `.peaks/_runtime/<sid>/presence-index/<callerId>.json`. Stores only
+ * the active lease reference (no lifecycle fields); readers can find
+ * the active lease in O(1) without enumerating the leases dir.
+ */
+export interface PresenceIndex {
+    readonly callerId: string;
+    readonly sessionId: string;
+    readonly leaseRef: string;
+    readonly workflowId: string;
+    readonly graphRef: string;
+    readonly updatedAt: string;
+    readonly schemaVersion: 1;
+}
+/**
+ * `PresenceProjection` — the canonical envelope returned by
+ * `readPresenceLease` / `setPresenceLease`. Combines lease + index +
+ * graph info into a single typed record that hook consumers and the
+ * statusline already know how to render.
+ */
+export interface PresenceProjection {
+    readonly active: boolean;
+    readonly legacyPresence: boolean;
+    readonly lease: SkillPresenceLease | null;
+    readonly index: PresenceIndex | null;
+    readonly callerId: string;
+    readonly sessionId: string | null;
+    readonly skill: string;
+    readonly mode?: string;
+    readonly gate?: string;
+    readonly setAt: string | null;
+    readonly lastHeartbeat: string | null;
+}
+/** Gc result — additive so existing presence consumers can ignore. */
+export interface GcResult {
+    readonly removed: number;
+    readonly retained: number;
+    readonly trigger: 'manual' | 'workspace-init' | 'presence-set';
+    readonly inFlightBatch: boolean;
+    readonly warnings: ReadonlyArray<{
+        code: string;
+        leaseRef: string;
+        message: string;
+    }>;
+    readonly errors: ReadonlyArray<{
+        code: string;
+        leaseRef: string;
+        message: string;
+    }>;
+}
+export { PEAKS_CALLER_NOT_RESOLVED, PEAKS_SESSION_NOT_BOUND, PEAKS_GRAPH_REF_BROKEN, } from '../workflow/workflow-graph-store.js';

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

@@ -0,0 +1,16 @@
+/**
+ * Skill presence lease types (RD §2 — slice 4.0.8 presence-lease-graph).
+ *
+ * Pure type definitions for the canonical lease + caller index shapes.
+ * These types are the contract for `.peaks/_runtime/<sid>/leases/...` and
+ * `.peaks/_runtime/<sid>/presence-index/...` writes. No vendor env
+ * lookups; no filesystem I/O.
+ */
+// Re-export the 4.0.8 typed error union + projection shape from
+// caller-id-types so lease consumers can branch on the canonical code
+// without importing the session service directly. The error code
+// `PEAKS_CALLER_NOT_RESOLVED` is the only failure path for
+// resolveCallerId in 4.0.8; `PEAKS_SESSION_NOT_BOUND` is the
+// companion failure when setPresenceLease is called without a
+// bound session.
+export { PEAKS_CALLER_NOT_RESOLVED, PEAKS_SESSION_NOT_BOUND, PEAKS_GRAPH_REF_BROKEN, } from '../workflow/workflow-graph-store.js';