@lmzhen/dsh-evolution-merge 0.30.17 → 0.30.19

package/lib/types/commit-recovery.js

@@ -1,120 +1,97 @@
-/** Startup replay for non-terminal commit journals. */
+/** Startup replay for non-terminal commit journals: report only, never write skills. */
 import { join } from 'node:path';
-import { recoveryFor } from "./domain/commit-journal.js";
 import { writeJournal } from "./domain/commit-journal-store.js";
-import { readCommitSnapshot, skillBodyPath, skillFilePath } from "./commit-snapshot.js";
+import { snapshotPath } from "./commit-snapshot.js";
 import { readCommitReceipt } from "./commit-receipt.js";
-export async function recoverCommitJournals(io, home, now, skillRoot, restoreSource, isActive) {
+import { readUnitEvidence } from '@lmzhen/dsh-evolution-core';
+export async function recoverCommitJournals(io, home, now, isActive) {
     const dir = join(home, 'merge', 'journals');
-    if (!(await io.exists(dir)))
-        return [];
-    const files = (await io.list(dir)).filter(name => name.endsWith('.json'));
     const reports = [];
-    for (const file of files) {
-        let journal;
-        try {
-            journal = JSON.parse(await io.readText(join(dir, file)) ?? '');
-        }
-        catch {
-            continue;
-        }
-        if (isActive?.(journal.runId) === true) {
-            reports.push({ runId: journal.runId, phase: journal.phase, action: 'skipped-active-run', ok: true });
-            continue;
-        }
-        const recovery = recoveryFor(journal);
-        if (recovery === 'none')
-            continue;
-        if (recovery === 'refuse') {
-            reports.push({ runId: journal.runId, phase: journal.phase, action: 'unknown-phase-refused', ok: false });
-            continue;
-        }
-        let receipt = null;
+    let files = [];
+    if (await io.exists(dir)) {
         try {
-            receipt = await readCommitReceipt(io, home, journal.runId, journal.target);
+            files = (await io.list(dir)).filter(name => name.endsWith('.json'));
         }
         catch {
-            reports.push({ runId: journal.runId, phase: journal.phase, action: 'receipt-read-failed', ok: false });
-            continue;
+            reports.push({ runId: '(list)', phase: 'unknown', action: 'journal-list-failed', ok: false, journalPath: dir });
         }
-        if (receipt !== null) {
-            await writeJournal(io, home, { ...journal, phase: 'committed', unitId: receipt.unitId, updatedAt: new Date(now).toISOString() });
-            reports.push({ runId: journal.runId, phase: journal.phase, action: 'receipt-committed', ok: true });
-            continue;
-        }
-        let snapshot;
+    }
+    for (const file of files) {
+        const path = join(dir, file);
         try {
-            snapshot = await readCommitSnapshot(io, home, journal.runId);
+            let journal;
+            try {
+                journal = JSON.parse(await io.readText(path) ?? '');
+            }
+            catch {
+                reports.push({ runId: file.replace(/\.json$/, ''), phase: 'unknown', action: 'journal-unreadable', ok: false, journalPath: path });
+                continue;
+            }
+            if (isActive?.(journal.runId) === true) {
+                reports.push({ runId: journal.runId, phase: journal.phase, action: 'skipped-active-run', ok: true, target: journal.target, sources: journal.sources, journalPath: path });
+                continue;
+            }
+            let receipt = null;
+            try {
+                receipt = await readCommitReceipt(io, home, journal.runId, journal.target);
+            }
+            catch {
+                reports.push({ runId: journal.runId, phase: journal.phase, action: 'receipt-read-failed', ok: false, target: journal.target, sources: journal.sources, journalPath: path });
+                continue;
+            }
+            if (receipt !== null) {
+                await writeJournal(io, home, { ...journal, phase: 'committed', unitId: receipt.unitId, updatedAt: new Date(now).toISOString() });
+                reports.push({ runId: journal.runId, phase: journal.phase, action: 'receipt-committed', ok: true, target: journal.target, sources: journal.sources, journalPath: path, unitId: receipt.unitId });
+                continue;
+            }
+            if (journal.phase === 'committed') {
+                reports.push({ runId: journal.runId, phase: journal.phase, action: 'receipt-missing', ok: false, target: journal.target, sources: journal.sources, journalPath: path });
+                continue;
+            }
+            if (journal.phase === 'failed' || journal.phase === 'rolled-back')
+                continue;
+            reports.push({
+                runId: journal.runId, phase: journal.phase, action: 'manual-required', ok: false,
+                target: journal.target, sources: journal.sources, journalPath: path, snapshotPath: snapshotPath(home, journal.runId),
+            });
         }
         catch (error) {
-            reports.push({ runId: journal.runId, phase: journal.phase, action: 'snapshot-read-failed: ' + (error instanceof Error ? error.message : String(error)), ok: false });
-            continue;
-        }
-        let action = 'report-only';
-        let ok = true;
-        if (recovery === 'retry-commit') {
-            action = 'no-host-write';
+            reports.push({ runId: file.replace(/\.json$/, ''), phase: 'unknown', action: 'recovery-error: ' + (error instanceof Error ? error.message : String(error)), ok: false, journalPath: path });
         }
-        else if (snapshot === null) {
-            action = 'snapshot-missing';
-            ok = false;
+    }
+    const unitDir = join(home, 'merge', 'unit-journals');
+    if (await io.exists(unitDir)) {
+        let unitFiles = [];
+        try {
+            unitFiles = (await io.list(unitDir)).filter(name => name.endsWith('.json'));
         }
-        else {
+        catch { /* no unit journals */ }
+        for (const file of unitFiles) {
+            const path = join(unitDir, file);
             try {
-                if (recovery === 'rollback-sources') {
-                    let restoredArchived = restoreSource !== undefined;
-                    if (restoreSource !== undefined) {
-                        for (const source of snapshot.sourceBodies) {
-                            if (!(await restoreSource(source.name)))
-                                restoredArchived = false;
-                        }
-                    }
-                    if (!restoredArchived) {
-                        for (const source of snapshot.sourceBodies)
-                            await io.writeText(skillBodyPath(skillRoot, source.name), source.body);
-                    }
-                }
-                if (snapshot.create && snapshot.targetBody === null) {
-                    try {
-                        await io.remove(skillBodyPath(skillRoot, snapshot.target));
-                    }
-                    catch { /* already gone */ }
-                    try {
-                        const dir = join(skillRoot, snapshot.target);
-                        if ((await io.list(dir)).length === 0)
-                            await io.remove(dir);
-                    }
-                    catch { /* absent or non-empty */ }
+                const journal = JSON.parse(await io.readText(path) ?? '');
+                const evidence = await readUnitEvidence(io, home, journal.unitId);
+                if (evidence !== null) {
+                    reports.push({ runId: journal.runId, phase: 'committed', action: 'unit-committed', ok: true, target: journal.target, sources: journal.sources, journalPath: path, unitId: journal.unitId });
+                    continue;
                 }
-                else if (snapshot.targetBody !== null) {
-                    await io.writeText(skillBodyPath(skillRoot, snapshot.target), snapshot.targetBody);
+                if (journal.phase === 'committed') {
+                    reports.push({ runId: journal.runId, phase: 'committed', action: 'unit-evidence-missing', ok: false, target: journal.target, sources: journal.sources, journalPath: path, unitId: journal.unitId });
+                    continue;
                 }
-                const oldPaths = new Set((snapshot.targetSupport ?? []).map(file => file.path));
-                for (const file of snapshot.targetSupport ?? []) {
-                    await io.writeText(skillFilePath(skillRoot, snapshot.target, file.path), file.content);
-                }
-                for (const file of snapshot.targetSupportAfter ?? []) {
-                    if (!oldPaths.has(file.path)) {
-                        try {
-                            await io.remove(skillFilePath(skillRoot, snapshot.target, file.path));
-                        }
-                        catch { /* already gone */ }
-                    }
-                }
-                for (const file of snapshot.sourceSupport ?? [])
-                    await io.writeText(skillFilePath(skillRoot, file.name, file.path), file.content);
-                action = recovery === 'rollback-sources' ? 'restored-sources-and-target' : 'restored-target';
+                if (journal.phase === 'failed' || journal.phase === 'rolled-back')
+                    continue;
+                reports.push({ runId: journal.runId, phase: journal.phase, action: 'unit-manual-required', ok: false, target: journal.target, sources: journal.sources, journalPath: path, unitId: journal.unitId });
             }
-            catch (error) {
-                action = 'restore-failed: ' + (error instanceof Error ? error.message : String(error));
-                ok = false;
+            catch {
+                reports.push({ runId: '(unit)', phase: 'unknown', action: 'unit-journal-unreadable', ok: false, journalPath: path });
             }
         }
-        if (ok)
-            await writeJournal(io, home, { ...journal, phase: 'rolled-back', updatedAt: new Date(now).toISOString() });
-        reports.push({ runId: journal.runId, phase: journal.phase, action, ok });
     }
-    await io.writeText(join(home, 'merge', 'recovery.json'), JSON.stringify(reports, null, 2));
+    try {
+        await io.writeText(join(home, 'merge', 'recovery.json'), JSON.stringify(reports, null, 2));
+    }
+    catch { /* report file is best-effort; reports are still returned */ }
     return reports;
 }
 //# sourceMappingURL=commit-recovery.js.map

package/lib/types/contracts.d.ts

@@ -4,7 +4,7 @@
  * The data layer keeps four states; the user face collapses verify/fuse into one retry
  * queue and keeps the stage as a chip. The API queue must never expose the raw state.
  */
-export declare const MERGE_STATE_VERSION = 2;
+export declare const MERGE_STATE_VERSION = 3;
 export type MergePairState = 'verify' | 'pending' | 'approved' | 'fuse' | 'skipped';
 export type MergeQueue = 'verify' | 'pending' | 'fuse' | 'skipped';
 export type MergeStage = 'verify' | 'decide' | 'author' | 'commit';
@@ -25,6 +25,7 @@ export interface MergeFailure {
     readonly message: string;
     readonly retryable: boolean;
     readonly retryFrom: 'agent1' | 'agent2' | 'none';
+    readonly lengths?: Readonly<Record<string, number>>;
 }
 /** One persisted pair. The id is stable for the UI; the pairKey is the natural key. */
 export interface MergeGateFact {
@@ -43,6 +44,12 @@ export interface MergeCandidate {
     readonly gate?: MergeGateFact;
     readonly source?: 'lexical' | 'proposed' | 'engine';
 }
+export type RevisionRef = {
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'present';
+    readonly sha256: string;
+};
 export interface MergeDecision {
     readonly shouldMerge: boolean;
     readonly mode: 'merge-into-existing' | 'create-umbrella' | 'keep';
@@ -50,9 +57,21 @@ export interface MergeDecision {
     readonly sources: readonly string[];
     readonly rationale: string;
     readonly confidence?: number;
+    readonly promptVersion?: string;
+    readonly promptHash?: string;
     readonly aSummary?: string;
     readonly bSummary?: string;
     readonly cacheRead?: number;
+    readonly targetRevisionRef?: RevisionRef;
+    readonly sourceRevisionRef?: RevisionRef;
+    /** Per-source anchors recorded with the decision; a commit re-checks each one. */
+    readonly sourceRevisions?: Readonly<Record<string, RevisionRef>>;
+    readonly supportDigest?: string;
+}
+export interface MergeValidationPlanRef {
+    readonly planVersion: 1;
+    readonly stageDigest: string;
+    readonly revision: string;
 }
 export interface MergeUsage {
     readonly inputTokens?: number;
@@ -86,7 +105,18 @@ export interface MergeReportPair {
     readonly unitId?: string;
     readonly failure?: MergeFailure;
     readonly usage?: MergeUsage;
+    readonly lengths?: Readonly<Record<string, number>>;
     readonly timing?: MergeTiming;
+    readonly validationPlan?: MergeValidationPlanRef;
+    readonly criteria?: MergeCriteria;
+    readonly reportOnly?: boolean;
+}
+export interface MergeCriteria {
+    readonly decision: 'keep' | 'merge' | 'candidate';
+    readonly validation: 'not-run' | 'report-only' | 'required';
+    readonly commit: 'never' | 'if-approved' | 'required';
+    readonly archive: 'none' | 'sources';
+    readonly evidence: 'none' | 'receipt';
 }
 export interface MergeReport {
     readonly schemaVersion: 2;
@@ -111,6 +141,17 @@ export interface MergeReport {
         readonly pairKey: string;
         readonly queue: MergeQueue;
     }[];
+    readonly reportOnly?: readonly MergeReportPair[];
+    readonly validationFailures?: readonly MergeReportPair[];
+    readonly archived?: readonly string[];
+    readonly commit?: {
+        readonly unitId?: string;
+        readonly target?: string;
+        readonly created?: boolean;
+    };
+    readonly usage?: MergeUsage;
+    readonly timing?: MergeTiming;
+    readonly criteria?: readonly MergeCriteria[];
 }
 export interface MergeRow {
     readonly id: string;
@@ -131,6 +172,8 @@ export interface MergeRow {
     readonly decision?: MergeDecision;
     readonly sourceRevision?: string;
     readonly targetRevision?: string;
+    readonly sourceRevisionRef?: RevisionRef;
+    readonly targetRevisionRef?: RevisionRef;
     readonly runId?: string;
     readonly unitId?: string;
     readonly origin?: 'agent' | 'human' | 'system';

package/lib/types/contracts.js

@@ -4,7 +4,7 @@
  * The data layer keeps four states; the user face collapses verify/fuse into one retry
  * queue and keeps the stage as a chip. The API queue must never expose the raw state.
  */
-export const MERGE_STATE_VERSION = 2;
+export const MERGE_STATE_VERSION = 3;
 export const MERGE_PAIR_STATES = ['verify', 'pending', 'approved', 'fuse', 'skipped'];
 export const MERGE_QUEUES = ['verify', 'pending', 'fuse', 'skipped'];
 /** User-facing queue of one data state. verify/fuse share retry, not two tabs. */

package/lib/types/coordinator.d.ts

@@ -2,7 +2,7 @@
  * Pure merge transition table. No io, no run shell, no subagents.
  *
  * Every transition returns the whole next row (or a drop), so the caller can persist it
- * through mutateMergeState in one transaction. Invalid transitions are refused by name;
+ * through one state transaction. Invalid transitions are refused by name;
  * a caller never "repairs" a row by guessing which state the operator meant.
  */
 import { type MergeDecision, type MergeFailure, type MergeRow } from './contracts.ts';
@@ -72,5 +72,6 @@ export type TransitionResult = {
     readonly code: 'invalid-transition';
     readonly message: string;
 };
-export declare function transition(current: MergeRow | undefined, event: MergeEvent): TransitionResult;
+/** Legacy v2 projection only; runtime writes must use transitionV3/RowTx. */
+export declare function transitionLegacyForProjection(current: MergeRow | undefined, event: MergeEvent): TransitionResult;
 //# sourceMappingURL=coordinator.d.ts.map

package/lib/types/coordinator.js

@@ -2,7 +2,7 @@
  * Pure merge transition table. No io, no run shell, no subagents.
  *
  * Every transition returns the whole next row (or a drop), so the caller can persist it
- * through mutateMergeState in one transaction. Invalid transitions are refused by name;
+ * through one state transaction. Invalid transitions are refused by name;
  * a caller never "repairs" a row by guessing which state the operator meant.
  */
 import { pairKey, queueOf, rowIdOf, } from "./contracts.js";
@@ -49,7 +49,8 @@ function next(row, at, state, patch = {}) {
         },
     };
 }
-export function transition(current, event) {
+/** Legacy v2 projection only; runtime writes must use transitionV3/RowTx. */
+export function transitionLegacyForProjection(current, event) {
     if (event.type === 'candidate') {
         if (current !== undefined)
             return { ok: true, row: current };
@@ -106,7 +107,7 @@ export function transition(current, event) {
                 : invalid(event, current.state);
         case 'approve':
             return current.state === 'pending'
-                ? next(current, event.at, 'approved', { ...(event.runId === undefined ? {} : { runId: event.runId }) })
+                ? next(current, event.at, 'approved', (event.runId === undefined ? {} : { runId: event.runId }))
                 : invalid(event, current.state);
         case 'reject':
             return current.state === 'pending' ? next(current, event.at, 'skipped', { origin: 'human' }) : invalid(event, current.state);

package/lib/types/decision.js

@@ -1,5 +1,5 @@
 function extractJson(text) {
-    const fenced = /\`\`\`(?:json)?\s*([\s\S]*?)\`\`\`/i.exec(text);
+    const fenced = /`\``(?:json)?\s*([\s\S]*?)`\``/i.exec(text);
     const body = fenced?.[1] ?? text;
     const start = body.indexOf('{');
     if (start < 0)

package/lib/types/doctor.d.ts

@@ -1,10 +1,27 @@
 import { type EvolutionIoLike } from '@lmzhen/dsh-evolution-core';
+import { type ReconcileReport } from './domain/reconcile.ts';
+import type { DoctorView } from './wire.ts';
 export declare const MERGE_DOCTOR_SCHEMA_VERSION = 3;
+/** The global doctor's merge line; built from the DoctorView envelope, never from raw files. */
+export interface MergeDoctorFact {
+    readonly status: 'ok' | 'warn' | 'fail' | 'unknown';
+    readonly detail: string;
+    readonly remedy?: string;
+}
+/** Compose the one-line global-doctor fact from buildDoctorView + the last reconcile report. */
+export declare function mergeDoctorFact(view: DoctorView, report: ReconcileReport | null): MergeDoctorFact;
 export interface MergeDoctorRow {
     readonly key: string;
     readonly label: string;
-    readonly status: 'ok' | 'warn' | 'unknown';
+    readonly status: 'ok' | 'warn' | 'blocked' | 'unknown';
     readonly detail: string;
 }
+/** Global doctor host section: a missing merge mount must fail with E-325, not render empty. */
+export declare function mergeDoctorAvailability(mounted: boolean): {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly code: 'E-325';
+};
 export declare function mergeDoctor(io: EvolutionIoLike, home: string, configuredRoot?: string): Promise<readonly MergeDoctorRow[]>;
 //# sourceMappingURL=doctor.d.ts.map

package/lib/types/doctor.js

@@ -1,27 +1,163 @@
+import { readTextOrNull } from "./domain/read-probe.js";
 /**
  * Merge doctor rows: state, pending, gate cache and staging are each probed read-only.
  * A missing file is an empty feature, not a failure; an unreadable file is a warning the
  * operator can act on. This module never repairs or writes.
  */
+import { createHash } from 'node:crypto';
+import { stat } from 'node:fs/promises';
 import { join } from 'node:path';
-import { probeList } from '@lmzhen/dsh-evolution-core';
-import { loadMergeState } from "./state.js";
-import { countRows } from "./status.js";
+import { probeList, readTreeLock, runsFile } from '@lmzhen/dsh-evolution-core';
+import { migrationJournalPath, migrationReportPath, v2BackupPath } from "./domain/state-bootstrap.js";
+import { readMergeSnapshot } from "./domain/merge-snapshot.js";
+import { validateArtifacts } from "./domain/consistency.js";
+import { readJournal } from "./domain/commit-journal-store.js";
 import { stagingRoot } from "./staging.js";
+import { readReconcileReport } from "./domain/reconcile.js";
 export const MERGE_DOCTOR_SCHEMA_VERSION = 3;
+/** Compose the one-line global-doctor fact from buildDoctorView + the last reconcile report. */
+export function mergeDoctorFact(view, report) {
+    const counts = view.counts;
+    const reconcileText = report === null
+        ? 'reconcile 尚未运行'
+        : report.state === 'blocked'
+            ? 'reconcile blocked ' + (report.code ?? 'merge-state-blocked')
+            : 'reconcile ' + String(report.actions.length) + ' 项动作';
+    const problems = [];
+    if (view.blocked !== undefined)
+        problems.push('state blocked ' + view.blocked.code);
+    if (view.hostOnly !== undefined)
+        problems.push('宿主数据面不可用 ' + view.hostOnly.code);
+    if (view.staging.state === 'unreadable')
+        problems.push('staging 索引不可读' + (view.staging.detail === undefined ? '' : '：' + view.staging.detail));
+    if (counts.expired > 0)
+        problems.push('expired ' + String(counts.expired));
+    const unstable = view.rows.filter(row => row.status === 'warn' || row.status === 'fail');
+    if (unstable.length > 0)
+        problems.push(unstable.map(row => row.key + '=' + row.status).join(','));
+    if (report?.state === 'blocked')
+        problems.push('reconcile blocked');
+    const latest = view.latestRun;
+    const latestText = latest === undefined ? '' : '；最近 run ' + latest.id + ' [' + latest.state + ']';
+    const detail = 'verify ' + String(counts.active.verify) + ' / pending ' + String(counts.active.pending) + ' / fuse ' + String(counts.active.fuse) + ' / skipped ' + String(counts.active.skipped) + ' / expired ' + String(counts.expired)
+        + '；staging ' + view.staging.state + ' dirs=' + String(view.staging.dirs)
+        + '；审批 ' + (view.approval.mergeApproval ? '开' : '关') + '；' + reconcileText + latestText
+        + (problems.length === 0 ? '' : '；问题：' + problems.join('；'));
+    const status = problems.length === 0
+        ? 'ok'
+        : view.blocked !== undefined || view.hostOnly !== undefined || report?.state === 'blocked' ? 'fail' : 'warn';
+    return problems.length === 0 ? { status, detail } : { status, detail, remedy: '运行 /evolution merge doctor 查看逐项；必要时 /evolution merge reconcile 收敛' };
+}
+/** Global doctor host section: a missing merge mount must fail with E-325, not render empty. */
+export function mergeDoctorAvailability(mounted) {
+    return mounted ? { ok: true } : { ok: false, code: 'E-325' };
+}
 export async function mergeDoctor(io, home, configuredRoot) {
     const rows = [];
-    const loaded = await loadMergeState(io, home);
-    const counts = countRows(loaded.state.rows);
+    const snapshot = await readMergeSnapshot({ io, home, runs: [], approval: false });
+    const hasState = await io.exists(join(home, 'merge', 'merge-state.json'));
+    const counts = snapshot.doctor.counts.active;
     rows.push({
         key: 'state',
         label: '合并状态',
-        status: loaded.note === undefined ? 'ok' : 'warn',
-        detail: loaded.note ?? 'pairs ' + String(loaded.state.rows.length) + '；verify ' + String(counts.verify) + ' / pending ' + String(counts.pending) + ' / fuse ' + String(counts.fuse) + ' / skipped ' + String(counts.skipped),
+        status: snapshot.blocked === undefined || !hasState ? 'ok' : 'warn',
+        detail: snapshot.blocked === undefined ? 'pairs ' + String(snapshot.rows.length) + '；verify ' + String(counts.verify) + ' / pending ' + String(counts.pending) + ' / fuse ' + String(counts.fuse) + ' / skipped ' + String(counts.skipped) : snapshot.blocked.code + ': ' + snapshot.blocked.message,
+    });
+    const recoveryRuns = new Set();
+    try {
+        const raw = await io.readText(join(home, 'merge', 'recovery.json'));
+        if (raw !== null)
+            for (const report of JSON.parse(raw))
+                if (report.ok === true && report.runId !== undefined)
+                    recoveryRuns.add(report.runId);
+    }
+    catch { }
+    const receiptRuns = new Set();
+    const receiptDir = await probeList(io, join(home, 'merge', 'receipts'));
+    if (receiptDir.kind === 'present')
+        for (const name of receiptDir.value)
+            receiptRuns.add(name);
+    const invalid = [];
+    if (snapshot.blocked !== undefined)
+        invalid.push({ id: 'state', reason: snapshot.blocked.code });
+    for (const item of snapshot.rows) {
+        const row = item.row;
+        const runId = row.runId ?? (item.stage?.ref.split('/')[0]);
+        const artifactRow = row.state === 'approved' ? 'approved' : row.state === 'fuse' ? 'fuse' : row.state;
+        const run = runId === undefined ? 'none' : row.state === 'pending' ? 'awaiting-approval' : 'running';
+        const staging = item.stage === null ? (row.state === 'fuse' ? 'missing' : 'none') : item.stage.state === 'present' || item.stage.state === 'reserved' ? 'kept' : row.state === 'fuse' ? 'missing' : 'none';
+        const phase = runId === undefined ? null : await readJournal(io, home, runId);
+        const journal = phase === null ? 'none' : phase.phase === 'prepared' ? 'prepared' : phase.phase === 'target-written' || phase.phase === 'sources-archived' ? 'committing' : phase.phase === 'committed' ? 'committed' : phase.phase === 'rolled-back' ? 'rolled-back' : 'failed';
+        const evidence = runId !== undefined && await readTextOrNull(io, join(home, 'merge', 'receipts', runId + '.json')) !== null ? 'receipt' : 'none';
+        const result = validateArtifacts({ row: artifactRow, run, staging, journal, evidence, activeRuns: run === 'running' || run === 'awaiting-approval' ? 1 : 0, ...(runId !== undefined && recoveryRuns.has(runId) ? { recovery: true } : {}) });
+        if (!result.ok)
+            invalid.push({ id: row.id, reason: result.reason ?? 'not-allowed' });
+    }
+    rows.push({ key: 'merge-state-v3', label: 'state schema', status: snapshot.blocked === undefined ? 'ok' : 'warn', detail: snapshot.blocked === undefined ? 'schemaVersion 4' : snapshot.blocked.code });
+    let quarantineCount = 0;
+    try {
+        const qraw = await io.readText(join(home, 'merge', 'merge-state.quarantine.json'));
+        if (qraw !== null) {
+            const parsed = JSON.parse(qraw);
+            quarantineCount = Array.isArray(parsed) ? parsed.length : 0;
+        }
+    }
+    catch {
+        quarantineCount = -1;
+    }
+    rows.push({ key: 'quarantine', label: 'quarantine', status: quarantineCount < 0 ? 'unknown' : quarantineCount === 0 ? 'ok' : 'warn', detail: quarantineCount < 0 ? 'quarantine 不可读' : quarantineCount + ' 行待人工检查' });
+    const holder = await readTreeLock(io, home).catch(() => null);
+    rows.push({ key: 'tree-lock', label: 'tree lock', status: holder == null ? 'ok' : 'warn', detail: holder == null ? 'free' : 'holder pid=' + String(holder.pid) + ' epoch=' + String(holder.epoch) + ' token=' + holder.token.slice(0, 8) });
+    const backupPath = v2BackupPath(home);
+    const backupRaw = await readTextOrNull(io, backupPath);
+    const backupMode = await stat(backupPath).then(value => value.mode).catch(() => null);
+    const backupReadOnly = backupMode === null ? null : (backupMode & 0o200) === 0;
+    rows.push({ key: 'backup', label: 'v2 backup', status: backupRaw === null ? 'unknown' : backupReadOnly === false ? 'warn' : 'ok', detail: backupRaw === null ? 'no v2 backup (not migrated or already cleaned)' : 'merge-state.v2.bak.json sha256=' + createHash('sha256').update(backupRaw).digest('hex').slice(0, 16) + ' readonly=' + String(backupReadOnly) });
+    const journal = await readTextOrNull(io, migrationJournalPath(home));
+    const report = await readTextOrNull(io, migrationReportPath(home));
+    rows.push({ key: 'migration', label: 'state migration', status: snapshot.blocked === undefined ? (journal === null ? 'ok' : 'warn') : 'warn', detail: snapshot.blocked === undefined ? (journal === null ? (report === null ? 'ready (no migration report)' : 'ready; report present') : 'ready; migration journal pending') : snapshot.blocked.code + ': ' + snapshot.blocked.message });
+    rows.push({ key: 'staging-index', label: 'staging index', status: 'ok', detail: String(snapshot.stages.length) + ' index entries' });
+    const claims = await probeList(io, join(home, 'merge', 'claims'));
+    rows.push({ key: 'target-claim', label: 'target claim', status: claims.kind === 'unknown' ? 'unknown' : 'ok', detail: claims.kind === 'unknown' ? 'claims unreadable' : claims.kind === 'absent' ? 'no claims' : String(claims.value.length) + ' claim files' });
+    let orphanRuns = 0;
+    let runCount = 0;
+    try {
+        const raw = await io.readText(runsFile(home));
+        if (raw !== null) {
+            const parsed = JSON.parse(raw);
+            runCount = parsed.runs?.length ?? 0;
+            for (const run of parsed.runs ?? []) {
+                if (run.state !== 'running' || typeof run.pid !== 'number')
+                    continue;
+                try {
+                    process.kill(run.pid, 0);
+                }
+                catch {
+                    orphanRuns += 1;
+                }
+            }
+        }
+    }
+    catch {
+        orphanRuns = -1;
+    }
+    rows.push({ key: 'runs', label: 'run owner', status: orphanRuns < 0 ? 'unknown' : orphanRuns === 0 ? 'ok' : 'warn', detail: orphanRuns < 0 ? 'runs.json unreadable' : String(runCount) + ' runs; ' + String(orphanRuns) + ' dead-owner running' });
+    rows.push({ key: 'install', label: 'install form', status: io.exists === undefined ? 'unknown' : 'ok', detail: 'merge plugin loaded' });
+    const reconcile = await readReconcileReport(io, home);
+    rows.push({
+        key: 'reconcile',
+        label: '状态收敛',
+        status: reconcile === null ? 'unknown' : reconcile.state === 'blocked' ? 'warn' : reconcile.actions.length > 0 ? 'warn' : 'ok',
+        detail: reconcile === null
+            ? '尚无 reconcile 报告（启动或 /evolution merge reconcile 会生成）'
+            : reconcile.state === 'blocked'
+                ? 'blocked：' + (reconcile.code ?? 'merge-state-blocked') + (reconcile.message === undefined ? '' : ' — ' + reconcile.message)
+                : String(reconcile.actions.length) + ' 项动作（' + new Date(reconcile.at).toISOString() + '）' + (reconcile.actions.length === 0 ? '' : '：' + reconcile.actions.map(action => action.rowId + '=' + action.code).join(', ')),
     });
-    const modelRoot = configuredRoot !== undefined && configuredRoot !== '' ? configuredRoot : process.env.SKILL_MERGE_MODELS_ROOT;
-    if (modelRoot === undefined || modelRoot === '') {
-        rows.push({ key: 'models', label: '合并模型', status: 'warn', detail: '未设置 SKILL_MERGE_MODELS_ROOT；合并扫描会 fail loud' });
+    rows.push({ key: 'consistency', label: '一致性', status: snapshot.blocked !== undefined ? 'blocked' : invalid.length === 0 ? 'ok' : 'warn', detail: snapshot.blocked !== undefined ? 'blocked: ' + snapshot.blocked.code : invalid.length === 0 ? '无非法组合' : String(invalid.length) + ' 行需人工检查: ' + invalid.map(row => row.id + '=' + row.reason).join(', ') });
+    const modelRoot = configuredRoot?.trim() ?? '';
+    if (modelRoot === '') {
+        rows.push({ key: 'models', label: '合并模型', status: 'warn', detail: '未配置 mergeModelsRoot；合并扫描会 fail loud' });
     }
     else {
         const int8 = join(modelRoot, 'potion-multilingual-128M-int8');
@@ -45,6 +181,24 @@ export async function mergeDoctor(io, home, configuredRoot) {
         status: 'ok',
         detail: stagingRoot(home, '<runId>'),
     });
+    try {
+        const raw = await io.readText(join(home, 'merge', 'recovery.json'));
+        if (raw !== null) {
+            const reports = JSON.parse(raw);
+            const failed = reports.filter(report => report.ok !== true);
+            rows.push({
+                key: 'recovery',
+                label: '提交恢复',
+                status: failed.length === 0 ? 'ok' : 'warn',
+                detail: failed.length === 0
+                    ? String(reports.length) + ' 条恢复报告，无待处理'
+                    : String(failed.length) + ' 条待处理：' + failed.map(report => (report.runId ?? '?') + '=' + (report.action ?? '?')).join(', '),
+            });
+        }
+    }
+    catch {
+        rows.push({ key: 'recovery', label: '提交恢复', status: 'unknown', detail: '无法读取 merge/recovery.json' });
+    }
     return rows;
 }
 //# sourceMappingURL=doctor.js.map

package/lib/types/domain/authoring-manifest.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The round-2 JSON envelope a child writes after authoring: which files the merge left
+ * behind. Both authoring paths (same-child scan round2 and the new-child approve/resume
+ * path) parse it identically, so a declared-but-missing file fails the same way on both.
+ */
+export interface AuthoringManifest {
+    readonly target?: string;
+    readonly files: readonly string[];
+}
+/**
+ * Parse `{"target":..., "files":[...]}` from a child's final turn text.
+ * @param text - the child's answer (JSON is expected; prose is tolerated).
+ * @returns the manifest, or null when the turn carried no well-formed envelope.
+ */
+export declare function parseAuthoringManifest(text: string): AuthoringManifest | null;
+/** Files a manifest promises for a staged tree (declared list, or the tree when undeclared). */
+export declare function manifestFilesOf(manifest: AuthoringManifest | null, stagedPaths: readonly string[]): readonly string[];
+/**
+ * The first file the manifest promises but the staged tree does not contain.
+ * SKILL.md itself is always required, whether or not the manifest lists it.
+ * @param files - manifest files (see {@link manifestFilesOf}).
+ * @param stagedPaths - support-file paths actually present in the staged tree.
+ * @returns the missing path, or null when the declaration is satisfied.
+ */
+export declare function missingManifestFile(files: readonly string[], stagedPaths: readonly string[]): string | null;
+//# sourceMappingURL=authoring-manifest.d.ts.map