@planu/cli 5.3.67 → 5.3.69

package/dist/engine/version-resolver.js

@@ -6,6 +6,7 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fetchLatestVersion } from './package-registry.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { getCachedVersions, saveCachedVersions, isExpired as isCachedVersionExpired, } from '../storage/version-cache-store.js';
 // -- Constants ---------------------------------------------------------------
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours

package/dist/engine/workers/handlers/auto-drift.js

@@ -1,8 +1,11 @@
 // engine/workers/handlers/auto-drift.ts — Auto drift detection on file changes (SPEC-225)
 import { relative, extname } from 'node:path';
 import { readdir, stat } from 'node:fs/promises';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { specStore } from '../../../storage/index.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { hashProjectPath } from '../../../storage/base-store.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { DriftCacheStore } from '../../../storage/drift-cache-store.js';
 import { emitAutopilotEvent } from '../../autopilot/event-bus.js';
 // ---------------------------------------------------------------------------

package/dist/engine/workspace-manager.js

@@ -1,8 +1,12 @@
 // engine/workspace-manager.ts — SPEC-363: Multi-tenant Workspace Dashboard
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { getProjects, addProject } from '../storage/global-projects-store.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { specStore } from '../storage/index.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { hashProjectPath, readJson } from '../storage/base-store.js';
 import { glob } from 'glob';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { resolveStorageLayout } from '../storage/storage-layout.js';
 // ---------------------------------------------------------------------------
 // SPEC-789: Project discovery fallback

package/dist/hosts/gemini/config-scaffold.js

@@ -2,11 +2,12 @@
 // Writes .gemini/conventions.md, .gemini/skills/planu-*.md, and .gemini/hooks/
 // equivalents when init_project runs inside a Gemini workspace.
 // NOTE: This function deliberately does NOT create .claude/ files.
