create-claude-cabinet 0.39.0 → 0.41.0

package/README.md

@@ -221,6 +221,17 @@ the listed modules to what's already there, it doesn't replace your
 module set. Safe to run on a mature project without losing
 customization. You can pass multiple modules: `--modules verify,audit`.
 
+### Opt-in Modules
+
+| Module | What it does |
+|--------|-------------|
+| **verify** | Cucumber + Playwright walkthrough verification harness |
+| **site-audit** | 14-check deployed-site quality audit with HTML reports |
+| **engagement** | Client engagement management — packets, billing, feedback loops |
+| **engagement-server** | Central multi-engagement API server (Railway/Fly deploy) |
+| **watchtower** | Continuous background state management replacing orient/debrief |
+| **mux** | Multi-project terminal manager — desks, auto-worktrees with shared identity, trail logging, DX captures, portal color-switching, durable tmux bindings, clipboard copy with hard-wrap removal, screenshot-to-clipboard launchd watcher |
+
 ## CLI Options
 
 ```

package/lib/cli.js

@@ -4,7 +4,7 @@ const fs = require('fs');
 const os = require('os');
 const crypto = require('crypto');
 const { copyTemplates } = require('./copy');
-const { mergeSettings, healUserSettings, mergeWatchtowerHooks } = require('./settings-merge');
+const { mergeSettings, healUserSettings, mergeWatchtowerHooks, mergeMuxHooks } = require('./settings-merge');
 const { create: createMetadata, read: readMetadata } = require('./metadata');
 const { setupDb } = require('./db-setup');
 const { setupVerifyRuntime } = require('./verify-setup');
@@ -496,7 +496,7 @@ const MODULES = {
     mandatory: false,
     default: true,
     lean: false,
-    templates: ['rules/enforcement-pipeline.md', 'memory/patterns/_pattern-template.md', 'memory/patterns/pattern-intelligence-first.md'],
+    templates: ['rules/enforcement-pipeline.md', 'rules/maintainability.md', 'memory/patterns/_pattern-template.md', 'memory/patterns/pattern-intelligence-first.md'],
   },
   'memory': {
     name: 'Built-In Memory (cc-remember + reader + validator)',
@@ -623,7 +623,7 @@ const MODULES = {
   },
   watchtower: {
     name: 'Watchtower (continuous background state)',
-    description: 'Replaces orient/debrief with continuous background processing. Three rings (mechanical cron, Claude intelligence, session-aware), ambient state injection via SessionStart hook, and an asynchronous decision queue. Sessions start informed with minimal context cost.',
+    description: 'Replaces orient/debrief with continuous background processing. Three rings (mechanical cron, Claude intelligence, session-aware), ambient state injection via SessionStart hook, and an inbox for extracted knowledge and signals. Sessions start informed with minimal context cost.',
     mandatory: false,
     default: false,
     lean: false,
@@ -632,6 +632,7 @@ const MODULES = {
       'cabinet/watchtower-contracts.md',
       'scripts/watchtower-lib.mjs',
       'scripts/watchtower-queue.mjs',
+      'skills/inbox',
       'skills/decisions',
       'hooks/watchtower-session-start.sh',
       'scripts/watchtower-build-context.mjs',
@@ -651,6 +652,7 @@ const MODULES = {
       'watchtower/watchtower-ring2-slow.timer',
       'hooks/watchtower-session-end.sh',
       'scripts/watchtower-ring3-close.mjs',
+      'scripts/watchtower-status.sh',
       'skills/briefing',
     ],
   },
@@ -1285,6 +1287,11 @@ async function run() {
       mergeWatchtowerHooks(settingsPath);
       console.log('  ⚙️  Registered watchtower SessionStart/SessionEnd hooks');
     }
+
+    if (selectedModules.includes('mux')) {
+      mergeMuxHooks(settingsPath);
+      console.log('  ⚙️  Registered mux worktree health SessionStart hook');
+    }
   }
 
   // --- Heal user-level ~/.claude/settings.json ---
@@ -1308,6 +1315,11 @@ async function run() {
         if (fs.existsSync(mcpJsonPath)) {
           existing = JSON.parse(fs.readFileSync(mcpJsonPath, 'utf8'));
         }
+        // Guard shape drift: .mcpServers set on a top-level array would be
+        // silently dropped on serialize.
+        if (typeof existing !== 'object' || existing === null || Array.isArray(existing)) {
+          existing = {};
+        }
         if (!existing.mcpServers) existing.mcpServers = {};
         Object.assign(existing.mcpServers, mcpConfig.mcpServers);
         fs.writeFileSync(mcpJsonPath, JSON.stringify(existing, null, 2) + '\n');
@@ -1560,6 +1572,15 @@ async function run() {
       if (fs.existsSync(registryPath)) {
         registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
       }
+      // Normalize shape drift: a bare top-level array has been observed
+      // (ad-hoc edit dropped the {"projects": ...} wrapper). Re-wrap so
+      // the update below also heals the file on disk.
+      if (Array.isArray(registry)) {
+        registry = { projects: registry };
+      }
+      if (!Array.isArray(registry.projects)) {
+        registry.projects = [];
+      }
       const existingIdx = registry.projects.findIndex(p => p.path === projectDir);
       const entry = {
         path: projectDir,

package/lib/engagement-server-setup.js

@@ -57,7 +57,11 @@ function compareVersions(a, b) {
 function readGlobalManifest() {
   if (!fs.existsSync(GLOBAL_MANIFEST_PATH)) return { files: {} };
   try {
-    return JSON.parse(fs.readFileSync(GLOBAL_MANIFEST_PATH, 'utf8'));
+    const m = JSON.parse(fs.readFileSync(GLOBAL_MANIFEST_PATH, 'utf8'));
+    // Guard shape drift: manifest.files is indexed unconditionally below.
+    if (typeof m !== 'object' || m === null || Array.isArray(m)) return { files: {} };
+    if (typeof m.files !== 'object' || m.files === null || Array.isArray(m.files)) m.files = {};
+    return m;
   } catch {
     return { files: {} };
   }

package/lib/metadata.js

@@ -10,13 +10,20 @@ function metadataPath(projectDir) {
 
 function read(projectDir) {
   const file = metadataPath(projectDir);
-  if (fs.existsSync(file)) return JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (fs.existsSync(file)) return normalize(JSON.parse(fs.readFileSync(file, 'utf8')));
   // Fall back to legacy manifest from pre-v0.6.0 installs
   const legacyFile = path.join(projectDir, LEGACY_METADATA_FILE);
-  if (fs.existsSync(legacyFile)) return JSON.parse(fs.readFileSync(legacyFile, 'utf8'));
+  if (fs.existsSync(legacyFile)) return normalize(JSON.parse(fs.readFileSync(legacyFile, 'utf8')));
   return null;
 }
 
+// Guard shape drift: callers key into .modules/.manifest/.version — a
+// non-object top level must read as "no metadata", not crash the installer.
+function normalize(data) {
+  if (typeof data !== 'object' || data === null || Array.isArray(data)) return null;
+  return data;
+}
+
 function write(projectDir, data) {
   const file = metadataPath(projectDir);
   fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n');

package/lib/mux-setup.js

@@ -42,6 +42,12 @@ const MANAGED_FILES = [
   { src: 'config/help.txt', dest: path.join(os.homedir(), '.config', 'mux', 'help.txt') },
   { src: 'config/_mux', dest: path.join(os.homedir(), '.config', 'mux', '_mux') },
   { src: 'config/mux.bash', dest: path.join(os.homedir(), '.config', 'mux', 'mux.bash') },
+  { src: 'config/worktree-session-health.sh', dest: path.join(os.homedir(), '.config', 'mux', 'worktree-session-health.sh'), mode: 0o755 },
+  { src: 'config/worktree-health-popup.sh', dest: path.join(os.homedir(), '.config', 'mux', 'worktree-health-popup.sh'), mode: 0o755 },
+  { src: 'config/worktree-cleanup.sh', dest: path.join(os.homedir(), '.config', 'mux', 'worktree-cleanup.sh'), mode: 0o755 },
+  { src: 'config/mux.tmux.conf', dest: path.join(os.homedir(), '.config', 'mux', 'mux.tmux.conf') },
+  { src: 'config/unwrap-copy.py', dest: path.join(os.homedir(), '.config', 'mux', 'unwrap-copy.py'), mode: 0o755 },
+  { src: 'config/screenshot-to-clipboard.sh', dest: path.join(os.homedir(), '.config', 'mux', 'screenshot-to-clipboard.sh'), mode: 0o755 },
 ];
 
 const DATA_DIRS = [
@@ -50,6 +56,7 @@ const DATA_DIRS = [
   path.join(os.homedir(), '.config', 'mux', 'notes'),
   path.join(os.homedir(), '.config', 'mux', 'dx'),
   path.join(os.homedir(), '.config', 'mux', 'pending-prompts'),
+  path.join(os.homedir(), '.local', 'share', 'mux', 'wt-health'),
 ];
 
 function sha256(content) {
@@ -71,7 +78,11 @@ function compareVersions(a, b) {
 function readGlobalManifest() {
   if (!fs.existsSync(GLOBAL_MANIFEST_PATH)) return { files: {} };
   try {
-    return JSON.parse(fs.readFileSync(GLOBAL_MANIFEST_PATH, 'utf8'));
+    const m = JSON.parse(fs.readFileSync(GLOBAL_MANIFEST_PATH, 'utf8'));
+    // Guard shape drift: manifest.files is indexed unconditionally below.
+    if (typeof m !== 'object' || m === null || Array.isArray(m)) return { files: {} };
+    if (typeof m.files !== 'object' || m.files === null || Array.isArray(m.files)) m.files = {};
+    return m;
   } catch {
     return { files: {} };
   }
@@ -183,7 +194,116 @@ function setupMux(opts = {}) {
 
   results.push(`  ${copiedCount} file${copiedCount !== 1 ? 's' : ''} installed to user paths`);
 
+  if (process.platform === 'darwin') {
+    setupDarwinIntegration({ dryRun, results });
+  }
+
   return { results, status: installedVersion ? 'upgraded' : 'installed' };
 }
 
+/**
+ * macOS-specific wiring: tmux.conf source line, live binding reload,
+ * and the screenshot-to-clipboard launchd watcher. All steps are
+ * idempotent and individually fault-tolerant — a failure in one is
+ * reported but never aborts the install.
+ */
+function setupDarwinIntegration({ dryRun, results }) {
+  const { execSync } = require('child_process');
+  const run = (cmd) => execSync(cmd, { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
+
+  // 1. ~/.tmux.conf sources mux.tmux.conf so mux bindings survive tmux
+  //    server restarts (inline bind-key calls from bin/mux evaporate).
+  const tmuxConf = path.join(os.homedir(), '.tmux.conf');
+  const sourceLine = 'source-file -q ~/.config/mux/mux.tmux.conf';
+  try {
+    const existing = fs.existsSync(tmuxConf) ? fs.readFileSync(tmuxConf, 'utf8') : '';
+    if (!existing.includes('mux.tmux.conf')) {
+      if (dryRun) {
+        results.push(`  [dry-run] append "${sourceLine}" to ~/.tmux.conf`);
+      } else {
+        const block = `\n# mux-managed bindings (CC) — keep this line; mux upgrades edit the sourced file\n${sourceLine}\n`;
+        fs.appendFileSync(tmuxConf, block);
+        results.push('  ~/.tmux.conf now sources mux.tmux.conf');
+      }
+    }
+  } catch (err) {
+    results.push(`  ⚠ Could not update ~/.tmux.conf: ${err.message}`);
+  }
+
+  // 2. Apply bindings to a running tmux server immediately.
+  if (!dryRun) {
+    try {
+      run('tmux source-file ~/.config/mux/mux.tmux.conf');
+      results.push('  mux.tmux.conf applied to running tmux server');
+    } catch {
+      // No server running — bindings load at next server start via ~/.tmux.conf.
+    }
+  }
+
+  // 3. Screenshot-to-clipboard launchd watcher. Watches the macOS
+  //    screenshot folder and puts each new screenshot on the clipboard
+  //    as a file reference.
+  const label = 'com.mux.screenshot-to-clipboard';
+  const agentDir = path.join(os.homedir(), 'Library', 'LaunchAgents');
+  const plistPath = path.join(agentDir, `${label}.plist`);
+  const legacyLabel = 'com.orenmagid.screenshot-to-clipboard';
+  const legacyPlist = path.join(agentDir, `${legacyLabel}.plist`);
+  const scriptPath = path.join(os.homedir(), '.config', 'mux', 'screenshot-to-clipboard.sh');
+
+  let shotDir = path.join(os.homedir(), 'Desktop');
+  try {
+    const loc = run('defaults read com.apple.screencapture location');
+    if (loc) shotDir = loc.replace(/^~/, os.homedir());
+  } catch {
+    /* default location */
+  }
+
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>${label}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/bin/bash</string>
+        <string>${scriptPath}</string>
+    </array>
+    <key>WatchPaths</key>
+    <array>
+        <string>${shotDir}</string>
+    </array>
+</dict>
+</plist>
+`;
+
+  if (dryRun) {
+    results.push(`  [dry-run] install launchd watcher ${label} (watching ${shotDir})`);
+    return;
+  }
+
+  try {
+    const uid = run('id -u');
+
+    // Migrate: unload + remove a pre-CC hand-rolled watcher so the two
+    // never double-fire. The old script file is left in place.
+    if (fs.existsSync(legacyPlist)) {
+      try { run(`launchctl bootout gui/${uid}/${legacyLabel}`); } catch { /* not loaded */ }
+      fs.unlinkSync(legacyPlist);
+      results.push(`  migrated legacy watcher (${legacyLabel} removed)`);
+    }
+
+    fs.mkdirSync(agentDir, { recursive: true });
+    const hadPlist = fs.existsSync(plistPath);
+    fs.writeFileSync(plistPath, plist);
+    if (hadPlist) {
+      try { run(`launchctl bootout gui/${uid}/${label}`); } catch { /* not loaded */ }
+    }
+    run(`launchctl bootstrap gui/${uid} ${plistPath}`);
+    results.push(`  screenshot-to-clipboard watcher loaded (watching ${shotDir})`);
+  } catch (err) {
+    results.push(`  ⚠ launchd watcher setup failed: ${err.message}`);
+  }
+}
+
 module.exports = { setupMux };

package/lib/settings-merge.js

@@ -107,6 +107,20 @@ const WATCHTOWER_HOOKS = {
   ],
 };
 
+const MUX_HOOKS = {
+  SessionStart: [
+    {
+      matcher: '',
+      hooks: [
+        {
+          type: 'command',
+          command: '$HOME/.config/mux/worktree-session-health.sh',
+        },
+      ],
+    },
+  ],
+};
+
 // Legacy hook script names that should be stripped on any merge.
 // Centralizes cleanup so a user who skips --migrate-memory but runs
 // any other CC operation still gets omega-era hooks pruned.
@@ -139,6 +153,11 @@ function mergeSettings(projectDir, { includeDb = true } = {}) {
   if (fs.existsSync(settingsPath)) {
     settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
   }
+  // Guard shape drift: setting .hooks on a top-level array would silently
+  // drop it on serialize (JSON.stringify ignores non-index array props).
+  if (typeof settings !== 'object' || settings === null || Array.isArray(settings)) {
+    settings = {};
+  }
 
   if (!settings.hooks) settings.hooks = {};
 
@@ -264,4 +283,29 @@ function mergeWatchtowerHooks(settingsPath) {
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
 }
 
-module.exports = { mergeSettings, healUserSettings, mergeWatchtowerHooks, DEFAULT_HOOKS, WATCHTOWER_HOOKS, LEGACY_HOOK_COMMANDS };
+function mergeMuxHooks(settingsPath) {
+  if (!fs.existsSync(settingsPath)) return;
+  const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  if (!settings.hooks) settings.hooks = {};
+
+  for (const [event, newHooks] of Object.entries(MUX_HOOKS)) {
+    if (!settings.hooks[event]) {
+      settings.hooks[event] = newHooks;
+    } else {
+      for (const newHook of newHooks) {
+        const hookKey = h => h.command || h.prompt || '';
+        const existingKeys = settings.hooks[event].flatMap(h =>
+          h.hooks.map(hh => hookKey(hh))
+        );
+        const newKeys = newHook.hooks.map(h => hookKey(h));
+        if (!newKeys.every(k => existingKeys.includes(k))) {
+          settings.hooks[event].push(newHook);
+        }
+      }
+    }
+  }
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+}
+
+module.exports = { mergeSettings, healUserSettings, mergeWatchtowerHooks, mergeMuxHooks, DEFAULT_HOOKS, WATCHTOWER_HOOKS, MUX_HOOKS, LEGACY_HOOK_COMMANDS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-cabinet",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "description": "Claude Cabinet — opinionated process scaffolding for Claude Code projects",
   "bin": {
     "create-claude-cabinet": "bin/create-claude-cabinet.js"
@@ -8,7 +8,9 @@
   "files": [
     "bin/",
     "lib/",
-    "templates/"
+    "templates/",
+    "!**/__pycache__",
+    "!**/*.pyc"
   ],
   "keywords": [
     "claude",

package/templates/cabinet/_cabinet-member-template.md

@@ -125,33 +125,21 @@ to anchor the boundaries.
 
 ### 7. Historically Problematic Patterns
 
-Two-file overlay:
-
 ```markdown
 ## Historically Problematic Patterns
 
