@saadnvd1/agent-os 0.3.637 → 0.3.644

package/components/Health/SweepRuns.tsx

@@ -0,0 +1,125 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import { useRunSweep, useWorktreeSweep } from "@/data/worktree-sweep";
+import { compactTimeAgo, fromSqliteTime } from "@/lib/session-meta";
+import { formatBytes } from "@/lib/share/view";
+import type { SweepRun } from "@/lib/worktree-sweep/types";
+
+const KIND: Record<string, string> = {
+  settled: "settled session",
+  orphan: "orphan folder",
+  "test-leak": "test leftover",
+};
+
+const name = (p: string) => p.split("/").pop();
+
+function Run({ run }: { run: SweepRun }) {
+  const skipped = run.details?.skipped ?? [];
+  const removed = run.details?.removed ?? [];
+  return (
+    <li className="border-border/60 border-b px-3 py-1 last:border-b-0">
+      <details>
+        <summary className="flex min-h-11 cursor-pointer flex-wrap items-center gap-x-3 gap-y-1 text-sm">
+          <span className="font-medium">
+            {run.dryRun ? "Dry run, would remove" : "Removed"} {run.removed}
+          </span>
+          <span className="text-muted-foreground tabular-nums">
+            {formatBytes(run.freedBytes)}
+          </span>
+          <span className="text-muted-foreground">{run.skipped} skipped</span>
+          <span className="text-muted-foreground ml-auto text-xs">
+            {run.finishedAt
+              ? compactTimeAgo(fromSqliteTime(run.finishedAt))
+              : "running"}
+          </span>
+        </summary>
+        {run.error && (
+          <p role="alert" className="text-destructive mt-2 text-sm">
+            {run.error}
+          </p>
+        )}
+        {skipped.length > 0 && (
+          <div className="mt-2 space-y-1 pb-2">
+            <p className="text-sm font-medium">Skipped</p>
+            <ul className="text-muted-foreground space-y-1 text-xs">
+              {skipped.slice(0, 200).map((s) => (
+                <li key={s.path} className="break-all">
+                  {name(s.path)}: {s.reason}
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+        {removed.length > 0 && (
+          <div className="mt-2 space-y-1 pb-2">
+            <p className="text-sm font-medium">Removed</p>
+            <ul className="text-muted-foreground space-y-1 text-xs">
+              {removed.slice(0, 200).map((r) => (
+                <li key={r.path} className="break-all">
+                  {name(r.path)} ({KIND[r.kind]}, {formatBytes(r.bytes)})
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+      </details>
+    </li>
+  );
+}
+
+// Each worktree clean-up run: what it removed, freed and skipped, and why.
+export function SweepRuns() {
+  const { data, isPending, error } = useWorktreeSweep();
+  const run = useRunSweep();
+  return (
+    <div className="space-y-3">
+      <div className="flex flex-wrap items-center gap-2">
+        <p className="text-muted-foreground min-w-0 flex-1 text-sm">
+          Settled worktrees older than {data?.days ?? data?.defaultDays ?? 7}{" "}
+          days are removed every 6 hours. Branches and conversations stay.
+        </p>
+        <Button
+          variant="outline"
+          className="min-h-11 md:min-h-8"
+          disabled={run.isPending}
+          onClick={() => run.mutate(true)}
+        >
+          Dry run
+        </Button>
+        <Button
+          className="min-h-11 md:min-h-8"
+          disabled={run.isPending}
+          onClick={() => run.mutate(false)}
+        >
+          Run now
+        </Button>
+      </div>
+      {run.error && (
+        <p role="alert" className="text-destructive text-sm">
+          {run.error.message}
+        </p>
+      )}
+      {error && (
+        <p role="alert" className="text-destructive text-sm">
+          {error.message}
+        </p>
+      )}
+      {isPending && (
+        <div className="bg-muted/40 h-24 animate-pulse rounded-xl" />
+      )}
+      {data && data.runs.length === 0 && (
+        <p className="text-muted-foreground text-sm">
+          No run yet. The first one starts 10 minutes after the server does.
+        </p>
+      )}
+      {data && data.runs.length > 0 && (
+        <ul className="border-border/60 overflow-hidden rounded-xl border">
+          {data.runs.map((r) => (
+            <Run key={r.id} run={r} />
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

package/components/Merge/GlobalMergeSection.tsx

@@ -11,6 +11,7 @@ import {
 } from "@/lib/tasks/merge-methods";
 import { MergeApprovalToggle } from "./MergeApprovalToggle";
 import { MergeSettingsFields } from "./MergeSettingsFields";
+import { GlobalSweepSection } from "./WorktreeSweepSection";
 
 // "rebase, keeps worktree"
 function describe(s: MergeSettings): string {
@@ -85,6 +86,7 @@ export function GlobalMergeSection() {
         )}
       </div>
       {data && <Overrides overrides={data.overrides} />}
+      <GlobalSweepSection />
     </div>
   );
 }

package/components/Merge/ProjectMergeSection.tsx

@@ -5,6 +5,7 @@ import {
   useUpdateProjectMergeSettings,
 } from "@/data/merge";
 import { MergeSettingsFields } from "./MergeSettingsFields";
+import { ProjectSweepSection } from "./WorktreeSweepSection";
 
 // A project's own merge settings, saved as they change. Unset ones inherit
 // from agentos.json, then the global settings.
@@ -42,6 +43,7 @@ export function ProjectMergeSection({
         <p className="text-destructive text-sm">{update.error.message}</p>
       )}
       <p className="text-muted-foreground text-xs">Saved as you change them.</p>
+      <ProjectSweepSection projectId={projectId} />
     </div>
   );
 }

package/components/Merge/WorktreeSweepSection.tsx

@@ -0,0 +1,125 @@
+"use client";
+
+import { useState } from "react";
+import { Input } from "@/components/ui/input";
+import { useSetSweepDays, useWorktreeSweep } from "@/data/worktree-sweep";
+import { compactTimeAgo, fromSqliteTime } from "@/lib/session-meta";
+import { formatBytes } from "@/lib/share/view";
+
+// Days as the box shows them; empty means "inherit".
+function DaysInput({
+  value,
+  placeholder,
+  disabled,
+  onSave,
+}: {
+  value: number | null;
+  placeholder: string;
+  disabled: boolean;
+  onSave: (days: number | null) => void;
+}) {
+  const [text, setText] = useState(value === null ? "" : String(value));
+  const commit = () => {
+    const raw = text.trim();
+    const next = raw === "" ? null : Number(raw);
+    if (next === value || (next !== null && !Number.isInteger(next))) return;
+    onSave(next);
+  };
+  return (
+    <Input
+      aria-label="Days before a settled worktree is removed"
+      inputMode="numeric"
+      value={text}
+      placeholder={placeholder}
+      disabled={disabled}
+      onChange={(e) => setText(e.target.value)}
+      onBlur={commit}
+      onKeyDown={(e) => e.key === "Enter" && e.currentTarget.blur()}
+      className="h-11 w-24 text-right tabular-nums md:h-9"
+    />
+  );
+}
+
+function LastRun() {
+  const { data } = useWorktreeSweep();
+  const last = data?.runs.find((r) => r.finishedAt && !r.dryRun);
+  if (!last) return null;
+  return (
+    <p className="text-muted-foreground text-xs">
+      Last run {compactTimeAgo(fromSqliteTime(last.finishedAt!))}: removed{" "}
+      {last.removed}, {formatBytes(last.freedBytes)} freed, {last.skipped}{" "}
+      skipped. Details in Health &gt; Clean-up.
+    </p>
+  );
+}
+
+// How long a settled worktree stays on disk. The branch and the conversation
+// stay; restoring the session rebuilds it.
+export function GlobalSweepSection() {
+  const { data, isPending, isError, error } = useWorktreeSweep();
+  const save = useSetSweepDays();
+  return (
+    <div className="space-y-2">
+      <h3 className="text-sm font-medium">Worktree clean-up</h3>
+      <p className="text-muted-foreground text-sm">
+        Remove the worktree of a merged, dropped, done or archived session this
+        many days after it settled, when nothing in it would be lost. 0 turns it
+        off.
+      </p>
+      {isPending && (
+        <div className="bg-muted/40 h-11 animate-pulse rounded-lg" />
+      )}
+      {isError && <p className="text-destructive text-sm">{error.message}</p>}
+      {data && (
+        <div className="flex items-center gap-3">
+          <DaysInput
+            key={data.days ?? "none"}
+            value={data.days}
+            placeholder={String(data.defaultDays)}
+            disabled={save.isPending}
+            onSave={(days) => save.mutate({ days })}
+          />
+          <span className="text-muted-foreground text-sm">days</span>
+        </div>
+      )}
+      {data && data.overrides.length > 0 && (
+        <p className="text-muted-foreground text-xs">
+          Own number:{" "}
+          {data.overrides.map((o) => `${o.name} (${o.days})`).join(", ")}
+        </p>
+      )}
+      {save.isError && (
+        <p className="text-destructive text-sm">{save.error.message}</p>
+      )}
+      <LastRun />
+    </div>
+  );
+}
+
+export function ProjectSweepSection({ projectId }: { projectId: string }) {
+  const { data } = useWorktreeSweep();
+  const save = useSetSweepDays();
+  const own =
+    data?.overrides.find((o) => o.projectId === projectId)?.days ?? null;
+  const inherited = data?.days ?? data?.defaultDays ?? 7;
+  return (
+    <div className="space-y-2">
+      <h3 className="text-sm font-medium">Worktree clean-up</h3>
+      <div className="flex items-center gap-3">
+        <DaysInput
+          key={own ?? "none"}
+          value={own}
+          placeholder={String(inherited)}
+          disabled={!data || save.isPending}
+          onSave={(days) => save.mutate({ days, projectId })}
+        />
+        <span className="text-muted-foreground text-sm">
+          days after a session settles (empty: {inherited}, 0: off)
+        </span>
+      </div>
+      {save.isError && (
+        <p className="text-destructive text-sm">{save.error.message}</p>
+      )}
+    </div>
+  );
+}

package/components/Settings/NoApprovalsSection.tsx

@@ -8,7 +8,7 @@ import { useApprovalsModeQuery, useSetApprovalsMode } from "@/data/approvals";
 // What it switches off, said plainly before it can be switched on.
 export const NO_APPROVALS_WARNING = [
   "Every ask is approved the moment it is raised, hard lines included: public posts and messages, money, irreversible or destructive changes, credentials.",
-  "A PR that failed its gates twice, has no CI, or is too big to review still merges.",
+  "A PR stuck failing its gates, with no CI, or too big to review still merges.",
   "Brakes stop holding new starts, and plan-only tasks go on to implement without waiting for a plan approval.",
   "Every agent AgentOS starts runs with its permission prompts off, and prompts already waiting are allowed.",
 ];

package/components/Settings/SettingsDialog.tsx

@@ -59,7 +59,7 @@ export const SECTION_INFO: Record<
 > = {
   merging: {
     label: "Merging",
-    hint: "Approval, merge method, branch clean-up",
+    hint: "Approval, merge method, branch and worktree clean-up",
     icon: GitMerge,
   },
   approvals: {

package/data/worktree-sweep/index.ts

@@ -0,0 +1,56 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import type { SweepState } from "@/lib/worktree-sweep/state";
+
+export const sweepKeys = { all: ["worktree-sweep"] as const };
+
+async function json<T>(res: Response): Promise<T> {
+  const data = await res.json();
+  if (!res.ok) throw new Error(data.error || "Request failed");
+  return data;
+}
+
+export function useWorktreeSweep(enabled = true) {
+  return useQuery({
+    queryKey: sweepKeys.all,
+    queryFn: async () => json<SweepState>(await fetch("/api/worktree-sweep")),
+    enabled,
+    refetchInterval: 60_000,
+  });
+}
+
+export function useSetSweepDays() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (v: { days: number | null; projectId?: string }) =>
+      json<SweepState>(
+        await fetch("/api/worktree-sweep", {
+          method: "PUT",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(v),
+        })
+      ),
+    onSuccess: (data) => queryClient.setQueryData(sweepKeys.all, data),
+  });
+}
+
+export function useRunSweep() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (dryRun: boolean) =>
+      json<{ started: boolean }>(
+        await fetch("/api/worktree-sweep/run", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ dryRun }),
+        })
+      ),
+    onSuccess: () => {
+      // The run is in the background; look again as it goes.
+      for (const ms of [1500, 8000, 30000])
+        setTimeout(
+          () => queryClient.invalidateQueries({ queryKey: sweepKeys.all }),
+          ms
+        );
+    },
+  });
+}

package/lib/approvals/enable.ts

@@ -29,7 +29,7 @@ async function sweep(): Promise<void> {
   }
   const plans = db
     .prepare(
-      `SELECT id, host_id, plan_waits_for_caller FROM sessions WHERE plan_phase = 'awaiting' AND task_status = 'running'`
+      `SELECT id, host_id, plan_waits_for_caller FROM session_rows WHERE plan_phase = 'awaiting' AND task_status = 'running'`
     )
     .all() as {
     id: string;

package/lib/away/report.ts

@@ -92,7 +92,7 @@ export function inFlightWhy(t: {
 }): string {
   const escalated = t.failures.filter((f) => f.escalated_at);
   if (escalated.length)
-    return `with you: the ${escalated.map((f) => f.gate).join(" and ")} gate failed twice`;
+    return `with you: the ${escalated.map((f) => f.gate).join(" and ")} gate kept failing (the loop guard)`;
   if (t.askKinds.length) return `waiting on your answer (${t.askKinds[0]})`;
   const flagged = t.flagged
     ? `; flagged to the orchestrator ${t.flagged}x while you were away`
@@ -137,7 +137,7 @@ function merged(
   const rows = db
     .prepare(
       `SELECT s.id, s.name, p.name AS project, p.id AS project_id, s.pr_number, s.pr_url
-       FROM sessions s JOIN projects p ON p.id = s.project_id
+       FROM session_rows s JOIN projects p ON p.id = s.project_id
        WHERE p.workspace_id = ? AND s.task_status = 'merged'
          AND s.merged_at >= ? AND s.merged_at <= ?
        ORDER BY s.merged_at, s.id`
@@ -178,7 +178,7 @@ function inFlight(workspaceId: string, awayId: number): InFlightItem[] {
     .prepare(
       `SELECT s.id, s.name, p.name AS project, s.pr_number, s.pr_url,
          s.merge_armed_at AS armed_at
-       FROM sessions s JOIN projects p ON p.id = s.project_id
+       FROM session_rows s JOIN projects p ON p.id = s.project_id
        WHERE p.workspace_id = ? AND s.role IS NULL AND s.archived_at IS NULL
          AND s.task_status = 'running'
          AND EXISTS (SELECT 1 FROM away_actions a WHERE a.away_id = ?
@@ -224,7 +224,7 @@ function failed(workspaceId: string, away: AwayRow, end: string) {
   const deploys = db
     .prepare(
       `SELECT a.detail, s.name, s.pr_number, s.pr_url FROM away_actions a
-       LEFT JOIN sessions s ON s.id = a.subject
+       LEFT JOIN session_rows s ON s.id = a.subject
        WHERE a.away_id = ? AND a.workspace_id = ? AND a.kind = 'deploy_failed'
        ORDER BY a.id`
     )
@@ -236,7 +236,7 @@ function failed(workspaceId: string, away: AwayRow, end: string) {
   }[];
   const ended = db
     .prepare(
-      `SELECT s.name, s.task_status, s.pr_number, s.pr_url FROM sessions s
+      `SELECT s.name, s.task_status, s.pr_number, s.pr_url FROM session_rows s
        JOIN projects p ON p.id = s.project_id
        WHERE p.workspace_id = ? AND s.task_status IN ('dropped', 'done')
          AND s.task_ended_at >= ? AND s.task_ended_at <= ?

package/lib/away/run.ts

@@ -69,7 +69,7 @@ function orchestrated(): { workspaceId: string; orchestratorId: string }[] {
 }
 
 const sessionRow = (id: string) =>
-  db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(id) as
+  db.prepare(`SELECT * FROM session_rows WHERE id = ?`).get(id) as
     | Session
     | undefined;
 
@@ -330,7 +330,7 @@ async function checkDeploys(
   const found: DeployFinding[] = [];
   const merged = db
     .prepare(
-      `SELECT s.* FROM sessions s JOIN projects p ON p.id = s.project_id
+      `SELECT s.* FROM session_rows s JOIN projects p ON p.id = s.project_id
        WHERE p.workspace_id = ? AND s.task_status = 'merged' AND s.merged_at >= ?
          AND NOT EXISTS (SELECT 1 FROM away_actions a
            WHERE a.away_id = ? AND a.key = 'deploy:' || s.id)`

package/lib/bookmarks/store.ts

@@ -57,7 +57,7 @@ type Joined = Row & {
 // The bookmark with its chat's state as of now.
 const SELECT = `
   SELECT b.*, s.id AS s_id, s.task_status, s.archived_at
-  FROM chat_bookmarks b LEFT JOIN sessions s ON s.id = b.session_id`;
+  FROM chat_bookmarks b LEFT JOIN session_rows s ON s.id = b.session_id`;
 
 function toBookmark(r: Joined): Bookmark {
   return {
@@ -141,7 +141,7 @@ export function createBookmark(input: {
     throw new BookmarkError("scope must be 'item' or 'turn'", 400);
   const note = cleanNote(input.note);
   const session = db
-    .prepare(`SELECT * FROM sessions WHERE id = ?`)
+    .prepare(`SELECT * FROM session_rows WHERE id = ?`)
     .get(sessionId) as Session | undefined;
   if (!session) throw new BookmarkError("Session not found", 404);
   const existing = db
@@ -308,7 +308,7 @@ export function insertMovedBookmarks(
 ): void {
   if (!rows.length) return;
   const session = db
-    .prepare(`SELECT * FROM sessions WHERE id = ?`)
+    .prepare(`SELECT * FROM session_rows WHERE id = ?`)
     .get(sessionId) as Session | undefined;
   if (!session) return;
   const workspace = sessionWorkspace(session);

package/lib/bus/held-reply.ts

@@ -68,7 +68,7 @@ export function pendingReplies(device: string, limit = 50): PendingReply[] {
     db
       .prepare(
         `SELECT m.id, m.from_id AS fromId, m.body, m.created_at AS createdAt
-         FROM bus_messages m JOIN sessions s ON s.id = m.from_id
+         FROM bus_messages m JOIN session_rows s ON s.id = m.from_id
          WHERE m.relay_state = 'pending' AND s.held_by_device = ?
          ORDER BY m.id LIMIT ?`
       )
@@ -81,7 +81,7 @@ export function ackReplies(device: string, ids: number[]): void {
   const mark = db.prepare(
     `UPDATE bus_messages SET relay_state = 'relayed', delivered_at = datetime('now')
      WHERE id = ? AND relay_state = 'pending'
-       AND from_id IN (SELECT id FROM sessions WHERE held_by_device = ?)`
+       AND from_id IN (SELECT id FROM session_rows WHERE held_by_device = ?)`
   );
   db.transaction(() => {
     for (const id of ids) mark.run(id, device);

package/lib/bus/index.ts

@@ -15,7 +15,7 @@ import { deliverToPane, type Delivery } from "./delivery";
 import { resolveRef, wasNames, type Candidate } from "./resolve";
 import { tmuxPane } from "./tmux-pane";
 import { pauseHoldOf, pausedNote } from "../tasks/pause-hold";
-import { isHeldRemote, relayToHeldTask } from "../tasks/held-remote";
+import { isHeldRemote, relayToHeldTask } from "../tasks/contract/held-calls";
 import {
   assertTakesMessages,
   findQueuedTarget,
@@ -43,7 +43,7 @@ export interface Peer {
 function liveSessions(): Session[] {
   return db
     .prepare(
-      `SELECT * FROM sessions WHERE (task_status IS NULL OR task_status = 'running')
+      `SELECT * FROM session_rows WHERE (task_status IS NULL OR task_status = 'running')
          AND archived_at IS NULL
        ORDER BY updated_at DESC`
     )
@@ -63,7 +63,7 @@ function candidates(sessions: Session[]): Candidate[] {
 
 const sessionById = (id: string | null | undefined) =>
   id
-    ? (db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(id) as
+    ? (db.prepare(`SELECT * FROM session_rows WHERE id = ?`).get(id) as
         | Session
         | undefined)
     : undefined;

package/lib/chat/compact-context.ts

@@ -28,7 +28,7 @@ async function gitStatus(cwd: string): Promise<string> {
 export async function compactContext(sessionId: string): Promise<string> {
   const session = db
     .prepare(
-      `SELECT working_directory, task_prompt, role FROM sessions WHERE id = ?`
+      `SELECT working_directory, task_prompt, role FROM session_rows WHERE id = ?`
     )
     .get(sessionId) as
     | Pick<Session, "working_directory" | "task_prompt" | "role">

package/lib/chat/hold.ts

@@ -15,10 +15,10 @@ import { db } from "../db";
 
 // The SQL form, for queries that take the session id as @sid.
 export const HELD_SQL = `(
-  EXISTS (SELECT 1 FROM sessions WHERE id = @sid AND task_status = 'moving')
+  EXISTS (SELECT 1 FROM session_rows WHERE id = @sid AND task_status = 'moving')
   OR EXISTS (SELECT 1 FROM stack_items i JOIN stacks s ON s.id = i.stack_id
              WHERE i.session_id = @sid AND s.status = 'landing')
-  OR EXISTS (SELECT 1 FROM sessions WHERE id = @sid
+  OR EXISTS (SELECT 1 FROM session_rows WHERE id = @sid
              AND pause_state IN ('pausing', 'paused'))
 )`;
 
@@ -58,7 +58,7 @@ const holdRow = (sessionId: string) =>
       `SELECT task_status, moved_to, quick_of, pause_state, paused_until,
          EXISTS (SELECT 1 FROM stack_items i JOIN stacks s ON s.id = i.stack_id
                  WHERE i.session_id = @sid AND s.status = 'landing') AS landing
-       FROM sessions WHERE id = @sid`
+       FROM session_rows WHERE id = @sid`
     )
     .get({ sid: sessionId }) as HoldRow | undefined;
 

package/lib/chat/refresh.ts

@@ -163,7 +163,7 @@ export function autoCompactEnv(sessionId: string): Record<string, string> {
   const row = db
     .prepare(
       `SELECT role, task_status, plan_phase, started_by, model_provider
-       FROM sessions WHERE id = ?`
+       FROM session_rows WHERE id = ?`
     )
     .get(sessionId) as
     | {

package/lib/chat/registry.ts

@@ -112,9 +112,9 @@ export function emit(sessionId: string, m: ChatServerMessage): void {
 }
 
 export function getSession(sessionId: string): Session {
-  const s = db.prepare(`SELECT * FROM sessions WHERE id = ?`).get(sessionId) as
-    | Session
-    | undefined;
+  const s = db
+    .prepare(`SELECT * FROM session_rows WHERE id = ?`)
+    .get(sessionId) as Session | undefined;
   if (!s) throw new Error("Session not found");
   return s;
 }

package/lib/chat/runner.ts

@@ -549,7 +549,7 @@ async function resumeCutOff(sessionId: string): Promise<void> {
     .prepare(
       `SELECT s.name, s.view, s.archived_at, s.task_status, s.role,
          COALESCE(s.workspace_id, p.workspace_id) AS workspace_id
-       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.id = ?`
     )
     .get(sessionId) as

package/lib/chat/worker/main.ts

@@ -30,7 +30,7 @@ async function main(sessionId: string) {
   const { ChatHost } = await import("./host");
 
   const row = db
-    .prepare(`SELECT * FROM sessions WHERE id = ?`)
+    .prepare(`SELECT * FROM session_rows WHERE id = ?`)
     .get(sessionId) as Session | undefined;
   if (!row) {
     console.error(`No session ${sessionId}`);

package/lib/db/backup.ts

@@ -0,0 +1,49 @@
+import type Database from "better-sqlite3";
+import Sqlite from "better-sqlite3";
+import { randomBytes } from "crypto";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { refuseRealStateUnderTest } from "../test-home-guard";
+
+export const backupsDir = (): string =>
+  refuseRealStateUnderTest(path.join(os.homedir(), ".agent-os", "backups"));
+
+// A full copy of the database (VACUUM INTO) under ~/.agent-os/backups, taken
+// before a destructive migration. Throws, and the migration must stop, unless
+// the copy exists and holds every session. The message never says "already
+// exists": the migration runner reads that as applied.
+export function backupDatabase(
+  db: Database.Database,
+  label: string,
+  dir: string = backupsDir()
+): string {
+  const stamp = new Date().toISOString().replace(/[-:]/g, "").slice(0, 15);
+  const file = path.join(
+    dir,
+    `agent-os-${stamp}-${process.pid}-${randomBytes(3).toString("hex")}-${label}.db`
+  );
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    db.prepare(`VACUUM INTO ?`).run(file);
+    fs.chmodSync(file, 0o600);
+    const copy = new Sqlite(file, { readonly: true });
+    try {
+      const count = (sql: Database.Database) =>
+        (
+          sql.prepare(`SELECT COUNT(*) AS n FROM sessions`).get() as {
+            n: number;
+          }
+        ).n;
+      if (count(copy) !== count(db)) throw new Error("session count differs");
+    } finally {
+      copy.close();
+    }
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Backup before ${label} failed (${file}): ${reason.replace(/already exists/gi, "is present")}. Nothing was changed.`
+    );
+  }
+  return file;
+}

package/lib/db/index.ts

@@ -1,16 +1,18 @@
 import Database from "better-sqlite3";
-import path from "path";
 import fs from "fs";
 import { createSchema } from "./schema";
 import { runMigrations } from "./migrations";
 import { dbPath } from "./path";
 
+import { machineDb } from "./machine-scope";
+
 // Re-export types and queries
 export * from "./types";
 export { queries, sessionListColumns } from "./queries";
 export * from "./lumifyhub";
 export * from "./lumifyhub-docs";
 export * from "./stacks";
+export * from "./session-parts";
 
 const DB_PATH = dbPath();
 const LOCK_PATH = DB_PATH + ".init-lock";
@@ -89,6 +91,8 @@ export function initDb(): Database.Database {
 let _db: Database.Database | null = null;
 
 export function getDb(): Database.Database {
+  const scoped = machineDb.getStore();
+  if (scoped) return scoped;
   if (!_db) {
     _db = initDb();
   }