@isaacriehm/cairn-core 0.1.0

package/dist/sensors/stub-catalog.js

@@ -0,0 +1,115 @@
+/**
+ * Layer A — mechanical stub-pattern catalog.
+ *
+ * Run regex patterns from `.cairn/config/stub-patterns.yaml` against every
+ * file changed in the diff. Hard-severity match fails the run; soft-severity
+ * contributes to attestation cross-check (stubs_introduced count).
+ *
+ * Per PRIMER §10 Layer A. Catalog grows additively via /oops dialog (L25).
+ */
+const SENSOR_ID = "stub-pattern-catalog";
+/** Detect language from extension. Returns undefined for binaries / unknown. */
+export function detectLanguage(path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".ts") || lower.endsWith(".tsx") || lower.endsWith(".cts") || lower.endsWith(".mts"))
+        return "typescript";
+    if (lower.endsWith(".js") || lower.endsWith(".jsx") || lower.endsWith(".cjs") || lower.endsWith(".mjs"))
+        return "javascript";
+    if (lower.endsWith(".py"))
+        return "python";
+    if (lower.endsWith(".rb"))
+        return "ruby";
+    if (lower.endsWith(".go"))
+        return "go";
+    if (lower.endsWith(".rs"))
+        return "rust";
+    if (lower.endsWith(".sql"))
+        return "sql";
+    return undefined;
+}
+/**
+ * Walk the diff and emit a match for every regex hit on lines that were
+ * added or are part of a new file. Modified files: only count hits on lines
+ * not present at the SHA pin (i.e. genuinely-new debt).
+ */
+export function detectStubMatches(args) {
+    const out = [];
+    for (const entry of args.diff) {
+        if (entry.status === "deleted")
+            continue;
+        const lang = detectLanguage(entry.path);
+        if (lang === undefined)
+            continue;
+        if (args.languages !== undefined && !args.languages.includes(lang))
+            continue;
+        const after = entry.afterContent ?? "";
+        if (after.length === 0)
+            continue;
+        const beforeLines = new Set((entry.beforeContent ?? "").split(/\r?\n/));
+        const afterLines = after.split(/\r?\n/);
+        for (const pattern of args.catalog.patterns) {
+            if (!pattern.languages.includes(lang))
+                continue;
+            const re = new RegExp(pattern.regex, "gm");
+            let m;
+            while ((m = re.exec(after)) !== null) {
+                const matchedText = m[0];
+                // Find the line number this match starts on (1-based).
+                const lineIdx = lineOf(after, m.index);
+                const lineText = afterLines[lineIdx - 1] ?? "";
+                // Only count if this line was added — i.e. not present in the
+                // pre-change content. Catches genuinely-new debt; ignores stubs that
+                // existed prior. For added files the beforeLines set is empty.
+                if (beforeLines.has(lineText))
+                    continue;
+                out.push({
+                    sensor_id: SENSOR_ID,
+                    pattern_id: pattern.id,
+                    description: pattern.description,
+                    severity: pattern.severity,
+                    path: entry.path,
+                    line: lineIdx,
+                    matched_text: matchedText,
+                });
+                if (re.lastIndex === m.index)
+                    re.lastIndex += 1;
+            }
+        }
+    }
+    return out;
+}
+/** Convert a character offset within `text` to a 1-based line number. */
+function lineOf(text, charIndex) {
+    let line = 1;
+    for (let i = 0; i < charIndex && i < text.length; i++) {
+        if (text.charCodeAt(i) === 10 /* \n */)
+            line += 1;
+    }
+    return line;
+}
+/** Run the Layer A sensor against a diff. */
+export function runStubCatalog(args) {
+    const startedAt = Date.now();
+    const matches = detectStubMatches({
+        diff: args.diff,
+        catalog: args.catalog,
+        languages: args.languages,
+    });
+    const findings = matches.map((m) => ({
+        sensor_id: SENSOR_ID,
+        pattern_id: m.pattern_id,
+        path: m.path,
+        line: m.line,
+        matched_text: m.matched_text,
+        severity: m.severity,
+        message: `${m.path}:${m.line} matches stub pattern \`${m.pattern_id}\` — ${m.description}`,
+    }));
+    const ok = findings.every((f) => f.severity !== "hard");
+    return {
+        sensor_id: SENSOR_ID,
+        ok,
+        duration_ms: Date.now() - startedAt,
+        findings,
+    };
+}
+//# sourceMappingURL=stub-catalog.js.map