-import { writeFile, readFile, mkdir, access } from 'node:fs/promises';
+import { writeFile, readFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { buildRulesForHost } from '../../engine/host-rules-templates/index.js';
 import { assertEnglishOnlyArtifactText } from '../../engine/spec-language/english-only.js';
 import { PLANU_VERSION } from '../../config/version.js';
+import { fileExists } from '../../core/shared/fs.js';
 // ---------------------------------------------------------------------------
 // File content generators
 // ---------------------------------------------------------------------------
@@ -188,13 +189,4 @@ async function injectRulesBlock(filePath, version) {
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
-async function fileExists(filePath) {
-    try {
-        await access(filePath);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 //# sourceMappingURL=config-scaffold.js.map

package/dist/storage/approval-operation-lock.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { isAbsolute, resolve } from 'node:path';
 import { withFileLock } from './file-mutex.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { LockBusyError, withSpecLock } from '../engine/safety/cross-process-lock.js';
 const heldApprovalLocks = new AsyncLocalStorage();
 function approvalLockId(specId) {

package/dist/storage/auto-promoter-config-store.js

@@ -1,6 +1,7 @@
 // storage/auto-promoter-config-store.ts — Persists auto-promoter config (SPEC-391)
 // Layout: data/projects/{hash}/config/auto-promoter.json
 import { readJson, writeJson, projectDataDir, hashProjectPath } from './base-store.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { getDefaultConfig } from '../engine/auto-promoter.js';
 function configFile(projectId) {
     return `${projectDataDir(projectId)}/config/auto-promoter.json`;

package/dist/storage/autopilot-log-store.js

@@ -1,6 +1,7 @@
 // storage/autopilot-log-store.ts — SPEC-772: Autopilot cascade log persistence
 import { readFile, mkdir } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { atomicWriteFile } from '../engine/safety/atomic-write-file.js';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 import { projectDataDir } from './base-store.js';

package/dist/storage/base-store.js

@@ -3,6 +3,7 @@
 import { readFile, mkdir } from 'node:fs/promises';
 import { readFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { writeJsonSafe } from '../engine/safety/atomic-writer.js';
 import { resolveStorageLayout } from './storage-layout.js';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';

package/dist/storage/checkpoint-store.js

@@ -3,6 +3,7 @@ import { readdir, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { readJson, writeJson, projectDataDir } from './base-store.js';
 import { withFileLock } from './file-mutex.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { writeJsonSafe } from '../engine/safety/atomic-writer.js';
 // ---------------------------------------------------------------------------
 // Helpers

package/dist/storage/feedback-remote.js

@@ -1,5 +1,6 @@
 // storage/feedback-remote.ts — Configured remote feedback relay (fire-and-forget)
 // No PII is ever sent: no project paths, no user names, no emails.
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { networkFetch, withNetworkConsent } from '../engine/network-policy.js';
 function resolveConfiguredFeedbackEndpoint(endpoint) {
     const configured = endpoint ?? process.env.PLANU_FEEDBACK_ENDPOINT;

package/dist/storage/gaps-log.js

@@ -7,6 +7,7 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { appendFile, readFile, mkdir } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { fastAppendGapEntry, fastVerifyGapsChain } from '../engine/core-bridge.js';
 import { projectDataDir } from './base-store.js';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';

package/dist/storage/global-projects-store.d.ts

@@ -1,4 +1,6 @@
 import type { RegisteredProject, GlobalProjectsRegistry } from '../types/index.js';
+/** Best-effort, non-creating read of a checkout's logical project identity. */
+export declare function readLogicalProjectId(projectPath: string): Promise<string | undefined>;
 /**
  * Read the full registry from disk.
  * Returns an empty registry when the file does not exist.
@@ -15,6 +17,21 @@ export declare function saveRegistry(registry: GlobalProjectsRegistry): Promise<
  * Returns the registered project entry.
  */
 export declare function addProject(projectPath: string): Promise<RegisteredProject>;
+/** Stable, classified failure for a logical project id with no unambiguous canonical root. */
+export type CanonicalRootResult = {
+    readonly ok: true;
+    readonly root: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'zero' | 'ambiguous';
+    readonly roots: readonly string[];
+};
+/**
+ * Resolve the single canonical root registered for a logical project identity.
+ * Fails closed — never guesses a first match — when zero or more than one
+ * distinct registered path claims the same `logicalProjectId`.
+ */
+export declare function getCanonicalRoot(logicalProjectId: string): Promise<CanonicalRootResult>;
 /**
  * Remove a project from the registry by path.
  * Returns true if the project was found and removed, false otherwise.

package/dist/storage/global-projects-store.js

@@ -2,8 +2,26 @@
 // Persistence file: data/global/registered-projects.json
 import { readJson, writeJson, globalDataDir, hashProjectPath } from './base-store.js';
 import { withFileLock } from './file-mutex.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { isEphemeralProject } from '../engine/data-projects-gc/pattern-matcher.js';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/** Best-effort, non-creating read of a checkout's logical project identity. */
+export async function readLogicalProjectId(projectPath) {
+    try {
+        const raw = JSON.parse(await readFile(join(projectPath, 'planu', 'project.json'), 'utf8'));
+        const id = raw?.logicalProjectId;
+        return typeof id === 'string' && UUID_PATTERN.test(id) ? id : undefined;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            reportClassifiedDegradation('LOGICAL_PROJECT_ID_READ_FAILED', error);
+        }
+        return undefined;
+    }
+}
 // ---------------------------------------------------------------------------
 // File path
 // ---------------------------------------------------------------------------
@@ -46,11 +64,15 @@ export async function addProject(projectPath) {
             specCount: 0,
         };
     }
+    const logicalProjectId = await readLogicalProjectId(projectPath);
     return withFileLock(registryFile(), async () => {
         const registry = await getRegistry();
         const existing = registry.projects.find((p) => p.path === projectPath);
         if (existing !== undefined) {
             existing.hash = hash;
+            if (logicalProjectId !== undefined) {
+                existing.logicalProjectId = logicalProjectId;
+            }
             registry.updatedAt = new Date().toISOString();
             await saveRegistry(registry);
             return existing;
@@ -60,6 +82,7 @@ export async function addProject(projectPath) {
             hash,
             registeredAt: new Date().toISOString(),
             specCount: 0,
+            ...(logicalProjectId !== undefined && { logicalProjectId }),
         };
         registry.projects.push(entry);
         registry.updatedAt = new Date().toISOString();
@@ -67,6 +90,30 @@ export async function addProject(projectPath) {
         return entry;
     });
 }
+/**
+ * Resolve the single canonical root registered for a logical project identity.
+ * Fails closed — never guesses a first match — when zero or more than one
+ * distinct registered path claims the same `logicalProjectId`.
+ */
+export async function getCanonicalRoot(logicalProjectId) {
+    const projects = await getProjects();
+    const roots = [
+        ...new Set(projects
+            .filter((project) => project.logicalProjectId === logicalProjectId)
+            .map((project) => project.path)),
+    ];
+    if (roots.length === 0) {
+        return { ok: false, reason: 'zero', roots };
+    }
+    if (roots.length > 1) {
+        return { ok: false, reason: 'ambiguous', roots };
+    }
+    const [root] = roots;
+    if (root === undefined) {
+        return { ok: false, reason: 'zero', roots };
+    }
+    return { ok: true, root };
+}
 /**
  * Remove a project from the registry by path.
  * Returns true if the project was found and removed, false otherwise.

package/dist/storage/global-store.js

@@ -1,5 +1,6 @@
 import { readJson, writeJson, globalDataDir } from './base-store.js';
 import { withFileLock } from './file-mutex.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { applyLearnedLimit, markVerified } from '../engine/registry-extender.js';
 import { readFileSync } from 'node:fs';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';

package/dist/storage/knowledge-store/sessions.js

@@ -1,6 +1,8 @@
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { mergeContext } from '../../engine/context-merger.js';
 import { readJson, writeJson, projectDataDir } from '../base-store.js';
 import { withFileLock } from '../file-mutex.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { addMetricsToState } from '../../engine/calibrator.js';
 import { getKnowledge, knowledgeFile } from './knowledge.js';
 // --- File paths ---

package/dist/storage/migrations/canonical-storage.js

@@ -3,7 +3,9 @@ import { copyFile, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from
 import { createHash, randomUUID } from 'node:crypto';
 import { homedir, tmpdir } from 'node:os';
 import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { acquireLock as acquireFileMutex, releaseLock as releaseFileMutex, } from '../../engine/safety/file-mutex.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { assertNoObsoleteFileLock } from '../../engine/safety/obsolete-lock-guard.js';
 function sha256(value) {
     return createHash('sha256').update(value).digest('hex');
@@ -174,10 +176,17 @@ async function readJournal(path, expected) {
         throw error;
     }
 }
+function isTerminalPhaseValue(value) {
+    return value === 'completed';
+}
+async function quarantineStaleJournal(journalPath) {
+    const quarantinePath = journalPath.replace(/\.journal\.json$/, `.journal.stale-${String(Date.now())}.json`);
+    await rename(journalPath, quarantinePath);
+}
 async function retireCompletedJournalForNewSources(journalPath, expected) {
-    let parsed;
+    let rawText;
     try {
-        parsed = JSON.parse(await readFile(journalPath, 'utf8'));
+        rawText = await readFile(journalPath, 'utf8');
     }
     catch (error) {
         if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
@@ -185,32 +194,47 @@ async function retireCompletedJournalForNewSources(journalPath, expected) {
         }
         throw error;
     }
+    const parsed = JSON.parse(rawText);
     if (!parsed || typeof parsed !== 'object' || !('legacyRoots' in parsed)) {
         throw new Error('[Planu] Invalid or unsafe migration journal');
     }
-    const rawRoots = parsed.legacyRoots;
+    const record = parsed;
+    const rawRoots = record.legacyRoots;
     if (!Array.isArray(rawRoots) || !rawRoots.every((root) => typeof root === 'string')) {
         throw new Error('[Planu] Invalid or unsafe migration journal');
     }
-    if (JSON.stringify(rawRoots) === JSON.stringify(expected.legacyRoots)) {
-        return;
+    const rootsChanged = JSON.stringify(rawRoots) !== JSON.stringify(expected.legacyRoots);
+    const previousRoots = rootsChanged
+        ? rawRoots.map((root) => assertAbsolute(root, 'journal legacyRoot'))
+        : [...expected.legacyRoots];
+    if (rootsChanged) {
+        for (const root of previousRoots) {
+            assertNarrowLegacyRoot(root);
+            if (isInside(root, expected.destinationRoot) || isInside(expected.destinationRoot, root)) {
+                throw new Error('[Planu] Invalid or unsafe migration journal');
+            }
+        }
     }
-    const previousRoots = rawRoots.map((root) => assertAbsolute(root, 'journal legacyRoot'));
-    for (const root of previousRoots) {
-        assertNarrowLegacyRoot(root);
-        if (isInside(root, expected.destinationRoot) || isInside(expected.destinationRoot, root)) {
-            throw new Error('[Planu] Invalid or unsafe migration journal');
+    try {
+        const previous = validateJournal(parsed, { ...expected, legacyRoots: previousRoots });
+        if (!rootsChanged) {
+            return;
+        }
+        if (previous.phase !== 'completed') {
+            throw new Error('[Planu] Active migration journal does not match requested roots');
         }
+        // A completed destination remains live and may legitimately receive newer
+        // canonical records. Re-inventory its real directory instead of requiring
+        // the historical generation digest to remain frozen forever.
+        await inventoryStorageRoot(expected.destinationRoot);
+        await rm(journalPath, { force: true });
     }
-    const previous = validateJournal(parsed, { ...expected, legacyRoots: previousRoots });
-    if (previous.phase !== 'completed') {
-        throw new Error('[Planu] Active migration journal does not match requested roots');
+    catch (error) {
+        if (!isTerminalPhaseValue(record.phase)) {
+            throw error;
+        }
+        await quarantineStaleJournal(journalPath);
     }
-    // A completed destination remains live and may legitimately receive newer
-    // canonical records. Re-inventory its real directory instead of requiring
-    // the historical generation digest to remain frozen forever.
-    await inventoryStorageRoot(expected.destinationRoot);
-    await rm(journalPath, { force: true });
 }
 function recordTimestamp(value) {
     if (!value || typeof value !== 'object') {

package/dist/storage/project-drift-store.js

@@ -1,6 +1,7 @@
 // storage/project-drift-store.ts — SPEC-666: Read/write drift signals from .planu/drift-commits.ndjson
 import { readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { analyzeCommitRecord } from '../engine/project-drift-detector.js';
 import { hashProjectPath, projectDataDir } from './base-store.js';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';

package/dist/storage/project-identity.d.ts

@@ -27,6 +27,33 @@ export declare function hashWorkspaceKey(workspaceKey: string): string;
 export declare function deriveWorkspaceKey(projectPath: string): Promise<string>;
 /** Resolve or create stable project and machine-workspace UUIDs. */
 export declare function ensureProjectIdentity(projectPath: string, options: ProjectIdentityOptions): Promise<ResolvedProjectIdentity>;
+export type PortablePathErrorCode = 'INVALID_TYPE' | 'EMPTY' | 'NUL_BYTE' | 'NOT_PORTABLE_SHAPE' | 'WRONG_SPEC' | 'ESCAPES_ROOT' | 'ROOT_NOT_FOUND' | 'ROOT_UNVERIFIED' | 'NOT_FOUND' | 'SYMLINK' | 'NOT_FILE';
+/** Stable, classified failure for a spec path that cannot be resolved as a portable identity. */
+export declare class PortablePathError extends Error {
+    readonly code: PortablePathErrorCode;
+    constructor(code: PortablePathErrorCode, message: string);
+}
+/**
+ * Extract the portable `planu/specs/<specId[-slug]>/<filename>` suffix from a stored
+ * path value, rejecting anything that is not that exact shape for the given spec.
+ * Works for both legacy absolute values and already-portable relative ones — the
+ * incoming prefix is discarded, so this doubles as the legacy-path normalizer.
+ */
+export declare function toPortableSpecPath(specId: string, storedPath: unknown): string;
+/**
+ * Resolve a stored `specPath`/`technicalPath` value against the verified canonical
+ * root, returning the realpath of the contained file. Fails closed — with a stable
+ * classified {@link PortablePathError} — for any absent, malformed, escaping,
+ * symlinked, or cross-spec value, before any content is read or written.
+ */
+export declare function resolvePortableSpecPath(specId: string, storedPath: unknown, canonicalRoot: string): Promise<string>;
+/**
+ * Lifecycle-consumer entry point: verify the candidate root against the
+ * global project registry before resolving through it, so an unregistered,
+ * ambiguous, or stale checkout never stands in for the real canonical root.
+ * Delegates to {@link resolvePortableSpecPath} once verified.
+ */
+export declare function resolveVerifiedSpecPath(specId: string, storedPath: unknown, canonicalRoot: string): Promise<string>;
 /** Explicitly turn a copied project into an independent logical project. */
 export declare function forkProjectIdentity(projectPath: string, options: ProjectIdentityOptions): Promise<ResolvedProjectIdentity>;
 //# sourceMappingURL=project-identity.d.ts.map

package/dist/storage/project-identity.js

@@ -1,7 +1,10 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { mkdir, open, readFile, realpath, rename, rm, stat } from 'node:fs/promises';
-import { basename, dirname, join, normalize, resolve, sep } from 'node:path';
+import { lstat, mkdir, open, readFile, realpath, rename, rm, stat } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
 import { resolveStorageLayout } from './storage-layout.js';
+import { getCanonicalRoot, readLogicalProjectId } from './global-projects-store.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
+import { isEphemeralProject } from '../engine/data-projects-gc/pattern-matcher.js';
 const IDENTITY_VERSION = 1;
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 function isProjectIdentity(value) {
@@ -156,6 +159,133 @@ export async function ensureProjectIdentity(projectPath, options) {
     const workspace = await ensureWorkspaceDocument(options.layout ?? resolveStorageLayout(), options.workspaceKey, project.logicalProjectId);
     return { project, workspace, canonicalProjectPath };
 }
+/** Stable, classified failure for a spec path that cannot be resolved as a portable identity. */
+export class PortablePathError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'PortablePathError';
+        this.code = code;
+    }
+}
+/**
+ * Extract the portable `planu/specs/<specId[-slug]>/<filename>` suffix from a stored
+ * path value, rejecting anything that is not that exact shape for the given spec.
+ * Works for both legacy absolute values and already-portable relative ones — the
+ * incoming prefix is discarded, so this doubles as the legacy-path normalizer.
+ */
+export function toPortableSpecPath(specId, storedPath) {
+    if (typeof storedPath !== 'string') {
+        throw new PortablePathError('INVALID_TYPE', '[Planu] specPath must be a string');
+    }
+    if (storedPath.includes('\0')) {
+        throw new PortablePathError('NUL_BYTE', '[Planu] specPath must not contain a NUL byte');
+    }
+    if (storedPath.trim().length === 0) {
+        throw new PortablePathError('EMPTY', '[Planu] specPath must not be empty or whitespace-only');
+    }
+    const segments = normalize(storedPath).split(sep).filter(Boolean);
+    const planuIndex = segments.lastIndexOf('planu');
+    const dir = segments[planuIndex + 2];
+    const filename = segments[planuIndex + 3];
+    const isPortableShape = planuIndex >= 0 &&
+        segments[planuIndex + 1] === 'specs' &&
+        dir !== undefined &&
+        filename !== undefined &&
+        planuIndex + 4 === segments.length;
+    if (!isPortableShape) {
+        throw new PortablePathError('NOT_PORTABLE_SHAPE', '[Planu] specPath is not a portable planu/specs/<dir>/<file> contract');
+    }
+    if (dir !== specId && !dir.startsWith(`${specId}-`)) {
+        throw new PortablePathError('WRONG_SPEC', `[Planu] specPath directory "${dir}" does not belong to ${specId}`);
+    }
+    return join('planu', 'specs', dir, filename);
+}
+function rejectsRootEscape(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel.startsWith(`..${sep}`) || rel === '..' || isAbsolute(rel);
+}
+async function realpathClassified(path, notFoundCode) {
+    try {
+        return await realpath(path);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            throw new PortablePathError(notFoundCode, `[Planu] path not found: ${notFoundCode}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Reject a candidate root that carries a tracked logical project identity but
+ * is not the single registry-confirmed canonical root for it — a checkout
+ * left over from a rename/fork, or an ambiguous/unregistered project never
+ * resolves specs against an arbitrary directory. A candidate with no tracked
+ * identity (`planu/project.json` absent) is untracked, not unverified, and
+ * passes through unchanged — as does an ephemeral checkout (test fixture,
+ * scratch clone), since the global registry deliberately excludes those
+ * (SPEC-581) and can never confirm a root for them.
+ */
+async function rejectsUnverifiedRoot(root) {
+    if (isEphemeralProject(root)) {
+        return false;
+    }
+    const logicalProjectId = await readLogicalProjectId(root);
+    if (logicalProjectId === undefined) {
+        return false;
+    }
+    const canonical = await getCanonicalRoot(logicalProjectId);
+    return !canonical.ok || resolve(canonical.root) !== root;
+}
+/**
+ * Resolve a stored `specPath`/`technicalPath` value against the verified canonical
+ * root, returning the realpath of the contained file. Fails closed — with a stable
+ * classified {@link PortablePathError} — for any absent, malformed, escaping,
+ * symlinked, or cross-spec value, before any content is read or written.
+ */
+export async function resolvePortableSpecPath(specId, storedPath, canonicalRoot) {
+    const suffix = toPortableSpecPath(specId, storedPath);
+    const root = resolve(canonicalRoot);
+    const candidate = resolve(root, suffix);
+    if (rejectsRootEscape(root, candidate)) {
+        throw new PortablePathError('ESCAPES_ROOT', '[Planu] specPath escapes the canonical root');
+    }
+    const rootReal = await realpathClassified(root, 'ROOT_NOT_FOUND');
+    let candidateReal;
+    let candidateStat;
+    try {
+        candidateReal = await realpathClassified(candidate, 'NOT_FOUND');
+        candidateStat = await lstat(candidate);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            throw new PortablePathError('NOT_FOUND', '[Planu] spec file not found under canonical root');
+        }
+        throw error;
+    }
+    if (candidateStat.isSymbolicLink()) {
+        throw new PortablePathError('SYMLINK', '[Planu] specPath must not resolve through a symlink');
+    }
+    if (!candidateStat.isFile()) {
+        throw new PortablePathError('NOT_FILE', '[Planu] specPath must resolve to a regular file');
+    }
+    if (rejectsRootEscape(rootReal, candidateReal)) {
+        throw new PortablePathError('ESCAPES_ROOT', '[Planu] specPath escapes the canonical root');
+    }
+    return candidateReal;
+}
+/**
+ * Lifecycle-consumer entry point: verify the candidate root against the
+ * global project registry before resolving through it, so an unregistered,
+ * ambiguous, or stale checkout never stands in for the real canonical root.
+ * Delegates to {@link resolvePortableSpecPath} once verified.
+ */
+export async function resolveVerifiedSpecPath(specId, storedPath, canonicalRoot) {
+    if (await rejectsUnverifiedRoot(resolve(canonicalRoot))) {
+        throw new PortablePathError('ROOT_UNVERIFIED', '[Planu] canonical root is not the single registry-confirmed root for this project');
+    }
+    return resolvePortableSpecPath(specId, storedPath, canonicalRoot);
+}
 /** Explicitly turn a copied project into an independent logical project. */
 export async function forkProjectIdentity(projectPath, options) {
     const canonicalProjectPath = await canonicalizeProjectPath(projectPath);

package/dist/storage/project-resolver.js

@@ -2,27 +2,11 @@
 // Resolves a project from its data directory OR from disk fingerprints (planu/ + specs/).
 // Used by planu_status, challenge_spec, and snapshot_spec_hashes to avoid "Project not found"
 // when the knowledge entry is missing but the project clearly exists on disk.
-import { access } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getKnowledge, saveKnowledge } from './knowledge-store/knowledge.js';
 import { hashProjectPath, projectDataDir } from './base-store.js';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
-/**
- * Check whether a file/directory path exists on disk (no-throw helper).
- */
-async function pathExists(p) {
-    try {
-        await access(p);
-        return true;
-    }
-    catch (error) {
-        if (error.code === 'ENOENT' ||
-            (error instanceof Error && error.message === 'ENOENT')) {
-            return false;
-        }
-        throw error;
-    }
-}
+import { pathExistsStrict as pathExists } from '../core/shared/fs.js';
 /**
  * Resolve a project from its projectPath.
  *

package/dist/storage/runtime-db.d.ts

@@ -1,4 +1,6 @@
+import { DURABLE_JOB_STATES, type DurableJobRecord, type DurableJobState } from '../types/durable-job.js';
 import { type ValidationReceiptCheckpointLimits } from '../types/durable-validation.js';
+export { DURABLE_JOB_STATES, type DurableJobRecord, type DurableJobState };
 /** Count-only process diagnostic for deterministic resource lifecycle tests. */
 export declare function getRuntimeDatabaseDiagnosticsForTests(): {
     readonly openConnections: number;
@@ -50,26 +52,6 @@ export interface RuntimeProjectBundle {
     readonly outbox: readonly Record<string, unknown>[];
     readonly audit: readonly Record<string, unknown>[];
 }
-export declare const DURABLE_JOB_STATES: readonly ['accepted', 'running', 'checkpointed', 'cancelled', 'failed', 'dead-letter', 'completed'];
-export type DurableJobState = (typeof DURABLE_JOB_STATES)[number];
-export interface DurableJobRecord {
-    readonly id: string;
-    readonly projectId: string;
-    readonly workspaceId: string;
-    readonly state: DurableJobState;
-    readonly payload: unknown;
-    readonly checkpoint?: unknown;
-    readonly result?: unknown;
-    readonly error?: string;
-    readonly attempts: number;
-    readonly maxAttempts: number;
-    readonly cancelRequested: boolean;
-    readonly leaseOwner?: string;
-    readonly leaseExpiresAt?: string;
-    readonly fencingToken: number;
-    readonly createdAt: string;
-    readonly updatedAt: string;
-}
 export interface JobLeaseInput {
     readonly id: string;
     readonly projectId: string;

package/dist/storage/runtime-db.js

@@ -2,7 +2,9 @@
 import { mkdirSync } from 'node:fs';
 import { dirname, isAbsolute, resolve } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
+import { DURABLE_JOB_STATES, } from '../types/durable-job.js';
 import { parseValidationReceiptPendingCheckpoint, } from '../types/durable-validation.js';
+export { DURABLE_JOB_STATES };
 const CURRENT_SCHEMA_VERSION = 4;
 const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
 const DEFAULT_MAX_CONNECTIONS = 4;
@@ -47,15 +49,6 @@ export function getRuntimeDatabaseDiagnosticsForTests() {
     }
     return { openConnections: count, integrityCheckedOpens, integrityBypassedOpens };
 }
-export const DURABLE_JOB_STATES = [
-    'accepted',
-    'running',
-    'checkpointed',
-    'cancelled',
-    'failed',
-    'dead-letter',
-    'completed',
-];
 export class RuntimeDatabaseCorruptionError extends Error {
     databasePath;
     detail;

package/dist/storage/semantic-index-store.js

@@ -6,6 +6,7 @@
 import { createHash } from 'node:crypto';
 import { readJson, writeJson, projectDataDir } from './base-store.js';
 import { withFileLock } from './file-mutex.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { TFIDFEngine, TFIDF_SCHEMA_VERSION, tokenize } from '../engine/vector-store/tfidf.js';
 function hashContent(content) {
     return createHash('sha256').update(content).digest('hex');