@productbrain/cli 0.1.0-beta.95 → 0.1.0-beta.958

package/dist/commands/handshake.js

@@ -1,14 +1,14 @@
 /**
  * pb handshake — generate context files for AI developer tools.
- * The fourth delivery surface: context export (GLO-63, DEC-161).
+ * Context export wiring (read-only filesystem bridge; GLO-63, DEC-161) — not a product surface.
  */
-import { mkdirSync, writeFileSync, existsSync, readFileSync, readdirSync, copyFileSync } from 'fs';
-import { join, dirname, resolve } 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';
 import { getConfigOrGuide } from '../lib/config.js';
-import { select as promptSelect } from '../lib/prompts.js';
+import { select as promptSelect, confirm as promptConfirm } from '../lib/prompts.js';
 import { composeHooksFromIntents, getHookStatusForSurface } from '../lib/hook-intents.js';
 import { kernelCall, kernelCallWithSession } from '../lib/client.js';
 import { readSession } from '../lib/session.js';
@@ -21,10 +21,231 @@ 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 { readManifest, filterByAdoptionState } from '../generators/manifest.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';
 import { CLIError, ErrorCode } from '../lib/errors.js';
 import { trackEvent } from '../lib/telemetry.js';
+import { replaceVocabTokens } from '../lib/canonicalRefs.js';
+// WP-436 S3: vocab projector — resolves {{vocab:...}} tokens before writing to disk.
+import { getOrFetchVocabCtx } from '../lib/workspaceVocabCache.js';
+import { normalizeMaterializedFilename } from '../lib/normalizeMaterializedFilename.js';
+import { assertSetupWritePath } from '../setup/perimeter.js';
+// WP-421 S3: SurfaceAdapter reverse-map for tampered prompts (DEC-952, doneWhen #34).
+import { canonicalPathForAnySurface, SURFACE_GOVERN_NO_SURFACES, SURFACE_REGISTRY, validateSurfacesForMode, } from '../surfaces/registry.js';
+import { getReverseMapFallbackMessage, reportReverseMapMissing } from '../surfaces/telemetry.js';
+const MAX_HANDSHAKE_WAIT_MS = 10_000; // 10 seconds
+const POLL_INTERVAL_MS = 500; // 500 ms per poll
+const MAX_POLLS = MAX_HANDSHAKE_WAIT_MS / POLL_INTERVAL_MS; // 20
+// ── WP-379 S4: Dormant marker ─────────────────────────────────────────────────
+/**
+ * DORMANT_MARKER — appended to previously-projected asset files when the asset's
+ * gate deactivates (e.g. workspace readiness exceeds the max threshold).
+ *
+ * Contract:
+ *   - The file is NOT deleted. It persists on disk so that history is preserved
+ *     and the agent surface remains inspectable.
+ *   - The marker is appended at the end of the file, idempotent — if it already
+ *     exists, no second append occurs.
+ *   - The marker does NOT trigger a drift TEN. Dormant files are intentionally
+ *     deactivated, not accidentally forked.
+ *   - The marker is never included in active file writes — only dormant writes.
+ *
+ * Used by: writeDormantMarker() (write) and hasDormantMarker() (idempotency check).
+ * Exported for use in tests.
+ *
+ * Chain: WP-379 S4.
+ */
+export const DORMANT_MARKER = '<!-- pb-status: dormant -->';
+/**
+ * hasDormantMarker — check whether a file on disk already has the dormant marker.
+ * Used for idempotency: if the marker is already present, skip the append.
+ */
+function hasDormantMarker(content) {
+    return content.includes(DORMANT_MARKER);
+}
+/**
+ * writeDormantMarker — append the dormant marker to a previously-projected file.
+ *
+ * Idempotent: if DORMANT_MARKER is already present, no-op.
+ * Only operates on files that have the auto-gen MARKER — we never touch
+ * manually-authored files.
+ *
+ * @param filePath  Absolute path to the file.
+ * @returns         'written' | 'already-dormant' | 'skipped' (no auto-gen marker)
+ */
+export function writeDormantMarkerToFile(filePath) {
+    if (!existsSync(filePath))
+        return 'skipped';
+    const content = readFileSync(filePath, 'utf8');
+    // Only mark files that were originally projected by pb handshake.
+    // Files without the auto-gen MARKER are manually authored — leave them alone.
+    if (!content.includes(MARKER))
+        return 'skipped';
+    if (hasDormantMarker(content))
+        return 'already-dormant';
+    // Append the marker on its own line. No trailing newline assumption —
+    // appendFileSync adds to whatever is already there.
+    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).
+ *
+ * Assets are projected to one or more surfaces (cursor/claude/codex) depending
+ * on shouldEmitToTarget. Since we don't re-run shouldEmitToTarget here, we
+ * speculatively probe all known surface paths and let writeDormantMarkerToFile
+ * decide whether each exists and has the auto-gen MARKER.
+ *
+ * @param asset  The dormant asset from the server.
+ * @param cwd    Current working directory (project root).
+ * @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
+    // entries (not user input), validate it against a strict charset before
+    // interpolating into a filesystem path. Reject anything that could traverse
+    // out of the expected directories. WP-379 S4 review finding.
+    if (!/^[A-Za-z0-9 ._-]+$/.test(asset.name)) {
+        return [];
+    }
+    const out = [];
+    const { name, assetKind } = asset;
+    if (assetKind === 'skill') {
+        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') {
+        out.push({ path: join(cwd, '.cursor', 'rules', `${name}.mdc`), surface: 'cursor' });
+        out.push({ path: join(cwd, '.claude', 'rules', `${name}.md`), surface: 'claude' });
+    }
+    return out;
+}
+/**
+ * Single-shot health probe — calls `workspace.health` and inspects
+ * `starterSetupSeeded`. Does NOT poll internally; polling is the caller's
+ * responsibility (connect-context.ts).
+ *
+ * Returns:
+ *  - `seeds-ready`   — health query succeeded AND starterSetupSeeded is true
+ *  - `seeds-pending` — health query succeeded but starterSetupSeeded is false
+ *  - `probe-failed`  — health query threw (network, auth, etc.)
+ */
+export async function probeStarterSetupSeeded() {
+    try {
+        const health = await kernelCall('workspace.health', {});
+        if (health.starterSetupSeeded) {
+            return { status: 'seeds-ready' };
+        }
+        const starterGaps = (health.gaps ?? []).filter((g) => g.kind === 'starter-setup-missing' || g.kind === 'platform-domains-missing');
+        return {
+            status: 'seeds-pending',
+            gaps: starterGaps.length > 0 ? starterGaps : [
+                {
+                    kind: 'starter-setup-missing',
+                    severity: 'warn',
+                    message: 'Starter setup seeds are still running.',
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            status: 'probe-failed',
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * 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-context.ts can use it without re-implementing the loop.
+ */
+export async function pollUntilSeedsReady() {
+    for (let poll = 0; poll < MAX_POLLS; poll++) {
+        const result = await probeStarterSetupSeeded();
+        if (result.status === 'seeds-ready')
+            return result;
+        if (result.status === 'probe-failed')
+            return result; // don't retry on auth/network errors
+        // seeds-pending — wait before next poll
+        if (poll < MAX_POLLS - 1) {
+            await new Promise((res) => setTimeout(res, POLL_INTERVAL_MS));
+        }
+    }
+    // Final probe after exhausting waits — return whatever state we have
+    return probeStarterSetupSeeded();
+}
 const LEVELS = {
     guide: {
         label: 'Guide me',
@@ -269,6 +490,256 @@ function shouldWriteAdapter(filePath, force) {
     const content = readFileSync(filePath, 'utf8');
     return content.includes(MARKER);
 }
+function normalizeSurfaceName(surface) {
+    const stripped = surface.startsWith('.') ? surface.slice(1) : surface;
+    const normalized = stripped === 'github' ? 'copilot' : stripped;
+    return normalized in SURFACE_REGISTRY ? normalized : null;
+}
+function surfacePerimeterRoots(surface) {
+    if (surface === 'codex')
+        return ['.codex', SURFACE_REGISTRY.codex.hookFilePath];
+    if (surface === 'copilot')
+        return ['.github', SURFACE_REGISTRY.copilot.hookFilePath];
+    if (surface === 'claude')
+        return ['.claude', 'CLAUDE.md'];
+    return [`.${surface}`];
+}
+function modeRank(mode) {
+    return { off: 0, observe: 1, project: 2, govern: 3 }[mode];
+}
+function normalizeSetupAuthoringBody(body) {
+    return body.replace(/\r\n/g, '\n').replace(/\r/g, '\n').trimEnd();
+}
+function setupAuthoringAssetHash(asset) {
+    const canonical = {
+        entryId: asset.entryId,
+        name: asset.name,
+        description: asset.description ?? '',
+        assetKind: asset.assetKind,
+        triggers: asset.triggers ?? [],
+        semanticRefs: asset.semanticRefs ?? [],
+        body: normalizeSetupAuthoringBody(asset.body),
+    };
+    return `sha256:${createHash('sha256').update(JSON.stringify(canonical), 'utf8').digest('hex')}`;
+}
+function parseSetupAuthoringFrontmatter(raw) {
+    const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!fmMatch) {
+        const h1 = raw.match(/^# (.+)$/m);
+        return { name: h1?.[1] ?? '', description: '', body: raw, triggers: [], semanticRefs: [] };
+    }
+    const fields = new Map();
+    const arrayFields = new Map();
+    const lines = fmMatch[1].split('\n');
+    let currentArrayKey = null;
+    let currentArrayValues = [];
+    for (const line of lines) {
+        const arrayItemMatch = line.match(/^\s+-\s+(.+)$/);
+        const keyValueMatch = line.match(/^(\w+):\s*(.*)$/);
+        if (arrayItemMatch && currentArrayKey) {
+            currentArrayValues.push(arrayItemMatch[1].trim().replace(/^['"]|['"]$/g, ''));
+        }
+        else if (keyValueMatch) {
+            if (currentArrayKey) {
+                arrayFields.set(currentArrayKey, currentArrayValues);
+                currentArrayKey = null;
+                currentArrayValues = [];
+            }
+            const [, key, value] = keyValueMatch;
+            if (value.trim() === '') {
+                currentArrayKey = key;
+            }
+            else {
+                fields.set(key, value.trim().replace(/^['"]|['"]$/g, ''));
+            }
+        }
+    }
+    if (currentArrayKey)
+        arrayFields.set(currentArrayKey, currentArrayValues);
+    const body = fmMatch[2];
+    return {
+        frontmatterId: fields.get('id'),
+        name: fields.get('name') ?? body.match(/^# (.+)$/m)?.[1] ?? '',
+        description: fields.get('description') ?? '',
+        body,
+        triggers: arrayFields.get('triggers') ?? [],
+        semanticRefs: arrayFields.get('semanticRefs') ?? [],
+    };
+}
+function deriveSetupAuthoringEntryId(filename, kind) {
+    const base = basename(filename, '.md');
+    const snakeCase = base.toUpperCase().replace(/[^A-Z0-9]+/g, '_');
+    return `SETUP-${kind.toUpperCase()}-${snakeCase}`;
+}
+function scanSetupAuthoringFiles(productbrainDir) {
+    const dirs = [
+        { dir: 'skills', kind: 'skill' },
+        { dir: 'rules', kind: 'rule' },
+        { dir: 'hooks', kind: 'hook' },
+    ];
+    const items = [];
+    for (const { dir, kind } of dirs) {
+        const absDir = join(productbrainDir, dir);
+        if (!existsSync(absDir))
+            continue;
+        for (const file of readdirSync(absDir).filter((f) => f.endsWith('.md'))) {
+            const filePath = join(absDir, file);
+            const parsed = parseSetupAuthoringFrontmatter(readFileSync(filePath, 'utf8'));
+            const fallbackName = basename(file, '.md');
+            items.push({
+                filePath,
+                derivedEntryId: deriveSetupAuthoringEntryId(file, kind),
+                frontmatterId: parsed.frontmatterId,
+                name: parsed.name || fallbackName,
+                description: parsed.description,
+                body: parsed.body,
+                assetKind: kind,
+                triggers: parsed.triggers,
+                semanticRefs: parsed.semanticRefs,
+            });
+        }
+    }
+    return items.sort((a, b) => a.filePath.localeCompare(b.filePath));
+}
+function setupAuthoringDirForKind(kind) {
+    if (kind === 'skill')
+        return 'skills';
+    if (kind === 'rule')
+        return 'rules';
+    if (kind === 'hook')
+        return 'hooks';
+    return null;
+}
+function setupAuthoringFilename(name, entryId) {
+    const base = (name || entryId)
+        .replace(/[\/\\:*?"<>|]/g, '-')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return `${base || entryId}.md`;
+}
+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) {
+    const lines = [
+        '---',
+        `id: ${asset.entryId}`,
+        `name: ${JSON.stringify(asset.name)}`,
+        `description: ${JSON.stringify(asset.description ?? '')}`,
+        `assetKind: ${asset.assetKind}`,
+    ];
+    const pushArray = (key, values) => {
+        if (!values || values.length === 0)
+            return;
+        lines.push(`${key}:`);
+        for (const value of values)
+            lines.push(`  - ${JSON.stringify(value)}`);
+    };
+    pushArray('triggers', asset.triggers);
+    pushArray('semanticRefs', asset.semanticRefs);
+    lines.push('---', normalizeSetupAuthoringBody(asset.body), '');
+    return lines.join('\n');
+}
+function loadAuthoringSyncState(productbrainDir) {
+    const statePath = join(productbrainDir, '.authoring-sync.json');
+    if (!existsSync(statePath))
+        return { version: 1, assets: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(statePath, 'utf8'));
+        if (parsed.version !== 1 || !parsed.assets || typeof parsed.assets !== 'object') {
+            return { version: 1, 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: {} };
+    }
+}
+function saveAuthoringSyncState(productbrainDir, state) {
+    const statePath = join(productbrainDir, '.authoring-sync.json');
+    assertSetupWritePath(statePath, { surfaces: [] });
+    mkdirSync(productbrainDir, { recursive: true });
+    writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n');
+}
+const DRIFT_HASH_TRAILER_REGEX = /^<!--\s*pb-hash:\s*sha256:([0-9a-f]+)\s*-->\s*$/m;
+const DRIFT_HASH_TRAILER_STRIP = /^<!--\s*pb-hash:.*-->\s*$/gm;
+const DRIFT_TIMESTAMP_STRIP = /^<!--\s*pb-generated-at:.*-->\s*$/gm;
+/**
+ * Classify a single projection-target file into one of the three drift buckets.
+ *
+ * Returns `null` when `filePath` does not exist (first-run / unprojected) — the
+ * write loop treats that as "would-write" and the file is not part of any bucket.
+ *
+ * @param filePath  Absolute path to the projection file on disk.
+ * @returns         { bucket, expectedHash, actualHash } when the file exists.
+ *                  `expectedHash`/`actualHash` are populated only for the
+ *                  tampered bucket so the headless refusal payload can include
+ *                  them verbatim. For clean / user-owned, both are `''`.
+ */
+export function classifyDriftBucket(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    const content = readFileSync(filePath, 'utf8');
+    // No auto-gen MARKER → user-owned. Never touch.
+    if (!content.includes(MARKER)) {
+        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 user-owned-vs-clean
+    // semantic falls back to existing shouldWriteAdapter behavior.
+    const trailerMatch = content.match(DRIFT_HASH_TRAILER_REGEX);
+    if (!trailerMatch) {
+        return { bucket: 'pb-managed-clean', expectedHash: '', actualHash: '' };
+    }
+    const expectedHash = `sha256:${trailerMatch[1]}`;
+    // Recompute the actual hash from the body (strip trailer + timestamp, LF, trim).
+    const normalized = content
+        .replace(DRIFT_HASH_TRAILER_STRIP, '')
+        .replace(DRIFT_TIMESTAMP_STRIP, '')
+        .replace(/\r\n/g, '\n')
+        .replace(/\r/g, '\n')
+        .trimEnd();
+    const actualHash = `sha256:${createHash('sha256').update(normalized, 'utf8').digest('hex')}`;
+    if (actualHash === expectedHash) {
+        return { bucket: 'pb-managed-clean', expectedHash, actualHash };
+    }
+    return { bucket: 'pb-managed-tampered', expectedHash, actualHash };
+}
 function deduplicateEntries(entries) {
     const seen = new Set();
     const result = [];
@@ -281,10 +752,168 @@ function deduplicateEntries(entries) {
     }
     return result;
 }
+/**
+ * resolveProjectionCollision — WP-379 S5b
+ *
+ * Marker-scoped orphan unlink: enumerates target dirs (.cursor/rules/,
+ * .claude/rules/, .claude/skills/, .codex/skills/); for each file that has
+ * the auto-gen MARKER whose lowercase-normalized filename does NOT match any
+ * current active-asset materializedFilename, the file is unlinked.
+ *
+ * User-owned files (no MARKER) are never touched, regardless of name.
+ *
+ * Linux case-collision disambiguation:
+ *   1. Exact match (lowercase name == any canonical name): survives.
+ *   2. Case-variant with MARKER (marker file, no exact canonical match): unlinked.
+ *   3. Ambiguous (zero exact, multiple case-variants with MARKER):
+ *      newest mtime wins; all others are unlinked; a collision TEN is
+ *      appended to the session capture queue (not fired inline).
+ *
+ * Returns a list of unlink results so the caller can log/report them.
+ *
+ * @param cwd         Project root (absolute path).
+ * @param assetNames  The current set of canonical asset names from the server
+ *                    (e.g. ["Setup-ProductBrain", "chain-rules"]).
+ * @param log         Progress log function.
+ * @param logErr      Error log function.
+ */
+export function resolveProjectionCollision(cwd, assetNames, log, logErr) {
+    // Target directories by extension suffix.
+    const TARGET_DIRS_BY_EXT = [
+        { dir: join(cwd, '.cursor', 'rules'), ext: '.mdc' },
+        { dir: join(cwd, '.claude', 'rules'), ext: '.md' },
+        { dir: join(cwd, '.claude', 'skills'), ext: '.md' },
+        { dir: join(cwd, '.codex', 'skills'), ext: '.md' },
+    ];
+    // Build a set of normalized canonical names (without extension) for fast lookup.
+    // We normalize all asset names to detect case-variant collisions.
+    // For each asset name we derive the normalized basename (the part before the ext).
+    // canonicalNormalizedNames: Set<normalized-stem> (lowercase + slug).
+    const canonicalNormalizedStems = new Set(assetNames.map((n) => normalizeMaterializedFilename(n)));
+    const results = [];
+    const collisionTens = [];
+    for (const { dir, ext } of TARGET_DIRS_BY_EXT) {
+        if (!existsSync(dir))
+            continue;
+        let files;
+        try {
+            files = readdirSync(dir);
+        }
+        catch {
+            continue; // unreadable dir — skip
+        }
+        // Group files by their normalized stem.
+        // normalizedStem → [ { filename, fullPath } ]
+        const groups = new Map();
+        for (const filename of files) {
+            if (!filename.endsWith(ext))
+                continue;
+            const fullPath = join(dir, filename);
+            // Only operate on files that have the auto-gen MARKER.
+            let content;
+            try {
+                content = readFileSync(fullPath, 'utf8');
+            }
+            catch {
+                continue; // unreadable file — skip
+            }
+            if (!content.includes(MARKER))
+                continue; // user-owned — never touch
+            const stem = basename(filename, ext);
+            const normalizedStem = normalizeMaterializedFilename(stem);
+            const group = groups.get(normalizedStem) ?? [];
+            group.push({ filename, fullPath });
+            groups.set(normalizedStem, group);
+        }
+        // Evaluate each normalized stem group.
+        for (const [normalizedStem, members] of groups) {
+            const isKnownCanonical = canonicalNormalizedStems.has(normalizedStem);
+            if (!isKnownCanonical) {
+                // All members of this group are orphans (no canonical asset with this stem).
+                // Unlink them all — they're stale projections of an asset no longer in the server.
+                for (const { filename, fullPath } of members) {
+                    try {
+                        unlinkSync(fullPath);
+                        log(`Orphan unlinked: ${fullPath}`);
+                        results.push({ action: 'unlinked', filePath: fullPath, reason: 'orphan-no-canonical-match' });
+                    }
+                    catch (err) {
+                        logErr(`Warning: could not unlink orphan ${fullPath} — ${err instanceof Error ? err.message : String(err)}`);
+                        results.push({ action: 'kept', filePath: fullPath, reason: 'unlink-failed' });
+                    }
+                }
+                continue;
+            }
+            // The stem IS known canonical. Check for case-collision.
+            if (members.length === 1) {
+                // Single file — no collision.
+                results.push({ action: 'kept', filePath: members[0].fullPath, reason: 'canonical-exact' });
+                continue;
+            }
+            // Multiple files with the same normalized stem → case-collision.
+            // Rule: exact match (filename stem === normalized stem, i.e. already lowercase) wins.
+            const exactMatches = members.filter(({ filename }) => {
+                const stem = basename(filename, ext);
+                return stem === normalizedStem; // lowercase-equal means already normalized
+            });
+            if (exactMatches.length === 1) {
+                // Rule 1: exactly one exact match → keep it, unlink all case-variants.
+                const keeper = exactMatches[0];
+                results.push({ action: 'kept', filePath: keeper.fullPath, reason: 'case-exact-match-wins' });
+                for (const member of members) {
+                    if (member.fullPath === keeper.fullPath)
+                        continue;
+                    try {
+                        unlinkSync(member.fullPath);
+                        log(`Case-variant unlinked: ${member.fullPath} (kept: ${keeper.filename})`);
+                        results.push({ action: 'unlinked', filePath: member.fullPath, reason: 'case-variant-unlinked' });
+                    }
+                    catch (err) {
+                        logErr(`Warning: could not unlink case-variant ${member.fullPath} — ${err instanceof Error ? err.message : String(err)}`);
+                        results.push({ action: 'kept', filePath: member.fullPath, reason: 'unlink-failed' });
+                    }
+                }
+                continue;
+            }
+            // Rule 3: ambiguous — zero exact matches (or multiple exact matches, which
+            // can't happen on a case-sensitive FS). Newest mtime wins.
+            // Sort by mtime descending: highest mtime = newest = winner.
+            const withStats = members.map(({ filename, fullPath }) => {
+                try {
+                    const { mtimeMs } = statSync(fullPath);
+                    return { filename, fullPath, mtimeMs };
+                }
+                catch {
+                    return { filename, fullPath, mtimeMs: 0 };
+                }
+            });
+            withStats.sort((a, b) => b.mtimeMs - a.mtimeMs);
+            const winner = withStats[0];
+            log(`Case-collision ambiguous for ${normalizedStem}${ext}: newest mtime wins (${winner.filename})`);
+            results.push({ action: 'collision-ten', filePath: winner.fullPath, reason: 'ambiguous-newest-mtime-wins' });
+            const tenMsg = `Handshake case-collision: ambiguous filename for stem "${normalizedStem}${ext}" ` +
+                `(${members.map((m) => m.filename).join(', ')}). ` +
+                `Kept newest: ${winner.filename}. Consider renaming to ${normalizedStem}${ext}.`;
+            collisionTens.push(tenMsg);
+            for (const member of withStats.slice(1)) {
+                try {
+                    unlinkSync(member.fullPath);
+                    log(`Case-variant (ambiguous) unlinked: ${member.fullPath}`);
+                    results.push({ action: 'unlinked', filePath: member.fullPath, reason: 'ambiguous-case-variant-unlinked' });
+                }
+                catch (err) {
+                    logErr(`Warning: could not unlink ambiguous case-variant ${member.fullPath} — ${err instanceof Error ? err.message : String(err)}`);
+                    results.push({ action: 'kept', filePath: member.fullPath, reason: 'unlink-failed' });
+                }
+            }
+        }
+    }
+    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;
@@ -323,7 +952,7 @@ export async function runHandshake(options = {}) {
     try {
         const workspaceReadinessPromise = kernelCall('chain.workspaceReadiness', {}).catch(() => null);
         const [orientResult, readinessRaw] = await Promise.all([
-            kernelCall('chain.getOrientView', {}).catch((err) => {
+            kernelCall('chain.getOrientView', { tier: 'standard' }).catch((err) => {
                 logErr(`Warning: could not fetch workspace context — ${err instanceof Error ? err.message : err}`);
                 logErr('Continuing with limited context (Chain search + portable knowledge only).');
                 return null;
@@ -364,25 +993,208 @@ export async function runHandshake(options = {}) {
     // Primary: query setup.listAssetsForUser from DB (workspace SSOT).
     // Fallback: read from .productbrain/ filesystem (legacy — used when DB is empty or unavailable).
     const pbDir = join(cwd, '.productbrain');
+    const manifestStatus = readManifestStatus(pbDir);
+    const manifest = manifestStatus.manifest;
+    const surfaceValidation = validateSurfacesForMode(manifestStatus.mode, manifestStatus.surfaces);
+    if (applyMode && surfaceValidation.error === SURFACE_GOVERN_NO_SURFACES) {
+        throw new CLIError('materialize: govern requires at least one registered manifest surface.', {
+            code: ErrorCode.VALIDATION_FAILED,
+            category: 'validation',
+            guidance: 'Add surfaces such as `.cursor` or `.claude` to .productbrain/manifest.yaml.',
+        });
+    }
+    for (const surface of surfaceValidation.unregisteredSurfaces) {
+        logErr(`Warning: manifest surface "${surface}" is not registered; skipping it.`);
+    }
+    const manifestTargets = new Set(surfaceValidation.registeredSurfaces);
+    const cliTargets = new Set();
+    const ignoredCliSurfaces = [];
+    for (const surface of options.surfaces ?? []) {
+        const normalized = normalizeSurfaceName(surface);
+        if (normalized && manifestTargets.has(normalized)) {
+            cliTargets.add(normalized);
+        }
+        else {
+            ignoredCliSurfaces.push(surface);
+        }
+    }
+    if (ignoredCliSurfaces.length > 0) {
+        logErr(`Warning: --surfaces ignored outside manifest.surfaces: ${ignoredCliSurfaces.join(', ')}`);
+    }
+    const allowedTargets = options.surfaces && options.surfaces.length > 0
+        ? cliTargets
+        : manifestTargets;
+    const perimeterManifest = {
+        surfaces: [...manifestTargets].flatMap(surfacePerimeterRoots),
+    };
+    const authorityCanWrite = manifestStatus.mode === 'project' || manifestStatus.mode === 'govern';
+    const authorityPreviewOnly = applyMode && !authorityCanWrite;
+    const writeMode = applyMode && authorityCanWrite;
     let dbSkills = [];
     let dbRules = [];
     let usedDbSource = false;
     let dbAssetRows = [];
+    // WP-379 S4: dormant assets (gate-failed) — their on-disk files get the dormant marker.
+    let dormantDbAssetRows = [];
+    // WP-428 S2 (Finding #5): tracks entryIds whose body fetch from storage failed.
+    // 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();
     const dbProjectionHashes = new Map();
+    const syncDriftTensToFire = [];
+    const deferredAuthoringBaselineEntryIds = new Set();
+    if (writeMode) {
+        const authoringItems = scanSetupAuthoringFiles(pbDir);
+        if (authoringItems.length > 0) {
+            // WP-428 S2 (Critical #1): ingestSetupAssetsBatch is an internalMutation — it cannot
+            // call ctx.storage.store(). We now call ingestSetupAssetWithBody (action) per-asset so
+            // each asset gets bodyStorageId written. This loses intra-batch collision detection;
+            // canonical-id collision check is now client-side before dispatch.
+            //
+            // Client-side collision detection (replaces server-side DEC-954 check in the batch mutation):
+            const idToPaths = new Map();
+            for (const item of authoringItems) {
+                const canonicalId = item.frontmatterId?.trim() || item.derivedEntryId;
+                const paths = idToPaths.get(canonicalId) ?? [];
+                paths.push(item.filePath);
+                idToPaths.set(canonicalId, paths);
+            }
+            const conflictingPaths = new Set();
+            for (const [, paths] of idToPaths) {
+                if (paths.length > 1) {
+                    for (const p of paths)
+                        conflictingPaths.add(p);
+                }
+            }
+            if (conflictingPaths.size > 0) {
+                logErr(`Setup authoring import partial: ${conflictingPaths.size} file(s) refused for duplicate setup id. ` +
+                    [...conflictingPaths].join(', '));
+            }
+            const itemsToIngest = authoringItems.filter((item) => !conflictingPaths.has(item.filePath));
+            if (itemsToIngest.length > 0) {
+                try {
+                    // Parallel uploads — concurrency limit 10 to avoid overwhelming the gateway.
+                    const CONCURRENCY = 10;
+                    const ingestResults = [];
+                    for (let i = 0; i < itemsToIngest.length; i += CONCURRENCY) {
+                        const batch = itemsToIngest.slice(i, i + CONCURRENCY);
+                        const settled = await Promise.allSettled(batch.map(async (item) => {
+                            const result = await kernelCall('setup.ingestSetupAssetWithBody', {
+                                entryId: item.derivedEntryId,
+                                frontmatterId: item.frontmatterId,
+                                name: item.name,
+                                description: item.description,
+                                body: item.body,
+                                assetKind: item.assetKind,
+                                triggers: item.triggers,
+                                semanticRefs: item.semanticRefs,
+                                authoringPath: relative(pbDir, item.filePath).split(sep).join('/'),
+                            });
+                            return { filePath: item.filePath, ...result };
+                        }));
+                        for (const r of settled) {
+                            if (r.status === 'fulfilled') {
+                                ingestResults.push(r.value);
+                                if (r.value.conflict === 'repo-wins') {
+                                    syncDriftTensToFire.push(`Repo authoring file won setup sync conflict for ${r.value.entryId} at ${r.value.filePath}.`);
+                                    logErr(`Warning: repo authoring file won sync conflict for ${r.value.entryId}; DB edit was overwritten.`);
+                                }
+                            }
+                            else {
+                                trackEvent('setup.authoring_import.item_failed', { error: r.reason instanceof Error ? r.reason.message : String(r.reason) });
+                                logErr(`Warning: setup authoring import failed for one asset — ${r.reason instanceof Error ? r.reason.message : String(r.reason)}`);
+                            }
+                        }
+                    }
+                    if (ingestResults.length > 0) {
+                        log(`Setup authoring import: ${ingestResults.length} file(s) checked (with bodyStorageId).`);
+                    }
+                }
+                catch (err) {
+                    trackEvent('setup.authoring_import.failed', { error: err instanceof Error ? err.message : String(err) });
+                    logErr(`Warning: setup authoring import failed — ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+    }
     try {
-        const dbAssets = await kernelCall('setup.listAssetsForUser', {}).catch(() => null);
-        if (dbAssets && dbAssets.length > 0) {
+        // WP-379 S4: listAssetsForUser now returns { activeAssets, dormantAssets }.
+        // Wire format changed from DbAsset[] to { activeAssets: DbAsset[], dormantAssets: DbAsset[] }.
+        // Fall back to empty arrays if the server returns the old flat-array shape (graceful degradation).
+        const rawResponse = await kernelCall('setup.listAssetsForUser', {}).catch(() => null);
+        let dbAssets = [];
+        if (rawResponse !== null) {
+            if (Array.isArray(rawResponse)) {
+                // Pre-S4 server — treat entire response as active assets with no dormant list.
+                dbAssets = rawResponse;
+                dormantDbAssetRows = [];
+            }
+            else {
+                dbAssets = rawResponse.activeAssets ?? [];
+                dormantDbAssetRows = rawResponse.dormantAssets ?? [];
+            }
+        }
+        if (dbAssets.length > 0) {
             dbAssetRows = dbAssets;
+            // WP-428 S2: body is no longer inline — fetch from storage per-asset when bodyStorageId is set.
+            // Projectable assets: non-disabled skill/rule/hook entries. Fetch bodies in parallel (bounded).
+            const projectableAssets = dbAssets.filter((a) => !a.disabledByOwner && (a.assetKind === 'skill' || a.assetKind === 'rule' || a.assetKind === 'hook'));
+            const assetsNeedingBodyFetch = projectableAssets.filter((a) => a.bodyStorageId);
+            const bodyFetchMap = new Map(); // entryId → body
+            // WP-428 S2 (Finding #5/#12): track fetch-failed assets so we can skip their projection.
+            // Failed entryIds are excluded from dbSkills/dbRules — no empty body written, no lastProjectedHash update.
+            // bodyFetchFailedEntryIds is declared at outer scope (also used by authoring-file projection loop).
+            if (assetsNeedingBodyFetch.length > 0) {
+                log(`Fetching ${assetsNeedingBodyFetch.length} asset body(s) from storage...`);
+                const bodyFetchResults = await Promise.allSettled(assetsNeedingBodyFetch.map(async (asset) => {
+                    const result = await kernelCall('setup.fetchAssetBody', { bodyStorageId: asset.bodyStorageId });
+                    return { entryId: asset.entryId, name: asset.name, body: result.body };
+                }));
+                for (let i = 0; i < bodyFetchResults.length; i++) {
+                    const result = bodyFetchResults[i];
+                    if (result.status === 'fulfilled') {
+                        bodyFetchMap.set(result.value.entryId, result.value.body);
+                    }
+                    else {
+                        // WP-428 S2 (Finding #12): include entryId and name in the warning (Finding #5: skip projection).
+                        const asset = assetsNeedingBodyFetch[i];
+                        logErr(`Warning: failed to fetch body for ${asset.entryId} (${asset.name}) — ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`);
+                        bodyFetchFailedEntryIds.add(asset.entryId);
+                    }
+                }
+                if (bodyFetchFailedEntryIds.size > 0) {
+                    // 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
             for (const asset of dbAssets) {
                 if (asset.disabledByOwner)
                     continue;
+                // WP-428 S2 (Finding #5): skip projection for assets whose body fetch failed.
+                // Do NOT write empty body to disk and do NOT update lastProjectedHash.
+                if (bodyFetchFailedEntryIds.has(asset.entryId))
+                    continue;
+                // WP-428 S2: resolve body — prefer storage-fetched body, fall back to inline body (pre-S2 servers).
+                // Fallback: pre-S2 servers (no bodyStorageId) return inline body. Once all servers are S2+, this can be deleted.
+                const resolvedBody = bodyFetchMap.get(asset.entryId) ?? asset.body ?? '';
                 if (asset.assetKind === 'skill') {
                     dbSkills.push({
                         name: asset.name,
                         description: asset.description,
                         triggers: asset.triggers ?? [],
-                        body: asset.body,
+                        body: resolvedBody,
                         sourcePath: `db:${asset.entryId}`,
                     });
                 }
@@ -391,13 +1203,16 @@ export async function runHandshake(options = {}) {
                         name: asset.name,
                         description: asset.description,
                         autoApply: false,
-                        body: asset.body,
+                        body: resolvedBody,
                         sourcePath: `db:${asset.entryId}`,
                     });
                 }
             }
             usedDbSource = true;
             log(`Setup assets: ${dbSkills.length} skills, ${dbRules.length} rules/hooks from DB (WP-345 DB-first path)`);
+            if (dormantDbAssetRows.length > 0) {
+                log(`Setup assets: ${dormantDbAssetRows.length} dormant (gate-filtered) asset(s) will be marked on disk`);
+            }
         }
     }
     catch {
@@ -412,14 +1227,15 @@ export async function runHandshake(options = {}) {
     // For each asset with semanticRefs[], resolve them via the Convex resolver and
     // replace {{ref:key}} placeholders in the body. Runs in apply mode only (not preview).
     // NG11: PostHog events fire from CLI side only (never inside Convex mutations).
-    if (usedDbSource && applyMode) {
+    if (usedDbSource && writeMode) {
         const projectableDbAssets = dbAssetRows.filter((a) => !a.disabledByOwner && (a.assetKind === 'skill' || a.assetKind === 'rule' || a.assetKind === 'hook'));
         const assetsWithRefs = projectableDbAssets.filter((a) => a.semanticRefs && a.semanticRefs.length > 0);
         if (assetsWithRefs.length > 0) {
             log(`Resolving semantic refs for ${assetsWithRefs.length} asset(s)...`);
             // Collect unique ref keys across all assets
             const allRefKeys = [...new Set(assetsWithRefs.flatMap((a) => a.semanticRefs))];
-            // Resolve all refs in a single batch call
+            // Resolve all refs in a single batch call. Shape: SetupRefResolution[]
+            // (DEC-767 / WP-354 Build-Order #6 — kind + status discriminator).
             let resolvedRefs = [];
             try {
                 resolvedRefs = await kernelCall('setup.resolveSemanticRefs', { semanticRefs: allRefKeys });
@@ -428,21 +1244,26 @@ export async function runHandshake(options = {}) {
                 trackEvent('setup.refs.resolve_failed', { error: err instanceof Error ? err.message : String(err) });
                 logErr(`Warning: could not resolve semantic refs — ${err instanceof Error ? err.message : String(err)}`);
             }
-            // Build resolved map: canonicalKey → display name
+            // Build resolved map: canonicalKey → display name. Only required refs
+            // count as unresolved warnings; seed/unknown refs are not gates.
             const resolvedMap = new Map();
             let unresolvedCount = 0;
             for (const result of resolvedRefs) {
-                if (result.resolved) {
-                    resolvedMap.set(result.ref, result.resolved.name);
-                    trackEvent('skill.ref.resolved', { ref: result.ref });
+                if (result.status === 'resolved' && result.localEntryId) {
+                    resolvedMap.set(result.ref, result.localEntryId);
+                    trackEvent('skill.ref.resolved', { ref: result.ref, kind: result.kind });
                 }
-                else {
+                else if (result.status === 'unsupported-future') {
+                    // seed: refs are explicitly future scope per WP-354 Build-Order #6 — not a warning.
+                    trackEvent('skill.ref.future', { ref: result.ref, kind: result.kind });
+                }
+                else if (result.required) {
                     unresolvedCount++;
-                    trackEvent('skill.ref.unresolved', { ref: result.ref });
+                    trackEvent('skill.ref.unresolved', { ref: result.ref, kind: result.kind, status: result.status });
                 }
             }
             if (unresolvedCount > 0) {
-                logErr(`Warning: ${unresolvedCount} semantic ref(s) could not be resolved.`);
+                logErr(`Warning: ${unresolvedCount} required semantic ref(s) could not be resolved.`);
             }
             // Projection must preserve ref tokens as portable machine-readable refs.
             // resolvedMap is only used for validation/telemetry here; generated setup
@@ -554,9 +1375,6 @@ export async function runHandshake(options = {}) {
         }
         allSkills.push(...personalSkills);
     }
-    // 5c. Apply manifest-based adoption filter (WP-310 E1)
-    // readManifest returns null when manifest.yaml is absent → filterByAdoptionState is a no-op.
-    const manifest = readManifest(pbDir);
     // 5d. Load method registry (WP-310 E4) — only when manifest is present.
     let registrySource;
     let registryStale;
@@ -623,13 +1441,13 @@ export async function runHandshake(options = {}) {
     const agentsWorkspaceContext = workspaceProfile
         ? {
             stage: workspaceProfile.stage,
-            focus: orientView?.strategicContext?.currentBet ?? undefined,
+            focus: orientView?.strategicContext?.currentWorkPackage ?? undefined,
             governanceMode: workspaceProfile.governanceMode,
             totalEntries: workspaceProfile.totalEntries,
         }
         : undefined;
-    // Collect codex-targeted skills for AGENTS.md skill directory
-    // Exclude persist: 'local' rules — committed adapter files must never include local-only rules.
+    // Collect codex-targeted skills for AGENTS.md skill directory.
+    // persist: 'local' entries are included; all projections are now local-only.
     const agentsCodexSkills = canonicalSkills
         .filter((s) => shouldEmitToTarget(s, 'codex'))
         .map((s) => ({
@@ -668,21 +1486,141 @@ export async function runHandshake(options = {}) {
     const claudeContent = generateClaudeMd(timestamp);
     const cursorContent = generateCursorMdc(timestamp);
     const copilotContent = generateCopilotMd(timestamp, copilotOptions);
+    const boundaryEnforcementMode = getBoundaryEnforcementMode(manifest);
+    const boundaryManifestContent = boundaryEnforcementMode === 'advisory'
+        ? null
+        : generateBoundaryManifest(pbDir);
     // 7. Write files
     const filesWritten = [];
     const filesSkipped = [];
     const previewPlan = [];
-    // Surface filtering: skip adapter writes for targets not in the allowed set
-    const allowedTargets = options.surfaces && options.surfaces.length > 0
-        ? new Set(options.surfaces)
-        : null; // null = write all
+    if (writeMode && usedDbSource) {
+        const authoringSyncState = loadAuthoringSyncState(pbDir);
+        let authoringSyncStateChanged = false;
+        const personalAssets = dbAssetRows.filter((asset) => asset.scope === 'personal' &&
+            !asset.disabledByOwner &&
+            (asset.assetKind === 'skill' || asset.assetKind === 'rule' || asset.assetKind === 'hook'));
+        for (const asset of personalAssets) {
+            // WP-428 S2 (Finding #5): skip projection for assets whose body fetch failed.
+            // Do NOT write the authoring file with empty body, do NOT update lastProjectedHash.
+            if (bodyFetchFailedEntryIds.has(asset.entryId))
+                continue;
+            const authoringPath = setupAuthoringPath(cwd, asset);
+            if (!authoringPath)
+                continue;
+            // 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];
+            const trackedHere = tracked?.path === relativeAuthoringPath;
+            const trackedMatchesServer = Boolean(trackedHere && asset.lastProjectedHash && tracked?.hash === asset.lastProjectedHash);
+            if (!authoringExists && asset.lastProjectedHash && trackedHere && trackedMatchesServer) {
+                try {
+                    const dormantResult = await kernelCall('setup.markPersonalSetupAssetDormantFromSync', { entryId: asset.entryId, expectedLastProjectedHash: tracked.hash });
+                    if (dormantResult.action === 'conflict') {
+                        syncDriftTensToFire.push(`Repo authoring deletion skipped for ${asset.entryId}; server baseline changed during sync, so writeback was deferred until the next DB read.`);
+                        logErr(`Warning: authoring deletion for ${asset.entryId} was not applied because the DB baseline changed during sync.`);
+                        deferredAuthoringBaselineEntryIds.add(asset.entryId);
+                        continue;
+                    }
+                    else {
+                        syncDriftTensToFire.push(`Repo authoring file was deleted for ${asset.entryId}; caller-owned personal setup asset marked dormant.`);
+                        log(`Setup authoring deletion: ${asset.entryId} marked dormant.`);
+                        delete authoringSyncState.assets[asset.entryId];
+                        authoringSyncStateChanged = true;
+                        continue;
+                    }
+                }
+                catch (err) {
+                    logErr(`Warning: could not mark ${asset.entryId} dormant after authoring deletion — ${err instanceof Error ? err.message : String(err)}`);
+                    continue;
+                }
+            }
+            else if (!authoringExists && asset.lastProjectedHash && trackedHere) {
+                syncDriftTensToFire.push(`Repo authoring deletion skipped for ${asset.entryId}; local sync baseline is stale, so DB writeback wins.`);
+                logErr(`Warning: authoring deletion for ${asset.entryId} was not applied because the DB baseline changed.`);
+            }
+            const nextAuthoringContent = renderSetupAuthoringFile(asset);
+            if (authoringExists) {
+                const parsed = parseSetupAuthoringFrontmatter(readFileSync(authoringPath, 'utf8'));
+                const fileHash = setupAuthoringAssetHash({
+                    entryId: parsed.frontmatterId?.trim() || asset.entryId,
+                    name: parsed.name || asset.name,
+                    description: parsed.description,
+                    body: parsed.body,
+                    assetKind: asset.assetKind,
+                    triggers: parsed.triggers,
+                    semanticRefs: parsed.semanticRefs,
+                });
+                if (fileHash === bodyHash) {
+                    if (asset.lastProjectedHash !== bodyHash) {
+                        await kernelCall('setup.updateLastProjectedHash', {
+                            entryId: asset.entryId,
+                            hash: bodyHash,
+                        }).catch(() => null);
+                    }
+                    authoringSyncState.assets[asset.entryId] = { path: relativeAuthoringPath, hash: bodyHash };
+                    authoringSyncStateChanged = true;
+                    continue;
+                }
+                if (!asset.lastProjectedHash) {
+                    syncDriftTensToFire.push(`Repo authoring file differs from DB for ${asset.entryId} at ${authoringPath} with no shared baseline; DB writeback skipped.`);
+                    logErr(`Warning: setup authoring drift for ${asset.entryId}; DB writeback skipped because no shared baseline exists.`);
+                    continue;
+                }
+                if (fileHash !== asset.lastProjectedHash &&
+                    bodyHash !== asset.lastProjectedHash) {
+                    syncDriftTensToFire.push(`Repo authoring file won setup sync conflict for ${asset.entryId} at ${authoringPath}.`);
+                    logErr(`Warning: repo authoring file won sync conflict for ${asset.entryId}; DB writeback skipped.`);
+                    continue;
+                }
+                if (fileHash !== asset.lastProjectedHash) {
+                    syncDriftTensToFire.push(`Repo authoring file differs from DB baseline for ${asset.entryId} at ${authoringPath}; DB writeback skipped.`);
+                    logErr(`Warning: setup authoring drift for ${asset.entryId}; DB writeback skipped.`);
+                    continue;
+                }
+            }
+            try {
+                assertSetupWritePath(authoringPath, perimeterManifest);
+                mkdirSync(dirname(authoringPath), { recursive: true });
+                writeFileSync(authoringPath, nextAuthoringContent);
+                filesWritten.push(relativeAuthoringPath);
+                await kernelCall('setup.updateLastProjectedHash', {
+                    entryId: asset.entryId,
+                    hash: bodyHash,
+                }).catch(() => null);
+                authoringSyncState.assets[asset.entryId] = { path: relativeAuthoringPath, hash: bodyHash };
+                authoringSyncStateChanged = true;
+            }
+            catch (err) {
+                logErr(`Warning: could not write setup authoring file for ${asset.entryId} — ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        if (authoringSyncStateChanged) {
+            try {
+                saveAuthoringSyncState(pbDir, authoringSyncState);
+            }
+            catch (err) {
+                logErr(`Warning: could not persist setup authoring sync state — ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
     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 ? [{
+                path: join(cwd, '.productbrain', 'generated', 'boundaries.json'),
+                relative: '.productbrain/generated/boundaries.json',
+                content: boundaryManifestContent,
+                dirs: join(cwd, '.productbrain', 'generated'),
+                isAdapter: false,
+            }] : []),
     ];
     // Add Cursor skill copies (filtered by target)
     const cursorProfile = resolveSurfaceProfile('cursor');
@@ -770,33 +1708,166 @@ export async function runHandshake(options = {}) {
             target: 'claude',
         });
     }
-    const forkedPaths = [];
+    // 7a. WP-379 S5b: Resolve projection collisions before writing.
+    // In apply mode, enumerate target dirs and unlink any auto-generated files
+    // whose normalized name no longer matches any active asset from the server.
+    // This prevents case-variant orphans from accumulating across handshakes.
+    // Runs only when we have a DB asset list (usedDbSource) — without a DB source,
+    // we can't determine which files are canonical vs. orphan.
+    const collisionTensToFire = [];
+    if (writeMode && usedDbSource) {
+        const activeAssetNames = dbAssetRows
+            .filter((a) => !a.disabledByOwner)
+            .map((a) => a.name);
+        const { collisionTens } = resolveProjectionCollision(cwd, activeAssetNames, log, logErr);
+        collisionTensToFire.push(...collisionTens);
+    }
+    // ── WP-436 S3: Vocab projector — fetch workspace vocab context once per handshake ──
+    // Source-side (.productbrain/skills/*.md + rules/*.md) stays tokenized.
+    // The projector resolves {{vocab:...}} tokens before writing adapter output to disk
+    // (.cursor/rules/, .claude/rules/, CLAUDE.md, AGENTS.md, .github/copilot-instructions.md).
+    // Fail-open: if vocab fetch fails, skip resolution and write raw token (no breakage).
+    const handshakeVocabCtx = await getOrFetchVocabCtx(config.apiKey, async () => {
+        try {
+            const vocab = await kernelCall('chain.getVocabulary', {});
+            if (vocab?.collectionLabels || vocab?.collectionDefaults) {
+                return {
+                    ...(vocab.collectionLabels ? { collectionLabels: vocab.collectionLabels } : {}),
+                    ...(vocab.collectionDefaults ? { collectionDefaults: vocab.collectionDefaults } : {}),
+                };
+            }
+            return null;
+        }
+        catch {
+            return null; // fail-open
+        }
+    });
+    const userOwnedSkipped = [];
     const projectedHashUpdates = new Map();
+    const cleanBucketPaths = [];
+    const tamperedBucket = [];
     const recordProjectedHash = (entryId) => {
         if (!applyMode || !entryId)
             return;
+        if (deferredAuthoringBaselineEntryIds.has(entryId))
+            return;
         const projection = dbProjectionHashes.get(entryId);
         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 (allowedTargets && w.target && !allowedTargets.has(w.target)) {
+        if (w.target && !allowedTargets.has(w.target)) {
             filesSkipped.push({ path: w.relative, reason: `filtered (surface: ${w.target})` });
             if (preview)
                 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;
         }
+        if (authorityPreviewOnly) {
+            filesSkipped.push({
+                path: w.relative,
+                reason: `preview-only (materialize: ${manifestStatus.mode})`,
+            });
+            continue;
+        }
         if (preview || dryRun) {
             // In preview/dry-run mode: check content to distinguish new/update/unchanged
             if (existsSync(w.path)) {
@@ -821,11 +1892,44 @@ export async function runHandshake(options = {}) {
             }
             continue;
         }
+        // ── WP-421 S3: defer tampered adapter writes (doneWhen #17) ──────────────
+        // For adapter projections that already exist on disk, classify into
+        // pb-managed-clean / pb-managed-tampered. Tampered = MARKER present +
+        // hash trailer mismatches body. Defer (do NOT overwrite); post-loop
+        // resolution handles them. --force bypasses the tampered defer (legacy
+        // semantic: explicit user opt-in to overwrite).
+        if (w.isAdapter && !force) {
+            const drift = classifyDriftBucket(w.path);
+            if (drift && drift.bucket === 'pb-managed-tampered') {
+                tamperedBucket.push({
+                    path: w.path,
+                    relative: w.relative,
+                    content: w.content,
+                    expectedHash: drift.expectedHash,
+                    actualHash: drift.actualHash,
+                    dirs: w.dirs,
+                    dbAssetEntryId: w.dbAssetEntryId,
+                });
+                // Do NOT write — defer until prompt/refusal resolves the file.
+                continue;
+            }
+            if (drift && drift.bucket === 'pb-managed-clean') {
+                cleanBucketPaths.push(w.relative);
+            }
+        }
+        assertSetupWritePath(w.path, perimeterManifest);
         if (w.dirs)
             mkdirSync(w.dirs, { recursive: true });
+        // WP-436 S3: resolve {{vocab:...}} tokens before writing projected adapter files.
+        // Source-side (.productbrain/skills/*.md, rules/*.md) stays tokenized.
+        // Only adapter projections (cursor/rules, claude/rules, CLAUDE.md, AGENTS.md, etc.) get resolved.
+        // Fail-open: if vocabCtx is undefined, replaceVocabTokens falls back to canonicalKey literals.
+        const resolvedContent = w.isAdapter
+            ? replaceVocabTokens(w.content, handshakeVocabCtx)
+            : w.content;
         if (existsSync(w.path)) {
             const current = readFileSync(w.path, 'utf8');
-            const nextNormalized = normalizeHandshakeContentForComparison(w.content);
+            const nextNormalized = normalizeHandshakeContentForComparison(resolvedContent);
             const currentNormalized = normalizeHandshakeContentForComparison(current);
             if (nextNormalized === currentNormalized) {
                 filesSkipped.push({ path: w.relative, reason: 'unchanged' });
@@ -833,7 +1937,7 @@ export async function runHandshake(options = {}) {
                 continue;
             }
         }
-        writeFileSync(w.path, w.content);
+        writeFileSync(w.path, resolvedContent);
         filesWritten.push(w.relative);
         recordProjectedHash(w.dbAssetEntryId);
     }
@@ -850,26 +1954,420 @@ export async function runHandshake(options = {}) {
             }
         });
     }
-    // 8. Drift logging — if apply mode encountered forked adapters and a session is active, log a draft TEN
-    if (forkedPaths.length > 0) {
+    // 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).
+    //
+    // Headless = `--no-prompt` flag OR `process.stdout.isTTY === false`. When
+    // headless: enumerate each tampered file to stderr, write a setup_receipt
+    // row with kind='transition' (DEC-962) capturing `refusedTamperedFiles[]`,
+    // then exit non-zero. NEVER auto-resolve. (#17 + exclusions: edits to
+    // projection dirs are detected, NOT silently overwritten.)
+    //
+    // Interactive: for each tampered file, present adopt-or-revert. Adopt =
+    // create a personal-scoped setup_asset draft from the tampered content
+    // (see helper below). Revert = re-project canonical content over the
+    // tampered file (write w.content to w.path).
+    const adoptedTamperedPaths = [];
+    const revertedTamperedPaths = [];
+    if (writeMode && tamperedBucket.length > 0) {
+        const headless = options.noPrompt === true || !process.stdout.isTTY;
+        if (headless) {
+            // ── Headless refusal path (doneWhen #17) ────────────────────────────────
+            logErr('');
+            logErr(`pb handshake: ${tamperedBucket.length} PB-managed projection file(s) were edited downstream of the auto-gen marker.`);
+            logErr('Headless mode (--no-prompt or no TTY) cannot resolve adopt-or-revert — refusing.');
+            logErr('');
+            const refusedTamperedFiles = tamperedBucket.map((t) => ({
+                path: t.relative,
+                expectedHash: t.expectedHash,
+                actualHash: t.actualHash,
+            }));
+            for (const refused of refusedTamperedFiles) {
+                // Per #17: stderr enumerates each tampered file as
+                // {path, expectedHash, actualHash, bucket}.
+                logErr(`  ${JSON.stringify({ ...refused, bucket: 'pb-managed-tampered' })}`);
+            }
+            logErr('');
+            logErr('Re-run interactively to resolve, or use --force to overwrite (data loss).');
+            // Write the kind='transition' setup_receipt row. Fail-open on the
+            // network/auth side: if the row cannot be written, we still exit non-zero
+            // (the audit trail is best-effort; refusal is mandatory).
+            try {
+                const manifestStatus = readManifestStatus(pbDir);
+                await kernelCall('setup.recordTamperRefusal', {
+                    mode: manifestStatus.mode,
+                    refusedTamperedFiles,
+                });
+                trackEvent('setup.transition.refused', {
+                    fileCount: refusedTamperedFiles.length,
+                    mode: manifestStatus.mode,
+                });
+            }
+            catch (err) {
+                trackEvent('setup.transition.refused.write_failed', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                logErr(`Warning: could not record transition receipt — ${err instanceof Error ? err.message : String(err)}`);
+            }
+            // Surface the report counts before exit (visibility for CI logs).
+            if (!quiet) {
+                process.stdout.write('\n');
+                process.stdout.write(formatHandshakeReport({
+                    filesWritten,
+                    filesSkipped,
+                    matchedEntries,
+                    searchQueries: uniqueQueries,
+                    repo,
+                    codexWarnings: codexWarnings.length > 0 ? codexWarnings : undefined,
+                    chainRulesStats: chainRulesStats ?? undefined,
+                    chainGaps: chainGaps.length > 0 ? chainGaps : undefined,
+                    adoptedCount: adoptedRulesCount,
+                    rejectedCount: rejectedRulesCount,
+                    personalRuleCount: personalRules.length > 0 ? personalRules.length : undefined,
+                    personalSkillCount: personalSkills.length > 0 ? personalSkills.length : undefined,
+                    registrySource,
+                    registryStale,
+                    userOwnedSkipped: userOwnedSkipped.length > 0 ? userOwnedSkipped : undefined,
+                    managedCleanCount: cleanBucketPaths.length || undefined,
+                    tamperedFiles: refusedTamperedFiles,
+                }) + '\n');
+            }
+            // Exit non-zero per #17.
+            process.exit(1);
+        }
+        // ── Interactive path: prompt adopt-or-revert per file ──────────────────────
+        log('');
+        log(`pb handshake: ${tamperedBucket.length} PB-managed projection file(s) were edited downstream of the auto-gen marker.`);
+        log('You can ADOPT (capture your edits as a personal-scoped draft) or REVERT (overwrite with canonical content).');
+        // Batch yes-to-all / no-to-all when the user has many tampered files.
+        // Threshold: 5 (arbitrary; mirrors the typical handshake projection set).
+        let batchChoice = null;
+        if (tamperedBucket.length >= 5) {
+            const useBatch = await promptConfirm({
+                message: `Apply the same choice to all ${tamperedBucket.length} tampered files?`,
+                initialValue: false,
+            });
+            if (useBatch) {
+                const choice = await promptSelect({
+                    message: 'Apply to all:',
+                    options: [
+                        { value: 'adopt', label: 'Adopt all — capture each as a personal-scoped draft' },
+                        { value: 'revert', label: 'Revert all — overwrite with canonical content' },
+                    ],
+                });
+                batchChoice = choice === 'adopt' ? 'adopt-all' : 'revert-all';
+            }
+        }
+        for (const tamper of tamperedBucket) {
+            // Reverse-map the projection path back to the canonical authoring path.
+            const reverse = canonicalPathForAnySurface(tamper.relative);
+            const canonicalHint = reverse
+                ? `Canonical authoring path: ${reverse.canonicalPath}`
+                : (() => {
+                    // Telemetry + fallback message per surfaces/telemetry.ts.
+                    reportReverseMapMissing({ surface: 'unknown', projectionPath: tamper.relative }, logErr);
+                    return `Canonical authoring path: ${getReverseMapFallbackMessage()}`;
+                })();
+            log('');
+            log(`Tampered: ${tamper.relative}`);
+            log(`  expected: ${tamper.expectedHash}`);
+            log(`  actual:   ${tamper.actualHash}`);
+            log(`  ${canonicalHint}`);
+            let action;
+            if (batchChoice === 'adopt-all')
+                action = 'adopt';
+            else if (batchChoice === 'revert-all')
+                action = 'revert';
+            else {
+                action = await promptSelect({
+                    message: 'Adopt or revert?',
+                    options: [
+                        { value: 'adopt', label: 'Adopt — capture this as a personal-scoped setup_asset draft' },
+                        { value: 'revert', label: 'Revert — overwrite with canonical content' },
+                    ],
+                });
+            }
+            if (action === 'revert') {
+                // Re-project canonical content over the tampered file.
+                // WP-436 S3: resolve vocab tokens before writing (all tampered files are adapters).
+                if (tamper.dirs)
+                    mkdirSync(tamper.dirs, { recursive: true });
+                assertSetupWritePath(tamper.path, perimeterManifest);
+                writeFileSync(tamper.path, replaceVocabTokens(tamper.content, handshakeVocabCtx));
+                revertedTamperedPaths.push(tamper.relative);
+                recordProjectedHash(tamper.dbAssetEntryId);
+                trackEvent('setup.tampered.reverted', { path: tamper.relative });
+            }
+            else {
+                // Adopt: capture the tampered content as a personal-scoped draft.
+                // Per DEC-953 sync rules: personal scope = push (no fork required).
+                // The mutation is best-effort — if the adopt write fails, the file is
+                // kept on disk untouched and a warning is logged. Adopt does NOT
+                // revert; it preserves the user's edits AND records them as a draft.
+                const draftName = basename(tamper.relative).replace(/\.(md|mdc)$/, '') + ' (adopted)';
+                try {
+                    const tamperedContent = readFileSync(tamper.path, 'utf8');
+                    const session = readSession();
+                    const caller = session ? kernelCallWithSession : kernelCall;
+                    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).`,
+                        body: tamperedContent,
+                        assetKind: tamper.relative.includes('/skills/') ? 'skill' : 'rule',
+                        triggers: [],
+                        semanticRefs: [],
+                    });
+                    adoptedTamperedPaths.push(tamper.relative);
+                    trackEvent('setup.tampered.adopted', { path: tamper.relative });
+                }
+                catch (err) {
+                    logErr(`Warning: could not adopt ${tamper.relative} as draft — ${err instanceof Error ? err.message : String(err)}`);
+                    trackEvent('setup.tampered.adopt_failed', {
+                        path: tamper.relative,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+        }
+    }
+    // 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) {
+            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')
+                        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).`);
+                    }
+                }
+                catch (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)}`);
+            }
+        }
+    }
+    // 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)}`);
+                }
+            }
+        }
+        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) {
-            const names = forkedPaths.join(', ');
-            kernelCallWithSession('chain.createEntry', {
-                collectionSlug: 'tensions',
-                name: `TEN: handshake drift — ${forkedPaths.length} adapter(s) forked, sync blocked`,
-                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(() => { });
+            for (const driftDescription of syncDriftTensToFire) {
+                kernelCallWithSession('chain.createEntry', {
+                    collectionSlug: 'tensions',
+                    name: 'TEN: setup authoring sync drift — repo wins',
+                    status: 'draft',
+                    data: {
+                        kind: 'drift',
+                        description: driftDescription,
+                    },
+                    sessionId: session.sessionId,
+                    createdBy: `agent:${session.sessionId}`,
+                }).catch(() => { });
+            }
+        }
+    }
+    // 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 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) {
+            for (const tenDescription of collisionTensToFire) {
+                kernelCallWithSession('chain.createEntry', {
+                    collectionSlug: 'tensions',
+                    name: `TEN: handshake case-collision — ambiguous filename resolved by mtime`,
+                    // Collision 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: tenDescription },
+                    sessionId: session.sessionId,
+                    createdBy: `agent:${session.sessionId}`,
+                }).catch(() => { });
+            }
         }
     }
     // 8b. Setup receipt — record which assets were materialized (apply mode only)
     // Fail-open: receipt write is advisory, never blocks the handshake.
     if (applyMode) {
+        const session = readSession();
+        const caller = session ? kernelCallWithSession : kernelCall;
+        try {
+            const currentState = await caller('setup.getCurrentSetupState', {});
+            const fromMode = currentState?.effectiveMode ?? 'observe';
+            if (fromMode !== manifestStatus.mode) {
+                await caller('setup.recordTransition', {
+                    fromMode,
+                    toMode: manifestStatus.mode,
+                    parseStatus: manifestStatus.parseStatus,
+                    surfaces: manifestStatus.surfaces,
+                    lock: manifestStatus.lock,
+                });
+                if (modeRank(manifestStatus.mode) < modeRank(fromMode)) {
+                    trackEvent('setup.transition.lowered', { fromMode, toMode: manifestStatus.mode });
+                }
+            }
+        }
+        catch (err) {
+            trackEvent('setup.transition.write_failed', { error: err instanceof Error ? err.message : String(err) });
+            logErr(`Warning: could not record setup transition — ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (writeMode) {
         const session = readSession();
         const caller = session ? kernelCallWithSession : kernelCall;
         try {
@@ -901,11 +2399,22 @@ 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.
+        managedCleanCount: cleanBucketPaths.length > 0 ? cleanBucketPaths.length : undefined,
+        adoptedTamperedPaths: adoptedTamperedPaths.length > 0 ? adoptedTamperedPaths : undefined,
+        revertedTamperedPaths: revertedTamperedPaths.length > 0 ? revertedTamperedPaths : undefined,
     };
     if (!quiet) {
         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