@geminixiang/mikan 1.0.0-beta.4 → 1.0.0-beta.41

package/dist/sessions/history-line.js

@@ -0,0 +1,45 @@
+/**
+ * Format a Date as a local-timezone timestamp string: YYYY-MM-DD HH:MM:SS±HH:MM
+ * Returns null when the date is invalid (non-finite time value).
+ *
+ * This is the timestamp spelling inside history lines; keeping writer,
+ * parser, and timestamp format in one module ensures HISTORY_LINE_PREFIX's
+ * regex stays valid.
+ */
+export function formatLocalTimestamp(date) {
+    const time = date.getTime();
+    if (!Number.isFinite(time))
+        return null;
+    const offset = -date.getTimezoneOffset();
+    const sign = offset >= 0 ? "+" : "-";
+    const abs = Math.abs(offset);
+    return (`${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +
+        `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}` +
+        `${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`);
+}
+function pad(n) {
+    return n.toString().padStart(2, "0");
+}
+/**
+ * The prompt history-line grammar:
+ *
+ *   `[YYYY-MM-DD HH:MM:SS±HH:MM] [userName] [in-thread:ts]: text`
+ *
+ * agent.ts writes it when prompting the model; session resume strips the
+ * prefix to compare platform log history against persisted session messages
+ * (dedupe). Writer and parser live together here so the grammar cannot drift
+ * apart silently — if the format changes, the round-trip test fails instead
+ * of every resumed session duplicating its history.
+ */
+export function formatHistoryLine(options) {
+    const timestamp = options.date ? formatLocalTimestamp(options.date) : null;
+    const timestampPart = timestamp ? `[${timestamp}] ` : "";
+    const threadPart = options.threadTs ? ` [in-thread:${options.threadTs}]` : "";
+    return `${timestampPart}[${options.userName || "unknown"}]${threadPart}: ${options.text}`;
+}
+const HISTORY_LINE_PREFIX = /^\[[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}[+-][0-9]{2}:[0-9]{2}\]\s+\[[^\]]+\](?:\s+\[in-thread:[^\]]+\])?:\s*/;
+/** Strip the timestamped prefix so log text and session text compare equal. */
+export function stripHistoryLinePrefix(text) {
+    return text.replace(HISTORY_LINE_PREFIX, "").trim();
+}
+//# sourceMappingURL=history-line.js.map

package/dist/sessions/history-line.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-line.js","sourceRoot":"","sources":["../../src/sessions/history-line.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAU;IAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;IAC5B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAExC,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;IACrC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7B,OAAO,CACL,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG;QAC3E,GAAG,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,EAAE;QAC7E,GAAG,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,CACvD,CAAC;AACJ,CAAC;AAED,SAAS,GAAG,CAAC,CAAS;IACpB,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAKjC;IACC,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,oBAAoB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3E,MAAM,aAAa,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,SAAS,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IACzD,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,eAAe,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9E,OAAO,GAAG,aAAa,IAAI,OAAO,CAAC,QAAQ,IAAI,SAAS,IAAI,UAAU,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC;AAC5F,CAAC;AAED,MAAM,mBAAmB,GACvB,8HAA8H,CAAC;AAEjI,+EAA+E;AAC/E,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,IAAI,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACtD,CAAC","sourcesContent":["/**\n * Format a Date as a local-timezone timestamp string: YYYY-MM-DD HH:MM:SS±HH:MM\n * Returns null when the date is invalid (non-finite time value).\n *\n * This is the timestamp spelling inside history lines; keeping writer,\n * parser, and timestamp format in one module ensures HISTORY_LINE_PREFIX's\n * regex stays valid.\n */\nexport function formatLocalTimestamp(date: Date): string | null {\n  const time = date.getTime();\n  if (!Number.isFinite(time)) return null;\n\n  const offset = -date.getTimezoneOffset();\n  const sign = offset >= 0 ? \"+\" : \"-\";\n  const abs = Math.abs(offset);\n  return (\n    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +\n    `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}` +\n    `${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`\n  );\n}\n\nfunction pad(n: number): string {\n  return n.toString().padStart(2, \"0\");\n}\n\n/**\n * The prompt history-line grammar:\n *\n *   `[YYYY-MM-DD HH:MM:SS±HH:MM] [userName] [in-thread:ts]: text`\n *\n * agent.ts writes it when prompting the model; session resume strips the\n * prefix to compare platform log history against persisted session messages\n * (dedupe). Writer and parser live together here so the grammar cannot drift\n * apart silently — if the format changes, the round-trip test fails instead\n * of every resumed session duplicating its history.\n */\nexport function formatHistoryLine(options: {\n  date?: Date;\n  userName?: string;\n  threadTs?: string;\n  text: string;\n}): string {\n  const timestamp = options.date ? formatLocalTimestamp(options.date) : null;\n  const timestampPart = timestamp ? `[${timestamp}] ` : \"\";\n  const threadPart = options.threadTs ? ` [in-thread:${options.threadTs}]` : \"\";\n  return `${timestampPart}[${options.userName || \"unknown\"}]${threadPart}: ${options.text}`;\n}\n\nconst HISTORY_LINE_PREFIX =\n  /^\\[[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}[+-][0-9]{2}:[0-9]{2}\\]\\s+\\[[^\\]]+\\](?:\\s+\\[in-thread:[^\\]]+\\])?:\\s*/;\n\n/** Strip the timestamped prefix so log text and session text compare equal. */\nexport function stripHistoryLinePrefix(text: string): string {\n  return text.replace(HISTORY_LINE_PREFIX, \"\").trim();\n}\n"]}

package/dist/sessions/rotation.d.ts

@@ -0,0 +1,2 @@
+export declare function shouldRotateTopLevelSession(sessionFile: string, now: Date): boolean;
+//# sourceMappingURL=rotation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rotation.d.ts","sourceRoot":"","sources":["../../src/sessions/rotation.ts"],"names":[],"mappings":"AAWA,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAGnF"}

package/dist/sessions/rotation.js

@@ -0,0 +1,39 @@
+import { isRecord, parseJsonValue, readTextFileIfExists } from "../utils/file-guards.js";
+/**
+ * Biweekly rotation clock for top-level shared sessions: a session file
+ * rotates when its header timestamp falls in a different two-week bucket
+ * (anchored to a fixed Sunday) than the given "now".
+ */
+const BIWEEKLY_ROTATION_ANCHOR = new Date(2026, 0, 4); // Sunday
+const BIWEEKLY_MS = 14 * 24 * 60 * 60 * 1000;
+export function shouldRotateTopLevelSession(sessionFile, now) {
+    const timestamp = readSessionTimestamp(sessionFile);
+    return timestamp !== null && biweeklyBucket(timestamp) !== biweeklyBucket(now);
+}
+function readSessionTimestamp(sessionFile) {
+    const raw = readTextFileIfExists(sessionFile);
+    if (raw === undefined)
+        return null;
+    const firstLine = raw.split("\n").find((line) => line.trim());
+    if (!firstLine)
+        return null;
+    try {
+        const header = parseJsonValue(firstLine, (value) => isRecord(value), (detail) => (detail === "unexpected JSON shape" ? "expected a JSON object" : detail));
+        if (typeof header.timestamp !== "string")
+            return null;
+        const date = new Date(header.timestamp);
+        return Number.isFinite(date.getTime()) ? date : null;
+    }
+    catch {
+        return null;
+    }
+}
+function biweeklyBucket(date) {
+    const weekStart = sundayStart(date).getTime();
+    const anchor = sundayStart(BIWEEKLY_ROTATION_ANCHOR).getTime();
+    return Math.floor((weekStart - anchor) / BIWEEKLY_MS);
+}
+function sundayStart(date) {
+    return new Date(date.getFullYear(), date.getMonth(), date.getDate() - date.getDay());
+}
+//# sourceMappingURL=rotation.js.map

package/dist/sessions/rotation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotation.js","sourceRoot":"","sources":["../../src/sessions/rotation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAEzF;;;;GAIG;AAEH,MAAM,wBAAwB,GAAG,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS;AAChE,MAAM,WAAW,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE7C,MAAM,UAAU,2BAA2B,CAAC,WAAmB,EAAE,GAAS;IACxE,MAAM,SAAS,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;IACpD,OAAO,SAAS,KAAK,IAAI,IAAI,cAAc,CAAC,SAAS,CAAC,KAAK,cAAc,CAAC,GAAG,CAAC,CAAC;AACjF,CAAC;AAED,SAAS,oBAAoB,CAAC,WAAmB;IAC/C,MAAM,GAAG,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAC9C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC9D,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,cAAc,CAC3B,SAAS,EACT,CAAC,KAAK,EAAoC,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,EAC5D,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,KAAK,uBAAuB,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,MAAM,CAAC,CACrF,CAAC;QACF,IAAI,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACtD,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACxC,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,IAAU;IAChC,MAAM,SAAS,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;IAC9C,MAAM,MAAM,GAAG,WAAW,CAAC,wBAAwB,CAAC,CAAC,OAAO,EAAE,CAAC;IAC/D,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,GAAG,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC;AACxD,CAAC;AAED,SAAS,WAAW,CAAC,IAAU;IAC7B,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;AACvF,CAAC","sourcesContent":["import { isRecord, parseJsonValue, readTextFileIfExists } from \"../utils/file-guards.js\";\n\n/**\n * Biweekly rotation clock for top-level shared sessions: a session file\n * rotates when its header timestamp falls in a different two-week bucket\n * (anchored to a fixed Sunday) than the given \"now\".\n */\n\nconst BIWEEKLY_ROTATION_ANCHOR = new Date(2026, 0, 4); // Sunday\nconst BIWEEKLY_MS = 14 * 24 * 60 * 60 * 1000;\n\nexport function shouldRotateTopLevelSession(sessionFile: string, now: Date): boolean {\n  const timestamp = readSessionTimestamp(sessionFile);\n  return timestamp !== null && biweeklyBucket(timestamp) !== biweeklyBucket(now);\n}\n\nfunction readSessionTimestamp(sessionFile: string): Date | null {\n  const raw = readTextFileIfExists(sessionFile);\n  if (raw === undefined) return null;\n  const firstLine = raw.split(\"\\n\").find((line) => line.trim());\n  if (!firstLine) return null;\n  try {\n    const header = parseJsonValue(\n      firstLine,\n      (value): value is { timestamp?: unknown } => isRecord(value),\n      (detail) => (detail === \"unexpected JSON shape\" ? \"expected a JSON object\" : detail),\n    );\n    if (typeof header.timestamp !== \"string\") return null;\n    const date = new Date(header.timestamp);\n    return Number.isFinite(date.getTime()) ? date : null;\n  } catch {\n    return null;\n  }\n}\n\nfunction biweeklyBucket(date: Date): number {\n  const weekStart = sundayStart(date).getTime();\n  const anchor = sundayStart(BIWEEKLY_ROTATION_ANCHOR).getTime();\n  return Math.floor((weekStart - anchor) / BIWEEKLY_MS);\n}\n\nfunction sundayStart(date: Date): Date {\n  return new Date(date.getFullYear(), date.getMonth(), date.getDate() - date.getDay());\n}\n"]}

package/dist/sessions/session-key.d.ts

@@ -0,0 +1,33 @@
+import type { ConversationKind } from "../adapter.js";
+export type { ResolveSessionKeyOptions } from "./types.js";
+import type { ResolveSessionKeyOptions } from "./types.js";
+export declare function assertConversationId(conversationId: string): string;
+/** Validate the opaque scoped suffix without changing its platform value. */
+export declare function assertSessionSuffix(suffix: string): string;
+/** Build a scoped thread session key. */
+export declare function makeThreadSessionKey(conversationId: string, suffix: string): string;
+/**
+ * Validate that a platform-computed session key belongs to its conversation.
+ * The key may be the bare conversation id or one of that conversation's
+ * scoped keys; callers must not be able to select another conversation's
+ * runtime/cache entry.
+ */
+export declare function assertSessionKeyBelongsToConversation(sessionKey: string, conversationId: string): string;
+/**
+ * The runtime fallback: honor a platform-computed session key, otherwise
+ * scope the event to its thread (or to itself for thread-starting messages).
+ */
+export declare function deriveSessionKey(event: {
+    sessionKey?: string;
+    conversationId: string;
+    thread_ts?: string;
+    ts: string;
+}): string;
+export declare function isThreadSessionKey(sessionKey: string): boolean;
+/** The conversation a session key belongs to (identity for bare keys). */
+export declare function conversationIdOf(sessionKey: string): string;
+/** The thread suffix of a scoped key, or null for a bare conversation key. */
+export declare function threadSuffixOf(sessionKey: string): string | null;
+export declare function resolveChatSessionKey(options: ResolveSessionKeyOptions): string;
+export declare function inferConversationKind(platform: string, conversationId: string): ConversationKind;
+//# sourceMappingURL=session-key.d.ts.map

