AGENT SKILL

governance-lock-lifecycle

Use when blocked after fleet update or end_change rejects.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 4
Forks
1

01 前言 Front Matter

name
governance-lock-lifecycle
author
Steadfaste Fleet curator
license
MIT
version
1.1.0
category
devops
metadata
{ "hermes": { "tags": [ "governance", "lock", "fleet-update", "loop-governance", "deploy" ], "related_skills": [ "loop-governance", "fleet-deployment-sync", "fleet-preflight", "two-hard-rules" ] } }
platforms
[ "linux", "macos" ]
description
Use when blocked after fleet update or end_change rejects.

02 资源文件 2

03 SKILL.md 正文

Governance Lock Lifecycle During Deploy Operations

Class of task: any session that runs fleet-update.sh (or any deploy that triggers purge-stale-governance-locks.py), then hits GOVERNANCE LOCK REQUIRED on a subsequent tool call, or finds end_change rejecting with "no scored cycle". Also covers the "pull latest → update → doctor → fix" loop.

The Core Mechanic

fleet-update.sh runs purge-stale-governance-locks.py at the END of EVERY run — it removes every .governance-*.json lock file, including your active session's lock. This is by design (Pitfall 4 in fleet-deployment-sync), but the blast radius is bigger than most agents expect:

  1. ALL terminal is gated, not just writes. The enforcer's GOVERNANCE LOCK REQUIRED fires on ANY terminal() call without an active lock — even a read-only grep of the update log. ls, grep, cat, git status all blocked until you re-acquire.
  2. read_file / search_files / skill_view are NOT gated. These are the escape hatch for inspecting output between the purge and your re-acquire.
  3. Each re-acquire creates a NEW pending cycle under the same task_id. Two re-acquires → three pending cycles total (original + 2). All must be scored before end_change() or it rejects.

The Working Sequence (verified 2026-08-03)

begin_change(task_id="pull-latest-fleet-update")     # cycle #1
git pull --rebase --autostash origin main
fleet-update.sh > /tmp/update-full.log 2>&1          # redirect UNDER the lock
                                                      #   ← purge fires, lock GONE
# terminal() now blocked — use read_file on /tmp/update-full.log
check_lock → active: false                            # confirm
begin_change(same task_id)                            # cycle #2 — REQUIRED before more terminal
... fix work ...
begin_change(same task_id)                            # cycle #3 if purged again
...
cycle_query(task_id=...)                              # lists ALL pending cycles
feedback_accept(id=N1, note=...)                      # score EVERY one
feedback_accept(id=N2, note=...)
feedback_accept(id=N3, note=...)
end_change(task_id=...)                               # only now succeeds

Pitfalls

Pitfall 1: Redirect capture must happen UNDER the lock

fleet-update.sh > /tmp/log 2>&1 is fine while the lock is active (the redirect is the point — it survives the purge). But a ;-chained command like fleet-update.sh > log 2>&1; grep ... can be classified as a write by the enforcer and blocked before it runs if the lock was already purged. Pattern to avoid: run the update, then try to grep the log in the same command — the grep half dies.

Pitfall 2: | tail -60 truncates the embedded doctor report

The update's output embeds the full doctor run (475+ lines: 268 pass · 9 warn · 2 fail · 3 info). tail -60 only shows the summary + REQUIRED ACTIONS, hiding WHICH checks failed. Always redirect to a file and read_file the whole thing — you need the per-check ⚠️/❌ lines to fix anything.

Pitfall 3: Score ALL pending cycles, not just the newest

end_change(task_id) rejects with "no scored cycle" if ANY cycle for that task is still PENDING. cycle_query(task_id) returns them all — iterate and feedback_accept each ID before closing. This is the #1 cause of the "end_change rejected" confession.

