Expose sanctioned MCP reconnect action to Codex workflow sessions #678

New Issue

2026-07-11T20:14:31-05:00

jcwalker3 commented

2026-07-11 20:14:31 -05:00

Problem

Codex sessions can detect stale or closed Gitea MCP runtimes, but the sanctioned client reconnect/reload action is not exposed as a callable tool. When gitea_resolve_task_capability returns stop_required=true / restart_required=true, Codex must stop and ask the operator to reconnect manually. This blocks reconciliation, review, and cleanup workflows even when the correct safe action is known.

Observed

Task: verify PR #677 / Issue #671 cleanup.
Required profile: prgs-reconciler.
Resolver required reconnect/restart.
Codex searched available tools and found health checks but no reconnect/reload/relaunch/respawn action.
No mutation occurred because shell/process/config/session-state workarounds are forbidden.

Forbidden recovery paths (do not suggest)

Workflows must not recover via:

pkill / kill
touch (including mtime-based config reload hacks)
.env edits
config edits
session-state edits
raw API calls

Related guardrail: #630 (block manual MCP daemon process killing as workflow recovery).

Required behavior

Provide one of:

A sanctioned MCP reconnect/reload action callable from Codex for a named MCP namespace, or
An explicit operator-only recovery path documented as a typed blocker with exact UI steps.

The reconnect action (if exposed) must reconnect the selected MCP namespace without any of the forbidden paths above.

After reconnect, workflows must restart from identity / runtime / capability preflight (gitea_whoami → gitea_resolve_task_capability → task).

Expected reconnect result fields

When reconnect is exposed, the result should report at least:

Field	Description
`namespace`	MCP namespace reconnected
`profile`	Active execution profile
`pid` / session	Process or session id if available
`startup_sha`	SHA the runtime started on
`current_master_sha`	Current master head
`boundary_status`	Clean / mismatch / stale

Typed blocker (if reconnect is not exposed)

If no callable reconnect exists, the workflow must return a typed blocker that includes:

Namespace(s) needing reconnect
Why reconnect is required (stale-runtime, transport EOF, missing namespace, etc.)
Exact operator UI steps (client-specific: Codex MCP reload / reconnect control)
Instruction to restart the workflow from preflight after reconnect
Explicit ban on process kill / touch / config / session-state hacks

Acceptance criteria

Codex can invoke or request a sanctioned reconnect for a named MCP namespace.
Reconnect result reports namespace, profile, PID/session if available, startup SHA, current master SHA, and boundary status.
If reconnect is not exposed, the workflow returns a typed blocker with exact operator UI steps.
Tests/docs cover:
- stale runtime
- transport EOF
- missing namespace
- successful reconnect
No workflow suggests process killing or mtime/config hacks as recovery.

Related issues

#584 — Transport closed; host auto-reconnect at session startup
#610 — Capability resolver vs master parity on stale runtime
#630 — Block manual MCP daemon process killing as recovery
#642 — Web Console: Sanctioned restart and graceful reload controls
#655 — Umbrella: Governed MCP restart coordination
#669 — Replace full-server MCP resets with scoped component recovery
#671 / #677 — stable-branch push guard (triggering task context)

Notes

Distinct from web-console restart (#642): this issue is about the Codex client surface exposing a safe reconnect that agents can invoke or request without operator shell workarounds.
Prefer client-layer reconnect/reload over daemon process management.
Health/read-only checks alone are insufficient when stop_required / restart_required is true.

## Problem Codex sessions can detect stale or closed Gitea MCP runtimes, but the **sanctioned client reconnect/reload action is not exposed as a callable tool**. When `gitea_resolve_task_capability` returns `stop_required=true` / `restart_required=true`, Codex must stop and ask the operator to reconnect manually. This blocks reconciliation, review, and cleanup workflows even when the correct safe action is known. ## Observed * **Task:** verify PR #677 / Issue #671 cleanup. * **Required profile:** `prgs-reconciler`. * Resolver required reconnect/restart. * Codex searched available tools and found health checks but **no reconnect/reload/relaunch/respawn action**. * No mutation occurred because shell/process/config/session-state workarounds are forbidden. ### Forbidden recovery paths (do not suggest) Workflows must **not** recover via: * `pkill` / `kill` * `touch` (including mtime-based config reload hacks) * `.env` edits * config edits * session-state edits * raw API calls Related guardrail: #630 (block manual MCP daemon process killing as workflow recovery). ## Required behavior Provide **one** of: 1. A **sanctioned MCP reconnect/reload action** callable from Codex for a named MCP namespace, **or** 2. An **explicit operator-only recovery path** documented as a typed blocker with exact UI steps. The reconnect action (if exposed) must reconnect the selected MCP namespace without any of the forbidden paths above. After reconnect, workflows must restart from **identity / runtime / capability preflight** (`gitea_whoami` → `gitea_resolve_task_capability` → task). ### Expected reconnect result fields When reconnect is exposed, the result should report at least: | Field | Description | |---|---| | `namespace` | MCP namespace reconnected | | `profile` | Active execution profile | | `pid` / session | Process or session id if available | | `startup_sha` | SHA the runtime started on | | `current_master_sha` | Current master head | | `boundary_status` | Clean / mismatch / stale | ### Typed blocker (if reconnect is not exposed) If no callable reconnect exists, the workflow must return a **typed blocker** that includes: * Namespace(s) needing reconnect * Why reconnect is required (`stale-runtime`, transport EOF, missing namespace, etc.) * Exact operator UI steps (client-specific: Codex MCP reload / reconnect control) * Instruction to restart the workflow from preflight after reconnect * Explicit ban on process kill / touch / config / session-state hacks ## Acceptance criteria 1. Codex can **invoke or request** a sanctioned reconnect for a named MCP namespace. 2. Reconnect result reports namespace, profile, PID/session if available, startup SHA, current master SHA, and boundary status. 3. If reconnect is not exposed, the workflow returns a **typed blocker** with exact operator UI steps. 4. Tests/docs cover: * stale runtime * transport EOF * missing namespace * successful reconnect 5. No workflow suggests process killing or mtime/config hacks as recovery. ## Related issues * #584 — Transport closed; host auto-reconnect at session startup * #610 — Capability resolver vs master parity on stale runtime * #630 — Block manual MCP daemon process killing as recovery * #642 — Web Console: Sanctioned restart and graceful reload controls * #655 — Umbrella: Governed MCP restart coordination * #669 — Replace full-server MCP resets with scoped component recovery * #671 / #677 — stable-branch push guard (triggering task context) ## Notes * Distinct from web-console restart (#642): this issue is about the **Codex client surface** exposing a safe reconnect that agents can invoke or request without operator shell workarounds. * Prefer client-layer reconnect/reload over daemon process management. * Health/read-only checks alone are insufficient when `stop_required` / `restart_required` is true.