package/dist/sessions/session-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-key.d.ts","sourceRoot":"","sources":["../../src/sessions/session-key.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,YAAY,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAuC3D,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CASnE;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,yCAAyC;AACzC,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnF;AAED;;;;;GAKG;AACH,wBAAgB,qCAAqC,CACnD,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GACrB,MAAM,CAYR;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;CACZ,GAAG,MAAM,CAKT;AAED,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAG3D;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhE;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CAgB/E;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,gBAAgB,CAehG"}

package/dist/sessions/session-key.js

@@ -0,0 +1,115 @@
+/**
+ * The session-key grammar. A session key is the conversation-scoped runtime
+ * identity used to serialize and resume work (see CONTEXT.md):
+ *
+ *   `conversationId`            — the persistent conversation session
+ *   `conversationId:suffix`     — a scoped thread session (suffix = thread
+ *                                 ts / message id, opaque to this module)
+ *
+ * This module owns the convention; nothing else may split on ":". The grammar
+ * only works because conversation ids never contain ":" — that invariant is
+ * asserted here at every derivation instead of being assumed everywhere.
+ */
+/** Characters that can change host path structure or make identity logs ambiguous. */
+const PATH_SEPARATOR_PATTERN = /[\\/]/;
+function containsControlCharacter(value) {
+    for (const character of value) {
+        const codePoint = character.codePointAt(0);
+        if (codePoint <= 0x1f || codePoint === 0x7f)
+            return true;
+    }
+    return false;
+}
+function assertSafeIdentityPart(value, label) {
+    if (!value || value === "." || value === "..") {
+        throw new Error(`${label} must be a non-empty identity segment (got ${JSON.stringify(value)})`);
+    }
+    if (PATH_SEPARATOR_PATTERN.test(value)) {
+        throw new Error(`${label} must not contain path separators (got ${JSON.stringify(value)})`);
+    }
+    if (containsControlCharacter(value)) {
+        throw new Error(`${label} must not contain control characters (got ${JSON.stringify(value)})`);
+    }
+    return value;
+}
+export function assertConversationId(conversationId) {
+    assertSafeIdentityPart(conversationId, "Conversation id");
+    if (conversationId.includes(":")) {
+        throw new Error(`Conversation id must not contain ":" (got ${JSON.stringify(conversationId)}); ` +
+            "the session-key grammar reserves it for thread suffixes");
+    }
+    return conversationId;
+}
+/** Validate the opaque scoped suffix without changing its platform value. */
+export function assertSessionSuffix(suffix) {
+    return assertSafeIdentityPart(suffix, "Session suffix");
+}
+/** Build a scoped thread session key. */
+export function makeThreadSessionKey(conversationId, suffix) {
+    return `${assertConversationId(conversationId)}:${assertSessionSuffix(suffix)}`;
+}
+/**
+ * Validate that a platform-computed session key belongs to its conversation.
+ * The key may be the bare conversation id or one of that conversation's
+ * scoped keys; callers must not be able to select another conversation's
+ * runtime/cache entry.
+ */
+export function assertSessionKeyBelongsToConversation(sessionKey, conversationId) {
+    const expectedConversationId = assertConversationId(conversationId);
+    const actualConversationId = conversationIdOf(sessionKey);
+    if (actualConversationId !== expectedConversationId) {
+        throw new Error(`Session key ${JSON.stringify(sessionKey)} does not belong to conversation ` +
+            JSON.stringify(conversationId));
+    }
+    const suffix = threadSuffixOf(sessionKey);
+    if (suffix !== null)
+        assertSessionSuffix(suffix);
+    return sessionKey;
+}
+/**
+ * The runtime fallback: honor a platform-computed session key, otherwise
+ * scope the event to its thread (or to itself for thread-starting messages).
+ */
+export function deriveSessionKey(event) {
+    if (event.sessionKey !== undefined) {
+        return assertSessionKeyBelongsToConversation(event.sessionKey, event.conversationId);
+    }
+    return makeThreadSessionKey(event.conversationId, event.thread_ts ?? event.ts);
+}
+export function isThreadSessionKey(sessionKey) {
+    return sessionKey.includes(":");
+}
+/** The conversation a session key belongs to (identity for bare keys). */
+export function conversationIdOf(sessionKey) {
+    const separator = sessionKey.indexOf(":");
+    return separator === -1 ? sessionKey : sessionKey.slice(0, separator);
+}
+/** The thread suffix of a scoped key, or null for a bare conversation key. */
+export function threadSuffixOf(sessionKey) {
+    const separator = sessionKey.indexOf(":");
+    return separator === -1 ? null : sessionKey.slice(separator + 1);
+}
+export function resolveChatSessionKey(options) {
+    const { conversationId, conversationKind, messageId, persistentTopLevel, scopeDirectThreads, threadTs, } = options;
+    if (conversationKind === "direct" && (!threadTs || !scopeDirectThreads)) {
+        return assertConversationId(conversationId);
+    }
+    if (!threadTs && persistentTopLevel) {
+        return assertConversationId(conversationId);
+    }
+    return makeThreadSessionKey(conversationId, threadTs || messageId);
+}
+export function inferConversationKind(platform, conversationId) {
+    if (platform === "slack") {
+        return conversationId.startsWith("D") ? "direct" : "shared";
+    }
+    if (platform === "telegram") {
+        return conversationId.startsWith("-") ? "shared" : "direct";
+    }
+    if (platform === "discord") {
+        return conversationId.startsWith("DM") ? "direct" : "shared";
+    }
+    // github: issues/PRs are always shared within the repo; there are no DMs.
+    return "shared";
+}
+//# sourceMappingURL=session-key.js.map

