@vellumai/assistant 0.10.0 → 0.10.1-staging.1

package/src/cli/commands/db/__tests__/status.test.ts

@@ -177,9 +177,13 @@ describe("assistant db status — happy path", () => {
     const { stdout } = await runStatus(["status"]);
 
     // The 'started' row is more recent but value != '1', so the
-    // completed row before it wins.
+    // completed row before it wins for "Schema (last)".
     expect(stdout).toContain("newest_v1");
-    expect(stdout).not.toContain("running_v1");
+    // The crashed migration appears in the Crashed line, not in Schema (last).
+    const schemaLine = stdout.match(/Schema \(last\)\s+(.*)/)?.[1] ?? "";
+    expect(schemaLine).not.toContain("running_v1");
+    expect(stdout).toContain("Crashed");
+    expect(stdout).toContain("running_v1");
   });
 
   test("reports WAL journal mode after seeding with WAL", async () => {
@@ -203,7 +207,7 @@ describe("assistant db status — happy path", () => {
     expect(parsed.file.path).toBe(dbPath);
     expect(parsed.db.journalMode).toBe("wal");
     expect(parsed.db.tableCount).toBe(3);
-    expect(parsed.db.latestMigration.key).toBe("migration_newest_v1");
+    expect(parsed.migration.latestKey).toBe("newest_v1");
     expect(Array.isArray(parsed.db.largest)).toBe(true);
     expect(parsed.db.largest.length).toBeGreaterThan(0);
     // Either 'bytes' (if dbstat is available) or 'rows' fallback.

package/src/cli/commands/db/status.ts

@@ -28,6 +28,8 @@ import { Database } from "bun:sqlite";
 
 import type { Command } from "commander";
 
+import { getLogsDbPath } from "../../../util/logs-db-path.js";
+import { getMemoryDbPath } from "../../../util/memory-db-path.js";
 import { getDbPath } from "../../../util/platform.js";
 import { red } from "../../lib/cli-colors.js";
 import { shouldOutputJson, writeOutput } from "../../output.js";
@@ -66,7 +68,6 @@ interface DbFacts {
   walAutocheckpoint: number;
   mmapSize: number;
   tableCount: number;
-  latestMigration: { key: string; updatedAtMs: number } | null;
   largest: { name: string; metric: number }[];
   sizingMethod: SizingMethod;
 }
@@ -74,6 +75,43 @@ interface DbFacts {
 interface StatusReport {
   file: FileFacts;
   db: DbFacts | null;
+  /**
+   * Cross-database migration state, read from the main DB's
+   * `memory_checkpoints` ledger. Because the secondary databases (logs,
+   * memory) are ATTACHed and managed by the same migration runner, the
+   * checkpoint ledger lives only in the main DB — this summary is the single
+   * source of truth for "what migration state is the workspace at?"
+   */
+  migration?: MigrationSummary;
+  /**
+   * The dedicated append-only database (`assistant-logs.db`). Omitted from the
+   * report when the file does not exist yet — it is created the first time the
+   * daemon opens its connection, so a fresh install that has never run the
+   * daemon won't have one.
+   */
+  logsFile?: FileFacts;
+  logsDb?: DbFacts | null;
+  /**
+   * The dedicated memory database (`assistant-memory.db`). Like `logsFile`, it
+   * is omitted from the report until the file exists on disk — it is created
+   * the first time the daemon opens its connection, so a fresh install that
+   * has never run the daemon won't have one.
+   */
+  memoryFile?: FileFacts;
+  memoryDb?: DbFacts | null;
+}
+
+interface MigrationSummary {
+  /** Latest registry-backed migration checkpoint key (without `migration_` prefix). */
+  latestKey: string | null;
+  /** Age of the latest checkpoint, in ms. */
+  latestUpdatedAtMs: number | null;
+  /** Count of `step:*` checkpoints with value='1'. */
+  appliedSteps: number;
+  /** Count of `migration_*` / `backfill_*` / `drop_*` checkpoints with value='1'. */
+  appliedRegistry: number;
+  /** Checkpoint keys still in 'started' or 'rolling_back' state (crash recovery). */
+  crashed: string[];
 }
 
 // ---------------------------------------------------------------------------
@@ -150,26 +188,6 @@ function readDbFacts(path: string): DbFacts {
         )
         .get()?.n ?? 0;
 
-    // Latest applied migration. The memory migration runner writes
-    // `migration_<name>` rows into `memory_checkpoints` with value='1' on
-    // success. If `memory_checkpoints` doesn't exist yet (pre-migration
-    // database), best-effort skip without erroring out.
-    let latestMigration: DbFacts["latestMigration"] = null;
-    try {
-      const row = db
-        .query<{ key: string; updated_at: number }, []>(
-          `SELECT key, updated_at FROM memory_checkpoints
-           WHERE key LIKE 'migration_%' AND value = '1'
-           ORDER BY updated_at DESC LIMIT 1`,
-        )
-        .get();
-      if (row) {
-        latestMigration = { key: row.key, updatedAtMs: row.updated_at };
-      }
-    } catch {
-      latestMigration = null;
-    }
-
     // Largest tables. Prefer `dbstat` when the runtime SQLite has it
     // compiled in (gives true byte sizes). Bun's bundled SQLite omits
     // dbstat, so we fall back to COUNT(*). Detect at runtime, not via
@@ -223,7 +241,6 @@ function readDbFacts(path: string): DbFacts {
       walAutocheckpoint,
       mmapSize,
       tableCount,
-      latestMigration,
       largest,
       sizingMethod,
     };
@@ -242,8 +259,7 @@ function row(label: string, value: string): string {
   return `${label.padEnd(LABEL_WIDTH)}${value}\n`;
 }
 
-function renderHuman(report: StatusReport): string {
-  const { file, db } = report;
+function renderDbBlock(file: FileFacts, db: DbFacts | null): string {
   let out = "";
 
   out += row("Path", file.path);
@@ -275,14 +291,6 @@ function renderHuman(report: StatusReport): string {
 
   out += "\n";
   out += row("Tables", String(db.tableCount));
-  if (db.latestMigration) {
-    out += row(
-      "Schema (last)",
-      `${db.latestMigration.key.replace(/^migration_/, "")}  (${formatAge(Date.now() - db.latestMigration.updatedAtMs)})`,
-    );
-  } else {
-    out += row("Schema (last)", "unknown");
-  }
 
   out += "\n";
   const sizingHeader =
@@ -302,6 +310,137 @@ function renderHuman(report: StatusReport): string {
   return out;
 }
 
+function renderHuman(report: StatusReport): string {
+  let out = renderDbBlock(report.file, report.db);
+
+  // The secondary append-only file is only reported once it exists on disk.
+  if (report.logsFile?.exists) {
+    out += "\n";
+    out += "Logs database (append-only tables)\n";
+    out += renderDbBlock(report.logsFile, report.logsDb ?? null);
+  }
+
+  // The secondary memory file is likewise only reported once it exists.
+  if (report.memoryFile?.exists) {
+    out += "\n";
+    out += "Memory database (high-churn memory tables)\n";
+    out += renderDbBlock(report.memoryFile, report.memoryDb ?? null);
+  }
+
+  // Cross-database migration summary — the checkpoint ledger lives only in
+  // the main DB, so this is a single block at the end covering all three.
+  out += renderSummary(report.migration);
+
+  return out;
+}
+
+/**
+ * Read cross-database migration state from the main DB's `memory_checkpoints`.
+ *
+ * The checkpoint ledger lives only in the main DB — secondary databases
+ * (logs, memory) are ATTACHed and managed by the same runner, so their
+ * migration state is tracked here. This is the single query point for
+ * "what schema version is the workspace at?"
+ */
+function readMigrationSummary(mainDbPath: string): MigrationSummary | null {
+  const db = new Database(mainDbPath, { readonly: true });
+  try {
+    // Latest registry-backed migration checkpoint.
+    let latestKey: string | null = null;
+    let latestUpdatedAtMs: number | null = null;
+    try {
+      const row = db
+        .query<{ key: string; updated_at: number }, []>(
+          `SELECT key, updated_at FROM memory_checkpoints
+           WHERE (key LIKE 'migration_%' OR key LIKE 'backfill_%' OR key LIKE 'drop_%')
+             AND value = '1'
+           ORDER BY updated_at DESC LIMIT 1`,
+        )
+        .get();
+      if (row) {
+        latestKey = row.key.replace(/^migration_/, "");
+        latestUpdatedAtMs = row.updated_at;
+      }
+    } catch {
+      // memory_checkpoints doesn't exist yet (pre-migration database).
+    }
+
+    // Count of step: checkpoints (step runner system).
+    let appliedSteps = 0;
+    try {
+      appliedSteps =
+        db
+          .query<{ n: number }, []>(
+            `SELECT COUNT(*) AS n FROM memory_checkpoints
+             WHERE key LIKE 'step:%' AND value = '1'`,
+          )
+          .get()?.n ?? 0;
+    } catch {
+      // No table yet.
+    }
+
+    // Count of registry-backed checkpoints.
+    let appliedRegistry = 0;
+    try {
+      appliedRegistry =
+        db
+          .query<{ n: number }, []>(
+            `SELECT COUNT(*) AS n FROM memory_checkpoints
+             WHERE (key LIKE 'migration_%' OR key LIKE 'backfill_%' OR key LIKE 'drop_%')
+               AND value = '1'`,
+          )
+          .get()?.n ?? 0;
+    } catch {
+      // No table yet.
+    }
+
+    // Crashed (started or rolling_back) checkpoints.
+    let crashed: string[] = [];
+    try {
+      crashed = (
+        db
+          .query<{ key: string }, []>(
+            `SELECT key FROM memory_checkpoints
+             WHERE value = 'started' OR value = 'rolling_back'`,
+          )
+          .all() as { key: string }[]
+      ).map((r) => r.key);
+    } catch {
+      // No table yet.
+    }
+
+    return { latestKey, latestUpdatedAtMs, appliedSteps, appliedRegistry, crashed };
+  } finally {
+    db.close();
+  }
+}
+
+function renderSummary(migration: MigrationSummary | undefined): string {
+  if (!migration) return "";
+
+  let out = "\nMigration summary (cross-database)\n";
+
+  if (migration.latestKey) {
+    const age = migration.latestUpdatedAtMs
+      ? formatAge(Date.now() - migration.latestUpdatedAtMs)
+      : "?";
+    out += row("Schema (last)", `${migration.latestKey}  (${age})`);
+  } else {
+    out += row("Schema (last)", "unknown");
+  }
+  out += row("Steps applied", String(migration.appliedSteps));
+  out += row("Registry applied", String(migration.appliedRegistry));
+
+  if (migration.crashed.length > 0) {
+    out += row(
+      "Crashed",
+      `${red(String(migration.crashed.length))}  (${migration.crashed.join(", ")})`,
+    );
+  }
+
+  return out;
+}
+
 function renderMissing(path: string): string {
   return (
     `${red("ERROR")}  Database not found at ${path}\n\n` +
@@ -356,7 +495,47 @@ export function registerDbStatus(parent: Command): void {
         process.exit(1);
       }
 
-      const report: StatusReport = { file, db };
+      // Best-effort probe of the dedicated append-only DB. It may not exist
+      // yet (fresh install that has never started the daemon), and a probe
+      // failure must never mask the main-DB report.
+      const logsFile = readFileFacts(getLogsDbPath());
+      let logsDb: DbFacts | null = null;
+      if (logsFile.exists) {
+        try {
+          logsDb = readDbFacts(logsFile.path);
+        } catch {
+          logsDb = null;
+        }
+      }
+
+      // Same best-effort probe for the dedicated memory DB.
+      const memoryFile = readFileFacts(getMemoryDbPath());
+      let memoryDb: DbFacts | null = null;
+      if (memoryFile.exists) {
+        try {
+          memoryDb = readDbFacts(memoryFile.path);
+        } catch {
+          memoryDb = null;
+        }
+      }
+
+      // Cross-database migration summary from the main DB's checkpoint ledger.
+      let migration: MigrationSummary | null = null;
+      try {
+        migration = readMigrationSummary(file.path);
+      } catch {
+        migration = null;
+      }
+
+      const report: StatusReport = {
+        file,
+        db,
+        migration: migration ?? undefined,
+        logsFile,
+        logsDb,
+        memoryFile,
+        memoryDb,
+      };
       if (shouldOutputJson(this)) {
         writeOutput(this, report);
       } else {

package/src/cli/commands/memory/__tests__/memory-v3.test.ts

@@ -145,7 +145,12 @@ describe("subcommand registration", () => {
     const v3 = memory!.commands.find((c) => c.name() === "v3");
     expect(v3).toBeDefined();
     const subcommandNames = v3!.commands.map((c) => c.name()).sort();
-    expect(subcommandNames).toEqual(["backfill-sections", "eval", "rebuild-index"]);
+    expect(subcommandNames).toEqual([
+      "backfill-sections",
+      "eval",
+      "eval-tally",
+      "rebuild-index",
+    ]);
   });
 });
 

package/src/cli/commands/memory/index.ts

@@ -1,6 +1,7 @@
 import type { Command } from "commander";
 
 import { registerCommand } from "../../lib/register-command.js";
+import { registerMemoryRetrospectiveCommand } from "./memory-retrospective.js";
 import { registerMemoryV2Command } from "./memory-v2.js";
 import { registerMemoryV3Command } from "./memory-v3.js";
 
@@ -25,6 +26,7 @@ Examples:
 
       registerMemoryV2Command(memory);
       registerMemoryV3Command(memory);
+      registerMemoryRetrospectiveCommand(memory);
     },
   });
 }

package/src/cli/commands/memory/memory-retrospective.ts

@@ -0,0 +1,129 @@
+/**
+ * `assistant memory retrospective` CLI subgroup.
+ *
+ * Runs memory retrospectives directly in the CLI process — no IPC, no daemon
+ * required. Each subcommand imports the retrospective machinery and calls it
+ * against the workspace's on-disk SQLite database directly.
+ *
+ * Subcommands:
+ *
+ *   - `run <conversationId>` — run a fork-based retrospective on a conversation.
+ *   - `list` — list the last five retrospectives (TODO).
+ */
+
+import type { Command } from "commander";
+
+import { getConfig } from "../../../config/loader.js";
+import {
+  type MemoryRetrospectiveOutcome,
+  runForkBasedRetrospective,
+} from "../../../memory/memory-retrospective-job.js";
+import { registerCommand } from "../../lib/register-command.js";
+import { log } from "../../logger.js";
+import { shouldOutputJson, writeOutput } from "../../output.js";
+
+export function registerMemoryRetrospectiveCommand(memory: Command): void {
+  registerCommand(memory, {
+    name: "retrospective",
+    transport: "local",
+    description: "Run and inspect memory retrospectives (direct, no IPC)",
+    build: (retro) => {
+      retro.addHelpText(
+        "after",
+        `
+Runs memory retrospectives directly against the workspace database — the CLI
+process imports the retrospective machinery and calls it in-process, so no
+running daemon is required.
+
+Examples:
+  $ assistant memory retrospective run <conversationId>`,
+      );
+
+      // ── run ───────────────────────────────────────────────────────────────
+
+      retro
+        .command("run")
+        .description("Run a fork-based retrospective on a conversation")
+        .argument("<conversationId>", "Source conversation to retrospective")
+        .option("--json", "Emit raw JSON instead of a formatted summary")
+        .addHelpText(
+          "after",
+          `
+Forks the source conversation through its latest message, persists a
+retrospective instruction, and wakes the fork so the agent reviews the new
+messages and calls \`remember\` on anything worth saving. Runs entirely in the
+CLI process — no IPC round-trip to the daemon.
+
+Examples:
+  $ assistant memory retrospective run abc123`,
+        )
+        .action(async (conversationId: string, opts: { json?: boolean }, cmd: Command) => {
+          const config = getConfig();
+          let outcome: MemoryRetrospectiveOutcome;
+          try {
+            outcome = await runForkBasedRetrospective(conversationId, config);
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            log.error(
+              { err, conversationId },
+              "memory-retrospective: run threw",
+            );
+            if (opts.json === true) {
+              writeOutput(cmd, { kind: "error", error: msg });
+            } else {
+              log.error(msg);
+            }
+            process.exitCode = 1;
+            return;
+          }
+
+          if (shouldOutputJson(cmd)) {
+            writeOutput(cmd, outcome);
+            return;
+          }
+
+          renderOutcome(outcome);
+        });
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Human-readable rendering
+// ---------------------------------------------------------------------------
+
+function renderOutcome(outcome: MemoryRetrospectiveOutcome): void {
+  switch (outcome.kind) {
+    case "disabled":
+      log.info("Retrospective is disabled for this workspace.");
+      break;
+    case "no_new_messages":
+      log.info("No new messages to review since the last retrospective.");
+      break;
+    case "source_processing":
+      log.info(
+        "Source conversation is mid-turn; skipping (will retry next trigger).",
+      );
+      break;
+    case "wake_failed":
+      log.error(
+        `Wake failed${outcome.reason ? `: ${outcome.reason}` : ""}` +
+          (outcome.conversationId
+            ? ` (fork: ${outcome.conversationId})`
+            : ""),
+      );
+      process.exitCode = 1;
+      break;
+    case "invoked":
+      log.info(
+        `Retrospective invoked.\n` +
+          `  fork conversation: ${outcome.backgroundConversationId}\n` +
+          `  cutoff message:    ${outcome.cutoffMessageId}\n` +
+          `  new messages:      ${outcome.newMessageCount}` +
+          (outcome.followUpJobIds.length > 0
+            ? `\n  follow-up jobs:    ${outcome.followUpJobIds.join(", ")}`
+            : ""),
+      );
+      break;
+  }
+}