@planu/cli 5.7.5 → 5.7.6

package/dist/engine/reconcile/propagate-mirrors.js

@@ -0,0 +1,311 @@
+import { escapeRegex } from '../../core/shared/strings.js';
+import { normalizeCriterionText } from '../criterion-identity.js';
+import { parseBddScenarios, renderBddScenariosYaml } from '../spec-format/bdd-parser.js';
+import { extractSectionCriteria } from '../spec-format/acceptance-criteria.js';
+import { extractListItems, findMarkdownSectionRange } from '../spec-format/markdown-sections.js';
+import { parseCriterionGroundingRecords, parseTechnicalReferenceGroundingRecords, renderGroundingFrontmatter, renderTechnicalReferenceGroundingFrontmatter, } from '../spec-grounding/contract.js';
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n/;
+const ACCEPTANCE_CRITERIA_HEADING = 'Acceptance Criteria';
+const FILES_HEADING = 'Files';
+const TECHNICAL_HEADING = 'Technical';
+const FILE_WORK_PLAN_HEADING = 'File-Level Work Plan';
+const ACCEPTANCE_MAP_HEADING = 'Acceptance-To-Verification Map';
+const VERIFICATION_COMMANDS_HEADING = 'Verification Commands';
+const VERIFICATION_STARTS_WITH_RE = /Verification starts with:\s*`([^`]+)`/i;
+export function propagateMirrors(content, appliedSections) {
+    let result = content;
+    if (appliedSections.has(ACCEPTANCE_CRITERIA_HEADING)) {
+        result = propagateAcceptanceCriteria(result);
+    }
+    if (appliedSections.has(FILES_HEADING)) {
+        result = propagateFiles(result);
+    }
+    if (appliedSections.has(TECHNICAL_HEADING)) {
+        result = propagateTechnicalVerificationCommand(result);
+    }
+    return result;
+}
+function propagateAcceptanceCriteria(content) {
+    const section = findMarkdownSectionRange(content, ACCEPTANCE_CRITERIA_HEADING);
+    if (!section) {
+        return content;
+    }
+    const sectionBody = content.slice(section.contentStart, section.end);
+    const criteriaTexts = extractSectionCriteria(sectionBody);
+    const scenarios = criteriaTexts.map(criterionToScenario);
+    const oldRecords = mapWithFrontmatter(content, (fm) => indexCriterionRecords(parseCriterionGroundingRecords(fm)));
+    const oldTestPaths = mapWithFrontmatter(content, (fm) => parseTechnicalReferenceGroundingRecords(fm)
+        .filter((record) => record.section === 'test')
+        .map((record) => record.path));
+    const criteriaRecords = criteriaTexts.map((text) => oldRecords.get(normalizeCriterionText(text)) ?? {
+        text,
+        source: 'user_input',
+        evidence: ['reconcile_spec.changes'],
+        confidence: 'high',
+    });
+    let result = transformFrontmatter(content, (fm) => {
+        let updated = replaceFrontmatterKeyBlock(fm, 'scenarios', renderBddScenariosYaml(scenarios));
+        updated = replaceFrontmatterKeyBlock(updated, 'grounding', groundingBlockLines(criteriaRecords, technicalReferencesFromFrontmatter(fm)));
+        return updated;
+    });
+    result = withSectionBody(result, ACCEPTANCE_MAP_HEADING, (body) => syncAcceptanceMapForCriteria(body, criteriaTexts, oldTestPaths));
+    return result;
+}
+function propagateFiles(content) {
+    const section = findMarkdownSectionRange(content, FILES_HEADING);
+    if (!section) {
+        return content;
+    }
+    const sectionBody = content.slice(section.contentStart, section.end);
+    const files = parseFilesSection(sectionBody);
+    const oldTestPaths = mapWithFrontmatter(content, (fm) => parseTechnicalReferenceGroundingRecords(fm)
+        .filter((record) => record.section === 'test')
+        .map((record) => record.path));
+    const oldTechnicalReferences = mapWithFrontmatter(content, (fm) => indexTechnicalReferenceRecords(parseTechnicalReferenceGroundingRecords(fm)));
+    const technicalReferences = buildTechnicalReferenceRecords(files, oldTechnicalReferences);
+    const newTestPaths = files.test;
+    let result = transformFrontmatter(content, (fm) => replaceFrontmatterKeyBlock(fm, 'grounding', groundingBlockLines(criteriaRecordsFromFrontmatter(fm), technicalReferences)));
+    result = replaceNamedSection(result, FILE_WORK_PLAN_HEADING, renderFileWorkPlan(files));
+    result = withSectionBody(result, ACCEPTANCE_MAP_HEADING, (body) => addVerifiedTestPathEntries(body, oldTestPaths, newTestPaths));
+    result = withSectionBody(result, VERIFICATION_COMMANDS_HEADING, (body) => syncVerificationCommandLines(body, oldTestPaths, newTestPaths));
+    return result;
+}
+function propagateTechnicalVerificationCommand(content) {
+    const technicalSection = findMarkdownSectionRange(content, TECHNICAL_HEADING);
+    if (!technicalSection) {
+        return content;
+    }
+    const technicalBody = content.slice(technicalSection.contentStart, technicalSection.end);
+    const newCommand = VERIFICATION_STARTS_WITH_RE.exec(technicalBody)?.[1]?.trim();
+    if (!newCommand) {
+        return content;
+    }
+    const commandsSection = findMarkdownSectionRange(content, VERIFICATION_COMMANDS_HEADING);
+    if (!commandsSection) {
+        return content;
+    }
+    const currentBody = content.slice(commandsSection.contentStart, commandsSection.end);
+    if (currentBody.includes(newCommand)) {
+        return content;
+    }
+    return replaceNamedSection(content, VERIFICATION_COMMANDS_HEADING, [`- \`${newCommand}\``]);
+}
+function criterionToScenario(text) {
+    const gwtLines = text
+        .split(/\b(GIVEN|WHEN|THEN|AND)\b/)
+        .reduce((lines, part, index, parts) => {
+        if (index % 2 === 0) {
+            return lines;
+        }
+        const keyword = part;
+        const rest = (parts[index + 1] ?? '').trim();
+        lines.push(`${keyword} ${rest}`);
+        return lines;
+    }, []);
+    const [scenario] = parseBddScenarios(gwtLines.join('\n'));
+    return scenario ?? { title: text, steps: [{ keyword: 'then', text }], done: false };
+}
+function indexCriterionRecords(records) {
+    const index = new Map();
+    for (const record of records) {
+        index.set(normalizeCriterionText(record.text), record);
+    }
+    return index;
+}
+function indexTechnicalReferenceRecords(records) {
+    const index = new Map();
+    for (const record of records) {
+        index.set(record.path, record);
+    }
+    return index;
+}
+function parseFilesSection(sectionBody) {
+    return {
+        create: parseFilesSubsection(sectionBody, 'Create'),
+        modify: parseFilesSubsection(sectionBody, 'Modify'),
+        test: parseFilesSubsection(sectionBody, 'Test'),
+    };
+}
+function parseFilesSubsection(sectionBody, heading) {
+    const range = findMarkdownSectionRange(sectionBody, heading);
+    if (!range) {
+        return [];
+    }
+    const body = sectionBody.slice(range.contentStart, range.end);
+    return extractListItems(body).map((item) => item.replace(/`/g, '').trim());
+}
+function buildTechnicalReferenceRecords(files, oldRecords) {
+    const groups = [
+        ['create', files.create],
+        ['modify', files.modify],
+        ['test', files.test],
+    ];
+    const records = [];
+    for (const [section, paths] of groups) {
+        for (const path of paths) {
+            const existing = oldRecords.get(path);
+            records.push(existing
+                ? { ...existing, section }
+                : {
+                    path,
+                    section,
+                    source: 'user_input',
+                    evidence: ['reconcile_spec.changes'],
+                    confidence: 'high',
+                });
+        }
+    }
+    return records;
+}
+function renderFileWorkPlan(files) {
+    const groups = [
+        ['Create', files.create],
+        ['Modify', files.modify],
+        ['Test', files.test],
+    ];
+    return groups.flatMap(([label, paths]) => paths.map((path) => `- ${label}: \`${path}\` (pending)`));
+}
+function isVerifiedByLine(line, path) {
+    return /^-\s*Verified by:/i.test(line.trim()) && line.includes(path);
+}
+function addVerifiedTestPathEntries(body, oldPaths, newPaths) {
+    const removed = oldPaths.filter((path) => !newPaths.includes(path));
+    const added = newPaths.filter((path) => !oldPaths.includes(path));
+    if (removed.length === 0 && added.length === 0) {
+        return body;
+    }
+    let updated = removed.length === 0
+        ? body
+        : body
+            .split('\n')
+            .filter((line) => !removed.some((path) => isVerifiedByLine(line, path)))
+            .join('\n');
+    if (added.length > 0) {
+        const bulletLines = added.map((path) => `- Verified by: \`${path}\``).join('\n');
+        updated = `${updated.trimEnd()}\n${bulletLines}\n`;
+    }
+    return updated;
+}
+function isTestRunnerCommandLine(line) {
+    return /`[^`]*\b(vitest|jest|mocha|pnpm test|npm test)\b[^`]*`/i.test(line);
+}
+function syncVerificationCommandLines(body, oldPaths, newPaths) {
+    const removed = oldPaths.filter((path) => !newPaths.includes(path));
+    const added = newPaths.filter((path) => !oldPaths.includes(path));
+    if (removed.length === 0 && added.length === 0) {
+        return body;
+    }
+    const lines = body.split('\n').map((line) => {
+        if (!oldPaths.some((path) => line.includes(path))) {
+            return line;
+        }
+        return substituteTestPathsInLine(line, removed, added);
+    });
+    const stillMissing = added.filter((path) => !lines.some((line) => line.includes(path)));
+    if (stillMissing.length === 0) {
+        return lines.join('\n');
+    }
+    const commandLineIndex = lines.findIndex(isTestRunnerCommandLine);
+    if (commandLineIndex !== -1) {
+        lines[commandLineIndex] = substituteTestPathsInLine(lines[commandLineIndex] ?? '', [], stillMissing);
+        return lines.join('\n');
+    }
+    while (lines.length > 0 && lines[lines.length - 1]?.trim() === '') {
+        lines.pop();
+    }
+    return `${[...lines, ...stillMissing.map((path) => `- \`${path}\``)].join('\n')}\n`;
+}
+function syncAcceptanceMapForCriteria(body, criteriaTexts, testPaths) {
+    const lines = body.split('\n').filter((line) => line.trim().length > 0);
+    const kept = lines.filter((line) => criteriaTexts.some((text) => line.includes(text)));
+    const covered = new Set(kept.flatMap((line) => criteriaTexts.filter((text) => line.includes(text))));
+    const newEntries = criteriaTexts
+        .filter((text) => !covered.has(text))
+        .map((text) => renderAcceptanceMapEntry(text, testPaths));
+    const resultLines = [...kept, ...newEntries];
+    if (resultLines.length === 0) {
+        return body;
+    }
+    return `${resultLines.join('\n')}\n`;
+}
+function renderAcceptanceMapEntry(criterionText, testPaths) {
+    return testPaths.length > 0
+        ? `- ${criterionText}: verified by ${testPaths.map((path) => `\`${path}\``).join(', ')}`
+        : `- ${criterionText}: verification pending — no test file listed yet`;
+}
+function substituteTestPathsInLine(line, removed, added) {
+    let updated = line;
+    for (const path of removed) {
+        updated = updated.replace(new RegExp(`\\s*${escapeRegex(path)}`), '');
+    }
+    if (added.length === 0) {
+        return updated;
+    }
+    const insertion = ` ${added.join(' ')}`;
+    if (updated.endsWith('`.')) {
+        return `${updated.slice(0, -2)}${insertion}\`.`;
+    }
+    if (updated.endsWith('`')) {
+        return `${updated.slice(0, -1)}${insertion}\``;
+    }
+    return `${updated}${insertion}`;
+}
+function replaceNamedSection(content, headingName, bodyLines) {
+    const range = findMarkdownSectionRange(content, headingName);
+    if (!range) {
+        return content;
+    }
+    const isLast = range.end >= content.length;
+    const body = bodyLines.join('\n');
+    const tail = isLast ? `${body}\n` : `${body}\n\n`;
+    return content.slice(0, range.contentStart) + tail + content.slice(range.end);
+}
+function withSectionBody(content, headingName, transform) {
+    const range = findMarkdownSectionRange(content, headingName);
+    if (!range) {
+        return content;
+    }
+    const body = content.slice(range.contentStart, range.end);
+    const updated = transform(body);
+    if (updated === body) {
+        return content;
+    }
+    return content.slice(0, range.contentStart) + updated + content.slice(range.end);
+}
+function transformFrontmatter(content, transform) {
+    const match = FRONTMATTER_RE.exec(content);
+    if (!match?.[1]) {
+        return content;
+    }
+    const updated = transform(match[1]);
+    return `---\n${updated}\n---\n${content.slice(match[0].length)}`;
+}
+function mapWithFrontmatter(content, read) {
+    const match = FRONTMATTER_RE.exec(content);
+    return read(match?.[1] ?? '');
+}
+function technicalReferencesFromFrontmatter(frontmatter) {
+    return parseTechnicalReferenceGroundingRecords(frontmatter);
+}
+function criteriaRecordsFromFrontmatter(frontmatter) {
+    return parseCriterionGroundingRecords(frontmatter);
+}
+function groundingBlockLines(criteria, technicalReferences) {
+    const criteriaLines = renderGroundingFrontmatter(criteria).slice(2);
+    const technicalReferenceLines = technicalReferences.length > 0
+        ? renderTechnicalReferenceGroundingFrontmatter(technicalReferences)
+        : [];
+    return ['grounding:', ...criteriaLines, ...technicalReferenceLines];
+}
+function replaceFrontmatterKeyBlock(frontmatter, key, blockLines) {
+    const re = new RegExp(`^${escapeRegex(key)}:.*(?:\\n[ \\t]+.*)*`, 'm');
+    const match = re.exec(frontmatter);
+    const replacement = blockLines.join('\n');
+    if (!match) {
+        return `${frontmatter.trimEnd()}\n${replacement}`;
+    }
+    return (frontmatter.slice(0, match.index) +
+        replacement +
+        frontmatter.slice(match.index + match[0].length));
+}
+//# sourceMappingURL=propagate-mirrors.js.map