But a refusal that says the cycle is NOT scored while the ROW reads MOVE_ON is a stale module, not a missing score. The tell is in the refusal itself: it names the SAME cycle id you just scored, and cycle_query or the DB row shows decision=MOVE_ON with a non-zero composite and no unscored_reason. The close's scored-cycle precondition reads the store through the LOADED loop-governance module, and the in-process MCP child holds the revision it STARTED with — so a DISAGREEMENT between what the store says and what the close reports is a deploy-≠-load failure, and the doctor says so in its own REQUIRED ACTIONS: "Restart the gateway to load the new loop-governance module. Until then end_change may read a cycle as PENDING right after it was scored — a retry after a cycle_query is the workaround, not the fix." Exits, in order: run the close through the CLI adapter (it imports the module fresh on every call, so it reads current code right now), or respawn the MCP child and confirm a NEW pid before trusting the reload. Do NOT re-score the cycle, do not open a carrier cycle, and never force=True — all three treat a transport staleness as a store problem and leave the real cause in place. Corollary for diagnosis: the cycle row's timestamp is its CREATION time (the scoring UPDATE does not touch it), so a timestamp that predates your close attempts proves nothing about when the score landed — compare decision/composite, and keep the number of close attempts you spend on this to one.

Pitfall 3b: An end_change that TIMES OUT is not a verdict — read the store before reacting

The MCP call carries a 300 s client timeout, and a close that runs the self-adversarial review can exceed it. The timeout is client-side only: the scoring you did beforehand may already be in the store, the review may still be running, and the lock may still be held — so TimeoutError tells you NOTHING about the outcome. Read both before reacting: cycle_query(task_id=...) for the cycle's decision/composite, and check_lock for the lock. Measured: after a timeout the cycle row already read MOVE_ON with its composite recorded while the lock was still live and stamped executing; re-issuing end_change then returned the review's ACTUAL verdict (findings), which the timeout had swallowed. So do not re-score, do not open a carrier cycle, and do not treat the timeout as a refusal or as a success — re-issue end_change once and read the verdict it returns.

Pitfall 4: Doctor remediation hints may not match the real CLI

The doctor's REQUIRED ACTIONS print commands like Check: hermes cron logs --name agent-... — but logs is NOT a valid hermes cron subcommand and runs rejects --name. Valid subcommands: list, create, add, edit, pause, resume, run, remove, rm, delete, status, runs, history, tick. Pass the cron name positionally (hermes cron runs <name>), no --name flag. Don't burn cycles re-trying the doctor's literal suggestion.

Pitfall 5: The survey gate fires on ANY .py write, even throwaway