-Two sources — read both and merge at runtime:
-
-1. **This section** (upstream, CC-owned) — universal patterns that apply to
-   any project. Grows when consuming projects promote recurring findings
-   via field-feedback.
-2. **`patterns-project.md`** in this skill's directory — project-specific
-   patterns discovered during audits of this particular project. Project-
-   owned, never overwritten by CC upgrades.
-
-If `patterns-project.md` exists, read it alongside this section. Both
-inform your analysis equally.
-
-**How patterns get here:** A consuming project's audit finds a real issue.
-If the same pattern recurs across projects, it gets promoted upstream via
-field-feedback. The CC maintainer adds it to this section. Project-specific
-patterns that don't generalize stay in `patterns-project.md`.
+If `patterns-project.md` exists in this skill directory, read it for
+project-specific patterns from prior audits and apply alongside the
+universal patterns below. Absent is normal — it is seeded by debrief
+when recurring findings accumulate.
 
 <!-- Universal patterns below this line -->
 ```
 
-This section starts empty for new members. It accumulates from real
-findings over time — never pre-fill with hypothetical patterns.
+This section starts empty for new members. Universal patterns accumulate
+from real field-feedback findings over time — never pre-fill with
+hypothetical patterns. Project-specific patterns live in
+`patterns-project.md` (project-owned, never overwritten by CC upgrades).
 
 ## Optional Sections
 

package/templates/cabinet/watchtower-contracts.md

@@ -17,12 +17,12 @@ fs.renameSync(tmp, filePath);
 
 ## No-Index Convention
 
-The decision queue uses directory listing, not an index file. To list
+The inbox queue uses directory listing, not an index file. To list
 pending items, read `queue/items/`, open each `.json`, filter by
 status. No manifest, no index.json.
 
 Rationale: one fewer file to keep consistent. Directory listing is
-O(n) but n is small (decision queues rarely exceed 50 items). If
+O(n) but n is small (inbox items rarely exceed 50 items). If
 listing exceeds 2 seconds or 500 items, revisit via `act:2b638b02`.
 
 ## Schema Versioning
@@ -70,7 +70,7 @@ standard files:
 | `memory-refs.md` | Ring 2 fast | Relevant memory entries |
 | `options-analysis.md` | Ring 2 fast | Pros/cons with evidence |
 
-`/decisions` reads these when `enrichment_status` is `"complete"`.
+`/inbox` reads these when `enrichment_status` is `"complete"`.
 Missing files degrade gracefully (null in the read result).
 
 ## Deferred Schemas
@@ -85,3 +85,75 @@ their owning plan ships:
 | `hooks/<ring>-<phase>.d/` | Plan 9 | Lifecycle hooks |
 | `logs/<ring>.log` | Plan 4 | Ring 1 runner |
 | `lock/<ring>.pid` | Plan 4 | Ring 1 runner |
+
+## Ring 4 — Periodic Truth Reconciliation (design phase)
+
+**Status: concept. Needs design session before implementation.**
+
+Rings 1–3 operate on individual signals: individual files (R1),
+individual patterns (R2), individual sessions (R3). Nothing catches
+**cumulative drift** — the slow rot where twenty sessions each move
+reality a little further from what documents claim, but no single
+session is the tipping point.
+
+Ring 4 is the answer to: "Is what we wrote still true?"
+
+### The problem it solves
+
+The maginnis project's architecture briefing said "Layer 4 Not built"
+and "tech stack TBD" for three weeks after the platform shipped with
+a Rails 8 app, Mantine frontend, 421 RSpec specs, and staging on
+Railway. No individual session caused the staleness. No individual
+session's debrief would flag it. The drift was invisible until
+someone tried to use the briefing for a real audit and found it
+described a project that no longer existed.
+
+This class of problem includes:
+- **Briefing-to-codebase drift** — claims about architecture, tech
+  stack, file layout, or project state that no longer match reality
+- **Memory-to-codebase drift** — memory files that reference
+  functions, files, or flags that have been renamed or removed
+- **CLAUDE.md drift** — sections describing architecture or
+  conventions that have been refactored past
+- **Plan-to-reality drift** — plan files describing work that's been
+  done but never marked complete, or describing approaches that were
+  abandoned
+
+### Cadence and weight
+
+Less frequent than R1–R3. Daily or weekly, not per-session or
+per-minute. Heavier per run — reads real code, cross-references
+document claims against codebase state, may invoke Claude for
+semantic comparison. Acceptable cost because it runs rarely and
+catches problems that compound silently.
+
+### Relationship to other rings
+
+Following the nervous system principle (not a stack): R4 consumes
+signals from R1–R3 (what changed recently, what sessions touched,
+what patterns emerged) to prioritize what to reconcile. R4 produces
+inbox items when drift is detected. R4 does not mutate documents —
+it flags, the user triages and routes.
+
+R3 catches "this session broke the briefing." R4 catches "the
+briefing has been slowly wrong for three weeks and nobody noticed."
+They're complementary, not redundant.
+
+### Open design questions
+
+- **Scope per run:** Reconcile everything every time, or rotate
+  through documents on a schedule? Full sweep is thorough but
+  expensive; rotation risks missing urgent drift on off-cycle docs.
+- **Drift threshold:** How wrong does a document need to be before
+  it's worth flagging? A missing model in the architecture briefing
+  is clear; a slightly outdated line count is noise.
+- **Trigger vs schedule:** Pure schedule (weekly), or also triggered
+  when R1/R2 detect significant codebase changes (new migration,
+  major refactor, new dependency)?
+- **Cross-project scope:** Per-project reconciliation, or also
+  cross-project (e.g., a CC template claiming something about
+  consumer behavior that's no longer true)?
+- **Relationship to Ring 2 slow tier:** R2 slow already does some
+  staleness detection (stale work, memory hygiene). Where's the line
+  between R2's "is this work item stale?" and R4's "is this document
+  still true?" Is R4 an extension of R2 slow, or genuinely distinct?

package/templates/engagement-server/Dockerfile

@@ -1,5 +1,7 @@
 FROM node:20-slim
 
+RUN apt-get update && apt-get install -y python3 make g++ && rm -rf /var/lib/apt/lists/*
+
 WORKDIR /app
 
 COPY package.json package-lock.json* ./

package/templates/engagement-server/server.mjs

@@ -73,7 +73,7 @@ function hashToken(raw) {
   return createHash('sha256').update(raw).digest('hex');
 }
 
-function resolveToken(tokenHash) {
+function resolveLocalToken(tokenHash) {
   return db.prepare(`
     SELECT u.id AS user_id, u.engagement_id, u.role, u.name AS user_name,
            e.auth_mode, e.auth_config
