@saadnvd1/agent-os 0.3.631 → 0.3.639

package/lib/db/queries.ts

@@ -1,4 +1,5 @@
 import type Database from "better-sqlite3";
+import { SESSION_ROW_COLUMNS } from "./session-parts/columns";
 
 // Prepared statement cache
 const stmtCache = new Map<string, Database.Statement>();
@@ -13,28 +14,18 @@ function getStmt(db: Database.Database, sql: string): Database.Statement {
   return stmt;
 }
 
-// Every sessions column but the two large text ones, which only the single
+// Every session column but the two large text ones, which only the single
 // session paths read; a list gets has_brief for whether a brief exists.
-const listColumns = new WeakMap<Database.Database, string>();
-export function sessionListColumns(db: Database.Database, alias = ""): string {
-  let cols = listColumns.get(db);
-  if (!cols) {
-    cols = (
-      db.prepare(`PRAGMA table_info(sessions)`).all() as { name: string }[]
-    )
-      .map((c) => c.name)
-      .filter((n) => n !== "task_brief" && n !== "system_prompt")
-      .join(",");
-    listColumns.set(db, cols);
-  }
+// Read from session_rows (lib/db/session-parts).
+const LIST_COLUMNS = SESSION_ROW_COLUMNS.filter(
+  (n) => n !== "task_brief" && n !== "system_prompt"
+);
+export function sessionListColumns(_db: Database.Database, alias = ""): string {
   const prefix = alias ? `${alias}.` : "";
-  const list = cols
-    .split(",")
-    .map((c) => `${prefix}${c}`)
-    .join(", ");
+  const list = LIST_COLUMNS.map((c) => `${prefix}${c}`).join(", ");
   // The recipe run or feature piece a session is, as JSON, for its row's chip.
-  const recipe = `(SELECT json_object('id', r.id, 'name', r.name, 'seq', rr.seq, 'status', rr.status) FROM recipe_runs rr JOIN recipes r ON r.id = rr.recipe_id WHERE rr.session_id = ${alias || "sessions"}.id)`;
-  const piece = `(SELECT json_object('feature', f.id, 'name', f.name, 'position', fp.position, 'total', (SELECT COUNT(*) FROM feature_pieces WHERE feature_id = f.id AND status != 'dropped')) FROM feature_pieces fp JOIN features f ON f.id = fp.feature_id WHERE fp.session_id = ${alias || "sessions"}.id)`;
+  const recipe = `(SELECT json_object('id', r.id, 'name', r.name, 'seq', rr.seq, 'status', rr.status) FROM recipe_runs rr JOIN recipes r ON r.id = rr.recipe_id WHERE rr.session_id = ${alias || "session_rows"}.id)`;
+  const piece = `(SELECT json_object('feature', f.id, 'name', f.name, 'position', fp.position, 'total', (SELECT COUNT(*) FROM feature_pieces WHERE feature_id = f.id AND status != 'dropped')) FROM feature_pieces fp JOIN features f ON f.id = fp.feature_id WHERE fp.session_id = ${alias || "session_rows"}.id)`;
   return `${list}, (${prefix}task_brief IS NOT NULL AND ${prefix}task_brief != '') AS has_brief, ${recipe} AS recipe_run, ${piece} AS feature_piece`;
 }
 
@@ -48,12 +39,12 @@ export const queries = {
     ),
 
   getSession: (db: Database.Database) =>
-    getStmt(db, `SELECT * FROM sessions WHERE id = ?`),
+    getStmt(db, `SELECT * FROM session_rows WHERE id = ?`),
 
   getAllSessions: (db: Database.Database) =>
     getStmt(
       db,
-      `SELECT ${sessionListColumns(db)} FROM sessions ORDER BY updated_at DESC`
+      `SELECT ${sessionListColumns(db)} FROM session_rows ORDER BY updated_at DESC`
     ),
 
   // The sidebar's sessions: not archived, and not a dropped task (a
@@ -62,7 +53,7 @@ export const queries = {
   getSidebarSessions: (db: Database.Database) =>
     getStmt(
       db,
-      `SELECT ${sessionListColumns(db)} FROM sessions
+      `SELECT ${sessionListColumns(db)} FROM session_rows
          WHERE archived_at IS NULL
            AND (task_status IS NULL
                 OR task_status NOT IN ('dropped', 'moved'))
@@ -103,12 +94,6 @@ export const queries = {
       `UPDATE sessions SET worktree_path = ?, branch_name = ?, base_branch = ?, dev_server_port = ?, updated_at = datetime('now') WHERE id = ?`
     ),
 
-  updateSessionPR: (db: Database.Database) =>
-    getStmt(
-      db,
-      `UPDATE sessions SET pr_url = ?, pr_number = ?, pr_status = ?, updated_at = datetime('now') WHERE id = ?`
-    ),
-
   updateSessionGroup: (db: Database.Database) =>
     getStmt(
       db,
@@ -118,7 +103,7 @@ export const queries = {
   getSessionsByGroup: (db: Database.Database) =>
     getStmt(
       db,
-      `SELECT * FROM sessions WHERE group_path = ? ORDER BY updated_at DESC`
+      `SELECT * FROM session_rows WHERE group_path = ? ORDER BY updated_at DESC`
     ),
 
   moveSessionsToGroup: (db: Database.Database) =>
@@ -136,14 +121,14 @@ export const queries = {
   getSessionsByProject: (db: Database.Database) =>
     getStmt(
       db,
-      `SELECT * FROM sessions WHERE project_id = ? ORDER BY updated_at DESC`
+      `SELECT * FROM session_rows WHERE project_id = ? ORDER BY updated_at DESC`
     ),
 
   // Orchestration
   getWorkersByConductor: (db: Database.Database) =>
     getStmt(
       db,
-      `SELECT * FROM sessions WHERE conductor_session_id = ? ORDER BY created_at ASC`
+      `SELECT * FROM session_rows WHERE conductor_session_id = ? ORDER BY created_at ASC`
     ),
 
   updateWorkerStatus: (db: Database.Database) =>

package/lib/db/session-parts/columns.ts

@@ -0,0 +1,186 @@
+import type { Session } from "@/lib/db/types";
+
+// The sessions columns that live in their own tables, by concern. Each table
+// is keyed by session_id and holds a row only for a session that has a value
+// in the group; `session_rows` joins them back into the flat shape of a
+// session. See docs/decisions/2026-10-15-split-sessions-table.md.
+export const PART_COLUMNS = {
+  session_tasks: [
+    "task_prompt",
+    "task_brief",
+    "task_status",
+    "task_since",
+    "task_ended_at",
+    "merged_at",
+    "priority",
+    "quick_of",
+    "moved_to",
+    "moved_from",
+    "model_overrides",
+    "lh_card_id",
+    "lh_board_id",
+    "lh_card_list",
+  ],
+  session_prs: [
+    "pr_url",
+    "pr_number",
+    "pr_status",
+    "merge_armed_at",
+    "merge_armed_seen",
+    "rebased_from",
+    "rebased_to",
+    "rebase_asked_head",
+    "pr_wake_since",
+  ],
+  session_plans: [
+    "plan_phase",
+    "plan_only",
+    "plan_decided",
+    "plan_reason",
+    "plan_note",
+    "plan_edits",
+    "plan_waits_for_caller",
+    "plan_handoff_message",
+  ],
+  session_placement: [
+    "peer_mirror",
+    "placed_note",
+    "held_by_device",
+    "held_from",
+    "held_for",
+    "held_for_name",
+    "started_by_device",
+  ],
+  session_pauses: ["pause_state", "paused_until", "pause_id", "pause_note"],
+} as const satisfies Record<string, readonly (keyof Session)[]>;
+
+export type PartTable = keyof typeof PART_COLUMNS;
+export type PartColumn<T extends PartTable> = (typeof PART_COLUMNS)[T][number];
+export type PartPatch<T extends PartTable> = {
+  [C in PartColumn<T>]?: Session[C & keyof Session];
+};
+
+export const PART_TABLES = Object.keys(PART_COLUMNS) as PartTable[];
+
+// Everything else is an INTEGER or TEXT by this list.
+export const INTEGER_COLUMNS: ReadonlySet<string> = new Set([
+  "pr_number",
+  "plan_only",
+  "plan_decided",
+  "plan_waits_for_caller",
+  "peer_mirror",
+  "pause_id",
+]);
+
+const partOfColumn = new Map<string, PartTable>(
+  PART_TABLES.flatMap((t) =>
+    (PART_COLUMNS[t] as readonly string[]).map((c) => [c, t] as const)
+  )
+);
+
+export const isMovedColumn = (column: string): boolean =>
+  partOfColumn.has(column);
+
+export const partOf = (column: string): PartTable | undefined =>
+  partOfColumn.get(column);
+
+// Every column of the sessions table, in order: the shape of a session row
+// and of `session_rows`. A migration that adds a sessions column adds it here
+// and rebuilds the view (createSessionRowsView).
+export const SESSION_ROW_COLUMNS: readonly string[] = [
+  "id",
+  "name",
+  "created_at",
+  "updated_at",
+  "status",
+  "working_directory",
+  "parent_session_id",
+  "claude_session_id",
+  "model",
+  "system_prompt",
+  "group_path",
+  "agent_type",
+  "worktree_path",
+  "branch_name",
+  "base_branch",
+  "dev_server_port",
+  "pr_url",
+  "pr_number",
+  "pr_status",
+  "conductor_session_id",
+  "worker_task",
+  "worker_status",
+  "auto_approve",
+  "project_id",
+  "tmux_name",
+  "host_id",
+  "task_prompt",
+  "task_status",
+  "view",
+  "lh_card_id",
+  "lh_board_id",
+  "lh_card_list",
+  "chat_access",
+  "chat_resume_at",
+  "last_seen_at",
+  "role",
+  "workspace_id",
+  "orch_token",
+  "archived_at",
+  "pinned",
+  "chat_suggestion",
+  "chat_plan",
+  "chat_context",
+  "chat_usage",
+  "name_source",
+  "setup_status",
+  "setup_ms",
+  "setup_error",
+  "task_brief",
+  "moved_to",
+  "moved_from",
+  "port_slot",
+  "ports",
+  "database",
+  "peer_mirror",
+  "chat_restarted",
+  "chat_tools_digest",
+  "merge_armed_at",
+  "merge_armed_seen",
+  "rebased_from",
+  "rebased_to",
+  "rebase_asked_head",
+  "chat_refreshed",
+  "pr_wake_since",
+  "merged_at",
+  "task_ended_at",
+  "model_provider",
+  "model_overrides",
+  "plan_phase",
+  "quick_of",
+  "started_by",
+  "plan_decided",
+  "plan_reason",
+  "task_since",
+  "held_by_device",
+  "held_from",
+  "plan_note",
+  "held_for",
+  "held_for_name",
+  "plan_only",
+  "plan_edits",
+  "active_at",
+  "settled_at",
+  "snoozed_until",
+  "snoozed_at",
+  "priority",
+  "pause_state",
+  "paused_until",
+  "pause_id",
+  "placed_note",
+  "started_by_device",
+  "pause_note",
+  "started_via",
+  "plan_waits_for_caller",
+  "plan_handoff_message",
+];

package/lib/db/session-parts/fill.ts

@@ -0,0 +1,33 @@
+import type Database from "better-sqlite3";
+import { partOf, type PartTable } from "./columns";
+import { writePart } from "./write";
+
+// Copies values onto a session's moved columns where it has none yet: a
+// column that already holds a value, and a null to copy, are left alone.
+// Names that aren't moved columns are the caller's to write.
+export function fillMissing(
+  db: Database.Database,
+  sessionId: string,
+  values: Record<string, string | number | null | undefined>
+): void {
+  const byTable = new Map<PartTable, string[]>();
+  for (const [column, value] of Object.entries(values)) {
+    const table = partOf(column);
+    if (!table || value === null || value === undefined) continue;
+    byTable.set(table, [...(byTable.get(table) ?? []), column]);
+  }
+  db.transaction(() => {
+    for (const [table, columns] of byTable) {
+      const current = db
+        .prepare(`SELECT ${columns.join(", ")} FROM session_rows WHERE id = ?`)
+        .get(sessionId) as Record<string, unknown> | undefined;
+      if (!current) continue;
+      const patch = Object.fromEntries(
+        columns
+          .filter((c) => current[c] === null)
+          .map((c) => [c, values[c]] as const)
+      );
+      writePart(db, table, sessionId, patch as never);
+    }
+  })();
+}

package/lib/db/session-parts/index.ts

@@ -0,0 +1,9 @@
+export * from "./columns";
+export { createSessionRowsView } from "./view";
+export { writePart, type When } from "./write";
+export { setTask, startTaskClock } from "./tasks";
+export { setPr, recordPr } from "./prs";
+export { setPlan, advancePlan } from "./plans";
+export { setPlacement } from "./placement";
+export { setPause } from "./pauses";
+export { fillMissing } from "./fill";

package/lib/db/session-parts/pauses.ts

@@ -0,0 +1,11 @@
+import type Database from "better-sqlite3";
+import type { PartPatch } from "./columns";
+import { writePart, type When } from "./write";
+
+// A task's timed pause.
+export const setPause = (
+  db: Database.Database,
+  sessionId: string,
+  patch: PartPatch<"session_pauses">,
+  when?: When<"session_pauses">
+): boolean => writePart(db, "session_pauses", sessionId, patch, when);

package/lib/db/session-parts/placement.ts

@@ -0,0 +1,11 @@
+import type Database from "better-sqlite3";
+import type { PartPatch } from "./columns";
+import { writePart, type When } from "./write";
+
+// Where a task came from and who holds it: mirror, holder, starting device.
+export const setPlacement = (
+  db: Database.Database,
+  sessionId: string,
+  patch: PartPatch<"session_placement">,
+  when?: When<"session_placement">
+): boolean => writePart(db, "session_placement", sessionId, patch, when);

package/lib/db/session-parts/plans.ts

@@ -0,0 +1,31 @@
+import type Database from "better-sqlite3";
+import type { PartPatch } from "./columns";
+import { writePart, type When } from "./write";
+
+// A task's plan step: phase, note, edits and the hand-off.
+export const setPlan = (
+  db: Database.Database,
+  sessionId: string,
+  patch: PartPatch<"session_plans">,
+  when?: When<"session_plans">
+): boolean => writePart(db, "session_plans", sessionId, patch, when);
+
+// Moves a plan from one phase to the next, only while the task is running
+// and still in `from` (a step another caller took first returns false).
+export function advancePlan(
+  db: Database.Database,
+  sessionId: string,
+  from: string,
+  to: NonNullable<PartPatch<"session_plans">["plan_phase"]>
+): boolean {
+  return db.transaction(() => {
+    const running = db
+      .prepare(
+        `SELECT 1 FROM session_rows WHERE id = ? AND task_status = 'running'`
+      )
+      .get(sessionId);
+    return running
+      ? setPlan(db, sessionId, { plan_phase: to }, { plan_phase: from })
+      : false;
+  })();
+}

package/lib/db/session-parts/prs.ts

@@ -0,0 +1,31 @@
+import type Database from "better-sqlite3";
+import type { Session } from "@/lib/db/types";
+import type { PartPatch } from "./columns";
+import { writePart, type When } from "./write";
+
+// A session's PR and the merge and rebase state kept for it.
+export const setPr = (
+  db: Database.Database,
+  sessionId: string,
+  patch: PartPatch<"session_prs">,
+  when?: When<"session_prs">
+): boolean => writePart(db, "session_prs", sessionId, patch, when);
+
+// A PR found for the session: its link, number and state, and the session
+// counts as touched.
+export function recordPr(
+  db: Database.Database,
+  sessionId: string,
+  pr: { url: string; number: number; state: string }
+): void {
+  db.transaction(() => {
+    setPr(db, sessionId, {
+      pr_url: pr.url,
+      pr_number: pr.number,
+      pr_status: pr.state as Session["pr_status"],
+    });
+    db.prepare(
+      `UPDATE sessions SET updated_at = datetime('now') WHERE id = ?`
+    ).run(sessionId);
+  })();
+}

package/lib/db/session-parts/tasks.ts

@@ -0,0 +1,27 @@
+import type Database from "better-sqlite3";
+import type { PartPatch } from "./columns";
+import { writePart, type When } from "./write";
+
+// A task's brief, status, priority, models and card: lib/db/session-parts/columns.ts.
+export const setTask = (
+  db: Database.Database,
+  sessionId: string,
+  patch: PartPatch<"session_tasks">,
+  when?: When<"session_tasks">
+): boolean => writePart(db, "session_tasks", sessionId, patch, when);
+
+// The task's first start, kept across moves: set once, from created_at when
+// the caller has no better time.
+export function startTaskClock(
+  db: Database.Database,
+  sessionId: string,
+  at?: string | null
+): void {
+  const row = db
+    .prepare(`SELECT created_at, task_since FROM session_rows WHERE id = ?`)
+    .get(sessionId) as
+    | { created_at: string; task_since: string | null }
+    | undefined;
+  if (!row || row.task_since) return;
+  setTask(db, sessionId, { task_since: at ?? row.created_at });
+}

package/lib/db/session-parts/view.ts

@@ -0,0 +1,43 @@
+import type Database from "better-sqlite3";
+import { PART_COLUMNS, type PartTable } from "./columns";
+
+const ALIAS: Record<PartTable, string> = {
+  session_tasks: "t",
+  session_prs: "pr",
+  session_plans: "pl",
+  session_placement: "pp",
+  session_pauses: "pa",
+};
+
+// `session_rows`: the sessions table with each moved column read from its own
+// table, under the same names and in the same order, so a row is the flat
+// session it always was. A column with a default on sessions
+// (peer_mirror) keeps it. Rebuild it in any migration that adds a sessions
+// column. `parts` is the split as that migration knew it.
+export function createSessionRowsView(
+  db: Database.Database,
+  parts: Record<PartTable, readonly string[]> = PART_COLUMNS
+): void {
+  const source = new Map<string, string>();
+  for (const table of Object.keys(parts) as PartTable[])
+    for (const c of parts[table]) source.set(c, ALIAS[table]);
+  const sessionColumns = (
+    db.prepare(`PRAGMA table_info(sessions)`).all() as { name: string }[]
+  ).map((c) => c.name);
+  const select = sessionColumns
+    .map((c) => {
+      const alias = source.get(c);
+      if (!alias) return `s.${c}`;
+      return c === "peer_mirror"
+        ? `COALESCE(${alias}.${c}, 0) AS ${c}`
+        : `${alias}.${c} AS ${c}`;
+    })
+    .join(", ");
+  const joins = (Object.keys(parts) as PartTable[])
+    .map((t) => `LEFT JOIN ${t} ${ALIAS[t]} ON ${ALIAS[t]}.session_id = s.id`)
+    .join(" ");
+  db.exec(`DROP VIEW IF EXISTS session_rows`);
+  db.exec(
+    `CREATE VIEW session_rows AS SELECT ${select} FROM sessions s ${joins}`
+  );
+}

package/lib/db/session-parts/write.ts

@@ -0,0 +1,69 @@
+import type Database from "better-sqlite3";
+import { PART_COLUMNS, type PartPatch, type PartTable } from "./columns";
+
+type Value = string | number | null;
+
+// A condition on the part row's current values, checked with the write in one
+// transaction: every column must equal one of its listed values (null for
+// "unset").
+export type When<T extends PartTable> = {
+  [C in keyof PartPatch<T>]?: Value | readonly Value[];
+};
+
+const sameAs = (current: unknown, wanted: Value | readonly Value[]): boolean =>
+  (Array.isArray(wanted) ? (wanted as Value[]) : [wanted as Value]).some(
+    (w) => (current ?? null) === w
+  );
+
+// The one writer of the part tables. Writes the patched columns to the part
+// table, then mirrors the same values onto the legacy sessions columns, which
+// stay until they are dropped (docs/decisions/2026-10-15-split-sessions-table.md):
+// that UPDATE is the only dual-write, and the step that drops the columns
+// deletes it. Returns whether it wrote (false: the session is gone or `when`
+// no longer holds).
+export function writePart<T extends PartTable>(
+  db: Database.Database,
+  table: T,
+  sessionId: string,
+  patch: PartPatch<T>,
+  when?: When<T>
+): boolean {
+  const allowed = PART_COLUMNS[table] as readonly string[];
+  const columns = Object.keys(patch).filter(
+    (c) => (patch as Record<string, unknown>)[c] !== undefined
+  );
+  for (const c of [...columns, ...Object.keys(when ?? {})])
+    if (!allowed.includes(c)) throw new Error(`${c} is not a ${table} column`);
+  if (columns.length === 0) return false;
+
+  const run = db.transaction((): boolean => {
+    if (when && Object.keys(when).length > 0) {
+      const current = db
+        .prepare(
+          `SELECT ${Object.keys(when).join(", ")} FROM session_rows WHERE id = ?`
+        )
+        .get(sessionId) as Record<string, unknown> | undefined;
+      if (!current) return false;
+      for (const [c, wanted] of Object.entries(when))
+        if (!sameAs(current[c], wanted as Value | readonly Value[]))
+          return false;
+    }
+    const values = { id: sessionId, ...(patch as Record<string, Value>) };
+    const inserted = db
+      .prepare(
+        `INSERT INTO ${table} (session_id, ${columns.join(", ")})
+         SELECT id, ${columns.map((c) => `@${c}`).join(", ")}
+           FROM sessions WHERE id = @id
+         ON CONFLICT(session_id) DO UPDATE SET
+           ${columns.map((c) => `${c} = excluded.${c}`).join(", ")}`
+      )
+      .run(values);
+    if (inserted.changes === 0) return false;
+    db.prepare(
+      `UPDATE sessions SET ${columns.map((c) => `${c} = @${c}`).join(", ")}
+        WHERE id = @id`
+    ).run(values);
+    return true;
+  });
+  return run();
+}

package/lib/db/types.ts

@@ -20,7 +20,7 @@ export interface Session {
   model_overrides?: string | null;
   // A task's plan step: planning on the planning model, then implementing.
   // 'awaiting': a plan-only task's plan is written; it waits for approval.
-  plan_phase?: "planning" | "awaiting" | "implementing" | null;
+  plan_phase?: "planning" | "awaiting" | "handoff" | "implementing" | null;
   plan_only?: number | null;
   // The orchestrator session that started this one; null for a person.
   started_by?: string | null;
@@ -156,6 +156,11 @@ export interface Session {
   held_for_name?: string | null;
   // A held task's "plan written" line, for its orchestrator to read.
   plan_note?: string | null;
+  // The task's plan stops for the machine that placed it here to decide what
+  // comes next (1); on that machine's mirror, the approval's message waits for
+  // the move home.
+  plan_waits_for_caller?: number | null;
+  plan_handoff_message?: string | null;
   // Orchestration fields
   conductor_session_id: string | null;
   worker_task: string | null;

package/lib/done/archive.ts

@@ -34,7 +34,7 @@ export function unarchiveSession(id: string): Session {
       `UPDATE sessions SET archived_at = NULL WHERE id = ? AND archived_at IS NOT NULL`
     )
     .run(id).changes;
-  const row = db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(id) as
+  const row = db.prepare(`SELECT * FROM session_rows WHERE id = ?`).get(id) as
     | Session
     | undefined;
   if (!row) throw new Error("Session not found");
@@ -48,7 +48,7 @@ export function listArchived(workspaceId?: string): ArchivedView[] {
     .prepare(
       `SELECT s.id, s.name, s.project_id, s.view, s.task_status, s.branch_name,
          s.pr_url, s.worktree_path, s.archived_at, p.name AS project_name, p.workspace_id AS project_workspace
-       FROM sessions s LEFT JOIN projects p ON p.id = s.project_id
+       FROM session_rows s LEFT JOIN projects p ON p.id = s.project_id
        WHERE s.archived_at IS NOT NULL
          AND (? IS NULL OR p.workspace_id = ?)
        ORDER BY s.archived_at DESC, s.updated_at DESC`

package/lib/done/auto-archive.ts

@@ -33,7 +33,7 @@ const inDone = (s: Session) =>
 export async function archiveStaleDone(now = Date.now()): Promise<string[]> {
   const rows = db
     .prepare(
-      `SELECT * FROM sessions
+      `SELECT * FROM session_rows
        WHERE archived_at IS NULL AND pinned = 0 AND role IS NULL
          AND peer_mirror = 0 AND quick_of IS NULL
          AND (pr_status IS NULL OR pr_status != 'open')`

package/lib/done/bulk.ts

@@ -50,7 +50,7 @@ function scopeSessions(scope: DoneScope): Session[] {
   if (!projectIds.length) return [];
   return db
     .prepare(
-      `SELECT * FROM sessions
+      `SELECT * FROM session_rows
        WHERE project_id IN (${projectIds.map(() => "?").join(", ")})
          AND role IS NULL AND archived_at IS NULL
          -- A linked machine's own sessions are cleaned up there.