paseo-smart-session 1.2.1

package/hooks/ask-compact.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * A `Stop` hook that asks the session to compact itself — and nothing else.
+ *
+ * This is the piece that keeps compaction agent-mandated. The plugin never decides
+ * to compact a session and never sends it a message to say so; it puts the question
+ * at the one moment where acting on it is safe, and the agent answers with its own
+ * tool call. What Paseo sends is the `/compact` the agent asked for.
+ *
+ * `Stop` is the right event for three reasons, all of them verified against Claude
+ * Code 2.1.263 rather than assumed (`RESEARCH.md` §3.4):
+ *
+ *   - it fires at a turn boundary, which is exactly the moment the governor used to
+ *     sit in a fifteen-second poll waiting for;
+ *   - its `additionalContext` is documented as "non-error feedback delivered to the
+ *     model; the conversation continues so the model can act on it", so the ask
+ *     costs no extra turn and needs no `decision: "block"`; and
+ *   - its payload carries `background_tasks`, which is how a hook tells "this
+ *     session is done" from "this session is waiting on work still in flight".
+ *
+ * It stays completely silent unless there is something worth stopping for.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { isEnrolled, occupancy, readSettings } from "./context.mjs";
+import { pluginDir, stateAgeSeconds, statePath } from "./pointer.mjs";
+import { readLedger, recordAsk, shouldAsk } from "./asks.mjs";
+
+/**
+ * A compaction that had to be repeated within minutes is not solving the problem —
+ * something in the loop is refilling the window as fast as it is emptied, and
+ * another compaction just burns tokens on summarizing. Claude Code detects the same
+ * pathology and calls it thrashing.
+ */
+const THRASH_WINDOW_MS = 15 * 60_000;
+
+/** The governor's queue, read directly: a hook must not open a daemon connection. */
+function compactions() {
+  try {
+    const parsed = JSON.parse(readFileSync(join(pluginDir(), "compactions.json"), "utf8"));
+    return Array.isArray(parsed?.items) ? parsed.items : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Already asked and waiting to be delivered: there is nothing to add. */
+function alreadyQueued(items, agentId) {
+  return items.some(
+    (item) => item.agentId === agentId && (item.state === "pending" || item.state === "sending"),
+  );
+}
+
+function thrashing(items, agentId, now = Date.now()) {
+  return items.some(
+    (item) =>
+      item.agentId === agentId &&
+      item.state === "sent" &&
+      item.settledAt !== null &&
+      now - Date.parse(item.settledAt) < THRASH_WINDOW_MS,
+  );
+}
+
+/**
+ * The question.
+ *
+ * On a large window the headline is the token count, not the percentage: "30% full"
+ * sounds like there is plenty of room, and 300,000 tokens does not.
+ *
+ * It has to be answerable in one turn, so it names the tools and says what to do
+ * with each, and it has to be refusable, or it is not a question — hence the
+ * deferral, which the agent is told about in the same breath.
+ */
+function ask({ used, max, pct }, path, age, freshMinutes) {
+  const stale = age === null || age > freshMinutes * 60;
+  const lines = [
+    `Smart Compact: this session holds ${used.toLocaleString()} tokens (${pct}% of a ${max.toLocaleString()}-token window).`,
+    max >= 400_000
+      ? "That is worth compacting now even though the window is nowhere near full — what costs you is the prefix re-read on every turn, not the ceiling."
+      : "This is the point where recall degrades noticeably and every turn re-reads an expensive prefix.",
+    "Compacting is your call, not this plugin's, and nothing will happen unless you ask. Do one of these before you stop:",
+  ];
+
+  if (stale) {
+    lines.push(
+      age === null
+        ? `1. There is no task state on disk yet. Call checkpoint — goal, the step in progress and its exact next action, decisions and why, and every approach already tried and rejected — then call request_compaction. Anything you do not write down is gone after the compaction.`
+        : `1. Your task state at ${path} was last written ${Math.round(age / 60)} minutes ago, so it may predate recent work. Call checkpoint to bring it up to date, then call request_compaction.`,
+    );
+  } else {
+    lines.push(
+      `1. Your task state at ${path} is current, so this is cheap: call request_compaction with a one-line reason. If work remains, ask it to continue (and optionally choose the follow-up message); if the task is finished, ask it not to continue.`,
+    );
+  }
+
+  lines.push(
+    "2. Or, if this is the wrong moment — mid-refactor, a tool sequence half finished, an answer the user is waiting on — call defer_compaction with a reason and you will not be asked again for a while.",
+    "Either way, do it now and then stop. A queued compaction is delivered as a real /compact once this session goes idle; a follow-up turn is sent only if you requested one.",
+  );
+  return lines.join("\n");
+}
+
+/**
+ * What to say instead, when compacting is not the answer.
+ *
+ * Said once, as an ask, so it counts against the same latch: repeating it every
+ * turn would be the nagging this hook exists to avoid.
+ */
+function thrashAdvice({ used, pct }) {
+  return [
+    `Smart Compact: this session refilled to ${used.toLocaleString()} tokens (${pct}%) within minutes of its last compaction.`,
+    "Compacting again would not help — something in this loop is reading far more than it keeps, so the window would refill just as fast and you would pay for another summary.",
+    "Write what you have learned to your state file with checkpoint, then either change the approach so it stops re-reading the same material, or finish and let a fresh session take the rest.",
+  ].join("\n");
+}
+
+function emit(text) {
+  process.stdout.write(
+    `${JSON.stringify({
+      hookSpecificOutput: { hookEventName: "Stop", additionalContext: text },
+      suppressOutput: true,
+    })}\n`,
+  );
+}
+
+async function main() {
+  const raw = await new Promise((resolve) => {
+    let input = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => (input += chunk));
+    process.stdin.on("end", () => resolve(input));
+  });
+
+  let event;
+  try {
+    event = JSON.parse(raw);
+  } catch {
+    return; // Not our business to complain about a malformed event.
+  }
+
+  // Claude Code overrides a hook that keeps a turn alive too many times in a row,
+  // and tells you to check this flag. A second ask would also be arriving into the
+  // turn the first one created, which is not a boundary at all.
+  if (event.stop_hook_active === true) return;
+
+  // Subagents have their own short-lived windows and their own stop conditions.
+  if (event.agent_id !== undefined && event.agent_id !== null) return;
+
+  // "Stopped" and "waiting for work that is still running" are different states.
+  // Compacting through the second one discards the context that work reports into.
+  if (Array.isArray(event.background_tasks) && event.background_tasks.length > 0) return;
+
+  const transcriptPath = event.transcript_path;
+  const sessionId = event.session_id;
+  if (typeof transcriptPath !== "string" || typeof sessionId !== "string") return;
+
+  const settings = readSettings();
+  if (!settings.enabled) return;
+
+  const agentId = process.env.PASEO_AGENT_ID ?? null;
+  if (!isEnrolled(agentId, settings)) return;
+
+  const now = occupancy(transcriptPath, settings);
+  if (now === null || now.pct < now.profile.compact) return;
+
+  const ledger = readLedger(sessionId);
+  if (!shouldAsk(ledger, now.pct)) return;
+
+  const queue = compactions();
+  if (alreadyQueued(queue, agentId)) return;
+
+  const path = statePath();
+  const age = stateAgeSeconds(path);
+  const text = thrashing(queue, agentId)
+    ? thrashAdvice(now)
+    : ask(now, path, age, settings.freshStateMinutes);
+
+  // Recorded only after it has reached stdout: a latch set on an ask that was never
+  // delivered would silence the next one for nothing.
+  emit(text);
+  recordAsk(sessionId, ledger, now.pct);
+}
+
+void main();

package/hooks/asks.mjs

@@ -0,0 +1,117 @@
+/**
+ * The record of what this session has already been asked, and what it answered.
+ *
+ * Asking once and never again lets a session drift; asking every turn is nagging.
+ * So the ask is latched, re-armed by growth rather than by a clock alone, and can
+ * be switched off for a while by the agent itself — that last part is what makes it
+ * a question instead of an announcement.
+ *
+ * One file per agent rather than one shared file. `state/<agentId>.md` already
+ * works that way, and it means the `Stop` hook and the `defer_compaction` tool —
+ * two separate processes — can never be writing the same file at the same moment.
+ */
+
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+
+import { pluginDir } from "./pointer.mjs";
+
+/** Asks per compaction epoch, after which the session is left to its own judgement. */
+export const MAX_ASKS = 3;
+
+/**
+ * Further occupancy, in percentage points of the window, that re-arms the ask.
+ *
+ * Time alone is the wrong trigger: a session parked at 31% for an hour has not
+ * changed its situation, and one that went 31% to 55% in ten minutes plainly has.
+ */
+export const RE_ASK_GROWTH_PCT = 10;
+
+const EMPTY = { askCount: 0, lastAskedAt: null, askedAtPct: null, deferredUntil: null, deferReason: null };
+
+/**
+ * Keyed by Paseo agent id where there is one, because that survives compaction
+ * whatever Claude Code decides to do with the session id.
+ */
+export function ledgerPath(sessionId) {
+  const agentId = process.env.PASEO_AGENT_ID;
+  const key = agentId !== undefined && agentId !== "" ? agentId : sessionId;
+  if (typeof key !== "string" || key === "") return null;
+  return join(pluginDir(), "asks", `${key.replace(/[^A-Za-z0-9_-]/g, "_")}.json`);
+}
+
+export function readLedger(sessionId) {
+  const path = ledgerPath(sessionId);
+  if (path === null) return { ...EMPTY };
+  try {
+    return { ...EMPTY, ...JSON.parse(readFileSync(path, "utf8")) };
+  } catch {
+    return { ...EMPTY };
+  }
+}
+
+export function writeLedger(sessionId, ledger) {
+  const path = ledgerPath(sessionId);
+  if (path === null) return;
+  try {
+    mkdirSync(join(pluginDir(), "asks"), { recursive: true });
+    const temp = `${path}.${randomUUID()}.tmp`;
+    writeFileSync(temp, JSON.stringify(ledger), "utf8");
+    renameSync(temp, path);
+  } catch {
+    // A hook that cannot persist its latch must still not break the turn.
+  }
+}
+
+/**
+ * Forgets everything, because the window just emptied.
+ *
+ * A compaction is a new epoch: the occupancy the last ask was about is gone, and a
+ * session that fills up again deserves to be asked again.
+ */
+export function resetLedger(sessionId) {
+  const path = ledgerPath(sessionId);
+  if (path === null) return;
+  try {
+    rmSync(path, { force: true });
+  } catch {
+    // A stale ledger costs one missed ask, never a failed turn.
+  }
+}
+
+/** The agent's own answer: not now, and here is for how long. */
+export function defer(sessionId, minutes, reason) {
+  const ledger = readLedger(sessionId);
+  const until = new Date(Date.now() + minutes * 60_000).toISOString();
+  writeLedger(sessionId, { ...ledger, deferredUntil: until, deferReason: reason });
+  return until;
+}
+
+/**
+ * Whether to ask, given what has already been said and how much has changed.
+ *
+ * `pct` is the occupancy now; `askedAtPct` the occupancy the last ask was about.
+ */
+export function shouldAsk(ledger, pct, now = Date.now()) {
+  if (ledger.deferredUntil !== null) {
+    const until = Date.parse(ledger.deferredUntil);
+    if (Number.isFinite(until) && now < until) return false;
+  }
+  if (ledger.askCount >= MAX_ASKS) return false;
+  if (ledger.askedAtPct === null) return true;
+  return pct >= ledger.askedAtPct + RE_ASK_GROWTH_PCT;
+}
+
+/** Records that the question was actually put to the model. */
+export function recordAsk(sessionId, ledger, pct) {
+  writeLedger(sessionId, {
+    ...ledger,
+    askCount: ledger.askCount + 1,
+    lastAskedAt: new Date().toISOString(),
+    askedAtPct: pct,
+    // An answered ask clears the deferral it was waiting out.
+    deferredUntil: null,
+    deferReason: null,
+  });
+}

package/hooks/context-threshold.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * A PostToolUse hook that tells the agent how full it is — but only when that has
+ * just become worth saying.
+ *
+ * Sensing is useless if the agent has to remember to ask. This runs after every
+ * tool call, stays completely silent below the first threshold, and injects one
+ * short line the moment context crosses each band. Each level fires once per
+ * compaction epoch, so a long session gets three sentences, not three hundred.
+ *
+ * It describes; it never asks for anything. Deciding that a session should compact
+ * belongs at a turn boundary, and that is `ask-compact.mjs` on `Stop`.
+ *
+ * It reads the transcript rather than asking Paseo, so it works in any Claude Code
+ * session, and it reads only the tail of it, because this runs on the hot path.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { BANDS, DEFAULT_THRESHOLDS, occupancy, readSettings } from "./context.mjs";
+import { clearPending, pluginDir, readPending, statePath } from "./pointer.mjs";
+
+function latchPathFor(sessionId) {
+  return join(pluginDir(), "thresholds", `${sessionId}.json`);
+}
+
+function readLatch(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return { fired: [], lastUsed: 0 };
+  }
+}
+
+function writeLatch(path, latch) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(latch), "utf8");
+  } catch {
+    // A hook that cannot persist its latch must still not break the turn.
+  }
+}
+
+/**
+ * `band` chooses the urgency; `pct` and `used` describe the situation.
+ *
+ * On a large window the headline is the token count, not the percentage: "30% full"
+ * sounds like there is plenty of room, and 300,000 tokens does not.
+ */
+function advice(band, pct, used, max, path) {
+  const large = max >= DEFAULT_THRESHOLDS.largeWindowFrom;
+  const lines = [
+    `Context holds ${used.toLocaleString()} tokens (${pct}% of a ${max.toLocaleString()}-token window).`,
+  ];
+
+  if (band === "compact") {
+    lines.push(
+      large
+        ? "That is a large enough context to be worth compacting now, even though the window is nowhere near full — what costs you is the prefix re-read on every turn, not the ceiling. Finish the step you are on and make sure your durable task state is on disk."
+        : "This is the point where recall degrades noticeably and every turn re-reads an expensive prefix. Finish the step you are on and write your durable task state to disk — do not start a new large step first.",
+    );
+  } else if (band === "closing") {
+    lines.push(
+      "Start closing out the current step rather than opening a new one. Make sure your durable task state — goal, current step and its next action, decisions and why, and every approach already tried and rejected — is written to disk, not only held in this conversation.",
+    );
+  } else {
+    lines.push(
+      "Nothing is wrong yet. This is the moment to make sure your task state is on disk, so that compacting later is cheap rather than lossy.",
+    );
+  }
+
+  if (path !== null) lines.push(`Your state file for this task: ${path}`);
+  else lines.push("If you have not chosen a state file for this task yet, choose one now and write to it.");
+  return lines.join(" ");
+}
+
+async function main() {
+  const raw = await new Promise((resolve) => {
+    let input = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => (input += chunk));
+    process.stdin.on("end", () => resolve(input));
+  });
+
+  let event;
+  try {
+    event = JSON.parse(raw);
+  } catch {
+    return; // Not our business to complain about a malformed event.
+  }
+
+  // Subagents have their own short-lived windows and their own stop conditions;
+  // warning them about the main thread's occupancy would be noise.
+  if (event.agent_id !== undefined && event.agent_id !== null) return;
+  const transcriptPath = event.transcript_path;
+  const sessionId = event.session_id;
+  if (typeof transcriptPath !== "string" || typeof sessionId !== "string") return;
+
+  // A compaction may have left a state-file pointer that no other hook could
+  // deliver. Said first, because it changes what the agent thinks it knows.
+  const parts = [];
+  const pending = readPending(sessionId);
+  if (pending !== null) parts.push(pending);
+
+  const now = occupancy(transcriptPath, readSettings());
+  if (now === null) return emit(sessionId, parts, pending);
+
+  const latchPath = latchPathFor(sessionId);
+  const latch = readLatch(latchPath);
+
+  // A compaction resets the epoch: the window emptied, so the warnings should be
+  // available again. Detected as a large drop rather than any drop, because usage
+  // wobbles by a few tokens between turns.
+  if (latch.lastUsed > 0 && now.used < latch.lastUsed * 0.6) latch.fired = [];
+  latch.lastUsed = now.used;
+
+  const reached = BANDS.filter((band) => now.pct >= now.profile[band]);
+  const crossed = reached.filter((band) => !latch.fired.includes(band));
+  if (crossed.length === 0) {
+    writeLatch(latchPath, latch);
+    return emit(sessionId, parts, pending);
+  }
+
+  // A session that jumped two bands in one turn hears the more urgent one.
+  const band = crossed[crossed.length - 1];
+  latch.fired = [...new Set([...latch.fired, ...crossed])];
+  writeLatch(latchPath, latch);
+
+  parts.push(advice(band, now.pct, now.used, now.max, statePath()));
+  return emit(sessionId, parts, pending);
+}
+
+/**
+ * Writes whatever there is to say, and only then forgets the pending pointer:
+ * clearing it before it reaches stdout would lose it on any later failure.
+ */
+function emit(sessionId, parts, pending) {
+  if (parts.length === 0) return;
+  process.stdout.write(
+    `${JSON.stringify({
+      hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: parts.join("\n\n") },
+      suppressOutput: true,
+    })}\n`,
+  );
+  if (pending !== null) clearPending(sessionId);
+}
+
+void main();

