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

package/dist/commands/handshake.js

@@ -8,7 +8,7 @@ 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,12 +21,19 @@ 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 { 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
@@ -419,6 +426,224 @@ 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;
+    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: {} };
+        }
+        return { version: 1, assets: parsed.assets };
+    }
+    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 forked-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 = [];
@@ -672,16 +897,132 @@ 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();
     // WP-379 S5b: whether any setup_receipt exists for this workspace (first-run UX gate).
     // undefined when server is pre-S5b (treat as unknown → suppress drift TENs conservatively).
     let hasAnyReceipt = undefined;
     const dbProjectionHashes = new Map();
+    const syncDriftTensToFire = [];
+    const deferredAuthoringBaselineEntryIds = new Set();
+    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,
+                            });
+                            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 {
         // WP-379 S4: listAssetsForUser now returns { activeAssets, dormantAssets }.
         // Wire format changed from DbAsset[] to { activeAssets: DbAsset[], dormantAssets: DbAsset[] }.
@@ -705,16 +1046,53 @@ export async function runHandshake(options = {}) {
         }
         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) {
+                    logErr(`${bodyFetchFailedEntryIds.size} asset(s) skipped due to body fetch failure: ${[...bodyFetchFailedEntryIds].join(', ')}`);
+                }
+            }
             // 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}`,
                     });
                 }
@@ -723,7 +1101,7 @@ export async function runHandshake(options = {}) {
                         name: asset.name,
                         description: asset.description,
                         autoApply: false,
-                        body: asset.body,
+                        body: resolvedBody,
                         sourcePath: `db:${asset.entryId}`,
                     });
                 }
@@ -747,7 +1125,7 @@ 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) {
@@ -895,9 +1273,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;
@@ -964,7 +1339,7 @@ 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,
         }
@@ -1017,10 +1392,117 @@ export async function runHandshake(options = {}) {
     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;
+            const relativeAuthoringPath = authoringPath.replace(cwd + '/', '');
+            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 },
@@ -1129,25 +1611,49 @@ export async function runHandshake(options = {}) {
     // 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 (applyMode && usedDbSource) {
+    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 forkedPaths = [];
     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);
     };
     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' });
@@ -1163,6 +1669,13 @@ export async function runHandshake(options = {}) {
             }
             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)) {
@@ -1187,11 +1700,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' });
@@ -1199,7 +1745,7 @@ export async function runHandshake(options = {}) {
                 continue;
             }
         }
-        writeFileSync(w.path, w.content);
+        writeFileSync(w.path, resolvedContent);
         filesWritten.push(w.relative);
         recordProjectedHash(w.dbAssetEntryId);
     }
@@ -1216,6 +1762,184 @@ export async function runHandshake(options = {}) {
             }
         });
     }
+    // ── 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,
+                    driftConflicts: forkedPaths.length > 0 ? forkedPaths : 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 writes (WP-379 S4) — apply mode only.
     // For each dormant asset (gate-filtered by the server), locate any previously-projected
     // on-disk files and append the DORMANT_MARKER trailer. Files are NOT deleted.
@@ -1230,11 +1954,12 @@ export async function runHandshake(options = {}) {
     //
     // Fail-open: if a dormant marker write fails, log and continue. Never crash the handshake.
     const dormantMarkedPaths = [];
-    if (applyMode && dormantDbAssetRows.length > 0) {
+    if (writeMode && dormantDbAssetRows.length > 0) {
         for (const dormantAsset of dormantDbAssetRows) {
             const candidatePaths = deriveDormantFilePaths(dormantAsset, cwd);
             for (const filePath of candidatePaths) {
                 try {
+                    assertSetupWritePath(filePath, perimeterManifest);
                     const markerResult = writeDormantMarkerToFile(filePath);
                     if (markerResult === 'written') {
                         dormantMarkedPaths.push(filePath);
@@ -1276,6 +2001,8 @@ export async function runHandshake(options = {}) {
                 kernelCallWithSession('chain.createEntry', {
                     collectionSlug: 'tensions',
                     name: `TEN: handshake drift — ${forkedPaths.length} adapter(s) forked, sync blocked`,
+                    // Drift audit TENs intentionally stay draft — they need explicit human review,
+                    // not auto-commit, even in Open mode (mirrors smart-capture.ts recordCommitFailure).
                     status: 'draft',
                     data: {
                         description: `pb handshake --apply encountered forked adapters that blocked sync. Files: ${names}. Use --force to overwrite or resolve drift manually.`,
@@ -1286,6 +2013,24 @@ export async function runHandshake(options = {}) {
             }
         }
     }
+    if (syncDriftTensToFire.length > 0) {
+        const session = readSession();
+        if (session) {
+            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) — fire after the first-run gate.
     // These are distinct from drift TENs: they record ambiguous filename collisions
     // where the "newest mtime wins" heuristic was applied. They fire regardless of
@@ -1297,6 +2042,8 @@ export async function runHandshake(options = {}) {
                 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,
@@ -1308,6 +2055,30 @@ export async function runHandshake(options = {}) {
     // 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 {
@@ -1340,6 +2111,12 @@ export async function runHandshake(options = {}) {
         preview: preview ? true : undefined,
         previewPlan: preview && previewPlan.length > 0 ? previewPlan : undefined,
         driftConflicts: forkedPaths.length > 0 ? forkedPaths : 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');