# Architecture

English | [中文](architecture.zh.md)

## Product boundary

```
DeepSeek Harness
        ↓
capability surfaces and domain state
        ↓
internal dshline presentation adapters
        ↓
bounded TuiSlots / Screen rows
        ↓
native terminal
```

**Harness owns capabilities; dshline owns terminal presentation.** Harness is
where lifecycle, state, persistence, provider selection, authority, and policy
belong. dshline reads the narrowest authoritative surface, turns structured
facts into terminal rows, and does not recreate a runtime, a provider
connection, or a domain state machine.

The renderer package is below that boundary. It knows display widths, control
escaping, keys, boxes, and `Screen`; it must not learn about Harness, agents,
jobs, providers, or a domain such as Todos.

## Native scrollback is the terminal model

`Screen.commit()` writes finished transcript rows into the user's real terminal
scrollback. Those rows are never virtualized, retained as an in-memory screen,
or rewritten. `Screen` redraws only the bounded live region at the bottom: a
streaming line, composer, status, or temporary overlay. Every terminal write
passes through it so that live region stays last.

This is deliberate product architecture, not a temporary implementation choice.
dshline will not replace `Screen` with a reconciler that owns historical
terminal output, or adopt an alternate-screen/full-screen transcript model.
React + Ink can support different terminal trade-offs; dshline keeps normal
terminal scrolling, selection, and copying available for its finished
transcript.

Future view code may become more declarative, but its final output must still
be bounded terminal rows for `TuiSlots` and `Screen`. An overlay may change the
live region while it is open; it must not rewrite committed scrollback.

## Supporting Harness capabilities

Supporting a Harness plugin does not mean copying each plugin or provider into
dshline. The upstream service graph calls some of these surfaces *seams* and
others core services; for presentation, the important distinction is whether
there is a standard authoritative contract dshline can consume.

### 1. Generic capability surfaces

Prefer a standard Harness surface over a concrete package or provider:

| Need | Authority | Presentation consequence |
| --- | --- | --- |
| background work | `ctx.jobs` | Observe generic job snapshots and changes. |
| delegated work | `ctx.subagents` | Observe provider-neutral lifecycle and discovery. |
| live agent registry | `ctx.agents` | Resolve live local Agents and delegate fresh/resumed attachment through the published factory seam; do not own AgentLoop or persistence policy. |
| orchestrated work | `ctx.workflowEngine` + durable `tool-workflow/*` records | Observe run identity, phases, and members; own no run handle. |
| models | `ctx.llm` | Read registered provider/model metadata, and the configurable-provider directory of routes configuration can activate. |
| default model | `ctx.agentDefaultModel` | Read or save the composition's default selection when the optional service is mounted; do not persist a second copy in dshline. |
| user configuration | `ctx.settings` | Read redacted namespace descriptors; write path ops against the revision they were read at. |
| secrets | `ctx.credentials` | Ask whether a reference or record is configured and writable; never hold a value. |
| obtaining a credential | `ctx.authorization` | Render the seam's neutral notice and prompt vocabulary; own no login protocol. |
| human commands | `ctx.commands` | Discover and execute the registered command contract. Attachment admission is the registry's: honour `input.attachments` before dispatch, and submit only the discriminated attachment kinds this frontend can author. |
| assistant output | durable `assistant/message` / `assistant/attempt` on `session/event`, plus live `agent/assistant-stream` frames | Two contracts, kept apart. The settlements are the transcript; the frames are transient presentation for the attached Agent alone. Never expand an embedded stream into a live feed, never persist a frame, and never commit an attempt that settled without a message. |
| tools | `ctx.tools` | Render tool-owned presentation intents, not tool-name cases. |
| human answers | `ctx.userQuestions` | Register a terminal answerer; claim a request this frontend can present, never assuming it was addressed only to this frontend. |
| approvals | `ctx.approval` | Answer only requests owned by this frontend; let the waterfall fail closed for other agent identities. |
| permission presets | `ctx.permissionPresets` + `ctx.sessionProjections` (`permissions`) | Two authorities, not one. Read the live process-level catalog with `catalog()` at the moment a picker opens, and the durable current selection from the projection; keep a copy of neither. Mutate only through the registered `/permission <preset>` command, and offer nothing the live catalog does not list. Treat both as optional. |
| sessions | `ctx.sessionQuery` | Query Harness's live-preferred session corpus; do not build another database. Its full-text methods are abstract, so treat content search as optional. Its `SessionHeader.cwd` values are also the only working-directory authority: group them transiently, never store a directory list, a worktree registry, or a Git state cache. |
| attachments | `ctx.fs` + `ctx.attachments` | Keep paths as session-local drafts; perform bounded reads through the active filesystem and publish durable image references as one batch. Never persist bytes, base64, or host paths. |
| log-derived state | `ctx.sessionProjections` | Consume registered domain snapshots and changes. |
| context occupancy | `ctx.sessionProjections` (`contextPressure`, `contextBreakdown`, `tokenUsage`) | Read the O(1) folds; never count tokens or tokenize. |
| session statistics | `ctx.sessionProjections` (`sessionStats`) | Read the whole-log counts and wall times; derive nothing beyond one division over two published totals. Treat the unit as optional. |
| turn outline | `ctx.sessionProjections` (`turnOutline`) | Read Harness's turn number, each turn's `turn/start` seq, and the bounded prompt/response previews. Keep no turn list, fold no events, and never infer a completed turn from a preview — an empty preview is a valid state. Treat the unit as optional. |
| request metadata | `Session.requestHeader()` + `Session.requestContext()` | Read the logged route and tool counts, and the recorded route's system-prompt update mode, for cache/usage views; do not maintain a parallel header. |
| the system prompt | durable `system/message` surface nodes | It is conversation history, not request metadata: read it as a surface entry through the same authorities every other entry uses, keep it out of the human transcript, and hold no prompt state of dshline's own. |
| context composition per entry | `ctx.tokenMeter` | Ask for the per-node measurement only when an inspector needs it; its own contract calls it O(surface). |
| plan mode | committed `plan/mode` events; Harness's `plan` projection as contract evidence | Fold committed mode events with `planModeAfter()`; do not maintain a mutable second state or read `ctx.planMode` as a presentation mirror. |
| reducing context | `ctx.commands` (`/compact`) | Dispatch the registered command; observe `compaction/*` events. Never call `ctx.compaction`. |
| agent composition | `ctx.agentPresets` | Read the roster, one preset's composition, and which preset a session actually runs; join or switch an agent through the seam, never a private registry. |
| host composition | `ctx.dshHomePath`, `ctx.baseUrl`, `dsh plugin` | Read the profile roster from Harness's own home-path service and the booted profile from the Loader's base URL; mutate only by forwarding to `dsh plugin`, never by writing a profile manifest. |
| subprocess | `ctx.subprocess` | Forward the launcher argv, environment, and timeout through the Harness runtime; do not reimplement launcher or profile policy. |
| session title | `ctx.sessionTitle` | Rename through the live-session service; do not mutate a copied header or maintain a title store. |
| skills | `ctx.skills` | Observe the effective per-scope catalog with `snapshot({ cwd, scope: agent })`; offer and inspect the resolved summaries. Never discover, load, or inject a skill body — a leading `/name` line is sent verbatim and `dsh-tool-skill` owns what it means. |
| provider health | `ctx.subagents` | Ask the registry which providers exist before presenting a row that names one as usable; never infer availability from a row being enabled. |

A new subagent provider should appear through `ctx.subagents`; a background
producer through `ctx.jobs`; an LLM adapter through `ctx.llm`; and a command
or tool through its standard registry. The real Codex acceptance has proven
that a provider publishing `ctx.subagents` / `ctx.jobs` is shown by generic
Work, not by Codex-specific dshline code. [Provider acceptance](provider-acceptance.md)
records that evidence and its configuration boundary. If a required fact is
absent from the surface, improve the upstream contract rather than parse text
or connect to a provider privately.

Skills are the current live example of that last rule. `ctx.skills` answers
which skills an agent can see and which of them are `userInvocable`, but the
consumer that actually interprets a human `/name` gesture is a separate
package (`dsh-tool-skill`), and no surface says whether a composition mounted
it. So a hand-built composition can publish a user-invocable skill that no
`/name` line reaches. dshline does not infer readiness — not by parsing preset
YAML, not by inspecting Cordis listener registrations, and not by treating a
model tool named `skill` as proof of a human gesture boundary; every one of
those reads implementation rather than contract. It follows `userInvocable`,
which is the same contract Harness's own Web client follows
(`session-controller`'s skill catalog Remote filters on `isUserInvocable`
alone), and the gap is documented for the user rather than guessed at. An
authoritative readiness seam is upstream work.

### 2. Known projection domains

A domain plugin may publish structured, log-derived state through
`ctx.sessionProjections`. dshline can offer a native presentation adapter for a
known key such as `todos` or `goal`, but the domain and Harness remain the
state authority. The TUI must not parse tool output, fold a second copy of the
session log, or create a competing persistence format.

The projection pattern is:

```
domain plugin
        ↓ registers a projection unit
Harness projection registry drives, caches, and notifies
        ↓ snapshot + change feed
dshline presentation adapter
```

For authoritative projection state, read
`ctx.sessionProjections.snapshot(session)` and subscribe with
`ctx.sessionProjections.onChanged(...)`. The registry drives registered pure
units over committed events, gives `snapshot()` one synchronous consistent cut,
and emits a change only when a unit changes. dshline's internal,
session-scoped observer subscribes once for the exact `Session`, coalesces an
invalidation in a microtask after that synchronous drive settles, and leaves
all values in the registry for adapters to read through `snapshot()`. It is not
a second projection store. Projection-key presence is process-wide, not a
per-session capability signal: a key registered by any composition can appear
in every session snapshot. Interpret the projection value (for example, a Todo
list or `null`) rather than treating the presence of `todos` as proof that this
exact agent has Todos enabled. This is an internal architecture pattern, **not**
a stable public `ProjectionAdapter` interface.

