fix(runtime): recognize client identity environment and refresh worker registrations #976

2026-07-29T20:08:51-05:00

jcwalker3 commented

2026-07-29 20:08:51 -05:00

Closes #975

Head SHA under review: 1a38ef95e3119512d41e2b230c1f389b9821331e

What was broken

Two defects in the #948 client/session ownership lifecycle. They are inseparable:
repairing either alone still leaves sanctioned multi-client operation impossible.

1. Client-identity environment keys were not recognized

gitea_mcp_server reads GITEA_MCP_CLIENT, GITEA_MCP_CLIENT_INSTANCE and
GITEA_MCP_CLIENT_SESSION as the authoritative client-identity inputs for worker
registration. None of the three appeared in
gitea_config.RECOGNIZED_GITEA_ENV_KEYS, and none matched
RECOGNIZED_GITEA_ENV_PREFIXES.

The runtime diagnostic scans every peer mcp_server.py process environment and
classifies any unlisted GITEA_* key as an unsupported override. That reason is
raised as a runtime blocker, so gitea_resolve_task_capability returned
blocker_kind=runtime_reconnect_required, restart_required=true,
stop_required=true. Because that resolver is the mandatory preflight for every
author, reviewer and merger mutation, setting the very variable #948 requires for
client identity closed the mutation gate for the whole fleet. Reconnecting could
not clear it: the variable is re-exported from the client's server definition on
every launch. It was reached with the server in full parity.

2. `WorkerRegistry.heartbeat()` had no production caller

#948 delivered heartbeat(), but only tests called it. The single production
writer registers once per process behind an attempted-once flag, and
register() stamps one timestamp into both started_at and
last_heartbeat_at. Nothing advanced it afterwards — no lifespan hook, no
background task, no atexit handler in a process that blocks in mcp.run(...).

Since liveness is now - last_heartbeat_at against heartbeat_ttl_seconds
(900.0), that TTL was never a liveness window in production. It was a hard cap on
how long any client could stay attached: at 900 seconds a healthy, connected,
client-managed process became session_ownership: unowned /
blocker_kind: session_attachment_missing and could no longer mutate.

Observed on a live author namespace at control revision 324a0c8a:
started_at and last_heartbeat_at were byte-identical, with
heartbeat_ttl_seconds: 900.0.

What changed

gitea_config.py — the three client-identity keys are named individually in
the recognized-key set. No prefix is added, so an unrecognized GITEA_* override
is still refused exactly as before.

gitea_mcp_server.py — a second inconsistency in the same path: the
diagnostic reasons are raised as one RuntimeError, but the preflight re-raise
recognized only "stale-runtime:", so an "unsupported-env:" reason was
silently swallowed there while still failing the resolver. Both reason families
now live in RUNTIME_DIAGNOSTIC_HARD_PREFIXES, declared beside the function that
produces them, and both propagate identically. This only widens what is refused,
never what is permitted. The module also starts the heartbeat supervisor from
_active_worker_identity() at the moment register() succeeds — the only point
where identity and fencing_epoch are both known — and surfaces
worker_heartbeat read-only on gitea_get_runtime_context.

mcp_worker_identity.py — WorkerHeartbeatSupervisor is the missing caller.

Heartbeat lifecycle design

A daemon thread, not an asyncio task and not request-driven refresh:

Renewal must survive an idle session. A request-driven refresh cannot renew
while no tool is called, so it cannot satisfy the objective.
Registration happens lazily inside a tool call on the server's event loop, and
the registry performs blocking BEGIN IMMEDIATE sqlite writes with a 30s
timeout, which must not run on that loop.
daemon=True is deliberate: a hard kill takes the thread with it, so a dead
worker still goes stale on the normal TTL.

heartbeat_interval_for(ttl) returns ttl / 3 (300s at the 900s default),
hard-capped at ttl / 2. Two consecutive beats can be lost without the row
expiring, and no override can produce an interval that outlives the registration
it exists to renew.

heartbeat() gains optional keyword-only expectations — expected_session_id,
expected_generation_id, expected_client_name, expected_pid. Each supplied
one must match the recorded row or the renewal is refused with the existing
BLOCKER_FENCED literal; no new blocker_kind value is invented, because
consumers switch on that value. Omitting them preserves the pre-existing
behavior exactly. Client names are compared normalized, so several namespaces of
one application stay one client while separate applications stay distinct.

A terminal refusal (fenced, or no registration) stops the supervisor permanently
and records why, so a fenced session can never beat its way back into ownership.
A transient failure is counted and beating continues, staying observable. An
atexit hook stops it on orderly shutdown.

claim_generation() still has no production caller. It bumps fencing_epoch,
which would fence the supervisor's cached epoch. The strict refusal is left in
place deliberately and documented: auto-re-adopting a bumped epoch would defeat
fencing.

Scope guarantees

No lock or lease TTL is changed, including the author issue-lock TTL.
No mutation refused today becomes permitted.
Provenance, parity, role, repository and mutation gates keep current behavior.
The heartbeat thread is not started under pytest; tests drive the supervisor
directly with an injected clock, so the suite leaves no background sqlite
writers behind.
#963 is not closed and not modified. This unblocks it and nothing more.
The canary was not started.

Files changed

File	Lines
`gitea_config.py`	+10
`gitea_mcp_server.py`	+115 / −2
`mcp_worker_identity.py`	+386
`tests/test_issue_975_client_identity_heartbeat.py`	+759 (new)

Test results

Focused, from inside the branches worktree:

tests/test_issue_975_client_identity_heartbeat.py
40 passed, 15 subtests passed in 2.42s

Adjacent suites for every touched surface:

tests/test_issue_948_client_session_provenance.py
tests/test_issue_973_cross_repo_canonical_roots.py
tests/test_issue_973_b10_mode_contract.py
tests/test_issue_686_manual_mcp_provenance.py
114 passed, 39 subtests passed in 14.67s

Full suite, both runs from a branches/ worktree because baselines here are
location-sensitive:

baseline  (branches/baseline-975-324a0c8a @ 324a0c8a)
  28 failed, 6065 passed, 6 skipped, 1090 subtests passed in 212.49s

branch    (branches/issue-975-client-identity-heartbeat @ 1a38ef95)
  28 failed, 6105 passed, 6 skipped, 1105 subtests passed in 212.54s

The two failure sets were diffed and are identical: zero new failures, zero
pre-existing failures fixed. The delta is exactly the 40 added tests and 15
added subtests. The 28 failures are the known pre-existing baseline at this
control revision.

All 13 acceptance criteria are covered. Every TTL assertion uses an injected
clock — no test waits for a real TTL. The two thread-loop tests use a
millisecond-scale interval with bounded polling.

Handoff

STATE: ready-for-review
WHO_IS_NEXT: reviewer
HEAD_SHA: 1a38ef95e3119512d41e2b230c1f389b9821331e
BRANCH: fix/issue-975-client-identity-heartbeat
BASE: master
NEXT_ACTION: Independent reviewer verifies this PR at exact head 1a38ef95e3119512d41e2b230c1f389b9821331e
NEXT_PROMPT:
Role: REVIEWER
Repo: prgs / Scaled-Tech-Consulting / Gitea-Tools
PR: this PR
Issue: #975

1. Native MCP only on prgs-reviewer; bind a branches/ worktree at exact head 1a38ef95e3119512d41e2b230c1f389b9821331e.
2. Verify the three client-identity keys are recognized individually and that no prefix was added, so an unknown GITEA_* override is still refused.
3. Verify the unsupported-env reason now propagates through the preflight re-raise, and that this only widens refusal.
4. Verify the heartbeat renews only the exact current worker: wrong session, wrong generation, wrong client name and wrong pid must each be refused with BLOCKER_FENCED.
5. Verify a fenced or missing registration stops the supervisor permanently, that orderly shutdown stops it, and that a stopped worker still expires on the configured TTL.
6. Re-run the focused suite and the full suite from a branches/ worktree and confirm the failure set matches the 324a0c8a baseline.
7. Confirm no lock or lease TTL changed, #963 stayed open and unmodified, and the canary was not started.

Author did not approve or merge this PR.

