@geraldmaron/construct 1.4.2 → 1.5.1

package/lib/hooks/pre-compact.mjs

@@ -21,10 +21,12 @@ import { join } from 'path';
 import { writeContextState, contextMarkdownPath, contextJsonPath } from '../context-state.mjs';
 import { flushReadTrackerDeltas } from '../read-tracker-store.mjs';
 import { doctorRoot } from '../config/xdg.mjs';
+import { isMainModule } from '../roots.mjs';
 
 // Section headings that are auto-generated by this hook. Any other heading in
 // the existing context.md is treated as manually authored and preserved.
-const AUTO_SECTION_NAMES = new Set([
+// Exported so tests exercise the real set instead of a re-pasted copy.
+export const AUTO_SECTION_NAMES = new Set([
   'what was in progress',
   'files changed this session',
   'decisions captured',
@@ -38,7 +40,7 @@ const AUTO_SECTION_NAMES = new Set([
  * Parse a markdown string into `[{heading, level, body}]` sections.
  * Returns an empty array for empty/missing input.
  */
-function parseSections(md) {
+export function parseSections(md) {
   if (!md) return [];
   const lines = md.split('\n');
   const sections = [];
@@ -60,7 +62,7 @@ function parseSections(md) {
  * Extract sections from an existing context.md that were NOT auto-generated.
  * Returns a markdown string (may be empty) to append after the auto content.
  */
-function extractManualSections(mdPath) {
+export function extractManualSections(mdPath) {
   if (!existsSync(mdPath)) return '';
   let existing = '';
   try { existing = readFileSync(mdPath, 'utf8'); } catch { return ''; }
@@ -76,7 +78,7 @@ function extractManualSections(mdPath) {
  * Merge non-empty arrays from existing context.json into the new state to
  * prevent the hook from discarding decisions/filesChanged captured manually.
  */
-function mergeExistingJson(jsonPath, newState) {
+export function mergeExistingJson(jsonPath, newState) {
   if (!existsSync(jsonPath)) return newState;
   let existing = {};
   try { existing = JSON.parse(readFileSync(jsonPath, 'utf8')); } catch { return newState; }
@@ -89,198 +91,204 @@ function mergeExistingJson(jsonPath, newState) {
   return merged;
 }
 
-let input = {};
-try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+// Guard the hook body so importing this module for its exported helpers
+// (tests, other tools) does not trigger the stdin read + process.exit(0).
+// Mirrors the entrypoint guard already used in lib/hooks/rule-verifier.mjs.
 
-try { flushReadTrackerDeltas({ env: process.env }); } catch { /* best effort */ }
+if (isMainModule(import.meta.url)) {
+  let input = {};
+  try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
 
-const cwd = input?.cwd || process.cwd();
-const transcriptPath = input?.transcript_path || '';
+  try { flushReadTrackerDeltas({ env: process.env }); } catch { /* best effort */ }
 
-const filesChanged = [];
-const decisions = [];
-const pendingTodos = [];
-const warnFlagsPath = join(doctorRoot(), 'warn-flags.txt');
-const efficiencyPath = join(doctorRoot(), 'session-efficiency.json');
-let lastSummary = '';
+  const cwd = input?.cwd || process.cwd();
+  const transcriptPath = input?.transcript_path || '';
 
-if (transcriptPath && existsSync(transcriptPath)) {
-  try {
-    const transcriptRaw = readFileSync(transcriptPath, 'utf8');
-    let transcript;
+  const filesChanged = [];
+  const decisions = [];
+  const pendingTodos = [];
+  const warnFlagsPath = join(doctorRoot(), 'warn-flags.txt');
+  const efficiencyPath = join(doctorRoot(), 'session-efficiency.json');
+  let lastSummary = '';
+
+  if (transcriptPath && existsSync(transcriptPath)) {
     try {
-      transcript = JSON.parse(transcriptRaw);
-    } catch {
-      transcript = transcriptRaw
-        .split('\n')
-        .filter(Boolean)
-        .map((line) => {
-          try { return JSON.parse(line); } catch { return null; }
-        })
-        .filter(Boolean);
-    }
-    const messages = Array.isArray(transcript) ? transcript : (transcript.messages || []);
-    const recent = messages.slice(-60);
+      const transcriptRaw = readFileSync(transcriptPath, 'utf8');
+      let transcript;
+      try {
+        transcript = JSON.parse(transcriptRaw);
+      } catch {
+        transcript = transcriptRaw
+          .split('\n')
+          .filter(Boolean)
+          .map((line) => {
+            try { return JSON.parse(line); } catch { return null; }
+          })
+          .filter(Boolean);
+      }
+      const messages = Array.isArray(transcript) ? transcript : (transcript.messages || []);
+      const recent = messages.slice(-60);
 
-    // Track the latest TodoWrite call to get current todo state
-    let latestTodos = null;
+      // Track the latest TodoWrite call to get current todo state
+      let latestTodos = null;
 
-    for (const msg of recent) {
-      if (msg.role === 'tool' || msg.type === 'tool_result') continue;
+      for (const msg of recent) {
+        if (msg.role === 'tool' || msg.type === 'tool_result') continue;
 
-      // Handle both array-of-blocks and plain-string content formats
-      const blocks = Array.isArray(msg.content)
-        ? msg.content
-        : (typeof msg.content === 'string' ? [{ type: 'text', text: msg.content }] : []);
+        // Handle both array-of-blocks and plain-string content formats
+        const blocks = Array.isArray(msg.content)
+          ? msg.content
+          : (typeof msg.content === 'string' ? [{ type: 'text', text: msg.content }] : []);
 
-      for (const block of blocks) {
-        if (block.type === 'tool_use' && (block.name === 'Write' || block.name === 'Edit')) {
-          const fp = block.input?.file_path || block.input?.path || '';
-          if (fp && !filesChanged.includes(fp)) filesChanged.push(fp);
-        }
-        if (block.type === 'tool_use' && block.name === 'TodoWrite') {
-          const todos = block.input?.todos;
-          if (Array.isArray(todos)) latestTodos = todos;
-        }
-        if (block.type === 'text' && msg.role === 'assistant') {
-          const text = (block.text || '').trim();
-          // Prefer the last substantive response (>80 chars) over short one-liners
-          if (text.length > 80 || (!lastSummary && text.length > 0)) {
-            lastSummary = text.slice(0, 400);
+        for (const block of blocks) {
+          if (block.type === 'tool_use' && (block.name === 'Write' || block.name === 'Edit')) {
+            const fp = block.input?.file_path || block.input?.path || '';
+            if (fp && !filesChanged.includes(fp)) filesChanged.push(fp);
+          }
+          if (block.type === 'tool_use' && block.name === 'TodoWrite') {
+            const todos = block.input?.todos;
+            if (Array.isArray(todos)) latestTodos = todos;
           }
-          const decisionMatches = text.match(/(?:^|\n)(?:DECISION:|Decision:|\*\*Decision\*\*:)\s*([^\n]+)/g) || [];
-          for (const match of decisionMatches) {
-            const cleaned = match.replace(/^\n?/, '').replace(/^(?:DECISION:|Decision:|\*\*Decision\*\*:)\s*/, '').trim();
-            if (cleaned && !decisions.includes(cleaned)) decisions.push(cleaned);
+          if (block.type === 'text' && msg.role === 'assistant') {
+            const text = (block.text || '').trim();
+            // Prefer the last substantive response (>80 chars) over short one-liners
+            if (text.length > 80 || (!lastSummary && text.length > 0)) {
+              lastSummary = text.slice(0, 400);
+            }
+            const decisionMatches = text.match(/(?:^|\n)(?:DECISION:|Decision:|\*\*Decision\*\*:)\s*([^\n]+)/g) || [];
+            for (const match of decisionMatches) {
+              const cleaned = match.replace(/^\n?/, '').replace(/^(?:DECISION:|Decision:|\*\*Decision\*\*:)\s*/, '').trim();
+              if (cleaned && !decisions.includes(cleaned)) decisions.push(cleaned);
+            }
           }
         }
       }
-    }
 
-    // Extract pending/in_progress todos from latest TodoWrite
-    if (latestTodos) {
-      for (const todo of latestTodos) {
-        if (todo.status === 'pending' || todo.status === 'in_progress') {
-          pendingTodos.push(todo);
+      // Extract pending/in_progress todos from latest TodoWrite
+      if (latestTodos) {
+        for (const todo of latestTodos) {
+          if (todo.status === 'pending' || todo.status === 'in_progress') {
+            pendingTodos.push(todo);
+          }
         }
       }
-    }
 
-  } catch { /* best effort */ }
-}
+    } catch { /* best effort */ }
+  }
+
+  const warnFlags = (() => {
+    try { return readFileSync(warnFlagsPath, 'utf8').trim(); } catch { return ''; }
+  })();
 
-const warnFlags = (() => {
-  try { return readFileSync(warnFlagsPath, 'utf8').trim(); } catch { return ''; }
-})();
-
-const efficiencySummary = (() => {
-  try {
-    const stats = JSON.parse(readFileSync(efficiencyPath, 'utf8'));
-    const parts = [
-      `${stats.readCount || 0} reads`,
-      `${stats.uniqueFileCount || 0} unique files`,
-    ];
-    if (stats.repeatedReadCount) parts.push(`${stats.repeatedReadCount} repeated reads`);
-    if (stats.largeReadCount) parts.push(`${stats.largeReadCount} large reads`);
-    if (stats.totalBytesRead) parts.push(`${Math.round(stats.totalBytesRead / 1024)} KB read`);
-    return parts.join(' · ');
-  } catch {
-    return '';
+  const efficiencySummary = (() => {
+    try {
+      const stats = JSON.parse(readFileSync(efficiencyPath, 'utf8'));
+      const parts = [
+        `${stats.readCount || 0} reads`,
+        `${stats.uniqueFileCount || 0} unique files`,
+      ];
+      if (stats.repeatedReadCount) parts.push(`${stats.repeatedReadCount} repeated reads`);
+      if (stats.largeReadCount) parts.push(`${stats.largeReadCount} large reads`);
+      if (stats.totalBytesRead) parts.push(`${Math.round(stats.totalBytesRead / 1024)} KB read`);
+      return parts.join(' · ');
+    } catch {
+      return '';
+    }
+  })();
+
+  const projectName = cwd.split('/').pop() || 'project';
+  const date = new Date().toISOString().slice(0, 16).replace('T', ' ');
+
+  const contextLines = [
+    `# Session Context`,
+    `Last saved: ${date}`,
+    ``,
+    `## What was in progress`,
+    lastSummary || '(no summary available)',
+    ``,
+  ];
+
+  if (filesChanged.length) {
+    contextLines.push('## Files changed this session');
+    for (const f of filesChanged.slice(0, 20)) contextLines.push(`- ${f}`);
+    contextLines.push('');
   }
-})();
-
-const projectName = cwd.split('/').pop() || 'project';
-const date = new Date().toISOString().slice(0, 16).replace('T', ' ');
-
-const contextLines = [
-  `# Session Context`,
-  `Last saved: ${date}`,
-  ``,
-  `## What was in progress`,
-  lastSummary || '(no summary available)',
-  ``,
-];
-
-if (filesChanged.length) {
-  contextLines.push('## Files changed this session');
-  for (const f of filesChanged.slice(0, 20)) contextLines.push(`- ${f}`);
-  contextLines.push('');
-}
 
-if (decisions.length) {
-  contextLines.push('## Decisions captured');
-  for (const decision of decisions.slice(-10)) contextLines.push(`- ${decision}`);
-  contextLines.push('');
-}
+  if (decisions.length) {
+    contextLines.push('## Decisions captured');
+    for (const decision of decisions.slice(-10)) contextLines.push(`- ${decision}`);
+    contextLines.push('');
+  }
 
-if (pendingTodos.length) {
-  contextLines.push('## Pending TODOs');
-  for (const todo of pendingTodos) {
-    const status = todo.status === 'in_progress' ? '[~]' : '[ ]';
-    contextLines.push(`${status} ${todo.content || todo.title || todo.text || JSON.stringify(todo)}`);
+  if (pendingTodos.length) {
+    contextLines.push('## Pending TODOs');
+    for (const todo of pendingTodos) {
+      const status = todo.status === 'in_progress' ? '[~]' : '[ ]';
+      contextLines.push(`${status} ${todo.content || todo.title || todo.text || JSON.stringify(todo)}`);
+    }
+    contextLines.push('');
   }
-  contextLines.push('');
-}
 
-if (efficiencySummary) {
-  contextLines.push('## Session efficiency snapshot');
-  contextLines.push(efficiencySummary);
-  contextLines.push('');
-}
+  if (efficiencySummary) {
+    contextLines.push('## Session efficiency snapshot');
+    contextLines.push(efficiencySummary);
+    contextLines.push('');
+  }
 
-contextLines.push('## Open issues');
-contextLines.push(warnFlags || 'None');
-
-const content = contextLines.join('\n') + '\n';
-
-const projectCxDir = join(cwd, '.cx');
-try { mkdirSync(projectCxDir, { recursive: true }); } catch { /* exists */ }
-
-// Preserve manually-written sections from the existing context.md.
-const projectMdPath = contextMarkdownPath(cwd);
-const manualSections = extractManualSections(projectMdPath);
-const finalContent = content + (manualSections ? '\n' + manualSections : '');
-
-const contextJson = {
-  source: 'pre-compact',
-  projectName,
-  lastSummary,
-  filesChanged: filesChanged.slice(0, 20),
-  decisions: decisions.slice(-10),
-  pendingTodos: pendingTodos.slice(0, 20),
-  efficiencySummary,
-  warnFlags: warnFlags || 'None',
-};
-
-// Merge non-empty arrays from the existing JSON so manually recorded state
-// is not silently dropped when the transcript scan finds nothing new.
-const mergedJson = mergeExistingJson(contextJsonPath(cwd), contextJson);
-
-try { writeContextState(cwd, { ...mergedJson, contextSummary: lastSummary }, { markdown: finalContent }); } catch { /* best effort */ }
-if (decisions.length) {
-  const decisionsDir = join(projectCxDir, 'decisions');
-  const slug = `${date.replace(/[^0-9]/g, '')}-session-decisions`;
-  const decisionDoc = [
-    '# Session Decisions',
-    `Captured: ${date}`,
-    '',
-    '## Decisions',
-    ...decisions.slice(-10).map((decision) => `- ${decision}`),
-    '',
-    '## Files changed',
-    ...(filesChanged.length ? filesChanged.slice(0, 20).map((file) => `- ${file}`) : ['- None captured']),
-    '',
-  ].join('\n');
-  try { mkdirSync(decisionsDir, { recursive: true }); } catch { /* exists */ }
-  try { writeFileSync(join(decisionsDir, `${slug}.md`), decisionDoc); } catch { /* best effort */ }
-}
+  contextLines.push('## Open issues');
+  contextLines.push(warnFlags || 'None');
+
+  const content = contextLines.join('\n') + '\n';
+
+  const projectCxDir = join(cwd, '.cx');
+  try { mkdirSync(projectCxDir, { recursive: true }); } catch { /* exists */ }
+
+  // Preserve manually-written sections from the existing context.md.
+  const projectMdPath = contextMarkdownPath(cwd);
+  const manualSections = extractManualSections(projectMdPath);
+  const finalContent = content + (manualSections ? '\n' + manualSections : '');
+
+  const contextJson = {
+    source: 'pre-compact',
+    projectName,
+    lastSummary,
+    filesChanged: filesChanged.slice(0, 20),
+    decisions: decisions.slice(-10),
+    pendingTodos: pendingTodos.slice(0, 20),
+    efficiencySummary,
+    warnFlags: warnFlags || 'None',
+  };
+
+  // Merge non-empty arrays from the existing JSON so manually recorded state
+  // is not silently dropped when the transcript scan finds nothing new.
+  const mergedJson = mergeExistingJson(contextJsonPath(cwd), contextJson);
+
+  try { writeContextState(cwd, { ...mergedJson, contextSummary: lastSummary }, { markdown: finalContent }); } catch { /* best effort */ }
+  if (decisions.length) {
+    const decisionsDir = join(projectCxDir, 'decisions');
+    const slug = `${date.replace(/[^0-9]/g, '')}-session-decisions`;
+    const decisionDoc = [
+      '# Session Decisions',
+      `Captured: ${date}`,
+      '',
+      '## Decisions',
+      ...decisions.slice(-10).map((decision) => `- ${decision}`),
+      '',
+      '## Files changed',
+      ...(filesChanged.length ? filesChanged.slice(0, 20).map((file) => `- ${file}`) : ['- None captured']),
+      '',
+    ].join('\n');
+    try { mkdirSync(decisionsDir, { recursive: true }); } catch { /* exists */ }
+    try { writeFileSync(join(decisionsDir, `${slug}.md`), decisionDoc); } catch { /* best effort */ }
+  }
 
-const globalCxDir = join(doctorRoot(), '.cx');
-try { mkdirSync(globalCxDir, { recursive: true }); } catch { /* exists */ }
-const globalMdPath = contextMarkdownPath(doctorRoot());
-const globalManualSections = extractManualSections(globalMdPath);
-const globalFinalContent = content + (globalManualSections ? '\n' + globalManualSections : '');
-const globalMergedJson = mergeExistingJson(contextJsonPath(doctorRoot()), contextJson);
-try { writeContextState(doctorRoot(), { ...globalMergedJson, contextSummary: lastSummary }, { markdown: globalFinalContent }); } catch { /* best effort */ }
+  const globalCxDir = join(doctorRoot(), '.cx');
+  try { mkdirSync(globalCxDir, { recursive: true }); } catch { /* exists */ }
+  const globalMdPath = contextMarkdownPath(doctorRoot());
+  const globalManualSections = extractManualSections(globalMdPath);
+  const globalFinalContent = content + (globalManualSections ? '\n' + globalManualSections : '');
+  const globalMergedJson = mergeExistingJson(contextJsonPath(doctorRoot()), contextJson);
+  try { writeContextState(doctorRoot(), { ...globalMergedJson, contextSummary: lastSummary }, { markdown: globalFinalContent }); } catch { /* best effort */ }
 
-process.exit(0);
+  process.exit(0);
+}

package/lib/hooks/rule-verifier.mjs

@@ -29,6 +29,7 @@
 import { readFileSync, existsSync, appendFileSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { logHookFailure } from './_lib/log.mjs';
+import { isMainModule } from '../roots.mjs';
 
 const AUDIT_REL = '.cx/audit.jsonl';
 
@@ -202,7 +203,7 @@ function writeAudit(cwd, payload) {
   catch (err) { logHookFailure({ hook: 'rule-verifier', err, phase: 'append-audit' }); }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   let input = {};
   try { input = JSON.parse(readFileSync(0, 'utf8')); }
   catch (err) { logHookFailure({ hook: 'rule-verifier', err, phase: 'parse-stdin' }); process.exit(0); }

package/lib/hooks/session-reflect.mjs

@@ -21,12 +21,13 @@
  */
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
+import { resolveNonNegativeSetting } from '../env-config.mjs';
 
 // 500ms keeps the per-turn Stop-hook tax small (ADR-0029): reflection is
 // best-effort and a LanceDB write that overruns the budget is left to the
 // embed daemon's reconcile to backfill. CONSTRUCT_REFLECT_BUDGET_MS raises the
 // ceiling where the write must complete deterministically (slow disks, tests).
-const HARD_BUDGET_MS = Number(process.env.CONSTRUCT_REFLECT_BUDGET_MS) || 500;
+const HARD_BUDGET_MS = resolveNonNegativeSetting(process.env, 'CONSTRUCT_REFLECT_BUDGET_MS', 500);
 const startedAt = Date.now();
 
 // Opt-out before any heavy work — the env check is cheaper than parsing input.

package/lib/hooks/session-start.mjs

@@ -192,7 +192,7 @@ const header = `## Resuming — ${projectName} · ${date}
 const footer = [statusLine, recentLine].filter(Boolean).join(' · ');
 
 const body = context || (contextStale
-  ? '## Stale context — last context.md update >7 days old. Run `construct context refresh` or rely on `memory_recent`.\n'
+  ? '## Stale context — last context.md update >7 days old. Edit .cx/context.md directly (or use the remember:context skill) to update it — the session-tracking-refresh hook refreshes it automatically on edit.\n'
   : '## Fresh start — no prior context found.\n');
 // Tier 3 hint — efficiency snapshot fires only when status is 'degraded'
 // (repeated-read ratio or byte threshold exceeded). 'configured' (large reads
@@ -292,8 +292,8 @@ try {
   const embedStatus = resolveEmbedStatus(process.env);
   if (embedStatus.level !== 'none') {
     embedStatusNote = `\n## Embed daemon\n${embedStatus.label} · ${embedStatus.detail}\n`;
-    if (embedStatus.level === 'stopped' && process.env.CX_AUTO_EMBED === '1') {
-      const result = await autoStartEmbedIfNeeded(process.env);
+    if (embedStatus.level === 'stopped') {
+      const result = await autoStartEmbedIfNeeded(process.env, undefined, undefined, process.cwd());
       if (result.started) {
         embedStatusNote = `\n## Embed daemon\nembed: auto-started (pid ${result.pid}) · background polling active\n`;
       }

package/lib/host-capabilities.mjs

@@ -13,6 +13,7 @@ import fs from "node:fs";
 import net from "node:net";
 import os from "node:os";
 import path from "node:path";
+import { isMainModule } from './roots.mjs';
 
 const LOWEST_PORT = 0;
 const HIGHEST_PORT = 65535;
@@ -133,9 +134,13 @@ export function detectActiveSessions() {
     }
   } catch { /* not logged in or gh cli missing */ }
   
-  // Anthropic / Claude Code check
+  // Anthropic / Claude Code check. MCP server definitions live in
+  // ~/.claude.json's top-level `mcpServers`, not settings.json (construct-ranh);
+  // settings.json is still checked for `primaryModel` and any legacy `mcpServers`
+  // a user configured by hand before that was confirmed inert.
   const home = os.homedir();
   const claudeSettings = path.join(home, ".claude", "settings.json");
+  const claudeUserConfig = path.join(home, ".claude.json");
   try {
     if (fs.existsSync(claudeSettings)) {
       const settings = JSON.parse(fs.readFileSync(claudeSettings, "utf8"));
@@ -143,6 +148,12 @@ export function detectActiveSessions() {
         active.push("anthropic");
       }
     }
+    if (!active.includes("anthropic") && fs.existsSync(claudeUserConfig)) {
+      const userConfig = JSON.parse(fs.readFileSync(claudeUserConfig, "utf8"));
+      if (userConfig?.mcpServers) {
+        active.push("anthropic");
+      }
+    }
   } catch { /* invalid or missing config */ }
   
   return active;
@@ -278,7 +289,7 @@ export function printHostCapabilities(hosts = detectHostCapabilities()) {
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   const args = new Set(process.argv.slice(2));
   if (args.has('--json')) {
     process.stdout.write(formatHostCapabilitiesJson());

package/lib/host-disposition.mjs

@@ -1,20 +1,32 @@
 /**
  * lib/host-disposition.mjs — single source of truth for the disposition of
- * every artifact Construct creates in a host project (ADR-0027 §1).
+ * every artifact Construct creates in a host project (ADR-0027 §1, extended
+ * by ADR-0066 §"Decision" for the machine-scoped heavy-state split).
  *
  * Scope model (see docs/guides/concepts/project-scopes.md):
- *   templates/, docs/  — package/repo durable sources (committed)
- *   .construct/        — per-project launcher (ignored)
- *   .cx/               — per-project runtime: intake, oracle, observations, demos (ignored)
- *   ~/.construct/      — user credentials and doctor state
- *   ~/.cx/             — user-scope telemetry fallback
+ *   templates/, docs/            — package/repo durable sources (committed)
+ *   .construct/                  — per-project launcher (ignored)
+ *   .cx/                         — per-project config-layer + small runtime
+ *                                  markers: context.md/json, workflow.json,
+ *                                  intake, oracle, observations, knowledge,
+ *                                  graph, demos (ignored)
+ *   ~/.construct/projects/<key>/ — per-project machine-scoped heavy state:
+ *                                  traces, orchestration runs, worker logs,
+ *                                  the LanceDB vector index, docling/whisper
+ *                                  bootstrap venvs (ADR-0066)
+ *   ~/.construct/                — user credentials and doctor state
+ *   ~/.cx/                       — user-scope telemetry fallback
  *
  * `IGNORED_PATTERNS` enumerates machine-specific, sync-regenerated artifacts
  * that must never be committed; the init `.gitignore` writer and the
  * `gitignore-coverage` reconciliation both read from here, and uninstall /
  * adapter-prune consume `ADAPTER_DIRS`. Keep this 1:1 with the host-relevant
  * subset of Construct's own repo .gitignore so forward-fix and backward-repair
- * never diverge.
+ * never diverge. `.cx/` covers both the config-layer files and the small
+ * runtime markers that remain project-local post-ADR-0066 — the heavy
+ * categories that moved to `~/.construct/projects/<key>/` are resolved
+ * through `lib/state-root.mjs`, not listed here, since they were never
+ * project-relative paths to gitignore in the first place.
  */
 
 import fs from 'node:fs';

package/lib/identity.mjs

@@ -0,0 +1,92 @@
+/**
+ * lib/identity.mjs — actor and service identity for the control plane.
+ *
+ * Resolves human vs service identity from request headers (X-Construct-Actor-Id,
+ * -Tenant-Id, -Session-Id) or env fallback, and validates it per deployment mode
+ * (team/enterprise reject implicit-solo identity). Feeds policy, approval, and audit.
+ */
+
+import { getDeploymentMode } from './deployment-mode.mjs';
+import os from 'node:os';
+
+export class IdentityError extends Error {
+  constructor(message) { super(message); this.name = 'IdentityError'; }
+}
+
+export function serviceIdentity({ serviceId, deploymentMode, role, source } = {}) {
+  return {
+    type: 'service',
+    serviceId: serviceId || 'construct-mcp',
+    deploymentMode: deploymentMode || 'solo',
+    pid: process.pid,
+    role: role || null,
+    source: source || 'implicit-solo',
+  };
+}
+
+export function humanIdentity({ userId, tenantId, sessionId, role, source } = {}) {
+  return {
+    type: 'human',
+    userId: userId || null,
+    tenantId: tenantId || null,
+    sessionId: sessionId || null,
+    role: role || null,
+    source: source || 'headers',
+  };
+}
+
+export function resolveIdentity(params = {}, { env = process.env, cwd } = {}) {
+  const mode = getDeploymentMode(env, { cwd });
+  const meta = params?._meta || {};
+
+  const actorId = meta['X-Construct-Actor-Id'] || '';
+  const tenantId = meta['X-Construct-Tenant-Id'] || '';
+  const sessionId = meta['X-Construct-Session-Id'] || '';
+  const hasHeaders = Boolean(actorId);
+
+  if ((mode === 'team' || mode === 'enterprise') && !hasHeaders) {
+    const role = env.CONSTRUCT_ROLE;
+    if (role) {
+      return serviceIdentity({ serviceId: `role:${role}`, deploymentMode: mode, role, source: 'env-fallback' });
+    }
+    throw new IdentityError(`Missing actor identity in ${mode} mode. Set X-Construct-Actor-Id header or CONSTRUCT_ROLE env var.`);
+  }
+
+  if (hasHeaders) {
+    const isHuman = actorId.includes('@');
+    if (isHuman) {
+      return humanIdentity({ userId: actorId, tenantId: tenantId || null, sessionId: sessionId || null, role: env.CONSTRUCT_ROLE || null, source: 'headers' });
+    }
+    return serviceIdentity({ serviceId: actorId, deploymentMode: mode, role: env.CONSTRUCT_ROLE || null, source: 'headers' });
+  }
+
+  return serviceIdentity({ serviceId: `local-${os.hostname()}`, deploymentMode: mode, role: env.CONSTRUCT_ROLE || null, source: 'implicit-solo' });
+}
+
+export function identityRole(identity) {
+  return identity?.role || null;
+}
+
+export function validateIdentity(identity, mode) {
+  if (!identity) return 'Identity is required';
+  if (!identity.type) return 'Identity type is required';
+  if (identity.type === 'human' && !identity.userId) return 'Human identity requires userId';
+  if (identity.type === 'service' && !identity.serviceId) return 'Service identity requires serviceId';
+  if ((mode === 'team' || mode === 'enterprise') && identity.source === 'implicit-solo') {
+    return `Implicit identity not allowed in ${mode} mode`;
+  }
+  return null;
+}
+
+export function identityToRecord(identity) {
+  if (!identity) return {};
+  return {
+    type: identity.type,
+    userId: identity.userId || null,
+    serviceId: identity.serviceId || null,
+    tenantId: identity.tenantId || null,
+    sessionId: identity.sessionId || null,
+    role: identity.role || null,
+    deploymentMode: identity.deploymentMode || null,
+  };
+}