@planu/cli 5.0.0 → 5.2.0

package/CHANGELOG.md

@@ -1,3 +1,78 @@
+## [5.2.0] - 2026-08-04
+
+### Features
+- feat(autopilot): refresh semantic index fire-and-forget on spec:created (SPEC-1345)
+- feat(i18n): auto-detect and persist user locale (SPEC-1347)
+- feat(spec-language): offer translation instead of rejecting non-English specs (SPEC-1342)
+- feat(semantic-search): persist index with incremental updates (SPEC-1345)
+
+### Bug Fixes
+- fix(storage): classify non-ENOENT failures in sync global-config read
+- fix(status): prefer implementing work over review work in compact status (SPEC-1228)
+- fix(challenge): stop handler names activating event scenarios across clauses (SPEC-1262)
+
+### Performance
+- perf(core-bridge): route main-thread hot paths through native dispatch (SPEC-1344)
+- perf(init-project): parallelize independent pipeline stages (SPEC-1343)
+
+### Chores
+- chore(website): regenerate deterministic product proof
+- chore(planu): close lifecycle for 8 specs done + SPEC-1368 bug spec + session checkpoint
+- chore(planu): file SPEC-1367 dogfood bug spec (validate false-negative on test-only criteria)
+- chore(planu): file SPEC-1366 dogfood bug spec and refresh session context
+- chore(doctor): remove commercial remnants and deepen diagnostics (SPEC-1346)
+- chore(planu): file SPEC-1365 dogfood bug spec (teamSuggestion recommends unregistered tools)
+- chore(planu): session checkpoint after v5.1.1 release
+
+
+## [5.1.1] - 2026-08-04
+
+### Bug Fixes
+- fix(release-harness): resolve published artifact from staged repack when publish has no tarball argv
+- fix(release): stop CLI-guard stdout pollution, npm view array probe, and tarball-path publish leak
+
+
+## [5.1.0] - 2026-08-04
+
+### Features
+- feat(lifecycle): automate done evidence pipeline end to end
+
+### Bug Fixes
+- fix(update-status): make typed failure explicit at dod-gates catch sites
+- fix(deps): patch hono, fast-uri, ip-address, and undici advisories via overrides
+- fix(evidence-gates): derive contract example kinds from filenames
+- fix(reverse-engineer): share walk-ignore list and add fast release-gate test lane
+- fix(challenge): suppress ungrounded concurrency boilerplate in challenge_spec
+- fix(update-status): report per-spec failure reasons in batch results
+- fix(create-spec): guarantee spec.md write before reporting persisted
+- fix(create-spec): release idempotency claim when create_spec fails before commit
+- fix(release): accept npm 12 pack metadata
+- fix(deps): patch transitive security advisories
+- fix(privacy): redact minimality policy locators
+- fix(lifecycle): route review evidence by target
+- fix(readiness): unify canonical validation evidence
+
+### Chores
+- chore(pnpm): disable modules purge confirmation for non-TTY automation
+- chore(planu): session checkpoint before release
+- chore(planu): close SPEC-1350 lifecycle state
+- chore(planu): hand off freshness blocker
+- chore(planu): checkpoint release handoff
+- chore(planu): preserve native engine review state
+- chore(planu): persist delayed challenge evidence
+- chore(planu): recover delayed audit specs
+- chore(planu): capture lifecycle dogfood failures
+- chore(planu): persist release remediation handoffs
+- chore(planu): approve final release blockers
+- chore(planu): start dependency security remediation
+- chore(planu): approve final security remediation
+- chore(planu): checkpoint final release remediations
+- chore(planu): start lifecycle routing implementation
+- chore(planu): approve lifecycle routing remediation
+- chore(planu): checkpoint release remediation specs
+- chore(planu): track v5 release dogfood regressions
+
+
 ## [5.0.0] - 2026-07-31
 
 ### Breaking Changes
@@ -4508,4 +4583,4 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 - Mermaid diagram generation (architecture, sequence, state machine, ER, data flow)
 - Multi-language i18n (EN/ES/PT) for generated specs
 - Clean Architecture (hexagonal) — engine, tools, storage, types layers
-- 10,857 tests with ≥95% coverage
+- 10,857 tests with ≥95% coverage

package/dist/cli/commands/doctor.d.ts

@@ -10,7 +10,29 @@ interface ToolCheck {
     paths: string[];
     format: 'standard' | 'zed';
 }