Closes #975 Head SHA under review: `1a38ef95e3119512d41e2b230c1f389b9821331e` ## What was broken Two defects in the #948 client/session ownership lifecycle. They are inseparable: repairing either alone still leaves sanctioned multi-client operation impossible. ### 1. Client-identity environment keys were not recognized `gitea_mcp_server` reads `GITEA_MCP_CLIENT`, `GITEA_MCP_CLIENT_INSTANCE` and `GITEA_MCP_CLIENT_SESSION` as the authoritative client-identity inputs for worker registration. None of the three appeared in `gitea_config.RECOGNIZED_GITEA_ENV_KEYS`, and none matched `RECOGNIZED_GITEA_ENV_PREFIXES`. The runtime diagnostic scans every peer `mcp_server.py` process environment and classifies any unlisted `GITEA_*` key as an unsupported override. That reason is raised as a runtime blocker, so `gitea_resolve_task_capability` returned `blocker_kind=runtime_reconnect_required`, `restart_required=true`, `stop_required=true`. Because that resolver is the mandatory preflight for every author, reviewer and merger mutation, setting the very variable #948 requires for client identity closed the mutation gate for the whole fleet. Reconnecting could not clear it: the variable is re-exported from the client's server definition on every launch. It was reached with the server in full parity. ### 2. `WorkerRegistry.heartbeat()` had no production caller #948 delivered `heartbeat()`, but only tests called it. The single production writer registers once per process behind an attempted-once flag, and `register()` stamps one timestamp into both `started_at` and `last_heartbeat_at`. Nothing advanced it afterwards — no lifespan hook, no background task, no `atexit` handler in a process that blocks in `mcp.run(...)`. Since liveness is `now - last_heartbeat_at` against `heartbeat_ttl_seconds` (900.0), that TTL was never a liveness window in production. It was a hard cap on how long any client could stay attached: at 900 seconds a healthy, connected, client-managed process became `session_ownership: unowned` / `blocker_kind: session_attachment_missing` and could no longer mutate. Observed on a live author namespace at control revision `324a0c8a`: `started_at` and `last_heartbeat_at` were byte-identical, with `heartbeat_ttl_seconds: 900.0`. ## What changed **`gitea_config.py`** — the three client-identity keys are named individually in the recognized-key set. No prefix is added, so an unrecognized `GITEA_*` override is still refused exactly as before. **`gitea_mcp_server.py`** — a second inconsistency in the same path: the diagnostic reasons are raised as one `RuntimeError`, but the preflight re-raise recognized only `"stale-runtime:"`, so an `"unsupported-env:"` reason was silently swallowed there while still failing the resolver. Both reason families now live in `RUNTIME_DIAGNOSTIC_HARD_PREFIXES`, declared beside the function that produces them, and both propagate identically. This only widens what is refused, never what is permitted. The module also starts the heartbeat supervisor from `_active_worker_identity()` at the moment `register()` succeeds — the only point where identity and `fencing_epoch` are both known — and surfaces `worker_heartbeat` read-only on `gitea_get_runtime_context`. **`mcp_worker_identity.py`** — `WorkerHeartbeatSupervisor` is the missing caller. ## Heartbeat lifecycle design A daemon thread, not an asyncio task and not request-driven refresh: - Renewal must survive an **idle** session. A request-driven refresh cannot renew while no tool is called, so it cannot satisfy the objective. - Registration happens lazily inside a tool call on the server's event loop, and the registry performs blocking `BEGIN IMMEDIATE` sqlite writes with a 30s timeout, which must not run on that loop. - `daemon=True` is deliberate: a hard kill takes the thread with it, so a dead worker still goes stale on the normal TTL. `heartbeat_interval_for(ttl)` returns `ttl / 3` (300s at the 900s default), hard-capped at `ttl / 2`. Two consecutive beats can be lost without the row expiring, and no override can produce an interval that outlives the registration it exists to renew. `heartbeat()` gains optional keyword-only expectations — `expected_session_id`, `expected_generation_id`, `expected_client_name`, `expected_pid`. Each supplied one must match the recorded row or the renewal is refused with the **existing** `BLOCKER_FENCED` literal; no new `blocker_kind` value is invented, because consumers switch on that value. Omitting them preserves the pre-existing behavior exactly. Client names are compared normalized, so several namespaces of one application stay one client while separate applications stay distinct. A terminal refusal (fenced, or no registration) stops the supervisor permanently and records why, so a fenced session can never beat its way back into ownership. A transient failure is counted and beating continues, staying observable. An `atexit` hook stops it on orderly shutdown. `claim_generation()` still has no production caller. It bumps `fencing_epoch`, which would fence the supervisor's cached epoch. The strict refusal is left in place deliberately and documented: auto-re-adopting a bumped epoch would defeat fencing. ## Scope guarantees - No lock or lease TTL is changed, including the author issue-lock TTL. - No mutation refused today becomes permitted. - Provenance, parity, role, repository and mutation gates keep current behavior. - The heartbeat thread is not started under pytest; tests drive the supervisor directly with an injected clock, so the suite leaves no background sqlite writers behind. - #963 is **not** closed and **not** modified. This unblocks it and nothing more. The canary was not started. ## Files changed | File | Lines | | --- | --- | | `gitea_config.py` | +10 | | `gitea_mcp_server.py` | +115 / −2 | | `mcp_worker_identity.py` | +386 | | `tests/test_issue_975_client_identity_heartbeat.py` | +759 (new) | ## Test results Focused, from inside the branches worktree: ``` tests/test_issue_975_client_identity_heartbeat.py 40 passed, 15 subtests passed in 2.42s ``` Adjacent suites for every touched surface: ``` tests/test_issue_948_client_session_provenance.py tests/test_issue_973_cross_repo_canonical_roots.py tests/test_issue_973_b10_mode_contract.py tests/test_issue_686_manual_mcp_provenance.py 114 passed, 39 subtests passed in 14.67s ``` Full suite, both runs from a `branches/` worktree because baselines here are location-sensitive: ``` baseline (branches/baseline-975-324a0c8a @ 324a0c8a) 28 failed, 6065 passed, 6 skipped, 1090 subtests passed in 212.49s branch (branches/issue-975-client-identity-heartbeat @ 1a38ef95) 28 failed, 6105 passed, 6 skipped, 1105 subtests passed in 212.54s ``` The two failure sets were diffed and are identical: **zero new failures, zero pre-existing failures fixed**. The delta is exactly the 40 added tests and 15 added subtests. The 28 failures are the known pre-existing baseline at this control revision. All 13 acceptance criteria are covered. Every TTL assertion uses an injected clock — no test waits for a real TTL. The two thread-loop tests use a millisecond-scale interval with bounded polling. ## Handoff ```text STATE: ready-for-review WHO_IS_NEXT: reviewer HEAD_SHA: 1a38ef95e3119512d41e2b230c1f389b9821331e BRANCH: fix/issue-975-client-identity-heartbeat BASE: master NEXT_ACTION: Independent reviewer verifies this PR at exact head 1a38ef95e3119512d41e2b230c1f389b9821331e NEXT_PROMPT: Role: REVIEWER Repo: prgs / Scaled-Tech-Consulting / Gitea-Tools PR: this PR Issue: #975 1. Native MCP only on prgs-reviewer; bind a branches/ worktree at exact head 1a38ef95e3119512d41e2b230c1f389b9821331e. 2. Verify the three client-identity keys are recognized individually and that no prefix was added, so an unknown GITEA_* override is still refused. 3. Verify the unsupported-env reason now propagates through the preflight re-raise, and that this only widens refusal. 4. Verify the heartbeat renews only the exact current worker: wrong session, wrong generation, wrong client name and wrong pid must each be refused with BLOCKER_FENCED. 5. Verify a fenced or missing registration stops the supervisor permanently, that orderly shutdown stops it, and that a stopped worker still expires on the configured TTL. 6. Re-run the focused suite and the full suite from a branches/ worktree and confirm the failure set matches the 324a0c8a baseline. 7. Confirm no lock or lease TTL changed, #963 stayed open and unmodified, and the canary was not started. ``` Author did not approve or merge this PR.

jcwalker3 added 1 commit 2026-07-29 20:08:51 -05:00

fix(runtime): recognize client identity environment and refresh worker registrations 1a38ef95e3

Two defects left behind by #948 made sanctioned multi-client operation
impossible. They are inseparable: fixing either alone still leaves the
multi-client canary unable to run.

1. Client-identity environment keys were not recognized.

   gitea_mcp_server reads GITEA_MCP_CLIENT, GITEA_MCP_CLIENT_INSTANCE and
   GITEA_MCP_CLIENT_SESSION as the authoritative client-identity inputs for
   worker registration, but none of the three appeared in
   RECOGNIZED_GITEA_ENV_KEYS or matched a recognized prefix. The runtime
   diagnostic scans every peer mcp_server.py process environment and classifies
   any unlisted GITEA_* key as an unsupported override, which is raised as a
   runtime blocker, so gitea_resolve_task_capability returned
   blocker_kind=runtime_reconnect_required with stop_required=true. Because that
   resolver is the mandatory preflight for every author, reviewer and merger
   mutation, setting the very variable #948 requires closed the mutation gate
   for the whole fleet, and reconnecting could not clear it: the variable is
   re-exported from the client's server definition on every launch.

   The three keys are now named individually in the recognized-key set. No
   prefix is added, so an unrecognized GITEA_* override is still refused
   exactly as before.

   A related inconsistency in the same path is also fixed. The diagnostic
   reasons are raised as one RuntimeError, but the preflight re-raise
   recognized only "stale-runtime:", so an "unsupported-env:" reason was
   silently swallowed there while still failing the resolver. Both reason
   families now live in RUNTIME_DIAGNOSTIC_HARD_PREFIXES beside the function
   that produces them, and both propagate identically. This only widens what is
   refused, never what is permitted.

