@planu/cli 5.7.5 → 5.7.6

package/dist/engine/evidence-index/index-builder.js

@@ -1,5 +1,5 @@
-import { stat } from 'node:fs/promises';
 import { isAbsolute, join, normalize } from 'node:path';
+import { pathExistsByStat as pathExists } from '../../core/shared/fs.js';
 import { createCriterionIdentity, criterionIdentitiesMatch } from '../criterion-identity.js';
 export function criterionKey(criterion) {
     return createCriterionIdentity(criterion).stableKey;
@@ -9,6 +9,10 @@ function truncateAtEvidenceMarker(value) {
     const markerIndex = value.search(EVIDENCE_MARKER);
     return markerIndex === -1 ? value : value.slice(0, markerIndex);
 }
+const LINE_CITATION_SUFFIX = /:\d+(?:-\d+)?$/;
+function pathForExistenceCheck(value) {
+    return value.replace(LINE_CITATION_SUFFIX, '');
+}
 export async function buildSpecEvidenceIndex(args) {
     const diagnostics = [...args.artifacts.invalidArtifacts];
     const matrixRows = args.artifacts.traceabilityMatrix?.rows ?? [];
@@ -129,12 +133,25 @@ async function pathRecord(kind, value, source, args, fieldName) {
     if (!args.projectPath) {
         return record(kind, value, 'missing', source, evidencePathReason(fieldName, 'projectPath unavailable'));
     }
-    const exists = await stat(safe.path)
-        .then(() => true)
-        .catch(() => false);
+    const literalExists = await pathExists(safe.path);
+    const exists = literalExists || (await fallbackExists(value, fieldName, args.projectPath));
     const missingReason = evidencePathReason(fieldName, `Missing path: ${value}`);
     return record(kind, value, exists ? 'valid' : missingPathStatus(fieldName), source, exists ? undefined : missingReason);
 }
+async function fallbackExists(value, fieldName, projectPath) {
+    if (fieldName === 'changedFiles') {
+        return false;
+    }
+    const strippedValue = pathForExistenceCheck(value);
+    if (strippedValue === value || strippedValue.length === 0) {
+        return false;
+    }
+    const strippedSafe = resolveSafeProjectPath(strippedValue, projectPath, fieldName);
+    if (!strippedSafe.ok) {
+        return false;
+    }
+    return pathExists(strippedSafe.path);
+}
 function missingPathStatus(fieldName) {
     return fieldName === 'changedFiles' ? 'missing' : 'stale';
 }

package/dist/engine/execution/job-runtime.js

@@ -249,7 +249,7 @@ function isQueueRelevant(job) {
         return true;
     }
     const kind = job.payload.kind;
-    return kind === undefined || kind === 'validate';
+    return kind === undefined || kind === 'validate' || kind === 'package-handoff';
 }
 function remainingBudgetMs(job, now = Date.now()) {
     const payload = job.payload && typeof job.payload === 'object'

package/dist/engine/execution/package-handoff-job-executor.d.ts

@@ -0,0 +1,22 @@
+import { DurableJobRuntime } from './job-runtime.js';
+import type { DurableJobRecord, PackageHandoffDurableJobPayload, PackageHandoffStageResult } from '../../types/durable-job.js';
+export declare function isPackageHandoffJob(value: unknown): boolean;
+export declare function parsePackageHandoffPayload(value: unknown): PackageHandoffDurableJobPayload | undefined;
+/** Bounds one stage with AbortSignal.timeout + Promise.race; the stage's own promise is orphaned on timeout. */
+export declare function runStageWithDeadline<T>(stage: string, budgetMs: number, fn: (signal: AbortSignal) => Promise<T>): Promise<PackageHandoffStageResult<T>>;
+/** Executes accepted package-handoff jobs directly against the packaging engine, never through MCP. */
+export declare class PackageHandoffJobExecutor {
+    private readonly runtime;
+    private readonly workerId;
+    constructor(runtime: DurableJobRuntime, workerId?: string);
+    runOnce(projectId: string, workspaceId?: string): Promise<readonly DurableJobRecord[]>;
+    runUntilIdle(projectId: string, workspaceId?: string): Promise<void>;
+    private candidates;
+    private execute;
+    private runJob;
+}
+/** Schedules background execution after the submit response can be flushed. */
+export declare function schedulePackageHandoffJobExecution(projectId: string, workspaceId?: string): void;
+/** Re-enqueues accepted/checkpointed package-handoff work discovered after a process restart. */
+export declare function recoverPackageHandoffJobsAtStartup(): void;
+//# sourceMappingURL=package-handoff-job-executor.d.ts.map

package/dist/engine/execution/package-handoff-job-executor.js

@@ -0,0 +1,490 @@
+// engine/execution/package-handoff-job-executor.ts — Durable executor for package_handoff (SPEC-1240)
+// Mirrors the validate-job-executor submit/claim/execute lifecycle, bounding every stage with
+// its own deadline so a slow readiness check, packager write, or enrichment stage can never hang
+// the MCP transport. Core stages fail the job classified; enrichment stages degrade and the job
+// still completes.
+/* eslint-disable max-lines -- stage deadlines, core/enrichment orchestration, and the durable executor lifecycle stay co-located for auditability */
+import { randomUUID } from 'node:crypto';
+import { DurableJobRuntime } from './job-runtime.js';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
+import { specStore, knowledgeStore } from '../../storage/index.js';
+import { checkSpecReadiness } from '../readiness-checker.js';
+import { packageHandoff } from '../handoff-packager.js';
+import { detectParadigms } from '../paradigm-detector.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
+import { appendTransitionEvent } from '../../storage/transition-log.js';
+import { formatHandoff, topItems, buildHandoffSummaryText, summarizeMinimality, summarizeTokenWaste, summarizeGraphContext, buildHandoffTokenWasteReport, buildGraphContextSection, buildMinimalImplementationReport, } from '../handoff-format.js';
+const WORKSPACE_ID = 'global';
+const CORE_BUDGET_DEFAULT_MS = 20_000;
+const ENRICHMENT_BUDGET_DEFAULT_MS = 8_000;
+const ENRICHMENT_STAGE_COUNT = 4;
+const LEASE_SAFETY_MARGIN_MS = 15_000;
+const activeScopes = new Map();
+export function isPackageHandoffJob(value) {
+    return Boolean(value && typeof value === 'object' && value.kind === 'package-handoff');
+}
+export function parsePackageHandoffPayload(value) {
+    if (!value || typeof value !== 'object') {
+        return undefined;
+    }
+    const candidate = value;
+    if (candidate.kind === 'package-handoff' &&
+        candidate.schemaVersion === 1 &&
+        typeof candidate.projectId === 'string' &&
+        typeof candidate.specId === 'string' &&
+        typeof candidate.specVersion === 'string') {
+        return candidate;
+    }
+    return undefined;
+}
+function envBudgetMs(variableName, defaultMs) {
+    const raw = process.env[variableName];
+    if (raw === undefined || raw.trim() === '') {
+        return defaultMs;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : defaultMs;
+}
+function coreBudgetMs() {
+    return envBudgetMs('PLANU_HANDOFF_CORE_BUDGET_MS', CORE_BUDGET_DEFAULT_MS);
+}
+function enrichmentBudgetMs() {
+    return envBudgetMs('PLANU_HANDOFF_ENRICHMENT_BUDGET_MS', ENRICHMENT_BUDGET_DEFAULT_MS);
+}
+/** Bounds one stage with AbortSignal.timeout + Promise.race; the stage's own promise is orphaned on timeout. */
+export async function runStageWithDeadline(stage, budgetMs, fn) {
+    const startedAt = Date.now();
+    if (budgetMs <= 0) {
+        return {
+            stage,
+            durationMs: 0,
+            outcome: {
+                ok: false,
+                timedOut: true,
+                error: new Error(`[Planu] stage "${stage}" had no remaining budget`),
+            },
+        };
+    }
+    const timeoutSignal = AbortSignal.timeout(budgetMs);
+    let timedOut = false;
+    const timeoutPromise = new Promise((_resolve, reject) => {
+        timeoutSignal.addEventListener('abort', () => {
+            timedOut = true;
+            reject(new Error(`[Planu] stage "${stage}" exceeded its ${String(budgetMs)}ms budget`));
+        }, { once: true });
+    });
+    try {
+        const value = await Promise.race([fn(timeoutSignal), timeoutPromise]);
+        return {
+            stage,
+            durationMs: Date.now() - startedAt,
+            outcome: { ok: true, value, timedOut: false },
+        };
+    }
+    catch (error) {
+        reportClassifiedDegradation('HANDOFF_STAGE_FAILURE', error);
+        return { stage, durationMs: Date.now() - startedAt, outcome: { ok: false, timedOut, error } };
+    }
+}
+class CoreStageFailure extends Error {
+    stage;
+    timedOut;
+    cause;
+    stageTimings;
+    constructor(stage, timedOut, cause, stageTimings) {
+        super(`[Planu] package-handoff core stage "${stage}" failed`);
+        this.stage = stage;
+        this.timedOut = timedOut;
+        this.cause = cause;
+        this.stageTimings = stageTimings;
+        this.name = 'CoreStageFailure';
+    }
+}
+function classifiedCoreFailureMessage(failure) {
+    const code = failure.timedOut ? 'HANDOFF_CORE_TIMEOUT' : 'HANDOFF_CORE_FAILURE';
+    const remediation = failure.timedOut
+        ? `The ${failure.stage} stage exceeded its budget. Increase PLANU_HANDOFF_CORE_BUDGET_MS or investigate why ${failure.stage} is slow, then retry with restart_job.`
+        : `The ${failure.stage} stage failed. Inspect the underlying cause, then retry with restart_job once fixed.`;
+    const cause = failure.cause instanceof Error ? failure.cause.message : String(failure.cause);
+    return (`[Planu] ${code} stage=${failure.stage} remediation=${remediation} cause=${cause} ` +
+        `stageTimings=${JSON.stringify(failure.stageTimings)}`);
+}
+function enrichmentDegradation(stage, timedOut) {
+    return {
+        stage,
+        code: timedOut ? 'HANDOFF_ENRICHMENT_TIMEOUT' : 'HANDOFF_ENRICHMENT_FAILURE',
+        remediation: timedOut
+            ? `The ${stage} enrichment stage exceeded its budget; the core handoff artifact is still valid. Increase PLANU_HANDOFF_ENRICHMENT_BUDGET_MS to include it next run.`
+            : `The ${stage} enrichment stage failed; the core handoff artifact is still valid. Re-run package_handoff once the underlying issue is fixed.`,
+    };
+}
+async function currentSpecVersion(projectId, specId, projectPath) {
+    const current = await specStore.getSpec(projectId, specId, projectPath);
+    return current?.spec_version;
+}
+async function runCoreStages(payload, spec, knowledge) {
+    const deadlineAt = Date.now() + coreBudgetMs();
+    const stageTimings = {};
+    const readinessResult = await runStageWithDeadline('readiness', Math.max(0, deadlineAt - Date.now()), () => checkSpecReadiness(spec, 'lenient'));
+    stageTimings.readiness = readinessResult.durationMs;
+    if (!readinessResult.outcome.ok) {
+        throw new CoreStageFailure('readiness', readinessResult.outcome.timedOut, readinessResult.outcome.error, stageTimings);
+    }
+    const packageCoreResult = await runStageWithDeadline('package-core', Math.max(0, deadlineAt - Date.now()), (signal) => packageHandoff(spec, knowledge, {
+        specVersion: payload.specVersion,
+        getCurrentSpecVersion: () => currentSpecVersion(payload.projectId, payload.specId, knowledge.projectPath),
+        signal,
+    }));
+    stageTimings['package-core'] = packageCoreResult.durationMs;
+    if (!packageCoreResult.outcome.ok) {
+        throw new CoreStageFailure('package-core', packageCoreResult.outcome.timedOut, packageCoreResult.outcome.error, stageTimings);
+    }
+    return {
+        readinessScore: readinessResult.outcome.value?.score ?? 0,
+        pkg: packageCoreResult.outcome.value,
+        stageTimings,
+    };
+}
+async function runParadigmStage(knowledge, constraints) {
+    if (!knowledge.projectPath) {
+        return { durationMs: 0, constraints, degradation: undefined };
+    }
+    const projectPath = knowledge.projectPath;
+    const paradigmResult = await runStageWithDeadline('paradigms', enrichmentBudgetMs(), () => detectParadigms(projectPath));
+    if (!paradigmResult.outcome.ok) {
+        return {
+            durationMs: paradigmResult.durationMs,
+            constraints,
+            degradation: enrichmentDegradation('paradigms', paradigmResult.outcome.timedOut),
+        };
+    }
+    const dominant = paradigmResult.outcome.value?.dominant;
+    if (!dominant || dominant.confidence < 0.5) {
+        return { durationMs: paradigmResult.durationMs, constraints, degradation: undefined };
+    }
+    return {
+        durationMs: paradigmResult.durationMs,
+        constraints: [
+            ...constraints,
+            {
+                type: 'interface',
+                description: `Follow ${dominant.name} paradigm patterns — dominant paradigm (confidence: ${(dominant.confidence * 100).toFixed(0)}%)`,
+                affectedItems: ['all new code'],
+            },
+        ],
+        degradation: undefined,
+    };
+}
+async function runGraphContextStage(payload, knowledge) {
+    const graphResult = await runStageWithDeadline('graph-context', enrichmentBudgetMs(), () => buildGraphContextSection({
+        projectId: payload.projectId,
+        projectPath: knowledge.projectPath,
+        specId: payload.specId,
+    }));
+    if (!graphResult.outcome.ok) {
+        return {
+            durationMs: graphResult.durationMs,
+            graphContext: null,
+            degradation: enrichmentDegradation('graph-context', graphResult.outcome.timedOut),
+        };
+    }
+    const graphContext = graphResult.outcome.value ?? null;
+    const unavailable = graphContext === null;
+    return {
+        durationMs: graphResult.durationMs,
+        graphContext,
+        degradation: unavailable
+            ? {
+                stage: 'graph-context',
+                code: 'HANDOFF_ENRICHMENT_FAILURE',
+                remediation: 'The project graph had no data for this spec — not a failure. Run configure_code_graph or index the project to include graph context in future handoffs.',
+            }
+            : undefined,
+    };
+}
+async function runEnrichmentStages(payload, spec, knowledge, pkgWithScore) {
+    const stageTimings = {};
+    const degradations = [];
+    const budgetMs = enrichmentBudgetMs();
+    const paradigmStage = await runParadigmStage(knowledge, pkgWithScore.constraints);
+    stageTimings.paradigms = paradigmStage.durationMs;
+    if (paradigmStage.degradation) {
+        degradations.push(paradigmStage.degradation);
+    }
+    const pkgWithConstraints = {
+        ...pkgWithScore,
+        constraints: paradigmStage.constraints,
+    };
+    const tokenWasteResult = await runStageWithDeadline('token-waste', budgetMs, () => buildHandoffTokenWasteReport(pkgWithConstraints, knowledge, spec));
+    stageTimings['token-waste'] = tokenWasteResult.durationMs;
+    const tokenWasteReport = tokenWasteResult.outcome.ok
+        ? (tokenWasteResult.outcome.value ?? null)
+        : null;
+    if (!tokenWasteResult.outcome.ok) {
+        degradations.push(enrichmentDegradation('token-waste', tokenWasteResult.outcome.timedOut));
+    }
+    const graphStage = await runGraphContextStage(payload, knowledge);
+    stageTimings['graph-context'] = graphStage.durationMs;
+    if (graphStage.degradation) {
+        degradations.push(graphStage.degradation);
+    }
+    const graphContext = graphStage.graphContext;
+    const baseHandoffText = graphContext !== null
+        ? `${formatHandoff(pkgWithConstraints)}\n${graphContext.text}`
+        : formatHandoff(pkgWithConstraints);
+    const minimalityResult = await runStageWithDeadline('minimality', budgetMs, () => buildMinimalImplementationReport(pkgWithConstraints, knowledge, spec, baseHandoffText));
+    stageTimings.minimality = minimalityResult.durationMs;
+    const minimalityReport = minimalityResult.outcome.ok
+        ? (minimalityResult.outcome.value ?? null)
+        : null;
+    if (!minimalityResult.outcome.ok) {
+        degradations.push(enrichmentDegradation('minimality', minimalityResult.outcome.timedOut));
+    }
+    return {
+        pkgWithConstraints,
+        graphContext,
+        minimalityBlocked: minimalityReport?.blocked ?? null,
+        minimalitySummary: summarizeMinimality(minimalityReport),
+        tokenWasteRiskCount: tokenWasteReport?.risks.length ?? null,
+        tokenWasteSummary: summarizeTokenWaste(tokenWasteReport),
+        stageTimings,
+        degradations,
+    };
+}
+function buildCompletionResult(args) {
+    const { specId, pkg, enrichment, stageTimings, degradations } = args;
+    const topBlockers = topItems(pkg.blockers, 3);
+    const ownershipBlockers = pkg.blockers.filter((blocker) => blocker.startsWith('handoff_ownership_invalid'));
+    const topRisks = topItems(pkg.risks, 5);
+    const graphSummary = enrichment.graphContext !== null
+        ? summarizeGraphContext(enrichment.graphContext.structured)
+        : undefined;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: buildHandoffSummaryText({
+                    pkg,
+                    topBlockers,
+                    topRisks,
+                    minimalityBlocked: enrichment.minimalityBlocked,
+                    tokenWasteRiskCount: enrichment.tokenWasteRiskCount,
+                }),
+            },
+        ],
+        structuredContent: {
+            resultSchema: 'package-handoff-completion/v1',
+            specId,
+            blocked: pkg.blocked,
+            readinessScore: pkg.readinessScore,
+            blockersCount: pkg.blockers.length,
+            blockersTop3: topBlockers,
+            ownershipBlockers,
+            risksTop5: topRisks,
+            criteriaTop5: topItems(pkg.criteria, 5),
+            constraintsTop5: topItems(pkg.constraints, 5),
+            warningsTop5: topItems(pkg.warnings, 5),
+            handoffPath: pkg.handoffPath,
+            contextHash: pkg.contextHash,
+            artifactRefs: { handoff: pkg.handoffPath },
+            counts: {
+                criteria: pkg.criteria.length,
+                filesToModify: pkg.filesToModify.length,
+                filesToCreate: pkg.filesToCreate.length,
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- compat guard: callers may construct a HandoffPackage object predating this field
+                filesToTest: (pkg.filesToTest ?? []).length,
+                ownership: pkg.ownership.length,
+                testPlan: pkg.testPlan.length,
+                risks: pkg.risks.length,
+                constraints: pkg.constraints.length,
+                warnings: pkg.warnings.length,
+                outOfScope: pkg.outOfScope.length,
+            },
+            nextAction: pkg.nextAction,
+            ...(enrichment.minimalitySummary !== undefined
+                ? { minimality: enrichment.minimalitySummary }
+                : {}),
+            ...(enrichment.tokenWasteSummary !== undefined
+                ? { tokenWaste: enrichment.tokenWasteSummary }
+                : {}),
+            ...(graphSummary !== undefined ? { graphContext: graphSummary } : {}),
+            stageTimings,
+            degradations,
+        },
+    };
+}
+/** Executes accepted package-handoff jobs directly against the packaging engine, never through MCP. */
+export class PackageHandoffJobExecutor {
+    runtime;
+    workerId;
+    constructor(runtime, workerId = `handoff-${randomUUID()}`) {
+        this.runtime = runtime;
+        this.workerId = workerId;
+    }
+    async runOnce(projectId, workspaceId = WORKSPACE_ID) {
+        const candidates = this.candidates(projectId, workspaceId);
+        return Promise.all(candidates.map((job) => this.execute(job)));
+    }
+    async runUntilIdle(projectId, workspaceId = WORKSPACE_ID) {
+        for (;;) {
+            const candidates = this.candidates(projectId, workspaceId);
+            if (candidates.length === 0) {
+                return;
+            }
+            await Promise.all(candidates.map((job) => this.execute(job).catch((error) => {
+                reportClassifiedDegradation('HANDOFF_JOB_EXECUTION_FAILURE', error);
+            })));
+        }
+    }
+    candidates(projectId, workspaceId) {
+        return this.runtime
+            .list(projectId, workspaceId)
+            .filter((job) => (job.state === 'accepted' || job.state === 'checkpointed') &&
+            isPackageHandoffJob(job.payload));
+    }
+    async execute(job) {
+        const identity = {
+            operationId: job.id,
+            projectId: job.projectId,
+            workspaceId: job.workspaceId,
+        };
+        const leaseMs = coreBudgetMs() + enrichmentBudgetMs() * ENRICHMENT_STAGE_COUNT + LEASE_SAFETY_MARGIN_MS;
+        const claimed = this.runtime.claim({ ...identity, workerId: this.workerId, leaseMs });
+        if (!claimed) {
+            return this.runtime.get(identity);
+        }
+        const payload = parsePackageHandoffPayload(claimed.payload);
+        if (!payload) {
+            return this.runtime.fail({
+                ...identity,
+                workerId: this.workerId,
+                fencingToken: claimed.fencingToken,
+                error: '[Planu] Invalid package-handoff job payload',
+            });
+        }
+        try {
+            const result = await this.runJob(payload);
+            const completed = this.runtime.complete({
+                ...identity,
+                workerId: this.workerId,
+                fencingToken: claimed.fencingToken,
+                result,
+            });
+            const structured = result.structuredContent;
+            try {
+                await appendTransitionEvent({
+                    projectId: payload.projectId,
+                    specId: payload.specId,
+                    eventType: 'handoff.intake',
+                    gateResults: { handoff: structured?.blocked === true ? 'fail' : 'pass' },
+                    meta: {
+                        handoffPath: structured?.handoffPath,
+                        contextHash: structured?.contextHash,
+                        blockers: structured?.blockersTop3 ?? [],
+                    },
+                });
+            }
+            catch (error) {
+                reportClassifiedDegradation('HANDOFF_INTAKE_EVENT_FAILURE', error);
+            }
+            return completed;
+        }
+        catch (error) {
+            if (error instanceof CoreStageFailure) {
+                return this.runtime.fail({
+                    ...identity,
+                    workerId: this.workerId,
+                    fencingToken: claimed.fencingToken,
+                    error: classifiedCoreFailureMessage(error),
+                });
+            }
+            reportClassifiedDegradation('HANDOFF_JOB_EXECUTION_FAILURE', error);
+            return this.runtime.fail({
+                ...identity,
+                workerId: this.workerId,
+                fencingToken: claimed.fencingToken,
+                error: (error instanceof Error ? error.message : String(error)).slice(0, 4_096),
+            });
+        }
+    }
+    async runJob(payload) {
+        const spec = await specStore.getSpec(payload.projectId, payload.specId);
+        if (!spec) {
+            throw new Error(`[Planu] Spec '${payload.specId}' not found in project '${payload.projectId}'`);
+        }
+        const knowledge = await knowledgeStore.getKnowledge(payload.projectId);
+        if (!knowledge) {
+            throw new Error(`[Planu] Project '${payload.projectId}' not found. Run init_project first.`);
+        }
+        const core = await runCoreStages(payload, spec, knowledge);
+        const pkgWithScore = { ...core.pkg, readinessScore: core.readinessScore };
+        const publishDegradation = core.pkg.staleVersionSkipped === true
+            ? {
+                stage: 'artifact-publish',
+                code: 'HANDOFF_STALE_VERSION_SKIPPED',
+                remediation: 'The spec advanced to a newer spec_version before this job published its artifact; the newer artifact was preserved untouched. Re-run package_handoff to publish the current version.',
+            }
+            : undefined;
+        const enrichment = await runEnrichmentStages(payload, spec, knowledge, pkgWithScore);
+        return buildCompletionResult({
+            specId: payload.specId,
+            pkg: enrichment.pkgWithConstraints,
+            enrichment,
+            stageTimings: { ...core.stageTimings, ...enrichment.stageTimings },
+            degradations: publishDegradation
+                ? [publishDegradation, ...enrichment.degradations]
+                : [...enrichment.degradations],
+        });
+    }
+}
+/** Schedules background execution after the submit response can be flushed. */
+export function schedulePackageHandoffJobExecution(projectId, workspaceId = WORKSPACE_ID) {
+    const scope = `${projectId}:${workspaceId}`;
+    const active = activeScopes.get(scope);
+    if (active) {
+        active.rescheduleRequested = true;
+        return;
+    }
+    const state = { rescheduleRequested: false };
+    activeScopes.set(scope, state);
+    setImmediate(() => {
+        const runtime = new DurableJobRuntime();
+        const executor = new PackageHandoffJobExecutor(runtime);
+        void (async () => {
+            try {
+                do {
+                    state.rescheduleRequested = false;
+                    await executor.runUntilIdle(projectId, workspaceId);
+                } while (rescheduleRequested(state));
+            }
+            finally {
+                runtime.close();
+                activeScopes.delete(scope);
+            }
+        })();
+    });
+}
+function rescheduleRequested(state) {
+    return state.rescheduleRequested;
+}
+/** Re-enqueues accepted/checkpointed package-handoff work discovered after a process restart. */
+export function recoverPackageHandoffJobsAtStartup() {
+    const runtime = new DurableJobRuntime();
+    try {
+        const scopes = runtime.listRunnableScopes();
+        for (const scope of scopes) {
+            const hasHandoffWork = runtime
+                .list(scope.projectId, scope.workspaceId)
+                .some((job) => (job.state === 'accepted' || job.state === 'checkpointed') &&
+                isPackageHandoffJob(job.payload));
+            if (hasHandoffWork) {
+                schedulePackageHandoffJobExecution(scope.projectId, scope.workspaceId);
+            }
+        }
+    }
+    finally {
+        runtime.close();
+    }
+}
+//# sourceMappingURL=package-handoff-job-executor.js.map

