pi-ca-leash 0.10.0

package/extensions/persistence.test.ts

@@ -0,0 +1,68 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createAttentionLedger } from "./support.ts";
+import { readAttentionLedger, serializeAttentionLedger, writeAttentionLedger } from "./persistence.ts";
+
+test("attention ledger persistence round-trips ack and snooze state", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "pi-ca-leash-attention-"));
+  const file = join(dir, "attention-ledger.json");
+  const ledger = {
+    runs: {
+      run1: {
+        note: "Needs attention: idle for 6000ms",
+        lastNotifiedNote: "Needs attention: idle for 6000ms",
+        acknowledgedNote: "Needs attention: idle for 6000ms",
+        snoozedUntil: 12_345,
+      },
+    },
+  };
+
+  await writeAttentionLedger(file, ledger);
+  const restored = await readAttentionLedger(file);
+  assert.deepEqual(restored, ledger);
+});
+
+test("missing or invalid attention ledger falls back to empty state", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "pi-ca-leash-attention-"));
+  const file = join(dir, "attention-ledger.json");
+
+  assert.deepEqual(await readAttentionLedger(file), createAttentionLedger());
+
+  await writeFile(file, "{ definitely-not-json\n", "utf8");
+  assert.deepEqual(await readAttentionLedger(file), createAttentionLedger());
+});
+
+test("attention ledger persistence sanitizes malformed entries", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "pi-ca-leash-attention-"));
+  const file = join(dir, "attention-ledger.json");
+
+  await writeFile(file, JSON.stringify({
+    runs: {
+      keep: {
+        note: "Needs attention: idle for 9000ms",
+        lastNotifiedNote: "Needs attention: idle for 9000ms",
+        acknowledgedNote: 42,
+        snoozedUntil: "later",
+      },
+      drop1: null,
+      drop2: { acknowledgedNote: "missing note" },
+    },
+  }), "utf8");
+
+  const restored = await readAttentionLedger(file);
+  assert.deepEqual(restored, {
+    runs: {
+      keep: {
+        note: "Needs attention: idle for 9000ms",
+        lastNotifiedNote: "Needs attention: idle for 9000ms",
+      },
+    },
+  });
+
+  const serialized = serializeAttentionLedger(restored);
+  assert.equal(JSON.parse(serialized).runs.keep.note, "Needs attention: idle for 9000ms");
+  assert.match(await readFile(file, "utf8"), /drop1/);
+});

package/extensions/persistence.ts

