portable-agent-layer 0.101.0 → 0.103.0

package/README.md

@@ -87,6 +87,7 @@ pal cli status        # check your setup
 | `pal cli usage` | Summarize token usage and estimated cost |
 | `pal cli cost` | What each month was paid against its API-equivalent cost, per agent |
 | `pal cli wrapped [--year <yyyy>]` | A year of your work in numbers, read from the event log |
+| `pal cli patterns` | How you work across projects, read from the event log |
 | `pal cli content preserve` | Copy every Claude Code transcript, gzipped, into `memory/content/` before Claude Code deletes it (30 days by default). Runs on its own whenever a session closes; the content store never leaves the machine, so `export` skips it |
 | `pal cli events discord-nag <sent\|answered>` | For a bot outside PAL: record a nag it sent (`--kind <kind>`), or the answer to one and how long it took (`--after-sec <n>`), in the local event log |
 | `pal cli infer` | One model call for scripts and bots, on the active agent's route: prompt on stdin, reply on stdout. `--tier small\|medium`, `--system <file>`, `--schema <file>` for a JSON reply checked against it, `--timeout <seconds>`. The call loads no PAL hooks or context; exits 1 with the reason when no route answers |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.101.0",
+  "version": "0.103.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/cost.ts

@@ -1,11 +1,31 @@
 import { labelOfRuntime } from "../hooks/lib/agent-registry";
-import { eventsSince } from "../hooks/lib/events";
+import { allEventsSince } from "../hooks/lib/events";
 import { leaf } from "../tools/lib/command";
+import { efficiency } from "../tools/lib/cost/efficiency";
+import { leaderboards } from "../tools/lib/cost/leaderboards";
+import { modelMix, palSpend } from "../tools/lib/cost/mix";
+import { contextOverhead } from "../tools/lib/cost/overhead";
+import {
+  efficiencyLines,
+  leaderboardLines,
+  overheadLines,
+  shareLines,
+} from "../tools/lib/cost/render";
 import { costLines, costMonths } from "../tools/lib/cost-report";
