@mafdet/cli 0.4.0 → 0.4.2

package/dist/index.js

@@ -10,6 +10,7 @@ import { doctorCommand } from "./commands/doctor.js";
 import { embedCommand } from "./commands/embed.js";
 import { speechCommand } from "./commands/speech.js";
 import { modelsCommand } from "./commands/models.js";
+import { sessionsCommand } from "./commands/sessions.js";
 import { ExitCode } from "./output/exit-codes.js";
 import { decideEntry, explainRefusal } from "./tui/route.js";
 // Read from the installed package rather than baking a literal in at build
@@ -36,6 +37,9 @@ Commands:
   account balance   Wallet balance and bonus
   account usage     Requests, tokens and spend over a window
   account subscription  Current plan and Playground allowance
+  sessions list     Conversations saved on this computer
+  sessions show     One saved conversation in detail
+  sessions delete   Remove a saved conversation from this computer
   config list       Show the resolved settings and where each came from
   doctor            Check key, endpoints, model, balance and workspace
   help              Show this help
@@ -110,6 +114,8 @@ export async function run(argv) {
     const io = {
         stdout: (text) => process.stdout.write(text),
         stderr: (text) => process.stderr.write(text),
+        env: process.env,
+        cwd: process.cwd(),
         version: version(),
     };
     if (command === "agent") {
@@ -142,6 +148,8 @@ export async function run(argv) {
         return modelsCommand(argv.slice(1), io);
     if (command === "account")
         return accountCommand(argv.slice(1), io);
+    if (command === "sessions")
+        return sessionsCommand(argv.slice(1), io);
     process.stderr.write(`mafdet: unknown command '${command}'\nRun 'mafdet help' to see available commands.\n`);
     return ExitCode.Usage;
 }

package/dist/security/redact.d.ts

@@ -8,9 +8,32 @@ export declare function redact(value: string): string;
  */
 export declare function redactDeep(value: unknown): unknown;
 /**
- * How a key may be shown: enough to tell two keys apart, never enough to use
- * one. Mafdet keys carry a meaningful prefix (`sk-mafdet-live-…`), so the
- * environment is visible without exposing the secret.
+ * How a key may be *shown*: the environment stays visible, the secret does not.
+ *
+ * ⚠️ This is a display form and nothing else. Every live Mafdet key renders as
+ * the same `sk-mafdet-live-<redacted>`, so two keys cannot be told apart by it.
+ * Use `keyDigest` wherever the question is "was this the same key?".
  */
 export declare function keyFingerprint(apiKey: string): string;
+/**
+ * How a key may be *compared*: a value that identifies which key was used
+ * without being usable as one, and without being confusable with another key.
+ *
+ * Plan §20.3 asks for per-key attribution while forbidding the key on disk, so
+ * what goes to disk is a SHA-256 digest of it. Twelve hex characters is plenty
+ * to separate the handful of keys one person holds, and the digest of a
+ * 40-plus character random secret is not going back the other way.
+ *
+ * The shape is deliberately NOT `sk-…`: `redact()` runs over everything the
+ * session store writes, and anything key-shaped would be replaced there — the
+ * stored value has to be able to survive its own redaction pass.
+ */
+export declare function keyDigest(apiKey: string): string;
+/**
+ * True for a ref written before `keyDigest` existed.
+ *
+ * Those were `keyFingerprint()` output, which is identical for every live key,
+ * so they cannot answer "same key?" and must not be treated as if they could.
+ */
+export declare function isComparableKeyRef(ref: string | undefined): ref is string;
 //# sourceMappingURL=redact.d.ts.map

package/dist/security/redact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../src/security/redact.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,QAAQ,eAAe,CAAC;AAErC,4DAA4D;AAC5D,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAY5C;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAkBlD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOrD"}
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../src/security/redact.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,QAAQ,eAAe,CAAC;AAErC,4DAA4D;AAC5D,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAY5C;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAkBlD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOrD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIhD;AAgBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,GAAG,IAAI,MAAM,CAEzE"}

package/dist/security/redact.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 // Every string that can reach a terminal, a log, an error or telemetry passes
 // through here first. Credentials leak through the boring paths — an exception
 // message, a --debug dump, a pasted bug report — so redaction lives at the
@@ -46,9 +47,11 @@ export function redactDeep(value) {
     return value;
 }
 /**
- * How a key may be shown: enough to tell two keys apart, never enough to use
- * one. Mafdet keys carry a meaningful prefix (`sk-mafdet-live-…`), so the
- * environment is visible without exposing the secret.
+ * How a key may be *shown*: the environment stays visible, the secret does not.
+ *
+ * ⚠️ This is a display form and nothing else. Every live Mafdet key renders as
+ * the same `sk-mafdet-live-<redacted>`, so two keys cannot be told apart by it.
+ * Use `keyDigest` wherever the question is "was this the same key?".
  */
 export function keyFingerprint(apiKey) {
     const trimmed = apiKey.trim();
@@ -59,3 +62,45 @@ export function keyFingerprint(apiKey) {
     const head = parts.slice(0, 3).join("-");
     return `${head}-${REDACTED}`;
 }
+/**
+ * How a key may be *compared*: a value that identifies which key was used
+ * without being usable as one, and without being confusable with another key.
+ *
+ * Plan §20.3 asks for per-key attribution while forbidding the key on disk, so
+ * what goes to disk is a SHA-256 digest of it. Twelve hex characters is plenty
+ * to separate the handful of keys one person holds, and the digest of a
+ * 40-plus character random secret is not going back the other way.
+ *
+ * The shape is deliberately NOT `sk-…`: `redact()` runs over everything the
+ * session store writes, and anything key-shaped would be replaced there — the
+ * stored value has to be able to survive its own redaction pass.
+ */
+export function keyDigest(apiKey) {
+    const trimmed = apiKey.trim();
+    if (trimmed.length === 0)
+        return "";
+    return `${environmentLabel(trimmed)}:${createHash("sha256").update(trimmed).digest("hex").slice(0, 12)}`;
+}
+/**
+ * `sk-mafdet-live-<secret>` → `mafdet-live`, and anything else → `key`.
+ *
+ * Only the segments `keyFingerprint` already prints are used, so this exposes
+ * nothing new; a key that does not have that shape gets no label at all rather
+ * than a guess that might quote part of the secret.
+ */
+function environmentLabel(key) {
+    const parts = key.split("-");
+    if (parts.length < 4 || parts[0] !== "sk")
+        return "key";
+    const label = parts.slice(1, 3).join("-");
+    return /^[A-Za-z0-9_-]+$/.test(label) ? label : "key";
+}
+/**
+ * True for a ref written before `keyDigest` existed.
+ *
+ * Those were `keyFingerprint()` output, which is identical for every live key,
+ * so they cannot answer "same key?" and must not be treated as if they could.
+ */
+export function isComparableKeyRef(ref) {
+    return typeof ref === "string" && ref.length > 0 && !ref.includes(REDACTED);
+}

package/dist/sessions/index-file.d.ts

@@ -0,0 +1,38 @@
+import { type SessionMetadata } from "./store.js";
+export interface IndexEntry {
+    readonly session_id: string;
+    readonly title: string;
+    readonly updated_at: string;
+    readonly model_id: string;
+    readonly workspace: string;
+    readonly model_requests: number;
+    readonly estimated_charge_micro_usd: string;
+}
+export interface SessionIndex {
+    readonly schema_version: number;
+    readonly sessions: readonly IndexEntry[];
+}
+export declare function indexPath(root: string): string;
+/**
+ * Rebuild from the metadata files, which are the truth.
+ *
+ * A session whose metadata cannot be read is skipped rather than fatal: one
+ * damaged directory must not hide every other conversation.
+ */
+export declare function rebuildIndex(root: string): SessionIndex;
+/** Temp file plus rename, so a crash never leaves half an index. */
+export declare function writeIndex(root: string, index: SessionIndex): void;
+/**
+ * Read the index, rebuilding whenever it cannot be trusted.
+ *
+ * "Cannot be trusted" includes disagreeing with the directory: an index that
+ * is merely stale would otherwise hide a session that exists, which is worse
+ * than the cost of a rebuild.
+ */
+export declare function loadIndex(root: string): SessionIndex;
+/** Record or update one session, leaving the rest of the index alone. */
+export declare function upsertIndexEntry(root: string, metadata: SessionMetadata): SessionIndex;
+export declare function removeIndexEntry(root: string, sessionId: string): SessionIndex;
+/** Stray temp files from a killed write, which nothing else will clean up. */
+export declare function sweepTempFiles(root: string): number;
+//# sourceMappingURL=index-file.d.ts.map

package/dist/sessions/index-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-file.d.ts","sourceRoot":"","sources":["../../src/sessions/index-file.ts"],"names":[],"mappings":"AAqBA,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,YAAY,CAAC;AAKpB,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAC;CAC7C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAC;CAC1C;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAmBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAoBvD;AAED,oEAAoE;AACpE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CAiBlE;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAapD;AAwBD,yEAAyE;AACzE,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,eAAe,GACxB,YAAY,CAUd;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,YAAY,CAed;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkBnD"}

package/dist/sessions/index-file.js

@@ -0,0 +1,174 @@
+// CLI-023 · The session index.
+//
+// Plan §20.13: "index 损坏可扫描各 metadata 重建". That line decides the whole
+// design - if the index can always be rebuilt from the metadata files, then it
+// is a cache and never the source of truth, and its corruption stops being an
+// incident. So nothing here ever fails because the index is wrong; it just
+// rebuilds.
+//
+// Listing also reconciles against the directory itself, so a session written
+// by a process that crashed before updating the index still appears.
+import { mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { basename, join } from "node:path";
+import { SCHEMA_VERSION, listSessionDirectories, readSession, } from "./store.js";
+const INDEX_FILE = "index.json";
+const FILE_MODE = 0o600;
+export function indexPath(root) {
+    return join(root, INDEX_FILE);
+}
+function entryOf(metadata) {
+    return {
+        session_id: metadata.session_id,
+        title: metadata.title,
+        updated_at: metadata.updated_at,
+        model_id: metadata.model_id,
+        workspace: metadata.workspace,
+        model_requests: metadata.model_requests,
+        estimated_charge_micro_usd: metadata.estimated_charge_micro_usd,
+    };
+}
+/** Newest first, which is the order a session list wants. */
+function byRecency(a, b) {
+    return b.updated_at.localeCompare(a.updated_at);
+}
+/**
+ * Rebuild from the metadata files, which are the truth.
+ *
+ * A session whose metadata cannot be read is skipped rather than fatal: one
+ * damaged directory must not hide every other conversation.
+ */
+export function rebuildIndex(root) {
+    const sessions = [];
+    for (const directory of listSessionDirectories(root)) {
+        try {
+            sessions.push(entryOf(readSession(directory).metadata));
+        }
+        catch {
+            // Unreadable or written by a newer CLI; leave it out of the listing.
+        }
+    }
+    sessions.sort(byRecency);
+    const index = { schema_version: SCHEMA_VERSION, sessions };
+    // Best effort. The index is a cache, so failing to persist it must not fail
+    // the read - on a machine with no sessions yet the directory does not even
+    // exist, and `mafdet sessions list` still has a correct answer: none.
+    try {
+        writeIndex(root, index);
+    }
+    catch {
+        // Nothing to do; the caller already has the right data.
+    }
+    return index;
+}
+/** Temp file plus rename, so a crash never leaves half an index. */
+export function writeIndex(root, index) {
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    const target = indexPath(root);
+    const temp = join(root, `.index.${process.pid}.tmp`);
+    try {
+        writeFileSync(temp, `${JSON.stringify(index, null, 2)}\n`, {
+            mode: FILE_MODE,
+        });
+        renameSync(temp, target);
+    }
+    catch (error) {
+        try {
+            unlinkSync(temp);
+        }
+        catch {
+            // May never have been created.
+        }
+        throw error;
+    }
+}
+/**
+ * Read the index, rebuilding whenever it cannot be trusted.
+ *
+ * "Cannot be trusted" includes disagreeing with the directory: an index that
+ * is merely stale would otherwise hide a session that exists, which is worse
+ * than the cost of a rebuild.
+ */
+export function loadIndex(root) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(indexPath(root), "utf8"));
+    }
+    catch {
+        return rebuildIndex(root);
+    }
+    if (!isIndex(parsed) || parsed.schema_version > SCHEMA_VERSION) {
+        return rebuildIndex(root);
+    }
+    if (!matchesDisk(root, parsed))
+        return rebuildIndex(root);
+    return parsed;
+}
+function isIndex(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const candidate = value;
+    if (typeof candidate.schema_version !== "number")
+        return false;
+    if (!Array.isArray(candidate.sessions))
+        return false;
+    return candidate.sessions.every((entry) => entry !== null &&
+        typeof entry === "object" &&
+        typeof entry.session_id === "string");
+}
+/** Same set of session ids as the directory, or the index is stale. */
+function matchesDisk(root, index) {
+    const onDisk = new Set(listSessionDirectories(root).map((directory) => basename(directory)));
+    if (onDisk.size !== index.sessions.length)
+        return false;
+    return index.sessions.every((entry) => onDisk.has(entry.session_id));
+}
+/** Record or update one session, leaving the rest of the index alone. */
+export function upsertIndexEntry(root, metadata) {
+    const current = loadIndex(root);
+    const entry = entryOf(metadata);
+    const sessions = current.sessions
+        .filter((existing) => existing.session_id !== entry.session_id)
+        .concat(entry)
+        .sort(byRecency);
+    const next = { schema_version: SCHEMA_VERSION, sessions };
+    writeIndex(root, next);
+    return next;
+}
+export function removeIndexEntry(root, sessionId) {
+    let current;
+    try {
+        current = loadIndex(root);
+    }
+    catch {
+        current = { schema_version: SCHEMA_VERSION, sessions: [] };
+    }
+    const next = {
+        schema_version: SCHEMA_VERSION,
+        sessions: current.sessions.filter((entry) => entry.session_id !== sessionId),
+    };
+    writeIndex(root, next);
+    return next;
+}
+/** Stray temp files from a killed write, which nothing else will clean up. */
+export function sweepTempFiles(root) {
+    let removed = 0;
+    let entries;
+    try {
+        entries = readdirSync(root);
+    }
+    catch {
+        return 0;
+    }
+    for (const name of entries) {
+        if (!name.startsWith(".index.") || !name.endsWith(".tmp"))
+            continue;
+        try {
+            unlinkSync(join(root, name));
+            removed += 1;
+        }
+        catch {
+            // Someone else's in-flight write; leave it.
+        }
+    }
+    return removed;
+}

package/dist/sessions/lock.d.ts

@@ -0,0 +1,39 @@
+export interface LockRecord {
+    readonly pid: number;
+    /** Distinguishes a recycled pid on this machine from the original holder. */
+    readonly started_at: string;
+    readonly host: string;
+}
+export declare class SessionLockedError extends Error {
+    readonly holder: LockRecord | undefined;
+    constructor(message: string, holder: LockRecord | undefined);
+}
+export interface LockHost {
+    readonly pid: number;
+    /** True when a process with this id exists and is ours to signal. */
+    isAlive(pid: number): boolean;
+    readonly host: string;
+    now(): Date;
+}
+export declare const systemHost: LockHost;
+export interface SessionLock {
+    readonly path: string;
+    release(): void;
+}
+export declare function lockPath(directory: string): string;
+/**
+ * Is this lock safe to take over?
+ *
+ * Only when we can be sure the holder is gone. A lock from another machine is
+ * never reclaimed: the pid means nothing here, and a shared filesystem is
+ * exactly where a wrong answer corrupts someone else's transcript.
+ */
+export declare function isStale(record: LockRecord | undefined, host: LockHost): boolean;
+/**
+ * Take the lock, reclaiming a dead one.
+ *
+ * Throws `SessionLockedError` when another live process holds it - the caller
+ * decides whether that means "open read-only" or "pick another session".
+ */
+export declare function acquireSessionLock(directory: string, host?: LockHost): SessionLock;
+//# sourceMappingURL=lock.d.ts.map

package/dist/sessions/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/sessions/lock.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS;gBADvC,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,UAAU,GAAG,SAAS;CAI1C;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,GAAG,IAAI,IAAI,CAAC;CACb;AAED,eAAO,MAAM,UAAU,EAAE,QAcxB,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAElD;AAqBD;;;;;;GAMG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,UAAU,GAAG,SAAS,EAC9B,IAAI,EAAE,QAAQ,GACb,OAAO,CAKT;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,QAAqB,GAC1B,WAAW,CA8Cb"}

package/dist/sessions/lock.js

@@ -0,0 +1,134 @@
+// CLI-023 · One writer per session.
+//
+// Plan §20.13: a second process opening the same session must not interleave
+// its events into the same file. The lock is advisory and deliberately simple
+// - `wx` fails if the file exists, which is the atomic primitive every
+// filesystem gives us without a dependency.
+//
+// The hard part is not taking the lock, it is deciding that an existing one is
+// dead. A crashed process leaves its lock behind forever, and a CLI that then
+// refuses to open your own conversation is worse than one that occasionally
+// takes a lock it should not have. So a lock whose process is gone is
+// reclaimed - and the check is narrow enough not to steal a live one.
+import { openSync, closeSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+const LOCK_FILE = "session.lock";
+const FILE_MODE = 0o600;
+export class SessionLockedError extends Error {
+    holder;
+    constructor(message, holder) {
+        super(message);
+        this.holder = holder;
+    }
+}
+export const systemHost = {
+    pid: process.pid,
+    isAlive(pid) {
+        try {
+            // Signal 0 checks for existence without delivering anything.
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            // EPERM means it exists but belongs to someone else: still alive.
+            return error.code === "EPERM";
+        }
+    },
+    host: hostname(),
+    now: () => new Date(),
+};
+export function lockPath(directory) {
+    return join(directory, LOCK_FILE);
+}
+function readRecord(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof parsed.pid !== "number")
+            return undefined;
+        return {
+            pid: parsed.pid,
+            started_at: typeof parsed.started_at === "string" ? parsed.started_at : "",
+            host: typeof parsed.host === "string" ? parsed.host : "",
+        };
+    }
+    catch {
+        // Unreadable or truncated: treat as stale rather than as a live holder,
+        // or a half-written lock would wedge the session permanently.
+        return undefined;
+    }
+}
+/**
+ * Is this lock safe to take over?
+ *
+ * Only when we can be sure the holder is gone. A lock from another machine is
+ * never reclaimed: the pid means nothing here, and a shared filesystem is
+ * exactly where a wrong answer corrupts someone else's transcript.
+ */
+export function isStale(record, host) {
+    if (record === undefined)
+        return true; // Unreadable; nothing to respect.
+    if (record.host !== "" && record.host !== host.host)
+        return false;
+    if (record.pid === host.pid)
+        return true; // Ours, from an earlier open.
+    return !host.isAlive(record.pid);
+}
+/**
+ * Take the lock, reclaiming a dead one.
+ *
+ * Throws `SessionLockedError` when another live process holds it - the caller
+ * decides whether that means "open read-only" or "pick another session".
+ */
+export function acquireSessionLock(directory, host = systemHost) {
+    const path = lockPath(directory);
+    const record = {
+        pid: host.pid,
+        started_at: host.now().toISOString(),
+        host: host.host,
+    };
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            // `wx` is the atomic part: it fails if the file already exists.
+            const fd = openSync(path, "wx", FILE_MODE);
+            try {
+                writeFileSync(fd, `${JSON.stringify(record)}\n`);
+            }
+            finally {
+                closeSync(fd);
+            }
+            return { path, release: () => releaseIfOurs(path, record) };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const holder = readRecord(path);
+            if (!isStale(holder, host)) {
+                throw new SessionLockedError(holder === undefined
+                    ? "this session is open in another process"
+                    : `this session is open in another process (pid ${holder.pid}${holder.host ? ` on ${holder.host}` : ""})`, holder);
+            }
+            // Stale: drop it and try once more. A second EEXIST means someone else
+            // won the race, and the next pass will report them as the holder.
+            try {
+                unlinkSync(path);
+            }
+            catch {
+                // Someone else cleaned it up first, which is fine.
+            }
+        }
+    }
+    throw new SessionLockedError("could not take the session lock", readRecord(path));
+}
+/** Only remove a lock we still own, so a reclaimed one is not deleted twice. */
+function releaseIfOurs(path, ours) {
+    const current = readRecord(path);
+    if (current !== undefined && current.pid !== ours.pid)
+        return;
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // Already gone.
+    }
+}