package/dist/sessions/session-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-key.js","sourceRoot":"","sources":["../../src/sessions/session-key.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ConversationKind } from \"../adapter.js\";\nexport type { ResolveSessionKeyOptions } from \"./types.js\";\nimport type { ResolveSessionKeyOptions } from \"./types.js\";\n\n/**\n * The session-key grammar. A session key is the conversation-scoped runtime\n * identity used to serialize and resume work (see CONTEXT.md):\n *\n *   `conversationId`            — the persistent conversation session\n *   `conversationId:suffix`     — a scoped thread session (suffix = thread\n *                                 ts / message id, opaque to this module)\n *\n * This module owns the convention; nothing else may split on \":\". The grammar\n * only works because conversation ids never contain \":\" — that invariant is\n * asserted here at every derivation instead of being assumed everywhere.\n */\n\n/** Characters that can change host path structure or make identity logs ambiguous. */\nconst PATH_SEPARATOR_PATTERN = /[\\\\/]/;\n\nfunction containsControlCharacter(value: string): boolean {\n  for (const character of value) {\n    const codePoint = character.codePointAt(0)!;\n    if (codePoint <= 0x1f || codePoint === 0x7f) return true;\n  }\n  return false;\n}\n\nfunction assertSafeIdentityPart(value: string, label: string): string {\n  if (!value || value === \".\" || value === \"..\") {\n    throw new Error(`${label} must be a non-empty identity segment (got ${JSON.stringify(value)})`);\n  }\n  if (PATH_SEPARATOR_PATTERN.test(value)) {\n    throw new Error(`${label} must not contain path separators (got ${JSON.stringify(value)})`);\n  }\n  if (containsControlCharacter(value)) {\n    throw new Error(`${label} must not contain control characters (got ${JSON.stringify(value)})`);\n  }\n  return value;\n}\n\nexport function assertConversationId(conversationId: string): string {\n  assertSafeIdentityPart(conversationId, \"Conversation id\");\n  if (conversationId.includes(\":\")) {\n    throw new Error(\n      `Conversation id must not contain \":\" (got ${JSON.stringify(conversationId)}); ` +\n        \"the session-key grammar reserves it for thread suffixes\",\n    );\n  }\n  return conversationId;\n}\n\n/** Validate the opaque scoped suffix without changing its platform value. */\nexport function assertSessionSuffix(suffix: string): string {\n  return assertSafeIdentityPart(suffix, \"Session suffix\");\n}\n\n/** Build a scoped thread session key. */\nexport function makeThreadSessionKey(conversationId: string, suffix: string): string {\n  return `${assertConversationId(conversationId)}:${assertSessionSuffix(suffix)}`;\n}\n\n/**\n * Validate that a platform-computed session key belongs to its conversation.\n * The key may be the bare conversation id or one of that conversation's\n * scoped keys; callers must not be able to select another conversation's\n * runtime/cache entry.\n */\nexport function assertSessionKeyBelongsToConversation(\n  sessionKey: string,\n  conversationId: string,\n): string {\n  const expectedConversationId = assertConversationId(conversationId);\n  const actualConversationId = conversationIdOf(sessionKey);\n  if (actualConversationId !== expectedConversationId) {\n    throw new Error(\n      `Session key ${JSON.stringify(sessionKey)} does not belong to conversation ` +\n        JSON.stringify(conversationId),\n    );\n  }\n  const suffix = threadSuffixOf(sessionKey);\n  if (suffix !== null) assertSessionSuffix(suffix);\n  return sessionKey;\n}\n\n/**\n * The runtime fallback: honor a platform-computed session key, otherwise\n * scope the event to its thread (or to itself for thread-starting messages).\n */\nexport function deriveSessionKey(event: {\n  sessionKey?: string;\n  conversationId: string;\n  thread_ts?: string;\n  ts: string;\n}): string {\n  if (event.sessionKey !== undefined) {\n    return assertSessionKeyBelongsToConversation(event.sessionKey, event.conversationId);\n  }\n  return makeThreadSessionKey(event.conversationId, event.thread_ts ?? event.ts);\n}\n\nexport function isThreadSessionKey(sessionKey: string): boolean {\n  return sessionKey.includes(\":\");\n}\n\n/** The conversation a session key belongs to (identity for bare keys). */\nexport function conversationIdOf(sessionKey: string): string {\n  const separator = sessionKey.indexOf(\":\");\n  return separator === -1 ? sessionKey : sessionKey.slice(0, separator);\n}\n\n/** The thread suffix of a scoped key, or null for a bare conversation key. */\nexport function threadSuffixOf(sessionKey: string): string | null {\n  const separator = sessionKey.indexOf(\":\");\n  return separator === -1 ? null : sessionKey.slice(separator + 1);\n}\n\nexport function resolveChatSessionKey(options: ResolveSessionKeyOptions): string {\n  const {\n    conversationId,\n    conversationKind,\n    messageId,\n    persistentTopLevel,\n    scopeDirectThreads,\n    threadTs,\n  } = options;\n  if (conversationKind === \"direct\" && (!threadTs || !scopeDirectThreads)) {\n    return assertConversationId(conversationId);\n  }\n  if (!threadTs && persistentTopLevel) {\n    return assertConversationId(conversationId);\n  }\n  return makeThreadSessionKey(conversationId, threadTs || messageId);\n}\n\nexport function inferConversationKind(platform: string, conversationId: string): ConversationKind {\n  if (platform === \"slack\") {\n    return conversationId.startsWith(\"D\") ? \"direct\" : \"shared\";\n  }\n\n  if (platform === \"telegram\") {\n    return conversationId.startsWith(\"-\") ? \"shared\" : \"direct\";\n  }\n\n  if (platform === \"discord\") {\n    return conversationId.startsWith(\"DM\") ? \"direct\" : \"shared\";\n  }\n\n  // github: issues/PRs are always shared within the repo; there are no DMs.\n  return \"shared\";\n}\n"]}

