@staix/agent-hub 0.34.0 → 0.35.0

package/docs/design/adapters.md

@@ -79,6 +79,18 @@ Older daemons retain their existing close-and-retry standby behavior. An ordinar
 owner departure may release an eligible standby through normal claim admission;
 a standby never evicts a live owner without the person's takeover operation.
 
+The detailed status the console reads also names the current owner (#1310), so it is never
+inferred from standby rows, process start times or attach order. `ownerAttachment` holds the
+current socket's bounded `ownerPid` when it reported one, `attachedAt` (when the asynchronous
+attach completed, not the earlier hello), and `nativeSessionId` only after the host bound a native
+session through its verified native-facts path and only when it is a short plain token. It is
+absent while a newer hello is claiming, while offline, and after a detach, roster removal or stop,
+and a new attach replaces every field in one step, so a previous owner's pid, time or native
+session never sits beside the new socket. It is display metadata, never authentication, delivery,
+takeover or permission evidence. It carries no environment, argv, cwd, credential, prompt, title
+or text, adds no event, log or memory payload, and is withheld from `status.json` and every
+non-console reader. The field is additive and optional; no control protocol version changes.
+
 ## Accepted channel delivery settlement (#1172)
 
 Only an attached push channel opts into explicit disposition of its own accepted delivery. An `accepted` receipt acknowledges that the notification was accepted by the channel transport; it is not a native handling or task-completion signal. The host reads `bus.accepted_settle_ms` from accepted configuration on its existing maintenance sweep, defaulting to ten minutes. A row that remains unconfirmed becomes `needs_review` with no replay. `hub_inbox` returns bounded id/revision metadata for the channel's accepted and held rows, including when an accepted push prevents the pull itself. The plugin renders that metadata and avoids both an empty-inbox claim and polling advice while there is an actionable row. Important, task and review timeouts produce one durable status-kind, status-priority conductor message containing ids only when the existing `conductor.feed` policy is on; `feed: off` remains an opt-out. Pull-only sessions do not gain the explicit accepted-disposition port.
