Skip to content

refactor(dashboard): split files.py, terminal.py and usage.py by owner - #20835

Merged
iamwhatever merged 1 commit into
mainfrom
refactor/linecap-s06-files
Oct 17, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
refactor/linecap-s06-files

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Bring dashboard/handlers/files.py, terminal.py and usage.py under the 2,000-line cap by moving their code into owner modules, with no behaviour change.

The repository is adopting a hard rule that no hand-written file exceeds 2,000 lines (#20192). These three dashboard handlers were 3,211, 2,895 and 2,807 lines. files.py changes several times a week, so it needs real headroom under the cap, not just a few lines.

Why it matters

Every file-route, terminal or usage change edits one of these three files, so concurrent changes collide in them and each review reads past thousands of unrelated lines. After this change each responsibility has its own module, and the next feature lands in the owner of its family instead of growing a 3,000-line file.

Not a goal

  • Any behaviour, route, message, log line or config change: every moved definition is the same code (see Move audit).
  • Moving code that an added-line gate or a repository guard holds in place: it stays in its original file (listed below).
  • Fixing or rewording pre-existing code or comments, beyond the citations that name where moved code lives.

What changed (motivation → approach → change)

Each module stays the import path and patch surface its routes, callers and tests use, and moves whole definitions, unchanged, into owners grouped by responsibility. files.py already composes the dashboard/file_api/ owners onto its globals (through the shared kiro_crew._facade_compose.compose), so its routes join that family. terminal.py and usage.py become mirror facades (kiro_crew._facade_mirror): the facade imports what its own code reads and serves the rest, and a patch through the facade is written into every owner that holds the name.

Facade Lines New or extended owners
handlers/files.py (compose) 3,216 → 1,261 file_api/path_probe.py (the _run_path_probe chokepoint), outbox.py (outbox routes), channel_upload.py (Slack and channel uploads and their admission gate), desktop.py (reveal, native picker, screenshot), editor.py (file read, raw, write, diff); grep.py takes api_file_grep
handlers/terminal.py (mirror) 2,895 → 1,551 terminal_session.py (session state, registry, config gate), terminal_shell.py (shell, cwd, child env), terminal_transport.py (socket ownership, PTY bytes), terminal_lifecycle.py (child exit, teardown, orphan reaper), terminal_complete.py (path-completion vetting), terminal_routes.py (create, list, delete)
handlers/usage.py (mirror) 2,807 → 842 usage_store.py (shards, window, slot categories, row readers), usage_spend.py, usage_context.py, usage_cost.py, usage_history.py, usage_sessions.py

What stays in each facade, and why, is listed under Move audit below: files.py keeps its state, shared seams and the two directory-picker routes (their skip sets hold a literal the internal content scan refuses on an added line), which is why it ends at 1,261 lines, under the 2,000-line cap.

Backwards compatibility

Compatible: every name the three modules bound before still resolves on them to the same object, routes and the handlers package re-exports are unchanged, and every patch target still reaches the code it patched (test_dashboard_files_composition_contract, test_campaign_facades_base_public_names, test_facade_mirror_guards).

Reader: src/kiro_crew/dashboard/handlers/files.py:is_tracked_channel -- chat -- bound on the facade by attribute (test_file_send_channel)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_reveal_path -- crew page -- composed from file_api/desktop.py (test_dashboard_files_composition_contract)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_outbox_notify -- subagent -- composed from file_api/outbox.py (test_file_delivery_consent)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_outbox_download -- chat -- composed from file_api/outbox.py (test_file_delivery_consent)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_outbox_list -- chat -- composed from file_api/outbox.py (test_dashboard_files_composition_contract)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_slack_upload_file -- chat -- composed from file_api/channel_upload.py (test_file_send_channel)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_channel_upload_file -- chat -- composed from file_api/channel_upload.py (test_file_send_channel)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_upload -- crew page -- composed from file_api/desktop.py (test_dashboard_files_composition_contract)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_screenshot -- crew page -- composed from file_api/desktop.py (test_dashboard_files_composition_contract)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_file_read -- crew page -- composed from file_api/editor.py (test_credential_redaction_switch)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_file_raw -- crew page -- composed from file_api/editor.py (test_file_raw)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_file_write -- crew page -- composed from file_api/editor.py (test_dashboard_file_io)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_file_grep -- crew page -- composed from file_api/grep.py (test_file_grep)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_file_diff -- crew page -- composed from file_api/editor.py (test_credential_redaction_switch)
Reader: src/kiro_crew/dashboard/handlers/terminal.py:api_terminal_create -- crew page -- served from terminal_routes (test_terminal_handler)
Reader: src/kiro_crew/dashboard/handlers/terminal.py:api_terminal_delete -- crew page -- served from terminal_routes (test_terminal_handler)
Reader: src/kiro_crew/dashboard/handlers/terminal.py:api_terminal_list -- crew page -- served from terminal_routes (test_terminal_handler)
Reader: src/kiro_crew/dashboard/handlers/terminal.py:reap_orphaned_terminals -- release -- served from terminal_lifecycle (test_dashboard_server_startup_coverage)
Reader: src/kiro_crew/dashboard/handlers/usage.py:resolve_window -- crew page -- served from usage_store (test_telemetry_time_window)
Reader: src/kiro_crew/dashboard/handlers/usage.py:spend_key_for_slot -- chat -- served from usage_spend (test_session_spend_identity)
Reader: src/kiro_crew/dashboard/handlers/usage.py:slot_spend -- chat -- served from usage_spend (test_session_memory)
Reader: src/kiro_crew/dashboard/handlers/usage.py:daily_credits -- crew page -- served from usage_spend (test_usage_daily_credits)
Reader: src/kiro_crew/dashboard/handlers/usage.py:is_session_slot -- crew page -- served from usage_store (test_cost_breakdown)
Reader: src/kiro_crew/dashboard/handlers/usage.py:session_category -- crew page -- served from usage_store (test_telemetry_column_taxonomy)
Reader: src/kiro_crew/dashboard/handlers/usage.py:context_occupancy -- crew page -- served from usage_context (test_context_occupancy)
Reader: src/kiro_crew/dashboard/handlers/usage.py:slot_turn_usage -- crew page -- served from usage_spend (test_usage_turns)
Reader: src/kiro_crew/dashboard/handlers/usage.py:context_trace -- crew page -- served from usage_context (test_context_trace)
Reader: src/kiro_crew/dashboard/handlers/usage.py:cost_breakdown -- crew page -- served from usage_cost (test_cost_breakdown)

Move audit

src/kiro_crew/dashboard/handlers/files.py: 3216 -> 1261 lines; moved 98.45% (python-ast)
   changed: Expr [Expr] 19 lines   (module docstring: the owner list)
   changed: Expr [Expr] 19 lines   (the compose call: five owners added)
src/kiro_crew/dashboard/handlers/terminal.py: 2895 -> 1551 lines; moved 98.72% (python-ast)
   changed: _pty_child_env [FunctionDef] 32 lines   (docstring pointer: the spawn comment it cites stays in api_terminal_ws)
   changed: If [If] 2 lines        (the TYPE_CHECKING DashboardState import moves to terminal_session)
src/kiro_crew/dashboard/handlers/usage.py: 2807 -> 842 lines; moved 98.11% (python-ast)
   changed: _wrapper_chain [FunctionDef] 47 lines   (kept in the facade; its docstring cites providers/acp_runtime_start.py, L29)

Every moved definition has the same AST as at base; owners are black-formatted. The edits inside moved code are comment and docstring only: an own-line # nosemgrep above the diff route's git show argv (the finding is pre-existing; a new path re-reports it), a same-line # wokeignore:rule=master on _TerminalSession.master_fd (the other master_fd lines carry it), and one docstring pointer in _pty_child_env (see the spawn comment in api_terminal_ws). files.py binds is_tracked_channel by attribute from channel_upload (the lazy-import contract pins every import of that name to kiro_crew.slack.handler). The one moved exception class, _PathProbeBusy, keeps __module__ = "kiro_crew.dashboard.handlers.files", the path callers import it from, so a traceback renders it as before; the other moved classes (_PathProbe, _TerminalSession, _ConptyBackend, TimeWindow) take their owner's module, and nothing in the tree reads their __module__ or pickles them. The split is a reproducible recipe; git diff and git diff --minimal add the same lines in every changed file (files.py +84/-2039, terminal.py +127/-1471, usage.py +144/-2109). Diff: 810,154 bytes.

What stays, and why: files.py keeps the module state, the imports its owners read, and the shared seams (_sel, _audit_file_send, _subagent_parent_session_key, _body_err_code, _walk_monotonic, _owner_view_bypasses_credential_pass). It also keeps the two directory-picker routes, api_browse_dirs and api_browse_files, byte-identical in their base place: their skip sets hold a literal the internal content scan refuses on an added line, so they cannot move. That is why files.py ends at 1,261 lines, above the 1,200 this campaign aims for on a file that changes this often, and well under the 2,000-line cap. terminal.py keeps the WebSocket route (path pins, BENIGN_SPAWNS), the completion route and its listing (comment-history and brand on its docstrings), the redaction route (NON_EGRESS_REDACTION_MODULES), the lsof and fence-shell probes (cross-platform and subprocess-encoding gates) and the bash readiness hook. usage.py keeps the token-record writer with the family's one kiro_crew.acp import (agent-sdk boundary), the one emit_turn_duration call, and the turn-model resolution. Moved code logs through the original logger names (logging.getLogger("kiro_crew.dashboard.handlers.terminal") / ...usage; file_api owners log through the facade's logger by compose), so log captures keyed on them see the same records. terminal_shell.py (139 lines) is under 150 on purpose: what a new session's shell is and inherits is one responsibility, separate from session state.