@@ -0,0 +1,67 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { AttentionLedger, AttentionLedgerEntry } from "./support.js";
+import { createAttentionLedger } from "./support.js";
+
+export async function readAttentionLedger(path: string): Promise<AttentionLedger> {
+  try {
+    const raw = await readFile(path, "utf8");
+    return normalizeAttentionLedger(JSON.parse(raw));
+  } catch {
+    return createAttentionLedger();
+  }
+}
+
+export async function writeAttentionLedger(path: string, ledger: AttentionLedger): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const tempPath = `${path}.${randomUUID()}.tmp`;
+  await writeFile(tempPath, `${serializeAttentionLedger(ledger)}\n`, "utf8");
+  await rename(tempPath, path);
+}
+
+export function serializeAttentionLedger(ledger: AttentionLedger): string {
+  return JSON.stringify(normalizeAttentionLedger(ledger), null, 2);
+}
+
+function normalizeAttentionLedger(value: unknown): AttentionLedger {
+  const result = createAttentionLedger();
+  if (!isRecord(value) || !isRecord(value.runs)) {
+    return result;
+  }
+
+  for (const [runId, entry] of Object.entries(value.runs)) {
+    const normalized = normalizeAttentionLedgerEntry(entry);
+    if (normalized) {
+      result.runs[runId] = normalized;
+    }
+  }
+
+  return result;
+}
+
+function normalizeAttentionLedgerEntry(value: unknown): AttentionLedgerEntry | undefined {
+  if (!isRecord(value) || typeof value.note !== "string" || value.note.trim().length === 0) {
+    return undefined;
+  }
+
+  const entry: AttentionLedgerEntry = {
+    note: value.note,
+  };
+
+  if (typeof value.lastNotifiedNote === "string") {
+    entry.lastNotifiedNote = value.lastNotifiedNote;
+  }
+  if (typeof value.acknowledgedNote === "string") {
+    entry.acknowledgedNote = value.acknowledgedNote;
+  }
+  if (typeof value.snoozedUntil === "number" && Number.isFinite(value.snoozedUntil) && value.snoozedUntil > 0) {
+    entry.snoozedUntil = value.snoozedUntil;
+  }
+
+  return entry;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/extensions/prompts/extension-log-tool.md

@@ -0,0 +1,5 @@
+Record structured pi-ca-leash extension feedback in .pi-ca-leash/log.md.
+- Use `extension_log` for product friction, confusing UX, missing guidance, brittle flows, poor defaults, repeated agent mistakes caused by the extension, or runtime behavior that should be smoothed.
+- Do not use it for normal task notes, user project TODOs, or every expected runtime failure.
+- Do not log secrets, credentials, full private transcripts, or unnecessary user-private content.
+- Keep entries concise and actionable.

package/extensions/prompts/peer-ask-tool.md

@@ -0,0 +1,5 @@
+Ask an existing peer for a status update, follow-up, or delegated result. Optionally pass model to switch the peer model persistently.
+- Use `peer_ask` only with an existing peer name.
+- Prefer concise direct asks because the peer reply is returned into the current turn.
+- Call `runtime_models` first when you need the supported model ids for a driver.
+- Pass `model` when you want this peer to switch models for this and future asks.

package/extensions/prompts/peer-bridge-system.md

@@ -0,0 +1,4 @@
+You are a long-lived coding agent worker reached through intercom-style messages.
+Treat new messages as continuation of same session, not fresh bootstrap.
+For asks and replies, answer concisely and directly.
+When you finish handling one inbound message, end in a clean idle state.

package/extensions/prompts/peer-history-tool.md

@@ -0,0 +1,3 @@
+Read older peer transcript history when you need to scroll back instead of asking the peer to repeat itself.
+- Use `peer_history` for audit/debug context, not for polling live completion.
+- Prefer small `limit` values.

package/extensions/prompts/peer-init-user-help.md

@@ -0,0 +1,11 @@
+Peer mode is active.
+
+Common commands:
+- `/peer start <prompt>` starts a background peer.
+- `/peer ask <name> | <message>` waits for a reply.
+- `/peer send <name> | <message>` sends fire-and-forget work.
+- `/peer list` shows peers and current state.
+- `/peer history <name>` scrolls a peer transcript.
+- `/peer models` shows model ids and aliases.
+- `/peer dashboard` opens the peer dashboard.
+- `/peer help` shows full command help.

package/extensions/prompts/peer-init.md

@@ -0,0 +1,17 @@
+How to work with pi-ca-leash:
+- You are the orchestrator in the driver's seat. Keep the plan, state, decisions, and final judgment in the main turn.
+- Treat peers as long-lived coding agents you coordinate through short handoffs, either in parallel or across many sequential sessions.
+- You can run multiple specialized peers at the same time when their work is independent, for example one planning/review peer and one implementation peer.
+- Most peers work in the same repository checkout. Prefer file-based handoffs through changed files, notes, tests, and diffs when that is cheaper than copying context through prompts and replies.
+- Optimize for control-plane tokens: read the latest peer relay first, then inspect only the evidence needed to decide the next step.
+- Delegate bounded work with a clear output: investigate one area, review one change, implement one scoped fix, or summarize one source.
+- Do not delegate work that blocks your immediate next step unless the peer can run while you make progress elsewhere.
+- It is okay to wait passively for a peer. Peer completion, blocked, or failure states are automatically relayed into the main chat with the peer's latest visible message.
+- Do not poll peers with repeated `peer_list`, `peer_history`, or `peer_ask` status checks. Use `peer_list` only when you need names or states.
+- Use `peer_history` like a human scrolling back in a chat: start with a small recent page, follow cursors only as needed, and do not reread full transcripts by default.
+- Prompt peers to return compact, verifiable outputs: changed files, commands run, test results, key findings, blockers, and residual risk. Do not ask them to paste large logs unless necessary.
+- Verification is risk-based. For low-risk read-only work, sanity-check the conclusion; for code changes, inspect the diff and relevant tests; for high-risk architecture, security, data loss, or broad edits, do deeper verification or assign an independent review peer.
+- When a peer returns, integrate useful parts and discard weak or stale assumptions. The orchestrator owns the final answer.
+- Choose models by risk and cost: strongest for architecture, ambiguous debugging, and risky edits; coding-focused for implementation; cheaper or faster for narrow checks, summaries, and parallel exploration.
+- Treat model catalog data as advisory. The local runtime decides actual availability.
+- While pi-ca-leash is pre-1.0, record concise extension friction, confusing guidance, bad defaults, brittle flows, or repeated interaction problems with `extension_log`.

package/extensions/prompts/peer-interrupt-tool.md

@@ -0,0 +1,2 @@
+Interrupt a peer that is busy or stuck. Prefer this before stopping/killing a peer.
+- Use `peer_interrupt` only when the peer appears stuck, has gone down the wrong path, or the user redirects the task.

package/extensions/prompts/peer-list-tool.md

@@ -0,0 +1,3 @@
+List current long-lived runtime-backed peers and their summarized activity.
+- Use `peer_list` before asking or stopping a peer when you need current names and states.
+- Do not poll repeatedly just to wait for completion; peer completions are relayed automatically.

package/extensions/prompts/peer-no-babysitting.md

@@ -0,0 +1,6 @@
+How to work with this peer:
+- Treat it as an async worker/subagent.
+- Do not poll it with peer_list, peer_history, or repeated peer_ask status checks.
+- Continue your own work or wait passively.
+- The peer will send a follow-up into the main context when it is done, blocked, or failed.
+- Only contact the peer if the user explicitly asks, or if the peer asks for input.

package/extensions/prompts/peer-send-tool.md

@@ -0,0 +1,5 @@
+Send input to a peer without waiting for the reply. Use this when the peer will report back asynchronously.
+- Use `peer_send` instead of `peer_ask` when you do not need an immediate reply.
+- Do not use it to poll for status; wait for automated peer updates.
+- If the peer is busy, wait for its automated update before sending more input.
+- Call `runtime_models` first when you need the supported model ids for a driver.

package/extensions/prompts/peer-start-tool.md

@@ -0,0 +1,7 @@
+Start a long-lived runtime-backed peer for delegated work. Returns peer name, state, session id, driver, model, cwd, and latest visible peer reply when available.
+- Use `peer_start` when you want a reusable long-lived peer instead of solving the task in the current turn.
+- Pass `name` only when you need a stable explicit peer name; otherwise let the tool auto-name from prompt.
+- Pass `driver` when you need to force `claude-sdk` or `codex-cli` for this peer instead of using the extension default.
+- Call `runtime_models` first when you need the supported model ids for a driver.
+- Pass `model` and `cwd` when you need a specific model and working directory.
+- Keep bootstrap prompts scoped. If the tool reports a prompt size warning, start a smaller peer and point it at files instead of pasting large context.

package/extensions/prompts/peer-stop-tool.md

@@ -0,0 +1,3 @@
+Stop a named peer when its work is done or you want to shut it down. Can also stop all peers with explicit confirmation.
+- Use `peer_stop` when retained peer state is no longer useful.
+- Stopping all peers requires `all: true` and `confirmAll: true`.

package/extensions/prompts/runtime-models-tool.md

@@ -0,0 +1,6 @@
+Inspect available model ids for claude-sdk and codex-cli before passing a model override to peer_start, peer_ask, subagent_run, or team_spawn.
+- Use `runtime_models` before choosing a non-default model.
+- Use `driver` to narrow results to `claude-sdk` or `codex-cli`.
+- Default output is a short recommended list with advisory use cases; pass `verbose: true` only when you need every bundled model id.
+- The report includes supported shorthand aliases. For example, Claude aliases such as `sonnet`, `opus`, and `haiku` are resolved to concrete model ids before launch.
+- Catalog entries are advisory; provider and CLI entitlements can drift, so unknown model ids are passed through to the runtime.

package/extensions/prompts/subagent-list-tool.md

@@ -0,0 +1,3 @@
+List retained local subagent runs when you need run ids, drivers, states, or agent names.
+- Use `subagent_list` to discover run ids before `subagent_status`.
+- Treat attention notes as operator-facing diagnostics.

package/extensions/prompts/subagent-run-tool.md

@@ -0,0 +1,6 @@
+Run a delegated subagent task through the local backend. Supports driver, model, cwd, and optional async execution.
+- Use `subagent_run` when you need a bounded delegated run instead of a reusable peer.
+- Pass `driver` to force `claude-sdk` or `codex-cli` for this run instead of using the extension default.
+- Call `runtime_models` first when you need the supported model ids for a driver.
+- Pass `async: true` when you want to launch a background run and inspect it later with `subagent_status` or `subagent_list`.
+- Keep delegated tasks bounded. If the tool reports a prompt size warning, split the run into smaller slices.

package/extensions/prompts/subagent-status-tool.md

@@ -0,0 +1,2 @@
+Inspect one retained local subagent run by run id.
+- Use `subagent_status` for details after `subagent_run` async mode or `subagent_list`.

package/extensions/prompts/team-list-tool.md

@@ -0,0 +1,2 @@
+List teammates and team tasks when you need the current retained local team state.
+- Use `team_list` before assigning or stopping when you need current teammate names and states.

package/extensions/prompts/team-message-tool.md

@@ -0,0 +1,2 @@
+Message an existing teammate when you need a follow-up without creating a new task record.
+- Use `team_message` for coordination, clarification, or lightweight status requests.

package/extensions/prompts/team-spawn-tool.md

@@ -0,0 +1,5 @@
+Spawn a persistent teammate when you want a named worker you can task or message repeatedly.
+- Use `team_spawn` for a persistent named worker, not for one-off bounded work.
+- Pass `driver` to force `claude-sdk` or `codex-cli` for this teammate instead of using the extension default.
+- Call `runtime_models` first when you need the supported model ids for a driver.
+- Keep the teammate bootstrap prompt compact; give detailed work through later `team_task` or `team_message` calls.

package/extensions/prompts/team-stop-tool.md

@@ -0,0 +1,2 @@
+Stop a named teammate when its work is done or you want to tear down its retained session.
+- Use `team_stop` only when retained teammate state is no longer needed.

package/extensions/prompts/team-task-tool.md

@@ -0,0 +1,3 @@
+Assign a task to an existing teammate when you want retained worker state across tasks.
+- Use `team_task` only after `team_spawn` or `team_list` confirms the teammate exists.
+- Give a concise title and concrete details.

package/extensions/prompts.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+function readPrompt(name: string): string {
+  return readFileSync(fileURLToPath(new URL(`./prompts/${name}.md`, import.meta.url)), "utf8").trim();
+}
+
+function readPromptBlock(name: string): { snippet: string; guidelines: string[] } {
+  const lines = readPrompt(name)
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const [snippet = "", ...guidelines] = lines;
+  return {
+    snippet,
+    guidelines: guidelines.map((line) => line.replace(/^- /, "")),
+  };
+}
+
+export const PEER_BRIDGE_APPEND_SYSTEM_PROMPT = readPrompt("peer-bridge-system").replace(/\s*\n\s*/g, " ");
+export const PEER_NO_BABYSITTING_GUIDANCE = readPrompt("peer-no-babysitting");
+export const PEER_INIT_GUIDE = readPrompt("peer-init");
+export const PEER_INIT_USER_HELP = readPrompt("peer-init-user-help");
+
+export const RUNTIME_MODELS_TOOL_PROMPT = readPromptBlock("runtime-models-tool");
+export const EXTENSION_LOG_TOOL_PROMPT = readPromptBlock("extension-log-tool");
+export const PEER_START_TOOL_PROMPT = readPromptBlock("peer-start-tool");
+export const PEER_ASK_TOOL_PROMPT = readPromptBlock("peer-ask-tool");
+export const PEER_HISTORY_TOOL_PROMPT = readPromptBlock("peer-history-tool");
+export const PEER_INTERRUPT_TOOL_PROMPT = readPromptBlock("peer-interrupt-tool");
+export const PEER_LIST_TOOL_PROMPT = readPromptBlock("peer-list-tool");
+export const PEER_SEND_TOOL_PROMPT = readPromptBlock("peer-send-tool");
+export const SUBAGENT_RUN_TOOL_PROMPT = readPromptBlock("subagent-run-tool");
+export const PEER_STOP_TOOL_PROMPT = readPromptBlock("peer-stop-tool");
+export const SUBAGENT_LIST_TOOL_PROMPT = readPromptBlock("subagent-list-tool");
+export const SUBAGENT_STATUS_TOOL_PROMPT = readPromptBlock("subagent-status-tool");
+export const TEAM_SPAWN_TOOL_PROMPT = readPromptBlock("team-spawn-tool");
+export const TEAM_LIST_TOOL_PROMPT = readPromptBlock("team-list-tool");
+export const TEAM_MESSAGE_TOOL_PROMPT = readPromptBlock("team-message-tool");
+export const TEAM_STOP_TOOL_PROMPT = readPromptBlock("team-stop-tool");
+export const TEAM_TASK_TOOL_PROMPT = readPromptBlock("team-task-tool");

package/extensions/runtime-driver.test.ts

@@ -0,0 +1,38 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  DEFAULT_RUNTIME_DRIVER_ENV,
+  parseRuntimeDriverName,
+  resolveExtensionRuntimeDriverConfig,
+} from "./runtime-driver.ts";
+
+test("parseRuntimeDriverName accepts supported names and rejects others", () => {
+  assert.equal(parseRuntimeDriverName("claude-sdk"), "claude-sdk");
+  assert.equal(parseRuntimeDriverName("codex-cli"), "codex-cli");
+  assert.equal(parseRuntimeDriverName(" codex-cli "), "codex-cli");
+  assert.equal(parseRuntimeDriverName("wat"), undefined);
+  assert.equal(parseRuntimeDriverName(undefined), undefined);
+});
+
+test("default runtime driver is claude-sdk when env unset", () => {
+  assert.deepEqual(resolveExtensionRuntimeDriverConfig({}), {
+    defaultDriver: "claude-sdk",
+  });
+});
+
+test("codex-cli env selects codex default driver", () => {
+  assert.deepEqual(resolveExtensionRuntimeDriverConfig({
+    [DEFAULT_RUNTIME_DRIVER_ENV]: "codex-cli",
+  }), {
+    defaultDriver: "codex-cli",
+  });
+});
+
+test("invalid env falls back to claude-sdk with note", () => {
+  assert.deepEqual(resolveExtensionRuntimeDriverConfig({
+    [DEFAULT_RUNTIME_DRIVER_ENV]: "wat",
+  }), {
+    defaultDriver: "claude-sdk",
+    note: `invalid ${DEFAULT_RUNTIME_DRIVER_ENV}=wat; using claude-sdk`,
+  });
+});