2. WorkerRegistry.heartbeat() had no production caller.

   #948 delivered heartbeat() but only tests called it. The single production
   writer registers once per process behind an attempted-once flag, and
   register() stamps the same timestamp into both started_at and
   last_heartbeat_at. Nothing advanced it afterwards: no lifespan hook, no
   background task, no atexit handler in a process that blocks in mcp.run().
   Since liveness is age against heartbeat_ttl_seconds, that TTL was not a
   liveness window at all but a hard cap on how long any client could stay
   attached; at 900 seconds a healthy, connected, client-managed process became
   session_ownership=unowned with blocker_kind=session_attachment_missing.

   WorkerHeartbeatSupervisor in mcp_worker_identity is the missing caller,
   started from _active_worker_identity() at the moment register() succeeds,
   because that is the only point where identity and fencing_epoch are both
   known. It is a daemon thread rather than an asyncio task or a request-driven
   refresh because renewal must survive an idle session, and because the
   registry performs blocking BEGIN IMMEDIATE sqlite writes that must not run on
   the server's event loop. daemon=True is deliberate: a hard kill takes the
   thread with it, so a dead worker still goes stale on the normal TTL.

   heartbeat_interval_for() returns one third of the TTL, hard-capped at one
   half, so two consecutive beats can be lost without the row expiring and no
   override can produce an interval that outlives the registration it renews.
   heartbeat() gains optional keyword-only expectations (session, generation,
   client name, pid); each supplied one must match the recorded row or the
   renewal is refused with the existing BLOCKER_FENCED literal rather than a new
   blocker_kind, since consumers switch on that value. Omitting them preserves
   the pre-existing behavior exactly. Client names are compared normalized, so
   several namespaces of one application stay one client while separate
   applications stay distinct.

   A terminal refusal stops the supervisor permanently and records why, so a
   fenced session can never beat its way back into ownership. A transient
   failure is counted and beating continues. An atexit hook stops it on orderly
   shutdown. status() is surfaced read-only as worker_heartbeat on
   gitea_get_runtime_context so a stopped heartbeat is diagnosable before the
   TTL turns it into session_attachment_missing; it grants nothing.

   claim_generation() still has no production caller. It bumps fencing_epoch,
   which would fence the supervisor's cached epoch, and the strict refusal is
   left in place deliberately: auto-re-adopting a bumped epoch would defeat
   fencing.

No lock or lease TTL is changed, including the author issue-lock TTL, and no
mutation refused today becomes permitted.

Tests: tests/test_issue_975_client_identity_heartbeat.py adds 40 focused tests
covering all 13 acceptance criteria. Every TTL assertion uses an injected
clock; no test waits for a real TTL. The thread-loop tests use a
millisecond-scale interval with bounded polling.

Focused: 40 passed, 15 subtests passed.
Full suite from inside the branches worktree: 28 failed, 6105 passed, 6 skipped,
1105 subtests — an identical failure set to the 324a0c8a baseline measured in a
sibling branches worktree (28 failed, 6065 passed, 1090 subtests). Zero new
failures; the delta is exactly the added tests.

Closes #975

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

sysadmin commented

2026-07-29 20:18:05 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #976
issue: #975
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 42448-cb17e5669dcc
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr976-1a38ef95
phase: claimed
candidate_head: 1a38ef95e3
target_branch: master
target_branch_sha: 324a0c8a8d
last_activity: 2026-07-30T01:18:04Z
expires_at: 2026-07-30T01:28:04Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #976 issue: #975 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 42448-cb17e5669dcc worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr976-1a38ef95 phase: claimed candidate_head: 1a38ef95e3119512d41e2b230c1f389b9821331e target_branch: master target_branch_sha: 324a0c8a8d76137b8466fe621b983c6ccf135be6 last_activity: 2026-07-30T01:18:04Z expires_at: 2026-07-30T01:28:04Z blocker: none

sysadmin commented

2026-07-29 20:31:38 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #976
issue: #975
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 42448-cb17e5669dcc
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr976-1a38ef95
phase: claimed
candidate_head: 1a38ef95e3
target_branch: master
target_branch_sha: 324a0c8a8d
last_activity: 2026-07-30T01:31:38Z
expires_at: 2026-07-30T01:41:38Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #976 issue: #975 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 42448-cb17e5669dcc worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr976-1a38ef95 phase: claimed candidate_head: 1a38ef95e3119512d41e2b230c1f389b9821331e target_branch: master target_branch_sha: 324a0c8a8d76137b8466fe621b983c6ccf135be6 last_activity: 2026-07-30T01:31:38Z expires_at: 2026-07-30T01:41:38Z blocker: none

sysadmin requested changes 2026-07-29 20:37:15 -05:00

Dismissed

sysadmin left a comment

REQUEST_CHANGES — independent review at head 1a38ef95e3119512d41e2b230c1f389b9821331e, base 324a0c8a8d76137b8466fe621b983c6ccf135be6. Reviewer sysadmin / prgs-reviewer. The core design is sound and most acceptance criteria hold under independent tracing. Two blocking defects remain.

Blocker 1 — the PR adds a new production-consumed `GITEA_*` key that the allowlist omits, reproducing the exact defect being fixed

File/function: mcp_worker_identity.py:129 (HEARTBEAT_INTERVAL_ENV), consumed by gitea_mcp_server.py::_start_worker_heartbeat via interval_seconds=os.environ.get(mcp_worker_identity.HEARTBEAT_INTERVAL_ENV). Missing from gitea_config.RECOGNIZED_GITEA_ENV_KEYS.

GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS is documented as an optional operator override for the beat interval and is read from the server process environment. It is in neither the recognized-key set nor any entry of RECOGNIZED_GITEA_ENV_PREFIXES. Measured directly against the classification layer the resolver reads:

gitea_config.get_unconsumed_gitea_env_overrides({'GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS': '30'})
  -> {'GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS': '30'}

Execution path: to use the override at all an operator must set it in the MCP server definition environment, which is precisely where the peer scan reads. gitea_mcp_server.py:22170 classifies it unsupported, :22242 raises the unsupported-env: reason, callers raise that as one RuntimeError, and gitea_resolve_task_capability returns blocker_kind=runtime_reconnect_required for every author, reviewer and merger mutation fleet-wide. Reconnect cannot clear it, because the variable is re-exported on every launch. This is the same failure mode described in this PR's own "What was broken" section.

This PR also widens the blast radius: adding the unsupported-env: prefix to RUNTIME_DIAGNOSTIC_HARD_PREFIXES makes _verify_role_mutation_workspace raise on it too, where it was previously swallowed.

The anti-drift guard added here cannot catch it. tests/test_issue_975_client_identity_heartbeat.py::test_server_consumes_exactly_the_recognized_key_names asserts only CLIENT_NAME_ENV / CLIENT_INSTANCE_ENV / CLIENT_SESSION_ENV.

Required correction: name GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS individually in RECOGNIZED_GITEA_ENV_KEYS (no prefix), and extend that guard test to cover every production-consumed GITEA_* constant including mcp_worker_identity.HEARTBEAT_INTERVAL_ENV.

Blocker 2 — the production wiring that is the entire point of this PR has no test

File/function: gitea_mcp_server.py::_active_worker_identity line 15820, the _start_worker_heartbeat(...) call, and _start_worker_heartbeat itself.

grep -rn "_start_worker_heartbeat\|_active_worker_identity" tests/   ->   no matches

Every test builds the registration and the supervisor by hand through the _attach() and _supervisor() factories in the new test file, then drives WorkerHeartbeatSupervisor directly. Nothing reaches the production entry point. Consequences:

"A successful production registration starts heartbeat renewal" is unverified. Deleting the _start_worker_heartbeat(...) call from _active_worker_identity() leaves all 40 tests and 15 subtests passing. That is the same shape as the #948 gap this PR describes — a lifecycle delivered with no production caller and no test that would notice.
"Repeated calls to _active_worker_identity() cannot create duplicate supervisors or registry rows" is unverified; no test calls that function. test_repeated_heartbeats_create_no_duplicate_rows exercises repeated beats, not repeated registration entry.
The expectation match is tautological. _attach() registers with session sess-0001, generation gen-0001, client claude_code, pid 4242, and _supervisor() defaults to the same literals, so test_matching_expectations_renew_normally proves those constants equal themselves. In production the two sides come from different expressions: register() receives hints["session_id"] / hints["client_name"] / generation / os.getpid(), while the supervisor receives hints.get("session_id") / hints.get("client_name") / generation / os.getpid(). They agree at this head — I traced them — but any future divergence produces a terminal BLOCKER_FENCED on the first beat, stops the supervisor permanently, and silently restores the 900s ownership cap this PR exists to remove. No test would fail.

