# awarer documentation corpus (awa v0.3.1) Every document of this release, in publication order, as Markdown. Bodies are reproduced byte for byte, so the relative `.md` links inside them address the offline documentation layout, not this site. Each document below is preceded by its canonical URL, and https://awarer.one-man-wolf-pack.com/llms.txt maps every document to one. --- source: https://awarer.one-man-wolf-pack.com/docs/agents/ --- # awa for coding agents Use awa for three things: explicit checkpoints of the worktree, reusable deterministic checks, and durable execution history. You do not need prior knowledge of the project — the commands below are the whole workflow. Start with the dashboard — it is the single entry point before a review: ```text awa status # checkpoint, dirty summary, reusable/near # runs, and the commands to run next ``` Before a meaningful change, checkpoint the worktree (replace the placeholder with a specific message; do not copy it literally): ```text awa checkpoint -m "" ``` Review what changed since the last checkpoint (default range latest..now): ```text awa changes awa diff [path] ``` A clean changes/diff delta means only "no changes since that baseline" — not that the whole worktree is reviewed. Before you declare work ready, inspect the full current uncommitted worktree, not just the checkpoint delta. `latest` is shared project-local state, not your private bookmark: it moves whenever any agent or user runs `awa checkpoint`. For a long review/fix loop, keep the checkpoint id that `awa checkpoint` prints and compare against it explicitly so another agent's checkpoint cannot silently move your baseline: ```text awa changes ..now awa diff ..now ``` If a default `awa changes` baseline ever surprises you, inspect recent checkpoints with `awa log -n 5`. Run a deterministic check through the cache (record first, reuse if safe): ```text awa run --display tail:200 -- awa run ls # checks reusable for the current state awa run ls --near # and why recent checks are now stale awa run show --last --tail 500 # inspect the last run's captured output awa run show --last --grep "" ``` Run a non-cacheable or side-effecting command with supervised history, and other useful forms: ```text awa run --record --display tail:200 -- awa changes run::before..run::after # what the command changed awa run explain -- # show the cache decision without running awa run --refresh -- # force a fresh deterministic check ``` ## Repairing an accidental rewrite A checkpoint is also evidence you can restore from — when a generator or formatter rewrites files it should not have, put the selected paths back: ```text awa restore -- # preview; changes nothing awa restore --apply -- # perform it ``` Preview first and always name the paths: preview is the default and changes nothing, `--apply` is the only mutating form and needs an explicit selection (paths or `--all`), and nothing you did not select is touched. Incomplete evidence refuses with a named reason; there is no force option. An apply records what it overwrote and prints a `restore::before` reference to undo it, retained under `[gc].keep_restores_for` — evidence with a lifetime, not a backup. See [awa help restore](restore.md). This is why side-effecting work belongs in `awa run --record`: a build, generator, formatter, migration, or deployment run through the wrapper has its before/after observation attributed immediately. awa can see a worktree drifted; without the wrapper it cannot prove what caused it. If awa notes that a large watched effect root (e.g. `target/`, `node_modules/`) dominated state observation, that is why run, `run ls --near`, and status felt slow — not a misconfiguration to fix by rerunning blindly. Prefer `awa run --record` for a command whose point is a side effect; reviewing the configured `[run]` effect roots is a policy decision, not a routine fix. ## Pick the right mode - `awa checkpoint` — explicit, user-authored checkpoints. - `awa run` — deterministic check: records first, becomes a reusable hit only if the run is clean, non-mutating, and its watched generated-output roots are unchanged. - `awa run --record` — supervised history: always executes, never becomes a reusable hit. Use it for side-effecting, deployment, migration, and formatter/fixer workflows where replay would be misleading. - `awa run ls` — the reusable-now view (reusable for the current observed inputs and configured effect-observation policy). - `awa run log` and `awa run show` — execution history and captured-output inspection. ## Machine output For automation, add `--json` — every review surface has a stable machine form so you never parse human text: ```text awa status --json # dashboard facts + a review object awa changes --json # summary, refs, and per-file changes awa run ls --near --json # reusable rows + near misses (reason, sample) awa run explain --json -- ``` ## Warnings are correctness signals, not noise - Do not use cache mode for non-idempotent commands or commands that depend on hidden external state; a false hit would skip real work. - A "skipped inputs" or "not cached" notice means the result was not made reusable — treat it as a signal, not clutter. - `awa run` is cwd-sensitive by design: the execution directory is part of the cache key. Use `--cwd ` to make it explicit. - `.gitignore` is OFF by default for awa's scan input, so a gitignored file is still a real input that can affect a command. ## Local evidence is private, not shared - `.awa/` holds durable evidence (command lines, captured output, cwd, manifests, content blobs). Do not commit it — awa keeps it owner-private and untracked and restores its `.gitignore` guard on checkpoint/run. - Allowlisted env values are keyed and passed to the child, but stored only as a redacted identity, never raw. Even so, do not print secrets through a wrapped command: captured stdout/stderr is stored verbatim as evidence. - An executed child gets `AWA_RUN=1`. It is advisory and forgeable: it grants nothing and proves nothing. - After a repo is moved, copied, or shared, run `awa doctor` to check the guard, permissions, and root hygiene. ## Discovering awa itself Each of these answers for the version you have installed, without a network: ```text awa version # the installed version awa help topics # every operational topic awa docs export --output # the complete documentation bundle ``` ## Where to read more Each question below has one page that owns it; go straight there rather than reading in order. - getting and identifying the binary — [awa help install](install.md) - a fresh project, first loop — [awa help quickstart](quickstart.md) - structuring a review or repeated fix loop — [awa help workflows](workflows.md) - putting paths back after a rewrite — [awa help restore](restore.md) - reading the dashboard — [awa help status](status.md) - finding and reading an earlier run's output — [awa help inspect](inspect.md) - something is slow, stale, blocked, or broken — [awa help troubleshooting](troubleshooting.md) - consuming awa from a script — [awa help json](json.md) ## See also - [awa help run](run.md) - [awa help record](record.md) - [awa help checkpoints](checkpoints.md) - [awa help restore](restore.md) - [awa help privacy](privacy.md) - [awa help exit-codes](exit-codes.md) --- source: https://awarer.one-man-wolf-pack.com/docs/install/ --- # installing, verifying, and upgrading awa `awa` is one static binary. It has no runtime dependencies, no daemon, no background service, no network calls, and no telemetry. Installing it means putting one file on `PATH`; removing it means deleting that file. A release reaches you two ways: a maintained Homebrew formula on macOS and Linux, or a release archive on every supported platform. Both give you the same release — Homebrew compiles it from the tagged source, the archive is the prebuilt binary — and both report the same version. Building from source yourself is documented further down and produces a development build rather than a release. On macOS the two paths do not carry the same minimum. The release archives are built with Go 1.27 and need macOS 13 Ventura or later; the formula is compiled by the Go that Homebrew installs as a build dependency, so it follows the macOS versions Homebrew supports. See [awa help platform](platform.md) for the published target list. ## Which version am I running The installed binary knows exactly which version it is. Ask it, not a website: ```text awa version awa version --json ``` The human line reads `awa (, )`. A build that was not stamped by the release tooling reports the version `0.0.0-dev`; treat that as "built from source", not as a release. The JSON form carries the same facts in the standard envelope described in [awa help json](json.md): `version` and `go` always, plus `revision` — the full commit, not the shortened one — and `time` when the Go toolchain stamped VCS metadata into the build. A release binary is built from a checkout and carries both; one built from an extracted source tree has no VCS to read, so it reports neither and its human line shows no commit in the parentheses. `awa version` takes no global options other than `--json`: it never reads a project, a config file, or `.awa/`, so it answers the same way anywhere. ## Install with Homebrew The formula is `awarer`; it installs `awa`. Use the fully qualified name because the formula is in a third-party tap and Homebrew already assigns `awa` to another application. ```text brew install one-man-wolf-pack/tap/awarer awa version ``` Homebrew builds `awa` from the released source. It installs Go itself as a build dependency, so you do not install Go first, and it is a build dependency only — the finished `awa` is still one static binary that depends on nothing at runtime. The trade is time: compiling takes longer than downloading an archive. What you get back is that the binary is built on your machine rather than downloaded, so there is nothing for macOS to mark as quarantined and no `xattr` step belongs to this path. Upgrading is Homebrew's ordinary flow — refresh the tap, then upgrade by name: ```text brew update brew upgrade awarer ``` Removing it is the counterpart: ```text brew uninstall awarer ``` Homebrew compiles the same immutable release tag and commit the archives below are built from, and the binary it produces reports that same version. It is not byte-identical to an archive, because it was compiled on your machine: the checksummed GitHub Release archives stay the authority for which versions exist and what prebuilt bytes they contain. Homebrew covers macOS and Linux — use the archive on Windows and FreeBSD. ## Install from a release archive Each tagged release publishes one archive per supported target and one SHA-256 checksum file, attached as assets to that tag's release: ```text https://github.com/one-man-wolf-pack/awarer https://github.com/one-man-wolf-pack/awarer/releases ``` The first is the source repository, the second is where the release assets live and is the authority for the archives described below. Archives are named `awa___.tar.gz`, except Windows, which uses `awa__windows_amd64.zip`. In an asset name `` is the release tag with its leading `v` removed, so tag `v1.2.3` publishes `awa_1.2.3_linux_amd64.tar.gz` — while the binary inside reports the tag as it is, `awa v1.2.3`. `` and `` are the Go platform names — `linux/amd64`, `linux/arm64`, `darwin/amd64`, `darwin/arm64`, `windows/amd64`, and `freebsd/amd64` are the supported set. On macOS, `uname -m` reports `arm64` for Apple silicon and `x86_64` for `amd64`. Download the archive for your platform together with the checksum file `awa__checksums.txt`, verify, then extract: ```text sha256sum --check --ignore-missing awa_1.2.3_checksums.txt # Linux shasum -a 256 --check --ignore-missing awa_1.2.3_checksums.txt # macOS ``` `--ignore-missing` is needed because the checksum file covers every target's archive and you downloaded one. On Windows, compare the digest yourself with PowerShell `Get-FileHash -Algorithm SHA256` or `certutil -hashfile SHA256` against the matching line in that file. Each archive contains exactly the `awa` binary (`awa.exe` on Windows), `README.md`, `LICENSE`, and `THIRD_PARTY_NOTICES`. Move the binary somewhere on `PATH` and confirm it runs: ```text awa version ``` A copy downloaded through a browser on macOS carries a quarantine attribute, and Gatekeeper refuses to run it until that attribute is cleared: ```text xattr -d com.apple.quarantine ``` On Windows, SmartScreen may warn on first run. Clearing either is you deciding to trust the copy you just verified — the checksum did not decide it for you, so do it after the checksum matched, not before. The third-party components linked into the binary are inventoried in the `THIRD_PARTY_NOTICES` file inside every archive. ## What the checksum does and does not prove The checksum file is an integrity manifest. It proves that the bytes you downloaded are the bytes that were published. It is not a publisher identity: a checksum file can be recomputed over any set of files by whoever writes them, so it cannot certify who produced the release or that the set is the intended one. Signing and attestation are deliberately out of scope for now. The current provenance is the checksum file plus the binary's own version and commit stamping. ## Build from source ```text go build -o awa ./cmd/awa ``` Building needs Go 1.26 or newer — the exact floor is the `go` line in `go.mod`, which the toolchain enforces for you. The produced binary needs nothing. The module path is local, so there is no `go install ` form, and a source-built binary reports `0.0.0-dev`. Homebrew compiles the same source but stamps the release tag it selected, which is why what it installs reports a release version and this does not. What a source-built binary needs to run follows the Go toolchain that compiled it, not the release archives: normal Go selection may use an installed toolchain newer than the one `go.mod` names, and `GOTOOLCHAIN=local` uses the installed one whatever it is. ## Upgrade `awa` keeps no global state, no user-level configuration directory, and no registry: upgrading is replacing the binary. Nothing has to be migrated before or after. Project state is per project and is not touched by installing a new binary: your worktree, `awa.toml`, and `.awaignore` are files a new binary simply reads. Existing evidence is a different question, and nothing is migrated. A record declaring a schema this awa cannot read is not upgraded in place and is never reusable; it is diagnosed rather than silently reinterpreted, and it is kept: - `awa doctor` reports it under its own finding, so an unreadable schema is diagnosed separately from corruption, and it neither migrates nor quarantines the record; - `awa gc` will not reclaim it. Nothing can prove what a record awa cannot decode references, so deleting it is not a safe automatic act: it is retained, the blob sweep stands down, and `gc` exits asking for a decision. Clearing it is therefore always deliberate. Remove a single stored run with `awa run rm `; there is no command that deletes one checkpoint. The recovery awa itself recommends is a fresh store. Reset it like this, in this order: 1. Stop anything still using the project — a running `awa run`, a collector, an agent shell. The reset removes `.awa/locks`, and deleting a live process's lock is how you get a half-recreated store rather than a clean one. 2. Change to the project root. Every path below is relative to it, so running them from a subdirectory quietly deletes nothing, or the wrong project. 3. Delete the evidence and runtime directories: ```text .awa/checkpoints .awa/runs .awa/restores .awa/store .awa/indexes .awa/locks .awa/logs ``` 4. Run `awa init`. Delete those directories, not `.awa/` itself. The state directory also holds your private `.awa/config.toml` layer and the awa-owned `.awa/.gitignore` guard, and removing the parent takes both with it. Resetting this way loses the local history and leaves your worktree, git history, committed `awa.toml`, `.awaignore`, and local config untouched. (Deleting `.awa/` outright is still the right move when you want the evidence *and* the private config gone — see [awa help privacy](privacy.md).) So plan an upgrade as "the binary changes, the evidence may need cleaning up", not as "everything keeps working". After an upgrade, or after a repository was moved, copied, or restored from a backup, run: ```text awa doctor ``` Downgrading is the same operation in reverse, with one caveat: a newer store may contain records an older binary reports as unreadable rather than migrating them backwards. ## See also - [awa help quickstart](quickstart.md) - [awa help platform](platform.md) - [awa help doctor](doctor.md) - [awa help json](json.md) --- source: https://awarer.one-man-wolf-pack.com/docs/quickstart/ --- # awa quick start — first project and first loop You have the binary and a working directory. This page takes you from nothing to a first review loop. Nothing here requires a git repository, a network, or a configuration file. ## Initialize the project ```text awa init awa init --profile strict awa init --root ``` `` is the directory to initialize; without `--root`, `awa init` uses the current directory and does not walk upwards looking for a better one. `awa init` creates a single `.awa/` directory at the project root, owner-private, holding every durable record awa keeps. It refuses to re-initialize a directory that already has one, so running it twice is safe and never disturbs existing state. Initialization is all-or-nothing: a failure part-way removes the partial `.awa/` rather than leaving something that looks complete. The default profile writes **no configuration file at all** — the built-in defaults apply and an absent file is the normal, correct outcome. `--profile strict` writes one local override, `trust_mode = "strict"` under `[hashing]`. `awa init` never prompts, so it is safe to run unattended from a script. ## The git ignore guard `.awa/` holds local evidence, not source, and must never be committed. `awa` owns `.awa/.gitignore` for exactly that purpose and restores it on checkpoint and run, so state cannot quietly start accumulating unguarded. `awa` never creates or edits your repository-root `.gitignore` — that file is yours. The guard is the one it does own, and there is no way to opt out of it. If it is ever missing or altered, `awa doctor --repair` puts it back. ## The first loop ```text awa status awa checkpoint -m "" awa changes awa diff awa run -- ``` `` is a placeholder: replace it with a short message describing this particular baseline, and do not copy the placeholder literally. `` is the check you want to make reusable, for example a test or lint invocation; everything after `--` belongs to that command, not to awa. What each step is for: - `awa status` is the dashboard and the single entry point before a review. It names the baseline, what is dirty, live git state, which runs are reusable, and the commands worth running next. - `awa checkpoint` records an explicit checkpoint of the worktree and prints its id. Keep that id — it is how you compare against this exact moment later. - `awa changes` summarizes what changed; `awa diff` shows the content. Both default to the range `latest..now`. - `awa run` executes a command, stores its output durably, and — when the run is clean and non-mutating — makes it reusable for an unchanged input tree. An empty `awa changes` means "nothing changed since that baseline". It is not proof that the whole worktree has been reviewed; finish with the full uncommitted surface before declaring work ready. ## Where state lives One `.awa/` directory at the project root, and nothing else. There is no global state, no user-level config directory, no daemon, and no network. Commands find the root by walking up from the current directory, or use `--root ` to say it explicitly. `awa` does not track files outside that root — the one way to change that is to deliberately enable both `follow_symlinks` and `allow_symlink_root_escape`, which are off by default. ## Configuration is optional Defaults are built into the binary, so most projects need no configuration at all. When you do need it, values are composed from five inputs, later ones winning: built-in defaults, then the shared committable `awa.toml` at the project root, then the private untracked `.awa/config.toml`, then an explicit `--config `, and finally command-line flags. A key written into the wrong table is a config error, not a silent no-op, so check the section name in the reference before hand-editing. One layering rule deserves stating before you write a second layer: a later layer replaces the whole value of a key, and for a list that means the entire list rather than a merge. A private `.awa/config.toml` setting `extra_excludes` discards the shared `awa.toml` list instead of adding to it — same for `include`, `env_allowlist`, `default_scope`, and `extra_effect_roots`. To extend a shared list, restate its entries in your layer, and use `awa config effective` to confirm what actually resolved. ```text awa config template awa config init --shared awa config init --local awa config show awa config effective awa config validate ``` `awa config template` prints an annotated template to stdout and needs no project. Use `--shared` for policy the whole team should get, `--local` for a private override. `awa config show` prints one layer's raw file contents — name `shared` or `local` when both exist — while `awa config effective` shows the composed result and which layer each value came from. Reach for `show` when you want to know what a file says, and `effective` when you want to know what awa will actually do. There is no command that sets a config value: `awa config init` writes a scaffold and then you edit the TOML yourself. `awa` never edits a config file on your behalf — in particular it will not widen or narrow the scan to improve the cache hit rate, because that is a policy decision with consequences you should choose knowingly. The full key schema lives in the configuration reference: [awa help config](../reference/configuration.md). ## See also - [awa help agents](agents.md) - [awa help status](status.md) - [awa help workflows](workflows.md) - [awa help ignores](ignores.md) - [awa help privacy](privacy.md) --- source: https://awarer.one-man-wolf-pack.com/docs/workflows/ --- # coding, review, specification, and fix loops This page is about structure: which awa commands to run, in what order, so that a multi-step task keeps an honest record of what changed and what was verified. The individual commands are documented on their own pages; what follows is how they compose. ## Pick a baseline and keep it Every comparison needs a baseline. The default one is `latest`, the newest checkpoint — and `latest` is shared project-local state, not your private bookmark. It moves whenever any agent or user runs `awa checkpoint`, including in another terminal. For anything longer than a single edit, capture the id instead: ```text awa checkpoint -m "" awa changes ..now awa diff ..now ``` `` is the short description of this baseline; `` is the id `awa checkpoint` printed (a unique prefix is enough). Using the explicit range means another agent's checkpoint cannot silently move what you are comparing against. If a default baseline ever surprises you: ```text awa log -n 5 ``` ## Coding loop ```text awa checkpoint -m "" awa changes awa run -- ``` Checkpoint before a meaningful change, make the change, review the delta, then run the check you care about. `` is your test, build, or lint invocation. A second `awa run` of the same command replays the stored result instead of re-executing — when the inputs, working directory, and keyed environment are unchanged, and the first run was clean and non-mutating, which is what made it publishable at all. Anything else is a miss, and a miss is information rather than a fault: see [awa help run](run.md). ## Review loop: two passes A review is finished only after both passes. First pass — focused review memory. What changed since the baseline you chose: ```text awa changes ..now awa diff ..now ``` Second pass — the full current uncommitted surface, using the project's normal review tooling (`git status`, `git diff`, or whatever this repository uses). An empty first pass means only "nothing changed since that baseline". It is never proof that the whole worktree has been reviewed, and a checkpoint delta is not the same set of changes as the uncommitted git diff. In a git repository, `awa changes` and `awa diff` name the current HEAD and add a note when the baseline predates or diverges from it — after commits, rebases, or amends. That note is context, not a fault: the comparison is still valid, but the delta may not map onto current HEAD, which is exactly when the second pass matters most. ## Repeated fix loop When a reviewer asks for several fixes in sequence, make each round individually verifiable: ```text awa checkpoint -m "" awa run -- awa changes ..now ``` One checkpoint per fix request, with a message naming that request. Re-run the same check after each fix. When a check that passed a moment ago no longer reuses its earlier result, ask why rather than assuming breakage: ```text awa run ls --near awa run explain -- ``` Do not reach for `--refresh` or `--no-cache` to make a loop feel faster: a miss is a statement about the current inputs, and an old successful run is not reusable for state that changed. See [awa help troubleshooting](troubleshooting.md). ## Specification and other long-running work For work spanning many sessions, keep the id each anchor checkpoint prints. An id never moves, so it stays a precise baseline no matter how many checkpoints are created after it — unlike `latest`, which always names the newest one: ```text awa checkpoint -m "" awa changes ..now ``` Record the id wherever the work itself is tracked, alongside the message that says what the anchor is — for example the identifier of the specification section you are implementing. To see the whole timeline rather than only checkpoints: ```text awa log --all ``` That adds recorded runs and git commit boundaries as context markers. The commit boundaries are markers only; they are not awa state references. After committing a cycle, start a fresh checkpoint for the next one and inspect what local evidence became redundant: ```text awa gc --committed --dry-run ``` ## Steps with side effects A command that deploys, migrates, formats, or otherwise changes the worktree must not be replayed from a cache. Record it instead, then inspect what it did: ```text awa run --record -- awa changes run::before..run::after ``` `` is the run id the record printed. A recorded run always executes and never becomes a reusable hit — that is the point of it. ## Several agents in one worktree `.awa/` is shared project-local state, so concurrent agents see each other's checkpoints and runs. Two habits keep that safe: always compare against an explicit checkpoint id rather than `latest`, and give each checkpoint a message specific enough that another agent can tell whose baseline it is. When a lock is briefly held by another process, awa reports it rather than waiting forever; see [awa help exit-codes](exit-codes.md). ## See also - [awa help agents](agents.md) - [awa help status](status.md) - [awa help checkpoints](checkpoints.md) - [awa help diff](diff.md) - [awa help refs](refs.md) - [awa help run](run.md) - [awa help record](record.md) --- source: https://awarer.one-man-wolf-pack.com/docs/status/ --- # awa status — the review dashboard ```text awa status awa status --json ``` `awa status` is the single entry point before a review, and the default command when `awa` is run with no arguments. It answers "where am I, what has drifted, what is reusable, what should I do next" in one bounded pass — prefer it over a sequence of `awa changes`, `awa run ls`, and `git status`. It never executes anything and never modifies durable records. ## Durable facts The first block describes the project and its store: ```text root: config: built-in defaults (no awa.toml or .awa/config.toml) initialized: yes checkpoints: 3 latest: at (0 skipped) run cache: 7 runs latest: exit=0 at store: ``` The `config:` line lists the layer files that actually exist, or says that the built-in defaults are in force. `skipped` counts inputs the scan could not read for that checkpoint. Sub-lines appear only when they have something to report: `unreadable:` for checkpoints that cannot be decoded (naming how many are in a schema this awa cannot read, when any are), and `corrupt:` or `incompatible:` for stored runs, each qualified by the newest-N sample they were counted in. ## The review dashboard The second block is the review state itself: ```text checkpoint: checkpoint "" () dirty: 4 changed (1A 2M 1D 0R 0T 0S) — awa changes --stat git: branch @ (dirty) reusable: 2 run(s) replayable now — awa run ls next: awa changes --stat # what changed since the checkpoint ``` - `checkpoint:` is the baseline everything else is measured against — the same label `awa changes` and `awa diff` print in their header. With no checkpoint yet, it says so and suggests creating one. - `dirty:` is either `clean since checkpoint` or a count with the per-kind breakdown: added, modified, deleted, renamed, type-changed, skipped. - `git:` is `branch @ ` with the worktree state, or `unavailable ()`, or `non-git`. The dashboard always states git status so it is obvious whether a git cross-check applies at all. - `reusable:` counts runs replayable for the current observed state. When none are, it reports how many near misses exist and points at `awa run ls --near`; a `nearest:` sub-line then names the closest candidate and its reason token. When that reason is `effect-state-differs` or `effect-state-unavailable` *and* the run's state was compared against an observation that identified a dominant watched root, one further `effect:` line names that root. Otherwise the reason token is the whole answer: a run recorded as non-reusable back when it ran keeps its reason without a root, because today's dominant root says nothing about that earlier execution, and repeating the token as prose would add nothing. `--json` still carries the rootless diagnosis with its sample fact and typed actions. Effect state has no changed-path sample, and the full exclude / effect-root / `awa run --record` decision stays with the `awa run` footer. - `next:` lists concrete follow-up commands chosen from the current state. In `--json` each entry also carries a `kind`, a `reason`, and a tokenized `argv`, so an agent can act on it without parsing the display text. ## Notes go to stderr Two advisories are written to stderr, not stdout: the git-freshness note (the baseline predates or diverges from HEAD) and the closing review-coverage note. Redirecting stdout therefore leaves the dashboard body clean, and a script that captures only stdout does not have to filter them out. ## What status deliberately does not do `awa status` is bounded on purpose, and it distinguishes "nothing" from "unknown": - `checkpoints: 0 readable` is not `none yet`. The first means records exist but could not be read; the second means none were ever created. - It does not walk the blob store, so it reports no footprint at all. The closest figure is `awa gc --dry-run --json`, and even that reports accounted bytes rather than physical space — an undecodable entry is still reclaimable but its size is never read. For a true on-disk size, measure `.awa/` with the operating system. - It samples the newest runs rather than validating every stored record, so the corrupt and incompatible counts are qualified by that sample. It is not the exhaustive diagnosis; use `awa doctor --json` for that, which the `next:` block suggests as soon as any degraded evidence appears. ## The dashboard is not a completed review `dirty:` reports what changed since the checkpoint baseline, which is not the same set of changes as the full uncommitted git diff. A `clean since checkpoint` line means only that nothing moved since that baseline. Before accepting work, inspect the full uncommitted worktree with the project's normal review tools — which is what the closing note on stderr says. ## Machine form `awa status --json` carries the same facts plus a `review` object with the checkpoint, dirty summary, git state, run counts, typed `next` entries, the baseline freshness token, and the review-coverage note. Timestamps are UTC. Degraded evidence appears as entries in `degradations` and `warnings` rather than as missing fields. The `effect:` detail above is not a separate status field: it is `review.runs.nearest.effect`, the same optional `{reason, root?, sample, actions}` object `awa run --json`, `awa run ls --near --json`, and `awa run explain --json` emit for an effect-state miss. ## See also - [awa help workflows](workflows.md) - [awa help diff](diff.md) - [awa help run](run.md) - [awa help doctor](doctor.md) - [awa help json](json.md) --- source: https://awarer.one-man-wolf-pack.com/docs/run/ --- # awa run — deterministic run cache ```text awa run [flags] -- [args...] ``` `awa run` wraps a command. On the first run it executes the command, captures its output and observed state, and — if the run is clean and non-mutating — stores a reusable cache entry keyed on the inputs the command could see. A later run with the same key replays the stored result instead of executing again. ## Result model - `hit` — a stored result was replayed; the command did not execute. - `miss` — the command executed; the result may be stored if cacheable. - `uncached` — the command executed but the result was not made reusable (e.g. skipped inputs without `--allow-skipped-inputs`). Stdout and stderr are captured separately; their cross-stream interleaving is neither recorded nor promised. Every hit returns the stored child exit. Outside `--json`, `--display full` writes each stream's exact bytes, complete stdout before complete stderr; bounded, hidden, and JSON displays claim no full byte replay. ## Cache key The cache key covers, at a high level: the command, the run input scan (files the command could read), the working directory relative to the project root, and the relevant environment. `awa run` is cwd-sensitive by design — the same command launched from a different directory is a different key. Make it explicit with: ```text awa run --cwd ./packages/api -- npm test ``` ## Trust mode How closely the input scan compares files is the trust mode, set by `[hashing].trust_mode` and overridable per invocation with the global `--trust-mode ` (`normal`, `strict`, or `fast`), or with `--strict` as a shorthand: - `normal` — the default balance of hashing and stat signatures. - `strict` — always hash content, never trust size and modification time. Slower, and the right choice when a file may change without its metadata changing. - `fast` — stat-only comparison. It can miss a same-size, same-mtime rewrite, so a run observed under it is recorded but never published as reusable (`fast-trust-mode`). Trust mode is part of the cache key, so changing it does not silently reuse results observed under a different one. ## Mutation guard `awa run` returns the wrapped command's own exit code after a hit or a miss, and a mutating or failed execution is still recorded as history. But only a clean, non-mutating run becomes a reusable hit — if the command changed observed state, the result is returned but never published for reuse. The cache prefers a false miss (re-run unnecessarily) over a false hit (skip work that mattered). ## Effect observation `awa run` also watches generated-output roots with a bounded stat signature. The watched set is the built-in one — every *baseline* exclude, such as `node_modules` and `target`, plus `build`, `dist`, `out`, and `coverage` — plus any `[run].extra_effect_roots`, selecting by name at any depth or by exact project-relative path. That second built-in group is watched though the input scan still sees it: a build artifact is both a real command input and generated state. `.awa/` and `.git/` are the exception: neither scanned nor watched, because awa's own state and your VCS metadata are outside its guarantee. Note the boundary, because it is the one place excluding a path can cost you a correct result: **an exclude you add yourself is not watched**, so a replay can report success while an excluded, unwatched directory is missing. "Effect roots vs excludes" below turns that into a decision. Deleting or changing that generated state after a reusable run misses instead of falsely hitting (reason `effect-state-differs`); a watched root that cannot be observed safely, or a run under the fast trust mode, records but never becomes reusable (`effect-state-unavailable`, `fast-trust-mode`). A cache hit is reusable for observed inputs and configured project-local observation policy; by default it does not track files outside the project root, and never network services, clocks, or home-directory config. ## Latency diagnostics awa explains slowness it can name and says nothing otherwise: a note appears only past the shared interactive threshold, at most two per invocation. Neither cause is a misconfiguration; neither is disableable. - `large-effect-root` (`run.effect-observation`, hint `record-mode`) — a watched generated-output root dominated state observation. - `full-input-rehash` (`run.input-observation`, hint `review-run-scope`) — reading the inputs was slow enough to notice; a hit pays it too. Both appear on `run`, `run explain`, `run ls` and `status`, and in JSON under `data.diagnostics.performance[]`. For the note and hint text, what each count means, and the safe response to each, see `awa help troubleshooting`. ## Display Display affects this invocation's terminal output only — never capture, the cache key, or the exit code: ```text --display full default; stream/replay the full output --display summary metadata plus a short excerpt --display tail: the last n lines --display none awa diagnostics only, no command output ``` ## Useful flags ```text --refresh ignore any existing hit, publish a fresh result --no-cache neither read nor write the cache --no-cache-failures execute, but do not cache a failed result --allow-skipped-inputs allow caching when the input scan skipped files --cwd set the execution directory (part of the key) ``` ## Footer and inline diagnosis Every real execution and hit ends with a compact footer: the storage state (hit/stored/record-only/uncached), the run id, cwd, exit, duration, whether the result is reusable, and the command to inspect it. A mutating or otherwise non-reusable run also prints the exact before/after compare command. For a common miss the footer also shows an inline cache diagnosis: the nearest previous run, why it is not reusable (e.g. `input-tree-differs`), a bounded sample of the changed inputs, and the exact `run explain` / `run ls --near` follow-ups — so the first response is useful without a second command. It is a bounded preview, not a replacement for `run explain` / `run ls --near`. ## Why a run is not reusable Every surface that reports reuse — `awa run`'s footer, `run ls`, `run ls --near`, `run explain`, and a stored run's recorded reuse state — names the cause with one token from a single closed vocabulary. This is that vocabulary, grouped by what the token is a statement about. The observed state no longer matches what was recorded: ```text input-tree-differs the observed input tree changed mutated-state the command changed observed state effect-state-differs watched generated output changed or was deleted effect-state-unavailable a watched root could not be observed safely fast-trust-mode observed under fast trust; recorded, never reusable ``` A recorded key fact no longer matches: ```text expired older than the run TTL env-mismatch an allowlisted environment fact differs cwd-mismatch the execution directory differs config-mismatch another keyed fact differs (scope, trust mode, ...) platform-mismatch recorded on a different OS or architecture ``` The stored evidence cannot be replayed honestly: ```text payload-missing the stored output is absent or fails its hash corrupt the stored metadata could not be decoded post-scan-failed the post-run observation scan failed ``` Policy declined to make the run reusable: ```text non-cacheable-policy caching was forbidden for this invocation record-only captured as supervised history, never offered no-cache ran without reading or writing the cache stdin-not-keyed piped or tty stdin is not part of the key skipped-inputs the scan skipped inputs without the allow flag capture-disabled output capture was off, so nothing was stored failed-not-cached the command failed and policy declines to cache it ``` Only `input-tree-differs` can produce a changed-input-path sample, because only that comparison has two input manifests to diff. The tokens are stable machine values: switch on them rather than on the surrounding prose. ## Inspect and explain ```text awa run ls current-state reuse view (reusable right now) awa run ls --near also list near misses and why they are not reusable awa run log chronological run history, newest first awa run show --last inspect a run's metadata and captured output awa run explain -- compute the key and cache decision without running ``` `run ls --near` explains a stale check: it adds a "near misses" section naming, for each recent non-reusable run, the mismatch reason (e.g. `input-tree-differs`) and a bounded sample of the changed input paths. `run explain` reports the same reason. Add `--json` to any of these for a stable machine form; `run ls --json` and `run explain --json` report the same facts and share one near-miss shape. See [awa help json](json.md). ## Evidence and privacy Captured stdout/stderr is stored verbatim as durable evidence, so a command that prints a secret stores it — awa does not redact output. Allowlisted env values are keyed and passed to the child but stored only as a redacted identity, never raw. If output exceeds the capture limit it is stored truncated and every surface (footer, replay, `run show`) says so with the omitted byte count, so a partial payload is never mistaken for the full output. The child does not inherit your environment: it gets the built-in baseline (your locale included, unchanged), what `env_allowlist` adds, and the fixed advisory marker `AWA_RUN=1` — all keyed. See [awa help privacy](privacy.md). ## Effect roots vs excludes The central run-cache decision: - The command **writes or refreshes** a generated directory during the run, and that output is disposable — it may safely be absent after a replay → `[run].extra_excludes` or `.awaignore`. Otherwise the self-generated output makes every run non-reusable. - The command **writes** output you actually need on disk afterwards → `awa run --record`. Excluding it would let a replay report success with the output missing. - The command only **reads** an already-produced generated directory that the run input scan no longer sees → `[run].extra_effect_roots`. Later changes to that generated state should invalidate reuse. - That directory is still **visible to the input scan** → configure nothing. Its contents already key the run; an effect root would add no coverage. - The command is a deploy, migration, formatter, live probe, or otherwise non-reusable → `awa run --record`. Keep durable evidence without publishing a reusable hit. Picking an effect-root selector (literal, never globs): - The same directory name at **any** depth, typically repeated across monorepo packages → a name: `extra_effect_roots = ["bin"]`. - Exactly **one** location → a project-relative path: `extra_effect_roots = ["artifacts/bin"]`, which watches neither `other/bin` nor `other/artifacts/bin`. Rules: - Writing to a watched effect root during the run makes the result non-reusable. - The two lists are separate: the watched set is the built-in effect roots plus `extra_effect_roots`. An exclude you add yourself is NOT watched, so an excluded, unwatched directory is invisible to the cache in both directions. - Excluding a path therefore weakens what `awa run` can observe, so do it intentionally. - awa will not auto-edit config to improve the cache hit rate. ## See also - [awa help record](record.md) - [awa help refs](refs.md) - [awa help ignores](ignores.md) - [awa help config](../reference/configuration.md) - [awa help privacy](privacy.md) --- source: https://awarer.one-man-wolf-pack.com/docs/record/ --- # awa run --record — supervised runs ```text awa run --record [flags] -- [args...] ``` Use `--record` for commands that must not be cached but whose execution still matters: deployments, migrations, Ansible playbooks, formatters, long validations, and anything whose log you may need later. `--record` always executes the command. It never reads an existing cache hit and never publishes a reusable hit. It captures stdout and stderr, the exit code or terminating signal, duration, the working directory, the command line, and the observed before/after state around the run — as durable history. ```text awa run --record --display tail:200 -- ansible-playbook site.yml awa run show --last --tail 500 # inspect the recorded run awa changes run::before..run::after # what the command changed awa run log # every recorded run awa log --all # full timeline: checkpoints # plus recorded runs ``` Even an ordinary `awa run` records a mutating or failed execution as history; only a clean, non-mutating run becomes reusable. Reach for `--record` when you know up front that caching is unsafe but you still want durable evidence. ## Long-running and noisy commands A recorded run is the better shape for a long deploy, migration, or full test sweep than redirecting to a scratch file. Bound what reaches the terminal while the full log is still stored: ```text awa run --record --display tail:200 -- awa run --record --display none -- ``` `` is the invocation to supervise. `--display` affects this terminal only — never what is captured, and never the exit code, which is the wrapped command's own whenever the command actually ran (see [awa help exit-codes](exit-codes.md) for the one awa-origin exception). Interrupting a recorded run leaves a non-reusable history entry rather than a partial result that could later replay. ## What a record proves, and what it does not A record proves what that execution printed, when it ran, from which directory, with which exit status, and how the observed state differed before and after it. It does not prove that running the command again now would do the same thing, and it is never a cache hit: a recorded run carries the reuse reason `record-only` and is never offered for replay, however clean it was. Nor does it capture anything awa does not observe — network services, databases, wall-clock behavior, and files outside the project root are all outside the evidence. ## Evidence of what changed The observed before/after states are addressable — for every stored run, not only a recorded one — which is how you check the effect rather than trusting the log: ```text awa changes run::before..run::after awa diff run::before..run::after ``` `` is the run id printed in the footer. Ignored and protected paths are outside the observed scope, so a change confined to them does not appear here. ## See also - [awa help run](run.md) - [awa help inspect](inspect.md) - [awa help diff](diff.md) - [awa help refs](refs.md) - [awa help workflows](workflows.md) --- source: https://awarer.one-man-wolf-pack.com/docs/inspect/ --- # finding stored runs and their output Every command executed through `awa run` is recorded, and its output is stored durably whether the run was cacheable or not — as long as capture is on, which it is by default. A project that sets `[run].capture_output = false` still gets the run in the history, but with nothing to read (reuse reason `capture-disabled`). This page is how you find a run again and read what it printed — instead of re-running it, or redirecting to a scratch file you will have to remember the name of. ## Find the run ```text awa run log awa run log -n 10 awa run log --command awa run ls awa run ls --all ``` `` matches anywhere in the recorded command line. `awa run log` is chronological history, newest first: everything that was recorded, including failed, mutating, and record-only runs. `awa run ls` is a different question — which stored runs are reusable for the *current* state — so a run missing from `ls` is not missing from history. `awa run ls --all` lists the non-reusable ones too, each with its reason token. There is no time-range filter. To find a run from a particular moment, narrow with `--command` and read the timestamps, choosing how they are rendered with `--time relative`, `--time local`, or `--time utc`. `awa run log` takes its default rendering from the `[ui]` config table, so a project that prefers absolute timestamps sets it once instead of passing `--time` every call. `awa run show` is the exception: it reads stored records only and loads no configuration, so its default stays `relative` whatever `[ui]` says. `--json` is unaffected either way — machine output is always UTC. ## Read the output ```text awa run show --last awa run show --last --tail 500 awa run show --last --grep "" awa run show --meta awa run show --stdout awa run show --stderr ``` `` is a run id (a unique prefix is enough) and `` is a regular expression. Exactly one of an id or `--last` selects the run. - `--meta` is metadata only: command, cwd, exit, duration, cacheability, reuse state, mutation outcome, key, and per-stream byte counts. - `--stdout` and `--stderr` write one raw stream and nothing else, so they are safe to pipe. - `--tail ` and `--grep ` filter what is shown; combined with a stream selector they filter that stream, otherwise both streams are shown under labelled headers. A tailed view says `(tail — earlier lines omitted)` so a partial view is never mistaken for the whole log. `awa run show` reads stored records only. It never scans the current worktree and never loads project configuration, so it keeps working when the tree has moved on or a config file is malformed. ## What the evidence does and does not prove Stored output is evidence of what that execution printed at that time. It is not a statement about the current state, and reading it is not the same as re-running the command. `awa run show --json` is metadata by default and reports each stream's integrity as `unverified`: the record was inspected, but no payload bytes were opened. Integrity becomes `verified` for a stream only when an explicit `--tail` or `--grep` read opens it and checks it against its recorded hash — and a stream that fails that check is a loud error, never a document quietly claiming `verified`. A stream you did not select stays `unverified`. Output beyond the capture limit is stored truncated, and every surface says so with the omitted byte count (`(stored , omitted)`). A partial payload is never presented as complete. Captured stdout and stderr are stored verbatim and are never redacted, so a command that printed a secret stored that secret. See [awa help privacy](privacy.md). ## What a run changed Every stored run — a record-only one, an ordinary cached one, a failed one — has an observed state before and after it, usable as state references: ```text awa changes run::before..run::after awa diff run::before..run::after ``` That is the honest way to answer "what did that command actually do", and it is the standard follow-up after a record-only run. Where one side has no stored file contents, `diff` reports the change as hash-only rather than inventing content. ## Delete stored runs ```text awa run rm awa run rm --command --dry-run awa run rm --older-than ``` `` accepts `d`, `h`, `m`, and `s` units, so `30d` and `720h` are both valid. Explicit ids and the filter flags are mutually exclusive, and `--dry-run` reports what would be removed without removing it. Deleting a run deletes the evidence, not the effect: whatever the command did to the worktree stays done. For routine cleanup driven by policy rather than by hand, prefer [awa help gc](gc.md). ## The wider timeline ```text awa log awa log --all ``` `awa log` lists explicit checkpoints only. `awa log --all` interleaves recorded runs and git commit boundaries as context markers — the commit boundaries are markers, not awa state references. ## See also - [awa help run](run.md) - [awa help record](record.md) - [awa help refs](refs.md) - [awa help privacy](privacy.md) - [awa help gc](gc.md) - [awa help json](json.md) --- source: https://awarer.one-man-wolf-pack.com/docs/checkpoints/ --- # awa checkpoint — explicit checkpoints ```text awa checkpoint [-m ] ``` `awa checkpoint` records an explicit checkpoint of the whole configured worktree scope. These are user-authored markers of "what did this project look like at this moment". ```text awa checkpoint -m "" ``` `` is a short description of this baseline; replace the placeholder, and do not copy it literally. A checkpoint has one durable address: the immutable id `awa checkpoint` prints. The message explains the checkpoint to a human and is never used to look one up. Use a specific message each time — do not reuse one generic message forever. `awa checkpoint` also prints copyable follow-up ranges (`awa changes ..now`, `awa diff ..now`); keep the id if a review/fix loop will continue, because `latest` is shared project-local state and can move if another agent checkpoints. Any unambiguous leading portion of an id works wherever the full id does (see [awa help refs](refs.md)). `awa checkpoint` takes no path argument — it always covers the full scope; a path is a usage error. Path filters belong to comparison output (see [awa help diff](diff.md)), not to partial checkpoints. What a checkpoint records is project policy, not a per-invocation flag, and it lives in the `[checkpoint]` config table: whether file contents are stored or only hashed, whether renames are detected, and the default diff context. Which paths are in scope is a separate decision with its own rules (see [awa help ignores](ignores.md)); within that scope a checkpoint always includes files git does not track, and no setting changes that. Turning off `store_file_contents` is the one that changes a checkpoint's recorded storage policy, so records made before and after that change are not equivalent evidence. The keys and their defaults are in [awa help config](../reference/configuration.md). ## Listing ```text awa log explicit checkpoints only (the default timeline) awa log --all explicit checkpoints plus recorded runs ``` Comparisons default to the range `latest..now`, so right after a checkpoint: ```text awa changes # summarize changes since the latest checkpoint awa diff # textual diff, latest..now ``` A clean delta only means "no changes since that checkpoint" — do a full uncommitted-worktree pass before final acceptance, not just the checkpoint delta. ## A checkpoint is also a repair source Comparison is not all a checkpoint is for: `awa restore` uses one as the evidence for putting selected paths back after an accidental generator or formatter rewrite. Preview first, name the paths, and let `--apply` be the deliberate step — see [awa help restore](restore.md). ## See also - [awa help diff](diff.md) - [awa help restore](restore.md) - [awa help refs](refs.md) - [awa help workflows](workflows.md) - [awa help status](status.md) --- source: https://awarer.one-man-wolf-pack.com/docs/diff/ --- # awa changes / awa diff ```text awa changes [range] [path...] awa diff [range] [path...] ``` Both compare two states. `changes` summarizes what differs (added/modified/ removed, optionally `--stat` or `--name-only`); `diff` shows the textual diff. If no range is given, both use `latest..now` (see [awa help refs](refs.md) for the range syntax). ```text awa changes # latest..now, summary awa diff @-2..@-1 # between two checkpoints awa diff -2 # shortcut for @-2..now awa changes ..now ``` `` is the immutable id `awa checkpoint` printed; any unambiguous leading portion of it works too. An empty changes/diff delta means only "no changes since that baseline" — never that the whole worktree is reviewed. Use the delta to verify a focused fix, then inspect the full current uncommitted worktree before final acceptance. ## Git context When the project is a git repo, `changes`/`diff` name the current git HEAD and add a "note:" when the baseline checkpoint predates or diverges from it — the baseline is still valid (useful for archaeology or a long review), but the delta may not map onto current HEAD, so review the full git diff before accepting. `awa log --all` interleaves git commit boundaries between awa records as context markers; a commit boundary is not an awa state reference and cannot be used in a range. ## Summary forms ```text awa changes --stat # one-line change-count summary awa changes --name-only # changed paths only awa diff --stat # the same summary for a content diff awa log --oneline # compact checkpoint listing ``` These are human output modes. Combining any of them with `--json` is a usage error, because the JSON document already carries the summary and the paths — see [awa help json](json.md). Rename detection is on by default and is bounded: past its limit, comparison reports the pair as a delete plus an add rather than spending unbounded time. `--no-renames` turns it off explicitly. ## Path filters Path filters restrict the comparison output to the given paths; they are resolved relative to your current directory and normalized to the project root. They filter output only — they do not create partial states. ## Scope caveats A comparison can only report what was scanned. Paths excluded by the ignore rules are not observed at all, so a change confined to them shows as no change here; see [awa help ignores](ignores.md). Inputs the scan could not read are counted as skipped and reported rather than silently dropped. A checkpoint delta is also not the uncommitted git diff: it is measured from the baseline you chose, which may be older or newer than HEAD. ## Diff algorithm `awa diff` defaults to the histogram algorithm; pass `--algorithm myers` for Myers. Selecting two different algorithms is a usage error. Binary or oversized files are compared hash-only (changed/unchanged) rather than shown as text. The project-wide default lives in the one-key `[diff]` config table, and the default hunk context in `[checkpoint].diff_context`; `--algorithm ` and `--context ` override them for a single invocation. Neither choice changes what is compared, only how the comparison is rendered — see [awa help config](../reference/configuration.md). Run observations can be used as state references (`run::before` / `run::after`). When one side has no stored content, `diff` degrades to a hash-only comparison for the affected paths. ## See also - [awa help refs](refs.md) - [awa help checkpoints](checkpoints.md) - [awa help record](record.md) - [awa help workflows](workflows.md) - [awa help ignores](ignores.md) --- source: https://awarer.one-man-wolf-pack.com/docs/restore/ --- # awa restore — repair selected paths from an immutable state ```text awa restore -- # preview (default) awa restore --dry-run -- # the same preview, spelled out awa restore --apply -- # the only mutating form awa restore --apply --all ``` `awa restore` repairs the worktree from one immutable stored state. It exists for mistakes made while the worktree is dirty: a generator that rewrote a subtree, a formatter applied to the wrong directory, a handful of files that should go back to a reviewed checkpoint. It is not a Git replacement. It does not read commit history, does not check out a commit, and does not touch files outside awa's evidence. ## Preview first, apply on purpose Preview is the default and changes nothing: no worktree path, and no stored awa state. `--dry-run` selects that same mode explicitly; combining it with `--apply` is a usage error, because the two name different modes. A selection is mandatory: one or more paths, or an explicit `--all`. An omitted selection is a usage error, never a whole-project restore. `--all` means all **proven restorable awa scope**, not every file under the project root. There is deliberately no force option. When the evidence is incomplete, restore refuses and tells you which reason blocked which path. ```text awa restore -- generated/client awa restore --apply -- generated/client awa changes ..now -- generated/client ``` The preview prints the exact apply command using the **resolved immutable id**, never the moving reference you typed, so running the suggestion cannot act on a state that moved in between. ## Sources The source must resolve to immutable stored evidence: - a checkpoint id or an unambiguous id prefix; - `latest` or `@-N`, resolved once and reported as a full checkpoint id; - `run::before` or `run::after`, while that observation is retained. A run observation records identity only: it is useful for comparison, for absence inside its observed scope, and for a symlink's stored target, but it supplies no regular-file bytes, so restoring one is reported as `hash-only-content`; - `restore::before`, a previous restore's recovery observation, while it is retained. `now` is not a source, and a range is not accepted: the source supplies the desired bytes, and the current worktree is always the destination. See [awa help refs](refs.md) for the reference syntax. ## What it can and cannot prove An entry hash proves identity, not recoverability. A regular file is restorable only when its source state points at a verified content blob. `hash-only` evidence stays useful for comparison but cannot manufacture bytes, and awa never recovers content from a current file that happens to match, from another path, from Git, or from the network. Symlinks are recreated from their stored target and are never followed. Special files (devices, sockets, fifos) are not restored. A path *reached through* a symlink — which only exists when the project enables `follow_symlinks` — is a boundary rather than work. awa writes and deletes through a no-follow descent, so it cannot act at a path whose components belong to a link's target: a change there is reported as `symlink-ancestor` instead of previewing as work that would fail. An unchanged path reached that way needs no mutation and is simply counted as already-matching scope. Deletion needs positive proof: the path must be currently observed and provably absent from a **policy-compatible** source. If the source was observed under a different scan policy, absence is not proof — the path may simply have been out of scope then — so deletions are not planned. Directory removal is empty-only and deepest-first; awa never recursively deletes a worktree path. Ignored paths are outside awa's evidence boundary. They are never restored and never deleted for being absent from a source manifest. ## Blocked reasons When a path cannot be restored, the preview names why with a stable token: `hash-only-content`, `blob-missing`, `blob-corrupt`, `skipped-boundary`, `ignored-boundary`, `policy-incompatible`, `observation-unstable`, `out-of-proven-scope`, `path-conflict`, `root-escape`, `symlink-ancestor`, or `unsupported-entry-kind`. `--apply` refuses while any of them applies. Selecting a path that awa cannot see is reported as `ignored-boundary` rather than as an empty result: "nothing to do" and "this path is outside my evidence" are different answers, and only one of them means the path is already correct. Selecting a path a `restore::before` source never covered is reported the same way, as `out-of-proven-scope` — that record proves exactly the paths one restore was going to change and holds no evidence about anything else. ## Undo: the recovery observation Before its first write, `--apply` durably records the exact current state it may replace or delete — with verified content — as an immutable **recovery observation**, and prints its `restore::before` reference: ```text recovery: restore::before undo: awa restore --apply restore::before -- generated/client ``` Content is captured whatever the project's storage preferences are — including `[checkpoint] store_file_contents = false` and a file large enough that `[hashing] large_file_policy = hash-only` recorded its identity only. Those bytes are exactly what would otherwise be unrecoverable, and a readable file stays readable no matter what a checkpoint would have stored. If the capture cannot be completed, apply refuses before mutating. It preserves what the worktree held when it was recorded, and nothing else. Bytes written after that moment are not in it — which is why apply re-proves each selected file's content identity immediately before touching it and reports a conflict instead of overwriting work no evidence describes. A recovery observation is system-owned evidence, not a checkpoint. It never appears in `awa log`, never moves `latest`, and is never selected by a checkpoint-relative reference; it shows up in `awa log --all` and as a state reference. It is one immutable record per applied restore, not a permanent backup and not an undo stack. Its retention is `[gc].keep_restores_for` (default `14d`), independent of `keep_runs_for`. Ordinary `awa gc` reclaims older observations, and an explicit `awa gc --older-than` overrides the window for that invocation — so treat it as evidence with a lifetime, not as a backup. ## When a multi-path apply stops Filesystem mutation across several paths is not transactional. If an external writer, an I/O failure, or an interruption stops a commit after the first path, restore reports `partial` with completed and remaining counts — never success. Rerunning re-plans from what the worktree is now and does only the remaining work. A file replacement leaves its destination holding either the old content or the complete new content: the bytes are written to a temporary file in the same directory and renamed into place. Two shapes cannot be done in one step — replacing a directory with a file or a link, and replacing a file or a link with a directory — because the old node has to be removed first. If a commit stops between those two steps that one path is left absent, and restore still reports `partial` even when no operation completed. It never reports `conflict` or `cancelled` in that case: those say the worktree was not touched. The recovery observation is what the absent path is restored from. Restore acquires the locks that serialize it against another restore and keep `awa gc` from reclaiming the blobs it is reading. It cannot lock your editor or your build tool; it observes the selected state twice and, immediately before touching each path, re-proves that path's kind, permission bits, symlink target, and — for a regular file — its content identity. Only a write that lands between that final read and the mutation itself can escape, which is the honest boundary. ## Machine output `--json` emits one typed document carrying the `awa-restore/v1` contract token, the full resolved source identity, the normalized selection, deterministic counts, the evidence boundary, stable reason tokens, completed/remaining facts, and the recovery observation's id and reference. It never contains file bytes. See [awa help json](json.md). ## See also - [awa help checkpoints](checkpoints.md) — recording the states restore reads - [awa help refs](refs.md) — the reference syntax - [awa help diff](diff.md) — inspecting a delta before and after a restore - [awa help gc](gc.md) — retention of recovery observations --- source: https://awarer.one-man-wolf-pack.com/docs/refs/ --- # state reference syntax Commands that name a stored state — `changes`, `diff`, and `restore` — share one reference syntax: ```text now current workspace state latest latest checkpoint @-1 latest checkpoint @-2 previous checkpoint @-N Nth checkpoint from the end (N >= 1) a checkpoint by its full immutable id a checkpoint by any unambiguous leading portion of it run::before a stored run's observed state before it ran run::after a stored run's observed state after it ran restore::before an applied restore's pre-restore recovery observation ``` Ranges use `A..B`: ```text latest..now @-2..@-1 ..now run::before..run::after ``` If a range is omitted, commands use `latest..now`. For `changes` and `diff`, the numeric shortcut `-N` means `@-N..now`. A checkpoint's only durable address is its immutable id. A checkpoint message is human context and is never a reference. A token that cannot be an id or id prefix is rejected as invalid syntax before any stored state is read; a well-formed prefix that matches nothing is not found, and one that matches several checkpoints fails as ambiguous rather than picking one — lengthen it. `latest` is shared project-local state, not an agent-private bookmark: it always names the newest checkpoint, so it moves whenever any agent or user runs `awa checkpoint`. For precision across a long review/fix loop, keep the id `awa checkpoint` printed and use an explicit range (`..now`) instead of relying on `latest`. Use `awa log -n 5` to inspect recent checkpoints when a default baseline is surprising. The `run:` forms work for any stored run, not only a `--record` one: an ordinary cached run and a failed run are addressable the same way. A run observation stores identity, not content: it compares, it proves what was absent inside its observed scope, and it keeps a symlink's target, but it holds no regular-file bytes — so `awa diff` against one degrades to hash-only and `awa restore` from one reports `hash-only-content` rather than writing a file. The `restore:` form names the immutable state an applied `awa restore` recorded before its first write. Unlike a run observation it carries content for every regular file it covers — that is the point of it — whatever storage policy the project applies to checkpoints. There is no `restore::after`: the state after a restore is the current worktree, which `now` already names. It stays resolvable while `[gc].keep_restores_for` retains it — see [awa help restore](restore.md). It is system-owned evidence, so it never appears as a checkpoint and is never selected by `latest` or `@-N`; `awa log --all` lists it and `awa state resolve` deliberately does not name it. `awa run explain` does not use this syntax: it selects a run with `--last` or `--from-run --to-now`, not a state reference or `A..B` range. Git commit boundaries shown in `awa log --all` are context markers, not awa records: they carry no reference token and cannot be used as a state reference or in an `A..B` range. ## See also - [awa help diff](diff.md) - [awa help restore](restore.md) - [awa help record](record.md) - [awa help checkpoints](checkpoints.md) - [awa help workflows](workflows.md) --- source: https://awarer.one-man-wolf-pack.com/docs/config/ --- # awa config — configuration schema, precedence, and when to change it ## Layer precedence Configuration is layered, lowest precedence first: ```text product defaults awa.toml optional shared project config, committable .awa/config.toml optional local override, ignored/private --config optional explicit invocation override (above shared/local) CLI flags highest ``` A later layer REPLACES a key, and for a list-valued key that means the whole list, never a merge. A local `.awa/config.toml` that sets `[scope].extra_excludes` discards the shared `awa.toml` list rather than adding to it, and the same is true of `include`, `env_allowlist`, `default_scope`, and `extra_effect_roots`. To keep a shared list and add to it, restate the shared entries in the overriding layer. `awa config effective` shows the resolved list and the layer it came from, which is the reliable way to catch a list you did not mean to drop. Each active layer that changes observation, hashing, diff, run cache identity, storage, or output policy is folded into the relevant config identity, so a reused run or checkpoint reflects the config it actually ran under. Invalid config in any active layer fails loudly and names the layer and path. Shared vs local: - `awa.toml` — share scan/run policy with all contributors and agents. - `.awa/config.toml` — personal overrides that must not be committed. - `.awaignore` — committable native ignore patterns. - `--config ` — one-off or CI invocation config. ## Discover and manage config from the binary ```text awa config template annotated template (redirect to a file) awa config init --shared write a committable awa.toml awa config init --local write a private .awa/config.toml awa config path show the shared and local paths and which exist awa config show print a layer's raw contents awa config effective the composed config plus each value's origin layer ``` ## Reference Defaults are shown; an absent key keeps its default. ### [scope] — Scan scope (history/checkpoint family and the shared base) The common scan boundary shared by awa checkpoint/changes/diff and, through extra_excludes, the run input scan. Only additive user values live here; the product baseline and protected defaults are built in. - **`include`** (path list, default: `["."]`) - Directories/files the scan includes; an explicit narrowed scope outranks every configurable and default exclude. - When to change: Narrow to a subtree, or bring back a path a baseline/ignore rule would otherwise drop. - **`extra_excludes`** (path list, default: `[]`) - Additive common excludes applied to both the history family and the run input scan, on top of the built-in baseline. - When to change: Exclude a project-specific directory from all scans. - **`use_gitignore`** (bool, default: `false`) - Whether .gitignore participates as an ignore source for the history family. Off by default: git ignores answer "what not to commit", not "what can affect a command". - When to change: Turn on only if your .gitignore genuinely matches what should not be observed. - **`use_awaignore`** (bool, default: `true`) - Whether .awaignore participates for the history family. On by default; .awaignore is awa's committable native ignore file. - When to change: Turn off to ignore .awaignore files entirely. - **`follow_symlinks`** (bool, default: `false`) - Whether the scanner follows symbolic links. - When to change: Enable when scoped content lives behind symlinks you trust. - **`symlink_max_depth`** (int, default: `16`) - Maximum symlink chain depth followed when follow_symlinks is on. - When to change: Raise or lower the guard against deep or cyclic link chains. - **`allow_symlink_root_escape`** (bool, default: `false`) - Whether a followed symlink may resolve outside the project root. - When to change: Enable only when you deliberately depend on out-of-root linked content. ### [history] — History-only excludes Excludes that affect awa checkpoint/changes/diff but never the run input scan, so a generated artifact can stay out of local history while remaining a real command input. The history family inherits its ignore-source policy from [scope]. - **`extra_excludes`** (path list, default: `[]`) - Additive history-only excludes, on top of the built-in history defaults (dist, build, coverage). - When to change: Keep a generated directory out of checkpoints/diffs while runs still key it. ### [hashing] — Content hashing and index trust Local content identity is fixed: awa hashes worktree content with BLAKE3 and persists every local digest with the blake3: prefix followed by lowercase hex. The primitive is product behavior, not a setting — there is no key here to change it, and only the policy governing how it is applied is configurable. The SHA-256 you see in a release checksum file, an exported documentation manifest, or a site asset digest is a separate external integrity convention and takes no part in local evidence identity. - **`trust_mode`** (enum: normal | strict | fast, default: `normal`) - How aggressively the worktree index is trusted to skip rehashing unchanged files. fast compares size and mtime only, which can miss a same-size same-mtime rewrite, so a run observed under it is recorded but never published as reusable. - When to change: Use strict for integrity-critical work; use fast only where losing run reuse entirely is an acceptable price for scan speed. - **`max_file_size`** (byte size (B/KiB/MiB/GiB/TiB), default: `50MiB`) - Threshold above which large_file_policy applies. - When to change: Raise to store larger blobs, or lower to keep the store lean. - **`large_file_policy`** (enum: hash-only | store | skip, default: `hash-only`) - What awa does with files above max_file_size: hash-only keeps them in tree hashes without storing blobs. - When to change: Use store to keep large blob content, or skip to leave them out of hashing entirely. ### [checkpoint] — Checkpoint recording - **`store_file_contents`** (bool, default: `true`) - Whether checkpoint blobs are stored (affects checkpoint policy identity). - When to change: Turn off to record checkpoint hashes without keeping content. - **`diff_context`** (int, default: `3`) - Default number of context lines in checkpoint diffs. - When to change: Adjust the default hunk context. - **`rename_detection`** (bool, default: `true`) - Whether diffs detect renames. - When to change: Turn off for pure add/delete diffs. ### [run] — Cached command execution The run cache. extra_excludes is additive run-only; the effective run input excludes omit the history-only defaults so a build artifact stays a real command input. extra_effect_roots watches generated-output directories a command reads but does not produce (see "Effect roots vs excludes"). A wrapped command never inherits the full ambient environment: it receives the built-in baseline, whatever env_allowlist adds, and the fixed advisory marker AWA_RUN=1, and every one of those participates in the cache key. Run `awa config effective` to see the resolved inherited names and injected facts. - **`default_scope`** (path list, default: `["."]`) - The run input scan scope when --scope is not given. - When to change: Narrow the default set of inputs a run keys on. - **`extra_excludes`** (path list, default: `[]`) - Additive run-only excludes, on top of the baseline. Excluding a path weakens what the run can observe, so do it intentionally. - When to change: Exclude self-generated output a command writes during the run. - **`use_gitignore`** (bool, default: `false`) - Whether .gitignore participates as an ignore source for the run input scan (keyed into the run cache). Off by default. - When to change: Turn on only if .gitignore matches what should not affect a command. - **`use_awaignore`** (bool, default: `true`) - Whether .awaignore participates for the run input scan. On by default. - When to change: Turn off to ignore .awaignore for runs. - **`env_allowlist`** (name list, default: `["CI", "NODE_ENV"]`) - Environment variable names, on top of the built-in baseline, folded into the run cache key and passed to the child. The baseline already covers execution (PATH, HOME, SHELL, TMPDIR, the Windows equivalents) and the caller's locale (LANG, LANGUAGE, LC_*), so listing one of those is rejected as redundant; AWA_RUN is reserved because awa injects it. - When to change: Add a variable your commands depend on so it keys the cache. - **`ttl`** (duration (d/h/m/s), default: `7d`) - Freshness window a reusable run entry stays eligible for a hit. - When to change: Shorten or lengthen how long a cached result is served. - **`max_stdout_size`** (byte size, default: `100MiB`) - Capture limit for stdout; output beyond it is truncated in stored evidence. - When to change: Raise for commands with very large output. - **`max_stderr_size`** (byte size, default: `100MiB`) - Capture limit for stderr. - When to change: Raise for commands with very large error output. - **`capture_output`** (bool, default: `true`) - Whether run output is captured and stored for replay/inspection. - When to change: Turn off to run without recording output. - **`cache_failed_runs`** (bool, default: `true`) - Whether non-zero-exit runs are cached. - When to change: Turn off to always re-run failed commands. - **`extra_effect_roots`** (name/path list, default: `[]`) - Additive watched generated-output selectors on top of the built-ins. Each is either a directory NAME matched wherever it appears ("bin") or an exact project-relative PATH matched only there ("artifacts/bin"). Literal, never globs. Additive only — a built-in cannot be silenced. - When to change: Watch a generated directory a command reads so later changes to it invalidate reuse. ### [gc] — Garbage collection retention - **`keep_last_checkpoints`** (int, default: `100`) - How many recent checkpoints gc retains. - When to change: Keep more or fewer checkpoints. - **`keep_runs_for`** (duration, default: `14d`) - How long run records are retained by gc. - When to change: Extend or shorten run history retention. - **`keep_restores_for`** (duration, default: `14d`) - How long a restore's pre-restore recovery observation — the evidence an applied restore can be undone from — is retained by gc. Independent of keep_runs_for. - When to change: Keep restore undo evidence longer (or shorter) than run history. ### [diff] — Content diff rendering - **`algorithm`** (enum: histogram | myers, default: `histogram`) - Text diff engine; histogram anchors on rare lines and falls back to myers locally. - When to change: Force myers for a stable, classic diff. ### [locks] — Writer/collector lock acquisition - **`timeout`** (duration, default: `5s`) - How long any interlock wait may last before the command fails with the lock-timeout exit code — including gc waiting for the exclusive collector lease another gc holds. A writer's lock is the one case that is not a wait: gc does not wait writers out, it suppresses its whole destructive pass, reports the lock as a blocked candidate, deletes nothing, and exits 0. Zero means fail fast; negative is a config error. - When to change: Raise on busy shared checkouts, or set 0 to never wait. ### [ui] — Human presentation Human output only; JSON always uses machine timestamps and never carries relative prose. - **`time`** (enum: relative | local | utc, default: `relative`) - How human output renders timestamps (log, run history). A --time flag overrides per invocation. - When to change: Prefer absolute local or utc timestamps over relative ages. ## Effect roots vs excludes The central run-cache decision: - The command **writes or refreshes** a generated directory during the run, and that output is disposable — it may safely be absent after a replay → `[run].extra_excludes` or `.awaignore`. Otherwise the self-generated output makes every run non-reusable. - The command **writes** output you actually need on disk afterwards → `awa run --record`. Excluding it would let a replay report success with the output missing. - The command only **reads** an already-produced generated directory that the run input scan no longer sees → `[run].extra_effect_roots`. Later changes to that generated state should invalidate reuse. - That directory is still **visible to the input scan** → configure nothing. Its contents already key the run; an effect root would add no coverage. - The command is a deploy, migration, formatter, live probe, or otherwise non-reusable → `awa run --record`. Keep durable evidence without publishing a reusable hit. Picking an effect-root selector (literal, never globs): - The same directory name at **any** depth, typically repeated across monorepo packages → a name: `extra_effect_roots = ["bin"]`. - Exactly **one** location → a project-relative path: `extra_effect_roots = ["artifacts/bin"]`, which watches neither `other/bin` nor `other/artifacts/bin`. Rules: - Writing to a watched effect root during the run makes the result non-reusable. - The two lists are separate: the watched set is the built-in effect roots plus `extra_effect_roots`. An exclude you add yourself is NOT watched, so an excluded, unwatched directory is invisible to the cache in both directions. - Excluding a path therefore weakens what `awa run` can observe, so do it intentionally. - awa will not auto-edit config to improve the cache hit rate. ## Pattern semantics - `.awaignore` — gitignore-like: globs, a trailing slash matches a directory, a leading slash anchors to the project root, and later rules override earlier ones. It is on by default; `.gitignore` is off by default. - `[scope].extra_excludes` and `[run].extra_excludes` — gitignore-style patterns, additive on top of the built-in baseline excludes. - `[run].extra_effect_roots` — literal selectors, never globs, in one of two forms. A single segment is a directory NAME matched by basename wherever it appears: `"target"` watches every `target/`. A slash-separated project-relative PATH matches that one location only: `"artifacts/bin"` watches `artifacts/bin` and neither `other/bin` nor `other/artifacts/bin`. Matching is case-sensitive and `/` is the separator on every platform. A backslash, a volume spelling, and a `.`/`..` component are rejected in either form; a path is also rejected when it begins or ends with a slash, holds an empty component, or names `.git` or `.awa`. Use `awa config effective` to see the resolved effective lists and the layer each value came from. --- source: https://awarer.one-man-wolf-pack.com/docs/ignores/ --- # scan inputs and ignore rules awa scans the worktree for two purposes: history (checkpoints, changes, diff) and run input (the files a wrapped command could read). Both honor these production defaults: - `.awa/` and `.git/` are always protected and never scanned; ordinary config cannot re-include them. - Baseline excludes (build/dependency caches such as `node_modules`, `target`, `__pycache__`, `.venv`, and similar) apply to both history and run input. - History-only excludes (`dist`, `build`, `coverage`) apply to checkpoints/diff but NOT to run input — a build or test must still see them, so they do not affect run cache keys. - `.awaignore` is ON by default (awa's native ignore source). - `.gitignore` is OFF by default. It answers "what should not be committed", not "what can affect a command", so a gitignored file is still a real run input. Because `.gitignore` is off by default, `awa run` sees files git ignores unless an awa rule (protected path, baseline exclude, or `.awaignore`) excludes them. ## Which layer am I looking at The layers apply in this order, and later ones cannot re-include what an earlier one protects: 1. **Protected** — `.awa/` and `.git/`. A hard boundary; no configuration overrides it. 2. **Baseline excludes** — dependency and cache directories, for both history and run input. 3. **History-only excludes** — `dist`, `build`, `coverage`. Hidden from checkpoints, changes, and diff; never hidden from run input, because a build or test must still see them. 4. **User rules** — `.awaignore`, plus `extra_excludes` in the `[scope]`, `[history]`, and `[run]` config sections, which are additive per family. An explicitly narrowed scope outranks excludes for the narrowed subtree: if you ask for a specific path with `scope.include` or `--scope`, you get it. The default scope of the whole project does not have that effect. The built-in layers are not listed in any config file, because they are product defaults rather than project policy. To see the lists that are actually in force, including the built-ins and which layer each value came from: ```text awa config effective ``` ## Why .gitignore is not the input boundary The two questions are different. `.gitignore` answers "what should not be committed"; awa's run scan must answer "what can affect this command". Generated files, local fixtures, and secrets are routinely gitignored and routinely change what a command does, so keying on git's answer would produce false cache hits — exactly the failure the cache is designed to avoid. Turning `.gitignore` on (`use_gitignore` in `[scope]` or `[run]`) is therefore a deliberate decision to stop keying on those files, not a tidiness setting. ## Ignored paths are outside the evidence An excluded path is not scanned, so it is not observed. Nothing awa records describes it: it is absent from checkpoints, from changes and diff output, from run input keys, and from a recorded run's before/after states. `awa` makes no claim about it and cannot restore it. That is the intended trade, but it has a consequence worth stating plainly: a change confined to ignored paths looks like "no changes" in every awa surface. When that matters — reviewing generated output, or checking what a formatter touched — either narrow the scope explicitly to include those paths, or use the project's own tooling instead of a checkpoint delta. ## Effect roots vs excludes The central run-cache decision: - The command **writes or refreshes** a generated directory during the run, and that output is disposable — it may safely be absent after a replay → `[run].extra_excludes` or `.awaignore`. Otherwise the self-generated output makes every run non-reusable. - The command **writes** output you actually need on disk afterwards → `awa run --record`. Excluding it would let a replay report success with the output missing. - The command only **reads** an already-produced generated directory that the run input scan no longer sees → `[run].extra_effect_roots`. Later changes to that generated state should invalidate reuse. - That directory is still **visible to the input scan** → configure nothing. Its contents already key the run; an effect root would add no coverage. - The command is a deploy, migration, formatter, live probe, or otherwise non-reusable → `awa run --record`. Keep durable evidence without publishing a reusable hit. Picking an effect-root selector (literal, never globs): - The same directory name at **any** depth, typically repeated across monorepo packages → a name: `extra_effect_roots = ["bin"]`. - Exactly **one** location → a project-relative path: `extra_effect_roots = ["artifacts/bin"]`, which watches neither `other/bin` nor `other/artifacts/bin`. Rules: - Writing to a watched effect root during the run makes the result non-reusable. - The two lists are separate: the watched set is the built-in effect roots plus `extra_effect_roots`. An exclude you add yourself is NOT watched, so an excluded, unwatched directory is invisible to the cache in both directions. - Excluding a path therefore weakens what `awa run` can observe, so do it intentionally. - awa will not auto-edit config to improve the cache hit rate. ## Pattern semantics - `.awaignore` — gitignore-like: globs, a trailing slash matches a directory, a leading slash anchors to the project root, and later rules override earlier ones. It is on by default; `.gitignore` is off by default. - `[scope].extra_excludes` and `[run].extra_excludes` — gitignore-style patterns, additive on top of the built-in baseline excludes. - `[run].extra_effect_roots` — literal selectors, never globs, in one of two forms. A single segment is a directory NAME matched by basename wherever it appears: `"target"` watches every `target/`. A slash-separated project-relative PATH matches that one location only: `"artifacts/bin"` watches `artifacts/bin` and neither `other/bin` nor `other/artifacts/bin`. Matching is case-sensitive and `/` is the separator on every platform. A backslash, a volume spelling, and a `.`/`..` component are rejected in either form; a path is also rejected when it begins or ends with a slash, holds an empty component, or names `.git` or `.awa`. Use `awa config effective` to see the resolved effective lists and the layer each value came from. ## See also - [awa help run](run.md) - [awa help config](../reference/configuration.md) - [awa help diff](diff.md) - [awa help privacy](privacy.md) - [awa help troubleshooting](troubleshooting.md) --- source: https://awarer.one-man-wolf-pack.com/docs/doctor/ --- # awa doctor — diagnose and repair local state ```text awa doctor [--repair] [--strict] ``` `awa doctor` inspects the durable `.awa/` state — the checkpoint store, blob store, run cache, worktree index, lock files, and the `.awa/` git guard — and prints a one-line health verdict plus one line per finding. It also raises local evidence/privacy findings: secret-looking env allowlist names, content storage in a project that appears to hold secrets, overly broad `.awa/` permissions, and nested or ancestor `.awa` markers (see [awa help privacy](privacy.md)). ```text awa doctor # report health and any findings awa doctor --repair # also perform the safe, mechanical repairs awa doctor --strict # recompute hashes instead of trusting stat signatures awa doctor --json # machine-readable findings (severity, subsystem, code) ``` Each finding is tagged by the action it invites: `[repaired]` for one `--repair` fixed, `[repairable]` for one `--repair` would fix, otherwise its severity. `--repair` performs only safe, mechanical fixes (such as restoring the `.awa/` git guard or removing an orphaned temp artifact); it never touches your worktree. The exit status is the diagnosis, not an awa failure (like `awa run`, there is no "awa:" error line): a healthy or warnings-only run exits 0, while unrepaired errors or unrepaired repairable findings exit 5 (local state needs an action). That code does not mean damage on its own: an unrepaired guard file earns it just as a corrupt record does, so read the findings rather than the code. ## Finding codes Every finding carries a stable machine code from a closed set, so a script can branch on the code rather than on the message. They group by subsystem: ```text config-invalid a config layer is present but not valid required-dir-* a required .awa/ directory is missing or wrong checkpoint-* a checkpoint record, manifest, or blob is corrupt, missing, or in a schema this awa cannot read run-* a stored run's metadata, pointer, or payload is corrupt, or in a schema this awa cannot read restore-recovery-* a restore recovery observation is unreadable, or its captured content is gone — that restore can no longer be undone index-* the worktree index is unreadable, schema-invalid, or stale lock-stale, lock-unknown a lock file left behind, or one awa cannot classify orphan-temp, temp-unreadable a leftover temp artifact under .awa/, or a temp location awa cannot read state-gitignore-* the awa-owned .awa/ git guard is missing, ineffective, or unreadable awa-tracked-by-git .awa/ content is tracked by git — evidence is being committed git-check-failed that git check could not be run at all state-permissions-too-broad .awa/ is readable beyond its owner env-allowlist-suspicious an allowlisted env name looks like a secret env-allowlist-injects-code an allowlisted env name can load or execute code in the wrapped command (LD_PRELOAD, DYLD_*, BASH_ENV, NODE_OPTIONS, RUBYOPT, ...) content-storage-enabled file contents are stored in a project that looks like it holds secrets nested-*, ancestor-* another .awa marker below or above this root, or a nested-marker scan that could not complete repair-failed a repair was attempted and did not succeed ``` ## What --repair will and will not do `--repair` performs exactly four safe, mechanical, awa-owned fixes, each for the findings that name it: - restores the awa-owned `.awa/.gitignore` guard when it is missing or ineffective; - removes an orphaned temp artifact under a known `.awa` temp location; - removes a lock record it proved stale — never one it cannot classify; - invalidates the worktree index when it is unreadable or stale, so the next scan rebuilds it. The index is acceleration-only state, so dropping it loses nothing durable. Everything else is diagnosed and left alone, including two cases worth knowing about before you reach for `--repair` expecting them. Overly broad `.awa/` permissions are reported, not changed: the finding names the exact `chmod` to run, because changing your filesystem permissions is your decision. And reclaiming unreferenced records is [awa help gc](gc.md)'s job — `doctor` never deletes a checkpoint, run, or blob. It never touches your worktree, never deletes a checkpoint or run you might still want, and never rewrites a corrupt record into a plausible-looking one. A finding it cannot fix safely stays reported — but only the findings the four repairs above cover are counted as repairable, so a finding doctor will never fix does not hold the exit code at 5 forever. ## When to use --strict `--strict` is not a doctor-local flag: it is the shorthand for the global `--trust-mode strict`, which doctor honors. That is why it appears in the usage line but not in the per-command flag table. By default the checks trust stat signatures (size and modification time) where they can. `--strict` recomputes content hashes instead. It is slower — on a large store, substantially — and it is the right choice when you suspect a file changed without its metadata changing, after a crash, or after copying a project between machines or filesystems. `--repair` and `--strict` combine: `awa doctor --repair --strict` diagnoses by content and then applies the safe fixes that diagnosis found. ## See also - [awa help gc](gc.md) - [awa help troubleshooting](troubleshooting.md) - [awa help privacy](privacy.md) - [awa help exit-codes](exit-codes.md) --- source: https://awarer.one-man-wolf-pack.com/docs/gc/ --- # awa gc — reclaim unreferenced local state ```text awa gc [--dry-run] [--committed] [filters] ``` `awa gc` removes state no longer reachable from a retained checkpoint, run, or restore recovery observation — unreachable blobs, expired runs, run entries in a schema this awa cannot read, expired checkpoints, expired recovery observations, and stale temp artifacts — under the retention policy in the `[gc]` config section. It takes the exclusive collector lease and waits (bounded by `[locks].timeout`) only for another collector holding it. It never waits out a writer: an in-flight checkpoint or run suppresses deletion outright rather than being raced — see Safety below. ```text awa gc --dry-run # show what would be removed and what is retained awa gc # reclaim now awa gc --json # machine-readable plan + execution summary ``` Both a dry run and a real run report the deletion candidates AND the retained or blocked ones, so the decision is always visible: you can see WHY nothing was removed, not just how much was kept. ## Why gc decided what it decided Every candidate carries one token from a single closed vocabulary, and each token maps to exactly one action — there is no "delete because it is the latest". This is that vocabulary, grouped by the action it justifies. The tokens are stable machine values: switch on them rather than on the surrounding prose. Deleted — proved disposable: ```text checkpoint-expired a checkpoint past the retention window run-expired a run older than the run retention window blob-unreachable a blob no retained checkpoint, run, or recovery observation references temp-stale a temp artifact left behind by a finished operation restore-expired a restore recovery observation past keep_restores_for ``` Retained — a retention rule protects it: ```text checkpoint-latest the newest checkpoint, always kept checkpoint-within-keep-last inside the keep_last_checkpoints window checkpoint-too-recent newer than the --older-than cutoff checkpoint-not-committed not covered by the current HEAD commit (--committed) run-too-recent newer than the --older-than cutoff run-not-committed not covered by the current HEAD commit (--committed) blob-referenced still referenced by a retained checkpoint, run, or recovery observation temp-fresh a temp artifact of a possibly in-flight operation restore-too-recent a recovery observation inside keep_restores_for git-unavailable git metadata could not be read, so nothing is assumed ``` Blocked — an obstruction stands in the way and nothing is removed: ```text lock-active another writer holds the lock lock-unknown a lock file awa cannot classify checkpoint-corrupt a checkpoint record that cannot be planned safely checkpoint-incompatible a checkpoint record in a schema this awa cannot read run-corrupt a run record that cannot be planned safely run-incompatible a run record in a schema this awa cannot read restore-corrupt a recovery observation that cannot be read, so blob reachability is incomplete and the sweep stands down ``` Skipped — excluded by a subsystem filter: ```text subsystem-filtered a restriction flag excluded an otherwise-deletable item ``` The two blocked families differ in exit status; see Safety below. ## Restore recovery observations An applied `awa restore` records the pre-restore state it overwrote as an immutable recovery observation (see [awa help restore](restore.md)). It is the only evidence that restore can be undone, so it has its own retention window, `[gc].keep_restores_for`, defaulting to `14d` and independent of `keep_runs_for` — shortening run history must never silently shorten the undo window. Recovery observations participate in ordinary unfiltered `awa gc`. `--runs-only`, `--checkpoints-only`, and `--blobs-only` exclude them, and there is no `--restores-only` flag. An explicit `awa gc --older-than ` overrides the configured window for that invocation, so awa does not print an "available until" date it cannot guarantee. `--committed` does not classify them: a commit advancing does not make the pre-restore state of an uncommitted worktree disposable, so only the age rule applies. An observation protected by an in-flight restore is retained, and one that cannot be read blocks the blob sweep rather than being guessed at. ## Narrowing what a run considers ```text --committed also reclaim WIP evidence from before the current commit --older-than only consider state older than a duration (e.g. 30d) ``` Per-subsystem restrictions and the retention override are listed in the generated [gc command reference](../commands/gc.md); this page covers when to reach for them rather than restating the flag table. Use `--committed` after a commit to reclaim the previous WIP cycle's evidence. It is conservative: it uses the current HEAD commit time only as an eligibility cutoff (never as proof of review), retains the latest checkpoint, and deletes nothing when git metadata is unavailable. Inspect it first with `awa gc --committed --dry-run`. The latest checkpoint is always retained, and so is every checkpoint inside the `keep_last_checkpoints` window. To keep more history, widen that window rather than protecting individual checkpoints — retention is a policy, not a per-record mark. ## Safety The destructive pass is all-or-nothing. If any candidate is blocked — by an active or unknown writer lock, by storage corruption, or by a record in a schema this awa cannot read — `gc` deletes nothing at all, not merely the blocked item. It never sweeps around an obstruction: a live writer may be publishing state the plan was computed against, so a partial sweep could reclaim something that just became reachable. ```text a writer holds a lock whole plan suppressed, nothing deleted exit 0 state needs a decision whole plan suppressed, nothing deleted exit 5 another gc is running never gets to plan; waits out the lease exit 6 ``` The obstruction is always reported, so you can see what stood in the way. The first two cases differ only in meaning: a lock is a normal "try again later", while corruption or an unreadable schema needs a person — run `awa doctor` first when `gc` reports either, and the report names which one it is. The third is a different mechanism: a second `gc` competing for the exclusive collector lease waits `[locks].timeout` and then fails with the lock-timeout code, so a script that treats every busy lock as exit 0 misreads it. What a blocked run does NOT give you is a complete picture of what could be reclaimed. `gc` reports the candidates it classified safely and skips the stages it cannot classify safely, with a warning naming the skip. In particular the blob sweep needs a complete reachability set, so a lock, a checkpoint or run record it cannot read, or an unanchored `--committed` cutoff makes it report only the blobs it proved *referenced* and classify no unreachable ones at all — a false "unreachable" would be data loss. The store's total footprint is still measured from the complete listing, but the would-free figure beside it is missing whatever that skipped stage would have found. Treat a blocked plan as "here is the obstruction", not as an estimate; clear the blocker and re-run `awa gc --dry-run` for an authoritative reclaim set. Freed/would-free bytes are the accounted bytes, summed from readable entries. An entry whose metadata does not decode contributes 0, because its size is never read — the reported figure is known/accounted bytes, not a guarantee of the exact physical space freed. `gc` never removes a record it cannot read. A record in a schema this awa does not speak is intact evidence with an unknown reference model: nothing can prove what it points at, so deleting it could orphan or destroy referenced content. It is retained under `checkpoint-incompatible` or `run-incompatible`, the blob sweep stands down, and `awa gc` exits with the state-action-required code. Resolving it is a deliberate act: drop a single stored run with `awa run rm `, or reset the store by deleting the evidence directories under `.awa/` and running `awa init` (see [awa help install](install.md)). Delete those directories rather than `.awa/` itself, which would take your private `.awa/config.toml` with it. ## See also - [awa help doctor](doctor.md) - [awa help checkpoints](checkpoints.md) - [awa help inspect](inspect.md) - [awa help troubleshooting](troubleshooting.md) --- source: https://awarer.one-man-wolf-pack.com/docs/troubleshooting/ --- # diagnosing awa — slow, stale, blocked, or broken Start from the symptom. Each section below ends at the topic that owns the detail, so you do not have to read the others. Two commands answer most questions before anything else: ```text awa status awa doctor ``` `awa status` is the bounded dashboard — baseline, drift, reuse, next steps. `awa doctor` is the exhaustive diagnosis of durable state, which status deliberately does not run. ## A check I expected to reuse ran again A miss is a statement about the current inputs, not a malfunction. Ask what changed: ```text awa run ls --near awa run explain -- ``` `` is the same invocation you wanted reused. Both report one token from the closed reason vocabulary in [awa help run](run.md); the common ones and what they mean for you: - `input-tree-differs` — an input the command can read changed. `--near` shows a bounded sample of which paths. - `effect-state-differs` — watched generated output (`build`, `dist`, `target`, `node_modules`, ...) changed or was deleted since the run. - `cwd-mismatch` — `awa run` is cwd-sensitive by design. Pin it with `--cwd `. - `env-mismatch` — an allowlisted environment fact differs. - `expired` — the entry is older than the configured run TTL. - `record-only` / `fast-trust-mode` — the run was recorded but was never offered for reuse in the first place. - `skipped-inputs` — the scan could not read some inputs, so the key could not honestly cover them. Do not make a miss disappear by weakening the key. `--refresh` and `--no-cache` change what this invocation does; they do not make an old result valid for changed state, and an old successful run is not reusable for state that moved. Record-only evidence is history, never a cache hit. If a command's point is its side effect, `awa run --record` is the right tool rather than a forced hit. ## awa feels slow awa names slowness it can classify and says nothing otherwise, so a quiet command is a command with no known cause — not a command that was fast. A note appears only when a stage crosses the interactive threshold, and at most two appear per invocation. `awa run`, `awa run explain`, `awa run ls`, and `awa status` all write them to stderr. There are two known causes. **A large watched generated-output root** (`large-effect-root`, component `run.effect-observation`) dominating state observation: ```text note: run state observation took ; effect root "" contains files hint: use `awa run --record` for evidence-only workflows, or review [run] effect roots ``` A root that could not be fully walked within its budget reports `exceeds files` instead of an exact count, never a fabricated number. **Reading the inputs** (`full-input-rehash`, component `run.input-observation`): ```text note: run input observation took ; hashed files under "." — the run-cache identity is read from file content, not from stat signatures, so a rewrite that leaves size and timestamps unchanged cannot replay a stale result hint: review what the run input scope covers with `awa help ignores`; never exclude a file the command actually reads — an unobserved input cannot invalidate a hit ``` The count is the exact number of regular files the scan hashed. A miss reads the inputs twice, before and after the command, and reports the slower pass as one note; a hit reads them once and reports that. Yes, a hit pays this too: proving a stored result still matches the worktree means reading the worktree. In JSON the same facts appear under `data.diagnostics.performance[]` with a stable `code`, `duration_ms`, the `component` it is attributed to, bounded `evidence`, and a typed `hint` — `record-mode` for the first cause, `review-run-scope` for the second — carrying the tokenized argv to run. This is information, not a misconfiguration to fix by re-running, and neither cause has a flag that turns it off. The safe responses differ by cause. For a large effect root: use `awa run --record` where you only want evidence, or review the configured `[run]` effect roots as a deliberate policy decision. For the input rehash: review what the input scope covers (`awa help ignores`) and narrow it only where it is genuinely wider than the command. Both reviews carry the same warning, and it is the important part. Dropping a root from observation, or excluding a file the command actually reads, is not a speedup — it is a decision to stop noticing that kind of change. The result is not a slower awa or a faster one; it is a hit that replays a result computed from state that has since moved, with nothing on screen to say so. ## A command exited non-zero Route by code: - `2` — usage. Read the message; it names the flag or argument. - `3` — no project here (or an explicit `--config` file that does not exist). Run `awa init`, or point at the project with `--root `. - `4` — a config layer is present but invalid. `awa config validate` names the layer and the key. - `5` — local state needs an action: corruption, or a finding nothing has repaired yet. Go to `awa doctor` and read what it names. - `6` — a required lock was not acquired in time. Another awa process is writing; retry, and if nothing else is running, look for a stale-lock finding in `awa doctor`. `[locks].timeout` sets the wait. - `130` — interrupted before anything authoritative was published. Re-run, but read the message first: it names anything the stopped command left in a path you gave it, and `awa docs export` leaves a directory you have to remove before the retry is allowed. If the command was `awa run`, the code may belong to the wrapped command rather than to awa. Use `--json` and read `data.run.exit_origin`, or look the run up with `awa run log`. Full table: [awa help exit-codes](exit-codes.md). ## The command behaves differently under `awa run` A wrapped command gets a sanitized environment, not yours: the built-in baseline, plus `[run].env_allowlist`, plus `AWA_RUN=1`. If behavior differs from a direct run, a variable the command depends on is almost always the reason. ```text awa config effective # effective_env_allowlist = what the child inherits # injected_env = what awa adds ``` Add the name and rerun: ```toml [run] env_allowlist = ["MY_TOOL_MODE"] ``` Encoding, sorting, or message language is the one case you should not need to fix yourself: the locale variables (`LANG`, `LC_*`, `LANGUAGE`) are inherited and keyed already, exactly as you have them. If a command still reports an ASCII or `C` encoding, check that the locale is actually set in the shell that invoked awa — `awa run` passes what it finds and never invents one. ## Config rejects an env_allowlist name ```text run.env_allowlist[0] "LANG" is already in the built-in baseline; remove it ``` That name is now inherited and keyed for every run, so listing it does nothing. Delete the entry from `awa.toml` or `.awa/config.toml`; nothing else changes. `AWA_RUN` is rejected differently, and permanently: it is awa's own injected marker, not a variable you can redirect or silence. ## Storage looks damaged ```text awa doctor awa doctor --repair awa doctor --repair --strict ``` Diagnose, then repair. `--repair` performs only safe, mechanical, awa-owned fixes and never touches your worktree. `--strict` is not the general escalation for "findings remain". All it changes is how the checks decide: it recomputes content hashes instead of trusting size and modification time, and then repairs what that deeper diagnosis found. So it helps exactly when content may have changed without its metadata changing — after a crash, after copying the project between machines or filesystems, or on a restored backup. It cannot resolve a policy warning or a finding that has no repair, and it is slower, substantially so on a large store. For anything else that survives `--repair`, read the finding: each one states the action it invites, and several are deliberately for you rather than for awa (broad `.awa/` permissions name the `chmod` to run; `.awa/` tracked by git is a commit to undo). See [awa help doctor](doctor.md) for the finding families. Note that `awa doctor` exits 5 while any repairable finding is unrepaired, so a 5 before you have run `--repair` does not by itself mean data is damaged. `awa gc` fails safe in the same situation, and does so wholesale: when corruption or an active or unknown writer lock makes deletion unsafe it reports those candidates as blocked and deletes nothing at all — not even the unblocked candidates. A lock exits 0 (retry later), corruption exits 5. Exit 6 from `gc` means something else entirely: another `gc` held the exclusive collector lease past `[locks].timeout`, so retry rather than reaching for `doctor`. If `gc` reports corruption, run `awa doctor` before anything else. As a last resort, `.awa/` is local evidence, not source: deleting it loses checkpoint and run history — and, because it lives inside `.awa/`, your private `.awa/config.toml` layer. Your worktree, your git history, and a committed `awa.toml` are untouched, and `awa init` starts a fresh store. ## awa cannot find the project `awa` walks up from the current directory looking for a `.awa/` directory. If it reports that this is not an awa project, either you are outside the tree or it was never initialized. Say where it is, or check which config files are in play: ```text awa status --root awa config path ``` ## The evidence looks unavailable rather than wrong For the provider surfaces (`awa state resolve`, `awa state compare`, `awa run show --json`), an unresolvable reference or an unreadable record is a *complete assessment*, not a failure: they exit 0 and name the situation with a closed reason token such as `not-initialized`, `not-found`, `ambiguous-reference`, `metadata-corrupt`, or `permission-denied`. Read the token rather than inferring from the exit code. See [awa help integrations](integrations.md). ## A generator or formatter rewrote files it should not have Put just those paths back from the checkpoint you were working against, previewing first: ```text awa restore -- awa restore --apply -- ``` If the preview reports blocked operations, it names why — `hash-only-content` means the source proved the file's identity but stored no bytes, `blob-missing` means the content was already reclaimed, `policy-incompatible` means the source was observed under a different scan policy so deletions cannot be justified. See [awa help restore](restore.md). ## See also - [awa help doctor](doctor.md) - [awa help gc](gc.md) - [awa help run](run.md) - [awa help status](status.md) - [awa help exit-codes](exit-codes.md) - [awa help json](json.md) - [awa help config](../reference/configuration.md) --- source: https://awarer.one-man-wolf-pack.com/docs/privacy/ --- # awa local evidence and privacy awa keeps durable local evidence under `.awa/` so you can review, replay, and audit work. That evidence is useful, but it means `.awa/` must stay private and untracked. ## What `.awa/` stores - checkpoint manifests and, when `store_file_contents` is on (default), the file contents themselves as content-addressed blobs; - run cache/history: the command line, cwd, exit status, timings, and captured stdout/stderr; - the run key inputs and diagnostics. Three facts combine in a way worth stating explicitly: a checkpoint always covers untracked files, checkpoints store file contents by default, and `.gitignore` is not an input boundary (see [awa help ignores](ignores.md)). So a gitignored, never-committed file — a local `.env`, a key, a seeded fixture database — is inside the scanned scope and its bytes can be stored as a checkpoint blob. Deleting the file from the worktree later does not remove it from an older checkpoint. If that is not what you want for a particular path, exclude it deliberately rather than relying on git having ignored it. ## What it does NOT store - raw environment values. Allowlisted env values are keyed and passed to the child, but the durable record keeps only a redacted identity (presence plus a value fingerprint), never the raw value — so a secret in an allowlisted variable is not written to disk. ## The environment a wrapped command runs with `awa run` does not hand the child your whole environment. It builds one: a built-in baseline, plus whatever `[run].env_allowlist` adds, plus a fixed fact awa injects — and nothing else. Refusing full inheritance is what makes the cache honest. Every value the child can see is in the cache key, so no variable can change a result behind awa's back, and no unrelated secret in your shell reaches a wrapped command. The baseline is what a command needs in order to run, and what decides how it reads and writes text: ```text PATH HOME USER LOGNAME SHELL TMPDIR TEMP TMP execution SystemRoot WINDIR COMSPEC PATHEXT execution (Windows) LANG LANGUAGE LC_ALL LC_COLLATE LC_CTYPE locale LC_MESSAGES LC_MONETARY LC_NUMERIC LC_TIME locale ``` Locale is inherited exactly as you have it. awa passes the state it found — unset stays unset, empty stays empty, a value is passed byte for byte — and never forces UTF-8, never falls back to `C`, and never invents a value you did not set. That matters because locale is not a preference: a reader that decodes UTF-8 under your locale decodes US-ASCII without it. Each locale variable is keyed like any other, so changing one is an honest cache miss rather than a silently different run. Everything else is opt-in, by name, in `[run].env_allowlist`. The shipped default is `["CI", "NODE_ENV"]`; add what your commands actually depend on: ```toml [run] env_allowlist = ["PYTHONPATH", "MY_TOOL_MODE"] ``` Some families are deliberately never in the baseline, because inheriting them by default would be wrong for most projects: ```text tokens, keys, passwords, SSH_AUTH_SOCK, cloud credentials and capabilities LD_PRELOAD, DYLD_*, BASH_ENV, NODE_OPTIONS loads or runs extra code GOFLAGS, CARGO_HOME, JAVA_HOME, PYTHONPATH toolchain settings XDG_CONFIG_HOME, XDG_CACHE_HOME, XDG_DATA_HOME external config and cache roots http_proxy, SSL_CERT_FILE, npm registry vars network trust EDITOR, PAGER, TERM, COLUMNS interactive shaping ``` You can allowlist any of them when a command genuinely needs it — that is a deliberate decision, and `awa doctor` will say so for the names that carry secrets or that can load code. A path-valued setting keeps one limit either way: awa keys the value, not what lives behind it, so the contents of those directories stay outside the evidence boundary and a cache hit does not prove they are unchanged. `PYTHONPATH` is the worked example, and why it is not a default: awa can tell that the path string is the same, never that the importable code behind it still is. ## The `AWA_RUN` marker Every child awa actually executes receives exactly: ```text AWA_RUN=1 ``` It lets a cooperative tool notice it is running under the wrapper — to pick quieter output, say. It is advisory and nothing more. Any process can set it, so it proves nothing: not that awa is present, not that a run record exists, not that anything is supervised. Never treat it as authentication or as permission to skip a check. It is fixed on purpose: no run id, timestamp, or store path travels through the environment. It is reserved, so `env_allowlist` rejects the name, and a cache hit executes no child and injects nothing. Treat captured output as evidence, not as sanitized text: stdout/stderr are stored verbatim, so a command that prints a secret stores that secret. awa does not redact command output (that would hide real compiler/test evidence). If output exceeds the capture limit it is stored truncated and every surface says so ("stored ... is incomplete evidence — N bytes omitted"); a truncated payload is never presented as complete. ## Keep `.awa/` private and untracked - awa creates `.awa/` and everything in it owner-private; do not widen it. - `.awa/.gitignore` keeps the directory out of git; awa restores it on checkpoint and run, and `awa doctor` reports if it is missing or ineffective. awa never edits your repository-root `.gitignore`. - `awa doctor` also flags secret-looking env allowlist names, content storage in a project that appears to hold secrets, overly broad permissions, and nested or ancestor `.awa` markers. Before you copy, snapshot, or share a repository, remember `.awa/` travels with it: ```text awa doctor # check guard, permissions, and root hygiene awa gc # reclaim unreferenced evidence rm -rf .awa # or delete it entirely if you do not want the evidence ``` Deleting the directory also removes the private `.awa/config.toml` layer, which lives inside it; a committed `awa.toml` and `.awaignore` are outside `.awa/` and survive. Note too that `awa gc` is a retention tool, not a sanitizer: it reclaims only what no retained checkpoint or run still references, and by default keeps the latest checkpoint and the configured keep-last window. If the goal is that nothing leaves with the copy, delete the directory or ship a fresh `git clone` rather than a directory copy. ## Restore recovery observations An applied `awa restore` records the worktree state it overwrote — including file content — under `.awa/restores/`, so the restore can be undone. That means it is evidence of the same kind as a checkpoint's blobs: private, owner-only, and never to be committed. It is retained under `[gc].keep_restores_for` (default `14d`), so ordinary `awa gc` reclaims it in time; `awa gc --older-than` reclaims it sooner. See [awa help restore](restore.md). ## See also - [awa help doctor](doctor.md) - [awa help run](run.md) - [awa help inspect](inspect.md) - [awa help ignores](ignores.md) - [awa help gc](gc.md) --- source: https://awarer.one-man-wolf-pack.com/docs/integrations/ --- # awa as a provider for other local tools Another local tool (an editor, a script, a review assistant) can use awa as an optional, read-only provider of worktree state and run evidence. Integrate only through the versioned subprocess contract below — never by reading `.awa/` directly. ## Subprocess-only, read-only - Run the awa binary and parse its `--json` output. Do not decode `.awa/checkpoints`, `.awa/runs`, manifests, indexes, or pointers; that layout is private and changes between releases without notice. - The provider surfaces are read-only. They never mutate state, create pins or leases, or edit another tool's files. ## State identity — `awa state` (provider_contract: `awa-state/v1`) ```text awa state resolve --json # a full immutable state identity, # or a stable reason it is unavailable awa state compare .. --json # equal / different (with counts) / # incomparable / unavailable ``` Refs: `now`, `latest`, ``, `run::before`, `run::after` (see [awa help refs](refs.md)). An expected "unavailable" is a successful assessment (exit 0), not an error to scrape from stderr. ## Run evidence — `awa run show` (provider_contract: `awa-evidence/v1`) ```text awa run show --json # one run as reference-quality metadata: # command, cwd, exit, duration, reuse, # mutation, before/after state identities, # and output byte/hash/truncation facts ``` `states.before` and `states.after` are complete `awa-state/v1` assessments, identical to `awa state resolve run::before|after`. Default JSON is metadata only: it includes captured stdout/stderr lines only through a bounded `--tail`/`--grep` sample (`--stdout`/`--stderr` merely pick which stream that sample covers and need a filter; a raw `--stdout`/`--stderr` dump is a non-JSON surface). A metadata view never claims payload bytes are intact: inspectability reports presence, and integrity stays "unverified" until an explicit `--tail`/`--grep` read opens and hash-verifies that stream, which reports it "verified" (an unselected stream stays "unverified"). ## Provider versioning Provider versions are independent. `awa-state/v1` versions state identity; the enclosing `awa-evidence/v1` versions run-evidence composition. Additive detail may appear; a changed identity field, outcome/reason spelling, or equality meaning is a version bump. The private `.awa/` storage format is separate from both and may change freely before release. ## Availability and GC Provider references are local evidence, not durable task records. Ordinary `awa gc` may remove a referenced checkpoint or run; a later resolve then returns unavailable with a stable reason, without rewriting the reference or calling a deleted record corrupt. Absence may weaken evidence but never blocks Git or manual review. awa adds no cross-tool pins, leases, callbacks, or retention. ## Privacy `.awa/` holds real evidence (see [awa help privacy](privacy.md)). Keep it private and untracked; captured output is stored verbatim, so treat it as evidence, not sanitized text. ## Excluding another tool's local state A tool that writes high-churn private state beside `.awa/` — for example `.rezonator/ledger.sqlite` — is project configuration, not universal awa knowledge. It is not a built-in exclude. Exclude it explicitly so its writes do not move checkpoint/current-state identity or invalidate unrelated cached checks: ```text echo '.rezonator/' >> .awaignore # or shared awa.toml scope.extra_excludes ``` After that, a write confined to `.rezonator/` leaves awa state equal, while a real source edit still moves it and invalidates the relevant checks. ## Commands that read excluded state If a command's behavior depends on an excluded directory, awa cannot soundly serve it from reusable cache mode — its inputs are no longer fully keyed. Run such a command directly, or under `awa run --record` when supervised history is useful; never weaken the cache key to make it "hit". awa never edits your `.awaignore`, `awa.toml`, `.gitignore`, or another tool's files. ## See also - [awa help refs](refs.md) - [awa help record](record.md) - [awa help json](json.md) - [awa help privacy](privacy.md) - [awa help gc](gc.md) --- source: https://awarer.one-man-wolf-pack.com/docs/platform/ --- # awa platform and filesystem support awa is a local, single-user tool. Its correctness assumptions are those of a local filesystem; behavior elsewhere is best-effort unless stated otherwise. ## Platforms A release publishes six targets, and they do not all carry the same evidence. The distinction is deliberate: "we build it" and "we run it" are different claims, and the two do not line up the way the target list suggests. ```text linux/amd64 Linux — the CI runtime platform: the whole test suite and race detector on every change, plus the stress suite on each push to the default branch darwin/arm64 macOS — the development platform, exercised interactively every day, but not covered by CI windows/amd64 Windows — compile-only, plus a narrow CI runtime suite for the filesystem primitives, the worktree mutation restore writes through (including symbolic links, which that lane requires rather than skips), and the documentation export, where its semantics differ enough to decide correctness freebsd/amd64 FreeBSD — compile-only, plus a focused CI runtime suite in a FreeBSD 15.1 (x86_64) virtual machine on each push to the default branch, covering the filesystem primitives, the private local state and stores built on them, the collector lock, the scanner, the worktree mutation restore writes through (symbolic links required, not skipped), doctor, and the documentation export; that run must be green before the release is authorized darwin/amd64 compile-only linux/arm64 compile-only ``` Compile-only means the binary is built for that platform in CI but is not exercised at runtime there, so its behavior is best-effort. Treat a failure on any published target as a bug worth reporting, not as an unsupported configuration. The two macOS archives require macOS 13 Ventura or later: Go 1.27 builds them, and that is the oldest macOS its runtime supports. The Homebrew formula is a source build compiled by Homebrew's own Go dependency, so it follows the macOS versions Homebrew supports rather than a version this project pins. Windows and FreeBSD both carry a focused runtime suite, but they do not carry the same local-filesystem guarantees. FreeBSD runs the same native implementations as Linux and macOS: descriptor-relative no-follow operations, so an operation reaches its target through the directory it opened and a path swapped underneath it cannot redirect the write; a kernel `flock` for the collector lock, so a crashed holder releases it without anything to detect or steal; and complete change-time, device, inode, and link-count fields in a scan signature. Windows exposes none of those, and its lane proves the weaker behavior it actually runs — the final path component is checked before the open rather than as part of it, an already-open directory is re-resolved by name, the exclusive lock is a best-effort file-content protocol, and those four stat fields are recorded as unavailable rather than guessed. Two consequences worth naming, because the ordering above is not the intuitive one: macOS is the most-used platform but the least automatically verified, and Linux is the most verified even though it is not the one this project is developed on. ## Filesystem assumptions - awa relies on local-filesystem semantics: flock advisory locks, atomic rename and hard-link publication, and owner-private permissions. - Network filesystems (NFS, SMB) are best-effort. Their locking and atomic-rename guarantees can differ, so concurrent use across hosts is not supported. ## Paths, case, and links - paths in manifests and JSON are stored relative to the project root with `/` separators, on every platform. - case is preserved exactly in manifests and JSON. Manifests assume a case-sensitive filesystem; on a case-insensitive one, two paths that differ only by case map to a single file — awa does not detect that, so treat case-insensitive filesystems as best-effort. - symlinks and hardlinks follow the scanner/checkpoint policy: symlinks are not followed by default (see `follow_symlinks` / `symlink_max_depth`), and a hardlink is treated as a regular file for content identity. - `.awa/` is assumed to be local, private state on the same filesystem as the project. ## Environment names and locale across platforms - environment variable names are case-sensitive on Unix and case-insensitive on Windows. `[run].env_allowlist` therefore rejects names that differ only by case on every platform, so one committed `awa.toml` behaves the same everywhere. - the POSIX locale variables (`LANG`, `LC_*`, `LANGUAGE`) are in the built-in baseline on every platform, including Windows, because being in the baseline means "inherit whatever the parent has". A Windows process usually has none of them, so nothing is passed and each is keyed as unset; a Windows process that does define one — under a POSIX-flavored shell or a cross-platform toolchain — has it passed through unchanged. awa never invents a POSIX locale value on a platform that does not use one. ## See also - [awa help install](install.md) - [awa help privacy](privacy.md) - [awa help doctor](doctor.md) - [awa help troubleshooting](troubleshooting.md) --- source: https://awarer.one-man-wolf-pack.com/docs/json/ --- # JSON output, exit origin, and script rules `--json` turns a command's human report into a stable machine document. Use it for anything automated: the human text is allowed to change wording, the JSON shape is not. ## The envelope Every JSON payload is wrapped the same way: ```text { "schema_version": 1, "command": "", "data": { ... } } ``` `` is the command that produced it (`status`, `changes`, `run.show`, ...). The envelope's `schema_version` versions the envelope itself. Provider contracts carried inside `data` — `awa-state/v1` for resolved state, `awa-evidence/v1` for run evidence — are versioned independently and appear as their own `provider_contract` fields. Payload goes to stdout. Diagnostics, notes, hints, and errors go to stderr, so a script can capture stdout alone and get only the document. ## Which commands accept --json Global options are honored per command, not universally: a command that does not act on `--json` rejects it as a usage error rather than accepting and ignoring it. The exhaustive list is in [global options](../reference/global-options.md) and the per-command pages under [commands](../commands/index.md). One case worth stating: `awa docs export` has no `--json`. The export writes its own machine contract, `manifest.json`, into the output directory. ## Rules for scripts Four rules make the difference between a robust consumer and one that occasionally believes a truncated document: 1. **Parse stdout only after the process exits.** Streamed payloads are written as they are produced. 2. **A non-zero exit does not mean the document is invalid.** For `awa run` the exit code is usually the wrapped command's own; the envelope is still one complete document. 3. **Treat a `partial output:` line on stderr as fatal for the document.** It means the report failed part-way through. 4. **Never salvage a partial document.** Discard stdout and re-run; do not reconstruct the missing tail or parse the fragment that arrived. Streaming surfaces such as `awa changes --json` and `awa diff --json` emit their entries incrementally, so a mid-stream failure leaves the document deliberately unterminated — it cannot parse as complete, which is the intended signal, paired with the `partial output:` diagnostic and a non-zero exit. ## Exit origin `awa run` returns the wrapped command's own exit code, and that code can overlap awa's own codes in the range 1–6. `$?` alone therefore cannot tell you who failed. The run envelope answers it explicitly: `data.run.exit_origin` is `child`, alongside `data.run.exit_code` and `data.run.signal`. An awa-origin failure — invalid configuration, a corrupt store, a lock timeout — is reported through the error path with an awa exit code and never as a run envelope, so the presence of the envelope is itself part of the classification. See [awa help exit-codes](exit-codes.md). ## Human output modes are not JSON modes `--stat`, `--name-only`, `--oneline`, and `--time` shape human output. Combining any of them with `--json` is a usage error (exit 2) rather than a silent no-op, because the JSON already carries the underlying facts. Timestamps in JSON are always UTC RFC3339 regardless of the configured display mode. ## Bounded and degraded results are labelled A payload never quietly shrinks. Where a list is capped, the document carries a completeness fact next to it — `complete`, `shown`, `limit`, and a `reason` — for example `candidates_bounded` on `awa gc --json`, while the summary still reports full totals. Similar fields elsewhere state whether a set of paths is complete, truncated, or unavailable. Degraded evidence is reported as a complete assessment rather than as an error: `awa state resolve`, `awa state compare`, and `awa run show --json` exit 0 and name the situation with a closed reason token (for example `not-initialized`, `not-found`, `ambiguous-reference`, `permission-denied`). A degradation is always named that way rather than left for you to infer from what is missing. Optional keys, on the other hand, are omitted when they have no value: a checkpoint with no message carries no `message` key, a run with capture disabled carries no `outputs` block, and a binary with no VCS stamping carries no `revision`. Read anything a document is not obliged to carry with a present-or-default access rather than a direct index. What is stable is the envelope plus the keys a document always carries — `awa run ls --json` always has its `diagnostics.performance` array, empty when nothing crossed the latency threshold, so machine-readable latency facts never live only on stderr. ## See also - [awa help exit-codes](exit-codes.md) - [awa help status](status.md) - [awa help run](run.md) - [awa help inspect](inspect.md) - [awa help integrations](integrations.md) --- source: https://awarer.one-man-wolf-pack.com/docs/exit-codes/ --- # awa exit codes awa returns stable process exit codes so scripts and agents can branch on them: ```text 0 success 1 generic error, or differences found / validation failed 2 usage error (unknown command, unknown flag, bad flag value) 3 a requested thing does not exist: the project root, a config file, or something the invocation named — an unmatched id prefix, an out-of-range @-N, an unknown run or restore id, or an observation awa does not have 4 configuration present but invalid 5 awa's local state needs an action (corruption, or an unrepaired finding) 6 a required lock could not be acquired in time 130 interrupted (Ctrl+C / SIGINT) before authoritative state was published ``` The awa-owned range is 0-6, plus 130 for interruption; every code is produced by a real command path. ## What to do about each ```text 1 read the message: a comparison found differences, or something failed 2 fix the invocation; the message names the flag or argument 3 read the message: it names what was not found. For a project, run 'awa init' or point at it with --root ; for something the invocation named, check it exists — 'awa log -n 5' for checkpoints, 'awa run ls' for runs 4 run 'awa config validate' — it names the layer and the key 5 run 'awa doctor', then 'awa doctor --repair'; read the findings before assuming damage 6 another awa process holds the lock: retry, check [locks].timeout, or look for a stale-lock finding in 'awa doctor' 130 nothing authoritative was published; re-run — but read the message first, it names anything the stopped command left behind ``` Longer decision paths for each of these live in [awa help troubleshooting](troubleshooting.md). Note that a diagnostic command's exit status is its verdict, not an awa failure, and two commands read the table more precisely than the one-line meanings above: - `awa doctor` exits 5 for unrepaired errors **and** for unrepaired repairable findings, so a 5 can mean "there is a safe mechanical fix waiting" rather than damaged data. `awa run explain` is the opposite case: it executes nothing, so it never reports a cache verdict as a non-zero code — a non-zero exit from it is always awa refusing to answer (no project, invalid config, bad invocation), never "this would miss". - Code 6 is for a command that could not do its job without the lock. `awa gc` answers two different lock questions. A writer's lock suppresses its whole destructive pass — nothing is deleted, the obstruction is reported as a blocked candidate, and it exits 0 as a normal "try again later". A second gc competing for the exclusive collector lease is the ordinary case instead: it waits out `[locks].timeout` and exits 6. So neither "gc met a busy lock" nor "gc exited 0" implies anything was reclaimed. ## Interruption Ctrl+C cancels the in-flight operation through one root context: the worktree scan, git subprocesses, GC sweep, streamed JSON, and any `awa run` child all stop. No reusable cache hit, checkpoint, cache pointer, or GC deletion is published from incomplete work. Non-`awa run` commands exit 130; `awa run` instead passes through its killed child's signal-derived code (e.g. 137) and records the interrupted run only as a non-reusable post-scan-failed history entry that can never replay. Nothing awa owns needs cleaning up afterwards. What a command wrote into paths YOU named is a separate question, and re-running answers it for all but one of them: an interrupted `awa restore` leaves the worktree part-way and re-plans from what is there now. `awa docs export` is the exception, because its rule is that the destination must not exist: interrupted after it created that directory, it leaves it, names it, and tells you to remove it — the directory holds no `manifest.json`, so it is not a valid export, and the next run refuses the path rather than resuming into it. ## Wrapped children `awa run` is special: when the wrapped command actually executes, or a cache hit is replayed, awa returns the wrapped command's own exit code rather than an awa code. A failure to write awa's own output is still reported as an awa error. Because a wrapped child may exit with a code that overlaps awa's 1-6 range, `$?` alone cannot distinguish an awa-origin failure from a child result. What settles it under `--json` is the *presence of the run envelope*: an awa-origin failure is reported on the error path with an awa code and never as a run envelope, so a document with `data.run.exit_origin` (always `"child"`) is by construction a child result. Without `--json`, `awa run log` identifies the execution. ## See also - [awa help run](run.md) - [awa help json](json.md) - [awa help troubleshooting](troubleshooting.md) - [exit-code reference](../reference/exit-codes.md) --- source: https://awarer.one-man-wolf-pack.com/docs/commands/ --- # awa command reference Every command of the installed version. Each page owns the exhaustive syntax for its command; the workflow guidance lives in the operational topics. ## Commands - [`awa init`](init.md) — create a new .awa project in the current directory - [`awa status`](status.md) — show project status (default command) - [`awa checkpoint`](checkpoint.md) — record a checkpoint of the worktree - [`awa log`](log.md) — list recorded checkpoints - [`awa changes`](changes.md) — summarize changes between two states - [`awa diff`](diff.md) — show a diff between two states - [`awa restore`](restore.md) — restore selected paths from an immutable state - [`awa run`](run.md) — run a command with caching and supervised history - [`awa gc`](gc.md) — garbage-collect unreferenced state - [`awa doctor`](doctor.md) — diagnose project and store health - [`awa config`](config.md) — inspect or edit configuration - [`awa state`](state.md) — resolve and compare state for the external provider - [`awa docs`](docs.md) — export the documentation of the installed version - [`awa help`](help.md) — show operational help for a topic - [`awa version`](version.md) — print version and build information ## See also - [global options](../reference/global-options.md) - [exit codes](../reference/exit-codes.md) --- source: https://awarer.one-man-wolf-pack.com/docs/command-init/ --- # awa init create a new .awa project in the current directory. ```text awa init [--profile ] [--root ] ``` ## Tokens after `--` A token after `--` is a usage error: this command takes no operands. ## Global options - `--root ` — project root override - `--json` — emit schema-versioned JSON Supports `--json` (schema-versioned output). ## Flags - `--profile ` — starter profile: default|strict (default: `default`) ## Workflow See [awa help quickstart](../topics/quickstart.md). --- source: https://awarer.one-man-wolf-pack.com/docs/command-status/ --- # awa status show project status (default command). ```text awa status ``` ## Tokens after `--` A token after `--` is a usage error: this command takes no operands. ## Global options - `--root ` — project root override - `--json` — emit schema-versioned JSON Supports `--json` (schema-versioned output). ## Workflow See [awa help status](../topics/status.md). --- source: https://awarer.one-man-wolf-pack.com/docs/command-checkpoint/ --- # awa checkpoint record a checkpoint of the worktree. ```text awa checkpoint [-m ] ``` ## Tokens after `--` A token after `--` is a usage error: this command takes no operands. ## Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON - `--trust-mode ` / `--strict` — cache trust level (normal|strict|fast) Supports `--json` (schema-versioned output). ## Flags - `-m, --message ` — checkpoint message ## Workflow See [awa help checkpoints](../topics/checkpoints.md). --- source: https://awarer.one-man-wolf-pack.com/docs/command-log/ --- # awa log list recorded checkpoints. ```text awa log [-n ] [--all] [--oneline] [--time ] ``` ## Tokens after `--` A token after `--` is a usage error: this command takes no operands. ## Global options - `--root ` — project root override - `--json` — emit schema-versioned JSON Supports `--json` (schema-versioned output). ## Flags - `-n, --limit ` — show at most \ entries - `-1` — shorthand for --limit 1 - `--all` — include the run timeline, not just checkpoints - `--oneline` — compact one-line-per-entry output (human only) - `--time ` — time display: relative|utc|local (human only) (default: `[ui].time`) ## Workflow See [awa help checkpoints](../topics/checkpoints.md). --- source: https://awarer.one-man-wolf-pack.com/docs/command-changes/ --- # awa changes summarize changes between two states. ```text awa changes [range] [-- path...] [--stat|--name-only] [--no-renames] ``` ## Tokens after `--` Tokens after `--` are path filters. They are resolved relative to your current directory and normalized to the project root, and they narrow the output only — they never create a partial state. ## Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON - `--trust-mode ` / `--strict` — cache trust level (normal|strict|fast) Supports `--json` (schema-versioned output). ## Flags - `--stat` — one-line change-count summary (human only) - `--name-only` — print only changed paths (human only) - `--no-renames` — disable rename detection ## Workflow See [awa help diff](../topics/diff.md). --- source: https://awarer.one-man-wolf-pack.com/docs/command-diff/ --- # awa diff show a diff between two states. ```text awa diff [range] [-- path...] [--context ] [--stat] [--no-renames] ``` ## Tokens after `--` Tokens after `--` are path filters. They are resolved relative to your current directory and normalized to the project root, and they narrow the output only — they never create a partial state. ## Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON - `--trust-mode ` / `--strict` — cache trust level (normal|strict|fast) Supports `--json` (schema-versioned output). ## Flags - `--context ` — lines of context around each change (default: `[checkpoint].diff_context`) - `--stat` — one-line change-count summary (human only) - `--no-renames` — disable rename detection - `--algorithm ` — select the diff engine (histogram|myers) (default: `[diff].algorithm`) ## Workflow See [awa help diff](../topics/diff.md). --- source: https://awarer.one-man-wolf-pack.com/docs/command-restore/ --- # awa restore restore selected paths from an immutable state. ```text awa restore -- awa restore [--dry-run|--apply] -- awa restore [--dry-run|--apply] --all ``` ## Tokens after `--` Tokens after `--` are path filters. They are resolved relative to your current directory and normalized to the project root, and they narrow the output only — they never create a partial state. ## Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON - `--trust-mode ` / `--strict` — cache trust level (normal|strict|fast) Supports `--json` (schema-versioned output). ## Flags - `--apply` — perform the restore (the only mutating mode) - `--dry-run` — preview explicitly; identical to the default - `--all` — select all proven restorable scope instead of paths ## Workflow See [awa help restore](../topics/restore.md). --- source: https://awarer.one-man-wolf-pack.com/docs/command-run/ --- # awa run run a command with caching and supervised history. ```text awa run [run flags] -- [args...] awa run [flags] (ls, log, show, rm, explain) ``` ## Tokens after `--` Tokens after `--` are the wrapped command and its arguments; awa passes them through unchanged. ## Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON - `--trust-mode ` / `--strict` — cache trust level (normal|strict|fast) Supports `--json` (schema-versioned output). ## Flags - `--display ` — terminal display: full|summary|tail:\|none (default: `full`) - `--record` — execute and record evidence, never a reusable hit - `--refresh` — ignore any cache hit and write a fresh entry - `--no-cache` — do not read or write the cache - `--no-cache-failures` — do not cache a failing command - `--scope ` — replace the run input scope - `--include ` — add an input path to the scope - `--exclude ` — remove an input path from the scope - `--cwd ` — run the command in this directory (inside the root) - `--allow-skipped-inputs` — allow a cache hit when some inputs were skipped - `--allow-tty` — attach the terminal to the child; forces non-cacheable ## Exit status exit code: awa run returns the wrapped command's own exit code after a hit or a miss. Because that can overlap awa's 1-6 codes, use --json (run.exit_origin) or the run log to tell an awa-origin failure from a child result. ## Subcommands ### awa run ls list reusable runs for the current state. ```text awa run ls [--all] [--near] [-n ] [--command ] [--time ] ``` #### Tokens after `--` A token after `--` is a usage error: this command takes no operands. #### Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON - `--trust-mode ` / `--strict` — cache trust level (normal|strict|fast) Supports `--json` (schema-versioned output). #### Flags - `--all` — also list non-reusable runs, each with a reason - `--near` — add the nearest near-miss section - `-n, --limit ` — show at most \ entries - `--command ` — filter to runs whose command contains \ - `--time ` — time display: relative|utc|local (human only) (default: `[ui].time`) #### Workflow See [awa help run](../topics/run.md). ### awa run log list recorded runs, newest first. ```text awa run log [-n ] [--command ] [--time ] ``` #### Tokens after `--` A token after `--` is a usage error: this command takes no operands. #### Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON Supports `--json` (schema-versioned output). #### Flags - `-n, --limit ` — show at most \ entries - `--command ` — filter to runs whose command contains \ - `--time ` — time display: relative|utc|local (human only) (default: `[ui].time`) #### Workflow See [awa help inspect](../topics/inspect.md). ### awa run show show one run's metadata and stored output. ```text awa run show |--last [--meta|--stdout|--stderr] [--tail ] [--grep ] ``` #### Tokens after `--` A token after `--` is a usage error: this command takes no operands. #### Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON Supports `--json` (schema-versioned output). #### Flags - `--last` — select the most recent readable run - `--meta` — metadata only (no output) - `--stdout` — write the stored stdout stream - `--stderr` — write the stored stderr stream - `--tail ` — only the last \ lines of the selected output - `--grep ` — only output lines matching \ - `--time ` — time display: relative|utc|local (human only; [ui].time is not read here) (default: `relative`) #### Workflow See [awa help inspect](../topics/inspect.md). ### awa run rm delete stored runs by id or filter. ```text awa run rm ... | (--command | --older-than ) [--dry-run] ``` #### Tokens after `--` A token after `--` is a usage error: this command takes no operands. #### Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON Supports `--json` (schema-versioned output). #### Flags - `--command ` — delete runs whose command contains \ - `--older-than ` — delete runs older than \ (e.g. 720h) - `--dry-run` — report what would be removed without deleting #### Workflow See [awa help inspect](../topics/inspect.md). ### awa run explain explain how the run cache would behave. ```text awa run explain -- [args...] awa run explain --last awa run explain --from-run --to-now ``` #### Tokens after `--` Tokens after `--` are the wrapped command and its arguments; awa passes them through unchanged. #### Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON - `--trust-mode ` / `--strict` — cache trust level (normal|strict|fast) Supports `--json` (schema-versioned output). #### Flags - `--last` — explain the most recent recorded run - `--from-run ` — explain a stored run's inputs against now (needs --to-now) - `--to-now` — compare the selected run's inputs to the current state - `--scope ` — replace the run input scope (command mode) - `--include ` — add an input path to the scope (command mode) - `--exclude ` — remove an input path from the scope (command mode) - `--cwd ` — resolve the key as if run in this directory (command mode) - `--refresh` — model run's --refresh policy (command mode) - `--no-cache` — model run's --no-cache policy (command mode) - `--no-cache-failures` — model run's --no-cache-failures policy (command mode) - `--allow-skipped-inputs` — model run's --allow-skipped-inputs policy (command mode) - `--allow-tty` — model run's --allow-tty stdin (command mode) #### Workflow See [awa help run](../topics/run.md). ## Workflow See [awa help run](../topics/run.md). --- source: https://awarer.one-man-wolf-pack.com/docs/command-gc/ --- # awa gc garbage-collect unreferenced state. ```text awa gc [--dry-run] [--committed] [--keep-last ] [--older-than ] awa gc [--runs-only|--checkpoints-only|--blobs-only] ``` ## Tokens after `--` A token after `--` is a usage error: this command takes no operands. ## Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON Supports `--json` (schema-versioned output). ## Flags - `--dry-run` — show the plan without deleting anything - `--committed` — also reclaim state made redundant by git commits - `--keep-last ` — retain the most recent \ checkpoints (default: `policy default`) - `--older-than ` — only reclaim entries older than \ (e.g. 720h) - `--runs-only` — restrict collection to the run cache - `--checkpoints-only` — restrict collection to checkpoints - `--blobs-only` — restrict collection to the blob store ## Workflow See [awa help gc](../topics/gc.md). --- source: https://awarer.one-man-wolf-pack.com/docs/command-doctor/ --- # awa doctor diagnose project and store health. ```text awa doctor [--repair] [--strict] ``` ## Tokens after `--` A token after `--` is a usage error: this command takes no operands. ## Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON - `--trust-mode ` / `--strict` — cache trust level (normal|strict|fast) Supports `--json` (schema-versioned output). ## Flags - `--repair` — restore safe awa-owned state where possible ## Exit status exit code: the diagnosis, not an awa failure. Healthy or warnings-only exits 0; unrepaired errors or unrepaired repairable findings exit 5. ## Workflow See [awa help doctor](../topics/doctor.md). --- source: https://awarer.one-man-wolf-pack.com/docs/command-config/ --- # awa config inspect or edit configuration. ```text awa config ``` ## Tokens after `--` A token after `--` is a usage error: this command takes no operands. ## Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON - `--trust-mode ` / `--strict` — cache trust level (normal|strict|fast) Supports `--json` (schema-versioned output). ## Subcommands ### awa config path show the shared and local config paths and which exist. ```text awa config path ``` #### Tokens after `--` A token after `--` is a usage error: this command takes no operands. #### Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON Supports `--json` (schema-versioned output). ### awa config show print a layer's raw contents (config show [shared|local]). ```text awa config show [shared|local] ``` #### Tokens after `--` A token after `--` is a usage error: this command takes no operands. #### Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON Supports `--json` (schema-versioned output). #### Workflow See [awa help config](../reference/configuration.md). ### awa config effective print the composed config plus each value's origin layer. ```text awa config effective ``` #### Tokens after `--` A token after `--` is a usage error: this command takes no operands. #### Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON - `--trust-mode ` / `--strict` — cache trust level (normal|strict|fast) Supports `--json` (schema-versioned output). ### awa config validate check that every active config layer is valid. ```text awa config validate ``` #### Tokens after `--` A token after `--` is a usage error: this command takes no operands. #### Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON Supports `--json` (schema-versioned output). ### awa config template print an annotated config template to stdout. ```text awa config template ``` #### Tokens after `--` A token after `--` is a usage error: this command takes no operands. #### Global options Accepts no global options other than `-h` / `--help`. ### awa config init write a shared awa.toml or local .awa/config.toml scaffold. ```text awa config init (--shared | --local) [--force] ``` #### Tokens after `--` A token after `--` is a usage error: this command takes no operands. #### Global options - `--root ` — project root override - `--json` — emit schema-versioned JSON Supports `--json` (schema-versioned output). #### Flags - `--shared` — write the shared, committable awa.toml - `--local` — write the private, untracked .awa/config.toml - `--force` — overwrite an existing config file #### Workflow See [awa help config](../reference/configuration.md). ## Workflow See [awa help config](../reference/configuration.md). --- source: https://awarer.one-man-wolf-pack.com/docs/command-state/ --- # awa state resolve and compare state for the external provider. ```text awa state ``` ## Tokens after `--` A token after `--` is a usage error: this command takes no operands. ## Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON - `--trust-mode ` / `--strict` — cache trust level (normal|strict|fast) Supports `--json` (schema-versioned output). ## Subcommands ### awa state resolve resolve a state reference to a full immutable identity. ```text awa state resolve [--json] ``` #### Tokens after `--` A token after `--` is a usage error: this command takes no operands. #### Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON - `--trust-mode ` / `--strict` — cache trust level (normal|strict|fast) Supports `--json` (schema-versioned output). ### awa state compare compare two states for freshness (summary-only). ```text awa state compare .. [--json] ``` #### Tokens after `--` A token after `--` is a usage error: this command takes no operands. #### Global options - `--root ` — project root override - `--config ` — config file override - `--json` — emit schema-versioned JSON - `--trust-mode ` / `--strict` — cache trust level (normal|strict|fast) Supports `--json` (schema-versioned output). ## Workflow See [awa help integrations](../topics/integrations.md). --- source: https://awarer.one-man-wolf-pack.com/docs/command-docs/ --- # awa docs export the documentation of the installed version. ```text awa docs ``` ## Tokens after `--` A token after `--` is a usage error: this command takes no operands. ## Global options Accepts no global options other than `-h` / `--help`. ## Subcommands ### awa docs export write the complete documentation bundle to a directory. ```text awa docs export --output ``` #### Tokens after `--` A token after `--` is a usage error: this command takes no operands. #### Global options Accepts no global options other than `-h` / `--help`. #### Flags - `--output ` — destination directory to create; it must not exist yet, and its parent must exist --- source: https://awarer.one-man-wolf-pack.com/docs/command-help/ --- # awa help show operational help for a topic. ```text awa help [topic] ``` ## Tokens after `--` A token after `--` is a usage error: this command takes no operands. ## Global options Accepts no global options other than `-h` / `--help`. --- source: https://awarer.one-man-wolf-pack.com/docs/command-version/ --- # awa version print version and build information. ```text awa version [--json] ``` ## Tokens after `--` A token after `--` is a usage error: this command takes no operands. ## Global options - `--json` — emit schema-versioned JSON Supports `--json` (schema-versioned output). ## Workflow See [awa help install](../topics/install.md). --- source: https://awarer.one-man-wolf-pack.com/docs/global-options/ --- # awa global options Global options may appear anywhere on the command line. A command accepts only the options listed on its own page; passing an unaccepted global is a usage error rather than a silently ignored flag. ## Options - `--root ` — project root override - Accepted by: `init`, `status`, `checkpoint`, `log`, `changes`, `diff`, `restore`, `run`, `gc`, `doctor`, `config`, `state`. - `--config ` — config file override - Accepted by: `checkpoint`, `changes`, `diff`, `restore`, `run`, `gc`, `doctor`, `config`, `state`. - `--json` — emit schema-versioned JSON - Accepted by: `init`, `status`, `checkpoint`, `log`, `changes`, `diff`, `restore`, `run`, `gc`, `doctor`, `config`, `state`, `version`. - `--trust-mode ` / `--strict` — cache trust level (normal|strict|fast) - Accepted by: `checkpoint`, `changes`, `diff`, `restore`, `run`, `doctor`, `config`, `state`. - `-h` / `--help` — show help - Handled by the parser for every command. ## See also - [command reference](../commands/index.md) - [exit codes](exit-codes.md) --- source: https://awarer.one-man-wolf-pack.com/docs/exit-code-reference/ --- # awa exit codes The exact process-exit contract. Each code has a stable number and a stable machine name; the meanings and the diagnosis guidance live in the operational topic linked below. ## awa-owned exit statuses - `0` — `success` - `1` — `generic-error` - `2` — `usage-error` - `3` — `not-found` - `4` — `config-error` - `5` — `state-action-required` - `6` — `lock-timeout` - `130` — `interrupted` ## Wrapped child exits `awa run` returns the wrapped command's own exit code rather than an awa code. A child's code can overlap awa's own range, so the exit status alone does not identify the origin. The run envelope disambiguates it in `data.run.exit_origin`. - Interruption of a normal command: `130`. - Interruption of a wrapped child: child signal-derived (e.g. 137 for SIGKILL). ## See also - [awa help exit-codes](../topics/exit-codes.md) - [global options](global-options.md)