package/extensions/runtime-driver.ts

@@ -0,0 +1,33 @@
+import type { RuntimeDriverName } from "@pi-claude-code-agent/runtime";
+
+export const DEFAULT_RUNTIME_DRIVER_ENV = "PI_CLAUDE_RUNTIME_DRIVER";
+
+export function parseRuntimeDriverName(value: unknown): RuntimeDriverName | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed === "claude-sdk" || trimmed === "codex-cli" ? trimmed : undefined;
+}
+
+export interface ExtensionRuntimeDriverConfig {
+  defaultDriver: RuntimeDriverName;
+  note?: string;
+}
+
+export function resolveExtensionRuntimeDriverConfig(
+  env: Record<string, string | undefined> = process.env,
+): ExtensionRuntimeDriverConfig {
+  const raw = env[DEFAULT_RUNTIME_DRIVER_ENV]?.trim();
+  if (!raw) {
+    return { defaultDriver: "claude-sdk" };
+  }
+  const parsed = parseRuntimeDriverName(raw);
+  if (parsed) {
+    return { defaultDriver: parsed };
+  }
+  return {
+    defaultDriver: "claude-sdk",
+    note: `invalid ${DEFAULT_RUNTIME_DRIVER_ENV}=${raw}; using claude-sdk`,
+  };
+}