package/dist/engine/execution/validate-job-executor.js

@@ -13,7 +13,7 @@ import { resolveStorageLayout } from '../../storage/storage-layout.js';
 import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 import { createValidationReceiptAuthority, ensureValidationIssuerKey, issueValidationReceipt, LOCAL_VALIDATION_RECEIPT_ISSUER, preflightValidationReceiptSigner, } from '../validation/validation-receipt.js';
 import { appendArtifact, readArtifact } from '../handoff-artifacts/io.js';
-import { assertValidationFreshnessBarrier, beginValidationFreshnessBarrier, beginValidationFreshnessPublicationWindow, bindValidationFreshnessLease, closeValidationFreshnessLease, rebaselineValidationFreshnessLeaseAfterRecompute, } from '../validation/validation-freshness.js';
+import { beginValidationFreshnessBarrier, beginValidationFreshnessPublicationWindow, bindValidationFreshnessLease, closeValidationFreshnessLease, evaluateValidationFreshnessBarrier, rebaselineValidationFreshnessLeaseAfterRecompute, } from '../validation/validation-freshness.js';
 import { recoverValidateJobs } from './validate-job-recovery.js';
 import { getRuntimePolicy } from '../runtime-policy.js';
 import { isValidateJob, parseValidatePayload, rehydrateValidationPayload, } from './validate-job-payload.js';