package/dist/sensors/stub-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub-catalog.js","sourceRoot":"","sources":["../../src/sensors/stub-catalog.ts"],"names":[],"mappings":"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"}

package/dist/sensors/types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Sensor types — Phase 9 honest-agent invariants stack.
+ *
+ * Sensors run after the implementer agent finishes. Each sensor reads a
+ * `SensorInput` (diff + attestation + decisions + project block) and emits
+ * `SensorFinding[]`. The orchestrator collects every sensor's `SensorResult`,
+ * builds a remediation prompt from any findings, and either passes the run
+ * through or feeds the prompt back to the agent for retry.
+ *
+ * Per PRIMER §10. Per OpenAI's pattern: failure messages are remediation
+ * prompts the agent consumes on retry.
+ */
+import type { DecisionFrontmatter } from "../ground/schemas.js";
+/** A single file changed in this run. */
+export interface DiffEntry {
+    /** Repo-relative path. */
+    path: string;
+    status: "added" | "modified" | "deleted" | "renamed";
+    /** Pre-change content. Undefined when status === "added". */
+    beforeContent?: string;
+    /** Post-change content. Undefined when status === "deleted". */
+    afterContent?: string;
+    /** Original path when status === "renamed". */
+    fromPath?: string;
+}
+/** Languages used to filter Layer A patterns + AST assertions. */
+export type SensorLanguage = "typescript" | "javascript" | "python" | "ruby" | "go" | "rust" | "sql";
+/** One pattern entry from .cairn/config/stub-patterns.yaml. */
+export interface StubPattern {
+    id: string;
+    languages: SensorLanguage[];
+    description: string;
+    regex: string;
+    severity: "hard" | "soft";
+}
+export interface StubCatalog {
+    version: number;
+    patterns: StubPattern[];
+}
+/** YAML block the agent emits at end of turn. */
+export interface AttestationDelivered {
+    symbol: string;
+    path?: string;
+    behavior: "full" | "partial" | "scaffolded";
+    sensors_passed?: string[];
+}
+export interface AttestationDeferred {
+    symbol: string;
+    reason: string;
+}
+export interface Attestation {
+    delivered: AttestationDelivered[];
+    deferred: AttestationDeferred[];
+    known_limitations: string[];
+    todos_introduced: number;
+    stubs_introduced: number;
+    files_touched: string[];
+    /** Set when the agent could not proceed; runner reports it as soft finding. */
+    blocked_by?: {
+        reason: string;
+        needed_from_operator?: string;
+    };
+}
+/**
+ * Project-extension block resolved from workflow.md `<project>:` extension.
+ * Sensors that trigger on `glob_keys` look up the matching key here.
+ */
+export interface ProjectGlobs {
+    route_handler_globs?: string[];
+    dto_globs?: string[];
+    generator_source_globs?: string[];
+    high_stakes_globs?: string[];
+    /** Off-limits — file_must_not_be_modified assertions also enforce these. */
+    off_limits?: string[];
+    [key: string]: string[] | undefined;
+}
+export interface SensorInput {
+    /** Absolute path to the mirror checkout. */
+    mirrorPath: string;
+    /** origin/main SHA pinned at workspace prep. */
+    shaPin: string;
+    /** Files changed in this run, content already loaded. */
+    changedFiles: DiffEntry[];
+    /** Parsed attestation; undefined if the agent emitted none (Layer B fails). */
+    attestation: Attestation | undefined;
+    /** Decisions accepted in scope of this diff. Already filtered. */
+    decisionsInScope: DecisionFrontmatter[];
+    /** Layer A catalog. */
+    stubCatalog: StubCatalog;
+    /** Stack profile language list — pattern filtering. */
+    languages: SensorLanguage[];
+    /** Project-extension globs. */
+    projectGlobs: ProjectGlobs;
+    /** Run id used in log lines. */
+    runId: string;
+}
+export interface SensorFinding {
+    /** id from sensors.yaml — e.g., "stub-pattern-catalog". */
+    sensor_id: string;
+    /** Layer A only — the pattern that matched. */
+    pattern_id?: string;
+    /** Decision-assertions only — the failing decision. */
+    decision_id?: string;
+    /** Decision-assertions only — the assertion that failed. */
+    assertion_id?: string;
+    /** Where the failure surfaced (repo-relative). */
+    path?: string;
+    /** Line number, 1-based. */
+    line?: number;
+    /** Verbatim text that caused the finding. */
+    matched_text?: string;
+    /** Human-readable, remediation-shaped one-liner. */
+    message: string;
+    severity: "hard" | "soft";
+}
+export interface SensorResult {
+    sensor_id: string;
+    ok: boolean;
+    duration_ms: number;
+    findings: SensorFinding[];
+    /** Set when the sensor opted out (e.g. no diff hits its glob keys). */
+    skipped?: {
+        reason: string;
+    };
+}
+/** Aggregated outcome of a single sensor sweep. */
+export interface SensorSweepResult {
+    ok: boolean;
+    hard_failures: number;
+    soft_findings: number;
+    results: SensorResult[];
+    /** Remediation prompt body to feed back to the agent on retry. Empty when ok. */
+    remediation_prompt: string;
+    duration_ms: number;
+}

package/dist/sensors/types.js

@@ -0,0 +1,14 @@
+/**
+ * Sensor types — Phase 9 honest-agent invariants stack.
+ *
+ * Sensors run after the implementer agent finishes. Each sensor reads a
+ * `SensorInput` (diff + attestation + decisions + project block) and emits
+ * `SensorFinding[]`. The orchestrator collects every sensor's `SensorResult`,
+ * builds a remediation prompt from any findings, and either passes the run
+ * through or feeds the prompt back to the agent for retry.
+ *
+ * Per PRIMER §10. Per OpenAI's pattern: failure messages are remediation
+ * prompts the agent consumes on retry.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/sensors/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sensors/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/session/events-marker.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Per-session events marker — `.cairn/sessions/<id>/events-marker.json`.
+ *
+ * Records the timestamp at which a session armed its events watch. The
+ * Stop hook (step 4) reads `eventsSince(repoRoot, marker.ts)` and
+ * surfaces only events that landed after this session started.
+ *
+ * Spec: PLUGIN_ARCHITECTURE §7 (invalidation events).
+ */
+export interface EventsMarker {
+    /** ms epoch at which the session armed its events watch. */
+    ts: number;
+    /** ms epoch of the last poll the Stop hook performed. Defaults to ts. */
+    last_polled_ts: number;
+}
+/** Absolute path to the marker file for `sessionId`. */
+export declare function eventsMarkerPath(repoRoot: string, sessionId: string): string;
+/**
+ * Seed the marker at session start. If a marker already exists (e.g.
+ * the SessionStart hook ran twice), the existing marker is preserved
+ * and returned unchanged.
+ */
+export declare function seedEventsMarker(args: {
+    repoRoot: string;
+    sessionId: string;
+    ts?: number;
+}): EventsMarker;
+/** Read the marker. Returns null when absent or malformed. */
+export declare function readEventsMarker(repoRoot: string, sessionId: string): EventsMarker | null;
+/**
+ * Stamp the marker's `last_polled_ts`. Called by the Stop hook after
+ * draining events so the next poll only sees newer ones. Safe to call
+ * before the marker exists — falls through and seeds.
+ */
+export declare function stampEventsPoll(args: {
+    repoRoot: string;
+    sessionId: string;
+    ts: number;
+}): EventsMarker;

package/dist/session/events-marker.js

