fix(runtime): land permission switches before the next turn's first tool call (#3349)

[chinawch007]

Summary

Fixes #3349

A permission switch (Auto→Bypass) was not observed by the next turn. Under Goal continuation the switch was rejected with session_busy — the quiescent mutation bailed eagerly whenever any execution claim existed, and claims are near-continuous while a Goal admits successor turns back to back. When a switch did commit mid-turn, tools still acted on a permissionMode frozen at backend build time, so the picker said Bypass while Bash stayed sandboxed and approvals kept prompting. The issue asks for one property in any session, not just Goals: a permission change is observed by the next turn that starts after it, before that turn's first tool call.

What changed

Kernel — execution serialization:

• New runSessionQueuedQuiescentMutation: a config change closes a per-session admission gate and waits for quiescence — every claim that predates the request has settled and no run is active — before its operation joins the mutation tail. The gate (not the tail) is what new claims observe, so admission mutations a running turn depends on — graph operator provisioning — still pass; waiting never holds a resource the waited-on execution needs, which keeps the queue deadlock-free. Claims only cover admission (a turn's claim settles at run bind), so runs are watched through hasActiveRuns; a run registers before its claim settles, leaving no instant where an in-flight admission is invisible.
• setPermissionMode, setExecutionBoundaryKind and transitionSessionConfiguration route through it. The eager hasActiveRuns rejections are gone — quiescence is now the kernel's single authority. The wait is scoped to the primary session; descendant activity is rejected at commit time (session_busy) instead of waited on, a truthful failure rather than a potential hang. waiting_for_user still rejects, now also when it appears mid-queue. Behavior change: a switch during an active turn waits (bounded by one turn) instead of rejecting.

Read model — the boundary as the single authority (#1611):

• ctx.permissionMode is derived live from the durable boundary at every tool dispatch (executionBoundaryDisplayMode plus the shared plan-mode downgrade), so a committed switch reaches the very next tool call without waiting for a backend rebuild; an external boundary falls back to the last known header mode.
• resolveCollaborationPermissionMode and executionBoundaryMatchesPermissionMode move to core, so the composer (build time) and the tool runtime (dispatch time) share one rule. The matcher now derives structurally: a read-only profile widened by an approved expansion no longer reads as explore, and a custom read-only profile is preserved instead of being reset.
• The catalog no-op short-circuit requires boundary consistency, so a header/boundary divergence is repaired instead of blessed; externally isolated sessions keep benign no-op updates on the header comparison.
• Revision guard: each backend generation records the boundary revision it was composed against; ensureActive rebuilds on drift — immediately when idle, or via the invalidation flush once live runs exit. Any write path that skips backend disposal self-heals within one activation.

How this meets the issue's stated goals

• "Observed by the next turn that starts after it, before that turn's first tool call" — the switch queues behind live execution, commits in the inter-turn gap, and turns admitted after the request wait at the admission gate until it commits; tools then read the boundary live on every call. Both facts the author named are covered at the dispatch site.
• Not Goal-specific — the fix is session-level. The reporter's plain-session case (switch between two ordinary turns, no Goal) is the primary regression test and asserts exactly what was asked: the successor turn's first tool call sees executionBoundary.kind === 'bypass' and ctx.permissionMode === 'bypass' together.
• Never silently drop a switch — return a truthful outcome — busy sessions delay the commit (bounded by one turn) instead of rejecting; a turn pausing on an interaction mid-queue rejects explicitly; descendants active at commit reject session_busy.
• The author's root-cause pointers are each addressed: the eager bail (replaced by queueing), the frozen permissionMode (live derivation), ensureActive reusing a stale generation (revision guard), and the catalog short-circuit that could bless a divergence (consistency check).

Verification

• Regression tests were written first and verified failing against the pre-change behavior: a gated turn with a mid-turn Auto→Bypass switch (queues, commits in the gap, next turn rebuilt from the committed mode), and the plain no-Goal session from the issue — the successor turn's first tool call sees executionBoundary.kind === 'bypass' and permissionMode === 'bypass' together, the reporter's primary case.

• A seeded interleaving sweep (100 iterations, fixed seed) alternates widening and narrowing switches across idle, mid-turn, and racing-the-release interleavings, asserting every turn started after a switch resolved observes the committed configuration.

• External review findings each carry their own regression test: the admission-gate deadlock interleaving, the widened read-only and external-boundary matcher cases, and the interaction-pause rejection.

• Not run: the full runtime-host suite and the remaining workspace suites, and manual Desktop verification of the picker.

• npm run format:check — clean (8 formatting nits auto-fixed and folded in)

• npm run lint — 2304 files, no issues

• npm run typecheck

• npm --workspace @maka/runtime run build — clean

• npm --workspace @maka/runtime run test:dist — 3110 tests, 3097 pass, 13 skip

Root cause

Three cooperating defects: the eager bail in runSessionQuiescentMutation, the build-time freeze of header.permissionMode into the tool context, and a catalog short-circuit that compared only header fields. The fix converges on the boundary as the single read model and moves quiescence authority into the kernel.

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: ZCode (Z.ai GLM) authored the implementation, tests, and review fixes; the contributor directed the design, reviewed each finding, and made the rebase decisions.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[Astro-Han]

Thanks for the careful admission-gate work and the unusually thorough race coverage. I found one security-timing gap at this exact head:

[P1] Apply permission reductions before waiting for the current turn to finish

runSessionQueuedQuiescentMutation closes admission for future claims but waits until hasActiveRuns(sessionId) is false before it runs the transition (packages/runtime/src/runtime-kernel.ts:578-587,664-703). The narrower boundary, shell-run termination, and backend disposal therefore do not begin until the current turn has fully ended (packages/runtime/src/session-manager.ts:1727-1789).

For a mid-turn Bypass→Auto/Explore request, the durable boundary remains bypass throughout that wait. ToolRuntime now correctly rereads the boundary per dispatch (packages/runtime/src/tool-runtime.ts:1326-1352), but every later tool call in that same turn still reads the old unrestricted boundary, and background shell authority is not terminated yet. This window is not usefully bounded in wall-clock time: the same dispatch path explicitly supports long-running installs, builds, training, and subagent loops, and a turn can issue multiple more tools.

The tests currently encode this gap: session-manager.test.ts:5164-5185 asserts the switch remains unsettled and the old boundary remains until turn 1 ends; the seeded sweep at :5498-5527 only verifies turns begun after the switch promise resolves. The per-dispatch test manually flips a fake boundary between calls, but the production transition cannot commit that flip while a run is active.

Please split widening from tightening. Delayed widening is a UX tradeoff, but tightening should establish a dispatch fence and revoke promptly—either stop the live turn or atomically install the narrower boundary so its next dispatch uses it, with the chosen contract also fencing already-running shell/subagent resources. An integrated Bypass→Ask/Explore regression should have the current turn attempt another write-capable/Bash dispatch after the user request but before terminal completion, and assert that it sees the narrower authority or that the turn was stopped. The successor-turn assertions should remain as a separate invariant.

[zhiiw]

Independent second lane at exact head 8ba7c4c907ec01e56035b0ee2e2742f1ec5d7417 (MERGEABLE). I read the mechanism before reading the existing review; converging on the same conclusion independently.

The existing [P1] is mechanically correct — confirmed by my own trace, not by reading it.

The tightening path: setPermissionMode → runSessionQueuedQuiescentMutation([sessionId], …) (session-manager.ts), which closes the admission gate immediately but runs the mutation — the durable boundary write included — only after quiescence (runtime-kernel.ts waitForSessionQuiescence loops on hasActiveRuns). So while the current turn is live, store.readExecutionBoundary still returns the old, wider boundary. ToolRuntime does re-read that store per dispatch (the new executionBoundaryDisplayMode derivation), but what it reads has not changed yet — the narrowing takes effect at the first dispatch after turn end, not after the user's request. The queueing machinery is direction-agnostic, so tightening inherits the same deferral as widening: session-manager.test.ts (Auto → Bypass requested mid-turn … the switch commits in the gap as soon as turn 1 settles) encodes this gap as the expected behavior, with expect((await store.readExecutionBoundary(session.id)).kind).toBe('managed') while the turn is still running.

The expensive parts the quiescence protects (backend disposal, descendant shell fencing) justify waiting — but the boundary write itself is a single store mutation, and the per-dispatch reread this PR added is precisely the mechanism that would let an early write take effect at the next tool call. Splitting "commit the narrower boundary now, dispose the old backend at quiescence" would close the window without destabilizing the running turn. Agree with the existing P1's framing: delayed widening is a UX tradeoff, delayed tightening is an authority window.

Checks note: the test check at this head is failure, but the failure is the ASF license-header gate — runtime-kernel-queued-quiescent-mutation.test.ts and tool-runtime-permission-mode.test.ts are missing headers, the job exits before running suites. So no test evidence exists on this head; the header gate failing early means the red X overstates what's known. npm run write:asf-headers should fix it.

No additional findings beyond the existing P1.

中文说明

独立复读了机制，既有 P1 成立：权限收窄请求进入排队静默 mutation，边界写入推迟到当前 turn 结束后的静默期；期间 ToolRuntime 虽然每次派发都重读边界，但读到的还是旧的宽边界。测试把这个窗口编码成了预期行为。另外这个 head 的 test 红是 ASF license header 门禁（两个新测试文件缺头文件注释），测试套件根本没跑——不是测试失败。