Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/system-specs/modules/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -1167,6 +1167,14 @@ never one) this gate keys one component deeper, so `/home/<user>/mnt/nas/x`
keys to `/home/<user>/mnt` and a dead FUSE or sshfs mount inside the home does
not refuse `/home/<user>/workspace`; the home itself keeps its own key. The rule
is lexical, and the resolver's cooldown keeps the plain `_stall_prefix` key.
A caller whose path is not the first argument names it with `stall_path=`,
keyed by the same rule (`""` means no key): the reveal-and-open closure passes
its path, the terminal passes the requested cwd, and the project-relative
resolve passes `_project_relative_stall_path` (the project directory for a
relative path, the path itself otherwise). Callers that touch several roots
(`/api/file-kinds`, the unscoped file-search fallback) use `_batch_stall_path`:
keyed only when every path shares one key, because a key on one of several
mounts would let a dead mount refuse a healthy one.
While `_PATH_PROBE_STUCK_TO_REFUSE` (2) probe-pool
calls under that prefix have each run longer than `_PATH_PROBE_STALL_SECS` (2 s),
any new call under it, probe or transfer, gets the same `503 path_probe_busy`
Expand Down
2 changes: 1 addition & 1 deletion src/kiro_crew/dashboard/file_api/desktop.py
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ def _stat_then_launch() -> tuple[bool, bool]:
return (True, platform_compat.open_with_default_app(path))

try:
is_regular_file, launched = await _run_path_probe(_stat_then_launch)
is_regular_file, launched = await _run_path_probe(_stat_then_launch, stall_path=path)
except _PathProbeBusy:
return _probe_busy_response(
resource=path, tool_name="reveal_path", session_key="api", source="api"
Expand Down
8 changes: 7 additions & 1 deletion src/kiro_crew/dashboard/file_api/editor.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
_PathProbeBusy,
_probe_busy_response,
_probe_request_path,
_project_relative_stall_path,
_read_request_path,
_resolve_project_relative,
_run_path_probe,
Expand Down Expand Up @@ -81,7 +82,11 @@ async def api_file_read(request: web.Request) -> web.Response:
# the resolved string, so it cannot be folded into the probe.
if request.query.get("resolve") == "1":
try:
raw_path, _resolve_err = await _run_path_probe(_resolve_project_relative, raw_path)
raw_path, _resolve_err = await _run_path_probe(
_resolve_project_relative,
raw_path,
stall_path=_project_relative_stall_path(raw_path),
)
except _PathProbeBusy:
return _probe_busy_response(resource=raw_path, tool_name="file_read")
if _resolve_err == "cannot_resolve":
Expand Down Expand Up @@ -275,6 +280,7 @@ async def api_file_raw(request: web.Request) -> web.Response:
max_bytes=_MAX_UPLOAD_BYTES,
),
transfer=True,
stall_path=request.query.get("path", ""),
)
except _PathProbeBusy:
return _probe_busy_response(resource=request.query.get("path", ""), tool_name="file_raw")
Expand Down
4 changes: 3 additions & 1 deletion src/kiro_crew/dashboard/file_api/grep.py
Original file line number Diff line number Diff line change
Expand Up @@ -802,7 +802,9 @@ def _search() -> tuple[list[dict], bool, str, int]:
return results + doc_hits, truncated or doc_truncated, engine, skipped

