@productbrain/cli 0.1.0-beta.109 → 0.1.0-beta.1096

package/dist/commands/handshake.js

@@ -2,8 +2,8 @@
  * pb handshake — generate context files for AI developer tools.
  * Context export wiring (read-only filesystem bridge; GLO-63, DEC-161) — not a product surface.
  */
-import { mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync, copyFileSync, appendFileSync, unlinkSync, statSync } from 'fs';
-import { join, dirname, resolve, basename } from 'path';
+import { mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync, copyFileSync, appendFileSync, unlinkSync, statSync, renameSync, rmSync, realpathSync } from 'fs';
+import { join, dirname, resolve, basename, relative, sep, isAbsolute } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
@@ -21,6 +21,8 @@ import { generateChainRules } from '../generators/chain-rules.js';
 import { saveHandshakeState, loadPreviousState, diffHandshakeState, formatDiff, buildCurrentState, } from '../generators/handshake-diff.js';
 import { resolveSurfaceProfile } from '../generators/surface-profiles.js';
 import { formatHandshakeReport } from '../formatters/handshake.js';
+import { classifyAdapterFile, detectEol, spliceAppend, spliceReplace } from '../generators/region.js';
+import { REGION_PROJECTIONS } from '../generators/region-projections.js';
 import { readManifest, readManifestStatus, filterByAdoptionState } from '../generators/manifest.js';
 import { generateBoundaryManifest, getBoundaryEnforcementMode } from '../generators/boundary-manifest.js';
 import { loadMethodRegistry } from '../lib/method-registry.js';
@@ -89,6 +91,71 @@ export function writeDormantMarkerToFile(filePath) {
     appendFileSync(filePath, `\n${DORMANT_MARKER}\n`);
     return 'written';
 }
