@naswerks/periscope 1.0.0 → 1.0.1

package/src/sessions/spawn-env.ts

@@ -0,0 +1,318 @@
+/**
+ * The environment a spawned agent process receives — an allow-list, not a strip-list.
+ *
+ * The Agent SDK's `env` option replaces the subprocess environment rather than merging it, and when
+ * omitted the subprocess inherits `process.env` whole. So the default posture is full inheritance,
+ * and the only way to hold a boundary is to state what crosses it. A strip-list can only ever remove
+ * what someone thought of; this one is "absent unless declared".
+ *
+ * The failures this prevents are all silent, which is why the set is pinned key-by-key rather than
+ * eyeballed. Three are recorded, and two have been observed in a live host:
+ *   - `CLAUDE_CODE_CHILD_SESSION` inherited: the CLI treats the spawn as a nested session and never
+ *     persists its transcript, while the Stop path still reports the path it never wrote.
+ *   - `CLAUDE_EFFORT` inherited: the host's own effort silently becomes every spawn's effort.
+ *   - a host secret inherited: every subprocess the agent runs authenticates as the host.
+ *
+ * How the declared set was derived — read this before adding or removing a key.
+ * Not copied from any single product's list. A list derived from a capture of one product's
+ * machines declares that product's own service-discovery variables; carrying those here is how a
+ * general-purpose package quietly becomes a single-product one. The test that gates this file runs
+ * a closed diff over two corpora — a live host capture and a production capture from a different
+ * machine — and every key in either is declared or carries a written reason for being dropped. Two
+ * corpora rather than one because a single capture under-includes whatever that box happens to
+ * lack: proxy variables, `XDG_`, `LC_`. Do not tidy them into one.
+ *
+ * Product-specific names are not declared here. They come back through `extraAllowedKeys`, which the
+ * embedder states for its own deployment — `USERPROFILE` is a primitive, a dashboard endpoint URL
+ * is somebody's product.
+ *
+ * The standing posture, because it decides every close call: over-inclusion is recoverable and
+ * visible; under-inclusion breaks agents in ways that read as model failures many sessions later.
+ * So a key is declared unless there is a positive reason to drop it — it carries a credential, it is
+ * another process's handle, it is one product's configuration, or it actively lies to the child
+ * about what it is.
+ */
+
+/** Any environment-shaped map. Deliberately not `NodeJS.ProcessEnv` — nothing here needs a runtime. */
+export type EnvSource = Readonly<Record<string, string | undefined>>;
+
+export interface SpawnEnvPolicy {
+  /**
+   * Keys the embedder declares for its own deployment, on top of the general set.
+   *
+   * This is where a product's own variables belong. Matched case-insensitively like the rest, and
+   * it cannot override a denied key — see `DENIED_PATTERNS`.
+   */
+  readonly extraAllowedKeys?: readonly string[];
+  /**
+   * Keys the embedder refuses even though they are declared. For a host that knows a name in the
+   * general set is a secret on its machines.
+   */
+  readonly extraDeniedKeys?: readonly string[];
+  /**
+   * Literal values set on the spawn, applied after filtering.
+   *
+   * Setting a value is not the same act as inheriting one: a value stated here is a decision with an
+   * author, and it overrides whatever the host env happened to hold. That asymmetry is deliberate —
+   * a variable this package refuses to inherit can still be set, but only by naming it and its value.
+   */
+  readonly extraEnv?: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// The declared set.
+// ---------------------------------------------------------------------------
+
+const ALLOWED_EXACT = [
+  // -- Home resolution. Load-bearing, and the group travels together or not at all.
+  //    On Windows the key is USERPROFILE, not HOME: `os.homedir()` reads the USERPROFILE family,
+  //    and `HOME` in a Windows child is a Git-Bash invention. Declaring HOME while omitting
+  //    USERPROFILE leaves the CLI unable to find its ambient credentials file — every agent
+  //    silently unauthenticated, presenting as a confused model rather than an error.
+  'USERPROFILE',
+  'HOMEDRIVE',
+  'HOMEPATH',
+  'HOME',
+  'APPDATA',
+  'LOCALAPPDATA',
+  'ALLUSERSPROFILE',
+  'OneDrive',
+  //    Belongs to the group above, not to the CLI knobs below: it is another spelling of "where are
+  //    my credentials", so dropping it breaks ambient auth in exactly the same silent way.
+  'CLAUDE_CONFIG_DIR',
+
+  // -- Identity
+  'USERNAME',
+  'USERDOMAIN',
+  'USERDOMAIN_ROAMINGPROFILE',
+  'COMPUTERNAME',
+  'USER',
+  'LOGNAME',
+
+  // -- Windows OS substrate
+  'PATH',
+  'PATHEXT',
+  'COMSPEC',
+  'SYSTEMDRIVE',
+  'SYSTEMROOT',
+  'WINDIR',
+  'TEMP',
+  'TMP',
+  'ProgramData',
+  'PROGRAMFILES',
+  'ProgramFiles(x86)',
+  'ProgramW6432',
+  'COMMONPROGRAMFILES',
+  'CommonProgramFiles(x86)',
+  'CommonProgramW6432',
+  'PUBLIC',
+  'DriverData',
+  'OS',
+  'NoDefaultCurrentDirectoryInExePath',
+  'PROMPT',
+  'PSModulePath',
+  'SESSIONNAME',
+  'LOGONSERVER',
+  'NUMBER_OF_PROCESSORS',
+  'ZES_ENABLE_SYSMAN',
+
+  // -- POSIX substrate. Neither corpus is a POSIX capture, so these are declared from the
+  //    Windows keys' POSIX twins rather than observed. Stated openly because it is the one place
+  //    this set is designed rather than derived — and under-inclusion on a platform no corpus
+  //    covers is the invisible direction.
+  'TMPDIR',
+
+  // -- Terminal + locale
+  'TERM',
+  'TERM_PROGRAM',
+  'TERM_PROGRAM_VERSION',
+  'COLORTERM',
+  'COLOR',
+  'LANG',
+  'TZ',
+
+  // -- Node / npm toolchain. `npm_config_*` rides the prefix list; `npm_package_*`,
+  //    `npm_lifecycle_*` and `INIT_CWD` deliberately do not — they describe the host's own npm
+  //    invocation and would tell a child it is the host package.
+  'NODE',
+  'npm_command',
+  'npm_execpath',
+  'npm_node_execpath',
+  'NVM_HOME',
+  'NVM_SYMLINK',
+  'COREPACK_ENABLE_AUTO_PIN',
+
+  // -- Shell, git and dev toolchain. EDITOR/GIT_EDITOR are declared because an agent running a git
+  //    command that opens an editor with none configured hangs instead of failing.
+  'SHELL',
+  'MSYSTEM',
+  'EXEPATH',
+  'PLINK_PROTOCOL',
+  'SSL_CERT_DIR',
+  'PWD',
+  'SHLVL',
+  'EDITOR',
+  'GIT_EDITOR',
+  'DOTNET_NOLOGO',
+  'MSBUILDTERMINALLOGGER',
+  'ChocolateyInstall',
+  'ChocolateyLastPathUpdate',
+
+  // -- Agent CLI knobs, exact names only. A `CLAUDE_` prefix would re-admit the stripped set below,
+  //    above all the effort variable, and undo the whole point of this file.
+  'CLAUDE_CODE_ENABLE_TELEMETRY',
+] as const;
+
+const ALLOWED_PREFIXES = [
+  'NODE_', // NODE_ENV / NODE_NO_WARNINGS / NODE_OPTIONS / NODE_EXTRA_CA_CERTS
+  'npm_config_', // a child running npm needs the host's cache and prefix resolution
+  'PROCESSOR_', // PROCESSOR_ARCHITECTURE / _IDENTIFIER / _LEVEL / _REVISION
+  'XDG_', // POSIX base directories
+  'LC_', // locale category overrides
+] as const;
+
+// Matched as a suffix so one entry covers HTTP_PROXY / http_proxy / HTTPS_PROXY / ALL_PROXY /
+// NO_PROXY, case-insensitively. A proxied host is exactly where under-inclusion is invisible on the
+// machine that wrote the list and fatal on the machine that runs it.
+const ALLOWED_SUFFIXES = ['_PROXY'] as const;
+
+/**
+ * Denied whatever else matches. Runs before every allow, including `extraAllowedKeys`, because a
+ * key that is a credential does not stop being one because someone widened a prefix.
+ */
+const DENIED_PATTERNS: readonly RegExp[] = [
+  // npm materialises every .npmrc key as an environment variable, so `npm_config_` genuinely
+  // matches shapes like `npm_config_//registry.example.com/:_authToken`. A targeted deny rather
+  // than a narrower prefix: a child running npm still needs the rest of its config resolution.
+  /^npm_config_.*(:_authtoken|:_auth|:_password|:username|:email|_auth)$/i,
+  // Disables certificate validation for every outbound request the child makes. A host may have a
+  // local reason for it; a spawned agent inherits the reason's absence along with the value, and
+  // the failure is a confidentiality one it cannot see. An embedder that means it states it as a
+  // literal through `extraEnv`, where it has an author.
+  /^NODE_TLS_REJECT_UNAUTHORIZED$/i,
+];
+
+/**
+ * Stripped last and unconditionally — after the allow-list, after `extraEnv`, after everything.
+ *
+ * Deliberately redundant with "absent unless declared": this survives a widened declared set, a
+ * `CLAUDE_`-shaped prefix added in haste, and an embedder that sets one of these by hand. The class
+ * is the running host's own session fingerprint, and a spawned agent is a top-level session, not a
+ * continuation of whoever launched the host.
+ */
+const HOST_SESSION_MARKERS = [
+  'CLAUDECODE',
+  'CLAUDE_CODE_CHILD_SESSION',
+  'CLAUDE_CODE_ENTRYPOINT',
+  'CLAUDE_CODE_SESSION_ID',
+  'CLAUDE_CODE_EXECPATH',
+  'CLAUDE_CODE_SSE_PORT',
+  'CLAUDE_PID',
+  'CLAUDE_EFFORT',
+  'CLAUDE_AGENT_SDK_VERSION',
+  'CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING',
+  'CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING',
+  'CLAUDE_CODE_ENABLE_TASKS',
+  'MCP_CONNECTION_NONBLOCKING',
+  'AI_AGENT',
+  // The host's own thinking budget, same class as the effort variable: an inherited value silently
+  // becomes every spawn's budget. A deliberate one arrives through the SDK options, which have an
+  // author and a type.
+  'MAX_THINKING_TOKENS',
+] as const;
+
+// ---------------------------------------------------------------------------
+// Matching.
+// ---------------------------------------------------------------------------
+
+// Matching is case-insensitive. Windows environment names are case-insensitive and Node preserves
+// the OS's own casing verbatim — `ProgramData`, `CommonProgramFiles(x86)`, `ChocolateyInstall` — so
+// a case-sensitive set silently drops real keys. On POSIX this only over-includes (a lowercase twin
+// of a declared name), which is the recoverable direction, and it is how `http_proxy` is covered by
+// the same entry as `HTTPS_PROXY`.
+const ALLOWED_EXACT_UPPER = new Set<string>(ALLOWED_EXACT.map((key) => key.toUpperCase()));
+const ALLOWED_PREFIXES_UPPER = ALLOWED_PREFIXES.map((prefix) => prefix.toUpperCase());
+const ALLOWED_SUFFIXES_UPPER = ALLOWED_SUFFIXES.map((suffix) => suffix.toUpperCase());
+const HOST_SESSION_MARKERS_UPPER = new Set<string>(HOST_SESSION_MARKERS.map((key) => key.toUpperCase()));
+
+/** Every key this package declares for a spawned agent, in declaration order. For the pin. */
+export const DECLARED_EXACT_KEYS: readonly string[] = ALLOWED_EXACT;
+export const DECLARED_PREFIXES: readonly string[] = ALLOWED_PREFIXES;
+export const DECLARED_SUFFIXES: readonly string[] = ALLOWED_SUFFIXES;
+export const STRIPPED_HOST_SESSION_KEYS: readonly string[] = HOST_SESSION_MARKERS;
+
+function isDenied(key: string, policy: SpawnEnvPolicy): boolean {
+  if (DENIED_PATTERNS.some((pattern) => pattern.test(key))) return true;
+  const upper = key.toUpperCase();
+  return (policy.extraDeniedKeys ?? []).some((denied) => denied.toUpperCase() === upper);
+}
+
+/** Is this key declared for spawned agents? Exported so the gate test can drive it directly. */
+export function isDeclaredSpawnEnvKey(key: string, policy: SpawnEnvPolicy = {}): boolean {
+  if (isDenied(key, policy)) return false;
+
+  const upper = key.toUpperCase();
+  if ((policy.extraAllowedKeys ?? []).some((extra) => extra.toUpperCase() === upper)) return true;
+  if (ALLOWED_EXACT_UPPER.has(upper)) return true;
+  if (ALLOWED_PREFIXES_UPPER.some((prefix) => upper.startsWith(prefix))) return true;
+  return ALLOWED_SUFFIXES_UPPER.some((suffix) => upper.endsWith(suffix));
+}
+
+const isProxyKey = (key: string): boolean =>
+  ALLOWED_SUFFIXES_UPPER.some((suffix) => key.toUpperCase().endsWith(suffix));
+
+/**
+ * Strip `user:pass@` from a proxy URL, keeping the proxy reachable.
+ *
+ * The key stays declared and the credential leaves the value: proxy URLs routinely embed
+ * credentials, so declaring the key was declaring a secret — but dropping the key breaks every
+ * spawn behind a corporate proxy, which trades an availability failure for a confidentiality one.
+ * A value that does not parse as a URL (`NO_PROXY` is a comma-separated host list) is returned
+ * verbatim: a redaction must never corrupt a value it does not understand, because a mangled
+ * no-proxy list silently changes which hosts bypass the proxy.
+ */
+export function redactProxyCredential(value: string): string {
+  if (!value.includes('@')) return value;
+  try {
+    const url = new URL(value);
+    if (url.username === '' && url.password === '') return value;
+    url.username = '';
+    url.password = '';
+    return url.toString();
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * The environment for a spawned agent: the declared subset of `baseEnv`, then the embedder's
+ * literals, then the host-session strip.
+ *
+ * The strip runs last on purpose. It is the one rule that cannot be widened away, so the property
+ * "a spawned agent is never told it is a continuation of this process" holds no matter what a later
+ * change does to the declared set or what an embedder passes.
+ *
+ * Returns a fresh object every call and never mutates `baseEnv`.
+ */
+export function composeSpawnEnv(baseEnv: EnvSource, policy: SpawnEnvPolicy = {}): Record<string, string> {
+  const env: Record<string, string> = {};
+
+  for (const key of Object.keys(baseEnv)) {
+    if (!isDeclaredSpawnEnvKey(key, policy)) continue;
+    const value = baseEnv[key];
+    // An undeclared value and an empty one are different things, but neither is worth passing: the
+    // SDK's env map allows `undefined` and the CLI would see the name with nothing behind it.
+    if (value === undefined) continue;
+    env[key] = isProxyKey(key) ? redactProxyCredential(value) : value;
+  }
+
+  for (const [key, value] of Object.entries(policy.extraEnv ?? {})) {
+    env[key] = value;
+  }
+
+  for (const key of Object.keys(env)) {
+    if (HOST_SESSION_MARKERS_UPPER.has(key.toUpperCase())) delete env[key];
+  }
+
+  return env;
+}

package/src/state/coverage.ts

@@ -0,0 +1,360 @@
+/**
+ * The coverage table. Every hook the SDK exposes and every message it can send is wired or
+ * declined here, in writing.
+ *
+ * An absent row is a gap, not a default — which is the entire reason this is a table rather than
+ * a wiring pass. "Every hook is handled" is unfalsifiable; "every hook has a row, and here are the
+ * ones deliberately not used and why" can be audited by someone who was not here.
+ *
+ * It cannot rot silently, and that is enforced twice.
+ *   1. `satisfies Record<HookEvent, …>` and `satisfies Record<MessageDiscriminator, …>` — both keyed
+ *      off the SDK's own unions, so an event added by an SDK upgrade breaks the build.
+ *   2. `pins/hook-coverage.test.ts` parses those unions straight out of the shipped `sdk.d.ts` and
+ *      fails when a literal has no row — which catches the case (1) cannot: someone widening the
+ *      local mirror instead of the table.
+ * A document that claims coverage is exactly the artifact that decays into a lie, so the claim is
+ * made checkable rather than merely careful.
+ *
+ * The rule for `wired`: an event is wired when it changes the session's state or activity, or
+ * when it names a why the trace would otherwise be missing. Everything else is declined — and the
+ * commonest honest reason is that the fact belongs to a neighbouring layer (content to streaming,
+ * cost to telemetry, transcripts to persistence), not that it is uninteresting.
+ */
+import type { HookEvent, MessageDiscriminator } from '../host/agent-process.js';
+
+export type CoverageHandling = 'wired' | 'declined';
+
+export interface CoverageRow {
+  readonly handling: CoverageHandling;
+  /** What it produces when wired; why it is not consumed when declined. Required either way. */
+  readonly note: string;
+}
+
+/**
+ * All 31 hook events. 18 wired, 13 declined.
+ *
+ * `PreToolUse` appears here as an observation only. The permission decision is a separate
+ * concern with a separate handler; `HookCallbackMatcher.hooks` is an array and the SDK runs every
+ * entry, so a decision handler registers alongside this one without either editing the other.
+ */
+export const HOOK_COVERAGE = {
+  // --- wired: the tool lane -------------------------------------------------
+  PreToolUse: {
+    handling: 'wired',
+    note: 'opens a `tool` entry keyed by tool_use_id; state -> working. Observation only — the permission decision is a separate handler on the same event.',
+  },
+  PostToolUse: {
+    handling: 'wired',
+    note: 'closes the `tool` entry for its tool_use_id. The ordinary exit.',
+  },
+  PostToolUseFailure: {
+    handling: 'wired',
+    note: 'closes the `tool` entry naming the failure — the failure exit, distinct from the success one because "it stopped" and "it broke" are different answers.',
+  },
+  PostToolBatch: {
+    handling: 'wired',
+    note: "fires exactly once after every call in a batch resolves, so it closes any tool entry still open. The backstop for a PostToolUse that never arrived — measured on two live sessions, including an all-denied batch: it fires on a hook-authored deny and its tool_calls includes the denied tool_use_id, so a denied call's entry does not leak. It closes the entry at end of batch and says only that; the denial itself is a separate transition the gate emits.",
+  },
+
+  // --- wired: the turn lane -------------------------------------------------
+  UserPromptSubmit: {
+    handling: 'wired',
+    note: 'state -> working. The turn boundary opening; the counterpart to Stop.',
+  },
+  Stop: {
+    handling: 'wired',
+    note: 'state -> idle. The clean turn end, recorded for every session with no exemption — a turn boundary that is missing for any class of session leaves every reader inferring.',
+  },
+  StopFailure: {
+    handling: 'wired',
+    note: 'state -> errored, carrying the SDKAssistantMessageError. Never collapsed into Stop: a turn that broke is not a turn that finished.',
+  },
+
+  // --- wired: session lifecycle --------------------------------------------
+  SessionStart: {
+    handling: 'wired',
+    note: 'records how the session began (startup | resume | clear | compact | fork). No state change — it names a why the trace would otherwise have to infer. Measured not to fire on an SDK-hosted start: a real session running every wired hook saw PreToolUse, PostToolUse, PostToolBatch, UserPromptSubmit and Stop, and no SessionStart. The likely reason is ordering — `options.hooks` reach the CLI after it has already started — but that was not isolated. Wired and not observed, which is a different row from declined.',
+  },
+  SessionEnd: {
+    handling: 'wired',
+    note: 'state -> ended, carrying the ExitReason. Never inferred from silence.',
+  },
+  CwdChanged: {
+    handling: 'wired',
+    note: 'updates `where.cwd` for every later transition. Declining it would leave every subsequent record carrying a stale directory — a trace that lies quietly.',
+  },
+
+  // --- wired: subagents -----------------------------------------------------
+  SubagentStart: {
+    handling: 'wired',
+    note: 'opens a `subagent` entry keyed by agent_id, carrying agent_type.',
+  },
+  SubagentStop: {
+    handling: 'wired',
+    note: 'closes the `subagent` entry for its agent_id.',
+  },
+
+  // --- wired: compaction ----------------------------------------------------
+  PreCompact: {
+    handling: 'wired',
+    note: 'opens a `compacting` entry, carrying trigger (manual | auto).',
+  },
+  PostCompact: {
+    handling: 'wired',
+    note: 'closes the `compacting` entry.',
+  },
+
+  // --- wired: the permission lane -------------------------------------------
+  PermissionRequest: {
+    handling: 'wired',
+    note: "opens a `permission` entry for the tool. Measured not to fire for a hook-authored decision — `gate/outcome.ts` records the measurement — so the held-visibility this model buys is delivered by the gate's own hold entry (keyed by tool_use_id), not by this hook. Do not wait on this hook for entries the gate opens elsewhere; re-measure before relying on it for any other decision path.",
+  },
+  PermissionDenied: {
+    handling: 'wired',
+    note: 'closes the `permission` entry, cause kind `hook`, carrying the deny reason. A denial and a permission-path outage must not read alike: an outage arrives as cause kind `refusal` with a refusal reason, so the two differ in kind and event. Measured not to fire for a hook-authored deny: a real session whose PreToolUse returned `permissionDecision: deny` blocked the tool (no PostToolUse) but emitted no PermissionDenied — so this hook appears to belong to a decision path other than the hook lane. Whoever builds the decision path must not rely on it as the deny receipt without re-measuring.',
+  },
+
+  // --- wired: elicitation ---------------------------------------------------
+  Elicitation: {
+    handling: 'wired',
+    note: 'opens an `elicitation` entry for the MCP server. The session is genuinely blocked on an answer.',
+  },
+  ElicitationResult: {
+    handling: 'wired',
+    note: 'closes the `elicitation` entry, carrying the action (accept | decline | cancel).',
+  },
+
+  // --- declined -------------------------------------------------------------
+  Notification: {
+    handling: 'declined',
+    note: 'a display notification (message, title, notification_type). Nothing about it moves the session; it is content, and content belongs to the streaming layer.',
+  },
+  UserPromptExpansion: {
+    handling: 'declined',
+    note: 'a slash-command or MCP-prompt expansion of a prompt already submitted. The turn boundary was UserPromptSubmit; recording this too would add a transition carrying no new fact.',
+  },
+  Setup: {
+    handling: 'declined',
+    note: 'environment housekeeping (trigger: init | maintenance). It runs beside the session rather than in it, and produces no condition the session can be blocked on.',
+  },
+  TeammateIdle: {
+    handling: 'declined',
+    note: "reports that another session is idle. Recording it here would attribute a different session's state to this one — precisely the cross-session aggregation that belongs to the controller, not a host.",
+  },
+  TaskCreated: {
+    handling: 'declined',
+    note: 'the task-list surface (task_subject, teammate_name). Its overlap with the task_started/task_updated message lane has not been resolved against a live session, and wiring both would double-count one entry. Declined on the unresolved overlap, not on irrelevance.',
+  },
+  TaskCompleted: {
+    handling: 'declined',
+    note: 'the closing half of TaskCreated, declined for the same unresolved overlap. system/task_notification is the completion signal that is wired.',
+  },
+  ConfigChange: {
+    handling: 'declined',
+    note: "settings or skills changed on disk. It changes what the session can do, not what it is doing — a capability fact, and capability is the workspace layer's.",
+  },
+  InstructionsLoaded: {
+    handling: 'declined',
+    note: 'memory/CLAUDE.md loading. Context composition, which is what a turn is made of rather than a condition it is in.',
+  },
+  WorktreeCreate: {
+    handling: 'declined',
+    note: 'the agent created a worktree. It does not move the session — `where` still describes where the session runs. Relevant to whichever layer provisions workspaces.',
+  },
+  WorktreeRemove: {
+    handling: 'declined',
+    note: 'as WorktreeCreate. Note that removing the worktree a session is in would be visible through CwdChanged, which is wired.',
+  },
+  DirectoryAdded: {
+    handling: 'declined',
+    note: 'widens the set of directories the session may touch. A permission-surface fact, not a state one; it belongs with whatever enforces the path boundary.',
+  },
+  FileChanged: {
+    handling: 'declined',
+    note: 'a watched file changed (change | add | unlink). High volume, driven by the filesystem rather than by the session, and it holds nothing.',
+  },
+  MessageDisplay: {
+    handling: 'declined',
+    note: "one flush of an assistant message, indexed per delta. The highest-volume event in the set and pure content — the streaming layer's lane, not the state model's.",
+  },
+} as const satisfies Record<HookEvent, CoverageRow>;
+
+/**
+ * All 39 members of the SDKMessage union, keyed by discriminator.
+ *
+ * Fewer keys than members: several shapes share one discriminator (`user` covers the ordinary and
+ * the replayed user message; `result` covers success and every error subtype). The pin walks the
+ * union member by member and checks each one's discriminator has a row, so the many-to-one is
+ * accounted for rather than hidden by the shorter key list.
+ */
+export const MESSAGE_COVERAGE = {
+  // --- wired ----------------------------------------------------------------
+  'system/init': {
+    handling: 'wired',
+    note: 'state -> ready, and the only place the session id, CLI version receipt, model, tool/skill/plugin inventory and apiKeySource arrive. Everything downstream keys off the id it carries.',
+  },
+  'system/status': {
+    handling: 'wired',
+    note: "SDKStatus — sets activity `requesting` or `compacting`, and closes it on null. The SDK's own word for what a session is doing, adopted verbatim.",
+  },
+  'system/session_state_changed': {
+    handling: 'wired',
+    note: 'documented as the authoritative turn-over signal — measured not to fire: never observed on any of the 3 real turns measured; `Stop` and `result` are the observed turn boundaries. When it does arrive: idle -> state idle, running -> state working. `requires_action` deliberately does not set state: what the session requires is already carried by the open permission or elicitation entry, and a second representation would be a second vocabulary.',
+  },
+  'system/compact_boundary': {
+    handling: 'wired',
+    note: 'compaction actually happened, with trigger and token counts. Closes the compacting entry as a backstop for a PostCompact that never arrived.',
+  },
+  'system/task_started': {
+    handling: 'wired',
+    note: 'no transition of its own — it supplies the task_id -> tool_use_id join, without which task_updated could not name the entry it backgrounds. Wired as correlation, and saying so is the point of this column.',
+  },
+  'system/task_updated': {
+    handling: 'wired',
+    note: '`patch.is_backgrounded` is the caused moment a task stops holding the session — the entry moves to the background lane there, never on a timer and never by inference. `patch.status` in completed | failed | killed closes it.',
+  },
+  'system/task_notification': {
+    handling: 'wired',
+    note: 'a background task finished (completed | failed | stopped) carrying tool_use_id. The exit for backgrounded work: backgrounding is not completion, so the entry stays open and ages until this arrives.',
+  },
+  'system/worker_shutting_down': {
+    handling: 'wired',
+    note: 'a named reason for a teardown that would otherwise present as the process simply ending. Its own type warns that absence is not a dead-host signal — handoffs and fatal paths emit nothing — so it is a why when present, never a liveness check.',
+  },
+  'system/model_refusal_no_fallback': {
+    handling: 'wired',
+    note: 'the turn ends with no retry. Records the why; the state change itself rides result/StopFailure, so the turn end is not recorded twice.',
+  },
+  result: {
+    handling: 'wired',
+    note: 'subtype success -> idle (the backstop for a missed Stop); every error subtype -> errored, carrying terminal_reason. This is where a turn that ended without any hook firing still gets a boundary.',
+  },
+
+  // --- declined -------------------------------------------------------------
+  assistant: {
+    handling: 'declined',
+    note: 'model output. Content, owned by the streaming layer; the state it implies is already carried by system/status and system/session_state_changed.',
+  },
+  user: {
+    handling: 'declined',
+    note: 'the turn input, including the replayed echo. UserPromptSubmit is the wired boundary; this is the payload that crossed it.',
+  },
+  stream_event: {
+    handling: 'declined',
+    note: "partial assistant deltas. The highest-volume message in the union and pure content — the streaming layer's.",
+  },
+  tool_progress: {
+    handling: 'declined',
+    note: "carries elapsed_time_seconds for a running tool. Declined deliberately: the open entry's age is computed from its own openedAt, and a second elapsed-time source is a number that can disagree with the trace.",
+  },
+  tool_use_summary: {
+    handling: 'declined',
+    note: 'a prose summary of preceding tool calls. Content.',
+  },
+  auth_status: {
+    handling: 'declined',
+    note: 'isAuthenticating plus provider output. An identity-plane fact; the session is not blocked on it in a way this model can name.',
+  },
+  rate_limit_event: {
+    handling: 'declined',
+    note: 'rate-limit windows. Usage and cost belong to the telemetry lane, which reads the same stream.',
+  },
+  prompt_suggestion: {
+    handling: 'declined',
+    note: 'a predicted next prompt. A suggestion for a human; nothing has happened.',
+  },
+  conversation_reset: {
+    handling: 'declined',
+    note: "/clear, plan-mode exit and fresh-session flows mint a new conversation id. The session continues — what changed is which transcript later reads attach to, which is the persistence layer's question.",
+  },
+  'system/api_retry': {
+    handling: 'declined',
+    note: "a retryable API failure being retried. The session stays in `requesting`, and a session stuck in retries is already visible as that entry's growing age rather than needing a state of its own.",
+  },
+  'system/control_request_progress': {
+    handling: 'declined',
+    note: 'progress for a client-originated control request. It belongs to whoever made that request, correlated by its own request_id.',
+  },
+  'system/model_refusal_fallback': {
+    handling: 'declined',
+    note: 'the turn was retried on a fallback model and continues. Nothing ended; the no-fallback counterpart is the one that is wired.',
+  },
+  'system/local_command_output': {
+    handling: 'declined',
+    note: 'output from a local slash command. Content.',
+  },
+  'system/hook_started': {
+    handling: 'declined',
+    note: 'the lifecycle of a command hook (hook_id, hook_name, stdout/stderr). This host installs in-process callbacks and runs no command hooks, so these describe a mechanism it does not use.',
+  },
+  'system/hook_progress': {
+    handling: 'declined',
+    note: 'as system/hook_started — the command-hook mechanism, unused here.',
+  },
+  'system/hook_response': {
+    handling: 'declined',
+    note: 'as system/hook_started. Worth revisiting by whoever builds the permission decision path if command hooks are ever installed alongside the in-process ones.',
+  },
+  'system/plugin_install': {
+    handling: 'declined',
+    note: 'headless plugin installation progress. A provisioning fact that precedes work rather than being work.',
+  },
+  'system/task_progress': {
+    handling: 'declined',
+    note: "periodic progress for a running task. High volume, and the entry's own age is the number that matters.",
+  },
+  'system/background_tasks_changed': {
+    handling: 'declined',
+    note: "declined on the type's own instruction. It is a level signal with replace semantics whose docs say the payload carries ids only and must not be correlated with the edge stream — so consuming it would mean rebuilding the entry set from ids, losing every entry's age and opening cause. The edges (task_started / task_updated / task_notification) are wired instead, and an edge that goes missing surfaces as an open entry with an age, which is the useful signal rather than the one a rebuild would erase.",
+  },
+  'system/thinking_tokens': {
+    handling: 'declined',
+    note: "a live thinking-token estimate for spinners. Explicitly approximate in its own docs, and telemetry's if anyone wants it.",
+  },
+  'system/commands_changed': {
+    handling: 'declined',
+    note: 'the slash-command list changed mid-session. A capability fact — what the session can do.',
+  },
+  'system/notification': {
+    handling: 'declined',
+    note: 'a loop-side text notification with a priority. Display.',
+  },
+  'system/files_persisted': {
+    handling: 'declined',
+    note: "file persistence results. The persistence layer's.",
+  },
+  'system/memory_recall': {
+    handling: 'declined',
+    note: 'memories surfaced into the turn. Context composition.',
+  },
+  'system/elicitation_complete': {
+    handling: 'declined',
+    note: 'a URL-mode elicitation confirmed complete by the MCP server. The ElicitationResult hook already closes the entry; consuming both would close it twice.',
+  },
+  'system/permission_denied': {
+    handling: 'declined',
+    note: 'mirrors the PermissionDenied hook, which is wired and additionally carries the deny reason. Consuming both would record one denial as two.',
+  },
+  'system/mirror_error': {
+    handling: 'declined',
+    note: "a real degrade — a transcript-mirror batch was dropped after retries. Declined here because it changes what can be read later, not what the session is doing; it is the persistence layer's to surface, and it must not be lost there.",
+  },
+  'system/informational': {
+    handling: 'declined',
+    note: 'a generic text banner, including hook feedback. Content.',
+  },
+} as const satisfies Record<MessageDiscriminator, CoverageRow>;
+
+/** Counts for the table's own summary line, computed rather than typed in — one less thing to rot. */
+export function coverageTally(table: Record<string, CoverageRow>): {
+  total: number;
+  wired: number;
+  declined: number;
+} {
+  const rows = Object.values(table);
+  return {
+    total: rows.length,
+    wired: rows.filter((row) => row.handling === 'wired').length,
+    declined: rows.filter((row) => row.handling === 'declined').length,
+  };
+}