Interlinked Observability

interlinked-observability — inspect what agents did

For Claude compiler batching, distinguish tool calls, scheduled checks, compiler executions and delivered diagnostics. hook-observation.v1 rows record scheduled TypeScript work; batch results and timing are in check-results.jsonl. Pending work survives in .interlinked/compiler-batches/. Coverage observations are retained even when repeated model warnings are suppressed. Silence does not mean coverage is complete. Measure a repeated-edit problem by assistant-message/tool-use identity and timestamps: an edit emitted before an earlier hook's feedback cannot be attributed to that feedback.

check-executions.jsonl also carries hook-observation.v1: scheduled external overlays, normal complexity/token measurements, and shadow trajectory observations. These are telemetry, not check passes or confirmed model delivery. check-results.jsonl retains full findings, including novelty, findingCount and server-computed writeAttribution where available. Newly observed means report novelty, not proven causation. Repeated advisories may be hidden from model feedback while remaining in each call's records; hidden findings prevent all-clean.

Use evals/compare-builds.mjs for paired explicit-build agent pilots. It retains fixtures, native streams, usage categories, settings, daemon status, final diffs and evaluator-owned functional checks. Activity warning counts are ledger metrics. Missing native delivery/token data remains unknown; do not infer billed savings from shorter commands or compressed rows.

repeated_implementation check results retain each current AST-matched group with a group=<sha256> detail identity, even when unchanged agent-facing warnings are suppressed. Compare these identities rather than line numbers across formatting edits. Post-tool suppression is session-local and resets with the daemon; Stop uses its existing digest state. NOT CHECKED means missing analysis, not zero clones. Findings are review candidates, not proven defects or evidence that an extraction helped.

hook-reentry.jsonl records Stop/SubagentStop re-entry suppressed before daemon evaluation. Translation receipts now include advisory context representation as well as denials and rewrites. Operator-only Stop diagnostics are not model-context delivery. Audit native completion messages by unique ID; streaming chunks and daemon Stop counts are insufficient to count continuations. The SlopCodeBench exporter retains these receipts and registrations.

Shared hook-check receipts may include scopes with a batch ID, check name, configuration hash and captured request-file identities. kind: request-inputs is historical execution evidence, not a complete runtime/dependency closure or reusable cache key. Nonempty unavailable preserves partial evidence and leaves the obligation pending. Keep those states separate from clean results when comparing recovered check counts or latency.

source-scan-scope.v1 capture rows record dependency/runtime exclusions from authored-source quality, with excluded_not_checked status. source-scan-security.v1 retains the separate security findings and request-input evidence. Neither row authenticates a writer or certifies runtime-input closure. Repeated unavailable-check messages are deduplicated for delivery by session, project, configuration and reason; raw check results retain missingness. Counts in the agent channel therefore differ intentionally from raw deferral counts.

Cowork plugin receipts use a separate metadata-only schema and explicit exports. Use interlinked-cowork and interlinked cowork report <receipts> --effects <listing> for native conformance. An intended hook decision is not execution/prevention proof; these receipts do not provide complete transcripts or authenticated writer attribution.

Search and organize all local evidence

When history can help diagnose a failure or explain prior work, use the logs as evidence:

1. Establish scope: project, session/call or file, and time window. Read data status --json and data health --json before interpreting missing results.
2. Choose the storage cost deliberately. data scan reads JSONL/gzip directly without an index or corpus copy. If an existing index is appropriate, explicitly run data index for stale sources; its import budget does not limit total disk growth. Report coverage.
3. Search with exact filters and a small --limit; correlate relevant records with data investigate, then retrieve supporting IDs with data show ID --json.
4. Report what was observed, the evidence IDs and hash-verification result, and capture or search limits. Recheck the current code before claiming an old failure is fixed.

Read evidence investigation workflows for task-specific recipes, source selection, pagination, and a concrete handoff checklist. Prefer bounded JSON results over dumping whole logs into context. Evidence payloads may contain user/code content; retrieve only relevant records and keep local evidence local unless sharing is authorized.

Read storage experiments to compare direct scans, native Claude snapshots, legacy/compact/bounded SQLite, compressed segments, and the experimental Cloudflare path. data lab always uses explicit corpus/output directories. Its portable literal queries, FTS token queries, and raw rg searches have distinct semantics.

interlinked data scan "compiler import" --source check-results --max-mb 32 --limit 10 --full-text --raw --json

Direct scans default to 32 MiB expanded input and 25,000 physical lines, taking complete-line prefixes of the most recently modified files. They include retained gzip archives and numeric rotations. A narrow time filter does not jump to a newer portion of a large file. Inspect coverage.complete and scope; increase explicit budgets or choose an existing index when necessary. --raw returns the observed source text with its hash. Scan/lab IDs are separate from production data show IDs. File filters for data scan use project-relative paths. Use --full-text when omission by the bounded index projection matters: it searches all decoded string values inside each readable complete record, excluding JSON field names. Byte/line budgets and oversized-record limits still apply. Without this flag, a complete scan with coverage.truncated > 0 does not establish that a term is absent from original payloads.

