steadfaste-fleet-repo-deploy
Use when committing to the steadfaste-fleet repo.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 4
- Forks
- 1
01 前言 Front Matter
- name
- steadfaste-fleet-repo-deploy
- version
- 1.0.0
- category
- devops
- platforms
- [ "linux", "macos" ]
- description
- Use when committing to the steadfaste-fleet repo.
03 SKILL.md 正文
<!-- Provenance: renamed from skills/devops/hermes-cortex-repo-deploy/SKILL.md on 2026-11-12 (hc→fleet brand sweep, commit 2dc01b0e). Content predates the range; the range swept the brand tokens only. -->
Steadfaste Fleet Repo — Deploy & Push Gates
Workflow for landing changes in ~/steadfaste-fleet (shared public repo). The
repo's own AGENTS.md governs governance mechanics; this skill carries the
deploy-order and manifest pitfalls that cost time when missed.
Push sequence (gates run in this order)
-
git pull --rebase origin main— REQUIRES a clean tree. ANY unstaged change blocks the rebase AND the push's built-in dogfood — your own edits included, not just a peer's. Stash the specific blocking files by name (nevergit stashbare), rebase/push, thengit stash popimmediately — pop your own files back FIRST so your edits are restored before the next step. Never stash, clean, or commit a peer's work, and never stage a file you did not edit.Never let a rebase run over unpushed commits. With local commits ahead of origin, or on a conflicted rebase,
pull --rebasemoves HEAD to origin and leaves the repo mid-rebase: the local commits drop out of HEAD and survive only in the reflog, while the working tree reverts to origin. The same hazard lives inside tooling — a pre-push gate that pulls for you can orphan your work the moment it fails. Recover withgit rebase --abort(restores the pre-rebase HEAD exactly); do not re-author the commits. Before pulling on a working branch, checkgit log --oneline origin/main..HEAD: if it lists anything, SKIP the pull — the local work is precisely what you are about to verify and push, so it must not be rebased under. -
git pushruns a doctor gate — it fails on ANY doctor ❌. Most common blocker:Deploy sync/Checksum: <file>FAIL because the deployed copy predates the pushed commit. Fix by runningfleet-update.sh, re-running the doctor (expect 0 fail), then retrying the push. Never bypass. -
After the push lands, run
fleet-update.shonce more so the deployed tree includes the just-pushed commit (the push gate's internal deploy can trail the newest commit).
The push also runs an always-review RECEIPT gate
git push refuses a range that touches an always-review path unless a CLEAN review receipt
exists for it (expected receipt: <state>/.reviewed-<slug>-<tip>.json). The receipt is keyed
by the TIP SHA, and the range spans origin's tip..HEAD — which has consequences that are not
obvious:
- A rebase invalidates it.
git pull --rebaserewrites SHAs, so a receipt written for the pre-rebase tip no longer matches the gate's expected filename. On a shared branch the rebase rewrites a PEER's unpushed commits too, so their receipt coverage dies with yours (their content survives; say so explicitly when you report it). Getting back requires a cycle that ENDS at the new tip and returns CLEAN from a real review — the receipt is written at close. fleet-dogfood.sh --forcecannot produce a receipt. It only passes--force-allto the deploy (a full re-deploy); it runs no review. There is no sanctioned way to re-review a CLOSED cycle either —record-review.pyis the raw sink the reviewer writes to, and the review-queue sweep never touches overrides. Never manufacture a receipt and never use an override: that gate is what keeps an enforcement change from shipping unreviewed.- The range includes a peer's commits, so when they touch an always-review file the review must cover the whole range, not just your own commits.
Run the deploy as the LAST step before the push. Any commit made after a deploy leaves
the deployed marker stale and the gate returns Deploy sync ❌ however clean your doctor
ran minutes earlier. Do both in ONE command, nothing in between:
bash ~/.steadfaste-fleet/scripts/fleet-update.sh > <log> 2>&1; git push origin main.
An operational cycle cannot carry evidence of its own success — commit the CHECK
The push is LAST, so a transcript of it can only be written afterwards; that commit changes
the tip, invalidating the per-tip receipt (above) and leaving the deployed tree trailing so
Deploy sync returns ❌. Reviewers are right to demand committed evidence, and the ordering
rules keep destroying it — committing more evidence repeats the loop.
Break it by committing a RE-RUNNABLE CHECK before the push, never a transcript:
python3 ops/scripts/manage/verify-landed.py --repo . [--base <rev>] [--no-remote]
It asserts (1) a CLEAN receipt for the tip, (2) every file the range changed that has a
deploy-map entry matches its DEPLOYED copy, (3) origin/<branch> == tip; it exits 0 / 1 (a
real mismatch, named) / 2 COULD NOT VERIFY, and prints no path on failure. A later reviewer
re-runs it against the state that exists AFTER the push, so the evidence cannot go stale and
needs no second commit.
Measure the checker before trusting it. On its first real range this check reported three false FAILs: it hashed deployed copies RAW, and the deploy's header (inserted after the shebang, closed by a blank line) makes the two sides differ by construction. When a check disagrees with an otherwise-green gate, print the FIRST DIFFERING LINE of the two bodies instead of assuming either side is wrong, and pin the real shape with a test.
A failed deploy: read the log's FIRST line, and check the lock after
fleet-update.sh sources the host env early, so a broken env file kills the run
before any deploy work and the exit code says nothing specific. Diagnose from the
log's first line, not the exit code:
rc=127whose entire output is.../.env: line N: <token>: command not found— the env file is CORRUPT, not the script. A comment line that lost its leading#makes the shell execute the remainder (a bare date fragment is the usual first token). Inspect structure WITHOUT printing values: report each line's key (text before the first=) with its length, and list the lines that are neither blank, nor start with#, nor contain=. Watch for one absurdly long line — a botched append glues a whole blob onto line 1 with no newline, so the header comment swallows kilobytes while every real key still sits on later lines. Repair is surgical and lossless: restore ONLY the damaged leading lines from the newest.env.bak-*, leave the rest byte-for-byte, then confirm the key count is unchanged and the mode is still0600. A corrupt env breaks EVERY deploy on that host, so treat it as urgent.- A quote/EOF error naming a line BEYOND the file's length is not a static error in that
file.
bash -n <script>passes on it — that pass is not a contradiction, it is the tell: bash numbers lines in whatever unit it is reading at that moment, so the reported line can never be the file's own. The failing text is an eval'd or generated fragment, or a file REWRITTEN while it executes (a deploy that syncs the very script it is running). Do not go editing the script to "fix" a syntax error that is not there: capture the run's WHOLE output to a file (never a pipe totail, which destroys the one artifact able to identify the unit) and re-run — a transient rewrite failure does not recur. ✗ Not a git repository: <path>— a git WORKTREE has a.gitfile, not a directory, and the script's repo check rejects it. Deploy from the primary working tree (or setREPO_DIR=); a session worktree can hold the work and push, but it cannot deploy.
After ANY failed deploy, check the enforcement files before doing anything
else — a run that dies after unlocking leaves them modifiable. sudo -n hermes-plugin-lock lock relocks every target in one call, and the doctor's
Immutable: lines are the authoritative confirmation.
Quoting in commit messages
Never put backticks in a shell-quoted commit message: the shell substitutes them
before git sees the text, mangling the message and leaking fragments onto the
command line. Observed consequence: an empty file literally named = was created
at the repo root, tracked, and flagged as scope drift by the reviewer before I
noticed it. Write the message to a FILE and use git commit -F <file> for any message, not only
one containing code formatting: the command is scanned as a whole, so a policy that
pattern-matches command text can refuse the entire commit over words in the MESSAGE
(a gateway-lifecycle guard rejecting a message that merely mentions a restart), and
the refusal names the command rather than the cause. Then run git status --short
and check for surprise paths before pushing.
Restoring a file you swapped in: git checkout -- restores the INDEX
To reproduce a failure against an older revision you may copy that revision over a working
file (git show <rev>:<path> > <path>). Restoring it with git checkout -- <path> gives
back the index copy, not the working tree — so any edit you made but had not staged is
silently discarded, and the command reports success. Observed: a comment fix was reverted
this way, and the commit that followed carried only the evidence file, so the reviewer's
finding it addressed came straight back on the next close.
- Copy the file aside FIRST (
cp <path> <scratch>/mine.py) and restore from that copy, or usegit checkout HEAD -- <path>when HEAD's version is the one you want. - Then grep for the edit before committing. A clean
git statusproves nothing here: a discarded edit leaves the tree cleaner, not dirtier.
Never ASSUME a deployed path — resolve it; never let a fallback carry a conclusion
The deployed path of a repo file CANNOT be derived from the repo path: 192 of ~289
register() entries follow no rule (see the header of ops/scripts/fleet_lib/paths.py).
A probe that mirrors the repo layout under the deploy home therefore checks NOTHING, and
paired with 2>/dev/null || echo "<conclusion>" it prints that failure AS a finding — this
is how the line "0 (deployed copy predates this commit)" reached a committed evidence file
while the deployed copy in fact already carried the change.
- Ask the map, never guess:
python3 ops/scripts/manage/deployed-path.py <repo-relative-path>prints the deployed destination (fromdeploy-manifest.tsv, generated from the register() lines) and exits 0 / 2 (no entry) / 3 (entry present, nothing at the destination). On a failure it prints NO path — there is deliberately no fallback value to mistake for an answer. - A repo copy is NOT the deployed copy. Check the two separately and say which you ran; a green check on the repo side proves nothing about what a host runs.
- Never let a fallback string carry a conclusion. If a check cannot run, print
COULD NOT VERIFY and exit non-zero.
|| echo "<something plausible>"converts a broken probe into durable "evidence", which is worse than having none.
Edit the REPO source, never the deployed tree
fleet-update.sh copies every register() source over its deployed destination,
and the deployed file says so in its own header (# SOURCE: <repo path> /
# Do NOT edit this file). An edit aimed at a deployed path SUCCEEDS silently and
looks right — the file is right there, and every test still passes, because the
tests import the REPO tree. The next deploy reverts it, since repo → deployed is
the only direction a deploy copies.
On an IMMUTABLE target the write does not even succeed — the enforcement surface
(the enforcer plugin, the git hooks, the loop-governance MCP server) carries the
kernel immutable flag, so a direct write fails with PermissionError: [Errno 1] Operation not permitted, or EPERM from a shell. That is the write-protection layer
working, not a permissions bug to escalate: you are editing the wrong side. Verify
with lsattr <deployed path> (expect ----i---------e-------, see
enforcement-immutability), then put the change in the REPO source and let
fleet-update.sh deploy it — the deploy owns the unlock/relock around the copy, so
it is the only sanctioned way to change one. A cp/python write to a deployed path
is the same wrong move whichever way it fails, loudly or silently.
- Patch by REPO path only. Anything under
~/.steadfaste-fleet/is an artifact; the editable twin is~/steadfaste-fleet/ops/scripts/…. Apatchcall resolves the path it is given, so a deployed path applies cleanly and gives no hint it will be thrown away. - The deploy's drift guard is the backstop, and it fails CLOSED. When a deployed
file differs from its source the run stops with
Copy the deployed changes to the repo source first, then commit(one line per file) and the doctor reportsDeploy syncFAIL. That is the guard working: a blind overwrite would destroy whichever side would lose. Resolve it by making the REPO carry the change and deploying again — never by copying the deployed file over the source, which discards the edits already in the source. - Work out which side is ahead before choosing a direction. The deployed header is NOT a
fixed block at the top: the deploy inserts it AFTER the shebang (
# SOURCE:then# Do NOT edit this file), and the block is closed by a BLANK line. Sotail -n +4misaligns the comparison — it drops the shebang and keeps the blank, and the diff shows a difference that is not there. Remove the header LINES and compare what remains; better still, do not hand-roll the comparison at all —python3 ops/scripts/manage/verify-landed.py --repo .compares every changed deploy-map file against its deployed copy and names any real mismatch. Edits only in the deployed copy must be synced INTO the repo; edits only in the repo just need a deploy. - After deploying, confirm the deployed file actually took the repo's version —
the same
diffabove returning nothing — before reporting the change as live. A deploy that printedrc=0also prints drift warnings for files it did NOT sync; read the run's summary, not just its exit code.
New shared module → register() entry in the SAME commit
A new module that an existing deployed script imports (e.g. a helper under
fleet_doctor/) must get its own register() line in fleet-update.sh,
placed next to its importer's. register() copies ONLY listed files — a
missing entry makes the next deploy break every importer with
ModuleNotFoundError: No module named '<module>' at the deploy's verification
step. Symptom to recognize in the deploy log; fix by adding the entry,
deploying, re-running the doctor.
The same rule covers a script the deployed code loads by path at runtime
rather than importing (importlib.util.spec_from_file_location, a subprocess
call, a plugin lookup): the loader finds nothing on hosts, so the feature is
silently absent there while it works perfectly in the repo. Register both the
script AND every file it resolves relative to itself — a config beside it
(Path(__file__).parent / "<name>.yaml") is not deployed by registering the
script alone. A loader written to try the repo path first then the deployed
path will pass every local test and fail only on hosts.
Note importlib.util.spec_from_file_location returns an Optional: guard
spec is None or spec.loader is None before module_from_spec, or a bad path
becomes an AttributeError at the first call instead of a clean skip.
A CLI ENTRYPOINT is the third shape of the same rule. A script the fleet is told to RUN from the deployed path (an agent-side tool, a reply primitive, a maintenance command) is imported by nothing, so a missing register entry breaks no import and no deploy step — the host simply has no such file, and the whole suite stays green because the tests load it by REPO path. The feature is not "silently degraded" here, it is absent: the documented way to do the job does not exist on any host. Add the register line beside its siblings and pin it with a test that asserts the entry AND the exact destination AND the premise (that its test still loads it from the repo — that is what makes a green suite uninformative). Then run the DEPLOYED copy before reporting, and say which path you exercised.
The commit-time audit WARNS about a missing register entry — it does not block. The
audit prints the exact line to add (register "<source>" "<destination>") beside
NEW file … is not registered, and the commit still lands, so a feature can ship with a
green suite, a green commit and committed evidence while the tool simply does not exist on
any other host (the tests load it by REPO path, which is precisely why the suite says
nothing). Treat that audit line as a gate rather than as noise: add the entry in the same
cycle it names the file, and after deploying, exercise the DEPLOYED path — not the repo
copy — before reporting the tool as available to the fleet.
Guard register-vs-directory agreement, and verify on the DEPLOYED tree. The repo's
tests import the REPO tree while the host runs the DEPLOYED tree, so a module that is
committed, imported by a deployed script, and never registered keeps a GREEN suite while
the host dies at startup (observed: RuntimeError: fleet_bus queue.py not found (bus core missing) out of bot_locks, whose loader probes ~/.steadfaste-fleet/queue.py — so that
DESTINATION, not just some deployed copy, is the contract). Assert agreement in BOTH
directions (an unregistered module; a register entry whose source no longer exists), assert
the guard's PREMISE (that the deployed script really does import what it protects), and add
a control that fails on a wrong destination — a guard that cannot fail is
indistinguishable from one that is not looking. Then exercise the deployed copy, not the
repo one, before reporting the fix.
A register entry in fleet_gateway/ must be a .py module. The guards compare
registered against fleet_gateway/*.py in BOTH directions, so registering a shell
helper beside the modules makes the reverse check fire —
register names files that do not exist: ['<x>.sh'] — even though the file is right
there, because the module glob only ever yields .py. Shell runners and evidence
scripts in that directory are therefore repo-only, exactly like the existing ones:
leave them out of the register and run them from the repo (they read the DEPLOYED
tree, so running them from the repo still tests what the host runs).
A new register entry changes numbers the suite asserts. docs/deploy-registry-pattern.md
quotes the register-map total, the derivable count and the no-rule count, and a test
recomputes all three from fleet-update.sh. Adding one line fails that test until the
doc is updated — do it in the SAME change, and derive the numbers from the script rather
than adjusting the old ones by hand.
Editing fleet-update.sh itself
- Insert failure-recording code AFTER
local -a _DEFERRED_FAILURES=(). The array is declared mid-function (after the skills sync, not at the top), and the script runs underset -u: an_DEFERRED_FAILURES+=(...)on an earlier line aborts the whole update with an unbound-variable error instead of deferring the failure it was meant to report. Place the new per-host steps in that same region and DEFER on their failure — a host whose state is wrong must not print a clean update. - A per-host state change belongs in the update path, and must be safe to re-run. Make the
mechanism a registered script with
--check, have the update call it every run, and design it to refuse to guess (exit a distinct code for "an operator decision is required") and to preserve anything it displaces by rename. A one-off manual fix is not a fix: the next update recreates the old state. - A
NEW file … is not registeredwarning is a decision, not noise. Either add theregister "<source>" "<destination>"line the audit prints, or state in the script's own header WHY it is checkout-only (a run-scoped evidence emitter that reads the DEPLOYED tree needs no entry). The warning does not block the commit, so an unaddressed one ships a tool that exists on no other host while every test stays green.
Register at the RIGHT SCOPE — universal vs orchestrator-only
register() deploys to every host; register_orch() deploys only to orchestrator
hosts. A file every agent needs but registered orch-only is simply ABSENT on
non-orchestrator hosts, and nothing fails loudly — an installer that expects it warns
and carries on, so the integration is silently partial (a Pi setup registering 3 of 4
MCP servers, a bus client with no bus server) and the on-host repair is a hand-copy
that the next agent repeats.
- Decide by who consumes it, and read the consumer's contract. A server whose tools are all CLIENT tools, whose consumers declare client access, and that an installer requires by path belongs on EVERY host. A dashboard, an orchestration loop, a launchd plist, or something only the orchestrator's own crons call stays orch-only.
- Exactly one class per source. Registering a file with BOTH
registerandregister_orchis the natural residue of "promote this to every host" — the new line added, the old one forgotten. The two entries look authoritative and disagree; delete the replaced entry in the same edit. - Guard the class with a test: parse both
registerandregister_orchout offleet-update.sh, then assert (a) everymcp-servers/*.pyis registered, (b) the ones every agent needs use the plain form, (c) no source appears in two classes. Add CONTROLS that run the guard against a modified COPY of the script — one that flips a universal registration back to orch-only, one that adds a duplicate — and assert the guard fires. A scope guard that cannot fail is indistinguishable from one that is not looking.
A registered source can be silently GITIGNORED — confirm it is tracked
git add -A skips ignored files with NO error and NO warning, so a register()
entry can ship while its source file does not. The deploy still succeeds on YOUR
host — it copies from the working tree — while every other host fails with a
source-missing warning, which is exactly why the defect is invisible locally. The
repo's gitignore carries deliberate secret guards (*secret*, *credential*,
*cred*, *token*, *.p12), so ANY artifact whose NAME matches one is affected —
tests included: a test named after a secret-ish artifact never reaches CI, and its
green local run becomes evidence nobody else can reproduce.
- Rename the artifact out of the guard's pattern (preferred).
git add -fis never the answer: an ignored file stays invisible to every OTHER agent'sgit add -A, so the manifest breaks again on the next artifact and the special case multiplies. A targeted!negation is the repo's EXISTING convention for a script that legitimately carries such a name —.gitignorealready negates the leak detector and the leak watchdog by full path, each with a comment saying why — so if you negate, negate a FULL PATH beside those and never a wildcard; expect a rename to be the smaller thing to explain later. - Confirm with
git check-ignore -v <path>(prints the .gitignore line that matched) andgit log --all -- <path>— EMPTY output means it was never committed, no matter how many times you ran it locally. - Guard the whole class with a test, not just your file: parse
^register "([^"]+)"out offleet-update.shand require every source to exist AND satisfygit ls-files --error-unmatch <path>, naming the matched ignore rule in the failure message. Measure the entry count and the current untracked total BEFORE asserting, so the test is not fighting legitimate exceptions; run it against a still-untracked artifact as a control — if a fresh file passes, the test is not inspecting what you think it is. - After
git add -A, readgit status --short. A path you meant to add but that shows noA/Mwas skipped silently; a missing error message is not evidence of a staged file.
Cron manifest: create_cron vs uninstall arrays
parse_expected_crons()(fleet_doctor/config.py) reads create_cron blocks, role-filtered (non-orch hosts exclude orch crons). Uninstall arrays are the CLEANUP list, not the expected list.- When a cron moves from universal (
install-crons.sh) to orchestrator-only (install-orch-crons.sh), KEEP its name in the universal uninstall array as a legacy-cleanup entry — non-orch hosts still need to uninstall the stale cron, and the doctor is unaffected. Drop orch-prefixed names that never had a universal create_cron. fix-cron-duplicates.py --fixaligns uninstall arrays to create_cron EXACTLY and strips legacy-cleanup entries. Do not run--fixblindly after adding one; either accept the warning or whitelist uninstall-only names in the tool first.- After any manifest change:
bash -n <install script>, runfix-cron-duplicates.py(no--fix) to check sync, deploy, run the doctor.
Cron scope/prompt change = three surfaces in one pass
Changing a cron's scope, prompt, or schedule touches three places; a partial update leaves each layer contradicting the others:
- Live prompt —
~/.hermes/cron/jobs.json, updated via the cronjob tool (action='update'); installer edits never rewrite an existing job's prompt. - Installer
create_cronblock — the durable source for non-local-crons. - Doc tables —
docs/fleet-reference.mdANDdocs/cron-schedules.mdeach carry one row per cron describing its scope. Alocal-cron has NO installer block, so its doc row is the repo's only record of the job's scope — commit the row update in the same push.
Verify the live prompt by reading it back out of jobs.json (the update
response shows only a truncated preview), grep both docs for the old scope
term to catch sibling rows, and fire one real run (cronjob action='run')
so the scheduler's last_status reflects the new prompt.
Never edit the repo while YOUR OWN ship is running
fleet-update.sh → fleet-dogfood.sh → git push can run for several minutes. Editing
files in that window — even "just a small fix" — races the ship: it commits (git add -A
seizes your half-written edit), then its pull --rebase/push meets a tree that changed
under it and fails with error: Please commit or stash them. or a non-fast-forward. The
symptom looks like a remote race, so the cause is easy to misread.
- Before editing anything, ask the ship — with a probe that cannot match itself.
A plain
pgrep -f "fleet-update.sh"matches the ASKER: the pattern appears in your own command line and in the shell running your wait loop, so it reports "STILL RUNNING" for a ship that already exited, and a bounded wait keyed on it spins its full timeout. Use a pattern that cannot self-match —pgrep -qf "[c]ortex-update.sh"— or check the pid you started withps -o pid,stat,args -p <pid>, where "no such pid" ends the wait at once. Reading is always safe; writing is not. - After any ship, verify the landing:
pgrepempty, thengit log --oneline -1 origin/mainandgit log --oneline origin/main..HEAD | wc -l== 0. A ship that printeddeploy rc=0can still have failed to push. - A push blocked with
unpushed: Nand a clean tree is already fixed — just push again; the failure was the race, not the commit.
Verify the DELIVERY, not the queue
A message that reached a queue is not a message that reached a human, and depth: 0 after
a send means something consumed it — including your own probe. Two false greens observed
on this path in one night: (1) a queue drained to 0 was read as "delivered" while the
consumer was the test harness calling poll_replies() before drain_outbound() saw it;
(2) a provider /models endpoint answering 200 was read as "credential valid" — that
endpoint is public and answers 200 for a revoked key (a real chat/completion call is the
test).
- Capture the DOWNSTREAM RECEIPT: spy the transport's
_apiand record themessage_idthe platform returns, or read the value back from the system you wrote to. - Measure the thing you claim. "Drained" needs a consumed-and-archived fact; "delivered" needs the receiver's id; "queued" needs the queue to still hold it.
- Verify on the endpoint the CONSUMER uses, not the one your write preferred. A client
with a primary URL plus a silent fallback can WRITE to a different instance than the
reader READS: a stale credential rejected at the primary sends the write to the fallback,
the send still returns a
msg_id, and a consumer pointed at the primary never sees it — a message that vanishes on a success response. Read the value back from the consumer's endpoint (or log which endpoint served the write) before reporting delivery, and when a write and a read disagree about existence, suspect TWO endpoints before suspecting the queue. - When a check can't verify (no receipt available), say COULD NOT VERIFY rather than reporting the nearest green signal.
Peer in-flight work
git status before staging. Modified files that aren't yours belong to a
concurrent session — leave them unstaged, commit only your files by explicit
path. The push-gate dogfood diffs the whole tree, so their in-flight edits
can trip doc-friendliness heuristics; coordinate rather than cleaning.
Perpetually-dirty pipeline file + push races
ops/install/deploy/nginx/blocked_ips.add is rewritten by the
agent-nginx-threat-pipeline cron on every tick — it is always modified at
commit time, and the pipeline both stages it and pushes its own commits. So
on the steadfaste-fleet repo:
- Expect this file to block
git pull --rebase("Please commit or stash them") on nearly every push. Stash just that path by name, rebase, pop. - Expect the push itself to be raced: the pipeline can land a new
auto: block N suspect IPscommit between yourpull --rebaseand yourpush, so the push is rejected as non-fast-forward.git pull --rebaseagain and retry the push — once it showsA..B main -> mainit has landed even if a later command in the same chain printed an earlier failure line. Verify withgit log --oneline -1 origin/main.
Doctor skill-drift: deployed newer than repo = sync INTO the repo
The doctor warns Skill drift: <skill> — Deployed copy is newer than repo source when accumulated lessons live only in ~/.hermes/skills/ (Hermes
skips Hermes-default skills, but deployed skills sourced from the repo drift
every time a session adds a lesson locally without committing). Fix direction
is deployed → repo, NOT repo → deployed (that would erase the lessons):
diff skills/<cat>/<skill>/SKILL.md ~/.hermes/skills/<cat>/<skill>/SKILL.mdand read it — confirm the delta is lesson additions, no PII.- Copy the deployed SKILL.md (and any deployed
references/files the repo copy lacks) into the repo, stage ONLY those paths, commit through the hook. fleet-update.sh, doctor, push. The drift warning clears when deployed matches repo again.
Do not "fix" drift by deleting the deployed copy or re-deploying over it — both discard the lessons the doctor is pointing you at.
Publishing a new skill to the fleet (end-to-end)
Skills reach every agent only through the repo: identify → vet → copy → clobber-check → commit → deploy → doctor → push → FLEET_NOTICE.
- Identify the skill.
find ~/.hermes/skills -name SKILL.md -newermt '<N days>'andcmpeach hit against the repo copy; grep~/.hermes/logs/agent.logfor the session that touched it so you publish the skill the user means, not just the newest-looking file. - Vet before publishing — skill-vetting checklist: read the FULL
SKILL.md (stub body, scripts, injection, exfil, undeclared services),
bash ops/scripts/secret-leak-detector.sh. Copy LICENSE andreferences/along with the skill, usingcp— byte-identical is the verification; a hand-typed rewrite can silently drift. - Clobber check before deploying. fleet-update's delta engine pushes
the REPO copy over the deployed skill, so any lesson that exists only in
~/.hermes/skills/— including ones other sessions added the same day, to skills you are not publishing — is erased by the publish deploy. Diff every recently-changed skill deployed vs repo and sync deployed → repo first. fleet-update's⚠ SKILL DRIFT: deployed copy is newer than repo sourceentries name them; each is content to copy in, never--forcepast. - Commit → deploy → doctor → push. Pull with
--autostash; expect the fleet push race (rebase onto new origin/main, retry). After a race-rebase your commit gets a new sha, so Deploy sync FAILs again — runbash ~/.steadfaste-fleet/scripts/fleet-dogfood.sh --force, push, then verifygit ls-remote origin main== HEAD. - Verify the deployed tree —
diff -r ~/steadfaste-fleet/skills/<name> ~/.hermes/skills/<name>identical — then broadcast FLEET_NOTICE per the fleet-commands skill (self-test on yourself, one message per agent with--self-tested, verify withfleet inboxpeeks).
Transient doctor FAILs — verify live before treating as host debt
Bus stuck msgsFAIL can be a sampling artifact. The doctor probes the LIVE bus over HTTP, and a message sitting between the handler's read and its early archive fails the check once, then clears. Confirm with the live endpoint before fixing handler debt:curl -s -u "$FLEET_BASIC_AUTH" "$FLEET_BUS_URL/api/pgmq/queue/inbox_<agent>"(both vars in~/steadfaste-fleet/.env) —depth: 0, processing: 0= clean, just push again. The path is singularqueue/;/queues/<name>404s. Don't conclude from local psql — on the backup orchestrator the local mycortex-postgres is a stale REPORTS MIRROR.- A 401/404 from that endpoint is a PROBE error, not proof the bus is
unverifiable. nginx demands Basic auth and ignores a Bearer token, so a bearer
request — or the plural
/queues/<name>path — answers 401/404 while the queue is perfectly readable withFLEET_BASIC_AUTH. Retry the documented form before reporting a dispatch as "sent, unverified", and if it still fails, name the exact probe that failed instead of implying the queue cannot be checked. Check the probe before doubting the system. fleetis not on PATH — call it as~/.steadfaste-fleet/scripts/fleet.
Reversing your own wrong fix
If a just-pushed correction turns out to be the wrong direction (e.g. you removed an uninstall-array entry that was serving legacy cleanup), supersede it with a new commit in the same session — a known-wrong commit on main propagates to every host on their next pull.
Before re-pushing into a contested area, check whether upstream still contains your
change. Peers work the same defects from the same symptoms, so a fix can be landed
AND reverted while you are still mid-cycle; git log --oneline origin/main -5 plus
git show --stat <sha> tell you whether a Revert has taken your work out, and
whether the current upstream state is coherent (source present, manifest pointing at
it). Push onto a verified base and raise the revert as a decision — do not silently
re-land a change someone deliberately reversed, and do not re-argue it by loop.
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-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.
fleet-deployment-sync
Use when pulling latest or running fleet update.