package/hooks/context.mjs

@@ -0,0 +1,233 @@
+/**
+ * What every hook needs to know about the session it is running in.
+ *
+ * Two hooks now answer "how full is this context" — `context-threshold.mjs` on
+ * `PostToolUse` and `ask-compact.mjs` on `Stop` — and they must not disagree. One
+ * reading them differently from the other would mean the agent hears the number and
+ * the advice from two different sessions.
+ *
+ * Everything here reads the tail of a file rather than the whole of it: these run
+ * on the hot path, and the newest row is the only one that matters.
+ */
+
+import { closeSync, fstatSync, openSync, readdirSync, readFileSync, readSync } from "node:fs";
+import { join } from "node:path";
+
+import { pluginDir } from "./pointer.mjs";
+
+/** Enough tail to contain the last assistant message in any realistic transcript. */
+const TAIL_BYTES = 256 * 1024;
+
+/**
+ * Defaults mirroring thresholds.shared.ts, used when the plugin has not written a
+ * settings file yet. Kept in sync by a test that runs the hooks and checks where
+ * they fire against the shared module's numbers.
+ *
+ * Two profiles because a percentage of the window is the wrong unit on its own:
+ * what tires a context is the absolute prefix re-read every turn, so 30% of a
+ * million tokens is a heavier context than 85% of two hundred thousand.
+ */
+export const DEFAULT_THRESHOLDS = {
+  largeWindowFrom: 400_000,
+  large: { notice: 15, closing: 22, compact: 30 },
+  small: { notice: 60, closing: 75, compact: 85 },
+};
+
+export const BANDS = ["notice", "closing", "compact"];
+
+export const DEFAULT_SETTINGS = {
+  enabled: true,
+  showPill: true,
+  autoEnrol: true,
+  freshStateMinutes: 30,
+  thresholds: DEFAULT_THRESHOLDS,
+};
+
+/** The plugin's settings are the single source of truth when they exist. */
+export function readSettings() {
+  try {
+    const raw = JSON.parse(readFileSync(join(pluginDir(), "settings.json"), "utf8"));
+    const merged = { ...DEFAULT_THRESHOLDS, ...(raw.thresholds ?? {}) };
+    return {
+      // Absent means an install that predates the switch, which was always meant
+      // to be on once it could only ask rather than act.
+      enabled: raw.enabled !== false,
+      showPill: raw.showPill !== false,
+      autoEnrol: raw.autoEnrol !== false,
+      freshStateMinutes:
+        typeof raw.freshStateMinutes === "number" && raw.freshStateMinutes > 0
+          ? raw.freshStateMinutes
+          : DEFAULT_SETTINGS.freshStateMinutes,
+      thresholds: {
+        largeWindowFrom: merged.largeWindowFrom ?? DEFAULT_THRESHOLDS.largeWindowFrom,
+        large: { ...DEFAULT_THRESHOLDS.large, ...(merged.large ?? {}) },
+        small: { ...DEFAULT_THRESHOLDS.small, ...(merged.small ?? {}) },
+      },
+    };
+  } catch {
+    return DEFAULT_SETTINGS;
+  }
+}
+
+export function profileFor(maxTokens, thresholds) {
+  return maxTokens >= thresholds.largeWindowFrom ? thresholds.large : thresholds.small;
+}
+
+/**
+ * Whether this agent is one the governor may speak to.
+ *
+ * The same rule settings.server.ts resolves, duplicated here because a hook on the
+ * hot path must not open a daemon connection to answer it: an explicit answer in
+ * `enrolment.json` outranks the state-file inference in both directions, and the
+ * inference itself only counts while `autoEnrol` is on.
+ */
+export function isEnrolled(agentId, settings = readSettings()) {
+  if (typeof agentId !== "string" || agentId === "") return false;
+  try {
+    const overrides = JSON.parse(readFileSync(join(pluginDir(), "enrolment.json"), "utf8"));
+    if (typeof overrides?.[agentId] === "boolean") return overrides[agentId];
+  } catch {
+    // No file, or one we cannot read: nobody has overridden anything.
+  }
+  if (!settings.autoEnrol) return false;
+  try {
+    return readdirSync(join(pluginDir(), "state")).includes(`${agentId}.md`);
+  } catch {
+    return false;
+  }
+}
+
+/** The tail of a file as text, or null if it cannot be read. */
+function tail(path, bytes) {
+  let fd;
+  try {
+    fd = openSync(path, "r");
+  } catch {
+    return null;
+  }
+  try {
+    const size = fstatSync(fd).size;
+    const length = Math.min(size, bytes);
+    const buffer = Buffer.allocUnsafe(length);
+    readSync(fd, buffer, 0, length, size - length);
+    return buffer.toString("utf8");
+  } catch {
+    return null;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * Context occupancy from the last assistant message's usage.
+ *
+ * input + cache_read + cache_creation + output is the same arithmetic Claude Code
+ * itself documents for a resumed session's `context_tokens`, so it is the
+ * sanctioned way to ask "how much of the window is currently occupied".
+ */
+export function readContextTokens(transcriptPath) {
+  const text = tail(transcriptPath, TAIL_BYTES);
+  if (text === null) return null;
+  const lines = text.split("\n");
+
+  // Backwards: the newest assistant message wins, and a partial first line from
+  // slicing mid-file simply fails to parse and is skipped.
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const line = lines[index];
+    if (line === undefined || line === "" || !line.includes('"usage"')) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (entry?.type !== "assistant") continue;
+    // A subagent's usage is its own window, not the main thread's.
+    if (entry.isSidechain === true) continue;
+    const usage = entry.message?.usage;
+    if (usage === undefined) continue;
+    const used =
+      (usage.input_tokens ?? 0) +
+      (usage.cache_read_input_tokens ?? 0) +
+      (usage.cache_creation_input_tokens ?? 0) +
+      (usage.output_tokens ?? 0);
+    return { used, model: entry.message?.model ?? null };
+  }
+  return null;
+}
+
+/**
+ * Models whose context window is not the current default of 1M.
+ *
+ * The transcript records the resolved model id (`claude-opus-5`), never the config
+ * alias (`opus[1m]`), so the suffix is not a signal. Every current Opus, Sonnet and
+ * Fable model has a 1M window; Haiku and the older generations do not.
+ */
+const SMALL_WINDOW = /haiku|-3-|sonnet-3|opus-3|sonnet-4-5|opus-4-5|sonnet-4-20|opus-4-20/;
+
+/**
+ * The window size Paseo reported for this agent, from the recorder's own log.
+ *
+ * Read from the tail, like the transcript: this is the hot path, and the newest row
+ * is the only one that matters.
+ */
+function recordedWindow() {
+  const agentId = process.env.PASEO_AGENT_ID;
+  if (agentId === undefined || agentId === "") return null;
+  const month = new Date().toISOString().slice(0, 7);
+  const text = tail(join(pluginDir(), `context-${month}.jsonl`), 64 * 1024);
+  if (text === null) return null;
+
+  const lines = text.split("\n");
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const line = lines[index];
+    if (line === undefined || !line.includes(agentId)) continue;
+    try {
+      const row = JSON.parse(line);
+      if (row.agentId === agentId && typeof row.maxTokens === "number" && row.maxTokens > 0) {
+        return row.maxTokens;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * The window size for this session.
+ *
+ * Getting this wrong is worse than not warning at all: assuming 200k on a 1M
+ * session warns at a fifth of the real occupancy and reports negative headroom.
+ * So the first choice is what Paseo actually measured for this agent — recorded by
+ * the plugin, read from the tail of its log — and the model table is the fallback.
+ */
+export function windowFor(model) {
+  const override = Number(process.env.SMART_SESSION_CONTEXT_WINDOW ?? "");
+  if (Number.isFinite(override) && override > 0) return override;
+
+  const recorded = recordedWindow();
+  if (recorded !== null) return recorded;
+
+  if (typeof model === "string" && SMALL_WINDOW.test(model)) return 200_000;
+  return 1_000_000;
+}
+
+/**
+ * Occupancy, the window it is measured against, and the bands that apply.
+ *
+ * Returns null when the transcript says nothing yet — a session with no completed
+ * assistant turn has no usage to read, and guessing would be worse than silence.
+ */
+export function occupancy(transcriptPath, settings = readSettings()) {
+  const reading = readContextTokens(transcriptPath);
+  if (reading === null) return null;
+  const max = windowFor(reading.model);
+  return {
+    used: reading.used,
+    max,
+    model: reading.model,
+    pct: Math.floor((reading.used / max) * 100),
+    profile: profileFor(max, settings.thresholds),
+  };
+}