portable-agent-layer 0.71.0 → 0.73.0

package/src/tools/control-room/ui/theme.css

@@ -0,0 +1,127 @@
+/**
+ * Industry, as Tailwind sees it. Source file — `bun run build:ui` compiles this
+ * to tailwind.css, which is what index.html actually links.
+ */
+
+@layer theme, base, components, utilities;
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/preflight.css" layer(base);
+@import "tailwindcss/utilities.css" layer(utilities) source(none);
+
+@source "./*.tsx";
+@source "./**/*.tsx";
+@source "./index.html";
+
+@theme static {
+  --color-bg: #f2f2f3;
+  --color-surface: #e9e9ea;
+  --color-ink: #1d1f20;
+  --color-divider: color-mix(in srgb, #1d1f20 16%, transparent);
+
+  --color-neutral-100: #f5f5f8;
+  --color-neutral-200: #e7e7ea;
+  --color-neutral-300: #d4d4d7;
+  --color-neutral-400: #b7b7ba;
+  --color-neutral-500: #98989b;
+  --color-neutral-600: #7a7a7d;
+  --color-neutral-700: #5d5d60;
+  --color-neutral-800: #424244;
+  --color-neutral-900: #2b2b2d;
+
+  --color-accent: #5980a6;
+  --color-accent-100: #eef6ff;
+  --color-accent-200: #d6ebff;
+  --color-accent-300: #b5d9fd;
+  --color-accent-400: #94bce3;
+  --color-accent-500: #749dc4;
+  --color-accent-600: #597ea3;
+  --color-accent-700: #416180;
+  --color-accent-800: #2c455d;
+  --color-accent-900: #1d2d3d;
+
+  --color-alarm: oklch(0.55 0.17 27);
+
+  --font-heading: "Barlow Condensed", system-ui, sans-serif;
+  --font-body: "Barlow", system-ui, sans-serif;
+  --font-mono: ui-monospace, Menlo, monospace;
+
+  /* Industry's --space-N is exactly N x 3.4px, which is Tailwind's own scale
+     with a retuned base — so p-4 here is Industry's --space-4 to the pixel. */
+  --spacing: 0.2125rem;
+
+  --radius-sm: 2px;
+  --radius-md: 4px;
+  --radius-lg: 7px;
+
+  --shadow-sm: 0 1px 2px color-mix(in srgb, #2b2b2d 14%, transparent);
+  --shadow-md: 0 3px 10px color-mix(in srgb, #2b2b2d 16%, transparent);
+  --shadow-lg: 0 12px 32px color-mix(in srgb, #2b2b2d 22%, transparent);
+
+  /* Industry draws an 11px crosshair in 55% ink whose centre sits on the
+     border line — .corner is 11px at top/left -6px over a 1px border. */
+  --registration-size: 11px;
+  --registration-inset: -6px;
+  --registration-mark: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='11' height='11'%3E%3Cpath d='M5.5 0v11M0 5.5h11' stroke='%231d1f20' stroke-opacity='.55' stroke-width='1'/%3E%3C/svg%3E");
+}
+
+@layer base {
+  body {
+    background: var(--color-bg);
+    color: var(--color-ink);
+    font-family: var(--font-body);
+    font-size: 13px;
+    line-height: 1.45;
+  }
+
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    font-family: var(--font-heading);
+    font-weight: 600;
+    letter-spacing: 0.02em;
+  }
+
+  :focus-visible {
+    outline: 2px solid var(--color-accent);
+    outline-offset: 2px;
+  }
+
+  ::selection {
+    background: var(--color-accent-200);
+  }
+}
+
+/**
+ * The wireframe frame every card, figure and primary button wears: square
+ * corners, a hairline border and four "+" registration marks drawn outside the
+ * box. Industry ships it as a class plus four <i> children; here the marks are
+ * one pseudo-element, so the markup stays clean.
+ */
+@utility blueprint {
+  position: relative;
+  border: 1px solid var(--color-divider);
+  border-radius: 0;
+
+  &::after {
+    content: "";
+    position: absolute;
+    inset: var(--registration-inset);
+    pointer-events: none;
+    background-image: var(--registration-mark), var(--registration-mark),
+      var(--registration-mark), var(--registration-mark);
+    background-repeat: no-repeat;
+    background-size: var(--registration-size) var(--registration-size);
+    background-position: left top, right top, left bottom, right bottom;
+  }
+}
+
+/** Industry's uppercase eyebrow, used for every panel heading and column label. */
+@utility eyebrow {
+  font-size: 10px;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+  color: var(--color-neutral-700);
+}

package/src/tools/control-room/ui/vite.config.ts

@@ -0,0 +1,36 @@
+/**
+ * The control room's build. Bun serves the page and owns every API route, but
+ * Bun's CSS bundler passes Tailwind's directives through as unknown at-rules —
+ * so the page is built here, by the first-party plugin that moves in lockstep
+ * with Tailwind itself, and Bun serves the result out of dist/.
+ *
+ * `server.proxy` is what makes `bun run dev:ui` usable: the page comes from Vite
+ * with hot reload while every /api call goes to the real control room.
+ */
+
+import tailwindcss from "@tailwindcss/vite";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+/**
+ * Mirrors DEFAULT_PORT in ../server-config.ts. A config the loader reads before
+ * TypeScript resolution cannot import from the source tree, so a test asserts
+ * the two agree.
+ */
+const API_ORIGIN = "http://127.0.0.1:7250";
+
+export default defineConfig({
+  root: import.meta.dirname,
+  base: "/",
+  plugins: [react(), tailwindcss()],
+  build: {
+    outDir: "dist",
+    emptyOutDir: true,
+    sourcemap: false,
+  },
+  server: {
+    proxy: {
+      "/api": API_ORIGIN,
+    },
+  },
+});

package/src/tools/control-room/writes.ts

@@ -0,0 +1,106 @@
+/**
+ * The three things the page may change without an agent.
+ *
+ * Each one is a single named field on a single record, reached through the same
+ * rule the CLI uses — the page is a second hand on the same instrument, not a
+ * write surface over ~/.pal.
+ */
+
+import { readProject, writeProject } from "../../hooks/lib/projects";
+import {
+  raw as rawSettings,
+  reload,
+  write as writeSettings,
+} from "../../hooks/lib/settings";
+import { completeIsc, type IscSections, reopenIsc } from "../lib/project-isc";
+
+export type WriteOutcome =
+  | { ok: true; changed: boolean }
+  | { ok: false; status: number; error: string };
+
+const missing = (project: string): WriteOutcome => ({
+  ok: false,
+  status: 404,
+  error: `no such project: ${project}`,
+});
+
+export function setIscStatus(project: string, id: number, close: boolean): WriteOutcome {
+  const p = readProject(project);
+  if (!p) return missing(project);
+  const sections: IscSections = {
+    criteria: p.criteria ?? "",
+    changelog: p.changelog ?? "",
+  };
+  const move = close ? completeIsc(sections, id) : reopenIsc(sections, id);
+  if (!move.ok) return { ok: false, status: 404, error: move.reason };
+  if (move.already) return { ok: true, changed: false };
+  p.criteria = move.criteria;
+  p.changelog = move.changelog;
+  p.updated = new Date().toISOString();
+  writeProject(p);
+  return { ok: true, changed: true };
+}
+
+export const QUADRANTS = ["now", "plan", "noise", "later"] as const;
+export type Quadrant = (typeof QUADRANTS)[number];
+
+export function isQuadrant(value: unknown): value is Quadrant {
+  return typeof value === "string" && (QUADRANTS as readonly string[]).includes(value);
+}
+
+/**
+ * Importance already has a home in `serves`; urgency is read off the files.
+ * A placement overrules the pair, and says who decided, so the next guess can
+ * run freely without overwriting the answer.
+ */
+export function setPlacement(project: string, quadrant: Quadrant | null): WriteOutcome {
+  const p = readProject(project);
+  if (!p) return missing(project);
+  if (quadrant) {
+    p.placed = quadrant;
+    p.placed_by = "user";
+  } else {
+    p.placed = undefined;
+    p.placed_by = undefined;
+  }
+  p.updated = new Date().toISOString();
+  writeProject(p);
+  return { ok: true, changed: true };
+}
+
+export interface InstallSettings {
+  actor: string;
+  timezone: string;
+}
+
+export function readInstallSettings(): InstallSettings {
+  const identity = rawSettings().identity ?? {};
+  return {
+    actor: identity.principal?.name ?? "",
+    timezone: identity.principal?.timezone ?? "",
+  };
+}
+
+/** Only the two fields the Settings panel offers; everything else is left alone. */
+export function writeInstallSettings(update: Partial<InstallSettings>): WriteOutcome {
+  if (update.timezone && !isTimezone(update.timezone)) {
+    return { ok: false, status: 400, error: `not a timezone: ${update.timezone}` };
+  }
+  const data = rawSettings();
+  const identity = data.identity ?? {};
+  const principal = { ...identity.principal };
+  if (update.actor !== undefined) principal.name = update.actor;
+  if (update.timezone !== undefined) principal.timezone = update.timezone;
+  writeSettings({ ...data, identity: { ...identity, principal } });
+  reload();
+  return { ok: true, changed: true };
+}
+
+function isTimezone(value: string): boolean {
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: value });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/tools/ledger/outcomes.ts

@@ -0,0 +1,9 @@
+/**
+ * The outcomes a page groups by. Kept apart from view.ts because the browser
+ * needs this list and nothing else from that module — importing it there would
+ * drag the actor and machine registries, and node:fs behind them, into the
+ * page bundle.
+ */
+
+export const PAGE_OUTCOMES = ["applied", "failed", "denied", "blocked"] as const;
+export type PageOutcome = (typeof PAGE_OUTCOMES)[number];

package/src/tools/ledger/query.ts

@@ -34,6 +34,7 @@ export interface LedgerFilter {
   actor?: string;
   machine?: string;
   runtime?: string;
+  authority?: string;
   outcome?: string;
   tool?: string;
   target?: string;
@@ -100,6 +101,7 @@ function matchesFilter(entry: LedgerEntry, filter: LedgerFilter): boolean {
   if (filter.actor && entry.actor !== filter.actor) return false;
   if (filter.machine && entry.machine !== filter.machine) return false;
   if (filter.runtime && entry.runtime !== filter.runtime) return false;
+  if (filter.authority && entry.authority !== filter.authority) return false;
   if (filter.outcome && entry.outcome !== filter.outcome) return false;
   if (filter.tool && entry.tool.toLowerCase() !== filter.tool.toLowerCase()) return false;
   if (filter.target && !entry.target.includes(filter.target)) return false;

package/src/tools/ledger/view.ts

@@ -12,10 +12,16 @@ import {
   readActorRegistry,
 } from "../../hooks/lib/actor";
 import type { LedgerEntry } from "../../hooks/lib/ledger";
+import {
+  loadMachine,
+  displayName as machineDisplayName,
+  type RegistryEntry,
+  readRegistry as readMachineRegistry,
+} from "../../hooks/lib/machine";
+import { PAGE_OUTCOMES, type PageOutcome } from "./outcomes";
 import { anchorSlugOf, changedLines, type LedgerFilter, queryLedger } from "./query";
 
-export const PAGE_OUTCOMES = ["applied", "failed", "denied", "blocked"] as const;
-export type PageOutcome = (typeof PAGE_OUTCOMES)[number];
+export { PAGE_OUTCOMES, type PageOutcome };
 
 export interface OutcomeCount {
   total: number;
@@ -32,6 +38,8 @@ export interface LedgerViewStats {
 export interface LedgerViewRow {
   id: string;
   ts: string;
+  /** Where the record was written. Local-only in the record; the page names it. */
+  machine: string;
   actor: string;
   authority: string;
   runtime: string;
@@ -40,6 +48,8 @@ export interface LedgerViewRow {
   change: string;
   outcome: string;
   reason?: string;
+  /** Present only on a blocked shell action, where the target is a directory. */
+  command?: string;
 }
 
 export interface LedgerView {
@@ -87,11 +97,17 @@ export function displayTarget(target: string): string {
   return rest ? `${slug} ${rest}` : slug;
 }
 
-function toRow(entry: LedgerEntry, registry: ActorRegistryEntry[]): LedgerViewRow {
+interface Names {
+  actors: ActorRegistryEntry[];
+  machines: RegistryEntry[];
+}
+
+function toRow(entry: LedgerEntry, { actors, machines }: Names): LedgerViewRow {
   const row: LedgerViewRow = {
     id: entry.id,
     ts: entry.ts,
-    actor: actorDisplayName(entry.actor, registry),
+    machine: machineDisplayName(entry.machine, machines),
+    actor: actorDisplayName(entry.actor, actors),
     authority: entry.authority,
     runtime: entry.runtime,
     tool: entry.tool,
@@ -100,21 +116,29 @@ function toRow(entry: LedgerEntry, registry: ActorRegistryEntry[]): LedgerViewRo
     outcome: entry.outcome,
   };
   if (entry.reason) row.reason = entry.reason;
+  if (entry.command) row.command = entry.command;
   return row;
 }
 
-/** The local actor first: on a fresh install the registry may not list them yet. */
-function knownActors(): ActorRegistryEntry[] {
-  const self = loadActor();
-  return [{ id: self.id, label: self.label }, ...readActorRegistry()];
+/** This install first: on a fresh machine the registries may not list it yet. */
+function knownNames(): Names {
+  const actor = loadActor();
+  const machine = loadMachine();
+  return {
+    actors: [{ id: actor.id, label: actor.label }, ...readActorRegistry()],
+    machines: [
+      { id: machine.id, label: machine.label, os: machine.os },
+      ...readMachineRegistry(),
+    ],
+  };
 }
 
 export function viewRows(entries: LedgerEntry[]): LedgerViewRow[] {
-  const registry = knownActors();
+  const names = knownNames();
   return entries
     .slice()
     .reverse()
-    .map((entry) => toRow(entry, registry));
+    .map((entry) => toRow(entry, names));
 }
 
 export function ledgerView(filter: LedgerFilter = {}): LedgerView {

package/src/tools/lib/algorithm-reflect.ts

@@ -0,0 +1,84 @@
+/**
+ * The shape of an algorithm reflection: what a LEARN phase records, and the
+ * defaults and clamps applied to whatever the CLI was handed.
+ *
+ * The tool around this is only ever spawned, so the stamping, the clamp and the
+ * scope default were reachable only through argv. They take their clock and
+ * their directory as parameters here, which is what makes them assertable.
+ */
+
+import { currentAttribution, type RecordAttribution } from "../../hooks/lib/actor";
+import { encodeAnchor } from "../../hooks/lib/anchor";
+
+const MIN_SENTIMENT = 1;
+const MAX_SENTIMENT = 10;
+const DEFAULT_SENTIMENT = 5;
+
+export interface AlgorithmReflection extends RecordAttribution {
+  timestamp: string;
+  cwd: string;
+  task: string;
+  criteria_count: number;
+  criteria_passed: number;
+  criteria_failed: number;
+  sentiment: number;
+  q1: string;
+  q2: string;
+  q3: string;
+  /** general = the improvement ideas generalize to the algorithm; task-specific = bound to this task. */
+  scope: "general" | "task-specific";
+}
+
+export interface ReflectionInput {
+  task: string;
+  q1: string;
+  q2: string;
+  q3: string;
+  criteria_count?: number;
+  criteria_passed?: number;
+  criteria_failed?: number;
+  sentiment?: number;
+  scope?: string;
+}
+
+/** An absent flag reads as its default; a non-numeric one reads as NaN, not zero. */
+export function intOr(value: string | undefined, fallback: number): number {
+  return Number.parseInt(value || String(fallback), 10);
+}
+
+export function clampSentiment(sentiment: number | undefined): number {
+  return Math.max(MIN_SENTIMENT, Math.min(MAX_SENTIMENT, sentiment ?? DEFAULT_SENTIMENT));
+}
+
+/**
+ * General is the ~94% case, so only an explicit "task-specific" opts out of
+ * algorithm-update's clustering — anything else, including a typo, stays general.
+ */
+export function scopeOf(scope: string | undefined): AlgorithmReflection["scope"] {
+  return scope === "task-specific" ? "task-specific" : "general";
+}
+
+export function buildReflection(
+  input: ReflectionInput,
+  now: Date = new Date(),
+  cwd: string = process.cwd()
+): AlgorithmReflection {
+  return {
+    timestamp: now.toISOString(),
+    cwd: encodeAnchor(cwd),
+    ...currentAttribution(),
+    task: input.task,
+    criteria_count: input.criteria_count ?? 0,
+    criteria_passed: input.criteria_passed ?? 0,
+    criteria_failed: input.criteria_failed ?? 0,
+    sentiment: clampSentiment(input.sentiment),
+    q1: input.q1,
+    q2: input.q2,
+    q3: input.q3,
+    scope: scopeOf(input.scope),
+  };
+}
+
+export function reflectionLine(reflection: AlgorithmReflection): string {
+  return `${JSON.stringify(reflection)}\n`;
+}

package/src/tools/lib/analyze-report.ts

@@ -0,0 +1,120 @@
+/**
+ * The learning-analysis report, as lines rather than as console output.
+ *
+ * The tool around it is spawned, so every judgement in here — which colour a
+ * rating average earns, whether an entry came from a failure or a learning,
+ * what is shown when there is nothing to show — was written straight into
+ * console.log and could not be read back by a test.
+ */
+
+import type { AnalysisResult } from "../../hooks/lib/graduation";
+
+type PatternGroup = AnalysisResult["candidates"][number];
+type AnalysisEntry = PatternGroup["entries"][number];
+type RatingsSummary = NonNullable<AnalysisResult["ratings"]>;
+
+const c = {
+  bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
+  dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
+  cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
+  yellow: (s: string) => `\x1b[33m${s}\x1b[0m`,
+  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
+  red: (s: string) => `\x1b[31m${s}\x1b[0m`,
+  magenta: (s: string) => `\x1b[35m${s}\x1b[0m`,
+};
+
+const RULE = c.dim("─────────────────────────────────────────────────");
+
+/** Green from 7, red at 4 and below, amber for the band between them. */
+function averageColour(average: number) {
+  if (average >= 7) return c.green;
+  return average <= 4 ? c.red : c.yellow;
+}
+
+function ratingsLines(r: RatingsSummary): string[] {
+  const average = averageColour(r.average)(`${r.average.toFixed(1)}/10`);
+  const low = c.red(`Low (≤4): ${r.low.count}`);
+  const high = c.green(`High (≥7): ${r.high.count}`);
+  return [
+    `\n  ${c.bold("Ratings:")} ${average} avg (${r.total} total)`,
+    `  ${low} | ${high}`,
+  ];
+}
+
+/** The source string carries where the entry came from; the tag says which. */
+function entryLine(entry: AnalysisEntry, maxChars: number): string {
+  const kind = entry.source.startsWith("failure:") ? "failure" : "learning";
+  const tag = kind === "failure" ? c.red(`[${kind}]`) : c.yellow(`[${kind}]`);
+  return `    ${c.dim(entry.date || "unknown")} ${tag} ${entry.text.slice(0, maxChars)}`;
+}
+
+function headingOf(group: PatternGroup): string {
+  const domain = c.cyan(`[${group.domain}]`);
+  const count = c.bold(`${group.entries.length}x`);
+  return `  ${domain} ${count}`;
+}
+
+function fileLines(group: PatternGroup): string[] {
+  return group.entries.map((entry) => `    ${c.dim(entry.path)}`);
+}
+
+function candidateLines(candidate: PatternGroup): string[] {
+  const framePath = c.magenta(`memory/wisdom/frames/${candidate.domain}.md`);
+  return [
+    `${headingOf(candidate)} occurrences`,
+    "",
+    ...candidate.entries.map((entry) => entryLine(entry, 100)),
+    `\n  ${c.dim("Files:")}`,
+    ...fileLines(candidate),
+    "",
+    `  Target frame: ${framePath}`,
+    `  ${RULE}\n`,
+  ];
+}
+
+function emergingLines(group: PatternGroup): string[] {
+  return [
+    headingOf(group),
+    ...group.entries.map((entry) => entryLine(entry, 80)),
+    "  Files:",
+    ...fileLines(group),
+    "",
+  ];
+}
+
+export function reportLines(result: AnalysisResult): string[] {
+  const hasPatterns = result.candidates.length > 0 || result.emerging.length > 0;
+  if (!hasPatterns && result.ratings === null) {
+    return ["\n  No patterns or ratings data found.\n"];
+  }
+
+  const lines: string[] = [];
+
+  if (result.ratings) lines.push(...ratingsLines(result.ratings));
+
+  if (result.candidates.length > 0) {
+    const header = `Graduation Report — ${result.candidates.length} pattern(s) detected`;
+    lines.push(`\n  ${c.bold(c.green(header))}\n`, `  ${RULE}\n`);
+    for (const candidate of result.candidates) lines.push(...candidateLines(candidate));
+  }
+
+  if (result.emerging.length > 0) {
+    lines.push(`  ${c.bold(c.yellow("Emerging (2x — one more to graduate)"))}\n`);
+    for (const group of result.emerging) lines.push(...emergingLines(group));
+  }
+
+  if (result.recommendations.length > 0) {
+    lines.push(`  ${c.bold("Recommendations:")}\n`);
+    for (const rec of result.recommendations) lines.push(`    ${rec}`);
+    lines.push("");
+  }
+
+  if (result.candidates.length > 0) {
+    lines.push(
+      "  To crystallize: add a line to the wisdom frame file.",
+      `  Format: ${c.green("- Your principle here [CRYSTAL: 85%]")}\n`
+    );
+  }
+
+  return lines;
+}

package/src/tools/lib/handoff-note.ts

@@ -0,0 +1,102 @@
+/**
+ * The handoff store: what an unfinished session leaves behind for the next one,
+ * keyed by the directory the work happened in.
+ *
+ * The tool around this is only ever spawned, so the shape of an entry and the
+ * trim that keeps the file a working set were reachable only by running the CLI
+ * and reading the file back. Everything here takes the store it operates on and
+ * the clock it stamps with.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ensureDir, paths } from "../../hooks/lib/paths";
+
+export interface HandoffEntry {
+  timestamp: string;
+  title: string;
+  status: "in-progress" | "completed";
+  handoff: string;
+  artifacts: string[];
+  source: "deliberate" | "auto";
+  /** What the work needs from the human before it can move — the one thing an agent cannot unblock. */
+  waitingOn?: string;
+}
+
+export interface NoteInput {
+  cwd: string;
+  title: string;
+  text: string;
+  done: boolean;
+  waitingOn?: string;
+}
+
+export type HandoffStore = Record<string, HandoffEntry>;
+
+/** The file is a working set, not an archive: the oldest keys fall off first. */
+const MAX_ENTRIES = 20;
+
+export function handoffFile(): string {
+  return resolve(ensureDir(paths.state()), "last-handoff.json");
+}
+
+export function parseHandoffs(content: string): HandoffStore {
+  try {
+    return JSON.parse(content) as HandoffStore;
+  } catch {
+    return {};
+  }
+}
+
+export function readHandoffs(file: string = handoffFile()): HandoffStore {
+  if (!existsSync(file)) return {};
+  try {
+    return parseHandoffs(readFileSync(file, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+export function trimHandoffs(handoffs: HandoffStore): HandoffStore {
+  const entries = Object.entries(handoffs);
+  if (entries.length <= MAX_ENTRIES) return handoffs;
+  return Object.fromEntries(entries.slice(-MAX_ENTRIES));
+}
+
+export const statusOf = (note: NoteInput): HandoffEntry["status"] =>
+  note.done ? "completed" : "in-progress";
+
+/** A closed session carries no waiting line, so the key is absent rather than empty. */
+export function entryFor(note: NoteInput, now: Date): HandoffEntry {
+  return {
+    timestamp: now.toISOString(),
+    title: note.title,
+    status: statusOf(note),
+    handoff: note.text,
+    artifacts: [],
+    source: "deliberate",
+    ...(note.waitingOn ? { waitingOn: note.waitingOn } : {}),
+  };
+}
+
+export function recordNote(
+  store: HandoffStore,
+  note: NoteInput,
+  now: Date
+): HandoffStore {
+  return trimHandoffs({ ...store, [note.cwd]: entryFor(note, now) });
+}
+
+/**
+ * Fills in the one field an auto handoff cannot write for itself. Never
+ * overwrites an answer already on the entry, and never invents an entry.
+ */
+export function withWaitingOn(
+  store: HandoffStore,
+  cwd: string,
+  question: string
+): HandoffStore {
+  const entry = store[cwd];
+  if (!entry || entry.waitingOn) return store;
+  return { ...store, [cwd]: { ...entry, waitingOn: question } };
+}