@sqdr2/dsh-fusion 0.0.0-stage → 0.3.2

package/contracts/fusion.ts

@@ -0,0 +1,279 @@
+/**
+ * Proposed plugin-domain contracts, NOT existing DSH API declarations.
+ * No runtime behavior or authorization is supplied by these types.
+ * Convert DSH branded IDs only in the version-pinned bridge layer.
+ */
+export type Brand<T, B extends string> = T & { readonly __brand: B };
+export type TaskId = Brand<string, 'FusionTaskId'>;
+export type SessionId = Brand<string, 'DshSessionId'>;
+export type WorkOrderId = Brand<string, 'FusionWorkOrderId'>;
+export type OperationId = Brand<string, 'FusionOperationId'>;
+export type ArtifactId = Brand<string, 'FusionArtifactId'>;
+export type SnapshotId = Brand<string, 'FusionSnapshotId'>;
+export type Digest = Brand<string, 'Sha256Hex'>;
+/** Decimal string avoids binary-float money and is JSON serializable. */
+export type UsdDecimal = Brand<string, 'UsdDecimal'>;
+export type EpochId = Brand<string, 'ContextEpochId'>;
+
+export interface PhysicalRoute {
+  provider: string;
+  model: string;
+  reasoningEffort?: string; // Validate against the owning adapter's opaque IDs.
+}
+export type RunSelection =
+  | { kind: 'model'; route: PhysicalRoute }
+  | { kind: 'profile'; profileId: string; requestedVersion?: string };
+export type Role = 'lead' | 'worker';
+export type Phase =
+  | 'READY' | 'PLANNING' | 'DIRECT' | 'WORKER_RUNNING' | 'REVIEWING'
+  | 'REWORK' | 'WAITING_APPROVAL' | 'WAITING_USER' | 'WAITING_BUDGET'
+  | 'RECOVERING' | 'PAUSED' | 'STOPPING' | 'NEEDS_DECISION'
+  | 'FAILED' | 'COMPLETED' | 'CANCELLED';
+export type VerificationLevel = 'unverified' | 'partial' | 'verified';
+
+export interface SourceRef {
+  sessionId: SessionId;
+  eventSeq: number;
+  messageId?: string;
+}
+export interface ArtifactRef {
+  id: ArtifactId;
+  digest: Digest;
+  ownerTaskId: TaskId;
+  mediaType: string;
+  bytes: number;
+}
+export interface Constraint {
+  id: string;
+  text: string;
+  source: SourceRef;
+  provenance: 'user' | 'policy' | 'inferred';
+  mandatory: boolean;
+}
+export interface AcceptanceCriterion {
+  id: string;
+  description: string;
+  verificationKind: 'test' | 'static-check' | 'human' | 'review';
+  mandatory: boolean;
+  verifierId?: string;
+  planId?: string;
+  planDigest?: Digest;
+}
+export interface ResourcePolicy {
+  maxWorkerSteps: number;
+  maxReworkRounds: number;
+  maxCapabilityUpgrades: number;
+  modelSpendAuthorizationId?: string;
+  maxApiCostUsd?: UsdDecimal;
+  maxTotalOutputTokens: number;
+  /** Human approval has no expiry; only machine execution has a deadline. */
+  commandMaxSeconds: number;
+}
+export interface WorkOrder {
+  schemaVersion: 1;
+  taskId: TaskId;
+  id: WorkOrderId;
+  operationId: OperationId;
+  revision: number;
+  goal: string;
+  constraints: readonly Constraint[];
+  acceptance: readonly AcceptanceCriterion[];
+  allowedPaths: readonly string[];
+  forbiddenActions: readonly string[];
+  baseSnapshot: SnapshotId;
+  evidence: readonly ArtifactRef[];
+  decisions: readonly { text: string; source: SourceRef }[];
+  uncertainties: readonly string[];
+  policy: ResourcePolicy;
+}
+export interface CoverageClaim {
+  criterionId: string;
+  state: 'satisfied' | 'not-satisfied' | 'not-verified';
+  evidenceIds: readonly ArtifactId[];
+  explanation: string;
+}
+export interface WorkerReport {
+  schemaVersion: 1;
+  workOrderId: WorkOrderId;
+  revision: number;
+  status: 'completed' | 'blocked' | 'needs-decision';
+  summary: string;
+  snapshot: SnapshotId;
+  changeManifest: ArtifactRef;
+  coverage: readonly CoverageClaim[];
+  verification: readonly ArtifactRef[];
+  unresolved: readonly string[];
+  questions: readonly string[];
+}
+export interface ToolEvidence {
+  schemaVersion: 1;
+  taskId: TaskId;
+  operationId: OperationId;
+  actor: SessionId;
+  nativeToolCallId: string;
+  argvDigest: Digest;
+  cwdDigest: Digest;
+  inputSnapshot: SnapshotId;
+  outputSnapshot?: SnapshotId;
+  exitCode: number | null;
+  startedAt: string;
+  endedAt: string | null;
+  stdout: ArtifactRef;
+  stderr: ArtifactRef;
+  state: 'started' | 'completed' | 'cancelled' | 'outcome-unknown';
+  kind?: 'tool' | 'human-decision' | 'review-accept';
+}
+export interface ContextCheckpoint {
+  schemaVersion: 1;
+  epochId: EpochId;
+  taskId: TaskId;
+  revision: number;
+  goal: string;
+  mandatoryConstraints: readonly Constraint[];
+  snapshot: SnapshotId;
+  decisions: readonly { text: string; source: SourceRef }[];
+  coverage: readonly CoverageClaim[];
+  pendingApprovalIds: readonly string[];
+  openQuestions: readonly string[];
+  evidence: readonly ArtifactRef[];
+  sourceSurfaceSeqs: readonly number[]; // Surface order, NOT numeric sorting.
+  digest: Digest;
+}
+export interface RoleContextPolicy {
+  targetInputTokens: number;
+  reserveOutputTokens: number;
+  minSafetyTokens: number;
+  safetyFraction: number;
+  compactToFraction: number;
+  evidenceReadTokens: number;
+  maxToolVisibleTokens: number;
+}
+export interface PairProfile {
+  schemaVersion: 1;
+  id: string;
+  version: string;
+  digest: Digest;
+  enabled: boolean;
+  quality: 'experimental' | 'validated' | 'deprecated';
+  lead: PhysicalRoute;
+  worker: PhysicalRoute;
+  workerUpgradePath: readonly PhysicalRoute[];
+  promptDigests: Readonly<Record<'lead' | 'worker' | 'compact', Digest>>;
+  context: Readonly<Record<Role, RoleContextPolicy>>;
+  /** Experimental auxiliary calls, explicitly enabled for the frozen routes. */
+  cacheKeepalive?: Readonly<Record<Role, boolean>>;
+  /** Optional explicit summary route. Missing means the current role model. */
+  compactor?: { readonly route: PhysicalRoute; readonly maxOutputTokens: number };
+  dataPolicyId: string;
+  evidenceCampaignIds: readonly string[];
+}
+export interface LogicalApproval {
+  id: string;
+  taskId: TaskId;
+  revision: number;
+  operationId: OperationId;
+  nativeRequestId?: string;
+  argsDigest: Digest;
+  snapshot: SnapshotId;
+  permissionPolicyDigest: Digest;
+  state: 'pending' | 'approved' | 'rejected' | 'withdrawn' | 'consumed';
+  decisionBy?: 'human' | 'preauthorized-policy';
+  /** No expiresAt: pending human work does not expire automatically. */
+}
+export interface WriteLease {
+  workspaceId: string;
+  holder: SessionId;
+  taskId: TaskId;
+  generation: number;
+  activeOperationIds: readonly OperationId[];
+}
+export interface TokenMeasurement {
+  inputTokens: number;
+  reservedOutputTokens: number;
+  contextWindow: number;
+  safetyTokens: number;
+  quality: 'exact' | 'provider-estimated' | 'heuristic';
+  requestDigest: Digest;
+}
+/** Mutually exclusive buckets. Null means unavailable, never zero. */
+export type UsageApplicability = 'not_applicable' | 'unknown' | 'known';
+export interface NormalizedUsage {
+  uncachedInput: number | null;
+  cacheRead: number | null;
+  cacheReadStatus: UsageApplicability;
+  cacheWrite: Readonly<Record<string, number | null>>;
+  cacheWriteStatus: Readonly<Record<string, UsageApplicability>>;
+  output: number | null;
+  /** Informational subset; do not charge again if included in output. */
+  reasoningOutputSubset: number | null;
+  /** Separately billed reasoning. Charge at the reasoning or output rate. */
+  reasoningSeparate: number | null;
+  /** Reasoning tokens whose include-in-output contract is unknown. */
+  reasoningUnspecified: number | null;
+  reasoningBilling: {
+    kind: 'included' | 'separate' | 'unknown' | 'not_applicable';
+    tokens: number | null;
+  };
+  inputIncludesCacheRead: boolean | null;
+}
+
+export interface ReportSubject {
+  taskId: TaskId;
+  workOrderId: WorkOrderId;
+  revision: number;
+  reportId: string;
+  reportDigest: Digest;
+  snapshot: SnapshotId;
+}
+export interface ReviewTicket {
+  id: string;
+  requestId: string;
+  generation: number;
+  subject: ReportSubject;
+  validationDigest: Digest;
+  workOrderDigest: Digest;
+}
+export interface ControlState {
+  mode: 'running' | 'paused' | 'stop-requested' | 'cancelled' | 'completed';
+  pendingApprovalIds: readonly string[];
+  budgetBlocked: boolean;
+  recovering: boolean;
+  outcomeUnknown: boolean;
+}
+export interface UsageAttempt {
+  attemptId: string;
+  taskId: TaskId;
+  agentId: SessionId;
+  role: Role;
+  purpose: 'conversation' | 'compaction' | 'review' | 'routing' | 'other';
+  route: PhysicalRoute;
+  epochId: EpochId;
+  serviceTier?: string;
+  rawUsage?: ArtifactRef;
+  normalized: NormalizedUsage;
+  priceCardDigest?: Digest;
+  apiEquivalentUsd: UsdDecimal | null;
+  actualBilledUsd: UsdDecimal | null;
+  status: 'pending' | 'complete' | 'partial' | 'unknown';
+}
+export interface EventEnvelope<T extends string, P> {
+  schemaVersion: 1;
+  id: string;
+  taskId: TaskId;
+  seq: number;
+  revision: number;
+  type: T;
+  createdAt: string;
+  causeId: string;
+  payload: P;
+}
+export type FusionEvent =
+  | EventEnvelope<'task/created', { parent: SessionId; selection: RunSelection }>
+  | EventEnvelope<'work-order/prepared', { order: WorkOrder; reservedChild: SessionId }>
+  | EventEnvelope<'child/accepted', { operationId: OperationId; child: SessionId; messageId: string }>
+  | EventEnvelope<'report/validated', { operationId: OperationId; report: WorkerReport }>
+  | EventEnvelope<'approval/pending', { approval: LogicalApproval }>
+  | EventEnvelope<'effect/outcome-unknown', { operationId: OperationId; reason: string }>
+  | EventEnvelope<'task/completed', { snapshot: SnapshotId; verification: VerificationLevel }>
+  | EventEnvelope<'task/paused', { reason: string }>;
+// Expand this union when implementing all specified event kinds; do not use any.

