@staix/agent-hub 0.12.22 → 0.12.24

package/docs/bench.md

@@ -97,9 +97,10 @@ record reads `interrupted`.
 machine. Schema `agent-hub.bench/v1`:
 
 - `run` header: suite name and SHA-256 of the suite file, arm, fingerprint (the peers attached at the start, with the requested model and
-  permission mode where the hub's status reports them: today the model for Pi only; the SHA-256 of `routing.toml`; the
-  hub version), task order, repeats, the runner's process.
-- `attempt`: task id, repeat, outcome, error reason, verify exit code, hub task id, start, end, duration, and, for an
+  permission mode where the hub's status reports them: today the model for Pi only, and each peer's add-ons by name and
+  version as `ahub research addons` detects them (docs/research.md); the SHA-256 of `routing.toml`; the
+  hub version), the declared add-on `condition` when the arm has one, task order, repeats, the runner's process.
+- `attempt`: arm, task id, repeat, outcome, error reason, verify exit code, hub task id, start, end, duration, and, for an
   approved task, its #247 measures (tokens, wall and active time, review rounds, changes requested, failed checks, first
   pass, turns, files changed, models). They are read once the turns started since the task's proposal have ended (the
   runner waits only while their peers are still busy or paused, at most 10 minutes), so the turn that approved the task is
@@ -130,6 +131,30 @@ ms, tokens, wallMs, activeMs, reviewRounds, changesRequested, checkFailed, first
 The dashboard's Benchmarks section shows the latest runs with their progress (the attempt in progress, elapsed time and
 attempts left while one runs) and, per suite with two or more arms, a bar per arm and measure with its number as text.
 
+## Add-on arms (#248)
+
+`--addon <name>=on|off` (repeatable; names: `claude-mem`, `ponytail`, `ripwire`, `open-code-review`, `codex-plugin`,
+`dot-admit`) declares an arm's add-on state. Before anything is recorded or reset, the runner reads each attached peer's
+add-ons: an add-on declared `on` must be with at least one of them and one declared `off` with none; otherwise the run is
+refused and names the add-on. The header keeps the declaration as
+`condition.addons`, and every attempt names its arm. The study for one add-on is its arms with every add-on on, that one
+off, and all off, on the same suite, refs and peers, interleaved and with the task order randomized per run:
+
+```bash
+ahub bench run ../suites/s.json --arm all-on --addon claude-mem=on --addon ponytail=on --addon ripwire=on --repeat 5
+ahub bench run ../suites/s.json --arm ripwire-off --addon claude-mem=on --addon ponytail=on --addon ripwire=off --repeat 5
+ahub bench run ../suites/s.json --arm all-off --addon claude-mem=off --addon ponytail=off --addon ripwire=off --repeat 5
+ahub bench compare all-on ripwire-off all-off
+```
+
+`--memory off|claude-mem|native|both` declares which memory the arm's hub runs with (#258): `off` is neither
+claude-mem nor hub memory, `claude-mem` only claude-mem, `native` only hub memory, `both` both. The runner reads the
+project's `memory.enabled` and `memory.native` and refuses a mismatch before anything runs; restart the hub after
+changing them. The header keeps it as `condition.memory`.
+
+Switching an add-on is the person's setup between runs (a plugin's `enabledPlugins` entry, PATH); the runner only
+checks it. CooperBench (`docs/cooperbench.md`) keeps every add-on off by design, so add-on arms run here.
+
 ## A fair comparison
 
 - Change one thing per arm (a model, a permission mode, an add-on, a routing rule) and keep the suite, the refs and the

package/docs/cooperbench.md

