Skip to content

feat(taskq): serve one scrubbed timeline per task to the owner - #19942

Merged
javenciu merged 1 commit into
mainfrom
feat/task-timeline-route
Nov 9, 2026
Merged

javenciu merged 1 commit into
mainfrom
feat/task-timeline-route

Conversation

@javenciu

@javenciu javenciu commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An owner can read one chronological, redacted account of what happened to a task, without joining three records by hand.

A task's history is recorded in three places that share only the task id:

  • the task_events rows of the durable queue, which GET /api/tasks/{task_id} serves as the last 200 rows;
  • for a subagent row, the subagent/* entries of the crew log of the session that dispatched it;
  • for a workflow-agent row, the events of the workflow run it belongs to.

They use three time spellings (epoch seconds, epoch milliseconds, ISO 8601) and three read paths, so answering "what happened to this task" means opening all three and ordering the lines by hand.

Why it matters

A task that ends failed, cancelled or unknown_side_effect is diagnosed from its sequence of events: when it was accepted and claimed, what the dispatching session recorded for it, what the workflow run logged around it. Today that sequence exists only as three unrelated records.

Not a goal

  • No panel, link or button. The route returns markdown to an API caller; a Tasks-panel entry is a separate change.
  • No new storage, no write into any of the three streams, and no mirroring of queue transitions into the crew log (no new crew-log entry type). The queue owns its transitions; a mirror would make the crew log a second writer of them.
  • No per-call attribution of workflow events. The stream shows the run's events (see below).
  • No change to GET /api/tasks/{task_id} or any other existing task route.
  • Nothing agent-facing: no MCP tool and no internal-path entry.

What changed (motivation → approach → change)

Approach. A read-only view over the read surfaces that already exist, merged by time. The alternatives were a stored per-task timeline (a fourth copy to keep consistent with three owners) and mirroring queue transitions into the crew log (a second writer of facts the queue owns, and a reconcile question for a transition that lands in one store and not the other). Neither is needed to answer the read.

Route. GET /api/tasks/{task_id}/timeline in src/kiro_crew/dashboard/handlers/tasks.py (api_task_timeline, _timeline_sync), registered in routes/system.py and exposed through a lazy wrapper in handlers/__init__.py (the package must not import tasks.py at boot). It passes the dashboard's token middleware and then require_owner_dashboard_request(request, "task_timeline") first, so an app token, a non-owner user or a request with no claims is refused (owner_only, or 401 for a stale pre-owner subject) before the row is read. The gate is stricter than the detail route's because the view reaches the spawning session's log and a workflow run. Responses: 200 {task_id, markdown, entries}; 404 not_found for an unknown id; 404 unavailable when the gateway has no task store; 503 unavailable when the store read fails. Every read runs in asyncio.to_thread.

Renderer. The new src/kiro_crew/taskq/timeline.py: render_timeline, read_child_entries, events_from_registry, and the types Sources, Timeline, StreamReport and CrewRead, with the named bounds CREW_SCAN_MAX (5000 entries read), CREW_ENTRIES_MAX and WORKFLOW_EVENTS_MAX (200 kept each, newest) and VALUE_MAX_CHARS (300 per rendered value). It is a leaf under taskq: it imports taskq.model and taskq.adapters.runner and reaches the crew log only through child_record and read_page.

Stream Applies to Read through
task_events every row TaskStore.events, with the detail route's own _EVENTS_TAIL (200) passed in
crew_log subagent rows crew_log_slots_for names every slot the parent's log may be filed under; child_record searches each slot's units for the child in the subagents fold state and returns its seq_spawned; then one read_page from that seq, filtered to subagent/* entries with data.agent_id == task_id. The fold row alone cannot serve it: it keeps one summary per child and does not read subagent/steered
workflow workflow_agent rows the run registry's handle for the run in the row id, its events read in place

Every bound is applied before anything is copied or rendered. The queue tail is bounded by the store read (events(limit + 1), one probe row past the bound). The crew-log and workflow streams each make one pass over their entries parsing only the time, into a deque(maxlen=<bound>) (_newest): an entry that falls off the front and an entry whose time does not read are counted and never kept, and only the kept entries have their data scrubbed and rendered. events_from_registry hands the run's event objects over as they are, so a run with 1,000 events costs the view 200 data reads and no conversion.

Items sort by (time, stream order, the stream's own sequence), so a tie is deterministic. An entry whose time cannot be read is not placed; it is counted in its stream's dropped.

The workflow stream is the run's events, not one call's. The call number in a workflow:<run>:agent<N> row id is a 1-based counter in the agent pool, and an event's call_index is a 0-based counter in the runner. They count different things, so no event can be attributed to one row. Every event of the run is shown with its type and data, so an agent_* event shows the agent_id it is required to carry and a run-level event (log, phase_started, budget_update, approval_requested, run_*) shows none; a sibling call's events appear beside this call's.

A stream that cannot be read is reported, not dropped. Each stream carries a status (ok, absent, truncated, unavailable) and a closed reason (no_record, not_retained, not_applicable, tail_limit, scan_limit, kept_limit, read_failed, no_source), in a ## Streams list at the end of the markdown. A failing stream does not fail the others, and an unreadable stream never renders as an empty one. The store read of the row itself is the one error that propagates.

Scrubbing. Every string goes through the scrubber the handlers already use for task payloads (_scrub_value in tasks.py). render_timeline takes it as a required argument with no default, so there is no path that renders unscrubbed text, and the module defines and imports no scrubber of its own. Before anything is encoded, every leaf and every mapping key of an event's data, at any depth, is scrubbed as the text it holds (bytes decoded as UTF-8, any other object through str), because str, repr and JSON each escape a newline and a multi-line credential then does not match. It runs before anything is flattened or cut, so a credential is matched whole and a value cut at VALUE_MAX_CHARS cannot leave a prefix no pattern recognises, and again on every rendered line, which covers a damaged store's kind or type.

Two lookups outside the timeline module. child_record in crew_log/resolve.py is a read-only sibling of unit_holding_child. It resolves the slot's units the same way (crew_log_units(..., strict=True), so the permanent-delete exclusion applies, newest first, UnitSearchFailed when the store cannot be read), but it searches the subagents fold state rather than its render. The state keeps a child whose card was dismissed, while the render leaves it out because the panel draws only the cards the user kept. unit_holding_child is unchanged: the dismissal writer must not find a row it already cleared. crew_log_slots_for in dashboard/chat_utils_slots.py lists every slot name a crew-log writer may have recorded for a session key, with no dependence on an open tab: the live tab first, then the channel transcript stem (slack_<ts>, which messaging/dispatch_crew_log.py records), or for a cron key its per-run tab, its transcript stem and the job's own cron-<job> tab. A dispatch past the fold's retain cap has no row to place, and is reported as not_retained.

Docs. A "Task timeline" section in docs/system-specs/modules/taskq.md, the route in the feature map's Endpoints column, and one bullet in the task-routes list of docs/system-specs/modules/learn-cron-dashboard.md.

Backwards compatibility

Compatible: one GET route is added. The five existing task routes answer byte for byte as on main for one fixed store (pinned below), the route table gains exactly this one entry, and no function body in tasks.py changes (three docstring hunks and the added handlers).

Removes nothing: no route, key, field or kind is removed, renamed or hidden.

Tests

Rebased onto main at 0c0dd82 (2026-11-09). The three conflicts were text-only: the handlers/tasks.py module docstring, one bullet in taskq.md and one row in the feature map. The new module, the handler, the route and the tests are byte for byte as before. The only addition is a # flake-ok: a fake log clock, no wait tag on the ticks fixture's now_ms patch, because the K19 ratchet reads the _ms suffix as a wait. On this head, test_taskq_timeline.py with the task-route, taskq, facade-guard and spawn-audit neighbours (13 files) passes 615 tests, three runs in a row (-n0, -n 4, -n 4). The merge onto main at 3987f3a is clean.

Dismissed and unretained children (review round on 5bed177). The crew-log stream now finds a child through child_record in crew_log/resolve.py, which searches each slot unit's subagents fold state, not its render. The state keeps a row whose card was dismissed. unit_holding_child is unchanged, because the dismissal writer must not find a row it already cleared. A dispatch past the fold's retain cap is reported as absent (not_retained) rather than no_record. New tests: test_a_dismissed_childs_entries_are_still_served_in_order, test_a_dispatch_the_fold_did_not_retain_is_reported_as_not_retained and test_a_child_in_a_permanently_deleted_conversation_is_still_not_found; the first two fail on 5bed177. On head fd57d33, the timeline tests with the task-route, taskq, crew-log resolver, facade-guard and spawn-audit neighbours (21 files) pass 992 tests, three runs in a row (-n0, -n 4, -n 4). The merge onto main at d0e911b is clean.

Parents with no open tab (review round on fd57d33). The crew-log slot no longer depends on an open dashboard tab. crew_log_slots_for in dashboard/chat_utils_slots.py lists every name a crew-log writer may have recorded for the parent: the live tab first, then the channel transcript stem (slack_<ts>, which the channel dispatcher records), or for a cron parent its per-run tab, its transcript stem and the job's own cron-<job> tab. The reader tries each name in order. Twelve new tests fail on fd57d33, including end-to-end reads through the real handler for a Slack parent, a cron parent and a per-run cron parent. On head c6b02da, the timeline tests with every file that touches the task route, the taskq timeline, the crew-log resolver or the slot helpers (42 files) pass 1744 tests, three runs in a row (-n0, -n 4, -n 4). The merge onto main at 6259ac7 is clean.

The facade's type-checker list (CI on c6b02da). test/test_chat_utils_facade.py failed on CI. crew_log_slots_for reads transcript_stem, which chat_utils_slots.py imports from kiro_crew.history_files at module level, so the chat_utils facade serves that name too, and the facade's TYPE_CHECKING block must name every served name from its home module. The block names it there, beside the kiro_crew.history names it already lists. No other line changes. test_every_name_served_from_outside_the_family_is_visible_to_type_checkers fails on c6b02da and passes here. The run's other red, test_the_lazy_imports_stay_inside_the_functions_that_need_them, came from main and was re-pinned there by #34010. On head 0757b9b, merged locally onto main at fd5d9ef, the timeline, facade, crew-log, task-route and server-composition tests (94 files) pass 3665 tests, and mypy src/kiro_crew/ reports no issues.

In short: 137 cases in the new test/test_taskq_timeline.py fail at import on main and pass here, including a credential planted in each stream and a route test that refuses a non-owner before the row is read. Size: 760 added source lines (589 of them the new module, whose only caller is this route) and 1,708 test lines; the module stays whole because splitting it would leave it without a caller.

Red on main (detached origin/main, the test file copied in, imported from that checkout's own src, 3 runs):

ImportError: cannot import name 'timeline' from 'kiro_crew.taskq'

Green on this branch: 137 passed at -n0, three passes; 212 passed at -n 4 --dist loadgroup beside test_api_tasks.py, test_dashboard_handlers_lazy_tasks.py, test_taskq_startup.py and test_chat_utils_facade.py.

What each group locks in:

  • Merge order: test_the_merge_orders_by_time_then_stream_then_the_streams_own_order, and test_a_concatenation_of_the_streams_is_not_a_timeline fails a view that appends the streams instead of merging them.
  • Reporting: a failing crew-log or workflow reader, no workflow service, a full queue tail, a scan past CREW_SCAN_MAX, entries past a kept bound and entries without a readable time are each reported on the result and in the markdown, while the other streams still render.
  • Bounds: test_a_long_run_is_bounded_before_any_event_is_converted_or_rendered gives the registry adapter a run of 1,000 event objects that count their to_json calls and data reads: zero conversions, at most WORKFLOW_EVENTS_MAX reads, truncated (kept_limit) with 200 kept, and two events without a readable time, one outside and one inside the kept window, both counted as dropped; test_a_stream_renders_only_the_entries_it_keeps hands the crew-log and workflow streams 1,000 entries each and counts the data mappings the scrubber is given (exactly the bound); test_the_registry_adapter_hands_the_runs_events_over_in_place pins that the adapter copies nothing.
  • Scrubbing: test_a_credential_in_any_stream_never_reaches_the_output plants a credential in each of the three streams as a value, a nested value, a key block and a nested key block; test_a_bytes_pem_is_redacted_before_any_encoding_escapes_it plants an unterminated bytes PEM as a value, inside a mapping, inside a list, as a nested key and as a top-level key on each stream; test_a_credential_cut_by_the_line_bound_is_redacted_before_the_cut, test_a_credential_in_a_label_is_redacted and test_a_credential_in_the_rows_own_fields_is_redacted cover the cut, the labels and the row fields; test_the_renderer_has_no_default_scrubber pins that scrub is a required argument; test_the_renderer_uses_the_scrubber_it_is_given; test_the_route_scrubs_what_the_store_holds runs it through the real handler and a real store.
  • The real crew log: test_the_reader_returns_only_the_childs_subagent_entries_in_order, a child dispatched before a reset found in the older unit, an absent child reported absent, a failing unit search reported unavailable, test_the_scan_window_starts_at_the_childs_dispatch_not_at_the_top_of_the_log, and test_a_real_log_and_a_real_row_merge_end_to_end.
  • The route: test_a_non_owner_is_refused_before_the_row_is_read (an app token, a non-owner user, no claims; the store read is counted and stays at zero), test_the_configured_owner_passes_the_gate, 404 and 503 each with a code, test_reading_a_timeline_changes_nothing, and test_the_lazy_wrapper_calls_the_real_handler.
  • Existing routes unchanged: test_every_existing_task_route_answers_byte_for_byte_as_before compares eight captured responses of the existing routes with the live handlers, and test_the_task_routes_are_the_old_set_plus_one_get pins the route table.
  • Structure: test_the_timeline_is_a_read_only_leaf_with_no_scrubber_of_its_own, test_the_timeline_makes_no_mutating_call_and_never_opens_a_file, test_the_crew_log_is_reached_only_through_its_read_surface and test_timeline_py_is_the_only_reader_added_and_the_route_the_only_caller.

Neighbours run in one process at -n0: the route-table, error-code, call-site-auth, composition and client-contract suites, test_api_tasks.py, test_overload_integration_glue.py, test_taskq_startup.py and the taskq store, reconcile, admission and runner-adapter suites (593 passed). The wait-discipline, flake-pattern, pid-reader, kill-chokepoint, spawn-audit, tmpdir-helper and dir-fd ratchets pass at -n0 (175 passed). The new file followed by test_taskrunner_atomic_persistence.py, test_taskrunner_execution_capture_async.py, test_unattended_slot_guardrails.py and test_wheel_apply.py in one process passes (234 passed), because the new tests patch module attributes. mypy src/kiro_crew/, black, isort and flake8 on the touched files, scripts/check_agent_sdk_boundary.py, the comment-history, brand and feature-map gates and scripts/docs-lint.sh pass.

Manual verification

N/A — no UI. The route is exercised through the real handler, a real TaskStore and a real crew log in test_taskq_timeline.py. Not measured: a read of a long-lived session's log on a gateway with a large real history. The crew-log side reads one window from the child's dispatch to the end of its unit, off the loop, with memory bounded by CREW_SCAN_MAX rows.

Screenshots / video

N/A — the change adds an API route and no user-visible surface; no file under website/ changes.

Related Issues

None describes this gap. #13628 asks for a tool-call and cost view on the Subagents card, a different surface that this change does not provide.

Pattern harvest

Not generalizable: this adds a feature, so there is no fixed defect whose class a rule could stop.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

@javenciu
javenciu requested review from a team and KiroCrewCaptain as code owners October 13, 2026 20:57
@javenciu
javenciu requested a review from mbriones98 October 13, 2026 20:57
@javenciu

Copy link
Copy Markdown
Contributor Author

Closing and reopening right after opening so CI runs on hosted runners: same-repo runs from this account queue on the fleet label without a runner (details on #19683).

@javenciu javenciu closed this Oct 13, 2026
@javenciu javenciu reopened this Oct 13, 2026
@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 0757b9b87899ce6df395a0bb16560378b475c761 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 0757b9b87899ce6df395a0bb16560378b475c761 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the route only adds a read-only view, gated to the owner, over three stores that already exist. It takes nothing away and changes no route that already exists.

Notes

  • read_child_entries reads one read_page window of CREW_SCAN_MAX entries starting at seq_spawned. On a long parent session, a child's late subagent/* entries (steered, completed) can fall past the window and come back as truncated/scan_limit. That leaves the end of the task, which is what a failure diagnosis needs most, as the part most likely to be missing.
  • The workflow stream shows every event of the run, including sibling calls, so on a large fan-out run the 200-event cap may push out this call's own agent_* events. If the pool exposes the agent_id it assigns to each call, filtering agent_* events by that id would keep this call's events.

[DESIGN-REVIEWED] 0757b9b

Description read

[DESCRIPTION-READ] f48ba72df26ea31bdb6783338544cac14212dff383c36b2a2324f4b58af93155

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 0757b9b87899ce6df395a0bb16560378b475c761 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

The new owner-only GET route has no caller anywhere in the repo, but it is read-only and could be deleted next week without locking anyone out.

Notes

  • Item 1 — zero consumers: grepping tasks/.*timeline turns up only the spec and feature-map lines. No website code, CLI or MCP tool calls it ("No panel, link or button… a Tasks-panel entry is a separate change"). Subtraction: wait to ship GET /api/tasks/{task_id}/timeline and its routes/system.py row until the PR for the panel that reads it.

What this change ships

Inventory (5 items) — 4 justified

Intent: an owner reads one time-ordered, redacted history of a task instead of joining three records by hand. This is an ADDITION.

  1. An owner can GET /api/tasks/{id}/timeline and get merged markdown back — zero consumers: no caller in the repo yet
  2. The response ends with a status for each stream (ok/absent/truncated/unavailable) — justified
  3. Credentials are scrubbed in every stream through the existing _scrub_value — justified
  4. child_record finds a child whose card the user dismissed, by searching the fold state rather than its render — justified
  5. crew_log_slots_for lists every slot name a session's log may be filed under, even after its tab has closed — justified

[FIRST-PRINCIPLES-REVIEWED] 0757b9b

Description read

[DESCRIPTION-READ] bf515c87395b728e6e067557ea0db594995c5d5bd85b60e113c327bd91861b13

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 0757b9b87899ce6df395a0bb16560378b475c761 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 0757b9b

Verdict parsed from the review's SHA-scoped output markers for commit 0757b9b87899ce6df395a0bb16560378b475c761.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 0757b9b87899ce6df395a0bb16560378b475c761 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 0757b9b87899ce6df395a0bb16560378b475c761 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 0757b9b

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 0757b9b87899ce6df395a0bb16560378b475c761 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Oct 13, 2026
@javenciu

Copy link
Copy Markdown
Contributor Author

Thanks for the reviews. One fix commit answers them, and each point is below.

  1. GPT, nested keys leak credential prefixes across the cut (src/kiro_crew/taskq/timeline.py). Fixed. _one_line (timeline.py:206) now takes the scrubber and runs it over the whole text before it flattens and cuts. _value (timeline.py:219) and _describe (timeline.py:235) take the scrubber too, so a serialized mapping (keys included), a leaf rendered through str by default=str, and the repr fallback are all scrubbed after serialization and before the cut. _text (timeline.py:295) passes its scrubber to the same cut, so no value or label is cut unscrubbed, whatever its call site. Test: test_text_the_serializer_adds_is_scrubbed_before_the_cut (nested key, str-rendered leaf and repr fallback, in each of the three streams). Each case pads the key or leaf with 285 characters and a space, then plants an access-key id, and asserts that no prefix of the id of length 4 or more reaches the markdown. Red on the reviewed head: 9 failed in 3 of 3 runs (assert ['AKIA', ..., 'AKIAIOSFO'] == []). Green: 3 of 3 runs. test_a_benign_nested_mapping_still_renders_whole checks that a plain nested mapping still renders as compact JSON in each stream. Two deliberate breaks, one removing the scrub in _one_line and one bypassing it for serialized values only, each fail exactly these 9 cases. The Scrubbing paragraph of docs/system-specs/modules/taskq.md names the pass.

  2. GPT, autouse isolation fixtures use the shared undo stack (test/test_taskq_timeline.py). Fixed. _isolated_home (test_taskq_timeline.py:62) and _fresh_monitor (test_taskq_timeline.py:68) request and patch through _floor_monkeypatch, so a test that calls monkeypatch.undo() cannot lift the data-home pin or the private health monitor. No autouse fixture in the file takes monkeypatch.

  3. Opus, an out-of-range timestamp fails the whole view. Fixed. _seconds (timeline.py:261) turns a stored time into epoch seconds only when the value is finite and _stamp can spell it, and each of the three streams counts any other time in its dropped, the same way it counts an unreadable one. The task_events stream now reports dropped as well. _order (timeline.py:279) falls back to 0 for an order that does not read as an integer. Test: test_a_time_no_clock_can_spell_is_counted_not_placed (inf, nan and 1e20 seconds in task_events, 10**20 ms, 10**400 and inf in the crew log, and ISO stamps outside years 1 to 9999 in the workflow stream), plus test_an_unreadable_order_leaves_the_entry_placed_by_its_time. Red on the reviewed head: 9 failed in 3 of 3 runs. Green: 3 of 3 runs.

  4. First Principles, item 1 (the route has no consumer in this PR) and item 3 (the injection seam and the exports). These are answered in their own disposition comments.

Gates on the new head: the timeline file, test_taskq_store.py and test_taskq_store_invariant_pins.py at -n0 pass. The timeline file run in one process ahead of test_taskrunner_atomic_persistence.py, test_taskrunner_execution_capture_async.py, test_unattended_slot_guardrails.py and test_wheel_apply.py passes. The new cases pass 20 of 20 runs at -n0 and 10 of 10 at -n 4, with the order shuffled on each run. test_flake_pattern_ratchet.py passes. black, isort, flake8 and mypy on the touched files pass, as do scripts/check_agent_sdk_boundary.py, scripts/check_sync_io_in_async.py, scripts/check_loop_bound_locks.py, the comment-history and feature-map gates and scripts/docs-lint.sh.

  1. Opus FINDING 2 (timeline.py:457): a history exactly events_limit long read truncated. The reader now asks for one row past the bound and reports truncation only when it exists (test_a_history_exactly_as_long_as_the_bound_is_not_called_truncated; red at exactly the bound before, green now, the fix reverted fails exactly that test). Folded into the same fix commit.

@javenciu

Copy link
Copy Markdown
Contributor Author

span=fff1c91d1aa9

fixed e180349: _one_line (src/kiro_crew/taskq/timeline.py:206) takes the scrubber and scrubs the whole text before it cuts; _value (:219) and _describe (:235) pass it, so serialized keys, default=str leaves and the repr fallback are scrubbed after serialization and before the cut.
test_text_the_serializer_adds_is_scrubbed_before_the_cut (nested key, str-rendered leaf, repr fallback, x 3 streams; no id prefix of length >= 4 in the output): red 9 failed on this head in 3/3 runs, green in 3/3; both mutants (no scrub in _one_line, no scrub for serialized values) fail exactly those 9.

@javenciu

Copy link
Copy Markdown
Contributor Author

span=12b7dfb4bf33

fixed e180349: _isolated_home (test/test_taskq_timeline.py:62) and _fresh_monitor (:68) request and patch through _floor_monkeypatch instead of the shared monkeypatch.
No autouse fixture in the file takes monkeypatch (grep over every autouse=True definition); the file passes at -n0, 3 of 3 runs.

@javenciu

javenciu commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor Author

span=38f34b109679

  • timeline.py:475, a stored time that parses but cannot be stamped failed the whole view. fixed e180349: _seconds (src/kiro_crew/taskq/timeline.py:261-276) reads every stored time through float(), rejects a non-finite value and anything _stamp cannot spell (OverflowError, OSError, ValueError), and returns None; the caller counts that entry as an unreadable time and the view renders. Pinned by test_a_time_no_clock_can_spell_is_counted_not_placed (test/test_taskq_timeline.py:468, parametrized over the three streams and 10**20, 10**400, inf, nan): red on 60964bf (the view raised), green on the fix.

@javenciu

Copy link
Copy Markdown
Contributor Author

span=2f09ffd7272f

rebutted: the route is the module's consumer and a complete read on its own. api_task_timeline (src/kiro_crew/dashboard/handlers/tasks.py:417) gates on the owner first, then answers 200 with the merged markdown and the per-stream reports, 404 not_found or unavailable, or 503 unavailable. An owner reads it with the same token as every other dashboard route.
The suggested subtraction leaves taskq/timeline.py with no caller at all, which is the shape item 3 objects to. The other way to clear it, a panel in this PR, adds a frontend surface to a backend change. The description lists the panel under Not a goal as a separate change, which is the split CONTRIBUTING.md:262-264 asks for.

@javenciu

Copy link
Copy Markdown
Contributor Author

span=5d7d3a98a4f3

rebutted: CrewRead is not test-only. It is the return type of the production reader read_child_entries (src/kiro_crew/taskq/timeline.py:325), and _crew_stream (:358) reads its found, rows and complete (:370, :374, :395). Those fields are what separate absent (no_record) from truncated (scan_limit) in the report.
Sources.crew_reader (:152) is a typed fault seam. The route never sets it (tasks.py:413), and the tests use it to inject a failing or bounded reader without patching a module global. The status and reason names in __all__ are the values of the route's streams[].status and streams[].reason, so a client and the spec (docs/system-specs/modules/taskq.md, Task timeline) share one spelling. Shrinking the list changes no behaviour.

@javenciu

Copy link
Copy Markdown
Contributor Author

Closing and reopening so CI runs on hosted runners: same-repo runs from this account queue on the fleet label without a runner (details on #19683).

@javenciu javenciu closed this Oct 13, 2026
@javenciu javenciu reopened this Oct 13, 2026
@javenciu
javenciu force-pushed the feat/task-timeline-route branch from e180349 to 74fc9cd Compare October 14, 2026 11:11
@javenciu

Copy link
Copy Markdown
Contributor Author

Closing and reopening so CI runs on hosted runners: same-repo runs from this account queue on the fleet label without a runner (details on #19683).

@javenciu javenciu closed this Oct 14, 2026
@javenciu javenciu reopened this Oct 14, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 15, 2026
@javenciu

Copy link
Copy Markdown
Contributor Author

span=38f34b109679

  • timeline.py:457, a history exactly events_limit long was reported truncated. fixed e180349: the reader asks the store for events_limit + 1 rows and reports truncated (tail_limit) only when that extra row exists, dropping it so the rendered tail keeps its bound (src/kiro_crew/taskq/timeline.py:503-513). Pinned by test_a_history_exactly_as_long_as_the_bound_is_not_called_truncated (test/test_taskq_timeline.py:354): four events with a bound of four read ok; a bound of three reads truncated again. Red on the previous head (truncated at exactly the bound), green on the fix; the fix reverted fails exactly this test.

@javenciu
javenciu force-pushed the feat/task-timeline-route branch from 74fc9cd to e35218d Compare October 16, 2026 01:42
@javenciu

Copy link
Copy Markdown
Contributor Author

span=fff1c91d1aa9

  • JSON escaping bypasses multiline mapping-key redaction. fixed: _value (src/kiro_crew/taskq/timeline.py:240) now builds a rendering-only copy whose mapping keys are scrubbed while their newlines are still real (_render_mapping_keys, :219), and both json.dumps and its repr fallback read that copy (:252-261), so an unterminated PEM block used as a key is redacted before either encoder escapes it; the whole serialized text is still scrubbed before the cut. test_an_unterminated_pem_mapping_key_is_redacted_before_json_encoding (test/test_taskq_timeline.py:571) fails on this head (3 of 3 streams leak the key body) and passes now, and test_a_mapping_json_cannot_sort_is_rendered_from_the_scrubbed_copy (:593) covers the fallback, which a mapping with mixed key types reaches.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 16, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 9, 2026
@javenciu

javenciu commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

span=fff1c91d1aa9

Fixed in fd57d33. The timeline no longer finds a child through the panel's rendered fold. A new read-only resolver, child_record in crew_log/resolve.py, resolves the slot's units the way unit_holding_child does: crew_log_units(slot_key, strict=True), so the permanent-delete exclusion still applies, searched newest first, raising UnitSearchFailed when the store cannot be read. It then searches each unit's subagents fold state (checkpoints["subagents"].state["by_id"]), which keeps a dismissed row. unit_holding_child is unchanged, because the dismissal writer must not find a row it already cleared.

A dispatch past the fold's retain cap has no row in the state either. The stream now reports that as absent (not_retained) instead of no_record, so the view no longer claims nothing was recorded.

Proof: test_a_dismissed_childs_entries_are_still_served_in_order (spawn, steer, complete, dismiss on a real crew log; the entries come back in order with status ok), test_a_dispatch_the_fold_did_not_retain_is_reported_as_not_retained, and test_a_child_in_a_permanently_deleted_conversation_is_still_not_found. The first two fail on 5bed177.

@javenciu
javenciu force-pushed the feat/task-timeline-route branch from 5bed177 to fd57d33 Compare November 9, 2026 16:44
@javenciu

javenciu commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

span=deec9253d54e

Fixed in fd57d33, with the first option the review names: each slot unit's fold state is searched, dismissed and omitted rows included. The new read-only child_record in crew_log/resolve.py resolves the units exactly as unit_holding_child does (crew_log_units(slot_key, strict=True), newest first, UnitSearchFailed on a read failure). It searches checkpoints["subagents"].state["by_id"] instead of the render, and returns the unit and seq_spawned for read_page. unit_holding_child is unchanged.

A child past the 512-row OPEN_RETAIN_LIMIT has no row in the state either. Placing it would need a raw scan of the log, so the stream reports absent (not_retained) instead of a false no_record.

Proof: test_a_dismissed_childs_entries_are_still_served_in_order (a real crew log: spawn, steer, complete, dismiss; the entries come back in order with status ok), test_a_dispatch_the_fold_did_not_retain_is_reported_as_not_retained, and test_a_child_in_a_permanently_deleted_conversation_is_still_not_found. The first two fail on 5bed177.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 9, 2026
@javenciu
javenciu force-pushed the feat/task-timeline-route branch from fd57d33 to c6b02da Compare November 9, 2026 18:15
@javenciu

javenciu commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

span=b9f3467ba93c

Fixed in c6b02da. The timeline no longer resolves the parent's crew-log slot through an open tab. A new crew_log_slots_for(session_key) in dashboard/chat_utils_slots.py lists every slot name a crew-log writer may have recorded, with no dependence on open surfaces: the live tab name first (subagent_event_slot), then transcript_stem(session_key) for a channel key (what messaging/dispatch_crew_log.py records), or for a cron: key the per-run tab (cron_tab_name), its transcript stem and the job's own tab cron-<job>. Sources.slot_of became slots_of, and read_child_entries tries each distinct name in order with child_record and reads the first that holds the child. The handler passes crew_log_slots_for.

Proof: the new tests fail on fd57d33 and pass here. They cover the name list for a Slack key, cron:job1 and cron:job1:run2 with no surface registered, the in-order search, omitted across slots, and an end-to-end read through the real _timeline_sync for a Slack parent filed under slack_<ts>, a cron parent under cron-job1, and a per-run cron parent under both its run tab and the job tab.

@javenciu

javenciu commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 4, child_record repeats unit_holding_child's search loop. kept: the repeat is about 20 lines, and in exchange this PR edits no existing function. unit_holding_child is the lookup both dismissal writers call: the dismiss route (src/kiro_crew/dashboard/messaging_api/run_control.py:825) and the panel pop (src/kiro_crew/subagent_parts/terminal_surface.py:218). Reducing it to a wrapper over child_record would send both writers through the reader's search, so this PR would also need tests showing each writer still finds the same unit. If a maintainer prefers the single loop, I will make that change here, with those tests.

@javenciu

javenciu commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author
  • Item 5, crew_log_slots_for is undeclared in "What changed". fixed in the description: the What changed section names both new lookups, child_record and crew_log_slots_for, in the crew-log row of the stream table and in "Two lookups outside the timeline module". The Renderer paragraph says the module reaches the crew log only through child_record and read_page. No code changed.

@javenciu

javenciu commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author
  • The visible description says the crew-log stream goes through unit_holding_child. fixed in the description: the Renderer paragraph says the module reaches the crew log only through child_record and read_page, which is what read_child_entries imports and calls (src/kiro_crew/taskq/timeline.py:378-391). The crew-log row of the stream table names crew_log_slots_for and child_record, and "Two lookups outside the timeline module" describes both. No code changed.

@javenciu
javenciu force-pushed the feat/task-timeline-route branch from c6b02da to 0757b9b Compare November 9, 2026 21:15
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 9, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

This needs a maintainer decision before it can merge. The PR adds a new owner-only API route, GET /api/tasks/{task_id}/timeline, and adds it to the feature map. Two questions are still open for a maintainer. First, can the route land before the panel that will call it? Nothing in the website, CLI or MCP calls it yet. Second, a maintainer reserved the new auth gate and credential redaction on this PR for their own review. A maintainer will post the decision here. To propose a design, follow the request-for-change process in CONTRIBUTING.md (docs/request-for-change/).

The review found no blocking defect on head 0757b9b. It checked that the owner gate runs before the task row is read and that all store, crew-log and registry reads run off the event loop. It also checked that every key and leaf is scrubbed before encoding and before the length cut, and that a stream that cannot be read is reported as unavailable or truncated, never as empty. The new test file passed its 137 tests serially, under xdist, in reversed order and in a shuffled order.

Security: the route calls require_owner_dashboard_request first. That gate is stricter than the one the sibling task routes use: it refuses app tokens and non-owner callers, and it records each denial in the audit log. task_id reaches only a parameterized store lookup. scrub is a required argument with no default, so the renderer cannot run unscrubbed. Tests pin the gate, the key scrub and the final line scrub.

Optional:

  • test/test_taskq_timeline.py lines 1446 and 1470 to 1582: _BASE_GOLDEN and the exact route-set equality pin five task routes this PR does not touch, so an unrelated later change to those routes turns this file red. Checking only that the timeline route is present would avoid that, and it also brings the file under the 1,600-line target.
  • crew_log/resolve.py child_record: its strict=True listing and its fold-failure UnitSearchFailed have no test, because the only failure-path test replaces child_record itself. A test that makes the store or the fold fail, like the ones in test/test_subagent_panel_fold_replay.py, would pin the rule that an unreadable stream never shows as empty.
  • docs/system-specs/modules/learn-cron-dashboard.md around line 3926 still says only the two action routes are owner-gated and that app tokens are not affected. The timeline route uses the stricter gate, which refuses app tokens.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving at 0757b9b, without auto since you hold auto-merge.

  • GET /api/tasks/{task_id}/timeline merges one task's task_events, the subagent/* entries of the session that dispatched it, and, for a workflow agent row, the run's events into one markdown list in time order (taskq/timeline.py). It is a read-only view: nothing is stored or written back, and each stream is read through its owner's existing surface (child_record and read_page for the crew log, the run registry for workflows).
  • The route is owner-only, and the gate runs before the id is looked up, so a refused caller learns nothing about it. scrub is a required argument with no default. It runs on every key and leaf before any encoding, on every value before it is cut, and on every rendered line, using the same _scrub_value as the other task payloads.
  • Every stream has a bound: CREW_SCAN_MAX, CREW_ENTRIES_MAX, WORKFLOW_EVENTS_MAX and the detail route's events tail. A stream that cannot be read is reported as unavailable or truncated with a reason in the ## Streams list, not dropped, so an empty timeline never reads as "nothing happened". A damaged time (inf, nan, out of range) is counted as unreadable instead of failing the view.
  • crew_log_slots_for tries every slot name a crew-log writer may have used, so a closed tab's log is still found. child_record reads the fold state, so a child whose card was dismissed still has a history.
  • No regex in product code, and nothing that newly refuses: it is a new owner-only read.

The newest run of every check on this head is green, and the Opus 5.5 lane reports no findings.

@javenciu
javenciu merged commit 1ece378 into main Nov 9, 2026
99 of 108 checks passed
@javenciu
javenciu deleted the feat/task-timeline-route branch November 9, 2026 23:12
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants