portable-agent-layer 0.71.0 → 0.73.0

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

@@ -14,11 +14,19 @@ import {
 } from "../../hooks/lib/algorithm-review";
 import { loadAnalyzeNudge } from "../../hooks/lib/analyze-nudge";
 import { paths } from "../../hooks/lib/paths";
-import { isStale, type ProjectProgress, readAllProjects } from "../../hooks/lib/projects";
+import {
+  isStale,
+  type ProjectProgress,
+  readAllProjects,
+  type ServesAuthority,
+  type ServesKind,
+} from "../../hooks/lib/projects";
 import { readProjectHistory } from "../../hooks/lib/work-tracking";
-import { type HandoffEntry, readHandoffs } from "../agent/handoff-note";
-import { parseIscs } from "../agent/project";
 import { anchorSlugOf, type LedgerFilter, queryLedger } from "../ledger/query";
+import { viewStats } from "../ledger/view";
+import { type HandoffEntry, readHandoffs } from "../lib/handoff-note";
+import { parseIscs } from "../lib/project-isc";
+import { readSnoozes, snoozedUntil } from "./snooze";
 
 const DAY_MS = 86_400_000;
 const HANDOFF_FRESH_DAYS = 7;
@@ -38,6 +46,19 @@ export interface ProjectCard {
   lastSession: { date: string; title: string } | null;
   sessions30d: number;
   asking: string[];
+  /** What the project is for, and who decided — the fact importance is ranked from. */
+  serves: ServesKind | null;
+  servesBy: ServesAuthority | null;
+  /** Which agents touched it, and how often, over the same 30 days. */
+  runtimes: Record<string, number>;
+}
+
+export interface SummaryView {
+  since: string;
+  days: number;
+  actions: number;
+  refusals: number;
+  rating: number | null;
 }
 
 export interface HandoffCard {
@@ -91,7 +112,7 @@ export interface SignalView {
   };
 }
 