package/dist/engine/self-healing/healer.js

@@ -3,6 +3,7 @@ import { applyTypescriptFix } from './strategies/typescript-fix.js';
 import { applyLintFix } from './strategies/lint-fix.js';
 import { applyTestFix } from './strategies/test-fix.js';
 import { applyCoverageFix } from './strategies/coverage-fix.js';
+import { qaCheckTimeoutMs } from '../qa-gate.js';
 const MAX_ATTEMPTS = 3;
 /**
  * Maps a failure type to the appropriate fix strategy name.
@@ -24,14 +25,14 @@ export function identifyFixStrategy(failureType) {
 /**
  * Dispatches to the appropriate strategy based on strategy name.
  */
-function runStrategy(strategyName, projectPath, details) {
+function runStrategy(strategyName, projectPath, details, timeoutMs) {
     switch (strategyName) {
         case technologyValue('technology-typescript-969545'):
-            return applyTypescriptFix(projectPath, details);
+            return applyTypescriptFix(projectPath, details, timeoutMs);
         case 'lint':
-            return applyLintFix(projectPath, details);
+            return applyLintFix(projectPath, details, timeoutMs);
         case 'tests':
-            return applyTestFix(projectPath, details);
+            return applyTestFix(projectPath, details, timeoutMs);
         case 'coverage':
             return applyCoverageFix(projectPath, details);
     }
@@ -47,8 +48,14 @@ export async function runHealingLoop(specId, projectPath, failureContext) {
     const fixedIssues = [];
     const remainingIssues = [];
     let healed = false;
+    const deadline = Date.now() + qaCheckTimeoutMs();
     for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
-        const result = await runStrategy(strategy, projectPath, failureContext.details);
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+            remainingIssues.push(`Attempt ${attempt}: skipped — healing wall-clock budget exhausted`);
+            break;
+        }
+        const result = await runStrategy(strategy, projectPath, failureContext.details, remainingMs);
         if (result.fixed) {
             attempts.push({
                 strategy,

package/dist/engine/self-healing/strategies/lint-fix.d.ts

@@ -2,5 +2,5 @@ import type { StrategyResult } from '../../../types/index.js';
 /**
  * Runs eslint --fix on the project and reports what was fixed.
  */
-export declare function applyLintFix(projectPath: string, _details: string): Promise<StrategyResult>;
+export declare function applyLintFix(projectPath: string, _details: string, timeoutMs?: number): Promise<StrategyResult>;
 //# sourceMappingURL=lint-fix.d.ts.map

package/dist/engine/self-healing/strategies/lint-fix.js

@@ -1,14 +1,17 @@
 // engine/self-healing/strategies/lint-fix.ts — SPEC-474: ESLint auto-fix strategy
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { qaCheckTimeoutMs } from '../../qa-gate.js';
 const execFileAsync = promisify(execFile);
 /**
  * Runs eslint --fix on the project and reports what was fixed.
  */
-export async function applyLintFix(projectPath, _details) {
+export async function applyLintFix(projectPath, _details, timeoutMs = qaCheckTimeoutMs()) {
     try {
         await execFileAsync('pnpm', ['eslint', '--fix', 'src/', 'tests/', '--ext', '.ts'], {
             cwd: projectPath,
+            timeout: timeoutMs,
+            maxBuffer: 10 * 1024 * 1024,
         });
         return {
             fixed: true,

package/dist/engine/self-healing/strategies/test-fix.d.ts

@@ -1,7 +1,8 @@
 import type { StrategyResult } from '../../../types/index.js';
 /**
- * Identifies failing tests from `pnpm test` output and reports what needs manual review.
- * Does NOT modify test files — test logic changes require human judgment.
+ * Identifies failing tests from the project's test command output and reports
+ * what needs manual review. Does NOT modify test files — test logic changes
+ * require human judgment.
  */
-export declare function applyTestFix(projectPath: string, _details: string): Promise<StrategyResult>;
+export declare function applyTestFix(projectPath: string, _details: string, timeoutMs?: number): Promise<StrategyResult>;
 //# sourceMappingURL=test-fix.d.ts.map

package/dist/engine/self-healing/strategies/test-fix.js

@@ -1,5 +1,8 @@
 // engine/self-healing/strategies/test-fix.ts — SPEC-474: Test fix strategy
-import { execSync } from 'node:child_process';
+import { detectPackageManager } from '../../project-dna/stack-detector.js';
+import { runAbortableProcess } from '../../abortable-process-runner.js';
+import { getRuntimePolicy } from '../../runtime-policy.js';
+import { qaCheckTimeoutMs } from '../../qa-gate.js';
 /**
  * Parses failing test entries from vitest output.
  * Looks for:
@@ -42,25 +45,40 @@ function parseFailingTests(output) {
     }
     return results;
 }
+function testCommandFor(packageManager) {
+    switch (packageManager) {
+        case 'yarn':
+            return { executable: 'yarn', args: ['test'] };
+        case 'npm':
+            return { executable: 'npm', args: ['test'] };
+        case 'bun':
+            return { executable: 'bun', args: ['run', 'test'] };
+        default:
+            return { executable: 'pnpm', args: ['test'] };
+    }
+}
 /**
- * Identifies failing tests from `pnpm test` output and reports what needs manual review.
- * Does NOT modify test files — test logic changes require human judgment.
+ * Identifies failing tests from the project's test command output and reports
+ * what needs manual review. Does NOT modify test files — test logic changes
+ * require human judgment.
  */
-export function applyTestFix(projectPath, _details) {
-    return Promise.resolve(runTestDiagnostic(projectPath));
+export async function applyTestFix(projectPath, _details, timeoutMs = qaCheckTimeoutMs()) {
+    return runTestDiagnostic(await captureTestOutput(projectPath, timeoutMs));
 }
-function captureTestOutput(projectPath) {
-    try {
-        execSync('pnpm test', { cwd: projectPath, stdio: 'pipe', encoding: 'utf-8' });
+async function captureTestOutput(projectPath, timeoutMs) {
+    const packageManager = await detectPackageManager(projectPath);
+    const { executable, args } = testCommandFor(packageManager);
+    const result = await runAbortableProcess(executable, args, {
+        cwd: projectPath,
+        timeoutMs,
+        maxBufferBytes: getRuntimePolicy().qualityAssurance.maximumOutputBufferBytes,
+    });
+    if (result.status === 0) {
         return null;
     }
-    catch (err) {
-        const errObj = err;
-        return errObj.stdout ?? errObj.stderr ?? errObj.message ?? '';
-    }
+    return [result.stdout, result.stderr].join('\n');
 }
-function runTestDiagnostic(projectPath) {
-    const output = captureTestOutput(projectPath);
+function runTestDiagnostic(output) {
     if (output === null) {
         return { fixed: true, reason: 'All tests pass — no failures detected', fixedIssues: [] };
     }

package/dist/engine/self-healing/strategies/typescript-fix.d.ts

@@ -1,3 +1,3 @@
 import type { StrategyResult } from '../../../types/index.js';
-export declare function applyTypescriptFix(projectPath: string, _details: string): Promise<StrategyResult>;
+export declare function applyTypescriptFix(projectPath: string, _details: string, timeoutMs?: number): Promise<StrategyResult>;
 //# sourceMappingURL=typescript-fix.d.ts.map

package/dist/engine/self-healing/strategies/typescript-fix.js

@@ -1,7 +1,10 @@
 // engine/self-healing/strategies/typescript-fix.ts — SPEC-474: TypeScript fix strategy
-import { execSync } from 'node:child_process';
 import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { detectPackageManager } from '../../project-dna/stack-detector.js';
+import { runAbortableProcess } from '../../abortable-process-runner.js';
+import { getRuntimePolicy } from '../../runtime-policy.js';
+import { qaCheckTimeoutMs } from '../../qa-gate.js';
 /**
  * Parses TS6133 (unused import) errors from tsc output.
  * Format: path/file.ts(10,5): error TS6133: 'foo' is declared but its value is never read.
@@ -94,22 +97,37 @@ async function fixFileUnusedImports(projectPath, filePath, entries) {
     }
     return { fixed: fixedDescriptions, skipped };
 }
+function typecheckCommandFor(packageManager) {
+    switch (packageManager) {
+        case 'yarn':
+            return { executable: 'yarn', args: ['typecheck'] };
+        case 'npm':
+            return { executable: 'npm', args: ['run', 'typecheck'] };
+        case 'bun':
+            return { executable: 'bun', args: ['run', 'typecheck'] };
+        default:
+            return { executable: 'pnpm', args: ['typecheck'] };
+    }
+}
 /**
  * Attempts to fix TypeScript errors by parsing tsc output and applying safe fixes:
  * - TS6133: removes unused imports when the pattern is unambiguous
  */
-function captureTypecheckOutput(projectPath) {
-    try {
-        execSync('pnpm typecheck', { cwd: projectPath, stdio: 'pipe', encoding: 'utf-8' });
+async function captureTypecheckOutput(projectPath, timeoutMs) {
+    const packageManager = await detectPackageManager(projectPath);
+    const { executable, args } = typecheckCommandFor(packageManager);
+    const result = await runAbortableProcess(executable, args, {
+        cwd: projectPath,
+        timeoutMs,
+        maxBufferBytes: getRuntimePolicy().qualityAssurance.maximumOutputBufferBytes,
+    });
+    if (result.status === 0) {
         return null;
     }
-    catch (err) {
-        const errObj = err;
-        return errObj.stdout ?? errObj.stderr ?? errObj.message ?? '';
-    }
+    return [result.stdout, result.stderr].join('\n');
 }
-export async function applyTypescriptFix(projectPath, _details) {
-    const output = captureTypecheckOutput(projectPath);
+export async function applyTypescriptFix(projectPath, _details, timeoutMs = qaCheckTimeoutMs()) {
+    const output = await captureTypecheckOutput(projectPath, timeoutMs);
     if (output === null) {
         return { fixed: true, reason: 'No TypeScript errors found', fixedIssues: [] };
     }

package/dist/engine/session/checkpoint-writer.js

@@ -3,7 +3,7 @@
 // Fire-and-forget safe — never throws to caller.
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { sessionTracker } from './session-tracker.js';
+import { getSessionTracker } from './session-tracker.js';
 const MAX_DISPLAYED_CALLS = 5;
 const MAX_DISPLAYED_ERRORS = 3;
 const MAX_DISPLAYED_FILES = 10;
@@ -83,9 +83,13 @@ export async function writeCheckpoint(projectPath, snapshot) {
  * Call this from safe-handler.ts after each tool response.
  */
 export function maybeWriteCheckpoint(toolName, success, projectPath) {
-    sessionTracker.recordCall(toolName, success);
-    if (sessionTracker.shouldCheckpoint() && projectPath !== undefined) {
-        void writeCheckpoint(projectPath, sessionTracker.getSnapshot()).catch(() => {
+    if (projectPath === undefined) {
+        return;
+    }
+    const tracker = getSessionTracker(projectPath);
+    tracker.recordCall(toolName, success);
+    if (tracker.shouldCheckpoint()) {
+        void writeCheckpoint(projectPath, tracker.getSnapshot()).catch(() => {
             /* resilient — never affects tool response */
         });
     }

package/dist/engine/session/session-tracker.d.ts

@@ -1,31 +1,20 @@
 import type { AutoCheckpointPolicy, AutoSessionSnapshot } from '../../types/index.js';
-declare class SessionTracker {
+export declare class SessionTracker {
     private callCount;
     private readonly lastCalls;
     private readonly modifiedFiles;
     private readonly errors;
-    private policy;
-    /** Record a tool call. Appends to lastCalls (capped at MAX_LAST_CALLS). */
     recordCall(tool: string, success: boolean): void;
-    /** Record a file path as modified during this session. */
     recordFile(path: string): void;
-    /** Record an error message (capped at MAX_ERRORS). */
     recordError(msg: string): void;
-    /**
-     * Returns true when a checkpoint should be written:
-     * policy is enabled, callCount > 0, and callCount is a multiple of threshold.
-     */
     shouldCheckpoint(): boolean;
-    /** Return a compact snapshot of the current session state. */
     getSnapshot(): AutoSessionSnapshot;
-    /** Update the checkpoint policy (partial update — unspecified fields keep current values). */
     setPolicy(p: Partial<AutoCheckpointPolicy>): void;
-    /** Return the current checkpoint policy. */
     getPolicy(): AutoCheckpointPolicy;
-    /** Reset the tracker state (useful for testing). */
     reset(): void;
 }
-/** Singleton session tracker — one per process. */
-export declare const sessionTracker: SessionTracker;
-export {};
+export declare function getSessionTracker(projectPath: string): SessionTracker;
+export declare function setCheckpointPolicy(p: Partial<AutoCheckpointPolicy>): void;
+export declare function getCheckpointPolicy(): AutoCheckpointPolicy;
+export declare function resetSessionTrackers(): void;
 //# sourceMappingURL=session-tracker.d.ts.map