+interface DeepCheckResult {
+    name: string;
+    /** 'warn' is a degraded-but-working state (e.g. TS fallback active); 'fail' blocks usage. */
+    status: 'ok' | 'warn' | 'fail';
+    detail: string;
+}
 declare function checkTool(check: ToolCheck): ToolReport[];
+/** Check (1): the running Node version satisfies the `engines.node` field in package.json. */
+declare function checkNodeVersion(): DeepCheckResult;
+/**
+ * Check (2): the native Rust module loads, with a remediation hint when it doesn't.
+ * Missing native is a supported degraded mode (TypeScript fallback stays correct), so
+ * this reports 'warn' rather than 'fail' — it never blocks `planu doctor`'s exit code.
+ */
+declare function checkNativeModule(): DeepCheckResult;
+/** Check (3): PLANU_HOME / the resolved data directory is writable. */
+declare function checkDataDirWritable(): DeepCheckResult;
+/** Check (4): the runtime SQLite database opens without corruption. */
+declare function checkRuntimeDatabase(): DeepCheckResult;
+/** Check (5): the active locale resolves to a real translated message. */
+declare function checkLocaleResolution(): DeepCheckResult;
+declare function runDeepChecks(): DeepCheckResult[];
+export { checkNodeVersion, checkNativeModule, checkDataDirWritable, checkRuntimeDatabase, checkLocaleResolution, runDeepChecks, };
 export { checkTool };
 export declare const doctorCommand: CliCommand;
 //# sourceMappingURL=doctor.d.ts.map

package/dist/cli/commands/doctor.js

@@ -1,9 +1,16 @@
 // cli/commands/doctor.ts — planu doctor: verify MCP installations health (SPEC-236)
-import { existsSync } from 'node:fs';
+// Deep diagnostics (Node version, native engine, storage writability, runtime DB,
+// locale resolution) added by SPEC-1346 / SPEC-1344.
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { bold, cyan, green, yellow, red, dim } from '../colors.js';
 import { readJsonFile, hasPlanuEntry } from './install.js';
+import { resolveStorageLayout } from '../../storage/storage-layout.js';
+import { RuntimeDatabase } from '../../storage/runtime-db.js';
+import { probeNativeLoad } from '../../engine/core-bridge.js';
+import { getLocale, t } from '../../i18n/index.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -86,6 +93,166 @@ function checkTool(check) {
     }
     return reports;
 }
