dsh-llm-fallbacks 0.6.6 → 0.6.8

package/dist/role-resolution.d.ts

@@ -1,17 +1,23 @@
 /**
- * Dispatch-time three-stage role resolution (plan fallbacks-role-automatch
- * Task 2).
+ * Dispatch-time role resolution (plan fallbacks-role-automatch Task 2; the
+ * dispatch-role stage added by plan dsh-148-agent-team-role-delivery Task 1).
  *
- * Precedence (first hit wins):
+ * Precedence (first hit wins) across four ordered stages:
  * 1. explicit — `session.header.agentPreset` trimmed matches a declared role
  *    id → that role's DECLARED RAW id (via the `roleIds` trimmed-id map, the
  *    same canonicalization the rules path uses); the reserved `'inherit'`
  *    and undeclared presets are NEVER dispatchable explicit roles and fall
- *    through to rules;
- * 2. rules — the existing `resolveRole` passthrough, unchanged (a declared
+ *    through to the next stage;
+ * 2. dispatch — `opts.dispatchRole`: the role the dispatch seam resolved from
+ *    the Assignment/teammate prompt (`**Execute as**: <id>`, the single
+ *    parser in `src/subagents-seam.ts`), canonicalized by the same trim +
+ *    `roleIds` lookup. An absent, empty, `'inherit'` or no-longer-declared
+ *    reference falls through silently — a role removed after the dispatch is
+ *    not an error;
+ * 3. rules — the existing `resolveRole` passthrough, unchanged (a declared
  *    role wins; no-rule-match / an explicit rule targeting `'inherit'`
  *    resolve to `'inherit'`);
- * 3. auto-match — only when stage 2 resolved to `'inherit'` AND
+ * 4. auto-match — only when stage 3 resolved to `'inherit'` AND
  *    `opts.automatchEnabled`: call `opts.automatch` with the agent. The hook
  *    (Task 3 supplies the bounded LLM caller) MUST return a declared raw id
  *    or `null`; the resolver defensively validates the return against
@@ -35,10 +41,16 @@ import type { Selector } from './selectors.ts';
 export type { FallbacksRoleRule } from './config.ts';
 /** Options for {@link resolveRoleAtDispatch}. */
 export interface ResolveRoleAtDispatchOptions {
+    /**
+     * Dispatch-declared role: the DECLARED RAW id the seam resolved from the
+     * Assignment/teammate prompt (`**Execute as**: <id>`). Validated against the
+     * live `roleIds` map; absent, `inherit`, or no-longer-declared → skipped.
+     */
+    dispatchRole?: string;
     /**
      * Whether the auto-match stage may run (the `roleAutoMatch` config switch).
-     * When `false`, stage 3 never runs and the outcome is identical to the
-     * rules stage alone.
+     * When `false`, stage 4 never runs and the outcome is identical to the
+     * explicit/dispatch/rules stages alone.
      */
     automatchEnabled: boolean;
     /**
@@ -64,10 +76,11 @@ export interface ResolveRoleAtDispatchOptions {
     };
 }
 /**
- * Resolve the dispatch-time role for an agent across three ordered stages
- * (explicit → rules → auto-match hook). Never throws on its own inputs; the
- * hook's own rejection is deliberately NOT caught here (the Task-3/4 wiring
- * bounds the LLM call so it never throws out of the request path).
+ * Resolve the dispatch-time role for an agent across four ordered stages
+ * (explicit → dispatch → rules → auto-match hook). Never throws on its own
+ * inputs; the hook's own rejection is deliberately NOT caught here (the
+ * Task-3/4 wiring bounds the LLM call so it never throws out of the request
+ * path).
  *
  * `roleIds` is the canonical trimmed-id map (`trimmed id → declared raw id`,
  * built in `src/index.ts` apply()): every stage canonicalizes its reference

package/dist/roles.d.ts

@@ -3,10 +3,12 @@
  * Task 1).
  *
  * This module is the RULES stage. Dispatch-time role resolution
- * (plan fallbacks-role-automatch) is the three-stage resolver in
- * `role-resolution.ts` — explicit (`session.header.agentPreset`) → this
- * rules stage → an optional auto-match hook; `AgentLike` carries the additive
- * `session.header.agentPreset?` carrier for that explicit stage.
+ * (plan fallbacks-role-automatch; plan dsh-148 added the dispatch stage) is
+ * the four-stage resolver in `role-resolution.ts` — explicit
+ * (`session.header.agentPreset`) → dispatch-declared role (the seam record
+ * resolved from `**Execute as**`) → this rules stage → an optional auto-match
+ * hook; `AgentLike` carries the additive `session.header.agentPreset?`
+ * carrier for that explicit stage.
  *
  * Precedence (first hit wins):
  * 1. the first `rules` entry whose specified provider/model patterns match

package/package.json

@@ -5,7 +5,7 @@
     "dsh",
     "dsh-plugin"
   ],
-  "version": "0.6.6",
+  "version": "0.6.8",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

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,

package/scripts/session-logs/catalog.ts

@@ -67,12 +67,20 @@ const CATALOG_PACKAGE_DIR = 'dsh-session-format-catalog'
 export const CATALOG_ENV_VAR = 'DSH_SESSION_FORMAT_CATALOG'
 
 /**
- * The oldest released catalog this tool accepts as its oracle: the format
+ * The oldest released catalog this tool accepts as its oracle AND the format
  * generation it repairs TO (`CURRENT_VERSION_FLOOR`, the pre-V3 scope). A catalog
  * below it cannot read a successor this tool would write, so `--apply` must
  * refuse rather than verify its own output against a build the GUI does not run.
  * One constant for both the selection scope and the oracle floor: they are the
  * same number and must not drift.
+ *
+ * The repair target stays at this floor even when the installed build is newer:
+ * the tool only repairs logs BELOW the floor, and the next released edge
+ * (V3→V4) requires historical child evidence (one parent's complete child
+ * descriptors) that a single-log repair cannot produce. The successor is
+ * therefore encoded through the newer build's own `historicalSessionFormatCatalog`
+ * (see {@link CatalogHandle.floor}) and the host migrates it onward, with its own
+ * child facts, exactly like any other readable pre-V3 session it opens.
  */
 export const REQUIRED_CATALOG_VERSION = 3
 
@@ -131,24 +139,77 @@ export interface CatalogHandle {
   readonly packageVersion: string | null
   /** The released catalog module's `sessionFormatCatalog` export. */
   readonly catalog: ReleasedCatalog
+  /**
+   * The catalog generation this tool REPAIRS TO — the format floor
+   * ({@link REQUIRED_CATALOG_VERSION}): the declared catalog itself when the
+   * resolved build is AT the floor, otherwise that build's
+   * `historicalSessionFormatCatalog` export (the V0–V3 reader/encoder).
+   *
+   * Every restore, classification and published successor goes through this
+   * catalog, so the successor's header version (and the `N` in its canonical
+   * filename) is the floor, never a generation whose migration needs evidence a
+   * single-log repair cannot supply. `null` when the resolved build is newer than
+   * the floor but exposes no usable historical catalog: the caller refuses the
+   * whole run through {@link catalogVersionRefusal} (fatal, exit 2) instead of
+   * publishing a generation it cannot restore, verify or hand to the host.
+   */
+  readonly floor: ReleasedCatalog | null
 }
 
 /**
  * Why a resolved catalog may not be used as this run's oracle, or `null` when it
  * may. The caller turns a non-`null` reason into a fatal (exit 2) refusal: a
  * below-floor catalog would encode a successor this tool's own read-back cannot
- * vouch for, and the GUI would not run it either.
+ * vouch for, and the GUI would not run it either; a newer build without a usable
+ * repair floor could not be restored or encoded at all.
  */
 export function catalogVersionRefusal(handle: CatalogHandle): string | null {
   const version = handle.catalog.currentVersion
-  if (typeof version === 'number' && Number.isSafeInteger(version) && version >= REQUIRED_CATALOG_VERSION) {
-    return null
+  if (!(typeof version === 'number' && Number.isSafeInteger(version) && version >= REQUIRED_CATALOG_VERSION)) {
+    return `the resolved released catalog at ${handle.modulePath}`
+      + `${handle.packageVersion === null ? '' : ` (package version ${handle.packageVersion})`}`
+      + ` declares currentVersion ${JSON.stringify(version)}, but this tool requires at least `
+      + `${REQUIRED_CATALOG_VERSION}: it would publish a successor that build cannot read. `
+      + 'Point --catalog (or DSH_SESSION_FORMAT_CATALOG) at the catalog of the release the GUI runs.'
+  }
+  if (handle.floor === null) {
+    return `the resolved released catalog at ${handle.modulePath}`
+      + `${handle.packageVersion === null ? '' : ` (package version ${handle.packageVersion})`}`
+      + ` declares currentVersion ${version}, but it exposes no usable historicalSessionFormatCatalog at the `
+      + `repair floor (v${REQUIRED_CATALOG_VERSION}). This tool repairs pre-V3 logs by publishing a v`
+      + `${REQUIRED_CATALOG_VERSION} successor: the V3→V4 edge needs historical child evidence that a single-log `
+      + 'repair cannot supply, so the floor reader/encoder is what restores and verifies the successor and the '
+      + 'host migrates it onward when it opens the session. Point --catalog (or DSH_SESSION_FORMAT_CATALOG) at '
+      + `a build that declares currentVersion >= ${REQUIRED_CATALOG_VERSION} and still exports `
+      + 'historicalSessionFormatCatalog.'
+  }
+  const floorVersion = handle.floor.currentVersion
+  if (!(typeof floorVersion === 'number' && Number.isSafeInteger(floorVersion)
+    && floorVersion >= REQUIRED_CATALOG_VERSION && floorVersion <= version)) {
+    return `the resolved released catalog at ${handle.modulePath} exposes a repair-floor catalog that declares `
+      + `currentVersion ${JSON.stringify(floorVersion)}, but this tool requires a floor of at least `
+      + `${REQUIRED_CATALOG_VERSION} no greater than the declared currentVersion ${version}. `
+      + 'Point --catalog (or DSH_SESSION_FORMAT_CATALOG) at the catalog of the release the GUI runs.'
   }
-  return `the resolved released catalog at ${handle.modulePath}`
-    + `${handle.packageVersion === null ? '' : ` (package version ${handle.packageVersion})`}`
-    + ` declares currentVersion ${JSON.stringify(version)}, but this tool requires at least `
-    + `${REQUIRED_CATALOG_VERSION}: it would publish a successor that build cannot read. `
-    + 'Point --catalog (or DSH_SESSION_FORMAT_CATALOG) at the catalog of the release the GUI runs.'
+  return null
+}
+
+/**
+ * The catalog generation this tool repairs TO (see {@link CatalogHandle.floor}).
+ *
+ * Callers reach this only after {@link catalogVersionRefusal} accepted the handle;
+ * the throw is the fail-closed backstop for a caller that skipped that gate (a
+ * restore or encode through a missing floor must never degrade to "nothing was
+ * published").
+ */
+export function repairCatalog(handle: CatalogHandle): ReleasedCatalog {
+  if (handle.floor === null) {
+    throw new Error(
+      `the resolved session-format catalog exposes no usable repair-floor catalog (v${REQUIRED_CATALOG_VERSION}): `
+      + 'refusing to restore or encode a successor with it',
+    )
+  }
+  return handle.floor
 }
 
 /** Inputs for {@link resolveCatalog}. */
@@ -195,19 +256,44 @@ async function loadCatalog(
   const modulePath = resolveCatalogEntry(candidate, env)
   if (modulePath === null) return null
   try {
-    const loaded = (await import(pathToFileURL(modulePath).href)) as { sessionFormatCatalog?: unknown }
+    const loaded = (await import(pathToFileURL(modulePath).href)) as {
+      sessionFormatCatalog?: unknown
+      historicalSessionFormatCatalog?: unknown
+    }
     if (!isReleasedCatalog(loaded.sessionFormatCatalog)) return null
     return {
       modulePath,
       resolvedBy,
       packageVersion: catalogPackageVersion(modulePath),
       catalog: loaded.sessionFormatCatalog,
+      floor: floorCatalogOf(loaded.sessionFormatCatalog, loaded.historicalSessionFormatCatalog),
     }
   } catch {
     return null
   }
 }
 
+/**
+ * The catalog generation this tool repairs TO: the declared catalog itself when
+ * the resolved build is at or below the floor, otherwise that build's
+ * `historicalSessionFormatCatalog` export.
+ *
+ * A build newer than the floor publishes nothing but its own current generation,
+ * and the released V3→V4 edge needs historical child evidence no single-log
+ * repair can produce; the historical export is that build's own V0–V3
+ * reader/encoder, so restoring through it and encoding the floor generation is
+ * the only successor the tool can both verify and hand to the host.
+ *
+ * @param catalog the module's declared `sessionFormatCatalog`.
+ * @param historical the module's `historicalSessionFormatCatalog`, unknown.
+ * @returns the floor catalog, or `null` when a newer build exposes none.
+ */
+function floorCatalogOf(catalog: ReleasedCatalog, historical: unknown): ReleasedCatalog | null {
+  if (catalog.currentVersion <= REQUIRED_CATALOG_VERSION) return catalog
+  if (isReleasedCatalog(historical) && historical.currentVersion === REQUIRED_CATALOG_VERSION) return historical
+  return null
+}
+
 /**
  * The owning catalog package's own `version`, walking up from a module entry to
  * the nearest `package.json` that names the catalog package; `null` when none is
@@ -526,7 +612,12 @@ function refusalClass(error: unknown): RefusalClass {
  * The restore runs under the pinned policy
  * `createRestore(header, { recovery: 'recoverable', validation: 'transformed' })`
  * and every row is decoded before `finish()`, so the class is the one the
- * released chain raises first for this log.
+ * released chain raises first for this log on its way to the REPAIR FLOOR
+ * ({@link CatalogHandle.floor}) — the pre-V3 chain this tool repairs along and
+ * the generation it publishes. With a newer installed build the floor is that
+ * build's `historicalSessionFormatCatalog`; the host's forward migration from
+ * the floor to current (which needs corpus-level child evidence) is outside a
+ * single log's verdict.
  *
  * Returned classes: `'ok'` when the restore completes, `'source-kind'`,
  * `'subagent-descriptor-version'`, `'unknown-event-type'` for the three released
@@ -539,7 +630,7 @@ function refusalClass(error: unknown): RefusalClass {
  */
 export function classifyWithCatalog(rows: readonly ParsedRow[], catalog: CatalogHandle): RefusalClass {
   try {
-    restoreRows(catalog.catalog, rows, { recovery: 'recoverable', validation: 'transformed' })
+    restoreRows(repairCatalog(catalog), rows, { recovery: 'recoverable', validation: 'transformed' })
     return 'ok'
   } catch (error) {
     return refusalClass(error)

package/scripts/session-logs/publish.ts

@@ -14,7 +14,11 @@
  *     (`ZSTD_c_checksumFlag`), exactly like the released writer.
  * The successor's records come from the RELEASED encoder
  * (`encodeCurrentHeader` / `encodeCurrentEvent`), not from the input rows, so
- * the written generation is whatever the catalog considers current.
+ * the written generation is whatever the catalog's REPAIR FLOOR considers
+ * current — v3 when the installed build is newer (see `CatalogHandle.floor`).
+ * The host then migrates that v3 generation onward to the installed current
+ * format with its own historical child evidence; this module never paints a
+ * generation whose migration needs corpus-level facts a single log lacks.
  *
  * COMPRESSION — Node's `node:zlib` zstd API, no `zstd` CLI (measured on
  * v24.18.0: `zstdCompress`/`zstdDecompress` exist and are used here):
@@ -66,7 +70,7 @@ import { link, readFile, rm, writeFile } from 'node:fs/promises'
 import { dirname, join, resolve } from 'node:path'
 import { constants, zstdCompressSync, zstdDecompressSync } from 'node:zlib'
 import type { CatalogHandle, ReleasedArtifact, ReleasedCatalog } from './catalog.ts'
-import { restoreRows } from './catalog.ts'
+import { repairCatalog, restoreRows } from './catalog.ts'
 import type { ParsedRow } from './rules.ts'
 
 /** Zstandard frame magic (little-endian `0xFD2FB528`). */
@@ -333,8 +337,9 @@ function sizeToNumber(buffer: Buffer, offset: number, width: number): number | n
  * function, which it receives from `runRepair`'s dynamic import of this module
  * (a static import would defeat the `node:zlib` zstd runtime probe that must run
  * first). `publishSuccessor` derives its target from the RESTORED header's
- * version, the CLI's probe from the resolved catalog's declared
- * `currentVersion` — see the probe's comment in `repair-session-logs.ts`.
+ * version (the repair floor), and the CLI's probe resolves the floor's
+ * `currentVersion` through the catalog handle — the two agree for every released
+ * catalog, whose restore settles at the floor it was chosen for.
  */
 export function successorFilename(version: number): string {
   return version === 0 ? 'session.jsonl.zstd' : `session.v${version}.jsonl.zstd`
@@ -382,6 +387,13 @@ export async function publishSuccessor(
   sourceDigest: string,
 ): Promise<PublishedSuccessor> {
   const handle = assertCatalog(catalog)
+  // The generation this tool repairs TO: the declared catalog itself on a build
+  // at the floor, the build's own historical V0–V3 catalog on a newer one. A
+  // restore through the newer build's current catalog would demand historical
+  // child evidence this single-log tool cannot produce; the floor restore has no
+  // such requirement, and the host migrates the published floor generation
+  // onward with its own child facts.
+  const floor = repairCatalog(handle)
   const originalBytes = await readFile(logPath)
   const originalDigest = sha256(originalBytes)
   if (originalDigest !== sourceDigest) {
@@ -394,7 +406,7 @@ export async function publishSuccessor(
   // Defensive copy: the caller's rows alias `form` / `summary` / `sections`
   // objects, and the released restore may normalize the artifact in place.
   const rows = structuredClone(normalizedRows)
-  const artifact = restoreRows(handle.catalog, rows, { recovery: 'strict', validation: 'transformed' })
+  const artifact = restoreRows(floor, rows, { recovery: 'strict', validation: 'transformed' })
   const generation = artifact.header.version
   const targetPath = join(dirname(logPath), successorFilename(generation))
   if (resolve(targetPath) === resolve(logPath)) {
@@ -405,10 +417,10 @@ export async function publishSuccessor(
   // (lazily): materializing them all first would hold a second copy of the session
   // alongside the restored artifact it was built from.
   const encodedEvents = function* (): Generator<Record<string, unknown>> {
-    for (const event of artifact.events) yield handle.catalog.encodeCurrentEvent(event)
+    for (const event of artifact.events) yield floor.encodeCurrentEvent(event)
   }
   const bytes = encodeZstdFrames(
-    handle.catalog.encodeCurrentHeader(artifact.header, artifact.inheritedEventCount),
+    floor.encodeCurrentHeader(artifact.header, artifact.inheritedEventCount),
     encodedEvents(),
   )
 
@@ -422,8 +434,10 @@ export async function publishSuccessor(
     // names instead of ignoring them.
     await writeFile(temporaryPath, bytes, { flag: 'wx', mode: 0o600 })
     // Read the staged generation back with the host's current-generation policy
-    // BEFORE it becomes visible under its canonical name.
-    verifyGeneration(handle.catalog, await readFile(temporaryPath), generation)
+    // BEFORE it becomes visible under its canonical name. The floor catalog is
+    // the one that must read it: it is the build whose encoder wrote it and the
+    // same historical reader the host uses for a pre-current generation.
+    verifyGeneration(floor, await readFile(temporaryPath), generation)
     outcome = await publishExclusive(temporaryPath, targetPath, sha256(bytes))
   } catch (error) {
     try {