threadwire 0.1.20 → 0.1.22

package/CHANGELOG.md

@@ -2,6 +2,124 @@
 
 ## Unreleased
 
+- Fix Node 24 release-prepublish timeouts in `run-worker` process-tree cleanup.
+  The dedicated `npm-release` service now runs with Docker's `init: true` so
+  terminated descendants are reaped instead of becoming zombies that keep the
+  attempt-owned process group alive. Harden the default process-group probe in
+  `src/run-worker.js` to treat `EPERM` as "still alive" and only `ESRCH`/`EINVAL`
+  as "gone", preventing false settlement when signaling is denied. Add a focused
+  regression test that mocks `process.kill` returning `EPERM`.
+
+- Allow the Kimi model broker to bind port `0` for both the admin and worker
+  listeners and expose the OS-assigned actual ports in the returned config.
+  Update `test/kimi-model-broker.test.js` to use this deterministic allocation
+  instead of a `freePort()` helper that closed a socket before the broker
+  rebound it, eliminating the EADDRINUSE race when `node --test` runs test
+  files concurrently. Add a regression test that starts many brokers in
+  parallel with port `0` and verifies no duplicate ports are assigned.
+  Production defaults (8791/8792) and explicit fixed-port configuration are
+  unchanged.
+
+- Mount the existing read-only GitHub CLI config into the dedicated
+  `npm-release` service at `${DEV_CONTAINER_HOME}/.config/gh` and set
+  `GH_CONFIG_DIR`. The `docker/npm-release-entrypoint.sh` entrypoint now runs
+  `gh auth setup-git` before forwarding to `npm run release:patch`, initializing
+  GitHub CLI's HTTPS credential helper in the writable HOME git config from the
+  read-only GH config so the fresh origin/master preflight (`git fetch origin`)
+  can authenticate. Fail closed if setup-git fails. The npm publish token remains
+  the only release-only credential; no provider runtime, agent context, or
+  provider credentials are added to `npm-release`, and `home-init` still
+  receives no auth mounts. Update `AGENTS.md`,
+  `docs/development-container.md`, and contract tests to match.
+
+- Align npm release auth with the fleet standard. Rename
+  `NPM_CONFIG_SOURCE_PATH` to `NPM_AUTH_SOURCE_PATH`; the canonical credential
+  is `${NPM_AUTH_SOURCE_PATH}/npmrc` and is mounted read-only into the
+  dedicated `npm-release` service at `${DEV_CONTAINER_HOME}/.npmrc`. The
+  persistent `app` service and profile-free `home-init` never receive the npm
+  auth source. Update `.env.example`, `AGENTS.md`,
+  `docs/development-container.md`, and tests to match.
+
+- Add `release-patch@1.0.3` as a devDependency and a `release:patch` package
+  script. `npm run release:patch` is now the only normal publishing path; it
+  owns version bump, changelog/tag handling, publish verification, and the
+  final `npm publish` step. The dedicated `npm-release` service in
+  `compose.dev.yaml` now runs `npm run release:patch` instead of invoking
+  `npm publish` directly, and `AGENTS.md` and `docs/development-container.md`
+  document the new contract.
+
+- Add a dedicated, profile-gated `npm-release` service to `compose.dev.yaml`
+  for npm releases. The service mounts the server-held publish token read-only
+  at `${DEV_CONTAINER_HOME}/.npmrc`, runs as UID/GID 1000 on the canonical
+  checkout, and executes the repository-owned `npm publish` procedure. The
+  persistent `app` service no longer mounts the npm auth config, so the token
+  is never exposed to workers, scripts, or the long-running development
+  container. A new `docker/npm-release-entrypoint.sh` image entrypoint simply
+  forwards to the release command without loading auth, agent context, or
+  provider discovery links. `AGENTS.md`, `docs/development-container.md`, and
+  `.env.example` document the new release-only workflow.
+
+- Add a per-run SQLite evidence index using the built-in `node:sqlite` module.
+  Every evidence-creating run now writes a private, pending-until-finalized
+  `.index` database alongside the canonical raw and result artifacts. The index
+  stores a versioned manifest and an ordered event ledger of bounded fixed kinds
+  (prompt, provider stdout/stderr, assistant, tool, lifecycle, diagnostic,
+  context metrics, provider result) with timestamps, order, and artifact
+  references; it does not duplicate arbitrarily large raw chunks and applies the
+  same redaction and retention boundaries as the existing `read` surface. Indexes
+  use `DELETE` journal mode and atomic rename so crashes leave no published
+  database; leftover pending/journal files are reconciled on startup and removed
+  with their run when the last artifact is cleaned up.
+- Add `threadwire evidence inspect --handle evidence_<bearer>` with fixed
+  selectors only: `--summary`, `--events` (with optional `--kind`, `--after`,
+  `--before`, and `--limit`), and `--failures` (with optional `--after` and
+  `--limit`). The database path is never exposed, results are byte/event bounded,
+  and authorization, expiry, and redaction remain consistent with `threadwire evidence read`.
+  `--failures` filters diagnostic errors and finished tool events inside SQLite
+  before applying the limit, supports deterministic `--after` pagination, and
+  reports `truncated: true` only when additional matching failures exist.
+  Telegram ingress creates and finalizes the same per-run index for its evidence runs.
+- Account per-run `.index` bytes against the existing `maxRunBytes` and
+  `maxStoreBytes` quotas with bounded per-event reservations and final-size
+  settlement. Index growth that would exceed a run or store limit is rejected
+  safely, the pending database is never published, and bytes are released when a
+  run's last artifact is cleaned up, revoked, or aborted before finalization;
+  restart reconciliation reserves bytes for existing ready indexes.
+- Apply the artifact redaction policy to index event metadata: secrets
+  configured for `evidence read` are replaced with `[REDACTED]` in persisted and
+  returned index summaries, lifecycle/diagnostic strings, and tool detail before
+  SQLite storage or inspection output; raw evidence remains the canonical
+  unindexed source.
+- Upgrade the checked-in Node runtime target to the Node 24 LTS (Krypton)
+  release `v24.19.0`. Update `Dockerfile`, `docker/Dockerfile.dev`,
+  `src/isolated-runtime.js`, `docker/test/isolated-runtime-e2e.sh`, tests,
+  `AGENTS.md`, `README.md`, and `docs/container-runtime.md`; update
+  `@types/node` to `24.13.3` and `engines.node` to `>=24` in `package.json`.
+  Archive SHA-256 values for the development image are verified against the
+  official Node SHASUMS256.txt.
+
+- Standardize the development container on Hermes' shared provider runtime with
+  UID/GID-1000-only Codex, OpenCode, and Kimi bootstrap links.
+- Keep the OpenCode data directory (`~/.local/share/opencode`) local to each
+  `DEV_HOME_PATH`; share only the `auth.json` file from the provider runtime and
+  continue sharing the dedicated `.opencode` plugin-state directory. Update the
+  home initializer, entrypoint verification, tests, and guidance to match.
+
+- Make the checked-in development container portable and secure for direct
+  native Kimi: runtime paths (`DEV_CONTAINER_HOME`, `KIMI_CODE_HOME`) are
+  explicit, portable, and absolute instead of hard-coded `/home/dev`; the
+  immutable agent context mounts from the named external Docker volume
+  `AGENT_CONTEXT_VOLUME` rather than a host path; agent-context links for Kimi
+  go to the configured `KIMI_CODE_HOME`, which may differ from the dev home;
+  direct Kimi auth mounts from the named external volume `KIMI_AUTH_VOLUME`
+  only as narrow subpaths under the configurable `KIMI_AUTH_VOLUME_SUBPATH`
+  (default `.kimi-code`; `credentials` writable, `config.toml` and `device_id`
+  read-only) in the normal `app` service; a dedicated profiled `kimi-auth`
+  service bypasses the normal dev entrypoint, mounts the full auth volume root
+  writable, bootstraps the configured subpath, and runs `kimi login` for
+  interactive authentication/refresh. The Kimi Code CLI in the dev image is
+  pinned to `0.34.0` with the same integrity verification used in production.
+  Production runtime files remain unchanged.
 - Resolve native Kimi through the normal `PATH` (`kimi`) instead of requiring
   `/usr/local/bin/kimi`; `THREADWIRE_KIMI_BIN` remains the explicit override.
 - Resolve native Codex through `THREADWIRE_CODEX_BIN` or normal `PATH` lookup,

