@naswerks/periscope 1.0.0

package/dist/sessions/spawn-env.js

@@ -0,0 +1,277 @@
+/**
+ * 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.
+ */
+// ---------------------------------------------------------------------------
+// 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',
+];
+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
+];
+// 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'];
+/**
+ * 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 = [
+    // 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',
+];
+// ---------------------------------------------------------------------------
+// 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(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(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 = ALLOWED_EXACT;
+export const DECLARED_PREFIXES = ALLOWED_PREFIXES;
+export const DECLARED_SUFFIXES = ALLOWED_SUFFIXES;
+export const STRIPPED_HOST_SESSION_KEYS = HOST_SESSION_MARKERS;
+function isDenied(key, policy) {
+    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, policy = {}) {
+    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) => 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) {
+    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, policy = {}) {
+    const env = {};
+    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;
+}
+//# sourceMappingURL=spawn-env.js.map

package/dist/state/coverage.d.ts

@@ -0,0 +1,308 @@
+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 declare const HOOK_COVERAGE: {
+    readonly PreToolUse: {
+        readonly handling: "wired";
+        readonly 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.";
+    };
+    readonly PostToolUse: {
+        readonly handling: "wired";
+        readonly note: "closes the `tool` entry for its tool_use_id. The ordinary exit.";
+    };
+    readonly PostToolUseFailure: {
+        readonly handling: "wired";
+        readonly 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.";
+    };
+    readonly PostToolBatch: {
+        readonly handling: "wired";
+        readonly 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.";
+    };
+    readonly UserPromptSubmit: {
+        readonly handling: "wired";
+        readonly note: "state -> working. The turn boundary opening; the counterpart to Stop.";
+    };
+    readonly Stop: {
+        readonly handling: "wired";
+        readonly 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.";
+    };
+    readonly StopFailure: {
+        readonly handling: "wired";
+        readonly note: "state -> errored, carrying the SDKAssistantMessageError. Never collapsed into Stop: a turn that broke is not a turn that finished.";
+    };
+    readonly SessionStart: {
+        readonly handling: "wired";
+        readonly 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.";
+    };
+    readonly SessionEnd: {
+        readonly handling: "wired";
+        readonly note: "state -> ended, carrying the ExitReason. Never inferred from silence.";
+    };
+    readonly CwdChanged: {
+        readonly handling: "wired";
+        readonly note: "updates `where.cwd` for every later transition. Declining it would leave every subsequent record carrying a stale directory — a trace that lies quietly.";
+    };
+    readonly SubagentStart: {
+        readonly handling: "wired";
+        readonly note: "opens a `subagent` entry keyed by agent_id, carrying agent_type.";
+    };
+    readonly SubagentStop: {
+        readonly handling: "wired";
+        readonly note: "closes the `subagent` entry for its agent_id.";
+    };
+    readonly PreCompact: {
+        readonly handling: "wired";
+        readonly note: "opens a `compacting` entry, carrying trigger (manual | auto).";
+    };
+    readonly PostCompact: {
+        readonly handling: "wired";
+        readonly note: "closes the `compacting` entry.";
+    };
+    readonly PermissionRequest: {
+        readonly handling: "wired";
+        readonly 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.";
+    };
+    readonly PermissionDenied: {
+        readonly handling: "wired";
+        readonly 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.";
+    };
+    readonly Elicitation: {
+        readonly handling: "wired";
+        readonly note: "opens an `elicitation` entry for the MCP server. The session is genuinely blocked on an answer.";
+    };
+    readonly ElicitationResult: {
+        readonly handling: "wired";
+        readonly note: "closes the `elicitation` entry, carrying the action (accept | decline | cancel).";
+    };
+    readonly Notification: {
+        readonly handling: "declined";
+        readonly note: "a display notification (message, title, notification_type). Nothing about it moves the session; it is content, and content belongs to the streaming layer.";
+    };
+    readonly UserPromptExpansion: {
+        readonly handling: "declined";
+        readonly 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.";
+    };
+    readonly Setup: {
+        readonly handling: "declined";
+        readonly 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.";
+    };
+    readonly TeammateIdle: {
+        readonly handling: "declined";
+        readonly 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.";
+    };
+    readonly TaskCreated: {
+        readonly handling: "declined";
+        readonly 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.";
+    };
+    readonly TaskCompleted: {
+        readonly handling: "declined";
+        readonly note: "the closing half of TaskCreated, declined for the same unresolved overlap. system/task_notification is the completion signal that is wired.";
+    };
+    readonly ConfigChange: {
+        readonly handling: "declined";
+        readonly 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.";
+    };
+    readonly InstructionsLoaded: {
+        readonly handling: "declined";
+        readonly note: "memory/CLAUDE.md loading. Context composition, which is what a turn is made of rather than a condition it is in.";
+    };
+    readonly WorktreeCreate: {
+        readonly handling: "declined";
+        readonly 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.";
+    };
+    readonly WorktreeRemove: {
+        readonly handling: "declined";
+        readonly note: "as WorktreeCreate. Note that removing the worktree a session is in would be visible through CwdChanged, which is wired.";
+    };
+    readonly DirectoryAdded: {
+        readonly handling: "declined";
+        readonly 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.";
+    };
+    readonly FileChanged: {
+        readonly handling: "declined";
+        readonly note: "a watched file changed (change | add | unlink). High volume, driven by the filesystem rather than by the session, and it holds nothing.";
+    };
+    readonly MessageDisplay: {
+        readonly handling: "declined";
+        readonly 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.";
+    };
+};
+/**
+ * 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 declare const MESSAGE_COVERAGE: {
+    readonly 'system/init': {
+        readonly handling: "wired";
+        readonly 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.";
+    };
+    readonly 'system/status': {
+        readonly handling: "wired";
+        readonly 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.";
+    };
+    readonly 'system/session_state_changed': {
+        readonly handling: "wired";
+        readonly 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.";
+    };
+    readonly 'system/compact_boundary': {
+        readonly handling: "wired";
+        readonly note: "compaction actually happened, with trigger and token counts. Closes the compacting entry as a backstop for a PostCompact that never arrived.";
+    };
+    readonly 'system/task_started': {
+        readonly handling: "wired";
+        readonly 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.";
+    };
+    readonly 'system/task_updated': {
+        readonly handling: "wired";
+        readonly 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.";
+    };
+    readonly 'system/task_notification': {
+        readonly handling: "wired";
+        readonly 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.";
+    };
+    readonly 'system/worker_shutting_down': {
+        readonly handling: "wired";
+        readonly 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.";
+    };
+    readonly 'system/model_refusal_no_fallback': {
+        readonly handling: "wired";
+        readonly 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.";
+    };
+    readonly result: {
+        readonly handling: "wired";
+        readonly 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.";
+    };
+    readonly assistant: {
+        readonly handling: "declined";
+        readonly note: "model output. Content, owned by the streaming layer; the state it implies is already carried by system/status and system/session_state_changed.";
+    };
+    readonly user: {
+        readonly handling: "declined";
+        readonly note: "the turn input, including the replayed echo. UserPromptSubmit is the wired boundary; this is the payload that crossed it.";
+    };
+    readonly stream_event: {
+        readonly handling: "declined";
+        readonly note: "partial assistant deltas. The highest-volume message in the union and pure content — the streaming layer's.";
+    };
+    readonly tool_progress: {
+        readonly handling: "declined";
+        readonly 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.";
+    };
+    readonly tool_use_summary: {
+        readonly handling: "declined";
+        readonly note: "a prose summary of preceding tool calls. Content.";
+    };
+    readonly auth_status: {
+        readonly handling: "declined";
+        readonly note: "isAuthenticating plus provider output. An identity-plane fact; the session is not blocked on it in a way this model can name.";
+    };
+    readonly rate_limit_event: {
+        readonly handling: "declined";
+        readonly note: "rate-limit windows. Usage and cost belong to the telemetry lane, which reads the same stream.";
+    };
+    readonly prompt_suggestion: {
+        readonly handling: "declined";
+        readonly note: "a predicted next prompt. A suggestion for a human; nothing has happened.";
+    };
+    readonly conversation_reset: {
+        readonly handling: "declined";
+        readonly 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.";
+    };
+    readonly 'system/api_retry': {
+        readonly handling: "declined";
+        readonly 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.";
+    };
+    readonly 'system/control_request_progress': {
+        readonly handling: "declined";
+        readonly note: "progress for a client-originated control request. It belongs to whoever made that request, correlated by its own request_id.";
+    };
+    readonly 'system/model_refusal_fallback': {
+        readonly handling: "declined";
+        readonly note: "the turn was retried on a fallback model and continues. Nothing ended; the no-fallback counterpart is the one that is wired.";
+    };
+    readonly 'system/local_command_output': {
+        readonly handling: "declined";
+        readonly note: "output from a local slash command. Content.";
+    };
+    readonly 'system/hook_started': {
+        readonly handling: "declined";
+        readonly 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.";
+    };
+    readonly 'system/hook_progress': {
+        readonly handling: "declined";
+        readonly note: "as system/hook_started — the command-hook mechanism, unused here.";
+    };
+    readonly 'system/hook_response': {
+        readonly handling: "declined";
+        readonly 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.";
+    };
+    readonly 'system/plugin_install': {
+        readonly handling: "declined";
+        readonly note: "headless plugin installation progress. A provisioning fact that precedes work rather than being work.";
+    };
+    readonly 'system/task_progress': {
+        readonly handling: "declined";
+        readonly note: "periodic progress for a running task. High volume, and the entry's own age is the number that matters.";
+    };
+    readonly 'system/background_tasks_changed': {
+        readonly handling: "declined";
+        readonly 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.";
+    };
+    readonly 'system/thinking_tokens': {
+        readonly handling: "declined";
+        readonly note: "a live thinking-token estimate for spinners. Explicitly approximate in its own docs, and telemetry's if anyone wants it.";
+    };
+    readonly 'system/commands_changed': {
+        readonly handling: "declined";
+        readonly note: "the slash-command list changed mid-session. A capability fact — what the session can do.";
+    };
+    readonly 'system/notification': {
+        readonly handling: "declined";
+        readonly note: "a loop-side text notification with a priority. Display.";
+    };
+    readonly 'system/files_persisted': {
+        readonly handling: "declined";
+        readonly note: "file persistence results. The persistence layer's.";
+    };
+    readonly 'system/memory_recall': {
+        readonly handling: "declined";
+        readonly note: "memories surfaced into the turn. Context composition.";
+    };
+    readonly 'system/elicitation_complete': {
+        readonly handling: "declined";
+        readonly note: "a URL-mode elicitation confirmed complete by the MCP server. The ElicitationResult hook already closes the entry; consuming both would close it twice.";
+    };
+    readonly 'system/permission_denied': {
+        readonly handling: "declined";
+        readonly note: "mirrors the PermissionDenied hook, which is wired and additionally carries the deny reason. Consuming both would record one denial as two.";
+    };
+    readonly 'system/mirror_error': {
+        readonly handling: "declined";
+        readonly 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.";
+    };
+    readonly 'system/informational': {
+        readonly handling: "declined";
+        readonly note: "a generic text banner, including hook feedback. Content.";
+    };
+};
+/** Counts for the table's own summary line, computed rather than typed in — one less thing to rot. */
+export declare function coverageTally(table: Record<string, CoverageRow>): {
+    total: number;
+    wired: number;
+    declined: number;
+};
+//# sourceMappingURL=coverage.d.ts.map