The docs follow the move: the owner maps in docs/system-specs/modules/learn-cron-dashboard.md (file API, terminal and usage owners), the file citations in file-search.md, security.md, governance.md, computer-use.md, platform-context.md, metrics.md, crew-log-emitter.md, common/code-style.md, rfc-issue-radar-crews.md, rfc-chat-document-attachments.md and rfc-resumable-subagent-sessions.md (a line citation becomes a symbol), and the facade list in docs/feature-map/README.md. src/kiro_crew/security_posture.py lists the outbox, channel_upload and editor owners in NON_EGRESS_REDACTION_MODULES beside grep.py: they redact what the facade's registered sink rows already name.

Comment citations (KC28 L29)

Prose that named one of these files as the home of code this change moves now names the owner; only the cited path changes.

File Old New
agent.py, agent_discovery.py, apps/bridges.py, apps/builtins/auto_research/campaign/storage.py, dashboard/handlers/files.py, dashboard/handlers/hooks.py, dashboard/handlers/mcp.py, mcp_discovery.py, session_map.py, slack/sessions_view.py, subagent_persistence.py dashboard/handlers/usage.py is the reference implementation dashboard/handlers/usage_store.py ...
test/test_lazy_data_home_paths.py:22 dashboard/handlers/usage.py dashboard/handlers/usage_store.py
crew_log/emit.py:127, config/paths.py:1205 dashboard/handlers/usage.py dashboard/handlers/usage_sessions.py
dashboard/handlers/usage.py:106 (relayed from the provider split) providers/acp.py:610 providers/acp_runtime_start.py (AcpProvider._start_kiro_runtime_impl, where _client takes the session provider)
dashboard/handlers/core.py:3190 terminal.py _completion_disabled terminal_session.py _completion_disabled
dashboard/handlers/appearances.py:60, :156 handlers/files.py (SVG policy) file_api/editor.py
dashboard/handlers/knowledge.py:1278 handlers/files.py (native picker) file_api/desktop.py
apps/builtins/pptx_maker/backend/routes.py:382 dashboard/handlers/files.py (SVG hazard note) dashboard/file_api/outbox.py
task_executor.py:997, :1656, dashboard/handlers/hooks.py:1564, subagent_manager/run.py:3545 dashboard/handlers/files.py imports is_tracked_channel dashboard/file_api/channel_upload.py imports ...
docs/request-for-change/rfc-issue-radar-crews.md:533, :625 _MAX_SESSIONS in handlers/terminal.py handlers/terminal_session.py
docs/request-for-change/rfc-chat-document-attachments.md:124 _gate_upload_file (handlers/files.py) dashboard/file_api/channel_upload.py
test/test_session_memory.py:514 slot_spend ... usage.py usage_spend.py
test/test_api_file_diff.py:1 api_file_diff ... dashboard/handlers/files.py dashboard/file_api/editor.py (served by handlers/files.py)