@@ -0,0 +1,74 @@
+/**
+ * Per-session events marker — `.cairn/sessions/<id>/events-marker.json`.
+ *
+ * Records the timestamp at which a session armed its events watch. The
+ * Stop hook (step 4) reads `eventsSince(repoRoot, marker.ts)` and
+ * surfaces only events that landed after this session started.
+ *
+ * Spec: PLUGIN_ARCHITECTURE §7 (invalidation events).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { sessionStateDir } from "../paths/index.js";
+const MARKER_FILE = "events-marker.json";
+/** Absolute path to the marker file for `sessionId`. */
+export function eventsMarkerPath(repoRoot, sessionId) {
+    return join(sessionStateDir(repoRoot, sessionId), MARKER_FILE);
+}
+/**
+ * Seed the marker at session start. If a marker already exists (e.g.
+ * the SessionStart hook ran twice), the existing marker is preserved
+ * and returned unchanged.
+ */
+export function seedEventsMarker(args) {
+    const dir = sessionStateDir(args.repoRoot, args.sessionId);
+    const path = join(dir, MARKER_FILE);
+    if (existsSync(path)) {
+        try {
+            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            if (typeof parsed?.ts === "number") {
+                const last = typeof parsed.last_polled_ts === "number" ? parsed.last_polled_ts : parsed.ts;
+                return { ts: parsed.ts, last_polled_ts: last };
+            }
+        }
+        catch {
+            // fall through and overwrite
+        }
+    }
+    const ts = args.ts ?? Date.now();
+    const marker = { ts, last_polled_ts: ts };
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, `${JSON.stringify(marker, null, 2)}\n`, "utf8");
+    return marker;
+}
+/** Read the marker. Returns null when absent or malformed. */
+export function readEventsMarker(repoRoot, sessionId) {
+    const path = eventsMarkerPath(repoRoot, sessionId);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof parsed?.ts !== "number")
+            return null;
+        const last = typeof parsed.last_polled_ts === "number" ? parsed.last_polled_ts : parsed.ts;
+        return { ts: parsed.ts, last_polled_ts: last };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Stamp the marker's `last_polled_ts`. Called by the Stop hook after
+ * draining events so the next poll only sees newer ones. Safe to call
+ * before the marker exists — falls through and seeds.
+ */
+export function stampEventsPoll(args) {
+    const existing = readEventsMarker(args.repoRoot, args.sessionId);
+    const baseTs = existing?.ts ?? args.ts;
+    const marker = { ts: baseTs, last_polled_ts: args.ts };
+    const dir = sessionStateDir(args.repoRoot, args.sessionId);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(eventsMarkerPath(args.repoRoot, args.sessionId), `${JSON.stringify(marker, null, 2)}\n`, "utf8");
+    return marker;
+}
+//# sourceMappingURL=events-marker.js.map

package/dist/session/events-marker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events-marker.js","sourceRoot":"","sources":["../../src/session/events-marker.ts"],"names":[],"mappings":"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"}

