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:
- ALL terminal is gated, not just writes. The enforcer's
GOVERNANCE LOCK REQUIREDfires on ANYterminal()call without an active lock — even a read-onlygrepof the update log.ls,grep,cat,git statusall blocked until you re-acquire. read_file/search_files/skill_vieware NOT gated. These are the escape hatch for inspecting output between the purge and your re-acquire.- 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 beforeend_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:
- Relock on error.
fleet-update.shinstalls_relock_enforcementas anEXITtrap — andfleet-dogfood.shhas 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 (badFLEET_DEPLOY_HOME→ rc=1) and watching all nine files come back----i---------e-------. - Relock after inactivity.
agent-remediate-apply.py(no_agent, every 10 min) self-heals at the top of every cycle, probinghermes-plugin-lock statusFIRST so the already-locked case costs onelsattrand no sudo.fleet_doctor --fixrelocks on a failingImmutable: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_issuekeeps 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_heartbeatruns on writes), not justcheck_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_stateis also the recovery for a lock stranded by a CRASHED close. A close that raises afterfeedback_acceptleaves the cycle scored-but-PENDING with the lock still held, and a repeatedend_changethrows 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 intask_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_stateretires 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 carriescancelled/suspendedand logs the reason intask_events, so the mis-framed task was retired through it (noforce, nouser_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;
activealone is only YOUR lock. A call with no args cannot resolve a session, soactivereportsfalsewhile another session's lock is live on disk — that field answers "do I hold a lock", never "is any lock held". The call also returnslocks+live_lock_countlisting every live lock (task, session, agent, repo, heartbeat): read those before concluding none exists, and when the lock FILE says active whileactivesays 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-EMPTYrepo_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 withrepo_pathEMPTY. Two locks can name the same slug by opposite routes — readrepo_pathto 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.pyprints 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_interruptioncannot 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 NEWbegin_changeunder the correct name (areframe_changetool would be the clean fix; until it exists, retire-and-reopen is the sanctioned path).- Order matters: do not
cancelbefore interrupting.request_interruptionrefuses a task already in a terminal state, so a cancel-then-interrupt sequence wedges. Interrupt (or reopen) first; checkTERMINAL_STATESbefore sequencing any state transition. - The TTL expiry is a real, usable exit. After a lock expires,
begin_changeunder 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_lockdoes not consult repo identity. Name the cause in the reason; the range is left without a receipt, so whoever pushes must close something.blockedis NOT a release. It is non-terminal, so it keeps holding the lock — parking a lock you cannot close withblockedis what turns a stuck cycle into a stuck repo. Fromblockedthe way out iscancelled(orplanning).- A zero-diff placeholder cycle is closed by SCORING it.
feedback_acceptwith anunscored_reasontakes it PENDING → MOVE_ON; "it can never close" is true ofend_changeonly, 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
rmof 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_ONcycle (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. Thenend_change— if the lock is already released it answers "nothing to release", which is fine. - The cheapest leak check is the gate itself:
begin_changeREFUSES while an unscored PENDING cycle exists and NAMES it, so a successfulbegin_changeis proof the host is clear and a refusal is proof it is not.cycle_querynames 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=Truethe only exit was the original bug). The leak this can leave is repaired by the resolver, byreclaim_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 ACTIONline, never a silentkept. - 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_cyclesinside atry/exceptwhose 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_changeflow). 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, orbegin_changewhile 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_changeor 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_changeruns 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_lockconfirms the purge (active: false) — expect this after every update runcycle_queryshows no PENDING cycles beforeend_changeend_changereturns 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 pitfallsfleet-preflight— pre-flight checks + fleet-update side-effect tableloop-governance— scoring internals, lock-lifecycle race history
04 同仓库更多 Skills
macbook-linux-maintenance
Legacy MacBook Linux fixes: GPU wedge, reboot hang, thermal.
governance-regression-triage
Triage a host's governance issues: what changed.
enforcement-immutability
Use when enforcement files lose their immutable flag.
steadfaste-fleet-repo-deploy
Use when committing to the steadfaste-fleet repo.
steadfaste-fleet-maintenance
Maintain an installed Steadfaste Fleet instance — update both the upstream Hermes Agent and the fleet repo layer, merge diverged histories, sync skills safely, and troubleshoot common issues. Covers the dual-update workflow (hermes update + fleet-update.sh), encrypted brain data backup, mycortex import, and recovery techniques.
fleet-preflight
DEPRECATED alias — merged into survey-before-action (2026-08-20). Load survey-before-action instead; its "Repo-Specific Pre-Flight" section covers git search, Hermes boundary, and deployment verification.