+// ---------------------------------------------------------------------------
+// Deep diagnostics (SPEC-1346 / SPEC-1344)
+// ---------------------------------------------------------------------------
+/** Root of the package, resolved relative to this module so it works from src/ and dist/. */
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '../../../package.json');
+function parseVersionTuple(version) {
+    const match = /(\d+)\.(\d+)\.(\d+)/.exec(version);
+    return [Number(match?.[1] ?? 0), Number(match?.[2] ?? 0), Number(match?.[3] ?? 0)];
+}
+function isVersionAtLeast(actual, required) {
+    for (let i = 0; i < 3; i++) {
+        const a = actual[i] ?? 0;
+        const r = required[i] ?? 0;
+        if (a !== r) {
+            return a > r;
+        }
+    }
+    return true;
+}
+/** Check (1): the running Node version satisfies the `engines.node` field in package.json. */
+function checkNodeVersion() {
+    let requiredRange;
+    try {
+        const pkg = JSON.parse(readFileSync(PACKAGE_ROOT, 'utf-8'));
+        requiredRange = pkg.engines?.node ?? '';
+    }
+    catch {
+        return {
+            name: 'Node version',
+            status: 'fail',
+            detail: 'Could not read package.json engines field',
+        };
+    }
+    if (!requiredRange) {
+        return { name: 'Node version', status: 'ok', detail: `Running Node ${process.version}` };
+    }
+    const required = parseVersionTuple(requiredRange);
+    const actual = parseVersionTuple(process.version);
+    if (isVersionAtLeast(actual, required)) {
+        return {
+            name: 'Node version',
+            status: 'ok',
+            detail: `${process.version} satisfies ${requiredRange}`,
+        };
+    }
+    return {
+        name: 'Node version',
+        status: 'fail',
+        detail: `${process.version} does not satisfy required range ${requiredRange}. Upgrade Node to continue.`,
+    };
+}
+/**
+ * Check (2): the native Rust module loads, with a remediation hint when it doesn't.
+ * Missing native is a supported degraded mode (TypeScript fallback stays correct), so
+ * this reports 'warn' rather than 'fail' — it never blocks `planu doctor`'s exit code.
+ */
+function checkNativeModule() {
+    if (process.env.DISABLE_NATIVE_CORE === '1') {
+        return {
+            name: 'Native engine',
+            status: 'ok',
+            detail: 'Disabled via DISABLE_NATIVE_CORE=1 (TypeScript fallback in use)',
+        };
+    }
+    const diagnostic = probeNativeLoad();
+    if (diagnostic.loaded) {
+        return { name: 'Native engine', status: 'ok', detail: `Loaded (${diagnostic.loaded})` };
+    }
+    const reason = diagnostic.errors[0] ?? 'unknown failure';
+    return {
+        name: 'Native engine',
+        status: 'warn',
+        detail: `Failed to load (${reason}). Running on the TypeScript fallback. Reinstall the platform package for your OS/arch to restore native acceleration.`,
+    };
+}
+/** Check (3): PLANU_HOME / the resolved data directory is writable. */
+function checkDataDirWritable() {
+    const layout = resolveStorageLayout();
+    const probePath = join(layout.data, `.doctor-write-probe-${String(process.pid)}`);
+    try {
+        mkdirSync(layout.data, { recursive: true, mode: 0o700 });
+        writeFileSync(probePath, 'ok', { mode: 0o600 });
+        unlinkSync(probePath);
+        return { name: 'Data directory', status: 'ok', detail: `Writable: ${layout.data}` };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: 'Data directory',
+            status: 'fail',
+            detail: `Cannot write to ${layout.data} (${message}). Check ownership/permissions on that path or set PLANU_HOME to a writable location.`,
+        };
+    }
+}
+/** Check (4): the runtime SQLite database opens without corruption. */
+function checkRuntimeDatabase() {
+    const layout = resolveStorageLayout();
+    try {
+        const db = new RuntimeDatabase({ path: layout.runtimeDatabase });
+        db.close();
+        return {
+            name: 'Runtime database',
+            status: 'ok',
+            detail: `Opens correctly: ${layout.runtimeDatabase}`,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            name: 'Runtime database',
+            status: 'fail',
+            detail: `Cannot open ${layout.runtimeDatabase} (${message}). Move or delete the corrupted file and retry — Planu recreates it on next use.`,
+        };
+    }
+}
+/** Check (5): the active locale resolves to a real translated message. */
+function checkLocaleResolution() {
+    const locale = getLocale();
+    const sample = t('locale.changed', locale);
+    if (sample === 'locale.changed') {
+        return {
+            name: 'Locale resolution',
+            status: 'fail',
+            detail: `Locale "${locale}" resolved but message bundle failed to load. Reinstall Planu to restore i18n/messages/.`,
+        };
+    }
+    return { name: 'Locale resolution', status: 'ok', detail: `Resolved locale: ${locale}` };
+}
+function runDeepChecks() {
+    return [
+        checkNodeVersion(),
+        checkNativeModule(),
+        checkDataDirWritable(),
+        checkRuntimeDatabase(),
+        checkLocaleResolution(),
+    ];
+}
+function deepCheckIcon(status) {
+    if (status === 'ok') {
+        return green('+');
+    }
+    return status === 'warn' ? yellow('!') : red('x');
+}
+function deepCheckLabel(status) {
+    if (status === 'ok') {
+        return green('OK');
+    }
+    return status === 'warn' ? yellow('DEGRADED') : red('FAIL');
+}
+function printDeepChecks(results) {
+    process.stdout.write(`\n${bold('Deep diagnostics')}\n\n`);
+    for (const result of results) {
+        const icon = deepCheckIcon(result.status);
+        const label = deepCheckLabel(result.status);
+        process.stdout.write(`  [${icon}] ${result.name.padEnd(18)} ${label}\n`);
+        process.stdout.write(`       ${dim(result.detail)}\n`);
+    }
+}
+// Exported for tests
+export { checkNodeVersion, checkNativeModule, checkDataDirWritable, checkRuntimeDatabase, checkLocaleResolution, runDeepChecks, };
 function statusIcon(status) {
     switch (status) {
         case 'ok':
@@ -143,9 +310,16 @@ export const doctorCommand = {
             }
         }
         printReports(allReports);
+        const deepChecks = runDeepChecks();
+        printDeepChecks(deepChecks);
         const installed = allReports.filter((r) => r.status === 'ok').length;
         const invalid = allReports.filter((r) => r.status === 'invalid-config').length;
+        const failedDeepChecks = deepChecks.filter((c) => c.status === 'fail').length;
         process.stdout.write('\n');
+        if (failedDeepChecks > 0) {
+            process.stdout.write(`${red('Warning:')} ${String(failedDeepChecks)} deep diagnostic check(s) failed. See remediation steps above.\n`);
+            process.exitCode = 1;
+        }
         if (invalid > 0) {
             process.stdout.write(`${yellow('Warning:')} ${String(invalid)} config file(s) have invalid JSON. Run ${cyan('planu install')} to fix.\n`);
         }

package/dist/cli/commands/spec.js

@@ -30,13 +30,14 @@ function printSpecSubcommandHelp() {
         `  ${'list'.padEnd(10)} ${dim('List specs [--status draft|approved|done...]')}`,
         `  ${'show'.padEnd(10)} ${dim('Show spec details (SPEC-NNN)')}`,
         `  ${'status'.padEnd(10)} ${dim('Update spec status (SPEC-NNN <status>)')}`,
+        `  ${''.padEnd(10)} ${dim('Batch targets: draft|review|approved|implementing|discarded')}`,
         `  ${'validate'.padEnd(10)} ${dim('Validate a spec against its codebase')}`,
         '',
         cyan('Examples:'),
         `  planu spec create "Add login flow"`,
         `  planu spec list --status approved`,
         `  planu spec show SPEC-001`,
-        `  planu spec status SPEC-001 done`,
+        `  planu spec status SPEC-001 done --implementation-review-digest sha256:<64-hex>`,
         `  planu spec validate SPEC-001`,
     ];
     process.stdout.write(lines.join('\n') + '\n');
@@ -207,6 +208,7 @@ async function runShow(args, flags) {
 // ---------------------------------------------------------------------------
 // Subcommand: spec status
 // ---------------------------------------------------------------------------
+// eslint-disable-next-line complexity -- batch done requires an explicit pre-resolution fail-closed branch
 async function runStatus(args, flags) {
     const { positionals, values } = parseArgs({
         args,
@@ -215,6 +217,7 @@ async function runStatus(args, flags) {
             notes: { type: 'string', short: 'n' },
             batch: { type: 'boolean' },
             set: { type: 'string', short: 's' },
+            'implementation-review-digest': { type: 'string' },
         },
         strict: false,
         allowPositionals: true,
@@ -232,6 +235,11 @@ async function runStatus(args, flags) {
         process.exitCode = 1;
         return;
     }
+    if (batch && status === 'done') {
+        process.stderr.write(`${red('BATCH_DONE_UNSUPPORTED:')} Close specs individually with update_status(done) and full implementation review evidence.\n`);
+        process.exitCode = 1;
+        return;
+    }
     const projectId = values['project-id'] ?? detectProjectId();
     if (batch) {
         const result = await handleUpdateStatusBatch({
@@ -253,6 +261,7 @@ async function runStatus(args, flags) {
         projectId,
         status: status,
         reviewNotes: values.notes ?? undefined,
+        implementationReviewDigest: values['implementation-review-digest'] ?? undefined,
     });
     if (result.isError) {
         process.stderr.write(`${red(formatToolResult(result, flags))}\n`);

package/dist/core/spec-validator.js

@@ -6,6 +6,8 @@ import { readFile } from 'node:fs/promises';
 import { checkSpecReadiness } from '../engine/readiness-checker.js';
 import { scoreSpecQuality } from '../engine/spec-quality-scorer.js';
 import { parseFrontmatter, stripFrontmatter } from '../engine/frontmatter-parser.js';
+import { extractNormalizedAcceptanceCriteria } from '../engine/spec-format/acceptance-criteria.js';
+import { parseFrontmatterScenarios } from '../engine/validator/spec-compliance-runner.js';
 // ── Required frontmatter fields ──────────────────────────────────────────────
 const REQUIRED_FRONTMATTER_FIELDS = ['id', 'title', 'status', 'type', 'target', 'scope'];
 // ── Required body sections (SPEC-785 aligned with lean-spec-generator output) ─
@@ -133,6 +135,20 @@ function mapQualityToValidation(dimensions) {
     }
     return warnings;
 }
+function countCanonicalBddScenarios(raw) {
+    const criteria = extractNormalizedAcceptanceCriteria(raw, { allowLegacyBodyFallback: false });
+    const bodyCriteria = criteria.filter((criterion) => criterion.source === 'body');
+    const bddCandidates = bodyCriteria.length > 0
+        ? bodyCriteria.map((criterion) => criterion.text)
+        : parseFrontmatterScenarios(raw).map((scenario) => scenario.steps?.map((step) => `${step.keyword} ${step.text}`).join(' ') ??
+            scenario.title);
+    return {
+        criteriaCount: criteria.length,
+        bddScenarioCount: bddCandidates.filter((criterion) => /\b(?:given|dado)\b/i.test(criterion) &&
+            /\b(?:when|cuando)\b/i.test(criterion) &&
+            /\b(?:then|entonces)\b/i.test(criterion)).length,
+    };
+}
 // ── Public API ───────────────────────────────────────────────────────────────
 /**
  * Validate a spec's format against the unified spec.md schema (SPEC-630).
@@ -168,22 +184,16 @@ export async function validateSpecFormat(spec, opts) {
     allWarnings.push(...unifiedResult.warnings);
     // ── 4. Readiness check ───────────────────────────────────────────────────
     let readinessScore = 0;
-    let bddScenarioCount = 0;
-    let criteriaCount = 0;
+    let readinessReport;
+    // The canonical metrics are independent from the readiness checker. Keep
+    // them truthful even when that best-effort checker throws.
+    const { criteriaCount, bddScenarioCount } = countCanonicalBddScenarios(raw);
     try {
         // Cast to Spec since checkSpecReadiness needs the full type but only reads
         // the fields available on the Pick type we receive.
-        const report = await checkSpecReadiness(spec, readinessMode);
-        readinessScore = report.score;
-        // Count scenarios from frontmatter block
-        bddScenarioCount = (raw.match(/^\s+-\s+title:/gm) ?? []).length;
-        // Count criteria lines (checkbox or GIVEN/WHEN/THEN)
-        const bodyLines = body.split('\n');
-        criteriaCount = bodyLines.filter((l) => /^- \[[ x]\]/i.test(l.trim()) || /^- .*\bgiven\b.*\bwhen\b.*\bthen\b/i.test(l.trim())).length;
-        if (criteriaCount === 0) {
-            criteriaCount = bddScenarioCount;
-        }
-        const mapped = mapReadinessToValidation(report.issues.blockers, report.issues.warnings);
+        readinessReport = await checkSpecReadiness(spec, readinessMode);
+        readinessScore = readinessReport.score;
+        const mapped = mapReadinessToValidation(readinessReport.issues.blockers, readinessReport.issues.warnings);
         allErrors.push(...mapped.errors);
         allWarnings.push(...mapped.warnings);
     }
@@ -197,11 +207,12 @@ export async function validateSpecFormat(spec, opts) {
         return { valid, errors: allErrors, warnings: allWarnings };
     }
     // ── 5. Quality scoring ───────────────────────────────────────────────────
-    let qualityScore = 0;
-    let qualityGrade = 'F';
+    let qualityScore;
+    let qualityGrade;
+    let qualityReport;
     if (!skipQuality) {
         try {
-            const qualityReport = await scoreSpecQuality(spec);
+            qualityReport = await scoreSpecQuality(spec);
             qualityScore = qualityReport.score.total;
             qualityGrade = qualityReport.score.grade;
             const qualityWarnings = mapQualityToValidation(qualityReport.dimensions);
@@ -226,11 +237,14 @@ export async function validateSpecFormat(spec, opts) {
         warnings: allWarnings,
         metrics: {
             readinessScore,
-            qualityScore,
-            qualityGrade,
             bddScenarioCount,
             criteriaCount,
+            ...(qualityScore === undefined || qualityGrade === undefined
+                ? {}
+                : { qualityScore, qualityGrade }),
         },
+        readinessReport,
+        qualityReport,
     };
 }
 //# sourceMappingURL=spec-validator.js.map

package/dist/engine/autopilot/bootstrap.js

@@ -99,6 +99,31 @@ function registerPluginInstalledListener() {
         })();
     });
 }
+/**
+ * SPEC-1345 AC4: Fire-and-forget semantic index refresh on spec:created.
+ * Reconciles the persisted TF-IDF index against the current corpus so the next
+ * semantic_search call hits a warm, up-to-date index.
+ */
+function registerSemanticIndexRefreshListener() {
+    onAutopilotEvent('spec:created', (event) => {
+        void (async () => {
+            try {
+                const { getOrCreateBackend } = await import('../../storage/vector-store/backend-factory.js');
+                const { SemanticIndexStore } = await import('../../storage/semantic-index-store.js');
+                const backend = await getOrCreateBackend(event.projectId);
+                const allDocs = await backend.getAll();
+                if (allDocs.length === 0) {
+                    return;
+                }
+                const indexStore = new SemanticIndexStore(event.projectId, 'all');
+                await indexStore.loadOrBuild(allDocs.map((doc) => ({ id: doc.id, content: doc.content })));
+            }
+            catch {
+                /* best-effort — never surface to user */
+            }
+        })();
+    });
+}
 const AUTOPILOT_EVENTS = [
     'spec:created',
     'spec:status:approved',
@@ -133,5 +158,7 @@ export function bootstrapAutopilotHandlers() {
     registerPluginInstalledListener();
     // SPEC-628: Register daily cron for auto_fix_health (moved from update_status cascade)
     registerDailyCronListener();
+    // SPEC-1345 AC4: Register semantic index refresh on spec:created
+    registerSemanticIndexRefreshListener();
 }
 //# sourceMappingURL=bootstrap.js.map

package/dist/engine/core-bridge.d.ts

@@ -31,6 +31,34 @@ export declare function fastExtractTsRelations(rootPath: string, paths: string[]
 export declare function fastQueryAffectedNodes(seed: string, edges: GraphEdgeInputRs[], relationFilter: string[], policy: ProjectGraphLimitsPolicyRs, overrides?: Partial<ResolvedProjectGraphLimitsRs>): AffectedNodeRs[];
 export declare function fastQueryShortestPath(from: string, to: string, edges: GraphEdgeInputRs[], relationFilter: string[], policy: ProjectGraphLimitsPolicyRs, overrides?: Partial<ResolvedProjectGraphLimitsRs>): ShortestPathResultRs;
 export declare function fastSelectCompactGraphSlice(seeds: string[], nodes: GraphNodeInputRs[], edges: GraphEdgeInputRs[], policy: ProjectGraphLimitsPolicyRs, overrides?: Partial<ResolvedProjectGraphLimitsRs>): CompactGraphSliceRs;
+/** Worker-dispatched variant of {@link fastDetectDriftParallel} for main-thread callers. */
+export declare function fastDetectDriftParallelAsync(rootPath: string, keywords: string[]): Promise<{
+    value: DriftResult;
+    degradationNotice?: string;
+}>;
+/** Worker-dispatched variant of {@link fastScanAndHashFiles} for main-thread callers. */
+export declare function fastScanAndHashFilesAsync(rootPath: string): Promise<{
+    value: FileHash[];
+    degradationNotice?: string;
+}>;
+/** Worker-dispatched variant of {@link fastScanProjectMetadata} for main-thread callers. */
+export declare function fastScanProjectMetadataAsync(rootPath: string): Promise<{
+    value: FileMetadata[];
+    degradationNotice?: string;
+}>;
+/** Worker-dispatched variant of {@link fastScanSpecs} for main-thread callers. */
+export declare function fastScanSpecsAsync(rootPath: string): Promise<{
+    value: SpecBriefRs[] | null;
+    degradationNotice?: string;
+}>;
 export declare const isNativeActive: () => boolean;
 export declare const nativeLoadDiagnostic: () => NativeLoadDiagnostic;
+/**
+ * Force a native load attempt regardless of the calling thread and return the
+ * resulting diagnostic. `nativeLoadDiagnostic()` alone only reports load state
+ * that some other main-thread-bypassing caller already triggered (e.g. the
+ * macOS Keychain port); this is the main-thread-safe way to actually probe
+ * native availability, used by `planu doctor`.
+ */
+export declare const probeNativeLoad: () => NativeLoadDiagnostic;
 //# sourceMappingURL=core-bridge.d.ts.map

package/dist/engine/core-bridge.js

@@ -12,6 +12,7 @@ import { detectMusl } from './native-platform.js';
 import { findDuplicateBlocks } from './core-bridge-duplicate-blocks.js';
 import { appendGapEntry, verifyGapsChain } from './core-bridge-gaps.js';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
+import { runNativeWorkerOperation } from './execution/native-worker-runtime.js';
 export { negotiateNativeRuntime, NATIVE_CAPABILITY_ABI, NATIVE_NODE_API_ABI, NATIVE_PROTOCOL_ABI, RUNTIME_STORAGE_SCHEMA, };
 const require = createRequire(import.meta.url);
 const reportedDegradations = new Set();
@@ -678,9 +679,75 @@ export function fastSelectCompactGraphSlice(seeds, nodes, edges, policy, overrid
     }
     return tsSelectCompactGraphSlice(seeds, nodes, edges, limits);
 }
+// Main-thread dispatch strategy (SPEC-1344) -----------------------------------
+// getNative() deliberately returns null on the main thread so long native FFI
+// calls never block the event loop (see comment above getNative()). For hot
+// paths that need acceleration anyway, dispatchViaWorker() moves the call onto
+// the existing native-worker-dispatch.ts runtime (a worker thread, where
+// isMainThread is false and native loads normally). If the worker fails to
+// spawn, times out, or the operation isn't allowlisted, it falls back to the
+// caller-supplied synchronous implementation so behavior never regresses.
+const WORKER_DISPATCH_TIMEOUT_MS = 30_000;
+const DEGRADATION_NOTICE_THRESHOLD_MS = 2_000;
+async function dispatchViaWorker(operation, payload, projectId, syncFallback) {
+    const start = Date.now();
+    if (isMainThread && process.env.DISABLE_NATIVE_CORE !== '1') {
+        try {
+            const value = (await runNativeWorkerOperation({
+                operation,
+                payload,
+                projectId,
+                deadlineAt: start + WORKER_DISPATCH_TIMEOUT_MS,
+            }));
+            return { value };
+        }
+        catch (error) {
+            /* reliability-optional: NATIVE_WORKER_DISPATCH_FAILED — falls through to sync fallback */
+            reportOnce(`NATIVE_WORKER_DISPATCH_FAILED:${operation}`, () => {
+                reportClassifiedDegradation('NATIVE_WORKER_DISPATCH_FAILED', error instanceof Error ? error : FALLBACK_ERROR);
+            });
+        }
+    }
+    const value = syncFallback();
+    const elapsedMs = Date.now() - start;
+    if (elapsedMs > DEGRADATION_NOTICE_THRESHOLD_MS) {
+        return {
+            value,
+            degradationNotice: `native engine unavailable — run planu doctor (fallback took ${String(elapsedMs)}ms)`,
+        };
+    }
+    return { value };
+}
+/** Worker-dispatched variant of {@link fastDetectDriftParallel} for main-thread callers. */
+export async function fastDetectDriftParallelAsync(rootPath, keywords) {
+    return dispatchViaWorker('detect-drift', { rootPath, keywords }, fastHashProjectPath(rootPath), () => fastDetectDriftParallel(rootPath, keywords));
+}
+/** Worker-dispatched variant of {@link fastScanAndHashFiles} for main-thread callers. */
+export async function fastScanAndHashFilesAsync(rootPath) {
+    return dispatchViaWorker('scan-and-hash-files', { rootPath }, fastHashProjectPath(rootPath), () => fastScanAndHashFiles(rootPath));
+}
+/** Worker-dispatched variant of {@link fastScanProjectMetadata} for main-thread callers. */
+export async function fastScanProjectMetadataAsync(rootPath) {
+    return dispatchViaWorker('scan-project-metadata', { rootPath }, fastHashProjectPath(rootPath), () => fastScanProjectMetadata(rootPath));
+}
+/** Worker-dispatched variant of {@link fastScanSpecs} for main-thread callers. */
+export async function fastScanSpecsAsync(rootPath) {
+    return dispatchViaWorker('scan-specs', { rootPath }, fastHashProjectPath(rootPath), () => fastScanSpecs(rootPath));
+}
 export const isNativeActive = () => getNative() !== null;
 export const nativeLoadDiagnostic = () => {
     refreshNativeCapabilityDiagnostic();
     return loadDiagnostic;
 };
+/**
+ * Force a native load attempt regardless of the calling thread and return the
+ * resulting diagnostic. `nativeLoadDiagnostic()` alone only reports load state
+ * that some other main-thread-bypassing caller already triggered (e.g. the
+ * macOS Keychain port); this is the main-thread-safe way to actually probe
+ * native availability, used by `planu doctor`.
+ */
+export const probeNativeLoad = () => {
+    loadNative();
+    return nativeLoadDiagnostic();
+};
 //# sourceMappingURL=core-bridge.js.map