@@ -148,6 +148,16 @@ function toolResultError(result) {
 function executionAborted(signal) {
     return signal.aborted;
 }
+function actionableFreshnessMessage(prefix, reason, changedInput) {
+    const changedSuffix = changedInput ? ` (changed: ${changedInput})` : '';
+    return `${prefix}: ${reason}${changedSuffix} Re-run validate to issue a fresh receipt, then retry the original call.`;
+}
+function freshnessBarrierErrorMessage(phase, result) {
+    return actionableFreshnessMessage(`[Planu] Validation inputs changed ${phase} receipt publication`, result.reason, result.changedInput);
+}
+function rebaselineRejectionErrorMessage(rejection) {
+    return actionableFreshnessMessage('[Planu] Validation inputs changed before receipt publication', rejection.reason, rejection.changedInput);
+}
 function hasReceiptInputs(payload) {
     return Boolean(payload.bindings && payload.artifactDigests && payload.freshnessLease);
 }
@@ -688,8 +698,9 @@ export class ValidateJobExecutor {
             if (executionAborted(signal)) {
                 signal.throwIfAborted();
             }
-            if (!(await assertValidationFreshnessBarrier(publicationLease, receiptBindings))) {
-                throw new Error('[Planu] Validation inputs changed before receipt publication');
+            const barrierBeforePublication = await evaluateValidationFreshnessBarrier(publicationLease, receiptBindings);
+            if (!barrierBeforePublication.fresh) {
+                throw new Error(freshnessBarrierErrorMessage('before', barrierBeforePublication));
             }
             const database = new RuntimeDatabase({ path: resolveStorageLayout().runtimeDatabase });
             try {
@@ -723,9 +734,10 @@ export class ValidateJobExecutor {
                 if (executionAborted(signal)) {
                     signal.throwIfAborted();
                 }
-                if (!(await assertValidationFreshnessBarrier(publicationLease, receiptBindings))) {
+                const barrierDuringPublication = await evaluateValidationFreshnessBarrier(publicationLease, receiptBindings);
+                if (!barrierDuringPublication.fresh) {
                     await store.invalidateCurrentBindings(identity.projectId, payload.bindings.specId);
-                    throw new Error('[Planu] Validation inputs changed during receipt publication');
+                    throw new Error(freshnessBarrierErrorMessage('during', barrierDuringPublication));
                 }
                 const receiptKey = `validation-receipt:${receipt.receiptId.slice('sha256:'.length)}`;
                 let enrichedReportSha;
@@ -775,10 +787,10 @@ export class ValidateJobExecutor {
                 return toValidationReceiptBindings(observed.bindings, observed.artifactDigests);
             },
         });
-        if (!rebaselined) {
-            throw new Error('[Planu] Validation inputs changed before receipt publication');
+        if ('rejection' in rebaselined) {
+            throw new Error(rebaselineRejectionErrorMessage(rebaselined.rejection));
         }
-        lease = rebaselined;
+        lease = rebaselined.lease;
         return lease;
     }
     async persistReceiptArtifacts(identity, payload, receiptId, receiptKey) {

package/dist/engine/git/exec-git.d.ts

@@ -0,0 +1,4 @@
+export declare const GIT_EXEC_TIMEOUT_MS = 5000;
+export declare const GIT_EXEC_MAX_BUFFER_BYTES: number;
+export declare function execGitCapture(command: string, cwd: string): string;
+//# sourceMappingURL=exec-git.d.ts.map

package/dist/engine/git/exec-git.js

@@ -0,0 +1,14 @@
+// engine/git/exec-git.ts — SPEC-1560: bounded synchronous git capture helper
+import { execSync } from 'node:child_process';
+export const GIT_EXEC_TIMEOUT_MS = 5_000;
+export const GIT_EXEC_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+export function execGitCapture(command, cwd) {
+    return execSync(command, {
+        cwd,
+        timeout: GIT_EXEC_TIMEOUT_MS,
+        maxBuffer: GIT_EXEC_MAX_BUFFER_BYTES,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        encoding: 'utf-8',
+    });
+}
+//# sourceMappingURL=exec-git.js.map