package/dist/sessions/store.d.ts

@@ -1,11 +1,7 @@
 import { SessionStore } from "../harness/index.js";
 export type { ResolvedSessionScope, ThreadRootMessage } from "./types.js";
-/**
- * Returns the shared session directory for a conversation.
- * Channel sessions use a current pointer within this directory.
- * Thread sessions are stored as fixed files within the same directory.
- */
-export declare function getChannelSessionDir(channelDir: string): string;
+export type { MikanSessionHeader } from "./types.js";
+export declare function isPlatformHistorySession(sessionFile: string): boolean;
 /**
  * Resolves the current active session file for a session directory.
  * Reads the "current" pointer file; creates a new session if none exists
@@ -49,7 +45,11 @@ export declare function openManagedSession(sessionFile: string, cwd: string): Se
 /**
  * Creates or overwrites a fixed-path session file with a valid session header.
  */
-export declare function createManagedSessionFileAtPath(sessionFile: string, cwd: string): string;
+export interface ParentSessionRef {
+    path: string;
+    id: string;
+}
+export declare function createManagedSessionFileAtPath(sessionFile: string, cwd: string, parent?: ParentSessionRef): string;
 /**
  * Returns the fixed session file path for a Slack thread.
  */
@@ -69,4 +69,12 @@ export declare function tryResolveThreadSession(sessionFile: string): string | n
  * Returns null if no channel session exists.
  */
 export declare function resolveChannelSessionFile(channelDir: string): string | null;
+/**
+ * Resolve the main session file that was active when a thread was created.
+ * Uses the thread's Slack timestamp to find the main session whose creation
+ * time is the latest one at or before that moment — stable across rotations.
+ * Falls back to resolveChannelSessionFile when threadTs is absent or unparseable.
+ * Returns both path and session UUID so callers can store a UUID-stable reference.
+ */
+export declare function resolveParentSessionForThread(channelDir: string, threadTs: string | undefined): ParentSessionRef | null;
 //# sourceMappingURL=store.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/sessions/store.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAInD,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE1E;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAIjF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAG/D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAO/D;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAOhF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAMjF;AAaD;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAGvF;AAeD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEnF;AAkDD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI1E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE1E;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE3E"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/sessions/store.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AASnD,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC1E,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGrD,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAOrE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAIjF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE/D;AAiBD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAO/D;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAOhF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAMjF;AAaD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,gBAAgB,GACxB,MAAM,CAGR;AAiBD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAGnF;AAkED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI1E;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE1E;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE3E;AAKD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,gBAAgB,GAAG,IAAI,CAYzB"}

package/dist/sessions/store.js

@@ -1,17 +1,18 @@
-import { randomUUID } from "crypto";
-import { existsSync, mkdirSync, rmSync } from "fs";
-import { basename, dirname, join } from "path";
+import { randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { SessionStore } from "../harness/index.js";
-import { isRecord, parseJsonValue, readTextFileIfExists } from "../utils/file-guards.js";
-import { atomicWritePrivateFile } from "../utils/fs-atomic.js";
-import { isPlatformHistorySession } from "./metadata.js";
-/**
- * Returns the shared session directory for a conversation.
- * Channel sessions use a current pointer within this directory.
- * Thread sessions are stored as fixed files within the same directory.
- */
-export function getChannelSessionDir(channelDir) {
-    return join(channelDir, "sessions");
+import { atomicWritePrivateFile, isRecord, parseJsonValue, readTextFileIfExists, } from "../utils/file-guards.js";
+import { officeSessionsDir } from "../office/index.js";
+import { assertSessionSuffix, threadSuffixOf } from "./session-key.js";
+export function isPlatformHistorySession(sessionFile) {
+    try {
+        const header = SessionStore.open(sessionFile).getHeader();
+        return header?.source?.kind === "platform-history";
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * Resolves the current active session file for a session directory.
@@ -46,8 +47,21 @@ export function extractSessionUuid(sessionFile) {
  * "channelId:threadId" → "threadId", "channelId" → "channelId"
  */
 export function extractSessionSuffix(sessionKey) {
-    const parts = sessionKey.split(":");
-    return parts.length > 1 ? parts[parts.length - 1] : sessionKey;
+    return assertSessionSuffix(threadSuffixOf(sessionKey) ?? sessionKey);
+}
+/**
+ * Resolve one child path and prove it remains inside its owning directory.
+ * Identity validation is the first guard; containment is defense in depth for
+ * every session path derived from platform-controlled values.
+ */
+function resolveChildPath(root, child) {
+    const resolvedRoot = resolve(root);
+    const resolvedChild = resolve(resolvedRoot, child);
+    const relation = relative(resolvedRoot, resolvedChild);
+    if (!relation || relation === ".." || relation.startsWith(`..${sep}`)) {
+        throw new Error(`Session path escapes its owning directory: ${JSON.stringify(child)}`);
+    }
+    return resolvedChild;
 }
 /**
  * Creates an empty timestamped file and updates the "current" pointer.
@@ -96,30 +110,33 @@ function setCurrentPointer(sessionDir, sessionFilePath) {
     mkdirSync(sessionDir, { recursive: true });
     atomicWritePrivateFile(join(sessionDir, "current"), filename);
 }
-/**
- * Creates or overwrites a fixed-path session file with a valid session header.
- */
-export function createManagedSessionFileAtPath(sessionFile, cwd) {
-    writeSessionHeader(sessionFile, cwd);
+export function createManagedSessionFileAtPath(sessionFile, cwd, parent) {
+    writeSessionHeader(sessionFile, cwd, undefined, parent);
     return sessionFile;
 }
-function writeSessionHeader(sessionFile, cwd, sessionId = randomUUID()) {
-    const sessionDir = dirname(sessionFile);
-    mkdirSync(sessionDir, { recursive: true });
-    const header = {
-        type: "session",
-        version: 3,
+function writeSessionHeader(sessionFile, cwd, sessionId = randomUUID(), parent) {
+    mkdirSync(dirname(sessionFile), { recursive: true });
+    // The header format (and its version) is owned by the harness store; this
+    // layer only decides the path and the id.
+    SessionStore.create(sessionFile, cwd, {
         id: sessionId,
-        timestamp: new Date().toISOString(),
-        cwd,
-    };
-    atomicWritePrivateFile(sessionFile, `${JSON.stringify(header)}\n`);
+        ...(parent ? { parentSession: parent.path, parentSessionId: parent.id } : {}),
+    });
 }
 /**
  * Returns the fixed session file path for a Slack thread.
  */
 export function getThreadSessionFile(channelDir, sessionKey) {
-    return join(getChannelSessionDir(channelDir), `${extractSessionSuffix(sessionKey)}.jsonl`);
+    const sessionDir = officeSessionsDir(channelDir);
+    return resolveChildPath(sessionDir, `${extractSessionSuffix(sessionKey)}.jsonl`);
+}
+function isRegularSessionFile(sessionFile) {
+    try {
+        return lstatSync(sessionFile).isFile();
+    }
+    catch {
+        return false;
+    }
 }
 function hasSessionHeader(sessionFile) {
     try {
@@ -150,7 +167,13 @@ function shouldRecreatePreinitializedSession(sessionFile) {
             .map((line) => line.trim())
             .filter(Boolean)
             .map(parseSessionEntry);
-        return entries.length === 1 && entries[0]?.type === "session";
+        if (entries.length !== 1 || entries[0]?.type !== "session")
+            return false;
+        // Sessions with lineage metadata are fully initialized — preserve them.
+        const h = entries[0];
+        if (h.parentSession || h.parentSessionId)
+            return false;
+        return true;
     }
     catch {
         return false;
@@ -164,7 +187,12 @@ function getCurrentSessionPath(sessionDir) {
     const filename = readTextFileIfExists(pointerFile)?.trim();
     if (!filename)
         return null;
-    return join(sessionDir, filename);
+    try {
+        return resolveChildPath(sessionDir, filename);
+    }
+    catch {
+        return null;
+    }
 }
 /**
  * Try to resolve an existing current session file.
@@ -172,7 +200,7 @@ function getCurrentSessionPath(sessionDir) {
  */
 export function tryResolveCurrentSession(sessionDir) {
     const fullPath = getCurrentSessionPath(sessionDir);
-    if (fullPath && existsSync(fullPath) && hasSessionHeader(fullPath))
+    if (fullPath && isRegularSessionFile(fullPath) && hasSessionHeader(fullPath))
         return fullPath;
     return null;
 }
@@ -181,13 +209,76 @@ export function tryResolveCurrentSession(sessionDir) {
  * Returns the file path if found, or null if no valid thread session exists yet.
  */
 export function tryResolveThreadSession(sessionFile) {
-    return existsSync(sessionFile) && hasSessionHeader(sessionFile) ? sessionFile : null;
+    return isRegularSessionFile(sessionFile) && hasSessionHeader(sessionFile) ? sessionFile : null;
 }
 /**
  * Resolve the channel's current session file path.
  * Returns null if no channel session exists.
  */
 export function resolveChannelSessionFile(channelDir) {
-    return tryResolveCurrentSession(getChannelSessionDir(channelDir));
+    return tryResolveCurrentSession(officeSessionsDir(channelDir));
+}
+// Matches timestamped main session filenames; thread sessions use bare threadTs.
+const MAIN_SESSION_FILENAME = /^\d{4}-\d{2}-\d{2}T.+_[0-9a-f]{8}\.jsonl$/i;
+/**
+ * Resolve the main session file that was active when a thread was created.
+ * Uses the thread's Slack timestamp to find the main session whose creation
+ * time is the latest one at or before that moment — stable across rotations.
+ * Falls back to resolveChannelSessionFile when threadTs is absent or unparseable.
+ * Returns both path and session UUID so callers can store a UUID-stable reference.
+ */
+export function resolveParentSessionForThread(channelDir, threadTs) {
+    if (threadTs !== undefined) {
+        const threadTimeMs = Number(threadTs) * 1000;
+        if (Number.isFinite(threadTimeMs)) {
+            const best = findMainSessionActiveAtTime(channelDir, threadTimeMs);
+            if (best)
+                return best;
+        }
+    }
+    const path = resolveChannelSessionFile(channelDir);
+    if (!path)
+        return null;
+    const id = readSessionHeaderSummary(path)?.id;
+    return id ? { path, id } : null;
+}
+function findMainSessionActiveAtTime(channelDir, targetMs) {
+    const sessionDir = officeSessionsDir(channelDir);
+    if (!existsSync(sessionDir))
+        return null;
+    let best = null;
+    let bestCreatedMs = -Infinity;
+    for (const name of readdirSync(sessionDir)) {
+        if (!MAIN_SESSION_FILENAME.test(name))
+            continue;
+        const filePath = join(sessionDir, name);
+        const summary = readSessionHeaderSummary(filePath);
+        if (!summary)
+            continue;
+        if (summary.timestampMs <= targetMs && summary.timestampMs > bestCreatedMs) {
+            bestCreatedMs = summary.timestampMs;
+            best = { path: filePath, id: summary.id };
+        }
+    }
+    return best;
+}
+function readSessionHeaderSummary(filePath) {
+    try {
+        const raw = readTextFileIfExists(filePath);
+        if (!raw)
+            return null;
+        const firstLine = raw.slice(0, raw.indexOf("\n")).trim();
+        if (!firstLine)
+            return null;
+        const entry = parseSessionEntry(firstLine);
+        const { id, timestamp } = entry;
+        if (typeof id !== "string" || typeof timestamp !== "string")
+            return null;
+        const timestampMs = new Date(timestamp).getTime();
+        return Number.isFinite(timestampMs) ? { id, timestampMs } : null;
+    }
+    catch {
+        return null;
+    }
 }
 //# sourceMappingURL=store.js.map