[aponcedeleonch]

Stage: Implementation. Implements the follow-ups agreed in the #1935 review (now merged).

What it does

• Refused-mode recovery reachable from mecatui. When mecatui --resume shows a pending approval that the server refuses because the session's stored mode is no longer admitted, shift+tab now switches to a lower mode. The server's refused_mode_recovery cancels the pending turn without running it, and the UI returns to an idle, usable session with the draft kept. A refused switch keeps the approval open and shows the server's reason. An approve or deny that the server refuses for this reason now names the recovery instead of the generic "could not be acknowledged" message. Gated on the refused_mode_recovery feature.

• Refused-mode recovery observable to watchers. After the recovery save, SetMode appends and publishes the same shape a live cancellation produces, stamped with the parked run's id: permission.retract for the ask, one cancellation tool.result per unanswered call, then result{cancelled}. Watchers and live subscribers no longer see an ask that stays open forever, and eventsource.Fold agrees with the snapshot. The close-out text comes from the new Session.InterruptCloseOuts, the same text the next run's Interrupt writes.

• A resumed auto subagent needs an enforcing checker. A persisted child stored in auto and resumed under a yolo parent kept auto but ran with advisory or no checking after a restart that removed the checker. A resume now runs the host's admission rule on the child's re-admitted mode (new agent.WithChildModeAdmission, wired to the same server.ModeAdmission the server applies to stored sessions). A refused resume is a tool error to the parent; the child doesn't run and its history is unchanged.

• Crash-orphaned running session in a refused mode. A session left running by a crash, under a mode the restarted server no longer admits, had no prompt recovery: StartRun refused before its crash-orphan repair, SetMode was illegal from running, CancelRun had no live run, and the stale sweep only applies after its threshold. SetMode now abandons the dead turn to idle (closing out unanswered tool calls, running nothing) and applies the mode in one save, under runEntryMu and the mutation lease with no registered run, the same proof StartRun's repair uses. A peer holding the lease keeps it refused, and the admission error for a running session names the recovery. Raised by @jhrozek on feat(permissions): one named permission-mode vocabulary and two admission gates #1935.

• ApprovePlan with an unspecified or unrecognized target denies. The proto documents PLAN/UNSPECIFIED target_mode as a deny, and HTTP already treats an empty or unknown target that way, but gRPC mapped UNSPECIFIED, and any out-of-range enum value, to default and approved the plan. Both now deny. Raised on feat(permissions): one named permission-mode vocabulary and two admission gates #1935.

• The stored-mode refusal has its own error code. admitStoredMode now refuses with session_mode_not_admitted (still FailedPrecondition / HTTP 412) instead of the generic failed_precondition. mecatui offers the shift+tab recovery only for that code, so another refusal on the verdict path (for example, an ask another client already answered) keeps the generic "changed or could not be acknowledged" message and no mode switch. The TypeScript SDK error-code list gains the code.

• Lease warnings. Build warns when a store other processes may share resolves no session lease, and a lease backend that reports leasing unsupported now downgrades at WARN instead of INFO. The storage-level gaps (no fencing token or aggregate version on Save) are out of scope.

• Tests. The unavailable-mode composer tests now execute the returned commands and assert exactly one transport send. TestPermissionModeTokenDerivesNoTrust seeds an AGENTS.md sentinel and checks whether it reaches the model, in addition to the trust narration. The resumed-subagent admission test runs for a no-FS parent too, and the mecatui client's SetMode state mapping is tested over real gRPC.

• Server CLI reference. user-docs/reference/server-cli.md is regenerated; it had drifted from the --permission-mode help text changed in feat(permissions): one named permission-mode vocabulary and two admission gates #1935.

API compatibility

Assessment: additive. No API major change.

• The refused-mode recovery and its refused_mode_recovery feature are unreleased (feat(permissions): one named permission-mode vocabulary and two admission gates #1935). This PR only appends existing event types (permission.retract, tool.result, result) with the existing run-id stamping on that feature-advertised path. Existing clients already handle all three for a run. No new event type, no field change. The feature and SetMode proto comments describe the events.
• A Subagent resume returns an error tool result only when the child's mode is one the server already refuses for stored sessions. No shapes change.
• SetMode on a stored running session left by a crash in a refused mode goes from InvalidArgument to success, within the same unreleased refused_mode_recovery feature. No shapes change; the feature, proto SetMode comment, and API-surface doc describe it.
• gRPC ApprovePlan with UNSPECIFIED or an unrecognized target_mode now denies instead of approving. This restores the documented proto contract and matches HTTP, so a conforming client is unaffected. The TypeScript SDK and mecatui always send an explicit, defined target.
• The stored-mode refusal's ErrorInfo reason changes from failed_precondition to the new stable code session_mode_not_admitted. The refusal is unreleased (not in v0.0.49), so no deployed client branches on the old reason; gRPC code and HTTP status are unchanged. Adding a code is a minor SDK change.
• mecatui consumes refused_mode_recovery; without it, shift+tab in the approval view does nothing, as before.

Go source: engine adds Session.InterruptCloseOuts and agent.WithChildModeAdmission (both Added, minor); see engine/CHANGELOG.md. Stored data: no schema change.

User-facing documentation: user-docs/mecatui/sessions.md (recover a pending approval), user-docs/mecatui/keybindings.md (shift+tab), user-docs/features/security-and-execution/permissions-and-posture.md, and the ApprovePlan rows in the gRPC and HTTP/SSE references.

Gates

• task lint: clean except the pre-existing darwin-only gosec finding in environment/microvm (untouched).
• task docs, task api:check, task generate (no drift): pass.
• task test:race: pass except tests that also fail on main on the author's macOS machine (socket paths, /private temp symlinks, git worktrees, microVM, kind fixtures). Run with provider keys unset and KUBECONFIG=/dev/null.
• go run ./cmd/mecademo: tool call, permission ask/approval, and result.
• Last three commits (error code, unrecognized target, tests): task lint, task docs, task generate, and the SDK typecheck/test/API/docs checks pass. Race tests of internal/adapter/server, internal/app, and cmd/mecatui/{client,ui} pass except eight macOS-only failures that reproduce without these commits. The full task test:race was not rerun for them.

🤖 Generated with Claude Code

[aponcedeleonch]

#1935 picked up jhrozek's review fixes, so this needs a rebase on the updated branch. Expect overlap in the mecatui header and /posture code and in internal/app permission-mode files.

Besides the existing commits, this PR should take:

• Crash-orphan recovery (review thread): when the lease proves a session left Running is orphaned, repair it to Idle without running before stored-mode admission, so SetMode can downgrade after a restart with a lower ceiling. Document it next to the awaiting/authorizing recovery cases.
• ApprovePlan with UNSPECIFIED approves while the proto says it denies (grpc_approveplan.go, same on main).

[aponcedeleonch]

Both follow-ups from the note above are in, and the branch is rebased on main.

• Crash-orphan recovery: 49e18aa. Once the lease proves no server drives the run, a switch to an admitted mode abandons the interrupted turn without running it. It's documented next to the awaiting/authorizing cases in docs/architecture/api-surface.md, the SetMode proto comment, and permissions-and-posture.md.
• ApprovePlan with UNSPECIFIED now denies, matching the proto: 0b64e32. e2832eb extends that to an unrecognized target mode.