-export interface AgentsRow {
+interface AgentsRow {
   slug: string;
   actions: number;
   runtimes: Record<string, number>;
@@ -142,10 +163,29 @@ export function askingReasons(
   return reasons;
 }
 
+function runtimesBySlug(since: Date): Map<string, Record<string, number>> {
+  const bySlug = Map.groupBy(
+    queryLedger({ since }),
+    (e) => anchorSlugOf(e.target) ?? "unanchored"
+  );
+  return new Map(
+    [...bySlug.entries()].map(([slug, entries]) => [
+      slug,
+      Object.fromEntries(
+        Map.groupBy(entries, (e) => e.runtime)
+          .entries()
+          .map(([runtime, group]) => [runtime, group.length])
+      ),
+    ])
+  );
+}
+
 function toCard(
   p: ProjectProgress,
   handoff: HandoffEntry | undefined,
-  now: Date
+  now: Date,
+  runtimes: Record<string, number>,
+  snoozes: Record<string, string>
 ): ProjectCard {
   const path = p.path ?? null;
   const stale = isStale(p);
@@ -158,7 +198,9 @@ function toCard(
     updated: p.updated,
     ageDays: daysBetween(p.updated, now),
     stale,
-    openIscs: parseIscs(p.criteria ?? "").filter((i) => i.status === "open").length,
+    openIscs: parseIscs(p.criteria ?? "").filter(
+      (i) => i.status === "open" && !snoozedUntil(p.name, i.id, snoozes)
+    ).length,
     next: p.next ?? [],
     blockers: p.blockers ?? [],
     lastSession: last ? { date: last.date, title: last.title } : null,
@@ -167,6 +209,9 @@ function toCard(
       new Date(now.getTime() - SESSION_WINDOW_DAYS * DAY_MS)
     ),
     asking: askingReasons(p, handoff, stale),
+    serves: p.serves ?? null,
+    servesBy: p.serves_by ?? null,
+    runtimes,
   };
 }
 
@@ -178,9 +223,17 @@ export function sortBoard(cards: ProjectCard[]): ProjectCard[] {
 
 export function board(now: Date = new Date()): ProjectCard[] {
   const handoffs = new Map(freshHandoffs(now));
+  const runtimes = runtimesBySlug(new Date(now.getTime() - SESSION_WINDOW_DAYS * DAY_MS));
+  const snoozes = readSnoozes(now);
   return sortBoard(
     readAllProjects().map((p) =>
-      toCard(p, p.path ? handoffs.get(p.path) : undefined, now)
+      toCard(
+        p,
+        p.path ? handoffs.get(p.path) : undefined,
+        now,
+        runtimes.get(p.name) ?? {},
+        snoozes
+      )
     )
   );
 }
@@ -296,6 +349,24 @@ export function signal(now: Date = new Date()): SignalView {
   };
 }
 
+/**
+ * The morning tile: how much happened, how much was refused, and how it was
+ * rated — three numbers over one window, so the page asks once instead of
+ * pulling the whole ledger down to count it in the browser.
+ */
+export function summary(days: number, now: Date = new Date()): SummaryView {
+  const since = new Date(now.getTime() - days * DAY_MS);
+  const stats = viewStats(queryLedger({ since }));
+  const ratings = readSynthesis()?.ratings as SignalView["ratings"] | undefined;
+  return {
+    since: since.toISOString(),
+    days,
+    actions: stats.total,
+    refusals: stats.refusals,
+    rating: ratings?.recentAvg ?? null,
+  };
+}
+
 function count<T>(items: T[], key: (item: T) => string): number {
   return new Set(items.map(key)).size;
 }

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

@@ -0,0 +1,158 @@
+/**
+ * One project, assembled. The board answers "which projects want you"; this
+ * answers "what is the state of this one" — the criteria it is judged against,
+ * the decisions behind it, and what the agents have been doing to it.
+ *
+ * Two of its sections live on the record as prose rather than fields, so they
+ * are parsed here: decisions are written by `add-decision` in a fixed shape, and
+ * context is whatever bullets the ISA carries.
+ */
+
+import {
+  readProject,
+  type ServesAuthority,
+  type ServesKind,
+} from "../../hooks/lib/projects";
+import { SERVES_MEANING } from "../../hooks/lib/serves";
+import { anchorSlugOf, queryLedger } from "../ledger/query";
+import { type LedgerViewRow, viewRows } from "../ledger/view";
+import type { HandoffEntry } from "../lib/handoff-note";
+import { type Isc, parseIscs } from "../lib/project-isc";
+import { freshHandoffs, handoffSentence } from "./data";
+import { readSnoozes, snoozedUntil } from "./snooze";
+
+const DAY_MS = 86_400_000;
+const RECENT_ACTIONS = 8;
+const ACTIVITY_WINDOW_DAYS = 14;
+
+export interface Decision {
+  date: string | null;
+  text: string;
+  why: string | null;
+}
+
+interface DetailHandoff {
+  sentence: string;
+  full: string;
+  at: string;
+  source: HandoffEntry["source"];
+  waitingOn: string | null;
+}
+
+export interface SnoozableIsc extends Isc {
+  snoozedUntil: string | null;
+}
+
+export interface ProjectDetailView {
+  slug: string;
+  status: string;
+  path: string | null;
+  remote: string | null;
+  goal: string;
+  purpose: string;
+  serves: ServesKind | null;
+  servesBy: ServesAuthority | null;
+  placed: string | null;
+  updated: string;
+  iscs: SnoozableIsc[];
+  next: string[];
+  blockers: string[];
+  decisions: Decision[];
+  context: string[];
+  handoff: DetailHandoff | null;
+  runtimes: Record<string, number>;
+  recent: LedgerViewRow[];
+}
+
+const DECISION_LINE = /^-\s*(\d{4}-\d{2}-\d{2}):\s*(.+?)(?:\s*\((.+)\))?\s*$/;
+
+/** `add-decision` writes "- YYYY-MM-DD: what (why)"; anything else is kept whole. */
+export function parseDecisions(section: string | undefined): Decision[] {
+  if (!section) return [];
+  const decisions: Decision[] = [];
+  for (const line of section.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const match = DECISION_LINE.exec(trimmed);
+    decisions.push(
+      match
+        ? { date: match[1], text: match[2].trim(), why: match[3]?.trim() ?? null }
+        : { date: null, text: trimmed.replace(/^-\s*/, ""), why: null }
+    );
+  }
+  return decisions.reverse();
+}
+
+/** Bullets when the section has them, otherwise each non-empty line stands alone. */
+export function parseBullets(section: string | undefined): string[] {
+  if (!section) return [];
+  const lines = section
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean);
+  const bullets = lines.filter((l) => /^[-*+]\s+\S/.test(l));
+  const chosen = bullets.length > 0 ? bullets : lines;
+  return chosen.map((l) => l.replace(/^[-*+]\s+/, ""));
+}
+
+function detailHandoff(entry: HandoffEntry | undefined): DetailHandoff | null {
+  if (!entry) return null;
+  return {
+    sentence: handoffSentence(entry.handoff),
+    full: entry.handoff,
+    at: entry.timestamp,
+    source: entry.source,
+    waitingOn: entry.waitingOn ?? null,
+  };
+}
+
+function activity(slug: string, since: Date) {
+  const entries = queryLedger({ since }).filter((e) => anchorSlugOf(e.target) === slug);
+  const runtimes = Object.fromEntries(
+    Map.groupBy(entries, (e) => e.runtime)
+      .entries()
+      .map(([runtime, group]) => [runtime, group.length])
+  );
+  return { runtimes, recent: viewRows(entries).slice(0, RECENT_ACTIONS) };
+}
+
+export function projectDetail(
+  slug: string,
+  now: Date = new Date()
+): ProjectDetailView | null {
+  const project = readProject(slug);
+  if (!project) return null;
+
+  const handoffs = new Map(freshHandoffs(now));
+  const snoozes = readSnoozes(now);
+  const { runtimes, recent } = activity(
+    slug,
+    new Date(now.getTime() - ACTIVITY_WINDOW_DAYS * DAY_MS)
+  );
+
+  return {
+    slug: project.name,
+    status: project.status,
+    path: project.path ?? null,
+    remote: project.remote ?? null,
+    goal: project.goal ?? "",
+    purpose: project.serves
+      ? SERVES_MEANING[project.serves]
+      : "no purpose on record yet — set one to rank it",
+    serves: project.serves ?? null,
+    servesBy: project.serves_by ?? null,
+    placed: project.placed ?? null,
+    updated: project.updated,
+    iscs: [
+      ...parseIscs(project.criteria ?? ""),
+      ...parseIscs(project.changelog ?? ""),
+    ].map((isc) => ({ ...isc, snoozedUntil: snoozedUntil(slug, isc.id, snoozes) })),
+    next: project.next ?? [],
+    blockers: project.blockers ?? [],
+    decisions: parseDecisions(project.decisions),
+    context: parseBullets(project.context),
+    handoff: detailHandoff(project.path ? handoffs.get(project.path) : undefined),
+    runtimes,
+    recent,
+  };
+}

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

@@ -12,7 +12,11 @@
  */
 
 import {
-  PROJECT_STALE_DAYS_DEFAULT,
+  type GoalProgress,
+  progressFor,
+  readGoalLinks,
+} from "../../hooks/lib/goal-links";
+import {
   type ProjectProgress,
   readAllProjects,
   type ServesAuthority,
@@ -20,10 +24,12 @@ import {
 } from "../../hooks/lib/projects";
 import { isImportant, SERVES_MEANING } from "../../hooks/lib/serves";
 import { dueFrom, readTelosGoals, type TelosGoal } from "../../hooks/lib/telos-goals";
-import type { HandoffEntry } from "../agent/handoff-note";
+import type { HandoffEntry } from "../lib/handoff-note";
+import { parseIscs } from "../lib/project-isc";
 import { freshHandoffs } from "./data";
+import { type ControlRoomPrefs, readPrefs } from "./prefs";
+import { readSnoozes, snoozedUntil } from "./snooze";
 
-const URGENT_WITHIN_DAYS = 14;
 const RANKED_STATUSES = new Set(["active", "paused"]);
 
 export interface MatrixItem {
@@ -33,12 +39,16 @@ export interface MatrixItem {
   detail: string;
   urgent: boolean;
   important: boolean;
+  /** The quadrant the user pinned this to, which overrules both guesses. */
+  placed: string | null;
   urgentBecause: string[];
   importantBecause: string;
   serves: ServesKind | null;
   servesBy: ServesAuthority | null;
   due: string | null;
   waitingOn: string | null;
+  /** Counted from the criteria of the projects serving it, or null when none does. */
+  progress: { projects: string[]; closed: number; written: number } | null;
 }
 
 export interface Matrix {
@@ -50,11 +60,11 @@ export interface Matrix {
   unranked: number;
 }
 
-function dueSoon(due: string | null, now: Date): boolean {
+function dueSoon(due: string | null, now: Date, withinDays: number): boolean {
   if (!due) return false;
   const at = new Date(`${due}T23:59:59Z`).getTime();
   if (!Number.isFinite(at)) return false;
-  return at - now.getTime() <= URGENT_WITHIN_DAYS * 86_400_000;
+  return at - now.getTime() <= withinDays * 86_400_000;
 }
 
 function earliestDue(lines: string[]): string | null {
@@ -67,10 +77,10 @@ function plural(count: number, noun: string): string {
 }
 
 /** Measured against the grid's own clock, so a placement can be pinned in a test. */
-function quietSince(updated: string | undefined, now: Date): boolean {
+function quietSince(updated: string | undefined, now: Date, afterDays: number): boolean {
   if (!updated) return false;
   const age = now.getTime() - new Date(updated).getTime();
-  return Number.isFinite(age) && age > PROJECT_STALE_DAYS_DEFAULT * 86_400_000;
+  return Number.isFinite(age) && age > afterDays * 86_400_000;
 }
 
 /**
@@ -83,15 +93,20 @@ function projectUrgency(
   waiting: string | null,
   due: string | null,
   hasHandoff: boolean,
-  now: Date
+  now: Date,
+  prefs: ControlRoomPrefs
 ): string[] {
   const reasons: string[] = [];
   const blockers = p.blockers?.length ?? 0;
   if (blockers > 0) reasons.push(plural(blockers, "blocker"));
   if (waiting) reasons.push("waiting on you");
   else if (hasHandoff) reasons.push("handoff in progress");
-  if (dueSoon(due, now)) reasons.push(`next step dated ${due}`);
-  if (important && p.status === "active" && quietSince(p.updated, now)) {
+  if (dueSoon(due, now, prefs.urgentWithinDays)) reasons.push(`next step dated ${due}`);
+  if (
+    important &&
+    p.status === "active" &&
+    quietSince(p.updated, now, prefs.quietAfterDays)
+  ) {
     reasons.push("gone quiet");
   }
   return reasons;
@@ -100,7 +115,8 @@ function projectUrgency(
 function projectItem(
   p: ProjectProgress,
   handoffs: Map<string, HandoffEntry>,
-  now: Date
+  now: Date,
+  prefs: ControlRoomPrefs
 ): MatrixItem {
   const entry = p.path ? handoffs.get(p.path) : undefined;
   const waiting = entry?.waitingOn ?? null;
@@ -112,17 +128,20 @@ function projectItem(
     waiting,
     due,
     entry !== undefined,
-    now
+    now,
+    prefs
   );
 
+  const placed = placementOf(p.placed);
   return {
     kind: "project",
     id: p.name,
     label: p.name,
     detail: p.serves_note ?? p.next?.[0] ?? "",
-    urgent: urgentBecause.length > 0,
-    important,
-    urgentBecause,
+    urgent: placed ? placed.urgent : urgentBecause.length > 0,
+    important: placed ? placed.important : important,
+    placed: p.placed ?? null,
+    urgentBecause: placed ? ["placed by you", ...urgentBecause] : urgentBecause,
     importantBecause: p.serves
       ? SERVES_MEANING[p.serves]
       : "no purpose on record yet — set one to rank it",
@@ -130,11 +149,17 @@ function projectItem(
     servesBy: p.serves_by ?? null,
     due,
     waitingOn: waiting,
+    progress: null,
   };
 }
 
-function goalItem(goal: TelosGoal, now: Date): MatrixItem {
-  const urgent = dueSoon(goal.due, now);
+function goalItem(
+  goal: TelosGoal,
+  now: Date,
+  prefs: ControlRoomPrefs,
+  progress: GoalProgress | null
+): MatrixItem {
+  const urgent = dueSoon(goal.due, now, prefs.urgentWithinDays);
   return {
     kind: "goal",
     id: goal.id,
@@ -142,15 +167,54 @@ function goalItem(goal: TelosGoal, now: Date): MatrixItem {
     detail: goal.horizon ?? goal.text,
     urgent,
     important: true,
+    placed: null,
     urgentBecause: urgent ? [`dated ${goal.due}`] : [],
     importantBecause: "a goal you stated",
     serves: null,
     servesBy: null,
     due: goal.due,
     waitingOn: null,
+    progress,
   };
 }
 
+/** The user's placement, translated back into the two axes it stands for. */
+function placementOf(
+  placed: string | undefined
+): { urgent: boolean; important: boolean } | null {
+  switch (placed) {
+    case "now":
+      return { urgent: true, important: true };
+    case "plan":
+      return { urgent: false, important: true };
+    case "noise":
+      return { urgent: true, important: false };
+    case "later":
+      return { urgent: false, important: false };
+    default:
+      return null;
+  }
+}
+
+/** Criteria closed over criteria written, with snoozed and retired ones left out. */
+function criteriaBySlug(
+  projects: ProjectProgress[],
+  snoozes: Record<string, string>
+): Map<string, { closed: number; written: number }> {
+  return new Map(
+    projects.map((p) => {
+      const iscs = [
+        ...parseIscs(p.criteria ?? ""),
+        ...parseIscs(p.changelog ?? ""),
+      ].filter((i) => i.status !== "retired" && !snoozedUntil(p.name, i.id, snoozes));
+      return [
+        p.name,
+        { closed: iscs.filter((i) => i.status === "done").length, written: iscs.length },
+      ];
+    })
+  );
+}
+
 function quadrant(items: MatrixItem[], urgent: boolean, important: boolean) {
   return items
     .filter((i) => i.urgent === urgent && i.important === important)
@@ -172,11 +236,19 @@ export function buildMatrix(items: MatrixItem[], unranked: number): Matrix {
 }
 
 export function matrix(now: Date = new Date()): Matrix {
+  const prefs = readPrefs();
   const handoffs = new Map(freshHandoffs(now));
-  const ranked = readAllProjects().filter((p) => RANKED_STATUSES.has(p.status));
+  const all = readAllProjects();
+  const ranked = all.filter((p) => RANKED_STATUSES.has(p.status));
+  const links = readGoalLinks();
+  const criteria = criteriaBySlug(all, readSnoozes(now));
   const items = [
-    ...ranked.map((p) => projectItem(p, handoffs, now)),
-    ...readTelosGoals().map((g) => goalItem(g, now)),
+    ...ranked.map((p) => projectItem(p, handoffs, now, prefs)),
+    ...(prefs.rankGoals
+      ? readTelosGoals().map((g) =>
+          goalItem(g, now, prefs, progressFor(g.id, links, criteria))
+        )
+      : []),
   ];
   return buildMatrix(items, ranked.filter((p) => !p.serves).length);
 }

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

@@ -0,0 +1,96 @@
+/**
+ * The knobs behind the grid and the bell.
+ *
+ * These were constants in the source, which meant "gone quiet after 14 days"
+ * was PAL's opinion rather than the user's. They live in pal-settings.json now,
+ * with the old constants as the defaults so nothing changes until someone says
+ * otherwise.
+ */
+
+import { PROJECT_STALE_DAYS_DEFAULT } from "../../hooks/lib/projects";
+import {
+  raw as rawSettings,
+  reload,
+  write as writeSettings,
+} from "../../hooks/lib/settings";
+
+const ATTENTION_SOURCES = ["refusals", "waiting", "unranked"] as const;
+export type AttentionSource = (typeof ATTENTION_SOURCES)[number];
+
+export interface ControlRoomPrefs {
+  quietAfterDays: number;
+  urgentWithinDays: number;
+  rankGoals: boolean;
+  attention: Record<AttentionSource, boolean>;
+}
+
+const PREF_DEFAULTS: ControlRoomPrefs = {
+  quietAfterDays: PROJECT_STALE_DAYS_DEFAULT,
+  urgentWithinDays: 14,
+  rankGoals: true,
+  attention: { refusals: true, waiting: true, unranked: true },
+};
+
+const DAY_LIMIT = 365;
+
+function storedPrefs(): Partial<ControlRoomPrefs> {
+  const stored = rawSettings().controlRoom;
+  return (stored ?? {}) as Partial<ControlRoomPrefs>;
+}
+
+function positiveDays(value: unknown, fallback: number): number {
+  return typeof value === "number" &&
+    Number.isInteger(value) &&
+    value > 0 &&
+    value <= DAY_LIMIT
+    ? value
+    : fallback;
+}
+
+export function readPrefs(): ControlRoomPrefs {
+  const stored = storedPrefs();
+  return {
+    quietAfterDays: positiveDays(stored.quietAfterDays, PREF_DEFAULTS.quietAfterDays),
+    urgentWithinDays: positiveDays(
+      stored.urgentWithinDays,
+      PREF_DEFAULTS.urgentWithinDays
+    ),
+    rankGoals: stored.rankGoals ?? PREF_DEFAULTS.rankGoals,
+    attention: { ...PREF_DEFAULTS.attention, ...(stored.attention ?? {}) },
+  };
+}
+
+export type PrefUpdate = Partial<ControlRoomPrefs>;
+
+export function validatePrefs(update: PrefUpdate): string | null {
+  for (const key of ["quietAfterDays", "urgentWithinDays"] as const) {
+    const value = update[key];
+    if (value === undefined) continue;
+    if (positiveDays(value, -1) === -1) {
+      return `${key} must be a whole number of days, 1..${DAY_LIMIT}`;
+    }
+  }
+  if (update.rankGoals !== undefined && typeof update.rankGoals !== "boolean") {
+    return "rankGoals must be true or false";
+  }
+  for (const [key, value] of Object.entries(update.attention ?? {})) {
+    if (!(ATTENTION_SOURCES as readonly string[]).includes(key)) {
+      return `unknown attention source: ${key}`;
+    }
+    if (typeof value !== "boolean") return `attention.${key} must be true or false`;
+  }
+  return null;
+}
+
+export function writePrefs(update: PrefUpdate): ControlRoomPrefs {
+  const data = rawSettings();
+  const current = readPrefs();
+  const next: ControlRoomPrefs = {
+    ...current,
+    ...update,
+    attention: { ...current.attention, ...(update.attention ?? {}) },
+  };
+  writeSettings({ ...data, controlRoom: { ...next } });
+  reload();
+  return next;
+}

package/src/tools/control-room/server-config.ts

@@ -0,0 +1,8 @@
+/**
+ * Where the control room listens. Split from server.ts so the build can read it
+ * without importing the server itself — server.ts imports the page bundle, and
+ * a bundler asked to load that would be chasing its own output.
+ */
+
+export const DEFAULT_PORT = 7250;
+export const LOOPBACK = "127.0.0.1";