+import { ofType } from "../tools/lib/wrapped/year";
 
 function printCost(): undefined {
-  const months = costMonths(eventsSince("model_call", new Date(0)));
-  for (const line of costLines(months, labelOfRuntime)) console.log(line);
+  const events = allEventsSince(new Date(0));
+  const months = costMonths(ofType(events, "model_call"));
+  const lines = [
+    ...costLines(months, labelOfRuntime),
+    ...leaderboardLines(leaderboards(events)),
+    ...efficiencyLines(efficiency(events)),
+    ...shareLines("Model mix", modelMix(events)),
+    ...shareLines("PAL's own spend per caller, already in the totals", palSpend(events)),
+    ...overheadLines(contextOverhead(events)),
+  ];
+  for (const line of lines) console.log(line);
 }
 
 export const costCommand = leaf({

package/src/cli/patterns.ts

@@ -0,0 +1,31 @@
+import { allEventsSince } from "../hooks/lib/events";
+import { localDay } from "../hooks/lib/wall-clock";
+import { leaf } from "../tools/lib/command";
+import { projectActivity } from "../tools/lib/patterns/activity";
+import { contextSwitches, dayShape } from "../tools/lib/patterns/days";
+import { focusBlocks } from "../tools/lib/patterns/focus";
+import { projectProfiles } from "../tools/lib/patterns/profiles";
+import {
+  daysLines,
+  focusLines,
+  momentumLines,
+  projectsLines,
+} from "../tools/lib/patterns/render";
+import { currentSprint, quietAfterBurst } from "../tools/lib/patterns/sprint";
+
+function printPatterns(): undefined {
+  const activity = projectActivity(allEventsSince(new Date(0)));
+  console.log("\n  PAL Patterns");
+  const lines = [
+    ...momentumLines(currentSprint(activity), quietAfterBurst(activity, localDay())),
+    ...daysLines(dayShape(activity), contextSwitches(activity)),
+    ...focusLines(focusBlocks(activity)),
+    ...projectsLines(projectProfiles(activity)),
+  ];
+  for (const line of lines) console.log(line);
+}
+
+export const patternsCommand = leaf({
+  summary: "How you work across projects, read from the event log",
+  run: () => printPatterns(),
+});

package/src/cli/tree.ts

@@ -22,6 +22,7 @@ import { inferCommand } from "./infer";
 import { knowledgeCommand } from "./knowledge";
 import { ledgerCommand } from "./ledger-command";
 import { runMigrate } from "./migrate";
+import { patternsCommand } from "./patterns";
 import { telosCommand, timezoneCommand } from "./personal-context";
 import { ruleCommand } from "./rule";
 import { serverCommand } from "./server";
@@ -157,6 +158,7 @@ export function cliTree(admin: AdminHandlers): Group {
       usage: usageCommand,
       cost: costCommand,
       wrapped: wrappedCommand,
+      patterns: patternsCommand,
       content: contentCommand,
       events: eventsCommand,
       infer: inferCommand,

package/src/hooks/LoadContext.ts

@@ -8,23 +8,21 @@
  * Which agent gets what, in which envelope, is in lib/session-context.ts.
  */
 
-import { mkdirSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
 import { getActiveAgent } from "./lib/agent";
 import { autoUpdateOnStart } from "./lib/auto-update";
 import { buildClaudeMd, regenerateIfNeeded } from "./lib/claude-md";
 import { type AgentTarget, buildSystemReminder } from "./lib/context";
+import { logContextInjected } from "./lib/context-overhead";
 import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { logContextSnapshot, logDebug, logError } from "./lib/log";
-import { platform } from "./lib/paths";
 import {
   contextEnvelope,
   contextForSource,
-  copilotInstructions,
   isSubagentSession,
   needsAgentsMd,
+  writeCopilotInstructions,
 } from "./lib/session-context";
-import { logSessionStart } from "./lib/session-events";
+import { logSessionStart, type SessionStartPayload } from "./lib/session-events";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
 
@@ -49,7 +47,7 @@ try {
 
 try {
   const active = getActiveAgent();
-  const input = await readStdinJSON<{ source?: string }>();
+  const input = await readStdinJSON<SessionStartPayload>();
   logSessionStart(input);
   const wanted = contextForSource(active, input?.source);
   if (wanted === "none") {
@@ -75,15 +73,11 @@ try {
   );
   if (!envelope) process.exit(0);
 
-  if (envelope.file) {
-    const dir = resolve(platform.copilotDir(), "instructions");
-    mkdirSync(dir, { recursive: true });
-    const path = resolve(dir, "pal-session.instructions.md");
-    writeFileSync(path, copilotInstructions(envelope.file), "utf-8");
-  }
+  if (envelope.file) writeCopilotInstructions(envelope.file);
 
   if (envelope.kind === "text") console.log(envelope.payload);
   else process.stdout.write(envelope.payload);
+  logContextInjected(input, reminder);
   logDebug("LoadContext", `Reminder injected: ${reminder.length} chars`);
 } catch (err) {
   logError("LoadContext:reminder", err);

package/src/hooks/lib/context-overhead.ts

@@ -0,0 +1,30 @@
+import { buildClaudeMd } from "./claude-md";
+import { appendEvent, logQuietly } from "./events";
+import { type HookTurnPayload, hookSessionId } from "./hook-turn";
+import { getSemiStaticSources, readFileSafe } from "./semi-static";
+
+function semiStaticChars(): number {
+  return getSemiStaticSources().reduce(
+    (sum, source) => sum + readFileSafe(source.path).length,
+    0
+  );
+}
+
+/** Chars, not tokens: no tokenizer runs at session start. */
+export function logContextInjected(
+  payload: HookTurnPayload | null,
+  reminder: string,
+  now: Date = new Date()
+): void {
+  logQuietly("context_injected", () =>
+    appendEvent(
+      "context_injected",
+      {
+        instructionsChars: buildClaudeMd().length,
+        semiStaticChars: semiStaticChars(),
+        dynamicChars: reminder.length,
+      },
+      { ts: now.toISOString(), session: hookSessionId(payload) ?? null }
+    )
+  );
+}

package/src/hooks/lib/events.ts

@@ -54,6 +54,7 @@ export const EVENT_FIELDS = {
   ],
   session_end: ["reason", "durationSec", "turns", "messages", "status"],
   compaction: ["trigger", "withInstructions", "contextTokens"],
+  context_injected: ["instructionsChars", "semiStaticChars", "dynamicChars"],
   hook_timing: ["hook", "totalMs", "handlers"],
   inference_call: [
     "caller",

package/src/hooks/lib/semi-static.ts

@@ -48,7 +48,7 @@ export function antigravityRule(description: string, content: string): string {
   return `---\ntrigger: always_on\ndescription: ${description}\n---\n\n${content}`;
 }
 
-function readFileSafe(path: string): string {
+export function readFileSafe(path: string): string {
   try {
     if (!existsSync(path)) return "";
     return readFileSync(path, "utf-8").trim();

package/src/hooks/lib/session-context.ts

@@ -7,7 +7,10 @@
  * context for weeks — and none of it was reachable from a test.
  */
 
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
 import type { AgentName } from "./agent-registry";
+import { platform } from "./paths";
 
 export interface ContextEnvelope {
   /** Whether the agent parses stdout as JSON or reads it as raw text. */
@@ -96,3 +99,10 @@ export function contextEnvelope(
 export function copilotInstructions(context: string): string {
   return `---\napplyTo: "**"\n---\n\n${context}`;
 }
+
+export function writeCopilotInstructions(context: string): void {
+  const dir = resolve(platform.copilotDir(), "instructions");
+  mkdirSync(dir, { recursive: true });
+  const path = resolve(dir, "pal-session.instructions.md");
+  writeFileSync(path, copilotInstructions(context), "utf-8");
+}

package/src/hooks/lib/session-events.ts

@@ -20,7 +20,7 @@ const SESSION_LOOKBACK_MS = 7 * 24 * 60 * 60 * 1000;
 const TRANSCRIPT_TAIL_BYTES = 256 * 1024;
 const MAX_FIELD = 64;
 
-interface SessionStartPayload extends HookTurnPayload {
+export interface SessionStartPayload extends HookTurnPayload {
   source?: string;
   model?: unknown;
 }

package/src/tools/lib/cost/efficiency.ts

@@ -0,0 +1,58 @@
+import type { LoggedEvent } from "../../../hooks/lib/events";
+import { apiPriceOf } from "../cost-report";
+import { dayOf, numberOf, ofType } from "../wrapped/year";
+
+export interface PerUnit {
+  cost: number;
+  units: number;
+  lowerBound: boolean;
+}
+
+export interface Efficiency {
+  since: string;
+  perCommit: PerUnit | null;
+  perClosedIsc: PerUnit | null;
+  cacheHitRate: number | null;
+}
+
+const PROMPT_FIELDS = [
+  "inputTokens",
+  "cacheRead",
+  "cacheWrite5m",
+  "cacheWrite1h",
+] as const;
+
+function cacheHitRate(calls: LoggedEvent[]): number | null {
+  let read = 0;
+  let prompt = 0;
+  for (const call of calls) {
+    for (const field of PROMPT_FIELDS) prompt += numberOf(call[field]) ?? 0;
+    read += numberOf(call.cacheRead) ?? 0;
+  }
+  return prompt === 0 ? null : read / prompt;
+}
+
+function perUnit(spent: number, unpriced: number, units: number): PerUnit | null {
+  return units === 0 ? null : { cost: spent / units, units, lowerBound: unpriced > 0 };
+}
+
+/** Only since the first logged model call: older commits and ISCs cost nothing PAL saw. */
+export function efficiency(events: LoggedEvent[]): Efficiency | null {
+  const calls = ofType(events, "model_call");
+  const [first] = [...calls].sort((a, b) => a.ts.localeCompare(b.ts));
+  if (first === undefined) return null;
+  const since = (e: LoggedEvent) => e.ts >= first.ts;
+  const prices = calls.map(apiPriceOf);
+  const spent = prices.reduce<number>((sum, p) => sum + (p ?? 0), 0);
+  const unpriced = prices.filter((p) => p === null).length;
+  const commits = ofType(events, "commit").filter(since).length;
+  const closed = ofType(events, "commitment").filter(
+    (e) => since(e) && e.outcome === "kept"
+  ).length;
+  return {
+    since: dayOf(first),
+    perCommit: perUnit(spent, unpriced, commits),
+    perClosedIsc: perUnit(spent, unpriced, closed),
+    cacheHitRate: cacheHitRate(calls),
+  };
+}

package/src/tools/lib/cost/leaderboards.ts

@@ -0,0 +1,81 @@
+import type { LoggedEvent } from "../../../hooks/lib/events";
+import { apiPriceOf } from "../cost-report";
+import { turnCost, turnSpans, whereAndWhen } from "../wrapped/records";
+import { dayOf, ofType, tally } from "../wrapped/year";
+
+export interface Entry {
+  label: string;
+  cost: number;
+  unpriced: number;
+}
+
+export interface Leaderboards {
+  projects: Entry[];
+  sessions: Entry[];
+  days: Entry[];
+  turns: Entry[];
+}
+
+const TOP = 5;
+
+const mostExpensive = (entries: Entry[]) =>
+  entries.sort((a, b) => b.cost - a.cost || a.label.localeCompare(b.label)).slice(0, TOP);
+
+function board(calls: LoggedEvent[], labelOf: (call: LoggedEvent) => string): Entry[] {
+  const entries = new Map<string, Entry>();
+  for (const call of calls) {
+    const label = labelOf(call);
+    const entry = entries.get(label) ?? { label, cost: 0, unpriced: 0 };
+    entries.set(label, entry);
+    const price = apiPriceOf(call);
+    if (price === null) entry.unpriced++;
+    else entry.cost += price;
+  }
+  return mostExpensive([...entries.values()]);
+}
+
+const projectOf = (call: LoggedEvent) => call.project ?? "no project";
+
+function sessionLabel(session: string | null, own: LoggedEvent[]): string {
+  const [project] = tally(
+    own.filter((call) => call.project !== null),
+    projectOf
+  );
+  const [first] = own.sort((a, b) => a.ts.localeCompare(b.ts));
+  const id = session?.slice(0, 8) ?? "no session";
+  return `${id} (${project?.name ?? "no project"}, ${dayOf(first)})`;
+}
+
+/** A session is named by the project most of its calls ran in, and the day it started. */
+function sessionLabels(calls: LoggedEvent[]): Map<string | null, string> {
+  const bySession = new Map<string | null, LoggedEvent[]>();
+  for (const call of calls) {
+    const own = bySession.get(call.session) ?? [];
+    bySession.set(call.session, own);
+    own.push(call);
+  }
+  return new Map(
+    [...bySession].map(([session, own]) => [session, sessionLabel(session, own)])
+  );
+}
+
+function turnBoard(events: LoggedEvent[]): Entry[] {
+  return mostExpensive(
+    turnSpans(events).flatMap((span) => {
+      const cost = turnCost(span);
+      return cost === null ? [] : [{ label: whereAndWhen(span.turn), cost, unpriced: 0 }];
+    })
+  );
+}
+
+/** Every model call counts, PAL's own spawns included; its inference_call twins never do. */
+export function leaderboards(events: LoggedEvent[]): Leaderboards {
+  const calls = ofType(events, "model_call");
+  const sessions = sessionLabels(calls);
+  return {
+    projects: board(calls, projectOf),
+    sessions: board(calls, (call) => String(sessions.get(call.session))),
+    days: board(calls, dayOf),
+    turns: turnBoard(events),
+  };
+}

package/src/tools/lib/cost/mix.ts

@@ -0,0 +1,50 @@
+import type { LoggedEvent } from "../../../hooks/lib/events";
+import { apiPriceOf } from "../cost-report";
+import { numberOf, ofType } from "../wrapped/year";
+
+export interface Share {
+  label: string;
+  calls: number;
+  cost: number;
+  unpriced: number;
+}
+
+function shares(
+  calls: LoggedEvent[],
+  labelOf: (call: LoggedEvent) => string,
+  priceOf: (call: LoggedEvent) => number | null
+): Share[] {
+  const byLabel = new Map<string, Share>();
+  for (const call of calls) {
+    const label = labelOf(call);
+    const share = byLabel.get(label) ?? { label, calls: 0, cost: 0, unpriced: 0 };
+    byLabel.set(label, share);
+    share.calls++;
+    const price = priceOf(call);
+    if (price === null) share.unpriced++;
+    else share.cost += price;
+  }
+  return [...byLabel.values()].sort(
+    (a, b) => b.cost - a.cost || b.calls - a.calls || a.label.localeCompare(b.label)
+  );
+}
+
+const textOr = (value: unknown, fallback: string) =>
+  typeof value === "string" ? value : fallback;
+
+export function modelMix(events: LoggedEvent[]): Share[] {
+  return shares(
+    ofType(events, "model_call"),
+    (call) => textOr(call.model, "unknown model"),
+    apiPriceOf
+  );
+}
+
+/** Already inside the model calls PAL spawned; never add it to a total. */
+export function palSpend(events: LoggedEvent[]): Share[] {
+  return shares(
+    ofType(events, "inference_call"),
+    (call) => textOr(call.caller, "unknown caller"),
+    (call) => numberOf(call.costUsd)
+  );
+}

package/src/tools/lib/cost/overhead.ts

@@ -0,0 +1,29 @@
+import type { LoggedEvent } from "../../../hooks/lib/events";
+import { dayOf, numberOf, ofType } from "../wrapped/year";
+
+type Tier = "instructionsChars" | "semiStaticChars" | "dynamicChars";
+
+export interface Overhead {
+  since: string;
+  sessions: number;
+  perSession: Record<Tier, number>;
+}
+
+/** A compacted session is injected again; its injections add up. */
+export function contextOverhead(events: LoggedEvent[]): Overhead | null {
+  const injections = ofType(events, "context_injected");
+  const [first] = [...injections].sort((a, b) => a.ts.localeCompare(b.ts));
+  if (first === undefined) return null;
+  const sessions = new Set(injections.map((e) => e.session ?? e.id)).size;
+  const average = (tier: Tier) =>
+    injections.reduce((sum, e) => sum + (numberOf(e[tier]) ?? 0), 0) / sessions;
+  return {
+    since: dayOf(first),
+    sessions,
+    perSession: {
+      instructionsChars: average("instructionsChars"),
+      semiStaticChars: average("semiStaticChars"),
+      dynamicChars: average("dynamicChars"),
+    },
+  };
+}

package/src/tools/lib/cost/render.ts

@@ -0,0 +1,70 @@
+import { count, counted } from "../report-rows";
+import { fmtCost } from "../token-report";
+import type { Efficiency, PerUnit } from "./efficiency";
+import type { Entry, Leaderboards } from "./leaderboards";
+import type { Share } from "./mix";
+import type { Overhead } from "./overhead";
+
+function entryLine({ label, cost, unpriced }: Entry): string {
+  const extra = unpriced > 0 ? ` + ${count(unpriced)} unpriced calls` : "";
+  return `    ${fmtCost(cost).padStart(10)}  ${label}${extra}`;
+}
+
+function boardLines(title: string, entries: Entry[]): string[] {
+  const lines = entries.length === 0 ? ["    unknown"] : entries.map(entryLine);
+  return [`\n  Most expensive ${title}\n`, ...lines];
+}
+
+export function leaderboardLines(boards: Leaderboards): string[] {
+  return [
+    ...boardLines("projects", boards.projects),
+    ...boardLines("sessions", boards.sessions),
+    ...boardLines("days", boards.days),
+    ...boardLines("turns", boards.turns),
+  ];
+}
+
+function perUnitText(per: PerUnit | null, unit: string): string {
+  if (per === null) return "unknown";
+  const atLeast = per.lowerBound ? "at least " : "";
+  return `${atLeast}${fmtCost(per.cost)} over ${counted(per.units, unit)}`;
+}
+
+const percent = (rate: number | null) =>
+  rate === null ? "unknown" : `${(rate * 100).toFixed(1)}%`;
+
+export function efficiencyLines(efficiency: Efficiency | null): string[] {
+  if (efficiency === null) return [];
+  return [
+    `\n  Since ${efficiency.since}\n`,
+    `    Per commit       ${perUnitText(efficiency.perCommit, "commit")}`,
+    `    Per closed ISC   ${perUnitText(efficiency.perClosedIsc, "ISC")}`,
+    `    Cache hit rate   ${percent(efficiency.cacheHitRate)}`,
+  ];
+}
+
+function shareLine({ label, calls, cost, unpriced }: Share): string {
+  const price = unpriced === calls ? "unknown" : fmtCost(cost);
+  const extra = unpriced > 0 && unpriced < calls ? `, ${count(unpriced)} unpriced` : "";
+  return `    ${price.padStart(10)}  ${label}  ${counted(calls, "call")}${extra}`;
+}
+
+const chars = (n: number) => `${count(Math.round(n))} chars`.padStart(14);
+
+export function overheadLines(overhead: Overhead | null): string[] {
+  const title = "\n  PAL context per session\n";
+  if (overhead === null) return [title, "    unknown"];
+  const { instructionsChars, semiStaticChars, dynamicChars } = overhead.perSession;
+  return [
+    `\n  PAL context per session, over ${counted(overhead.sessions, "session")} since ${overhead.since}\n`,
+    `    Instructions ${chars(instructionsChars)}`,
+    `    Semi-static  ${chars(semiStaticChars)}`,
+    `    Dynamic      ${chars(dynamicChars)}`,
+    `    Total        ${chars(instructionsChars + semiStaticChars + dynamicChars)}`,
+  ];
+}
+
+export function shareLines(title: string, shares: Share[]): string[] {
+  const lines = shares.length === 0 ? ["    unknown"] : shares.map(shareLine);
+  return [`\n  ${title}\n`, ...lines];
+}

package/src/tools/lib/patterns/activity.ts

@@ -0,0 +1,41 @@
+import type { LoggedEvent } from "../../../hooks/lib/events";
+import { dayOf, isUserActivity } from "../wrapped/year";
+
+export interface Activity {
+  ms: number;
+  day: string;
+  project: string;
+  event: LoggedEvent;
+}
+
+/** The user's own work that landed in a project, oldest first. */
+export function projectActivity(events: LoggedEvent[]): Activity[] {
+  return events
+    .filter(isUserActivity)
+    .flatMap((event) =>
+      typeof event.project === "string"
+        ? [{ ms: Date.parse(event.ts), day: dayOf(event), project: event.project, event }]
+        : []
+    )
+    .sort((a, b) => a.ms - b.ms);
+}
+
+export const movesAttention = ({ event }: Activity) =>
+  event.type === "turn" || event.type === "commit";
+
+export function projectsByDay(activity: Activity[]): Map<string, Set<string>> {
+  const byDay = new Map<string, Set<string>>();
+  for (const { day, project } of activity) {
+    byDay.set(day, (byDay.get(day) ?? new Set()).add(project));
+  }
+  return byDay;
+}
+
+/** Oldest day first, as the activity is. */
+export function daysByProject(activity: Activity[]): Map<string, string[]> {
+  const byProject = new Map<string, Set<string>>();
+  for (const { day, project } of activity) {
+    byProject.set(project, (byProject.get(project) ?? new Set()).add(day));
+  }
+  return new Map([...byProject].map(([project, days]) => [project, [...days]]));
+}

package/src/tools/lib/patterns/days.ts

@@ -0,0 +1,38 @@
+import type { Best } from "../wrapped/records";
+import { type Activity, movesAttention, projectsByDay } from "./activity";
+
+export interface DayShape {
+  oneProject: number;
+  manyProjects: number;
+}
+
+export interface Switches {
+  perDay: number;
+  mostInADay: Best;
+}
+
+export function dayShape(activity: Activity[]): DayShape {
+  const sizes = [...projectsByDay(activity).values()].map((projects) => projects.size);
+  return {
+    oneProject: sizes.filter((n) => n === 1).length,
+    manyProjects: sizes.filter((n) => n > 1).length,
+  };
+}
+
+/** Model calls are left out: two sessions running side by side interleave theirs without the user moving. */
+export function contextSwitches(activity: Activity[]): Switches | null {
+  const moves = activity.filter(movesAttention);
+  const perDay = new Map<string, number>();
+  moves.forEach((a, i) => {
+    const previous = moves[i - 1];
+    const switched = previous?.day === a.day && previous.project !== a.project;
+    perDay.set(a.day, (perDay.get(a.day) ?? 0) + (switched ? 1 : 0));
+  });
+  const counts = [...perDay];
+  if (counts.length === 0) return null;
+  const [day, most] = counts.reduce((top, c) => (c[1] > top[1] ? c : top));
+  return {
+    perDay: counts.reduce((sum, [, n]) => sum + n, 0) / counts.length,
+    mostInADay: { value: most, label: day },
+  };
+}

package/src/tools/lib/patterns/focus.ts

@@ -0,0 +1,59 @@
+import type { Best } from "../wrapped/records";
+import { type Activity, movesAttention } from "./activity";
+
+export interface Focus {
+  blocks: number;
+  minutes: number;
+  longest: Best | null;
+}
+
+interface Block {
+  first: Activity;
+  last: Activity;
+}
+
+const MINUTE_MS = 60_000;
+const FOCUS_MINUTES = 90;
+const MAX_GAP_MINUTES = 30;
+
+const minutesOf = ({ first, last }: Block) => (last.ms - first.ms) / MINUTE_MS;
+
+function continues(block: Block, next: Activity): boolean {
+  return (
+    next.project === block.last.project &&
+    (next.ms - block.last.ms) / MINUTE_MS <= MAX_GAP_MINUTES
+  );
+}
+
+/** A parallel session's model calls in another project leave the block alone; the user moving there ends it. */
+function blocksOf(activity: Activity[]): Block[] {
+  const blocks: Block[] = [];
+  for (const next of activity) {
+    const current = blocks.at(-1);
+    if (current && continues(current, next)) current.last = next;
+    else if (!current || current.last.project === next.project || movesAttention(next))
+      blocks.push({ first: next, last: next });
+  }
+  return blocks;
+}
+
+/** 90 minutes or more on one project with no gap over 30. */
+export function focusBlocks(activity: Activity[]): Focus | null {
+  if (activity.length === 0) return null;
+  const focused = blocksOf(activity).filter((b) => minutesOf(b) >= FOCUS_MINUTES);
+  const longest = focused.reduce<Block | null>(
+    (top, b) => (top === null || minutesOf(b) > minutesOf(top) ? b : top),
+    null
+  );
+  return {
+    blocks: focused.length,
+    minutes: focused.reduce((sum, b) => sum + minutesOf(b), 0),
+    longest:
+      longest === null
+        ? null
+        : {
+            value: minutesOf(longest),
+            label: `${longest.first.project}, ${longest.first.day}`,
+          },
+  };
+}

package/src/tools/lib/patterns/profiles.ts

@@ -0,0 +1,59 @@
+import { labelOfRuntime } from "../../../hooks/lib/agent-registry";
+import { localClock } from "../../../hooks/lib/wall-clock";
+import { channelOf } from "../wrapped/habits";
+import { type Tally, tally } from "../wrapped/year";
+import type { Activity } from "./activity";
+
+export interface ProjectProfile {
+  project: string;
+  activeDays: number;
+  hour: string;
+  weekday: string;
+  agents: Tally[];
+  channels: Tally[];
+}
+
+interface Slot {
+  hour: string;
+  weekday: string;
+}
+
+/** One slot per local hour the project saw work, however busy it was. */
+function slotsOf(activity: Activity[]): Slot[] {
+  const slots = new Map<string, Slot>();
+  for (const a of activity) {
+    const clock = localClock(new Date(a.ms));
+    const hour = `${String(clock.hour).padStart(2, "0")}:00`;
+    slots.set(`${a.day} ${hour}`, { hour, weekday: clock.weekday });
+  }
+  return [...slots.values()];
+}
+
+const topOf = (slots: Slot[], labelOf: (slot: Slot) => string) =>
+  tally(slots, labelOf)[0].name;
+
+function profileOf(project: string, activity: Activity[]): ProjectProfile {
+  const slots = slotsOf(activity);
+  const turns = activity.filter((a) => a.event.type === "turn").map((a) => a.event);
+  return {
+    project,
+    activeDays: new Set(activity.map((a) => a.day)).size,
+    hour: topOf(slots, (s) => s.hour),
+    weekday: topOf(slots, (s) => s.weekday),
+    agents: tally(turns, (t) => labelOfRuntime(t.runtime)),
+    channels: tally(turns, channelOf),
+  };
+}
+
+/** Most worked-on first. */
+export function projectProfiles(activity: Activity[]): ProjectProfile[] {
+  const byProject = new Map<string, Activity[]>();
+  for (const a of activity) {
+    const own = byProject.get(a.project) ?? [];
+    byProject.set(a.project, own);
+    own.push(a);
+  }
+  return [...byProject]
+    .map(([project, own]) => profileOf(project, own))
+    .sort((a, b) => b.activeDays - a.activeDays || a.project.localeCompare(b.project));
+}

package/src/tools/lib/patterns/render.ts

@@ -0,0 +1,89 @@
+import { count, days, row, tallyLabel } from "../report-rows";
+import type { DayShape, Switches } from "./days";
+import type { Focus } from "./focus";
+import type { ProjectProfile } from "./profiles";
+import type { QuietProject, Sprint } from "./sprint";
+
+function shapeLabel({ oneProject, manyProjects }: DayShape): string {
+  const total = oneProject + manyProjects;
+  if (total === 0) return "unknown";
+  return `${days(oneProject)} on one project, ${days(manyProjects)} on several (${Math.round((oneProject / total) * 100)}% focused)`;
+}
+
+function switchesLabel(switches: Switches | null): string {
+  if (switches === null) return "unknown";
+  const { value, label } = switches.mostInADay;
+  return `${switches.perDay.toFixed(1)} a day, at most ${count(value)} (${label})`;
+}
+
+function hoursAndMinutes(minutes: number): string {
+  const whole = Math.round(minutes);
+  return `${Math.floor(whole / 60)}h ${String(whole % 60).padStart(2, "0")}m`;
+}
+
+function longestLabel(focus: Focus): string {
+  const longest = focus.longest;
+  return longest === null
+    ? "none"
+    : `${hoursAndMinutes(longest.value)} (${longest.label})`;
+}
+
+export function focusLines(focus: Focus | null): string[] {
+  if (focus === null)
+    return ["\n  Focus\n", row("focus blocks", "unknown"), row("longest", "unknown")];
+  return [
+    "\n  Focus\n",
+    row(
+      "focus blocks",
+      `${count(focus.blocks)}, ${hoursAndMinutes(focus.minutes)} in all`
+    ),
+    row("longest", longestLabel(focus)),
+  ];
+}
+
+function profileLines(profile: ProjectProfile): string[] {
+  return [
+    row(
+      profile.project,
+      `${days(profile.activeDays)}, most at ${profile.hour} on ${profile.weekday}`
+    ),
+    row("  agents", tallyLabel(profile.agents)),
+    row("  channels", tallyLabel(profile.channels)),
+  ];
+}
+
+export function projectsLines(profiles: ProjectProfile[]): string[] {
+  if (profiles.length === 0) return ["\n  Projects\n", row("projects", "unknown")];
+  return ["\n  Projects\n", ...profiles.flatMap(profileLines)];
+}
+
+export function daysLines(shape: DayShape, switches: Switches | null): string[] {
+  return [
+    "\n  Days\n",
+    row("project days", shapeLabel(shape)),
+    row("context switches", switchesLabel(switches)),
+  ];
+}
+
+function quietLabel(quiet: QuietProject[]): string {
+  if (quiet.length === 0) return "none";
+  return quiet.map((q) => `${q.project} (quiet ${days(q.quietDays)})`).join(" · ");
+}
+
+/** With no activity at all, there is no telling which projects went quiet. */
+export function momentumLines(sprint: Sprint | null, quiet: QuietProject[]): string[] {
+  if (sprint === null)
+    return [
+      "\n  Momentum\n",
+      row("current sprint", "unknown"),
+      row("quiet after a burst", "unknown"),
+    ];
+  return [
+    "\n  Momentum\n",
+    row(
+      "current sprint",
+      `${sprint.project}, ${days(sprint.days)} of work since ${sprint.since}`
+    ),
+    row("quiet after a burst", quietLabel(quiet)),
+  ];
+}

package/src/tools/lib/patterns/sprint.ts

@@ -0,0 +1,58 @@
+import { daysBetween } from "../wrapped/year";
+import { type Activity, daysByProject, projectsByDay } from "./activity";
+
+export interface Sprint {
+  project: string;
+  days: number;
+  since: string;
+}
+
+export interface QuietProject {
+  project: string;
+  lastActive: string;
+  quietDays: number;
+  burstDays: number;
+}
+
+const BURST_DAYS = 3;
+const BURST_WINDOW_DAYS = 7;
+const QUIET_DAYS = 14;
+
+/** Counted in the days the user worked at all, so a weekend off does not end it. */
+export function currentSprint(activity: Activity[]): Sprint | null {
+  const days = [...projectsByDay(activity)];
+  const latest = days.at(-1);
+  if (latest === undefined) return null;
+  const sprints = [...latest[1]].map((project) => {
+    let start = days.length - 1;
+    while (start > 0 && days[start - 1][1].has(project)) start--;
+    return { project, days: days.length - start, since: days[start][0] };
+  });
+  return sprints.sort((a, b) => b.days - a.days || a.project.localeCompare(b.project))[0];
+}
+
+function busiestWindow(days: string[]): number {
+  let most = 0;
+  let start = 0;
+  for (let end = 0; end < days.length; end++) {
+    while (daysBetween(days[start], days[end]) >= BURST_WINDOW_DAYS) start++;
+    most = Math.max(most, end - start + 1);
+  }
+  return most;
+}
+
+/** A burst is 3 active days within 7; quiet is 14 days without any. */
+export function quietAfterBurst(activity: Activity[], today: string): QuietProject[] {
+  return [...daysByProject(activity)]
+    .map(([project, days]) => {
+      const lastActive = days.at(-1) ?? today;
+      return {
+        project,
+        lastActive,
+        quietDays: daysBetween(lastActive, today),
+        burstDays: busiestWindow(days),
+      };
+    })
+    .filter((p) => p.burstDays >= BURST_DAYS && p.quietDays >= QUIET_DAYS)
+    .sort((a, b) => b.lastActive.localeCompare(a.lastActive));
+}

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

@@ -0,0 +1,17 @@
+import type { Tally } from "./wrapped/year";
+
+export const count = (n: number) => n.toLocaleString("en-US");
+
+export function row(label: string, value: string): string {
+  return `    ${label.padEnd(20)} ${value}`;
+}
+
+export function tallyLabel(tallies: Tally[]): string {
+  if (tallies.length === 0) return "unknown";
+  return tallies.map((t) => `${t.name} ${count(t.count)}`).join(" · ");
+}
+
+export const counted = (n: number, noun: string) =>
+  `${count(n)} ${noun}${n === 1 ? "" : "s"}`;
+
+export const days = (n: number) => counted(n, "day");

package/src/tools/lib/wrapped/habits.ts

@@ -5,6 +5,8 @@ import { dayOf, isUserActivity, ofType, type Tally, tally } from "./year";
 
 export interface WrappedHabits {
   mostActiveHour: Best | null;
+  mostActiveWeekday: Best | null;
+  mostActiveMonth: Best | null;
   nightShare: number | null;
   weekendShare: number | null;
   channels: Tally[];
@@ -13,6 +15,7 @@ export interface WrappedHabits {
 }
 
 interface HourSlot {
+  day: string;
   hour: number;
   weekday: string;
 }
@@ -25,8 +28,9 @@ const WEEKEND = new Set(["Sat", "Sun"]);
 function activeSlots(events: LoggedEvent[]): HourSlot[] {
   const slots = new Map<string, HourSlot>();
   for (const e of events.filter(isUserActivity)) {
+    const day = dayOf(e);
     const clock = localClock(new Date(e.ts));
-    slots.set(`${dayOf(e)} ${clock.hour}`, clock);
+    slots.set(`${day} ${clock.hour}`, { day, ...clock });
   }
   return [...slots.values()];
 }
@@ -35,16 +39,17 @@ function shareOf<T>(items: T[], matches: (item: T) => boolean): number | null {
   return items.length === 0 ? null : items.filter(matches).length / items.length;
 }
 
-function mostActiveHour(slots: HourSlot[]): Best | null {
-  const perHour = new Map<number, number>();
-  for (const { hour } of slots) perHour.set(hour, (perHour.get(hour) ?? 0) + 1);
-  const [top] = [...perHour].sort(([ha, a], [hb, b]) => b - a || ha - hb);
-  return top ? { value: top[1], label: `${String(top[0]).padStart(2, "0")}:00` } : null;
+/** Ties go to the first label, which for hours and months is the earliest. */
+function busiest(slots: HourSlot[], labelOf: (slot: HourSlot) => string): Best | null {
+  const [top] = tally(slots, labelOf);
+  return top ? { value: top.count, label: top.name } : null;
 }
 
+const hourOf = ({ hour }: HourSlot) => `${String(hour).padStart(2, "0")}:00`;
+
 const isNight = ({ hour }: HourSlot) => hour >= NIGHT_FROM || hour < NIGHT_UNTIL;
 
-const channelOf = (turn: LoggedEvent) =>
+export const channelOf = (turn: LoggedEvent) =>
   typeof turn.channel === "string" ? turn.channel : "terminal";
 
 /** Skimming is only measured on a turn that answered a reply. */
@@ -52,7 +57,9 @@ export function wrappedHabits(events: LoggedEvent[]): WrappedHabits {
   const slots = activeSlots(events);
   const turns = ofType(events, "turn");
   return {
-    mostActiveHour: mostActiveHour(slots),
+    mostActiveHour: busiest(slots, hourOf),
+    mostActiveWeekday: busiest(slots, (s) => s.weekday),
+    mostActiveMonth: busiest(slots, (s) => s.day.slice(0, 7)),
     nightShare: shareOf(slots, isNight),
     weekendShare: shareOf(slots, (s) => WEEKEND.has(s.weekday)),
     channels: tally(turns, channelOf),

package/src/tools/lib/wrapped/records.ts

@@ -1,6 +1,6 @@
 import type { LoggedEvent } from "../../../hooks/lib/events";
 import { apiPriceOf } from "../cost-report";
-import { dayOf, isUserActivity, numberOf, ofType } from "./year";
+import { dayOf, daysBetween, isUserActivity, numberOf, ofType } from "./year";
 
 export interface Best {
   value: number;
@@ -17,8 +17,6 @@ export interface WrappedRecords {
   biggestToolBurst: Best | null;
 }
 
-const DAY_MS = 86_400_000;
-
 function best(candidates: Best[]): Best | null {
   return candidates.reduce<Best | null>(
     (top, c) => (top === null || c.value > top.value ? c : top),
@@ -32,10 +30,6 @@ function countBy(events: LoggedEvent[], keyOf: (e: LoggedEvent) => string): Best
   return [...counts].map(([label, value]) => ({ label, value }));
 }
 
-function daysBetween(from: string, to: string): number {
-  return Math.round((Date.parse(to) - Date.parse(from)) / DAY_MS);
-}
-
 function longestProject(events: LoggedEvent[]): Best | null {
   const daysOf = new Map<string, string[]>();
   for (const e of events) {
@@ -71,13 +65,13 @@ function longestAgentRun(events: LoggedEvent[]): Best | null {
   );
 }
 
-interface TurnSpan {
+export interface TurnSpan {
   turn: LoggedEvent;
   inside: LoggedEvent[];
 }
 
 /** Each user turn and what happened in its session until the next one. */
-function turnSpans(events: LoggedEvent[]): TurnSpan[] {
+export function turnSpans(events: LoggedEvent[]): TurnSpan[] {
   const open = new Map<string, TurnSpan>();
   const spans: TurnSpan[] = [];
   const inTimeOrder = [...events].sort((a, b) => a.ts.localeCompare(b.ts));
@@ -92,11 +86,11 @@ function turnSpans(events: LoggedEvent[]): TurnSpan[] {
   return spans;
 }
 
-const whereAndWhen = (turn: LoggedEvent) =>
+export const whereAndWhen = (turn: LoggedEvent) =>
   turn.project === null ? dayOf(turn) : `${dayOf(turn)}, ${turn.project}`;
 
 /** A turn with any call PAL cannot price is left out rather than undercounted. */
-function turnCost({ inside }: TurnSpan): number | null {
+export function turnCost({ inside }: TurnSpan): number | null {
   const prices = ofType(inside, "model_call").map(apiPriceOf);
   if (prices.length === 0 || prices.includes(null)) return null;
   return prices.reduce<number>((sum, p) => sum + (p ?? 0), 0);

package/src/tools/lib/wrapped/render.ts

@@ -1,5 +1,6 @@
 import { labelOfRuntime } from "../../../hooks/lib/agent-registry";
 import type { CostTotals } from "../cost-report";
+import { count, days, row, tallyLabel } from "../report-rows";
 import { fmtDuration } from "../session-usage";
 import { fmtCost } from "../token-report";
 import type { RuntimeCost, WrappedAgents } from "./agents";
@@ -9,12 +10,6 @@ import type { Best, WrappedRecords } from "./records";
 import type { WrappedTotals } from "./totals";
 import type { Tally } from "./year";
 
-const count = (n: number) => n.toLocaleString("en-US");
-
-function row(label: string, value: string): string {
-  return `    ${label.padEnd(20)} ${value}`;
-}
-
 function recordRow(
   label: string,
   record: Best | null,
@@ -25,8 +20,6 @@ function recordRow(
   return `    ${label.padEnd(36)} ${value}`;
 }
 
-const days = (n: number) => `${count(n)} ${n === 1 ? "day" : "days"}`;
-
 export function recordsLines(records: WrappedRecords): string[] {
   return [
     "\n  Records\n",
@@ -53,19 +46,21 @@ export function recordsLines(records: WrappedRecords): string[] {
 const percent = (share: number | null) =>
   share === null ? "unknown" : `${Math.round(share * 100)}%`;
 
-function tallyLabel(tallies: Tally[]): string {
-  if (tallies.length === 0) return "unknown";
-  return tallies.map((t) => `${t.name} ${count(t.count)}`).join(" · ");
+const hours = (n: number) => `${count(n)} active ${n === 1 ? "hour" : "hours"}`;
+
+function busiestLabel(best: Best | null, unit: (n: number) => string): string {
+  return best === null ? "unknown" : `${best.label}  (${unit(best.value)})`;
 }
 
 export function habitsLines(habits: WrappedHabits): string[] {
-  const hour = habits.mostActiveHour;
   return [
     "\n  Habits\n",
     row(
       "most active hour",
-      hour === null ? "unknown" : `${hour.label}  (active on ${days(hour.value)})`
+      busiestLabel(habits.mostActiveHour, (n) => `active on ${days(n)}`)
     ),
+    row("most active weekday", busiestLabel(habits.mostActiveWeekday, hours)),
+    row("most active month", busiestLabel(habits.mostActiveMonth, hours)),
     row("at night (22-06)", percent(habits.nightShare)),
     row("on weekends", percent(habits.weekendShare)),
     row("messages by channel", tallyLabel(habits.channels)),

package/src/tools/lib/wrapped/year.ts

@@ -9,6 +9,12 @@ export function dayOf(event: LoggedEvent): string {
   return localDay(new Date(event.ts));
 }
 
+const DAY_MS = 86_400_000;
+
+export function daysBetween(from: string, to: string): number {
+  return Math.round((Date.parse(to) - Date.parse(from)) / DAY_MS);
+}
+
 export function ofType(events: LoggedEvent[], type: EventType): LoggedEvent[] {
   return events.filter((e) => e.type === type);
 }