try:
results, truncated, engine, skipped_docs = await _run_path_probe(_search, transfer=True)
results, truncated, engine, skipped_docs = await _run_path_probe(
_search, transfer=True, stall_path=root
)
except _PathProbeBusy:
return _probe_busy_response(
resource=f"q={logged_query} root={root}", operation="file_grep", caller=caller
Expand Down
9 changes: 7 additions & 2 deletions src/kiro_crew/dashboard/file_api/office_preview.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
_OpenDenied,
_PathProbeBusy,
_probe_busy_response,
_project_relative_stall_path,
_resolve_project_relative,
_run_path_probe,
_sel,
Expand Down Expand Up @@ -197,7 +198,11 @@ def _log(outcome: str, res: str, error: str = "") -> None:
# Off-loop: the resolution is a pair of realpath calls.
if request.query.get("resolve") == "1":
try:
raw_path, _resolve_err = await _run_path_probe(_resolve_project_relative, raw_path)
raw_path, _resolve_err = await _run_path_probe(
_resolve_project_relative,
raw_path,
stall_path=_project_relative_stall_path(raw_path),
)
except _PathProbeBusy:
return _probe_busy_response(resource=raw_path, tool_name="file_office_preview")
if _resolve_err == "cannot_resolve":
Expand Down Expand Up @@ -340,7 +345,7 @@ def _open_and_extract() -> dict[str, object] | _OpenDenied:
return payload

try:
result = await _run_path_probe(_open_and_extract, transfer=True)
result = await _run_path_probe(_open_and_extract, transfer=True, stall_path=raw_path)
except asyncio.CancelledError:
# Gateway shutdown / client disconnect while the worker thread is
# parsing: the access attempt already happened, so record it before
Expand Down
13 changes: 11 additions & 2 deletions src/kiro_crew/dashboard/file_api/path_probe.py
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,11 @@ def _tracked_path_probe(key: str, fn: Callable[..., _ProbeT], /, *args: object)


async def _run_path_probe(
fn: Callable[..., _ProbeT], /, *args: object, transfer: bool = False
fn: Callable[..., _ProbeT],
/,
*args: object,
transfer: bool = False,
stall_path: str | None = None,
) -> _ProbeT:
"""Run a blocking request-path call on a dedicated bounded pool, or refuse.

Expand Down Expand Up @@ -215,8 +219,13 @@ async def _run_path_probe(
served. Probes that arrive together, before any of them is past the budget,
are still bounded only by the pool. A transfer naming a stuck prefix is refused the same way,
but a transfer never marks a prefix stuck: it legitimately runs long.

``stall_path`` names the path the call touches when it is not the first
argument: a closure, a config-first helper, a root the caller computed. It
is keyed by the same lexical rule, and ``""`` means no key. Without it the
first argument is the key, as before.
"""
key = _path_probe_stall_key(args)
key = _path_probe_stall_key(args if stall_path is None else (stall_path,))
if key and _path_probe_prefix_wedged(key):
raise _PathProbeBusy()
pool = executors.path_transfer_executor() if transfer else executors.path_probe_executor()
Expand Down
33 changes: 32 additions & 1 deletion src/kiro_crew/dashboard/file_api/pinned_io.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
_FILE_KINDS_MAX_PATHS,
_FILE_READ_BINARY_EXTS,
_FILE_READ_SNIFF_BYTES,
_path_probe_stall_key,
_PathProbeBusy,
_probe_busy_response,
_probe_request_path,
Expand Down Expand Up @@ -412,6 +413,34 @@ def _resolve_project_relative(raw: str) -> tuple[str, str | None]:
return candidate, None


def _project_relative_stall_path(raw: str) -> str:
"""The path :func:`_resolve_project_relative` touches for *raw*, for the probe's stall key.

A path it passes through unchanged is its own key, as before. A relative
one is resolved inside the project directory, so it is charged to that
directory: two resolves stuck on a dead project mount then refuse the next
one. ``""`` (no key) when no project directory is set, since that answer
touches no filesystem. Lexical, so it runs on the event loop.
"""
if not raw or raw.startswith(("/", "~", "\\")) or ntpath.splitdrive(raw)[0]:
return raw
return os.environ.get("KIROCREW_PROJECT_DIR", "")


def _batch_stall_path(raws: list[str]) -> str:
"""The stall path for :func:`_classify_request_paths` over *raws*, or ``""``.

The batch is keyed only when every path in it falls under ONE stall key;
then that key is exactly the mount the hop can wedge on. A batch spanning
several mounts gets no key: keying it on any one path (the first, say)
would let two batches stuck on a dead mount listed third refuse a healthy
mount listed first, on every route. Such a batch stays bounded by the pool.
"""
paths = [_project_relative_stall_path(raw) for raw in raws]
keys = {_path_probe_stall_key((p,)) for p in paths}
return paths[0] if len(keys) == 1 else ""


def _classify_request_paths(raws: list[str]) -> list[tuple[str, str, str]]:
"""Classify each request path exactly as ``HEAD /api/file-read?resolve=1`` would.

Expand Down Expand Up @@ -489,7 +518,9 @@ async def api_file_kinds(request: web.Request) -> web.Response:
if not unique:
return web.json_response({"kinds": {}})
try:
verdicts = await _run_path_probe(_classify_request_paths, unique)
verdicts = await _run_path_probe(
_classify_request_paths, unique, stall_path=_batch_stall_path(unique)
)
except _PathProbeBusy:
return _probe_busy_response(resource=f"{len(unique)} paths", tool_name="file_read")
sel = _sel()
Expand Down
14 changes: 11 additions & 3 deletions src/kiro_crew/dashboard/file_api/search.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
_WALK_SKIP_DIRS,
_WALK_TIME_BUDGET_SECS,
DashboardState,
_batch_stall_path,
_PathProbeBusy,
_probe_busy_response,
_run_path_probe,
Expand Down Expand Up @@ -264,9 +265,14 @@ def _probe_fallback_roots() -> tuple[bool, bool]:
return bool(proj) and os.path.isdir(proj), os.path.isdir(mc_workspace)

# Off-loop: two isdir probes on operator-configured paths, either of
# which may sit on a network mount.
# which may sit on a network mount. Keyed only when both roots share
# one mount, the batch rule: a key on either root alone would let a
# dead workspace mount refuse a healthy project dir, or the reverse.
try:
proj_is_dir, workspace_is_dir = await _run_path_probe(_probe_fallback_roots)
proj_is_dir, workspace_is_dir = await _run_path_probe(
_probe_fallback_roots,
stall_path=_batch_stall_path([r for r in (proj, mc_workspace) if r]),
)
except _PathProbeBusy:
return _probe_busy_response(resource=proj, operation="file_search", caller=caller)
if proj_is_dir:
Expand Down Expand Up @@ -457,7 +463,9 @@ def _collect(kind: str, dirpath: str, names: list[str], root_dir: str) -> None:
# probe slot too: a walk into a dead mount would otherwise pin a
# default-executor worker exactly as an unbounded stat does.
try:
results = await _run_path_probe(_walk_file_search, transfer=True)
results = await _run_path_probe(
_walk_file_search, transfer=True, stall_path=_batch_stall_path(safe_roots)
)
except _PathProbeBusy:
return _probe_busy_response(resource=f"q={query}", operation="file_search", caller=caller)

Expand Down
2 changes: 1 addition & 1 deletion src/kiro_crew/dashboard/file_api/sheet.py
Original file line number Diff line number Diff line change
Expand Up @@ -303,7 +303,7 @@ def _open_and_load() -> dict | _OpenDenied:
return _load_sheet_payload(checked.file, max_bytes=_MAX_UPLOAD_BYTES)

try:
result = await _run_path_probe(_open_and_load, transfer=True)
result = await _run_path_probe(_open_and_load, transfer=True, stall_path=raw_path)
except asyncio.CancelledError:
# Shutdown or client disconnect: the access attempt must not vanish
# from the audit trail. No resource handling here -- the worker
Expand Down
8 changes: 7 additions & 1 deletion src/kiro_crew/dashboard/file_api/transfer.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
_PathProbeBusy,
_probe_busy_response,
_probe_request_path,
_project_relative_stall_path,
_resolve_project_relative,
_run_path_probe,
_sel,
Expand Down Expand Up @@ -208,7 +209,11 @@ async def api_file_download(request: web.Request) -> web.Response:
# api_file_read). Off-loop: the resolution is a pair of realpath calls.
if request.query.get("resolve") == "1":
try:
raw_path, _resolve_err = await _run_path_probe(_resolve_project_relative, raw_path)
raw_path, _resolve_err = await _run_path_probe(
_resolve_project_relative,
raw_path,
stall_path=_project_relative_stall_path(raw_path),
)
except _PathProbeBusy:
return _probe_busy_response(resource=raw_path, tool_name="file_download")
if _resolve_err == "cannot_resolve":
Expand Down Expand Up @@ -243,6 +248,7 @@ async def api_file_download(request: web.Request) -> web.Response:
_open_checked, raw_path, tool_name="file_download", max_bytes=_MAX_UPLOAD_BYTES
),
transfer=True,
stall_path=raw_path,
)
except _PathProbeBusy:
return _probe_busy_response(resource=raw_path, tool_name="file_download")
Expand Down
2 changes: 2 additions & 0 deletions src/kiro_crew/dashboard/handlers/files.py
Original file line number Diff line number Diff line change
Expand Up @@ -202,6 +202,7 @@
_validate_dashboard_path,
)
from kiro_crew.dashboard.file_api.pinned_io import ( # noqa: F401
_batch_stall_path,
_CheckedFile,
_classify_request_paths,
_file_write_blocking,
Expand All @@ -211,6 +212,7 @@
_OpenDenied,
_OpenedFile,
_OpenRefusal,
_project_relative_stall_path,
_read_request_path,
_resolve_project_relative,
_TextRead,
Expand Down
6 changes: 5 additions & 1 deletion src/kiro_crew/dashboard/handlers/office_slides.py
Original file line number Diff line number Diff line change
Expand Up @@ -1301,7 +1301,11 @@ async def _resolve_path(request: web.Request, tool_name: str) -> tuple[str, web.
raw_path = request.query.get("path", "")
if request.query.get("resolve") == "1":
try:
raw_path, err = await _files._run_path_probe(_files._resolve_project_relative, raw_path)
raw_path, err = await _files._run_path_probe(
_files._resolve_project_relative,
raw_path,
stall_path=_files._project_relative_stall_path(raw_path),
)
except _files._PathProbeBusy:
return raw_path, _files._probe_busy_response(resource=raw_path, tool_name=tool_name)
if err == "cannot_resolve":
Expand Down
4 changes: 3 additions & 1 deletion src/kiro_crew/dashboard/handlers/terminal.py
Original file line number Diff line number Diff line change
Expand Up @@ -595,7 +595,9 @@ async def api_terminal_ws(request: web.Request) -> web.WebSocketResponse | web.R
requested_cwd = request.query.get("cwd")
if requested_cwd:
cwd = await asyncio.wait_for(
_run_path_probe(_resolve_cwd, cfg, requested_cwd),
_run_path_probe(
_resolve_cwd, cfg, requested_cwd, stall_path=requested_cwd
),
timeout=_TERMINAL_CWD_TIMEOUT_S,
)
else:
Expand Down
3 changes: 2 additions & 1 deletion test/test_dashboard_files_composition_contract.py
Original file line number Diff line number Diff line change
Expand Up @@ -255,7 +255,8 @@
#: project-tree walk replaced the ``project_tree`` helpers.
#: Recaptured with the ``path_probe``, ``outbox``, ``channel_upload``, ``desktop`` and
#: ``editor`` owners, from the base file, where each of their names had the same shape.
_BASE_SHAPE_DIGEST = "65c4f9e11ec674f56489bb76f0c456811a262047983e711248ab01ad828beeca"
#: Recaptured when ``_run_path_probe`` gained its keyword-only ``stall_path``.
_BASE_SHAPE_DIGEST = "00b01a4e5eb247df7c73163e04a56f9bf00495f64187cd93a253fc958c3a9d8e"
#: Definitions that stay in the facade file: the seams the owners share -- the SEL
#: accessor, the file-send audit, the sub-agent session mapping and the request-body
#: error code -- the search walk's clock, the file viewer's owner-view verdict, whose
Expand Down
Loading
Loading