package/contracts/storage.sql

@@ -0,0 +1,86 @@
+-- Optional SQLite task store. Does not replace or share a transaction with DSH Session.
+PRAGMA foreign_keys = ON;
+PRAGMA journal_mode = WAL;
+CREATE TABLE IF NOT EXISTS schema_meta(version INTEGER NOT NULL);
+INSERT INTO schema_meta(version) SELECT 1 WHERE NOT EXISTS (SELECT 1 FROM schema_meta);
+CREATE TABLE IF NOT EXISTS tasks (
+ task_id TEXT PRIMARY KEY,
+ revision INTEGER NOT NULL CHECK(revision >= 1),
+ state TEXT NOT NULL,
+ parent_session_id TEXT NOT NULL,
+ profile_digest TEXT NOT NULL,
+ state_seq INTEGER NOT NULL DEFAULT 0 CHECK(state_seq >= 0),
+ created_at TEXT NOT NULL,
+ updated_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS events (
+ event_id TEXT PRIMARY KEY,
+ task_id TEXT NOT NULL REFERENCES tasks(task_id),
+ seq INTEGER NOT NULL CHECK(seq >= 1),
+ revision INTEGER NOT NULL CHECK(revision >= 1),
+ type TEXT NOT NULL,
+ payload_version INTEGER NOT NULL,
+ payload_json TEXT NOT NULL,
+ cause_id TEXT NOT NULL,
+ created_at TEXT NOT NULL,
+ UNIQUE(task_id,seq)
+);
+CREATE TABLE IF NOT EXISTS artifacts (
+ artifact_id TEXT PRIMARY KEY,
+ task_id TEXT NOT NULL REFERENCES tasks(task_id),
+ content_digest TEXT NOT NULL,
+ storage_ref TEXT NOT NULL,
+ bytes INTEGER NOT NULL CHECK(bytes >= 0),
+ media_type TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS work_orders (
+ work_order_id TEXT PRIMARY KEY,
+ task_id TEXT NOT NULL REFERENCES tasks(task_id),
+ revision INTEGER NOT NULL,
+ child_session_id TEXT NOT NULL,
+ status TEXT NOT NULL,
+ brief_artifact_id TEXT NOT NULL REFERENCES artifacts(artifact_id)
+);
+CREATE TABLE IF NOT EXISTS outbox (
+ operation_id TEXT PRIMARY KEY,
+ task_id TEXT NOT NULL REFERENCES tasks(task_id),
+ kind TEXT NOT NULL,
+ state TEXT NOT NULL,
+ payload_artifact_id TEXT NOT NULL REFERENCES artifacts(artifact_id),
+ native_message_id TEXT,
+ result_artifact_id TEXT REFERENCES artifacts(artifact_id)
+);
+CREATE TABLE IF NOT EXISTS effects (
+ effect_id TEXT PRIMARY KEY,
+ operation_id TEXT NOT NULL UNIQUE REFERENCES outbox(operation_id),
+ args_digest TEXT NOT NULL,
+ snapshot_id TEXT NOT NULL,
+ stage TEXT NOT NULL,
+ outcome_artifact_id TEXT REFERENCES artifacts(artifact_id)
+);
+CREATE TABLE IF NOT EXISTS logical_approvals (
+ logical_id TEXT PRIMARY KEY,
+ effect_id TEXT NOT NULL UNIQUE REFERENCES effects(effect_id),
+ decision TEXT NOT NULL CHECK(decision IN ('pending','approved','rejected','withdrawn','consumed')),
+ native_request_id TEXT,
+ decision_scope_digest TEXT NOT NULL,
+ updated_at TEXT NOT NULL
+ -- Intentionally no expiry column for pending human decisions.
+);
+CREATE TABLE IF NOT EXISTS usage_attempts (
+ attempt_id TEXT PRIMARY KEY,
+ task_id TEXT NOT NULL REFERENCES tasks(task_id),
+ accounting_status TEXT NOT NULL,
+ normalized_json TEXT NOT NULL,
+ raw_usage_artifact_id TEXT REFERENCES artifacts(artifact_id)
+);
+CREATE TABLE IF NOT EXISTS leases (
+ workspace_id TEXT PRIMARY KEY,
+ generation INTEGER NOT NULL CHECK(generation >= 1),
+ owner_task_id TEXT NOT NULL REFERENCES tasks(task_id),
+ live_process_refs_json TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS events_by_task ON events(task_id,seq);
+CREATE INDEX IF NOT EXISTS outbox_pending ON outbox(state,task_id);
+-- Application must perform state/version CAS + event append + outbox write in one transaction.
+-- SQL uniqueness is not proof of exactly-once external side effects.

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-fusion
+      name: '@sqdr2/dsh-fusion'

package/docs/COMPATIBILITY.md

@@ -0,0 +1,162 @@
+# DSH compatibility
+
+Fusion supports **DeepSeek Harness 0.2.0-rc.2 and 0.2.1-rc.2**. It is an ordinary external plugin: it uses only DSH's public
+plugin APIs and never patches, replaces or rebuilds DSH itself. `scripts/build.mjs` accepts either of those two Host
+checkouts, `engines.dsh` declares the supported runtime, and every `@deepseek-ai/dsh*` peer uses the same range.
+
+## What Fusion depends on
+
+Public services always used (`ctx.*`): `agents`, `subagents`, `sessions`, `sessionQuery`, `sessionController`
+(`modelCatalog`, `selectModel`, `resolveAgent`), `llm` (`stream` hooks, `resolveModelInfo`, `registerAdapter`),
+`tools` (`guard`, `execute`, per-agent catalog), `commands`, `webServer`, `agentDefaultModel`, `logger`.
+
+Services Fusion looks up at runtime (`ctx.get`), with what happens when one is missing:
+
+| Service | Used for | Without it |
+| --- | --- | --- |
+| `sandboxPolicy` | the Lead's read-only sandbox (enforced-v3) | every Lead shell command is refused; the Lead still reads with file and search tools |
+| `jobs` | the Sidekick's background commands | background commands are refused |
+| `tokenMeter` | measuring each request against the context window | Fusion requests stop with an error |
+| `compaction`, `agentPresets` | compacting a long Fusion conversation | Fusion pauses when the context is full, keeping the full record |
+| `approval` | routing Sidekick approvals through DSH's own approval policy | commands that need approval fail |
+| `locale` (client) | Chinese / English UI | the UI follows the browser language |
+
+Packages imported: `cordis`, `schemastery`, `dsh-agent`, `dsh-llm`, `dsh-session`, `dsh-session-query`,
+`dsh-subagent`, `dsh-tools`, `dsh-jobs`, `dsh-commands`, `dsh-host-webserver`, `dsh-api-session-controller`,
+`dsh-agent-default-model`, `dsh-agent-preset-registry`, `dsh-compaction`, `dsh-token-meter`, `dsh-user-approval` and the
+client packages `dsh-client-ui-*` and `dsh-client-store`. Only package entry points and their documented `/client` and
+`/types` subpaths are imported.
+
+Fusion writes only public session events (messages, tool calls and results, and `sandbox/mode` for the Lead's read-only
+sandbox) and stores its own records in its plugin directory.
+
+## Changes from 0.2.0-rc.2 to 0.2.1-rc.2
+
+The subagent seam was renamed and widened; the delegation composition knobs moved. Everything else Fusion imports
+kept its shape — all 25 non-client `@deepseek-ai/*` symbols Fusion imports still exist with unchanged signatures.
+
+| 0.2.0-rc.2 | 0.2.1-rc.2 | Fusion's handling |
+| --- | --- | --- |
+| `ctx.subagents.startContinuable(spec)` | `ctx.subagents.startActivation(spec)` | if `startActivation` exists, call it with `delivery: 'parent'` and no persona or toolFilter; otherwise call `startContinuable` exactly as on 0.2.0 |
+| `ContinuableStartSpec`, `ContinuableStart` | `SubagentActivationSpec`, `SubagentActivation` | spec gained a required `delivery: 'parent' \| 'caller'`; the return gained `result`/`dispose()` and made `messageId` optional |
+| `ctx.subagents.drainContinuableChildren(parent, childIds)` | `ctx.subagents.drainChildren(parent, childIds)` | call whichever function exists; `drainDescendants(parents)` is the broader form |
+| `ctx.subagents.start(name, request)` | removed | the benchmark baseline uses `start` on 0.2.0 and `startActivation` with `delivery: 'caller'` on 0.2.1 |
+| `SubagentRun.localAgent` | removed | 0.2.0 reads `localAgent`; 0.2.1 reads `ctx.agents.get(childId)` |
+| `request.persona`, `request.toolFilter` | removed (DSH directs callers to an Agent Preset) | kept on the 0.2.0 start; see below for 0.2.1 |
+| `TerminalBlockLabels` (client) | gained a required `commandLine` | always passed in `src/client/ActivityRows.tsx`; 0.2.0 ignores the extra field |
+
+Detection is the presence of the function, not a version string. If neither start exists, or neither drain exists,
+Fusion throws and names 0.2.0-rc.2 and 0.2.1-rc.2 as the supported range. `delivery: 'parent'` preserves the 0.2.0
+behaviour: the Worker's settlement reaches the Lead's inbox, which is what the Lead reconciles from the session log.
+
+**On 0.2.1 the persona and tool-ceiling knobs have no start-time replacement.** 0.2.1 rejects them outright
+(`tool-subagent: persona is no longer supported; configure persona and tool plugins in an Agent Preset and select it
+with agentPreset`) and `SubagentStartRequest` no longer declares them. The sanctioned replacement is an Agent Preset,
+but Fusion computes the Worker's persona and its tool set per work order at runtime, so a preset cannot express them —
+and requiring a user-configured preset would silently change Fusion's contract. On that host both live inside the
+native role scope Fusion already owns:
+
+- the Worker's persona prompt was already redundant: `NativeFusionScopes` installs the `fusion-role` system-prompt
+  section carrying `binding.prompts[role]` on the child's own context;
+- the Worker's tool ceiling was **not** redundant. In `implement` mode `readOnlyTools` used to return `undefined` and
+  the ceiling came from the start-time `toolFilter` alone. When `startActivation` exists, `readOnlyTools` returns
+  `workerTools` for implement mode, so `NativeFusionScopes` narrows the inherited tool set. The scope is installed at
+  `agent/created`, before the child's first request, and the existing deny-only guard remains the second gate.
+
+That return value also runs `tools.presentAs('native')`, so an implement-mode Worker on 0.2.1 is presented natively,
+as the read-only modes already were. The advertised names stay `workerTools`. On 0.2.0 implement mode still returns
+`undefined`. The ceiling stays the start-time `toolFilter`, and `presentAs('native')` does not start applying to those
+Workers, so 0.2.0 behaviour is unchanged. Text and explore modes already returned an allowlist on both hosts.
+
+### Version declarations
+
+The old `>=0.2.0-rc.1 <0.2.1` range was **not** what blocked 0.2.1. DSH evaluates plugin requirements with
+`includePrerelease: true`, and `0.2.1-rc.2` sorts *below* `0.2.1`, so that range already satisfied the 0.2.1 gate.
+What broke was the code (`startContinuable` is gone). `scripts/link-host.mjs` checks the same peers with **plain**
+semver, where a prerelease only matches a comparator that has a prerelease on the same major.minor.patch, so
+`>=0.2.0-rc.1 <0.2.1` rejects `0.2.1-rc.2`.
+
+`engines.dsh` and every `@deepseek-ai/dsh*` peer therefore use:
+
+```text
+>=0.2.0-rc.1 <0.2.1-0 || >=0.2.1-rc.2 <0.3.0-0
+```
+
+Dev dependencies and `pnpm-lock.yaml` stay on the published 0.2.0-rc.2 packages (the CI devkit pins that tag). The
+0.2.1-only methods are local structural types, so typecheck does not need the 0.2.1 packages installed.
+
+| Version | plain `satisfies` | `{ includePrerelease: true }` |
+| --- | --- | --- |
+| `0.2.0-rc.1` | accept | accept |
+| `0.2.0-rc.2` | accept | accept |
+| `0.2.1-rc.1` | reject | reject |
+| `0.2.1-rc.2` | accept | accept |
+| `0.2.1-rc.3` | accept | accept |
+| `0.2.1` | accept | accept |
+| `0.3.0-rc.1` | reject | reject |
+| `0.3.0` | reject | reject |
+
+## Changes from 0.1.5 to 0.1.7 (an example of what an upgrade touches)
+
+- Plugin message sources became `{ kind: 'plugin:<id>' }` (was `{ kind: 'plugin', plugin: '<id>' }`); Fusion declares its
+  kind in `src/message-source.ts`.
+- Jobs: `JobSnapshot`/`onJobDone` became `JobView`/`events.subscribe`, and job calls take the calling agent's id.
+- `dsh-agent-presets` became `dsh-agent-preset-registry`.
+- Tool results became `role: 'tool'` messages that carry `toolCallId` and `isError` themselves.
+- Session logs are `session.v4.jsonl.zstd` (benchmark tooling reads v3 and v4).
+- Plugins declare a bundle patch (`dsh.bundle.patch` → `cordis.patch.yml`).
+
+## Adapting to a new DSH release (for example 0.1.8)
+
+1. Check out the new Harness release and point `DSHX_HARNESS` at it.
+2. Update the version check in `scripts/build.mjs`, `engines.dsh` and the `@deepseek-ai/*` `peerDependencies`; relink
+   with `node scripts/link-host.mjs <harness>`. Pick the range carefully: DSH's gate uses `includePrerelease`, where a
+   prerelease sorts below its own release, so a stale upper bound like `<0.2.1` still admits `0.2.1-rc.2` and silently
+   passes — while `scripts/link-host.mjs` uses plain semver and rejects it. A prerelease only matches a plain
+   comparator that carries a prerelease on the same major.minor.patch, which is why the current span is
+   `>=0.2.0-rc.1 <0.2.1-0 || >=0.2.1-rc.2 <0.3.0-0`. Verify both consumers.
+3. Read the release notes and run `dshx check` for compatibility rules; fix type errors (`pnpm typecheck`). Renames in
+   the subagent seam are not caught by type checking when the old name is simply gone — grep `ctx.subagents` calls by
+   hand, and check the client packages too (`TerminalBlockLabels` gained a required field this time).
+4. Run `pnpm test` and `pnpm test:host` against the new Harness; the Host suite exercises the real Agent, session,
+   tool, job, sandbox and subagent services.
+5. Cold-boot the plugin alone in a temporary home: `dshx verify-boot <plugin dir>`.
+6. Install into a real DSH and run a short task with a Fusion pair; check the Lead read-only probe from the README.
+7. Update the supported version in `README.md`, `README.en.md`, `INSTALL*.md` and this file.
+
+## Other plugins that rewrite the tool table
+
+Fusion registers `fusion_*` tools on the agent and then filters `system-prompt/assemble` down to the role allowlist.
+That filter only removes tools. A plugin that **replaces** `assembled.tools` inside the same hook — `dsh-tool-search` does
+this, keeping an eager set such as `bash`, `glob`, `grep`, `read` and moving everything else, including `fusion_*` and
+often `job_output`, out of the request — used to leave the Lead with no delegation tool. The task could then end
+`COMPLETED` without any Fusion work.
+
+Fusion now rebuilds the request table as **allowlist ∪ its own registry** after `next()` returns. Names the role is
+allowed to see are copied back from `tools.schemas(agent)` when another plugin dropped them. If a required `fusion_*`
+tool is not in that registry either, assembly throws `FUSION_TOOL_TABLE_INCOMPLETE` instead of sending the request.
+Putting those names in `dsh-tool-search`'s `core` list is unnecessary once this build is installed; it remains harmless.
+
+## Host behaviour Fusion does not own
+
+These show up next to Fusion's own gates. Fusion does not patch the host to remove them.
+
+- **Sandbox read-only denial.** `[sandbox: file access denied under read-only mode]` is the DSH sandbox backend.
+  enforced-v3 keeps the Lead's session read-only on purpose. The Sidekick is given the mode the user chose for the
+  conversation. Fusion applies that mode when the user appends `sandbox/mode`, including onto a resident Sidekick, and
+  again on the Sidekick's next model request. It never widens the Lead, and it cannot grant a mode the user did not set.
+  A Sidekick that has already been disposed has no session left to update; the next delegation seeds a new one.
+- **Reload recovery after a quota stop.** A Worker that stops on provider quota often leaves its `native-worker` outbox
+  row `accepted` because no report was acknowledged. The next host start treats that row like any other unacknowledged
+  dispatch and sets `recovering`. Continue and role switch both run only after `settled()`, which requires
+  `recovering` to be clear, and the route is not written if that check fails. That inspection stays: Fusion cannot see
+  host file or process effects that were not in its own journal. Use `/fusion recover <inspection note>`, then continue
+  or switch the Sidekick from the recovery panel. Saving a new pair in Settings changes the default for new
+  conversations only.
+- **Natural Worker disposal.** DSH `0.2.0-rc.2` disposes a continuable child in `finishDisposal` and only then sends
+  `subagent-settled`. `fusion_wait` reads the persisted task when that handle is already gone. It asks for recovery
+  only when a native effect is still pending or the outcome is unknown. An ended Worker with no report is
+  `WORKFLOW_INCOMPLETE`, not a quota or provider outage. On `0.2.1-rc.2` the same settlement flushes the child log
+  and then closes the persistence handle. A later `stop` that sees `SessionHandleClosedError` treats that log as
+  already durable, kills any recorded job, and releases the writer. Host unload while `runtime.background` is set
+  records `recovery/needed` before that settlement can clear the flag.

package/docs/EVIDENCE.md

@@ -0,0 +1,141 @@
+# Evidence: does Fusion give frontier results at a discount?
+
+Short answer, on the tasks measured: **yes for GPT-6 Astra + GLM-5.3-Flash** — more tasks resolved than GPT-6 Astra
+alone, at 46% of its cost. The sample is small; read the limitations below.
+
+## Result
+
+Nine real SWE-rebench issues, two attempts each (18 per condition), graded by the maintainers' hidden tests.
+Plugin 0.2.0-preview.11, DSH Studio 0.1.7-rc.2 on macOS. Costs are API-equivalent at list prices, not bills.
+
+| Condition | Resolved | Total cost | Paired cost vs Astra alone (median / total) | Lead cost (cache hits) | Sidekick cost | Attempt time |
+| --- | --- | --- | --- | --- | --- | --- |
+| GPT-6 Astra alone (round 4) | 9/18 | $39.17 | — | — | — | 1.6 h |
+| **Fusion: Astra + GLM-5.3-Flash** | **11/18** | **$18.07** | **0.51 / 0.46** | $13.70 (85%) | $4.37 | 8.3 h |
+| Fusion: Astra + Grok 4.6 | 13/18 | $41.27 | 0.85 / 1.05 | $13.34 (86%) | $27.93 | 3.4 h |
+
+- Astra + Flash met both preregistered rules: quality at least Astra alone − 2 (it resolved 2 more), and a median
+  paired cost ratio ≤ 0.6.
+- Astra + Grok 4.6 was the most accurate pair (13/18 in rounds 4 and 5) but not cheaper: the Grok Sidekick costs about
+  what the Lead saves.
+- The Lead never needed to take over the code: 0 takeovers in 72 Fusion attempts (rounds 4 and 5).
+- Fusion is slower: about 5× the attempt time of Astra alone, mostly Sidekick generation (Flash makes ~80 calls per
+  task).
+
+Per task (Fusion from round 5, Astra alone from round 4; ✓ = resolved, two attempts each, cost of both):
+
+| Task | Astra alone | Astra + Flash | Astra + Grok 4.6 |
+| --- | --- | --- | --- |
+| pypa__twine-1309 | ✗ ✗ $2.83 | ✗ ✗ $1.16 | ✓ ✓ $2.16 |
+| delgan__loguru-1451 | ✓ ✓ $3.35 | ✓ ✓ $2.07 | ✓ ✓ $2.40 |
+| sqlfluff__sqlfluff-7615 | ✗ ✗ $8.28 | ✓ ✗ $2.03 | ✓ ✓ $6.93 |
+| pycqa__isort-2491 | ✗ ✗ $5.19 | ✗ ✗ $3.01 | ✗ ✗ $12.41 |
+| holoviz__param-1117 | ✓ ✓ $4.57 | ✓ ✓ $2.52 | ✓ ✓ $4.40 |
+| ucfopen__canvasapi-716 | ✓ ✗ $2.79 | ✓ ✓ $1.16 | ✓ ✓ $1.56 |
+| pallets__click-3239 | ✓ ✓ $4.35 | ✓ ✓ $2.51 | ✓ ✓ $4.10 |
+| python-scim__scim2-models-139_interface | ✓ ✓ $5.47 | ✓ ✓ $2.51 | ✗ ✓ $5.02 |
+| pallets-eco__wtforms-892_interface | ✗ ✗ $2.34 | ✗ ✗ $1.12 | ✗ ✗ $2.30 |
+
+## Against Devin's own Fusion (round devin-r1, 2026-09-29)
+
+This round compared the plugin (0.2.0) with Fusion inside Devin, using the same pair: GPT-6 Astra (high) as Lead and
+SWE-2 (medium) as Sidekick. Both got the same prompt, the same fresh checkouts and the same hidden-test grading. Each
+single model ran alone as a baseline.
+
+Seven attempts were excluded as contaminated:
+- Six Devin reruns started in workspaces that still held the hidden tests from grading an earlier, quota-blocked
+  attempt.
+- One DSH Sidekick downloaded the upstream fix. It still failed.
+
+The four tasks that were clean in every condition give this result:
+
+| Condition | Resolved | Cost | Mean minutes |
+| --- | --- | --- | --- |
+| **DSH Fusion: Astra + SWE-2** | **4/4** | **$2.73** | 20.1 |
+| Devin Fusion: Astra + SWE-2 | 3/4 | $4.81 | 6.0 |
+| Devin, Astra alone | 3/4 | $8.13 | 5.1 |
+| DSH, Astra alone (round 4) | 3/4 | $10.11 | 5.8 |
+
+- Fusion was cheaper than the single model on both harnesses: 41% less on Devin and 73% less on DSH.
+- The one task only DSH Fusion solved was sqlfluff-7615.
+- Four tasks with one attempt each cannot rank the two systems. It is no claim of parity or superiority.
+- SWE-2 is free in Devin's catalog and is priced at $0 on both sides, so these costs are the Lead's.
+- The plugin's Sidekick used about 4× Devin's Sidekick calls, and the plugin took about 3.4× Devin's wall time.
+- Freshly processed prompt input was 5% of all prompt tokens for the plugin and 19% for Devin Fusion.
+- Protocol, deviations and root causes: [REBENCH_DEVIN.md](REBENCH_DEVIN.md) and
+  `benchmark/rebench/results-devin-r1/`.
+
+## Setup
+
+**Tasks.** Nine instances from `nebius/SWE-rebench-leaderboard` (split 2026_03): real GitHub issues with the
+maintainers' fix. Each was validated without a model: its FAIL_TO_PASS tests fail at the base commit, and every
+FAIL_TO_PASS and PASS_TO_PASS test passes with the maintainers' patch.
+
+| Tier | Instance | Maintainers' patch | FAIL_TO_PASS / PASS_TO_PASS |
+| --- | --- | --- | --- |
+| easy | pypa__twine-1309 | 1 file, 15 lines | 1 / 3 |
+| easy | delgan__loguru-1451 | 1 file, 16 lines | 2 / 22 |
+| easy | sqlfluff__sqlfluff-7615 | 2 files, 12 lines | 1 / 24 |
+| medium | pycqa__isort-2491 | 1 file, 50 lines | 1 / 73 |
+| medium | holoviz__param-1117 | 1 file, 47 lines | 2 / 94 |
+| medium | ucfopen__canvasapi-716 | 1 file, 43 lines | 2 / 60 |
+| hard | pallets__click-3239 | 3 files, 131 lines | 4 / 694 |
+| hard | python-scim__scim2-models-139_interface | 5 files, 279 lines | 9 / 0 |
+| hard | pallets-eco__wtforms-892_interface | 8 files, 107 lines | 10 / 0 |
+
+**Protocol.**
+- Each attempt starts from a fresh checkout at the base commit with dependencies in `./.venv`.
+- The hidden tests and the maintainers' patch never enter a workspace.
+- Every condition gets the same prompt: the issue text and how to use `./.venv`, with no hints and no mention of
+  Fusion or delegation.
+- Grading follows the official harness: restore the files the hidden test patch touches, apply it, run the tests.
+  An attempt is resolved only if every FAIL_TO_PASS and PASS_TO_PASS test passes.
+- No model outcome is retried. Infrastructure or provider failures are rerun once and listed.
+- Nobody edits a candidate, answers a model's question or changes the plugin during a round.
+- Conditions rotate per task; concurrency 3; 6-hour limit per attempt (never reached).
+- Models: GPT-6 Astra through the ChatGPT subscription route, GLM-5.3-Flash and Grok 4.6 through their own routes, all
+  at reasoning effort `high`, permission preset "approve for me".
+
+**Cost.** Tokens come from DSH's own session logs for the Lead and every Sidekick session it started, converted with
+list prices (USD per 1M tokens, uncached input / cache read / output): gpt-6-astra 10 / 1 / 50, grok-4.6 2 / 0.3 / 6,
+glm-5.3-flash 0.15 / 0.03 / 0.50. The ratio that the rules use is the median over the 18 paired attempts (same task,
+same repetition) of Fusion cost ÷ Astra-alone cost.
+
+## How the result was reached
+
+Each round was preregistered (question, conditions and decision rules written before the first model call).
+
+| Round | Question | Outcome |
+| --- | --- | --- |
+| 1–2 | Fusion with a GLM-5.3 (max) Lead | Found plugin defects (Lead blocking delegation, attempts where the Sidekick never ran). A GLM Lead is too close in price to the Sidekick to show a saving. Not included here. |
+| 3 | Astra + Flash, one attempt per task ([preregistration](REBENCH_ROUND3.md), [conclusion](../benchmark/rebench/results-r3/CONCLUSION.md)) | 6/9 vs Astra 5/9; cost ratio 0.67. Showed that exact wording in requirements could get lost between brief and implementation → verbatim requirements with per-requirement verdicts. |
+| 4 | Which Sidekick: Grok 4.6 or Flash ([preregistration](REBENCH_ROUND4.md), [conclusion](../benchmark/rebench/results-r4/CONCLUSION.md)) | Both beat Astra on quality; neither reached the 0.6 cost rule. Cause: the Lead's prompt cache (69% hits) — its tool list changed with the task phase, and keepalive was off. |
+| 5 | Same after the cache fixes ([conclusion](../benchmark/rebench/results-r5/CONCLUSION.md)) | Lead cache hits 85%, Lead cost −37%; Astra + Flash meets both rules. |
+
+Round 5 also corrected a measurement error: Sidekick sessions are attributed by their `parentSession`, since repeated
+rounds reuse workspace paths. `results.raw.jsonl` keeps the uncorrected rows.
+
+## Limitations
+
+- Small sample: nine tasks, two attempts each. A difference of one or two tasks is within noise.
+- Python only, and all from one benchmark split. The issues are public and may be in the models' training data.
+- One machine, one user's subscriptions; Astra alone comes from round 4 (a day earlier), not from round 5.
+- Costs are list-price estimates. Subscription plans bill differently.
+- The Lead takeover path never triggered in a real run; only automated tests cover it.
+
+## Reproduce
+
+Requires DSH 0.1.7-rc.2 running with Fusion installed and the models signed in, a checkout of the same Harness release
+(`DSH_ROOT`, used to talk to the running Host), Node 22, Python 3 and `uv` (task environments use Python 3.13).
+
+```sh
+export DSH_ROOT=/path/to/deepseek-harness-0.1.7-rc.2
+cd benchmark/rebench
+python3 harness.py fetch && python3 harness.py validate          # download and validate the nine tasks (no model calls)
+python3 run.py --plan plan-r5.json --out results.jsonl --dry-run # grade the maintainers' patches: proves the setup
+python3 run.py --plan plan-r5.json --out results.jsonl --cleanup # the real run
+python3 report.py results.jsonl
+```
+
+`plan-r5.json` names the providers used here; change them to your own routes. Raw rows for every round are in
+`benchmark/rebench/results-r*/`.