klyro 0.1.63 → 1.0.1

package/dist/mcp/registry.js

@@ -0,0 +1,244 @@
+/**
+ * P1 — MCP tool registration (r-11-17.md §3.1).
+ *
+ * Exposes MCP server tools through the {@link ToolRegistry} under
+ * `mcp__<server>__<tool>` names. Security properties (non-negotiable):
+ *
+ *   1. Deny-by-default: `evaluateMcpPolicy` runs BEFORE any client I/O; a
+ *      denied tool returns POLICY_DENIED without touching the subprocess.
+ *   2. Redact-before-transcript: every success value AND error message passes
+ *      through `redact()` before it can reach the model or trace.
+ *   3. `requireApproval` servers add an ask-rule to the PolicyEngine so the
+ *      runtime loop prompts before executing.
+ *
+ * Permission class: no code in src consumes `Tool.permission` (it is
+ * write-only metadata today), so we pick the most restrictive class,
+ * 'admin' — the same class as `spawn_agent`, since MCP tools execute
+ * arbitrary external side effects (read/write/network) outside our control.
+ */
+import { McpClient, McpError } from './client.js';
+import { loadMcpServers } from './config.js';
+import { evaluateMcpPolicy } from './policy.js';
+import { jsonSchemaToZod } from './schema.js';
+import { redact } from '../policy/secret-redactor.js';
+import { defineTool } from '../tools/types.js';
+/** Hard cap so generated names always fit model/tool-name limits. */
+const MAX_NAME_LEN = 64;
+/** Server part is capped here; the tool part takes whatever remains. */
+const MAX_SERVER_PART = 20;
+/** Success values are redacted FIRST, then truncated to this many chars. */
+export const MCP_SUCCESS_MAX_CHARS = 12_000;
+function sanitizePart(s) {
+    return s.replace(/[^A-Za-z0-9_]/g, '_');
+}
+/**
+ * `mcp__<server>__<tool>`, sanitized, server part ≤20 chars, total ≤64.
+ *
+ * No `'server'`/`'tool'` fallbacks: an empty raw part (or one that
+ * sanitizes to empty) yields an empty segment, and registration skips that
+ * tool with an `empty-name` error instead of masking a misconfiguration
+ * behind a plausible-looking name.
+ */
+export function sanitizeMcpName(server, tool) {
+    const srv = sanitizePart(server).slice(0, MAX_SERVER_PART);
+    const maxTool = Math.max(1, MAX_NAME_LEN - 'mcp__'.length - srv.length - '__'.length);
+    const tl = sanitizePart(tool).slice(0, maxTool);
+    return `mcp__${srv}__${tl}`;
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function executeMcpTool(spec, toolDef, client, input, ctx) {
+    try {
+        // (1) Deny-by-default — runs BEFORE any client I/O.
+        const decision = evaluateMcpPolicy(spec.policy, toolDef.name);
+        if (!decision.allowed) {
+            return {
+                ok: false,
+                error: { code: 'POLICY_DENIED', message: decision.reason ?? `mcp tool denied: ${toolDef.name}` },
+            };
+        }
+        // (2) Delegate to the server, honouring abort.
+        let res;
+        try {
+            res = await client.callTool(toolDef.name, input, ctx.signal);
+        }
+        catch (err) {
+            // (3) Typed server failures keep their code; everything else is TOOL_ERROR.
+            // Redact BEFORE the message can reach the model/trace.
+            if (err instanceof McpError) {
+                return { ok: false, error: { code: err.code, message: redact(err.message) } };
+            }
+            return { ok: false, error: { code: 'TOOL_ERROR', message: redact(errMessage(err)) } };
+        }
+        // (4) Server-reported error → TOOL_ERROR, redacted, bounded.
+        if (res.isError) {
+            return { ok: false, error: { code: 'TOOL_ERROR', message: redact(res.text).slice(0, 2000) } };
+        }
+        // (5) Success — redact BEFORE the value reaches the model/trace, then
+        // truncate to a bounded size with a marker.
+        const redacted = redact(res.text);
+        if (redacted.length > MCP_SUCCESS_MAX_CHARS) {
+            return {
+                ok: true,
+                value: redacted.slice(0, MCP_SUCCESS_MAX_CHARS) +
+                    `\n... [truncated ${redacted.length - MCP_SUCCESS_MAX_CHARS} chars]`,
+            };
+        }
+        return { ok: true, value: redacted };
+    }
+    catch (err) {
+        // Tool contract: never throw — always return a ToolResult.
+        return { ok: false, error: { code: 'TOOL_ERROR', message: redact(errMessage(err)) } };
+    }
+}
+export async function registerMcpServers(cfg, opts) {
+    const { registry, policy } = opts;
+    const factory = opts.clientFactory ?? ((name, spec) => new McpClient(name, spec));
+    const registered = [];
+    const errors = [];
+    const skipped = [];
+    const clients = [];
+    // Sanitized name → first raw (server, tool) that claimed it, used to tell
+    // sanitization-collisions apart from exact-duplicates (see below).
+    const claimed = new Map();
+    for (const [server, spec] of Object.entries(cfg.servers)) {
+        try {
+            // enabledServers-style: skip disabled entries silently.
+            if (spec.disabled)
+                continue;
+            // Default factory returns a bare McpClient — connect it here so fake
+            // McpClientLike factories (no connect method) also work.
+            let client;
+            try {
+                client = await factory(server, spec);
+                const withConnect = client;
+                if (typeof withConnect.connect === 'function') {
+                    await withConnect.connect();
+                }
+            }
+            catch (err) {
+                errors.push({ server, message: errMessage(err) });
+                continue; // never throw — keep registering other servers
+            }
+            let tools;
+            try {
+                tools = await client.listTools();
+            }
+            catch (err) {
+                errors.push({ server, message: errMessage(err) });
+                try {
+                    await client.close();
+                }
+                catch {
+                    /* best-effort */
+                }
+                continue;
+            }
+            clients.push(client);
+            for (const toolDef of tools) {
+                // Empty raw names (or names that sanitize to empty) are a
+                // misconfiguration — skip as an error, never with a fallback name.
+                if (!server || !toolDef.name || sanitizePart(server) === '' || sanitizePart(toolDef.name) === '') {
+                    errors.push({ server, message: `empty-name: server "${server}" tool "${toolDef.name}" sanitizes to an empty name part (skipped)` });
+                    continue;
+                }
+                const name = sanitizeMcpName(server, toolDef.name);
+                const prior = claimed.get(name);
+                if (prior) {
+                    if (prior.server === server && prior.tool === toolDef.name) {
+                        skipped.push({ name, reason: 'name-collision' });
+                        continue;
+                    }
+                    // Sanitization-collision: two DIFFERENT raw names map to the same
+                    // sanitized name. This is an error (not a silent skip) and names
+                    // both raw identities so the conflict is actionable.
+                    errors.push({
+                        server,
+                        message: `name collision: "${prior.server}/${prior.tool}" and "${server}/${toolDef.name}" both sanitize to "${name}" (skipped)`,
+                    });
+                    continue;
+                }
+                if (registry.get(name)) {
+                    // Exact-duplicate: the literal name already exists (e.g. a
+                    // builtin) — skip quietly, first registration wins.
+                    skipped.push({ name, reason: 'name-collision' });
+                    continue;
+                }
+                claimed.set(name, { server, tool: toolDef.name });
+                // Capture per-tool bindings for the closure.
+                const boundSpec = spec;
+                const boundDef = toolDef;
+                const boundClient = client;
+                const tool = defineTool({
+                    name,
+                    description: `[mcp:${server}] ${boundDef.description ?? boundDef.name}`,
+                    inputSchema: jsonSchemaToZod(boundDef.inputSchema ?? { type: 'object' }),
+                    // 'admin': most restrictive class — MCP tools run arbitrary
+                    // external side effects; nothing in src reads this field yet.
+                    permission: 'admin',
+                    execute: (input, ctx) => executeMcpTool(boundSpec, boundDef, boundClient, input, ctx),
+                });
+                registry.register(tool);
+                registered.push(name);
+                if (boundSpec.policy?.requireApproval && policy) {
+                    policy.addAsk(name);
+                }
+            }
+        }
+        catch (err) {
+            // Belt-and-braces: registerMcpServers never throws.
+            errors.push({ server, message: errMessage(err) });
+        }
+    }
+    return {
+        registered,
+        errors,
+        skipped,
+        closeAll: async () => {
+            await Promise.allSettled(clients.map((c) => c.close()));
+        },
+    };
+}
+export async function loadAndRegisterMcp(opts) {
+    try {
+        const cfg = loadMcpServers(opts.cwd);
+        const filtered = {};
+        const gateErrors = [];
+        for (const [name, spec] of Object.entries(cfg.servers)) {
+            if (cfg.sources[name] !== 'project') {
+                filtered[name] = spec;
+                continue;
+            }
+            if (!opts.approveProjectServer) {
+                gateErrors.push({ server: name, message: 'project server requires approval (skipped)' });
+                continue;
+            }
+            let ok = false;
+            try {
+                ok = await opts.approveProjectServer({ name, source: 'project' });
+            }
+            catch (err) {
+                gateErrors.push({ server: name, message: `project server approval error (skipped): ${errMessage(err)}` });
+                continue;
+            }
+            if (!ok) {
+                gateErrors.push({ server: name, message: 'project server not approved (skipped)' });
+                continue;
+            }
+            filtered[name] = spec;
+        }
+        const res = await registerMcpServers({ servers: filtered }, opts);
+        res.errors.unshift(...gateErrors);
+        return res;
+    }
+    catch (err) {
+        // Never throws — surface load failures as error entries.
+        return {
+            registered: [],
+            errors: [{ server: '*', message: errMessage(err) }],
+            skipped: [],
+            closeAll: async () => { },
+        };
+    }
+}

package/dist/mcp/schema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * P1 — JSON Schema → Zod converter for MCP tool input schemas.
+ *
+ * MCP servers describe inputs with JSON Schema; Klyro tools validate with
+ * Zod. Supported subset:
+ *
+ *   - `type`: `object` (with `properties` + `required`), `string`,
+ *     `number`, `integer`, `boolean`, `array` (with `items`)
+ *   - string `enum` (handled before `type`)
+ *   - a schema object WITHOUT a `type` but WITH a `properties` map is
+ *     treated as `type: 'object'` (many servers omit the type)
+ *
+ * Anything else — an empty/absent schema, non-object input, an unknown
+ * `type` — falls back to `z.unknown()` (accept anything, validate nothing).
+ * Validation must never trust, but must also never crash on exotic schemas.
+ */
+import { z } from 'zod';
+export declare function jsonSchemaToZod(schema: unknown): z.ZodTypeAny;

package/dist/mcp/schema.js

@@ -0,0 +1,57 @@
+/**
+ * P1 — JSON Schema → Zod converter for MCP tool input schemas.
+ *
+ * MCP servers describe inputs with JSON Schema; Klyro tools validate with
+ * Zod. Supported subset:
+ *
+ *   - `type`: `object` (with `properties` + `required`), `string`,
+ *     `number`, `integer`, `boolean`, `array` (with `items`)
+ *   - string `enum` (handled before `type`)
+ *   - a schema object WITHOUT a `type` but WITH a `properties` map is
+ *     treated as `type: 'object'` (many servers omit the type)
+ *
+ * Anything else — an empty/absent schema, non-object input, an unknown
+ * `type` — falls back to `z.unknown()` (accept anything, validate nothing).
+ * Validation must never trust, but must also never crash on exotic schemas.
+ */
+import { z } from 'zod';
+function objectFrom(s) {
+    const props = s['properties'] ?? {};
+    const required = new Set(Array.isArray(s['required']) ? s['required'].filter((v) => typeof v === 'string') : []);
+    const shape = {};
+    for (const [k, v] of Object.entries(props)) {
+        const inner = jsonSchemaToZod(v);
+        shape[k] = required.has(k) ? inner : inner.optional();
+    }
+    return z.looseObject(shape);
+}
+export function jsonSchemaToZod(schema) {
+    if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+        return z.unknown();
+    }
+    const s = schema;
+    const enumerated = Array.isArray(s['enum']) ? s['enum'] : undefined;
+    if (enumerated && enumerated.length > 0 && enumerated.every((v) => typeof v === 'string')) {
+        return z.enum(enumerated);
+    }
+    const t = s['type'];
+    if (t === 'object' || (t === undefined && s['properties'] !== undefined && typeof s['properties'] === 'object' && s['properties'] !== null && !Array.isArray(s['properties']))) {
+        return objectFrom(s);
+    }
+    switch (t) {
+        case 'string':
+            return z.string();
+        case 'number':
+            return z.number();
+        case 'integer':
+            return z.number().int();
+        case 'boolean':
+            return z.boolean();
+        case 'array': {
+            const items = jsonSchemaToZod(s['items']);
+            return z.array(items);
+        }
+        default:
+            return z.unknown();
+    }
+}