package/README.md

@@ -24,7 +24,7 @@ See [Isolated provider runtime](docs/isolated-provider-runtime.md).
 
 ## Run with npx
 
-Threadwire requires Node.js 22 or newer. Run the published CLI without a global
+Threadwire requires Node.js 24 or newer. Run the published CLI without a global
 installation:
 
 ```sh
@@ -122,7 +122,9 @@ Provider stdout is decoded as JSONL with a finite 1 MiB UTF-8 byte limit for eac
 
 For normal `threadwire run` execution, Threadwire stdout is the parent-model admission plane. It emits exactly one versioned terminal `delegated_result` JSON object and no progress records. The envelope contains a bounded, credential-redacted, control-normalized final conclusion when one was produced, structured terminal state and exit code, and the exact bounded provider session handle when available. Its closed schema can also represent concise blocker/decision requests, opaque artifact handles, commit/URL references, and a concise validation summary; current provider adapters do not infer these optional fields from prose. Unknown, nested, wrongly typed, cardinality-invalid, or oversized admission candidates fail closed. See [Delegated-result protocol](docs/delegated-result-protocol.md) for the complete schema, limits, and caller obligations.
 
-Scoped evidence artifacts are separate from both files above. Set the trusted operator setting `THREADWIRE_EVIDENCE_ROOT` for standalone runs; Telegram ingress uses its dedicated evidence volume automatically. CLI and ingress runs reserve separate normalized provider-result and raw prompt/provider-stream artifacts; CLI raw evidence also records final context metrics. A raw handle enters a normalized result only after the raw artifact is durable; if raw metrics append or finalization fails, the error remains visible while the completed provider result retains only its independently durable result handle. The result artifact carries a stable delivery identity and authenticated state, and ingress sends that result handle through the same bounded notice queue. Retrieve later with `threadwire evidence read` or the authenticated `/evidence` Telegram command and an explicit bounded selector. See [Evidence artifacts](docs/evidence-artifacts.md) for permissions, delivery states, quotas, retention, recovery, authorization, redaction, privacy, and cleanup behavior.
+Scoped evidence artifacts are separate from both files above. Set the trusted operator setting `THREADWIRE_EVIDENCE_ROOT` for standalone runs; Telegram ingress uses its dedicated evidence volume automatically. CLI and ingress runs reserve separate normalized provider-result and raw prompt/provider-stream artifacts; CLI raw evidence also records final context metrics. A raw handle enters a normalized result only after the raw artifact is durable; if raw metrics append or finalization fails, the error remains visible while the completed provider result retains only its independently durable result handle. The result artifact carries a stable delivery identity and authenticated state, and ingress sends that result handle through the same bounded notice queue. Retrieve later with `threadwire evidence read`, inspect the per-run SQLite index
+with `threadwire evidence inspect`, or use the authenticated `/evidence` Telegram
+command with an explicit bounded selector. See [Evidence artifacts](docs/evidence-artifacts.md) for permissions, delivery states, quotas, retention, recovery, authorization, redaction, privacy, cleanup, and the inspect fixed-selector contract.
 
 `threadwire capacity` is a read-only reporting command that probes live account capacity for authenticated Codex (`codex app-server` JSON-RPC `account/rateLimits/read`) and Kimi (`GET https://api.kimi.com/coding/v1/usages` with the installed OAuth credential), normalizes both into one closed short/long-window schema, and prints one deterministic reserve-gated admission selection as a single JSON document. It persists nothing, never prints tokens or account data, takes no session arguments, and does not change `run` provider selection; an external worker ledger consumes the report and owns pinning provider/model/session. See [Capacity admission](docs/capacity-admission.md) for the schema, tie-break, error taxonomy, and security boundary.
 
