@planu/cli 4.14.1 → 5.0.0

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

@@ -1,87 +1,144 @@
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { projectDataDir } from '../../storage/base-store.js';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 import { computeDurableValidationBindings, toValidationReceiptBindings, } from '../validation/durable-validation.js';
-import { assertValidationFreshnessBarrier, beginValidationFreshnessBarrier, bindValidationFreshnessLease, } from '../validation/validation-freshness.js';
-import { PROJECT_ID as CANONICAL_PROJECT_ID } from '../validation/validation-receipt-codec.js';
+import { assertValidationFreshnessBarrier, beginValidationFreshnessBarrier, bindValidationFreshnessLease, closeValidationFreshnessLease, } from '../validation/validation-freshness.js';
+import { PROJECT_ID as CANONICAL_PROJECT_ID, SPEC_ID as CANONICAL_SPEC_ID, } from '../validation/validation-receipt-codec.js';
+import { isValidationRootId, revalidateValidationWorktree, ValidationWorktreeError, } from '../validation/validation-worktree.js';
 export function isValidateJob(value) {
     return Boolean(value && typeof value === 'object' && value.kind === 'validate');
 }
+async function closeFreshnessLeaseWithoutMasking(lease) {
+    try {
+        await closeValidationFreshnessLease(lease);
+    }
+    catch (error) {
+        reportClassifiedDegradation('VALIDATION_FRESHNESS_CHECK_FAILED', error);
+    }
+}
+function hasValidBindingIdentity(payload) {
+    return (payload.bindings === undefined ||
+        (payload.bindings.projectId === payload.input?.projectId &&
+            CANONICAL_PROJECT_ID.test(payload.bindings.projectId)));
+}
+function hasValidPayloadShape(payload) {
+    return Boolean(payload.kind === 'validate' &&
+        payload.schemaVersion === 2 &&
+        payload.input &&
+        typeof payload.input.specId === 'string' &&
+        CANONICAL_SPEC_ID.test(payload.input.specId) &&
+        typeof payload.input.projectId === 'string' &&
+        CANONICAL_PROJECT_ID.test(payload.input.projectId) &&
+        typeof payload.input.projectPath === 'string' &&
+        typeof payload.specPath === 'string' &&
+        hasValidBindingIdentity(payload));
+}
 export function parseValidatePayload(value) {
     if (!value || typeof value !== 'object') {
         return undefined;
     }
     const payload = value;
-    if (payload.kind !== 'validate' ||
-        payload.schemaVersion !== 1 ||
-        !payload.input ||
-        typeof payload.input.specId !== 'string' ||
-        typeof payload.input.projectId !== 'string' ||
-        !CANONICAL_PROJECT_ID.test(payload.input.projectId) ||
-        (payload.bindings !== undefined &&
-            (payload.bindings.projectId !== payload.input.projectId ||
-                !CANONICAL_PROJECT_ID.test(payload.bindings.projectId))) ||
-        (payload.input.projectPath !== undefined && typeof payload.input.projectPath !== 'string')) {
+    const schemaVersion = value.schemaVersion;
+    const rawSpecId = payload.input?.specId;
+    const inputSpecId = typeof rawSpecId === 'string' && CANONICAL_SPEC_ID.test(rawSpecId) ? rawSpecId : 'SPEC-unknown';
+    if (schemaVersion !== 2) {
+        throw new ValidationWorktreeError('VALIDATION_PAYLOAD_VERSION_UNSUPPORTED', inputSpecId);
+    }
+    if (!isValidationRootId(payload.validationRootId)) {
+        throw new ValidationWorktreeError('VALIDATION_ROOT_ID_MALFORMED', inputSpecId);
+    }
+    if (typeof rawSpecId !== 'string' || !CANONICAL_SPEC_ID.test(rawSpecId)) {
+        throw new ValidationWorktreeError('VALIDATION_SPEC_ID_MISMATCH', 'SPEC-unknown');
+    }
+    if (!hasValidPayloadShape(payload)) {
         return undefined;
     }
     return payload;
 }
-export async function rehydrateValidationPayload(payload) {
-    const projectPath = payload.input.projectPath;
-    const specPath = payload.specPath;
-    if (!projectPath || !specPath) {
-        return payload;
+async function computeFreshSnapshot(input) {
+    const handoffPath = join(projectDataDir(input.projectId), 'handoffs', input.specId);
+    await mkdir(handoffPath, { recursive: true });
+    const freshnessLease = await beginValidationFreshnessBarrier({
+        projectId: input.projectId,
+        specId: input.specId,
+        projectPath: input.projectPath,
+        handoffPath,
+    });
+    try {
+        const observed = await computeDurableValidationBindings({
+            canonicalProjectId: input.projectId,
+            specId: input.specId,
+            projectPath: input.projectPath,
+            specPath: input.specPath,
+        });
+        return { freshnessLease, observed };
+    }
+    catch (error) {
+        await closeFreshnessLeaseWithoutMasking(freshnessLease);
+        throw error;
     }
+}
+export async function rehydrateValidationPayload(payload) {
+    const resolved = await revalidateValidationWorktree({
+        projectPath: payload.input.projectPath ?? '',
+        specPath: payload.specPath,
+        specId: payload.input.specId,
+        validationRootId: payload.validationRootId,
+    });
+    const projectPath = resolved.projectPath;
+    const specPath = resolved.specPath;
+    const normalizedPayload = {
+        ...payload,
+        input: { ...payload.input, projectPath },
+        specPath,
+    };
     if (!payload.bindings || !payload.artifactDigests) {
-        const handoffPath = join(projectDataDir(payload.input.projectId), 'handoffs', payload.input.specId);
-        await mkdir(handoffPath, { recursive: true });
-        const freshnessLease = await beginValidationFreshnessBarrier({
+        const { freshnessLease, observed } = await computeFreshSnapshot({
             projectId: payload.input.projectId,
             specId: payload.input.specId,
             projectPath,
-            handoffPath,
-        });
-        const observed = await computeDurableValidationBindings({
-            canonicalProjectId: payload.input.projectId,
-            specId: payload.input.specId,
-            projectPath,
             specPath,
         });
-        const observedReceiptBindings = toValidationReceiptBindings(observed.bindings, observed.artifactDigests);
-        if (!(await bindValidationFreshnessLease(freshnessLease, observedReceiptBindings))) {
-            throw new Error('[Planu] Validation inputs changed while the snapshot was computed');
+        try {
+            const observedReceiptBindings = toValidationReceiptBindings(observed.bindings, observed.artifactDigests);
+            if (!(await bindValidationFreshnessLease(freshnessLease, observedReceiptBindings))) {
+                throw new Error('[Planu] Validation inputs changed while the snapshot was computed');
+            }
+            return {
+                ...normalizedPayload,
+                bindings: observed.bindings,
+                artifactDigests: observed.artifactDigests,
+                freshnessLease,
+            };
+        }
+        catch (error) {
+            await closeFreshnessLeaseWithoutMasking(freshnessLease);
+            throw error;
         }
-        return {
-            ...payload,
-            bindings: observed.bindings,
-            artifactDigests: observed.artifactDigests,
-            freshnessLease,
-        };
     }
     const expected = toValidationReceiptBindings(payload.bindings, payload.artifactDigests);
     if (payload.freshnessLease &&
         (await assertValidationFreshnessBarrier(payload.freshnessLease, expected))) {
-        return payload;
+        return normalizedPayload;
     }
-    const handoffPath = join(projectDataDir(payload.bindings.projectId), 'handoffs', payload.bindings.specId);
-    await mkdir(handoffPath, { recursive: true });
-    const freshnessLease = await beginValidationFreshnessBarrier({
+    const { freshnessLease, observed } = await computeFreshSnapshot({
         projectId: payload.bindings.projectId,
         specId: payload.bindings.specId,
         projectPath,
-        handoffPath,
-    });
-    const observed = await computeDurableValidationBindings({
-        canonicalProjectId: payload.bindings.projectId,
-        specId: payload.bindings.specId,
-        projectPath,
         specPath,
     });
-    const observedReceiptBindings = toValidationReceiptBindings(observed.bindings, observed.artifactDigests);
-    if (JSON.stringify(expected) !== JSON.stringify(observedReceiptBindings) ||
-        !(await bindValidationFreshnessLease(freshnessLease, observedReceiptBindings))) {
-        throw new Error('[Planu] Durable validation bindings became stale; submit a new validation');
+    try {
+        const observedReceiptBindings = toValidationReceiptBindings(observed.bindings, observed.artifactDigests);
+        if (JSON.stringify(expected) !== JSON.stringify(observedReceiptBindings) ||
+            !(await bindValidationFreshnessLease(freshnessLease, observedReceiptBindings))) {
+            throw new Error('[Planu] Durable validation bindings became stale; submit a new validation');
+        }
+        return { ...normalizedPayload, freshnessLease };
+    }
+    catch (error) {
+        await closeFreshnessLeaseWithoutMasking(freshnessLease);
+        throw error;
     }
-    return { ...payload, freshnessLease };
 }
 //# sourceMappingURL=validate-job-payload.js.map

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

@@ -3,7 +3,7 @@ function isValidatePayload(value) {
     return Boolean(value &&
         typeof value === 'object' &&
         value.kind === 'validate' &&
-        value.schemaVersion === 1);
+        value.schemaVersion === 2);
 }
 /** Recover runnable validation work and program one global sweep for the earliest live lease. */
 export function recoverValidateJobs(defaultSchedule, options = {}) {

package/dist/engine/execution/validate-worker-runtime.d.ts

@@ -1,5 +1,10 @@
 import type { ValidateWorkerCall } from '../../types/validate-worker.js';
 import type { ToolResult } from '../../types/index.js';
+export declare class ValidationWorkerStalledError extends Error {
+    readonly code: 'VALIDATION_STALLED';
+    readonly lastPhase: string;
+    constructor(lastPhase: string);
+}
 /** Execute validation in a supervised OS worker thread, isolated from the MCP event loop. */
 export declare function runValidateWorker(call: ValidateWorkerCall): Promise<ToolResult>;
 //# sourceMappingURL=validate-worker-runtime.d.ts.map

package/dist/engine/execution/validate-worker-runtime.js

@@ -3,6 +3,69 @@ import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { Worker } from 'node:worker_threads';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
+import { getRuntimePolicy } from '../runtime-policy.js';
+export class ValidationWorkerStalledError extends Error {
+    code = 'VALIDATION_STALLED';
+    lastPhase;
+    constructor(lastPhase) {
+        const phase = safePhase(lastPhase);
+        super(`[Planu] VALIDATION_STALLED: no semantic progress during ${phase}`);
+        this.name = 'ValidationWorkerStalledError';
+        this.lastPhase = phase;
+    }
+}
+function safePhase(phase) {
+    const normalized = phase.trim();
+    return /^[a-z][a-z0-9_-]{0,79}$/iu.test(normalized) ? normalized : 'redacted';
+}
+function semanticProgressAdvanced(previous, current) {
+    if (previous === undefined) {
+        return true;
+    }
+    if (current.completedGates < previous.completedGates ||
+        current.lastProgressAt < previous.lastProgressAt) {
+        return false;
+    }
+    return (current.phase !== previous.phase ||
+        current.status !== previous.status ||
+        current.completedGates > previous.completedGates);
+}
+class SemanticProgressWatchdog {
+    timeoutMs;
+    onStalled;
+    timer;
+    previous;
+    phase = 'startup';
+    constructor(timeoutMs, onStalled) {
+        this.timeoutMs = timeoutMs;
+        this.onStalled = onStalled;
+    }
+    start() {
+        this.arm();
+    }
+    observe(progress) {
+        if (!semanticProgressAdvanced(this.previous, progress)) {
+            return;
+        }
+        this.phase = progress.phase;
+        this.previous = progress;
+        this.arm();
+    }
+    dispose() {
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+    }
+    arm() {
+        this.dispose();
+        this.timer = setTimeout(() => {
+            this.onStalled(this.phase);
+        }, this.timeoutMs);
+        this.timer.unref();
+    }
+}
 function workerUrl() {
     const sibling = new URL('./validate-worker-thread.js', import.meta.url);
     if (existsSync(sibling)) {
@@ -15,6 +78,7 @@ function workerUrl() {
     throw new Error('[Planu] Validate worker artifact is missing; run the production build');
 }
 /** Execute validation in a supervised OS worker thread, isolated from the MCP event loop. */
+// eslint-disable-next-line max-lines-per-function -- lifecycle handlers stay co-located around one worker instance.
 export function runValidateWorker(call) {
     if (call.signal?.aborted) {
         return Promise.reject(abortError(call.signal));
@@ -23,16 +87,29 @@ export function runValidateWorker(call) {
         return Promise.reject(new Error('[Planu] Validate worker requires a future deadline'));
     }
     const secret = randomBytes(32).toString('hex');
-    const worker = new Worker(workerUrl(), { workerData: { secret } });
+    const worker = new Worker(workerUrl(), { workerData: { secret }, execArgv: [] });
+    // eslint-disable-next-line max-lines-per-function -- watchdog and authenticated worker share one settlement boundary
     return new Promise((resolveCall, reject) => {
         let settled = false;
         let sent = false;
+        const watchdog = new SemanticProgressWatchdog(getRuntimePolicy().validation.noProgressTimeoutMs, (phase) => {
+            if (call.signal?.aborted) {
+                abort();
+            }
+            else if (Date.now() >= call.deadlineAt) {
+                finish(new Error('[Planu] Validate worker deadline exceeded'));
+            }
+            else {
+                finish(new ValidationWorkerStalledError(phase));
+            }
+        });
         const finish = (error, result) => {
             if (settled) {
                 return;
             }
             settled = true;
             clearTimeout(timer);
+            watchdog.dispose();
             call.signal?.removeEventListener('abort', abort);
             void worker.terminate();
             if (error) {
@@ -52,6 +129,7 @@ export function runValidateWorker(call) {
             finish(new Error('[Planu] Validate worker deadline exceeded'));
         }, Math.max(1, call.deadlineAt - Date.now()));
         timer.unref();
+        watchdog.start();
         call.signal?.addEventListener('abort', abort, { once: true });
         worker.once('error', (error) => {
             finish(error instanceof Error ? error : new Error(String(error)));
@@ -62,6 +140,9 @@ export function runValidateWorker(call) {
             }
         });
         worker.on('message', (value) => {
+            if (settled) {
+                return;
+            }
             const response = value;
             if (response.kind === 'ready' && response.schemaVersion === 1 && !sent) {
                 const request = {
@@ -81,7 +162,14 @@ export function runValidateWorker(call) {
                 finish(new Error('[Planu] Validate worker response identity mismatch'));
             }
             else if (response.kind === 'validate-progress' && response.progress !== undefined) {
-                call.onProgress?.(response.progress);
+                watchdog.observe(response.progress);
+                try {
+                    call.onProgress?.(response.progress);
+                }
+                catch (error) {
+                    reportClassifiedDegradation('VALIDATE_WORKER_PROGRESS_CALLBACK_FAILURE', error);
+                    finish(error instanceof Error ? error : new Error(String(error)));
+                }
             }
             else if (response.kind === 'validate-error') {
                 finish(new Error(response.message));

package/dist/engine/execution/validate-worker-thread.js

@@ -1,5 +1,6 @@
 import { parentPort, workerData } from 'node:worker_threads';
 import { redactFailureMessage, reportClassifiedDegradation, } from '../../errors/classified-degradation.js';
+import { createExecutionScope } from './context.js';
 const bootstrap = workerData;
 if (!parentPort || typeof bootstrap?.secret !== 'string' || bootstrap.secret.length < 32) {
     throw new Error('[Planu] Validate worker bootstrap authentication failed');
@@ -26,30 +27,22 @@ async function execute(value) {
             throw new Error('[Planu] Validate worker rejected malformed or expired work');
         }
         const { executeValidate } = await import('../../tools/validate.js');
-        const startedAt = Date.now();
-        port.postMessage({
-            kind: 'validate-progress',
-            schemaVersion: 1,
-            requestId,
-            progress: {
-                phase: 'validation',
-                command: 'planu validate',
-                durationMs: 0,
-                status: 'running',
-            },
-        });
-        const result = await executeValidate(request.input);
-        port.postMessage({
-            kind: 'validate-progress',
-            schemaVersion: 1,
-            requestId,
-            progress: {
-                phase: 'validation',
-                command: 'planu validate',
-                durationMs: Date.now() - startedAt,
-                status: result.isError === true ? 'failed' : 'passed',
-            },
-        });
+        const input = request.input;
+        const scope = createExecutionScope({ requestId, deadlineAt: request.deadlineAt });
+        let result;
+        try {
+            result = await scope.run(() => executeValidate(input, undefined, (progress) => {
+                port.postMessage({
+                    kind: 'validate-progress',
+                    schemaVersion: 1,
+                    requestId,
+                    progress,
+                });
+            }));
+        }
+        finally {
+            scope.dispose();
+        }
         port.postMessage({
             kind: 'validate-result',
             schemaVersion: 1,

package/dist/engine/handoff-artifacts/schemas.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { ArtifactKind } from '../../types/handoff-artifacts.js';
+import type { ArtifactKind, ReconciliationReceiptV1 } from '../../types/handoff-artifacts.js';
 import type { ValidationOk, ValidationErr } from './validation-result.js';
 export declare const SchemaVersion: z.ZodString;
 export declare const IntakeV1Schema: z.ZodObject<{
@@ -157,6 +157,7 @@ export declare const ValidationReportV1Schema: z.ZodObject<{
     score: z.ZodOptional<z.ZodNumber>;
     completedAt: z.ZodISODateTime;
 }, z.core.$strip>;
+export declare const ReconciliationReceiptV1Schema: z.ZodType<ReconciliationReceiptV1>;
 export declare const ARTIFACT_SCHEMAS: {
     readonly intake: z.ZodObject<{
         schema_version: z.ZodString;

package/dist/engine/handoff-artifacts/schemas.js

@@ -121,6 +121,39 @@ export const ValidationReportV1Schema = z.object({
     score: z.number().optional(),
     completedAt: z.iso.datetime(),
 });
+export const ReconciliationReceiptV1Schema = z.object({
+    schema_version: z.literal('1.0.0'),
+    projectId: z.string().min(1),
+    specId: z.string().min(1),
+    requestId: z
+        .string()
+        .regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u),
+    sourceImplementingTransitionId: z.string().min(1),
+    sourceUpdatedAt: z.iso.datetime(),
+    bindingDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+    reasonDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+    implementationReviewDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+    supersededArtifacts: z.array(z.object({
+        artifactId: z.string().min(1),
+        sha256: z
+            .string()
+            .regex(/^sha256:[a-f0-9]{64}$/u)
+            .optional(),
+    })),
+    state: z.enum(['prepared', 'committed', 'aborted']),
+    stateHistory: z.array(z.object({
+        state: z.enum(['prepared', 'committed', 'aborted']),
+        at: z.iso.datetime(),
+        reason: z.string().optional(),
+    })),
+    preparedAt: z.iso.datetime(),
+    committedAt: z.iso.datetime().optional(),
+    abortedAt: z.iso.datetime().optional(),
+    committedTransitionId: z.string().min(1).optional(),
+    transitionId: z.string().min(1).optional(),
+    phase: z.enum(['prepared', 'status-committed', 'spec-synced', 'audit-appended']).optional(),
+    auditPending: z.boolean().optional(),
+});
 // ---------------------------------------------------------------------------
 // Schema registry
 // ---------------------------------------------------------------------------

package/dist/engine/handoff-packager.d.ts

@@ -1,3 +1,22 @@
 import type { Spec, ProjectKnowledge, HandoffPackage } from '../types/index.js';
+/** Normalize one repository-relative ownership path without retaining unsafe input in diagnostics. */
+export declare function normalizeOwnedPath(value: string): {
+    status: 'valid';
+    path: string;
+} | {
+    status: 'none';
+} | {
+    status: 'invalid';
+    code: 'INVALID_FILE_OWNERSHIP_EMPTY' | 'INVALID_FILE_OWNERSHIP_FENCED' | 'INVALID_FILE_OWNERSHIP_NUL' | 'INVALID_FILE_OWNERSHIP_ABSOLUTE' | 'INVALID_FILE_OWNERSHIP_HOME_RELATIVE' | 'INVALID_FILE_OWNERSHIP_UNC' | 'INVALID_FILE_OWNERSHIP_DRIVE_ABSOLUTE' | 'INVALID_FILE_OWNERSHIP_URI' | 'INVALID_FILE_OWNERSHIP_TRAVERSAL' | 'INVALID_FILE_OWNERSHIP_MARKDOWN' | 'INVALID_FILE_OWNERSHIP_DESCRIPTION';
+};
+/** Normalize a raw traceability changed-file value without interpreting Markdown or prose. */
+export declare function normalizeChangedFilePath(value: string): ReturnType<typeof normalizeOwnedPath>;
+export declare function extractCanonicalFileOwnership(content: string): {
+    present: boolean;
+    toModify: string[];
+    toCreate: string[];
+    toTest: string[];
+    blockers: string[];
+};
 export declare function packageHandoff(spec: Spec, knowledge: ProjectKnowledge): Promise<HandoffPackage>;
 //# sourceMappingURL=handoff-packager.d.ts.map