package/extensions/runtime-safety.test.ts

@@ -0,0 +1,21 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { describePromptSize, explainRuntimeFailure } from "./runtime-safety.ts";
+
+test("describePromptSize warns for large prompts", () => {
+  assert.equal(describePromptSize("peer prompt", "small"), undefined);
+
+  const note = describePromptSize("peer prompt", "x".repeat(24_000));
+  assert.match(note ?? "", /prompt size note/);
+  assert.match(note ?? "", /peer prompt is 24000 chars/);
+});
+
+test("explainRuntimeFailure adds actionable runtime hints", () => {
+  const binary = explainRuntimeFailure("Claude Code native binary not found", "claude-sdk");
+  assert.match(binary, /CLAUDE_CODE_EXECUTABLE/);
+
+  const bedrock = explainRuntimeFailure("Amazon Bedrock rejected request: missing API key", "claude-sdk", "opus");
+  assert.match(bedrock, /runtime_models/);
+  assert.match(bedrock, /credentials/);
+  assert.match(bedrock, /shorthand alias/);
+});

package/extensions/runtime-safety.ts

@@ -0,0 +1,49 @@
+const PROMPT_WARNING_CHAR_THRESHOLD = 24_000;
+const PROMPT_DANGER_CHAR_THRESHOLD = 100_000;
+
+export function describePromptSize(label: string, text: string): string | undefined {
+  const chars = text.length;
+  if (chars < PROMPT_WARNING_CHAR_THRESHOLD) {
+    return undefined;
+  }
+
+  const approxTokens = Math.ceil(chars / 4);
+  const severity = chars >= PROMPT_DANGER_CHAR_THRESHOLD ? "large prompt risk" : "prompt size note";
+  return `${severity}: ${label} is ${chars} chars (~${approxTokens} tokens). Prefer a smaller scoped prompt or point the peer at files instead of pasting large context.`;
+}
+
+export function explainRuntimeFailure(message: string, driver?: string, model?: string): string {
+  const lower = message.toLowerCase();
+  const hints: string[] = [];
+
+  if (lower.includes("native binary not found") || lower.includes("claude code") && lower.includes("not found")) {
+    hints.push("Claude Code executable was not found. Install Claude Code or set CLAUDE_CODE_EXECUTABLE to the native binary path.");
+  }
+
+  if (lower.includes("enoent") || lower.includes("spawn") && lower.includes("not found")) {
+    const binary = driver === "codex-cli" ? "codex" : driver === "claude-sdk" ? "Claude Code" : "runtime";
+    hints.push(`${binary} executable could not be spawned. Check PATH or configure the matching executable env var before starting peers.`);
+  }
+
+  if (lower.includes("bedrock")) {
+    hints.push("The provider appears to route through Amazon Bedrock. Use a fully qualified catalog model id from runtime_models, or configure the required Bedrock credentials.");
+  }
+
+  if (lower.includes("api key") || lower.includes("apikey") || lower.includes("unauthorized")) {
+    hints.push("Provider credentials are missing or rejected for this runtime/model.");
+  }
+
+  if (lower.includes("prompt is too long") || lower.includes("prompt too long") || lower.includes("context length")) {
+    hints.push("The prompt exceeded the provider context budget. Split the task into smaller slices or ask the peer to inspect files instead of pasting large context.");
+  }
+
+  if (model && /^(opus|sonnet|haiku)$/i.test(model.trim())) {
+    hints.push(`"${model}" is a shorthand alias; pi-ca-leash now resolves it before future runtime calls. Use runtime_models to inspect the exact id.`);
+  }
+
+  if (hints.length === 0) {
+    return message;
+  }
+
+  return [message, ...[...new Set(hints)].map((hint) => `Hint: ${hint}`)].join("\n");
+}