@@ -127,6 +127,10 @@ Manifest v3 run directories (headless Pi/Qwen, `protocol: native-pq-v3` in every
 
 Contributions are a heuristic for possible loss, never a certificate: per agent and file, the identifiers and changed fragments its applied writes introduced (only a Claude tool call with a successful result, or a completed Codex patch, counts; a Write replaces the agent's earlier contribution and is not credited with what other agents wrote; a delete removes it; when a file is moved, every agent's contributions to it are checked at its new path) that the final tree lacks, a fragment counting as present anywhere in the file. A same-name overwrite shows as a lost fragment. Shell commands run during the task are not attributed and are counted under `coverage`, with a missing transcript or an unreadable file. Correctness comes from the official grader, for every arm.
 
+## Routing-time prediction preregistration (#109, 2026-10-11)
+
+The owner approved 120 controlled matched task pairs, 60 development and 60 held-out, comparing split execution of the same work units against both solo controls. The input/outcome, exclusion, unknown-value and reporting contract is [the routing evaluation preregistration](plans/2026-10-11-routing-evaluation-proposal.md). This freezes the design and sample budget, not the execution manifests: task-family/split membership, source/check hashes, native versions, profiles and warmup history must be sealed before the first scored attempt. No collection is authorized in the solo implementation session; automatic routing remains off. AC5, T3 and T4 remain open until their measured evidence and implementation gates pass.
+
 ## Preregistration (v2)
 
 Fixed before outcomes are collected (issue #110):

package/docs/data-policy.md

@@ -0,0 +1,36 @@
+# Private and read-only data paths (#259)
+
+- Optional shared or machine-local config declares `pii.paths` and `data.readonly`, each at most 64 project-relative paths/patterns of at most 200 characters. Entries name exact paths/subtrees or bounded globs, with no command execution. Empty or absent lists preserve existing behavior. These initial policies apply at daemon start; edit config deliberately and restart to refresh them.
+- Example: `{ "pii": { "paths": ["data/private"] }, "data": { "readonly": ["data/raw"] } }`.
+- Matching compares declared spellings and real targets, including symlink aliases and case variants. Unknown resolution conservatively matches an active policy. Paths outside the project cannot be selected as policy entries; managed tools retain their existing project boundary.
+
+# Private task flow
+
+- Declared refs, plan paths and section file anchors matching pii.paths receive a hard private signal before triage, board writes, notices or memory. The task remains local-only even if ordinary pattern-based PII routing is off.
+- Directory scopes containing a protected path are private too. Automatic facts omit configured private files even without an open private task. Public titles/views stay stubs, private envelopes stay private, and automatic notes skip memory. Newly accepted plans cannot silently add a private path to an ordinary task. Existing pattern screening and unknown verdict handling remain in force.
+- This governs declared task paths and the managed flow. It does not contain a same-user external shell or another native peer reading arbitrary files outside its declared task.
+
+# Read-only managed tools
+
+- Local/Pi read operations retain access. Managed write/edit refuse protected paths before asking for approval and re-check real targets after approval. With an active read-only policy, hardlinked write targets are refused because their identity cannot be attributed safely to one declared name.
+- Managed command execution (bash and git) becomes filesystem read-only whenever data.readonly is active. It keeps reads and stdout/stderr, allows /dev/null, and grants no project or temporary-directory writes. Commands that create output files or caches must instead return stdout or use managed write/edit for an unprotected output path. This restriction is required by the reproduced hardlink-alias bypass of path-only Seatbelt denies.
+- The command profile and runner must both use read-only mode; the runner refuses a profile that still carries a broad project write grant. No approval or permission mode overrides the data policy. Existing network and credential boundaries stay in force.
+- This policy controls managed local/Pi tools, not the owner or other native processes. The hub's state, receipts, explicitly configured completion checks and temporary command directory are maintained by the daemon outside the managed command.
+
+# Evidence boundary
+
+- Source tests cover bounded config/layers, real-path aliases, private flow before triage, public redaction, approval re-checks and managed hardlink refusal.
+- Native macOS command tests cover direct write, parent rename, existing/new hardlinks, temporary aliases and preserved reads. Linux runs the source guards and retains its existing no-sandbox/no-command behavior.
+- Real-account/model execution remains unverified; no live research study runs as part of this implementation. Profile converters and shadow repositories are later #259 slices.
+
+
+# Bounded glob policy
+
+- `*` matches any characters within one path segment, `?` matches one character, and a whole-segment `**` matches zero or more segments. Matching includes dot names and folds case consistently with the existing exact policy. A matched directory protects its subtree. Directory task scopes are private if they can contain a future matching descendant, even before a file exists.
+- Examples: `pii.paths = ["data/**/*.csv"]` and `data.readonly = ["data/raw-*/**"]`. Up to 16 wildcard characters per pattern. Absolute paths, parent traversal, bracket classes, braces, negation and mixed `**suffix` forms are refused. Backslashes remain literal in exact entries but are refused in glob entries; no escape syntax is interpreted.
+- Match both declared spelling and real target. Wildcard directory/file aliases are discovered from compatible prefixes, including symlink aliases to future targets. Discovery is refreshed per decision, with no stale cached expansion. It reads at most 4096 directory entries and traverses at most 32 levels. An unreadable/dangling/cyclic/out-of-project alias or an exhausted discovery bound conservatively protects rather than declaring a path public/writable. No discovered name or policy body is logged.
+- Managed local/Pi write/edit and private Tasks/facts use this same matcher. Existing hardlink refusal, post-approval recheck and filesystem-read-only command profile remain unchanged.
+- Claude's managed `ask-when-needed` hook receives `ask` for a write matching data.readonly. Reads and ordinary project writes retain their existing scoped decisions. The daemon evaluates policy locally only for the current managed PreToolUse ask-when-needed write grant and sends no pattern list to the hook. PostToolUse, unavailable/ask/never-ask modes and non-write tools perform no grant-policy discovery. Explicit native approval and `never-ask` remain the person's native authority; this is scoped auto-grant filtering, not a new Claude sandbox or containment claim.
+- The previous malformed-config fixture that refused every wildcard now refuses an unsupported bracket class; its rejection assertion is retained. New tests establish the deliberately added glob grammar, future paths, wildcard aliases/retargeting, private scopes, discovery failures and actual daemon hook replies. Native account/model consumption is unverified.
+
+- Hardlink identity refusal precedes path matching for managed writes, including an already protected original. This keeps the refusal stable across platform-specific real-path alias choices; read access and policy-off behavior remain unchanged.

package/docs/events.md

@@ -25,6 +25,9 @@ marked `private: true`, and PII tasks `pii: true`.
 | `progress` | `peer`, `task` (task id), `severity`, `spinning`, `exploring`, `production`: normalized tool activity dimensions for an open task; coverage differs by peer and no commands or task text are recorded |
 | `stuck` | `peer`, `task` (task id), `category` (`repetition`, `false_progress`, `drift`, `desperation`, `capability_gap`), `streak`, `latched`: an escalation verdict; it recommends considering reassignment and never reassigns automatically |
 | `capability` | `peer`, `state` (`verified` or `lost`), `via`: a peer's context path for facts |
+| `memory_brief` | `peer`, `task`, `native`, `fails`, `claudeMem`: what a task brief carried, as counts (#258, docs/memory.md) |
+| `hub_start` | `instance`: a hub run began, written once it holds its control port and before any peer can attach (a daemon that cannot bind writes none); every peer counts as detached until its next `state` event |
+| `tooling` | `peer`, `addons` (`{ name, version }` from a closed list, version null when unknown): the add-ons a peer works with, at each attach (#248, docs/research.md) |
 | `native_turn_end` | `peer`, `id` (an opaque hash that names the completed turn): the end of a Claude turn, recorded once the hub finds the turn its Stop hook reported completed in the native transcript (Codex's is its `turn_end`); quiescence evidence for an integration |
 | `supervision_turn` | `peer`, `turn` (the hub turn a supervision notice was delivered into, or `supervision-<uuid>` when none was open), `tokens` (when the adapter reported any for it), `ms` (from that turn's start, or from the delivery when none was open, to its native end): a completed native turn that received supervision, which `ahub report` counts; a failed delivery or turn, a peer that went offline or a changed native session records none |
 | `conduct` | `peer` (the conductor, or `user` when the console releases a conductor hold), `action`, `task` (when the action names or creates one), `target` (the peer an assignment, start, hold or release names): one action of the conductor that ran, the structured twin of the console's `conductor` notice. `action` is a tool name without its `hub_` prefix: a conductor tool (`status`, `task_show`, `task_assign`, `task_escalate`, `peer_start`, `peer_hold`, `peer_release`), or one of the conductor peer's own task tools, which are not conductor tools (`task_propose`, `task_accept`, `task_decline`, `task_done`, `review`, `checkpoint`, `remember`). The role-free reads and redirects (a task's owner or reviewer with `hub_task_show`, its proposer with `hub_task_assign`) record none, and neither does `hub_task_list` |
@@ -41,17 +44,21 @@ marked `private: true`, and PII tasks `pii: true`.
 | `task` | `id`, `event` (the board history event, e.g. `proposed`, `assigned`, `done`, `check failed`, `blocked`, `ready`), `by`, `state`, `owner`, `reviewer`, `class`, `pii`, and `reason` when the board recorded a move reason (`manual`, `budget`, `offline`, `idle`, `rejections`, `declined`, `inference_failed`, `delivery_failed`) |
 | `overlap` | `task`, `owner`, `others` (`task`, `owner`, `paths`, and `symbols` when plans name the same symbol; a name that matches a PII pattern is left out, so either list can be empty), the structured twin of the console notice |
 | `permission_mode` | `peer`, `from`, `to` (`ask`, `ask-when-needed`, `never-ask`): a person set a peer's permission mode (`from` equals `to` when it was already in force) or confirmed a never-ask default (issue #242) |
+| `settings` | `key` (a registry key such as `permission.kimi` or `routing.classes.implement.peers`), `from`, `to` (the value before and after: the one in force for a setting that applies at once, the stored one for a setting read at a start; a closed word, a boolean, a list of peer ids, a route id, or null for none), `source` (`dashboard`, `terminal`), and `undo: true` for an undo: a person changed a setting from the dashboard or `ahub settings` (issue #269). A mode change also writes its `permission_mode` event |
 | `permission` | `id`, `peer`, `event` (`requested`, then one of `answered`, `expired`, `cancelled`) and, on the closing event, `latencyMs`, `surface` (`console`, `dashboard`, `terminal`: where a person answered; absent when the hub closed the request) and `option` (the kind of the option chosen: `allow_once`, `allow_always`, `reject_once`, `reject_always`): one approval request relayed to the console and how it ended. `expired` is `approvals.timeout_s` without an answer. `cancelled` with a `surface` is a person's deny in the console or by `ahub permit <id> deny` (a deny on the dashboard is `answered` with a reject option); without one, the hub withdrew the request (its call or turn ended, the peer was stopped, or the hub is stopping). Never the title or the tool |
 | `pii_screen` | `task` (absent for a budget hand-off or a note not about a task), `item` (`task`, `summary`, `review note`, `handoff`, `note`), `label` (`pii`, `clear`), `source` (`regex`: a pattern matched and no call was made; `screen`; `unknown`: no verdict, handled as PII), `category` (`name`, `student_id`, `phone`, `address`, `grade`, `health`, `other`), `miss` (why there was no verdict: `too long`, `off campus`, `timeout`, `unreadable`, `failed`), `ms` (absent for `regex`): one PII screen verdict while `signals.pii_screen = "local"` (issue #198); never the text |
-| `context_pressure` | `peer`, `source` (`claude_statusline`, `codex_token_usage`), `measuredAt` (epoch ms of the reading), `used` (the fraction of the context window in use, 0 to 1), `window` (its size in tokens, or null): a fresh reading of a peer's native context reached `context.gate`. Recorded once per crossing, until a reading below the gate or a new native session rearms it, and not while the peer is paused or offline or the hub is in recovery or stopping |
+| `context_pressure` | `peer`, `source` (`claude_statusline`, `codex_token_usage`, `acp_usage_update`), `measuredAt` (epoch ms of the reading), `used` (the fraction of the context window in use, 0 to 1), `window` (its size in tokens, or null): a fresh reading of a peer's native context reached `context.gate`. Recorded once per crossing, until a reading below the gate or a new native session rearms it, and not while the peer is paused or offline or the hub is in recovery or stopping |
 | `quota` | `peer`, `windows` (`id`, `used`, `resetsAt`), `hard`, `measuredAt` (when the reading was taken, if not when it arrived: Claude's numbers come through a file) |
 | `conflict` | `peer`, `task` (its task in progress, when it had one), `other` (the other owner's open task), `owner`, `paths` (names that match a PII pattern left out, so it can be empty), `concurrent` (another peer worked during the turn), `turns` (the two turn ids, when two overlapping turns' snapshots both hold the change) |
 
 Token usage by adapter:
 
 - Kimi (ACP `usage_update`, and the usage a `session/prompt` result carries): recorded when it holds a checked
-  total or an input/output pair. The `{used, size}` shape Kimi sends is context occupancy and is not recorded
-  (issue #285 tracks showing Kimi's usage).
+  total or an input/output pair. The `{used, size}` shape Kimi sends is context occupancy: it is shown as the peer's
+  native context reading (source `acp_usage_update`, #285 phase 1) and no `tokens` event is written from it; Kimi's
+  consumption is not recorded yet (phase 2). The adapter accepts the update whenever it names the current session;
+  Kimi 2.1.1's source text emits it after the prompt resolves, when the peer may already be idle, and that order is
+  not yet observed live through the hub (docs/smoke.md).
 - Codex (app-server `thread/tokenUsage/updated`): recorded as the growth of the thread's running total, so
   compaction estimates, usage-limit refreshes and the replay to a reattaching connection add nothing. A thread
   started under the hub counts from zero; a resumed thread's first update is its history and only sets the

package/docs/gsd-collaboration-analysis.md

@@ -0,0 +1,48 @@
+# GSD-shaped collaboration in agent-hub (#252)
+
+Source review: 2026-10-11, agent-hub 5647038. Recommendation: preserve the default flow; offer a bounded gsd-lite checklist/dependency presentation through #257's opt-in lifecycle. Defer a bidirectional GSD artifact bridge until it has a separately reviewed import contract and measured value.
+
+## Evidence boundary
+
+This is source-based analysis, not a measured claim that GSD improves quality or cost. No matched default/GSD comparison or add-on arm ran in this solo implementation. Research records (#247, docs/research.md) store task outcomes, counts, tokens and timings, not task/plan text. The #251 bench infrastructure can compare configurations on a common suite, but infrastructure existence does not provide an effect estimate.
+
+The inspected local adapter is `/Users/yj.lee/.agents/skills/gsd-execute-phase/SKILL.md`, SHA-256 `b10610df4d9b55bdf39141cbf469525f1429cea4ae774dc4cd486520a62cae51`. Its installation revision was not recorded, so it is not asserted to equal an upstream release. Independently reviewed upstream [execute-phase command](https://github.com/gsd-build/get-shit-done/blob/bdcaab2c752d9a33a1a1ca9acf3a3c81fb991815/commands/gsd/execute-phase.md), [workflow](https://github.com/gsd-build/get-shit-done/blob/bdcaab2c752d9a33a1a1ca9acf3a3c81fb991815/get-shit-done/workflows/execute-phase.md) and [installer](https://github.com/gsd-build/get-shit-done/blob/bdcaab2c752d9a33a1a1ca9acf3a3c81fb991815/bin/install.js) at full commit `bdcaab2c752d9a33a1a1ca9acf3a3c81fb991815` establish Codex support, dependency waves and context handoff. Codex worktree isolation is explicitly refused by that workflow; support is not a blanket guarantee of runtime parity. Therefore the issue's older claim that non-Claude runtimes cannot use GSD is too broad: Codex integration exists. Kimi/Pi/local runtime coverage was not established. The skill was inspected as reference material; its delegation/autonomous workflow was not invoked.
+
+## Benefits and costs (qualitative)
+
+| GSD idea | Current hub mechanism | Potential value | Cost or failure boundary |
+| --- | --- | --- | --- |
+| Shared written plan | Issue spec plus Task.plan signatures/paths/insertion points | More consistent implementation scope and fewer context rediscoveries | Copying the issue into an independently editable PLAN creates spec drift; derive it and preserve issue precedence |
+| Dependency waves | Tasks.after waits for approval; overlap/cohort guards already protect integration | Expose safe concurrency and explain why work waits | A whole-wave barrier can idle independent successors; use exact predecessor edges, not an unconditional global wave barrier |
+| Goal-backward verification | sendReview already renders a per-task checklist | Catch phase-level omissions that individually passing tasks miss | A checklist is not evidence; require exact artifacts/check results and permit inconclusive findings |
+| Durable STATE/HANDOFF | Board/history, receipts, events, #247 records | Recover human understanding of purpose and remaining work | A second writable state authority loses or duplicates work; board remains authoritative, exports are derived |
+| Codebase map/context packets | Plans, refs, briefs, facts and native context readings | Reduce repeated discovery across peers | Maps go stale; source hashes and bounded context are needed; privacy/PII rules remain at existing boundaries |
+| Atomic per-task commits | Repository branch/PR conventions | Reviewable rollback and clearer scope | Additional commits are not proof of independent review; immutable head and CI gates still belong to SDLC |
+
+These are hypotheses. There are no measured first-pass, rework, regression, token, wall-time or operator-overhead differences reported here.
+
+## Mapping and authority
+
+- A phase maps to an issue/release slice, not a replacement spec. Its tasks are board tasks with explicit after edges; runtime-specific executors are ordinary owners under existing roles and capabilities.
+- Verification is a reviewer task with the phase's deliverable checklist. Task approval and phase verification remain distinct; a failed phase check does not silently erase completed task history.
+- STATE/HANDOFF are board-derived readbacks with artifact ids, current heads, pending gates and next actors. Import is a validated proposal, never an overwrite of accepted work.
+- GSD's workspace-pinned no-auto-advance and branch-first rules are retained. This comparison grants no extra command, permission, tool, sandbox, native restart or coordinator authority.
+- PII stays local/on campus, untrusted text is sanitized by existing output boundaries, and model-written guidance is not evidence merely because it is in a plan.
+
+## Recommended delivery contract (specified before implementation)
+
+The initial option is gsd-lite, off by default, implemented with #257's lifecycle rather than a second scheduler:
+
+- `workflow: none | gsd-lite` is a data choice, with none the default. It changes guidance/presentation only unless SDLC enforcement is separately selected.
+- Planner input is a bounded list of task ids and predecessor ids. It resolves to exact existing after edges, validates acyclic dependencies, preserves accepted owners/reservations and rejects private text on cloud surfaces. No model-generated wave bypasses Tasks.
+- A phase reviewer checklist stores criterion ids and evidence refs. The reviewer may pass, request changes or mark an item unverified; the parent slice is not complete while a required item remains unverified.
+- route explain, console and dashboard show the active workflow and blocking predecessor/verification gates from the same data; defaults remain unchanged.
+- No extra STATE/PLAN/HANDOFF authority is introduced. Explicit exports contain safe derived state and source hashes. No auto-advance or autonomous merge/release.
+
+This bounded option is covered by a dated amendment to #257 before code. A full `workflow: gsd` bridge is not recommended for implementation yet: it needs bounded import size, source/phase identity, idempotency, conflict handling, authority and PII rules defined in a separate contract. That distinction prevents calling a partial bridge done.
+
+## Measurement plan
+
+Use #251 on the same sealed suite, native/model/effort profiles, role set, tools, permission modes and resource limits. Compare default versus gsd-lite checklist/dependency presentation. Preregister the task-family split and attempt/token/wall-time budget; include failed/time-limited attempts, abstentions and operator interventions. Report approved-task rate, first-pass rate, rework/regressions, observed conflicts/idle time and normalized token/time measures with family-cluster intervals. Missing activity or provider costs stay unknown. #248 separately measures add-ons; they are not credited to the workflow without their own controlled condition.
+
+No measurement was run here. AC1 is answered qualitatively and AC2 has the bounded #257 contract; #252 stays open for the built option and AC3 comparison. Native multi-agent research is outside this turn's solo/no-ahub execution.

package/docs/memory.md

@@ -0,0 +1,231 @@
+# Hub memory
+
+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).
+
+## Turning it on and off
+
+On with any project config (`.agenthub/config.json`); `"memory": { "native": false }` turns it off for a project.
+`memory.short_ttl_days` (default 14, a whole number from 1 to 3650; anything else fails the config) sets how long
+short-term entries live after their task is approved, and `memory.sync_interval_min` (default 10, 0 off, at most 1440) how often a running
+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).
+
+## What gets written
+
+- `hub_remember` from any peer or `ahub remember`, after the existing checks: a note about a PII task, or one matching a
+  PII pattern, is refused; the PII screen (#198) must clear it; a note that looks like it holds a secret (a private key,
+  a cloud or GitHub token, `password: ...`) is refused.
+- The hub's own notes on a task: the done summary (finding), the review verdict and an escalation (decision), with the
+  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.
+
+- 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.
+
+## Long-term tasks
+
+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:
+
+| `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) |
+
+- **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.
+- **Links**: a peer joins its own board task to one of this project's long-term tasks with
+  `hub_task_propose(..., goal: "<id>")`; a person links any board task of the project to any long-term task with
+  `ahub goal link <id> <task>` (through the running hub, so the board task is checked). Nothing about a PII task is linked.
+- **Lease**: while a linked board task is in progress on this machine's hub, the hub holds the long-term task's lease
+  (default 4 hours, renewed past half its time). It looks at every in-progress task at start, every 10 minutes, when
+  a task changes on the board and when a person links one, so a task worked on for hours keeps its lease. It never takes a lease another machine holds: the console says who
+  holds it, and a person takes it over with `ahub goal take <id> --force`, which voids every earlier claim. A lease that
+  expired is free for anyone.
+- **Conflicts**: sync is eventually consistent, so a lease is advisory. Two machines that claim inside one sync window
+  both stand: the earlier claim holds and the other shows as a conflict everywhere (status, dashboard, `ahub goal`)
+  until a person settles it with `--force`. There is no consensus; a broker would make it a real lock if concurrent
+  work across machines ever needs one.
+- **Where it shows**: at hub start (a console line per open long-term task of the project), in `ahub status`, in
+  `ahub goal list`, on the dashboard's Long-term tasks tab, and leading the session-start recall. Briefs bring along
+  the entries of the long-term task's other board tasks.
+
+```bash
+ahub goal new "native memory" --milestone "phase 1" --milestone "phase 2"   # a person's
+ahub goal link 1a2b3c4d 12
+ahub goal                                  # open long-term tasks, their state and lease
+ahub goal show 1a2b3c4d
+ahub goal take 1a2b3c4d [--force]
+ahub goal state 1a2b3c4d blocked
+ahub goal done 1a2b3c4d
+```
+
+## Machine sync
+
+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.
+
+```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.
+
+## Reading it
+
+- **Task briefs**: when a task is handed to an owner, its brief lists hub memory first (entries one or two hops from
+  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.
+- **`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):
+
+```bash
+ahub memory                              # this project's entries, newest first, with tier counts
+ahub memory list --tier long --kind fail --peer codex --since 2026-10-01 --json
+ahub memory search parser quoting        # every word must match the title, text or nodes
+ahub memory show 1a2b3c4d                # one entry with provenance and edges (this project's or a shared one)
+ahub memory graph 1a2b3c4d --hops 2      # its neighbourhood as edges, a person's (labels are unscreened); also a node: path:src/csv.ts
+```
+
+- **The dashboard** has a Memory section: short- and long-term tabs, search, filters by kind, peer, machine and time,
+  the list of entries, and for a selected entry or node its neighbourhood (one or two hops, at most 200 nodes) as an
+  inline SVG drawn in the page with the same edges as a text list, and its detail with provenance. It is read-only and
+  stays inside the page's content security policy: no requests other than the dashboard's own snapshot.
+
+## Changing it
+
+`list`, `search` and `show` may run in agent shells, so they leave out notes that match the project's current PII
+patterns or are about a path its `pii.paths` makes private (a shared note was accepted under another project's patterns) and say how many; the dashboard shows a person
+everything. A person's, from a terminal (agent shells are refused):
+
+```bash
+ahub memory promote 1a2b3c4d             # a short-term entry gets a long-term copy
+ahub memory demote 1a2b3c4d              # a long-term entry becomes short-term and expires
+ahub memory forget 1a2b3c4d              # gone from the index here, and on other machines once synced
+ahub memory supersede <old> <new>        # the old one is dropped from briefs and recall
+ahub memory rebuild
+```
+
+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.
+
+## Importing from claude-mem
+
+`ahub memory import claude-mem [--db <path>] [--limit N]` (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 (claude-mem files them under the repository's own name; a superproject's
+notes stay out, and two unrelated repositories with one name share it). Model answers from `ahub ask --remember`, text
+matching a PII pattern, text about a path the project's `pii.paths` makes private and secret-looking text are skipped. An
+imported note is placed in the graph by the paths and symbols in its text (claude-mem keeps no task proposal time).
+claude-mem's database is opened read-only and never changed; an observation always maps to the same entry, on any
+machine, so importing again adds nothing.
+
+## Measuring it
+
+Whether hub memory helps is measured, not assumed (#258 AC11, with #248):
+
+- Each task brief writes a `memory_brief` event with counts only (hub-memory items, fails among them, claude-mem
+  items); research records keep `briefs` (`delivered`, `withFail`), and `ahub research` splits approved tasks into
+  "a fail note in its brief", "brief without a fail note" and "no brief recorded" (first pass, rework, check failures).
+- `ahub bench run --memory off|claude-mem|native|both` declares an arm's memory and refuses a hub that runs with other
+  settings; compare the arms with `ahub bench compare`.
+- Whether an agent retried an approach a fail note had ruled out cannot be read from ids and counts. A task whose brief
+  carried a fail note and was still sent back or failed a check is a candidate, to read by hand.
+
+## Privacy
+
+- 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.