Writing /tmp/inspect.py triggers the domain-skill gate: "write blocked until test-driven-development loaded". Loading it satisfies the gate — it does NOT obligate a TDD cycle for a disposable inspection script (TDD's own exceptions cover throwaway prototypes). State this explicitly ("gate satisfied — disposable script, no test cycle") so the user isn't confused about why TDD was loaded.

Guarantees (2026-10-02) — the unlock can no longer outlive the run

The deploy unlocks each immutable enforcement file before overwriting it. Two guarantees make a leftover unlocked state self-correcting:

  1. Relock on error. fleet-update.sh installs _relock_enforcement as an EXIT trap — and fleet-dogfood.sh has its own, so the mandated pre-push gate does not depend on a CHILD script's trap for a security property. The relock runs on success, on error and on signal alike; a FAILED deploy no longer leaves the gate tamperable. Verified by failing a deploy on purpose (bad FLEET_DEPLOY_HOME → rc=1) and watching all nine files come back ----i---------e-------.
  2. Relock after inactivity. agent-remediate-apply.py (no_agent, every 10 min) self-heals at the top of every cycle, probing hermes-plugin-lock status FIRST so the already-locked case costs one lsattr and no sudo. fleet_doctor --fix relocks on a failing Immutable: check as well.

Consequences for an agent who finds a missing i flag: it is a symptom, not a task. Wait one cycle, or run sudo -n hermes-plugin-lock lock. Do NOT hand-lock individual files, and never "fix" it by weakening the check.

Pitfall 6: A cycle whose remaining deliverable is blocked by a THIRD PARTY has no sanctioned exit

The close gate scores complexity over the lock window and refuses to release the lock while a sufficiently complex change is unclosed. That is correct when the work is incomplete — but when the ONLY thing left is something you are forbidden to do (merge over another session's uncommitted files, edit a generated security artifact, or produce an authorization record that lives in the operator's own chat), the gate refuses forever, and each rereview_change is a fresh sampling call that returns new findings rather than closure. Two rules follow:

  • Do not re-roll the reviewer. Once a finding's remedy is impossible or contradicts the operator's explicit instruction, state that once with the evidence and stop: repeated re-reviews burn tokens and add findings without changing the blocker.
  • Record the blocker instead of forcing a close. record_issue keeps it tracked (give it a blocker/obstacle category); the work already committed and deployed stays landed. Never reach for a force or replace-lock route to escape it — an override is the operator's call, and asking is cheap.
  • Know how the lock actually clears: the TTL, not you — and only once you STOP WORKING. A lock ages out an hour after its last heartbeat, and ANY write-class tool call refreshes that heartbeat (_touch_heartbeat runs on writes), not just check_lock. So "wait out the TTL" is not available to the session still holding the lock: while it keeps working the lock never goes stale, and the wait the docs suggest can never arrive. Reach for a terminal state (Pitfall 8) instead of waiting. A scored (non-PENDING) cycle left this way is clean: the doctor's leak check does not fire. But no push receipt was written, so whoever performs the push must run its own close to write one. A held lock does not stop a second session acquiring its own, so the deferred work can proceed while yours waits.

Pitfall 7: "No sanctioned exit" is a claim to TEST, not a conclusion to trust

Before declaring a cycle unrecoverable, enumerate the tools that exist — the answer is often that the tool was there all along and a wrong assumption hid it. Verified 2026-10-10, one session — the four claims below are asserted by the committed, re-runnable test tests/test_governance_lock_lifecycle_claims.py (transcript: docs/evidence/governance-lock-lifecycle-claims/transcript.txt), which drives the deployed loop-gov-mcp.py directly:

  • advance_task_state is also the recovery for a lock stranded by a CRASHED close. A close that raises after feedback_accept leaves the cycle scored-but-PENDING with the lock still held, and a repeated end_change throws again rather than clearing it. A terminal transition (new_state="cancelled") releases it — the tool reports "a terminal task holds nothing" — and records the reason in task_events. Use that instead of a force/override, and say plainly in the reason what crashed, because the range then has no receipt and the next close must mint one.
  • advance_task_state retires a mis-framed cycle without an override. The user asked how to clear a cycle that kept being refused for scope drift. Reading the tool list settled it in minutes: the state machine carries cancelled/suspended and logs the reason in task_events, so the mis-framed task was retired through it (no force, no user_overrode) and the real work reopened under a correctly-named cycle, which closed CLEAN first try. A "no exit" assumption had already cost four refusals and an hour-long TTL wait.
  • Read the lock's FULL picture; active alone is only YOUR lock. A call with no args cannot resolve a session, so active reports false while another session's lock is live on disk — that field answers "do I hold a lock", never "is any lock held". The call also returns locks + live_lock_count listing every live lock (task, session, agent, repo, heartbeat): read those before concluding none exists, and when the lock FILE says active while active says false, the file is right — the close will succeed. Do not re-acquire and do not open a carrier cycle; that false negative manufactures the very extra cycle you were trying to avoid.
  • The lock's repo identity is legible in repo_path. A lock stamped from a git repo carries a NON-EMPTY repo_path; one opened where the cwd is NOT a repo (a plain working copy, a deploy dir) has nothing stamped, so it inherits the host-canonical slug with repo_path EMPTY. Two locks can name the same slug by opposite routes — read repo_path to tell them apart, and treat an empty one as "this lock does not govern the tree I worked in": the close gate composes review material from the named repo, so a mis-tagged lock gets reviewed against a tree that cannot contain the work. loop-gov.py prints a note naming the cwd and the repo it will claim when it cannot resolve one; run governance from inside the repo, or pass --repo <path>, rather than accepting the fallback.
  • request_interruption cannot rename a cycle — it derives the sub-task id by suffixing the parent's, so splitting work with it does not fix a mismatched task id. Renaming needs a NEW begin_change under the correct name (a reframe_change tool would be the clean fix; until it exists, retire-and-reopen is the sanctioned path).
  • Order matters: do not cancel before interrupting. request_interruption refuses a task already in a terminal state, so a cancel-then-interrupt sequence wedges. Interrupt (or reopen) first; check TERMINAL_STATES before sequencing any state transition.
  • The TTL expiry is a real, usable exit. After a lock expires, begin_change under the correctly-named task opens a fresh cycle. Waiting out the TTL is preferable to forcing a close on a mis-framed one.

General rule: when a gate refuses in a way that looks unbounded, the first move is to re-read the available tools and their parameters — not to re-roll the reviewer, and never to override.

Pitfall 8: A lock minted WITHOUT repo identity cannot be closed — only a TERMINAL state clears it

end_change refuses such a cycle with "Cannot close: no governed repo to measure complexity — the self-adversarial review cannot run", because the close composes its review material from the repo the lock names and this lock names none. Nothing ages it out (Pitfall 6: the owner's own work keeps it alive), so the lock outlives every retry. Releases:

  • advance_task_state(task_id=..., new_state="cancelled", reason=...) — terminal, and it reports "a terminal task holds nothing" because _release_lock does not consult repo identity. Name the cause in the reason; the range is left without a receipt, so whoever pushes must close something.
  • blocked is NOT a release. It is non-terminal, so it keeps holding the lock — parking a lock you cannot close with blocked is what turns a stuck cycle into a stuck repo. From blocked the way out is cancelled (or planning).
  • A zero-diff placeholder cycle is closed by SCORING it. feedback_accept with an unscored_reason takes it PENDING → MOVE_ON; "it can never close" is true of end_change only, and the remaining work is just the lock release above.
  • A different session cannot release it. Locks are session-scoped, so a later session cannot end_change or advance the lock a dead session left; only the TTL purge (or the operator's rm of the file) clears it. Say so rather than leaving the next agent hunting for a tool.

Diagnose before concluding: read the lock FILE and check repo_path / repo_slug; empty or absent identifies this class in one read.

Mint sites: any writer that builds a FRESH lock state instead of re-writing one that already carries the repo. Re-writers inherit the repo fields, so all 14 other lock-write call sites are unaffected — and when you fix one fresh-state writer, pin it with a test asserting the state it hands to the writer carries repo_path AND repo_slug. Such a lock also creates no claimable task row, so a promotion that mints one leaves a lock, a cycle and an event but nothing to claim.

Which refusals free you — and why a freed lock must come with a resolved cycle. A refusal about the LOCK'S METADATA (the lock names no repo, or names a repo this session is not working in) judged nothing: no diff was read, no verdict exists, and no receipt is written on that path, so holding the lock authorises nothing while dead-ending the session that holds it — and the sessions queued behind it. Current builds RELEASE the lock on those refusals and close the cycle UNSCORED (MOVE_ON plus a reason naming the refusal), which makes the terminal-state route above the path for a lock left by an older build or a crashed close rather than the only way out. A verdict about the WORK (findings, reviewer unavailable) is different in kind: the close is refused and the lock is released so you are not trapped, but the range still needs a CLEAN receipt before it can be pushed — so re-check the receipt, do not re-close to "clear" it.

Any change that frees a lock must resolve its cycle in the same step. The doctor counts a PENDING cycle as EXPECTED while a live lock exists and as a leak FAIL the moment the lock is gone, and ANY doctor FAIL blocks the push for every agent on the host — so releasing alone converts one session's dead-end into a host-wide block. Before "recovering" a cycle you believe is PENDING, read what the score reports: MOVE_ON → MOVE_ON means something already resolved it, so your scoring was a no-op rather than the fix, and the remaining problem is elsewhere.

There are TWO lock-removers, and each needs its own audit. The MCP releases locks on refusals; the standalone purge-stale-governance-locks.py (run by every deploy and by a cron) unlinks stale files. Fixing one does not fix the class — grep both files for every site that unlinks a lock or makes a task terminal, and check each against the invariant above. The sweep also had a SECOND divergence: its staleness rule was TTL-only, with none of the liveness rescue the MCP predicate gained, so it would happily remove a busy session's lock (heartbeat frozen through hours of editing, no governed call) and that session's next write was refused — the deadlock the rescue exists to remove. A second copy of a predicate is a second rule: when you touch either path, compare the PREDICATE (not just the removal) against the fleet's, and pin the comparison with a test.

Removing a lock and resolving its cycle are ONE step — and two details of the ORDER trap you

  • Resolve the cycle BEFORE unlinking the file. A crash between the two must leave a DEAD lock beside a MOVE_ON cycle (harmless, and the next sweep removes the file) and never a lockless PENDING cycle, which blocks every push on the host with no owner left to clear it.
  • Close through the PER-TASK closer, never through an orphan-cycle resolver. The resolver's own precondition is "this task holds no live lock", and at the moment you are about to unlink, the file is still on disk — so routing the close through it closes NOTHING and the leak you set out to remove survives, while the code reads as if it did the work. Prove it with a probe on a throwaway state dir; do not accept the call site by inspection.
  • A cycle whose work was CANCELLED is closed with no score invented. feedback_override (→ MOVE_ON) records that nothing landed; scoring it would claim work that does not exist. Then end_change — if the lock is already released it answers "nothing to release", which is fine.
  • The cheapest leak check is the gate itself: begin_change REFUSES while an unscored PENDING cycle exists and NAMES it, so a successful begin_change is proof the host is clear and a refusal is proof it is not. cycle_query names them directly.
  • When a release path is added, add it to the sweep test's enumeration. A class-level rule ("every site that drops a lock also resolves its cycle") is held by a test that FAILS on any NEW call site which omits the paired action, with each exemption declared and its justifying gate asserted against the source.

The sweep's disposition differs from the MCP's ON PURPOSE — do not "unify" them

When the cycle cannot be resolved, the MCP still releases the lock and the sweep KEEPS it. Both are right, and the reason is what each caller's alternative costs:

  • MCP release paths release anyway — a live session must never be dead-ended by a broken store (no release, no path forward, force=True the only exit was the original bug). The leak this can leave is repaired by the resolver, by reclaim_dead_locks, or by the >24h auto-resolve.
  • The unattended sweep keeps the lock — nothing is waiting on it, so a stale file on disk costs nothing while the lockless PENDING cycle it would create blocks every push on the host. It escalates instead: exit code 2 with an OPERATOR ACTION line, never a silent kept.
  • A permanently failing fail-closed path needs an exit code, not a log line. Silence on a broken store is how a repairable host becomes permanent: a cron that always exits 0 turns a dead DB into background noise. Give the could-not-do-my-job outcome its own non-zero code and say who must act.
  • A lock file that is unparseable AND well past the TTL is corruption, not a mid-write race. The mid-write guard (never delete an unparseable file) is right, but a file in that state for hours can never be aged, so it and any cycle behind it sit forever. COLLECT those and report them for cleanup rather than skipping them silently every run.

Minting a lock is the MIRROR of removing one — the cycle must exist FIRST

The removal rule ("removing a lock and resolving its cycle are ONE step") has a twin that is easier to miss because it lives on the happy path: a lock is only ever written AFTER the cycle it names exists in the store. Get the order wrong and the failure is the worst kind — the operation reports SUCCESS while leaving a live lock whose task has no scorable cycle, which is unclosable, unfreeable by begin_change, and escapable only by an override.

  • Create the cycle first, then write the lock; REFUSE the operation if the create fails. A refusal is recoverable in seconds; a lock with no cycle costs the session and everything queued behind it.
  • Never let the cycle create fail SILENTLY. An inline INSERT INTO loop_cycles inside a try/except whose fallback is a note like "(note: no cycle record — DB unavailable)" is the bug: on a transient DB error the caller gets a lock AND a success message. The create must raise into a refusal.
  • A second copy of the CREATE is a second rule. Hunting the class means grepping every lock-writing path for its OWN inline cycle insert — fixing one writer leaves the identical ordering bug in a sibling tool (an ISSUE-PROMOTION path is the classic second copy, because it builds a fresh task outside the normal begin_change flow). Prefer ONE shared _create_pending_cycle(task_id, session_id, outcome) helper called by every mint site; two implementations drift.
  • Pin the invariant per mint site, not once for the file. The test should assert the cycle-create call appears BEFORE the lock write in EACH function that mints, so a NEW call site that omits it fails the suite. A class-level rule held by one site's test protects one site.

The tell, for diagnosis in the field: end_change answers "no governance cycle found for this task" while begin_change answers "a governance session is already active … use force=True". Both messages are correct about different stores — the LOCK exists, the CYCLE does not — and that pair is the signature of this class, not a scoring problem. Re-score nothing; check whether the lock's task has a cycle row at all, then free the lock (a terminal transition) and fix the ordering in the code that minted it.

A session that resolves NO repo is UNGOVERNED, not lock-blocked — say so, and make recovery one step

Governance is REPO-SCOPED: a lock binds to a repo, so a call that resolves no repo cannot be authorised by ANY lock. When the gate refuses such a call by telling the agent to "acquire a lock", that is an impossible demand, and it becomes a LOCKOUT: the agent cannot mint the lock, and it cannot run the compound it needs to find the checkout, because a compound is write-class. Read-only primitives stay free, so orienting is still possible — the failure is the refusal's framing, not the rule.

  • Resolve the repo from the SESSION, not only from the call's arguments. A command like git commit -m … carries no path of its own, so path-argument resolution returns nothing and the call falls through to slug matching alone. Fall back to the repo the session already recorded from an earlier call's arguments — the same repo it has been working in, not a new permission — before concluding there is none.
  • With no repo, refuse in its OWN words. Say that governance is repo-scoped so no lock could authorise the call, then name the escapes that actually work: pass the repo on the call (workdir=<path>), make the command's own path point inside the checkout, or begin_change while working in it. Add that read-only commands never need a lock, so they can be used to find the checkout. A generic "this repo requires an active governance lock" when there IS no repo makes a dead end look like policy — and the agent loops on the same blocked command.
  • A gate/plugin fix is not live until the process that LOADS it restarts. Handing a fleet fix over means naming BOTH steps for the affected host: update (pull the file) and restart (load it). A corrected enforcer on disk changes nothing in a running gateway, and the host stays blocked while everything looks fixed.

Pitfall 9: begin_change SUCCEEDS yet every write still deadlocks — the injection is tool-PREFIX-bound

The enforcer stamps session_id + repo_path into governance MCP args by matching the TOOL NAME prefix (tool_name.startswith("mcp__<name>__"), two matcher sites). Renaming the review MCP server (or any server the enforcer injects into) without updating those matchers silences the injection: the server falls back to its own derivation (env/per-repo file) and mints locks under a different id than the enforcer expects. Signature: a fresh begin_change reports success and a lock FILE exists, yet every write-class tool still refuses with GOVERNANCE LOCK REQUIRED. Diagnose by comparing ~/.steadfaste-fleet/state/.hermes-session-current.id (the enforcer's canonical id) with the lock file the fresh begin_change just wrote — different ids, and the enforcer can never see that lock. The CLI with an explicit session_id is the recovery: drive python3 ops/scripts/loop-gov.py begin_change '{"session_id": "<id from .hermes-session-current.id>", …}' through a composite tool the gate does not hook (terminal itself is refused — the gate is the broken thing), then fix the real defect: add the new prefix to both matchers, pin RED→GREEN with a test driving _inject_session_context under the new name, deploy, reload/restart; retire any lock minted under the derived id with advance_task_state new_state=cancelled. Full recipe: rename-sweep → references/mcp-server-name-rename.md.

Pitfall 10: A session's governance identity can FREEZE onto the wrong repo — the exit is a FRESH session

Governance is SESSION-scoped. The session id arrives from the Hermes conversation (kwargs['session_id'], README "Session ID Handoff Architecture") and the governed repo is resolved from that session together with the call's cwd/args. A session that once resolved the WRONG repo can therefore re-tag that same wrong repo on every later begin_change — so the failure is whole-session, not one bad call: the lock's repo_path/repo_slug name a tree that is not yours, the agent identity can read unknown, and work in the correct repo keeps being governed against the wrong one.

  • Try the sanctioned escapes first: run governance from inside your checkout, or pass a workdir / --repo <path> that points into it, so the call resolves the right repo on its own terms before you conclude the session is stuck.
  • A restart is NOT a remedy. The identity is keyed to the conversation session, not to the process, so restarting the gateway or the host does not clear it. Do not burn cycles re-running begin_change or rebooting, expecting a different tag.
  • The reliable exit is a NEW conversation (/new). A fresh session mints a clean session id and re-resolves the repo from scratch. Before you leave, record the frozen session's state — SHAs, and anything left STAGED (a staged change survives in the index and the next session can commit it) — so the follow-on session finishes the work instead of rediscovering it.

Pitfall 11: The loop-gov daemon doctor WARN re-fires after EVERY fleet-update — only a gateway restart clears it

The doctor's loop-gov daemon check verifies the running loop-gov MCP daemons by CONTENT: each daemon records a stamp (~/.steadfaste-fleet/state/loop-gov-daemon.json) that holds ONE pid plus the sha256 of the module it loaded. Two daemons run (review and loop-governance roles) but only the last one to start owns the stamp slot — the other daemon can never be content-verified and falls back to mtime-vs-start comparison. fleet-update.sh force-rewrites every mapped file, so loop-gov-mcp.py's mtime advances past both daemons' start even when the bytes are byte-identical — after EVERY deploy the unstamped daemon reads "COULD NOT VERIFY by content" and the WARN re-fires no matter how recently the gateway restarted. The check only passes while the module mtime predates the daemon start, i.e. after a gateway restart that follows the last deploy. So: read the WARN as a deploy artifact, not stale code; clear it with hermes gateway restart after the final deploy; and never hand-edit or fabricate the stamp file — the check is only meaningful if the daemon itself wrote it. Root cause is the single-slot stamp: the durable fix is a per-pid stamp map so every daemon is verified by content and the byte-identical rewrite stops re-warning.

A wide close judges a WAVE of blobs per pass — concurrency, never a longer window

A close refused with "N blob(s) of the push range still carry no review verdict" names the exact remaining files. The per-blob pass now issues a wave of BLOB_REVIEW_CONCURRENCY (4) reviewer calls CONCURRENTLY, and because elapsed time is the SLOWEST call rather than their sum, four calls of 180–220 s land inside the same ~240 s window. Measured: a four-file change closes in ONE pass, and a 15-file range in four round trips where it previously took fifteen. Verdicts are keyed by blob CONTENT, so each pass resumes from where the last stopped instead of redoing judged work. Re-issue end_change until it reports the session closed — the counter must decrease (by up to the wave size), and a repeat that does NOT decrease is the real signal something is wrong. Do not read the repetition as a broken loop, and do not widen the review range to shorten it.

A blob judged NOT clean must CHANGE content — re-issuing on identical bytes returns nothing. The close reads "no blob was SENT this pass ... re-reviewing identical bytes cannot produce a different verdict". That is the save-and-stop signal, not a hang: fix the file so it is a NEW blob, commit the fix (a partial git commit -m msg -- <paths> — the shared-index hook refuses an un-scoped bare commit), then re-issue end_change. The committed fix is judged on its own and the close continues from there. Do NOT re-roll the reviewer on unchanged material and do NOT open a carrier cycle — neither produces a different verdict.

A reviewer finding on a TEST is often a real lesson: fix the test, not the production code. The tell is a meaningful finding that names exact lines in the test file (e.g. a test mutates os.environ without restoring it). The fix is the test using the fixture (monkeypatch.setenv, which restores in a finally regardless of assertion outcome) — shipped as its own small commit, so it is a new blob for the close. A dependent-classes finding ("the function is in the sibling file") may be a false positive the reviewer itself tells you to downgrade to info-level — read the finding's own recommendation before treating it as a blocker.

Do NOT raise the MCP client ceiling to shorten it. This skill used to call that "the lever that actually shortens it", and that is wrong twice over: the operator's standing requirement is that reviews stay under 300 s — the module records it verbatim, "the window is never raised" — and it would not have helped anyway, because a sequential pass already spent its whole window on ONE call. Concurrency is what fits several blobs per round trip, with the same reviewer, the same prompt and the same verdict. Raising a THRESHOLD (blobs per window, the wide-diff split line count) buys passes by reviewing less and is a governance reduction. More per call, never less per blob.

Judging a lock dead

The predicate is "heartbeat past the lock's own TTL AND no evidence the agent is working". Three rules make the second half safe, and all three are load-bearing:

  • Scope the liveness evidence by AUTHOR, not by repo. A commit authored by the lock's own agent counts; a peer's commit in the same repo does not (that would only delay the peer's own takeover, which is the deadlock again). Scoping by repo ALONE is the trap: a session doing a long stretch in a DIFFERENT checkout authors nothing in the lock's repo, so it gets judged dead while it is holding the lock right now. Look across the candidate repos under HOME for that author.
  • The widening is safe only because the renewal budget bounds it (LIVENESS_MAX_RENEWALS) — do not report the widening as harmless on its own. The budget is PER ACQUISITION, which is a dependency you must verify, not assume: a new acquisition builds a FRESH lock state, so the counter starts at 0. If a release/re-acquire cycle left the counter at its ceiling, the bound would be a one-time gate instead of a per-session limit.
  • Authorship is not identity. A cron or daemon committing AS that agent (or --author=) is indistinguishable from the session and reads as proof of life. The failure mode is a lock kept alive for a session that is gone, bounded to ONE renewal past the TTL — say that trade-off in the docstring rather than claiming the check is sound, and name the stronger signal you would want (a per-session token the enforcer injects, which cannot be forged like a git author).

Testing governance helpers

  • Never drive an entry point whose PRECONDITIONS consult live state to assert one branch. begin_change runs the dogfood check and the unscored-PENDING-cycle check before the refusal you want to test, so the assertion ends up measuring the host (a dirty tree or an open cycle fails a message test). Extract the decision/message into its own function and drive that — and assert BOTH directions: the repo-less lock gets the terminal-state guidance, a normal lock still gets the ordinary "call end_change".
  • Write lock fixtures with the module's OWN writer (_write_lock(state, {"session_id": sid})), never a hand-built path: the path helper need not share the global you swapped, so the entry point starts a NEW session and the test passes while measuring the wrong subject.

Verification

  • check_lock confirms the purge (active: false) — expect this after every update run
  • cycle_query shows no PENDING cycles before end_change
  • end_change returns success (no rejection)
  • Doctor overall line eventually shows the reduced warn/fail counts

Related (user-owned, may need hermes curator adopt)

  • fleet-deployment-sync — deploy mechanics, invocation forms, immutable-file pitfalls
  • fleet-preflight — pre-flight checks + fleet-update side-effect table
  • loop-governance — scoring internals, lock-lifecycle race history

04 同仓库更多 Skills