package/dist/sessions/open.d.ts

@@ -0,0 +1,45 @@
+import type { ChatMessage } from "../agent/loop.js";
+import { type SessionLock } from "./lock.js";
+import { permissionsForResume, type ResumeBlocker } from "./resume.js";
+import { SessionWriter, type SessionMetadata } from "./store.js";
+export interface OpenForResumeInput {
+    readonly root: string;
+    readonly sessionId: string;
+    readonly systemPrompt: string;
+    /** Model ids the current key can call. */
+    readonly callable: readonly string[];
+    readonly agentCapable: readonly string[];
+    readonly allowedCommandsThisRun: readonly string[];
+}
+export type OpenResult = {
+    readonly kind: "missing";
+} | {
+    readonly kind: "locked";
+    readonly reason: string;
+} | {
+    readonly kind: "unreadable";
+    readonly reason: string;
+} | {
+    readonly kind: "opened";
+    readonly metadata: SessionMetadata;
+    readonly messages: ChatMessage[];
+    readonly writer: SessionWriter;
+    readonly lock: SessionLock;
+    /** Empty when nothing stands in the way of continuing. */
+    readonly blockers: readonly ResumeBlocker[];
+    readonly omitted: number;
+    readonly toolRunsSummarised: number;
+    readonly permissions: ReturnType<typeof permissionsForResume>;
+};
+export declare function openForResume(input: OpenForResumeInput): OpenResult;
+/**
+ * What to tell the user when a session is reopened.
+ *
+ * The cost sentence is the one that earns its place: opening was free, but the
+ * next message re-sends this history as input tokens, and someone who does not
+ * know that will be surprised by the bill rather than by the feature.
+ */
+export declare function describeResume(result: Extract<OpenResult, {
+    kind: "opened";
+}>): string;
+//# sourceMappingURL=open.d.ts.map

package/dist/sessions/open.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open.d.ts","sourceRoot":"","sources":["../../src/sessions/open.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAEL,oBAAoB,EAGpB,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAe,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAE9E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;CACpD;AAED,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxD;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC;CAC/D,CAAC;AAEN,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,UAAU,CA4DnE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,GAC9C,MAAM,CAwBR"}