@@ -89,16 +101,104 @@ Permission modes control whether native actions prompt; they do not widen a sand
 
 When the hub starts a child, the host constructs its environment, binds its launch and generation, and owns its process-group lifecycle. Stop and recovery require current evidence for the process actually started; a PID, adapter label, successful start call, or stale session record is not enough. This keeps teardown from signaling a person's unrelated process and prevents a late native callback from acquiring a replaced session's authority ([#115](https://github.com/STAIxBWLB/agent-hub/issues/115), [#625](https://github.com/STAIxBWLB/agent-hub/issues/625)).
 
+Fresh Kimi reviews keep the complete synchronous isolation fence before spawn and
+at verdict/task-MCP authority boundaries. Periodic full checks use one review-owned
+worker with expected paths and fingerprints, no serialized task text or inherited
+environment, and boolean replies. A serialized 100 ms absolute cadence coalesces
+missed ticks without overlapping checks or adding a fixed delay after a slow check.
+Worker results cannot grant or restore authority. Revocation fences the exact
+child/review sequence; worker termination and join precede private-profile removal
+and confirmed input cleanup, including failed native teardown. An unconfirmed join
+retains ownership and the profile for an explicit stop retry ([#1284](https://github.com/STAIxBWLB/agent-hub/issues/1284)).
+
 Permission decisions are bound to the authenticated caller and current session. A hub CLI call inside an agent session acts as that peer, not as the person; role and task checks still apply at each tool boundary. Permission modes are person-controlled, and a conductor role does not grant them. This avoids turning a received message into user consent ([#193](https://github.com/STAIxBWLB/agent-hub/issues/193), [#242](https://github.com/STAIxBWLB/agent-hub/issues/242)).
 
 ## Model, account, and memory boundaries
 
-Subscription-based native CLIs keep their own account authentication; those credentials are not pooled through the hub. Hub-owned inference, including internal summaries and local-worker model calls, uses the in-process model route and OmniRoute provider boundary. Prompt text may inform configured routing, but it cannot grant credential access or replace host routing policy. This separates native subscription identity from hub service credentials ([#553](https://github.com/STAIxBWLB/agent-hub/issues/553)).
+Subscription-based native CLIs keep their own account authentication; those credentials are not pooled through the hub. Hub-owned inference, including internal summaries and local-worker model calls, uses the in-process model route and OmniRoute provider boundary. Prompt text may inform configured routing, but it cannot grant credential access or replace host routing policy. The optional local-worker adec consumer (#554) releases only bounded host-screened evidence, after campus/privacy and observer admission; native account, TUI, reviewer and task-assignment authority are unchanged. Shadow preserves the gateway model/effort and conversation; enforcement is refused at configuration load and no pair is applied. An explicit live model override bypasses the decision service. Current board/turn privacy and observer authority fence the optional request across waits and its proposal before telemetry; an authority change refuses the stale turn, and the refusal is not converted into a fixed-model fallback. There is no new gateway or native turn/spawn effort path. This separates native subscription identity from hub service credentials ([#553](https://github.com/STAIxBWLB/agent-hub/issues/553)).
 
 The PII screen is distinct from ordinary optional inference. It may use an on-device model; a gateway screen requires positive on-campus admission and `onCampusOnly`. If no allowed path returns a closed `clear` or PII verdict before the deadline, the result is unknown and handled as private. This keeps network and model uncertainty from becoming a disclosure ([#198](https://github.com/STAIxBWLB/agent-hub/issues/198)).
 
 Runtime memory capture and recall use the in-process `@staix/agent-mem` package, screened and invoked by host integration. claude-mem is off by default and import-only; there is no worker HTTP or model-summary path in the runtime. This avoids a parallel capture route with different privacy checks ([#752](https://github.com/STAIxBWLB/agent-hub/issues/752), [agent-mem#13](https://github.com/STAIxBWLB/agent-mem/issues/13)).
 
+## Person-owned live model selection (#1317)
+
+A person may store a per-peer model override in `hub.db` with `ahub model set`,
+clear it with `ahub model clear`, or inspect it with `ahub model list`. The CLI
+uses the settings command's identity boundary, but all model subcommands are
+person-only, including list. Dashboard changes use the existing person settings
+session and preview/confirm flow. No hub tool, conductor role or agent shell
+receives this authority. Provider, account, native home and executable changes
+remain on their existing machine-local configuration paths.
+
+The host stores desired state independently of an active turn. A model selection
+is captured once at the next supported turn/review boundary and stays unchanged
+through steering and local tool rounds. Captured application callbacks bind the
+exact adapter owner and turn; they cannot mark a newer desired revision applied.
+Two changes before a turn leave the last desired value. Status distinguishes the
+effective selection, its source, a pending next-turn value and unsupported live
+selection; a desired row alone is never evidence that a native model accepted it.
+The precedence is override, instance model, launch model, then native default,
+where the surface already supports that source. An unknown native default stays
+unknown rather than becoming an invented model id.
+
+Claude headless implementers select `--model` per spawned turn; codex-review
+selects `-m` per isolated review spawn. Supported Codex app-server `turn/start`
+requests carry `model` only for an override, alongside the existing permission
+policy. Both hub-delivered and client-forwarded app-server `turn/start` paths
+support it, but an explicit client model (for example the person's native
+`/model` choice) wins and is never rewritten. The app-server retains a
+`turn/start` model as its thread default. Clearing the hub override returns
+selection to that current native default; it does not reconstruct an earlier
+thread model. Native client acceptance does not certify a conflicting hub
+override as applied. Raw or pull-only `WsPeer` TUI attachments remain unsupported.
+When clear retains an acknowledged former override as the thread default,
+status labels its source `native thread default (was override)`. A rejected
+start retires its unused capture so a later start can sample a corrected choice;
+an older rejection cannot retire a newer accepted or pending start.
+`turn/steer` never acquires a model field. Local uses the existing direct
+OmniRoute model path for an explicit override while retaining budget, campus,
+observer and generation guards. Pi reuses its model-selection path at the next
+turn and retains a separate baseline so clear can restore normal selection.
+Existing no-override behavior and native permission/isolation proofs stay intact.
+
+Live ACP selection requires two independent facts: the existing native admission
+and an exact-version model-free setter receipt. Qwen and Jcode compatibility
+admission includes the person's existing exact-version trust; Kimi headless uses
+its existing native-identity admission, independently of Kimi reviewer isolation
+compatibility. Only Kimi Code CLI 2.5.2 headless is currently enabled, through
+`session/set_config_option` with `configId: model` and the
+[model-free setter receipt](../verification/2026-11-08-kimi-252-model-setter-1317.md).
+Qwen remains unavailable because its native clear fixture observed A/B/B after
+ACKs for B then A. Jcode headless A/B/A passed, but its shared-TUI turn fence
+across failover remains unqualified; its production setter stays unavailable. A native TUI or external adapter cannot acquire a setter from an
+advertisement or a registry label.
+
+The host captures one selection before awaiting a setter, validates bounded
+current-session model choices and owned process identity, then sends the prompt.
+Setter acknowledgement and model/config notifications are not prompt admission:
+only current prompt activity or successful completion acknowledges application.
+An unanswered setter leaves native selection unknown and takes the peer offline
+through its owned stop path. Trust revocation is rechecked before the prompt.
+Clear restores the validated pre-override session baseline, with instance and
+launch precedence retained; status does not expose a pending setter target as
+that baseline. Unsupported no-override delivery retains its ordinary behavior;
+a retained override instead refuses before a prompt until the person clears it
+or starts a supported owner.
+
+Fresh reviewer variants explicitly strip inherited model capability. Only an
+explicit per-spawn capability, such as codex-review, receives a model getter;
+a long-lived ACP policy never enables the reviewer print path. Unsupported
+surfaces refuse a live set with a cause and `ahub restart <peer>` as the next
+step, without storing a newly refused override or restarting anything.
+
+Overrides survive daemon restart and are cleared by runtime reset. Retained
+state must remain protected by recovery feature/integrity admission. Model ids
+use the existing #844 bounded token rule, with no spaces or leading dash.
+`model_change` records only peer, previous/new ids, person surface and a next-turn
+boundary, never prompts or credentials. A future native turn id is not invented;
+`appliesFrom: next_turn` and an existing `afterTurn` identify the boundary.
+
 ## Compatibility and external modules
 
 Native CLI compatibility is centralized in `compat.ts`. Each gated operation asks that policy for a verified, in-contract, person-trusted, or refused result; person trust for one exact version does not skip a separate isolation or runtime proof. This lets upstream versions change without turning an untested protocol assumption into support ([#691](https://github.com/STAIxBWLB/agent-hub/issues/691)).
@@ -107,7 +207,9 @@ External adapter modules are an explicit, person-owned, machine-local opt-in. Th
 
 `questionWaitMs` (#1053) is the time a `hub_ask` call waits for the person before it answers `pending`. It is a fixed-builtin field like `title`: `assertNativeCapabilityScope` refuses it on a configured or external definition, and the person overrides it per kind with `questions.wait_ms.<kind>`, never the caller. MCP peers carry 45 s, Pi and the local worker 300 s, provisional until the live timeout measurements of #1053 T1.
 
-`settle` (#1054) is the code-verified signal that ends a peer's logical run, so the hub can create a completion for a run a person started. It is a fixed-builtin field like `questionWaitMs`: `assertNativeCapabilityScope` refuses it on a configured or external definition. **Owner decision 2026-11-04 (issue #1054):** completions exist only for adapters whose signal the T1 audit verified in code. Claude's TUI (`native-stop`: the transcript-verified Stop, never a lost channel or watchdog) and headless implementer, Codex (`turn-completed`), Pi (`agent-settled`, its own event: the `agent_end` plus retry/compaction fallback is not implemented), the local worker (`route-outcome`), ACP Kimi and Jcode headless (`prompt-response`) and the Qwen TUI (`message-stop`) declare one. **Absent means no completions:** Kimi in its own TUI (pull-only, no signal), agy (its declared `native-hook` signal is not verified end to end) and phase-2 person-typed Codex turns declare none, and the daemon starts no run for a peer attached pull-only. agy joins after a live receipt verifies its Stop readback and completion row; Codex person-typed turns after an origin receipt. The settle rule, outcomes and restart reconstruction live in `src/hub/completions.ts` and `src/hub/completions-store.ts`; a run settles only when the adapter signal fired AND no queued continuation, open permission or question, owned child, running check or held delivery remains.
+`settle` (#1054) is the code-verified signal that ends a peer's logical run, so the hub can create a completion for a run a person started. It is a fixed-builtin field like `questionWaitMs`: `assertNativeCapabilityScope` refuses it on a configured or external definition. **Owner decision 2026-11-04 (issue #1054):** completions exist only for adapters whose signal the T1 audit verified in code. Claude's TUI (`native-stop`: the transcript-verified Stop, never a lost channel or watchdog) and headless implementer, Codex (`turn-completed`), Pi (`agent-settled`, its own event: the `agent_end` plus retry/compaction fallback is not implemented), the local worker (`route-outcome`), ACP Kimi and Jcode headless (`prompt-response`) and the Qwen TUI (`message-stop`) declare one. **Absent means no completions:** agy (its declared `native-hook` signal is not verified end to end) and phase-2 person-typed Codex turns declare none, and an unattached pull-only peer starts no run. agy joins after a live receipt verifies its Stop readback and completion row; Codex person-typed turns after an origin receipt. The settle rule, outcomes and restart reconstruction live in `src/hub/completions.ts` and `src/hub/completions-store.ts`; a run settles only when the adapter signal fired AND no queued continuation, open permission or question, owned child, running check or held delivery remains.
+
+Kimi 2.5.2's own TUI also earns completions, but only through the `ahub kimi` launcher's ephemeral `native_hook_launch` and local plugin (#1282). The plugin record binds the launch to its owner pid and process signature. A different launch may replace it only when that owner is proven gone; an active or unknown owner, including one from another project sharing the native home, is left unchanged. Replacement and cleanup share one fail-closed lock per native home, with no automatic stale-lock deletion. If begin or setup fails, the launcher reports the cause and starts the plain TUI without completion receipts. Quiet background/final-turn re-reads back off from 250 ms to 1 s, and the 2 s Stop deadline also arms them. A hook is a candidate observation, never proof. The daemon admits only the exact `kimi-tui` compat version and binds the observation to daemon, launch, native home, native session, project and current socket generation. The transcript's `turn.prompt` supplies the origin and turn id; its final `turn.ended` supplies the outcome. `prompt.completed` and `prompt.aborted`, when present, must agree with that turn; a notification may omit both id forms, so the native notification id or turn id is the fallback identity. A blocked Stop has no final row, so it cannot settle. StopFailure needs `failed`, Interrupt stays quiet with no result, and launcher loss or daemon reconstruction creates at most one `interrupted`. Every native-person result is private because the hook path cannot prove it is public. Headless ACP keeps `prompt-response`; an unverified TUI version or a launch without these readbacks keeps the old no-completion behavior. Native background task files supply the count or an explicit unknown; work or an unreadable inventory never settles. A 250 ms re-read covers missing TaskStarted/Notification hooks without turning elapsed time into evidence. No prompt, answer, error, task command or title reaches completion rows, events, logs or memory. The exact-version receipt is `docs/verification/2026-11-08-kimi-tui-completion-1282.md`.
 
 ## Session title slots
 
@@ -182,3 +284,9 @@ When a quote-bearing review reaches a peer without a stable native session ID, t
 ## Local review turns (#1056)
 
 The local worker binds review observer exclusion to its actual input envelopes before awaiting model or tool work. An anchored `hub_review` submission latches that exclusion for the rest of the batch/turn, including sibling and later tool calls. While latched, `hub_remember` and `hub_task_propose` are refused before reaching the host task tools; the caller can retry them in a later ordinary turn. Such turns do not call capture, commit review messages into later model history, or put provider error text and partial model text in failure logs. A later ordinary local turn resumes ordinary history and capture without inheriting the review payload. This is distinct from the PII policy: a public review package retains ordinary task authority and does not acquire an on-campus-only model route. Vendor-native histories remain owned by their adapters; the hub's current-turn and named-parent observer provenance is described in [the bus contract](bus.md#review-observer-provenance-1056).
+
+## Headless Record boundaries (#1320)
+
+Only a host-owned getter supplies the imported agent-mem instruction at an admitted headless turn boundary, after owned input and busy state exist and before the native prompt/model request. Multi-call local turns keep one fixed prompt. Native-client prompts, steer, Claude hooks and isolated reviewers keep their separate surfaces. A getter failure omits optional Record guidance and does not change ordinary routing. The production getter reads the public `recordsEnabled(activeHome, executionCwd)` accessor from the exact-pinned amem package; either machine or repository false disables the optional Record path. Its boolean revision is not a privacy-policy fingerprint: current package and hub screens are rechecked separately before effects.
+
+Model final output uses a host-only final-answer callback distinct from explicit send tools and diagnostic messages. Only normal completion can append Record rows; partial output is stripped for sharing without certifying a settled record. Capture binds immutable owner, turn, session/generation, execution cwd, profile and policy identity. Replacement, exclusion or unsafe steering revokes the frame before any later append. This grants no task, permission, native consumption or model acceptance authority.

package/docs/design/agent-hub-architecture.md

@@ -90,14 +90,76 @@ returns an ids-only receipt and excludes its arguments/results from capture.
 Its T1 authorization, revision and recovery boundaries are defined in
 [the task-board contract](task-board.md#claim-evidence-records-931-t1).
 
+## Bounded visual attachments (#1058)
+
+Bounded visual attachments (#1058) are local project records in `hub.db`, separate
+from task transitions and delivery receipts. The hub validates and privacy-screens
+the exact acon `VisualPayload` shape; peers receive only a sanitized stub with
+`refs.visual`, and explicitly request the source through a guarded read. acon owns
+rendering and its sandbox; the standalone dashboard uses text/source fallback.
+The hub imports contract types only, with no renderer or new runtime dependency.
+Image bytes use the existing guarded deliverable reader and current hash/policy
+checks; console asset identifiers bind their originating project and instance.
+Raw visual tool arguments/results never enter observer capture, even on refusal.
+The unchanged acon shape has additional hub admission ceilings: 1 MiB serialized
+payload; UTF-8 bytes Mermaid source 20 KiB, title 300, caption 2000, alt 1000,
+text side 20 KiB, option
+summary 4000, each pro/con 2000, table cell 4000, key 128, path 4096 and asset
+reference 256. These are hub limits, not a claim that acon imposes each limit;
+validation refuses rather than truncates. acon counts Mermaid UTF-16 code units
+and leaves captions unbounded, while the hub counts UTF-8 bytes. All 42 published
+acon 0.1.7 visual cases are consumed directly; six named valid-acon cases are
+rejected only by these stricter source/caption/asset-ID ceilings. Historical
+hub-owned cases remain extra coverage, not a substitute for the shared fixture.
+
+Periodic dashboard snapshots and task lists project bounded, screened metadata
+only; they do not deserialize or screen complete visual payloads. Explicit show
+and asset requests perform the full current-policy checks. A missing image does
+not erase its visual's public explanation; asset existence and hash validation
+belong to the guarded asset read. Non-sensitive refusals identify recovery,
+authority, concurrent change or unavailable screening and their repair action;
+sensitive privacy refusals keep a uniform message.
+
+Publication does a non-consuming rate check before model screening or image
+reads and still consumes admission once immediately before publication. Visuals
+are explanatory output, not task progress for no-write detection.
+Held controlled recovery compares retained visual integrity before startup
+retention pruning; startup, periodic and tool pruning all wait until both the
+recovery transaction and bus recovery hold are clear.
+
 ## Models and memory
 
-Peer selection, hub-owned model routing, and provider access are distinct layers. Task routing chooses a peer; the in-process route selects a model for hub-owned inference; OmniRoute owns provider keys, provider fallback, and usage. Native CLIs retain their own account and provider configuration; subscription OAuth credentials are not pooled through the gateway. The former Switchyard sidecar is retired; routing now runs in process. This keeps provider credentials and fallback policy in one gateway while avoiding a second routing service ([#553](https://github.com/STAIxBWLB/agent-hub/issues/553)).
+
+Peer selection, hub-owned model routing, and provider access are distinct layers. Task routing chooses a peer; the in-process route selects a model for hub-owned inference; OmniRoute owns provider keys, provider fallback, and usage. Native CLIs retain their own account and provider configuration; subscription OAuth credentials are not pooled through the gateway. The former Switchyard sidecar is retired; routing now runs in process. An opt-in `decision` route may consult the loopback agent-decide policy service; execution and provider access remain in the hub and OmniRoute, with the existing heuristic as the consumer fallback. This keeps worker-provider credentials and provider failover in one gateway; the optional policy consult does not proxy the worker's inference traffic ([#553](https://github.com/STAIxBWLB/agent-hub/issues/553)).
+
+Person-owned live model overrides (#1317) are runtime state in `hub.db`, not
+configuration edits. The host owns person admission, desired-versus-applied
+selection, next-turn fencing, status and audit; adapters acknowledge only their
+own captured spawn/transport acceptance. The override does not grant a model,
+provider or account authority to a peer. Unsupported surfaces remain unsupported
+without automatic restarts. Tier 3 configuration, recovery and native isolation
+boundaries stay in place; the [adapter contract](adapters.md#person-owned-live-model-selection-1317)
+defines supported turn paths and evidence limits.
 
 The hub's portable memory storage, sync, indexing, and project helpers come from the pinned first-party `@staix/agent-mem` package. `src/memory/` and `Tasks` provide hub-specific capture, recall, privacy screening, task briefs, and shared notes. Runtime memory is in-process: there is no claude-mem worker HTTP client or model summarizer. claude-mem is an off-by-default, import-only source. This removes a second capture path while keeping caller authority and task privacy in the hub ([#752](https://github.com/STAIxBWLB/agent-hub/issues/752), [agent-mem#13](https://github.com/STAIxBWLB/agent-mem/issues/13)).
 
 Long-term hub writes and core promotion callbacks use the configured standalone sync policy plus hub narrowing. Profile readiness is independent of the current daemon's last automatic sync result. Public status exposes safe cause/count/action metadata; person-only declined inspection exposes IDs and rule categories, with explicit incomplete state when the portable core cannot supply a bounded physical view. Portable row placement and physical sync inspection remain agent-mem responsibilities.
 
+
+The adec backend (#554) is default-off and shadow-first. A shadow pick changes
+neither the heuristic model/effort nor the forwarded conversation. The service
+owns question assembly, hard rules, thresholds, pins and policy fallback; the hub
+owns allowed-pair validation, its default-off shadow switch, current turn and
+budget/campus admission, and original gateway execution. `enforce` is refused at configuration load and
+no pick is applied in this delivery. The bounded evidence
+builder runs only after admission and uses the host public-view screen; it never
+sends tool arguments, system instructions or full history. Sensitive turns are
+campus-gated before evidence and carry dimensions only plus privacy flags.
+Review-observer and remote inputs do not reach this optional observer. Route
+records retain closed metadata, not evidence or service error prose. Direct
+System One integration, the optional stage classifier and the manual triage
+comparison remain outside this consumer slice.
+
 ## Privacy and recovery
 
 Session titles for the two hub-owned title slots (#1055) are conditional writes

package/docs/design/agent-hub.md

@@ -25,6 +25,12 @@ The core loop is to propose and assign work, exchange addressed messages while p
 
 The hub also owns a local worker and optional model calls for its own inference. It does not replace every native agent with that loop, pool subscription credentials, or make native behavior identical across vendors. Native adapters preserve those differences behind explicit contracts ([#625](https://github.com/STAIxBWLB/agent-hub/issues/625), [#553](https://github.com/STAIxBWLB/agent-hub/issues/553)).
 
+Bounded local visual attachments let ordinary peers explain public work with a
+diagram, comparison, table or before/after view. The hub stores and screens the
+record while acon renders it; recipients receive a text stub, and the standalone
+dashboard retains a readable source fallback. This adds no renderer, native-agent
+authority or cross-project board to the hub ([#1058](https://github.com/STAIxBWLB/agent-hub/issues/1058)).
+
 ## Product decisions
 
 | Current rule | Reason and deciding issue |

package/docs/design/bus.md

@@ -31,6 +31,18 @@ The bus applies limits to a sender, sender-recipient pair, important messages, a
 
 ## Queues and delivery outcomes
 
+`hub_visual` (#1058) publishes only a bounded chat stub naming a local visual
+record through `refs.visual`. Its default audience is the console at FYI priority;
+explicit recipients use existing addressed-message rules. Neither Mermaid source,
+table/comparison bodies nor image bytes are embedded in the envelope or delivery
+journal. A source read is explicit, local to the project and privacy-guarded.
+Visual publication grants no task, native-session, invocation or broker authority.
+Before expensive visual screening or image reads, `Limiter.peek` uses the same
+admission decision as `admit` without changing buckets or repeat history. The
+final `admit` still consumes once against current state before record/publication
+effects; a successful preflight never reserves or grants future delivery.
+
+
 The in-memory bus schedules messages; `DeliveryJournal` durably records an individual transport attempt and the original envelopes behind any rendered output. A peer receipt such as `accepted` or `completed` describes transport, not the corresponding task's acceptance, completion, or approval. That separation lets a timeout or restart remain explicitly uncertain without inventing a task outcome ([#37](https://github.com/STAIxBWLB/agent-hub/issues/37)).
 
 A closed bus returns an empty publication outcome before provenance, privacy,
@@ -297,3 +309,9 @@ step. Support is rechecked across awaited admission and at actual publication.
 Live signed observations are scoped to the current connection and roster; saved,
 stale or replayed presence never grants codec support. Existing native, exposure,
 privacy and invocation authorization checks still decide whether a send is allowed.
+
+## Record final-answer projection (#1320)
+
+The final-answer boundary strips agent-authored `amem:` lines before invocation answer handling, ordinary publication, journaled/shared bodies, digest rendering or console envelope taps. Explicit send tools keep their existing path. Original priority and audience/hop/receipt rules are retained. Stripping runs even when optional capture is disabled or fails. Final dispatch traverses the current `onMessage` observer chain exactly once. A peer/body/options-scoped host marker identifies the final-only raw capture path, is consumed before nested messages and is restored or cleared on exit; no final marker is accepted from a wire envelope. Stale replaced owners cannot route or capture a final answer.
+
+The raw-final capture observer is host-only and limited to a complete, currently owned public turn. Private inputs or outputs, review/observer holds, remote inputs/audiences, invocation answers and unknown parents cannot reach it. Count-only observers cannot change routing. The memory owner applies current policy before storage or selection; captured Record rows remain uncurated reference data. A bounded, ephemeral saved-ID/raw-anchor registry can prove display substitution for generated notes, with no persistence or inference from titles or prose. Restart and eviction preserve unproved old content.

package/docs/design/execution-reference.md

@@ -0,0 +1,146 @@
+---
+id: execution-reference
+type: module
+title: Execution Reference and Bounded Lineage
+status: draft
+parent: agent-hub-architecture
+depends-on: [task-board, bus]
+references: [task-board, bus]
+implements: []
+covers: [execution-reference]
+tags: [agent-hub]
+paths:
+  - src/hub/execution-reference.ts
+  - src/hub/execution-lineage.ts
+  - test/execution-reference.test.ts
+  - test/execution-lineage.test.ts
+  - test/fixtures/execution-reference-v1.json
+---
+
+# ExecutionReferenceV1
+
+Source-owner contract for [#1220](https://github.com/STAIxBWLB/agent-hub/issues/1220).
+T1 supplies an address validator, neutral vectors and a pure reader. T2 owns
+Tasks admission and CLI/MCP wiring; T3 owns the console and measured performance.
+There is no new persistence, automatic resolver or runtime polling in T1.
+
+## Address contract
+
+An address is `{v: 1, tool, projectKey, kind, id, revision?, sha256?}`.
+It names evidence; it does not attest to it or grant access to it.
+
+| Field | Rule |
+| --- | --- |
+| `v` | Exactly the integer 1 |
+| `tool` | Known producer id: `ahub`, `ares`, `amem`, `vmem` |
+| `projectKey` | Opaque producer project identity, nonempty, at most 256 UTF-8 bytes |
+| `kind` | Producer-namespaced by `(tool, kind)`, lowercase token matching `[a-z][a-z0-9._-]*`, at most 64 bytes |
+| `id` | Opaque source identity, nonempty, at most 256 UTF-8 bytes |
+| `revision` | Optional nonempty opaque source revision, at most 128 UTF-8 bytes |
+| `sha256` | Optional lowercase 64-hex content hash |
+
+Reject unknown fields, unsupported producers/versions, null optional fields,
+control characters, unpaired surrogates, accessors, symbol keys and inherited
+objects. Do not trim, case-fold or Unicode-normalize identity. Absent optional
+fields stay absent. The producer vocabulary identifies owners, not enabled
+resolvers: an unknown kind can be syntactically valid yet unsupported by its owner.
+Consumers validate this boundary locally without importing hub internals or a new
+shared runtime dependency. Neutral valid/invalid JSON vectors live in
+`test/fixtures/execution-reference-v1.json`; UTF-8 limits include multibyte cases.
+
+A path-like or URL-like id is still opaque data. Never open, execute, fetch,
+route to another node or interpret credentials from any address field. A resolver
+must separately select a known source owner and its authorized project; no
+implicit node or project fallback is allowed.
+
+## Pure source boundary
+
+`readExecutionLineage(source, query)` receives a host-owned snapshot of an explicit
+root neighborhood and returns values only. It does not construct a Board,
+DeliveryJournal or CompletionStore (their constructors can write), read files,
+call a model, spawn a process, probe, replay, fetch or write memory. T2 must reuse
+already-open owner readers and indexed relationships to assemble the snapshot;
+it must not scan the entire board on every inbox poll.
+
+The host pins `id`, `revision`, `projectKey` and caller `scope`, source `health`,
+source-read `authorized` authority and diagnostic authority. These are never
+accepted from a producer or query. A snapshot contains metadata nodes and explicit
+edges, already privacy-projected by the source owner. Each node carries its own
+source reference, state token and evidence strength; no title, note, path,
+session-native identifier or review body enters this projection. States keep
+their owner's meaning: a completed dispatch is not a successful attempt; an
+approved review does not change a failed attempt.
+
+Evidence strengths are `declared`, `host-observed`, `runner-attested` and
+`unknown`. Relations are `dispatched`, `attempted`, `produced`, `reviewed` and
+`declared-external`. An edge is emitted only when both endpoints are visible.
+An external declaration remains declared; a reference/hash never upgrades it.
+The reader never infers edges from names, titles, timestamps, shared paths,
+trace ids, current roles or matching hashes alone.
+
+### Existing owner mappings and missing observations
+
+| Existing relationship | Valid projection | Ceiling |
+| --- | --- | --- |
+| Task `offer.envelopeId` and matching journal `originals[].id` / `refs.task` | Task to dispatch | Dispatch/handout observation, not model consumption |
+| `ExperimentAttemptRecord.attempt.taskId` | Task to research attempt | Does not identify the dispatch that caused it |
+| Attempt id on output event and host observations | Attempt to output | Event is declared unless its stored owner observation proves more |
+| Verified runner receipt `attemptId`, `protocolHash`, output name/hash | Attempt/output evidence | Preserve verified runner provenance; a runner output name is not a hub deliverable id |
+| Review history `deliverables[].id/sha256`, `reviewedHead` | Output to review | Historical exact-hash/head binding, not current approval of edited bytes |
+| Journal `previousId` | Exact predecessor metadata | `attempt` is a retry ordinal, not a research attempt id |
+
+There is currently no persisted dispatch-to-research-attempt relationship.
+`JournalDelivery.out` is rendered input handed to a peer, not produced output.
+The fixture modeling current record relationships therefore leaves this gap. A separate deterministic
+full-chain fixture supplies an explicit `declared-external` edge and keeps that
+edge declared. This proves traversal, not native causal coverage. T1 does not
+introduce a new relationship writer to make the gap disappear.
+
+## Bounds, privacy and pages
+
+Pages contain at most 100 nodes, 200 edges and 262144 UTF-8 bytes of serialized
+JSON, including metadata and cursor. A query can lower the node/edge ceilings;
+its byte budget is between 4096 and 262144 bytes. Nodes and edges have independent
+continuations: a page's edge may refer to a node in another page. Consumers combine
+pages by the complete source reference and never label a truncated page complete.
+Traversal follows only explicit edges in either direction from the named root.
+
+After owner privacy projection, snapshot admission bounds query-local work to 2048 nodes, 4096 edges and 4 MiB of
+projected metadata. Oversized sources are unavailable, not an empty or silently
+partial successful graph. The owner must supply a complete indexed neighborhood
+within this ceiling; larger graphs require a future owner paging contract.
+This is a bounded projection ceiling, not a performance or full-board coverage claim.
+
+The reader checks source authority before reading health, records or the root.
+For callers without source-read authority, absent, denied and unavailable all
+return exactly `{state: "unavailable"}`. Ordinary authorized readers get the
+same shape for hidden or missing roots. Only an already authorized diagnostic
+operator can see the closed reason `missing`, `corrupt`, `unsupported`, `withheld`,
+`cursor_invalid` or `invalid`; never a hidden id, count or source prose.
+Host privacy applies in the source owner's indexed read before assembling this
+snapshot, so hidden rows never enter even its bound calculations or cursor.
+Only the host supplies these snapshots; accepting a producer-supplied graph or
+policy flags would violate this boundary. A hidden requested root is a source
+`withheld` result. Hidden records neither consume public page slots nor create
+dangling edges; a dangling edge in an admitted public snapshot is corrupt.
+
+An available page has `{state: "available", nodes, edges, truncated, cursor?}`.
+The cursor is an opaque continuation bound to source id/revision, caller scope,
+root, limits and the visible graph. Changed source snapshots, privacy views,
+roots or limits invalidate it. Cursor contents grant no authority. A cursor
+is authenticated with a host-owned ephemeral HMAC key (32 to 128 UTF-8 bytes),
+never a key supplied by a query. This reader creates or persists no key; key
+rotation/restart invalidates prior cursors. Edited offsets are refused.
+A cursor
+must be used only with the same admitted source; on invalidation refresh from
+the root. Source health failure is never a complete empty graph. No cursor is
+returned on a complete page.
+
+## Verification boundary
+
+`test/execution-reference.test.ts` consumes the neutral vectors and pins closed
+parsing. `test/execution-lineage.test.ts` pins explicit traversal, missing edges,
+independent states, evidence ceilings, privacy, unavailable equivalence, bounded
+pages and source/scope/root invalidation. Fixtures run without a daemon, native
+agent or account. CLI/MCP equivalence, admission, review currency and native
+coverage remain T2/T3 work; these fixtures do not claim those acceptance legs.

package/docs/design/task-board.md

@@ -61,6 +61,16 @@ The task board is the shared record of work and its authority, not a transcript
 
 ## Authority and state
 
+Visual attachments (#1058) annotate public work without changing a task's state,
+outcome or evidence authority. Publication checks current role, turn, task and
+privacy admission before record/bus effects and after awaited file reads. A PII
+task or private turn refuses publication; a task becoming private also withholds
+its retained visual from public reads and assets. A visual id is not a verdict or
+deliverable receipt, and visual-only calls do not count as task progress for
+no-write detection. Ordinary shared tools and the local worker can publish where
+their role permits; isolated fresh-reviewer MCP keeps its exact two-tool contract.
+
+
 `Tasks` mediates task proposals, planning, owner/reviewer changes, acceptance, completion and review. `Board` persists the rows, history and typed evidence in SQLite; transport, CLI and UI layers do not independently apply task transitions. The issue remains the change spec and GitHub remains authority for PR/check/tag facts. Separating these authorities prevents a chat claim or adapter callback from bypassing task policy ([#481](https://github.com/STAIxBWLB/agent-hub/issues/481)).
 
 A command is authorized against the current actor, role, task state and revision. An asynchronous operation can lose authority while preparing evidence, so write boundaries recheck current scope. Console actions bind the selected task ID and its observed flow revision, rather than an unstable list position. The reason is to keep an approved action attached to the row and state the person actually saw ([#424](https://github.com/STAIxBWLB/agent-hub/issues/424), [#525](https://github.com/STAIxBWLB/agent-hub/issues/525)).