@productbrain/cli 0.1.0-beta.100 → 0.1.0-beta.104

package/dist/commands/handshake.d.ts

@@ -1,7 +1,74 @@
 /**
  * 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 type { WorkspaceHealthResult } from './workspace.js';
+/**
+ * Wire-safe alias for a single health gap.
+ * Derived from the CLI mirror in workspace.ts — no convex/ import needed.
+ */
+export type HealthGap = WorkspaceHealthResult['gaps'][number];
+/**
+ * Structured result returned by probeStarterSetupSeeded when seeds are still
+ * pending or when the health query is unavailable.
+ */
+export type SeedsPendingResult = {
+    status: 'seeds-pending';
+    gaps: ReadonlyArray<HealthGap>;
+} | {
+    status: 'seeds-ready';
+} | {
+    status: 'probe-failed';
+    error: string;
+};
+/**
+ * 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 declare const DORMANT_MARKER = "<!-- pb-status: dormant -->";
+/**
+ * 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 declare function writeDormantMarkerToFile(filePath: string): 'written' | 'already-dormant' | 'skipped';
+/**
+ * Single-shot health probe — calls `workspace.health` and inspects
+ * `starterSetupSeeded`. Does NOT poll internally; polling is the caller's
+ * responsibility (connect-screens.tsx).
+ *
+ * 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 declare function probeStarterSetupSeeded(): Promise<SeedsPendingResult>;
+/**
+ * Poll `probeStarterSetupSeeded` up to MAX_POLLS times (10s at 500ms intervals).
+ * Returns the final probe result — caller decides how to render the outcome.
+ *
+ * Exported so connect-screens.tsx can use it without re-implementing the loop.
+ */
+export declare function pollUntilSeedsReady(): Promise<SeedsPendingResult>;
 export declare function runHandshakeInit(options?: {
     level?: string;
     dryRun?: boolean;
@@ -25,6 +92,51 @@ interface HandshakeOptions {
  * meaningless rewrites when semantic content is unchanged.
  */
 export declare function normalizeHandshakeContentForComparison(content: string): string;
+/**
+ * Result of a single unlink decision during resolveProjectionCollision.
+ */
+type CollisionUnlinkResult = {
+    action: 'kept';
+    filePath: string;
+    reason: string;
+} | {
+    action: 'unlinked';
+    filePath: string;
+    reason: string;
+} | {
+    action: 'collision-ten';
+    filePath: string;
+    reason: string;
+};
+/**
+ * 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-forked 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 declare function resolveProjectionCollision(cwd: string, assetNames: string[], log: (msg: string) => void, logErr: (msg: string) => void): {
+    results: CollisionUnlinkResult[];
+    collisionTens: string[];
+};
 export declare function runHandshake(options?: HandshakeOptions): Promise<void>;
 export {};
 //# sourceMappingURL=handshake.d.ts.map

package/dist/commands/handshake.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../../src/commands/handshake.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA4LH,wBAAsB,gBAAgB,CAAC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CA2HxG;AACD,UAAU,gBAAgB;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qFAAqF;IACrF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,sCAAsC,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAO9E;AAsBD,wBAAsB,YAAY,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwtBhF"}
+{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../../src/commands/handshake.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuDH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAK5D;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;CAAE,GAC3D;IAAE,MAAM,EAAE,aAAa,CAAA;CAAE,GACzB;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAQ9C;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,gCAAgC,CAAC;AAU5D;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,iBAAiB,GAAG,SAAS,CAWpG;AAuCD;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAyB3E;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAYvE;AAsID,wBAAsB,gBAAgB,CAAC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CA2HxG;AACD,UAAU,gBAAgB;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qFAAqF;IACrF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,sCAAsC,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAO9E;AAwBD;;GAEG;AACH,KAAK,qBAAqB,GACtB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAAE,EACpB,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,EAC1B,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAC5B;IAAE,OAAO,EAAE,qBAAqB,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAE,CAkJ/D;AAED,wBAAsB,YAAY,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA41BhF"}

package/dist/commands/handshake.js

@@ -1,9 +1,9 @@
 /**
  * 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 } from 'fs';
+import { join, dirname, resolve, basename } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
@@ -26,6 +26,155 @@ import { generateBoundaryManifest, getBoundaryEnforcementMode } from '../generat
 import { loadMethodRegistry } from '../lib/method-registry.js';
 import { CLIError, ErrorCode } from '../lib/errors.js';
 import { trackEvent } from '../lib/telemetry.js';
+import { normalizeMaterializedFilename } from '../lib/normalizeMaterializedFilename.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';
+}
+/**
+ * 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      Array of absolute file paths to probe.
+ */
+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 paths = [];
+    const { name, assetKind } = asset;
+    if (assetKind === 'skill') {
+        // Cursor skill
+        paths.push(join(cwd, '.cursor', 'skills', name, 'SKILL.md'));
+        // Codex skill
+        paths.push(join(cwd, '.codex', 'skills', `${name}.md`));
+    }
+    else if (assetKind === 'rule' || assetKind === 'hook') {
+        // Cursor rule
+        paths.push(join(cwd, '.cursor', 'rules', `${name}.mdc`));
+        // Claude rule
+        paths.push(join(cwd, '.claude', 'rules', `${name}.md`));
+    }
+    return paths;
+}
+/**
+ * Single-shot health probe — calls `workspace.health` and inspects
+ * `starterSetupSeeded`. Does NOT poll internally; polling is the caller's
+ * responsibility (connect-screens.tsx).
+ *
+ * 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-screens.tsx 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',
@@ -282,6 +431,164 @@ 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-forked 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-forked — 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));
     if (!config)
@@ -369,10 +676,34 @@ export async function runHandshake(options = {}) {
     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-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();
     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 = [];
+                hasAnyReceipt = undefined; // unknown on legacy servers
+            }
+            else {
+                dbAssets = rawResponse.activeAssets ?? [];
+                dormantDbAssetRows = rawResponse.dormantAssets ?? [];
+                // WP-379 S5b: extract hasAnyReceipt when provided by the server.
+                // undefined means pre-S5b server — we treat as unknown (no receipts assumed).
+                hasAnyReceipt = rawResponse.hasAnyReceipt;
+            }
+        }
+        if (dbAssets.length > 0) {
             dbAssetRows = dbAssets;
             // Map DB assets to CanonicalSkill/CanonicalRule shapes
             for (const asset of dbAssets) {
@@ -399,6 +730,9 @@ export async function runHandshake(options = {}) {
             }
             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 {
@@ -788,6 +1122,20 @@ export async function runHandshake(options = {}) {
             target: 'claude',
         });
     }
+    // 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 (applyMode && usedDbSource) {
+        const activeAssetNames = dbAssetRows
+            .filter((a) => !a.disabledByOwner)
+            .map((a) => a.name);
+        const { collisionTens } = resolveProjectionCollision(cwd, activeAssetNames, log, logErr);
+        collisionTensToFire.push(...collisionTens);
+    }
     const forkedPaths = [];
     const projectedHashUpdates = new Map();
     const recordProjectedHash = (entryId) => {
@@ -868,21 +1216,93 @@ export async function runHandshake(options = {}) {
             }
         });
     }
-    // 8. Drift logging — if apply mode encountered forked adapters and a session is active, log a draft TEN
+    // 8a. Dormant marker writes (WP-379 S4) — apply mode only.
+    // For each dormant asset (gate-filtered by the server), locate any previously-projected
+    // on-disk files and append the DORMANT_MARKER trailer. Files are NOT deleted.
+    //
+    // Drift TEN exclusion: dormant-marked files have the auto-gen MARKER, so
+    // shouldWriteAdapter() returns true for them. However, because the asset is dormant,
+    // it is NOT in the `writes` array — it was never queued for a fresh write. Therefore,
+    // dormant files will never appear in forkedPaths (forkedPaths only catches files that
+    // ARE in the writes array but fail shouldWriteAdapter). The dormant marker write is a
+    // separate, independent pass that runs BEFORE the drift TEN check — intentionally
+    // after the main write loop to avoid interfering with active asset writes.
+    //
+    // Fail-open: if a dormant marker write fails, log and continue. Never crash the handshake.
+    const dormantMarkedPaths = [];
+    if (applyMode && dormantDbAssetRows.length > 0) {
+        for (const dormantAsset of dormantDbAssetRows) {
+            const candidatePaths = deriveDormantFilePaths(dormantAsset, cwd);
+            for (const filePath of candidatePaths) {
+                try {
+                    const markerResult = writeDormantMarkerToFile(filePath);
+                    if (markerResult === 'written') {
+                        dormantMarkedPaths.push(filePath);
+                        log(`Dormant marker written: ${filePath}`);
+                    }
+                    // 'already-dormant' and 'skipped' are silent no-ops — idempotent.
+                }
+                catch (err) {
+                    // Fail-open: dormant marker write is advisory. Log, never throw.
+                    logErr(`Warning: could not write dormant marker to ${filePath} — ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+    }
+    // 8. Drift logging — if apply mode encountered forked adapters and a session is active, log a draft TEN.
+    // Dormant-marked files are NOT forked — they were intentionally deactivated and have the auto-gen MARKER.
+    // They will never appear in forkedPaths because they are excluded from the `writes` array entirely.
+    //
+    // WP-379 S5b — First-run UX rule:
+    // When `hasAnyReceipt` is false OR undefined (unknown / pre-S5b server), drift TENs are suppressed.
+    // Rationale: on the first handshake, users may have pre-existing non-marked files from manual
+    // setup; we must not flood them with TENs before they've even had one successful materialization.
+    // A TEN fires only after setup_receipt.count >= 1 for this workspace.
+    //
+    // Conservative unknown-treatment: if the server does not provide hasAnyReceipt (old server),
+    // we treat it as "no receipt exists" and suppress the TEN. The day-1 experience is more important
+    // than catching every early drift case; the TEN will fire on the next run once the server is updated.
+    const isFirstRun = hasAnyReceipt !== true; // true when no receipts or unknown
     if (forkedPaths.length > 0) {
+        if (isFirstRun) {
+            log(`Info: ${forkedPaths.length} adapter(s) skipped (user files without auto-gen marker). ` +
+                'Drift TEN suppressed — first run (no setup receipt yet). Files: ' +
+                forkedPaths.join(', '));
+        }
+        else {
+            const session = readSession();
+            if (session) {
+                const names = forkedPaths.join(', ');
+                kernelCallWithSession('chain.createEntry', {
+                    collectionSlug: 'tensions',
+                    name: `TEN: handshake drift — ${forkedPaths.length} adapter(s) forked, sync blocked`,
+                    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(() => { });
+            }
+        }
+    }
+    // 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
+    // first-run status (collision is a data quality issue, not a drift issue).
+    if (collisionTensToFire.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 tenDescription of collisionTensToFire) {
+                kernelCallWithSession('chain.createEntry', {
+                    collectionSlug: 'tensions',
+                    name: `TEN: handshake case-collision — ambiguous filename resolved by mtime`,
+                    status: 'draft',
+                    data: { description: tenDescription },
+                    sessionId: session.sessionId,
+                    createdBy: `agent:${session.sessionId}`,
+                }).catch(() => { });
+            }
         }
     }
     // 8b. Setup receipt — record which assets were materialized (apply mode only)