mirror-mind 0.36.0 → 0.36.2

package/ts/src/guards/retiredSurfaces.ts

@@ -280,9 +280,9 @@ export const RETIRED: readonly RetiredSurface[] = [
     absentPaths: [],
     forbiddenPatterns: [
       // The flags and the two service methods. NOT the bare word `backfill`:
-      // `conversation-logger backfill-pi-sessions` and
-      // `ts/src/conversation/backfill.ts` are the TRANSCRIPT backfills, a
-      // different feature that is ported and staying.
+      // the transcript backfill (`ts/src/conversation/transcriptBackfill.ts`)
+      // is a different feature, ported and staying. (The Pi session backfill
+      // that stood beside it is retired by its own row, `pi-session-backfill`.)
       "--metadata-backfill-",
       "metadata_backfill",
       "preview_metadata_backfill",
@@ -492,8 +492,6 @@ export const RETIRED: readonly RetiredSurface[] = [
     exemptions: {
       "docs/getting-started.md":
         "the un-wiring guidance: a user who started codex through the retired wrapper needs its name to undo that wiring",
-      "ts/src/conversation/backfill.ts":
-        "the header names the retired importer to say where it went, beside the Pi importer that stays",
     },
   },
   {
@@ -545,6 +543,45 @@ export const RETIRED: readonly RetiredSurface[] = [
     ],
     exemptions: {},
   },
+  {
+    surfaceId: "pi-session-backfill",
+    story: "CR153",
+    // Session maintenance's Pi backfill: a walk of Pi's session directory that
+    // imported every file this home's `runtime_sessions` did not track. That
+    // held while a machine had one home. With two, each imported the other's
+    // sessions -- 543 conversations on the maintainer's machine, both ways,
+    // each titled again through the provider -- and both imported the sessions
+    // of scratch homes and of Pi run without Mirror, while the gap it existed
+    // to fill, a session the home's own extension never logged, came up once
+    // in three months. A home's Pi conversations are the ones the Pi extension
+    // logged into it, and nothing reads a Pi session file. `importClosedConversation`
+    // went with it: the Codex importer that also wrote through it retired with
+    // DS4.TS5. `PI_SESSIONS_DIR` is inert, and only the records that say so,
+    // and the test that proves it, may name it.
+    absentPaths: [
+      "ts/src/conversation/backfill.ts",
+      "ts/src/conversation/sessionImport.ts",
+      "ts/test/conversation/backfill.test.ts",
+      "ts/test/db/homeBornAt.test.ts",
+      "ts/test/fixtures/backfill/pi-sessions/",
+    ],
+    forbiddenPatterns: [
+      "backfillPiSessions",
+      "resolvePiSessionsDir",
+      "homeBornAt",
+      "importClosedConversation",
+      "PI_SESSIONS_DIR",
+      "Backfilled Pi sessions",
+    ],
+    exemptions: {
+      "docs/reference/configuration.md":
+        "the inert-values record: a `.env` may still carry PI_SESSIONS_DIR, and the reference says nothing reads it",
+      ".env.example.advanced":
+        "marks PI_SESSIONS_DIR inert, so a leftover line is recognized rather than trusted",
+      "ts/test/conversation/loggerCli.test.ts":
+        "sets PI_SESSIONS_DIR to a directory holding a fresh session and proves maintenance imports nothing from it",
+    },
+  },
 ];
 
 export interface SurfaceProblem {

package/ts/src/util/strictArgs.ts

@@ -0,0 +1,59 @@
+// argparse-shaped strict parsing: every option declared, anything else refused.
+//
+// Moved from `dbSafetyToolsRoute.ts`, where `backup` and `repair-encoding` use
+// it, when CR154 needed the same strictness for `conversations imported`. The
+// reason is the same in all three: these commands write, and a lenient parser
+// turns a typo into a different command. Under the `conversations` listing's
+// parser, which ignores what it does not know, `remove --all --projet <folder>
+// --apply` would drop the misspelled filter and remove every import in the
+// home. Here the typo is refused, and nothing runs.
+//
+// Positionals are opt-in, for a grammar that takes them (CR154's ids). A token
+// that starts with `-` is never a positional: an option nobody declared is a
+// typo, not a value.
+
+export interface StrictArgsSpec {
+  /** Options that stand alone. */
+  readonly flags: readonly string[];
+  /** Options that take the next token as their value, whatever it looks like. */
+  readonly valued: readonly string[];
+  /** Whether bare tokens are accepted, in order; otherwise they are unrecognized. */
+  readonly positionals?: boolean;
+}
+
+export interface ParsedArgs {
+  flags: Set<string>;
+  values: Map<string, string>;
+  positionals: string[];
+  /** argparse's message for the first problem, or null. */
+  error: string | null;
+}
+
+export function parseArgs(args: readonly string[], spec: StrictArgsSpec): ParsedArgs {
+  const flags = new Set<string>();
+  const values = new Map<string, string>();
+  const positionals: string[] = [];
+  const unrecognized: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] as string;
+    if (spec.flags.includes(arg)) {
+      flags.add(arg);
+    } else if (spec.valued.includes(arg)) {
+      const value = args[index + 1];
+      if (value === undefined)
+        return { flags, values, positionals, error: `argument ${arg}: expected one argument` };
+      values.set(arg, value);
+      index += 1;
+    } else if (spec.positionals === true && !arg.startsWith("-")) {
+      positionals.push(arg);
+    } else {
+      unrecognized.push(arg);
+    }
+  }
+  return {
+    flags,
+    values,
+    positionals,
+    error: unrecognized.length > 0 ? `unrecognized arguments: ${unrecognized.join(" ")}` : null,
+  };
+}