package/dist/session/id.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Session id resolution + per-session directory lifecycle.
+ *
+ * Per PLUGIN_ARCHITECTURE §7, each Claude Code session owns a
+ * `.cairn/sessions/<session-id>/` directory holding its mutable state
+ * (status.json, current task pointer, run notes). The directory is
+ * created at SessionStart and removed at SessionEnd. Stale dirs left
+ * behind by crashed sessions (no live PID, > MAX_AGE_MS old) are GC'd
+ * by the next SessionStart in any session.
+ *
+ * Concurrency: session dirs are owned by one session — no lock. The
+ * GC sweep only deletes dirs whose PID is dead OR whose mtime is past
+ * the staleness threshold; it never touches a live session's dir.
+ */
+/** Session id payload shape — Claude Code's hook stdin includes `session_id`. */
+export interface SessionIdSource {
+    session_id?: unknown;
+}
+/**
+ * Resolve a session id from a hook payload. Prefers Claude Code's
+ * `session_id` when present; otherwise generates a uuid for the
+ * caller to use (CLI / test invocation).
+ */
+export declare function resolveSessionId(payload: SessionIdSource | null | undefined): string;
+export interface SessionMeta {
+    /** Session id (post-sanitize, matches the dir name). */
+    session_id: string;
+    /** ISO timestamp the session dir was created. */
+    started_at: string;
+    /** PID of the Claude Code process that owns the session, when known. */
+    pid: number | null;
+}
+export interface EnsureSessionDirArgs {
+    repoRoot: string;
+    sessionId: string;
+    /**
+     * PID of the owning process. Default `process.pid` (the SessionStart
+     * hook subprocess — short-lived, but its parent Claude Code PID is
+     * not exposed via the payload, so subprocess PID is the best proxy
+     * for "was this session started by a live process at this time").
+     */
+    pid?: number | null;
+}
+export interface EnsureSessionDirResult {
+    /** Absolute path to the per-session dir. */
+    dir: string;
+    /** Whether the dir was just created (false if it already existed). */
+    created: boolean;
+    /** Meta written into `meta.json`. */
+    meta: SessionMeta;
+}
+/**
+ * Create (or refresh) the per-session directory and write `meta.json`.
+ * Idempotent — if the dir exists already, the existing meta is read,
+ * `pid` and `started_at` left intact when valid.
+ */
+export declare function ensureSessionDir(args: EnsureSessionDirArgs): EnsureSessionDirResult;
+/**
+ * Remove the per-session directory. Returns true when something was
+ * removed, false when the dir was already absent.
+ */
+export declare function cleanupSession(repoRoot: string, sessionId: string): boolean;
+export interface GcStaleSessionsArgs {
+    repoRoot: string;
+    /** ISO time threshold; dirs older than this AND with a dead PID are removed. Default 24h. */
+    maxAgeMs?: number;
+    /** Override Date.now() for tests. */
+    now?: () => number;
+}
+export interface GcStaleSessionsResult {
+    /** Session ids that were removed. */
+    removed: string[];
+    /** Session ids that were inspected but kept (live PID or fresh). */
+    kept: string[];
+}
+/**
+ * Sweep the sessions directory and remove dirs that look abandoned —
+ * either older than `maxAgeMs` AND with a dead PID, or with a malformed
+ * meta.json. Live sessions (PID alive) are never touched, regardless
+ * of age. A missing PID counts as "dead" so dirs from operator-deleted
+ * meta files don't accumulate.
+ */
+export declare function gcStaleSessions(args: GcStaleSessionsArgs): GcStaleSessionsResult;

package/dist/session/id.js

