@journeykit/canon 0.37.0 → 0.39.0

package/dist/skills/SKILL.src.md

@@ -160,7 +160,21 @@ an object-store tier, in which case `evidence add`, `review scenario`, `review c
 `canon artifacts verify` (`--full` re-hashes every blob) ask the store and
 refuse, never pass, when it cannot be reached. Moving an existing store with
 `canon artifacts move --tier <tier>` is the repo owner's decision, not a step
-of the loop.
+of the loop. So is `canon artifacts prune`, which deletes the blobs no record
+binds any more (the store only grows: a report written anew on every run adds a
+blob per run). A blob stays while the latest evidence or a current review binds
+it (what the gate and `artifacts verify` read), while a record not promoted yet
+binds it, and, with `--keep-days N`, while any evidence or review of the last
+`N` days binds it; the bare run previews the blobs it deletes and why the rest
+stay, and `--commit --plan-digest` deletes. A deleted local blob stays in git
+history (shrinking that history is the repo owner's call, not the command's); a
+deleted object of an object-store tier is gone for good. The preview and the
+commit also cover the stale temp files a killed blob write leaves in
+`.canon/artifacts/sha256` (`.tmp-<sha256>-<pid>-<nanos>`, a regular file
+modified over five minutes ago): the plan lists them in `data.staleTemps`, and
+`artifacts verify` only counts them (it deletes nothing and its exit does not
+change). A temp file is no finished blob, so deleting it changes no record; one
+that git already tracks must be taken out of the commit.
 
 ### Search and trace
 
@@ -215,8 +229,11 @@ A role is guidance, not enforcement: `--role` on `evidence add` and
   your complete command set, every option of every leaf included. Run `canon schema <command> --json` only for a
   command it does not list, or after a `USAGE` refusal (read `error.field`
   and `error.expected` first). `canon schema --json` is the tree of every group and command
-  with its `effect` and `x-canon.roles` (`--as <role>` lists one role's, and `x-canon.as` names it);
-  its `options` define once the options that two or more commands share (`--repo`, `--as`, `--actor`, …)
+  with its `effect` and `x-canon.roles` (`--as <role>` lists one role's, and `x-canon.as` names it).
+  `x-canon.roles` is the string `all` for a command all four roles use, else an array of
+  role names (empty: only a human runs it), so read it as `roles == "all"` or a name in the array;
+  the root's `x-canon.rolesForm` says so once. The tree's
+  `options` define once the options that two or more commands share (`--repo`, `--as`, `--actor`, …)
   and a command names them. `canon schema <group> --json` lists a group's
   commands; `canon schema <command> --json` is the call surface of one command and nothing
   else: `options` (each name of a tree option, or an object with `valueType`, a typed
@@ -316,9 +333,9 @@ leaves below take one object only.
 
 ### Preview, then `--commit`
 
-The five commands that delete or rewrite existing data (`canon purge`,
+The six commands that delete or rewrite existing data (`canon purge`,
 `canon tier age`, `canon ledger compact`, `canon artifacts move`,
-`canon migrate`) act in two steps. The bare run previews: it writes nothing,
+`canon artifacts prune`, `canon migrate`) act in two steps. The bare run previews: it writes nothing,
 exits 0 and prints the effects and a `planDigest`. Read the effects, then act
 with `--commit --plan-digest <planDigest>`. It refuses (`PLAN_STALE`) when
 the plan differs from the one you previewed, so run the preview again. Appends
@@ -327,7 +344,7 @@ preview helps elsewhere (`init`, `skills install`, `export`, `inventory sync`,
 `subject adopt`, …) `--dry-run` validates fully and writes nothing.
 
 ```bash
-canon purge --kind session --before 2026-01-01
+canon purge --kind run --before 2026-01-01
 ```
 
 ## Upgrading a repo from 0.27
@@ -353,15 +370,15 @@ and `canon context` warn when the repo holds 0.27-era state and put
 ```bash
 # canon.yaml, starter policy (--policy light|standard|strict, default strict; see canon-policy), AGENTS.md block, commented plans examples
 canon init
-# harnesses for the canon skill; without it init takes the detected .claude/.codex/.omp/.pi (it never asks)
-canon init --providers=claude,codex
+# harnesses for the canon skill, one --harness each (--no-harness for none); without them init takes the detected .claude/.codex/.omp/.pi (it never asks)
+canon init --harness claude --harness codex
 # follows canon.yaml skills.providers (else the install lock's, else the detected ones; none detected installs nothing); prunes projected files the bundle no longer ships when their bytes match the lock, keeps a modified one and reports `kept:`
 canon skills install
-# any subset or none; rewrites skills.providers
-canon skills install --providers=claude,codex,omp,pi
+# any subset; rewrites skills.providers (--no-harness records none)
+canon skills install --harness claude --harness codex --harness omp --harness pi
 # read-only drift check; exit 1 (SKILLS_CHECK_FAILED) names each orphan, a projected file the bundle no longer ships
 canon skills check