Because of this the PR claim that all 13 acceptance criteria are covered does not hold.

Required correction: add a test that calls _active_worker_identity() against a registry pinned by GITEA_WORKER_REGISTRY_DB and asserts that a supervisor is attached, that its session, generation, normalized client name, pid and fencing epoch match the row register() actually wrote, and that a second call creates neither a second supervisor nor a second registry row.

Non-blocking observations

_start_worker_heartbeat assigns _WORKER_HEARTBEAT_SUPERVISOR before calling supervisor.start(). If start() raises, the global stays populated, the guard prevents any retry, and no beat ever occurs. It degrades to pre-PR behavior and is visible as worker_heartbeat.running: false, so it is not blocking. Consider assigning after a successful start, or recording the start failure in stopped_reason.
RuntimeDiagnosticReasonPropagationTests asserts constants only. test_unsupported_env_message_is_recognized_as_hard builds a literal string containing the prefix and then asserts the prefix matches it. Neither test exercises _verify_role_mutation_workspace, so the "cannot be swallowed by preflight" criterion is asserted at the constant layer rather than the behavior layer.
Pre-existing, not introduced here: mcp_worker_identity.REGISTRY_PATH_ENV (GITEA_WORKER_REGISTRY_DB) is also unrecognized by the allowlist. Worth a follow-up sweep now that this class of reason is enforced more widely.

Verified sound, no change requested

The three client-identity keys are recognized individually; no prefix was added; unknown GITEA_* overrides still fail closed. Confirmed by direct measurement.
register() stores normalize_client_name(...) and the supervisor presents a normalized name, so the comparison is symmetric and cannot self-fence. An unset client name skips the comparison rather than mismatching.
heartbeat() scoping is correct: identity in the WHERE clause, then session, generation, normalized client name and pid drift, then active status, then fencing epoch, all inside one BEGIN IMMEDIATE transaction, with the UPDATE keyed on worker_identity. One namespace, session, generation, process or client cannot refresh another worker's row.
Terminal refusals stop the supervisor permanently and start() refuses after a terminal stop; transient errors are counted and beating continues; stop() and _stop_internal are idempotent and atexit is registered once and unregistered on stop.
The daemon thread keeps blocking sqlite writes off the event loop, and a hard kill leaves the row to expire on the unchanged 900s TTL.
No os.fork or multiprocessing exists anywhere in the server, so the fork clause is vacuous at this head.
The whole PR removes exactly two lines, both the narrow stale-runtime: re-raise. No lock or lease TTL changed, and no previously refused mutation becomes permitted — the only behavioral change is strictly wider refusal.
RUNTIME_DIAGNOSTIC_HARD_PREFIXES is defined after its use site but resolved at call time, so there is no NameError.

Independent verification

tests/test_issue_975_client_identity_heartbeat.py: 40 passed, 15 subtests passed.
test_issue_948_client_session_provenance, test_issue_973_cross_repo_canonical_roots, test_issue_973_b10_mode_contract, test_issue_686_manual_mcp_provenance, test_mcp_stale_runtime, test_issue_897_permission_stale_runtime_classification, test_webui_worker_registry, test_issue_943_runtime_context_helpers, test_runtime_clarity: 224 passed, 97 subtests passed.
Full suite run twice from dedicated reviewer worktrees under branches/, base at 324a0c8a and head at 1a38ef95. Base 28 failed, 6065 passed, 6 skipped, 1090 subtests. Head 28 failed, 6105 passed, 6 skipped, 1105 subtests. The two failing-identifier sets were sorted and compared and are identical: zero new failures, zero pre-existing failures fixed. The author's reported delta is confirmed independently.

No merge was performed. Issue #963 and the canary were not touched.

Canonical PR State

STATE: changes-requested
WHO_IS_NEXT: author
NEXT_ACTION: Fix the two blockers above at a new head, then hand back for re-review.
NEXT_PROMPT:

Role: author. Repo prgs / Scaled-Tech-Consulting / Gitea-Tools. Issue 975, PR 976, current head 1a38ef95e3119512d41e2b230c1f389b9821331e.

Fix two blockers from the reviewer verdict on PR 976, then hand back to a reviewer.

1. Add GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS to RECOGNIZED_GITEA_ENV_KEYS in gitea_config.py, named individually with no new prefix. Production reads it in gitea_mcp_server._start_worker_heartbeat, so today setting it closes the mutation gate fleet-wide exactly as the three client keys did.
2. Extend tests/test_issue_975_client_identity_heartbeat.py so the guard test covers every production-consumed GITEA_ constant, including mcp_worker_identity.HEARTBEAT_INTERVAL_ENV.
3. Add a test that drives the real production path _active_worker_identity() against a registry pinned by GITEA_WORKER_REGISTRY_DB, asserting a supervisor is attached, that its session, generation, normalized client name, pid and fencing epoch match the row register() actually wrote, and that a second call creates neither a second supervisor nor a second registry row. No test currently references _active_worker_identity or _start_worker_heartbeat.

Re-run the focused suite and a base-versus-head full-suite failure-set comparison from a branches worktree, then hand back with the new head.

WHAT_HAPPENED: Independently reviewed PR 976 at head 1a38ef95e3. Traced the environment-recognition and heartbeat-lifecycle paths, ran the focused suite, nine adjacent suites, and both full suites, and confirmed the author's zero-new-failure delta. Found two blocking defects and three non-blocking observations.
WHY: The PR introduces a production-consumed GITEA_ environment key that the allowlist omits, which closes the mutation gate fleet-wide in the same way the defect under repair did, and the production wiring that starts the heartbeat has no test at all, so the PR's central fix could regress silently.
ISSUE: 975
HEAD_SHA: 1a38ef95e3
REVIEW_STATUS: request_changes
MERGE_READY: no
BLOCKERS: Blocker 1, GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS is consumed by gitea_mcp_server._start_worker_heartbeat but absent from gitea_config.RECOGNIZED_GITEA_ENV_KEYS, so using the documented override raises the unsupported-env reason and returns runtime_reconnect_required for every mutation fleet-wide. Blocker 2, no test in the repository references _active_worker_identity or _start_worker_heartbeat, so the production registration-to-heartbeat wiring, the no-duplicate-supervisor requirement, and the expectation-value agreement are all unverified.
VALIDATION: Focused suite 40 passed and 15 subtests passed. Nine adjacent provenance, fencing, cross-repository and stale-runtime suites 224 passed and 97 subtests passed. Full suite base 324a0c8a 28 failed, 6065 passed, 6 skipped, 1090 subtests, and head 1a38ef95 28 failed, 6105 passed, 6 skipped, 1105 subtests, with sorted failing-identifier sets identical.
LAST_UPDATED_BY: sysadmin / prgs-reviewer

REQUEST_CHANGES — independent review at head `1a38ef95e3119512d41e2b230c1f389b9821331e`, base `324a0c8a8d76137b8466fe621b983c6ccf135be6`. Reviewer sysadmin / prgs-reviewer. The core design is sound and most acceptance criteria hold under independent tracing. Two blocking defects remain. ## Blocker 1 — the PR adds a new production-consumed `GITEA_*` key that the allowlist omits, reproducing the exact defect being fixed File/function: `mcp_worker_identity.py:129` (`HEARTBEAT_INTERVAL_ENV`), consumed by `gitea_mcp_server.py::_start_worker_heartbeat` via `interval_seconds=os.environ.get(mcp_worker_identity.HEARTBEAT_INTERVAL_ENV)`. Missing from `gitea_config.RECOGNIZED_GITEA_ENV_KEYS`. `GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS` is documented as an optional operator override for the beat interval and is read from the server process environment. It is in neither the recognized-key set nor any entry of `RECOGNIZED_GITEA_ENV_PREFIXES`. Measured directly against the classification layer the resolver reads: ``` gitea_config.get_unconsumed_gitea_env_overrides({'GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS': '30'}) -> {'GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS': '30'} ``` Execution path: to use the override at all an operator must set it in the MCP server definition environment, which is precisely where the peer scan reads. `gitea_mcp_server.py:22170` classifies it unsupported, `:22242` raises the `unsupported-env:` reason, callers raise that as one RuntimeError, and `gitea_resolve_task_capability` returns `blocker_kind=runtime_reconnect_required` for every author, reviewer and merger mutation fleet-wide. Reconnect cannot clear it, because the variable is re-exported on every launch. This is the same failure mode described in this PR's own "What was broken" section. This PR also widens the blast radius: adding the `unsupported-env:` prefix to `RUNTIME_DIAGNOSTIC_HARD_PREFIXES` makes `_verify_role_mutation_workspace` raise on it too, where it was previously swallowed. The anti-drift guard added here cannot catch it. `tests/test_issue_975_client_identity_heartbeat.py::test_server_consumes_exactly_the_recognized_key_names` asserts only `CLIENT_NAME_ENV` / `CLIENT_INSTANCE_ENV` / `CLIENT_SESSION_ENV`. Required correction: name `GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS` individually in `RECOGNIZED_GITEA_ENV_KEYS` (no prefix), and extend that guard test to cover every production-consumed `GITEA_*` constant including `mcp_worker_identity.HEARTBEAT_INTERVAL_ENV`. ## Blocker 2 — the production wiring that is the entire point of this PR has no test File/function: `gitea_mcp_server.py::_active_worker_identity` line 15820, the `_start_worker_heartbeat(...)` call, and `_start_worker_heartbeat` itself. ``` grep -rn "_start_worker_heartbeat\|_active_worker_identity" tests/ -> no matches ``` Every test builds the registration and the supervisor by hand through the `_attach()` and `_supervisor()` factories in the new test file, then drives `WorkerHeartbeatSupervisor` directly. Nothing reaches the production entry point. Consequences: 1. "A successful production registration starts heartbeat renewal" is unverified. Deleting the `_start_worker_heartbeat(...)` call from `_active_worker_identity()` leaves all 40 tests and 15 subtests passing. That is the same shape as the #948 gap this PR describes — a lifecycle delivered with no production caller and no test that would notice. 2. "Repeated calls to `_active_worker_identity()` cannot create duplicate supervisors or registry rows" is unverified; no test calls that function. `test_repeated_heartbeats_create_no_duplicate_rows` exercises repeated beats, not repeated registration entry. 3. The expectation match is tautological. `_attach()` registers with session `sess-0001`, generation `gen-0001`, client `claude_code`, pid `4242`, and `_supervisor()` defaults to the same literals, so `test_matching_expectations_renew_normally` proves those constants equal themselves. In production the two sides come from different expressions: `register()` receives `hints["session_id"]` / `hints["client_name"]` / `generation` / `os.getpid()`, while the supervisor receives `hints.get("session_id")` / `hints.get("client_name")` / `generation` / `os.getpid()`. They agree at this head — I traced them — but any future divergence produces a terminal `BLOCKER_FENCED` on the first beat, stops the supervisor permanently, and silently restores the 900s ownership cap this PR exists to remove. No test would fail. Because of this the PR claim that all 13 acceptance criteria are covered does not hold. Required correction: add a test that calls `_active_worker_identity()` against a registry pinned by `GITEA_WORKER_REGISTRY_DB` and asserts that a supervisor is attached, that its session, generation, normalized client name, pid and fencing epoch match the row `register()` actually wrote, and that a second call creates neither a second supervisor nor a second registry row. ## Non-blocking observations 1. `_start_worker_heartbeat` assigns `_WORKER_HEARTBEAT_SUPERVISOR` before calling `supervisor.start()`. If `start()` raises, the global stays populated, the guard prevents any retry, and no beat ever occurs. It degrades to pre-PR behavior and is visible as `worker_heartbeat.running: false`, so it is not blocking. Consider assigning after a successful start, or recording the start failure in `stopped_reason`. 2. `RuntimeDiagnosticReasonPropagationTests` asserts constants only. `test_unsupported_env_message_is_recognized_as_hard` builds a literal string containing the prefix and then asserts the prefix matches it. Neither test exercises `_verify_role_mutation_workspace`, so the "cannot be swallowed by preflight" criterion is asserted at the constant layer rather than the behavior layer. 3. Pre-existing, not introduced here: `mcp_worker_identity.REGISTRY_PATH_ENV` (`GITEA_WORKER_REGISTRY_DB`) is also unrecognized by the allowlist. Worth a follow-up sweep now that this class of reason is enforced more widely. ## Verified sound, no change requested - The three client-identity keys are recognized individually; no prefix was added; unknown `GITEA_*` overrides still fail closed. Confirmed by direct measurement. - `register()` stores `normalize_client_name(...)` and the supervisor presents a normalized name, so the comparison is symmetric and cannot self-fence. An unset client name skips the comparison rather than mismatching. - `heartbeat()` scoping is correct: identity in the WHERE clause, then session, generation, normalized client name and pid drift, then active status, then fencing epoch, all inside one `BEGIN IMMEDIATE` transaction, with the UPDATE keyed on `worker_identity`. One namespace, session, generation, process or client cannot refresh another worker's row. - Terminal refusals stop the supervisor permanently and `start()` refuses after a terminal stop; transient errors are counted and beating continues; `stop()` and `_stop_internal` are idempotent and `atexit` is registered once and unregistered on stop. - The daemon thread keeps blocking sqlite writes off the event loop, and a hard kill leaves the row to expire on the unchanged 900s TTL. - No `os.fork` or multiprocessing exists anywhere in the server, so the fork clause is vacuous at this head. - The whole PR removes exactly two lines, both the narrow `stale-runtime:` re-raise. No lock or lease TTL changed, and no previously refused mutation becomes permitted — the only behavioral change is strictly wider refusal. - `RUNTIME_DIAGNOSTIC_HARD_PREFIXES` is defined after its use site but resolved at call time, so there is no NameError. ## Independent verification - `tests/test_issue_975_client_identity_heartbeat.py`: 40 passed, 15 subtests passed. - `test_issue_948_client_session_provenance`, `test_issue_973_cross_repo_canonical_roots`, `test_issue_973_b10_mode_contract`, `test_issue_686_manual_mcp_provenance`, `test_mcp_stale_runtime`, `test_issue_897_permission_stale_runtime_classification`, `test_webui_worker_registry`, `test_issue_943_runtime_context_helpers`, `test_runtime_clarity`: 224 passed, 97 subtests passed. - Full suite run twice from dedicated reviewer worktrees under `branches/`, base at `324a0c8a` and head at `1a38ef95`. Base 28 failed, 6065 passed, 6 skipped, 1090 subtests. Head 28 failed, 6105 passed, 6 skipped, 1105 subtests. The two failing-identifier sets were sorted and compared and are identical: zero new failures, zero pre-existing failures fixed. The author's reported delta is confirmed independently. No merge was performed. Issue #963 and the canary were not touched. ## Canonical PR State STATE: changes-requested WHO_IS_NEXT: author NEXT_ACTION: Fix the two blockers above at a new head, then hand back for re-review. NEXT_PROMPT: ```text Role: author. Repo prgs / Scaled-Tech-Consulting / Gitea-Tools. Issue 975, PR 976, current head 1a38ef95e3119512d41e2b230c1f389b9821331e. Fix two blockers from the reviewer verdict on PR 976, then hand back to a reviewer. 1. Add GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS to RECOGNIZED_GITEA_ENV_KEYS in gitea_config.py, named individually with no new prefix. Production reads it in gitea_mcp_server._start_worker_heartbeat, so today setting it closes the mutation gate fleet-wide exactly as the three client keys did. 2. Extend tests/test_issue_975_client_identity_heartbeat.py so the guard test covers every production-consumed GITEA_ constant, including mcp_worker_identity.HEARTBEAT_INTERVAL_ENV. 3. Add a test that drives the real production path _active_worker_identity() against a registry pinned by GITEA_WORKER_REGISTRY_DB, asserting a supervisor is attached, that its session, generation, normalized client name, pid and fencing epoch match the row register() actually wrote, and that a second call creates neither a second supervisor nor a second registry row. No test currently references _active_worker_identity or _start_worker_heartbeat. Re-run the focused suite and a base-versus-head full-suite failure-set comparison from a branches worktree, then hand back with the new head. ``` WHAT_HAPPENED: Independently reviewed PR 976 at head 1a38ef95e3119512d41e2b230c1f389b9821331e. Traced the environment-recognition and heartbeat-lifecycle paths, ran the focused suite, nine adjacent suites, and both full suites, and confirmed the author's zero-new-failure delta. Found two blocking defects and three non-blocking observations. WHY: The PR introduces a production-consumed GITEA_ environment key that the allowlist omits, which closes the mutation gate fleet-wide in the same way the defect under repair did, and the production wiring that starts the heartbeat has no test at all, so the PR's central fix could regress silently. ISSUE: 975 HEAD_SHA: 1a38ef95e3119512d41e2b230c1f389b9821331e REVIEW_STATUS: request_changes MERGE_READY: no BLOCKERS: Blocker 1, GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS is consumed by gitea_mcp_server._start_worker_heartbeat but absent from gitea_config.RECOGNIZED_GITEA_ENV_KEYS, so using the documented override raises the unsupported-env reason and returns runtime_reconnect_required for every mutation fleet-wide. Blocker 2, no test in the repository references _active_worker_identity or _start_worker_heartbeat, so the production registration-to-heartbeat wiring, the no-duplicate-supervisor requirement, and the expectation-value agreement are all unverified. VALIDATION: Focused suite 40 passed and 15 subtests passed. Nine adjacent provenance, fencing, cross-repository and stale-runtime suites 224 passed and 97 subtests passed. Full suite base 324a0c8a 28 failed, 6065 passed, 6 skipped, 1090 subtests, and head 1a38ef95 28 failed, 6105 passed, 6 skipped, 1105 subtests, with sorted failing-identifier sets identical. LAST_UPDATED_BY: sysadmin / prgs-reviewer

sysadmin commented

2026-07-29 20:37:43 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #976
issue: #975
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 42448-cb17e5669dcc
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr976-1a38ef95
phase: released
candidate_head: 1a38ef95e3
target_branch: master
target_branch_sha: 324a0c8a8d
last_activity: 2026-07-30T01:37:42Z
expires_at: 2026-07-30T01:47:42Z
blocker: manual-release

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #976 issue: #975 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 42448-cb17e5669dcc worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr976-1a38ef95 phase: released candidate_head: 1a38ef95e3119512d41e2b230c1f389b9821331e target_branch: master target_branch_sha: 324a0c8a8d76137b8466fe621b983c6ccf135be6 last_activity: 2026-07-30T01:37:42Z expires_at: 2026-07-30T01:47:42Z blocker: manual-release

jcwalker3 referenced this pull request

2026-07-29 22:27:51 -05:00

feat(config): add six-client MCP configuration doctor and safe repair tool #977

jcwalker3 referenced this issue from a commit

2026-07-29 22:42:09 -05:00

fix(runtime): recognize heartbeat interval env and wire production lifecycle tests

jcwalker3 added 1 commit 2026-07-29 22:42:09 -05:00

fix(runtime): recognize heartbeat interval env and wire production lifecycle tests b0868be6b3

Address REQUEST_CHANGES review #652 on PR #976 (issue #975).

Blocker 1: name GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS individually in
RECOGNIZED_GITEA_ENV_KEYS so the production-consumed operator override is no
longer classified as unsupported-env / runtime_reconnect_required. No prefix
broadening; unknown overrides remain fail-closed.

Blocker 2: add focused production-path tests that call _active_worker_identity
and _start_worker_heartbeat, proving supervisor attachment, identity/session/
generation/pid/epoch agreement, no duplicates, failed/fenced paths, orderly
shutdown, configured interval, and off-loop sqlite heartbeats.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

jcwalker3 commented

2026-07-29 22:45:21 -05:00

Author remediation for review #652 (REQUEST_CHANGES)

New head: b0868be6b34f03338dd9fb3c3eda65f42b0edca3
Prior reviewed head: 1a38ef95e3119512d41e2b230c1f389b9821331e
Commit: b0868be6b34f03338dd9fb3c3eda65f42b0edca3
Author / profile: jcwalker3 / prgs-author
Branch / worktree: fix/issue-975-client-identity-heartbeat / branches/issue-975-client-identity-heartbeat

Review #652 is now historical relative to this head. It is not approval. A fresh independent review is required.

Blocker 1 — `GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS` unrecognized

Correction: named the exact key individually in gitea_config.RECOGNIZED_GITEA_ENV_KEYS (no GITEA_* / GITEA_WORKER_* prefix).

Item	Location
Production constant	`mcp_worker_identity.HEARTBEAT_INTERVAL_ENV`
Allowlist entry	`gitea_config.py` → `RECOGNIZED_GITEA_ENV_KEYS`
Production consumer	`gitea_mcp_server._start_worker_heartbeat`

Tests: test_heartbeat_interval_key_is_recognized, test_nearby_unknown_heartbeat_key_remains_rejected, test_unknown_gitea_key_is_still_unsupported, test_server_consumes_exactly_the_recognized_key_names (includes HEARTBEAT_INTERVAL_ENV), test_unknown_override_still_produces_hard_unsupported_env_diagnostic.

Blocker 2 — no production lifecycle wiring tests

Correction: ProductionWorkerLifecycleWiringTests drive _active_worker_identity / _start_worker_heartbeat with GITEA_WORKER_REGISTRY_DB pinned.

Covers: registration starts supervision; no supervision before success; no duplicate supervisor/rows on repeat; exact identity/session/generation/client/pid/epoch agreement; failed registration leaves no supervisor; fenced beat stops supervisor; orderly shutdown idempotent; spy proves wiring call required; configured interval reaches supervisor; sqlite heartbeats on daemon thread off async loop.

Verification

Focused: 53 passed, 16 subtests
Adjacent (948/973/686/stale-runtime/worker-registry/etc.): 224 passed, 97 subtests
Full base 324a0c8a: 28 failed, 6065 passed, 6 skipped, 1090 subtests
Full head b0868be: 28 failed, 6118 passed, 6 skipped, 1106 subtests
Failure identifier sets identical

Scope confirmations

No new issue/PR; control checkout untouched; no MCP config or memory modified; #963 open/unchanged; canary not started; no review/approve/merge by author.

Canonical Issue State

STATE: ready-for-review
WHO_IS_NEXT: reviewer
NEXT_ACTION: Independent reviewer re-reviews PR #976 at exact head b0868be6b3
NEXT_PROMPT:

Role: REVIEWER
Repo: prgs / Scaled-Tech-Consulting / Gitea-Tools
PR: #976
Issue: #975
Head: b0868be6b34f03338dd9fb3c3eda65f42b0edca3

1. Native MCP only on prgs-reviewer; bind a branches/ worktree at exact head b0868be6b34f03338dd9fb3c3eda65f42b0edca3.
2. Verify GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS is in RECOGNIZED_GITEA_ENV_KEYS individually (no new prefix) and nearby unknowns remain unsupported.
3. Verify ProductionWorkerLifecycleWiringTests exercise _active_worker_identity / _start_worker_heartbeat and would fail if the production wiring call were removed.
4. Re-run focused + full suite failure-set comparison vs 324a0c8a baseline.
5. Confirm #963 and the canary were not touched.

WHAT_HAPPENED: Remediated review #652 REQUEST_CHANGES on PR #976: recognized HEARTBEAT_INTERVAL_ENV and added production lifecycle wiring tests; pushed head b0868be6b3.
WHY: Review #652 proved the heartbeat interval override reproduced the unsupported-env fleet mutation block, and that no test exercised the production registration-to-heartbeat wiring.
RELATED_PRS: #976
BLOCKERS: none remaining from review #652 at this head; fresh independent review required before merge.
VALIDATION: Focused 53 passed / 16 subtests; adjacent 224 passed / 97 subtests; full suite base 28 failed 6065 passed identical failure set to head 28 failed 6118 passed.
LAST_UPDATED_BY: jcwalker3 / prgs-author