@@ -139,7 +141,7 @@ The delivery queue has finite defaults of 100 pending notices and 256 KiB of pen
 ## Development
 
 The checked-in development container is the `app` service in `compose.dev.yaml`
-(Ubuntu 26.04 pinned by digest, non-root `1000:1000`, Node 22 LTS, npm-latest
+(Ubuntu 26.04 pinned by digest, non-root `1000:1000`, Node 24 LTS, npm-latest
 coding CLI baseline). Setup, the read-only GitHub CLI and agent-context mount
 contracts, and container commands are documented in [AGENTS.md](AGENTS.md).
 

package/docs/container-runtime.md

@@ -19,7 +19,7 @@ force unless `THREADWIRE_MAX_CONCURRENT_WORKERS` is explicitly lowered or raised
 
 ## Build and configure
 
-Use Node image `node:22.17.0-bookworm-slim`. The build derives seed identity
+Use Node image `node:24.19.0-bookworm-slim`. The build derives seed identity
 inside the image from deterministic paths, modes, file contents, symlink targets, and the generated `node_modules`; only `.git` and the identity output itself are excluded. No caller revision argument is accepted. The exact base-image tags are recorded but are not claimed
 immutable. Replace them with registry-verified manifest digests during a release
 only after independently verifying those digests; no digest is invented here.
@@ -211,7 +211,7 @@ relay also uses UID/GID 10003 with no mounts and no credential environment; the
 worker uses
 UID/GID 10002 with only the selected worktree and provider-bound state; the
 root supervisor alone receives the Docker socket. The broker/auth service uses
-Node `22.19.0` and exactly `@moonshot-ai/kimi-code@0.29.2` with the checked npm
+Node `24.19.0` and exactly `@moonshot-ai/kimi-code@0.34.0` with the checked npm
 integrity and archive SHA-512 in the Dockerfile.
 
 Enable the checked-in override with `--profile kimi` only after the OAuth/model

package/docs/development-container.md

@@ -6,30 +6,74 @@ installs Codex CLI, Claude Code CLI, the official Kimi Code CLI, OpenCode,
 `oc-codex-multi-auth`, `@ai-sdk/openai-compatible`, and `@ai-sdk/xai` during the
 Docker build. Runtime setup never downloads a plugin through `npx`.
 
-## Source paths
+## Source paths and volumes
 
 All source paths in `.env` are required and have no checked-in host defaults:
 
-- `DEV_HOME_PATH` is the complete dedicated development home. It remains the
-  owner of OpenCode database, session, log, and cache state.
+- `DEV_HOME_PATH` is the complete dedicated development home on the host. It
+  remains the owner of OpenCode database, session, log, and cache state.
+- `DEV_CONTAINER_HOME` is the absolute container path where `DEV_HOME_PATH` is
+  bind-mounted writable. The Threadwire checkout is expected at
+  `${DEV_CONTAINER_HOME}/threadwire`.
+- Kimi Code uses the standard `${DEV_CONTAINER_HOME}/.kimi-code` home.
 - `GH_CONFIG_SOURCE_PATH` is the GitHub CLI config directory and mounts
-  read-only.
-- `CODEX_AUTH_SOURCE_PATH` is native Codex's `auth.json` and mounts read-write
-  so OAuth refreshes persist to its canonical owner.
-- `OPENCODE_AUTH_SOURCE_PATH` is OpenCode's native `auth.json`. DeepSeek, xAI,
-  and Moonshot AI keys are entered with OpenCode's auth flow and persist
-  through this read-write file mount.
-- `OPENCODE_CODEX_STATE_SOURCE_PATH` is the plugin's dedicated state directory,
-  containing the OpenAI OAuth file and global account pool. It mounts
-  read-write as a directory because pool updates use atomic sibling-file
-  replacement.
-- `AGENT_CONTEXT_PATH` is the immutable agent-context snapshot and mounts
-  read-only.
-
-Hermes owns the canonical credential files. Do not copy them into the checkout,
-the image, or project-keyed task-home files. The app sets
-`CODEX_AUTH_PER_PROJECT_ACCOUNTS=0`, so `oc-codex-multi-auth` uses its one
-global mounted account pool rather than creating per-project credential copies.
+  read-only at `${DEV_CONTAINER_HOME}/.config/gh`.
+- `NPM_AUTH_SOURCE_PATH` is the server-held npm auth directory. The canonical
+  credential is `${NPM_AUTH_SOURCE_PATH}/npmrc`; it is mounted read-only into
+  the dedicated `npm-release` service at `${DEV_CONTAINER_HOME}/.npmrc` so
+  `npm publish` can authenticate without copying tokens into the checkout,
+  image, or writable container state. The persistent `app` service never
+  receives this mount.
+- `PROVIDER_RUNTIME_SOURCE_PATH` is Hermes' canonical shared provider runtime,
+  mounted at `/opt/hermes-dind-shared/auth/provider-runtime`.
+- `AGENT_CONTEXT_VOLUME` is the name of the external Docker volume that holds
+  the immutable agent-context snapshot. It mounts read-only at
+  `/opt/agent-context`.
+
+Hermes owns the canonical provider runtime. The UID/GID-1000 initializer links
+`.codex`, `.opencode`, and `.kimi-code` from the development home to matching
+directories under the mounted runtime. The OpenCode data directory
+`~/.local/share/opencode` remains local within `DEV_HOME_PATH`; only its
+`auth.json` file is linked to the shared runtime. It fails closed on
+conflicting paths and never copies credentials or changes host ownership. The
+app sets `CODEX_AUTH_PER_PROJECT_ACCOUNTS=0`, so `oc-codex-multi-auth` uses its
+one global mounted account pool rather than creating per-project credential
+copies.
+
+## Provider runtime bootstrap
+
+The profile-free `home-init` service creates the four provider-home symlinks as
+UID/GID 1000 before Docker creates the profiled app container. The app mounts
+the shared runtime read-write so provider login and token refresh can update its
+canonical owner. No development service starts as root or invokes `chown`.
+
+## npm releases
+
+Publish releases from the dedicated `npm-release` service. This profile-gated,
+short-lived container is the only place the server-held npm publish token is
+mounted; the persistent `app` service never sees it.
+
+```sh
+docker compose -f compose.dev.yaml --profile npm-release run --rm npm-release
+```
+
+The service runs `npm run release:patch` as UID/GID `1000` in the canonical
+checkout at `${DEV_CONTAINER_HOME}/threadwire`, with
+`${NPM_AUTH_SOURCE_PATH}/npmrc` bound read-only at
+`${DEV_CONTAINER_HOME}/.npmrc`. It also binds the existing GitHub CLI config
+read-only at `${DEV_CONTAINER_HOME}/.config/gh` and sets
+`GH_CONFIG_DIR: ${DEV_CONTAINER_HOME}/.config/gh`. Before forwarding to
+`npm run release:patch`, the entrypoint runs `gh auth setup-git`, initializing
+GitHub CLI's HTTPS credential helper in the writable HOME git config from the
+read-only GH config so the fresh origin/master preflight (`git fetch origin`)
+can authenticate; it fails closed if setup-git fails. No GitHub token is copied
+and the npm publish token remains release-only. It mounts only the dev home,
+the npmrc file, and the read-only GitHub config; it does not mount agent
+context, Codex, OpenCode, or Kimi credentials. `npm run release:patch` is the
+only normal publishing path and owns the version bump, changelog/tag handling,
+and publish verification; do not run `npm publish` directly. The repository's
+`prepublishOnly` script still runs `npm run all-checks` and `npm run
+verify:package` as the final publish gate.
 
 ## OpenCode catalog
 

package/docs/evidence-artifacts.md

@@ -123,6 +123,53 @@ and their pointer values become `[REDACTED]`; responses state whether they were
 redacted or truncated. This finite policy is defense in depth, not
 arbitrary-secret detection.
 
+## Per-run SQLite index
+
+Every run that creates evidence also builds a private per-run SQLite index using
+the built-in `node:sqlite` module. The index is created in a pending state and
+atomically renamed to a ready `.index` file only after the run's result artifact
+is finalized, so a crash or finalization failure leaves no published database.
+It uses `DELETE` journal mode: transient SQLite sidecars are removed on commit
+and any leftover journal files are reconciled on startup. The index is stored
+alongside the canonical raw and result artifacts and is removed when the run's
+last artifact is cleaned up or revoked.
+
+The index stores a versioned manifest (provider, destination, timestamps,
+terminal state) and an ordered event ledger of bounded, fixed kinds: `prompt`,
+`provider_stdout`, `provider_stderr`, `assistant`, `tool`, `lifecycle`,
+`diagnostic`, `context_metrics`, and `provider_result`. It records metadata,
+timestamps, order, and artifact references rather than duplicating arbitrarily
+large raw chunks; the canonical raw evidence remains the source of truth.
+Sensitive material is bounded or omitted consistently with the `read` surface.
+
+Inspect the index through the same opaque bearer handle with fixed selectors
+only; the database path is never exposed.
+
+```console
+threadwire evidence inspect --handle evidence_<bearer> --summary
+threadwire evidence inspect --handle evidence_<bearer> --events --kind tool --limit 50
+threadwire evidence inspect --handle evidence_<bearer> --failures --limit 20
+```
+
+`--summary` returns manifest, totals, and per-kind counts. `--events` supports an
+optional `--kind` filter plus `--after`/`--before` order bounds and `--limit`
+(up to 1000). `--failures` returns diagnostic errors and finished tool events,
+supports `--after` pagination, and reports `truncated: true` only when further
+matching failures exist after the returned page. Filtering happens inside SQLite
+before the result limit, so benign rows never hide later failures.
+
+The `.index` file size is counted against the same `maxRunBytes` and
+`maxStoreBytes` quotas as other artifacts; the store reserves a bounded per-event
+allowance during ingestion and settles against the final file size. Index growth
+is rejected safely rather than allowed to exhaust the volume, and the index is
+removed and its quota released when the run's last artifact is cleaned up,
+revoked, or aborted before finalization. All index event metadata is redacted
+with the same artifact redaction policy as `evidence read` before persistence
+and before return, so provider secrets do not leak into the queryable index.
+
+All results are byte/event bounded and expire with the artifact. A wrong scope,
+bad selector, missing capability, or expired index reports generic unavailability.
+
 ## Operations
 
 Run `cleanup()` from maintenance and use scoped removal for revocation. Cleanup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadwire",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Stream Codex, Claude, Kimi Code, and OpenCode worker progress to an explicit Telegram destination",
   "keywords": [
     "ai-agent",
@@ -30,7 +30,7 @@
     "threadwire-telegram-webhook": "bin/telegram-webhook.js"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "repository": {
     "type": "git",
@@ -55,16 +55,18 @@
     "test:container-e2e": "sh docker/test/production-e2e.sh",
     "test:isolated-runtime-e2e": "sh docker/test/isolated-runtime-e2e.sh",
     "typecheck": "tsc --noEmit",
+    "release:patch": "release-patch",
     "verify:package": "node scripts/verify-package.js",
     "test:kimi-isolated-runtime-e2e": "sh docker/test/kimi-isolated-runtime-e2e.sh"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@types/node": "22.15.3",
+    "@types/node": "24.13.3",
     "eslint": "10.0.1",
     "eslint-plugin-jsdoc": "63.0.0",
     "fallow": "3.2.0",
     "globals": "17.0.0",
+    "release-patch": "1.0.3",
     "typescript": "6.0.2"
   },
   "license": "AGPL-3.0-only"

package/scripts/verify-package.js

@@ -48,6 +48,7 @@ const EXPECTED_FILES = [
   "src/context-budget-metrics.js",
   "src/delegated-result-admission.js",
   "src/docker-api.js",
+  "src/evidence-index.js",
   "src/evidence-store.js",
   "src/isolated-runtime-client.js",
   "src/isolated-runtime.js",
@@ -70,6 +71,7 @@ const EXPECTED_FILES = [
   "src/providers/index.js",
   "src/providers/kimi.js",
   "src/providers/opencode.js",
+  "src/redaction.js",
   "src/provider-capacity-codex.js",
   "src/provider-capacity-kimi.js",
   "src/provider-capacity.js",

package/src/cli.js

@@ -15,6 +15,7 @@ import {buildProviderEnvironment, collectEvidenceRedactions, parseTelegramReques
 import {WorkerControl} from "./worker-control.js"
 import {EvidenceStore} from "./evidence-store.js"
 import {ContextBudgetMetrics} from "./context-budget-metrics.js"
+import {workerEventToIndexEvent} from "./evidence-index.js"
 import {isolatedRuntimeClientFromEnvironment} from "./isolated-runtime-client.js"
 import {validateRelayWriteProviderArguments} from "./relay-write.js"
 import {abortable} from "./absolute-deadline.js"
@@ -40,6 +41,8 @@ const HELP = `Usage: threadwire run --provider <codex|claude|kimi|opencode> --ta
   [-- <provider arguments...>]
        threadwire evidence read --handle <opaque-handle>
   (--bytes <offset>:<limit> | --lines <start>:<limit> | --query <literal> --context-bytes <limit>)
+       threadwire evidence inspect --handle <opaque-handle>
+  (--summary | --events [--kind <kind>] [--after <order>] [--before <order>] [--limit <positive-integer>] | --failures [--after <order>] [--limit <positive-integer>])
        threadwire capacity [--provider <codex|kimi>]...
   [--short-reserve-percent <0-100>] [--long-reserve-percent <0-100>]
   [--timeout-ms <positive-integer>]
@@ -47,7 +50,7 @@ const HELP = `Usage: threadwire run --provider <codex|claude|kimi|opencode> --ta
   (Emits one closed versioned JSON status document from the activity log.)`
 
 /** @typedef {{provider: string, target: string, cwd: string, toolMessages: boolean, relayWrite: boolean, prompt?: string, promptFile?: string, processNumber?: number, maxOutputLength?: number, resumeSession?: string, transcript?: string, activityLog?: string, providerArguments: string[]}} ParsedArguments */
-/** @typedef {{evidenceRead: true, request: unknown}} EvidenceParsedArguments */
+/** @typedef {{evidenceRead: true, request: unknown} | {evidenceInspect: true, request: unknown}} EvidenceParsedArguments */
 /** @typedef {{capacity: true, providers: import("./provider-capacity.js").CapacityProvider[], shortReservePercent: number, longReservePercent: number, timeoutMs: number}} CapacityParsedArguments */
 /** @typedef {{probe: (provider: import("./provider-capacity.js").CapacityProvider, timeoutMs?: number) => Promise<import("./provider-capacity.js").CapacityCandidate>}} CapacityProbeDependency */
 /**
@@ -128,31 +131,77 @@ export function parseArguments(arguments_) {
 }
 
 /** @param {string[]} arguments_ @returns {EvidenceParsedArguments} */
-function parseEvidenceArguments(arguments_) {
-  if (arguments_[1] !== "read") throw new Error(HELP)
-  /** @type {Record<string, string>} */
+export function parseEvidenceArguments(arguments_) {
+  const subcommand = arguments_[1]
+  if (subcommand !== "read" && subcommand !== "inspect") throw new Error(HELP)
+  /** @type {Record<string, string | boolean>} */
   const options = {}
-  for (let index = 2; index < arguments_.length; index += 2) {
+  let index = 2
+  while (index < arguments_.length) {
     const name = arguments_[index]
+    if (name === "--summary" || name === "--events" || name === "--failures") {
+      if (options[name] !== undefined) throw new Error(`Duplicate evidence option: ${name}`)
+      options[name] = true
+      index += 1
+      continue
+    }
     const value = arguments_[index + 1]
-    if (!name || !value || !["--handle", "--bytes", "--lines", "--query", "--context-bytes"].includes(name)) throw new Error(HELP)
+    if (!name || value === undefined) throw new Error(HELP)
+    const readOptions = ["--handle", "--bytes", "--lines", "--query", "--context-bytes"]
+    const inspectOptions = ["--handle", "--kind", "--after", "--before", "--limit"]
+    const allowed = subcommand === "read" ? readOptions : inspectOptions
+    if (!allowed.includes(name)) throw new Error(HELP)
     if (options[name] !== undefined) throw new Error(`Duplicate evidence option: ${name}`)
     options[name] = value
+    index += 2
   }
-  const handle = options["--handle"]
+  const handle = /** @type {string | undefined} */ (options["--handle"])
   if (!handle) throw new Error("--handle is required")
-  const selectors = ["--bytes", "--lines", "--query"].filter((name) => options[name] !== undefined)
-  if (selectors.length !== 1) throw new Error("Exactly one bounded evidence selector is required")
-  let request
-  if (options["--bytes"]) request = {handle, bytes: rangePair(options["--bytes"], true)}
-  else if (options["--lines"]) request = {handle, lines: rangePair(options["--lines"], false)}
-  else {
-    const context = options["--context-bytes"]
-    if (!context) throw new Error("--context-bytes is required with --query")
-    request = {handle, query: {literal: options["--query"], limit: 1, contextBytes: positiveInteger(context, "--context-bytes")}}
+  if (subcommand === "read") {
+    const selectors = ["--bytes", "--lines", "--query"].filter((name) => options[name] !== undefined)
+    if (selectors.length !== 1) throw new Error("Exactly one bounded evidence selector is required")
+    let request
+    if (options["--bytes"]) request = {handle, bytes: rangePair(/** @type {string} */ (options["--bytes"]), true)}
+    else if (options["--lines"]) request = {handle, lines: rangePair(/** @type {string} */ (options["--lines"]), false)}
+    else {
+      const context = options["--context-bytes"]
+      if (!context) throw new Error("--context-bytes is required with --query")
+      request = {handle, query: {literal: options["--query"], limit: 1, contextBytes: positiveInteger(/** @type {string} */ (context), "--context-bytes")}}
+    }
+    if (options["--query"] === undefined && options["--context-bytes"] !== undefined) throw new Error("--context-bytes requires --query")
+    return {evidenceRead: true, request}
+  }
+  const selectors = ["--summary", "--events", "--failures"].filter((name) => options[name] !== undefined)
+  if (selectors.length !== 1) throw new Error("Evidence inspect requires exactly one fixed selector")
+  const allowed = options["--summary"]
+    ? ["--handle", "--summary"]
+    : options["--events"]
+      ? ["--handle", "--events", "--kind", "--after", "--before", "--limit"]
+      : ["--handle", "--failures", "--after", "--limit"]
+  const allowedSet = new Set(allowed)
+  for (const key of Object.keys(options)) {
+    if (!allowedSet.has(key)) throw new Error(`Incompatible evidence inspect flag: ${key}`)
   }
-  if (options["--query"] === undefined && options["--context-bytes"] !== undefined) throw new Error("--context-bytes requires --query")
-  return {evidenceRead: true, request}
+  /** @type {import("./evidence-index.js").EvidenceInspectRequest} */
+  let request = {handle}
+  if (options["--summary"]) {
+    request = {...request, summary: true}
+  } else if (options["--events"]) {
+    /** @type {NonNullable<import("./evidence-index.js").EvidenceInspectRequest["events"]>} */
+    const events = {}
+    if (options["--kind"]) events.kind = /** @type {string} */ (options["--kind"])
+    if (options["--after"]) events.after = positiveInteger(/** @type {string} */ (options["--after"]), "--after")
+    if (options["--before"]) events.before = positiveInteger(/** @type {string} */ (options["--before"]), "--before")
+    if (options["--limit"]) events.limit = positiveInteger(/** @type {string} */ (options["--limit"]), "--limit")
+    request = {...request, events}
+  } else {
+    /** @type {NonNullable<import("./evidence-index.js").EvidenceInspectRequest["failures"]>} */
+    const failures = {}
+    if (options["--after"]) failures.after = positiveInteger(/** @type {string} */ (options["--after"]), "--after")
+    if (options["--limit"]) failures.limit = positiveInteger(/** @type {string} */ (options["--limit"]), "--limit")
+    request = {...request, failures}
+  }
+  return {evidenceInspect: true, request}
 }
 
 /** @param {string[]} arguments_ @returns {CapacityParsedArguments | {help: true}} */
@@ -292,13 +341,15 @@ export async function main(arguments_, dependencies = {}) {
       })}\n`)
       return selection === null ? 2 : 0
     }
-    if ("evidenceRead" in parsed) {
+    if ("evidenceRead" in parsed || "evidenceInspect" in parsed) {
       const root = evidenceRoot(sourceEnvironment.THREADWIRE_EVIDENCE_ROOT)
       if (!root) throw new Error("THREADWIRE_EVIDENCE_ROOT is required")
       if (validateOnly) return 0
       const store = await EvidenceStore.open({root})
       try {
-        const result = await store.readBearer(parsed.request)
+        const result = "evidenceRead" in parsed
+          ? await store.readBearer(parsed.request)
+          : await store.inspectBearer(parsed.request)
         output.write(`${JSON.stringify(result)}\n`)
         return 0
       } finally {
@@ -360,6 +411,11 @@ export async function main(arguments_, dependencies = {}) {
     let resultEvidenceBytes = 0
     const deliveryIdentity = randomUUID()
     const launchDeadline = isolatedPreflight?.deadline
+    /** @param {import("./evidence-index.js").EvidenceIndexEvent} event */
+    const recordEvidenceEvent = (event) => {
+      if (evidenceStore === undefined || evidenceOwner === undefined) return Promise.resolve()
+      return evidenceStore.recordEvent(evidenceOwner, event)
+    }
     try {
       environment = await boundedLaunch(resolveFileBackedSettings(
         sourceEnvironment,
@@ -381,7 +437,9 @@ export async function main(arguments_, dependencies = {}) {
             : "file",
           runId: deliveryIdentity
         })
+        evidenceStore.ensureRunIndex(evidenceOwner, {provider: parsed.provider})
         const redactions = await boundedLaunch(collectEvidenceRedactions(environment), launchDeadline)
+        evidenceStore.setRunIndexRedactions(evidenceOwner, redactions)
         evidence = await evidenceStore.createArtifact(evidenceOwner, {
           contentType: "text/plain; charset=utf-8",
           redactions
@@ -404,6 +462,12 @@ export async function main(arguments_, dependencies = {}) {
       if (evidence !== undefined) {
         const promptEvidence = `prompt\n${prompt}\nprovider-stream\n`
         await boundedLaunch(evidence.append("prompt", promptEvidence), launchDeadline)
+        await recordEvidenceEvent({
+          kind: "prompt",
+          artifactId: evidence.metadata.id,
+          provider: parsed.provider,
+          metadata: {length: Buffer.byteLength(promptEvidence, "utf8")}
+        })
         evidencePayloadBytes += Buffer.byteLength(promptEvidence, "utf8")
       }
       const providerEnvironment = buildProviderEnvironment(environment, {
@@ -455,6 +519,7 @@ export async function main(arguments_, dependencies = {}) {
           else if (event.type === "tool") activity?.recordActivity(provider.name, "tool")
           else if (event.type === "lifecycle") activity?.recordActivity(provider.name, "lifecycle")
           acceptAdmissionEvent(admission, event)
+          await recordEvidenceEvent(workerEventToIndexEvent(event, parsed.provider))
           if (control !== undefined) {
             try {
               await control.accept(event)
@@ -480,13 +545,29 @@ export async function main(arguments_, dependencies = {}) {
           metrics.recordRawChildChunk("provider_stdout", chunk.length)
           metrics.recordRejected("provider_stream", chunk.length)
           if (evidence === undefined) return undefined
-          return evidence.append("provider-stdout", chunk).then(() => { evidencePayloadBytes += chunk.length })
+          return Promise.all([
+            evidence.append("provider-stdout", chunk),
+            recordEvidenceEvent({
+              kind: "provider_stdout",
+              artifactId: evidence.metadata.id,
+              provider: parsed.provider,
+              metadata: {length: chunk.length}
+            })
+          ]).then(() => { evidencePayloadBytes += chunk.length })
         },
         onStderrChunk: (chunk) => {
           metrics.recordRawChildChunk("provider_stderr", chunk.length)
           metrics.recordRejected("stderr", chunk.length)
           if (evidence === undefined) return undefined
-          return evidence.append("provider-stderr", chunk).then(() => { evidencePayloadBytes += chunk.length })
+          return Promise.all([
+            evidence.append("provider-stderr", chunk),
+            recordEvidenceEvent({
+              kind: "provider_stderr",
+              artifactId: evidence.metadata.id,
+              provider: parsed.provider,
+              metadata: {length: chunk.length}
+            })
+          ]).then(() => { evidencePayloadBytes += chunk.length })
         }
       }
       let exitCode
@@ -520,6 +601,12 @@ export async function main(arguments_, dependencies = {}) {
           const providerResult = admission.createProviderResult(terminal)
           const serializedProviderResult = `${JSON.stringify(providerResult)}\n`
           await resultEvidence.append("provider-result", serializedProviderResult)
+          await recordEvidenceEvent({
+            kind: "provider_result",
+            artifactId: resultEvidence.metadata.id,
+            provider: parsed.provider,
+            metadata: {terminal, length: Buffer.byteLength(serializedProviderResult, "utf8")}
+          })
           const resultArtifact = await resultEvidence.finalize()
           resultEvidenceBytes = resultArtifact.bytes
           resultEvidenceFinalized = true
@@ -550,7 +637,14 @@ export async function main(arguments_, dependencies = {}) {
             evidencePayloadBytes + resultEvidenceBytes,
             2
           )
-          await evidence.append("context-metrics", `${JSON.stringify(metrics.snapshot())}\n`)
+          const metricsSnapshot = `${JSON.stringify(metrics.snapshot())}\n`
+          await evidence.append("context-metrics", metricsSnapshot)
+          await recordEvidenceEvent({
+            kind: "context_metrics",
+            artifactId: evidence.metadata.id,
+            provider: parsed.provider,
+            metadata: {length: Buffer.byteLength(metricsSnapshot, "utf8")}
+          })
           const artifact = await evidence.finalize()
           assertArtifactProjection(artifact.bytes + resultEvidenceBytes, projectedArtifactBytes)
         } catch (error) {
@@ -563,6 +657,13 @@ export async function main(arguments_, dependencies = {}) {
       } else if (resultEvidenceFinalized) {
         metrics.recordArtifact(resultEvidenceBytes, 1)
       }
+      if (evidenceStore !== undefined && evidenceOwner !== undefined && evidenceError === undefined) {
+        try {
+          await evidenceStore.finalizeRunIndex(evidenceOwner, terminal)
+        } catch (error) {
+          evidenceError ??= error
+        }
+      }
       admission.complete({state: terminalExitCode === 0 ? "completed" : "failed", exitCode: terminalExitCode})
       if (
         destination.type === "telegram" && resultEvidenceFinalized