portable-agent-layer 0.72.0 → 0.74.0

package/src/tools/agent/project.ts

@@ -42,13 +42,16 @@ import {
 import { isServesKind, SERVES_KINDS, setServes } from "../../hooks/lib/serves";
 import {
   archiveLine,
-  dropEmptyArchiveHeadings,
+  completeIsc,
   encodeIscText,
   ISC_BOX,
+  type IscMove,
+  type IscSections,
   iscTitle,
   nextIscId,
   parseIscs,
   removeIscLine,
+  reopenIsc,
   selectIscs,
   taskSlug,
 } from "../lib/project-isc";
@@ -440,17 +443,25 @@ function cmdCompleteIsc(args: string[]): void {
   const id = Number(args[1] ?? fail("Usage: complete-isc <name> <id>"));
   if (!Number.isInteger(id) || id < 1) fail("ISC id must be a positive integer");
   const p = requireProject(name);
-  if (parseIscs(p.changelog ?? "").some((i) => i.id === id)) {
+  const move = completeIsc(sectionsOf(p), id);
+  if (!move.ok) fail(`${move.reason} in project "${name}"`);
+  if (move.already) {
     ok({ checked: true, id, alreadyDone: true });
     return;
   }
-  const { line, rest } = removeIscLine(p.criteria ?? "", id);
-  if (!line) fail(`ISC-${id} not found in project "${name}"`);
-  p.criteria = rest;
-  p.changelog = archiveLine(p.changelog, line.replace("[ ]", "[x]"));
+  applyIscMove(p, move);
+  ok({ checked: true, id, archived: true });
+}
+
+function sectionsOf(p: ProjectProgress): IscSections {
+  return { criteria: p.criteria ?? "", changelog: p.changelog ?? "" };
+}
+
+function applyIscMove(p: ProjectProgress, move: IscMove & { ok: true }): void {
+  p.criteria = move.criteria;
+  p.changelog = move.changelog;
   p.updated = now();
   writeProject(p);
-  ok({ checked: true, id, archived: true });
 }
 
 // Reopening pulls the line back out of the Changelog (or legacy Criteria) into
@@ -460,22 +471,13 @@ function cmdReopenIsc(args: string[]): void {
   const id = Number(args[1] ?? fail("Usage: reopen-isc <name> <id>"));
   if (!Number.isInteger(id) || id < 1) fail("ISC id must be a positive integer");
   const p = requireProject(name);
-  if (parseIscs(p.criteria ?? "").some((i) => i.id === id && i.status === "open")) {
+  const move = reopenIsc(sectionsOf(p), id);
+  if (!move.ok) fail(`${move.reason} in project "${name}"`);
+  if (move.already) {
     ok({ checked: false, id, alreadyOpen: true });
     return;
   }
-  let removed = removeIscLine(p.changelog ?? "", id);
-  if (removed.line) {
-    p.changelog = dropEmptyArchiveHeadings(removed.rest);
-  } else {
-    removed = removeIscLine(p.criteria ?? "", id);
-    if (removed.line) p.criteria = removed.rest;
-  }
-  if (!removed.line) fail(`ISC-${id} not found in project "${name}"`);
-  const openLine = removed.line.replace(/\[[x~]\]/i, "[ ]");
-  p.criteria = p.criteria ? `${p.criteria.trimEnd()}\n${openLine}` : openLine;
-  p.updated = now();
-  writeProject(p);
+  applyIscMove(p, move);
   ok({ checked: false, id });
 }
 

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

@@ -0,0 +1,146 @@
+/**
+ * What is waiting on you, and what you have already seen.
+ *
+ * Every item here is a template over a fact PAL already holds — a refused tool
+ * call, an unanswered handoff, a project with no purpose on record. Nothing is
+ * inferred: the bell is the one surface that must be instant and always right,
+ * and a model in that path would fail silently exactly when it mattered.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ensureDir, paths } from "../../hooks/lib/paths";
+import { readAllProjects } from "../../hooks/lib/projects";
+import { queryLedger } from "../ledger/query";
+import { displayTarget } from "../ledger/view";
+import { freshHandoffs } from "./data";
+import { type AttentionSource, readPrefs } from "./prefs";
+
+const DAY_MS = 86_400_000;
+const REFUSAL_WINDOW_DAYS = 7;
+const MAX_ITEMS = 40;
+
+export interface AttentionItem {
+  id: string;
+  source: AttentionSource;
+  severity: "alarm" | "waiting" | "note";
+  title: string;
+  detail: string;
+  at: string;
+  project: string | null;
+  /** Where clicking it should land. */
+  href: string;
+  read: boolean;
+}
+
+export interface AttentionView {
+  unread: number;
+  items: AttentionItem[];
+}
+
+type ReadState = Record<string, string>;
+
+function readFile(): string {
+  return resolve(ensureDir(paths.state()), "attention-read.json");
+}
+
+function readMarks(): ReadState {
+  const file = readFile();
+  if (!existsSync(file)) return {};
+  try {
+    return JSON.parse(readFileSync(file, "utf-8")) as ReadState;
+  } catch {
+    return {};
+  }
+}
+
+function writeMarks(marks: ReadState): void {
+  writeFileSync(readFile(), `${JSON.stringify(marks, null, 2)}\n`, "utf-8");
+}
+
+export function markRead(ids: string[], now: Date = new Date()): number {
+  const marks = readMarks();
+  for (const id of ids) marks[id] = now.toISOString();
+  writeMarks(marks);
+  return ids.length;
+}
+
+function refusals(now: Date): AttentionItem[] {
+  const since = new Date(now.getTime() - REFUSAL_WINDOW_DAYS * DAY_MS);
+  return queryLedger({ since })
+    .filter((e) => e.outcome === "denied" || e.outcome === "blocked")
+    .map((e) => ({
+      id: `refusal:${e.id}`,
+      source: "refusals" as const,
+      severity: "alarm" as const,
+      title: `${e.outcome === "blocked" ? "Blocked" : "Denied"}: ${e.tool}`,
+      detail: e.reason ?? e.command ?? displayTarget(e.target),
+      at: e.ts,
+      project: anchorProject(e.target),
+      href: `/log?outcome=${e.outcome}`,
+      read: false,
+    }));
+}
+
+function anchorProject(target: string): string | null {
+  const match = /^\{proj:([^}]+)\}/.exec(target);
+  return match ? match[1] : null;
+}
+
+function waiting(now: Date): AttentionItem[] {
+  const slugByPath = new Map(
+    readAllProjects()
+      .filter((p) => p.path)
+      .map((p) => [p.path as string, p.name])
+  );
+  return freshHandoffs(now)
+    .filter(([, h]) => h.waitingOn)
+    .map(([cwd, h]) => {
+      const slug = slugByPath.get(cwd) ?? null;
+      return {
+        id: `waiting:${cwd}:${h.timestamp}`,
+        source: "waiting" as const,
+        severity: "waiting" as const,
+        title: `${slug ?? cwd} is waiting on you`,
+        detail: h.waitingOn as string,
+        at: h.timestamp,
+        project: slug,
+        href: slug ? `/projects/${slug}` : "/",
+        read: false,
+      };
+    });
+}
+
+function unranked(): AttentionItem[] {
+  return readAllProjects()
+    .filter((p) => p.status === "active" && !p.serves)
+    .map((p) => ({
+      id: `unranked:${p.name}`,
+      source: "unranked" as const,
+      severity: "note" as const,
+      title: `${p.name} has no purpose on record`,
+      detail: "It ranks as unimportant until you say what it serves.",
+      at: p.updated,
+      project: p.name,
+      href: `/projects/${p.name}`,
+      read: false,
+    }));
+}
+
+const SOURCES: Record<AttentionSource, (now: Date) => AttentionItem[]> = {
+  refusals,
+  waiting,
+  unranked: () => unranked(),
+};
+
+export function attention(now: Date = new Date()): AttentionView {
+  const prefs = readPrefs();
+  const marks = readMarks();
+  const items = (Object.keys(SOURCES) as AttentionSource[])
+    .filter((source) => prefs.attention[source])
+    .flatMap((source) => SOURCES[source](now))
+    .map((item) => ({ ...item, read: marks[item.id] !== undefined }))
+    .sort((a, b) => b.at.localeCompare(a.at))
+    .slice(0, MAX_ITEMS);
+  return { unread: items.filter((i) => !i.read).length, items };
+}

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 { 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,
+  };
+}