Use interlinked data catalog to discover registered and unknown JSONL files recursively, including numeric rotations and gzip archives. data health distinguishes observed writes, unsupported/disabled/idle producers, failures, and unmeasured populated files. Its receipt window is bounded; a quiet event-driven feed is not automatically broken. doctor reports capture failures and unmeasured coverage.

interlinked data index --max-mb 256 --max-records 250000 --json
interlinked data status --json
interlinked data search "compiler import" --since 7d --json
interlinked data search --source check-results --session SESSION --json
interlinked data show RECORD_ID
interlinked data investigate --session SESSION --json
interlinked data investigate --file src/app.ts --json
interlinked data checks --check typescript --json
interlinked data usage --session SESSION --json
interlinked data suggestions --json
interlinked data recurrence-inventory --json

Indexing is incremental and bounded: repeat until the retained backlog is covered. --rebuild clears only derived tables. SQLite/FTS5 loads lazily; use a Node runtime with built-in SQLite (Node 22.13+ avoids needing the earlier experimental flag). Search includes retained archives; --no-archives restricts it to live files. --fts opts into FTS5 query grammar. Structured filters include source/category/session/actor/provider/model/file/check/call/kind/decision/origin. Catalog source names and categories stay consistent between direct scans and indexed search, including sources stored under nested paths such as logs/latency.jsonl. Unknown event timestamps are excluded by time bounds. The older query command scans a bounded physical tail of one file and reports its scope; it does not promise archive coverage.

Each indexed answer carries a record ID; data show retrieves the original JSON and verifies its SHA-256. Projection text/field traversal is bounded, and oversized or malformed rows are reported without deleting their raw bytes. Check data status for freshness and parse failures. Invalid UTF-8 is malformed evidence: scans and new imports report it and continue to later complete records; data show refuses to verify it. A valid replacement character (�) in UTF-8 is ordinary text. For indexes created before strict UTF-8 validation, use an explicit data index --rebuild to remove earlier lossy projections; historical raw bytes remain intact. Exact duplicate raw records within one logical source share an indexed record but retain all physical locations. Cross-stream observations are not automatically independent executions.

data sessions/files/checks/usage/schema/suggestions expose evidence aggregates. investigate correlates exact provider/session/actor/call identities and labels missing phases; a file filter also strictly folds the obligations ledger. A block count is not a prevented-defect estimate. Suggestion shown means selected for presentation, not acknowledged; later absence is an observation, not proof of a fix. Usage has unknown values and no invented prices; never add overlapping timeline and costs totals. Recurrence inventory is separate from incident counts. Usage deduplication chooses a provider-message representative within the query's retained scope, so superseded source generations and excluded archives do not hide a retained copy. Aggregate limits bound returned groups, not necessarily database work; narrow supported filters first. schema is a source-wide observed field census: only --source and --limit affect its scope, even though its CLI accepts the shared filter flags.

data maintain previews retention. data maintain --execute --compact --no-index losslessly rotates eligible collection/timeline history without opening or creating SQLite. Add --index to explicitly import a bounded batch and translate existing evidence pointers during rotation. Without either index flag, indexing follows auto_index. It never deletes evidence or automatically compacts activity/state ledgers/corpora. Activity still requires the existing cursor-aware compact workflow. After an external compactor, rerun data index to discover replacement files and archives.

Preserve evidence indefinitely: do not delete, expire, truncate, sample away, or rewrite raw records, archives, manifests, or integrity checkpoints to reclaim space or hide bad rows. Lossless rotation changes physical placement while retaining every record. A smaller live file is not less retained history. Search archives with data search; older live-file readers cannot answer questions about the complete retained history. --rebuild replaces derived index tables only and is not a routine retention operation. Index storage can exceed raw-log storage substantially; the per-pass import budget is not a cap on total index size.

Rotation prepares the bulk retained suffix before acquiring the append lock. Identity is rechecked under the lock, and only a bounded catch-up plus the atomic rename exclude writers. An excessive append burst or competing replacement aborts safely for retry. Maintenance operation failures are recorded in capture health.

data configure --auto-index on opts into bounded SessionEnd background indexing; --auto-compact on independently enables collection/timeline rotation. Both default off; enabling rotation alone does not enable or run the SQLite importer. Defaults are 256 MiB/250,000 records per pass, a 256 MiB rotation threshold, and a 64 MiB live tail. Configure via --index-mb, --index-records, --compact-at-mb, --keep-live-mb. Settings live in data.config.json under the resolved data directory; capture itself continues independently. Load new daemon capture code through the normal build/reload workflow. SessionEnd is an actual provider lifecycle event, not each assistant Stop. This automation does not continuously watch files or refresh a long-running active session on a timer. Run an explicit index pass when recent evidence matters; a deferred background job is not freshness.

