Skip to content

fix(dashboard): check the screenshot output off the event loop - #24109

Merged
KiroCrewCaptain merged 1 commit into
kirodotdev:mainfrom
IngridMorstrad:fix/screenshot-exists-off-loop
Oct 26, 2026
Merged

KiroCrewCaptain merged 1 commit into
kirodotdev:mainfrom
IngridMorstrad:fix/screenshot-exists-off-loop

Conversation

@IngridMorstrad

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Taking a screenshot from the dashboard (POST /api/screenshot) no longer blocks the gateway's event loop.

api_screenshot created the data home's screenshots/ directory and, once screencapture -i exited, checked dest.exists() to tell a saved capture from a cancelled one. Both calls ran inside the coroutine. On a data home whose mount has stopped answering, each one blocks in the kernel, so all of the gateway's work stops while it waits. check_sync_io_in_async already listed the exists call in its baseline.

Why it matters

The gateway runs one event loop. A stalled syscall there freezes every session, channel, cron and MCP call at once. If the stall lasts longer than dashboard.loop_stall_exit_after_secs, the watchdog restarts the gateway and every in-flight turn is lost (#1572, #3057).

Not a goal

  • Changing what the route returns: the saved path, the empty path on cancel, the 504 on timeout, the 400 off macOS and the 501 without a trusted screencapture stay the same.
  • The trusted-binary lookups in the same file (trusted_system_bin), which stat fixed system directories, not the data home.
  • The other rows in the sync-io baseline.

What changed (motivation → approach → change)

Symptom: a slow or wedged data-home mount can stall every session while someone takes a screenshot. Root cause: the screenshots directory's mkdir and the output file's exists check ran on the event-loop thread.

Both calls now run through asyncio.to_thread in dashboard/file_api/desktop.py. The screenshots directory is the gateway's own path, never one the request picks, so the default executor is the right lane, not the bounded path-probe pool that request-chosen paths use (the same call as #22222 and #23967). The gate does not match mkdir, but it is the same blocking class on the same directory, so it moves too.

The file_api/desktop.py row is pruned from .github/sync-io-in-async-fs-baseline.txt with --update-baseline.

Backwards compatibility

Compatible: the route, its status codes and its response shape are unchanged; only the thread the two filesystem calls run on moves.

Removes nothing: the baseline row is dropped because the call it allowed no longer runs on the loop. No reader, route or key goes away.

Tests

  • test/test_dashboard_files_coverage.py::TestNativePickers::test_screenshot_fs_calls_run_off_the_event_loop_thread[saved|cancelled]: makes a real request through TestClient with a fake screencapture that either writes the file or does not. It asserts the response (the saved path, or "" on cancel) and that the screenshots directory's mkdir and the output file's exists ran on a thread other than the event loop's. The existing screenshot tests (saved, cancelled, timeout, off macOS, untrusted binary) pass unchanged.
  • Determinism: 20/20 repeated runs pass, and the whole TestNativePickers class passes in reversed order. The test only observes threading.get_ident() and uses no timing.

Proof: PROVEN test/test_dashboard_files_coverage.py::TestNativePickers::test_screenshot_fs_calls_run_off_the_event_loop_thread[saved], test/test_dashboard_files_coverage.py::TestNativePickers::test_screenshot_fs_calls_run_off_the_event_loop_thread[cancelled] (head 45b2986)

Gates run locally: check_sync_io_in_async.py (130 calls / 54 files), check_black_formatting.py, check_subprocess_encoding.py, comment-history, brand-name, isort, flake8, mypy, docs-lint.sh, test_flake_pattern_ratchet.py. test_dashboard_files_coverage.py, test_dashboard_files_onloop_fs.py, test_dashboard_files_composition_contract.py, test_lazy_data_home_paths.py and test_sync_io_in_async_gate.py pass (395 passed). local-gate.py's related set fails 27 tests, all in test_kas_bundle.py (this host's glibc (2.26) is older ...). The same 27 fail on a clean origin/main worktree on this host, so they come from the environment, not this diff. semgrep is not installed here, so the SAST lane covers it.