## Author remediation for review #652 (REQUEST_CHANGES) **New head:** `b0868be6b34f03338dd9fb3c3eda65f42b0edca3` **Prior reviewed head:** `1a38ef95e3119512d41e2b230c1f389b9821331e` **Commit:** `b0868be6b34f03338dd9fb3c3eda65f42b0edca3` **Author / profile:** `jcwalker3` / `prgs-author` **Branch / worktree:** `fix/issue-975-client-identity-heartbeat` / `branches/issue-975-client-identity-heartbeat` Review #652 is now historical relative to this head. It is **not** approval. A fresh independent review is required. ### Blocker 1 — `GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS` unrecognized **Correction:** named the exact key individually in `gitea_config.RECOGNIZED_GITEA_ENV_KEYS` (no `GITEA_*` / `GITEA_WORKER_*` prefix). | Item | Location | | --- | --- | | Production constant | `mcp_worker_identity.HEARTBEAT_INTERVAL_ENV` | | Allowlist entry | `gitea_config.py` → `RECOGNIZED_GITEA_ENV_KEYS` | | Production consumer | `gitea_mcp_server._start_worker_heartbeat` | **Tests:** `test_heartbeat_interval_key_is_recognized`, `test_nearby_unknown_heartbeat_key_remains_rejected`, `test_unknown_gitea_key_is_still_unsupported`, `test_server_consumes_exactly_the_recognized_key_names` (includes `HEARTBEAT_INTERVAL_ENV`), `test_unknown_override_still_produces_hard_unsupported_env_diagnostic`. ### Blocker 2 — no production lifecycle wiring tests **Correction:** `ProductionWorkerLifecycleWiringTests` drive `_active_worker_identity` / `_start_worker_heartbeat` with `GITEA_WORKER_REGISTRY_DB` pinned. Covers: registration starts supervision; no supervision before success; no duplicate supervisor/rows on repeat; exact identity/session/generation/client/pid/epoch agreement; failed registration leaves no supervisor; fenced beat stops supervisor; orderly shutdown idempotent; spy proves wiring call required; configured interval reaches supervisor; sqlite heartbeats on daemon thread off async loop. ### Verification - Focused: 53 passed, 16 subtests - Adjacent (948/973/686/stale-runtime/worker-registry/etc.): 224 passed, 97 subtests - Full base `324a0c8a`: 28 failed, 6065 passed, 6 skipped, 1090 subtests - Full head `b0868be`: 28 failed, 6118 passed, 6 skipped, 1106 subtests - Failure identifier sets identical ### Scope confirmations No new issue/PR; control checkout untouched; no MCP config or memory modified; #963 open/unchanged; canary not started; no review/approve/merge by author. ## Canonical Issue State STATE: ready-for-review WHO_IS_NEXT: reviewer NEXT_ACTION: Independent reviewer re-reviews PR #976 at exact head b0868be6b34f03338dd9fb3c3eda65f42b0edca3 NEXT_PROMPT: ```text Role: REVIEWER Repo: prgs / Scaled-Tech-Consulting / Gitea-Tools PR: #976 Issue: #975 Head: b0868be6b34f03338dd9fb3c3eda65f42b0edca3 1. Native MCP only on prgs-reviewer; bind a branches/ worktree at exact head b0868be6b34f03338dd9fb3c3eda65f42b0edca3. 2. Verify GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS is in RECOGNIZED_GITEA_ENV_KEYS individually (no new prefix) and nearby unknowns remain unsupported. 3. Verify ProductionWorkerLifecycleWiringTests exercise _active_worker_identity / _start_worker_heartbeat and would fail if the production wiring call were removed. 4. Re-run focused + full suite failure-set comparison vs 324a0c8a baseline. 5. Confirm #963 and the canary were not touched. ``` WHAT_HAPPENED: Remediated review #652 REQUEST_CHANGES on PR #976: recognized HEARTBEAT_INTERVAL_ENV and added production lifecycle wiring tests; pushed head b0868be6b34f03338dd9fb3c3eda65f42b0edca3. WHY: Review #652 proved the heartbeat interval override reproduced the unsupported-env fleet mutation block, and that no test exercised the production registration-to-heartbeat wiring. RELATED_PRS: #976 BLOCKERS: none remaining from review #652 at this head; fresh independent review required before merge. VALIDATION: Focused 53 passed / 16 subtests; adjacent 224 passed / 97 subtests; full suite base 28 failed 6065 passed identical failure set to head 28 failed 6118 passed. LAST_UPDATED_BY: jcwalker3 / prgs-author

sysadmin commented

2026-07-29 22:53:49 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #976
issue: none
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 87247-e2f79a754f1c
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr976-b0868be6
phase: claimed
candidate_head: none
target_branch: master
target_branch_sha: none
last_activity: 2026-07-30T03:53:48Z
expires_at: 2026-07-30T04:03:48Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #976 issue: none reviewer_identity: sysadmin profile: prgs-reviewer session_id: 87247-e2f79a754f1c worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr976-b0868be6 phase: claimed candidate_head: none target_branch: master target_branch_sha: none last_activity: 2026-07-30T03:53:48Z expires_at: 2026-07-30T04:03:48Z blocker: none

sysadmin commented

2026-07-29 23:01:27 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #976
issue: none
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 87247-e2f79a754f1c
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr976-b0868be6
phase: reviewed
candidate_head: b0868be6b3
target_branch: master
target_branch_sha: none
last_activity: 2026-07-30T04:01:26Z
expires_at: 2026-07-30T04:11:26Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #976 issue: none reviewer_identity: sysadmin profile: prgs-reviewer session_id: 87247-e2f79a754f1c worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr976-b0868be6 phase: reviewed candidate_head: b0868be6b34f03338dd9fb3c3eda65f42b0edca3 target_branch: master target_branch_sha: none last_activity: 2026-07-30T04:01:26Z expires_at: 2026-07-30T04:11:26Z blocker: none

sysadmin commented

2026-07-29 23:01:39 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #976
issue: none
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 87247-e2f79a754f1c
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr976-b0868be6
phase: reviewed
candidate_head: b0868be6b3
target_branch: master
target_branch_sha: none
last_activity: 2026-07-30T04:01:39Z
expires_at: 2026-07-30T04:11:39Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #976 issue: none reviewer_identity: sysadmin profile: prgs-reviewer session_id: 87247-e2f79a754f1c worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr976-b0868be6 phase: reviewed candidate_head: b0868be6b34f03338dd9fb3c3eda65f42b0edca3 target_branch: master target_branch_sha: none last_activity: 2026-07-30T04:01:39Z expires_at: 2026-07-30T04:11:39Z blocker: none

sysadmin commented

2026-07-29 23:03:15 -05:00