`todos` is the second proof. `@deepseek-ai/dsh-tool-todo` supplies the
model-facing `todo_write` tool, durable whole-list `todo/write` events, and the
optional `todos` projection. dshline presents its current snapshot through a
bounded `/todos` overlay and an optional `todo completed/total` status segment;
it owns no Todo mutation, lifecycle, fold, or persistence. Todo items have only
`content` and `pending`, `in_progress`, or `completed` status; each write
replaces the complete list. The projection is `null` before a write, contains
the latest list, and clears on the next `turn/start`. The intended path is:

```
@deepseek-ai/dsh-tool-todo
        ↓ todo/write and todos projection
ctx.sessionProjections
        ↓
dshline Todo presentation
```

It must not inspect `todo_write` calls or rendered cards to infer state.

Permission selection follows the same boundary, but over two Harness
authorities rather than one, because Harness owns them at two different scopes.
`ctx.permissionPresets.catalog()` is the live, process-level list of selectable
options, and it changes with contributions Harness announces on
`permission-presets/catalog-changed`; the `permissions` session projection
carries only the durable current selection. The intended path is:

```
ctx.permissionPresets.catalog()        ctx.sessionProjections
        ↓ live selectable options              ↓ permissions: current selection
                        \                     /
                         dshline permission picker
                                    ↓
                         /permission <option id>
                                    ↓
                           Harness-owned mutation
```

A bare terminal `/permission` reads both at the moment the picker opens, joins
them for presentation, and dispatches the chosen opaque option id back through
the registered Harness `/permission <preset>` command. dshline never folds
permission events, never calls the preset service to mutate, and never keeps a
copy of the catalog — it is live process state, not session history. Both
authorities are optional, and without either the bare command falls through
unchanged. A current value the live catalog does not list is reported as current
and offered as nothing: `custom` is how Harness derives exactly that state, and
inventing a catalog row for it would offer a command Harness rejects. The same
`permissions` projection is the status line's persistent current-state authority:
the footer reads its `currentValue` from the attachment's shared snapshot, so a
change folded from any of the three knobs repaints it. The catalog remains
selection-only.

**dshline does not subscribe to `permission-presets/catalog-changed` in order to
cache or mirror the catalog.** Harness publishes it, and what the picker takes
from its existence is that the catalog is live — which is why the read happens at
the interaction boundary rather than once at startup. A picker that was open
across a change can only submit an option id, and Harness's own command handler
validates that id against the catalog as it stands; a withdrawn option is refused
there, not filtered here. A cached copy would be a second authority on state
Harness already owns, and that is the thing this boundary exists to prevent. The
terminal picker is ephemeral by construction: its rows live for one interaction.

The persistent footer is the one consumer that does subscribe, and only as an
invalidation signal. Whether `auto` is currently contributed is a derivation
input, not Session history: withdrawing it can change what the next
`permissions.currentValue` derives from the same durable knobs while appending no
Session event and publishing no projection frame. The listener does nothing but
request a redraw, so the next paint re-reads the authoritative projection
snapshot; the catalog is still not the footer authority, and no catalog copy
exists.

The one risk this leaves with dshline is presentation. Harness publishes the
selectable catalog but no per-option risk metadata — `PresetOption` is a value,
a name and a description — so which options need an explicit human
acknowledgement before a *picker* dispatches them is a frontend decision. dshline
makes the same one Harness Web makes, for the same two upstream-known options
(full access, and the live `auto` review preset), as a small explicit table
keyed by opaque id. It never infers risk from sandbox or approval internals, nor
from an option's display name, and a typed `/permission <preset>` is ordinary
Harness command input that this step never sees.

Context intelligence is the fourth, and it is the one that separates a cheap
authority from an expensive one. `@deepseek-ai/dsh-token-meter` publishes three
projection units — `contextPressure` (the provider's newest prompt sample, the
same sample plus the signed heuristic repricing of the surface since, and the
newest recorded route capacity), `contextBreakdown` (heuristic system/tools/
messages composition), and `tokenUsage` (cumulative provider buckets) — all
O(1) folds. Those are what the status line and `/context`'s headline read.

The same service also exposes `measure(session)`, which prices every node of the
current surface and returns a deep clone; its own documentation states that
measurement is therefore O(surface). That is the per-entry X-ray, and the rule
is that only an open inspector may ask for it. dshline keys a cached measurement
on every input a node price depends on and nothing else: Harness's own surface
revision (node count plus `replaceGeneration`) and the effective pricing route,
read from `session.requestHeader()` because the header's provider and model are
what select the routed adapter's image pricing the meter prices with. The surface
revision also covers a system-prompt change, which is a surface change in the
adopted format — an in-history route appends a `system/message` node, an
incapable one replaces the head — so dshline tracks nothing extra for the prompt.
So an inspector left open through a streaming reply measures once, while a landed
compaction or a route change is picked up on the next paint, and the log length —
which moves on every committed event a turn logs — is deliberately not part of
the key. Only a SUCCESSFUL measurement is cached: an absent or refusing meter is
retried, because the meter can be mounted after an inspector first read and a
throw over a malformed log can be repaired by a later append. No timer exists
for any of it.

The two vocabularies are never mixed. Projected occupancy and heuristic
composition are presented side by side and never divided into each other, and
per-entry prices are presented as estimates because the node meter is
route-priced or heuristic rather than a provider's tokenizer. Scaling one into
the other to make a panel add up would be dshline inventing accounting — which
is also why a per-entry share is labelled as a share of the MESSAGE context:
`surfaceTokens` prices the conversation, and the envelope is priced by the other
authority.

