Skip to content

feat(remote-session): POSIX path rules for remote workspaces on Windows - #23498

Merged
bolichen97 merged 1 commit into
mainfrom
feat/windows-remote-workspace-posix-paths
Oct 23, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
feat/windows-remote-workspace-posix-paths

Conversation

@kyleseaman

@kyleseaman kyleseaman commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Remote session workspaces can run on a Windows gateway, with governance file rules still binding the workspace's files.

Today a Windows gateway refuses every remote workspace (REMOTE_NEEDS_POSIX_GATEWAY, from #19833). The refusal exists because governance's path matcher normalizes every queried path with the gateway's own os.path. On Windows that turns a Linux guest's /workspace/app/x into C:\workspace\app\x, so a deny written for /workspace/app/** would never match a workspace tool's target. A Windows user cannot use Session Environments at all.

Why it matters

Windows is a supported gateway OS. Without this, the remote-workspace preview is unavailable to every Windows operator. Lifting the refusal without fixing the matching would be a silent governance bypass, because file denies would stop binding remote targets.

Not a goal

  • Changing how local (non-remote) paths are matched on any OS.
  • Changing pattern expansion: ~ and $VAR in an operator's patterns still mean the gateway's values.
  • Governing run_command's cwd, or the contents a directory-scoped list_directory, glob or grep returns. Both match local execute_bash and the local tools today.
  • Credentialed git lending on Windows, which still refuses until feat: add credentialed git for remote sessions #21256. No git code is touched.
  • Taking Session Environments out of the KIROCREW_DEV_MODE developer preview.

What changed (motivation → approach → change)

Root cause → approach: the matcher needs to know, per call, that a target names a guest file. That fact must come from the gateway's own state, never from anything the model or guest sends.

  • Tag: build_permission_event (acp/_dispatch_parts/permission_requests.py) tags a call's arguments with a GuestPathParams Python type carrying the guest workdir (platform/guest_paths.py). It does so only in the branch reached when the runtime's own remote-workspace binding (set_remote_workspace, passed in by session_handle_permissions.py) attached the workspace server, and only for a trusted identity naming a known workspace tool.
  • Not forgeable: a type cannot be produced from JSON. Any GuestPathParams that reaches the builder another way is stripped back to a plain dict.
  • Unplaced remote calls: on a remote session, a call the builder cannot place for certain (an untrusted identity, or a workspace tool it does not know) is tagged also_local. It must pass every rule under both the guest and gateway readings.
  • Classification: classify_tool_args (governance_parts/tool_calls.py) emits each target of a tagged call as a GuestPath.
    • _match_path normalizes a GuestPath with posixpath (guest_norm). A relative path is anchored at the guest workdir, never the gateway's CWD. .. and a leading // collapse. Nothing is case-folded, and ~/$VAR are never expanded with the gateway's values. The guest tool server expands neither, and a test pins that.
    • A target with $, a ~ segment or a backslash is still checked against denies as the literal path the guest opens. It also adds a never-permittable item, so an allow-mode confinement refuses it.
    • GuestPath compares and hashes apart from a plain str, so gate_decision's dedupe can never keep a plain twin in its place.
  • Titles: gate_decision reads a Reading <path> title on a tagged call as the guest's path.
  • Diff paths: edit_target_candidates anchors a remote diff-block path with posixpath.isabs. On Python 3.13, Windows' ntpath.isabs("/x") is False, which would otherwise refuse those edits.
  • Refusal retired: check_remote_workspace_supported no longer refuses on Windows, and REMOTE_NEEDS_POSIX_GATEWAY and gateway_matches_posix_paths are removed.
  • Docs: governance.md gains a "Path matcher — remote-workspace targets" section, and providers.md is updated.

Alternative considered: carrying a posix_paths flag on AcpEvent → ToolCall → gate_tiers → _governance_denial → gate_decision. That threads the same fact explicitly, but it edits three Sensitive Change Review-watched files (hook_runtime/*). The type travels the same path by reference with no watched edit. A spy test, the product-path tests, and a fresh-context reviewer's trace of every gate site confirm nothing copies it in between.

No SCR-watched file is touched (checked against SENSITIVE_GLOBS). No dependency is added. This is not a product-shape change: no default or capability changes, and a refusal of an unsupported OS is lifted only once the feature works there.

Worst case if wrong: if the tag were lost between the builder and the matcher, a remote call on Windows would get the gateway reading, and a guest-path deny would miss for it (fail-open). If the tag were forged on a local call, a C:\... deny could miss. Tests cover both. How to undo: revert this PR, which restores the Windows refusal and the gateway-only reading.

Backwards compatibility

Compatible: local matching is unchanged on every OS. On a POSIX gateway, a remote call's absolute targets match exactly as before (parity test). The only differences are stricter: no gateway-env expansion inside guest targets, relative nested paths anchored at the guest, and allow-mode refusal of $, ~ and backslash spellings. A remote attach that was refused now succeeds.

Reader: src/kiro_crew/acp/runtime_remote_workspace.py:check_remote_workspace_supported -- chat -- the only production reader of REMOTE_NEEDS_POSIX_GATEWAY / gateway_matches_posix_paths; both reads are removed with them here
Reader: test/test_remote_session_launch.py:test_remote_workspace_needs_a_gateway_whose_path_rules_match_posix -- release -- test of the removed refusal, deleted; replaced by test_a_remote_workspace_attaches_on_any_gateway_os
Reader: test/test_remote_session_local_only_tools.py:posix_gateway -- release -- skip marker naming the removed refusal, deleted; its tests now run on Windows with guest paths

Tests

test/test_remote_workspace_guest_paths.py runs on every OS, including the Windows shards. It goes through the real product path (KAS permission frame → build_permission_event → ToolCall.from_event → HookManager.on_tool_call). Each test runs under this OS's reading and under a Windows reading simulated through the governance facade:

  • remote denies on /workspace/app/** bind .. escapes, // and /// prefixes, mixed separators and case variants for every workspace file tool; paths the guest opens elsewhere stay unbound;
  • allow confinement holds against .. escapes;
  • unexpanded ~, $HOME, ${HOME} and $VAR fail closed under allow, and are never expanded with the gateway's values;
  • forged markers on a local session keep the Windows reading and stay denied by a C:\... deny;
  • a stray tagged object on a local call is stripped;
  • a remote call cannot satisfy a gateway allow with a C:\ or UNC spelling;
  • unplaced remote calls must pass both readings;
  • Reading titles are read as the guest's path;
  • remote diff-path anchoring works;
  • local Windows matching is unchanged, plus a real-Windows-only case;
  • POSIX parity holds;
  • a remote workspace attaches with nothing patched;
  • the tag reaches gate_decision intact (spy).

test_remote_session_local_only_tools.py drops its posix_gateway skips and uses guest paths, so those tests run on Windows too.

Proof: each new guard was mutation-checked by removing it and re-running the tests:

  • the builder tag → 65 fail;
  • the dual reading → 4 fail;
  • the title rewrite → 1 fails;
  • diff anchoring → 2 fail;
  • the local strip → 1 fails.

Locally on the head: Backend Lint 15/15, Fast Gate 29/29, and 10,765 scoped tests passed (governance, hooks, tool_paths, remote session, dispatch, facades). The one failure, test_this_repo_s_real_primary_branch_is_allowlisted, reads this checkout's origin/HEAD and is a host artifact.

Manual verification

N/A — unit coverage is sufficient. The product-path tests drive the real permission builder and gate under both path flavours. A live Windows gateway with a Coder workspace was not run, and the Windows CI shards cover the Windows reading. A fresh-context GPT security review traced every gate site. It found no blocker, and its four minor findings are fixed in this PR.

Related Issues

Follows #19833. Git lending on Windows is #21256.

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

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@kyleseaman
kyleseaman requested review from a team and KiroCrewCaptain as code owners October 23, 2026 16:22
@kyleseaman
kyleseaman requested a review from mbriones98 October 23, 2026 16:22
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 23, 2026
@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 259a32ecd8dfb4541042e2c566040c20608a05b6 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 23, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 259a32ecd8dfb4541042e2c566040c20608a05b6 — 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. The PR removes the Windows refusal itself and fixes the reason that refusal gave ("a filesystem deny could not bind the workspace tools' POSIX targets"). The two leftovers are re-exports with no callers.

Notes

  • Item 9 — zero consumers: governance.py re-exports GuestPath, guest_also_local, guest_norm, guest_root, guest_unverifiable. I grepped src/ and test/ for those five names and found 0 callers through the facade; the new test imports them from platform.guest_paths. Subtraction: delete the from kiro_crew.platform.guest_paths import (...) # noqa: F401 - re-export block in governance.py.
  • Item 10 — zero consumers: _dispatch.py adds from kiro_crew.platform.guest_paths import GuestPathParams # noqa: F401. A grep for _dispatch.GuestPathParams found 0 uses; permission_requests.py imports it directly. Subtraction: delete that import line.

What this change ships

Inventory (10 items) — 8 justified

Intent: let an operator on a Windows gateway attach a dev-preview remote workspace while file deny/allow rules still apply to the guest's paths. This is an ADDITION.

  1. Remote workspaces now attach on a Windows gateway (the REMOTE_NEEDS_POSIX_GATEWAY refusal is gone) — justified
  2. Workspace tool targets are matched as the guest's POSIX paths on any gateway OS — justified
  3. Relative guest targets are anchored at the guest workdir, never the gateway's CWD — justified
  4. Under an allow-list, guest targets containing $, ~ or a backslash are now refused — justified
  5. Remote calls the builder can't place must pass every rule under both readings — justified
  6. A Reading <path> title on a remote call is read as a guest path — justified
  7. A remote diff-block path counts as absolute only by POSIX rules — justified
  8. A tagged-params object reaching a local call is turned back into a plain dict — justified
  9. Governance facade re-exports five guest-path helpers — zero consumers
  10. _dispatch facade re-exports GuestPathParams — zero consumers

[FIRST-PRINCIPLES-REVIEWED] 259a32e

Description read

[DESCRIPTION-READ] e532dc0e39bdcfad04f4cb1ba063624de35f647eda1d936fad0c581f2603f9e1

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks. The guest-path tag is set only by the runtime's own workspace binding, unplaced calls get both readings, and the change is behind dev mode and reverts cleanly.

Notes

  • The description has no ## Backwards compatibility section. It removes REMOTE_NEEDS_POSIX_GATEWAY and gateway_matches_posix_paths, and nothing in the tree still reads them, so they should be listed as Removes nothing: <why> rather than left out.
  • Fail-open hinges on raw_params reaching the matcher by reference (tool_identity.py:217/242). Any later dict(...) copy or JSON round-trip on that path silently drops the guest flavour on Windows. A one-line comment at those sites saying the type is load-bearing would keep it from being "simplified" away.

[DESIGN-REVIEWED] 259a32e

Description read

[DESCRIPTION-READ] 5fd030b52832e1d4a613445ee0c913c882b993fde39b231f776e2c1e9a7558ed

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.

…teway

Governance file rules now match a remote workspace tool's targets as the
Linux guest's POSIX paths, chosen per call. build_permission_event tags the
call's arguments with a GuestPathParams type only on a runtime whose own
remote-workspace binding attached the workspace server, for a trusted
identity; a stray tag on a local call is stripped. Tagged targets are
normalized with posixpath (anchored at the guest workdir, .. and leading //
collapsed, no ~/$VAR expansion); $/~/backslash spellings also refuse under
allow-mode. Unplaced remote calls must pass both readings. Local calls keep
the gateway's os.path reading unchanged.

This lets a Windows gateway attach a remote workspace, so the blanket
REMOTE_NEEDS_POSIX_GATEWAY refusal is retired.
@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 259a32ecd8dfb4541042e2c566040c20608a05b6 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.

[GPT-REVIEWED] 259a32e

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

@github-actions

github-actions Bot commented Oct 23, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 259a32ecd8dfb4541042e2c566040c20608a05b6 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 259a32e

Verdict parsed from the review's SHA-scoped output markers for commit 259a32ecd8dfb4541042e2c566040c20608a05b6.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 259a32ecd8dfb4541042e2c566040c20608a05b6: <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 23, 2026
@kyleseaman
kyleseaman force-pushed the feat/windows-remote-workspace-posix-paths branch from 1efdaa3 to 259a32e Compare October 23, 2026 16:46
@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 Oct 23, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) October 23, 2026 20:05

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

Reviewed current head 259a32ecd8dfb4541042e2c566040c20608a05b6 as Tier 2. Deep review found no blocking issue.

Security check: trusted remote workspaces use typed POSIX guest paths. Unknown origins must pass both guest and gateway rules. Unverifiable allow paths fail closed. Auto-merge remains subject to branch protection.

@bolichen97
bolichen97 merged commit dc18253 into main Oct 23, 2026
118 of 127 checks passed
@bolichen97
bolichen97 deleted the feat/windows-remote-workspace-posix-paths branch October 23, 2026 20:06
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 23, 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.

2 participants