+/**
+ * renameSurfaceForDormancy — rename a projected surface file to `<path>.dormant`
+ * so external scanners (which glob *.md / *.mdc) stop loading it. WP-426 E4.
+ * The HTML-comment marker is invisible to scanners; the extension change removes
+ * the file from their glob set. Only touches files carrying the auto-gen MARKER.
+ * Runs on an INDEPENDENT existence check (not gated on marker-write result) so
+ * legacy WP-379 marker-only files still rename. Idempotent.
+ * Codex P1: when a .dormant already exists, only replace it if its body matches the
+ * live file. A divergent .dormant (user edited it) is preserved and reported as 'drift'
+ * rather than force-deleted — no silent data loss.
+ * @returns 'renamed' | 'replaced' | 'already-dormant' | 'skipped' | 'drift'
+ */
+export function renameSurfaceForDormancy(filePath) {
+    const dormantPath = `${filePath}.dormant`;
+    if (!existsSync(filePath))
+        return existsSync(dormantPath) ? 'already-dormant' : 'skipped';
+    if (!readFileSync(filePath, 'utf8').includes(MARKER))
+        return 'skipped';
+    const replacing = existsSync(dormantPath);
+    if (replacing) {
+        // Codex P1: the existing .dormant may carry user edits (e.g. the user reactivated to
+        // the live path but kept an edited dormant sibling). Compare normalized bodies
+        // (DORMANT_MARKER + volatile auto-gen timestamp stripped from both); if they diverge,
+        // preserve the .dormant and signal drift instead of force-replacing it.
+        const strip = (s) => normalizeHandshakeContentForComparison(s.split(DORMANT_MARKER).join('')).trimEnd();
+        if (strip(readFileSync(filePath, 'utf8')) !== strip(readFileSync(dormantPath, 'utf8'))) {
+            return 'drift';
+        }
+        rmSync(dormantPath, { force: true });
+    }
+    renameSync(filePath, dormantPath);
+    return replacing ? 'replaced' : 'renamed';
+}
+/**
+ * restoreSurfaceFromDormant — clean the orphan `<path>.dormant` sibling after a
+ * raised (observe→project) asset has been re-projected fresh from the DB body by
+ * the normal write loop. WP-426 E4.
+ * Normalizes the volatile auto-gen timestamp (via normalizeHandshakeContentForComparison)
+ * before comparing, else the lowering-time timestamp would always force a false
+ * 'orphan-drift'. Identical body → remove. Differs (user edited) → preserve + drift.
+ * @returns 'restored' | 'orphan-drift' | 'skipped'
+ */
+export function restoreSurfaceFromDormant(filePath) {
+    const dormantPath = `${filePath}.dormant`;
+    if (!existsSync(dormantPath))
+        return 'skipped';
+    // WP-426 E4: no fresh live projection this run (surface filtered / user-owned / not written) →
+    // nothing to reconcile; absence of fresh is NOT evidence of a user edit. Leave the .dormant.
+    if (!existsSync(filePath))
+        return 'skipped';
+    const fresh = readFileSync(filePath, 'utf8');
+    // Codex P2: only reconcile against a PB-managed projection. A live file WITHOUT the auto-gen
+    // MARKER is a user-owned file (shouldWriteAdapter would have skipped reprojecting it),
+    // so it was NOT raised this run — comparing the .dormant against it would wrongly delete it or
+    // re-fire "edited while dormant" drift. Leave the .dormant untouched.
+    if (!fresh.includes(MARKER))
+        return 'skipped';
+    const dormant = readFileSync(dormantPath, 'utf8').split(DORMANT_MARKER).join('');
+    const norm = (s) => normalizeHandshakeContentForComparison(s).trimEnd();
+    if (norm(dormant) === norm(fresh)) {
+        rmSync(dormantPath, { force: true });
+        return 'restored';
+    }
+    return 'orphan-drift';
+}
 /**
  * deriveDormantFilePaths — compute the set of on-disk file paths that would have
  * been projected for a given dormant asset (by name and assetKind).
@@ -100,7 +167,8 @@ export function writeDormantMarkerToFile(filePath) {
  *
  * @param asset  The dormant asset from the server.
  * @param cwd    Current working directory (project root).
- * @returns      Array of absolute file paths to probe.
+ * @returns      Each candidate path paired with its owning surface, so callers can
+ *               filter by the run's allowedTargets (--surfaces) and the perimeter.
  */
 function deriveDormantFilePaths(asset, cwd) {
     // Defense-in-depth: even though `name` originates from platform-seeded DB
@@ -110,26 +178,22 @@ function deriveDormantFilePaths(asset, cwd) {
     if (!/^[A-Za-z0-9 ._-]+$/.test(asset.name)) {
         return [];
     }
-    const paths = [];
+    const out = [];
     const { name, assetKind } = asset;
     if (assetKind === 'skill') {
-        // Cursor skill
-        paths.push(join(cwd, '.cursor', 'skills', name, 'SKILL.md'));
-        // Codex skill
-        paths.push(join(cwd, '.codex', 'skills', `${name}.md`));
+        out.push({ path: join(cwd, '.cursor', 'skills', name, 'SKILL.md'), surface: 'cursor' });
+        out.push({ path: join(cwd, '.codex', 'skills', `${name}.md`), surface: 'codex' });
     }
     else if (assetKind === 'rule' || assetKind === 'hook') {
-        // Cursor rule
-        paths.push(join(cwd, '.cursor', 'rules', `${name}.mdc`));
-        // Claude rule
-        paths.push(join(cwd, '.claude', 'rules', `${name}.md`));
+        out.push({ path: join(cwd, '.cursor', 'rules', `${name}.mdc`), surface: 'cursor' });
+        out.push({ path: join(cwd, '.claude', 'rules', `${name}.md`), surface: 'claude' });
     }
-    return paths;
+    return out;
 }
 /**
  * Single-shot health probe — calls `workspace.health` and inspects
  * `starterSetupSeeded`. Does NOT poll internally; polling is the caller's
- * responsibility (connect-screens.tsx).
+ * responsibility (connect-context.ts).
  *
  * Returns:
  *  - `seeds-ready`   — health query succeeded AND starterSetupSeeded is true
@@ -165,7 +229,7 @@ export async function probeStarterSetupSeeded() {
  * Poll `probeStarterSetupSeeded` up to MAX_POLLS times (10s at 500ms intervals).
  * Returns the final probe result — caller decides how to render the outcome.
  *
- * Exported so connect-screens.tsx can use it without re-implementing the loop.
+ * Exported so connect-context.ts can use it without re-implementing the loop.
  */
 export async function pollUntilSeedsReady() {
     for (let poll = 0; poll < MAX_POLLS; poll++) {
@@ -557,6 +621,28 @@ function setupAuthoringPath(cwd, asset) {
     const dir = setupAuthoringDirForKind(asset.assetKind);
     if (!dir)
         return null;
+    // WP-426 E3: recorded authoring source path wins so reprojection lands where the
+    // user authored — no duplicate (TEN-1920). Stored relative to .productbrain/.
+    if (asset.authoringPath && asset.authoringPath.trim()) {
+        // Codex P1/P2: authoringPath comes from the DB and is untrusted at projection
+        // time. It is probed via existsSync/readFileSync (and later writeFileSync) in the
+        // writeback loop BEFORE any assertSetupWritePath guard runs. Containment alone is
+        // not enough — a bad DB row could still point at a directory (e.g. "skills") or an
+        // internal PB file (".authoring-sync.json", "manifest.yaml"), which the loop would
+        // mis-handle as markdown (throw on a directory read, or overwrite PB state).
+        // Constrain to a kind-appropriate markdown file (<dir>/**/*.md); otherwise fall
+        // back to the safe name-derived path.
+        const pbDir = join(cwd, '.productbrain');
+        const candidate = resolve(pbDir, asset.authoringPath);
+        const within = relative(pbDir, candidate);
+        const withinPosix = within.split(sep).join('/');
+        if (!within.startsWith('..') &&
+            !isAbsolute(within) &&
+            withinPosix.startsWith(`${dir}/`) &&
+            withinPosix.toLowerCase().endsWith('.md')) {
+            return candidate;
+        }
+    }
     return join(cwd, '.productbrain', dir, setupAuthoringFilename(asset.name, asset.entryId));
 }
 function renderSetupAuthoringFile(asset) {
@@ -588,7 +674,17 @@ function loadAuthoringSyncState(productbrainDir) {
         if (parsed.version !== 1 || !parsed.assets || typeof parsed.assets !== 'object') {
             return { version: 1, assets: {} };
         }
-        return { version: 1, assets: parsed.assets };
+        // Codex P2: the dormant registries are consumed via .includes() in the dormant loop
+        // BEFORE its per-file try/catch, so a malformed .authoring-sync.json (a field set to
+        // an object/number instead of an array) would throw a TypeError and abort the whole
+        // handshake. Coerce to a string[] (mirrors the assets validation above) to fail open.
+        const toStringArray = (v) => Array.isArray(v) ? v.filter((x) => typeof x === 'string') : [];
+        return {
+            version: 1,
+            assets: parsed.assets,
+            dormantRenamed: toStringArray(parsed.dormantRenamed),
+            dormantReactivated: toStringArray(parsed.dormantReactivated),
+        };
     }
     catch {
         return { version: 1, assets: {} };
@@ -624,7 +720,7 @@ export function classifyDriftBucket(filePath) {
         return { bucket: 'user-owned', expectedHash: '', actualHash: '' };
     }
     // Marker present but no hash trailer → legacy / pre-S0c projection: treat as
-    // clean (the hash trailer was added in WP-345 S0c). The forked-vs-clean
+    // clean (the hash trailer was added in WP-345 S0c). The user-owned-vs-clean
     // semantic falls back to existing shouldWriteAdapter behavior.
     const trailerMatch = content.match(DRIFT_HASH_TRAILER_REGEX);
     if (!trailerMatch) {
@@ -664,7 +760,7 @@ function deduplicateEntries(entries) {
  * the auto-gen MARKER whose lowercase-normalized filename does NOT match any
  * current active-asset materializedFilename, the file is unlinked.
  *
- * User-forked files (no MARKER) are never touched, regardless of name.
+ * User-owned files (no MARKER) are never touched, regardless of name.
  *
  * Linux case-collision disambiguation:
  *   1. Exact match (lowercase name == any canonical name): survives.
@@ -722,7 +818,7 @@ export function resolveProjectionCollision(cwd, assetNames, log, logErr) {
                 continue; // unreadable file — skip
             }
             if (!content.includes(MARKER))
-                continue; // user-forked — never touch
+                continue; // user-owned — never touch
             const stem = basename(filename, ext);
             const normalizedStem = normalizeMaterializedFilename(stem);
             const group = groups.get(normalizedStem) ?? [];
@@ -815,9 +911,9 @@ export function resolveProjectionCollision(cwd, assetNames, log, logErr) {
     return { results, collisionTens };
 }
 export async function runHandshake(options = {}) {
-    const config = await getConfigOrGuide(() => runHandshake(options));
+    const config = await getConfigOrGuide(async () => { await runHandshake(options); });
     if (!config)
-        return;
+        return undefined;
     const cwd = process.cwd();
     const force = options.force ?? false;
     const dryRun = options.dryRun ?? false;
@@ -944,9 +1040,6 @@ export async function runHandshake(options = {}) {
     // Hoisted here (same scope as dbAssetRows) so both the skills/rules projection loop
     // AND the authoring-file projection loop can skip failed assets.
     const bodyFetchFailedEntryIds = new Set();
-    // WP-379 S5b: whether any setup_receipt exists for this workspace (first-run UX gate).
-    // undefined when server is pre-S5b (treat as unknown → suppress drift TENs conservatively).
-    let hasAnyReceipt = undefined;
     const dbProjectionHashes = new Map();
     const syncDriftTensToFire = [];
     const deferredAuthoringBaselineEntryIds = new Set();
@@ -995,6 +1088,7 @@ export async function runHandshake(options = {}) {
                                 assetKind: item.assetKind,
                                 triggers: item.triggers,
                                 semanticRefs: item.semanticRefs,
+                                authoringPath: relative(pbDir, item.filePath).split(sep).join('/'),
                             });
                             return { filePath: item.filePath, ...result };
                         }));
@@ -1034,14 +1128,10 @@ export async function runHandshake(options = {}) {
                 // Pre-S4 server — treat entire response as active assets with no dormant list.
                 dbAssets = rawResponse;
                 dormantDbAssetRows = [];
-                hasAnyReceipt = undefined; // unknown on legacy servers
             }
             else {
                 dbAssets = rawResponse.activeAssets ?? [];
                 dormantDbAssetRows = rawResponse.dormantAssets ?? [];
-                // WP-379 S5b: extract hasAnyReceipt when provided by the server.
-                // undefined means pre-S5b server — we treat as unknown (no receipts assumed).
-                hasAnyReceipt = rawResponse.hasAnyReceipt;
             }
         }
         if (dbAssets.length > 0) {
@@ -1073,7 +1163,19 @@ export async function runHandshake(options = {}) {
                     }
                 }
                 if (bodyFetchFailedEntryIds.size > 0) {
-                    logErr(`${bodyFetchFailedEntryIds.size} asset(s) skipped due to body fetch failure: ${[...bodyFetchFailedEntryIds].join(', ')}`);
+                    // WP-439 S4: strict-by-default. Any body-fetch failure is a hard
+                    // failure unless --lenient is passed. The strict path surfaces an
+                    // actionable pointer at the audit/repair command operators can run
+                    // to diagnose and fix orphaned setup-asset rows.
+                    const failedList = [...bodyFetchFailedEntryIds].join(', ');
+                    if (options.lenient) {
+                        logErr(`Warning: ${bodyFetchFailedEntryIds.size} asset(s) skipped due to body fetch failure (--lenient): ${failedList}`);
+                    }
+                    else {
+                        throw new CLIError(`${bodyFetchFailedEntryIds.size} asset(s) failed body fetch: ${failedList}. ` +
+                            `Run \`pb setup-audit\` to diagnose, then \`pb setup-audit --repair\` to reseed. ` +
+                            `Pass --lenient to suppress this and continue with affected entries skipped (legacy behaviour).`, { code: ErrorCode.INTERNAL, category: 'internal' });
+                    }
                 }
             }
             // Map DB assets to CanonicalSkill/CanonicalRule shapes
@@ -1406,7 +1508,9 @@ export async function runHandshake(options = {}) {
             const authoringPath = setupAuthoringPath(cwd, asset);
             if (!authoringPath)
                 continue;
-            const relativeAuthoringPath = authoringPath.replace(cwd + '/', '');
+            // Review: use relative() for correct cross-platform path computation (string-replace
+            // mis-fires when cwd uses a non-'/' separator), matching the dormant passes below.
+            const relativeAuthoringPath = relative(cwd, authoringPath);
             const bodyHash = setupAuthoringAssetHash(asset);
             const authoringExists = existsSync(authoringPath);
             const tracked = authoringSyncState.assets[asset.entryId];
@@ -1506,8 +1610,8 @@ export async function runHandshake(options = {}) {
     const writes = [
         ...(contextContent ? [{ path: join(cwd, '.productbrain', 'context.md'), relative: '.productbrain/context.md', content: contextContent, dirs: join(cwd, '.productbrain'), isAdapter: false }] : []),
         { path: join(cwd, '.productbrain', 'briefing.md'), relative: '.productbrain/briefing.md', content: briefingContent, isAdapter: false },
-        { path: join(cwd, 'AGENTS.md'), relative: 'AGENTS.md', content: agentsContent, isAdapter: true, target: 'codex' },
-        { path: join(cwd, 'CLAUDE.md'), relative: 'CLAUDE.md', content: claudeContent, isAdapter: true, target: 'claude' },
+        { path: join(cwd, 'AGENTS.md'), relative: 'AGENTS.md', content: agentsContent, isAdapter: true, target: 'codex', augmentTarget: true },
+        { path: join(cwd, 'CLAUDE.md'), relative: 'CLAUDE.md', content: claudeContent, isAdapter: true, target: 'claude', augmentTarget: true },
         { path: join(cwd, '.cursor', 'rules', 'chain.mdc'), relative: '.cursor/rules/chain.mdc', content: cursorContent, dirs: join(cwd, '.cursor', 'rules'), isAdapter: true, target: 'cursor' },
         { path: join(cwd, '.github', 'copilot-instructions.md'), relative: '.github/copilot-instructions.md', content: copilotContent, dirs: join(cwd, '.github'), isAdapter: true, target: 'copilot' },
         ...(boundaryManifestContent ? [{
@@ -1638,7 +1742,7 @@ export async function runHandshake(options = {}) {
             return null; // fail-open
         }
     });
-    const forkedPaths = [];
+    const userOwnedSkipped = [];
     const projectedHashUpdates = new Map();
     const cleanBucketPaths = [];
     const tamperedBucket = [];
@@ -1651,6 +1755,29 @@ export async function runHandshake(options = {}) {
         if (projection)
             projectedHashUpdates.set(entryId, projection.hash);
     };
+    // TEN-2155: region augmentation context + symlink dedupe.
+    // codexActive gates the AGENTS.md skills-index pointer (region-projections.ts).
+    const regionCtx = { codexActive: allowedTargets.has('codex') };
+    const malformedRegionPaths = [];
+    // If two augment targets resolve to the same inode (e.g. CLAUDE.md symlinked to AGENTS.md),
+    // augment only the first-seen (AGENTS.md precedes CLAUDE.md in `writes`) to avoid double-injection.
+    const seenAugmentRealpaths = new Set();
+    const augmentTargetSkip = new Set();
+    for (const w of writes) {
+        if (!w.augmentTarget || !w.target || !allowedTargets.has(w.target) || !existsSync(w.path))
+            continue;
+        let real;
+        try {
+            real = realpathSync(w.path);
+        }
+        catch {
+            real = w.path;
+        }
+        if (seenAugmentRealpaths.has(real))
+            augmentTargetSkip.add(w.path);
+        else
+            seenAugmentRealpaths.add(real);
+    }
     for (const w of writes) {
         // Surface filtering: skip adapter writes for targets not in the allowed set
         if (w.target && !allowedTargets.has(w.target)) {
@@ -1659,13 +1786,78 @@ export async function runHandshake(options = {}) {
                 previewPlan.push({ path: w.relative, status: 'filtered' });
             continue;
         }
+        // ── TEN-2155: augment user-owned CLAUDE.md / AGENTS.md with a marked PB region ──
+        // Runs ahead of the legacy MARKER-keyed gates. Only existing augmentable/region-present
+        // files are spliced here; absent + legacy-pb-managed fall through to the legacy path.
+        if (w.augmentTarget) {
+            const projection = REGION_PROJECTIONS[w.target];
+            if (projection && existsSync(w.path)) {
+                if (augmentTargetSkip.has(w.path)) {
+                    filesSkipped.push({ path: w.relative, reason: 'symlinked to another augment target — augmented once' });
+                    continue;
+                }
+                const disk = readFileSync(w.path, 'utf8');
+                const cls = classifyAdapterFile(disk);
+                if (cls === 'augmentable' || cls === 'region-present') {
+                    const eol = detectEol(disk);
+                    const region = replaceVocabTokens(projection.build(regionCtx, eol), handshakeVocabCtx);
+                    // Defense-in-depth: the composed region (post vocab-token resolution) must itself be a
+                    // single well-formed region. v1 content has no vocab tokens so this is a no-op, but it
+                    // guards the documented future override/vocab seam from injecting a stray sentinel/MARKER.
+                    if (classifyAdapterFile(region) !== 'region-present') {
+                        filesSkipped.push({ path: w.relative, reason: 'internal: composed PB region malformed — skipped to protect your file' });
+                        if (preview)
+                            previewPlan.push({ path: w.relative, status: 'needs-attention' });
+                        continue;
+                    }
+                    const candidate = cls === 'augmentable' ? spliceAppend(disk, region, eol) : spliceReplace(disk, region);
+                    if (candidate === disk) {
+                        filesSkipped.push({ path: w.relative, reason: 'unchanged' });
+                        if (preview)
+                            previewPlan.push({ path: w.relative, status: 'unchanged' });
+                        continue;
+                    }
+                    if (preview || dryRun) {
+                        filesWritten.push(w.relative + (dryRun ? ' (dry run)' : ''));
+                        if (preview)
+                            previewPlan.push({ path: w.relative, status: 'would-augment' });
+                        continue;
+                    }
+                    if (authorityPreviewOnly) {
+                        // apply + materialize observe/off: honor authority — do NOT write; mirror the legacy
+                        // preview-only skip so the report does not falsely list it as written.
+                        filesSkipped.push({ path: w.relative, reason: `preview-only (materialize: ${manifestStatus.mode})` });
+                        continue;
+                    }
+                    assertSetupWritePath(w.path, perimeterManifest);
+                    writeFileSync(w.path, candidate);
+                    filesWritten.push(w.relative);
+                    continue;
+                }
+                if (cls === 'malformed') {
+                    filesSkipped.push({ path: w.relative, reason: 'malformed PB region — left untouched; fix the pb:region sentinels' });
+                    if (preview)
+                        previewPlan.push({ path: w.relative, status: 'needs-attention' });
+                    malformedRegionPaths.push(w.relative);
+                    continue;
+                }
+                // cls 'pb-managed' → fall through to the legacy whole-file re-projection path below.
+                // cls 'opt-out' (file carries the pb:no-augment sentinel — e.g. this repo's committed
+                // constitution) → fall through too, landing on the legacy user-owned skip: left untouched,
+                // never spliced. This is how a file declines augmentation without losing its user-owned status.
+            }
+            // absent file → fall through to legacy whole-file CREATE.
+        }
         if (w.isAdapter && !shouldWriteAdapter(w.path, force)) {
-            filesSkipped.push({ path: w.relative, reason: 'exists without auto-generated marker (use --force to overwrite)' });
+            // User-owned: a file at an adapter path without our auto-gen MARKER is the
+            // user's own file. Leave it untouched — never overwrite, never treat as drift
+            // or log a TEN (TEN-2150). Relayed to the connect screen via userOwnedSkipped.
+            filesSkipped.push({ path: w.relative, reason: 'user-owned — left untouched (pb won\'t overwrite your file)' });
             if (preview) {
-                previewPlan.push({ path: w.relative, status: 'forked' });
+                previewPlan.push({ path: w.relative, status: 'user-owned' });
             }
             else {
-                forkedPaths.push(w.relative);
+                userOwnedSkipped.push(w.relative);
             }
             continue;
         }
@@ -1762,6 +1954,20 @@ export async function runHandshake(options = {}) {
             }
         });
     }
+    // Ordering note: this refusal runs AFTER the projected-hash flush so that files legitimately
+    // written THIS run still record their hashes; malformed files were never written (no hash to record).
+    // TEN-2155: in non-interactive apply, a malformed PB region is a refusal, not a silent skip.
+    // Gated on applyMode (NOT writeMode): a malformed region is a user-file INTEGRITY fault, so the
+    // refusal fires on any headless `--apply` regardless of materialize authority (STD-263 invariant vi —
+    // "headless → non-zero refusal", unqualified). writeMode would suppress it under observe/off, where
+    // the malformed file still gets enumerated but the corruption signal would be silently dropped.
+    if (applyMode && malformedRegionPaths.length > 0 && (options.noPrompt || !process.stdout.isTTY)) {
+        throw new CLIError(`Malformed PB region in: ${malformedRegionPaths.join(', ')}`, {
+            code: ErrorCode.VALIDATION_FAILED,
+            category: 'validation',
+            guidance: 'Fix the `<!-- pb:region:start -->` / `<!-- pb:region:end -->` sentinels (one balanced pair), then re-run `pb handshake`.',
+        });
+    }
     // ── WP-421 S3: tampered-bucket resolution (doneWhen #17) ────────────────────
     // Apply mode only. Tampered files were DEFERRED in the write loop above;
     // here we either prompt the user (interactive TTY) or refuse (headless).
@@ -1836,7 +2042,7 @@ export async function runHandshake(options = {}) {
                     personalSkillCount: personalSkills.length > 0 ? personalSkills.length : undefined,
                     registrySource,
                     registryStale,
-                    driftConflicts: forkedPaths.length > 0 ? forkedPaths : undefined,
+                    userOwnedSkipped: userOwnedSkipped.length > 0 ? userOwnedSkipped : undefined,
                     managedCleanCount: cleanBucketPaths.length || undefined,
                     tamperedFiles: refusedTamperedFiles,
                 }) + '\n');
@@ -1921,7 +2127,8 @@ export async function runHandshake(options = {}) {
                     await caller('setup.ingestSetupAsset', {
                         entryId: `SETUP-ADOPTED-${Date.now()}-${draftName.replace(/\s+/g, '-')}`,
                         name: draftName,
-                        description: `Adopted from tampered projection at ${tamper.relative} (WP-421 S3).`,
+                        // WP-421 S3
+                        description: `Adopted from tampered projection at ${tamper.relative}.`,
                         body: tamperedContent,
                         assetKind: tamper.relative.includes('/skills/') ? 'skill' : 'rule',
                         triggers: [],
@@ -1940,79 +2147,162 @@ export async function runHandshake(options = {}) {
             }
         }
     }
-    // 8a. Dormant marker writes (WP-379 S4) — apply mode only.
-    // For each dormant asset (gate-filtered by the server), locate any previously-projected
-    // on-disk files and append the DORMANT_MARKER trailer. Files are NOT deleted.
-    //
-    // Drift TEN exclusion: dormant-marked files have the auto-gen MARKER, so
-    // shouldWriteAdapter() returns true for them. However, because the asset is dormant,
-    // it is NOT in the `writes` array — it was never queued for a fresh write. Therefore,
-    // dormant files will never appear in forkedPaths (forkedPaths only catches files that
-    // ARE in the writes array but fail shouldWriteAdapter). The dormant marker write is a
-    // separate, independent pass that runs BEFORE the drift TEN check — intentionally
-    // after the main write loop to avoid interfering with active asset writes.
-    //
-    // Fail-open: if a dormant marker write fails, log and continue. Never crash the handshake.
+    // 8a. Dormant marker + .dormant rename (WP-379 S4 + WP-426 E4) — apply mode only.
     const dormantMarkedPaths = [];
     if (writeMode && dormantDbAssetRows.length > 0) {
+        const dormantState = loadAuthoringSyncState(pbDir);
+        let dormantStateChanged = false;
         for (const dormantAsset of dormantDbAssetRows) {
-            const candidatePaths = deriveDormantFilePaths(dormantAsset, cwd);
-            for (const filePath of candidatePaths) {
+            for (const { path: filePath, surface } of deriveDormantFilePaths(dormantAsset, cwd)) {
+                // Codex P2: deriveDormantFilePaths emits every known surface path. Honor the run's
+                // target set (allowedTargets = the --surfaces selection, else all manifest surfaces)
+                // so a `--surfaces cursor` run never renames .claude/.codex to .dormant, and surfaces
+                // outside the manifest are skipped silently (no false "could not dormant-mark" warning).
+                if (!allowedTargets.has(surface))
+                    continue;
+                // FIX 4: use relative() instead of string-replace for correct cross-platform behaviour.
+                const rel = relative(cwd, filePath);
+                const alreadyReactivated = dormantState.dormantReactivated?.includes(rel) ?? false;
+                const previouslyRenamed = dormantState.dormantRenamed?.includes(rel) ?? false;
                 try {
                     assertSetupWritePath(filePath, perimeterManifest);
+                    // WP-426 E4: BUG 1 fix — hands-off set.
+                    //
+                    // Step 1: permanently hands-off — user already reactivated this path on a
+                    //   prior run. Skip silently every time until they re-lower or raise in PB.
+                    //   (Task 7 raise-cleanup must later also prune dormantReactivated for raised
+                    //   assets — see the `dormantReactivated` comment on AuthoringSyncState.)
+                    if (alreadyReactivated) {
+                        continue; // leave file untouched; no TEN (already fired on first detection)
+                    }
+                    // Step 2: FIRST detection of manual reactivation — we previously renamed
+                    //   this to .dormant but the user renamed it back to a live file. Push the
+                    //   drift TEN exactly once, add to the permanent hands-off set, remove from
+                    //   dormantRenamed, leave file untouched.
+                    if (previouslyRenamed && existsSync(filePath) && !existsSync(`${filePath}.dormant`)) {
+                        syncDriftTensToFire.push(`Dormant asset ${dormantAsset.entryId} was manually reactivated at ${rel}; left untouched. Re-lower or raise it in PB to resync.`);
+                        logErr(`Warning: ${rel} was manually un-dormanted; leaving it in place (drift).`);
+                        dormantState.dormantReactivated = [...(dormantState.dormantReactivated ?? []), rel];
+                        dormantState.dormantRenamed = (dormantState.dormantRenamed ?? []).filter((p) => p !== rel);
+                        dormantStateChanged = true;
+                        continue;
+                    }
+                    // Step 3: normal lowering — write dormant marker + rename to .dormant.
+                    // WP-426 E4 spec: every rename TARGET must also pass the perimeter guard.
+                    // Check the post-rename .dormant path BEFORE any FS mutation, so a guard
+                    // failure can't leave a half-dormant file (marker appended but not renamed).
+                    assertSetupWritePath(`${filePath}.dormant`, perimeterManifest);
                     const markerResult = writeDormantMarkerToFile(filePath);
-                    if (markerResult === 'written') {
-                        dormantMarkedPaths.push(filePath);
+                    if (markerResult === 'written')
                         log(`Dormant marker written: ${filePath}`);
+                    const renameResult = renameSurfaceForDormancy(filePath);
+                    if (renameResult === 'renamed' || renameResult === 'replaced') {
+                        // dormantMarkedPaths holds post-rename .dormant paths (not the original surface paths).
+                        dormantMarkedPaths.push(`${filePath}.dormant`);
+                        if (!dormantState.dormantRenamed?.includes(rel)) {
+                            dormantState.dormantRenamed = [...(dormantState.dormantRenamed ?? []), rel];
+                            dormantStateChanged = true;
+                        }
+                        log(`Dormant rename: ${filePath} → ${filePath}.dormant`);
+                    }
+                    else if (renameResult === 'drift') {
+                        // Codex P1: an edited .dormant already exists alongside the live file. Preserve
+                        // both and flag, rather than overwriting the user's edited dormant copy.
+                        syncDriftTensToFire.push(`Edited dormant copy ${rel}.dormant diverges from the live surface for ${dormantAsset.entryId}; left both in place. Resolve manually.`);
+                        logErr(`Warning: ${rel}.dormant diverges from the live file; not replacing (possible manual edit).`);
                     }
-                    // 'already-dormant' and 'skipped' are silent no-ops — idempotent.
                 }
                 catch (err) {
-                    // Fail-open: dormant marker write is advisory. Log, never throw.
-                    logErr(`Warning: could not write dormant marker to ${filePath} — ${err instanceof Error ? err.message : String(err)}`);
+                    logErr(`Warning: could not dormant-mark ${filePath} — ${err instanceof Error ? err.message : String(err)}`);
                 }
             }
         }
+        if (dormantMarkedPaths.length > 0) {
+            log('Run `pb setup observe --purge` to remove these instead of dormant-renaming.');
+        }
+        if (dormantStateChanged) {
+            try {
+                saveAuthoringSyncState(pbDir, dormantState);
+            }
+            catch (err) {
+                logErr(`Warning: could not persist dormancy state — ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
     }
-    // 8. Drift logging — if apply mode encountered forked adapters and a session is active, log a draft TEN.
-    // Dormant-marked files are NOT forked — they were intentionally deactivated and have the auto-gen MARKER.
-    // They will never appear in forkedPaths because they are excluded from the `writes` array entirely.
-    //
-    // WP-379 S5b — First-run UX rule:
-    // When `hasAnyReceipt` is false OR undefined (unknown / pre-S5b server), drift TENs are suppressed.
-    // Rationale: on the first handshake, users may have pre-existing non-marked files from manual
-    // setup; we must not flood them with TENs before they've even had one successful materialization.
-    // A TEN fires only after setup_receipt.count >= 1 for this workspace.
-    //
-    // Conservative unknown-treatment: if the server does not provide hasAnyReceipt (old server),
-    // we treat it as "no receipt exists" and suppress the TEN. The day-1 experience is more important
-    // than catching every early drift case; the TEN will fire on the next run once the server is updated.
-    const isFirstRun = hasAnyReceipt !== true; // true when no receipts or unknown
-    if (forkedPaths.length > 0) {
-        if (isFirstRun) {
-            log(`Info: ${forkedPaths.length} adapter(s) skipped (user files without auto-gen marker). ` +
-                'Drift TEN suppressed — first run (no setup receipt yet). Files: ' +
-                forkedPaths.join(', '));
+    // 8b. Raise-cleanup (WP-426 E4): for assets active this run, drop any orphan
+    // <surface>.dormant left by a prior lowering (active surface was re-projected
+    // fresh above). User-edited dormant copies are preserved + flagged. Fail-open.
+    if (writeMode) {
+        const raiseState = loadAuthoringSyncState(pbDir);
+        let raiseStateChanged = false;
+        const dormantIds = new Set(dormantDbAssetRows.map((a) => a.entryId));
+        const activeRows = dbAssetRows.filter((a) => !dormantIds.has(a.entryId) &&
+            (a.assetKind === 'skill' || a.assetKind === 'rule' || a.assetKind === 'hook'));
+        for (const asset of activeRows) {
+            // Codex P2: if this asset's body fetch failed, the write loop did NOT reproject its
+            // surfaces this run (same skip the authoring loop applies), so there's no fresh surface
+            // to reconcile against — skip raise-cleanup to avoid acting on stale content.
+            if (bodyFetchFailedEntryIds.has(asset.entryId))
+                continue;
+            for (const { path: filePath, surface } of deriveDormantFilePaths(asset, cwd)) {
+                // Codex P2: honor the run's target set (parity with the dormant pass) — a
+                // `--surfaces cursor` run must not touch .claude/.codex .dormant files, and surfaces
+                // outside the manifest are skipped silently (no false "raise-cleanup failed" warning).
+                if (!allowedTargets.has(surface))
+                    continue;
+                const rel = relative(cwd, filePath);
+                try {
+                    assertSetupWritePath(filePath, perimeterManifest); // WP-426 E4: perimeter before any FS mutation (parity with the dormant pass)
+                    // E4 spec parity (review): restoreSurfaceFromDormant deletes the .dormant
+                    // sibling, so guard that delete TARGET too — exactly as the lowering pass
+                    // guards both filePath and ${filePath}.dormant.
+                    assertSetupWritePath(`${filePath}.dormant`, perimeterManifest);
+                    const r = restoreSurfaceFromDormant(filePath);
+                    if (r === 'restored') {
+                        log(`Raised: removed superseded ${filePath}.dormant`);
+                    }
+                    else if (r === 'orphan-drift') {
+                        syncDriftTensToFire.push(`Dormant copy ${rel}.dormant was edited while dormant for ${asset.entryId}; preserved on raise. Resolve manually.`);
+                        logErr(`Warning: ${rel}.dormant differs from the freshly raised projection; left in place.`);
+                    }
+                    // Prune the registry only when no .dormant sibling remains for this surface:
+                    //   • 'restored' removed it, or
+                    //   • it was already gone (manual .dormant→live reactivation; 'skipped', no .dormant).
+                    // Carry-over obligation (Phase 3) + Codex P1: the manual-reactivation case must
+                    // leave the hands-off set so a future lowering can re-evaluate the surface.
+                    // Codex P2: but if a .dormant STILL exists (surface-filtered 'skipped' with no
+                    // fresh live file, or a preserved 'orphan-drift'), KEEP the registry evidence —
+                    // otherwise a later manual .dormant→live reactivation would not be recognized as
+                    // previouslyRenamed and would be silently re-dormanted on the next lowering.
+                    if (!existsSync(`${filePath}.dormant`)) {
+                        if (raiseState.dormantRenamed?.includes(rel)) {
+                            raiseState.dormantRenamed = raiseState.dormantRenamed.filter((p) => p !== rel);
+                            raiseStateChanged = true;
+                        }
+                        if (raiseState.dormantReactivated?.includes(rel)) {
+                            raiseState.dormantReactivated = raiseState.dormantReactivated.filter((p) => p !== rel);
+                            raiseStateChanged = true;
+                        }
+                    }
+                }
+                catch (err) {
+                    logErr(`Warning: raise-cleanup failed for ${filePath} — ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
         }
-        else {
-            const session = readSession();
-            if (session) {
-                const names = forkedPaths.join(', ');
-                kernelCallWithSession('chain.createEntry', {
-                    collectionSlug: 'tensions',
-                    name: `TEN: handshake drift — ${forkedPaths.length} adapter(s) forked, sync blocked`,
-                    // Drift audit TENs intentionally stay draft — they need explicit human review,
-                    // not auto-commit, even in Open mode (mirrors smart-capture.ts recordCommitFailure).
-                    status: 'draft',
-                    data: {
-                        description: `pb handshake --apply encountered forked adapters that blocked sync. Files: ${names}. Use --force to overwrite or resolve drift manually.`,
-                    },
-                    sessionId: session.sessionId,
-                    createdBy: `agent:${session.sessionId}`,
-                }).catch(() => { });
+        if (raiseStateChanged) {
+            try {
+                saveAuthoringSyncState(pbDir, raiseState);
             }
+            catch { /* fail-open */ }
         }
     }
+    // 8. User-owned files left untouched are NOT drift (TEN-2150).
+    // A marker-less file at an adapter path is the user's own file: handshake never
+    // wrote it, so there is nothing to "sync" and no draft TEN is logged. These files
+    // are surfaced benignly under "Skipped:" and relayed to the connect screen via
+    // report.userOwnedSkipped. (The legitimate "tampered" and authoring-sync drift
+    // signals below are unaffected.)
     if (syncDriftTensToFire.length > 0) {
         const session = readSession();
         if (session) {
@@ -2031,10 +2321,10 @@ export async function runHandshake(options = {}) {
             }
         }
     }
-    // 8. Case-collision TENs (WP-379 S5b) — fire after the first-run gate.
+    // 8. Case-collision TENs (WP-379 S5b).
     // These are distinct from drift TENs: they record ambiguous filename collisions
-    // where the "newest mtime wins" heuristic was applied. They fire regardless of
-    // first-run status (collision is a data quality issue, not a drift issue).
+    // where the "newest mtime wins" heuristic was applied. They always fire on a
+    // detected collision (collision is a data quality issue, not a drift issue).
     if (collisionTensToFire.length > 0) {
         const session = readSession();
         if (session) {
@@ -2110,7 +2400,7 @@ export async function runHandshake(options = {}) {
         registryStale,
         preview: preview ? true : undefined,
         previewPlan: preview && previewPlan.length > 0 ? previewPlan : undefined,
-        driftConflicts: forkedPaths.length > 0 ? forkedPaths : undefined,
+        userOwnedSkipped: userOwnedSkipped.length > 0 ? userOwnedSkipped : undefined,
         // WP-421 S3: three-bucket drift report (doneWhen #17). PB-managed-clean is
         // the count of files whose marker + hash matched. Tampered files were
         // resolved (adopted/reverted) above and are reported separately.
@@ -2122,5 +2412,10 @@ export async function runHandshake(options = {}) {
         process.stdout.write('\n');
         process.stdout.write(formatHandshakeReport(report) + '\n');
     }
+    // Return the report so non-UI callers (e.g. prepareConnectContext) can surface
+    // skipped/user-owned files without re-deriving the skip logic (TEN-2107).
+    return report;
 }
+// WP-426 E3/E4: exported test-only surface (not part of the public CLI API).
+export const __test = { setupAuthoringPath, renameSurfaceForDormancy, restoreSurfaceFromDormant, loadAuthoringSyncState, MARKER };
 //# sourceMappingURL=handshake.js.map