package/extensions/support.test.ts

@@ -0,0 +1,144 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import type { SubagentRunRecord } from "@pi-claude-code-agent/subagents-backend";
+import {
+  acknowledgeAttention,
+  computeWidgetSignature,
+  createAttentionLedger,
+  createDashboardState,
+  describeAttentionState,
+  detectConnectivityTransition,
+  recordDashboardEvent,
+  recordDashboardRefresh,
+  reconcileAttentionLedger,
+  shouldRebindTransport,
+  shouldSkipBackgroundRefresh,
+  snoozeAttention,
+  type WidgetSignatureInput,
+} from "./support.ts";
+
+function makeRun(overrides: Partial<SubagentRunRecord> = {}): SubagentRunRecord {
+  return {
+    runId: overrides.runId ?? "run-12345678",
+    runner: "claude-code-agent",
+    agentName: overrides.agentName ?? "worker",
+    sessionId: overrides.sessionId,
+    cwd: overrides.cwd ?? process.cwd(),
+    model: overrides.model,
+    state: overrides.state ?? "running",
+    context: overrides.context ?? "fresh",
+    createdAt: overrides.createdAt ?? "2026-04-29T10:00:00.000Z",
+    updatedAt: overrides.updatedAt ?? "2026-04-29T10:00:00.000Z",
+    lastActivityAt: overrides.lastActivityAt ?? "2026-04-29T10:00:00.000Z",
+    task: overrides.task ?? "Investigate",
+    result: overrides.result,
+    note: overrides.note,
+    raw: overrides.raw,
+  };
+}
+
+test("dashboard refresh does not overwrite last event timestamp", () => {
+  const state = createDashboardState("startup", 100);
+  recordDashboardRefresh(state, 250);
+  assert.deepEqual(state, {
+    lastEvent: "startup",
+    lastEventAt: 100,
+    lastRefreshedAt: 250,
+  });
+
+  recordDashboardEvent(state, "intercom connected", 400);
+  assert.deepEqual(state, {
+    lastEvent: "intercom connected",
+    lastEventAt: 400,
+    lastRefreshedAt: 400,
+  });
+});
+
+test("connectivity transitions only fire on real flips", () => {
+  assert.equal(detectConnectivityTransition(undefined, false), undefined);
+  assert.equal(detectConnectivityTransition(undefined, true), undefined);
+  assert.equal(detectConnectivityTransition(false, false), undefined);
+  assert.equal(detectConnectivityTransition(true, true), undefined);
+  assert.equal(detectConnectivityTransition(false, true), "connected");
+  assert.equal(detectConnectivityTransition(true, false), "disconnected");
+});
+
+test("transport rebind only needed when peers are missing broker connections", () => {
+  assert.equal(shouldRebindTransport(undefined), false);
+  assert.equal(shouldRebindTransport({ kind: "pi-intercom", boundPeers: 0, connectedPeers: 0 }), false);
+  assert.equal(shouldRebindTransport({ kind: "pi-intercom", boundPeers: 2, connectedPeers: 2 }), false);
+  assert.equal(shouldRebindTransport({ kind: "pi-intercom", boundPeers: 2, connectedPeers: 1 }), true);
+});
+
+test("computeWidgetSignature is stable for identical content and changes on peer state, model, or update time", () => {
+  const base: WidgetSignatureInput = {
+    peerRows: [{ name: "reviewer", state: "idle", activity: "last reply: ok", lastUpdateAt: "2026-05-02T10:00:00.000Z" }],
+    transportDegraded: false,
+    lastEvent: "startup",
+  };
+  assert.equal(computeWidgetSignature(base), computeWidgetSignature(base));
+  assert.notEqual(
+    computeWidgetSignature(base),
+    computeWidgetSignature({ ...base, peerRows: [{ name: "reviewer", state: "busy", activity: "Bash: npm test", lastUpdateAt: "2026-05-02T10:00:00.000Z" }] }),
+  );
+  assert.notEqual(
+    computeWidgetSignature(base),
+    computeWidgetSignature({ ...base, peerRows: [{ name: "reviewer", state: "idle", activity: "last reply: ok", lastUpdateAt: "2026-05-02T10:00:00.000Z", model: "claude-sonnet-4-6" }] }),
+  );
+  assert.notEqual(
+    computeWidgetSignature(base),
+    computeWidgetSignature({ ...base, peerRows: [{ name: "reviewer", state: "idle", activity: "last reply: ok", lastUpdateAt: "2026-05-02T10:01:00.000Z" }] }),
+  );
+  assert.notEqual(
+    computeWidgetSignature(base),
+    computeWidgetSignature({ ...base, peerRows: [{ name: "reviewer", state: "idle", activity: "last reply: ok", lastUpdateAt: "2026-05-02T10:00:00.000Z", contextPercentage: 25 }] }),
+  );
+  assert.equal(
+    computeWidgetSignature(base),
+    computeWidgetSignature({ ...base }),
+  );
+});
+
+test("shouldSkipBackgroundRefresh suppresses rapid refreshes within min interval", () => {
+  const state = createDashboardState("startup", 1_000);
+
+  assert.equal(shouldSkipBackgroundRefresh(state, 1_500, 3_000), true);
+  assert.equal(shouldSkipBackgroundRefresh(state, 3_999, 3_000), true);
+  assert.equal(shouldSkipBackgroundRefresh(state, 4_000, 3_000), false);
+  assert.equal(shouldSkipBackgroundRefresh(state, 5_000, 3_000), false);
+});
+
+test("attention ledger notifies once, supports ack, and resets on note change", () => {
+  const run = makeRun({ note: "Needs attention: idle for 6000ms" });
+  const first = reconcileAttentionLedger(createAttentionLedger(), [run], 1_000);
+  assert.equal(first.notify.length, 1);
+  assert.equal(first.active.length, 1);
+  assert.equal(describeAttentionState(first.active[0]!, 1_000), "active");
+
+  const acknowledged = acknowledgeAttention(first.ledger, run.runId);
+  const second = reconcileAttentionLedger(acknowledged, [run], 2_000);
+  assert.equal(second.notify.length, 0);
+  assert.equal(describeAttentionState(second.active[0]!, 2_000), "acked");
+
+  const changed = reconcileAttentionLedger(acknowledged, [{ ...run, note: "Needs attention: idle for 12000ms" }], 3_000);
+  assert.equal(changed.notify.length, 1);
+  assert.equal(describeAttentionState(changed.active[0]!, 3_000), "active");
+});
+
+test("attention snooze suppresses alerts until expiry and clears when attention ends", () => {
+  const run = makeRun({ note: "Needs attention: idle for 6000ms" });
+  const first = reconcileAttentionLedger(createAttentionLedger(), [run], 1_000);
+  const snoozed = snoozeAttention(first.ledger, run.runId, 10_000);
+
+  const hidden = reconcileAttentionLedger(snoozed, [run], 5_000);
+  assert.equal(hidden.notify.length, 0);
+  assert.equal(describeAttentionState(hidden.active[0]!, 5_000), "snoozed 1m");
+
+  const resumed = reconcileAttentionLedger(hidden.ledger, [run], 11_000);
+  assert.equal(resumed.notify.length, 1);
+  assert.equal(describeAttentionState(resumed.active[0]!, 11_000), "active");
+
+  const cleared = reconcileAttentionLedger(resumed.ledger, [{ ...run, note: undefined }], 12_000);
+  assert.equal(cleared.active.length, 0);
+  assert.deepEqual(cleared.ledger.runs, {});
+});