-# diagnostics, incl. a stray canon projection for an unselected provider and a projection a formatter rewrote, and `orphan:` lines for projected files the bundle no longer ships; never deletes user files
+# diagnostics, incl. a stray canon projection for an unselected harness and a projection a formatter rewrote, and `orphan:` lines for projected files the bundle no longer ships; never deletes user files
 canon skills doctor
 ```
 
@@ -372,7 +389,7 @@ Claude gets `.claude/skills/canon/`, Codex `.agents/skills/canon/`, OMP
 `.omp/skills/canon/`, Pi `.pi/skills/canon/` (the retrieve script is a sidecar,
 not an installed hook). `check` reports a stub written by another canon
 version; `install` rewrites it. The harness list lives in `canon.yaml` as
-`skills: { providers: [...] }`; change it with `canon skills install --providers=<list>`,
+`skills: { providers: [...] }`; change it with `canon skills install --harness <name>` once for each name (or `--no-harness`),
 never by assuming a default.
 
 `install` and `doctor` end with `owned-paths:`, the globs of every path
@@ -430,7 +447,6 @@ current step needs.
 | `canon-gate` | Evidence, gates, task checkboxes, hooks. |
 | `canon-review` | Findings and reviews. |
 | `canon-artifact-ingest` | `canon ingest records`: artifacts into verdict trajectories. |
-| `canon-session-ingest` | `canon ingest sessions`: agent transcripts into session records. |
 | `canon-plan-import` | `canon ingest plans`: plan state into change and task records. |
 | `canon-storage` | Storage rungs, tiers, retention, export, purge. |
 | `canon-policy` | The policy and the CEL expressions behind it. |

package/dist/skills/reference/canon-artifact-ingest.md

@@ -71,8 +71,6 @@ promotion/demotion.
 
 ## What this skill does NOT cover
 
-- Session/cost ingestion (`canon ingest sessions`) — a different
-  pipeline; see the `canon-session-ingest` skill.
 - Strategy promotion/demotion mechanics — see the `canon-learn` skill;
   this skill only produces the verdict evidence promotion reads.
 - The `regime_key` grammar itself — see `canon-retrieve`, which derives

package/dist/skills/reference/canon-gate.md

@@ -24,7 +24,7 @@ Every violation carries one of these stable, grep-able strings:
 | `uncovered-cell` | Either a policy-required evidence cell (role × artifact) with no matching record, or — with `spec_coverage` enabled — a spec scenario that is unimplemented or mismatched, or a feature surface missing a `require_cases` case. The detail string distinguishes them. Coverage means "a test exists", not "a test passed": even a `Divergent` verdict satisfies the role-cell form. At `verifying → shipped`, a `Divergent` latest verdict is `uncovered-cell` unless a reviewer accepted it (see Accepted divergence below), and a chore's approval, like a blocker closed `fixed`, needs every evidenced scenario evidenced again afterwards (see Re-verification below). |
 | `unreviewed-promotion` | An artifact tagged `reviewed` has no matching ledger review record — or, with `spec_coverage.require_review` set, an in-scope scenario has no qualifying `Review`: none at all, only self-reviews, only stale reviews (the spec or evidence it pinned changed since), or only `indeterminate`/`unavailable` ones. Also, subject `policy`: the policy changed since its approval or its approval is unreadable (fails closed; see `canon-policy`). See `canon-review`. |
 | `trust-below-required` | Achieved trust level is below `policy.yaml`'s `trust_required` for its class — RELEASE-scoped only (`canon gate check --release`); never fires on an ordinary run. |
-| `stale-evidence` | A passing record degraded to stale: its declared surface changed since its `evidence_sha`, or HEAD moved past `staleness.max_commits_behind`. Only degrades an already-green record. Also: a file bound to a latest evidence record whose bytes are gone — no intact blob in `.canon/artifacts/sha256/` and no working-tree copy with the recorded digest — or a file bound to an in-effect review with no intact blob (see Bound evidence stays provable below). |
+| `stale-evidence` | A passing record degraded to stale: a path that changed since its `evidence_sha` matches its declared surface (`--surface-ref`, a path pattern read from the repository root; the detail names the declarations and paths that matched), or HEAD moved past `staleness.max_commits_behind`. Only degrades an already-green record. Also: a file bound to a latest evidence record whose bytes are gone — no intact blob in `.canon/artifacts/sha256/` and no working-tree copy with the recorded digest — or a file bound to an in-effect review with no intact blob (see Bound evidence stays provable below). |
 | `malformed-evidence` | A candidate record doesn't parse, is misfiled, or carries an unparseable interim tag. Malformed evidence is no evidence. |
 | `flagged` | The human-only `flagged` overlay is set — never green regardless of passing evidence. |
 | `unevidenced-flip` | `canon task done <task_id>` was asked to flip a checkbox with no matching, non-`Divergent` evidence record. |
@@ -266,6 +266,32 @@ approval needs a new review, and so does a review of other code, as when the
 same brief is approved again over code that came after the review. An approval
 with no recorded tree (written before 0.37) follows the rule above.
 
+A policy may narrow what a chore asks for with `code_scopes` (0.38): a key is
+a scenario id's area (`core`) or surface (`app.bulkread`), the value a list of
+path patterns written like `code.exclude`; the surface key wins over the area
+key, and a scenario with neither has no scope. For a scenario with a scope the
+chore compares the code tree of its latest evidence with the tree now, and asks
+for new evidence only when a changed path (added, modified, deleted, a rename
+by its old and its new path) matches the scope; the refusal names the first
+three such paths and how many there are. No scope, no recorded tree, or an old
+tree that cannot be computed (the commit is gone, the evidence was recorded over
+uncommitted code) keep the rule above. The scopes stand only while the policy
+is the one a human approved: an agent cannot widen them (an edit after the
+approval fails closed, and so does a change that a brief approval would have
+approved implicitly), and `status` and
+`gate check` warn, never refuse, about a pattern that matches no file or a key
+that matches no scenario. A shared file (lock file, build setting, fixture)
+belongs in the scope of every scenario that depends on it.
+A key none of whose patterns matches a file of the current code tree declares no
+scope (a misspelt `Core/**` never exempts; matching is byte-exact), and an empty
+list is malformed, so that scenario follows the rule above; both are warned.
+`canon brief approve` records the policy approval in its own call except when
+the policy's `code_scopes` differs from the last approved policy's: then it
+approves the brief only, leaves the policy approval stale (the gate fails closed
+until a human reads the scopes and runs `canon policy approve`) and names the
+changed keys, so an agent cannot widen the scopes by asking for a brief's
+approval.
+
 ### Audit records (`canon evidence audit`)
 
 canon never generates or runs an audit. An external evaluator does, and
@@ -599,7 +625,11 @@ git-tracked, no credentials). With an object-store tier, `evidence add`,
 `canon artifacts verify [--full]` ask the store (a HEAD per digest; `--full`
 downloads and re-hashes) and refuse, never pass, when it cannot be reached.
 `canon artifacts move --tier <tier>` (a preview; `--commit --plan-digest` acts) moves an existing local
-store; it is the repo owner's decision. See `canon-storage`.
+store; it is the repo owner's decision. `canon artifacts prune` (a preview;
+`--commit --plan-digest` acts) deletes the blobs no record binds any more and
+leaves what `gate check` and `artifacts verify` read, so their answers do not
+change (it also deletes the stale `.tmp-` files a killed blob write left, which
+`artifacts verify` counts without deleting); it is the repo owner's decision too. See `canon-storage`.
 
 `canon gate check` re-checks every file bound to a LATEST evidence record
 (the latest per task and per `(project_id, scenario_id)`):
@@ -669,6 +699,30 @@ binding. This is still attestation input, not proof of the changed paths;
 run/diff metadata is authoritative when available, and an unavailable
 binding is a gate violation rather than a clean result.
 
+A `--surface-ref` that is not `effect:...` is a path pattern read from the
+repository root with the glob of `code.exclude`: `*` and `?` do not cross
+`/`, `**` does, a directory matches everything below it, and a trailing `/`
+is dropped. `src/`, `src`, `src/**` and `src/*.rs` all go `stale-evidence`
+when `src/a.rs` changes; for `src/x/b.rs` the first three do and `src/*.rs`
+does not. A name with no `/` is the file at the root: `Cargo.toml` is
+the root manifest, not every crate's. A value identical to a changed path
+matches it, and `effect:` is never compared with paths. A value that
+matches no file of the work tree is recorded all the same, with a
+`SURFACE_REF_UNMATCHED` warning. The `paths` of a risk tier keep their
+older reading (`*` crosses `/`) until the next release that breaks
+compatibility.
+
+When git cannot read the base commit of a passing cell, `canon gate check`
+prints one `staleness_unresolvable` advisory and `canon status` one
+`STALENESS_UNRESOLVABLE` warning, with the same sentence: how many
+(subject, role) cells, how many for each reason (`base_missing`: the commit
+is not in this repository, as in a shallow clone or after `git gc
+--prune=now`; `base_not_ancestor`: it is not an ancestor of HEAD, as after
+a squash merge; `git_unavailable`: git did not answer), the first three
+subjects, and `git fetch --unshallow` in a shallow clone. Verdicts and the
+exit status do not change: a `base_missing` or `git_unavailable` cell adds
+nothing, a `base_not_ancestor` cell is judged from `<base>..HEAD`.
+
 Approval identity is separate from attestation text. An approval counts
 only when it carries a detached SSH signature (`ssh-keygen -Y sign -n
 canon-approval-v1` over `canon evidence approval-payload`'s bytes) that

package/dist/skills/reference/canon-report-dashboard.md

@@ -1,9 +1,9 @@
 # canon-report-dashboard
 
-canon's single status surface: `canon report build` renders TEN panels to
-markdown, `canon report snapshot` exports the same ten marts to
+canon's single status surface: `canon report build` renders NINE panels to
+markdown, `canon report snapshot` exports the same nine marts to
 Parquet, and `canon dashboard` serves a small zero-network web app that
-renders SEVEN of them from such a snapshot. Neither surface computes an
+renders SIX of them from such a snapshot. Neither surface computes an
 aggregate itself — both read canon's precomputed
 `crates/canon-store/sql/views.sql` marts, and each run reads the corpus
 ONCE (`crates/canon-report/src/query.rs`'s `PIN_CORPUS_SQL`), so no two
@@ -35,7 +35,7 @@ drift-checked.
 
 ## `canon report build [--repo <dir>]`
 
-Renders the current ten-panel report to `<repo>/.canon/REPORT.md`.
+Renders the current nine-panel report to `<repo>/.canon/REPORT.md`.
 `--repo` resolves through the nearest-`canon.yaml`-ancestor walk every
 subcommand uses — omit it (or pass `.`) to run from any subdirectory.
 
@@ -82,7 +82,7 @@ and commit the result.
 
 ## `canon report snapshot <dir>`
 
-Exports all ten views to `<dir>/<table>.parquet` plus a
+Exports all nine views to `<dir>/<table>.parquet` plus a
 `<dir>/manifest.json`. One explicit `COPY` per view — the exported
 columns are each view's own `SELECT` list, wider than the curated column
 subset the markdown tables render. `file` is always
@@ -98,7 +98,6 @@ existing consumer's order never moves:
   "source_digest": "...",
   "tables": [
     { "table": "mart_trust_matrix", "file": "mart_trust_matrix.parquet" },
-    { "table": "mart_session_costs", "file": "mart_session_costs.parquet" },
     { "table": "mart_role_memory", "file": "mart_role_memory.parquet" },
     { "table": "mart_flywheel_funnel", "file": "mart_flywheel_funnel.parquet" },
     { "table": "mart_review_burndown", "file": "mart_review_burndown.parquet" },
@@ -174,7 +173,7 @@ human's explicit answer, with `--relayed-via`. The page lists the approvals an
 agent recorded for the human under "Approved through an agent" (`relayed` in
 `GET /api/briefs`), with the role, actor and tool of each.
 
-The dashboard renders SEVEN panels — trust matrix, session costs, role
+The dashboard renders SIX panels — trust matrix, role
 memory, flywheel funnel, review burn-down, review rounds, review totals.
 **Scope status
 and subjects are exported to the snapshot but have no dashboard panel**;
@@ -186,7 +185,7 @@ The dashboard's freshness banner shows the snapshot's
 snapshot, not necessarily the live checkout" note — treat "matches
 `canon report`" as "matches the inputs that produced THIS snapshot".
 
-## Reading the ten panels
+## Reading the nine panels
 
 In `canon report`'s own render order. Each panel names the view that
 computes it; nothing here is derived a second time.
@@ -202,17 +201,6 @@ computes it; nothing here is derived a second time.
   version; `green` and `who` are read off one whole winner row, so they can
   never come from two different attestations.
 
-- **Session costs** (`mart_session_costs`) — token/cost per
-  `(session, client, role, workspace_label)`. Every `run`/`session`/
-  `token_usage` record is folded to its latest version first, so
-  a re-ingested corrected cost REPLACES the superseded figure instead of being summed with it.
-  `workspace_label` is NOT a repo identity: it is the last non-empty path
-  segment of the `token_usage` event's workspace key and nothing more, so it
-  SPLITS one repo whose worktrees sit in differently-named directories and
-  MERGES two different repos sharing a directory name. Two stronger fields
-  exist and this mart reads neither — the event's own `workspace_key`, and
-  `Session.project_key`, which `canon-cli` stamps to the main worktree's key.
-
 - **Role memory** (`mart_role_memory`) — per-`(role, regime_key)` strategy
   counts. `hit_rate` is NOT a retrieval hit rate: it is the fraction of that
   namespace's distilled strategies carrying no `demotion` flag, i.e.
@@ -355,25 +343,28 @@ computes it; nothing here is derived a second time.
   a row is one change's review history, and `findings` moves with how
   much reviewing happened rather than with the change.
 
-Two marts in `views.sql` are NOT report panels and are not exported by
-`--snapshot`: `mart_records_by_kind` and `mart_session_run_handoff`.
-Read them with DuckDB directly against `views.sql`.
+One mart in `views.sql` is NOT a report panel and is not exported by
+`--snapshot`: `mart_records_by_kind`. It counts records per stored kind, so
+rows of the retired `session`/`event` kinds that remain in a store still show
+there until `canon purge` deletes them. Read it with DuckDB directly against
+`views.sql`.
 
 - **Run observability** (`mart_run_observability`) — one row per folded
-  `run_id`, appended as the tenth report/snapshot table after the established
-  nine tables. It reports lifecycle identifiers/status/timestamps, latency
-  only when both timestamps exist, event and label counts, child-run count,
-  guidance count, lineage provider/model, and token/cost source totals. These
-  are bounded observations and proxies: event counts do not infer tool calls,
-  retries, or human interventions, and no field claims guidance caused an
-  outcome. `directive_event_count` and `guidance_count` are counts only;
-  directive and guidance text is never emitted. `*_unknown` columns explicitly
-  expose missing joins/coverage, including missing session/project/task/lineage,
-  end timestamps, event times, costs, and guidance. Workspace absolute paths
-  and verbatim directives/guidance are intentionally omitted. The adapter
-  contract is strict read-only validation; this panel does not execute
-  adapters or enforce provider sandbox capabilities. Privacy-safe omission of
-  paths and directive/guidance text is part of the current semantics.
+  `run_id`, the ninth and last report/snapshot table after the established
+  eight tables. It reports lifecycle identifiers/status/timestamps, latency
+  only when both timestamps exist, child-run count, guidance count, and
+  lineage provider/model, all read from the `Run` record alone. These are
+  bounded observations and proxies: no field claims guidance caused an
+  outcome. `guidance_count` is a count only; guidance text is never emitted.
+  `*_unknown` columns explicitly expose missing values, including missing
+  session/project/task/parent-run lineage, end timestamps, provider/model and
+  guidance; a `Run` stored without `project_key` reads `project_key_unknown`.
+  There are no cost, token or event columns: canon has no cost or token
+  report and no replacement for it. Workspace absolute paths and verbatim
+  guidance are intentionally omitted. The adapter contract is strict
+  read-only validation; this panel does not execute adapters or enforce
+  provider sandbox capabilities. Privacy-safe omission of paths and guidance
+  text is part of the current semantics.
 
 ## What this skill does NOT cover
 

package/dist/skills/reference/canon-review.md

@@ -88,6 +88,15 @@ on the closing version, shown by `finding list` as `[reason: …]` and carried
 in the JSON. Give the reason when you reject or defer: it is the only record
 of why the finding was not fixed.
 
+Closing `rejected` or `deferred` overturns the judgement of whoever raised
+the finding, so it is the reviewer's: a call that declares another role
+(`--as` or `CANON_ROLE`: planner, implementer, orchestrator) is refused
+with `FINDING_ROLE_DENIED`, nothing is written and the finding stays open.
+`fixed` is closed by every role. The closing version records the role the
+call declared (`--role` is accepted only when it names that role, or when
+none is declared) and no role when none was; `finding list` names who
+closed each closed finding and under which role (`closedBy`, `closedRole`).
+
 `--scenario` (repeatable, each a scenario the index knows; refused with
 `SCENARIO_NOT_FOUND` otherwise) names the scenarios the finding is
 about. After a `fixed` close, fresh evidence for those scenarios alone
@@ -448,7 +457,7 @@ subject's `change_ids` (`canon subject adopt`). The subject string is
 `<change_id>#<round>.<seq>`:
 
 ```
-open-blocker c-demo#1.1 — open blocker finding by `reviewer-2` on change `c-demo` (subject `demo-subject`): unbounded subprocess wait; fix it and `canon finding close <change> --round <n> --seq <n> --disposition fixed`, or close it as rejected or deferred
+open-blocker c-demo#1.1 — open blocker finding by `reviewer-2` on change `c-demo` (subject `demo-subject`): unbounded subprocess wait; fix it and `canon finding close <change> --round <n> --seq <n> --disposition fixed`, or have a reviewer close it as rejected or deferred
 ```
 
 Findings on changes no in-scope subject has adopted do not block.

package/dist/skills/reference/canon-storage.md

@@ -172,6 +172,52 @@ uploads, reads back and verifies every local blob, then writes the
 `.canon/artifacts/`; commit the removals, `.gitignore` and `canon.yaml`. It is
 resumable and a second run finds nothing to do.
 
+The store only grows: a report written anew on every run adds a blob per run.
+`canon artifacts prune [--keep-days N]` (a preview; `--commit --plan-digest
+<digest>` acts) deletes the blobs no record binds. It keeps a blob for every
+reason that holds, and the preview names them: `latest-evidence` (the latest
+evidence per task and per `(project_id, scenario_id)` binds it, what the gate and
+`artifacts verify` read), `current-review` (a review still in effect binds it),
+`staged` (a record not promoted yet binds it) and `within-keep-days` (with
+`--keep-days N`, evidence or a review of the last `N` days, in the ledger or its
+archive, binds it). Everything else in the configured store goes: the local
+directory, or the objects of the tier `artifact_store:` names by the same rule
+(a copy left in the local directory of such a repo is judged by it too). The
+preview counts the blobs and bytes that go and stay, lists the blobs to delete
+a page at a time (`--limit`, `--cursor`, `--all`) and offers no `--commit` when
+there is nothing to delete. The plan digest covers the blobs to delete, the
+blobs to keep with their reasons and every record read, so evidence added since
+the preview is `PLAN_STALE` and nothing is deleted. A repo whose records,
+staging area or archive cannot be read in full is refused: a blob is never
+deleted on a guess. After a prune, `artifacts verify` and `gate check` answer as
+they did. A deleted local blob leaves the working tree: commit the removal. It
+stays in git history, and shrinking that history is the repo owner's call, not
+the command's. A deleted object of a tier cannot be undone, and the preview says
+so with the object count. A delete that fails stops the run: with nothing deleted yet
+it is `ARTIFACTS_STORE_FAILED` (an object) or `WRITE_FAILED` (a local file); after
+some, `ARTIFACTS_PRUNE_INCOMPLETE` names what was deleted, and a new preview
+lists what remains.
+
+A blob write stages `.canon/artifacts/sha256/.tmp-<sha256>-<pid>-<nanos>` and
+renames it when it is complete; a write killed in between (SIGKILL, a power
+cut) leaves the file, and nothing else removes it. `canon artifacts prune`
+counts the **stale** ones (a regular file of exactly that name shape, modified
+more than five minutes ago; a younger file may be a live write, and a link, a
+directory, a file stamped in the future or a name of another shape such as
+`.tmp-notes` is never touched) in `data.staleTemps` (`files`, `bytes` and the
+first names), apart from the blobs, and the commit deletes exactly the ones the
+plan lists. They are part of the plan digest, so a temp file added or removed
+since the preview is `PLAN_STALE`; the commit checks each again under the
+store lock and skips one that changed; a repo with only temp files and no blob
+to delete still gets the `--commit` command. `canon artifacts verify` takes no
+lock and deletes nothing: it prints one line with the count and bytes and
+`canon artifacts prune` when there are any, `data.staleTemps` always carries
+`files` and `bytes` (`unreadable` instead, never a zero, when the store
+directory cannot be read), and the exit follows the bound files alone. A temp
+file is no finished blob, so deleting it changes no record. One that was
+already committed is a tracked file: take it out of the commit (`git rm`, then
+commit); the preview's `staleTemps.gitNote` says so.
+
 ## What `canon report build` does and doesn't read
 
 canon exposes layered `stg_`/`int_`/`mart_` query views; `canon report build`
@@ -197,7 +243,11 @@ is the canonical data-lifecycle boundary: the bare run previews: it prints the r
 its `planDigest` and deletes nothing; `--commit --plan-digest <planDigest>` deletes only if
 the plan recomputed now has the same digest (`PLAN_STALE`, exit 2, when the
 data moved). The only purgeable kinds are
-`session`, `run`, `event`, and `trajectory`; the cutoff applies to every
+`run` and `trajectory`, plus the retired `session` and `event` (kept for this
+release only so stored rows can be deleted — delete them now, after the next
+release only direct database access remains; they read no routing, so they
+find rows in every configured tier even after `canon migrate` removes the
+`routing:`/`aging:` keys); the cutoff applies to every
 routed rung and every configured aging destination, including retained
 historical versions. For `trajectory`, the command also purges the
 operator-local Parquet learn store under `learn.root` in `canon.yaml`;
@@ -290,13 +340,13 @@ skills:
   providers: [claude, codex]   # any of claude, codex, omp, pi; [] for none
 ```
 
-`canon init` writes it and never asks: `--providers a,b` (or `none`) is the
+`canon init` writes it and never asks: `--harness a --harness b` (or `--no-harness`) is the
 answer; without it init takes the harnesses whose
 `.claude`, `.codex`, `.omp` or `.pi` directory exists, and with none detected
 it writes only a commented example
 and installs nothing. `.agents` alone never selects Codex. `canon skills
 install|check|doctor` follow the section; `install` prunes projected files the bundle no longer ships when their bytes match the lock (a modified one stays, reported as `kept:`), `check` exits 1 (`SKILLS_CHECK_FAILED`) naming each orphan and `doctor` prints `orphan:` lines; `canon skills install
---providers=<list>` rewrites it in place. Without the section they use the
+--harness <name>` (once for each name) or `--no-harness` rewrites it in place. Without the section they use the
 install lock's providers, then the detected ones; nothing undetected is ever
 added. A present section that is not this shape, or names another harness,
 fails those commands (exit `1`), and `canon init --check` reports
@@ -381,7 +431,7 @@ retry (the command exits `2` and writes no record).
 ## The repository write lock
 
 A committed destructive command (`canon purge`, `canon tier age`, `canon ledger
-compact`, `canon artifacts move`, `canon migrate`) recomputes its plan, checks
+compact`, `canon artifacts move`, `canon artifacts prune`, `canon migrate`) recomputes its plan, checks
 its digest and then makes the effects, and nothing may change the plan in
 between. It holds an OS file lock on `.canon/repo-write.lock` for the whole
 span, from before it recomputes the plan to after its last effect; a preview

package/dist/skills/reference/role-implementer.md

@@ -107,7 +107,7 @@ canon evidence approval-payload --scenario auth.login.01 --project root --approv
 ```
 ```text
 # Record an external evaluator's re-audit of one scenario (class `audit`; the verdict follows --audit-result; canon never runs the evaluator)
-usage: canon evidence audit <SCENARIO_ID> --ref <TEXT> --evaluator <ID> --evaluator-version <TEXT> --evaluator-digest <DIGEST> --audit-result <confirmed|refuted|indeterminate> [--project <PROJECT_ID>] [--summary <TEXT>] [--command-result <TEXT> (with --summary)] [--run <RUN_ID>] [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--rev <REV>] [--artifact <PATH>]* [--report <FORMAT:PATH>]* [--report-case <NAME> (with --report)]* [--max-artifact-mib <N>] [--override-reason <TEXT>] [--promote | --no-promote] [--input]
+usage: canon evidence audit <SCENARIO_ID> --ref <TEXT> --evaluator <EVALUATOR_ID> --evaluator-version <TEXT> --evaluator-digest <DIGEST> --audit-result <confirmed|refuted|indeterminate> [--project <PROJECT_ID>] [--summary <TEXT>] [--command-result <TEXT> (with --summary)] [--run <RUN_ID>] [--actor <ACTOR_ID>] [--role <ROLE>] [--session <SESSION_ID>] [--rev <REV>] [--artifact <PATH>]* [--report <FORMAT:PATH>]* [--report-case <NAME> (with --report)]* [--max-artifact-mib <N>] [--override-reason <TEXT>] [--promote | --no-promote] [--input]
 ```
 ```bash
 canon evidence audit auth.login.01 --ref audit-report.json --evaluator eval-1 --evaluator-version 2.1 --evaluator-digest 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef --audit-result confirmed --role implementer --json
@@ -156,7 +156,7 @@ canon inventory sync --json
 ```
 ```text
 # Read stored records across every storage tier
-usage: canon query --kind <change|task|scenario|session|run|event|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding> [--since <TIMESTAMP>] [--plugin <PLUGIN_ID> | --history] [--change <CHANGE_ID>] [--status <STATUS>] [--domain <NAME>] [--include-sensitive] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
+usage: canon query --kind <change|task|scenario|run|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding> [--since <TIMESTAMP>] [--plugin <PLUGIN_ID> | --history] [--change <CHANGE_ID>] [--status <STATUS>] [--domain <NAME>] [--include-sensitive] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
 ```
 ```bash
 canon query --kind evidence --json
@@ -184,7 +184,7 @@ canon schema evidence add --json
 ```
 ```text
 # Search records, brief sections and scenario text, with each hit's neighbors in the record graph
-usage: canon search <TEXT> [--kind <change|task|scenario|session|run|event|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding|brief>]* [--expand <N>] [--limit <N>]
+usage: canon search <TEXT> [--kind <change|task|scenario|run|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding|brief>]* [--expand <N>] [--limit <N>]
 ```
 ```bash
 canon search timeout --kind finding --json
@@ -212,7 +212,7 @@ canon task done add-login#1 --json
 ```
 ```text
 # Follow a finding's review loop in time order: review, finding, fix, re-review, evidence
-usage: canon trace <ID>
+usage: canon trace <TRACE_ID>
 ```
 ```bash
 canon trace add-login_1_1 --json
@@ -306,7 +306,8 @@ canon evidence add --input '[{"scenario":"auth.login.01","class":"test-run","ref
    re-checks them, so the working-tree report may be gitignored. Run
    `canon artifacts verify` to ask the store yourself; it refuses, never
    passes, when an object store cannot be reached. Moving an existing store
-   (`canon artifacts move --tier`) is the repo owner's call: do not run it.
+   (`canon artifacts move --tier`) and deleting the blobs no record binds
+   (`canon artifacts prune`) are the repo owner's call: do not run them.
    For a scenario about what users see, let the test report carry its
    screenshots: Playwright's JUnit reporter attaches, per test case, what a
    test attaches (`testInfo.attach(name, {path})`, or `screenshot: 'on'`), and

package/dist/skills/reference/role-orchestrator.md

@@ -44,6 +44,14 @@ usage: canon artifacts move --tier <TIER> [--commit --plan-digest <PLAN_DIGEST>]
 canon artifacts move --tier cold --json
 ```
 ```text
+# Delete the artifact blobs no record binds any more (the bare run previews; --commit --plan-digest deletes)
+usage: canon artifacts prune [--keep-days <N>] [--limit <N> | --all] [--cursor <CURSOR>] [--commit --plan-digest <PLAN_DIGEST>] [--input]
+# a bare run previews and prints planDigest; `--commit --plan-digest <PLAN_DIGEST>` with that digest acts
+```
+```bash
+canon artifacts prune --keep-days 30 --json
+```
+```text
 # Store the bound files of existing evidence records and current reviews in the artifact store (.canon/artifacts/sha256/)
 usage: canon artifacts store [--max-artifact-mib <N>] [--dry-run] [--input]
 ```
@@ -115,7 +123,7 @@ canon demo review --json
 ```
 ```text
 # Mint a Run manifest with retrieved guidance and context/policy lineage
-usage: canon dispatch begin --regime <KEY> [--role <ROLE>] [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--provider <NAME>] [--model <NAME>] [--skill <ID>] [--skill-digest <DIGEST> (with --skill)] [--manifest <FILE>] [--prompt-bundle <NAME@VERSION>] [--task <TASK_ID>] [--parent-run <RUN_ID>] [--input]
+usage: canon dispatch begin --regime <KEY> [--role <ROLE>] [--actor <ACTOR_ID>] [--session <SESSION_ID>] [--provider <NAME>] [--model <NAME>] [--skill <SKILL_ID>] [--skill-digest <DIGEST> (with --skill)] [--manifest <FILE>] [--prompt-bundle <NAME@VERSION>] [--task <TASK_ID>] [--parent-run <RUN_ID>] [--input]
 ```
 ```bash
 canon dispatch begin --regime implementer/my-repo/api/abcdef012345 --role implementer --json
@@ -150,7 +158,7 @@ canon evidence approval-payload --scenario auth.login.01 --project root --approv
 ```
 ```text
 # Export a redacted retention manifest without deleting records
-usage: canon export --kind <change|task|scenario|session|run|event|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding> [--before <TIMESTAMP>] [--after <TIMESTAMP>] [--output <FILE>] [--include-sensitive] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>] [--dry-run] [--input]
+usage: canon export --kind <change|task|scenario|run|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding> [--before <TIMESTAMP>] [--after <TIMESTAMP>] [--output <FILE>] [--include-sensitive] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>] [--dry-run] [--input]
 ```
 ```bash
 canon export --kind evidence --output evidence.json --json
@@ -198,15 +206,8 @@ usage: canon ingest records [--watch] [--interval-secs <N>] [--dry-run] [--run <
 canon ingest records --json
 ```
 ```text
-# Import agent CLI session transcripts (omp/pi, Claude Code, Codex, Hermes)
-usage: canon ingest sessions [--watch] [--interval-secs <N>] [--home <DIR>] [--full] [--all-workspaces] [--dry-run] [--input]
-```
-```bash
-canon ingest sessions --json
-```
-```text
 # Set up canon in a repo (canon.yaml, a starter policy, the AGENTS.md block, a plans home)
-usage: canon init [--check] [--no-agents-md | --check] [--policy <light|standard|strict> | --check | --no-policy] [--providers <LIST> | --check] [--language <TAG> | --check] [--dry-run | --check] [--input]
+usage: canon init [--check] [--no-agents-md | --check] [--policy <light|standard|strict> | --check | --no-policy] [--harness <claude|codex|omp|pi> | --check | --no-harness]* [--language <TAG> | --check] [--dry-run | --check] [--input]
 ```
 ```bash
 canon init --json
@@ -264,15 +265,15 @@ canon prompt show reviewer@v1 --json
 ```
 ```text
 # Remove allowlisted records older than a cutoff
-usage: canon purge --kind <session|run|event|trajectory> --before <TIMESTAMP> [--commit --plan-digest <PLAN_DIGEST>] [--input]
+usage: canon purge --kind <run|trajectory|session|event> --before <TIMESTAMP> [--commit --plan-digest <PLAN_DIGEST>] [--input]
 # a bare run previews and prints planDigest; `--commit --plan-digest <PLAN_DIGEST>` with that digest acts
 ```
 ```bash
-canon purge --kind session --before 2020-01-01T00:00:00Z --json
+canon purge --kind run --before 2020-01-01T00:00:00Z --json
 ```
 ```text
 # Read stored records across every storage tier
-usage: canon query --kind <change|task|scenario|session|run|event|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding> [--since <TIMESTAMP>] [--plugin <PLUGIN_ID> | --history] [--change <CHANGE_ID>] [--status <STATUS>] [--domain <NAME>] [--include-sensitive] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
+usage: canon query --kind <change|task|scenario|run|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding> [--since <TIMESTAMP>] [--plugin <PLUGIN_ID> | --history] [--change <CHANGE_ID>] [--status <STATUS>] [--domain <NAME>] [--include-sensitive] [--limit <N> | --all] [--cursor <CURSOR>] [--fields <FIELDS>]
 ```
 ```bash
 canon query --kind evidence --json
@@ -321,35 +322,35 @@ canon schema evidence add --json
 ```
 ```text
 # Search records, brief sections and scenario text, with each hit's neighbors in the record graph
-usage: canon search <TEXT> [--kind <change|task|scenario|session|run|event|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding|brief>]* [--expand <N>] [--limit <N>]
+usage: canon search <TEXT> [--kind <change|task|scenario|run|handoff|review|divergence|trajectory|strategy_item|evidence|subject|finding|brief>]* [--expand <N>] [--limit <N>]
 ```
 ```bash
 canon search timeout --kind finding --json
 ```
 ```text
 # Run canon's built-in fixture self-tests
-usage: canon selftest [--suite <trust-spine-gate|tiered-storage|typed-authoring-vocabulary|policy-expressions|format-authority|session-ingest|canon-context|artifact-ingest|spec-ledger-selftest|plugin-overlays|plan-import>]
+usage: canon selftest [--suite <trust-spine-gate|tiered-storage|typed-authoring-vocabulary|policy-expressions|format-authority|canon-context|artifact-ingest|spec-ledger-selftest|plugin-overlays|plan-import>]
 ```
 ```bash
 canon selftest --suite trust-spine-gate --json
 ```
 ```text
 # Check canonical projections without writing; exit 1 on drift, a legacy remnant, or a lock another canon version wrote
-usage: canon skills check [--skills-source <DIR>] [--providers <LIST>]
+usage: canon skills check [--skills-source <DIR>] [--harness <claude|codex|omp|pi> | --no-harness]*
 ```
 ```bash
 canon skills check --json
 ```
 ```text
-# Print diagnostics for canonical projections, the install lock's canon version, legacy remnants, canon projections for a provider that is not selected, and other skills whose description claims build work; reports only, never edits
-usage: canon skills doctor [--skills-source <DIR>] [--providers <LIST>]
+# Print diagnostics for canonical projections, the install lock's canon version, legacy remnants, canon projections for a harness that is not selected, and other skills whose description claims build work; reports only, never edits
+usage: canon skills doctor [--skills-source <DIR>] [--harness <claude|codex|omp|pi> | --no-harness]*
 ```
 ```bash
 canon skills doctor --json
 ```
 ```text
 # Install the canonical `canon` bundle or legacy developer skills
-usage: canon skills install [--skills-source <DIR>] [--providers <LIST>] [--dry-run] [--input]
+usage: canon skills install [--skills-source <DIR>] [--harness <claude|codex|omp|pi> | --no-harness]* [--dry-run] [--input]
 ```
 ```bash
 canon skills install --json
@@ -384,7 +385,7 @@ canon strategy promote 01ARZ3NDEKTSV4RRFFQ69G5FAV --json
 ```
 ```text
 # Disable an active strategy with durable rollback provenance
-usage: canon strategy rollback <STRATEGY_ID> --reason <TEXT> --actor <ACTOR_ID> --signature-file <FILE> --approval-at <TIMESTAMP> [--contradicting-trajectory <ID>] [--input]
+usage: canon strategy rollback <STRATEGY_ID> --reason <TEXT> --actor <ACTOR_ID> --signature-file <FILE> --approval-at <TIMESTAMP> [--contradicting-trajectory <TRAJECTORY_ID>] [--input]
 ```
 ```bash
 canon strategy rollback 01ARZ3NDEKTSV4RRFFQ69G5FAV --reason "regressed in production" --actor alice --signature-file approval.sig --approval-at 2030-01-01T00:00:00Z --json
@@ -434,7 +435,7 @@ canon tier age --json
 ```
 ```text
 # Follow a finding's review loop in time order: review, finding, fix, re-review, evidence
-usage: canon trace <ID>
+usage: canon trace <TRACE_ID>
 ```
 ```bash
 canon trace add-login_1_1 --json
@@ -631,7 +632,7 @@ read that changed since is `PLAN_STALE` too, and `meta.next[0]` is the preview
 to run again. A commit holds the repository write lock for its whole run:
 another command that writes waits for it, and one that waited 30 seconds
 answers `REPO_LOCK_UNAVAILABLE` (exit 2, retryable): run it again. A document passed
-with `--input` never carries `--commit` or `--plan-digest`, and these five
+with `--input` never carries `--commit` or `--plan-digest`, and these six
 leaves take one object only (`INPUT_INVALID`).
 
 ```bash
@@ -641,7 +642,11 @@ canon ledger compact
 ```
 
 `canon artifacts move --tier <tier>` moves the local artifact store to an
-object store and removes the local blobs, and `purge` deletes records. They
+object store and removes the local blobs, `canon artifacts prune` deletes the
+blobs no record binds any more and the stale `.tmp-` files a killed write left
+in the store (a deleted local blob stays in git history; a deleted object of a
+tier is gone for good; `canon artifacts verify` only counts the temp files), and
+`purge` deletes records. They
 are the repo owner's decisions, not steps of the loop: run the preview, give
 the human the effects, and run the commit only on their answer. If the repo is
 large, the store is slow or the human has not asked for it, do not run it.