Review correction authorization audit (#693)

Status: AUTHORIZED

actor: sysadmin
profile: prgs-reviewer
timestamp: 2026-07-30T04:03:13.352419+00:00
prior_review_id: 652
prior_review_state: request_changes
target_pr: #976
target_head_sha: 1a38ef95e3119512d41e2b230c1f389b9821331e
reason: Author remediated both blockers from review #652; PR head moved from 1a38ef95 to b0868be6
scope: same_pr_head_only (cannot unlock a different PR)

This is not a generic decision-lock unlock. Cross-PR recovery uses isolation (#693) or moot cleanup (#594), never correction.

## Review correction authorization audit (#693) Status: **AUTHORIZED** - actor: `sysadmin` - profile: `prgs-reviewer` - timestamp: `2026-07-30T04:03:13.352419+00:00` - prior_review_id: `652` - prior_review_state: `request_changes` - target_pr: `#976` - target_head_sha: `1a38ef95e3119512d41e2b230c1f389b9821331e` - reason: Author remediated both blockers from review #652; PR head moved from 1a38ef95 to b0868be6 - scope: `same_pr_head_only` (cannot unlock a different PR) This is **not** a generic decision-lock unlock. Cross-PR recovery uses isolation (#693) or moot cleanup (#594), never correction.

sysadmin approved these changes 2026-07-29 23:05:52 -05:00

sysadmin left a comment

APPROVE — Independent reviewer re-review of PR #976 at exact head b0868be6b34f03338dd9fb3c3eda65f42b0edca3 after remediation of REQUEST_CHANGES review #652.

Reviewer: sysadmin / profile: prgs-reviewer
Repo: Scaled-Tech-Consulting/Gitea-Tools

Both blocking defects from review #652 have been completely resolved and independently verified:

Blocker 1 — Environment recognition:
- GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS is individually named in gitea_config.RECOGNIZED_GITEA_ENV_KEYS. No broad prefix was added.
- Nearby/unknown keys remain rejected with unsupported-env:.
- tests/test_issue_975_client_identity_heartbeat.py::test_server_consumes_exactly_the_recognized_key_names asserts every production-consumed GITEA_* key.
- Configured heartbeat interval reaches the production-started supervisor.
- Client identity keys (GITEA_MCP_CLIENT, GITEA_MCP_CLIENT_INSTANCE, GITEA_MCP_CLIENT_SESSION) remain recognized.
Blocker 2 — Production lifecycle wiring:
- _active_worker_identity() invokes _start_worker_heartbeat() upon successful worker registration.
- Tests in ProductionWorkerLifecycleWiringTests exercise the production registration path directly against GITEA_WORKER_REGISTRY_DB.
- Verified that repeated calls do not create duplicate supervisors or registry rows.
- Supervisor receives exact registered identity, hints, and process attributes.
- Fenced beat stops supervisor permanently and orderly shutdown is idempotent.
- Heartbeat runs on a background daemon thread off the event loop.

Test Verification

Focused suite: 53 passed (including 16 subtests).
Adjacent suites: 224 passed (97 subtests).
Full suite regression check:
- Base 324a0c8a: 28 failed, 6065 passed, 6 skipped.
- Head b0868be6: 28 failed, 6118 passed, 6 skipped.
- Exact 28 failing test identities are identical between base and head (zero new failures, zero regressions).

No PR merge was performed. Issue #963 and multi-client canary were untouched. MCP configuration was untouched.

Canonical PR State

STATE: ready-to-merge
WHO_IS_NEXT: merger
NEXT_ACTION: Merger validates approval and merges PR #976 at exact head b0868be6b3
NEXT_PROMPT:

Role: MERGER
Repo: prgs / Scaled-Tech-Consulting / Gitea-Tools
PR: #976
Issue: #975

1. Native MCP only on prgs-merger.
2. Verify PR #976 has valid approval from sysadmin at exact head b0868be6b34f03338dd9fb3c3eda65f42b0edca3.
3. Call gitea_merge_pr for PR #976.

WHAT_HAPPENED: Independently re-reviewed PR #976 at head b0868be6b3. Verified both blockers from review #652 were fixed, ran focused (53 passed), adjacent (224 passed), and base/head full suites (identical 28 pre-existing failures).
WHY: All acceptance criteria and blocker remediation requirements are satisfied with complete test proof and zero regressions.
ISSUE: #975
HEAD_SHA: b0868be6b3
REVIEW_STATUS: approved / approval_at_current_head
MERGE_READY: true
BLOCKERS: none
VALIDATION: Focused suite 53 passed, 16 subtests. Adjacent suites 224 passed, 97 subtests. Full suite base 324a0c8a 28 failed, 6065 passed, 6 skipped; head b0868be6 28 failed, 6118 passed, 6 skipped. Failure sets identical.
NATIVE_REVIEW_PROOF: transport=native_mcp; entrypoint=mcp_server; token_fingerprint=dee48dbfef52d19c
LAST_UPDATED_BY: sysadmin / prgs-reviewer

APPROVE — Independent reviewer re-review of PR #976 at exact head `b0868be6b34f03338dd9fb3c3eda65f42b0edca3` after remediation of REQUEST_CHANGES review #652. Reviewer: `sysadmin` / profile: `prgs-reviewer` Repo: `Scaled-Tech-Consulting/Gitea-Tools` Both blocking defects from review #652 have been completely resolved and independently verified: 1. **Blocker 1 — Environment recognition**: - `GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS` is individually named in `gitea_config.RECOGNIZED_GITEA_ENV_KEYS`. No broad prefix was added. - Nearby/unknown keys remain rejected with `unsupported-env:`. - `tests/test_issue_975_client_identity_heartbeat.py::test_server_consumes_exactly_the_recognized_key_names` asserts every production-consumed `GITEA_*` key. - Configured heartbeat interval reaches the production-started supervisor. - Client identity keys (`GITEA_MCP_CLIENT`, `GITEA_MCP_CLIENT_INSTANCE`, `GITEA_MCP_CLIENT_SESSION`) remain recognized. 2. **Blocker 2 — Production lifecycle wiring**: - `_active_worker_identity()` invokes `_start_worker_heartbeat()` upon successful worker registration. - Tests in `ProductionWorkerLifecycleWiringTests` exercise the production registration path directly against `GITEA_WORKER_REGISTRY_DB`. - Verified that repeated calls do not create duplicate supervisors or registry rows. - Supervisor receives exact registered identity, hints, and process attributes. - Fenced beat stops supervisor permanently and orderly shutdown is idempotent. - Heartbeat runs on a background daemon thread off the event loop. ## Test Verification - **Focused suite**: 53 passed (including 16 subtests). - **Adjacent suites**: 224 passed (97 subtests). - **Full suite regression check**: - Base `324a0c8a`: 28 failed, 6065 passed, 6 skipped. - Head `b0868be6`: 28 failed, 6118 passed, 6 skipped. - Exact 28 failing test identities are identical between base and head (zero new failures, zero regressions). No PR merge was performed. Issue #963 and multi-client canary were untouched. MCP configuration was untouched. ## Canonical PR State STATE: ready-to-merge WHO_IS_NEXT: merger NEXT_ACTION: Merger validates approval and merges PR #976 at exact head b0868be6b34f03338dd9fb3c3eda65f42b0edca3 NEXT_PROMPT: ```text Role: MERGER Repo: prgs / Scaled-Tech-Consulting / Gitea-Tools PR: #976 Issue: #975 1. Native MCP only on prgs-merger. 2. Verify PR #976 has valid approval from sysadmin at exact head b0868be6b34f03338dd9fb3c3eda65f42b0edca3. 3. Call gitea_merge_pr for PR #976. ``` WHAT_HAPPENED: Independently re-reviewed PR #976 at head b0868be6b34f03338dd9fb3c3eda65f42b0edca3. Verified both blockers from review #652 were fixed, ran focused (53 passed), adjacent (224 passed), and base/head full suites (identical 28 pre-existing failures). WHY: All acceptance criteria and blocker remediation requirements are satisfied with complete test proof and zero regressions. ISSUE: #975 HEAD_SHA: b0868be6b34f03338dd9fb3c3eda65f42b0edca3 REVIEW_STATUS: approved / approval_at_current_head MERGE_READY: true BLOCKERS: none VALIDATION: Focused suite 53 passed, 16 subtests. Adjacent suites 224 passed, 97 subtests. Full suite base 324a0c8a 28 failed, 6065 passed, 6 skipped; head b0868be6 28 failed, 6118 passed, 6 skipped. Failure sets identical. NATIVE_REVIEW_PROOF: transport=native_mcp; entrypoint=mcp_server; token_fingerprint=dee48dbfef52d19c LAST_UPDATED_BY: sysadmin / prgs-reviewer

sysadmin commented

2026-07-29 23:06:08 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #976
issue: none
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 87247-e2f79a754f1c
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr976-b0868be6
phase: released
candidate_head: b0868be6b3
target_branch: master
target_branch_sha: none
last_activity: 2026-07-30T04:06:07Z
expires_at: 2026-07-30T04:16:07Z
blocker: manual-release

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #976 issue: none reviewer_identity: sysadmin profile: prgs-reviewer session_id: 87247-e2f79a754f1c worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr976-b0868be6 phase: released candidate_head: b0868be6b34f03338dd9fb3c3eda65f42b0edca3 target_branch: master target_branch_sha: none last_activity: 2026-07-30T04:06:07Z expires_at: 2026-07-30T04:16:07Z blocker: manual-release

sysadmin commented

2026-07-29 23:25:13 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #976
issue: #975
reviewer_identity: sysadmin
profile: prgs-merger
session_id: 37587-b3cfa5c84021
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr976-b0868be6
phase: claimed
candidate_head: b0868be6b3
target_branch: master
target_branch_sha: 324a0c8a8d
last_activity: 2026-07-30T04:25:13Z
expires_at: 2026-07-30T04:35:13Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #976 issue: #975 reviewer_identity: sysadmin profile: prgs-merger session_id: 37587-b3cfa5c84021 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr976-b0868be6 phase: claimed candidate_head: b0868be6b34f03338dd9fb3c3eda65f42b0edca3 target_branch: master target_branch_sha: 324a0c8a8d76137b8466fe621b983c6ccf135be6 last_activity: 2026-07-30T04:25:13Z expires_at: 2026-07-30T04:35:13Z blocker: none

sysadmin merged commit 6596b259fc into master

2026-07-29 23:26:34 -05:00

sysadmin commented

2026-07-29 23:26:42 -05:00

Stale #332 review-decision lock cleanup (#594)

Status: APPLIED

actor: sysadmin
profile: prgs-merger
timestamp: 2026-07-30T04:26:41.756255+00:00
last terminal: approve on PR fix(runtime): recognize client identity environment and refresh worker registrations (#976)
PR state: closed (merged=True)
merge_commit_sha: 6596b259fcc00d4a58668b4bae813a08e843d4b4
prior live_mutations_count: 2
prior profile_identity: prgs-reviewer

Manual deletion of session-state files is not the workflow.
This path only clears a lock when the referenced PR is merged/closed.

## Stale #332 review-decision lock cleanup (#594) Status: **APPLIED** - actor: `sysadmin` - profile: `prgs-merger` - timestamp: `2026-07-30T04:26:41.756255+00:00` - last terminal: `approve` on PR #976 - PR state: `closed` (merged=True) - merge_commit_sha: `6596b259fcc00d4a58668b4bae813a08e843d4b4` - prior live_mutations_count: `2` - prior profile_identity: `prgs-reviewer` Manual deletion of session-state files is **not** the workflow. This path only clears a lock when the referenced PR is merged/closed.

jcwalker3 referenced this pull request

2026-07-30 00:29:42 -05:00

Canary: five concurrent LLM clients with a negative concurrency suite #963

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#976

fix(runtime): recognize client identity environment and refresh worker registrations #976

What was broken

1. Client-identity environment keys were not recognized

2. WorkerRegistry.heartbeat() had no production caller

What changed

Heartbeat lifecycle design

Scope guarantees

Files changed

Test results

Handoff

Blocker 1 — the PR adds a new production-consumed GITEA_* key that the allowlist omits, reproducing the exact defect being fixed

Blocker 2 — the production wiring that is the entire point of this PR has no test

Non-blocking observations

Verified sound, no change requested

Independent verification

Canonical PR State

Author remediation for review #652 (REQUEST_CHANGES)

Blocker 1 — GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS unrecognized

Blocker 2 — no production lifecycle wiring tests

Verification

Scope confirmations

Canonical Issue State

Review correction authorization audit (#693)

Test Verification

Canonical PR State

Stale #332 review-decision lock cleanup (#594)

2. `WorkerRegistry.heartbeat()` had no production caller

Blocker 1 — the PR adds a new production-consumed `GITEA_*` key that the allowlist omits, reproducing the exact defect being fixed

Blocker 1 — `GITEA_WORKER_HEARTBEAT_INTERVAL_SECONDS` unrecognized