@@ -0,0 +1,166 @@
+/**
+ * Session id resolution + per-session directory lifecycle.
+ *
+ * Per PLUGIN_ARCHITECTURE §7, each Claude Code session owns a
+ * `.cairn/sessions/<session-id>/` directory holding its mutable state
+ * (status.json, current task pointer, run notes). The directory is
+ * created at SessionStart and removed at SessionEnd. Stale dirs left
+ * behind by crashed sessions (no live PID, > MAX_AGE_MS old) are GC'd
+ * by the next SessionStart in any session.
+ *
+ * Concurrency: session dirs are owned by one session — no lock. The
+ * GC sweep only deletes dirs whose PID is dead OR whose mtime is past
+ * the staleness threshold; it never touches a live session's dir.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { sessionStateDir, sessionsDir } from "../paths/index.js";
+/**
+ * Stale-session GC threshold. A session dir whose PID is dead AND whose
+ * `meta.json` `started_at` is older than this gets removed at the next
+ * SessionStart. 24h matches the spec.
+ */
+const MAX_STALE_AGE_MS = 24 * 60 * 60 * 1000;
+/**
+ * Resolve a session id from a hook payload. Prefers Claude Code's
+ * `session_id` when present; otherwise generates a uuid for the
+ * caller to use (CLI / test invocation).
+ */
+export function resolveSessionId(payload) {
+    const candidate = payload?.session_id;
+    if (typeof candidate === "string" && candidate.length > 0)
+        return candidate;
+    return randomUUID();
+}
+/**
+ * Create (or refresh) the per-session directory and write `meta.json`.
+ * Idempotent — if the dir exists already, the existing meta is read,
+ * `pid` and `started_at` left intact when valid.
+ */
+export function ensureSessionDir(args) {
+    const dir = sessionStateDir(args.repoRoot, args.sessionId);
+    const metaPath = join(dir, "meta.json");
+    const existed = existsSync(dir);
+    let meta;
+    if (existed && existsSync(metaPath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(metaPath, "utf8"));
+            const startedAt = typeof parsed.started_at === "string" ? parsed.started_at : new Date().toISOString();
+            const pidVal = typeof parsed.pid === "number" ? parsed.pid : (args.pid ?? process.pid);
+            meta = {
+                session_id: args.sessionId,
+                started_at: startedAt,
+                pid: pidVal,
+            };
+        }
+        catch {
+            meta = freshMeta(args);
+        }
+    }
+    else {
+        meta = freshMeta(args);
+    }
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(metaPath, `${JSON.stringify(meta, null, 2)}\n`, "utf8");
+    return { dir, created: !existed, meta };
+}
+function freshMeta(args) {
+    return {
+        session_id: args.sessionId,
+        started_at: new Date().toISOString(),
+        pid: args.pid === undefined ? process.pid : args.pid,
+    };
+}
+/**
+ * Remove the per-session directory. Returns true when something was
+ * removed, false when the dir was already absent.
+ */
+export function cleanupSession(repoRoot, sessionId) {
+    const dir = sessionStateDir(repoRoot, sessionId);
+    if (!existsSync(dir))
+        return false;
+    rmSync(dir, { recursive: true, force: true });
+    return true;
+}
+/**
+ * Sweep the sessions directory and remove dirs that look abandoned —
+ * either older than `maxAgeMs` AND with a dead PID, or with a malformed
+ * meta.json. Live sessions (PID alive) are never touched, regardless
+ * of age. A missing PID counts as "dead" so dirs from operator-deleted
+ * meta files don't accumulate.
+ */
+export function gcStaleSessions(args) {
+    const root = sessionsDir(args.repoRoot);
+    const removed = [];
+    const kept = [];
+    if (!existsSync(root))
+        return { removed, kept };
+    const maxAge = args.maxAgeMs ?? MAX_STALE_AGE_MS;
+    const now = args.now ? args.now() : Date.now();
+    const entries = readdirSync(root, { withFileTypes: true, encoding: "utf8" });
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const sessionId = entry.name;
+        const dir = join(root, sessionId);
+        const metaPath = join(dir, "meta.json");
+        let meta = null;
+        let mtime;
+        try {
+            mtime = statSync(dir).mtimeMs;
+        }
+        catch {
+            mtime = 0;
+        }
+        if (existsSync(metaPath)) {
+            try {
+                meta = JSON.parse(readFileSync(metaPath, "utf8"));
+            }
+            catch {
+                meta = null;
+            }
+        }
+        const pid = meta && typeof meta.pid === "number" ? meta.pid : null;
+        const startedAt = meta && typeof meta.started_at === "string" ? Date.parse(meta.started_at) : NaN;
+        const ageMs = Number.isFinite(startedAt) ? now - startedAt : now - mtime;
+        const pidAlive = pid !== null && isPidAlive(pid);
+        if (pidAlive) {
+            kept.push(sessionId);
+            continue;
+        }
+        if (ageMs >= maxAge) {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+                removed.push(sessionId);
+            }
+            catch {
+                kept.push(sessionId);
+            }
+        }
+        else {
+            kept.push(sessionId);
+        }
+    }
+    return { removed, kept };
+}
+/**
+ * Probe whether `pid` belongs to a live process. `kill(pid, 0)` is the
+ * portable way; throws ESRCH for dead PIDs. EPERM means "alive but not
+ * ours" — still alive.
+ */
+function isPidAlive(pid) {
+    if (!Number.isFinite(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EPERM")
+            return true;
+        return false;
+    }
+}
+//# sourceMappingURL=id.js.map

package/dist/session/id.js.map

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

package/dist/session/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Per-session state lifecycle.
+ *
+ * Owns `.cairn/sessions/<id>/` — the directory each Claude Code
+ * session uses for its own status.json, current task pointer, and run
+ * notes. Spec: PLUGIN_ARCHITECTURE §7.
+ *
+ * SessionStart hook calls `ensureSessionDir` + `gcStaleSessions`.
+ * SessionEnd hook calls `cleanupSession`.
+ */
+export { cleanupSession, ensureSessionDir, gcStaleSessions, resolveSessionId, } from "./id.js";
+export type { EnsureSessionDirArgs, EnsureSessionDirResult, GcStaleSessionsArgs, GcStaleSessionsResult, SessionIdSource, SessionMeta, } from "./id.js";
+export { eventsMarkerPath, readEventsMarker, seedEventsMarker, stampEventsPoll, } from "./events-marker.js";
+export type { EventsMarker } from "./events-marker.js";