data audit diagnose locates the first historical failure by physical source/offset and does not infer tampering intent. Its source line and byte offset refer to the physical record even when archived blank lines are omitted from the verifier's combined line count. After investigation, data audit checkpoint --reason TEXT records an explicit payload-verified live observation boundary. data audit verify --checkpoint ID checks subsequent retained evidence, including after rotation. The historical verdict stays unchanged; checkpoints never rewrite or reset the old chain.

The bundled workflow reference is available in installed skills. In the Interlinked CLI source repository, docs/data-observability.md and docs/generated/data-catalog.md provide the operator contract and generated source catalog; in another project, use data catalog --json to inspect its sources.

Interlinked captures normalized tool-call events that configured Claude Code, Codex, Copilot CLI, Gemini CLI, Cursor, OpenCode, and Pi integrations deliver — locally via hooks, offline-first, into append-only JSONL under .interlinked/. The running daemon persists those delivered events. Detached lifecycle events and asynchronous PostTool findings can arrive after the originating provider action, and a cold fallback is not a complete capture path, so the log is evidence of events already delivered and persisted—not a synchronous transcript of every agent action. You can answer what did I (or a parallel agent) just do? what ran, on what files, with what tokens? what did the guard block? what mistakes keep recurring? — all without a server (the server is optional enrichment).

Load this when

• "What did I / another agent do this session?" — or you want to tail activity live.
• Reviewing what the guard blocked or warned.
• Finding recurring mistakes to harden against.
• Reporting recorded local changes without turning correlation into a savings or causal claim.
• Inspecting a specific session, event, or the repo dependency graph.
• Backfilling external (Codex) sessions, verifying the audit log, or syncing to the server.

Command surface

Output-mode flags are per-command (not uniform); all support --json. --since grammar is strict: \d+(s|m|h|d) (e.g. 30m, 2d) — 15 or 1.5h throw.

Dashboard / feed

activity isolates local and server read failures: available server events still render if the local read fails, and local events remain available if the server client fails. A local read failure with no available server events is reported as an error.

Event log & raw

collect retains only the bounded incoming Codex candidate batch (at most 250,000 records / 64 MiB; each rollout file is capped at 64 MiB) and streams the existing timeline to remove already-seen keys. A corrupt, oversized-row, or unreadable destination timeline is an error, not an empty history: the command exits nonzero without appending duplicates. Full timeline rebuilds are an in-memory sort and therefore explicitly refuse inputs or existing snapshots over 250,000 records / 64 MiB instead of exhausting application memory.

Audit & maintenance

interlinked metrics (whole-repo code-quality scan) lives in interlinked-quality-gates; interlinked context (effective config) in interlinked-setup.

For measured gate execution, interlinked metrics gates --json separates enabled policy from actual attempts, fresh source-bound reach, stale/deferred/unavailable work and recorded latency percentiles. .interlinked/metrics/executions.jsonl is the bounded local execution journal; malformed/truncated evidence is reported. Historical ratchet file counts are not current test coverage, and a disabled gate measures nothing. metrics evidence status lists behavioral receipt freshness; metrics coverage status validates the contribution index. metrics coverage warm explicitly runs the suite and belongs to interlinked-quality-gates, so do not trigger its CPU work merely to display status.

For hook-check evidence, harness coverage status --progress --json reads cached observation time, generation, pending count and job counters without rehashing files or serializing receipt history. readiness describes that observation, not a fresh coverage verdict. Plain harness coverage status --json reconciles selected files and returns full pending identities and receipts. Neither starts recovery; route explicit harness coverage verify and unresolved check prerequisites to interlinked-verify. Hook-check receipts with nonempty unavailable retain partial work; their pending version is not discharged. Do not count them as fully checked files or reusable passing evidence. For runtime scan profiling, Node's interlinked.coverage-runtime-scan diagnostics channel emits root, completed flag, bytes read, entries visited and duration even on failed captures. Subscribers must be in the scanning process. The optional evals/slopcodebench/scan-cost.mjs preload prints bounded measurements to stderr; it emits no contents or environment values.

interlinked impact — facts, not attribution

interlinked impact [--base <ref>] [--experiment-manifest <path>] [--cwd <path>] [--short|--full|--json] is local and read-only. It compares a verified commit (default HEAD) with the worktree and reports four evidence classes without promoting one into another:

Every class/source is labeled available, not-recorded, or unavailable. An invalid --base makes git and dependency evidence unavailable rather than silently choosing another comparison. An explicitly named but unreadable experiment manifest is a command error; malformed manifests or artifact hash/read failures leave causal evidence unavailable. Untracked paths are counted without LOC; .interlinked/ evidence files are excluded from that count.

Keep the source scopes separate. Activity edit totals are gross retained events and can overlap the git delta. A baseline fold records tightened/refused water-lines, not why they changed. Finding touched or acked states are workflow facts, not proof that a defect was fixed. Never sum these sources into “saved LOC/time/money,” call them a gain, or say Interlinked caused them.