debug-apply-journal
Skill0 starsChanged 54 days agoMITView on GitHub
Diagnose a failed, interrupted or suspicious `apply` on a target root by reading the .axiom/ journal, staging and backup directories — determine the phase it died in, what was written, and whether rollback/recover is safe. Use when a user reports "apply left my tree half-written", ERR_LOCKED, a journal in `committing`, or wants to prove a rollback restored the pre-image.
In this repository4 other files it gives its agents.
- add-golden-fixtureSkill
- add-mcp-toolSkill
- add-predicateSkill
- release-axiomSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 28
Freeze the scene: Do not run apply again yet.
- Very specific: line 63
Add a line to /memories/repo/axiom-overview.md if the failure mode is new.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Debug an apply journal
@codai/axiom-apply is a two-phase commit. Everything it knows is on disk under
<root>/.axiom/ — read that first, reason second, mutate last (and only via
rollback()/recoverIfNeeded(), never by hand-deleting).
Layout (from packages/apply/src/apply.ts + journal.ts + lock.ts):
<root>/.axiom/
lock single writer: { pid, startedAt } — stale after 60 min
journal/<digest-hex>.json Journal { manifestDigest, phase, steps[], startedAt, pid }
stage/<digest-hex>/… phase-1 blobs, sha256-verified, not yet in place
backup/<digest-hex>/… pre-images of files phase 2 overwrote/deleted
applied/<digest-hex> marker written after a successful commit (idempotency)Phases (JournalPhaseSchema, packages/schema/src/apply.ts):
staged → committing → committed, or committing → rolling-back → rolled-back.
Steps
- Freeze the scene. Do not run
applyagain yet.git status --shortin the root (if it is a git tree) and list.axiom/journal/. Copy the whole.axiom/dir to.copilot-tmp/axiom-forensics-<ts>/before touching anything. - Read the journal:
Get-Content <root>/.axiom/journal/<hex>.json | ConvertFrom-Json. Notephase,pid,startedAt, and for each steppath,op,backup,done.done: falsesteps incommitting= files phase 2 never reached. - Match it to the manifest: the file name is
manifestDigestminussha256:. If the caller still has the bundle,axiom_manifest_verify(orverifyBundlein@codai/axiom-plan) confirms it is the same digest — a mismatch means someone applied a different bundle than they think. - Check the lock: is
pidalive? (Get-Process -Id <pid>). Alive → another apply is genuinely running; wait. Dead +startedAtolder thanLOCK_STALE_MS(60 min) →acquireLockwill reclaim it on the next call; younger →ERR_LOCKEDis correct, do not delete the file by hand. - Classify:
staged— nothing in the tree changed; stage dir can be discarded. Safe.committing, somedone: true— the tree is mixed. Every done step has abackupentry → rollback is possible and byte-exact.committed— apply finished; if the user sees "wrong content", comparesha256of each path againstartifacts[].sha256in the manifest before blaming apply (an editor or another agent may have written after).rolling-back— a rollback was interrupted;recoverIfNeeded(root)finishes it idempotently.
- Verify pre-images before rolling back: for each
donestep,Get-FileHash <root>/.axiom/backup/<hex>/<path>should equal the pre-image hash the journal/manifest recorded (ArtifactPrein the bundle). A mismatch is a TOCTOU finding — record it, it is the bug, not the symptom. - Recover:
rollback(root, "sha256:<hex>")from@codai/axiom-apply(or MCPaxiom_rollback). Then re-hash the touched paths against the backups: identical → VERIFIED restored. A second rollback must be a no-op. - Reproduce in a test, not in the user's tree:
packages/apply/src/apply.test.tshas fault-injection at step i — add the failing step index/shape you found as a new case, assertresult.codeand the byte-identical tree. - Report: phase found, steps done/undone, whether backups matched, what
restored it, and the root cause (
ERR_*code) — with the command output. Add a line to/memories/repo/axiom-overview.mdif the failure mode is new.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

