@staix/agent-hub 0.12.29 → 0.12.30

package/docs/memory.md

@@ -1,8 +1,28 @@
-# Hub memory
+# Hub memory integration
 
-The hub's own memory (#258): notes the agents and the hub save while they work, kept in two tiers and linked into a
-graph by what they are about. It sits beside claude-mem, which stays the capture and session-recall source where it is
-installed. Every machine keeps its own copy in `~/.agenthub/memory/` (directory 0700, files 0600).
+Agent-hub consumes the exact-pinned first-party [`@staix/agent-mem`](https://github.com/STAIxBWLB/agent-mem) library (current pin `0.3.0`, initial pin `0.1.1`). The package owns portable storage, tiers, graph, goals, sync, import and raw commands. Agent-hub owns caller authority, current project privacy policy, task lifecycle integration and presentation. Optional claude-mem remains a separate capture and session-recall source.
+
+## Portable core and data directory
+
+The [agent-mem repository](https://github.com/STAIxBWLB/agent-mem) is the reference for the data model, immutable entry IDs, append-only segments, derived SQLite index and rebuild equality, home selection, import cursors, dedupe and machine sync. Shared v1 remains the default and needs no migration: schema `agent-hub.memory/v1`, canonical hashes and log/machine/lock paths remain compatible. `memoryHome()` comes from the package and selects `AMEM_HOME`, then `$AGENTHUB_HOME/memory`, then `~/.agenthub/memory`; an explicit `StoreOptions.home` keeps its parent-directory meaning. The test preload (`test/hub-home.ts`) clears inherited `AMEM_HOME` and supplies an isolated `AGENTHUB_HOME` when none is provided.
+
+`src/memory/` contains hub integration only: briefs, recall, the claude-mem worker client and capture. `src/hub/memory-policy.ts` supplies `withoutPii`, `promotionScreen` and `mentionsPrivatePath`; `src/hub/read-tools.ts` supplies screened peer reads. Deny, hardened git, realPath and process identity come from the package's Node-safe `@staix/agent-mem/platform` entry and are re-exported through the existing local/hub/Pi modules. No core implementation is vendored in agent-hub. The `0.1.1` platform subpath is required because `0.1.0` exposes only a root entry that loads `bun:sqlite`, which Node-hosted Pi extensions cannot import. This is a packaging compatibility export; the platform algorithms are unchanged.
+
+## Selected memory profile
+
+The memory root `M` is independent of the project state directory. The package's `M/profile.json` selects shared v1 or an explicit generation `G`; an absent selector means shared v1. The hub opens the selected profile with its current privacy screen and configured TTL. A generation uses `M/generations/G`, reads legacy prefixes through the package's readonly bridge, and writes its own rows and sync history there. The bridge does not migrate legacy bytes or use the legacy index. Exact-entry prune remains the package's person-only operation; it adds no shared-v1 operation and gives hub tools no prune authority.
+
+All hub consumers share that binding: Tasks notes and lifecycle operations, leases, suggestions, briefs, recall, peer read tools, dashboard, ask and automatic sync. Standalone `amem` and `ahub memory`/`ahub goal` must resolve the same root and profile to see one another's writes. An invalid selector or missing/corrupt generation disables native memory without taking down the bus or task board; it never silently opens shared v1. The daemon reports its package/profile binding and availability separately from ordinary hub health.
+
+Person-facing status and memory output show the profile and nonzero malformed-row count. Allowed agent-shell reads retain current row screening and receive only a short profile label; full generation IDs, the memory home and home-wide skipped totals are available through authenticated person status and person CLI receipts, never the shell-readable status.json file or agent CLI output. Domain JSON shapes are unchanged; the additive `memoryProfile` receipt belongs to status, profile-check and the person-only decay object. Profile-check reports the registry scope it inspected; inventory separate custom registries too before treating zero live claims as quiescence.
+
+A running daemon keeps its original binding. Explicit checks at hub operation entry and before sidecar writes fence later operations when the selector changes or becomes unavailable; they do not switch stores in place. These checks are not atomic with an in-flight core operation: changing selection during such an operation is outside the supported cutover contract. Before migration or a selector change, quiesce every consumer of this memory home and close its handles; reopen through the supported session-preserving lifecycle afterward. A public core pre-write hook is the upgrade path for atomic in-flight cutover. Current policy screening, PII-turn refusal, capture exclusion and fail-open task delivery remain in force.
+
+Candidate/counter data stays at `M/candidates.db`, independently of the selected note profile, using the package's explicit sidecar home convention. It is not copied into `G`, migrated or synced. The hub fences sidecar producers with the note-profile binding. Standalone `amem review` still refuses a selected generation; this integration does not add generation candidate acceptance or dashboard acceptance.
+
+Source and synthetic fixture checks do not authorize migration of the person's memory home. Before real migration, every hub sharing the memory home must run 0.12.30. Real rollout still needs separately approved installation, matching live package/root/profile/selector bindings, synthetic cross-write and prune readbacks, and a supported quiesce/close/reopen sequence before separately confirmed real migration. Every running hub using this home needs an authenticated receipt: a matching ready binding, or a generation-capable unbound receipt (`disabled` when native memory is off, `unavailable` when opening failed) proving it holds no memory handle. An unbound daemon and zero running hubs are quiesced for memory; a stale bound handle, unreadable registry or unknown runtime is not ready. Real account/device sync, native capture and live memory receipts remain distinct acceptance legs. See [agent-mem migration and prune](https://github.com/STAIxBWLB/agent-mem#generation-migration-and-exact-entry-prune) for the person CLI and recovery limits.
+
+For a standalone CLI refusal, inspect the selector and generation state and run `ahub memory profile-check`. If deliberately abandoning the selected generation, use the person-only `amem migrate --deactivate` recovery path; a CLI error does not itself require restarting a hub.
 
 ## Turning it on and off
 
@@ -12,28 +32,9 @@ short-term entries live after their task is approved, and `memory.sync_interval_
 hub syncs once a remote is set. Writing and
 reading are fail-open: a store that cannot be written costs one notice, and never a tool call or a turn.
 
-## Tiers
-
-- **Short-term**: notes saved against a task that is still open, and notes saved with no task. They stay on this
-  machine (`local/<machine>.jsonl`) and leave the index `short_ttl_days` after their task is approved (a note with no
-  task, or saved with `horizon: "short"` on purpose: after it was written, and it is never promoted; a demoted entry:
-  after the demotion; a note on a task that is never approved: 180 days after it was written, the same for every
-  reader). The deadline is written into the entry (`expires`)
-  or the op (`settle`, `demote`) when it is set, so every process reading the store prunes the same rows whatever its
-  own setting. Their log lines stay on disk.
-- **Long-term**: decisions, contracts and fails that outlive their task. When a task is approved, its decision, contract
-  and fail notes are copied to long-term automatically (findings are not), and the short-term originals are hidden.
-  Each is screened again first under the project's current PII patterns and `pii.paths`; one that fails stays
-  short-term on this machine and expires. An
-  agent can save straight to long-term with `hub_remember(..., horizon: "long")`; a note against an already approved
-  task that is a decision, contract or fail is long-term at once. Long-term entries go to `log/<machine>.jsonl`, the
-  segment machine sync will carry.
-- **Scope**: `project` (default) entries are read only in the project that wrote them; `shared`
-  (`hub_remember(..., scope: "shared")`) entries are read from every project on the machine.
-
-A project is named by its `origin` remote, normalized to host and path (`github.com/owner/repo`, lowercased on GitHub, whose
-names ignore case; a URL keeps a port that is not its scheme's default), the same on every machine; a repository without one is named by its git chain plus a hash of its directory, so two unrelated
-repositories with the same name never share entries (that name is this machine's only).
+## Task lifecycle and host policy
+
+Notes on open tasks stay short-term. Approval settles the task and can promote decision, contract and fail notes; findings stay short-term. The hub injects its current project screen through `StoreOptions.screen`: another project's notes are left to that project's processes, and secret-looking text, current PII patterns and private paths keep a note local rather than promoting it. A task's current paths are screened as well as its stored nodes. Task-specific deadlines retain the existing configured TTL and package lifecycle semantics.
 
 ## What gets written
 
@@ -44,57 +45,15 @@ repositories with the same name never share entries (that name is this machine's
   same PII and secret rules. Nothing about a PII task is written.
 - Notes still go to claude-mem when it is enabled, as before; the other peers get the note line on their next delivery.
 
-## Entries (`agent-hub.memory/v1`)
-
-One JSON line each. The id is the first 32 hex characters of the SHA-256 of the entry's canonical JSON (sorted keys,
-without `id`), so the same content always has the same id and a line whose id does not match is skipped. Nothing is
-ever rewritten: a change is a new entry.
-
-| `op` | Fields |
-| --- | --- |
-| `note` | `project`, `scope`, `tier`, `kind` (`decision`, `finding`, `contract`, `fail`), `peer`, `title?`, `text` (at most 4000 characters), `task?` (`<project>#<id>@<created ms>`), `about` (nodes), `supersedes?`, `promotedFrom?`, `source` (`hub`, `person`, `claude-mem`), `expires?` (a short-term note with no task, on a task already settled, or saved short-term on purpose: its own deadline, whatever the task does); a promoted copy is dated as its source and keeps its fields, whoever promotes it |
-| `forget` | `target`: the entry is gone from the index, and so is its promoted copy or original |
-| `supersede` | `target`, `by`: the newer entry; superseded entries are dropped from briefs and recall while the newer one is live (forgetting it shows the old one again) |
-| `demote` | `target`, `by`: a long-term entry becomes short-term and leaves the index at `by` |
-| `settle` | `target`: a task key, `by`: when its short-term entries leave the index (written when the task is approved; a settlement a crash cut short is finished at the next read, and a held decision, contract or fail whose replacement is forgotten or expires moves to long-term then too) |
-
-Every entry also has `schema`, `id`, `at` (ISO time) and `machine` (a random id per `~/.agenthub`, in
-`memory/machine.json`, with a label a person can edit).
-
-## The graph
-
-Nodes are entries (`mem:<id>`), files (`path:src/a.ts`, relative to the project root), symbols (`symbol:parse@src/a.ts`,
-with the path when the task's plan names exactly one), issues (`issue:owner/repo#12`, the repo from the project's
-`origin` remote on GitHub, else the project name), board tasks (`task:<project>#3@<proposal ms>` for the task a note was saved against, so a task id reused after
-`ahub reset --all` is another node; `task #N` in a text names `task:<project>#N`), peers, machines and projects.
-Edges are deterministic and fixed when the entry is written, so a rebuild never depends on the file system:
-
-- `about`: from the task's refs and plan paths, plan symbols, paths named in the text that exist in the project at
-  write time (denylisted paths are left out), `#N` and `task #N`, and the task the note was saved against. A `fail`
-  draws them as `rules_out`.
-- `by` (peer, machine) and `in` (project), from the entry's fields; `supersedes` between entries.
-
-- `part_of` (board task to long-term task) and `depends_on` (between long-term tasks), from the links below.
+## Graph integration and suggestions
 
-- Model-suggested edges, off by default (`"memory": { "suggest_edges": true }`): after a note is saved, the hub's model
-  (the same route as digest condensation) names `contradicts` or `same_topic` between it and up to six near entries.
-  Its answer is read line by line against that closed list and stored as a suggestion by `hub-model` (`suggest`,
-  `confirm`, `reject` entries). Suggestions are drawn dashed on the dashboard and are never evidence: briefs, recall and
-  `ahub ask` ignore them until a person confirms one (`ahub memory confirm <id>`); a rejected one disappears.
+The hub supplies task refs, plan paths/symbols and note context when extracting deterministic nodes. Briefs and ask use the package graph; the portable node and edge model is documented in agent-mem.
 
-## Long-term tasks
+Model-suggested edges are off by default (`"memory": { "suggest_edges": true }`). After a note is saved, the hub's model (the digest-condensation route) may name `contradicts` or `same_topic` between it and up to six near entries. Answers are checked against that closed list and stored as `hub-model` suggestions. They are dashed on the dashboard and excluded from briefs, recall and `ahub ask` until a person confirms one (`ahub memory confirm <id>`); a rejected suggestion disappears.
 
-A long-term task (a goal) spans sessions, board tasks, projects and machines: an epic issue, a migration. It has a
-state (`open`, `active`, `blocked`, `done`, `dropped`), milestones, the long-term tasks it depends on, its linked board
-tasks (project, task id and proposal time, so a reset's reused ids never join it) and a lease. All of it lives in the
-synced log as entries:
+## Long-term task integration
 
-| `op` | Fields |
-| --- | --- |
-| `goal` | `project`, `scope`, `title`, `milestones`, `dependsOn`, `actor` |
-| `goal_state` | `target`, `by`: the state |
-| `goal_link` | `target`, `by`: the board task key |
-| `lease`, `lease_force` | `target`, `by`: until when (ISO) |
+Goal storage and leases are supplied by agent-mem. The hub integrates them with board tasks:
 
 - **Titles** and milestones are kept to one line (whatever another machine wrote), and recall lines are sanitized, so
   they cannot carry a forged message header into an agent's context.
@@ -124,39 +83,11 @@ ahub goal state 1a2b3c4d blocked
 ahub goal done 1a2b3c4d
 ```
 
-## Machine sync
+## Automatic sync integration
 
-The memory directory is a git repository that tracks only `log/*.jsonl` (and its `.gitignore`); the index, the local
-short-term segment and `machine.json` never leave the machine. Each machine commits only its own segment and starts
-its own history, so merging another machine's history never conflicts.
+A person configures the private remote with `ahub memory sync --remote <private-git-url>` and can sync immediately with `ahub memory sync`. Machine labels use `ahub memory machine --label <name>`.
 
-```bash
-ahub memory sync --remote git@github.com:you/agent-hub-memory.git   # once per machine, a person's
-ahub memory sync                                                    # pull, then push, now
-ahub memory machine --label "office mac"                            # a name shown beside the id
-```
-
-- A sync commits this machine's segment, fetches, merges the remote's history, pushes (once more after a merge when
-  another machine pushed in between) and indexes what arrived. One sync runs per machine at a time.
-- A running hub syncs 5 seconds after it starts and every `memory.sync_interval_min` minutes (default 10; 0 turns it
-  off) once a remote is set. A failure is one `hub.log` line and never blocks a turn; a store without a remote does
-  nothing and creates nothing.
-- The remote must be private: long-term entries hold note text. A GitHub remote is checked with `gh repo view` and a
-  public one is refused; any other host, or a `gh` that cannot answer, is unknown and the sync goes on with a warning.
-- Use an SSH remote, or HTTPS with a credential helper in your global git config: the hub keeps your credential helper
-  for this repository only, and never prompts.
-- A forgotten entry stays in the remote's git history; removing it from there is a person's history rewrite.
-
-## Index
-
-`index.db` (SQLite) is derived from the logs: entries, ops and edges are inserted with `INSERT OR IGNORE`, and every
-state (superseded, forgotten, promoted, demoted, expired) is computed from those rows, so reading the segments in any
-order gives the same index, and the index each hub keeps up to date as it writes equals a rebuild from the logs. Each
-reader keeps the byte offset it reached per segment and reads only what was appended since; a line still being written
-waits for the next read. A segment that got shorter, disappeared or was rewritten in place (the indexed part no longer
-hashes to what was indexed) makes the reader rebuild the index from every segment. Malformed lines and lines whose id does
-not match their content are skipped with one log line.
-`ahub memory rebuild` drops the rows and reads every segment again; deleting `index.db` does the same on the next start.
+A running hub syncs 5 seconds after start and every `memory.sync_interval_min` minutes (default 10; 0 disables it) once a remote is set. Failure produces one log line and never blocks a turn; without a remote it does nothing and creates nothing. The package retains one sync per machine, public-GitHub-remote refusal and unknown-visibility warnings. Credential-helper use is restricted to the memory repository the hub creates, never a project's git repository, and never prompts. Transport, segment merge, lock and retained-history semantics belong to agent-mem.
 
 ## Reading it
 
@@ -164,12 +95,11 @@ not match their content are skipped with one log line.
   the task's paths, symbols, issue and task: a linked fail first, then nearer, then newer; superseded entries dropped;
   other projects' entries only when shared), then claude-mem's, `memory.brief_items` lines in all. A peer is never
   shown the same entry twice in one hub run.
-- **Session-start recall**: this project's long-term decisions, contracts and fails (and shared ones), newest first,
-  lead the recall block; claude-mem's recent work follows. Each gets half of `memory.inject_tokens` when both answer.
+- **Session-start recall**: this project's long-term decisions, contracts and fails (and shared ones) lead the recall block; display-only filtering omits automatic approval notes, while changes-requested notes show their nonempty reasons. Lines preserve their headers and end at word boundaries with a visible marker when capped; each delivery deduplicates memory ids across prefaces and note lines. Stored notes and brief evidence are unchanged. Claude-mem's recent work follows; each gets half of `memory.inject_tokens` when both answer.
 - **`ahub ask`**: entries that match the question and the graph neighbourhood of what they are about are evidence, cited
   as `[mem:<8 hex>]`. A question that carries PII skips them. `ahub ask --remember` still saves only to claude-mem, so a
   model's answer never becomes hub memory.
-- **`ahub memory`** (no hub needed; reading is anyone's):
+- **`ahub memory`** needs no running hub. The hub CLI identity gate allows screened list/search/show reads in agent shells; graph and unscreened views are a person's. Managed peers use the bounded `hub_memory_search`, `hub_memory_show` and `hub_memory_graph` tools through the daemon, with project scope, `memory_read`, PII-turn refusal and capture exclusion:
 
 ```bash
 ahub memory                              # this project's entries, newest first, with tier counts
@@ -200,54 +130,15 @@ ahub memory dedupe                     # inspect legacy claude-mem duplicate gro
 ahub memory dedupe --apply             # append supersede relations, never rewrite log bytes
 ```
 
-A forgotten long-term entry stays in the log file and in the sync remote's git history; removing it from there is a
-person's rewrite of that history. Forgetting a claude-mem import forgets every known non-forgotten member of its tuple group (source, project, source timestamp and text), including hidden duplicates, so they cannot reappear when their replacement is forgotten.
+For storage-level forget, supersede, expiry and dedupe semantics, see [agent-mem](https://github.com/STAIxBWLB/agent-mem). A forgotten shared entry remains in log and remote git history; removing that history is a person's operation. The hub keeps current project privacy checks around every raw command callback. The standalone `amem --policy-free` choice is not available through `ahub memory` and never grants a peer extra authority.
 
 ## Importing from claude-mem
 
-`ahub memory import claude-mem [--db <path>] [--limit N] [--restart]` (a person's) copies the hub's own notes from claude-mem
-(observations whose metadata names a `peer`: `hub_remember` and the hub's task notes) into long-term hub memory as
-`source: claude-mem`, for this project only. The SQL filters by the repository's basename before applying the limit;
-a superproject's notes stay out, while two unrelated repositories with one basename still share claude-mem's namespace.
-Model answers from `ahub ask --remember`, PII-pattern text, text about a path made private by the project's `pii.paths`
-and secret-looking text are skipped. The source database is opened read-only and never changed.
-
-- Import graph nodes are derived from text only: no checkout existence check and no machine-local `local.deny`.
-  Built-in denylisted names, relative-path normalization, absolute/parent exclusion, sorting and the 64-node cap still apply.
-  The source's timestamp and the existing content hash stay unchanged. Matching observations on different checkouts now
-  produce the same id; old ids, references and content validation remain valid. The local tuple fallback keeps re-import
-  idempotent even for legacy ids (its known ceiling is that the tuple excludes title).
-- A machine-local `memory/import-state.json` records the last fully handled row, including all skips. The cursor key
-  combines the source DB's real path, claude-mem project name and hub project key. The file uses mode 0600 and atomic
-  replacement; it never syncs. Unreadable or malformed state replays from zero, write failure logs a warning and preserves
-  the import result, and a source whose maximum candidate id for this project is below the cursor resets it (unrelated projects cannot mask a recreated source). Completed progress is saved even if a later
-  row throws. `--restart` starts from zero; use it after changing a PII policy to revisit rows skipped under the old policy.
-- The default limit is 10000. JSON reports `read` (project-matched, peer-tagged SQL rows this run), `added`,
-  `skipped.model`, `skipped.pii`, `skipped.secret`, `cursor` (last handled id), and `more` (`read === limit`). Malformed
-  metadata, non-string peers and empty text count only in `read`; already imported rows add nothing. `more` asks for
-  another run, which can return zero rows when the last batch exactly filled the limit. There is no project-skip counter.
-- Repository identity still depends on the local real path without an origin remote, and non-GitHub remotes spelled
-  differently can yield different project keys. These affect all hub memory and remain outside this import fix.
-
-### Legacy duplicate imports
-
-`ahub memory dedupe [--apply] [--json]` is console-only, including the listing, because it shows unscreened note text.
-It groups this project's non-forgotten claude-mem entries by `(source, project, at, text)`. Listing reports only actionable
-groups, their members, heads and chosen target; `--apply` appends ordinary supersede operations in this machine's log.
-Historical log bytes are never rewritten. Forget operates on the whole known tuple group.
-
-- Heads have no current replacement. Existing replacement relations, including a person's distinct outside notes, stay
-  intact. If every head can reach a valid synced outside terminal (shared when any head is shared), the newest qualifying
-  terminal by `(at, id)` replaces all heads, even a single head. Otherwise multiple heads converge onto the smallest id
-  among the heads; zero heads or one head without a qualifying outside terminal require no writes. A refused supersede
-  is reported as an error. Re-running after convergence writes nothing.
-- When `A -> B` already exists inside a group, dedupe connects another head `C -> B`, without trying the cyclic `B -> A`.
-  When `B -> X` and `C -> Y` name outside user replacements, `X` and `Y` both remain visible; a remaining head moves to
-  the newer qualifying terminal. A later outside replacement can make a previously settled group actionable again.
-- Old or mixed extractor versions can still introduce duplicate ids. Run dedupe after syncing them. Two machines acting
-  on divergent prior relations can choose different targets; sync folds relations deterministically using the existing
-  latest-relation and cycle guards. If several group members remain visible, one more dedupe run converges them. New
-  same-version imports with stable project keys converge automatically in either sync order.
+`ahub memory import claude-mem [--db <path>] [--limit N] [--restart]` is a person's command. It imports peer-tagged hub observations for the current project through the package's read-only SQLite importer. The hub supplies the current routing PII patterns and `pii.paths` screen; model answers and secret-looking text remain excluded. The source database is never changed.
+
+The package owns deterministic import identity, text-only graph extraction, cursor bookkeeping, tuple fallback and result counts. `--restart` revisits rows skipped under an earlier policy. Claude-mem's basename namespace can still collide between unrelated repositories; a superproject's observations stay out. A repository without an origin still uses machine-local project identity. These ceilings are unchanged by the library switch.
+
+`ahub memory dedupe [--apply] [--json]` remains console-only, including listing, because it shows unscreened note text. The package's reconciliation appends ordinary supersede operations; historical log bytes are never rewritten.
 
 ## Measuring it
 
@@ -266,3 +157,30 @@ Whether hub memory helps is measured, not assumed (#258 AC11, with #248):
 - Nothing about a PII task enters the store: the tool refuses it and the hub's own notes skip it. Text that matches a
   PII pattern, that the PII screen does not clear, or that looks like a secret is refused or skipped with a notice.
 - Hub log lines about memory carry ids and counts only.
+
+
+## Stage A plan guard and fail notes (#412 P7-1)
+
+A plan's explicit paths/symbols and refs paths are matched against live, screened fail `about` nodes (the source of v1 `rules_out` graph edges). Matching fails lead the owner's brief and the review delivery's checklist; accepting a plan or claiming work returns the same current advice. Existing related-memory fails-first ordering is retained. Unrelated fails do not gain plan priority. The guard informs, never blocks or changes the task, and PII tasks never invoke it.
+
+`hub_remember` accepts optional string fields `approach`, `symptom`, `cause`, `evidence`, and `retry_when` only with `kind: "fail"`. Provided fields appear in that order with labels `Approach`, `Symptom`, `Cause`, `Evidence`, and `Retry when`, after optional plain text. A structured-only fail is valid; plain text remains valid. The completed text is validated before policy, storage or display: at most 4000 UTF-8 bytes, with actual/limit byte counts on refusal and no truncation. Every composed field passes the existing secret/PII/private-path checks.
+
+## Decay review
+
+`ahub memory decay [--days N] [--json]` is person-only, including in delegated live-test sessions. Default age is 90 days. It lists this project's long-term, live, non-superseded notes strictly older than the cutoff, excluding links to open/active/blocked goals through the note's task or `about` nodes. Reads use current privacy screening and defer automatic promotions; authoritative JSONL bytes do not change. Index maintenance remains derived-only. A person acts separately through existing `demote` or `forget`. These are review rows, with no candidate-sidecar write.
+
+## Read-time staleness hint
+
+Recall lines, native brief items, `hub_memory_show` lines and human `ahub memory show` output mark `(stale?)` when an allowed `path:` or symbol-file path is missing. CLI `--json` keeps the v1 row unchanged. The marker is never stored or used as evidence of correctness.
+
+Each rendered batch has a shared cache and a hard bound of 32 metadata probes. On a tree not modified during the call, no hint probe reaches a `pii.paths`/`local.deny` path: declared private paths and the common deny policy are checked lexically first, including folded spellings and globs. Absolute/escaping paths, symlinks observed by a probe, denied paths, unreadable metadata and exhausted budgets are unknown and produce no marker. A concurrent ancestor swap by a process running as you can expose one existence bit; it is outside the [security threat model](security.md), and the deterministic ceiling witness is retained in the tests. Descriptor-anchored traversal is needed before supporting that scenario. Symbol nodes are checked only through their allowed file; this hint does not parse source symbols or read file contents. Current privacy screening still precedes rendering and peer-output byte caps. No new memory operation or candidate writer is introduced.
+
+## Review candidates and local usage counters
+
+Agents propose a correction with `hub_memory_correct {id, text, reason}`. The target is an exact id or unique visible prefix, screened under this project's current policy. The tool requires `memory_correct`, refuses private turns, and records a candidate with the full target id and revision. It does not edit a note or notify the other peers with the proposed text. Arguments and results are excluded from capture.
+
+A `changes_requested` review with unmet items can create one fail candidate. Tasks screens the public task title, unmet items and review evidence before the sidecar write; private tasks, private turns, withheld text and failed or unknown screens produce no candidate. Cause and retry conditions are explicitly unknown unless a person supplies them when reviewing.
+
+Candidates and rendered/delivered/cited counters live only in agent-mem's machine-local `M/candidates.db` (package retention: 500 candidates/project for 30 days, 10,000 counters/project for 90 days). They are never imported or synced and are not evidence for recall, briefs, ask or graph. For shared v1, a person reviews them with `amem review` and accepts or rejects through that CLI's TTY and policy checks; generation review remains unsupported and refused. Dashboard acceptance is a later step. Accepted results are ordinary v1 notes under the package's acceptance contract; the hub tool has no acceptance authority.
+
+Rendered observations use the final journal payload, including memory lines in prefaces and briefs, with the real delivery id. Delivered observations require the journal's first positive transport acknowledgement (or the pull path's completed read receipt). Failed or uncertain handoffs do not establish delivery; journal-less transports leave it unknown. Citation observations resolve `mem:<id8+>` in a peer message or task completion summary against screened project-visible entries. Citations use explicit `message:<envelope-id>` or `summary:<task>:<history-index>` observation keys when the source delivery is not proven; their rendered/delivered values remain unknown. They do not establish a per-delivery causal ratio. Duplicate observations are idempotent per entry/context/observation, not cumulative usage claims. Unavailable task, turn or session identity and unobserved metrics remain unknown, never zero. No observation is written for a private envelope, PII task or PII turn. These are delivery and citation proxies, not proof that an agent understood or used a note correctly.

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operations guide
 
-This guide describes ahub 0.12.29 and control protocol 16. Live verification
+This guide describes ahub 0.12.30 and control protocol 16. Live verification
 results and remaining prerequisites are recorded separately in [the smoke ledger](smoke.md).
 
 ## Agent-operated live verification
@@ -176,6 +176,48 @@ decisions and a never-ask permission mode require confirmation; delivery resolut
 status state counts and never fetches the board. Leaving restores
 the terminal and returning from panels replays the bounded stream buffer.
 
+Tasks and Queue selections follow the selected id across refreshes. If that row
+disappears, no replacement row inherits the action. Task actions also bind the
+row's `flowRevision` (its history length); queue actions bind the delivery
+revision. The id and revision in a row-started command cannot be edited. Peer,
+reason and the final role/action remain editable, and the confirmation names the
+validated result. An older hub without `flowRevision` refuses revision-bound task
+row actions instead of silently running them unchecked.
+
+In Tasks, `a` assigns the owner in ordinary open states and the reviewer in
+`in_review`; a waiting task says when assignment is a reservation. `u` unassigns
+the corresponding role, and `r` reviews only in `in_review`. In Queue, `r`
+prefills `discard` for a queued row and `retry` for a needs_review row, with the
+action still editable before confirmation. `completed` is never the default.
+Every resolution needs a reason. Queue `discard` removes queued originals or
+settles a needs_review receipt; it never cancels a task or native turn.
+
+`ahub task unassign <id> [--role owner|reviewer] [--revision N]` is the terminal
+equivalent. Owner removal is allowed in `proposed`, `in_progress` and
+`changes_requested`, returns active work to `proposed`, and clears any owner
+reservation. It is refused in `in_review`, `approved` and `backlog`. Reviewer
+removal retains the state, including `in_review`, and refuses to remove the human
+reviewer of PII work. No replacement is routed and no native process or external
+effect is rolled back. A person-unassigned task stays out of automatic owner
+offers across dependency release, planner-pull processing, release timers and
+restarts until an explicit assignment or reservation. The later unassign also
+fences planner undo, so undo and re-pull cannot restore the removed reservation.
+Former queued assignment or review requests are withdrawn without resolving
+uncertain deliveries, and the former agent loses current authority. A withdrawal
+notice uses delivery evidence or that peer's own accept/self-claim after the
+latest assignment; another owner's in-progress state or an earlier acceptance
+does not count. Withdrawing an unread queue alone sends none. If a later person
+assignment supersedes an escalation or offline relay, the stale success result
+and decision note are suppressed, but the former owner is still told the current
+owner and to stop working.
+
+`ahub task assign <id> <peer> [--role owner|reviewer] [--revision N]` uses a
+checked console operation when a revision is present. Without it, existing CLI
+behavior is unchanged. `ahub queue resolve ... [--revision N]` uses the supplied
+revision instead of a fresh show. Revision mismatches and superseded post-await
+publications fail without a board or delivery side effect; a reviewer-only change
+keeps a valid owner assignment but refreshes its reviewer content.
+
 The Tasks panel summarizes the whole public board with an approved/all fraction,
 a 20-cell ASCII bar and state counts. Proposed tasks with unapproved or missing
 `after` dependencies count as waiting; PII stubs count normally. Each task has a
@@ -388,9 +430,136 @@ The Stop hook acknowledgement is not a counted completion. The daemon checks the
 native transcript after the hook can return; missing or changed-session evidence
 stays unknown.
 
+## Pi with DGX and MLX
+
+Pi is optional. Install Pi separately and set `pi.enabled` to `true` in
+`.agenthub/config.json`. Set `pi.auto_start` to `true` to start it with the hub.
+Pi starts in its TUI by default; `ahub pi --headless`, or the start mode
+setting (`ahub settings set peers.pi.start_mode headless`), asks for the
+background peer instead. The project uses its existing OmniRoute connection for DGX;
+`pi.dgx_coding` and `pi.dgx_fast` select the gateway's configured model IDs.
+
+```bash
+ahub models setup       # prepare bounded Qwen3.5 4B MLX in an existing Ollama service
+ahub models start       # verify loopback Ollama/model readiness (no daemon spawn)
+ahub models status
+ahub pi --headless --backend auto
+ahub say @pi "Read the project and summarize the next small implementation task"
+ahub pi                # its TUI in this terminal; an idle headless session moves into it
+```
+
+The default routing template assigns implementation, bulk edits and tests to
+DGX, and summaries/triage to MLX. Pi and the existing local worker take priority
+before cloud peers; planning and final review stay with Claude/Codex. Existing
+projects keep their routing file, so add `pi` to the relevant `peers` lists and
+set `pi_backend = "dgx"` or `"mlx"` for each class. PII tasks remain local-worker
+only. `--backend dgx` or `--backend mlx` explicitly pins a Pi session's backend.
+
+Pi connects to an authenticated relay with model aliases `dgx/coding`,
+`dgx/fast`, and `mlx/fast`; upstream gateway credentials stay in the hub.
+Its managed tools use the existing path guards, shell sandbox and terminal
+approval flow. Keep `ahub console` open to approve write/edit/shell operations:
+a request nobody answers expires, and two in a row end Pi's turn.
+Tool-call receipts survive daemon restart; an interrupted operation with an
+unknown outcome must be reconciled before repeating it. Cancelling a Pi turn
+does not automatically hand its task to a cloud peer.
+
+The `mlx/fast` alias now defaults to an externally managed Ollama MLX backend.
+Install and start Ollama separately, with `OLLAMA_NO_CLOUD=1`,
+`OLLAMA_NUM_PARALLEL=1`, `OLLAMA_MAX_LOADED_MODELS=1`, and a finite
+`OLLAMA_KEEP_ALIVE` (five minutes is the tested setting). `models setup`
+prepares `agenthub-fast-mlx:4b-8k` from `qwen3.5:4b-mlx`, with an 8K total
+context and a 2K output cap. The relay budgets input separately at 6,000
+estimated tokens and serializes local requests across project hubs.
+
+`models status` distinguishes model availability from memory residency.
+`models stop` refuses to unload an externally managed Ollama model: other
+clients may be using it. Ollama owns idle eviction; stopping a hub never
+kills Ollama. The OpenAI compatibility endpoint does not enforce a request
+`keep_alive` field, so configure the server and verify its expiry readback.
+The relay can fall back to DGX before streaming starts as before. See the
+[Ollama migration procedure](#ollama-mlx-migration-issue-51)
+for existing Python runtime/configuration cleanup and rollback.
+
+A project has one managed Pi session owner. Mode changes require the agent to
+settle and preserve the session file. Before the first generation, a live source
+verified to be empty can instead retain its exact session ID without a file.
+Missing history from a nonempty session blocks handover. Protocol 9 adds Pi
+recovery metadata. Protocol 10, released in 0.7.0, adds durable delivery
+receipts and conservative queue recovery; it is verified live (see the
+[smoke checklist](smoke.md)).
+Older protocol hubs still require their matching CLI and an attended bootstrap.
+
+## Local dashboard
+
+With a running daemon, `ahub ui` opens a local dashboard for messages, peer states
+and queues, the task board, budget windows, pending approvals and this machine's
+benchmark runs. Use `ahub ui --no-open` to print a single-use link when the
+browser cannot be opened.
+Open the link within 60 seconds; the browser session lasts one hour.
+
+The dashboard can send console messages, propose and assign tasks, pause or resume
+peers, answer approvals, start a peer in its start mode and show the settings.
+An ordinary session changes the safe switches and lowers a mode to `ask`; the
+rest needs `ahub ui --settings` or `ahub settings` in a terminal. See
+[Settings](#settings-from-the-dashboard-and-the-terminal) and
+[Start modes](#start-modes-tui-by-default-headless-as-opt-in).
+Budget pauses still require the terminal override.
+Private envelopes and PII tasks stay redacted. Local-worker and Pi tool details and
+allow decisions stay in `ahub tail` / `ahub permit`; the page can deny them.
+No dashboard port is opened until requested. See [the session security model](security.md#local-dashboard-sessions-issue-6).
+
+## Multiple projects and worktrees
+
+Version 0.4.0 adds one independent hub per repository or Git worktree.
+Subdirectory commands resolve to that project; symlink aliases resolve to the same
+hub. Explicit selection works from any directory:
+
+```bash
+ahub --project /path/to/project-a init
+ahub --project /path/to/project-b init
+ahub --project /path/to/project-a up
+ahub --project /path/to/project-b up
+ahub projects
+ahub status --all
+ahub --project /path/to/project-a codex
+ahub ui --all
+```
+
+The unified dashboard lists registered roots and opens their boards, streams,
+messages, approvals and budgets. It can start hubs and stop a selected hub after
+confirmation. Its Start control opens a peer's TUI only through a terminal provider
+(`terminal.open` or Orca); without one, launch Claude/Codex TUIs from a terminal. The manager stays available
+when a project stops; `ahub ui --all --stop` stops only the manager. Existing
+`ahub ui` still opens the current project's dashboard.
+
+`ahub projects --json` returns machine-readable live status. Use a listed ID or a
+path with `--project`; the selector must precede the command. `ahub projects remove
+<id>` forgets a stopped registration without deleting project data. A moved root
+gets a new registration. Missing roots remain visible until removed.
+
+Runtime state stays in each project's `.agenthub/state/`. The machine registry is
+`~/.agenthub/registry.db`; existing `ports.json` allocations are imported once.
+`AGENTHUB_HOME` selects an isolated machine registry (also used by tests). An
+inherited state directory from a different project cannot redirect a new CLI
+invocation. Explicit custom state requires a matching project marker or the
+initialization pair `AGENTHUB_PROJECT_DIR` / `AGENTHUB_STATE_DIR`.
+
+Manager-started hubs use attended mode and project configuration, including
+credential-file references. They do not inherit the launching project's gateway
+URL/key overrides. Native memory remains shared according to claude-mem aliases;
+worktrees recall their parent and composite identity. A shared-alias notice does
+not mean that task boards or agent sessions are shared. Provider quota readings
+may describe the same account and should not be added across projects.
+
+Before upgrading an older hub, inspect the plan with the matching CLI.
+Incompatible or unverified processes are shown explicitly and are never killed by
+PID-name matching. See the operations guide and the
+[multi-project specification](specs/2026-09-19-multi-project-design.md).
+
 ## Install and start
 
-Use Bun 1.3 or newer. Install the released package and install its Claude
+Use Bun 1.4.2 or newer. Install the released package and install its Claude
 channel plugin:
 
 ```bash
@@ -472,8 +641,9 @@ does not list), needs its directory in `local.read_allow`, for example
 hub's tools: list a peer and it keeps only the capabilities named, from
 `propose` (`hub_task_propose`), `assign` (proposing with another peer as owner),
 `remember` (the `hub_remember` tool; the notes the hub itself keeps of done
-summaries and review verdicts are not gated) and `important` (`[IMPORTANT]`
-messages). For example `"capabilities": { "local": ["propose", "remember"] }`.
+summaries and review verdicts are not gated), `memory_correct` (propose a local correction candidate for person review), `memory_read`
+(`hub_memory_search`, `hub_memory_show`, `hub_memory_graph`) and `important`
+(`[IMPORTANT]` messages). For example `"capabilities": { "local": ["propose", "remember"] }`.
 A peer that is not listed keeps all of them, a listed peer whose value is not a
 list gets none, and an unknown capability name grants nothing; `hub.log` says
 so for each, and logs every refusal (`capabilities:`). A refused tool call says
@@ -523,8 +693,7 @@ resolves an uncertain delivery automatically. The same rule holds on every path
 assigns a task (#297): once the move is saved on the board, a failed delivery prints
 exactly one console notice ("the move is saved... delivery is not confirmed"), printed
 where the error is thrown, and the caller (a peer in its turn, or the CLI) still gets
-its error. Two exceptions, by construction: a move superseded while the assignment was being prepared, meaning a later history entry that moves or settles the task (another assignment, an unassign, the owner's accept, done, approval, close; the hub's quiet bookkeeping such as a late check result or a reviewer change does not supersede), is
-the caller's error as before, with no notice naming either owner; and a claim is its own hand-over, so its
+its error. Two exceptions, by construction: a move superseded while the assignment was being prepared, meaning a later history entry that moves or settles the task (another assignment, an unassign, the owner's accept, done, approval, close; the hub's quiet bookkeeping such as a late check result or a reviewer change does not supersede), returns the current task without a failed tool call and with no notice naming either owner; and a claim is its own hand-over, so its
 accepted write and line stay outside the delivery rule (its overlap and routing announcements to earlier
 owners are deliveries and share it). The repair is always
 to look for a queued or needs_review delivery with
@@ -735,7 +904,7 @@ ahub task label 12 reverted        # a later verdict (ok, regressed, reverted, i
 
 ## Hub memory
 
-The hub keeps its own memory in `~/.agenthub/memory/` beside claude-mem ([how it works](memory.md)): notes saved
+The hub opens the selected memory profile under `memoryHome()` (default `~/.agenthub/memory/`) beside claude-mem ([how it works](memory.md)): notes saved
 against an open task are short-term; when the task is approved its decisions, contracts and fails become long-term.
 Task briefs, session-start recall and `ahub ask` read it first, and the dashboard has a Memory section.
 
@@ -748,6 +917,20 @@ ahub memory forget 1a2b3c4d              # a person's; also promote, demote, sup
 
 `"memory": { "native": false }` in `.agenthub/config.json` turns it off for a project.
 
+The exact-pinned `@staix/agent-mem` 0.3.0 resolves `AMEM_HOME`, then `$AGENTHUB_HOME/memory`, then `~/.agenthub/memory`. An absent `M/profile.json` selects shared v1; an explicit generation selects `M/generations/G` with the package's readonly legacy bridge. All daemon memory consumers and the hub memory/goal CLI use that selected profile. Invalid metadata or a missing selected generation makes native memory unavailable while the bus and board continue; there is no fallback to legacy writes. Inspect the daemon's memory binding/availability before interpreting missing memory as an empty store.
+
+The daemon checks its selector at hub operation entry and before candidate/counter writes. It does not hot-switch handles or provide an atomic fence against selection changes during an in-flight core call. Quiesce consumers and close their handles before migration or selection changes; reopen through the supported session-preserving lifecycle afterward. Candidate/counter storage remains `M/candidates.db`, independent of `G`; `amem review` on a generation is still refused. Every running hub using this home needs an authenticated receipt: a matching ready binding, or a generation-capable unbound receipt (`disabled` when native memory is off, `unavailable` when opening failed) proving it holds no memory handle. An unbound daemon and zero running hubs are quiesced for memory; a stale bound handle, unreadable registry or unknown runtime is not ready. Existing JSON memory/goal results remain unchanged; the additive binding receipt belongs to daemon status, profile-check and the decay object. This source integration does not authorize installing a new runtime, migrating real memory, restarting sessions or claiming real-machine sync/capture receipts. Migration/deactivation and their limits belong to [agent-mem](https://github.com/STAIxBWLB/agent-mem); see [the hub profile contract](memory.md#selected-memory-profile).
+
+Run `ahub memory profile-check [--json]` from the person's terminal for the read-only preflight. It identifies live registry owners by signed process identity and authenticated daemon replies, then reports their loaded memory package and bound home/profile. The receipt names the current `AGENTHUB_HOME` registry scope; zero results establish no live daemon in that inventory, not system-wide process absence. Inventory and check separate custom registries too when they share `AMEM_HOME`. A missing or unreadable runtime receipt never counts as a different home or permission to migrate.
+
+Before real migration, first upgrade every hub sharing the home to 0.12.30. Obtain positive ready or unbound/quiesced receipts in every relevant registry; then quiesce consumers and close bound handles before changing the selector. A matching ready handle proves compatibility but is still an open handle. Verify synthetic cross-writes before the separately approved real migration, then reopen through the supported session-preserving lifecycle afterward. Merely installing this release does not authorize migration or provide live capture/device-sync evidence.
+
+Managed agents read through `hub_memory_search`, `hub_memory_show` and `hub_memory_graph`, with the server's project identity, the `memory_read` capability and current privacy screening. They cannot supply another project; private turns are refused. The tools bound UTF-8 input/output, screen before counts and truncation, and exclude their arguments/results from hub-managed capture. `hub_memory_correct` has its own `memory_correct` capability and records a screened correction candidate, not a note change. See [the complete memory contract](memory.md) for caps and refusal semantics.
+
+Review candidates and rendered/delivered/cited counters stay in machine-local `M/candidates.db`, outside sync, import, recall, briefs, ask and graph evidence. Public changes-requested reviews with unmet items may propose a fail candidate; missing cause/retry details stay unknown. Shared-v1 acceptance is a person's `amem review` action with its TTY/policy checks; selected generations still refuse that command. Read-time `(stale?)` hints and plan-fail advice never change stored rows or task authority. Structured fail notes are validated against 4000 UTF-8 bytes before screening or writes, with no silent truncation.
+
+Recall presentation omits generated task-approval outcome notes and shows only nonempty reasons from generated changes-requested notes; an ordinary decision that merely resembles a header stays visible. Contracts and fails remain eligible. Capped recall lines preserve memory headers and end at word boundaries, and one delivery deduplicates ids across restored/current prefaces and shared note lines. Stored notes and brief evidence are unchanged; platform recall retains its budget split.
+
 Between your machines, through a private git remote, with long-term tasks that span them:
 
 ```bash
@@ -1659,21 +1842,21 @@ section is what they run.
 
 Upgrade running projects with the target release's own coordinator. It accepts
 a running source on control protocol 9 (0.6.x), 10 (0.7.0 through 0.12.0),
-11 (0.12.1 and 0.12.2), 12 (0.12.3), 13 (0.12.4 through 0.12.15), 14 (0.12.16), 15 (0.12.17 through 0.12.19) or 16 (0.12.20 through 0.12.29), and only
+11 (0.12.1 and 0.12.2), 12 (0.12.3), 13 (0.12.4 through 0.12.15), 14 (0.12.16), 15 (0.12.17 through 0.12.19) or 16 (0.12.20 through 0.12.30), and only
 a target on its own protocol, so the target's coordinator fits every supported
 source and carries every recovery fix released up to it. Protocol 8 and older
 (0.5.x and earlier) are refused as `manual-bootstrap-required`. Run from the
 project directory, without replacing the global CLI first:
 
 ```bash
-bunx --package @staix/agent-hub@0.12.29 ahub upgrade --to 0.12.29 --dry-run
-bunx --package @staix/agent-hub@0.12.29 ahub upgrade --to 0.12.29 --yes
+bunx --package @staix/agent-hub@0.12.30 ahub upgrade --to 0.12.30 --dry-run
+bunx --package @staix/agent-hub@0.12.30 ahub upgrade --to 0.12.30 --yes
 ```
 
 | Running now | Coordinator to use |
 | --- | --- |
 | 0.6.x (protocol 9) | the target's, through `bunx` as above |
-| 0.7.0 through 0.12.0 (protocol 10), 0.12.1 and 0.12.2 (protocol 11), 0.12.3 (protocol 12), 0.12.4 through 0.12.15 (protocol 13), 0.12.16 (protocol 14), 0.12.17 through 0.12.19 (protocol 15), 0.12.20 through 0.12.29 (protocol 16) | the target's, through `bunx` as above |
+| 0.7.0 through 0.12.0 (protocol 10), 0.12.1 and 0.12.2 (protocol 11), 0.12.3 (protocol 12), 0.12.4 through 0.12.15 (protocol 13), 0.12.16 (protocol 14), 0.12.17 through 0.12.19 (protocol 15), 0.12.20 through 0.12.30 (protocol 16) | the target's, through `bunx` as above |
 | any supported source, with the installed CLI already at the target | `ahub upgrade` below, which is the same coordinator |
 | 0.5.x or earlier (protocol 8 and older) | not supported: bootstrap by hand with the matching CLI |
 
@@ -1705,14 +1888,14 @@ projects first:
 
 ```bash
 ahub restart --dry-run
-ahub upgrade --to 0.12.29 --dry-run
+ahub upgrade --to 0.12.30 --dry-run
 ```
 
 Apply only after reviewing the plan:
 
 ```bash
 ahub restart --yes
-ahub upgrade --to 0.12.29 --yes
+ahub upgrade --to 0.12.30 --yes
 ahub recovery status [<operation-id>]
 ahub recovery resume [<operation-id>]
 ahub recovery abort [<operation-id>]
@@ -1777,7 +1960,9 @@ release. The global CLI is promoted last.
 
 A lost commit or start reply is reconciled against the actual daemon identity,
 package digest, terminal binding, and phase receipt. An uncertain terminal
-creation is never repeated blindly. If Claude shows its development-channel confirmation screen, confirm it in
+creation is never repeated blindly. Recovery retains the exact-pinned first-party memory package with the preserved runtime, includes its identity and bytes in the digest, and refuses missing, symlinked or changed retained dependencies instead of resolving a mutable ancestor/global installation. It does not copy the full dependency tree.
+
+After creating a managed terminal, the coordinator saves its binding before waiting up to 90 seconds for authenticated attachment to the expected target hub and conversation. An idle terminal alone is not attachment proof. Timeout retains the terminal and its diagnostic receipt; resume waits on that same binding rather than opening a duplicate. The zero-turn Claude exception still applies only when no original transcript exists. If Claude shows its development-channel confirmation screen, confirm it in
 the captured terminal, then run `ahub recovery resume <operation-id>`; resume must not open a duplicate terminal.
 Kimi and local sessions may start fresh with preserved routing and task context.
 A Claude session that never persisted a transcript (zero turns) also starts fresh: