dsh-llm-fallbacks 0.6.5 → 0.6.7

package/dist/subagents-seam.d.ts

@@ -1,13 +1,14 @@
 /**
  * Dispatch-seam role resolution + per-child record (plan
- * role-based-subagent-adoption Task 1).
+ * role-based-subagent-adoption Task 1; rc.1 `startActivation` migration, plan
+ * dsh-021-subagent-seam-repair Task 2).
  *
  * The seam is the documented cordis service-read waterfall
  * (`Events['internal/get']`, `@deepseek-ai/cordis`
  * `lib/types/events.d.ts`): a listener wraps the `subagents` service VALUE on
- * read and returns a prototype-delegating wrapper whose `start` /
- * `startContinuable` resolve the dispatch role from the incoming request
- * BEFORE delegating. The real service object is never mutated; readers of the
+ * read and returns a prototype-delegating wrapper whose `startActivation`
+ * resolves the dispatch role from the incoming activation spec BEFORE
+ * delegating. The real service object is never mutated; readers of the
  * `subagents` service transparently receive the wrapper.
  *
  * Role source (plan Global Constraints): the child request's prompt carries
@@ -29,34 +30,36 @@
  * ambiguity rule stands unchanged: the DISTINCT DECLARED ids must collapse to
  * exactly one, else the dispatch is a no-op — never a first-occurrence pick.
  *
- * Per-child record: the wrapped start's RESULT carries the child session id —
- * `start` resolves to a `SubagentRun` (`id` IS the published child session id
- * for a local run) and `startContinuable` to a `ContinuableStart` (`childId`).
- * The record `{ role, at, firstNoticePending }` is keyed by that id (Task 3
- * reads it to emit the one role notice row). A result carrying only a
- * `jobId` — a registry job id, NOT a session id — is never keyed: the child is
- * correlated instead through the parent-owned `subagent/catalog` session event
- * `{ childId, label }` joined on the delegating parent + request label.
+ * Per-child record + the timing rule (rc.1 `startActivation`): the record
+ * `{ role, at, firstNoticePending }` is keyed by the child id (Task 3 reads it
+ * to emit the one role notice row). The child is created INSIDE the native
+ * call — `manager.startLocal` mints/uses `spec.childId` and only then resolves
+ * the activation — so `agent/created` fires BEFORE any `.then` on this side
+ * could key a record off the resolved `SubagentActivation.childId`. The
+ * wrapper therefore reserves the child id itself for a LOCAL backend (the
+ * provider exposes `prepareContinuable`; a reserved id on any other backend is
+ * rejected with `UNSUPPORTED_CAPABILITY`) and writes the record SYNCHRONOUSLY
+ * before delegating, deleting it when the native call fails. An EXTERNAL
+ * backend allocates its own child id, receives the caller's OWN spec object
+ * untouched, and has its record keyed off the resolved activation's `childId`.
  *
- * Persona delivery (plan Task 2): the SAME single resolution point merges the
- * declared role's `roles.list[].persona` (trimmed, non-empty) into the
- * request's NATIVE `persona` slot — the slot the runtime composes as the
- * scoped `deployment:persona-prefix` system-prompt section on the child. The
- * source is the RESOLVED ROLE only, so delivery is chain-independent: a
- * `chain: []` role gets its persona exactly like a chained one (no routing
- * state is read). Both native start surfaces are covered, with the gate each
- * one's fail-loud contract needs (measured on the installed
- * `@deepseek-ai/dsh-subagent`): the one-shot `start` REJECTS a
- * request carrying `persona` for a provider whose
- * `getProvider(name).capabilities.persona` is not `true` (`lib/index.js:3284,3340-3363`,
- * `assertCapabilities`), so the merge pre-checks that flag; the continuable
- * surface is composed by the continuation manager, which applies
- * `request.persona` unconditionally (`lib/index.js:1691`) and is gated by
- * the provider's `prepareContinuable` presence instead (`lib/index.js:3316-3319`).
- * A gate miss skips the persona with ONE contained debug log — never a failed
- * start. An explicit caller `persona` WINS (the slot is filled only when it is
- * absent), and every skip path returns the caller's OWN request object, so the
- * native call stays byte-identical.
+ * A result carrying no child id — a `jobId` is a registry id, NOT a session id
+ * — is never keyed: the child is correlated instead through the parent-owned
+ * `subagent/catalog` session event `{ childId, label }` joined on the
+ * delegating parent + the activation `label` (the same string the cataloged
+ * child membership carries).
+ *
+ * Persona delivery is NO LONGER this module's job (plan Task 1): rc.1 removed
+ * `SubagentStartRequest.persona`, so the resolved role's persona is registered
+ * as a scoped `deployment:persona-prefix` section on the CHILD's own context
+ * by `./role-persona.ts`, over the SAME ROOT-shared record map this module
+ * writes. That listener owns the `personaNotApplied` verdict the notice row
+ * reads — EXCEPT when a reservation failure means it can never see the child
+ * (the runtime mints its own child id and `agent/created` has already run), in
+ * which case this module resolves the same question against the live roles
+ * source and carries the verdict onto the record keyed off the RESOLVED id,
+ * before the child's first pre-step. This module writes no request field,
+ * reads no provider persona capability, and injects no agent preset.
  *
  * In-session notice row (plan Task 3): the SAME install point registers the
  * `agent/pre-step` emitter (`./role-notice.ts`) over the record map it owns, so
@@ -103,14 +106,14 @@ export interface SubagentSeamRecord {
      * The DECLARED RAW role id resolved at the dispatch seam.
      *
      * Authoritative-role precedence (CF-10, documented rather than resolved by
-     * re-branding): a `startContinuable` resume re-keys the child and may resolve
-     * a DIFFERENT declared role, and this field is then rewritten while the
+     * re-branding): a resume that reuses a reserved `childId` may resolve a
+     * DIFFERENT declared role, and this field is then rewritten while the
      * durable notice row the child's session already carries keeps the FIRST role.
      * The projection deliberately reads the notice row, so the durable role is the
      * child's announced identity and this record is only the LIVE dispatch hint
-     * (what the next start / the resume fallback would use). The two can therefore
-     * disagree after a re-dispatch until the child is disposed; no consumer may
-     * treat the record as the durable role.
+     * (what the next activation / the resume fallback would use). The two can
+     * therefore disagree after a re-dispatch until the child is disposed; no
+     * consumer may treat the record as the durable role.
      */
     role: string;
     /** When the record was written (epoch ms). */
@@ -126,20 +129,24 @@ export interface SubagentSeamRecord {
     firstNoticePending: boolean;
     /**
      * `true` when the role DECLARES a persona and that persona was NOT delivered
-     * (Task 2's capability gate declined it, or no provider was registered to
-     * carry it). Absent when there was nothing to report: the persona was
-     * delivered, the caller set one (explicit intent wins), the role declares
-     * none, or no persona source is wired. Task 3 appends
-     * ` (persona not applied)` on `true` only.
+     * onto the child. Written by the `agent/created` role-persona listener
+     * (`./role-persona.ts`) over this same map — except when a reservation
+     * failure means that listener can never see the child (the runtime mints its
+     * own child id), where the seam itself carries the verdict onto the record
+     * keyed off the RESOLVED id. The seam never delivers or reads a persona
+     * other than for that one question. Absent when there was nothing to report:
+     * the section was registered, a same-name section was already on the child's
+     * scope (whoever registered it), the listener never saw the child (an
+     * EXTERNAL backend creates no local agent), the role declares none, or no
+     * persona source is wired. Task 3 appends ` (persona not applied)` on `true`
+     * only.
      *
-     * STICKY (Task 3 review Minor 4): a record rewrite (a `startContinuable`
-     * resume re-keys the child) can only ADD this verdict, never clear it. A
-     * resume recomputes the merge outcome on its own surface — and that surface
-     * legitimately returns `false` when it delivers the CALLER's persona or when
-     * its own merge degrades — but neither retroactively installs the role's
-     * DECLARED persona on the dispatch that already reported it missing. The
-     * child's one notice row is a claim about that dispatch, so the first `true`
-     * survives; a later `false` is simply not recorded.
+     * STICKY (Task 3 review Minor 4): a record rewrite — a resume reusing the
+     * reserved `childId`, or the resolved activation re-keying the same child
+     * after `agent/created` already ran — can only ADD this verdict, never clear
+     * it. A rewrite carries no verdict of its own, and the child's one notice row
+     * is a claim about the dispatch that already reported it missing, so the first
+     * `true` survives.
      */
     personaNotApplied?: boolean;
 }
@@ -149,29 +156,29 @@ export interface SubagentPromptBlockView {
     readonly text?: string;
 }
 /**
- * Structural view of the one-shot start request (consumed fields only): the
- * `prompt` is the role-extraction source, `label` + `parent` are the
- * catalog-correlation join key, and `persona` is the NATIVE per-child persona
- * slot the role persona is merged into (plan Global Constraints: an explicit
- * caller value wins). The wrapper forwards the request object itself, so every
- * other field reaches the service unchanged.
+ * Structural view of the activation request (consumed fields only): `prompt` is
+ * the role-extraction source and `parent` is the catalog-correlation join half.
+ * The wrapper forwards the request OBJECT itself, so every other field (cwd,
+ * agentOptions, outputSchema, maxDepth, the signal) reaches the service
+ * unchanged.
  */
 export interface SubagentStartRequestView {
     readonly prompt?: readonly SubagentPromptBlockView[];
-    readonly label?: string;
     readonly parent?: {
         readonly session?: {
             readonly id?: string;
         };
     };
-    readonly persona?: string;
 }
 /**
- * Structural view of the continuable start spec (consumed fields only):
- * `childId` is the caller-reserved identity a resume already carries, used as
- * the record fallback when the resume request has no Assignment header.
+ * Structural view of the activation spec (rc.1 `SubagentActivationSpec`,
+ * consumed fields only): `childId` is the caller-reserved identity a resume
+ * already carries — also the record fallback when the request carries no
+ * Assignment header — and `label` is the catalog join's other half (the
+ * cataloged child membership carries this exact string). `signal`, `delivery`
+ * and every future field travel with the caller's spec object.
  */