Manual verification

N/A: the route only runs on macOS and this change was made on Linux. The unit test drives the real aiohttp route and checks the thread the syscalls run on, which is the property this change exists for.

Related Issues

Closes #24094

Sibling sweep

Swept: git grep -nE "trusted_system_bin\(|\.mkdir\(|\.exists\(\)" -- src/kiro_crew/dashboard/file_api/desktop.py, an AST scan for .mkdir( calls inside async def under src/kiro_crew/dashboard/file_api/, and the file_api/ rows of .github/sync-io-in-async-fs-baseline.txt
Sibling: src/kiro_crew/dashboard/file_api/desktop.py:144 -- not affected -- the trusted_system_bin lookups here and at line 200 stat fixed system directories on the boot volume, not the data home
Sibling: src/kiro_crew/dashboard/file_api/uploads.py -- not affected -- a different handler family still on the baseline, out of this PR's goal

Pattern harvest

Not generalizable: the class (a blocking fs call inside async def) is already enforced repo-wide by scripts/check_sync_io_in_async.py; this PR only pays down one baselined row of it.

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

Contributed under the project's Apache-2.0 license.

POST /api/screenshot created the data home's screenshots directory and
checked whether screencapture wrote its file directly inside the
coroutine. On a data home whose mount has stopped answering, either
syscall blocks the gateway's single event loop, stalling every session
until the loop watchdog restarts the gateway.

Run the mkdir and the exists check with asyncio.to_thread. The
screenshots directory is the gateway's own path, not one the request
picks, so the default executor is the right lane. Prune the handler's
row from the sync-io baseline with --update-baseline and add a test that
both calls run off the loop thread for a saved and a cancelled capture.

Closes kirodotdev#24094
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Oct 25, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

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

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 45b2986777e62ee76de855081da51a9dfedaa5d1 via the fork AI-review pipeline — 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

Nothing blocks. Both moved calls are the only data-home filesystem calls in api_screenshot, and the file already uses asyncio.to_thread at line 116 for the same job.

What this change ships

Inventory (4 items) — 4 justified

Intent: let someone take a dashboard screenshot without freezing every other gateway session. This is a FIX (#24094).

  1. Creating the screenshots directory no longer blocks the gateway's event loop — justified
  2. The saved-vs-cancelled check on the capture no longer blocks the event loop — justified
  3. The sync-io gate no longer allows a blocking call in file_api/desktop.py — justified
  4. A test checks that both calls run on a thread other than the event loop's — justified

[FIRST-PRINCIPLES-REVIEWED] 45b2986

Description read

[DESCRIPTION-READ] d33349971b4e87df217fe2cb1b095a4fe3c766013ca2a7932406a38f82f90417

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 45b2986777e62ee76de855081da51a9dfedaa5d1 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the change only moves two data-home filesystem calls onto a worker thread, it takes nothing away, and CI runs the route under a fake screencapture (and has macOS lanes), so the "Manual verification: N/A" line covers no branch that CI misses.

[DESIGN-REVIEWED] 45b2986

Description read

[DESCRIPTION-READ] c4d5772a1d49eca0416bdd54a2fefc4af8de15f401c3c02b072827c8307757b5

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 45b2986777e62ee76de855081da51a9dfedaa5d1 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 45b2986

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 45b2986777e62ee76de855081da51a9dfedaa5d1 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 45b2986

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 25, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) October 26, 2026 03:02

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

Tier 1 auto-approve: fix (3 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: runs the screenshot directory mkdir and exists check on a worker thread and drops the sync-io baseline entry, with tests for the saved and cancelled paths.

@KiroCrewCaptain
KiroCrewCaptain merged commit 5555ef6 into kirodotdev:main Oct 26, 2026
185 of 189 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bug(dashboard): POST /api/screenshot checks its output file on the event loop

2 participants