@nanmicoder/dsh-agent-teams 0.1.22 → 0.1.23

package/lib/types/types.d.ts

@@ -7,6 +7,7 @@
  * survives harness restarts.
  * @module dsh-agent-teams/types
  */
+import type { MemberToolFilter } from './tool-policies.ts';
 /** Task lifecycle statuses in progression order. */
 export type TaskStatus = 'pending' | 'claimed' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
 /** Statuses after which a task can no longer be claimed or worked on. */
@@ -44,6 +45,49 @@ export interface CommandResult {
     exitCode?: number;
     evidence?: string;
 }
+/**
+ * Identity of one workspace path at one instant. A verdict is evidence about a
+ * revision, so recording the bytes it judged (not only the task id) lets the
+ * delivery check refuse to advertise a revision no review ever saw.
+ */
+export interface ArtifactDigest {
+    /** Workspace-relative POSIX path. */
+    path: string;
+    /** Whether a regular file existed when the digest was taken. */
+    present: boolean;
+    /** Lowercase hex sha256 of the file bytes; absent unless the file was read. */
+    sha256?: string;
+    /** File size in bytes; absent unless the file was read. */
+    size?: number;
+    /** File mtime in epoch ms; lets a legacy record detect a later edit. */
+    mtimeMs?: number;
+    /**
+     * The path exists but could not be read or safely resolved (permissions,
+     * symlink escaping the workspace, I/O error). Never conflated with "absent":
+     * unreadable bytes cannot be claimed as unchanged.
+     */
+    unreadable?: boolean;
+    /** Why the path could not be read, when `unreadable` is set. */
+    reason?: string;
+}
+/**
+ * A declared scope that could not be fully enumerated (file cap reached,
+ * unreadable directory, path that is not workspace-relative). Recorded so a
+ * partial artifact list is never mistaken for complete coverage.
+ */
+export interface ArtifactScopeGap {
+    /** The pattern or path that could not be fully resolved. */
+    pattern: string;
+    reason: string;
+}
+/** One set of artifact digests captured at a single instant. */
+export interface ArtifactSnapshot {
+    /** Epoch ms when these bytes were read. */
+    at: number;
+    artifacts: ArtifactDigest[];
+    /** Present when the recorded coverage is known to be incomplete. */
+    gaps?: ArtifactScopeGap[];
+}
 /** Profile / team review-loop limits. */
 export interface ReviewPolicy {
     requirementsMinRounds?: number;
@@ -121,9 +165,47 @@ export interface TeamTask {
     /** Supplemental observations, attributed to their original execution generation. */
     supplementalEvidence?: TaskEvidence[];
     reviewedTaskId?: string;
+    /** Execution generation of the reviewed task at the moment of judgment. */
     reviewedAttempt?: number;
+    /**
+     * Bytes this verdict judged, read from the workspace when the gate closed.
+     * A later edit, deletion or re-attempt invalidates the verdict.
+     */
+    reviewedArtifacts?: ArtifactDigest[];
+    /** Scope of that verdict that could not be fully enumerated, if any. */
+    reviewedGaps?: ArtifactScopeGap[];
+    /**
+     * Scope patterns the verdict bound (e.g. `lib/`). A file that appears under
+     * one of them later was never reviewed, so the verdict must not claim it.
+     */
+    reviewedScope?: string[];
+    /**
+     * Drift observed while this verdict was being formed (the workspace changed
+     * between claim and close). The verdict cannot be read as binding a stable
+     * revision.
+     */
+    reviewedDuringDrift?: string[];
+    /**
+     * Workspace snapshot taken when this verdict's attempt started, so a close
+     * can tell whether it judged a revision that was changing underneath it.
+     */
+    verdictStartSnapshot?: ArtifactSnapshot;
+    /**
+     * Workspace snapshot an auto-generated contract (acceptance / inScope /
+     * verify) was derived from. When a cited artifact changes underneath it the
+     * work order is marked stale instead of being read as authoritative.
+     */
+    contractSnapshot?: ArtifactSnapshot;
     /** Repair source: the implementation / previous successful artifact. */
     sourceTaskId?: string;
+    /**
+     * The failed gate task(s) whose findings this repair fixes. Recorded as an
+     * explicit causal edge because `dependencies` cannot carry it: a failed task
+     * never reaches `completed`, so a dependency on it would make the repair
+     * permanently unclaimable. Delivery reads this to tell a closed loop from
+     * genuinely unresolved work (issue #175A).
+     */
+    findingSourceTaskIds?: string[];
     sourceFindingIds?: string[];
     /** User-constraint / goal items this task claims to cover. */
     coverageOf?: string[];
@@ -157,6 +239,19 @@ export interface TeamMember {
     activeModel?: string;
     /** Whether the fallback route is currently active. */
     fallbackActive?: boolean;
+    /**
+     * Owner-declared tool-policy id this member selected (`#59`), absent for a
+     * member without a policy (the unchanged default behavior). The Captain
+     * model may only select a configured id; it never submits raw tool lists.
+     */
+    toolPolicy?: string;
+    /**
+     * The immutable effective tool filter resolved when the member was created
+     * and handed to the child's `toolFilter`. `team.json` keeps it for audit,
+     * status, and recovery diagnostics; the continuable descriptor remains the
+     * authority that reapplies the filter to a cold-resumed child.
+     */
+    toolFilter?: MemberToolFilter;
     joinedAt: number;
     status: MemberStatus;
     /** Execution admission is closed while a failed/pending handoff is drained. */

package/lib/types/workspace-audit.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The single workspace audit shared by every surface that reports a delivery
+ * or quality-loop conclusion.
+ *
+ * `agent_teams_status`, the activity-panel route and any Web API consumer must
+ * read the same current bytes: if only one of them compared recorded verdicts
+ * against the workspace, the other would keep advertising a passing gate over
+ * a revision no review ever saw (issue #161).
+ *
+ * The audit consumes the artifact reader's *complete* result — digests, the
+ * enumeration gaps and unreadable paths — because a partial read must never
+ * look like a clean one: a scope that outgrew its cap after the review would
+ * otherwise be reported as fully verified.
+ * @module dsh-agent-teams/workspace-audit
+ */
+import type { DeliveryAudit } from './quality-gates.ts';
+import type { TeamState } from './types.ts';
+/**
+ * Read the current workspace bytes a team's recorded verdicts and generated
+ * work orders depend on.
+ * @param workspace - absolute path of the owning workspace.
+ * @param team - the durable team record.
+ * @returns digests of every recorded path, the current contents of the scopes
+ * the verdicts bound (so a new file cannot slip into a broad scope), and every
+ * gap that makes this audit incomplete.
+ */
+export declare function auditTeamWorkspace(workspace: string, team: TeamState): DeliveryAudit;

package/lib/workspace-audit.js

@@ -0,0 +1,52 @@
+/**
+ * The single workspace audit shared by every surface that reports a delivery
+ * or quality-loop conclusion.
+ *
+ * `agent_teams_status`, the activity-panel route and any Web API consumer must
+ * read the same current bytes: if only one of them compared recorded verdicts
+ * against the workspace, the other would keep advertising a passing gate over
+ * a revision no review ever saw (issue #161).
+ *
+ * The audit consumes the artifact reader's *complete* result — digests, the
+ * enumeration gaps and unreadable paths — because a partial read must never
+ * look like a clean one: a scope that outgrew its cap after the review would
+ * otherwise be reported as fully verified.
+ * @module dsh-agent-teams/workspace-audit
+ */
+import { readArtifactScope } from "./artifacts.js";
+import { deliveryArtifactPaths, deliveryScopePatterns } from "./quality-gates.js";
+/**
+ * Read the current workspace bytes a team's recorded verdicts and generated
+ * work orders depend on.
+ * @param workspace - absolute path of the owning workspace.
+ * @param team - the durable team record.
+ * @returns digests of every recorded path, the current contents of the scopes
+ * the verdicts bound (so a new file cannot slip into a broad scope), and every
+ * gap that makes this audit incomplete.
+ */
+export function auditTeamWorkspace(workspace, team) {
+    const paths = deliveryArtifactPaths(team);
+    const scopePatterns = deliveryScopePatterns(team);
+    const pathRead = paths.length === 0 ? { artifacts: [], gaps: [] } : readArtifactScope(workspace, paths);
+    const scopeRead = scopePatterns.length === 0 ? { artifacts: [], gaps: [] } : readArtifactScope(workspace, scopePatterns);
+    const gaps = [...pathRead.gaps, ...scopeRead.gaps];
+    const seen = new Set(gaps.map((gap) => `${gap.pattern}\u0000${gap.reason}`));
+    const recordGap = (pattern, reason) => {
+        const key = `${pattern}\u0000${reason}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        gaps.push({ pattern, reason });
+    };
+    for (const artifact of [...pathRead.artifacts, ...scopeRead.artifacts]) {
+        // An unreadable path is not a gap in enumeration but a gap in evidence:
+        // report it the same way so no surface treats it as a clean read.
+        if (artifact.unreadable === true)
+            recordGap(artifact.path, artifact.reason ?? 'path could not be read');
+    }
+    return {
+        artifacts: pathRead.artifacts,
+        expandedScope: scopeRead.artifacts.map((artifact) => ({ path: artifact.path, present: artifact.present })),
+        ...gaps.length === 0 ? {} : { gaps },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanmicoder/dsh-agent-teams",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "AgentTeams for DeepSeek Harness: multi-agent team collaboration (captain, members, tasks with dependencies, messaging) driven by natural language, with a tree monitor in the web GUI",
   "type": "module",
   "main": "lib/index.js",
@@ -29,7 +29,8 @@
     "compatibility.json",
     "scripts/doctor.mjs",
     "scripts/compatibility.mjs",
-    "pnpm-workspace.yaml"
+    "pnpm-workspace.yaml",
+    "scripts/legacy-session-source-repair.mjs"
   ],
   "license": "MIT",
   "author": {
@@ -228,8 +229,10 @@
     "update:skills": "node scripts/update-skills.mjs",
     "test:skills-updater": "node --test scripts/update-skills.test.mjs",
     "verify:skill": "node scripts/sync-skill.mjs --check",
-    "verify": "node scripts/verify.mjs && node scripts/fallback-tdd.mjs && node scripts/member-failure-tdd.mjs && pnpm verify:quality-gates && node scripts/lifecycle-verify.mjs && node scripts/stress-verify.mjs && node --test scripts/issue-159.test.mjs && pnpm verify:web-routes && pnpm verify:release && pnpm verify:readme && pnpm verify:skill && pnpm verify:harness-contract && pnpm verify:http-body && pnpm verify:compatibility && pnpm verify:capabilities && pnpm verify:member-spawn-recovery && pnpm test:git-install && pnpm verify:source-runner && pnpm verify:git-artifact",
-    "verify:quality-gates": "node scripts/quality-gates-tdd.mjs && node --test scripts/quality-gates-repair-scope.test.mjs scripts/quality-gates-amend.test.mjs",
+    "verify": "node scripts/verify.mjs && node scripts/fallback-tdd.mjs && node scripts/member-failure-tdd.mjs && pnpm verify:issue-regressions && pnpm verify:quality-gates && node scripts/lifecycle-verify.mjs && node scripts/stress-verify.mjs && node --test scripts/issue-159.test.mjs && pnpm verify:issue-203 && pnpm verify:corrupt-state && pnpm verify:web-routes && pnpm verify:release && pnpm verify:readme && pnpm verify:skill && pnpm verify:harness-contract && pnpm verify:http-body && pnpm verify:compatibility && pnpm verify:capabilities && pnpm verify:tool-policies && pnpm verify:member-spawn-recovery && pnpm test:git-install && pnpm verify:source-runner && pnpm verify:lineage-identity && pnpm verify:legacy-session-repair && pnpm verify:git-artifact",
+    "verify:quality-gates": "node scripts/quality-gates-tdd.mjs && node --test scripts/quality-gates-repair-scope.test.mjs scripts/quality-gates-amend.test.mjs scripts/quality-gates-content-bound.test.mjs scripts/quality-gates-work-order.test.mjs scripts/quality-gates-repair-wiring.test.mjs scripts/quality-gates-excluded-scope.test.mjs scripts/quality-gates-cross-binding.test.mjs",
+    "verify:issue-203": "node --test scripts/issue-203-card.test.mjs",
+    "verify:corrupt-state": "node --test scripts/corrupt-teamjson.test.mjs",
     "verify:web-routes": "node scripts/web-routes-verify.mjs",
     "verify:release": "node --test scripts/release-metadata.test.mjs",
     "verify:readme": "node scripts/readme-version.mjs && node --test scripts/readme-version.test.mjs",
@@ -238,9 +241,13 @@
     "verify:http-body": "node --test scripts/http-body.test.mjs",
     "doctor": "node scripts/doctor.mjs",
     "verify:capabilities": "node --test scripts/capabilities.test.mjs",
+    "verify:tool-policies": "node --test scripts/tool-policies.test.mjs",
     "verify:member-spawn-recovery": "node --test scripts/member-spawn-recovery.test.mjs",
     "test:git-install": "node --test scripts/git-artifacts.test.mjs",
     "verify:source-runner": "node --test scripts/harness-source-verify.test.mjs",
-    "verify:git-artifact": "node scripts/git-artifacts.mjs"
+    "verify:git-artifact": "node scripts/git-artifacts.mjs",
+    "verify:issue-regressions": "node --test scripts/issue-188.test.mjs scripts/issue-189.test.mjs scripts/issue-205.test.mjs",
+    "verify:legacy-session-repair": "node --test scripts/legacy-session-source-repair.test.mjs",
+    "verify:lineage-identity": "node --test scripts/lineage-identity.test.mjs"
   }
 }

package/release-notes/v0.1.23.md

@@ -0,0 +1,34 @@
+# AgentTeams v0.1.23
+
+Stable plugin release on npm `latest`. The recommended host remains DeepSeek Harness `0.2.0-rc.2`; the exact eight-host support matrix is unchanged.
+
+## Changes
+
+- Fix Unicode team cards and legacy event folding so member rosters use the same team identity as persisted state (#203).
+- Reject invalid finding line numbers before persistence and normalize recoverable historical values (#188).
+- Resolve member models together with their configured provider, and preserve explicit provider selections (#189).
+- Record member turn failures that arrive after task settlement as durable captain notes (#205).
+- Bind review and verification verdicts to the actual artifact bytes and complete repair lineage; changed files block delivery until covered by a sound verdict (#161).
+- Preserve repair contracts, expose stale source warnings, and create repair/reverification follow-ups for failed verification without deadlocking on failed dependencies (#174, #175).
+- Escalate findings outside the permitted repair scope with a reason instead of creating impossible repair tasks (#183).
+- Preserve captain identity across warm and cold forks, including multihop lineage and member wake-ups (#176).
+- Write session source metadata in the current format and ship an explicit, non-destructive historical recovery utility with source backups (#160).
+- Add owner-configured member tool policies. Members select a policy ID; the four required coordination tools remain available. This controls tool availability and is not an operating-system sandbox (#59).
+
+## Install
+
+In Plugins → Add plugin, enter `@nanmicoder/dsh-agent-teams@0.1.23`. For CLI profiles:
+
+```sh
+dsh plugin --profile web add --save-exact @nanmicoder/dsh-agent-teams@0.1.23
+```
+
+Restart the target profile after installation. A global CLI update does not change a desktop application's embedded host.
+
+## Verification scope
+
+The source candidate passed typechecking, build, the full project verification suite, and 121 added regression cases. Local macOS arm64 acceptance used the official Harness `0.2.0-rc.2` Loader, real workspaces, and the existing `deepseek-account / deepseek-flash` login without new API keys. It exercised actual member file writes, failed verification followed by repair and independent rechecking, read-only review, cold fork recovery, and content-drift delivery blocking. Integration acceptance included a captain-driven role/contract correction; the original failed observations are retained.
+
+Publication requires Ubuntu/Windows static checks and the eight-host runtime matrix against one immutable tarball. CI uses deterministic model fixtures with real host implementations; those checks are separate from the local real-provider acceptance. Real account HTTP 429 responses, packaged Electron, and Windows product execution were not covered by that local acceptance.
+
+See [the issue triage and acceptance records](../docs/issue-maintenance-2026-10-10/README.md) for individual evidence and limits. #103's original reproduction already passed on the baseline; no speculative scheduler change is included. Third-party plugin reports and the broader #70/#71 feature requests are outside this release.

package/scripts/legacy-session-source-repair.mjs

@@ -0,0 +1,344 @@
+#!/usr/bin/env node
+/**
+ * Repair one historical AgentTeams session generation for #160.
+ *
+ * The released v2→v3 migration edge audits every message source against a
+ * closed list of released kinds, so a stored pre-v3 generation that contains
+ * the plugin's own producer kind (`agent-teams-command`) is refused in full by
+ * every later Harness (`SessionFormatUnsupportedMigrationError: cannot safely
+ * transform unclassified message source`). No plugin can change that read path:
+ * the published catalog is assembled from direct imports and runs before any
+ * plugin mounts. This tool is the reviewable, non-destructive recovery path:
+ *
+ *  - read-only unless `--apply` is passed;
+ *  - the stored source generation is never modified: it is copied to a backup
+ *    beside it (exclusive create, so an existing backup is never overwritten)
+ *    before anything is published, and its hash is compared before/after;
+ *  - a generation the installed catalog already migrates is left untouched;
+ *  - only source kinds outside the released vocabulary are normalized to the
+ *    released plugin wrapper (`{ kind: 'plugin', plugin: 'dsh-agent-teams' }`,
+ *    the shape the fixed plugin writes on those hosts). The released wrapper's
+ *    audit admits exactly those two members, so extra historical source fields
+ *    (goal, profile, ...) are *not* carried into the repaired generation: they
+ *    are listed in the report and remain only in the untouched source
+ *    generation and its byte-identical backup. Message content, ordering and
+ *    every other row value are preserved;
+ *  - the artifact is then migrated and validated by the *installed* Harness
+ *    catalog, re-encoded as the current generation through the installed
+ *    encoder, verified from its exact bytes, and published exclusively
+ *    (temporary file + link, never replacing an existing generation).
+ *
+ * Usage:
+ *   node scripts/legacy-session-source-repair.mjs --session-dir <dir> [--apply]
+ *     [--kinds agent-teams-command]
+ *
+ * Exit codes: 0 success (dry runs report `"applied": false`), 1 refusal or
+ * failure (nothing published).
+ */
+import { constants as fsConstants, copyFileSync, existsSync, linkSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { createHash } from 'node:crypto'
+import { constants as zlibConstants, zstdCompressSync, zstdDecompressSync } from 'node:zlib'
+
+/**
+ * Resolve one Harness package through the installed host cohort. The format
+ * packages are transitive to the exact `@deepseek-ai/dsh-session` this checkout
+ * pins, so they are resolved from that package's own dependency scope instead
+ * of duplicating a private copy of the format contract.
+ */
+function harnessImport(name) {
+  const require = createRequire(import.meta.url)
+  const sessionDir = dirname(require.resolve('@deepseek-ai/dsh-session/package.json'))
+  const nested = createRequire(join(sessionDir, 'package.json'))
+  return import(pathToFileURL(nested.resolve(name)).href)
+}
+
+const DEFAULT_KINDS = ['agent-teams-command']
+const BACKUP_SUFFIX = '.pre-160-repair.bak'
+
+/** Lowercase hex SHA-256 of one file's exact bytes. */
+function sha256(path) {
+  return createHash('sha256').update(readFileSync(path)).digest('hex')
+}
+
+function fail(message) {
+  console.error(`legacy session source repair: ${message}`)
+  process.exitCode = 1
+  return undefined
+}
+
+function parseArguments(argv) {
+  const options = { apply: false, kinds: DEFAULT_KINDS.slice(), sessionDir: undefined }
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index]
+    if (flag === '--apply') options.apply = true
+    else if (flag === '--session-dir') options.sessionDir = argv[++index]
+    else if (flag === '--kinds') options.kinds = String(argv[++index] ?? '').split(',').map(value => value.trim()).filter(Boolean)
+    else return fail(`unknown argument ${flag}`)
+  }
+  if (options.sessionDir === undefined || options.sessionDir === '') return fail('--session-dir is required')
+  if (options.kinds.length === 0) return fail('--kinds must name at least one source kind')
+  return options
+}
+
+/** Stored generation files in one session directory, newest generation last. */
+function storedGenerations(sessionDir) {
+  if (!existsSync(sessionDir)) return []
+  return readdirSync(sessionDir)
+    .map(name => {
+      const match = name.match(/^session\.v(\d+)\.jsonl(\.zstd)?$/)
+      return match === null ? undefined : { name, version: Number(match[1]), zstd: match[2] === '.zstd' }
+    })
+    .filter(entry => entry !== undefined)
+    .sort((left, right) => left.version - right.version)
+}
+
+/**
+ * Measure one complete Zstandard frame starting at `start` (RFC 8878):
+ * magic, frame header descriptor, optional window/dictionary/content-size
+ * fields, the block chain, and the optional checksum. Node's zstd APIs decode
+ * only the first frame of the store's concatenated container, and searching for
+ * the magic bytes would split on compressed payload that happens to contain
+ * them, so every frame is measured exactly.
+ */
+function zstdFrameLength(buffer, start) {
+  // The magic is the byte sequence 28 B5 2F FD, i.e. 0xFD2FB528 little-endian.
+  if (start + 5 > buffer.length || buffer.readUInt32LE(start) !== 0xfd2fb528) {
+    throw new Error(`corrupt Zstandard session log: invalid frame magic at byte ${start}`)
+  }
+  const descriptor = buffer[start + 4]
+  if (((descriptor >> 3) & 1) !== 0) throw new Error(`corrupt Zstandard session log: reserved frame-header bit at byte ${start}`)
+  const contentSizeFlag = descriptor >> 6
+  const singleSegment = (descriptor >> 5) & 1
+  const checksum = (descriptor >> 2) & 1
+  const dictionarySize = [0, 1, 2, 4][descriptor & 3]
+  let cursor = start + 5 + (singleSegment === 1 ? 0 : 1) + dictionarySize
+  const contentSizeBytes = contentSizeFlag === 0 ? (singleSegment === 1 ? 1 : 0) : [0, 2, 4, 8][contentSizeFlag]
+  let contentSize
+  if (contentSizeBytes === 1) contentSize = buffer.readUInt8(cursor)
+  else if (contentSizeBytes === 2) contentSize = buffer.readUInt16LE(cursor) + 256
+  else if (contentSizeBytes === 4) contentSize = buffer.readUInt32LE(cursor)
+  else if (contentSizeBytes === 8) contentSize = Number(buffer.readBigUInt64LE(cursor))
+  cursor += contentSizeBytes
+  for (;;) {
+    if (cursor + 3 > buffer.length) throw new Error(`corrupt Zstandard session log: truncated block header at byte ${cursor}`)
+    const blockHeader = buffer.readUIntLE(cursor, 3)
+    cursor += 3
+    const last = blockHeader & 1
+    const blockType = (blockHeader >> 1) & 3
+    const blockSize = blockHeader >> 3
+    if (blockType === 3) throw new Error(`corrupt Zstandard session log: reserved block type at byte ${cursor}`)
+    // RFC 8878 §3.1.1.2.2/3: Block_Size counts the block's *content*; an RLE
+    // block stores that content as a single repeated byte, so its payload is
+    // one byte regardless of Block_Size.
+    cursor += blockType === 1 ? 1 : blockSize
+    if (last === 1) break
+  }
+  if (checksum === 1) cursor += 4
+  if (cursor > buffer.length) throw new Error('corrupt Zstandard session log: truncated final frame')
+  if (contentSize !== undefined && contentSize !== 0) {
+    const decoded = zstdDecompressSync(buffer.subarray(start, cursor))
+    if (decoded.byteLength !== contentSize) throw new Error('corrupt Zstandard session log: frame content size disagrees with its header')
+  }
+  return cursor - start
+}
+
+/**
+ * Decode the store's concatenated-frame container: the first frame holds
+ * exactly the header line, later frames hold event batches.
+ */
+export function decodeStoredFrames(buffer) {
+  let offset = 0
+  let text = ''
+  while (offset < buffer.length) {
+    const length = zstdFrameLength(buffer, offset)
+    text += zstdDecompressSync(buffer.subarray(offset, offset + length)).toString('utf8')
+    offset += length
+  }
+  return text
+}
+
+/** Physical log text: the first line is the header, the rest are event rows. */
+function readPhysicalLog(path, zstd) {
+  const raw = readFileSync(path)
+  const text = zstd ? decodeStoredFrames(raw) : raw.toString('utf8')
+  const lines = text.split('\n')
+  while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+  return { bytes: raw, header: JSON.parse(lines[0]), rows: lines.slice(1).map(line => JSON.parse(line)) }
+}
+
+/** Normalize one out-of-vocabulary message source to the released plugin wrapper. */
+function normalizeSources(value, kinds, counter, depth = 0) {
+  if (depth > 12 || value === null || typeof value !== 'object') return value
+  if (Array.isArray(value)) return value.map(item => normalizeSources(item, kinds, counter, depth + 1))
+  const record = { ...value }
+  const source = record['source']
+  if (source !== null && typeof source === 'object' && !Array.isArray(source)
+    && typeof source['kind'] === 'string' && kinds.includes(source['kind'])) {
+    // The released wrapper's source audit admits exactly {kind, plugin}, so any
+    // extra historical metadata on this source cannot travel into the repaired
+    // generation. It is reported instead, and stays readable in the untouched
+    // source generation and its byte-identical backup.
+    const dropped = Object.keys(source).filter(key => key !== 'kind' && key !== 'plugin')
+    record['source'] = { kind: 'plugin', plugin: 'dsh-agent-teams' }
+    counter.normalized += 1
+    for (const key of dropped) counter.droppedFields.add(key)
+  }
+  for (const [key, item] of Object.entries(record)) {
+    if (key === 'source') continue
+    record[key] = normalizeSources(item, kinds, counter, depth + 1)
+  }
+  return record
+}
+
+/** Write the current-generation artifact with the store's checksummed frame container. */
+function encodeFrames(headerLine, rowLines) {
+  const frame = text => zstdCompressSync(Buffer.from(text, 'utf8'), { params: { [zlibConstants.ZSTD_c_checksumFlag]: 1 } })
+  const frames = [frame(`${headerLine}\n`)]
+  for (let index = 0; index < rowLines.length; index += 500) {
+    frames.push(frame(`${rowLines.slice(index, index + 500).join('\n')}\n`))
+  }
+  return Buffer.concat(frames)
+}
+
+async function repair(options) {
+  const sessionDir = resolve(options.sessionDir)
+  const catalogModule = await harnessImport('@deepseek-ai/dsh-session-format-catalog')
+  const catalog = catalogModule.sessionFormatCatalog
+  const withChildren = catalogModule.createSessionFormatCatalogWithChildren([])
+
+  const generations = storedGenerations(sessionDir)
+  if (generations.length === 0) return fail(`no stored session generation under ${sessionDir}`)
+  const source = generations[generations.length - 1]
+  if (source.version >= catalog.currentVersion) {
+    return fail(`stored generation v${source.version} is already current (v${catalog.currentVersion}); nothing to repair`)
+  }
+  const publishedName = `session.v${catalog.currentVersion}.jsonl${source.zstd ? '.zstd' : ''}`
+  const publishedPath = join(sessionDir, publishedName)
+  if (existsSync(publishedPath)) return fail(`${publishedName} already exists; refusing to overwrite it`)
+
+  const { header, rows } = readPhysicalLog(join(sessionDir, source.name), source.zstd)
+
+  // Only logs the installed catalog cannot migrate are touched. A generation
+  // whose sources are already readable (v3 producer kinds included) is a no-op
+  // so this tool never rewrites unrelated provenance.
+  const readableAsIs = (() => {
+    try {
+      const restore = withChildren.createRestore(header, { recovery: 'strict', validation: 'current' })
+      for (const row of rows) restore.decodeRow(row)
+      restore.finish()
+      return true
+    } catch {
+      return false
+    }
+  })()
+  if (readableAsIs) {
+    return {
+      sessionDir,
+      sourceGeneration: source.version,
+      sourceFile: source.name,
+      sourceBytes: readFileSync(join(sessionDir, source.name)).byteLength,
+      targetGeneration: catalog.currentVersion,
+      applied: false,
+      skipped: 'already-readable',
+    }
+  }
+
+  const counter = { normalized: 0, droppedFields: new Set() }
+  const normalizedRows = rows.map(row => normalizeSources(row, options.kinds, counter))
+  if (counter.normalized === 0) {
+    return fail(`${source.name} is refused by the installed Harness but carries none of ${options.kinds.join(', ')}; nothing this tool may repair`)
+  }
+
+  // Migrate and validate with the installed catalog: the whole artifact must be
+  // accepted before anything is published.
+  let artifact
+  try {
+    const restore = withChildren.createRestore(header, { recovery: 'strict', validation: 'current' })
+    for (const row of normalizedRows) restore.decodeRow(row)
+    artifact = restore.finish()
+  } catch (error) {
+    return fail(`the installed Harness still refuses ${source.name} after source normalization: ${error?.constructor?.name}: ${error?.message}`)
+  }
+
+  const currentHeader = catalog.encodeCurrentHeader(artifact.header, artifact.inheritedEventCount)
+  const currentRows = artifact.events.map(event => catalog.encodeCurrentEvent(event))
+  const report = {
+    sessionDir,
+    sourceGeneration: source.version,
+    sourceFile: source.name,
+    sourceBytes: readFileSync(join(sessionDir, source.name)).byteLength,
+    normalizedSources: counter.normalized,
+    normalizedDroppedSourceFields: [...counter.droppedFields].sort(),
+    events: artifact.events.length,
+    targetGeneration: catalog.currentVersion,
+    published: publishedName,
+    applied: false,
+  }
+  if (!options.apply) return report
+
+  const sourcePath = join(sessionDir, source.name)
+  const sourceHashBefore = sha256(sourcePath)
+  const backupPath = join(sessionDir, `${source.name}${BACKUP_SUFFIX}`)
+  // Exclusive copy (`COPYFILE_EXCL`): an existing backup is never overwritten,
+  // and a racing second run fails here instead of silently replacing it.
+  try {
+    copyFileSync(sourcePath, backupPath, fsConstants.COPYFILE_EXCL)
+  } catch (error) {
+    if (error?.code === 'EEXIST') return fail(`${backupPath} already exists; refusing to overwrite a backup`)
+    throw error
+  }
+  report.backup = `${source.name}${BACKUP_SUFFIX}`
+
+  const encoded = encodeFrames(JSON.stringify(currentHeader), currentRows.map(row => JSON.stringify(row)))
+  // Read the exact bytes back before publishing: a repair that cannot be read
+  // again must not replace a diagnosable state with an unreadable one.
+  const verify = (() => {
+    const text = decodeStoredFrames(encoded)
+    const lines = text.split('\n').filter(line => line !== '')
+    const restored = catalog.createRestore(JSON.parse(lines[0]), { recovery: 'strict', validation: 'current' })
+    for (const line of lines.slice(1)) restored.decodeRow(JSON.parse(line))
+    return restored.finish()
+  })()
+  if (verify.events.length !== artifact.events.length) {
+    return fail(`re-encoded artifact lost events (${verify.events.length} of ${artifact.events.length}); nothing published`)
+  }
+  // Publish exclusively: the complete artifact is first written to a temporary
+  // file in the same directory, verified there, and only then linked to its
+  // final name — a half-written current generation can never be visible to the
+  // host, and an existing one is never replaced.
+  const temporaryPath = join(sessionDir, `${publishedName}.tmp-${process.pid}`)
+  // Exclusive create: residue from a crashed run is never overwritten.
+  try {
+    writeFileSync(temporaryPath, encoded, { flag: 'wx' })
+  } catch (error) {
+    if (error?.code === 'EEXIST') return fail(`${temporaryPath} exists from an earlier interrupted run; remove it and retry`)
+    throw error
+  }
+  try {
+    linkSync(temporaryPath, publishedPath)
+  } catch (error) {
+    rmSync(temporaryPath, { force: true })
+    if (error?.code === 'EEXIST') return fail(`${publishedName} appeared while repairing; refusing to overwrite it`)
+    throw error
+  }
+  rmSync(temporaryPath, { force: true })
+  report.applied = true
+  report.publishedBytes = encoded.byteLength
+  report.sourceUnchanged = sha256(sourcePath) === sourceHashBefore
+  report.backupUnchanged = sha256(backupPath) === sourceHashBefore
+  return report
+}
+
+// CLI body: skipped when this module is imported for its container decoder.
+const invokedDirectly = process.argv[1] !== undefined
+  && pathToFileURL(process.argv[1]).href === import.meta.url
+if (invokedDirectly) {
+  const options = parseArguments(process.argv.slice(2))
+  if (options !== undefined) {
+    const report = await repair(options)
+    if (report !== undefined) console.log(JSON.stringify(report, null, 2))
+  }
+}