package/ts/src/conversation/backfill.ts

@@ -1,271 +0,0 @@
-// Session backfills from runtime-written JSONL (CV22.DS7.US10 slice E).
-//
-// Ports `backfill_pi_sessions` from `src/memory/cli/conversation_logger.py`:
-// it imports closed sessions the live hooks never saw, through the atomic
-// seam in `sessionImport.ts`, and is graded against
-// `ts/test/goldens/backfill.golden.json`. (The Codex importer,
-// `backfill_codex_session`, was ported beside it and retired with the
-// v0.32.1 Codex wrapper by CV21.DS4.TS5: its only caller was the wrapper's
-// session-end hook, and the plugin logs Codex turns live.)
-//
-// Pi titles through `set_provisional_title` (whitespace collapse plus
-// `title_source`/`title_status` provenance in metadata), tolerates a corrupt
-// or structurally invalid file by skipping THAT file and continuing the
-// walk, and parses every timestamp form (millisecond epoch, string, absent).
-//
-// Nothing here touches a provider or the clock directly: `now` is injected
-// through `LoggerDeps`, which is what makes "no timestamp -> now" pinnable.
-//
-// CR121 (2026-10-11): a home imports only the Pi sessions newer than itself.
-// Python imported every untracked session on the machine, which for a new
-// home meant the person's whole Pi history, copied and spent on before the
-// first prompt. The floor is explicit (`notBefore`), never defaulted, and
-// the rule fails closed: there is no value that means "everything" except
-// the epoch, which says so.
-
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { join, relative, sep } from "node:path";
-import { type LoggerDeps, setProvisionalTitle } from "#conversation/logger.ts";
-import { type ImportedMessage, importClosedConversation } from "#conversation/sessionImport.ts";
-import type { WritableDatabase } from "#db/database.ts";
-import { expandHome } from "#util/paths.ts";
-import { comparePathComponents, sliceCodePoints } from "#util/pythonText.ts";
-
-/** Python `_DEFAULT_PI_SESSIONS_DIR`: `~/.pi/agent/sessions`. */
-export function defaultPiSessionsDir(homeDir: string): string {
-  return join(homeDir, ".pi", "agent", "sessions");
-}
-
-/**
- * Python's source-directory resolution for the Pi backfill, in order:
- * explicit argument -> `PI_SESSIONS_DIR` -> `~/.pi/agent/sessions`.
- * (Python's module-level `_PI_SESSIONS_DIR` override exists only for its own
- * test monkey-patching and has no runtime input; it is not a contract.)
- */
-export function resolvePiSessionsDir(
-  explicit: string | null | undefined,
-  env: { PI_SESSIONS_DIR?: string },
-  homeDir: string,
-): string {
-  if (explicit) return expandHome(explicit);
-  if (env.PI_SESSIONS_DIR) return expandHome(env.PI_SESSIONS_DIR);
-  return defaultPiSessionsDir(homeDir);
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/**
- * Python `dict.get(key, default)` on a value that MUST be a dict: anything
- * else raises AttributeError, which each parser turns into its own failure
- * mode. The default applies only when the key is ABSENT -- a present `null`
- * is returned as null, exactly as Python returns None, so a later `.get` on
- * it raises rather than silently reading from the default.
- */
-function getOr(container: unknown, key: string, fallback: unknown): unknown {
-  if (!isRecord(container)) throw new TypeError(`expected an object with '${key}'`);
-  return key in container ? container[key] : fallback;
-}
-
-function getFrom(container: unknown, key: string): unknown {
-  return getOr(container, key, undefined);
-}
-
-/** Python `_parse_pi_content`: a string as-is, text blocks joined by `\n`, else `""`. */
-export function parsePiContent(content: unknown): string {
-  if (typeof content === "string") return content;
-  if (Array.isArray(content)) {
-    const parts: string[] = [];
-    for (const block of content) {
-      if (!isRecord(block) || block.type !== "text") continue;
-      const text = block.text ?? "";
-      // `"\n".join(...)` raises on a non-str item; the file is skipped.
-      if (typeof text !== "string") throw new TypeError("text block is not a string");
-      parts.push(text);
-    }
-    return parts.join("\n");
-  }
-  return "";
-}
-
-/**
- * Python `datetime.fromtimestamp(ms / 1000, tz=utc).isoformat()`:
- * `+00:00` suffix (not `Z`), microseconds only when non-zero, rounded from
- * the fractional second the way CPython does (`round(frac * 1e6)`).
- */
-function pythonUtcIsoFromEpochMs(epochMs: number): string {
-  const seconds = epochMs / 1000;
-  let whole = Math.floor(seconds);
-  let micros = Math.round((seconds - whole) * 1e6);
-  if (micros >= 1_000_000) {
-    whole += 1;
-    micros -= 1_000_000;
-  }
-  const base = new Date(whole * 1000).toISOString().slice(0, 19);
-  const fraction = micros === 0 ? "" : `.${String(micros).padStart(6, "0")}`;
-  return `${base}${fraction}+00:00`;
-}
-
-/**
- * Python `_parse_pi_timestamp`: a number above 1e10 is a millisecond epoch;
- * a string is stored verbatim; anything else (absent, null, a seconds epoch,
- * a boolean -- which is an int in Python but never exceeds 1e10) is `now`.
- */
-export function parsePiTimestamp(value: unknown, now: () => string): string {
-  if (typeof value === "number" && value > 1e10) return pythonUtcIsoFromEpochMs(value);
-  if (typeof value === "string") return value;
-  return now();
-}
-
-/**
- * Parse one Pi session file into importable messages. Throws on any line
- * that is not valid JSON or not the expected shape -- Python wraps the whole
- * file loop in one `try` and skips the file on the first failure, even after
- * earlier lines parsed cleanly.
- */
-function parsePiSessionFile(path: string, now: () => string): ImportedMessage[] {
-  const messages: ImportedMessage[] = [];
-  for (const line of readFileSync(path, "utf8").split(/\r?\n|\r/)) {
-    if (!line.trim()) continue;
-    const entry: unknown = JSON.parse(line);
-    if (getFrom(entry, "type") !== "message") continue;
-    const message = getOr(entry, "message", {});
-    const role = getOr(message, "role", "");
-    if (role !== "user" && role !== "assistant") continue;
-    const content = parsePiContent(getOr(message, "content", ""));
-    if (!content.trim()) continue;
-    const createdAt = parsePiTimestamp(getFrom(message, "timestamp"), now);
-    messages.push({ role, content, createdAt });
-  }
-  return messages;
-}
-
-/**
- * Python `sorted(pi_sessions_dir.rglob("*.jsonl"))`: every `.jsonl` file
- * under the directory, ordered by path components (see
- * `comparePathComponents` for why that is not a string sort).
- */
-function listPiSessionFiles(sessionsDir: string): string[] {
-  const entries = readdirSync(sessionsDir, { recursive: true, withFileTypes: true });
-  const found: string[][] = [];
-  for (const entry of entries) {
-    if (!entry.name.endsWith(".jsonl")) continue;
-    const parents = relative(sessionsDir, entry.parentPath).split(sep).filter(Boolean);
-    found.push([...parents, entry.name]);
-  }
-  found.sort(comparePathComponents);
-  return found.map((components) => join(sessionsDir, ...components));
-}
-
-export interface PiBackfillOptions {
-  /** Already resolved through `resolvePiSessionsDir`. */
-  sessionsDir: string;
-  /**
-   * An ISO instant: a session that ended at or before it is not imported
-   * (CR121). Production passes the home's birth (`homeBornAt`); a caller
-   * that wants no floor passes the epoch and says so.
-   */
-  notBefore: string;
-}
-
-/**
- * When this home was born: the first `applied_at` in the `_migrations`
- * ledger. A fresh database stamps its whole ledger at its first open, and a
- * database from any earlier era carries the ledger from its own first open,
- * so the minimum is the birth of every home there is -- with no new table,
- * column, or marker. Read once per maintenance run.
- *
- * The ledger means "which migrations ran, when"; reading its minimum as a
- * birth is an inference, accepted because every plausible edit to the ledger
- * moves the minimum forward and imports less, never more. `migrations.ts`
- * names this consumer at the ledger's definition. A second consumer of
- * "birth" is the trigger to model it as a row of its own.
- *
- * Fails closed: an empty ledger is an error, not a home born at the epoch.
- */
-export function homeBornAt(db: WritableDatabase): string {
-  const row = db.prepare("SELECT MIN(applied_at) AS born FROM _migrations").get() as
-    | { born: string | null }
-    | undefined;
-  if (typeof row?.born !== "string" || !row.born) {
-    throw new Error("the _migrations ledger is empty: this home's birth is unknown");
-  }
-  return row.born;
-}
-
-/** The instant of an ISO timestamp, or NaN for anything `Date.parse` rejects. */
-function instant(iso: string): number {
-  return Date.parse(iso);
-}
-
-/**
- * Python `backfill_pi_sessions`: import every untracked Pi session with at
- * least two messages as a closed `pi` conversation, titled provisionally from
- * the first user line. Returns the number imported.
- *
- * The session id is the session file's path, exactly as Python's
- * `str(session_file)` -- which is also what the live Pi extension binds, so a
- * session the hooks already track is skipped before its file is even read.
- *
- * CR121: a session is Mirror's only if it ended after `notBefore`. Two
- * checks, in cost order. A file whose mtime is at or before the floor is
- * skipped unread: its last message was written at or before its last write,
- * so it cannot be newer. (This is what keeps a skipped session, which is
- * never tracked, from being parsed again at every start for the rest of the
- * home's life.) A file written after the floor is parsed and judged by its
- * last message, the same instant it stores as `endedAt` -- a copy or a sync
- * can touch a file long after its conversation ended. A session whose
- * messages carry no parseable instant dates to `now` under the existing rule
- * and is imported: undated is newer, not older.
- */
-export function backfillPiSessions(
-  db: WritableDatabase,
-  options: PiBackfillOptions,
-  deps: LoggerDeps,
-): number {
-  const floor = instant(options.notBefore);
-  if (Number.isNaN(floor)) {
-    throw new Error(`notBefore is not an instant: ${JSON.stringify(options.notBefore)}`);
-  }
-  if (!existsSync(options.sessionsDir)) return 0;
-
-  let count = 0;
-  for (const sessionFile of listPiSessionFiles(options.sessionsDir)) {
-    const sessionId = sessionFile;
-    if (db.prepare("SELECT 1 FROM runtime_sessions WHERE session_id = ?").get(sessionId)) {
-      continue;
-    }
-    if (statSync(sessionFile).mtimeMs <= floor) continue;
-    let messages: ImportedMessage[];
-    try {
-      messages = parsePiSessionFile(sessionFile, deps.nowIso);
-    } catch {
-      continue;
-    }
-    if (messages.length < 2) continue;
-    const endedAt = instant((messages.at(-1) as ImportedMessage).createdAt);
-    if (endedAt <= floor) continue;
-
-    const conversationId = importClosedConversation(
-      db,
-      sessionId,
-      { interface: "pi", messages, endedAt: (messages.at(-1) as ImportedMessage).createdAt },
-      deps,
-    );
-    if (conversationId === null) {
-      // A concurrent writer (a live hook) bound this session while the import
-      // waited for the write lock -- their binding wins.
-      continue;
-    }
-    const firstUser = messages.find((message) => message.role === "user");
-    if (firstUser) {
-      // Python: `content.strip().split("\n")[0][:60]` -- cut BEFORE the
-      // provisional-title whitespace collapse, by code point.
-      const title = sliceCodePoints(firstUser.content.trim().split("\n")[0] ?? "", 60);
-      setProvisionalTitle(db, conversationId, title);
-    }
-    count += 1;
-  }
-  return count;
-}

package/ts/src/conversation/sessionImport.ts

@@ -1,90 +0,0 @@
-// Atomic closed-session import (CV22.DS7.US10 slice E).
-//
-// Ports `RuntimeSessionService.import_closed_conversation` from
-// `src/memory/services/runtime_session.py`, the seam both backfills write
-// through. It is the sibling of `getOrCreateSessionConversation` in
-// `logger.ts` and shares its transaction discipline for the same reason:
-// a backfill imports against the SAME `runtime_sessions` key a live hook
-// binds (Pi's live session id is the session file path), and the two can
-// interleave.
-//
-// Resolved decision 4B (plan.md): the binding check runs INSIDE the
-// `BEGIN IMMEDIATE` transaction, so a binding a concurrent hook committed
-// while this import waited for the write lock is seen and honored -- the
-// import returns null instead of clobbering a live session with
-// `active=0`/`closed_at`. The same atomicity removes the crash-window
-// duplicate-import path: either the conversation, every message, and the
-// binding all land, or nothing does.
-//
-// Titles are deliberately NOT set here. The two callers title differently
-// (Pi through `setProvisionalTitle`, Codex through a bare column write) and
-// Python applies both after commit; reproducing that asymmetry is the
-// callers' job.
-
-import type { LoggerDeps } from "#conversation/logger.ts";
-import { type WritableDatabase, withTransaction } from "#db/database.ts";
-
-export interface ImportedMessage {
-  role: string;
-  content: string;
-  createdAt: string;
-}
-
-export interface ClosedSessionImport {
-  interface: string;
-  messages: readonly ImportedMessage[];
-  endedAt: string;
-}
-
-/**
- * Import a closed session transcript as one conversation bound to
- * `sessionId`. Returns the new conversation id, or null when the session is
- * already tracked -- including by a writer that won the binding while this
- * call waited for the lock.
- */
-export function importClosedConversation(
-  db: WritableDatabase,
-  sessionId: string,
-  session: ClosedSessionImport,
-  deps: LoggerDeps,
-): string | null {
-  return withTransaction(db, () => {
-    const tracked = db
-      .prepare("SELECT 1 FROM runtime_sessions WHERE session_id = ?")
-      .get(sessionId);
-    if (tracked) return null;
-
-    // Python's Conversation(...) draws its id before its started_at; keep the
-    // same generator order so injected sequences line up with the oracle.
-    const conversationId = deps.newId();
-    const startedAt = deps.nowIso();
-    db.prepare(
-      `INSERT INTO conversations
-         (id, title, started_at, ended_at, interface, persona, journey, summary, tags, metadata)
-       VALUES (?, NULL, ?, ?, ?, NULL, NULL, NULL, NULL, NULL)`,
-    ).run(conversationId, startedAt, session.endedAt, session.interface);
-
-    const insertMessage = db.prepare(
-      `INSERT INTO messages (id, conversation_id, role, content, created_at, token_count, metadata)
-       VALUES (?, ?, ?, ?, ?, NULL, NULL)`,
-    );
-    for (const message of session.messages) {
-      insertMessage.run(
-        deps.newId(),
-        conversationId,
-        message.role,
-        message.content,
-        message.createdAt,
-      );
-    }
-
-    db.prepare(
-      `INSERT INTO runtime_sessions
-         (session_id, conversation_id, interface, mirror_active, persona, journey,
-          hook_injected, active, started_at, updated_at, closed_at, metadata)
-       VALUES (?, ?, ?, 0, NULL, NULL, 0, 0, ?, ?, ?, NULL)`,
-    ).run(sessionId, conversationId, session.interface, startedAt, startedAt, session.endedAt);
-
-    return conversationId;
-  });
-}