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

61 lines
4.3 KiB
Markdown

# 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](https://code.claude.com/docs/en/agent-sdk/typescript)
(`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.