@yadsh/dsh-qa-surface 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
+## 0.3.0 (2026-09-12)
+
+### 🚀 Features
+
+- Optional QA accounts and entry routing. `accounts.enabled` mounts a ([dc2f582](https://github.com/xarleyn/dsh-plugins/commit/dc2f582))
+  full-frame login/registration gate (email + password, coarse audience-safe
+  refusals, per-store rate limiting, self-registration toggle) backed by
+  `$DSH_HOME/qa-accounts.json`: scrypt password hashes, a persisted HMAC secret
+  for stateful-expiry account tokens, and a session ownership map. Ownership is
+  first come, first served - attesting or bulk-claiming an unowned session binds
+  it to the caller (the migration path for existing per-browser chats on first
+  login); sessions owned by another user refuse attestation with
+  `session-owned-elsewhere` and stay hidden from the sidebar, admins are not
+  refused. The identity rides as an explicit token argument into the gated
+  `qaSurface` remotes (the typert carrier never exposes HTTP requests), the
+  policy admission checks it before any session fact is revealed
+  (`auth-required` reopens the gate on expiry), and the account chip with
+  logout lives in the sidebar footer. `entry.redirectNonLoopback` injects a
+  guarded head script through the `webserver/index-inject` event that continues
+  non-loopback hostnames into the QA route - the navigation-marker hand-off is
+  never redirected (no loops), `/?ui=admin` persists an operator bypass and
+  `/?ui=qa` clears it. Accounts are an identity layer for the QA surface, not a
+  harness boundary: QA users still hold the shared host launch-token cookie.
+
+  Follow-ups adopted from a review of the independent dsh-auth-gate plugin: a
+  proxy-side deny list for the privileged config-plane RPC methods behind the
+  deploy proxy's Host/Origin rewrite, a plugin-side launch-token bridge
+  (`entry.cookieBootstrap`) that performs the one-time host-cookie exchange on
+  the `/qa` route itself, a `qa-accounts` bin CLI (list/add/set-role/disable/
+  enable/revoke) so account administration never requires hand-editing the
+  JSON file, and per-account state — a `disabled` flag refusing logins with
+  `account-disabled` plus a `tokenVersion` burned into tokens that
+  `disable`/`revoke` bump, making logout and lockout server-side facts.
+
+  Admins get cross-user views over the same ownership map:
+  `qaSurface/accountsListOwnership` (admin-only, `admin-required` refusal
+  otherwise) returns every chat with its owner's resolved display name, the
+  admin sidebar switches to per-owner sections ordered by their freshest chat
+  (unclaimed chats trail under "Без владельца"), and user messages in foreign
+  chats carry an `author` byline naming the chat owner. Ordinary accounts and
+  deployments with accounts disabled keep the flat sidebar and unlabeled
+  messages.
+
+- The chat-history sidebar gained a footer version button that opens an ([d9d5868](https://github.com/xarleyn/dsh-plugins/commit/d9d5868))
+  end-user changelog dialog: a curated per-version summary (new features and
+  fixes in Russian) rendered in a themed modal with Escape/backdrop close.
+  The bundled version and entries are pinned to package.json and the release
+  CHANGELOG by a unit test, so a release cannot ship a stale dialog.
+
+- Rebuild the client on the 0.1.5 surfaces: the transcript projects from the ([458b9c2](https://github.com/xarleyn/dsh-plugins/commit/458b9c2))
+  ui-chat conversation view's legacy slice, chat/model pinning moves to the
+  wire remotes (`agentPresets.select` on the still-blank session, then
+  `session.selectModel`) with the attestation ordering preserved, and
+  history reads go through the session-v3 surface. The supported host range
+  moves to `>=0.1.5-rc.2 <0.2.0`, dropping 0.1.1-rc.2.
+
+- Harden the gated QA experience and make cross-user history explicitly ([2ed2024](https://github.com/xarleyn/dsh-plugins/commit/2ed2024))
+  opt-in. A new `accounts.showOtherUsersChats` setting defaults to `false`, so
+  administrators only see their own chats unless the deployment enables the
+  shared ownership view. Account storage now follows external CLI updates and
+  uses process-scoped temporary writes, while session admission and client state
+  handling avoid stale async results and reset session-bound assets reliably.
+
+  The QA client now presents a dedicated test-interface disclosure, improves
+  chat search and owner matching, keeps row actions from disturbing result
+  layout, distinguishes administrator roles, and removes decorative middle-dot
+  separators from the sidebar, messages, and source details. Its curated 0.3.0
+  history entry is prepared in advance, while the current-version marker is
+  injected from package.json at build time so the release bump promotes it
+  without another source edit.
+
+### ❤️ Thank You
+
+- xarleyn @xarleyn
+
 ## 0.2.0 (2026-09-10)
 
+- Added DSH-style symmetric transcript/composer width handles with adaptive
+  defaults, viewport clamping, and per-route browser persistence.
+- Added Host-owned structured source provenance for parent and delegated turns,
+  replayable `qa/sources` snapshots, dedupe/ranking, opaque-provider reporting,
+  grouped source UI, and safe rendered/raw file previews.
+- Updated packed Host/browser smoke coverage for browser authentication,
+  revisioned client batches, scoped Remote injection, and current Typert RPC
+  envelopes.
+
 ### 🚀 Features
 
 - Make the QA surface a complete end-user assistant shell: image attachments ([b9af082](https://github.com/xarleyn/dsh-plugins/commit/b9af082))
@@ -19,7 +103,6 @@
   interaction palette as `--dsh-qa-*` tokens, and a split of the surface into
   focused drawer, switcher, and formatting modules.
 
-
 ### 🩹 Fixes
 
 - Pack the generated Typert host and remote-client entrypoints: the `files` ([0059cb4](https://github.com/xarleyn/dsh-plugins/commit/0059cb4))

package/README.md

@@ -18,6 +18,14 @@ Session and Agent Loop.
 - blocks unsupported approvals/questions instead of auto-approving them;
 - pins locked sessions to `read-only` + `approval=never` before Send is enabled;
 - applies a Host-side tool allow-list plus a monotonic execution guard;
+- optionally gates the surface behind email + password accounts
+  (`accounts.enabled`) with server-side session ownership, a first-login
+  migration of the browser's existing chats, a `qa-accounts` management CLI
+  (list/add/set-role/disable/revoke), and a coarse honest boundary:
+  accounts identify QA users, they do not fence the harness root;
+- optionally redirects non-loopback hostnames from the harness root into the
+  QA route (`entry.redirectNonLoopback`), keeping the operator's localhost
+  harness UI untouched;
 - uses the existing same-origin DSH connection and trust boundary.
 
 It does not add another HTTP server, provider proxy, permissive CORS rule, or
@@ -43,8 +51,8 @@ Some DSH patch operations replace a row's complete `config` instead of deeply
 merging it. When editing an existing row, provide every value that deployment
 needs.
 
-DSH `0.1.1-rc.2` serves unknown frontend paths as 404 rather than falling back
-to `index.html`. The Host half therefore claims only the configured QA
+Tested DSH releases serve unknown frontend paths as 404 rather than falling
+back to `index.html`. The Host half therefore claims only the configured QA
 navigation path and redirects it through the canonical `/` document with a
 short-lived query marker. The browser restores the requested `/qa` URL with
 `history.replaceState` before mounting the overlay. No second server, duplicate
@@ -90,6 +98,11 @@ config:
     renderMarkdown: true
     maxContentWidth: 900
     showSessionList: false
+  accounts:
+    enabled: false
+    allowRegistration: true
+    sessionTtlDays: 30
+    showOtherUsersChats: false
   suggestedQuestions:
     - Как запросить доступ?
     - Где лежит инструкция?
@@ -114,6 +127,38 @@ config:
     toolPolicy:
       mode: allow-list
       allow: []
+  sources:
+    enabled: true
+    collect:
+      parentAgent: true
+      subagents: true
+      persistTurnEvent: true
+    display:
+      sidebar: true
+      footer: true
+      groupByKind: true
+      showDiscovered: false
+      showOriginBadges: false
+      maxInitiallyVisiblePerGroup: 8
+    webSearch:
+      promoteSearchResultsWithoutFetch: true
+      maxPromotedPerSearch: 5
+    dedupe:
+      normalizeUrls: true
+      stripTrackingParams: true
+      mergeFileRanges: true
+    filePreview:
+      enabled: true
+      markdownRenderedByDefault: true
+      allowRawToggle: true
+      maxBytes: 2000000
+      maxMarkdownRenderBytes: 1000000
+    subagents:
+      inheritSources: true
+      enableReportToolFallback: true
+      markIncompleteOpaqueRuns: true
+    legacy:
+      parseAssistantSourcesBlock: false
 ```
 
 `workspaceId` is recommended for a deterministic assistant. Without it, DSH
@@ -151,12 +196,25 @@ prompt and the answer arrives as a follow-up turn; the projection hides that
 instruction and the consecutive turns read as variants of one question,
 navigable with a `< 2/2 >` switcher (newest shown by default).
 
-Sources: with `ui.showToolActivity: true` a header button opens a right-hand
-drawer listing the pages fetched, searches run and files read in this chat,
-projected from the same tool activity the work groups render - no extra
-prompting or tooling is involved. Clicking a source opens its full tool
-output with every http(s) link clickable, and web sources carry an
-"Открыть" button straight to the page (a Jira issue, a wiki article).
+Sources are structured Host-owned provenance, independent of
+`ui.showToolActivity`. Successful reads/fetches, bounded web-search evidence,
+Jira/Confluence/knowledge results, and inherited subagent sources are
+normalized and deduplicated into one turn bundle. That exact bundle feeds the
+answer footer and grouped drawer and is persisted as `qa/sources`, so reload
+does not rerun tools. Search-only discovery stays hidden by default.
+
+Local file cards open a source-scoped, read-only preview after Host-side real
+path validation against the attested session root. Markdown opens rendered by
+default with an HTML-free renderer and offers `Rendered / Raw`; raw mode jumps
+to recorded line ranges. The endpoint cannot browse or write files and refuses
+paths that are not evidence in the canonical bundle.
+
+Observable local subagents are inherited recursively. The internal
+`qa_report_sources` tool covers opaque delegated providers and is admitted as
+a provenance-only capability even when it is not listed among ordinary QA
+tools. A provider that neither exposes events nor reports sources marks the
+turn provenance incomplete. The QA prompt tells models not to append a manual
+`Sources`/`Источники` bibliography.
 
 Images: the composer accepts PNG/JPEG/WebP/GIF via drag & drop onto the
 composer, paste, and the picker button, several at once (soft client caps:
@@ -175,17 +233,32 @@ live transcript (composer disabled, one click back to the chat) - viewing
 never attests or writes.
 
 `ui.showSessionList: true` renders a minimal chat-history sidebar beside the
-conversation. It lists only the chats this browser has actually used: the
+conversation. By default it lists only the current user's chats: the
 client keeps a per-browser id index under
 `<storageKey>:v1:<route>:chats` in localStorage (capped at 50, most recently
 used first) and intersects it with the Host session list, so users sharing the
-deployment never see each other's chats. Switching re-runs the full policy
+deployment never see each other's chats. An admin can explicitly enable
+`accounts.showOtherUsersChats: true` to add chats owned by other QA accounts,
+grouped by owner. Switching re-runs the full policy
 attestation; a chat the Host no longer lists is pruned from the index. Each
 row carries a two-click delete control that removes the chat from this
 browser's index; deleting the chat that is currently open continues in a
 fresh attested session. Host-side sessions are not deleted — DSH 0.1.x
 exposes no session-deletion seam. The sidebar hides below 600px viewports.
 
+The sidebar footer shows the deployed plugin version. Clicking it opens a
+changelog dialog with a curated per-version summary (features and fixes);
+Escape or a backdrop click closes it.
+
+On `/qa`, the plugin shadows DSH's stock `welcome-notice` onboarding entry and
+renders a route-owned Russian testing disclosure. Keeping the visible dialog
+in the QA overlay prevents DSH's blank-session onboarding lifecycle from
+dismissing it when a question is submitted. It explains the DeepSeek Harness
+preview foundation, QA review of questions and answers, the work-related
+scope, and local in-contour model processing. Explicit acknowledgement is
+stored as a versioned browser-local flag; changing the disclosure version
+shows it again. Other DSH routes retain the stock onboarding entry.
+
 Locked mode requires a deployment permission preset named `qa-read-only`.
 Extend the existing `@deepseek-ai/dsh-permission-presets` row without changing
 its process-wide default:
@@ -264,8 +337,10 @@ What a LAN deployment does not change:
   `/qa`. Scope the port's reachability (subnet-limited firewall rule, VPN or
   tailnet, authenticating reverse proxy) and use a dedicated process identity.
 - Loopback-only settings, directory picking and credential RPCs stay refused
-  for LAN clients; the first-load welcome notice re-appears on reload because
-  remote browsers have no settings persistence.
+  for LAN clients. On `/qa`, the plugin replaces DSH's non-persistent welcome
+  step with a QA-specific testing disclosure and remembers its exact copy
+  version in that browser's local storage. The stock DSH notice remains
+  unchanged on operator routes.
 
 See [Configuration](docs/CONFIGURATION.md) for the config-channel details.
 

package/compatibility.json

@@ -1,19 +1,27 @@
 {
   "deepseekHarness": {
     "channel": "next",
-    "range": ">=0.1.1-rc.2 <0.2.0",
-    "testedReleases": ["0.1.1-rc.2"],
+    "range": ">=0.1.5-rc.2 <0.2.0",
+    "testedReleases": ["0.1.5-rc.2"],
     "requiredClientFeatures": [
       "shell.overlay",
-      "connection.api.sessions",
+      "remote.session.selectModel",
+      "remote.agentPresets.select",
+      "uiConversation.binding",
       "sessions.binding",
       "settingsScope",
+      "settings.onboarding list-slot shadowing",
       "webServer.register",
       "typert.remote",
       "agentPresets.composedPreset",
       "permissionPresets.set",
       "tools.restrict",
       "tools.guard",
+      "tools.register",
+      "session.event-extension",
+      "agent.turn-stopping",
+      "agent.currentInitiator",
+      "systemPrompt.section",
       "workspaceRegistry.get"
     ]
   },

package/docs/ARCHITECTURE.md

@@ -2,7 +2,7 @@
 
 The Host half validates the Loader configuration, registers the `qa-surface`
 settings namespace and owns one narrow GET/HEAD route for the configured QA
-path. Published DSH `0.1.1-rc.2` returns 404 for unknown frontend paths, so the
+path. Published DSH releases return 404 for unknown frontend paths, so the
 route redirects navigation through the canonical `/` index with an encoded
 same-origin path marker. It also exposes one typed
 `secureSession(sessionId)` operation whose policy is read only from Host

package/docs/COMPATIBILITY.md

@@ -2,7 +2,7 @@
 
 | Plugin version | Tested DSH release | Required public contracts                                                                                                                                                              |
 | -------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 0.1.x          | 0.1.1-rc.2         | `shell.overlay`, Typert remote, `agentPresets.composedPreset`, `permissionPresets`, agent-scoped `tools.restrict/guard`, `workspaceRegistry`, session/model APIs, `webServer.register` |
+| 0.1.x          | 0.1.5-rc.2         | `shell.overlay`, Typert remote, `agentPresets.composedPreset`, `permissionPresets`, agent-scoped `tools.restrict/guard`, `workspaceRegistry`, session/model APIs, `webServer.register` |
 
 DSH is developer-preview software. Compatibility-sensitive calls are isolated
 in `QaSessionController`, `QaTranscriptAdapter`, `QaConfigController` and

package/docs/CONFIGURATION.md

@@ -7,12 +7,17 @@ rules are:
   `/`, `/api` or `/plugins`;
 - `fixed` requires `fixedSessionId`;
 - `provider` and `model` are either both absent or both present;
-- `maxContentWidth` is an integer from 480 through 1600;
+- `maxContentWidth` is an integer from 480 through 1600 and caps the
+  user-resizable transcript/composer width; each QA route persists its chosen
+  width in browser storage;
 - duplicate/blank suggested questions are removed;
 - approval and question policies are fixed to safe blocking behavior;
 - reasoning and tool details are opt-in through `ui.showReasoning` and
   `ui.showToolActivity`; enable them only where those contents are appropriate
   for the QA audience;
+- accounts default to disabled; when enabled, `sessionTtlDays` is an integer
+  from 1 through 365, and other users' chats stay hidden unless an admin view
+  explicitly enables `accounts.showOtherUsersChats`;
 - lockdown defaults to enabled and requires a non-empty permission preset;
 - the preset must resolve on the Host to exactly `read-only` + `never`;
 - permission, slash-command, settings, rename, delete and arbitrary-open
@@ -77,6 +82,88 @@ part of the same change. The package's
 [default inventory](../capability-policy.json) is intentionally empty, matching
 the default `toolPolicy.allow`.
 
+## Structured sources
+
+The `sources` block controls provenance independently from Activity rendering.
+The defaults collect parent and subagent results, persist a `qa/sources` event,
+hide discovery-only candidates, group visible evidence by kind, and promote at
+most five substantive `web_search` results when no fetch occurs. URL tracking
+parameters and overlapping file ranges are normalized during deduplication.
+
+`sources.filePreview` is a narrow read capability, not a filesystem browser.
+The Host serves only a path already present in the attested session's canonical
+evidence bundle, resolves symlinks with `realpath`, rejects root escape, and
+applies `maxBytes` plus `maxMarkdownRenderBytes`. Markdown uses the client's
+HTML-free renderer; relative links and executable raw HTML are not activated.
+
+Set `sources.display.showOriginBadges: true` while auditing inheritance. Local
+subagent sources carry run/session origins automatically. An opaque provider
+can call the internal `qa_report_sources` tool; if it does not, and
+`markIncompleteOpaqueRuns` remains enabled, the bundle is explicitly marked
+incomplete.
+
+See [Structured sources migration](SOURCES-MIGRATION.md) before removing an
+older prompt-authored bibliography convention.
+
+## Accounts and the QA gate
+
+`accounts.enabled: true` mounts the login/registration gate in front of the
+QA surface and turns on server-side session ownership:
+
+- The store lives at `$DSH_HOME/qa-accounts.json` (created on first use). It
+  holds scrypt password hashes, a persisted HMAC secret for the account
+  tokens, and the session ownership map. The path is not configurable and no
+  secret ever reaches `describe()`.
+- `accounts.allowRegistration` (default true) controls self-service signup
+  in the gate; the first account ever registered becomes `admin`.
+- `accounts.sessionTtlDays` (default 30) is the account token lifetime. The
+  token is an HMAC-signed value the browser keeps in `localStorage`; logout
+  or expiry returns the browser to the gate, and the Host re-derives the
+  identity on every attestation.
+- `accounts.showOtherUsersChats` (default false) lets admins load and display
+  chats owned by other QA accounts. It has no effect for ordinary users.
+- Session ownership is first come, first served: attesting or bulk-claiming
+  an unowned session binds it to the caller's account (this is how existing
+  per-browser chats migrate on the first login). Sessions owned by another
+  user are refused with the coarse `session-owned-elsewhere` reason and
+  hidden from the sidebar; admins are not refused.
+- Manage accounts with the bundled CLI (no hand-editing of the JSON):
+
+  ```sh
+  qa-accounts list
+  qa-accounts add user@example.com --password-stdin --role user
+  qa-accounts set-role user@example.com admin
+  qa-accounts disable user@example.com   # blocks logins, revokes live tokens
+  qa-accounts revoke user@example.com    # invalidates every issued token
+  ```
+
+  `disable` bumps the account's token version, so all outstanding tokens die
+  server-side; `enable` requires a fresh sign-in. After a secret rotation
+  suspicion, `revoke` is the single-step response.
+
+- Honest boundary: accounts identify QA users and gate the QA surface and
+  its remotes. They do not fence the harness: every QA user also holds the
+  host launch-token cookie, with which the full root UI stays technically
+  reachable. Keep the network scoping advice from the deployment kit.
+
+## Entry redirect
+
+`entry.redirectNonLoopback: true` (default) injects one script into the
+served root `index.html`: browsers whose URL host is not loopback
+(`localhost`, `127.0.0.1`, `::1`, `*.localhost`) continue into the QA route,
+so LAN visitors never see the full harness root. The check is client-side on
+`location.hostname` on purpose - behind a local reverse proxy every request
+looks loopback to the server. The navigation hand-off `/?__dsh_qa_route=…`
+is never redirected (that would loop), `/?ui=admin` bypasses the redirect
+and is remembered for the browser, and `/?ui=qa` clears the bypass.
+
+`entry.cookieBootstrap: true` (default) additionally lets the `/qa` route
+itself bootstrap the host cookie: a browser without any `dsh-auth-` cookie is
+sent to the one-time `/?token=…` exchange (relative redirect, token resolved
+from the host connection service) before the marker hand-off. This makes the
+transparent entry work without the deploy proxy; with the proxy in front,
+either side may perform the exchange and the other becomes a no-op.
+
 ## Configuration channel over the LAN
 
 The browser normally reads the effective configuration from the Host-owned

package/docs/SOURCES-MIGRATION.md

@@ -0,0 +1,28 @@
+# Structured sources migration
+
+`dsh-qa-surface` now treats `QaTurnSources` as the only canonical provenance
+model. Assistant prose is never parsed for a `Sources` or `Источники` section,
+and the default `sources.legacy.parseAssistantSourcesBlock` remains `false`.
+
+## Deployment steps
+
+1. Keep the QA agent's existing read-only retrieval tools in
+   `lockdown.toolPolicy.allow`.
+2. Leave `sources.collect.persistTurnEvent: true` so completed turns append a
+   replayable `qa/sources` snapshot.
+3. Remove prompt instructions that ask the assistant to manually write a
+   bibliography. The plugin contributes its own scoped guidance after QA
+   attestation.
+4. For an opaque subagent provider, expose the inherited
+   `qa_report_sources` tool and ask the provider to call it before completion.
+   Local DSH subagents require no reporting prompt.
+5. Start with `sources.display.showDiscovered: false`; enable it only for
+   provenance debugging.
+
+Historical sessions without `qa/sources` remain readable: the Host reconstructs
+bundles from durable structured tool metadata when available. Historical
+assistant-authored source prose remains ordinary answer text and is not trusted
+as provenance.
+
+The `qa/sources` event is a required plugin-owned session event. Keep
+`dsh-qa-surface` loaded in any Host that restores sessions containing it.

package/docs/SOURCES-PROVENANCE-AUDIT.md

@@ -0,0 +1,88 @@
+# Sources / provenance implementation audit
+
+Date: 2026-09-11  
+Pinned DSH development API: `0.1.5-rc.2`
+
+This note records the Phase 0 findings for
+`SPEC-dsh-qa-surface-sources-provenance.md`. It is intentionally tied to the
+versions in this repository rather than to DSH `master`.
+
+## Existing QA data path
+
+- `QaSessionController` binds the client `UiConversation` snapshot.
+- `QaTranscriptAdapter` reads the `chat.legacy` projection.
+- The former Sources drawer inferred one row from selected tool names and raw
+  arguments. It counted a search query as a source and did not retain turn,
+  line-range, evidence, or origin data.
+- `ToolResultNode.meta` is available in the client projection. DSH documents it
+  as the tool-private, JSON-safe result presentation payload persisted on the
+  corresponding `tool/result` event.
+
+## Structured metadata available in the pinned version
+
+`@deepseek-ai/dsh-tools` exports the provider-neutral result shapes needed by
+the first implementation slice:
+
+- `ReadResultView`: `path`, numbered `lines`, `offset`, `totalLines`, `lang`;
+- `SearchResultView`: grouped grep matches or path discovery;
+- `WebSearchResultView`: structured `sources[]` and truncation state;
+- `WebFetchResultView`: final redirect URL, status, and truncation state;
+- generic call `FileLocation` values.
+
+The QA extractor layer therefore consumes `ToolResultNode.meta` first and uses
+tool arguments only as a compatibility fallback for direct read/fetch calls.
+It does not parse assistant prose.
+
+## Replay and persistence
+
+The completed implementation rebuilds collectors from persisted
+`tool/call`/`tool/result.meta` events and writes one materialized `qa/sources`
+snapshot at `agent/turn-stopping`. The type is declaration-merged into
+`SessionEventMap`.
+
+The pinned DSH exports its live `KNOWN_SESSION_EVENT_TYPES` set. As already
+demonstrated by the repository's `dsh-session-scope` plugin, registering the
+plugin event there is the supported compatibility mechanism when
+`Session.append` cannot mark an extension event ignorable. Registration is
+effect-scoped and removed on plugin disposal. A Host that owns sessions with
+these events must load `dsh-qa-surface`, just as it must load any plugin that
+owns a required durable event vocabulary.
+
+## Subagent lifecycle
+
+The pinned `@deepseek-ai/dsh-subagent` does expose process-local
+`subagent/start` and `subagent/end` events. Both carry `runId`, `provider`, child
+session `id`, and `local`; the terminal payload additionally carries
+`stopReason` and optional `lastAssistantMessage`. Scoped dispatch is keyed by
+the delegating parent.
+
+The Host now maintains that lineage registry, uses the child header or causal
+`AgentRegistry.currentInitiator()` attribution, bubbles nested local-child
+sources to the original root turn, and retains run/session origin fields.
+Opaque providers can call `qa_report_sources`; an unreported opaque run sets
+`complete=false` with an `incompleteOrigins` entry.
+
+## File preview reuse
+
+The new `readSourceFile` Remote is limited to evidence paths in canonical
+bundles, re-attests the session, resolves both root and target with `realpath`,
+rejects traversal/symlink escape, caps bytes, and exposes no write/list API.
+
+## Implemented scope
+
+- canonical source and turn-bundle types;
+- URL/path/range normalization;
+- extractor registry with read, grep discovery, web search, and web fetch;
+- evidence promotion, deduplication, ranking, and a default display threshold;
+- bounded structured web-search promotion (five results by default);
+- Host per-turn collectors and materialized/replayable `qa/sources` events;
+- local and nested subagent inheritance plus opaque-provider reporting;
+- structured Jira, Confluence, knowledge and reported-source adapters;
+- one canonical snapshot used by grouped drawer and answer footer;
+- source details, origin/partial badges and completeness state;
+- safe local-file preview, rendered/raw Markdown, range chips and exact raw
+  line highlighting;
+- configuration and tests for the feature surface.
+
+Optional inline citation rendering (SPEC Phase 5) remains intentionally out of
+the MVP, as specified.