Files
pipelines/docs/notes/background-task-metadata.md

4.3 KiB

Recorded background-task metadata

ChatShell now carries optional started_at/updated_at (epoch milliseconds), task_type, description, progress, last_tool, and nullable duration_ms, tool_count, token_count. A missing counter stays absent; an explicitly reported zero is preserved. Duration is backend-reported runtime, distinct from a client clock's elapsed time since a recorded start.

Sources and limits:

  • Claude's initiating Bash/Agent/Task tool_use transcript entry supplies its recorded timestamp and description. A matching live envelope timestamp is used when present. Known running tasks can recover this timing from the durable transcript by tool-use ID, including after detachable-host replay. The host's own creation time and server read/replay wall clock are never task start times.
  • Claude task_started correlates task ID and tool-use ID. task_progress and structured completion messages retain reported usage duration, tool/token counts, progress summary, description and last tool. Fields were verified in the official Agent SDK TypeScript reference (SDKTaskStartedMessage, SDKTaskProgressMessage, SDKTaskNotificationMessage). Those SDK events do not require timestamps; absent timestamps stay unknown.
  • Codex item lifecycle notifications expose startedAtMs/completedAtMs in the installed App Server schema. These supply recorded command timing. Historical commandExecution.durationMs supplies reported runtime; historical ThreadItems have no per-command start, so a readback without an observed start remains unknown. The unrelated thread/turn start is not substituted.
  • The currently supported OpenCode shell shape has no verified timing fields. Those remain absent. Its shared in-flight snapshot reconciliation preserves metadata rather than dropping it, and counts retained metadata bytes.

Partial frames and authoritative readback preserve known metadata for the same shell identity; another identity cannot borrow it. Terminal events retain the metadata while removing tasks from the running set. Repeated progress does not reset start times or regress reported counters. Descriptions/progress are capped at 2KiB, task types at 128 bytes and last-tool names at 256 bytes. Existing server replay and readback byte budgets now include these retained strings.

Claude's optional transcript enrichment uses a serialized scan, a 30-second missing-path lookup backoff, a 5-second scan throttle, and size/mtime/target-set fingerprints (including failed or oversized reads). It streams at most 64MiB with the existing transcript line limit and retains only requested tool-call metadata. Missing, malformed or oversized transcripts do not fail the primary task list. No new source file indexing or background reader is introduced.

Checks: focused Claude, Codex, protocol, OpenCode and server tests passed; tests cover live metadata, partial/stale frames, explicit zero/absent counters, silent host-style replay, durable transcript timestamps, missing/oversized-source retry, exit state, authoritative removal, source limits and retained byte budgets. No shared services were restarted, no real chats were changed and no TUI code changed.

Focused race tests also passed for Claude, Codex and protocol. Logs: /private/tmp/pipelines-background-metadata-checks.log and /private/tmp/pipelines-background-metadata-race.log. Final same-ID blank-command partial-frame assertion passed in protocol/server tests.

Backend deployment completed — 6 November 2026

Explicit operator instruction authorized immediate deployment. Installed clean staged commit c405cdfe2488ad0ef619790c529add3457d8d209 through the canonical manager with session detachment, preserving existing Claude host/CLI processes (PIDs 78036/78038 confirmed alive afterward). No executing pipeline runs were present. Live backend build identity verified; read-only Codex history returned 670 timestamped messages, OpenCode model metadata returned, and Claude shell metadata includes recorded start/type.

Deployment status: /Users/alan/.local/share/pipelines/logs/authorized-backend-cutover-20261106.json is complete. Binary/database rollback backup: /Users/alan/.local/share/pipelines/backups/maintenance-1793982619839486000. Earlier notes describing the backend as staged/pending are superseded by this verified delivery.