package/dist/mcp/trust.d.ts

@@ -0,0 +1,20 @@
+import type { McpServerSpec } from './config.js';
+export interface McpTrustRecord {
+    sha256: string;
+    trustedAt: number;
+}
+export type McpTrustStore = Record<string, McpTrustRecord>;
+/** sha256 of the canonical (key-sorted) JSON encoding of a server spec. */
+export declare function hashSpec(spec: McpServerSpec): string;
+export declare function defaultMcpTrustStorePath(): string;
+export declare class McpTrust {
+    private readonly storePath;
+    private store;
+    constructor(storePath?: string);
+    private load;
+    private save;
+    /** True only when `name` was approved for exactly this spec hash. */
+    isTrusted(name: string, hash: string): boolean;
+    /** Record approval of `name` for exactly this spec hash. */
+    approve(name: string, hash: string): void;
+}

package/dist/mcp/trust.js

@@ -0,0 +1,74 @@
+/**
+ * P1 — MCP server-spec trust store (hash-based approval persistence).
+ *
+ * Companions the project-server consent gate in `registry.ts`: callers ask
+ * the user to approve a project-sourced server once via
+ * `approveProjectServer`, then persist `(name → sha256(spec))` here so later
+ * runs can auto-approve unchanged specs. Any spec change (new hash) requires
+ * fresh approval. Decisions persist in `~/.klyro/mcp-trust.json`.
+ *
+ * `registry.ts` does NOT use this class directly — callers compose it with
+ * the `approveProjectServer` callback. This module is intentionally
+ * side-effect free on import (file I/O happens in the constructor).
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/** Deterministic JSON: object keys sorted recursively, arrays preserved. */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map((v) => stableStringify(v)).join(',')}]`;
+    const entries = Object.entries(value)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+    return `{${entries.join(',')}}`;
+}
+/** sha256 of the canonical (key-sorted) JSON encoding of a server spec. */
+export function hashSpec(spec) {
+    return crypto.createHash('sha256').update(stableStringify(spec), 'utf-8').digest('hex');
+}
+export function defaultMcpTrustStorePath() {
+    return path.join(os.homedir() || process.cwd(), '.klyro', 'mcp-trust.json');
+}
+export class McpTrust {
+    storePath;
+    store = {};
+    constructor(storePath = defaultMcpTrustStorePath()) {
+        this.storePath = storePath;
+        this.load();
+    }
+    load() {
+        try {
+            const raw = fs.readFileSync(this.storePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                this.store = parsed;
+            }
+        }
+        catch {
+            this.store = {};
+        }
+    }
+    save() {
+        try {
+            fs.mkdirSync(path.dirname(this.storePath), { recursive: true });
+            fs.writeFileSync(this.storePath, JSON.stringify(this.store, null, 2), 'utf-8');
+        }
+        catch {
+            /* best-effort — trust stays in memory for the session */
+        }
+    }
+    /** True only when `name` was approved for exactly this spec hash. */
+    isTrusted(name, hash) {
+        const rec = this.store[name];
+        return !!rec && rec.sha256 === hash;
+    }
+    /** Record approval of `name` for exactly this spec hash. */
+    approve(name, hash) {
+        this.store[name] = { sha256: hash, trustedAt: Date.now() };
+        this.save();
+    }
+}

package/dist/persistence/audit.d.ts

@@ -2,6 +2,11 @@
  * Audit log — append-only JSONL of runtime events. Same shape as the
  * future durable-task scheduler will read, so the data layout is
  * forward-compatible.
+ *
+ * Durability: every record is hash-chained. Each line carries `prevHash`
+ * (hex sha256 of the previous line's canonical JSON, 'GENESIS' for the
+ * first line) and `hash` (sha256 of the record-with-prevHash canonical
+ * JSON). `verifyAuditChain` recomputes the chain for `klyro audit`.
  */
 export type AuditEvent = {
     kind: 'session_created';
@@ -68,8 +73,31 @@ export type AuditEvent = {
     attempt: number;
     ts: number;
 };
+export declare const AUDIT_GENESIS = "GENESIS";
+export interface ChainedAuditRecord {
+    prevHash: string;
+    hash: string;
+    [key: string]: unknown;
+}
+/** Canonical JSON: object keys sorted recursively, so hashes are stable. */
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256Hex(s: string): string;
+/** Hash of a chained record excluding its own `hash` field. */
+export declare function hashAuditRecord(record: Record<string, unknown>): string;
 export declare class AuditLog {
     private readonly filePath;
+    /** Serializes chained appends so concurrent writes can't fork the chain. */
+    private chain;
     constructor(filePath: string);
     write(event: AuditEvent): Promise<void>;
+    private appendChained;
 }
+/**
+ * Recompute the hash chain of a session JSONL file.
+ * Sessions live at `<sessionsDir>/<sessionId>.jsonl` (see SessionStore).
+ */
+export declare function verifyAuditChain(sessionsDir: string, sessionId: string): Promise<{
+    ok: boolean;
+    events: number;
+    error?: string;
+}>;

package/dist/persistence/audit.js

@@ -2,14 +2,114 @@
  * Audit log — append-only JSONL of runtime events. Same shape as the
  * future durable-task scheduler will read, so the data layout is
  * forward-compatible.
+ *
+ * Durability: every record is hash-chained. Each line carries `prevHash`
+ * (hex sha256 of the previous line's canonical JSON, 'GENESIS' for the
+ * first line) and `hash` (sha256 of the record-with-prevHash canonical
+ * JSON). `verifyAuditChain` recomputes the chain for `klyro audit`.
  */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
 import { SessionStore } from './store.js';
+export const AUDIT_GENESIS = 'GENESIS';
+/** Canonical JSON: object keys sorted recursively, so hashes are stable. */
+export function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const rec = value;
+    const keys = Object.keys(rec).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(rec[k])}`).join(',')}}`;
+}
+export function sha256Hex(s) {
+    return crypto.createHash('sha256').update(s, 'utf-8').digest('hex');
+}
+/** Hash of a chained record excluding its own `hash` field. */
+export function hashAuditRecord(record) {
+    const { hash: _omit, ...body } = record;
+    void _omit;
+    return sha256Hex(canonicalJson(body));
+}
+async function readLastLine(filePath) {
+    try {
+        const raw = await fs.readFile(filePath, 'utf-8');
+        const lines = raw.split('\n').filter((l) => l.trim());
+        return lines.length > 0 ? lines[lines.length - 1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** prevHash for the next record: hash of the previous line, or GENESIS. */
+async function prevHashFor(filePath) {
+    const last = await readLastLine(filePath);
+    if (!last)
+        return AUDIT_GENESIS;
+    try {
+        const parsed = JSON.parse(last);
+        if (typeof parsed.hash === 'string' && parsed.hash)
+            return parsed.hash;
+        return sha256Hex(canonicalJson(parsed));
+    }
+    catch {
+        return sha256Hex(last);
+    }
+}
 export class AuditLog {
     filePath;
+    /** Serializes chained appends so concurrent writes can't fork the chain. */
+    chain = Promise.resolve();
     constructor(filePath) {
         this.filePath = filePath;
     }
     async write(event) {
-        await SessionStore.appendJsonl(this.filePath, event);
+        const task = this.chain.then(() => this.appendChained(event));
+        // Keep the chain alive across failures; the caller still sees its error.
+        this.chain = task.catch(() => undefined);
+        return task;
+    }
+    async appendChained(event) {
+        const prevHash = await prevHashFor(this.filePath);
+        const body = { ...event, prevHash };
+        const record = { ...body, prevHash, hash: sha256Hex(canonicalJson(body)) };
+        await SessionStore.appendJsonl(this.filePath, record);
+    }
+}
+/**
+ * Recompute the hash chain of a session JSONL file.
+ * Sessions live at `<sessionsDir>/<sessionId>.jsonl` (see SessionStore).
+ */
+export async function verifyAuditChain(sessionsDir, sessionId) {
+    const filePath = path.join(sessionsDir, `${sessionId}.jsonl`);
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        return { ok: false, events: 0, error: `audit log not found: ${filePath}` };
+    }
+    const lines = raw.split('\n').filter((l) => l.trim());
+    let expectedPrev = AUDIT_GENESIS;
+    let events = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return { ok: false, events, error: `line ${i + 1}: unparseable JSON` };
+        }
+        if (parsed.prevHash !== expectedPrev) {
+            return { ok: false, events, error: `line ${i + 1}: prevHash mismatch (chain fork or truncation)` };
+        }
+        if (typeof parsed.hash !== 'string' || parsed.hash !== hashAuditRecord(parsed)) {
+            return { ok: false, events, error: `line ${i + 1}: hash mismatch (tampered record)` };
+        }
+        expectedPrev = parsed.hash;
+        events++;
     }
+    return { ok: true, events };
 }

package/dist/persistence/store.d.ts

@@ -50,6 +50,8 @@ export declare class SessionStore {
     private writeIndex;
     private projectHash;
     private perProjectIndexPath;
+    /** Atomic per-project index write (tmp + fsync + rename). */
+    private writePerProjectIndex;
     private titleFor;
     create(opts: {
         cwd: string;
@@ -61,7 +63,7 @@ export declare class SessionStore {
      * continues with full context instead of starting blank.
      */
     fork(id: string, taskSuffix?: string): Promise<SessionRecord>;
-    /** Delete a session and all its artifacts (record, transcript, jsonl, indexes). */
+    /** Delete a session and all its artifacts (record, transcript, jsonl, lock, indexes). */
     delete(id: string): Promise<boolean>;
     private jsonlPath;
     appendJsonl(id: string, entry: unknown): Promise<void>;
@@ -77,6 +79,28 @@ export declare class SessionStore {
         status?: SessionStatus;
     }): Promise<SessionRecord[]>;
     get(id: string): Promise<SessionRecord | null>;
-    /** Atomic append — survives crashes; suitable for audit log. */
+    /** Atomic append + fsync — survives crashes; suitable for audit log. */
     static appendJsonl(filePath: string, entry: unknown): Promise<void>;
 }
+/**
+ * Redact text blocks of a stored message at the persist boundary.
+ * Handles string content, `{ text }` blocks, arrays of blocks, and plain
+ * objects (observation input/output) via a deep walk over string leaves.
+ * Only secret-shaped strings (key/token/password patterns, [:=-] shapes)
+ * are touched — normal prose passes through unchanged.
+ */
+export declare function redactStoredContent(content: unknown): unknown;
+export interface SessionLockInfo {
+    held: boolean;
+    pid?: number;
+    /** True when the lock holder process is (probably) still running. */
+    alive?: boolean;
+}
+/**
+ * Cross-process session lock probe. The lock file `<sessionsDir>/<id>.lock`
+ * contains the holder's PID. `alive` is resolved via `process.kill(pid, 0)`:
+ * EPERM means alive-but-unpermitted (→ true); ESRCH / other errors → false.
+ */
+export declare function readSessionLock(sessionsDir: string, id: string): SessionLockInfo;
+/** Best-effort release of the cross-process session lock. Never throws. */
+export declare function releaseSessionLock(sessionsDir: string, id: string): Promise<void>;