-export interface ContinuableStartSpecView {
+export interface SubagentActivationSpecView {
     readonly provider: string;
     readonly label?: string;
     readonly childId?: string;
@@ -180,14 +187,16 @@ export interface ContinuableStartSpecView {
 /** Options for {@link installSubagentSeam}. */
 export interface SubagentSeamOptions {
     /**
-     * Live declared-role id map (trimmed id → DECLARED RAW id), read per start
-     * so a settings change is observed without a re-install.
+     * Live declared-role id map (trimmed id → DECLARED RAW id), read per
+     * activation so a settings change is observed without a re-install.
      */
     roleIds: () => ReadonlyMap<string, string>;
     /**
-     * Live declared roles (`roles.list`) — the persona source, read per start so
-     * a settings/persona edit is observed without a re-install. Absent ⇒ the
-     * seam only records roles (no persona delivery).
+     * Live declared roles (`roles.list`) — the SAME source `./role-persona.ts`
+     * reads. Consulted ONLY when a reservation failure means that listener can
+     * never see the child: the seam is then the only place left that can carry
+     * the persona verdict to the child's notice row. Absent (no persona source is
+     * wired) ⇒ no verdict, exactly like a listener that never saw the child.
      */
     roles?: () => readonly FallbacksRole[];
     /** Contained debug sink (at most one line per contained degrade). */
@@ -196,10 +205,12 @@ export interface SubagentSeamOptions {
 /** The installed seam (Task 3 surface + explicit teardown). */
 export interface SubagentSeam {
     /**
-     * Per-child records keyed by the child SESSION id (the wrapped start's
-     * result id). ROOT-shared (CF-5): every fiber applied over the same root reads
+     * Per-child records keyed by the child id — the reserved id this wrapper
+     * wrote before a local activation, or the `childId` a resolved activation
+     * reported. ROOT-shared (CF-5): every fiber applied over the same root reads
      * the same map. Mutable by design: Task 3 clears `firstNoticePending` after
-     * emitting the notice.
+     * emitting the notice, and the role-persona listener writes
+     * `personaNotApplied`.
      */
     readonly records: Map<string, SubagentSeamRecord>;
     /**
@@ -253,7 +264,9 @@ export declare const PENDING_CORRELATION_LIMIT = 64;
  */
 export declare function resolveDeclaredRoleFromAssignment(prompt: string, roleIds: ReadonlyMap<string, string>): string | undefined;
 /**
- * PURE, chain-independent persona lookup (plan Task 2 / Global Constraints):
+ * PURE, chain-independent persona lookup for the `agent/created` role-persona
+ * listener (`./role-persona.ts`; rc.1 delivers the persona as a scoped prompt
+ * section on the child, never as a request field):
  * the DECLARED `persona` of `roleId`, trimmed, and only when it is still
  * non-empty after the trim — a blank persona is NO persona. `roleId` is the
  * DECLARED RAW id the seam already resolved, so this is an exact id match, not

package/package.json

@@ -5,7 +5,7 @@
     "dsh",
     "dsh-plugin"
   ],
-  "version": "0.6.5",
+  "version": "0.6.7",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -64,30 +64,31 @@
     "use-sync-external-store": "^1.6.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-api-gateway": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-api-remotes": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-api-session-controller": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-connection": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-locale": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-store": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-chat": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-plugin-manager": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-commands": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-llm-retry": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-session": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-session-projection": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-settings": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-tool-subagent": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-typert-registry": "^0.2.0-rc.2",
-    "@deepseek-ai/schemastery": "^3.18.2",
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-agent": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-api-gateway": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-api-remotes": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-api-session-controller": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-connection": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-store": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-chat": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-commands": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-llm-retry": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-session-projection": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-settings": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-tool-subagent": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-typert-registry": "^0.2.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.5",
     "react": "^18.2.0"
   },
   "devDependencies": {

package/scripts/repair-session-logs.ts

@@ -9,8 +9,12 @@
  * and — only for the classes whose normalization is provably shape-preserving
  * (the rule registry in `./session-logs/rules.ts`) and only with a resolved
  * released catalog as the oracle (`./session-logs/catalog.ts`) — publishes a
- * current-generation successor beside the original
- * (`./session-logs/publish.ts`). The original generation is never modified.
+ * REPAIR-FLOOR (v3) successor beside the original (`./session-logs/publish.ts`).
+ * The original generation is never modified. A newer installed catalog supplies
+ * that floor through its own `historicalSessionFormatCatalog`; the host migrates
+ * the published v3 generation onward when it opens the session, with its own
+ * historical child evidence (the V3→V4 edge needs evidence no single-log repair
+ * can produce — see `CatalogHandle.floor`).
  *
  * This module CONSUMES the frozen Task 1/2 modules; it re-implements none of
  * them. The refusal vocabulary, the rule registry, the oracle resolution and
@@ -134,8 +138,8 @@
  * at all (`skipped`), or a stale `session.repair.*.jsonl.zstd.tmp` was found under
  * the root; 2 = fatal (bad arguments, missing/unreadable
  * `--root`, `--apply` without a resolved catalog, a catalog below the required
- * format version, `--apply --drop-legacy-events` without `--backup`, or a runtime
- * without zstd).
+ * format version or a newer catalog without a usable repair floor,
+ * `--apply --drop-legacy-events` without `--backup`, or a runtime without zstd).
  */
 import { createHash } from 'node:crypto'
 import { constants as fsConstants } from 'node:fs'
@@ -149,6 +153,7 @@ import {
   REQUIRED_CATALOG_VERSION,
   catalogVersionRefusal,
   classifyWithCatalog,
+  repairCatalog,
   resolveCatalog,
   restoreRows,
 } from './session-logs/catalog.ts'
@@ -733,6 +738,12 @@ export interface RunResult {
       packageVersion: string | null
       /** The format version that catalog declares as current. */
       currentVersion: number
+      /**
+       * The format version this tool REPAIRS TO (the floor): the declared
+       * `currentVersion` on a build at the floor, otherwise that build's
+       * historical V0–V3 catalog. Successors are published at this version.
+       */
+      repairVersion: number
     }
     | { resolved: false }
   logs: LogOutcome[]
@@ -801,8 +812,11 @@ function strictRefusalOf(rows: readonly ParsedRow[], catalog: CatalogHandle | nu
     // differs from this one exactly by `recovery`, so a refusal found here can only
     // mean the rows after it are dropped — not merely that the session is not
     // current-shaped. Using the publisher's `validation: 'current'` axis here would
-    // over-claim truncation for a log that loses no rows at all.
-    restoreRows(catalog.catalog, structuredClone(rows), { recovery: 'strict', validation: 'transformed' })
+    // over-claim truncation for a log that loses no rows at all. The restore goes
+    // through the REPAIR FLOOR (the pre-V3 chain this tool repairs along and the
+    // generation it publishes); the host's floor→current migration needs
+    // corpus-level child evidence and is outside a single log's verdict.
+    restoreRows(repairCatalog(catalog), structuredClone(rows), { recovery: 'strict', validation: 'transformed' })
     return null
   } catch (error) {
     const cause = error instanceof Error ? error.cause : undefined
@@ -1004,7 +1018,10 @@ function lossyDropRefusal(
   try {
     // A defensive copy: the released restore normalizes a packed Assistant run's
     // stream IN PLACE, and `repaired` is what the publisher is about to write.
-    restoreRows(catalog.catalog, structuredClone(repaired), { recovery: 'strict', validation: 'transformed' })
+    restoreRows(repairCatalog(catalog), structuredClone(repaired), {
+      recovery: 'strict',
+      validation: 'transformed',
+    })
   } catch (error) {
     return {
       ok: false,
@@ -1228,23 +1245,25 @@ async function analyzeLog(candidate: LogGeneration, context: InspectContext): Pr
   }
   const renumbered = verdict === null ? 0 : verdict.renumberedEventCount
 
-  // The successor NAME needs the catalog's current version, so it is only known
-  // with a resolved oracle: in report mode without one nothing is probed (the log
-  // is still reported `repairable` from the rule registry alone), and `--apply`
-  // was already refused as fatal by the caller — which is why the null case is
-  // checked here rather than assumed away.
+  // The successor NAME needs the repair floor's version, so it is only known with
+  // a resolved oracle: in report mode without one nothing is probed (the log is
+  // still reported `repairable` from the rule registry alone), and `--apply` was
+  // already refused as fatal by the caller — which is why the null case is checked
+  // here rather than assumed away.
   //
   // The name comes from the publisher's own exported rule (no local copy). Note
-  // the two INPUTS differ: this probe uses the resolved catalog's declared
-  // `currentVersion`, while `publishSuccessor` derives its target from the version
-  // the RESTORED header settles on. They agree for every catalog whose restore
-  // settles at the version it declares (the released one does — its successor is
-  // read back and pinned to that version before publication); a catalog that
-  // declared one version and settled at another would leave this probe looking for
-  // a name the publication never used, so report mode alone could call such a log
-  // unpublished while `--apply` accepts the existing successor as byte-identical.
+  // the two INPUTS differ: this probe uses the handle's REPAIR FLOOR version,
+  // while `publishSuccessor` derives its target from the version the RESTORED
+  // header settles on. They agree for every released catalog (the floor catalog's
+  // restore settles at the floor it declares, and the publisher pins the
+  // successor to it before publication); a catalog whose restore settled at a
+  // different version would leave this probe looking for a name the publication
+  // never used, so report mode alone could call such a log unpublished while
+  // `--apply` accepts the existing successor as byte-identical.
   const catalog = context.catalog
-  const expected = catalog === null ? null : context.successorFilename(catalog.catalog.currentVersion)
+  const expected = catalog === null
+    ? null
+    : context.successorFilename(repairCatalog(catalog).currentVersion)
   const successorPath = expected === null ? null : join(candidate.sessionDir, expected)
   const existingSuccessor =
     successorPath !== null && (await fileExists(successorPath)) ? successorPath : null
@@ -1493,10 +1512,11 @@ export async function runRepair(
       throw new FatalError(messageOf(error))
     }
   }
-  // The oracle is pinned to a RELEASE, in every mode: the same module encodes the
-  // successor and reads it back, so "it accepts its own output" is only evidence
-  // when the module is the build that will read the session. A catalog below the
-  // floor is a fatal (exit 2), not a quieter classification.
+  // The oracle is pinned to a RELEASE, in every mode: the floor catalog encodes
+  // the successor and reads it back, so "it accepts its own output" is only
+  // evidence when the floor comes from the build that will read the session. A
+  // catalog below the floor, or a newer build with no usable floor, is a fatal
+  // (exit 2), not a quieter classification.
   const catalogProblem = catalog === null ? null : catalogVersionRefusal(catalog)
   if (catalogProblem !== null) throw new FatalError(catalogProblem)
 
@@ -1510,6 +1530,7 @@ export async function runRepair(
       resolvedBy: catalog.resolvedBy,
       packageVersion: catalog.packageVersion,
       currentVersion: catalog.catalog.currentVersion,
+      repairVersion: repairCatalog(catalog).currentVersion,
     }
 
   const reportRules = policyRules(options.dropLegacyEvents)
@@ -1741,6 +1762,9 @@ function reportHead(head: ReportHead, io: CliIO): void {
   io.out(
     head.catalog.resolved
       ? `catalog: ${head.catalog.modulePath} (v${head.catalog.currentVersion},`
+        + `${head.catalog.repairVersion === head.catalog.currentVersion
+          ? ''
+          : ` repair target v${head.catalog.repairVersion},`}`
         + ` package ${head.catalog.packageVersion ?? 'version unknown'}, resolved by ${head.catalog.resolvedBy})`
       : `catalog: none resolved — classification is STRUCTURAL ONLY and --apply would refuse `
         + `(no --catalog, no ${CATALOG_ENV_VAR}, no dsh on PATH, no npx install)`,
@@ -1884,15 +1908,19 @@ export function usage(): string {
 Triage (default, read-only) and repair (--apply) pre-V3 dsh session logs. A log is
 refused when the FROZEN released migration chain cannot classify it; this tool names
 the refusal class and, for the classes whose normalization is provably
-shape-preserving, publishes a current-generation successor beside the original. The
-original generation is never modified and never truncated.
+shape-preserving, publishes a REPAIR-FLOOR (v${CURRENT_VERSION_FLOOR}) successor generation
+beside the original. The original generation is never modified and never truncated.
+The floor stays v${CURRENT_VERSION_FLOOR} even when the installed catalog is newer: the next
+released edge (v${CURRENT_VERSION_FLOOR}->v${CURRENT_VERSION_FLOOR + 1}) needs historical child evidence a
+single-log repair cannot produce, so the host migrates the published v${CURRENT_VERSION_FLOOR}
+generation onward when it opens the session.
 
   --root DIR     session root to walk (default: $DSH_HOME or ~/.dsh, then /sessions).
                  Every <namespace>/<session>/ directory's newest canonical generation
                  below format v${CURRENT_VERSION_FLOOR} is considered; noncanonical names (staged
-                 .tmp files, .bak copies) are ignored, and a current generation already
-                 present beside it is reported as an already published successor (proven
-                 by a read-back) instead of being a repair target.
+                 .tmp files, .bak copies) are ignored, and a repair-floor generation
+                 already present beside it is reported as an already published
+                 successor (proven by a read-back) instead of being a repair target.
                  A namespace/session directory that cannot be read, a canonical
                  generation BELOW the format floor that is a symlink or not a regular
                  file, and a stale session.repair.*.jsonl.zstd.tmp are REPORTED (a
@@ -1903,7 +1931,8 @@ original generation is never modified and never truncated.
                  Symlinks are reported, never followed: a repair writes beside the
                  generation it repairs, which must stay inside --root.
   --apply        run the rules' proofs and publish a successor generation per repaired
-                 log. Requires a resolved catalog. Default: read-only report.
+                 log, at the repair floor (v${CURRENT_VERSION_FLOOR}). Requires a resolved catalog.
+                 Default: read-only report.
                  The revision this run DECODED is digest-checked against the file before
                  anything is staged, so a concurrent append is refused before the first
                  write; if the source moves after a publication this run CREATED, that
@@ -1924,9 +1953,14 @@ original generation is never modified and never truncated.
                  resolves, then the newest ~/.npm/_npx install. The resolved module is
                  EXECUTED, not parsed (the same privilege as running this tool), and it
                  must declare currentVersion >= ${CURRENT_VERSION_FLOOR}: a below-floor catalog is
-                 refused with exit 2 rather than trusted to verify its own output. A file
-                 candidate whose owning package.json names a different package is
-                 refused too. The report names the module path, its format version and
+                 refused with exit 2 rather than trusted to verify its own output. When
+                 currentVersion is ABOVE the floor, the module must also export
+                 historicalSessionFormatCatalog (that build's V0-V${CURRENT_VERSION_FLOOR} reader/encoder):
+                 the floor catalog restores and verifies the published v${CURRENT_VERSION_FLOOR} successor
+                 and the host migrates it onward with its own child evidence; a build
+                 without a usable floor is refused with exit 2. A file candidate whose
+                 owning package.json names a different package is refused too. The
+                 report names the module path, its format version, the repair target and
                  its package version.
   --backup       copy the original generation to <name>.bak before publishing. A run
                  that ends up publishing nothing removes the copy IT created again,