@saadnvd1/agent-os 0.3.503 → 0.3.506

package/lib/session-logs/build.ts

@@ -0,0 +1,253 @@
+/**
+ * A merged task's log as markdown, from data gathered by gather.ts. A fixed
+ * template and nothing else: no model is ever asked to write or summarise
+ * it. Text that came from a task, CI, a reviewer or a person is untrusted:
+ * long text goes in a fence it can't close, short text in a code span, so it
+ * can't add headings, links or sections to the document.
+ */
+
+import { redact } from "../orchestrator/untrusted";
+
+export interface LogEvent {
+  // SQLite UTC time ("YYYY-MM-DD HH:MM:SS"), or null when none was recorded.
+  at: string | null;
+  // AgentOS's own words for what happened.
+  text: string;
+  sha?: string | null;
+  // A short untrusted value that belongs in the sentence (a check's name).
+  quote?: string | null;
+  // Longer untrusted text (a verdict, an answer).
+  detail?: string | null;
+}
+
+export interface LogUsageRow {
+  role: string;
+  model: string;
+  turns: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  costUsd: number;
+  // The price table doesn't list the model: the cost is a floor.
+  unpriced: boolean;
+}
+
+export interface LogData {
+  id: string;
+  name: string;
+  workspace: string | null;
+  project: string | null;
+  branch: string | null;
+  prNumber: number | null;
+  prUrl: string | null;
+  mergeCommit: string | null;
+  startedAt: string | null;
+  mergedAt: string | null;
+  prompt: string;
+  scopeChanges: { at: string; text: string }[];
+  // null: the task wrote no plan. planKept false: it may have, and the file
+  // was gone before the log was written.
+  plan: string | null;
+  planKept: boolean;
+  timeline: LogEvent[];
+  usage: LogUsageRow[];
+  outcome: string | null;
+  // The session in the AgentOS UI, as a path.
+  sessionPath: string;
+  // Caps applied to long text, so a log stays readable.
+  verdictChars?: number;
+}
+
+export const VERDICT_CHARS = 1500;
+
+const fence = (text: string): string => {
+  const runs = text.match(/`+/g) ?? [];
+  const longest = runs.reduce((n, r) => Math.max(n, r.length), 0);
+  const ticks = "`".repeat(Math.max(3, longest + 1));
+  return `${ticks}text\n${text}\n${ticks}`;
+};
+
+const clean = (text: string) => redact(text.replace(/\r\n?/g, "\n")).trim();
+
+export const trim = (text: string, max: number): string =>
+  text.length > max ? `${text.slice(0, max).trimEnd()}\n… (trimmed)` : text;
+
+const oneLine = (text: string) => clean(text).replace(/\s+/g, " ");
+
+// Inline untrusted text as a code span, whatever it contains.
+export function codeSpan(text: string): string {
+  const t = oneLine(text) || "(empty)";
+  const runs = t.match(/`+/g) ?? [];
+  const longest = runs.reduce((n, r) => Math.max(n, r.length), 0);
+  const ticks = "`".repeat(longest + 1);
+  const pad = t.startsWith("`") || t.endsWith("`") ? " " : "";
+  return `${ticks}${pad}${t}${pad}${ticks}`;
+}
+
+// Untrusted text in a heading or a table cell: no markup survives.
+const plain = (text: string) =>
+  oneLine(text).replace(/[\\`*_{}[\]<>()#+!|~&]/g, (c) => `\\${c}`);
+
+const indent = (block: string, by = 2) =>
+  block
+    .split("\n")
+    .map((l) => (l ? " ".repeat(by) + l : l))
+    .join("\n");
+
+const when = (at: string | null) =>
+  at ? `${at.slice(0, 16).replace("T", " ")} UTC` : "—";
+
+export function formatDuration(ms: number): string {
+  const min = Math.max(0, Math.round(ms / 60_000));
+  const d = Math.floor(min / 1440);
+  const h = Math.floor((min % 1440) / 60);
+  const m = min % 60;
+  return [d && `${d}d`, (d || h) && `${h}h`, `${m}m`].filter(Boolean).join(" ");
+}
+
+// SQLite's UTC "YYYY-MM-DD HH:MM:SS" to ms.
+export const sqliteMs = (at: string | null | undefined): number | null => {
+  if (!at) return null;
+  const ms = Date.parse(
+    `${at.replace(" ", "T")}${at.includes("Z") ? "" : "Z"}`
+  );
+  return Number.isNaN(ms) ? null : ms;
+};
+
+const n = (x: number) => x.toLocaleString("en-US");
+const usd = (x: number, floor: boolean) =>
+  `${floor ? "≥ " : ""}$${x.toFixed(x >= 1 ? 2 : 4)}`;
+
+// A link only when it is a plain web address; anything else is shown as text.
+const url = (u: string) =>
+  /^https?:\/\/[^\s<>()[\]`]+$/.test(u) ? `<${u}>` : codeSpan(u);
+
+function header(d: LogData): string {
+  const start = sqliteMs(d.startedAt);
+  const end = sqliteMs(d.mergedAt);
+  const duration =
+    start !== null && end !== null ? formatDuration(end - start) : "unknown";
+  const rows: [string, string][] = [
+    ["Task", `${codeSpan(d.name)} (${codeSpan(d.id)})`],
+    ["Workspace", d.workspace ? codeSpan(d.workspace) : "none"],
+    ["Project", d.project ? codeSpan(d.project) : "none"],
+    ["Branch", d.branch ? codeSpan(d.branch) : "none"],
+    [
+      "Pull request",
+      d.prNumber
+        ? `#${d.prNumber}${d.prUrl ? ` ${url(d.prUrl)}` : ""}`
+        : "none recorded",
+    ],
+    ["Merge commit", d.mergeCommit ? codeSpan(d.mergeCommit) : "not recorded"],
+    ["Started", when(d.startedAt)],
+    ["Merged", when(d.mergedAt)],
+    ["Duration", duration],
+  ];
+  return rows.map(([k, v]) => `- **${k}:** ${v}`).join("\n");
+}
+
+function brief(d: LogData): string {
+  const parts = [
+    "## Brief",
+    "",
+    "### Original prompt",
+    "",
+    fence(clean(d.prompt)),
+  ];
+  if (d.scopeChanges.length) {
+    parts.push("", "### Scope changes", "");
+    d.scopeChanges.forEach((c, i) => {
+      parts.push(
+        `${i + 1}. ${when(c.at)}`,
+        "",
+        indent(fence(clean(c.text))),
+        ""
+      );
+    });
+    parts.pop();
+  }
+  return parts.join("\n");
+}
+
+function plan(d: LogData): string {
+  const body =
+    d.plan !== null
+      ? fence(clean(d.plan))
+      : d.planKept
+        ? "This task wrote no plan."
+        : "Plan not kept: this log was written after the task's worktree was removed.";
+  return `## Plan\n\n${body}`;
+}
+
+function timeline(d: LogData): string {
+  const cap = d.verdictChars ?? VERDICT_CHARS;
+  if (!d.timeline.length) return "## Timeline\n\nNothing was recorded.";
+  const lines = d.timeline.map((e) => {
+    const sha = e.sha ? ` on ${codeSpan(e.sha.slice(0, 7))}` : "";
+    const quote = e.quote ? `: ${codeSpan(trim(e.quote, 300))}` : "";
+    const head = `- ${e.at ? `${when(e.at)} — ` : ""}${e.text}${sha}${quote}`;
+    return e.detail
+      ? `${head}\n\n${indent(fence(trim(clean(e.detail), cap)))}\n`
+      : head;
+  });
+  return `## Timeline\n\n${lines.join("\n").replace(/\n+$/, "")}`;
+}
+
+function usage(d: LogData): string {
+  if (!d.usage.length)
+    return "## Usage\n\nNo model usage was recorded for this task.";
+  const head = [
+    "| Role | Model | Turns | Input | Output | Cache read | Cache write | Cost |",
+    "| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: |",
+  ];
+  const rows = d.usage.map(
+    (u) =>
+      `| ${plain(u.role)} | ${plain(u.model)} | ${n(u.turns)} | ${n(u.inputTokens)} | ${n(u.outputTokens)} | ${n(u.cacheReadTokens)} | ${n(u.cacheWriteTokens)} | ${usd(u.costUsd, u.unpriced)} |`
+  );
+  const sum = d.usage.reduce(
+    (t, u) => ({
+      turns: t.turns + u.turns,
+      i: t.i + u.inputTokens,
+      o: t.o + u.outputTokens,
+      cr: t.cr + u.cacheReadTokens,
+      cw: t.cw + u.cacheWriteTokens,
+      c: t.c + u.costUsd,
+      f: t.f || u.unpriced,
+    }),
+    { turns: 0, i: 0, o: 0, cr: 0, cw: 0, c: 0, f: false }
+  );
+  const total = `| **Total** | | ${n(sum.turns)} | ${n(sum.i)} | ${n(sum.o)} | ${n(sum.cr)} | ${n(sum.cw)} | ${usd(sum.c, sum.f)} |`;
+  return `## Usage\n\n${[...head, ...rows, total].join("\n")}\n\nCosts are estimates at list prices.`;
+}
+
+function outcome(d: LogData): string {
+  return `## Outcome\n\n${
+    d.outcome
+      ? fence(clean(d.outcome))
+      : "The task agent left no final message (a terminal task keeps none)."
+  }`;
+}
+
+function links(d: LogData): string {
+  const items = [
+    d.prUrl ? `- Pull request: ${url(d.prUrl)}` : null,
+    `- Session in AgentOS: ${codeSpan(d.sessionPath)}`,
+  ].filter(Boolean);
+  return `## Links\n\n${items.join("\n")}`;
+}
+
+export function buildLogMarkdown(d: LogData): string {
+  return (
+    [
+      `# Session log: ${plain(d.name)}`,
+      header(d),
+      brief(d),
+      plan(d),
+      timeline(d),
+      usage(d),
+      outcome(d),
+      links(d),
+    ].join("\n\n") + "\n"
+  );
+}

package/lib/session-logs/folder.ts

@@ -0,0 +1,142 @@
+/**
+ * Where a log's markdown file goes, first match wins: the project's own
+ * folder, then the workspace's HQ repo (<hq>/docs/sessions/<project>/), then
+ * ~/.agent-os/session-logs/<workspace>/<project>/. All as
+ * YYYY-MM-DD-<task>.md. Never inside the project's repository: repositories
+ * can be public, and a log holds briefs and reviews.
+ */
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { db } from "../db";
+import { slugify } from "../git";
+import { getProject } from "../projects";
+import { usableHq, type Visibility } from "./hq";
+import { expand, repoPaths, resolved, within } from "./paths";
+
+// AGENTOS_SESSION_LOGS_DIR moves the default (tests keep it off the real one).
+export const DEFAULT_ROOT = () =>
+  process.env.AGENTOS_SESSION_LOGS_DIR ||
+  path.join(os.homedir(), ".agent-os", "session-logs");
+
+const key = (projectId: string) => `session-logs.folder.${projectId}`;
+
+// Throws a plain message when `dir` is inside one of the project's repos.
+export function assertOutsideRepos(projectId: string, dir: string): void {
+  const target = resolved(dir);
+  const repo = repoPaths(projectId).find((r) => within(target, r));
+  if (repo)
+    throw new Error(
+      `${dir} is inside the project's repository (${repo}). Repositories can be public, so logs are never written into one: choose a folder outside it.`
+    );
+}
+
+export function logFolder(projectId: string): string | null {
+  const row = db
+    .prepare(`SELECT value FROM settings WHERE key = ?`)
+    .get(key(projectId)) as { value: string } | undefined;
+  return row?.value || null;
+}
+
+// Throws on a value that isn't an absolute or ~ path, or that points into
+// the project's repository. An empty value goes back to the default.
+export function setLogFolder(projectId: string, value: string | null): void {
+  const folder = value?.trim() ?? "";
+  if (!folder) {
+    db.prepare(`DELETE FROM settings WHERE key = ?`).run(key(projectId));
+    return;
+  }
+  if (!getProject(projectId)) throw new Error("Project not found");
+  if (!(folder === "~" || folder.startsWith("~/") || path.isAbsolute(folder)))
+    throw new Error(
+      `"${folder}" isn't an absolute path. Use a full path or one starting with ~/.`
+    );
+  assertOutsideRepos(projectId, expand(folder));
+  db.prepare(
+    `INSERT INTO settings (key, value) VALUES (?, ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value`
+  ).run(key(projectId), folder);
+}
+
+export interface FileTarget {
+  workspace: string | null;
+  workspaceId?: string | null;
+  project: string | null;
+  projectId: string | null;
+  name: string;
+  id: string;
+  // YYYY-MM-DD
+  day: string;
+}
+
+export interface Destination {
+  dir: string;
+  // The HQ repo the folder belongs to, when the log goes into one.
+  hq: { dir: string; visibility: Visibility } | null;
+}
+
+// The folder this task's log goes into: the project's override when it
+// still passes the repository check, else the workspace's HQ, else the
+// default.
+export function destination(t: FileTarget): Destination {
+  const projectSlug = slugify(t.project ?? "") || "no-project";
+  const custom = t.projectId ? logFolder(t.projectId) : null;
+  if (custom && t.projectId) {
+    try {
+      const dir = expand(custom);
+      assertOutsideRepos(t.projectId, dir);
+      return { dir, hq: null };
+    } catch (error) {
+      console.error(
+        `[session-logs] ignoring the project's log folder: ${error instanceof Error ? error.message : error}`
+      );
+    }
+  }
+  const workspaceId =
+    t.workspaceId ??
+    (t.projectId ? getProject(t.projectId)?.workspace_id : null) ??
+    null;
+  const hq = workspaceId ? usableHq(workspaceId) : null;
+  if (hq)
+    return { dir: path.join(hq.dir, "docs", "sessions", projectSlug), hq };
+  return {
+    dir: path.join(
+      DEFAULT_ROOT(),
+      slugify(t.workspace ?? "") || "no-workspace",
+      projectSlug
+    ),
+    hq: null,
+  };
+}
+
+export const targetDir = (t: FileTarget): string => destination(t).dir;
+
+// Writes the log once and returns its path. A file that's already there
+// (another task, same name, same day) is never overwritten.
+export function writeLogFileTo(
+  t: FileTarget,
+  markdown: string
+): { file: string; hq: Destination["hq"] } {
+  const { dir, hq } = destination(t);
+  if (t.projectId && !logFolder(t.projectId) && !hq)
+    assertOutsideRepos(t.projectId, dir);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const slug = slugify(t.name) || t.id.slice(0, 8);
+  for (const file of [
+    `${t.day}-${slug}.md`,
+    `${t.day}-${slug}-${t.id.slice(0, 8)}.md`,
+  ]) {
+    const full = path.join(dir, file);
+    try {
+      fs.writeFileSync(full, markdown, { flag: "wx", mode: 0o600 });
+      return { file: full, hq };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+  }
+  throw new Error(`a log file for ${t.name} already exists in ${dir}`);
+}
+
+export const writeLogFile = (t: FileTarget, markdown: string): string =>
+  writeLogFileTo(t, markdown).file;

package/lib/session-logs/gather.ts

@@ -0,0 +1,301 @@
+/**
+ * Everything a merged task's log says, read from what AgentOS already
+ * stores: the session row, the brief and its amendments, the independent
+ * review and CI records, the asks raised about it, the usage ledger and the
+ * task agent's last message. Nothing here is computed again or sent to a
+ * model.
+ */
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { db, type Session } from "../db";
+import { itemsOfKind } from "../chat/store";
+import { effectiveModels } from "../models/config";
+import { ANTHROPIC } from "../models/roles";
+import { getProject } from "../projects";
+import { getWorkspace } from "../workspaces";
+import { amendmentsOf } from "../orchestrator/amendments";
+import { PLAN_FILE } from "../models/plan-step";
+import { estimateCost, rowModel } from "../usage/cost";
+import { sessionLink } from "../session-url";
+import type { LogData, LogEvent, LogUsageRow } from "./build";
+
+const expandHome = (p: string) => p.replace(/^~/, os.homedir());
+
+// The task's plan file, read while its worktree still exists. null: none.
+const MAX_PLAN_BYTES = 256 * 1024;
+export function readPlanFile(worktreePath: string | null): string | null {
+  if (!worktreePath) return null;
+  try {
+    const file = path.join(expandHome(worktreePath), PLAN_FILE);
+    const stat = fs.statSync(file);
+    if (!stat.isFile() || stat.size > MAX_PLAN_BYTES) return null;
+    const text = fs.readFileSync(file, "utf8");
+    return text.trim() ? text : null;
+  } catch {
+    return null;
+  }
+}
+
+interface CheckRow {
+  sha: string;
+  kind: string;
+  status: string;
+  detail: string | null;
+  created_at: string;
+}
+
+const REVIEW_WORD: Record<string, string> = {
+  pass: "Review passed",
+  block: "Review blocked the merge",
+  error: "Review could not run",
+  running: "Review started",
+};
+const SCOPE_WORD: Record<string, string> = {
+  pass: "Scope check passed",
+  block: "Scope check blocked the merge",
+  error: "Scope check could not run",
+  running: "Scope check started",
+};
+
+function checkEvents(id: string, merged: string | null): LogEvent[] {
+  const rows = db
+    .prepare(
+      `SELECT sha, kind, status, detail, created_at FROM orchestrator_checks
+       WHERE session_id = ? ORDER BY created_at, id`
+    )
+    .all(id) as CheckRow[];
+  return rows.flatMap((c): LogEvent[] => {
+    if (c.kind === "ci")
+      // The settle record exists for every head that had checks; only the
+      // head that merged is known to have been green.
+      return c.sha === merged
+        ? [{ at: c.created_at, text: "CI green", sha: c.sha }]
+        : [];
+    const word = (c.kind === "review" ? REVIEW_WORD : SCOPE_WORD)[c.status];
+    if (!word) return [];
+    return [
+      {
+        at: c.created_at,
+        text: word,
+        sha: c.sha,
+        detail: c.status === "running" ? null : c.detail,
+      },
+    ];
+  });
+}
+
+const GATE_WORD: Record<string, string> = {
+  ci: "CI failed",
+  review: "Review gate failed",
+  "code-review": "Code-review gate failed",
+  scope: "Scope gate failed",
+  blocked: "Blocked gate failed",
+  stack: "Stack gate failed",
+};
+
+// The failure text names its failing check inside an untrusted fence;
+// the fence tags carry no information here.
+const unfence = (s: string) => s.replace(/<\/?untrusted[^>]*>/g, "");
+
+function failureEvents(id: string): LogEvent[] {
+  const rows = db
+    .prepare(
+      `SELECT gate, sha, reason, created_at FROM orchestrator_gate_failure_commits
+       WHERE session_id = ? ORDER BY created_at`
+    )
+    .all(id) as {
+    gate: string;
+    sha: string;
+    reason: string | null;
+    created_at: string;
+  }[];
+  return rows.map((r) => {
+    const conflict = /conflict/i.test(r.reason ?? "");
+    const failing =
+      r.gate === "ci" ? /\(([^)]+)\)\s*$/.exec(unfence(r.reason ?? "")) : null;
+    return {
+      at: r.created_at,
+      text: conflict
+        ? "Merge conflict held the gates"
+        : (GATE_WORD[r.gate] ?? `Gate ${r.gate} failed`),
+      sha: r.sha,
+      quote: failing ? `failing check: ${failing[1]}` : null,
+      detail: failing || !r.reason ? null : unfence(r.reason),
+    };
+  });
+}
+
+function askEvents(id: string): LogEvent[] {
+  const rows = db
+    .prepare(
+      `SELECT kind, title, detail, status, answer, created_at, resolved_at, sha
+       FROM orchestrator_asks WHERE subject = ? ORDER BY id`
+    )
+    .all(`task:${id}`) as {
+    kind: string;
+    title: string;
+    detail: string;
+    status: string;
+    answer: string | null;
+    created_at: string;
+    resolved_at: string | null;
+    sha: string | null;
+  }[];
+  return rows.flatMap((a): LogEvent[] => {
+    const raised: LogEvent = {
+      at: a.created_at,
+      text: `Escalated to Saad (${a.kind})`,
+      sha: a.sha,
+      quote: a.title,
+      detail: a.detail || null,
+    };
+    if (!a.resolved_at) return [raised];
+    return [
+      raised,
+      {
+        at: a.resolved_at,
+        text: `Saad ${a.status === "approved" ? "approved" : a.status === "declined" ? "declined" : "answered"}`,
+        sha: a.sha,
+        quote: a.title,
+        detail: a.answer,
+      },
+    ];
+  });
+}
+
+function rebaseEvents(s: Session): LogEvent[] {
+  if (!s.rebased_from || !s.rebased_to) return [];
+  return [
+    {
+      at: null,
+      text: `Last automatic rebase moved the branch from ${s.rebased_from.slice(0, 7)} to ${s.rebased_to.slice(0, 7)}`,
+    },
+  ];
+}
+
+export function usageRows(id: string): LogUsageRow[] {
+  const calls = db
+    .prepare(
+      `SELECT role, model, provider, COUNT(*) AS turns,
+         SUM(input_tokens) AS input_tokens,
+         SUM(output_tokens) AS output_tokens,
+         SUM(cache_read_tokens) AS cache_read_tokens,
+         SUM(cache_write_5m_tokens + cache_write_1h_tokens) AS cache_write_tokens
+       FROM usage_calls WHERE task_id = ? GROUP BY role, model, provider`
+    )
+    .all(id) as {
+    role: string | null;
+    model: string | null;
+    provider: string | null;
+    turns: number;
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens: number;
+    cache_write_tokens: number;
+  }[];
+  const { prices } = effectiveModels();
+  const label = (role: string | null) =>
+    role?.startsWith("gate-") ? role.slice(5) : (role ?? "unrecorded");
+  const rows = calls.map((c): LogUsageRow => {
+    const priced = {
+      provider: c.provider ?? ANTHROPIC,
+      model: c.model,
+      cost_usd: 0,
+      input_tokens: c.input_tokens,
+      output_tokens: c.output_tokens,
+      cache_read_tokens: c.cache_read_tokens,
+      cache_write_tokens: c.cache_write_tokens,
+    };
+    const cost = estimateCost(priced, prices);
+    const m = rowModel(priced);
+    return {
+      role: label(c.role),
+      model: `${m.provider}/${m.model}`,
+      turns: c.turns,
+      inputTokens: c.input_tokens,
+      outputTokens: c.output_tokens,
+      cacheReadTokens: c.cache_read_tokens,
+      cacheWriteTokens: c.cache_write_tokens,
+      costUsd: cost.usd,
+      unpriced: !cost.priced,
+    };
+  });
+  const order = ["plan", "implement", "review", "scope"];
+  const rank = (r: string) =>
+    order.indexOf(r) === -1 ? order.length : order.indexOf(r);
+  return rows.sort(
+    (a, b) => rank(a.role) - rank(b.role) || b.costUsd - a.costUsd
+  );
+}
+
+// The last thing the task's agent said, verbatim. A terminal task keeps no
+// conversation, so it has none.
+export function finalMessage(id: string): string | null {
+  const said = itemsOfKind(id, "assistant").filter((i) => i.text.trim());
+  return said.at(-1)?.text ?? null;
+}
+
+export interface GatherOpts {
+  // The plan file's text when it was read before the worktree went; undefined
+  // when nobody could (the backfill), which a log says.
+  plan?: string | null;
+  planKept?: boolean;
+  // The PR's head when it merged, and the commit the merge made.
+  head?: string | null;
+  mergeCommit?: string | null;
+}
+
+export function gatherLogData(s: Session, opts: GatherOpts = {}): LogData {
+  const project = s.project_id ? getProject(s.project_id) : undefined;
+  const workspaceId = s.workspace_id ?? project?.workspace_id ?? null;
+  const workspace = workspaceId ? getWorkspace(workspaceId) : null;
+  const amendments = amendmentsOf(s.id);
+  const mergedAt = s.merged_at ?? null;
+  const head = opts.head ?? null;
+  const events: LogEvent[] = [
+    ...(s.pr_number
+      ? [{ at: null, text: `PR #${s.pr_number} opened` } as LogEvent]
+      : []),
+    ...failureEvents(s.id),
+    ...checkEvents(s.id, head),
+    ...askEvents(s.id),
+  ];
+  // Dated events in time order (a stable sort keeps same-second ones as
+  // recorded); the undated ones bracket them: the PR opening first, the
+  // rebase before the merge.
+  const dated = events
+    .filter((e) => e.at)
+    .sort((a, b) => (a.at as string).localeCompare(b.at as string));
+  const opened = events.filter((e) => !e.at);
+  const timeline = [
+    ...opened,
+    ...dated,
+    ...rebaseEvents(s),
+    {
+      at: mergedAt,
+      text: `PR${s.pr_number ? ` #${s.pr_number}` : ""} merged`,
+    },
+  ];
+  return {
+    id: s.id,
+    name: s.name,
+    workspace: workspace?.name ?? null,
+    project: project?.name ?? null,
+    branch: s.branch_name,
+    prNumber: s.pr_number,
+    prUrl: s.pr_url,
+    mergeCommit: opts.mergeCommit ?? null,
+    startedAt: s.created_at,
+    mergedAt,
+    prompt: s.task_prompt ?? "",
+    scopeChanges: amendments.map((a) => ({ at: a.created_at, text: a.text })),
+    plan: opts.plan ?? null,
+    planKept: opts.planKept ?? true,
+    timeline,
+    usage: usageRows(s.id),
+    outcome: finalMessage(s.id),
+    sessionPath: sessionLink("", s.id),
+  };
+}