Provenance follows the same rule. `contextPressure.projectedTokens` is presented
as a projection, not as a provider figure that occasionally becomes exact:
equality with `pressureTokens` does not prove the surface has not moved, since
several changes can net to zero. A compaction summary is claimed only from
compaction's own durable checkpoint source — the `{ kind: 'plugin', plugin:
'compact' }` marker plus the transaction's `compactionId`, read structurally
rather than through `isCompactCheckpointSource`, which is a value in an optional
package — and any other replacement is reported as `replaced`, because the
surface contract permits a replacement from any producer and does not say a
replacement was a reduction.

`tokenUsage`'s scope is the agent's own model requests. A compaction's summarizer
reports its usage on `compaction/summary`, which the projection does not fold
(upstream's own projection test appends that event and asserts the buckets hold
still). dshline reports that scope rather than adding accounting for it.

Session statistics are the fifth domain, and the first one dshline composes
itself. `@deepseek-ai/dsh-session-stats` publishes a single `sessionStats` unit
— whole-log `turns`, `steps`, `llmMs`, `toolMs`, `ttftMs`, `ttftSteps`,
`decodeMs`, `decodeTokens` — folded over the complete durable log, so a resumed
session reports the whole of itself rather than the part this process watched.
`dsh-base` does not mount it, and upstream's own TUI and headless assemblies
therefore serve no such key, so dshline's bundle patch inserts the row
host-plane, beside the frontend's own rows and **not** behind an agent preset:
the unit registers a pure fold, is model-invisible, and is keyed by session
rather than by agent, so preset ownership would make `/usage`'s performance
figures a function of which preset a session happens to run — and would register the same
unit once per mounted preset. What upstream demonstrates is narrower than that
argument: Harness's own Web bundle mounts this same official package as a
host-level bundle row for the surface that consumes it, its chat stats strip.
This row is that same treatment for a different reader — one bounded `/usage`
section — and the reasoning above is dshline's.

The presentation treats the unit as optional regardless, and that is the part
that matters. Package availability and capability availability are separate
concepts: the shipped frontend brings the plugin its own bundle mounts, as an
ordinary dependency, while a composition remains free to drop the row. A
profile that does boots, runs sessions, and reports its tokens, cache split, and
cost exactly as before; the performance section says in one line that the
profile does not mount Harness session statistics, or is omitted entirely when
there is no projection registry at all, because the section above it has already
said so. There is no fallback implementation: dshline does not recount the
session log, install a timer, replay events, or keep an accumulator of its own,
and the only arithmetic it performs over the projection is two averages —
`ttftMs / ttftSteps` and `decodeTokens / (decodeMs / 1000)`.

Two rules govern what is printed, and they are different rules. A derived figure
with no denominator is absent, because `0 / 0` is not an average. A summed wall
time of zero is also absent, and for a stronger reason: in this unit zero is the
absence of a contribution rather than a measurement of zero. `llmMs` accrues only
over the request wall time from `step/start` to an assembled `assistant/message`,
and `toolMs` only over a `tool/call` matched by its `tool/result`, so a step that
streamed and was then cancelled, and a call whose result never landed, both leave
their total at zero while real work elapsed. `model time 0ms` would therefore
claim a measurement Harness never made. The counts are the exception and stay
unconditional: `turns` and `steps` come from `step/end`, which the agent loop
appends in a `finally`, so a zero there is a real count.

Nothing interpolates between Harness's updates to make a value move more smoothly
than the projection itself does. The section is live because it reads the same
session-scoped observer cut everything else reads, on the redraw a projection
change already causes — and because `sessionStats` and `tokenUsage` are values in
one `ProjectionSnapshot`, the two projection-backed halves of `/usage` cannot
describe two different moments. The money beside them is not in that snapshot:
it stays dshline's own pricing fold, reported alongside rather than within.

Compaction follows the observation/control split. dshline reads the durable
`compaction/start`, `compaction/summary`, `compaction/end`, and
`compaction/prune` events to present what changed, including for an automatic
compaction that has no command lifecycle at all, and correlates a command
result with the event it names through `sourceEventSeq` — honoured only for an
event this frontend actually projects. Reduction itself stays the registered
`/compact` command's, which owns validation, the idle-agent lock, cancellation,
the durable lifecycle, and the persistence checkpoint. `compactRegion` exists on
the service and is deliberately not exposed: the human command is argument-free,
and a range-selection UI would be a control contract upstream has not defined.

Goal is a known projection domain with two authorities, and dshline reads each
from its owner. Everything durable — objective, phase, blocked reason,
`roundsStarted`, `maxGoalRounds`, revision, timestamps — comes from the `goal`
projection, out of the same session-scoped observer cut the status line already
takes for Todo and context occupancy, so Goal adds no second direct dshline
snapshot. The persistent footer projects only the goal's compact state and
progress; `/goal` is the inspection surface for its objective. `ctx.goals` answers
exactly one question, and is asked only where the answer can change the reading:
live, process-local continuation activation, for
a projected goal whose durable phase is `active`. That read is live and never
cached, because `disarm()` is process-local by design — it changes activation
with no `goal/change` event, no revision, and no `goal/changed` notification, so
no projection observer can reconstruct or own it. An activation that cannot be
obtained is never taken for `armed`: a resumed session holding a durably active
goal reports `goal idle` rather than claiming this process will continue it,
which is the one thing neither authority could say on its own. The explicit bare
`/goal` is a bounded read-only inspector over that same pair: it reports the
projection's durable fields and the live activation as separate facts, re-reads
both on every paint, and owns nothing but its scroll position. Its activation
repaint comes from the one global `goal/activation-changed` event, filtered to
this exact Session, because that edge publishes no projection frame for the
observer above to see.

The service call is a whole-view read because the adopted generation publishes
no activation-only accessor, and `GoalService.get()` resolves its own durable
half through `sessionProjections.stateOf(session, 'goal')` before combining it
with process-local runtime state. That inner read belongs to the service, not to
this frontend, and `.activation` is the only field taken from what it returns —
so the authority split is exact even though it is not yet physically narrow. An
upstream activation-only accessor would remove that service-side `stateOf()`
read and make it both. Plan remains governed by its documented Harness
authority.

### 3. Novel third-party capabilities

A third-party plugin can introduce a domain for which dshline has no native
adapter. That is the reason to eventually offer a small TUI contribution API,
not a reason to promise bespoke UI for every plugin. First we need several
internal adapters to establish authority, lifecycle, and layout rules.

`TuiSlots`, `TuiSlotView`, `TuiSlotName`, and `TuiOverlay` are experimental
pre-1.0 vocabulary. They are not a stable SDK, and no public API package is
committed yet. Persistent extension rows additionally need a global layout
budget; until then, capability UI belongs in bounded overlays.

**Composer and overlays share a visual root, not ownership.** The composer and
every temporary overlay draw through one shared frame — `dshline` on the left,
the workspace or the view's identity on the right, navigation help inside the
bottom border — so a browser reads as the composer expanded rather than as a
detached modal. The sharing is presentation only: while an overlay is mounted it
still replaces the entire live region and owns every keystroke, the composer's
buffer and cursor are not underneath it, and closing it restores the composer
untouched. The shared chrome is a pure helper with no state, no inputs beyond
what it renders, and no lifetime or view of Harness; input and state ownership
are not shared with it.

## Work: the first generic adapter

Harness Work is the first adapter following this model. It presents `ctx.jobs`,
`ctx.subagents`, and Harness workflow runs in separate sections through `/work`
and an optional status summary. It reads job snapshots with `list()` and
observes `onJobsChanged()`; it does not consume the model-facing `read()`
cursor. It observes subagent lifecycle edges and enriches only from
`listChildren()` facts that Harness publishes. It neither merges two authorities
without an authoritative correlation id nor invents labels or active runs that a
provider did not expose.

Three authorities, one projection layer:

```
ctx.jobs                        → Jobs
ctx.subagents                   → Subagents
tool-workflow/* + workflow/*    → Workflows
```

Workflows needed a second ownership rule, and that is why they are a separate
adapter rather than more branches inside the jobs/subagents projection. Job
reads answer per caller and subagent lifecycle edges are scoped to the
delegating parent, but a raw `workflow/*` event carries `{ id, meta }` — a run's
identity and never the Session that asked for it. Subscribing to that feed alone
would show another window's orchestration inside this one.

So ownership comes from the durable side. `dsh-tool-workflow` appends
`tool-workflow/run-start` / `agent-start` / `agent-end` / `run-end` into the
parent Session of a top-level run and nowhere else; a nested run started inside
a subagent records nothing. A run whose `run-start` reached the attached
session's own log is provably this window's, and live `workflow/*` events are
accepted only for a run those records already proved — as enrichment (the
description, the current phase, the newest log line, the terminal stop reason),
never as a second member store. Four of the six `workflow/*` events are
subscribed: `workflow/start` is emitted synchronously inside
`workflowEngine.start()`, so the gate drops it every time, and
`workflow/agent-end` fires only for a call whose `agent-start` already carried
the identical meta. Reconstruction is
live-feed only: a `run-start` left behind by a process that died is not evidence
that a script is executing now, and durable workflow history belongs to the
transcript.

That ownership rule also buys the one correlation Work makes. `WorkflowAgentInfo`
publishes each member's `childId` on the subagent seam, so a workflow member and
a subagent epoch are provably the same child; the member presents that child
under its workflow instead of repeating it in the flat Subagents section, and
navigating from the member reaches the same subagent presentation. No other pair
of records is joined, and a settled member releases the join.

The animation rule follows from the same discipline. The arc spinner means
dshline holds evidence of running computation — a live in-process child Agent
Harness reports as `running`. A Job in `running` is a registry record rather
than an observation, and a provider that publishes no in-process child exposes
no intermediate activity through the generic seam, so both stay static. A
workflow animates only while one of its own members does, because the engine
publishes no execution signal of its own between `agent()` calls. `ctx.workflowEngine`
exposes `start()` and nothing else a UI could reach, so Work observes workflow
runs and offers no control over them.

The manually validated Codex provider is an acceptance proof for these generic
contracts, not a direct dshline integration. Claude Code through
`@deepseek-ai/dsh-subagent-claude-code`, `ctx.subagents`, and `ctx.jobs` is the
logical next target, but has not been manually validated. The required path for
both and future providers is documented in [Provider acceptance](provider-acceptance.md).

## Durable subagent conversations: the fourth adapter

Work represents **open lifecycle epochs**. A continuable subagent is also a
durable conversation, and the important case is exactly the one an epoch cannot
show: the child finishes its current turn, its epoch ends, and the user still
wants to inspect it and send another instruction. Folding that into `HarnessWork`
would also make `activeWorkCount()` — which gates retiring a session — treat a
settled child as active work.

So `/subagents` is a second, narrow adapter with its own presenter, keyed by the
**durable child session id** rather than a lifecycle `runId`:

```
ctx.subagents.listChildren   → durable direct-child catalog
ctx.sessionQuery             → one child's bounded session window (no resume)
ctx.subagents.prompt         → human queue / steer
```

Discovery is `listChildren(parentSessionId)`, whose rows are Harness facts:
durable id, label, `one-shot` versus `continuable`, session-store residency, and
whether the child has children. A diagnostic row is kept rather than dropped, so
a corrupt or unreadable candidate degrades honestly. Opening a child reads its
own log through `ctx.sessionQuery.listEvents` and one bounded `readEvent` window
and renders each event with Harness's `extractSessionEventText`; the child is
never resumed or published to inspect it, and moving the cursor never reads a
transcript. Both `[` older and `]` newer **replace** that window rather than
appending to it, so the inspector holds at most one page of 24 full event bodies
and one lightweight seq index, which is metadata, not bodies. Both directions
stay inside the captured index; newer reads anchor at the destination slice's
last seq with preceding context and `after: 0`, so appended events cannot leak
into navigation. Only `r` refreshes with `listEvents` and a newest bounded read.
Paging preserves the stale hint; a failed read retains the loaded page, and the
newest-started read wins if navigation races a refresh.

A human follow-up is the one place this frontend must be careful about which
Harness operation it calls. `SubagentRuntime.sendMessage(sender: Agent, …)` is
**model-authored** adjacent-Agent messaging: it takes an exact live `Agent`
sender and stamps `agent-message` provenance, so a terminal calling it would
impersonate the parent Agent. The human path is `ctx.subagents.prompt`, which
carries a durable parent/child address, a client-minted request identity, human
`kind: 'user'` provenance, the `queue`/`steer` choice, cold materialization, and
an accepted `MessageId` receipt. dshline's `HumanSubagentSeam` is a `Pick` of
`SubagentRuntime` with only `listChildren` and `prompt`, so reaching for
`sendMessage` fails type-check rather than shipping; a comment- and string-aware
source scan backstops that against a cast.

Acceptance is Harness's, so the field's `queue` and `steer` mean exactly what
Harness defines: a queued later turn, or the nearest step (starting a turn when
the child is idle). The terminal inserts no optimistic row — the message appears
in the child's transcript only when its own session log records it.

The durable inspector deliberately offers **no interrupt**. `listChildren()`
reports session-store residency, not proof that a turn is executing, and
Harness's `interrupt()` treats an absent or already-settled target as an
accepted no-op; offering the action here could therefore claim a cancellation
that never happened. Interrupt stays on `/work`, where an open lifecycle epoch
is the stronger premise, and through its existing human adapter.

## Sessions: one corpus, and two lifetimes

Sessions is the third adapter, and it reads exactly one authority. `ctx.sessionQuery`
already publishes a live-preferred logical corpus that merges `ctx.sessions` with
whatever persistence is mounted, so the browser lists `listSessions()` records and
folds their titles with one batched `readTitleSnapshots()` observation. There is no
sessions-directory scan, no title cache, and no second index; a frontend index
would disagree with the corpus the first time either changed.

Those two reads are the whole cost of browsing, which is a presentation decision
rather than a lucky one. The browser is a PICKER first: a row is the title and
the relative age, because those are the two facts that answer "which session,"
and every other fact competes with the answer. Workspace, origin, availability,
lineage, event count and session id are disclosed for ONE session behind `→`.
That is also where `listEvents()` is read. An event count and a last-activity
time cost a whole log load and surface fold, so a list that shows them has to
take that read every time the cursor moves; the disclosure is the surface that
presents them, so opening it is what pays for them. Filters answer a question
about the corpus rather than about a row, so they are a browser-level `ctrl-f`
— a ctrl gesture because every printable character here is already search input.

### `/session`: the attached conversation, not a catalog row

The terminal-local `/session` hub completes the navigation hierarchy:
`/worktrees` asks where, `/sessions` asks which conversation, `/session` asks
about the one attached here, and `/turns` asks which turn. It reads the attached
agent's live `Session` and immutable header directly, along with `ctx.sessionTitle`
and the optional `sessionStats` / `turnOutline` projection values. It does not
round-trip through `ctx.sessionQuery` merely to identify the current session or
build its summary.

The hub is only a router to established presentation: Find in conversation uses
the one-session query and bounded event-context reader, Turns uses the existing
turn outline, Lineage uses `traceSession`, and Rename uses `ctx.sessionTitle` on
the attached live Session. Each row is omitted when its owning capability is not
mounted; absence is not replaced with a local fold or a disabled promise.

Query cost follows the action boundary. Find submits `searchEvents` only after its
query is submitted and reads event context only when a result is selected; Lineage
calls `traceSession` only when that action is activated. Opening the hub, moving
among its rows, and reading its attached-session facts make neither query call.

Archive is Harness's, and dshline does not present it. `ctx.workspaceRegistry`
owns a durable registry-global archive set and `archiveSession()` adds to it,
but upstream records that archiving is one-way and no unarchive operation exists
yet, and the archive set is not a `ctx.sessionQuery` fact — `SessionRecord`
carries no archive field, `SessionResultFilter` has no archive predicate, and
the only stream of archive changes is the Workspace controller's Remote
`follow()`. Offering Archive would hand a reader an irreversible hide; hiding
archived sessions would take them out of the one surface that can still resume
them, and would require a second corpus authority to know which ones they are.
Both wait for a symmetric upstream lifecycle.

The engine's two full-text methods are its ONLY abstract surface, so content
search is an optional capability rather than a guaranteed one. A deployment whose
backend implements none reports `SESSION_QUERY_SEARCH_DISABLED`, and the browser
keeps filtering the rows it already has while saying that content search is off.
Filtering is not a private index: it matches the text a row already displays.

Sessions also forced a lifetime split the frontend did not previously need:

```
window        terminal, key routing, model route, reader preferences
   ↓ attaches
attachment    one Agent, its log projection, its capability adapters, its views
```

While a launch drove exactly one session for the life of the process, the plugin
fiber and the session were the same lifetime, and `ctx.effect` was the right
owner for everything. Reopening a session in place breaks that identity: the slot
registrations, the log listener, the spinner, and the Work and projection
adapters all describe one session, so they belong to a `SessionScope` that comes
down before its agent handle does. Key routing moved the other way, up to the
window, which is also why `ctrl-d` now quits from the launch browser without that
browser owning a keyboard of its own. The window remains the global quit owner; an
attached session supplies only a cancellation-aware prelude that cancels its own
async work and tears down presentation before interrupting the Agent through its
public cancel seam. It then requests `ctx.appExit`; Harness still owns AgentHandle
teardown, tree disposal, persistence, and final process shutdown.

Reopening uses the supported lifecycle and nothing else: the owned
`AgentHandle.dispose()` retires the current agent — the handle is this
frontend's capability because this frontend created the agent — and
`ctx.agents.resume` opens the next one. The transcript is appended into native
scrollback under what is already there; nothing committed is rewritten. A
rejected resume neither ends the process nor substitutes a session: by then the
previous agent is already retired, so the window commits Harness's reason and
asks again through the same browser. Dismissing it cancels the opening: the
loop exits the window rather than starting a session nobody asked for.

## Worktrees: the working directory is a different question

Sessions answers "which conversation". It cannot answer "where", because a
`cwd` is a field on a session header rather than a thing with an identity, and
several conversations share one. So `/worktrees` asks the level above — and
reads the same authority to do it:

```text
ctx.sessionQuery.listSessions()   the logical corpus: a fresh
                                  sessionPersistence.list() merged with this
                                  process's live sessions, newest first
      ↓ group by exact SessionHeader.cwd
worktree rows                     transient; alive only while the picker is
      ↓ select one                open, and stored nowhere
SessionCatalog { kind: 'cwd', cwd }
```

**A row is a definition, not a record.** It IS "the sessions whose header
records exactly this cwd", which is why it needs no id, no title, and nothing
durable: the grouping key is the definition. The count in the first view and
the rows in the second are therefore one relationship read twice, not two
authorities compared — and a fresh session needs no follow-up write at all,
because Harness stamps `cwd` into its immutable header and that header is the
rule.

**Why the session corpus and not the Workspace registry.** Harness does own a
durable Workspace entity (`ctx.workspaceRegistry`), and it was the first
instinct here. It is the wrong ownership model for THIS feature at the adopted
generation, and the reason is upstream's own documentation rather than a
preference. `/worktrees` exists to serve several dshline processes working in
several directories at once, and the durable domain stack the Workspace domain
sits on is single-process: `dsh-storage-domain` records that memory is
authoritative for an open domain and that `domain/changed` is in-process, so "a
second host process or a reconnecting GUI observes no changes";
`dsh-storage-json` records "no cross-process write locking", with concurrent
writers to one unit resolving last-completion-wins. Several terminals each
mounting and mutating that registry over one Harness home would hold stale
in-memory state and overwrite each other.

Session persistence is the opposite shape, and it is the shape this feature
needs: one artifact per session, one live writer per SESSION, and a fresh
`sessionPersistence.list()` on every corpus read. Distinct sessions in distinct
directories are exactly what it already models well, so the multi-terminal
workflow rides on the surface that was built for it, and dshline introduces no
shared mutable state of its own.

**One root Session per window survives.** A choice resolves to one of the two
attachment targets that already exist — `{ kind: 'resume', id }` or
`{ kind: 'new', cwd }` — and goes through the same retire-then-attach
transition `/sessions` and `/new` use, under the same `planResume` / `planNew`
refusals. `sessions/reopen.ts` gained no field and no domain knowledge for
this. There are no tabs, no panes, and no second live agent; parallel work
across directories is several terminals, each rooted in its own.

The second view is the very `SessionCatalog` `/sessions` uses, not a second
browser. That is what made the catalog's workspace scope an arbitrary exact
`cwd` rather than "this window's directory": `/sessions` supplies the attached
session's own workspace and `/worktrees` supplies the selected group's key, and
both reach `filterSessions` through one translation. Because the group is
DEFINED by `SessionHeader.cwd === cwd`, that filter is not an approximation of
the grouping — it is the grouping.

**Path identity stays Harness's.** The grouping key is the stored `cwd` string
exactly as Harness wrote it. dshline does not `realpath` it, join it, or
normalize it, so two spellings of one directory remain two rows if sessions
really were created with two different strings. That is deliberate: a frontend
inventing path identity would be a second canon, and the visible path already
tells a reader what happened.

**Discovery is a consequence, and its limit is documented rather than filled
in.** A directory appears because Harness has a session in it. A Git worktree
created and never worked in does not appear; starting dshline there puts it on
that window's list immediately through the corpus's live half, and once the
conversation has persisted the other windows find it through the persisted
half. The JSONL backend materializes a session lazily, so a conversation that
produced no durable history yet may not have reached another process — which is
acceptable, and is not a reason for a second discovery database. There is no
`git worktree list` here and nothing read under `.git`.

**Git owns Git.** A row carries a path and a session count. It carries no
branch, HEAD, dirty flag, lock, or prunable marker, and no enumerate, create,
or remove action, because the adopted generation publishes no Git or worktree
capability at all. The picker also takes no filesystem status check of its own:
if a chosen directory has gone, Harness's own session creation reports it
through the ordinary recovery path rather than a second truth about the
filesystem living in a browser. The transient cwd-group model is shaped so an
optional upstream capability publishing structured worktree facts can be
reconciled with it later; until one exists there is no `ctx.worktrees` here,
and no subprocess standing in for it.

**"Running" is used precisely, and the limit is a requirement rather than a
guard.** The persisted corpus deliberately includes sessions other dshline
processes created, and navigating them is the point. But `SessionRecord.live`
means live in the process that asked, `ctx.agents` is process-local, and the
adopted generation publishes no cross-process ownership or liveness contract —
so `current` marks the directory THIS window's session is rooted in and claims
nothing else. No row says "live in another terminal", "safe to take over", or
"idle in another process".

What Harness enforces is narrower than it first looks, and the distinction
matters enough to write down. `SessionPersistenceCoordinator` refuses to
prepare a session that is live — `prepare()` throws `cannot prepare session
"<id>" while it is live` — but the fact it consults is `this.ctx.sessions`,
which is this process's own store, and its serialization, live-owner, and
retirement bookkeeping are in-memory maps on one backend instance. The shipped
JSONL backend states the rest as a REQUIREMENT on callers, not as an
enforcement: "another instance or process must not write the same session until
that owner reaches quiescent disposal". There is no lease, pid owner,
heartbeat, or advisory lock anywhere in the session or storage packages at this
revision. (POSIX first materialization does use `link()`, so two processes
racing to create the same NEW id collide safely — but that says nothing about
reopening a session whose log already exists.)

So the honest reading is: this refusal is process-local, and dshline cannot
tell whether a persisted session is currently open in another dshline process.
It does not claim otherwise, and it does not invent the missing contract — no
pid files, lock files, heartbeats, sockets, process scanning, or cross-process
agent discovery. The user-facing consequence belongs in documentation rather
than in a badge on every row: do not drive one session from two processes at
once. This is `/sessions`'s limitation too, and `/worktrees` makes no stronger
promise than it does.

## Connect: configuration is four seams, not one

Provider configuration is where a frontend is most tempted to grow its own
opinions — a provider list, an OAuth implementation, a file it writes keys to.
Harness already owns all of it, in four separate surfaces that answer four
different questions:

| Question | Authority |
| --- | --- |
| Which provider routes can be configured at all? | `ctx.llm.listConfigurableProviders()` |
| Which are registered right now? | `ctx.llm.listProviders()` |
| How is one configured, and at what revision? | `ctx.settings.describe()` / `mutate()` |
| Is the secret it names present, and writable? | `ctx.credentials.describe()` / `set()` |
| How is a credential *obtained* when it must be asked for? | `ctx.authorization` |

`/connect` is the join of those and nothing else. Three consequences follow, and
each is the reason a shortcut was refused:

**No provider registry.** A route reaches the browser because a mounted adapter
declared it configurable — which a bare-mounted `llm-pi-ai` does for its whole
installed catalog before any route exists. dshline ships no list of provider
names, so an adapter that adds one is presented without a code change here.

**No field-name knowledge.** Storing an API key needs to know which profile
property carries the credential *reference*, and both shipped adapters call it
`apiKeyEnv`. dshline does not: it reads the namespace's serialized schema from
`describe()` and takes the property whose schemastery role is `credential-ref`.
The role is the contract; the name is a coincidence.

**No login protocol.** `ctx.authorization` renders as one notice shape and three
prompt shapes — `text`, `secret`, `select` — which is deliberately smaller than
any provider's own vocabulary. A surface that renders one flow renders all of
them, so OAuth, device code, and a key typed into a provider library's prompt
all arrive here as the same interaction. The terminal-specific decision is only
*where* each half goes: a notice is committed to native scrollback, because a
sign-in URL and a device code are the two things a person most needs to select
and copy, while a prompt is a bounded overlay because it takes the keyboard.

The browser owns the lifetime of what it starts. An authorization attempt can
sit waiting on a browser callback with no prompt mounted, so closing `/connect`
aborts the attempt's signal — the seam settles it as `cancelled`, any mounted
prompt comes down with it, and a later notice or prompt from a flow that has not
yet observed its signal is dropped rather than drawn over an unrelated
transcript.

Because both surfaces write the same namespace and the same reference, a change
made in the terminal is visible on the official web Models page and the other
way round. Neither has a store of its own to disagree from. The
`<ROUTE>_API_KEY` derivation for a route whose profile names no reference yet is
shared for exactly that reason.

`/connect` still does NOT merge its two sections. A configurable-provider
entry is addressed by `settingsNs` plus a route key; an authorization flow is
addressed by a `CredentialKey` whose scope is its owning plugin's registered
name. Harness publishes no contract that the two must correspond in general, so
merging the rows would be the frontend inventing a correlation — the same
refusal Work makes when it keeps jobs and subagents apart. Both are listed,
each under the identity Harness gave it.

What did change is the claim, not the refusal. One adapter family documents the
correspondence for ITSELF, on both sides: `dsh-llm-pi-ai`'s `recordKeyFor`
builds `llm-pi-ai/<providerId>` and calls that id "pi-ai's own provider id,
which is also the harness route key", while its `directoryEntries` publishes
the same id at `providers.<id>` in the same namespace. Reading one family's own
published identity is what `connect/pi-ai.ts` exists to do — it already holds
the curated field names and the declaration target for exactly this reason —
so `piAiSignInRoute` lives there and `connect/model.ts` stays generic, holding
a `route` field a presentation module may fill and deriving nothing. The link
is verified rather than assumed: a key resolves only against routes the
directory actually published, at the address it publishes them at, so a scope
that stops naming this namespace or a namespace that moves its routes both
answer "unknown" and leave the sign-in standing alone.

That link exists because the two writes are genuinely separate and both
required:

```
ctx.credentials   the RECORD an authorization flow commits   llm-pi-ai/openai
ctx.settings      the PROFILE that registers a route         llm-pi-ai.providers.openai
```

`registerPiAiFlows` offers a login for every installed catalog provider
"independent of the route set", while the adapter registers routes only for the
profiles settings supply. Both halves are right, and together they produce the
one failure this frontend most needed to explain: a person signs in, the flow
reports success, and `/model` still has nothing. `connect/activation.ts` is the
missing sentence and nothing more — it offers `Activate this route`, the action
the browser already had, against a FRESH reading, and writes only when a human
picks it. **A successful authentication is not consent to change provider
configuration**, so a dismissal, a `Not now`, and a closed browser all leave
settings untouched; and judging from a stale snapshot would mean writing an
empty profile over a route something else configured in the meantime.

### The authorization seam is a row dshline composes

At the adopted generation no shipped Harness bundle mounts
`@deepseek-ai/dsh-authorization` — not `dsh-base`, not `web-app`, not
`headless`, not `acp-app`, and not the `dsh` app itself. The one package that
registers flows into it scopes that registration to the seam's presence
(`ctx.inject(['authorization'], …)`), so a composition without the row has no
account sign-in for any provider: `/connect`'s Sign-ins section is permanently
empty and an account-authenticated provider is unreachable from a terminal.

dshline's own `cordis.patch.yml` therefore inserts it, exactly as it inserts
`session-stats` and for the same stated reason — a host-plane seam this surface
reads that the base does not carry. That is composition, which is what a bundle
is for; it is not dshline implementing, wrapping, or installing anything. The
seam and every flow remain Harness's.

The alternative was considered and rejected. `dsh-authorization` declares no
`dsh.bundle`, so `dsh plugin add` would install it as a plain dependency that
composes nothing — the "installed but inert" state `/profiles` already reports
— and finishing the job would mean dshline writing a composition row into the
profile's own `cordis.patch.yml`, a patch layer no Harness mutation API owns.
A first-run installer for a capability a bundle can simply compose is a second
lifecycle where none is needed.

Because the row is now dshline's to mount, its shape is dshline's compatibility
problem too: `tests/capability/authorization.probe.spec.ts` mounts the real
`AuthorizationService` over a minimal local credentials service implementing
its published record surface, and `tools/capability-probes.mjs` names that
orchestration as the `authorization` seam's evidence. The separate credentials
probe covers the abstract `CredentialProvider` contract; neither fixture claims
production storage policy.

The seam surfaces themselves are written out structurally in
`connect/harness.ts` rather than depended on as whole services, for the reason
`SessionQueryReads` gives — naming the calls a view makes is more legible than
depending on a whole service. Every import in that file is still type-only, so
Connect carries no Harness code at runtime; three assignments in
`connectSeams` check each narrow view against the real service on every build,
because each service package augments `Context` with its own type.

### Connect 2.0: one route can be a declaration, not only a lookup

`listConfigurableProviders()` says which routes an adapter already knows how
to activate. It says nothing about a route that does not exist yet — a
private gateway, a self-hosted server, a localhost OpenAI-compatible
endpoint — because nothing in `LlmConfigurableProvider` marks "this namespace
accepts a key it has never seen." That gap is real on current Harness: there
is no generic seam a configuration surface can ask "may I declare a brand-new
route here," and the official web Models page closes it the same way this
frontend does — by knowing, specifically, that `llm-pi-ai`'s settings profile
can describe a whole provider route.

A schema shaping a namespace's routes as a `dict` — the shape that means "one
element node describes every key, seen or not" — proves only that arbitrary
keys are structurally accepted there. It does not prove that writing one
declares a new LLM route: a future adapter could publish
`providers: dict<ProviderConfig>` while still only recognizing a fixed set of
keys, and the schema shape alone would say nothing to the contrary. `/connect`
does not let that inference cross into generic code. `connect/model.ts` keeps
`ConnectNewRouteTarget` as a plain data shape — a namespace, a parent path, a
revision — and asserts nothing about which namespaces it is safe to produce
one for; it is never derived there from schema shape alone.

That determination is made once, inside `connect/pi-ai.ts`, which is the one
module allowed to know that `llm-pi-ai` specifically is a domain whose
settings profile can describe a whole provider route.
`piAiDeclarationTarget()` filters the directory to `llm-pi-ai`'s own entries
first, then checks that they agree on where their dict sits, that the schema
there really does shape it as a `dict`, that the curated `baseURL` field is
still reachable, and that a protocol choice can still be derived — the same
schema-shape check `protocolChoices()` makes, because a namespace this module
cannot offer a protocol for is one it cannot safely declare a route into
either. Any one of those failing means the schema drifted from what this
presentation module knows how to read, and `+ Add custom provider` is offered
only when every check passes — never a row that is guaranteed to fail partway
through the wizard, which is the same "no offer known to fail" rule the rest
of Connect already follows for its ordinary actions. If another Harness domain
later published its own declaration seam, `piAiDeclarationTarget()` is the
function to replace, not `connect/model.ts`.

Knowing an address exists is not the same as knowing what to write there. A
curated editor needs field names — "base URL", "protocol", "request headers",
"model catalog" — that no generic seam publishes, so presenting them at all
means knowing one namespace's shape. That knowledge is isolated in
`connect/pi-ai.ts` alongside the declaration check above, and:

- names its curated fields as plain strings (`displayName`, `baseURL`, `api`,
  `headers`, `models`, and the per-model `name`/`contextWindow`/`maxTokens`/
  `input`/`reasoningEfforts`), and reads every CHOICE and VOCABULARY from the
  namespace's own serialized schema — protocol choices from a `z.union` of
  string consts, input modalities from the same shape, reasoning levels from a
  dict's declared key union, the explicit-disable branch from the union's
  `const(false)` — rather than a dshline constant, so a protocol, modality, or
  thinking level `dsh-llm-pi-ai` adds later needs no change here. The test for
  which fields earn a terminal form is what a route can REACH and what a
  deployment must be able to state; `compat`, retry policy, timeouts, and
  operational budgets still stay out;
- reads the SHAPE of a curated field from the schema even where it hard-codes
  the name: `headers` is offered only while the namespace still describes it as
  a dict of strings, the same fail-closed check that makes an unreadable `api`
  union produce no protocol choices rather than a stale list;
- writes through the same `ctx.settings.mutate()` path ops every other Connect
  action uses — one `set`/`unset` per changed field, never a wholesale
  replace, so `compat`, retry policy, and anything else this pass does not
  render survive an edit untouched;
- never imports `@deepseek-ai/dsh-llm-pi-ai` at runtime, registers no
  provider, parses no model output, and makes no network request. Harness
  still does every one of those.

The create wizard itself fails closed the same way its declaration check
does: if the protocol choices it derives at the moment the wizard opens turn
out empty — schema drift between the row being shown and the wizard actually
starting — it refuses immediately rather than writing a guessed `api: ''`
Harness would reject several steps later with a less useful error. And the
wizard never persists mid-flow: every field, including the model catalog, is
collected into an in-memory draft first, and only an explicit "Create
provider" on a final review — Provider ID and every other field shown back,
the API key only ever as "configured" or "not set" — triggers the first
write. Leaving the model submenu without adopting anything, in particular,
changes nothing: a route that inherits its catalog stays inherited until a
real edit happens, and that edit is written as `modelOverrides.<id>` — never
by materializing a `models` list the route did not have.

`connect/model-editor.ts` and `connect/route-editor.ts` sit on top: the first
is pure draft logic for a model list (adopting a discovered candidate without
overwriting a hand-corrected capacity, telling an inherited catalog apart from
an explicit one), and the second sequences the same `promptSelect` /
`promptText` overlays every other Connect action already uses into two small
menu loops — editing an existing route and declaring a new one — rather than a
bespoke form overlay.

Where the two catalogs differ is what a model edit WRITES. A route whose
profile carries an explicit `models` list writes that whole array back, with
every uncurated field (including `compat`) carried through each entry. A route
that serves no list — which is what an absent `models` key and `models: []`
both mean to `llm-pi-ai`; the schema materializes the former as the latter —
writes only the exact `modelOverrides.<id>.<field>` paths the reader actually
edited, so correcting one model leaves the rest of the catalog serving
untouched and leaves every field of that model the reader never opened at
whatever the current revision holds. The draft tracks that intent as a
per-entry set of changed fields, not as a diff of whole values: a field shown
but not touched is not a write, and a second save after a revision race
reapplies exactly the touched paths rather than a stale snapshot. An id the
reader removed is one whole-id `unset`; an id appearing for the first time is
one whole-value `set`, because it has no stored sibling yet. The two catalogs
are never written into one profile, and an override never carries an `id`,
because the adapter refuses both. The mode is read from the EFFECTIVE resolved
profile, while which overrides belong to the user layer is read
field-presence-wise from `descriptor.user` — the resolved value has schema
defaults applied, so it cannot tell a stored key from a materialized one.

Numeric fields are checked against the bounds the owning schema declares
(`min`/`step`), not against a rule written here: a schema that allows zero, or
a fractional step, is honored as written. The reasoning mapping's vocabulary
and its accepted value shape are read the same way — the level keys from the
dict's key schema, and whether one level's value accepts a string and/or null
from the dict's element schema. A leaf shape this walk cannot classify hides
the mapping editor instead of guessing, and WHICH levels may carry a null
value remains the adapter's own semantic rule: this frontend offers the shape
the schema publishes and shows Harness's refusal when a mapping it built is
not one the owner accepts. It keeps no second copy of that rule.

A rejected save keeps its draft. `connect/route-editor.ts` recognizes the
settings seam's `SETTINGS_CONFLICT` code structurally — no runtime import of
the error class — re-reads the descriptor and the configurable-provider
directory, and waits for a second explicit Save against the fresh revision;
there is no automatic retry, because a retry would apply an intent formed
against a state the reader never saw. A route deleted underneath the editor is
not resurrected: the draft stays on screen for inspection and the reader is
told to back out and add it again. What Harness refuses for a semantic reason —
a reasoning mapping the owner will not accept, an override on a model the
installed catalog does not describe — is shown verbatim and leaves the draft
intact; this frontend holds no second copy of that validator.

Three things that look similar are deliberately separate. A model's
`reasoningEfforts` is a DEPLOYMENT capability and wire mapping, written by
`/connect` into the provider profile. `/reasoning` is the AGENT's request
preference for a session. `/thinking` is display only. Connect therefore never
changes the Agent default selection or the session's reasoning choice, even
when the edited model stops supporting the level that choice names.

Model discovery is advisory, and stays that way by construction:
`ctx.llm.discoverModels()` takes a draft (`provider` for an existing route, so
the owning adapter resolves its own stored credential without this frontend
ever reading one back; a one-shot typed key for a route that does not exist
yet) and answers candidates. A candidate whose id is already in the draft is
left untouched — an endpoint listing carries at best an id, a name, and two
capacities, never more than a row a person already corrected knows — and
nothing fetched is written until the reader explicitly saves.

The result is the shape the acceptance test is built around:

```
custom endpoint
    ↓
Harness settings  (ctx.settings.mutate through connect/pi-ai.ts's path ops)
    ↓
llm-pi-ai         (resolves the declared profile into a live provider)
    ↓
ctx.llm provider route
    ↓
dshline /model
```

never:

```
custom endpoint
    ↓
dshline client
```

dshline performs no provider HTTP request, owns no secret beyond the one-shot
value it hands to `ctx.credentials.set()` after an explicit create, and keeps
no second state store: a created route is addressable, editable, and
removable through the exact same seams every catalog route already goes
through.

## Presets: composition is Harness's, not dshline's

An agent preset is Harness's own answer to "what can this agent do" — a named
composition of tools, prompt sections, and delegation backends, resolved
through `ctx.agentPresets` and joined to an agent at the one supported point
in its lifecycle, `setup(agentCtx, agent)`. `/plugins` is the terminal presentation
of that seam: it lists the roster, shows the rows the running agent's preset
actually composes, and carries out a change through the same authority a
change made from the official web interface would use. It keeps no plugin
registry, no capability list, and no provider-specific branch of its own —
exactly the rule every other adapter in this document follows, applied to
"which tools does this agent have" instead of "which providers can it talk
to."

**System presets are Harness's, and stay read-only here.** A preset shipped
with the deployment carries `system` trust; `/plugins` never edits that file.
Customizing one is Harness's own supported path — copy it to a new, locally
authored preset (`ctx.agentPresets.copy()`) and edit the copy — and pressing
space on a built-in preset's row is the terminal's offer to do exactly that,
never a shortcut around it. A user-authored copy has no narrower Harness
mutation API than its own composition file, so toggling one row there is the
smallest edit that touches only that field and leaves the rest of the file
alone; Harness's own health check on that preset, not a private read of it,
still decides whether the result is usable.

**Session composition is a lifecycle fact, not a setting this frontend
keeps.** A new session composes from the roster's current default. A resumed
session composes from whatever its own log recorded — the preset it was
created with, or a later switch made while it was still blank — never
whatever the default happens to be *today*; a produced session's tool set is
history, and treating it as a live setting would let it drift out from under
a conversation that already happened. Which preset that is, is read from
Harness's own `agentPreset` Session projection, which folds the creation
header with every later selection; dshline reconstructs nothing from the raw
log, so the resume path and `/plugins` cannot disagree about what a session
runs.

**Offering an action and authorizing it are different jobs.** Switching a
session's preset is Harness's whole operation — `ctx.agentPresets.select()`
serializes selections per session, re-reads the authoritative `turnBoundary`
projection inside that queue, refuses a started session, recomposes, and
records the switch only once the recomposition committed. `/plugins` calls it
and reports the answer. What this frontend still decides is only what to put
in front of a reader: a started session is offered the *default for the next
session* instead of a switch it cannot have. That offer reads the same
`turnBoundary` projection Harness re-checks, at the instant it is acted on
rather than from the reading a keystroke was decided against — an action here
holds its own awaits, two prompts a human answers, a file write, a Harness
re-resolve, and a turn beginning across them must move the answer. It is a
presentation decision that happens to agree with the authority, never a
second copy of it.

Where that history cannot be placed exactly, the gap is named rather than
papered over. A session produced before dshline adopted presets recorded no
preset at all, and resumes under the shipped `standard` — the preset built to
mean the exact flat tool set every such session actually ran under. A
deployment shipping no usable `standard` has no honest equivalent, so the
resume falls back to that deployment's own default and reports the
substitution into the transcript. Refusing the resume outright would protect
a composition record by withholding the transcript it belongs to, which is
the wrong trade: the reader can see a caveat, and cannot see a session that
will not open.

This is also why dshline's own composition changed shape to adopt it. Before
presets, dshline mounted `dsh-base`'s full tool set once, for the process —
correct for a frontend with nothing to switch between, but nothing for a
composition-browsing command to browse. Every per-agent row `dsh-base` used to
mount unconditionally now moves behind whichever preset an agent actually
joins, the same "agent plane moves behind agent presets" step Harness's own
Web bundle already took for the identical reason; process-wide services with
no per-session meaning — registries, the sandbox and approval stack, the
token meter — stay exactly where they were.

## Profiles provide; presets expose

Two Harness layers answer two different questions, and conflating them is the
mistake this frontend is built to make visible.

```
profile   what the HOST can do    dsh.profile.bundles → patch layers → the composed tree
preset    what an AGENT may see   agent.cordis.yml rows → one agent's tools and prompt
```

A profile is chosen by the launcher and applied once, at boot. A preset is
chosen per session and can be recomposed while a session is still blank. So
`/profiles` and `/plugins` are not two views of one thing: they sit on either
side of a boundary, and every difference between them follows from it.

**A row being enabled proves only the second half.** The shipped `standard`
preset says so beside its own optional delegation rows — "Install the matching
Bundle in this Profile and restart the Host, then copy this preset and remove
`disabled` from the matching tool row. Host availability alone grants no tool."
The reverse is easier to hit by accident: enabling a row whose bundle was never
installed yields a preset that mounts, a tool the model can see, and a
delegation that fails on first use. `/plugins` closes that gap where it can be
*proven* — a row naming a provider a mounted Host registry does not supply is
marked, and the row's own state is left honest. Where it cannot be proven,
nothing is claimed: the check is a data table of capability modules, so a
module it does not cover, a `!!js` provider it never evaluates, and a registry
this profile does not mount all produce no verdict rather than a guess.

**Restart is part of the boundary, not a caveat about it.** `/profiles`
performs bundle changes through `dsh plugin`, Harness's own package lifecycle,
and then says what it did and did not affect: a change to the running profile
reports `restart required`, a change to any other names the command that picks
it up. Switching profiles is not offered at all, because no seam re-links a
composed Host's bundle layers and inventing one would be exactly the competing
lifecycle this document forbids.

### The launcher's one lifecycle decision

`bin/dshline.mjs` is a launcher wrapper, and it touches lifecycle at exactly
three narrow points, each because leaving that state to Harness produced a failure
a user could not act on. It asks one question and, when the answer is yes, runs
one Harness command — `dsh plugin --profile dshline add @dshline/dshline` —
through the same launcher an ordinary start uses, then continues into the launch
that was originally asked for. It writes no profile file, never reads a package's
`dsh.bundle` declaration, and never resolves a package itself: those belong to
`dsh plugin`, which already initializes a profile on first use and reconciles
`dsh.profile.bundles` against what is actually installed.

The first point is **a prerequisite, checked before any mutation.** Harness
installs a profile's plugins with pnpm, so a machine without it created the
profile and stopped at `'pnpm' is not recognized`. The wrapper asks PATH whether
pnpm is reachable — a lookup, not a probe, for the reason the launcher lookup is
one — and refuses before creating anything, naming the mechanism the launcher came
from: `corepack enable pnpm` for a checkout, which declares the pnpm version it
wants in its own `packageManager`, and `npm install -g pnpm` otherwise.

The second and third points are the profile state, and the boundary there is one
question asked of one dependency: **does this profile record dshline's own
package, at dshline's own release?** A profile with no `package.json` is
**uninitialized** — the same test `dsh plugin` itself applies — and setup is
offered. A profile that records this package at this release is launched. A
recorded spec naming a folder or a VCS source is launched too: someone already
made that decision, and a path has no release to disagree with. The two states
left between them are reported instead of launched into, and each is a failure a
user has already met. A manifest with no dependency on this package is a setup
that stopped partway, which opened a blank terminal and waited, because Harness
never gets far enough to complain about a profile nothing was installed into. A
recorded release that is not this wrapper's is a profile an upgrade left behind,
which died inside Harness on `cannot get property "agent" without inject`. Both
are answered with `dshline --setup`, and on a terminal the wrapper offers to run
it, which is the same question a first run already asks.

Everything else about a profile stays Harness's judgement. A coherent bundle
list, a resolvable `node_modules`, a third plugin's breakage, a profile that fails
to boot for any other reason: launched anyway, and Harness's own loader says what
is wrong. Repairing those here would mean guessing at a diagnosis Harness makes
authoritatively and hiding it behind a package operation nobody asked for — and
reading them would be the second Harness dependency resolver this document
forbids. An explicit `--profile` — including `--profile dshline` — turns the
behaviour off entirely: the caller is using harness profile semantics directly, so
the wrapper adds nothing to them. It is also the documented way past either
diagnostic.

**dshline does not serialize or repair Harness profile mutations.** Concurrent
package mutation is Harness's to define; dshline delegates the setup it was given
permission to run and treats the harness's success or failure as authoritative —
a failed setup fails that invocation and launches nothing. So two overlapping
first runs each delegate, rather than one of them deciding the other's install is
finished. That decision has no honest local answer: `dsh plugin` writes the
profile manifest *before* it installs, so the file proves a setup began and never
that one completed, and telling the difference would mean reading dependencies,
node_modules, or bundle state — the profile health the paragraph above leaves to
Harness. A lock under `$DSH_HOME` would be the competing lifecycle this document
forbids.

## Setup: a conductor, not a wizard

Two things stand between installing dshline and sending a turn, and they live
on opposite sides of one boundary. `bin/dshline.mjs` can create the profile and
nothing else — it runs before any Host exists, so `ctx.llm`, `ctx.settings`,
`ctx.credentials`, and `ctx.authorization` are all out of reach, and reaching
for them would make the wrapper a second reader of Harness state outside
Harness. Everything past that one question therefore belongs to the
plugin, which is where every one of those seams already is.

So `src/setup/` runs inside the composed Host, and `dshline --setup` keeps its
existing meaning (install this package into the profile). The flow opens
automatically before the first attachment, and `/setup` opens it on demand.

**The trigger asks whether this launch could send a turn, not whether a route
exists.** Route registration alone is the wrong question: a registered route is
only what `/model` offers FROM, and the composer opens on whatever
`selection.current` resolved to. So `setupReason` reads two things the window
already holds — `ctx.llm.listProviders()` and the selection ref `/model` writes
— and names one of three states: nothing registered, nothing selected, or a
selection whose route no adapter registered (a remembered default whose
provider has left the profile).

Topology alone still says a stock first install is healthy, and it is not:
`dsh-base` composes a default selection (`deepseek-official/deepseek-flash`)
and `llm-deepseek` calls `registerAdapter` unconditionally, so all three checks
pass while the first request fails `MISSING_CREDENTIAL`. So when the topology
looks complete, one more question is asked — of Connect, not of a second
algorithm. `readinessOf` is factored out of `providerReadiness` and
`readRouteReadiness` reads ONE route: the directory entry, that namespace's
descriptor, and one `credentials.describe()`. Only a positive `missing` opens
setup; `ready` and both `unknown` cases (a route naming no reference, a store
that could not answer) leave the launch alone, because uncertainty is not
failure.

The cost is a directory lookup, `settings.describe()` — in-memory, measured at
~1.2 ms median for 35 namespaces — and one credential lookup, which on the
shipped local provider is a map read over a snapshot loaded at mount. No
adapter is asked for a catalog. It stops at PROVIDER granularity deliberately:
whether the route still serves that exact model id is a question only
`listModels` can answer, and asking it would put a possible network call in
front of every launch to refine a verdict the picker gives anyway. There is no
first-run marker anywhere — a stored "already set up" flag is duplicated state
that can disagree with the configuration it claims to describe, and re-asking
live state every launch cannot.

What setup contributes is a reading and an ordering, and nothing else. The
ordering is keyed to remediation, not to the mere presence of a warning: a
repair step appears only when the report carries a warning it can answer, so an
all-clear returns `✓ Ready.` and the composer rather than a picker of optional
changes, and a warning only Harness or a shell command can answer — a generation
mismatch, a profile that mounts nothing to configure a provider — stays in the
report and closes without a picker. It leads with whatever is missing: once a
route is registered, `Choose a model` goes first, and when `/connect` closes
having produced the first usable route while the selection is still absent or
stale, the conductor opens the picker itself rather than returning to a
checklist that would only say to open it. The conductor does that, never
`/connect` — the browser stays a browser and knows nothing about setup — and
only when the model is the missing piece, since connecting a second provider is
not a request to change a working selection.

Each step hands off to a browser that is already the authority for what it does
— `/connect` to configure and authenticate, `/model` to choose — so there is no
second route editor, no second model catalogue, and no state machine: the loop
re-reads Harness each pass and offers what is true now, which is why backing
out halfway leaves nothing behind and running it twice is the same as running
it once.

The reading is **committed to scrollback rather than drawn in an overlay**,
which is the terminal model doing real work rather than a style choice. Version
numbers and the sentence naming why there is no model are the output most worth
keeping; a bounded live region would scroll them away the moment the next thing
was drawn, and this is precisely the text a person pastes into a bug report.
The only live-region surface it uses is `promptSelect`, which is already
bounded, resize-safe, and tested.

### What a compatibility check may claim

Harness publishes no runtime version service at the adopted generation — no
`ctx.version`, `dsh-brand` is compile-time branding, and
`dsh-plugin-package-inventory-deepseek` builds a package list only as request
metadata for the official API. The evidence is therefore manifests on disk,
read through the machinery `/profiles` already owns: the adopted generation is
this package's own `dsh-*` peer pin (which `tools/harness-target.mjs` proves is
`HARNESS_TARGET.version`), and the installed one is the `@deepseek-ai/dsh-base`
version the running profile composes.

Three rules follow, and each is a refusal:

- **A mark is a claim, so an unknown gets no mark.** Either side unreadable is
  `·` and says so — never "incompatible", never "fine".
- **A mismatch states only the direction it can prove.** Installing the
  generation this build targets is deterministic, because that version is a
  fact the report already holds. Moving dshline instead is not its mirror
  image: `update` fetches whatever the registry serves, and nothing here knows
  whether any released dshline targets the installed generation. That
  direction is therefore offered as a condition, not an instruction —
  establishing it would mean resolving releases against their peer pins.
- **A confirmed mismatch stops startup.** dshline supports only its adopted
  generation, and a Host built for a different one is not guaranteed to provide
  the APIs this build targets, so dshline prints the report and refuses to open
  a session rather than move a failure to a later, less legible one. The report
  is the last thing on screen until the targeted generation is installed and
  dshline is started again; `ctrl-d` exits. This is still not a compatibility
  verdict about a version that could not be read: `unknown` stays `·`.

Node is reported without a verdict for the same reason in miniature: this
process is running on it, so a tick is circular, and turning `engines` into a
pass or a fail means evaluating a semver range.

## Observation is not control

A callable Harness mutation is not automatically a human-safe UI operation.
Before exposing a human action, verify that the owning surface explicitly
provides lifecycle semantics, authorization, scheduling semantics, and the
model-awareness or notification consequences of that action.

Sessions is the case where this rule pointed the other way. `AgentHandle` is
handed to the caller that created the agent, and its documentation says the
disposer is a capability held by that owner — so retiring the agent is authorized
here, and reopening a session is a human action the frontend may take. What
Harness does NOT define is what should happen to a job or a delegated subagent
whose owning agent disappears mid-flight, so the window refuses to reopen while
either is attached, and refuses mid-turn, naming the reason rather than guessing.
Renaming a session is deferred for the mirror-image reason: `ctx.sessionTitle`
models explicit `user` authority, so it will be exposed when the browser has a
text-entry mode, not as a side effect of listing titles.

`ctx.jobs.kill()` is the current counterexample: successful cancellation moves
the job to `stopping` and marks terminal delivery reported, which is a
model-facing control semantic. Work therefore observes jobs but does not offer
human cancellation. `ctx.subagents.interrupt(..., { kind: 'user',
parentSessionId })` is the contrasting case: the seam explicitly models human
authority to stop a live continuable child. This rule applies to every future
capability, not only Work. Likewise, Work presents lifecycle and job state,
not provider reasoning, commands, tool activity, progress, or diffs unless
Harness exposes those facts through a generic contract; it must never scrape
provider output.

## Upstream compatibility

dshline tracks Harness aggressively and supports it narrowly: it targets **one
adopted Harness architecture at a time**, kept close to upstream `master` so it
can use the latest Harness capabilities, performance work, and native APIs.
When Harness changes incompatibly the answer is to migrate dshline forward and
delete the obsolete assumption — not to add a compatibility layer, a runtime
feature test, or a second peer-range arm for an older prerelease. Both projects
are pre-1.0; historical prerelease compatibility is not a goal.

`HARNESS_TARGET` at the repository root is the single source of truth for that
architecture: one upstream commit, and the npm version cut from it. Every
`dsh-*` dependency in both manifests is pinned to that version, so an ordinary
`pnpm install && pnpm typecheck && pnpm test` validates the generation the
project claims to support rather than an older line that merely still resolves.
Every `dsh-*` dependency, devDependency, and peerDependency carries that
version literally — no carets, no `||`. A caret also promises later releases in
the same range, which is a compatibility claim nothing tests, and deciding
whether one still admits the target is exactly what a version compatibility
engine is for; exact versions delete the question instead of answering it.
`tools/harness-target.mjs` is therefore a string comparison, and it fails the
moment any of those specs drifts. `@deepseek-ai/cordis` and
`@deepseek-ai/schemastery` keep ordinary caret ranges: they version on their
own numbering and are not cut from the adopted revision.

The two lines in `HARNESS_TARGET` must describe one generation, and CI proves
it rather than trusting it — `Harness target` reads the checked-out Harness
workspace root's own `version` and fails with both values if it disagrees.
Without that guard a source lane and an npm lane could validate different
generations and both pass. The adopted revision is a release-generation commit
rather than an arbitrary point on `master`, which is what lets the source lane
and the published lane describe the same thing; it is not a claim that anything
older is supported. Advancing those two lines IS the migration, and it is one
commit.

The coverage is three separable questions, all in `.github/workflows/ci.yml`.
**Core** is dshline's own correctness on every supported Node, against the
adopted generation's published packages. **Harness target** checks the adopted
upstream revision out from source at that exact commit, builds it, and links it
with `tools/link-harness.mjs` exactly the way a local checkout is linked for
manual development — typecheck plus the capability probes, not the whole suite
a second time. It is blocking and deterministic: a full commit sha cannot move
between two runs of the same commit of this repository. **Harness published** answers the question source cannot: can
a normal user install this and does it boot, against the real published
launcher pinned to the adopted version.

Core additionally runs `pnpm peers check`, which is not about dshline's own
code at all. The Harness line states floors for packages that are deliberately
NOT pinned to `HARNESS_TARGET.version` — `@deepseek-ai/cordis` and
`@deepseek-ai/schemastery` version on their own numbering — and those floors
move between generations. When one did, nothing noticed for two generations: an
unmet peer is a warning an install prints and a build ignores, and the
source-linked lane cannot see it either, because linking a Harness checkout
substitutes that checkout's own vendored cordis. The check reads the lockfile,
needs no network, states no Harness-specific opinion, and simply refuses to let
the installed graph disagree with itself.

### Proposing the next generation

Nothing watches upstream `master` any more. Following a branch head was the
right instinct aimed at the wrong object: an arbitrary master commit is not
something `HARNESS_TARGET` can record, so the signal was never directly
actionable, and the lane that produced it had to be read and translated by a
human before it meant anything.

`.github/workflows/harness-sync.yml` watches what an adoption actually is
instead. Upstream marks every release generation the same way — a published
GitHub Release whose tag is `dsh-v<version>` — and every revision this project
has ever adopted is exactly the commit one of those tags names. A few times a
day, `tools/harness-sync.mjs` asks whether a newer one exists; if it does, it
resolves the tag to an immutable commit (dereferencing an annotated tag rather
than recording the tag object, and never reading `target_commitish`, which is a
branch name), checks that the commit's own root manifest declares the version
its tag encodes, and proves through upstream that the adopted revision is an
ancestor. Anything it cannot prove fails closed for a human to read.

Only then does it write the mechanical adoption state — the two lines of
`HARNESS_TARGET`, the governed `dsh-*` pins, a refreshed lockfile, and a
one-sentence changeset — and open a pull request.

That distinction is the design. The proposer never decides whether dshline
WORKS against the candidate; it reads no source and assesses no compatibility.
The jobs above do, on that pull request, exactly as they would for any other:

```text
harness-sync   is there a newer generation to propose?
ci             does dshline work against it?
```

Green means the adoption needed no code, and a human merges it. Red means a
real migration, and the answer is to migrate forward against that generation —
never to restore support for the previous one. There is no auto-merge, and
adding one is a separate decision to make after several generations have
actually behaved.

Two refusals are worth naming because both look like failures and are not. If
the candidate's packages are still inside the repository's release-age
quarantine, pnpm refuses to install them and the run reports that and stops —
no pull request, no exclusion, no independent age arithmetic. And an adoption
that is already open is never superseded automatically: it may carry migration
work, and force-pushing a newer candidate over it would discard exactly the
expensive part.

Development compatibility CI does not follow npm dist-tags. `next`, `alpha`,
and `rc` are upstream distribution channels, not dshline architectural
concepts: they change without the architecture changing, and a compatibility
lane keyed on a channel name would need redesigning every time one moved. The
target is an exact commit and an exact version, and the published lane asks
only whether that exact version exists on the registry yet. GitHub source moves
first and npm catches up afterwards; when it has not caught up, that lane says
so and validates nothing. "Not published yet" is a release-channel fact, and
it is never a reason to write compatibility code for an older published
generation.

### The release channel is a separate question

That release-channel fact does eventually decide something, and exactly one
thing: whether a dshline release may become the DEFAULT install. The two
concerns are easy to conflate and must not be, because they have opposite
answers to the same event.

The documented installation is two unqualified names, so both sides resolve
through npm's default tag:

```sh
npm install -g @deepseek-ai/dsh @dshline/dshline
```

`@deepseek-ai/dsh` pins the whole `dsh-*` line to its own generation, so
whichever version that tag serves IS the Harness generation an ordinary install
ends up running. The invariant is therefore about channels, not about code:

> `@dshline/dshline@latest` must never advance to a build whose adopted Harness
> generation differs from what `@deepseek-ai/dsh@latest` serves.

`main` may adopt a Harness release generation before DeepSeek promotes that
generation to npm's default tag, and routinely will — tracking aggressively is
the point. That gap does **not** create an obligation to keep working against
the older default: nothing is widened, no peer range grows a second arm, and no
runtime feature test appears. Publication waits instead. Changesets accumulate
normally, the generated `Version Packages` pull request may sit release-not-
ready for as long as it takes, and ordinary development against the adopted
generation is unaffected throughout.

`tools/check-release-harness.mjs` is that gate, and it compares
`HARNESS_TARGET.version` with `@deepseek-ai/dsh@latest` by exact string
equality. Exactness matters in both directions: dshline supports one
generation, so a default channel that has moved PAST the adopted target fails
too — "newer" is not "supported", and the response there is to migrate
`HARNESS_TARGET` onto whichever generation Harness actually promoted, never to
assume forward compatibility. A registry that cannot be reached fails closed
as well, reported as an unanswered question rather than as a mismatch.

It runs at the three boundaries where the answer could still change something:
on the generated `Version Packages` pull request, so default-install coherence
is visible before a human merges it; in `.github/workflows/version.yml` before the
immutable `v*` tag is created, which is the primary irreversible boundary —
failing there leaves no tag, nothing published, and nothing to clean up; and in
`.github/workflows/publish.yml` before the first package is published, because
the tag can move green to red in between. It is identified by branch and
repository rather than by pull-request title, and holds no write permission and
no secret: it reads one repository file and asks npm one question.

This is a release gate, not a compatibility lane, and none of it changes the
sentence above — a pull request that is not the generated release PR never
resolves a dist-tag, so a pointer DeepSeek moves can still never make unrelated
work unmergeable. Once the two defaults agree, an ordinary unqualified install
resolves a coherent pair again, which is the only thing the gate was ever
protecting.

Each Harness lane additionally runs `tools/capability-report.mjs`, which turns
named evidence into a PASS, FAIL, or MISSING result per capability. Capability
evidence is built against the real Harness contract at the strongest
deterministic layer available: concrete service or runtime behavior where
practical, base-class orchestration where that is the contract, or a minimal
subclass when the seam is intentionally abstract. Integration probes then
verify the production dshline consumer over that seam where relevant. The
table points to generic surfaces production dshline consumes that can
reasonably be exercised deterministically in-process; it is not a copied
contract or a completeness claim about host/bootstrap-only surfaces. The
pointer deliberately excludes `appExit`, `loader`, `cmdlineArgs`, `dshHomePath`,
and `baseUrl`; these are launcher/Host-plane inputs outside the named in-process
service inventory, and TUI-owned surfaces are not capability rows. The published
consumer lane proves real install/boot integration at that Host boundary, while
focused tests cover dshline's local forwarding and policy; this does not claim to
exercise every `/profiles` or host-accessor behavior. An upstream change to a named seam reads as
`sessionQuery contract changed` rather than only a generic `pnpm typecheck
failed`; a seam not in this table still has `pnpm typecheck`/`pnpm test` as its
backstop. `tools/capability-probes.mjs` remains a pointer table, not a second
copy of the contract: it names which existing or purpose-built test supplies
evidence, so growing the coverage means adding a line to that table (or a
small new probe under `packages/dshline/tests/capability/`), never teaching
this module the seam's shape itself.

`userQuestions` is this radar's first proof against a real break: Harness's
`ctx.userQuestions` registration shape moved, and `packages/dshline/src/questions.ts`
briefly bridged the two shapes with one small runtime check. That bridge was
debt rather than a pattern — it predated the one-adopted-generation rule — and
the adoption that followed deleted it: the module now registers directly on the
scoped `user-questions/request` waterfall. No new bridge like it should be
written. A migration removes the old call, it does not keep both.