Merge branch 'master' into fix/issue-790-slice-a-heartbeat-policy
Keep PR #794 current after master landed #863 (sanctioned restart controls). Preserves Slice A heartbeat conflict-gate remediation for review #544.
This commit is contained in:
@@ -0,0 +1,122 @@
|
||||
# Sanctioned restart and graceful reload controls (#642)
|
||||
|
||||
Sessions used to recover MCP connectivity by killing the host daemon
|
||||
(`pkill -f mcp_server.py`, #630). That is forbidden and stays forbidden: it
|
||||
kills every namespace on the host, contaminates whichever session survives, and
|
||||
leaves no audit trail. This document describes the sanctioned replacement,
|
||||
implemented in `webui/sanctioned_restart.py`.
|
||||
|
||||
## What the console will and will not do
|
||||
|
||||
The console **never** restarts anything. It authorizes an intent, records it,
|
||||
and hands off to a host supervisor. There is no code path in which the console
|
||||
sends a signal, spawns a process, or renders a kill command — a regression test
|
||||
asserts the module contains no `subprocess`, `signal`, `os.kill`, `os.system`,
|
||||
or `popen` reference, and that no returned payload contains a kill command.
|
||||
|
||||
## Operations
|
||||
|
||||
| Mode | Action | Minimum role | Behaviour |
|
||||
|------|--------|--------------|-----------|
|
||||
| `reload` | `system.reload_namespace` | controller | Host supervisor reloads the namespace in place, draining in-flight requests. |
|
||||
| `restart` | `system.restart_namespace` | admin | Host supervisor restarts the namespace. In-flight requests are lost. |
|
||||
|
||||
Scope is always exactly one namespace. A fleet-wide restart is an explicit
|
||||
non-goal: `all`, `*`, `fleet`, and an empty scope are refused with
|
||||
`fleet_scope_not_permitted`, because that is precisely the blast radius the
|
||||
forbidden kill already had. An unrecognised namespace is refused rather than
|
||||
passed through to the host.
|
||||
|
||||
## The gate sequence
|
||||
|
||||
`assess_restart_request()` applies every gate in order and reports the first
|
||||
failure with a stable reason code:
|
||||
|
||||
| Order | Gate | Reason code on failure |
|
||||
|-------|------|------------------------|
|
||||
| 1 | Mode is `restart` or `reload` | `unknown_mode` |
|
||||
| 2 | Scope is a single known namespace | `fleet_scope_not_permitted`, `unknown_namespace` |
|
||||
| 3 | Principal holds the required console role | `unauthorized` |
|
||||
| 4 | Confirmation phrase supplied | `confirmation_required` |
|
||||
| 5 | Confirmation names this namespace and mode | `confirmation_mismatch` |
|
||||
| 6 | Out-of-band operator authorization present | `operator_authorization_missing` |
|
||||
| 7 | Runtime is not contaminated | `contaminated_runtime` |
|
||||
| 8 | Host restart hook configured | `restart_hook_not_configured` |
|
||||
|
||||
Passing every gate yields `host_action_required`, never "restarted".
|
||||
|
||||
### Confirmation binds the namespace
|
||||
|
||||
The required phrase is `"<mode> <namespace>"` — for example
|
||||
`restart gitea-author`. Binding the namespace into the phrase is the point: a
|
||||
confirmation typed for one namespace cannot be replayed against another.
|
||||
|
||||
### Operator authorization is not self-assertable
|
||||
|
||||
Host daemon maintenance is authorized out of band through
|
||||
`GITEA_OPERATOR_DAEMON_MAINTENANCE_AUTHORIZATION`, read from the process
|
||||
environment and nowhere else (#630; #710 finding F1). A worker session cannot
|
||||
set an environment variable for an already-running daemon, so this cannot be
|
||||
faked the way a tool argument could.
|
||||
|
||||
### The host hook
|
||||
|
||||
`GITEA_SANCTIONED_RESTART_HOOK` holds an opaque reference the *host* resolves —
|
||||
a supervisor label such as a launchd job name, never a command line. With no
|
||||
hook configured the request is refused; the console does not fall back to a
|
||||
process kill. The value is read server-side and never rendered to a client.
|
||||
|
||||
## Manual kill remains contamination
|
||||
|
||||
`classify_restart_command()` classifies an operator-proposed recovery command.
|
||||
A manual `pkill`/`kill`/`killall` of the MCP daemon is contamination, not a
|
||||
restart: it returns `clean_claim_allowed: false` and builds a durable
|
||||
contamination marker (redacted command only, never secrets) naming
|
||||
`system.restart_namespace` as the sanctioned alternative.
|
||||
|
||||
A live, uncleared contamination marker also blocks a restart. This is stricter
|
||||
than #630's task-scoped gate, which deliberately lets a contaminated worker keep
|
||||
commenting and handing off: restarting a contaminated runtime would launder the
|
||||
contamination rather than resolve it. Clear the marker through the reconciler
|
||||
path first.
|
||||
|
||||
## Post-restart health verification
|
||||
|
||||
After the host supervisor acts, `verify_post_restart_health()` decides whether
|
||||
the session may claim to be clean:
|
||||
|
||||
| Status | Meaning | Clean claim |
|
||||
|--------|---------|-------------|
|
||||
| `clean` | Required tool callable, proven through the live client namespace | Allowed |
|
||||
| `unproven` | Reported healthy without live client-namespace evidence | Refused |
|
||||
| `unhealthy` | Probe failed | Refused |
|
||||
|
||||
Only `probe_source=client_namespace` evidence clears a session. Static tool
|
||||
registration is not proof, and neither is an offline subprocess probe — an IDE
|
||||
client can hold a registered tool list while live calls fail with
|
||||
`client is closing: EOF` (see
|
||||
[`mcp-namespace-health.md`](mcp-namespace-health.md)).
|
||||
|
||||
## Audit
|
||||
|
||||
Every attempt — allowed or denied — is recorded through
|
||||
`webui.console_audit` with actor, target namespace, mode, result, and reason
|
||||
code, and is redacted before it is persisted. `system.restart_namespace` is
|
||||
break-glass, so its records are retained for 730 days. Records carry
|
||||
`process_kill_executed: false`, which is a fact about the code path rather than
|
||||
a claim: no such path exists.
|
||||
|
||||
## Environment variables
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| `GITEA_SANCTIONED_RESTART_HOOK` | Host supervisor reference; absent means restart is refused. |
|
||||
| `GITEA_OPERATOR_DAEMON_MAINTENANCE_AUTHORIZATION` | Out-of-band operator authorization reference. |
|
||||
| `WEBUI_AUDIT_LOG` | Console audit sink; absent means records are built but not persisted. |
|
||||
|
||||
## Non-goals
|
||||
|
||||
* No unrestricted `kill` from the UI, in any role, in any phase.
|
||||
* No fleet-wide restart.
|
||||
* No silent auto-restart loop: every attempt is confirmed and audited.
|
||||
* This does not implement the Phase 1 health API (#634).
|
||||
@@ -91,6 +91,8 @@ already define, and a regression test asserts each mapping matches.
|
||||
| `close_pr` | controller | privileged | `gitea.pr.close` | Yes | No | No | 3 |
|
||||
| `merge_pr` | controller | privileged | `gitea.pr.merge` | Yes | **Yes** | **Yes** | 3 |
|
||||
| `delete_branch` | admin | destructive | `gitea.branch.delete` | Yes | **Yes** | **Yes** | 3 |
|
||||
| `system.reload_namespace` | controller | privileged | `runtime.reload_namespace` | Yes | No | No | 2 |
|
||||
| `system.restart_namespace` | admin | destructive | `runtime.restart_namespace` | Yes | **Yes** | **Yes** | 2 |
|
||||
|
||||
**Dual control** means the acting principal may not be the sole authority: a
|
||||
second distinct principal must confirm. **Break-glass** means the action is
|
||||
@@ -102,6 +104,13 @@ honouring it.
|
||||
`delete_branch` is admin-only rather than controller because it is the one
|
||||
irreversible action in the set.
|
||||
|
||||
`system.restart_namespace` is admin-only for the same reason: restarting a
|
||||
namespace drops every in-flight request on it. `system.reload_namespace` drains
|
||||
first, so it is privileged but not destructive. Neither action is ever executed
|
||||
by the console — both hand off to a host supervisor, and neither exposes a raw
|
||||
process kill. See
|
||||
[`sanctioned-restart-controls.md`](sanctioned-restart-controls.md) (#642).
|
||||
|
||||
### Authorization decision
|
||||
|
||||
`authorize(action_id, principal, for_execution=False)` returns a decision
|
||||
@@ -199,8 +208,8 @@ breaking the request it describes.
|
||||
| Class | Applies to | Default |
|
||||
|-------|-----------|---------|
|
||||
| `standard` | Routine gated writes | 90 days |
|
||||
| `privileged` | `review_pr`, `close_pr`, and any unclassifiable action | 365 days |
|
||||
| `break_glass` | `merge_pr`, `delete_branch` | 730 days |
|
||||
| `privileged` | `review_pr`, `close_pr`, `system.reload_namespace`, and any unclassifiable action | 365 days |
|
||||
| `break_glass` | `merge_pr`, `delete_branch`, `system.restart_namespace` | 730 days |
|
||||
|
||||
Each record carries its own class, day count, and computed `expires_at`, so
|
||||
retention is auditable per record rather than inferred from file age. An
|
||||
|
||||
Reference in New Issue
Block a user