@a-t-h-i/bot-lobby 0.6.3 → 0.6.4

package/src/schemas/task.ts

@@ -114,6 +114,21 @@ export interface TaskTriage {
   at: string;
 }
 
+/** What the working tree held when a task's agents started editing: its changed files, repository-relative, and the commit it stood on. */
+export interface ChangeBaseline {
+  at: string;
+  files: string[];
+  /** HEAD when the first worker started: the QA gate reviews everything since, committed work included. */
+  head?: string;
+}
+
+/** The user accepted a task's work without a QA pass. */
+export interface QaWaiver {
+  at: string;
+  /** What QA still asked for when the user accepted. */
+  open: string[];
+}
+
 export interface Task {
   id: string;
   title: string;
@@ -145,6 +160,12 @@ export interface Task {
   archivedAt?: string;
   /** The classifier's read of the request, when it was on as the task started. */
   triage?: TaskTriage;
+  /** Files already changed when the first worker started: the QA gate reads them as pre-existing, not as this task's work. */
+  baseline?: ChangeBaseline;
+  /** Review rounds the user granted past `workflow.maxReviewIterations`. */
+  extraReviewRounds?: number;
+  /** Set only by the user: the work is accepted without a QA pass, so the task may complete. */
+  qaWaiver?: QaWaiver;
 }
 
 export function createTask(

package/src/state/budget.ts

@@ -0,0 +1,274 @@
+/**
+ * A task's time budget: the minutes the user set (and granted since), the
+ * work time spent, and the time each delegation was given. Work time counts
+ * while the oracle works on the task — its own turns, which include every
+ * agent it runs — and not while it waits on the user (between turns, and
+ * while a dialog is open). It lives beside the task's state as budget.json,
+ * written by the session that owns the task; every write reads the file
+ * afresh, so the clock and the engine never overwrite each other.
+ */
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { taskDirFor } from "./persistence.ts";
+import { readJsonCached } from "./file-cache.ts";
+
+/** What one delegation was given. */
+export interface Allotment {
+  /** The delegation: a worker run, the scouts, the researcher, the QA gate. */
+  id: string;
+  who: string;
+  what: string;
+  /** Minutes given, including any granted after it ran out. */
+  minutes: number;
+  granted: number;
+  startedAt: string;
+  endedAt?: string;
+  outcome?: "finished" | "out of time" | "stopped";
+}
+
+export interface TaskBudget {
+  /** Minutes the user set. */
+  minutes: number;
+  /** Minutes the user granted on top since. */
+  granted: number;
+  /** Work time spent, in ms. */
+  usedMs: number;
+  allotments: Allotment[];
+}
+
+export const MAX_ALLOTMENTS = 40;
+/** Least a worker is given; below this the budget counts as spent. */
+export const MIN_ALLOT_MS = 3 * 60_000;
+/** Least a scout batch, the researcher or the QA gate is given. */
+export const MIN_READ_MS = 2 * 60_000;
+/** Kept back for the QA gate until it passes: this share of the budget, at least `QA_RESERVE_MIN_MS`. */
+export const QA_RESERVE_SHARE = 0.15;
+export const QA_RESERVE_MIN_MS = 5 * 60_000;
+/** Time an agent whose time is up has to write its report before it is stopped. */
+export const REPORT_GRACE_MS = 2 * 60_000;
+/** Longest budget accepted, in minutes. */
+export const MAX_BUDGET_MINUTES = 24 * 60;
+
+export function budgetPath(root: string, configDir: string, taskId: string): string {
+  return join(taskDirFor(root, configDir, taskId), "budget.json");
+}
+
+function isBudget(value: unknown): value is TaskBudget {
+  const budget = value as Partial<TaskBudget> | undefined;
+  return Boolean(budget && typeof budget.minutes === "number" && typeof budget.usedMs === "number");
+}
+
+export function readBudget(root: string, configDir: string, taskId: string): TaskBudget | undefined {
+  try {
+    const value: unknown = JSON.parse(readFileSync(budgetPath(root, configDir, taskId), "utf8"));
+    if (!isBudget(value)) return undefined;
+    return { minutes: value.minutes, granted: value.granted ?? 0, usedMs: value.usedMs, allotments: Array.isArray(value.allotments) ? value.allotments : [] };
+  } catch {
+    return undefined;
+  }
+}
+
+function writeBudget(root: string, configDir: string, taskId: string, budget: TaskBudget): void {
+  const path = budgetPath(root, configDir, taskId);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify({ ...budget, allotments: budget.allotments.slice(-MAX_ALLOTMENTS) }, null, 2)}\n`, "utf8");
+}
+
+/** A task's budget as a display reads it every frame: parsed again only when the file changes. */
+export function peekBudget(root: string, configDir: string, taskId: string): TaskBudget | undefined {
+  const value = readJsonCached(budgetPath(root, configDir, taskId), isBudget);
+  return value ? { minutes: value.minutes, granted: value.granted ?? 0, usedMs: value.usedMs, allotments: Array.isArray(value.allotments) ? value.allotments : [] } : undefined;
+}
+
+/** Work time spent of the whole, for the lobby's status box; undefined without a budget. */
+export function budgetClock(root: string, configDir: string, taskId: string, now = Date.now()): { usedMs: number; totalMs: number } | undefined {
+  const budget = peekBudget(root, configDir, taskId);
+  return budget ? { usedMs: usedMs(taskId, budget, now), totalMs: (budget.minutes + budget.granted) * 60_000 } : undefined;
+}
+
+/** Change a task's budget in place (read afresh, written back); undefined when it has none. */
+export function updateBudget(root: string, configDir: string, taskId: string, change: (budget: TaskBudget) => void): TaskBudget | undefined {
+  const budget = readBudget(root, configDir, taskId);
+  if (!budget) return undefined;
+  change(budget);
+  try {
+    writeBudget(root, configDir, taskId, budget);
+  } catch {
+    // A read-only tree must never fail a workflow step; the clock just stops being saved.
+  }
+  return budget;
+}
+
+/** Set (or, with 0, remove) a task's budget; time already spent is kept when it changes. */
+export function setBudget(root: string, configDir: string, taskId: string, minutes: number): TaskBudget | undefined {
+  if (minutes <= 0) {
+    rmSync(budgetPath(root, configDir, taskId), { force: true });
+    return undefined;
+  }
+  const current = readBudget(root, configDir, taskId);
+  const budget: TaskBudget = current ? { ...current, minutes, granted: 0 } : { minutes, granted: 0, usedMs: 0, allotments: [] };
+  writeBudget(root, configDir, taskId, budget);
+  return budget;
+}
+
+/** Minutes from `90`, `90m`, `90 min`, `1h`, `1.5h`, `1h30`, `1h30m` or `2 hours`; undefined for anything else. */
+export function parseMinutes(text: string): number | undefined {
+  const match = /^\s*(?:(\d+(?:\.\d+)?)\s*(?:h|hr|hrs|hours?))?\s*(?:(\d+(?:\.\d+)?)\s*(?:m|min|mins|minutes?)?)?\s*$/i.exec(text);
+  if (!match || (!match[1] && !match[2])) return undefined;
+  const minutes = Math.round(Number(match[1] ?? 0) * 60 + Number(match[2] ?? 0));
+  return minutes > 0 && minutes <= MAX_BUDGET_MINUTES ? minutes : undefined;
+}
+
+/** `34m`, `1h 05m`. */
+export function formatMinutes(ms: number): string {
+  const minutes = Math.max(0, Math.round(ms / 60_000));
+  if (minutes < 60) return `${minutes}m`;
+  return `${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, "0")}m`;
+}
+
+/* ------------------------------------------------------------ work clock */
+
+interface Clock {
+  root: string;
+  configDir: string;
+  /** The oracle's turn on the task is running. */
+  running: boolean;
+  /** Dialogs open: the user is being asked, so the clock waits. */
+  waits: number;
+  /** Since when the current stretch counts, while it does. */
+  since?: number;
+}
+
+/** Work clocks of the tasks this process drives. */
+const clocks = new Map<string, Clock>();
+/** How often a counting clock is saved, so other windows see time pass. */
+export const CLOCK_FLUSH_MS = 30_000;
+let flusher: ReturnType<typeof setInterval> | undefined;
+
+/** Fold the stretch that counted into the saved total, and start a new one if it still counts. */
+function settle(taskId: string, clock: Clock, now = Date.now()): void {
+  if (clock.since !== undefined) {
+    const spent = Math.max(0, now - clock.since);
+    clock.since = undefined;
+    if (spent > 0) updateBudget(clock.root, clock.configDir, taskId, (budget) => { budget.usedMs += spent; });
+  }
+  if (clock.running && clock.waits === 0) clock.since = now;
+}
+
+function ensureFlusher(): void {
+  if (flusher) return;
+  flusher = setInterval(() => {
+    for (const [taskId, clock] of clocks) if (clock.since !== undefined) settle(taskId, clock);
+  }, CLOCK_FLUSH_MS);
+  flusher.unref();
+}
+
+/** The oracle started a turn on a task: its clock runs, if the task has a budget. */
+export function startClock(root: string, configDir: string, taskId: string): void {
+  if (!readBudget(root, configDir, taskId)) return;
+  const clock = clocks.get(taskId) ?? { root, configDir, running: false, waits: 0 };
+  clocks.set(taskId, clock);
+  clock.running = true;
+  settle(taskId, clock);
+  ensureFlusher();
+}
+
+/** The oracle's turn ended: the clock stops until the next one. */
+export function stopClocks(): void {
+  for (const [taskId, clock] of clocks) {
+    clock.running = false;
+    settle(taskId, clock);
+  }
+}
+
+/** The user is being asked: every clock waits (nested dialogs each call this and `resumeClocks`). */
+export function pauseClocks(): void {
+  for (const [taskId, clock] of clocks) {
+    clock.waits += 1;
+    settle(taskId, clock);
+  }
+}
+
+export function resumeClocks(): void {
+  for (const [taskId, clock] of clocks) {
+    clock.waits = Math.max(0, clock.waits - 1);
+    settle(taskId, clock);
+  }
+}
+
+/** Run `ask` (a dialog) with every clock stopped: time spent waiting on the user is not the task's. */
+export async function whileAsking<T>(ask: () => Promise<T>): Promise<T> {
+  pauseClocks();
+  try {
+    return await ask();
+  } finally {
+    resumeClocks();
+  }
+}
+
+/** Work time spent on a task so far, the running stretch included. */
+export function usedMs(taskId: string, budget: TaskBudget, now = Date.now()): number {
+  const since = clocks.get(taskId)?.since;
+  return budget.usedMs + (since !== undefined ? Math.max(0, now - since) : 0);
+}
+
+/** Forget the clocks (tests; a session that ends). */
+export function resetClocks(): void {
+  clocks.clear();
+  if (flusher) clearInterval(flusher);
+  flusher = undefined;
+}
+
+/* -------------------------------------------------------------- dividing */
+
+/** Where a budget stands: all of it, spent, left, what is kept for the QA gate, and what the rest may use. */
+export interface BudgetState {
+  totalMs: number;
+  usedMs: number;
+  leftMs: number;
+  reserveMs: number;
+  /** Left once the QA gate's reserve is kept back. */
+  windowMs: number;
+}
+
+export function budgetState(taskId: string, budget: TaskBudget, qaPassed: boolean, now = Date.now()): BudgetState {
+  const totalMs = (budget.minutes + budget.granted) * 60_000;
+  const used = usedMs(taskId, budget, now);
+  const leftMs = Math.max(0, totalMs - used);
+  const reserveMs = qaPassed ? 0 : Math.min(leftMs, Math.max(QA_RESERVE_MIN_MS, totalMs * QA_RESERVE_SHARE));
+  return { totalMs, usedMs: used, leftMs, reserveMs, windowMs: Math.max(0, leftMs - reserveMs) };
+}
+
+/**
+ * What a worker delegation is given: the minutes the oracle asked for (it
+ * divides by scope), or an even share of what is left before the QA gate's
+ * reserve across the plan's domains still to build; never more than that
+ * window. Undefined when the window is too small for any real work.
+ */
+export function workerAllotment(state: BudgetState, askedMinutes: number | undefined, openSlots: number): { ms: number; note?: string } | undefined {
+  if (state.windowMs < MIN_ALLOT_MS) return undefined;
+  const asked = askedMinutes && askedMinutes > 0 ? askedMinutes * 60_000 : undefined;
+  const wanted = asked ?? state.windowMs / Math.max(1, openSlots);
+  const ms = Math.round(Math.min(state.windowMs, Math.max(MIN_ALLOT_MS, wanted)));
+  const note = asked && asked > state.windowMs ? `asked for ${formatMinutes(asked)}, but only ${formatMinutes(state.windowMs)} are left before the QA gate's reserve` : undefined;
+  return { ms, ...(note ? { note } : {}) };
+}
+
+/** What a read-only batch (scouts, the researcher) is given: a share of what is left, within its configured limit. */
+export function readerAllotment(state: BudgetState, share: number, limitMs: number): number | undefined {
+  if (state.leftMs < MIN_READ_MS) return undefined;
+  return Math.round(Math.min(limitMs, state.leftMs, Math.max(MIN_READ_MS, state.leftMs * share)));
+}
+
+/** What the QA gate is given: its reserve at least, its configured limit if more is left, never more than is left. */
+export function qaAllotment(state: BudgetState, limitMs: number): number | undefined {
+  if (state.leftMs < MIN_READ_MS) return undefined;
+  return Math.round(Math.min(state.leftMs, Math.max(state.reserveMs, limitMs)));
+}
+
+/** The line the oracle and `status` read: `Time budget: 90m (+15m granted) · 34m used · 71m left (14m kept for the QA gate).` */
+export function budgetLine(budget: TaskBudget, state: BudgetState): string {
+  const granted = budget.granted > 0 ? ` (+${budget.granted}m granted)` : "";
+  const reserve = state.reserveMs > 0 ? ` (${formatMinutes(state.reserveMs)} kept for the QA gate)` : "";
+  return `Time budget: ${budget.minutes}m${granted} · ${formatMinutes(state.usedMs)} used · ${formatMinutes(state.leftMs)} left${reserve}.`;
+}

package/src/state/changes.ts

@@ -0,0 +1,231 @@
+/**
+ * Who changed what: a project-wide ledger of the files each quick fix and each
+ * task worker edited, read from their own `edit`/`write` tool calls (never
+ * from their reports). The QA gate and the Master see every changed file of
+ * the working tree against it, so a quick fix the user asked for, a planned
+ * step, work that was there before the task and an edit no agent made each
+ * read as what they are, instead of all looking like unplanned changes.
+ * Append-only JSON lines beside the metrics; best-effort like them.
+ */
+import { appendFileSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import type { Domain } from "../schemas/agent.ts";
+import type { ChangeBaseline, Task } from "../schemas/task.ts";
+import { dataRoot } from "./project.ts";
+
+export type ChangeSource = "quickfix" | "worker";
+
+export interface ChangeRecord {
+  source: ChangeSource;
+  /** The quick fix (`QF-3`) or the worker run that made the edits. */
+  id: string;
+  /** The task a worker ran for. */
+  taskId?: string;
+  domain?: Domain;
+  /** What it was asked to do, one line. */
+  what: string;
+  /** Absolute paths it edited with `edit`/`write`. */
+  files: string[];
+  startedAt: string;
+  finishedAt: string;
+  status: string;
+}
+
+/** Past this size the ledger keeps only its newer half; records older than any open task are not needed. */
+export const MAX_LEDGER_BYTES = 512 * 1024;
+
+const EDIT_TOOLS = new Set(["edit", "write"]);
+
+export function ledgerPath(root: string, configDir: string): string {
+  return join(dataRoot(root, configDir), "changes.jsonl");
+}
+
+/** The absolute path an `edit`/`write` call changes, or undefined for any other call. */
+export function editedFile(toolName: string, args: unknown, cwd: string): string | undefined {
+  if (!EDIT_TOOLS.has(toolName.trim().toLowerCase()) || !args || typeof args !== "object") return undefined;
+  const fields = args as Record<string, unknown>;
+  const raw = [fields.path, fields.file_path, fields.file].find((value): value is string => typeof value === "string" && value.trim().length > 0);
+  if (!raw) return undefined;
+  // pi's file tools accept `@path` as well as `path`.
+  const path = raw.trim().replace(/^@/, "");
+  return isAbsolute(path) ? resolve(path) : resolve(cwd, path);
+}
+
+/** Collects the files one run edits, in the order it first touched them. */
+export class EditLog {
+  private readonly files = new Set<string>();
+  private readonly cwd: string;
+
+  constructor(cwd: string) {
+    // git names the repository by its real path (macOS: /private/var, not /var), so edits are recorded against it too.
+    let real = cwd;
+    try {
+      real = realpathSync(cwd);
+    } catch {
+      // A folder that cannot be resolved is recorded as given.
+    }
+    this.cwd = real;
+  }
+
+  /** Note a tool call; true when it edited a file not seen before. */
+  note(toolName: string, args: unknown): boolean {
+    const file = editedFile(toolName, args, this.cwd);
+    if (!file || this.files.has(file)) return false;
+    this.files.add(file);
+    return true;
+  }
+
+  list(): string[] {
+    return [...this.files];
+  }
+
+  /** The files as a person reads them: relative to the folder the run worked in, when they are inside it. */
+  shown(): string[] {
+    return this.list().map((file) => {
+      const path = relative(this.cwd, file);
+      return path && !path.startsWith("..") && !isAbsolute(path) ? path : file;
+    });
+  }
+}
+
+export function appendChange(root: string, configDir: string, record: ChangeRecord): void {
+  if (record.files.length === 0) return;
+  const path = ledgerPath(root, configDir);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${JSON.stringify(record)}\n`, "utf8");
+    if (statSync(path).size > MAX_LEDGER_BYTES) {
+      const lines = readFileSync(path, "utf8").split("\n").filter((line) => line.trim());
+      writeFileSync(path, `${lines.slice(Math.floor(lines.length / 2)).join("\n")}\n`, "utf8");
+    }
+  } catch {
+    // Provenance is best-effort; a read-only tree must never fail a run.
+  }
+}
+
+function isRecord(value: unknown): value is ChangeRecord {
+  if (!value || typeof value !== "object") return false;
+  const record = value as Partial<ChangeRecord>;
+  return (record.source === "quickfix" || record.source === "worker") && typeof record.id === "string" && Array.isArray(record.files) && typeof record.finishedAt === "string";
+}
+
+/** Every record in the ledger finished at or after `since` (ISO), oldest first. */
+export function readChanges(root: string, configDir: string, since?: string): ChangeRecord[] {
+  let text: string;
+  try {
+    text = readFileSync(ledgerPath(root, configDir), "utf8");
+  } catch {
+    return [];
+  }
+  const from = since ? Date.parse(since) : Number.NEGATIVE_INFINITY;
+  const records: ChangeRecord[] = [];
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const record: unknown = JSON.parse(line);
+      if (isRecord(record) && Date.parse(record.finishedAt) >= from) records.push(record);
+    } catch {
+      // A torn line (a crash mid-append) is skipped.
+    }
+  }
+  return records;
+}
+
+export type Provenance = "planned" | "quickfix" | "other-task" | "pre-existing" | "unattributed";
+
+export interface FileProvenance {
+  /** Repository-relative, as git reports it. */
+  path: string;
+  /** Every source that explains the change; `unattributed` alone when none does. */
+  kinds: Provenance[];
+  /** One clause per source: `planned: DEV — Add the login endpoint`. */
+  notes: string[];
+  /** The quick fixes that edited it. */
+  quickFixes: string[];
+}
+
+const DOMAIN_LABELS: Record<string, string> = { backend: "DEV", designer: "DESIGN", qa: "QA" };
+
+function clip(text: string, max = 90): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+function clock(iso: string): string {
+  const date = new Date(iso);
+  return Number.isNaN(date.getTime()) ? "" : ` at ${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
+}
+
+/**
+ * Explain each changed file of the working tree (`changed`, relative to the
+ * repository at `top`) for `task`: edits by its own workers are planned; by a
+ * quick fix, the user's direct request; by another task's workers, that
+ * task's; changed before its agents started, pre-existing; anything else, no
+ * agent recorded it. `records` should reach back to the task's start.
+ */
+export function explainChanges(task: Pick<Task, "id" | "baseline">, changed: readonly string[], top: string, records: readonly ChangeRecord[]): FileProvenance[] {
+  const byFile = new Map<string, ChangeRecord[]>();
+  for (const record of records) {
+    for (const file of record.files) {
+      // git names files with forward slashes on every platform.
+      const key = relative(top, file).split("\\").join("/");
+      if (key.startsWith("..") || isAbsolute(key)) continue;
+      const list = byFile.get(key) ?? [];
+      list.push(record);
+      byFile.set(key, list);
+    }
+  }
+  const before = new Set(task.baseline?.files ?? []);
+  return changed.map((path) => {
+    const kinds: Provenance[] = [];
+    const notes: string[] = [];
+    const quickFixes: string[] = [];
+    const add = (kind: Provenance, note: string) => {
+      if (!kinds.includes(kind)) kinds.push(kind);
+      if (!notes.includes(note)) notes.push(note);
+    };
+    for (const record of byFile.get(path) ?? []) {
+      if (record.source === "quickfix") {
+        add("quickfix", `quick fix ${record.id}${clock(record.finishedAt)}, asked by the user: "${clip(record.what)}"`);
+        if (!quickFixes.includes(record.id)) quickFixes.push(record.id);
+      } else if (record.taskId === task.id) add("planned", `planned: ${DOMAIN_LABELS[record.domain ?? ""] ?? record.domain ?? "worker"} — ${clip(record.what)}`);
+      else add("other-task", `another task's worker (${record.taskId ?? "unknown task"}): ${clip(record.what)}`);
+    }
+    if (before.has(path)) add("pre-existing", "pre-existing: it already had uncommitted changes before this task's agents started");
+    if (kinds.length === 0) add("unattributed", "unattributed: no bot-lobby agent recorded editing it");
+    return { path, kinds, notes, quickFixes };
+  });
+}
+
+/** Most files the reviewer is told about one by one. */
+export const MAX_PROVENANCE_LINES = 60;
+
+/** The provenance as the reviewer reads it: one line per changed file, the unexplained ones first, the rest counted past `max`. */
+export function provenanceLines(files: readonly FileProvenance[], max = MAX_PROVENANCE_LINES): string {
+  const order = (file: FileProvenance) => (file.kinds.includes("unattributed") ? 0 : file.kinds.includes("quickfix") ? 1 : 2);
+  const sorted = [...files].sort((a, b) => order(a) - order(b));
+  const lines = sorted.slice(0, max).map((file) => `- ${file.path} — ${file.notes.join("; ")}`);
+  const rest = sorted.slice(max);
+  if (rest.length > 0) lines.push(`- …and ${rest.length} more: ${provenanceSummary(rest)}`);
+  return lines.join("\n");
+}
+
+/** A one-line count for the Master: `4 planned · 1 quick fix (QF-2) · 1 unattributed (src/x.ts)`. */
+export function provenanceSummary(files: readonly FileProvenance[]): string {
+  const count = (kind: Provenance) => files.filter((file) => file.kinds.includes(kind));
+  const parts: string[] = [];
+  const planned = count("planned").length;
+  if (planned > 0) parts.push(`${planned} planned`);
+  const quick = count("quickfix");
+  if (quick.length > 0) {
+    const ids = [...new Set(quick.flatMap((file) => file.quickFixes))];
+    parts.push(`${quick.length} by quick fix (${ids.join(", ")})`);
+  }
+  const other = count("other-task").length;
+  if (other > 0) parts.push(`${other} by another task`);
+  const before = count("pre-existing").length;
+  if (before > 0) parts.push(`${before} pre-existing`);
+  const unknown = count("unattributed");
+  if (unknown.length > 0) parts.push(`${unknown.length} unattributed (${unknown.slice(0, 5).map((file) => file.path).join(", ")}${unknown.length > 5 ? ", …" : ""})`);
+  return parts.join(" · ");
+}

package/src/text.ts

@@ -5,6 +5,13 @@ export function truncate(text: string, maxChars: number): string {
   return `${text.slice(0, maxChars)}\n[...${text.length - maxChars} characters omitted]`;
 }
 
+/** The end of `text` within a character budget (the newest entries of a log), marking how much was left out before it. */
+export function tail(text: string, maxChars: number): string {
+  if (maxChars <= 0) return "";
+  if (text.length <= maxChars) return text;
+  return `[...${text.length - maxChars} earlier characters omitted]\n${text.slice(text.length - maxChars)}`;
+}
+
 /** Filler and imperative words that carry no topic signal in a request. */
 const FILLER_WORDS = new Set([
   "let's",
@@ -45,9 +52,28 @@ function fillerKey(word: string): string {
  */
 export function shortTitle(request: string, maxWords = 3): string {
   if (maxWords <= 0) return "";
-  const words = request.trim().split(/\s+/).filter(Boolean);
+  const words = titleText(request).split(/\s+/).filter(Boolean);
   const content = words.filter((word) => !FILLER_WORDS.has(fillerKey(word)));
-  return (content.length > 0 ? content : words).slice(0, maxWords).join(" ");
+  return (content.length > 0 ? content : words).slice(0, maxWords).join(" ").replace(/[:;,]+$/, "");
+}
+
+/** Headings that only label a section (`### Objective`), not name the work. */
+const LABEL_HEADING = /^#{1,6}\s*(objective|goal|goals|summary|overview|task|request|context|background|description|plan)\s*:?\s*$/i;
+
+/**
+ * A request as words for a title: escaped line breaks (`\\n` written out by a
+ * model) read as breaks, label headings are skipped, and Markdown marks
+ * (`#`, `-`, `*`, `>`, backticks) are dropped.
+ */
+function titleText(request: string): string {
+  return request
+    .replace(/\\[nrt]/g, "\n")
+    .split("\n")
+    .filter((line) => !LABEL_HEADING.test(line.trim()))
+    .join(" ")
+    .replace(/[#*>`|]+/g, " ")
+    .replace(/(^|\s)[-+](?=\s|$)/g, " ")
+    .trim();
 }
 
 /** Compact duration such as "45s", "3m" or "2m 05s"; a non-finite input reads "0s". */