@@ -84,31 +84,83 @@ function resolveToken(tokenHash) {
   `).get(tokenHash);
 }
 
+function getExternalEngagements() {
+  return db.prepare(`
+    SELECT id, auth_config FROM engagements
+    WHERE auth_mode = 'external' AND auth_config IS NOT NULL
+  `).all();
+}
+
+function resolveExternalUser(engagementId, email, roleMapping) {
+  const user = db.prepare(`
+    SELECT id AS user_id, engagement_id, role, name AS user_name
+    FROM users
+    WHERE engagement_id = ? AND email = ?
+  `).get(engagementId, email);
+  if (user) return user;
+
+  return null;
+}
+
 async function authenticateRequest(req) {
   const authHeader = req.headers['authorization'];
   if (!authHeader || !authHeader.startsWith('Bearer ')) return null;
 
   const raw = authHeader.slice(7);
-  const tokenData = resolveToken(hashToken(raw));
-  if (!tokenData) return null;
 
-  if (tokenData.auth_mode === 'external' && tokenData.auth_config) {
+  // Path 1: local token lookup (works for all auth modes)
+  const localData = resolveLocalToken(hashToken(raw));
+  if (localData && localData.auth_mode === 'local') return localData;
+
+  // Path 2: external auth — forward token to client app's validate_url
+  const externals = getExternalEngagements();
+  for (const eng of externals) {
     try {
-      const config = JSON.parse(tokenData.auth_config);
-      if (config.validate_url) {
-        const resp = await fetch(config.validate_url, {
-          headers: { 'Authorization': `Bearer ${raw}` },
-          signal: AbortSignal.timeout(5000),
-        });
-        if (!resp.ok) return null;
-      }
+      const config = JSON.parse(eng.auth_config);
+      if (!config.validate_url) continue;
+
+      const resp = await fetch(config.validate_url, {
+        headers: { 'Authorization': `Bearer ${raw}` },
+        signal: AbortSignal.timeout(5000),
+      });
+      if (!resp.ok) continue;
+
+      const identity = await resp.json();
+      const email = identity.email;
+      if (!email) continue;
+
+      // Map platform role to engagement role via role_mapping
+      const roleMapping = config.role_mapping || {};
+      const mappedRole = roleMapping[identity.role] || identity.role;
+
+      // Find matching local user by email for message attribution
+      const user = resolveExternalUser(eng.id, email, roleMapping);
+      if (user) return { ...user, auth_mode: 'external' };
+
+      // User authenticated with platform but no local user record —
+      // auto-create so messages are properly attributed
+      const userId = `usr_${randomBytes(6).toString('hex')}`;
+      const engRole = ['consultant', 'client'].includes(mappedRole) ? mappedRole : 'client';
+      db.prepare(`INSERT INTO users (id, engagement_id, name, email, role) VALUES (?, ?, ?, ?, ?)`)
+        .run(userId, eng.id, email.split('@')[0], email, engRole);
+
+      return {
+        user_id: userId,
+        engagement_id: eng.id,
+        role: engRole,
+        user_name: email.split('@')[0],
+        auth_mode: 'external',
+      };
     } catch (err) {
-      console.error(`External auth failed: ${err.message}`);
-      return { error: 'auth_backend_unavailable' };
+      console.error(`External auth failed for engagement ${eng.id}: ${err.message}`);
     }
   }
 
-  return tokenData;
+  // Path 3: local token in an external-auth engagement (consultant-side
+  // tokens may still be locally managed)
+  if (localData) return localData;
+
+  return null;
 }
 
 // ---------------------------------------------------------------------------
@@ -278,18 +330,18 @@ const server = createServer(async (req, res) => {
   const path = url.pathname;
   const method = req.method;
 
+  // Health check — no auth, before HTTPS enforcement (Railway internal probes lack x-forwarded-proto)
+  if (path === '/health' && method === 'GET') {
+    logRequest(req, 200, null);
+    return json(res, 200, { ok: true, version: SCHEMA_VERSION });
+  }
+
   // HTTPS enforcement (Railway terminates TLS)
   if (process.env.RAILWAY_ENVIRONMENT && req.headers['x-forwarded-proto'] !== 'https') {
     logRequest(req, 421, null);
     return json(res, 421, { error: 'https_required' });
   }
 
-  // Health check — no auth
-  if (path === '/health' && method === 'GET') {
-    logRequest(req, 200, null);
-    return json(res, 200, { ok: true, version: SCHEMA_VERSION });
-  }
-
   // All other routes require auth
   const authHeader = req.headers['authorization'];
   if (!authHeader || !authHeader.startsWith('Bearer ')) {