@yadsh/dsh-qa-surface 0.5.0 → 0.6.1

package/lib/types/types.d.ts

@@ -1,8 +1,15 @@
+import type { QaDocumentsConfig, ResolvedQaDocumentsConfig } from "./documents/config.js";
 import type { QaTurnSources } from "./provenance/types.js";
 export type QaSessionPolicy = "browser-persistent" | "new-on-load" | "fixed";
 export type QaSandboxMode = "read-only" | "workspace-write";
 export type QaApprovalPolicy = "never";
 export type QaToolPolicyMode = "allow-list";
+/**
+ * How the QA tool catalog is attached. `all` attaches the whole catalog once
+ * the activation skill loads; the field is reserved so a future grouped or
+ * searched mode needs no config redesign.
+ */
+export type QaToolActivationMode = "all";
 /**
  * How a tool policy `ask` resolves on an attested QA agent. `blocked` refuses
  * the call with the surface's own reason; `interactive` parks it until the
@@ -34,6 +41,8 @@ export interface QaAccountUserPublic {
     readonly disabled: boolean;
     /** Self-declared identity the QA prompt renders; empty until edited. */
     readonly profile: QaAccountProfile;
+    /** The account's own starter buttons; empty until customized. */
+    readonly starters: QaAccountStarters;
 }
 /** One external system the deployment collects a handle for. */
 export interface QaAccountIdentityField {
@@ -63,6 +72,26 @@ export interface QaAccountProfileInput {
     readonly identities: Readonly<Record<string, string>>;
     readonly instructions: string;
 }
+/** One starter button: what it reads and what pressing it sends. */
+export interface QaAccountStarter {
+    readonly label: string;
+    readonly prompt: string;
+}
+/**
+ * An account's own starter buttons plus the choice about the deployment's
+ * built-in suggestions. Pure UI preferences: unlike the profile, none of this
+ * reaches the agent prompt.
+ */
+export interface QaAccountStarters {
+    readonly items: readonly QaAccountStarter[];
+    /** Hide the deployment's suggested questions in this account's composer. */
+    readonly hideDefaults: boolean;
+}
+/** Full-replace starters write: an absent value clears the stored one. */
+export interface QaAccountStartersInput {
+    readonly items: readonly QaAccountStarter[];
+    readonly hideDefaults: boolean;
+}
 /** One successful login/registration: the bearer token plus the user. */
 export interface QaAccountSession {
     readonly token: string;
@@ -91,6 +120,90 @@ export interface QaOwnershipEntry {
     readonly displayName: string;
     readonly claimedAt: string;
 }
+/**
+ * Why one skill draft cannot be saved, or why it saves with a caveat. Codes
+ * stay stable on the wire; the browser owns the Russian copy.
+ */
+export type QaSkillDiagnosticCode = "name-required" | "name-invalid" | "name-mismatch" | "description-required" | "description-too-long" | "when-to-use-too-long" | "field-type-invalid" | "invocation-never" | "invocation-invalid" | "invocation-legacy-key" | "allowed-tools-invalid" | "tool-name-invalid" | "tool-unavailable" | "tools-too-many" | "file-too-large" | "frontmatter-missing" | "skill-file-missing" | "frontmatter-invalid" | "unknown-field" | "resource-unsupported";
+/** One finding about a skill file or an editor draft. */
+export interface QaSkillDiagnostic {
+    readonly code: QaSkillDiagnosticCode;
+    readonly severity: "error" | "warning";
+    /** The editor field the message belongs to, or null for a file-wide one. */
+    readonly field: string | null;
+    /** The offending value: a tool name, a frontmatter key, a limit. */
+    readonly detail: string | null;
+}
+/**
+ * A JSON-representable frontmatter value. The editor receives the preserved
+ * foreign fields verbatim over the Host bridge, which carries JSON only, so
+ * the parser drops anything a YAML document can hold but JSON cannot.
+ */
+export type QaSkillJsonValue = string | number | boolean | null | readonly QaSkillJsonValue[] | {
+    readonly [key: string]: QaSkillJsonValue;
+};
+/** One personal skill as the catalog list renders it. */
+export interface QaSkillSummary {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse: string | null;
+    readonly modelInvocable: boolean;
+    readonly userInvocable: boolean;
+    /** Declared tools, in canonical order; unknown ones included. */
+    readonly allowedTools: readonly string[];
+    /** Declared tools the current QA scope cannot use; still stored as declared. */
+    readonly unavailableTools: readonly string[];
+    /** Entries in the skill directory besides SKILL.md (references, assets, …). */
+    readonly resourceCount: number;
+    readonly valid: boolean;
+    readonly diagnostics: readonly QaSkillDiagnostic[];
+    readonly updatedAt: string | null;
+    /** sha256 of the stored bytes; an update must echo the revision it read. */
+    readonly revision: string;
+}
+/** One personal skill with everything the editor needs. */
+export interface QaSkillDocument extends QaSkillSummary {
+    readonly body: string;
+    /** Frontmatter the editor preserves but does not own. */
+    readonly extraFrontmatter: Readonly<Record<string, QaSkillJsonValue>>;
+    /** Absolute SKILL.md path; rendered read-only for advanced users. */
+    readonly sourcePath: string;
+    /** The canonical file the serializer writes, built from the parsed content. */
+    readonly preview: string;
+}
+/** One tool the picker can offer, with this deployment's availability. */
+export interface QaSkillToolDescriptor {
+    readonly name: string;
+    readonly description: string;
+    /** False when the QA session's own scope cannot use the tool. */
+    readonly available: boolean;
+}
+/** The editor's save payload. */
+export interface QaSkillDraftInput {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse: string | null;
+    readonly modelInvocable: boolean;
+    readonly userInvocable: boolean;
+    readonly allowedTools: readonly string[];
+    readonly body: string;
+    /** Echo of the revision the editor read; a stale one is refused. */
+    readonly expectedRevision: string | null;
+}
+/**
+ * The Host's answer about one unsaved draft: the file a save would write and
+ * the diagnostics it found. The editor shows its own subset immediately and
+ * this authoritative set as soon as it arrives.
+ */
+export interface QaSkillValidation {
+    readonly preview: string;
+    readonly diagnostics: readonly QaSkillDiagnostic[];
+}
+/** What one delete did: v1 keeps the directory recoverable. */
+export interface QaSkillRemoval {
+    readonly name: string;
+    readonly trashed: boolean;
+}
 export interface QaSourcesConfig {
     readonly enabled?: boolean;
     readonly collect?: {
@@ -174,6 +287,11 @@ export interface QaSurfaceConfig {
         /** Floor for the visitor-resizable transcript/composer width; the page caps it. */
         readonly minContentWidth?: number;
         readonly showSessionList?: boolean;
+        /**
+         * Sign subagent completion notices with deterministic codenames
+         * («Дотошный Барсук») instead of the child's readable name or raw id.
+         */
+        readonly subagentCodenames?: boolean;
     };
     readonly suggestedQuestions?: readonly string[];
     /**
@@ -185,6 +303,27 @@ export interface QaSurfaceConfig {
         readonly approvals?: QaApprovalInteraction;
         readonly questions?: QaQuestionInteraction;
     };
+    /**
+     * QA tool delivery. Dynamic activation keeps the QA tool schemas out of the
+     * model request until the activation skill has actually been loaded.
+     */
+    readonly tools?: {
+        /**
+         * `true` attaches the QA tools only after the activation skill loads;
+         * `false` attaches them to every managed agent at creation.
+         */
+        readonly dynamicActivation?: boolean;
+        /** The skill name whose successful load attaches the QA tools. */
+        readonly activationSkill?: string;
+        /** Accepted activation policy; only `all` is implemented. */
+        readonly activationMode?: QaToolActivationMode;
+        /**
+         * Agent presets whose sessions participate. An empty list leaves the gate
+         * open, which is only safe when this plugin serves one agent composition —
+         * name the QA preset in any deployment that composes more than one.
+         */
+        readonly activationPresets?: readonly string[];
+    };
     readonly lockdown?: {
         readonly enabled?: boolean;
         readonly enforceFixedAgentPreset?: boolean;
@@ -222,6 +361,20 @@ export interface QaSurfaceConfig {
          * The child directory is not registered as a separate DSH workspace.
          */
         readonly perUserWorkspace?: boolean;
+        /**
+         * Personal Skills: the user's own `.dsh/skills` below their QA workspace,
+         * surfaced through a skill provider this plugin owns.
+         */
+        readonly skills?: {
+            readonly enabled?: boolean;
+            /** Directory below the personal root; relative, never escaping it. */
+            readonly relativeRoot?: string;
+            /** Follow manual file edits and refresh the DSH catalog. */
+            readonly watch?: boolean;
+            readonly maxSkillBytes?: number;
+            /** Reserved for the resource editor; v1 edits SKILL.md only. */
+            readonly allowResourceEditing?: boolean;
+        };
         /** Self-declared profile: storage, the owner's form, and prompt injection. */
         readonly profile?: {
             readonly enabled?: boolean;
@@ -235,6 +388,10 @@ export interface QaSurfaceConfig {
             /** Character cap on the user's free-form agent guidance. */
             readonly instructionsMaxLength?: number;
         };
+        /** Per-account starter buttons above an empty composer. */
+        readonly starters?: {
+            readonly enabled?: boolean;
+        };
     };
     readonly entry?: {
         /** Inject the root → /qa redirect for non-loopback hostnames. */
@@ -244,6 +401,8 @@ export interface QaSurfaceConfig {
     };
     readonly sources?: QaSourcesConfig;
     readonly attachments?: QaAttachmentsConfig;
+    /** Document pipeline: creation, conversion and extraction (see documents/). */
+    readonly documents?: QaDocumentsConfig;
 }
 /** What a QA visitor may attach to one message. */
 export interface QaAttachmentsConfig {
@@ -299,6 +458,7 @@ export interface ResolvedQaSurfaceConfig {
         readonly renderMarkdown: boolean;
         readonly minContentWidth: number;
         readonly showSessionList: boolean;
+        readonly subagentCodenames: boolean;
     };
     readonly suggestedQuestions: readonly string[];
     readonly thinkingPhrases: readonly string[];
@@ -342,11 +502,33 @@ export interface ResolvedQaSurfaceConfig {
             readonly identities: readonly QaAccountIdentityField[];
             readonly instructionsMaxLength: number;
         };
+        /** Per-account starter buttons above an empty composer. */
+        readonly starters: {
+            readonly enabled: boolean;
+        };
+        /**
+         * Personal Skills. Resolution turns the flag off on any deployment that
+         * cannot give every account its own directory: the storage root is the
+         * account's own workspace, so there is no safe shared fallback.
+         */
+        skills: {
+            readonly enabled: boolean;
+            readonly relativeRoot: string;
+            readonly watch: boolean;
+            readonly maxSkillBytes: number;
+            readonly allowResourceEditing: boolean;
+        };
     };
     readonly entry: {
         readonly redirectNonLoopback: boolean;
         readonly cookieBootstrap: boolean;
     };
+    readonly tools: {
+        readonly dynamicActivation: boolean;
+        readonly activationSkill: string;
+        readonly activationMode: QaToolActivationMode;
+        readonly activationPresets: readonly string[];
+    };
     readonly sources: {
         readonly enabled: boolean;
         readonly collect: {
@@ -395,6 +577,7 @@ export interface ResolvedQaSurfaceConfig {
         readonly maxPending: number;
         readonly extensions: readonly string[];
     };
+    readonly documents: ResolvedQaDocumentsConfig;
 }
 export interface QaSourceFilePreview {
     readonly path: string;
@@ -417,11 +600,12 @@ export interface QaLockdownProof {
     readonly toolPolicyLoaded: boolean;
     readonly toolAllowList: readonly string[];
 }
-export type QaMessage = {
+export interface QaUserMessage {
     readonly id: string;
     readonly role: "user";
     readonly text: string;
-    readonly status: "committed";
+    /** `pending` is a browser-only optimistic row until the Host emits it. */
+    readonly status: "pending" | "committed";
     readonly timestamp?: number;
     readonly images?: readonly QaImageView[];
     /** Durable files the user attached to this message, in prompt order. */
@@ -431,7 +615,12 @@ export type QaMessage = {
      * chat; the owner themself sees their messages unlabeled.
      */
     readonly author?: string;
-} | {
+}
+/** Browser-only user row shown while the Host prepares the accepted turn. */
+export type QaPendingUserMessage = Omit<QaUserMessage, "status"> & {
+    readonly status: "pending";
+};
+export type QaMessage = QaUserMessage | {
     readonly id: string;
     readonly role: "assistant";
     readonly text: string;
@@ -462,6 +651,8 @@ export type QaMessage = {
     readonly notice?: {
         readonly title: string;
         readonly body: string;
+        /** Muted correlation line above the body (task name, session id). */
+        readonly meta?: string;
     };
 } | {
     readonly id: string;
@@ -528,6 +719,8 @@ export type QaAttachmentDraft = QaImageDraft | QaFileDraft;
 export interface QaImageView {
     readonly attachmentId: string;
     readonly mediaType: QaImageMediaType;
+    /** Browser-local thumbnail URL, present only on an optimistic message. */
+    readonly previewUrl?: string;
 }
 /**
  * A durable file attached to a sent message. The browser never reads these
@@ -592,7 +785,15 @@ export interface QaSessionState {
     readonly phase: QaSessionPhase;
     readonly sessionId: string | null;
     readonly messages: readonly QaMessage[];
+    /** Immediate send feedback, kept outside the durable transcript. */
+    readonly pendingMessage: QaPendingUserMessage | null;
     readonly error: string | null;
+    /**
+     * An owner-authorized historical chat whose recorded composition no longer
+     * matches the deployment. Its transcript remains visible, but no Host
+     * operation may be issued through this binding.
+     */
+    readonly compatibilityReadOnly?: boolean;
     readonly canSend: boolean;
     readonly canStop: boolean;
     /** Bumped whenever this browser's chat index changes (add/forget). */
@@ -608,4 +809,8 @@ export interface QaSessionState {
     /** Question requests parked for the operator's answer, oldest first. */
     readonly questions: readonly QaPendingQuestion[];
 }
+/** Minimal server-trusted identity exposed to principal-scoped plugins. */
+export interface QaPrincipal {
+    readonly userId: string;
+}
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yadsh/dsh-qa-surface",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "A focused end-user QA surface backed by native DeepSeek Harness sessions",
   "repository": {
     "type": "git",
@@ -15,7 +15,8 @@
   "main": "./lib/index.js",
   "types": "./lib/types/index.d.ts",
   "bin": {
-    "qa-accounts": "./lib/cli.js"
+    "qa-accounts": "./lib/cli.js",
+    "qa-repair-sessions": "./scripts/repair-session-events.mjs"
   },
   "exports": {
     ".": {
@@ -26,6 +27,14 @@
       "types": "./lib/types/client/index.d.ts",
       "default": "./lib/client.js"
     },
+    "./client/panels": {
+      "types": "./lib/types/client/panels/index.d.ts",
+      "default": "./lib/client/panels/index.js"
+    },
+    "./client/settings": {
+      "types": "./lib/types/client/settings-extensions/index.d.ts",
+      "default": "./lib/client/settings-extensions/index.js"
+    },
     "./remote": {
       "types": "./lib/typert.remote-client.d.ts",
       "default": "./lib/typert.remote-client.js"
@@ -66,6 +75,7 @@
     "lib/**/*.js",
     "lib/**/*.js.map",
     "lib/**/*.d.ts",
+    "scripts/repair-session-events.mjs",
     "cordis.patch.yml",
     "compatibility.json",
     "capability-policy.json",
@@ -110,6 +120,7 @@
     "@deepseek-ai/dsh-permission-presets": ">=0.1.5-rc.2 <0.2.0",
     "@deepseek-ai/dsh-session": ">=0.1.5-rc.2 <0.2.0",
     "@deepseek-ai/dsh-settings": ">=0.1.5-rc.2 <0.2.0",
+    "@deepseek-ai/dsh-skill": ">=0.1.5-rc.2 <0.2.0",
     "@deepseek-ai/dsh-system-prompt": ">=0.1.5-rc.2 <0.2.0",
     "@deepseek-ai/dsh-tools": ">=0.1.5-rc.2 <0.2.0",
     "@deepseek-ai/dsh-typert-protocol": ">=0.1.5-rc.2 <0.2.0",
@@ -118,8 +129,9 @@
     "react-dom": "^18.2.0"
   },
   "dependencies": {
+    "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "@yadsh/dsh-plugin-log": "^0.3.0"
+    "@yadsh/dsh-plugin-log": "^0.3.1"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.2",
@@ -141,8 +153,10 @@
     "@deepseek-ai/dsh-host-webserver": "0.1.5-rc.2",
     "@deepseek-ai/dsh-llm": "0.1.5-rc.2",
     "@deepseek-ai/dsh-permission-presets": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-scope": "0.1.5-rc.2",
     "@deepseek-ai/dsh-session": "0.1.5-rc.2",
     "@deepseek-ai/dsh-settings": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-skill": "0.1.5-rc.2",
     "@deepseek-ai/dsh-system-prompt": "0.1.5-rc.2",
     "@deepseek-ai/dsh-tools": "0.1.5-rc.2",
     "@deepseek-ai/dsh-typert-generator": "0.1.5-rc.2",
@@ -155,7 +169,6 @@
     "eslint": "10.9.1",
     "jsdom": "^26.1.0",
     "playwright": "1.62.1",
-    "prettier": "^3.6.2",
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "tsdown": "^0.22.14",
@@ -171,15 +184,15 @@
   },
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('lib', { recursive: true, force: true })\"",
-    "build": "pnpm run lint && pnpm run clean && node scripts/generate-typert.mjs && tsc -p tsconfig.build.json && tsdown",
+    "build": "pnpm run clean && node scripts/generate-typert.mjs && tsc -p tsconfig.build.json && tsdown",
     "lint": "eslint src tests scripts tsdown.config.ts",
-    "format": "prettier --check . --end-of-line auto",
-    "format:write": "prettier --write . --end-of-line auto",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
-    "verify": "node scripts/verify-package.mjs",
+    "verify:package": "node scripts/verify-package.mjs",
+    "verify": "pnpm run verify:package && pnpm run verify:consumer",
+    "verify:consumer": "tsc -p scripts/fixtures/tsconfig.json --noEmit",
     "smoke:packed": "node scripts/smoke-packed-dsh.mjs",
     "e2e:browser": "node scripts/smoke-packed-dsh.mjs --browser",
-    "check": "pnpm run format && pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run build && pnpm run verify"
+    "check": "pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run build && pnpm run verify"
   }
 }

package/scripts/repair-session-events.mjs

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+
+import {
+  chmodSync,
+  copyFileSync,
+  constants as fsConstants,
+  lstatSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  constants as zlibConstants,
+  zstdCompressSync,
+  zstdDecompressSync,
+} from "node:zlib";
+
+export const REPAIRABLE_EVENT_TYPES = new Set([
+  "safety-gate/check",
+  "safety-gate/block",
+  "safety-gate/warn",
+  "safety-gate/classifier-error",
+  "qa/sources",
+]);
+
+const ZSTD_MAGIC = 0xfd2fb528;
+const CHECKSUM_OPTIONS = {
+  params: { [zlibConstants.ZSTD_c_checksumFlag]: 1 },
+};
+
+/** Locate complete frames in a concatenated Zstandard artifact. */
+export function scanZstdFrames(buffer) {
+  const frames = [];
+  let offset = 0;
+  while (offset < buffer.length) {
+    const start = offset;
+    if (buffer.length - offset < 5) throw new Error(`torn frame at ${start}`);
+    if (buffer.readUInt32LE(offset) !== ZSTD_MAGIC) {
+      throw new Error(`bad Zstandard magic at ${offset}`);
+    }
+    offset += 4;
+    const descriptor = buffer.readUInt8(offset);
+    offset += 1;
+    const contentSizeFlag = descriptor >>> 6;
+    const singleSegment = (descriptor & 32) !== 0;
+    const checksum = (descriptor & 4) !== 0;
+    const dictionaryFlag = descriptor & 3;
+    const dictionaryBytes = dictionaryFlag === 3 ? 4 : dictionaryFlag;
+    const contentSizeBytes =
+      contentSizeFlag === 0 ? (singleSegment ? 1 : 0) : 1 << contentSizeFlag;
+    const headerBytes =
+      (singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes;
+    if (buffer.length - offset < headerBytes) {
+      throw new Error(`torn frame header at ${start}`);
+    }
+    offset += headerBytes;
+    for (;;) {
+      if (buffer.length - offset < 3) {
+        throw new Error(`torn block header at ${start}`);
+      }
+      const blockHeader = buffer.readUIntLE(offset, 3);
+      offset += 3;
+      const lastBlock = (blockHeader & 1) !== 0;
+      const blockType = (blockHeader >>> 1) & 3;
+      const blockSize = blockHeader >>> 3;
+      if (blockType === 3) throw new Error(`reserved block type at ${start}`);
+      const payloadBytes = blockType === 1 ? 1 : blockSize;
+      if (buffer.length - offset < payloadBytes) {
+        throw new Error(`torn block payload at ${start}`);
+      }
+      offset += payloadBytes;
+      if (lastBlock) break;
+    }
+    if (checksum) {
+      if (buffer.length - offset < 4) {
+        throw new Error(`torn checksum at ${start}`);
+      }
+      offset += 4;
+    }
+    frames.push({ start, end: offset });
+  }
+  return frames;
+}
+
+function decodeArtifact(filePath, content) {
+  if (!filePath.endsWith(".zstd")) return content.toString("utf8");
+  return scanZstdFrames(content)
+    .map(({ start, end }) =>
+      zstdDecompressSync(content.subarray(start, end)).toString("utf8"),
+    )
+    .join("");
+}
+
+function encodeArtifact(filePath, rows) {
+  const text = `${rows.map((row) => JSON.stringify(row)).join("\n")}\n`;
+  if (!filePath.endsWith(".zstd")) return Buffer.from(text, "utf8");
+  // Harness requires the first frame to contain exactly the header line.
+  const frames = [
+    zstdCompressSync(
+      Buffer.from(`${JSON.stringify(rows[0])}\n`, "utf8"),
+      CHECKSUM_OPTIONS,
+    ),
+  ];
+  const eventRows = rows.slice(1);
+  const frameSize = 2_000;
+  for (let index = 0; index < eventRows.length; index += frameSize) {
+    const plain = `${eventRows
+      .slice(index, index + frameSize)
+      .map((row) => JSON.stringify(row))
+      .join("\n")}\n`;
+    frames.push(zstdCompressSync(Buffer.from(plain, "utf8"), CHECKSUM_OPTIONS));
+  }
+  return Buffer.concat(frames);
+}
+
+function parseRows(filePath, plain) {
+  const lines = plain.split("\n").filter((line) => line.length > 0);
+  if (lines.length === 0) throw new Error(`${filePath}: empty session log`);
+  return lines.map((line, index) => {
+    try {
+      const row = JSON.parse(line);
+      if (typeof row !== "object" || row === null || Array.isArray(row)) {
+        throw new Error("row is not an object");
+      }
+      return row;
+    } catch (error) {
+      throw new Error(`${filePath}: invalid JSON on row ${index + 1}`, {
+        cause: error,
+      });
+    }
+  });
+}
+
+/** Repair one offline session log; dry-run is the default. */
+export function repairSessionFile(filePath, options = {}) {
+  const write = options.write === true;
+  const before = statSync(filePath);
+  const original = readFileSync(filePath);
+  const rows = parseRows(filePath, decodeArtifact(filePath, original));
+  let changed = 0;
+  const types = new Map();
+  for (let index = 1; index < rows.length; index += 1) {
+    const row = rows[index];
+    if (!REPAIRABLE_EVENT_TYPES.has(row.type) || row.ignorable === true)
+      continue;
+    row.ignorable = true;
+    changed += 1;
+    types.set(row.type, (types.get(row.type) ?? 0) + 1);
+  }
+  if (changed === 0 || !write) {
+    return {
+      filePath,
+      changed,
+      types: Object.fromEntries(types),
+      written: false,
+    };
+  }
+
+  const now = statSync(filePath);
+  if (now.size !== before.size || now.mtimeMs !== before.mtimeMs) {
+    throw new Error(
+      `${filePath}: changed while being inspected; stop DSH and retry`,
+    );
+  }
+  const backup = `${filePath}.pre-plugin-event-repair.bak`;
+  copyFileSync(filePath, backup, fsConstants.COPYFILE_EXCL);
+  const repaired = encodeArtifact(filePath, rows);
+  // Decode before publishing so a bad generated frame cannot replace the log.
+  parseRows(filePath, decodeArtifact(filePath, repaired));
+  const temp = `${filePath}.${process.pid}.repair.tmp`;
+  writeFileSync(temp, repaired, { mode: before.mode });
+  chmodSync(temp, before.mode);
+  renameSync(temp, filePath);
+  return {
+    filePath,
+    changed,
+    types: Object.fromEntries(types),
+    written: true,
+    backup,
+  };
+}
+
+function sessionFiles(target) {
+  const details = lstatSync(target);
+  if (details.isSymbolicLink()) return [];
+  if (details.isFile()) {
+    return target.endsWith(".jsonl") || target.endsWith(".jsonl.zstd")
+      ? [target]
+      : [];
+  }
+  if (!details.isDirectory()) return [];
+  return readdirSync(target, { withFileTypes: true }).flatMap((entry) => {
+    if (entry.isSymbolicLink()) return [];
+    return sessionFiles(path.join(target, entry.name));
+  });
+}
+
+function usage() {
+  return `Usage: qa-repair-sessions [--write] [session-file-or-directory ...]
+
+Dry-run is the default. With no target, scans $DSH_HOME/sessions (or
+~/.dsh/sessions when DSH_HOME is unset). Stop DSH before using --write.
+
+The command only adds ignorable:true to legacy safety-gate/* and qa/sources
+events. Before each changed file is replaced atomically, an exclusive
+*.pre-plugin-event-repair.bak backup is created.`;
+}
+
+export function main(argv = process.argv.slice(2)) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    console.log(usage());
+    return 0;
+  }
+  const write = argv.includes("--write");
+  const unknown = argv.filter(
+    (arg) => arg.startsWith("-") && arg !== "--write",
+  );
+  if (unknown.length > 0) throw new Error(`unknown option: ${unknown[0]}`);
+  const targets = argv.filter((arg) => !arg.startsWith("-"));
+  if (targets.length === 0) {
+    const home =
+      process.env.DSH_HOME?.trim() || path.join(os.homedir(), ".dsh");
+    targets.push(path.join(home, "sessions"));
+  }
+  if (write) console.error("write mode: DSH must be stopped");
+  const files = [...new Set(targets.flatMap(sessionFiles))].sort();
+  let candidates = 0;
+  let events = 0;
+  for (const file of files) {
+    const result = repairSessionFile(file, { write });
+    if (result.changed === 0) continue;
+    candidates += 1;
+    events += result.changed;
+    console.log(
+      `${result.written ? "repaired" : "would repair"}: ${file} (${result.changed} events)`,
+    );
+    if (result.backup !== undefined) console.log(`backup: ${result.backup}`);
+  }
+  console.log(
+    `${write ? "repaired" : "dry run"}: ${events} events in ${candidates} of ${files.length} session logs`,
+  );
+  return 0;
+}
+
+if (
+  process.argv[1] !== undefined &&
+  pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url
+) {
+  try {
+    process.exitCode = main();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}