Folded from the campaign review of this change: (1) the four is_tracked_channel circular-import comments, (2) _MAX_SESSIONS in rfc-issue-radar-crews.md (two sites), (3) _gate_upload_file in rfc-chat-document-attachments.md, (4) slot_spend in test_session_memory.py, (5) the module docstring of test_api_file_diff.py, (6) one sentence in the file_api/__init__.py docstring and in the learn-cron owner paragraph saying _PathProbeBusy reports the facade module, and (7, 8) the two frontend comments listed under "References not edited (cost)" below.

cron.py:286 and dashboard/state.py:7507 also cite the old files. Other changes were reshaping those files, so this PR leaves both alone; the re-point is tracked in #21087. Both names still resolve through the facades.

References not edited (cost): two frontend code comments keep their old path, because a comment-only edit there would pull the frontend CI jobs onto this backend split. The follow-up that re-points them is tracked in #21087.

File Cites Code now lives in
website/src/pages/telemetryRange.ts:6 resolve_window in dashboard/handlers/usage.py dashboard/handlers/usage_store.py (served by usage.py)
website/capture/path-chips.tsx:13 api_file_read in dashboard/handlers/files.py dashboard/file_api/editor.py (served by files.py)

CI path references

  • .github/workflows/macos-on-demand.yml darwin filter: the six src/kiro_crew/dashboard/handlers/terminal_*.py owners beside terminal.py (the file_api owners were already covered by file_api/**).

Tests

No assertion's matcher or expected value is relaxed. Source-reading pins read the code where it lives (KC28 L30 re-points, L40(8) joins), and each goes red under a mutation in the code's new home (21 mutation cases, all red):

  • Re-pointed: test_appearance_library (SVG policy) and test_desktop_ui_trusted_bin (git argv) read file_api/editor.py; test_cse_2026_08_07_fixes slices file_api/channel_upload.py.
  • Rows: test_json_object_body_guard (six register keys), test_spawn_audit BENIGN_SPAWNS (four keys, among them file_api/editor.py::_diff_redacted_bodies, the git spawn fix(dashboard): build the file panel diff from whole redacted files #20594 added to the diff route), test_security_posture census (dashboard/file_api/outbox.py: 1), test_credential_redaction_switch exact set (+ file_api/editor.py), test_no_config_dir_in_async (six owners), error-code-baseline.json (files.py's 33 split as outbox 11, editor 12, desktop 7, channel_upload 3; totals unchanged), test_campaign_facades_base_public_names (two new inventory files, test/campaign_facade_inventories/kiro_crew.dashboard.handlers.terminal.json and ...usage.json).
  • Joined (facade + every owner): the terminal stream guards (test_redactors_are_called_only_by_the_selection_handler, test_no_send_through_the_session_field_after_an_await) and the one-emit guard in test_turn_metric_all_surfaces.
  • test_dashboard_files_composition_contract: owner set, base owners, facade definitions and the shape digest gain the moved names (taken from the base file); _STAYS_IN_THE_FACADE becomes _GUARDED_CONSTRUCT_HOMES (each construct in exactly its named files, absent from every other file of the family). This reverses a base pin on purpose. Base _FACADE_DEFS kept file delivery (the outbox routes with the census site, the Slack and channel uploads with their admission gate) and every route a guard reads by path in files.py, because those guards read files.py by path. This PR re-points each of those guards, path only, to the file the route now lives in, and a mutation in that file turns each one red. That reason for holding the routes in files.py therefore no longer applies. What a gate cannot follow stays: the two directory-picker routes and their content-scan literal; the census check reads the outbox owner; the register keeps no handlers/files.py key.
  • New test_terminal_facade.py, test_usage_facade.py: owner set and layer order, the TYPE_CHECKING home manifest for served names, the shared logger, and a facade patch reaching the owner that reads it. New test_files_path_probe.py: _PathProbeBusy names the facade module in a traceback, is one class for every importer, and defines no methods (compose selects classes by their owner __module__, so a method on it would not be rebound). Each new file passes 5 repeat runs at -n 0 and one at -n 3.

Local gates: 159 related test files (every file that imports, patches or reads these modules, plus the repository guards that scan them) 7,608 passed, 16 skipped; every new module at or above 82% line coverage under them (channel_upload.py 82.1%, the rest 88-100%); mypy src/kiro_crew clean (2,447 files); isort, flake8, black gate, subprocess-encoding, agent-sdk boundary, sync-io, loop-locks, memory-store, cwd-reads, comment-history, brand, harness, feature-map, docs-lint and line-cap (0 failures) pass; semgrep 1.78 with CI's rule set over the 60 changed Python files: 0 new findings, no parse errors; flake-pattern ratchet passes; take-away hits are the 28 Reader lines above. scripts/local-gate.py --dry-run selects 3,678 backend + 2,139 frontend files, so the floor above ran instead and CI owns the broad matrix.

Notes: the terminal_transport.py module docstring and its entry in the learn-cron owner map say the bash readiness marker is "matched, not removed": the code matches it and forwards the output bytes unchanged, as the spec's "Terminal input readiness" row states.

Manual verification

N/A: a verbatim move behind unchanged import paths; the 159 related test files exercise every moved route and helper.

Related Issues

Part of #20192

Follow-up: #21087 (re-points four code comments that still cite the split files)

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • 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

Contributions are accepted under the project's Apache-2.0 license.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 4531849
  • What rule changed: no rule changes. src/kiro_crew/security_posture.py adds three NON_EGRESS_REDACTION_MODULES rows (dashboard/file_api/outbox.py, dashboard/file_api/channel_upload.py, dashboard/file_api/editor.py), because the redactor calls of the outbox, channel-upload and file read/diff routes move there from dashboard/handlers/files.py unchanged. One comment beside the grep row now names the owner files.
  • Before -> after (what was allowed/blocked, now): nothing allowed or blocked changes. Before, those redactor calls sat in handlers/files.py and its rows classified them; after, the same AST-identical calls sit in the three owners, classified non-egress for the same reason as the existing file_api/grep.py row. The sink rows keyed on handlers/files.py stay, because the facade still binds the redactors those routes call.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): the redaction drift guard would miss an egress sink in one of the three owners. No runtime path reads these registries, so no command breaks, no secret leaks and no user is locked out by the rows themselves.
  • Evidence checked (which sandbox result proves it): no sandbox code changes. test/test_security_posture.py passes, including the census row dashboard/file_api/outbox.py: 1 and omission detection. Mutations prove the guard reaches the moved code: removing the outbox row, or planting a second census site in channel_upload, turns it red. The move audit shows every moved route body AST-identical to base.
  • No regression:
  • Tools still work (which tools/commands were run, result): the file read, raw, diff, outbox and channel upload routes run the same code through the handlers/files.py facade; the 159 related test files pass (7,608 passed, 16 skipped) and mypy is clean.
  • Backward compatible (old config / old data / old callers still work, how checked): every import path and patch target on kiro_crew.dashboard.handlers.files still resolves, checked by test_dashboard_files_composition_contract and test_campaign_facades_base_public_names; no config or data format changes.
  • Existing tests (which suites passed on this head): test_security_posture, test_credential_redaction_switch, test_spawn_audit, test_api_file_diff, test_dashboard_files_composition_contract and the rest of the related set pass; only path-keyed rows are re-pointed to the owners, and no assertion is relaxed.
  • How to undo: revert this single commit; the registry rows and the moved code go back together.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 15, 2026
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Sensitive Change Review

Sensitive files changed:

  • src/kiro_crew/security_posture.py

  • @bolichen97 posted a complete reasoning template for 6495e53.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 6495e535d5e07777480e772d99c924d59e3f0b2c touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 6495e535d5e07777480e772d99c924d59e3f0b2c — 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/CONCERNS are advisory.

First-Principles-Verdict: PASS

Before merge, confirm that outbox.py, channel_upload.py and editor.py really open no output path of their own. The diff adds them to NON_EGRESS_REDACTION_MODULES.

What this change ships

Inventory (7 items) — 7 justified

Intent: keep three dashboard handler modules under the 2,000-line cap with no behaviour change. This is a FIX (a mandated cap), not a feature.

  1. files.py route families move into dashboard/file_api/ owners, joined through the existing _facade_compose — justified
  2. terminal.py splits into six terminal_* owners behind the existing _facade_mirror — justified
  3. usage.py splits into six usage_* owners behind the existing _facade_mirror — justified
  4. Three file_api owners join the NON_EGRESS_REDACTION_MODULES allowlist in security_posture.py — justified
  5. Rows for the three files leave the line-cap baseline; error-code, docs-lint and macOS-workflow lists follow the moved paths — justified
  6. Spec and RFC citations point at the owner modules instead of line numbers — justified
  7. _PathProbeBusy keeps its original __module__, so tracebacks look the same — justified

[FIRST-PRINCIPLES-REVIEWED] 6495e53

Description read

[DESCRIPTION-READ] 62c7ce9f6f9392d25f8df5824d7fbd38042b3a6f437a009a919cbea7c29efbb0

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 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — 🟡 CONCERNS

Design-level review of 6495e535d5e07777480e772d99c924d59e3f0b2c — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

The three new file_api owners are filed as "non-egress" even though they hold the actual egress redaction, so the posture census can no longer see new egress there.

Watch

  • The sink census now points at the facade, not at the code. Cause: + "dashboard/file_api/outbox.py", "dashboard/file_api/channel_upload.py", "dashboard/file_api/editor.py", added to NON_EGRESS_REDACTION_MODULES, while the sink rows in security_posture.py ("File cards broadcast…", "File viewer read and diff…") still name dashboard/handlers/files.py. Mechanism: being on the non-egress allowlist exempts a module from needing a registered sink row. These three modules now hold the file-card broadcast, the upload gates and the viewer bodies. Consequence: if a later change adds a new egress path to editor.py or outbox.py, it needs no sink row and the census stays green. The security-posture rows also attribute redaction to a file that no longer does it. grep.py set the precedent, but this PR extends it to the family's main egress code.
    Clears when: the two files.py sink rows are re-keyed to the owners that hold the redaction (outbox/channel_upload for file cards, editor for read/diff), and those owners are left off NON_EGRESS_REDACTION_MODULES.
  • I could only partly check the ## Backwards compatibility list. It is the last section before [description TRUNCATED, so its Reader: list may continue past the cut. The readers I found by path (BENIGN_SPAWNS, spawn audit, JSON-body register, redaction-switch file set, appearance SVG literal, census site) are all re-keyed in this patch, and I found no broken reader that the list leaves out.
    Clears when: the full Backwards compatibility section is visible to the review (trim the description under 8000 bytes or move the move audit into a PR comment).

[DESIGN-REVIEWED] 6495e53

Description read

[DESCRIPTION-READ] 76de102b8c97a4f1bc440b0ecc39e587b22d6d6e7e621cc852cbf2c4d480c680

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 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 6495e535d5e07777480e772d99c924d59e3f0b2c — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 6495e53

Verdict parsed from the review's SHA-scoped output markers for commit 6495e535d5e07777480e772d99c924d59e3f0b2c.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 6495e535d5e07777480e772d99c924d59e3f0b2c: <one-sentence reason>

@bolichen97
bolichen97 enabled auto-merge (squash) October 15, 2026 13:35
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 6495e535d5e07777480e772d99c924d59e3f0b2c and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6495e53

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 6495e535d5e07777480e772d99c924d59e3f0b2c: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 15, 2026
@bolichen97
bolichen97 force-pushed the refactor/linecap-s06-files branch from 4531849 to 7ed20a6 Compare October 15, 2026 14:10
@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 7ed20a6
  • What rule changed: no rule changes. src/kiro_crew/security_posture.py adds three NON_EGRESS_REDACTION_MODULES rows (dashboard/file_api/outbox.py, dashboard/file_api/channel_upload.py, dashboard/file_api/editor.py), because the redactor calls of the outbox, channel-upload and file read/diff routes move there from dashboard/handlers/files.py unchanged. One comment beside the grep row now names the owner files.
  • Before -> after (what was allowed/blocked, now): nothing allowed or blocked changes. Before, those redactor calls sat in handlers/files.py and its rows classified them; after, the same AST-identical calls sit in the three owners, classified non-egress for the same reason as the existing file_api/grep.py row. The sink rows keyed on handlers/files.py stay, because the facade still binds the redactors those routes call.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): the redaction drift guard would miss an egress sink in one of the three owners. No runtime path reads these registries, so no command breaks, no secret leaks and no user is locked out by the rows themselves.
  • Evidence checked (which sandbox result proves it): no sandbox code changes. test/test_security_posture.py passes, including the census row dashboard/file_api/outbox.py: 1 and omission detection. Mutations prove the guard reaches the moved code: removing the outbox row, or planting a second census site in channel_upload, turns it red. The move audit shows every moved route body AST-identical to base.
  • No regression:
  • Tools still work (which tools/commands were run, result): the file read, raw, diff, outbox and channel upload routes run the same code through the handlers/files.py facade; the 159 related test files pass (7,608 passed, 16 skipped) and mypy is clean.
  • Backward compatible (old config / old data / old callers still work, how checked): every import path and patch target on kiro_crew.dashboard.handlers.files still resolves, checked by test_dashboard_files_composition_contract and test_campaign_facades_base_public_names; no config or data format changes.
  • Existing tests (which suites passed on this head): test_security_posture, test_credential_redaction_switch, test_spawn_audit, test_api_file_diff, test_dashboard_files_composition_contract and the rest of the related set pass; only path-keyed rows are re-pointed to the owners, and no assertion is relaxed.
  • How to undo: revert this single commit; the registry rows and the moved code go back together.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 15, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Check the Windows terminal path (the _ConptyBackend move) on a Windows CI run

rebutted: the move cannot change Windows behaviour. _ConptyBackend is a typing.Protocol that only annotates _TerminalSession.winpty (now in terminal_session.py). It has no runtime code.
The Windows-only code that calls sess.winpty.* (_record_and_forward_terminal_output, _kill_session) moved with the same AST as base (move audit: terminal.py 98.72% unchanged; the two changed units are a docstring pointer and the TYPE_CHECKING import).
On this head every Windows lane is green: Backend Tests (Windows) 1-8, which run test_conpty_exit_status.py and test_conpty_wrapper.py (test_terminal_handler.py is POSIX-only by windows-collect-ignore.txt), plus the Windows Fail-Closed Sandbox Contract and the Windows E2E gateway boot.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Check that NON_EGRESS_REDACTION_MODULES still covers outbox, channel_upload and editor

fixed in the diff: the three rows classify the same redactor calls the facade's rows classified before. The calls moved byte-for-byte from dashboard/handlers/files.py into those owners, so the exemption covers no new call site. It now names the file each call lives in, as the existing file_api/grep.py row does.
Guarded both ways on this head: test_security_posture.py::TestOmissionDetection::test_every_redactor_call_site_is_a_registered_sink_or_allowlisted turns red when the outbox row is removed (mutation run on the final tree), and the census row dashboard/file_api/outbox.py: 1 turns red when a second site is planted in channel_upload.py. Both are recorded in the PR body's Tests section.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 15, 2026
chenmingwei23
chenmingwei23 previously approved these changes Oct 15, 2026

@chenmingwei23 chenmingwei23 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: readiness gate passed, no conflicts, checks green.

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approved by a maintainer after reading the review lanes: every lane is clean on this head, and the automated triage held it only on a size, path, category or doc rule.

@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
@bolichen97
bolichen97 force-pushed the refactor/linecap-s06-files branch from 7ed20a6 to 7a144ec Compare October 15, 2026 20:56
@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 7a144ec
  • What rule changed: no rule changes. src/kiro_crew/security_posture.py adds three NON_EGRESS_REDACTION_MODULES rows (dashboard/file_api/outbox.py, dashboard/file_api/channel_upload.py, dashboard/file_api/editor.py), because the redactor calls of the outbox, channel-upload and file read/diff routes move there from dashboard/handlers/files.py unchanged. One comment beside the grep row now names the owner files.
  • Before -> after (what was allowed/blocked, now): nothing allowed or blocked changes. Before, those redactor calls sat in handlers/files.py and its rows classified them; after, the same AST-identical calls sit in the three owners, classified non-egress for the same reason as the existing file_api/grep.py row. The sink rows keyed on handlers/files.py stay, because the facade still binds the redactors those routes call.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): the redaction drift guard would miss an egress sink in one of the three owners. No runtime path reads these registries, so no command breaks, no secret leaks and no user is locked out by the rows themselves.
  • Evidence checked (which sandbox result proves it): no sandbox code changes. test/test_security_posture.py passes, including the census row dashboard/file_api/outbox.py: 1 and omission detection. Mutations prove the guard reaches the moved code: removing the outbox row, or planting a second census site in channel_upload, turns it red. The move audit shows every moved route body AST-identical to base.
  • No regression:
  • Tools still work (which tools/commands were run, result): the file read, raw, diff, outbox and channel upload routes run the same code through the handlers/files.py facade; the 159 related test files pass (7,608 passed, 16 skipped) and mypy is clean.
  • Backward compatible (old config / old data / old callers still work, how checked): every import path and patch target on kiro_crew.dashboard.handlers.files still resolves, checked by test_dashboard_files_composition_contract and test_campaign_facades_base_public_names; no config or data format changes.
  • Existing tests (which suites passed on this head): test_security_posture, test_credential_redaction_switch, test_spawn_audit, test_api_file_diff, test_dashboard_files_composition_contract and the rest of the related set pass; only path-keyed rows are re-pointed to the owners, and no assertion is relaxed.
  • How to undo: revert this single commit; the registry rows and the moved code go back together.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased onto c6d610673b (main had moved; the PR was conflicting). CI re-running on 7a144ec068.

  • No split target or owner changed upstream. Every conflict was a row or line union: config/paths.py (one docstring line), the security-posture census rows, two security.md lines.
  • Facade inventories now live in their own files, in the new per-facade form: test/campaign_facade_inventories/kiro_crew.dashboard.handlers.terminal.json and ...usage.json. This PR no longer edits test_campaign_facades_base_public_names.py.
  • Folded in: the terminal_transport.py docstring and owner-map wording ("matched, not removed"), and the _wrapper_chain docstring citation now naming providers/acp_runtime_start.py.
  • git diff and git diff --minimal add the same lines in all 77 files; diff 805,213 bytes.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 16, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=b37f2fce0f3f Routes the deleted contract pin held in files.py moved out of it

fixed in the description, as the item's "Clears when" asks. The Tests section now names the reversed pin and says why its reason no longer applies. Base _FACADE_DEFS kept file delivery and the guard-read routes in files.py because those guards read files.py by path. This PR re-points each of those guards, path only, to the file the route now lives in: the census row, the JSON-body register keys, the BENIGN_SPAWNS keys, the credential-switch file set, and the appearance-library and desktop-binary pins.
Each re-point is proven to still reach the moved code: a mutation in the new home turns the guard red (21 cases). _GUARDED_CONSTRUCT_HOMES holds each construct to exactly its named file. What a gate cannot follow stays in files.py: the two directory-picker routes with their content-scan literal. This class was answered on 7a144ec (653136c5d766) and 6d60529 (a2db6c4c184c); the code is unchanged since.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 16, 2026
The dashboard's files, terminal and usage handlers were 3,211, 2,895 and
2,807 lines, past the 2,000-line cap on hand-written files. Each module
stays the import path and patch surface its routes, callers and tests
use, and its code moves unchanged into owners grouped by responsibility.

files.py stays the file_api compose facade: new path_probe, outbox,
channel_upload, desktop and editor owners, plus the grep owner, take its
routes, and it keeps the module state, the imports its owners read, the
shared seams and the two directory-picker routes, whose skip sets hold
a literal the internal content scan refuses on an added line (1,256
lines). Each construct a repository guard reads by path has named homes
that the composition contract pins.

terminal.py (1,551 lines) and usage.py (842 lines) become mirror facades
(kiro_crew._facade_mirror) over terminal_* and usage_* sibling owners,
so a patch through the facade still reaches every module holding the
name. They keep the code an added-line gate or a path pin holds in
place: the WebSocket, completion and redaction routes, the lsof and
fence-shell probes, the bash readiness hook, the model a turn is
recorded under, and the token writer with the family's one kiro_crew.acp
import.

Guards that read these files by path now read the code's new home, or
the facade joined with its owners; the path-keyed rows, baselines, CI
path filter and owning specs follow the move.

Part of #20192
@bolichen97
bolichen97 force-pushed the refactor/linecap-s06-files branch from c71121e to 6495e53 Compare October 16, 2026 23:14
@bolichen97

Copy link
Copy Markdown
Contributor Author

Sensitive change review

  • Head commit: 6495e53
  • What rule changed: no rule changes. src/kiro_crew/security_posture.py adds three NON_EGRESS_REDACTION_MODULES rows (dashboard/file_api/outbox.py, dashboard/file_api/channel_upload.py, dashboard/file_api/editor.py), because the redactor calls of the outbox, channel-upload and file read/diff routes move there from dashboard/handlers/files.py unchanged. One comment beside the grep row now names the owner files.
  • Before -> after (what was allowed/blocked, now): nothing allowed or blocked changes. Before, those redactor calls sat in handlers/files.py and its rows classified them; after, the same AST-identical calls sit in the three owners, classified non-egress for the same reason as the existing file_api/grep.py row. The sink rows keyed on handlers/files.py stay, because the facade still binds the redactors those routes call.
  • Worst case if wrong (breaks commands / leaks secret / locks user out): the redaction drift guard would miss an egress sink in one of the three owners. No runtime path reads these registries, so no command breaks, no secret leaks and no user is locked out by the rows themselves.
  • Evidence checked (which sandbox result proves it): no sandbox code changes. test/test_security_posture.py passes, including the census row dashboard/file_api/outbox.py: 1 and omission detection. Mutations prove the guard reaches the moved code: removing the outbox row, or planting a second census site in channel_upload, turns it red. The move audit shows every moved route body AST-identical to base.
  • No regression:
  • Tools still work (which tools/commands were run, result): the file read, raw, diff, outbox and channel upload routes run the same code through the handlers/files.py facade; the 159 related test files pass (7,608 passed, 16 skipped) and mypy is clean.
  • Backward compatible (old config / old data / old callers still work, how checked): every import path and patch target on kiro_crew.dashboard.handlers.files still resolves, checked by test_dashboard_files_composition_contract and test_campaign_facades_base_public_names; no config or data format changes.
  • Existing tests (which suites passed on this head): test_security_posture, test_credential_redaction_switch, test_spawn_audit, test_api_file_diff, test_dashboard_files_composition_contract and the rest of the related set pass; only path-keyed rows are re-pointed to the owners, and no assertion is relaxed.
  • How to undo: revert this single commit; the registry rows and the moved code go back together.

@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
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=6ebb92318f83 The sink census now points at the facade, not at the code

rebutted. Re-keying the two sink rows would change what users see: _redaction_sink_items renders each row's module path into Settings → Security → Output redaction (detail=f"{module} — {detail}"). This PR is a move with no behaviour change, so the posture page stays as it was.
Main already took this shape for the dashboard/state.py split (#6915). Its NON_EGRESS_REDACTION_MODULES comment reads: classifying the implementation files separately "would make a behavior-preserving decomposition change the public posture items". The owners added here follow that rule. They redact the same boundaries the facade's rows name (file-card broadcast, viewer read and diff), through the same routes, which still bind on handlers/files.py.
The guard is no weaker than at base. The drift guard classifies by module. At base every files.py call site was covered by its sink row, so a new egress call added to files.py passed silently, just as one added to outbox.py would now. A sink keyed on outbox.py would have the same per-module granularity. test_security_posture's census row dashboard/file_api/outbox.py: 1 still pins the outbox's log site exactly.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=7bb7997bc7ab The Backwards compatibility list sat past the 8000-byte cut

fixed in the description. ## Backwards compatibility now runs from byte 3,062 to 7,350, inside the first 8,000 bytes, and the move audit and "what stays" detail follow it. The section is complete: 28 Reader: lines, one for each public def take_away_check reports (it passes with exit 0).
Each reader still resolves on its facade: the composed file routes through _facade_compose, the terminal and usage names through the mirror. Each names the test that exercises it.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Confirm outbox.py, channel_upload.py and editor.py open no output path of their own

confirmed. The routes these three owners hold are registered on the facade's objects (handlers/__init__.py re-exports files.api_outbox_*, files.api_*upload_file and files.api_file_*), and their functions run on the facade's globals through _facade_compose. No owner registers a route, opens a socket or writes a response of its own.
What they redact is what the facade's two sink rows already name: the file-card broadcast, and the owner's file read and diff. channel_upload's calls are upload gates, which refuse a send rather than emit masked text. test_security_posture (census and omission detection) and the files composition contract pin this, and both pass on this head.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 17, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Holding 6495e53 for a human reviewer. No defect found.

Why it is reserved: the PR moves the file read/write/raw/diff routes, the outbox file-card broadcast, the upload gates, and the terminal PTY/reaper code. It also adds three dashboard/file_api/ owners to NON_EGRESS_REDACTION_MODULES in src/kiro_crew/security_posture.py. Changes to these areas go to a maintainer.

A maintainer needs to rule on the Design Review CONCERNS (span 6ebb92318f83): the two sink rows still name dashboard/handlers/files.py while the redaction now lives in the owners (

# The outbox routes, the Slack and channel uploads with their admission gate,
# and the file viewer's read, raw, write and diff routes, composed into
# dashboard/handlers/files.py: they redact the file cards, upload gates and
# viewer bodies that facade's registered sink rows already name, and open no
# output path of their own.
"dashboard/file_api/outbox.py",
"dashboard/file_api/channel_upload.py",
"dashboard/file_api/editor.py",
). The author's rebuttal is reasonable: re-keying would change the user-visible posture text, and main used the same shape for the dashboard/state.py split. Whether that is acceptable is a security-posture call for a maintainer.

Why the move looks safe: the AST check against merge base 9fba246 shows all 165 moved top-level units present in their owners. 163 are identical, and _pty_child_env and _wrapper_chain differ only in docstrings. The comment re-points are tracked in #21087, the workflow edit only extends a path filter, and CI is green.

— crew-pr-reviewer (r108)

@iamwhatever iamwhatever 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.

Deep check of 6495e53. This supersedes our earlier sensitive-file HOLD: the sensitive touches are mechanical moves.

  • The file read/raw/write/diff routes, the outbox broadcast, the upload admission gate, and the terminal PTY and orphan-reaper code all move unchanged. AST compare against merge base 9fba246 shows 165/165 units identical apart from docstrings. Every global the composed file_api owners read is bound in handlers/files.py, where _facade_compose runs them. Every old terminal and usage name is still served by the facade.
  • The three new NON_EGRESS_REDACTION_MODULES rows (
    # The outbox routes, the Slack and channel uploads with their admission gate,
    # and the file viewer's read, raw, write and diff routes, composed into
    # dashboard/handlers/files.py: they redact the file cards, upload gates and
    # viewer bodies that facade's registered sink rows already name, and open no
    # output path of their own.
    "dashboard/file_api/outbox.py",
    "dashboard/file_api/channel_upload.py",
    "dashboard/file_api/editor.py",
    ) follow the existing grep.py and dashboard/state.py precedent. The drift guard works per module, so coverage is the same as at base, and no row is dropped. The Design rebuttal holds: the sink rows render their module path on the posture page.
  • Each path-keyed guard (BENIGN_SPAWNS, the JSON-body register, the redaction-switch file set) now points at the file that holds its construct.

AI lanes are answered, the follow-up is #21087, there is no active change request, and CI is green.

— crew-pr-reviewer (r108 deep)

@iamwhatever
iamwhatever merged commit d60dbab into main Oct 17, 2026
119 of 128 checks passed
@iamwhatever
iamwhatever deleted the refactor/linecap-s06-files branch October 17, 2026 07:23
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 17, 2026
CrysisDeu added a commit that referenced this pull request Oct 20, 2026
This reverts commit 7f60e451f6d.

Removes the Estimated Tokens card, the Est. tokens Daily History
column and the backend estimator that fed them. Credits stay as they
were.

The estimator moved from handlers/usage.py into
handlers/usage_sessions.py after the original PR (#20835), so that
part is reverted by hand there; usage.py drops only the facade
re-exports. The docs keep the later credit run-out paragraph.
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