ushman-ledger 1.2.2 → 1.3.1

package/dist/cli.js

@@ -9,13 +9,13 @@ import * as v from 'valibot';
 import { readPatchTextFromFile } from "./blobs.js";
 import { openLedger } from "./handle.js";
 import { deriveFilesChangedFromPatch } from "./patch-resolver.js";
-import { ChangeLogParityStatusSchema, ChangeLogSmokeResultSchema, ChangeLogSubkindSchema, LEDGER_KINDS, LEDGER_PHASES, parseLedgerRecord, WorkspaceRelativePathSchema, } from "./schema/entry.js";
+import { ChangeLogParityStatusSchema, ChangeLogSmokeResultSchema, ChangeLogSubkindSchema, LEDGER_KINDS, LEDGER_PHASES, STAGE_WRITE_STAGES, parseLedgerRecord, WorkspaceRelativePathSchema, } from "./schema/entry.js";
 import { NoteSubkindSchema } from "./schema/note.js";
 import { LEDGER_LIBRARY_VERSION } from "./version.js";
 const execFileAsync = promisify(execFile);
 const DEFAULT_GIT_DIFF_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 const DEFAULT_GIT_DIFF_TIMEOUT_MS = 30_000;
-const BOOLEAN_FLAG_NAMES = new Set(['from-stdin', 'help', 'json']);
+const BOOLEAN_FLAG_NAMES = new Set(['from-stdin', 'help', 'json', 'progress', 'quiet']);
 const GIT_DIFF_FORMAT_ARGS = ['--no-color', '--no-ext-diff', '--src-prefix=a/', '--dst-prefix=b/'];
 const RENDER_TARGETS = [
     'retro',
@@ -25,6 +25,12 @@ const RENDER_TARGETS = [
     'migration-log-md',
     'workspace-narrative-md',
 ];
+const CANONICAL_RENDER_TARGETS = new Set([
+    'migration-log-md',
+    'retro',
+    'timeline-html',
+    'workspace-narrative-md',
+]);
 const GIT_DIFF_FLAG_NAMES = ['git-diff-max-buffer-bytes', 'git-diff-timeout-ms', 'git-paths'];
 const CHANGE_LOG_RECORD_ONLY_FLAGS = [
     'commands',
@@ -38,7 +44,8 @@ const CHANGE_LOG_RECORD_ONLY_FLAGS = [
     'smoke-result',
     'subkind',
 ];
-const renderRecordUsage = (commandName) => `${commandName} record [--workspace=<ws>] --kind=<kind> --phase=<phase> --summary="..." [--rationale="..."] [--action=<operator-action>] [--check-id=<check-id>] [--diff=<patch-file>] [--diff-from-git=<ref>] [--git-paths=<csv>] [--git-diff-timeout-ms=<ms>] [--git-diff-max-buffer-bytes=<bytes>] [--idempotency-key=<key>] [--subkind=<change-log-subkind>] [--files-changed=<csv>] [--hypothesis="..."] [--commands="cmd1\ncmd2" | --commands-from=<file>] [--smoke-result=<result>] [--smoke-notes="..."] [--parity-status=<status>] [--rollback-plan="..."] [--rolls-back=<entry-id>] [--from-stdin]`;
+const STAGE_WRITE_ONLY_FLAGS = ['file-path', 'stage'];
+const renderRecordUsage = (commandName) => `${commandName} record [--workspace=<ws>] --kind=<kind> --phase=<phase> --summary="..." [--rationale="..."] [--file-path=<path>] [--stage=<stage>] [--action=<operator-action>] [--check-id=<check-id>] [--diff=<patch-file>] [--diff-from-git=<ref>] [--git-paths=<csv>] [--git-diff-timeout-ms=<ms>] [--git-diff-max-buffer-bytes=<bytes>] [--idempotency-key=<key>] [--subkind=<change-log-subkind>] [--files-changed=<csv>] [--hypothesis="..."] [--commands="cmd1\ncmd2" | --commands-from=<file>] [--smoke-result=<result>] [--smoke-notes="..."] [--parity-status=<status>] [--rollback-plan="..."] [--rolls-back=<entry-id>] [--from-stdin]`;
 class CliUsageError extends Error {
 }
 const DEFAULT_CONTEXT = {
@@ -54,6 +61,7 @@ const DEFAULT_CONTEXT = {
 const renderValidValues = () => `Valid values:
   kinds: ${LEDGER_KINDS.join(', ')}
   phases: ${LEDGER_PHASES.join(', ')}
+  stage-write stages: ${STAGE_WRITE_STAGES.join(', ')}
   note subkinds: ${NoteSubkindSchema.options.join(', ')}
   render targets: ${RENDER_TARGETS.join(', ')}
 `;
@@ -64,6 +72,8 @@ const renderRuntimeTuningHelp = () => `Runtime tuning env vars:
   USHMAN_LEDGER_READ_INDEX_REBUILD_CONCURRENCY (default: USHMAN_LEDGER_SCAN_CONCURRENCY)
   USHMAN_LEDGER_COVERAGE_FILE_STAT_CONCURRENCY (default: USHMAN_LEDGER_SCAN_CONCURRENCY)
   USHMAN_LEDGER_BLOB_HASH_CONCURRENCY (default: USHMAN_LEDGER_SCAN_CONCURRENCY)
+  USHMAN_LEDGER_DOCTOR_CHECKPOINT_MAX_AGE_MS (default: 86400000)
+  USHMAN_LEDGER_DOCTOR_OPEN_ISSUE_MAX_AGE_MS (default: 2592000000)
   USHMAN_LEDGER_MAX_PATCH_BYTES (default: 10485760)
 `;
 const renderHelp = (commandName) => `${commandName}
@@ -71,12 +81,12 @@ const renderHelp = (commandName) => `${commandName}
 Commands:
   ${renderRecordUsage(commandName)}
   ${commandName} note <subkind> [--workspace=<ws>] --phase=<phase> --summary="..." [--body=<markdown-file>] [--from-stdin]
-  ${commandName} list [--workspace=<ws>] [--phase=<phase>] [--kind=<kind>] [--since=<iso>] [--limit=<n>] [--json]
+  ${commandName} list [--workspace=<ws>] [--phase=<phase>] [--kind=<kind>] [--since=<iso>] [--limit=<n>] [--json] [--quiet] [--progress]
   ${commandName} show [--workspace=<ws>] <entry-id>
   ${commandName} tail [--workspace=<ws>] [--phase=<phase>] [--limit=<n>]
-  ${commandName} render [--workspace=<ws>] [--to=retro|jsonl|timeline-html|dependency-graph|migration-log-md|workspace-narrative-md] [--phase=<phase>] [--since=<iso>] [--limit=<n>] [--out=<file>]
-  ${commandName} archive [--workspace=<ws>] --out=<file.tgz>
-  ${commandName} doctor [--workspace=<ws>] [--json]
+  ${commandName} render [--workspace=<ws>] [--to=retro|jsonl|timeline-html|dependency-graph|migration-log-md|workspace-narrative-md] [--phase=<phase>] [--since=<iso>] [--limit=<n>] [--out=<file>] [--quiet] [--progress]
+  ${commandName} archive [--workspace=<ws>] --out=<file.tgz> [--quiet] [--progress]
+  ${commandName} doctor [--workspace=<ws>] [--json] [--quiet] [--progress]
   ${commandName} --version
 
 ${renderValidValues()}
@@ -94,17 +104,17 @@ ${renderRuntimeTuningHelp()}`;
 ${renderValidValues()}
 ${renderRuntimeTuningHelp()}`;
         case 'list':
-            return `${commandName} list [--workspace=<ws>] [--phase=<phase>] [--kind=<kind>] [--since=<iso>] [--limit=<n>] [--json]
+            return `${commandName} list [--workspace=<ws>] [--phase=<phase>] [--kind=<kind>] [--since=<iso>] [--limit=<n>] [--json] [--quiet] [--progress]
 
 ${renderValidValues()}
 ${renderRuntimeTuningHelp()}`;
         case 'render':
-            return `${commandName} render [--workspace=<ws>] [--to=<target>] [--phase=<phase>] [--since=<iso>] [--limit=<n>] [--out=<file>]
+            return `${commandName} render [--workspace=<ws>] [--to=<target>] [--phase=<phase>] [--since=<iso>] [--limit=<n>] [--out=<file>] [--quiet] [--progress]
 
 ${renderValidValues()}
 ${renderRuntimeTuningHelp()}`;
         case 'doctor':
-            return `${commandName} doctor [--workspace=<ws>] [--json]
+            return `${commandName} doctor [--workspace=<ws>] [--json] [--quiet] [--progress]
 
 ${renderRuntimeTuningHelp()}`;
         default:
@@ -213,6 +223,18 @@ const parseWorkspaceRelativePathCsv = ({ flagName, raw }) => {
     }
     return uniquePaths;
 };
+const parseWorkspaceRelativePathFlag = ({ flagName, flags, required = false, }) => {
+    const raw = required ? getRequiredString(flags, flagName) : getFlag(flags, flagName);
+    if (!raw) {
+        return undefined;
+    }
+    try {
+        return v.parse(WorkspaceRelativePathSchema, raw);
+    }
+    catch {
+        throw new CliUsageError(`--${flagName} path is not a normalized workspace-relative path: ${raw}`);
+    }
+};
 const isGitDiffMaxBufferError = (error) => {
     const code = getErrorCode(error);
     if (code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
@@ -291,6 +313,14 @@ const print = (context, text) => {
 const printJson = (context, value) => {
     print(context, JSON.stringify(value, null, 2));
 };
+const isQuiet = (flags) => hasFlag(flags, 'quiet');
+const isProgressEnabled = (flags) => hasFlag(flags, 'progress') && !isQuiet(flags);
+const printProgress = (context, flags, message) => {
+    if (!isProgressEnabled(flags)) {
+        return;
+    }
+    context.stderr.write(`progress ${message}\n`);
+};
 const parseLimit = (flags) => getFlag(flags, 'limit')
     ? parsePositiveIntegerFlag({
         defaultValue: 0,
@@ -350,6 +380,13 @@ const parseRenderTarget = (flags) => {
     }
     return target;
 };
+const parseRequiredStageWriteStage = (flags) => {
+    const stage = getRequiredString(flags, 'stage');
+    if (!STAGE_WRITE_STAGES.includes(stage)) {
+        throw new CliUsageError(`Invalid --stage value: ${stage}. Expected one of: ${STAGE_WRITE_STAGES.join(', ')}.`);
+    }
+    return stage;
+};
 const splitCommandLines = (value) => value
     .split(/\r?\n/u)
     .map((command) => command.trim())
@@ -500,11 +537,13 @@ const validateRecordStdinFlags = (flags) => {
         'operator',
         'parity-status',
         'phase',
+        'file-path',
         'rationale',
         'rollback-plan',
         'rolls-back',
         'smoke-notes',
         'smoke-result',
+        'stage',
         'subkind',
         'summary',
     ].filter((flagName) => hasFlag(flags, flagName));
@@ -515,53 +554,87 @@ const validateRecordStdinFlags = (flags) => {
         .map((flagName) => `--${flagName}`)
         .join(', ')}. When using --from-stdin, provide all record fields in the JSON input.`);
 };
-const buildBaseRecordFromFlags = (parsed, context) => {
-    const kind = getRequiredKind(parsed.flags);
-    if (kind !== 'change-log') {
-        rejectUnsupportedFlags('change-log', parsed.flags, CHANGE_LOG_RECORD_ONLY_FLAGS);
+const applyRationaleFlag = ({ flags, kind, record, }) => {
+    const rationale = getFlag(flags, 'rationale');
+    if (!rationale) {
+        return rationale;
     }
-    const record = {
-        emitter: {
-            tool: context.defaultEmitter.tool,
-            version: context.defaultEmitter.version,
-        },
-        kind,
-        phase: getRequiredPhase(parsed.flags),
-        summary: getRequiredString(parsed.flags, 'summary'),
-    };
-    const rationale = getFlag(parsed.flags, 'rationale');
-    if (rationale) {
-        if (kind !== 'agent-patch' &&
-            kind !== 'operator-patch' &&
-            kind !== 'operator-decision' &&
-            kind !== 'correction') {
-            throw new CliUsageError('--rationale is only supported for patch, operator-decision, and correction records.');
-        }
-        if (kind !== 'operator-decision') {
-            record.rationale = rationale;
-        }
+    if (kind !== 'agent-patch' &&
+        kind !== 'operator-patch' &&
+        kind !== 'operator-decision' &&
+        kind !== 'correction' &&
+        kind !== 'stage-write') {
+        throw new CliUsageError('--rationale is only supported for patch, stage-write, operator-decision, and correction records.');
     }
+    if (kind !== 'operator-decision') {
+        record.rationale = rationale;
+    }
+    return rationale;
+};
+const applyKindSpecificRecordFields = ({ defaultTool, flags, kind, rationale, record, }) => {
     if (kind === 'agent-patch') {
         record.agent = {
-            name: getFlag(parsed.flags, 'agent') ?? context.defaultEmitter.tool,
+            name: getFlag(flags, 'agent') ?? defaultTool,
         };
+        return;
     }
     if (kind === 'operator-patch') {
         record.operator = {
-            name: getFlag(parsed.flags, 'operator') ?? context.defaultEmitter.tool,
+            name: getFlag(flags, 'operator') ?? defaultTool,
         };
+        return;
     }
     if (kind === 'operator-decision') {
-        const action = getRequiredString(parsed.flags, 'action');
         record.payload = {
-            action,
-            checkId: getFlag(parsed.flags, 'check-id'),
+            action: getRequiredString(flags, 'action'),
+            checkId: getFlag(flags, 'check-id'),
             rationale: rationale ?? '',
         };
+        return;
     }
     if (kind === 'change-log') {
-        record.subkind = parseRequiredChangeLogSubkind(parsed.flags);
+        record.subkind = parseRequiredChangeLogSubkind(flags);
+        return;
+    }
+    if (kind === 'stage-write') {
+        record.filePath = parseWorkspaceRelativePathFlag({
+            flagName: 'file-path',
+            flags,
+            required: true,
+        });
+        record.rationale = getRequiredString(flags, 'rationale');
+        record.stage = parseRequiredStageWriteStage(flags);
     }
+};
+const buildBaseRecordFromFlags = (parsed, context) => {
+    const kind = getRequiredKind(parsed.flags);
+    if (kind !== 'change-log') {
+        rejectUnsupportedFlags('change-log', parsed.flags, CHANGE_LOG_RECORD_ONLY_FLAGS);
+    }
+    if (kind !== 'stage-write') {
+        rejectUnsupportedFlags('stage-write', parsed.flags, STAGE_WRITE_ONLY_FLAGS);
+    }
+    const record = {
+        emitter: {
+            tool: context.defaultEmitter.tool,
+            version: context.defaultEmitter.version,
+        },
+        kind,
+        phase: getRequiredPhase(parsed.flags),
+        summary: getRequiredString(parsed.flags, 'summary'),
+    };
+    const rationale = applyRationaleFlag({
+        flags: parsed.flags,
+        kind,
+        record,
+    });
+    applyKindSpecificRecordFields({
+        defaultTool: context.defaultEmitter.tool,
+        flags: parsed.flags,
+        kind,
+        rationale,
+        record,
+    });
     const idempotencyKey = getFlag(parsed.flags, 'idempotency-key');
     if (idempotencyKey) {
         record.idempotencyKey = idempotencyKey;
@@ -732,7 +805,9 @@ const runNoteCli = async (parsed, context) => {
     return 0;
 };
 const runListCli = async (parsed, context) => {
+    printProgress(context, parsed.flags, 'list start');
     const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
+    let entryCount = 0;
     if (hasFlag(parsed.flags, 'json')) {
         let wroteEntry = false;
         context.stdout.write('[\n');
@@ -748,8 +823,10 @@ const runListCli = async (parsed, context) => {
             const renderedEntry = JSON.stringify(entry, null, 2).replaceAll('\n', '\n  ');
             context.stdout.write(`  ${renderedEntry}`);
             wroteEntry = true;
+            entryCount += 1;
         }
         context.stdout.write(wroteEntry ? '\n]\n' : ']\n');
+        printProgress(context, parsed.flags, `list done entries=${entryCount}`);
         return 0;
     }
     for await (const entry of ledger.list({
@@ -758,8 +835,15 @@ const runListCli = async (parsed, context) => {
         phase: parseOptionalPhase(parsed.flags),
         since: parseSince(parsed.flags),
     })) {
-        print(context, `${entry.id} ${entry.phase} ${entry.kind} ${entry.summary}`);
+        entryCount += 1;
+        if (isQuiet(parsed.flags)) {
+            print(context, entry.id);
+        }
+        else {
+            print(context, `${entry.id} ${entry.phase} ${entry.kind} ${entry.summary}`);
+        }
     }
+    printProgress(context, parsed.flags, `list done entries=${entryCount}`);
     return 0;
 };
 const runShowCli = async (parsed, context) => {
@@ -784,6 +868,7 @@ const runTailCli = async (parsed, context) => runListCli({
 }, context);
 const runRenderCli = async (parsed, context) => {
     const target = parseRenderTarget(parsed.flags);
+    printProgress(context, parsed.flags, `render start target=${target}`);
     const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
     const renderOptions = {
         limit: parseLimit(parsed.flags),
@@ -792,19 +877,29 @@ const runRenderCli = async (parsed, context) => {
         since: parseSince(parsed.flags),
         to: target,
     };
-    if (renderOptions.out) {
+    if (isQuiet(parsed.flags) && !renderOptions.out && !CANONICAL_RENDER_TARGETS.has(target)) {
+        throw new CliUsageError(`render --quiet requires --out for ${target} output.`);
+    }
+    if (renderOptions.out || isQuiet(parsed.flags)) {
         await ledger.renderTo(renderOptions);
+        if (isQuiet(parsed.flags)) {
+            print(context, 'ok');
+        }
+        printProgress(context, parsed.flags, `render done target=${target}`);
         return 0;
     }
     const content = await ledger.render(renderOptions);
     print(context, content);
+    printProgress(context, parsed.flags, `render done target=${target}`);
     return 0;
 };
 const runArchiveCli = async (parsed, context) => {
     const outPath = getRequiredString(parsed.flags, 'out');
+    printProgress(context, parsed.flags, 'archive start');
     const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
     const result = await ledger.archive(outPath);
-    print(context, result.integrityHash);
+    print(context, isQuiet(parsed.flags) ? 'ok' : result.integrityHash);
+    printProgress(context, parsed.flags, 'archive done');
     return 0;
 };
 const formatDoctorFinding = (finding) => [`[${finding.code}] ${finding.message}`, `Next step: ${finding.remediation}`].join('\n');
@@ -819,17 +914,32 @@ const printDoctorFindings = (context, report) => {
     context.stderr.write('\n');
 };
 const runDoctorCli = async (parsed, context) => {
+    printProgress(context, parsed.flags, 'doctor start');
     const ledger = await openLedger(getWorkspaceRoot(parsed.flags));
     const result = await ledger.doctor();
     if (hasFlag(parsed.flags, 'json')) {
         printJson(context, result);
+        printProgress(context, parsed.flags, `doctor done issues=${result.issueCount}`);
+        return result.ok ? 0 : 1;
+    }
+    if (isQuiet(parsed.flags)) {
+        if (result.ok) {
+            print(context, 'ok');
+        }
+        else {
+            for (const finding of result.findings) {
+                print(context, finding.code);
+            }
+        }
         return result.ok ? 0 : 1;
     }
     if (result.ok) {
         print(context, 'ok');
+        printProgress(context, parsed.flags, 'doctor done issues=0');
         return 0;
     }
     printDoctorFindings(context, result);
+    printProgress(context, parsed.flags, `doctor done issues=${result.issueCount}`);
     return 1;
 };
 const formatCliError = (error) => {

package/dist/doctor.d.ts

@@ -1,5 +1,5 @@
 import { type PreparedLedgerState } from './recovery.ts';
-export declare const DOCTOR_FINDING_CODES: readonly ["blob-corrupt", "blob-missing", "blob-unreadable", "change-log-rollback-missing-target", "change-log-smoke-failure-missing-rollback-plan", "manifest-entry-count-mismatch", "manifest-entry-location-missing", "manifest-entry-missing-on-disk", "manifest-last-sequence-mismatch", "manifest-per-phase-latest-mismatch", "manifest-phase-mismatch", "manifest-sequence-mismatch", "open-issue-stale", "phase-prev-entry-mismatch", "pre-change-checkpoint-stale", "read-failure"];
+export declare const DOCTOR_FINDING_CODES: readonly ["blob-corrupt", "blob-missing", "blob-unreadable", "change-log-rollback-missing-target", "change-log-smoke-failure-missing-rollback-plan", "manifest-entry-count-mismatch", "manifest-entry-location-missing", "manifest-entry-missing-on-disk", "manifest-last-sequence-mismatch", "manifest-per-phase-latest-mismatch", "manifest-phase-mismatch", "manifest-sequence-mismatch", "open-issue-stale", "pending-commit-quarantined", "phase-prev-entry-mismatch", "pre-change-checkpoint-stale", "read-failure"];
 export type DoctorFindingCode = (typeof DOCTOR_FINDING_CODES)[number];
 export type DoctorFindingMetadataValue = boolean | null | number | string;
 export type DoctorFinding = {

package/dist/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAMA,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAS1E,eAAO,MAAM,oBAAoB,8dAiBvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AACtE,MAAM,MAAM,0BAA0B,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1E,MAAM,MAAM,aAAa,GAAG;IACxB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,aAAa,EAAE,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;CACxB,CAAC;AAqjBF,eAAO,MAAM,eAAe,GACxB,eAAe,MAAM,EACrB,UAAS;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAA;CAAO,KACvF,OAAO,CAAC,YAAY,CAqCtB,CAAC"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../src/doctor.ts"],"names":[],"mappings":"AAMA,OAAO,EAAiD,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAUxG,eAAO,MAAM,oBAAoB,4fAkBvB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AACtE,MAAM,MAAM,0BAA0B,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1E,MAAM,MAAM,aAAa,GAAG;IACxB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,aAAa,EAAE,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;CACxB,CAAC;AAwlBF,eAAO,MAAM,eAAe,GACxB,eAAe,MAAM,EACrB,UAAS;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAA;CAAO,KACvF,OAAO,CAAC,YAAY,CAsCtB,CAAC"}

package/dist/doctor.js

@@ -4,11 +4,12 @@ import { resolveBlobPath } from "./blobs.js";
 import { sha256File } from "./json.js";
 import { getOrderedEntryLocations, readManifestEntryBatch } from "./list.js";
 import { isReadIndexCurrent, readReadIndex } from "./read-index.js";
-import { loadLedgerState } from "./recovery.js";
+import { listPendingCommitQuarantines, loadLedgerState } from "./recovery.js";
 import { getLedgerRuntimeConfig } from "./runtime-config.js";
 import { readManifest } from "./storage/filesystem.js";
-const CHECKPOINT_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
-const OPEN_ISSUE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1_000;
+const HOUR_MS = 60 * 60 * 1_000;
+const DAY_MS = 24 * HOUR_MS;
+const MINUTE_MS = 60 * 1_000;
 export const DOCTOR_FINDING_CODES = [
     'blob-corrupt',
     'blob-missing',
@@ -23,11 +24,12 @@ export const DOCTOR_FINDING_CODES = [
     'manifest-phase-mismatch',
     'manifest-sequence-mismatch',
     'open-issue-stale',
+    'pending-commit-quarantined',
     'phase-prev-entry-mismatch',
     'pre-change-checkpoint-stale',
     'read-failure',
 ];
-const createFinding = ({ code, message, metadata, remediation, }) => ({
+const createFinding = ({ code, message, metadata, remediation }) => ({
     code,
     message,
     metadata,
@@ -40,6 +42,19 @@ const buildDoctorReport = (findings) => ({
     issues: findings.map((finding) => finding.message),
     ok: findings.length === 0,
 });
+const formatAgeThreshold = (ageMs) => {
+    if (ageMs >= DAY_MS && ageMs % DAY_MS === 0) {
+        const days = ageMs / DAY_MS;
+        return `${days} day${days === 1 ? '' : 's'}`;
+    }
+    if (ageMs >= HOUR_MS && ageMs % HOUR_MS === 0) {
+        return `${ageMs / HOUR_MS}h`;
+    }
+    if (ageMs >= MINUTE_MS && ageMs % MINUTE_MS === 0) {
+        return `${ageMs / MINUTE_MS}m`;
+    }
+    return `${ageMs}ms`;
+};
 const pushFinding = (findings, finding) => {
     findings.push(finding);
 };
@@ -50,7 +65,7 @@ const isMissingPathError = (error) => {
 const buildReadFailure = (error) => buildDoctorReport([
     createFinding({
         code: 'read-failure',
-        message: `Failed to read ledger state: ${error instanceof Error ? error.message ?? error.name : String(error)}.`,
+        message: `Failed to read ledger state: ${error instanceof Error ? (error.message ?? error.name) : String(error)}.`,
         remediation: 'Re-open the ledger or rerun the command first so recovery can reconcile pending state. If the error persists, repair or restore the invalid manifest/read-index JSON before archiving.',
     }),
 ]);
@@ -130,6 +145,20 @@ const checkBlobPresence = async (workspaceRoot, blobChecks) => {
     });
     return results.flat();
 };
+const checkPendingCommitQuarantines = async (workspaceRoot) => {
+    const quarantines = await listPendingCommitQuarantines(workspaceRoot);
+    return quarantines.map((quarantine) => createFinding({
+        code: 'pending-commit-quarantined',
+        message: `Pending commit journal ${quarantine.originalFileName} is quarantined: ${quarantine.reason}`,
+        metadata: {
+            commitPath: quarantine.commitPath,
+            metadataPath: quarantine.metadataPath,
+            originalFileName: quarantine.originalFileName,
+            quarantinedAt: quarantine.quarantinedAt,
+        },
+        remediation: 'Inspect the quarantined journal under .lab/ledger/pending-quarantine/. Restore it to .lab/ledger/pending/ only if its entry, sequence, and manifest base are known to be safe; otherwise keep or remove it after recording an operator decision.',
+    }));
+};
 const checkManifestCounts = (findings, manifest, entryCount) => {
     if (manifest.entryCount !== entryCount) {
         pushFinding(findings, createFinding({
@@ -218,10 +247,11 @@ const trackIdempotencyEntry = (entry, entriesByIdempotencyKey) => {
     existingEntries.push({ id: entry.id, ts: entry.ts });
     entriesByIdempotencyKey.set(idempotencyKey, existingEntries);
 };
-const checkChangeLogWarnings = ({ checkpointEntries, entriesByIdempotencyKey, findings, nowMs, openIssueEntries, resolvedLedgerIds, }) => {
+const checkChangeLogWarnings = ({ checkpointEntries, checkpointMaxAgeMs, entriesByIdempotencyKey, findings, nowMs, openIssueMaxAgeMs, openIssueEntries, resolvedLedgerIds, }) => {
+    const checkpointMaxAgeLabel = formatAgeThreshold(checkpointMaxAgeMs);
     for (const checkpointEntry of checkpointEntries) {
         const ageMs = nowMs - Date.parse(checkpointEntry.ts);
-        if (ageMs <= CHECKPOINT_MAX_AGE_MS) {
+        if (ageMs <= checkpointMaxAgeMs) {
             continue;
         }
         const idempotencyKey = checkpointEntry.links.idempotencyKey;
@@ -230,7 +260,7 @@ const checkChangeLogWarnings = ({ checkpointEntries, entriesByIdempotencyKey, fi
         if (!hasFollowUp) {
             pushFinding(findings, createFinding({
                 code: 'pre-change-checkpoint-stale',
-                message: `Pre-change checkpoint ${checkpointEntry.id} is older than 24h and has no follow-up entry with matching idempotencyKey.`,
+                message: `Pre-change checkpoint ${checkpointEntry.id} is older than ${checkpointMaxAgeLabel} and has no follow-up entry with matching idempotencyKey.`,
                 metadata: {
                     entryId: checkpointEntry.id,
                     idempotencyKey: idempotencyKey ?? null,
@@ -239,14 +269,15 @@ const checkChangeLogWarnings = ({ checkpointEntries, entriesByIdempotencyKey, fi
             }));
         }
     }
+    const openIssueMaxAgeLabel = formatAgeThreshold(openIssueMaxAgeMs);
     for (const openIssueEntry of openIssueEntries) {
         const ageMs = nowMs - Date.parse(openIssueEntry.ts);
-        if (ageMs <= OPEN_ISSUE_MAX_AGE_MS || resolvedLedgerIds.has(openIssueEntry.id)) {
+        if (ageMs <= openIssueMaxAgeMs || resolvedLedgerIds.has(openIssueEntry.id)) {
             continue;
         }
         pushFinding(findings, createFinding({
             code: 'open-issue-stale',
-            message: `Open issue note ${openIssueEntry.id} is older than 30 days and has no resolution link.`,
+            message: `Open issue note ${openIssueEntry.id} is older than ${openIssueMaxAgeLabel} and has no resolution link.`,
             metadata: { entryId: openIssueEntry.id },
             remediation: 'Append a correction or superseding note that links back to the open issue once the follow-up is complete.',
         }));
@@ -351,7 +382,7 @@ const collectDoctorState = async (workspaceRoot, manifest, readIndex) => {
     const resolvedLedgerIds = new Set();
     let entryCount = 0;
     const nowMs = Date.now();
-    const { scanBatchSize, scanConcurrency } = getLedgerRuntimeConfig();
+    const { doctorCheckpointMaxAgeMs, doctorOpenIssueMaxAgeMs, scanBatchSize, scanConcurrency } = getLedgerRuntimeConfig();
     const orderedEntries = getOrderedEntryLocations(manifest, readIndex, {});
     checkManifestSequenceOrder(orderedEntries, findings);
     for (let index = 0; index < orderedEntries.length; index += scanBatchSize) {
@@ -384,9 +415,11 @@ const collectDoctorState = async (workspaceRoot, manifest, readIndex) => {
     }
     checkChangeLogWarnings({
         checkpointEntries,
+        checkpointMaxAgeMs: doctorCheckpointMaxAgeMs,
         entriesByIdempotencyKey,
         findings,
         nowMs,
+        openIssueMaxAgeMs: doctorOpenIssueMaxAgeMs,
         openIssueEntries,
         resolvedLedgerIds,
     });
@@ -427,6 +460,7 @@ export const runLedgerDoctor = async (workspaceRoot, options = {}) => {
         return buildReadFailure(error);
     }
     const { blobChecks, entryCount, findings, latestByPhase, unseenManifestEntryIds } = doctorState;
+    findings.push(...(await checkPendingCommitQuarantines(workspaceRoot)));
     findings.push(...(await checkBlobPresence(workspaceRoot, blobChecks)));
     finalizeManifestChecks({
         entryCount,

package/dist/handle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAA8B,KAAK,YAAY,EAAe,MAAM,WAAW,CAAC;AACvF,OAAO,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAStD,OAAO,KAAK,EAAE,WAAW,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAG9E,MAAM,MAAM,YAAY,GAClB,kBAAkB,GAClB,OAAO,GACP,kBAAkB,GAClB,OAAO,GACP,eAAe,GACf,wBAAwB,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEnE,iGAAiG;AACjG,MAAM,MAAM,mBAAmB,GAAG;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;CAC7B,CAAC;AAEF,2HAA2H;AAC3H,MAAM,MAAM,qBAAqB,GAAG;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;CACjC,CAAC;AA4GF,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1E,QAAQ,CAAC,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC;IACrF,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC;IAC5E,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,YAAY,KAAK,aAAa,CAAC,WAAW,CAAC,CAAC;IACrE,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtG,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACnE,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACnE,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,UAAU,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,YAAY,CAyF5E,CAAC"}
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAA8B,KAAK,YAAY,EAAe,MAAM,WAAW,CAAC;AACvF,OAAO,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAStD,OAAO,KAAK,EAAE,WAAW,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQ9E,MAAM,MAAM,YAAY,GAClB,kBAAkB,GAClB,OAAO,GACP,kBAAkB,GAClB,OAAO,GACP,eAAe,GACf,wBAAwB,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEnE,iGAAiG;AACjG,MAAM,MAAM,mBAAmB,GAAG;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;CAC7B,CAAC;AAEF,2HAA2H;AAC3H,MAAM,MAAM,qBAAqB,GAAG;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;CACjC,CAAC;AA+KF,MAAM,MAAM,YAAY,GAAG;IACvB,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1E,QAAQ,CAAC,eAAe,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC;IACrF,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC;IAC5E,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,YAAY,KAAK,aAAa,CAAC,WAAW,CAAC,CAAC;IACrE,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtG,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACnE,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;CACnE,CAAC;AAEF,yFAAyF;AACzF,eAAO,MAAM,UAAU,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,YAAY,CA6E5E,CAAC"}