create-walle 0.9.21 → 0.9.23

package/template/claude-task-manager/lib/storage-migration.js

@@ -0,0 +1,235 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawn } = require('child_process');
+const { classifySqlitePathRisk } = require('../../shared/sqlite-storage-policy');
+
+const CONTROL_DIR = path.join(os.homedir(), '.walle', 'control');
+const LOCK_FILE = 'storage-migration.lock';
+const JOURNAL_PREFIX = 'storage-migration-';
+const ACTIVE_JOURNAL = 'storage-migration-current.json';
+const STALE_LOCK_MS = 15 * 60 * 1000;
+const HEARTBEAT_STALE_MS = 2 * 60 * 1000;
+
+function normalizeUserPath(value) {
+  const raw = String(value || '').trim().replace(/[\r\n\0]/g, '');
+  if (!raw) return '';
+  const expanded = raw === '~'
+    ? os.homedir()
+    : raw.replace(/^~(?=\/|$)/, os.homedir() || '~');
+  return path.resolve(expanded);
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  const stat = fs.statSync(dir);
+  if (!stat.isDirectory()) throw new Error(`Not a directory: ${dir}`);
+  return dir;
+}
+
+function safeReadJson(file, fallback = null) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return fallback; }
+}
+
+function atomicWriteJson(file, data) {
+  ensureDir(path.dirname(file));
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+function migrationPaths(env = process.env) {
+  const root = normalizeUserPath(env.CTM_STORAGE_CONTROL_DIR || CONTROL_DIR);
+  return {
+    controlDir: root,
+    lockPath: path.join(root, LOCK_FILE),
+    activeJournalPath: path.join(root, ACTIVE_JOURNAL),
+  };
+}
+
+function isProcessAlive(pid) {
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 0) return false;
+  try {
+    process.kill(n, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readActiveMigration(env = process.env, nowMs = Date.now()) {
+  const paths = migrationPaths(env);
+  const lock = safeReadJson(paths.lockPath, null);
+  const journal = safeReadJson(paths.activeJournalPath, null);
+  if (!lock && !journal) return { active: false, paths };
+  const state = String(lock?.state || journal?.state || '').toLowerCase();
+  const pid = Number(lock?.pid || journal?.supervisor_pid || 0);
+  const heartbeatAt = Date.parse(lock?.heartbeat_at || journal?.heartbeat_at || lock?.updated_at || journal?.updated_at || 0);
+  const startedAt = Date.parse(lock?.started_at || journal?.started_at || 0);
+  const pidAlive = isProcessAlive(pid);
+  const heartbeatFresh = Number.isFinite(heartbeatAt) && (nowMs - heartbeatAt) < HEARTBEAT_STALE_MS;
+  const recentlyStarted = Number.isFinite(startedAt) && (nowMs - startedAt) < STALE_LOCK_MS;
+  const terminal = ['completed', 'reverted', 'failed'].includes(state);
+  const allowStart = lock?.allow_start === true || journal?.allow_start === true;
+  const active = !terminal && !allowStart && pidAlive && (heartbeatFresh || recentlyStarted);
+  return { active, stale: !terminal && !allowStart && !active, terminal, lock, journal, paths, pidAlive, heartbeatFresh, state, allow_start: allowStart };
+}
+
+function startupGuard(label, env = process.env) {
+  const current = readActiveMigration(env);
+  if (!current.active) return { ok: true, active: false, stale: current.stale || false };
+  const err = new Error(`${label || 'process'} paused for active storage migration`);
+  err.code = 'CTM_STORAGE_MIGRATION_ACTIVE';
+  err.migration = current;
+  return { ok: false, active: true, error: err };
+}
+
+function serviceCurrentFromDb(dbModule) {
+  const dbPath = dbModule.getDbPath ? dbModule.getDbPath() : '';
+  const backupInfo = dbModule.getBackupDirInfo ? dbModule.getBackupDirInfo() : { backup_dir: dbModule.getBackupDir?.() || '' };
+  return {
+    data_dir: dbPath ? path.dirname(dbPath) : '',
+    db_path: dbPath || '',
+    db_file: 'task-manager.db',
+    backup_dir: backupInfo.backup_dir || '',
+    default_backup_dir: backupInfo.default_backup_dir || '',
+    configured_backup_dir: backupInfo.configured_backup_dir || '',
+    backup_dir_source: backupInfo.source || 'default',
+  };
+}
+
+function normalizeServiceInput(raw = {}, current = {}) {
+  const dataDir = normalizeUserPath(raw.data_dir || raw.dataDir || current.data_dir);
+  const backupDir = normalizeUserPath(raw.backup_dir || raw.backupDir || current.backup_dir);
+  return {
+    data_dir: dataDir,
+    backup_dir: backupDir,
+    move_backups: raw.move_backups !== false && raw.moveBackups !== false,
+  };
+}
+
+function _riskForDir(dir) {
+  try {
+    const risk = classifySqlitePathRisk(path.join(dir, 'probe.db'), process.env);
+    return risk && risk.risky ? { level: risk.level || 'warn', reason: risk.reason || risk.message || 'risky storage' } : null;
+  } catch {
+    return null;
+  }
+}
+
+function buildStorageMigrationPlan(input = {}, deps = {}) {
+  const env = deps.env || process.env;
+  const ctmCurrent = deps.ctmCurrent || serviceCurrentFromDb(deps.dbModule || {});
+  const walleCurrent = deps.walleCurrent || {};
+  const requested = input.services || {};
+  const services = {};
+  const warnings = [];
+  const now = new Date();
+  const id = `storage-${now.toISOString().replace(/[:.]/g, '-')}-${crypto.randomBytes(4).toString('hex')}`;
+
+  for (const [name, dbFile] of [['ctm', 'task-manager.db'], ['walle', 'wall-e-brain.db']]) {
+    const current = name === 'ctm' ? ctmCurrent : walleCurrent;
+    const next = normalizeServiceInput(requested[name] || {}, current);
+    const currentDataDir = normalizeUserPath(current.data_dir || (current.db_path ? path.dirname(current.db_path) : ''));
+    const currentBackupDir = normalizeUserPath(current.backup_dir || '');
+    const dataDirChanged = !!next.data_dir && !!currentDataDir && path.resolve(next.data_dir) !== path.resolve(currentDataDir);
+    const backupDirChanged = !!next.backup_dir && !!currentBackupDir && path.resolve(next.backup_dir) !== path.resolve(currentBackupDir);
+    const service = {
+      name,
+      label: name === 'ctm' ? 'CTM' : 'Wall-E',
+      db_file: dbFile,
+      current_data_dir: currentDataDir,
+      target_data_dir: next.data_dir || currentDataDir,
+      current_db_path: current.db_path || path.join(currentDataDir, dbFile),
+      target_db_path: path.join(next.data_dir || currentDataDir, dbFile),
+      current_backup_dir: currentBackupDir,
+      target_backup_dir: next.backup_dir || currentBackupDir,
+      data_dir_changed: dataDirChanged,
+      backup_dir_changed: backupDirChanged,
+      move_backups: !!next.move_backups,
+    };
+    const risk = service.target_data_dir ? _riskForDir(service.target_data_dir) : null;
+    if (risk) {
+      warnings.push({
+        service: name,
+        type: 'sqlite_storage',
+        message: `${service.label} live SQLite target may be unsafe: ${risk.reason}`,
+      });
+    }
+    services[name] = service;
+  }
+
+  const dataDirChanges = Object.values(services).filter(s => s.data_dir_changed);
+  const backupChanges = Object.values(services).filter(s => s.backup_dir_changed);
+  return {
+    id,
+    created_at: now.toISOString(),
+    state: 'planned',
+    control_dir: normalizeUserPath(env.CTM_STORAGE_CONTROL_DIR || CONTROL_DIR),
+    ctm_pid: Number(env.CTM_PID || process.pid),
+    services,
+    requires_restart: dataDirChanges.length > 0,
+    data_dir_change_count: dataDirChanges.length,
+    backup_dir_change_count: backupChanges.length,
+    warnings,
+    steps: [
+      ...(backupChanges.length && !dataDirChanges.length ? ['move_backup_snapshots'] : []),
+      ...(dataDirChanges.length ? [
+        'write_journal',
+        'stop_wall_e',
+        'stop_ctm',
+        'copy_live_data',
+        'verify_sqlite_images',
+        ...(backupChanges.length ? ['copy_backup_snapshots'] : []),
+        'update_env',
+        'restart_ctm',
+        'restart_wall_e',
+      ] : []),
+    ],
+  };
+}
+
+function writeMigrationPlan(plan, env = process.env) {
+  const paths = migrationPaths(env);
+  ensureDir(paths.controlDir);
+  const journalPath = path.join(paths.controlDir, `${JOURNAL_PREFIX}${plan.id}.json`);
+  const withPaths = { ...plan, journal_path: journalPath };
+  atomicWriteJson(journalPath, withPaths);
+  atomicWriteJson(paths.activeJournalPath, withPaths);
+  return { ...withPaths, journal_path: journalPath, active_journal_path: paths.activeJournalPath };
+}
+
+function spawnStorageMigrationSupervisor(plan, opts = {}) {
+  const written = writeMigrationPlan(plan, opts.env || process.env);
+  const script = path.resolve(__dirname, '..', 'bin', 'storage-migration-supervisor.js');
+  const args = ['--journal', written.journal_path];
+  if (opts.dryRun) args.push('--dry-run');
+  const child = spawn(process.execPath, [script, ...args], {
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env, ...(opts.env || {}) },
+  });
+  child.unref();
+  return { ok: true, id: written.id, pid: child.pid, journal_path: written.journal_path };
+}
+
+module.exports = {
+  CONTROL_DIR,
+  LOCK_FILE,
+  STALE_LOCK_MS,
+  HEARTBEAT_STALE_MS,
+  normalizeUserPath,
+  ensureDir,
+  migrationPaths,
+  readActiveMigration,
+  startupGuard,
+  buildStorageMigrationPlan,
+  writeMigrationPlan,
+  spawnStorageMigrationSupervisor,
+  atomicWriteJson,
+  safeReadJson,
+};

package/template/claude-task-manager/lib/structured-capture.js

@@ -0,0 +1,298 @@
+'use strict';
+
+// Structured capture: provider-neutral structured messages for coding-agent
+// transcripts (Claude Code JSONL, Codex rollouts). A structured message is a
+// normal {role, text, timestamp} message plus a `metadata` object describing
+// what the text represents (tool call, tool result, reasoning, patch, ...).
+//
+// Contract notes the parsers and renderer rely on:
+// - role is ALWAYS 'system' so every role-based heuristic (turn starts,
+//   exclusions, prompt index, title pickers) keeps working unchanged.
+// - `text` is a human-readable fallback: legacy clients and FTS index it, and
+//   the renderer uses it when it doesn't recognize `metadata.kind`.
+// - metadata NEVER carries parentUuid/uuid — conversation-tail-merge reads
+//   those as dedup identity keys and would collapse structured messages into
+//   their sibling assistant message.
+// - tool_call / tool_result are separate messages paired at RENDER time via
+//   metadata.callId; pairing at parse time would require mutating
+//   already-persisted rows, breaking the append-only row-store fast path.
+
+const STRUCTURED_META_VERSION = 1;
+
+const ARGS_PREVIEW_CAP = 2048;
+const TOOL_RESULT_TEXT_CAP = 4096;
+const REASONING_TEXT_CAP = 8192;
+const PATCH_TEXT_CAP = 16384;
+const COMPACT_SUMMARY_CAP = 8192;
+const STRUCTURED_PATCH_HUNK_LINE_CAP = 400;
+const RAW_JSON_CAP = 4096;
+const SHELL_COMMAND_CAP = 2048;
+
+function structuredCaptureEnabled() {
+  return process.env.CTM_STRUCTURED_CAPTURE !== '0';
+}
+
+function capText(value, cap) {
+  const text = String(value == null ? '' : value);
+  const limit = Number.isFinite(cap) && cap > 0 ? Math.floor(cap) : text.length;
+  if (text.length <= limit) {
+    return { text, truncated: false, originalBytes: Buffer.byteLength(text, 'utf8') };
+  }
+  return {
+    text: text.slice(0, limit),
+    truncated: true,
+    originalBytes: Buffer.byteLength(text, 'utf8'),
+  };
+}
+
+const PATCH_SENTINEL = '*** Begin Patch';
+const PATCH_FILE_RE = /^\*\*\* (?:Update|Add|Delete) File: (.+)$/gm;
+
+function patchFilesFromText(patchText) {
+  const files = [];
+  const seen = new Set();
+  let match;
+  PATCH_FILE_RE.lastIndex = 0;
+  while ((match = PATCH_FILE_RE.exec(patchText)) !== null) {
+    const file = match[1].trim();
+    if (file && !seen.has(file)) { seen.add(file); files.push(file); }
+  }
+  return files;
+}
+
+// Detect an apply_patch payload in any of the three forms Codex emits:
+// 1. function_call name="apply_patch" whose `arguments` is a JSON string
+//    (or pre-parsed object) shaped {"input": "*** Begin Patch..."}.
+// 2. custom_tool_call with the raw patch text as `input`.
+// 3. a shell call whose argv is ["apply_patch", "*** Begin Patch..."] or
+//    whose command string embeds the patch sentinel.
+function detectApplyPatch({ name, argumentsJson, input, command } = {}) {
+  const fromText = (text) => {
+    const patchText = String(text == null ? '' : text);
+    if (!patchText.includes(PATCH_SENTINEL)) return null;
+    const start = patchText.indexOf(PATCH_SENTINEL);
+    const trimmed = patchText.slice(start);
+    return { patchText: trimmed, files: patchFilesFromText(trimmed) };
+  };
+
+  if (String(name || '').trim() === 'apply_patch' && argumentsJson != null) {
+    let args = argumentsJson;
+    if (typeof args === 'string') {
+      try { args = JSON.parse(args); } catch { return fromText(args); }
+    }
+    if (args && typeof args === 'object') {
+      const found = fromText(args.input != null ? args.input : args.patch);
+      if (found) return found;
+    }
+  }
+
+  if (input != null) {
+    const found = fromText(input);
+    if (found) return found;
+  }
+
+  if (Array.isArray(command)) {
+    if (String(command[0] || '').trim().endsWith('apply_patch')) {
+      for (const part of command.slice(1)) {
+        const found = fromText(part);
+        if (found) return found;
+      }
+    }
+    const joined = command.join(' ');
+    if (joined.includes(PATCH_SENTINEL)) return fromText(joined);
+  } else if (typeof command === 'string' && command.includes(PATCH_SENTINEL)) {
+    return fromText(command);
+  }
+
+  return null;
+}
+
+// Bound a Claude `toolUseResult.structuredPatch` (array of jsdiff-style hunks
+// {oldStart, oldLines, newStart, newLines, lines}) to a total line budget so a
+// giant edit can't bloat a stored row.
+function summarizeStructuredPatch(structuredPatch) {
+  if (!Array.isArray(structuredPatch) || !structuredPatch.length) return null;
+  const out = [];
+  let budget = STRUCTURED_PATCH_HUNK_LINE_CAP;
+  let truncated = false;
+  for (const hunk of structuredPatch) {
+    if (!hunk || typeof hunk !== 'object') continue;
+    if (budget <= 0) { truncated = true; break; }
+    const lines = Array.isArray(hunk.lines) ? hunk.lines : [];
+    let kept = lines;
+    if (lines.length > budget) {
+      kept = lines.slice(0, budget);
+      truncated = true;
+    }
+    budget -= kept.length;
+    out.push({
+      oldStart: hunk.oldStart,
+      oldLines: hunk.oldLines,
+      newStart: hunk.newStart,
+      newLines: hunk.newLines,
+      lines: kept.map(l => String(l)),
+    });
+  }
+  if (!out.length) return null;
+  return { structuredPatch: out, truncated };
+}
+
+function buildMessage(kind, provider, text, timestamp, fields) {
+  const metadata = { v: STRUCTURED_META_VERSION, kind };
+  if (provider) metadata.provider = provider;
+  for (const [key, value] of Object.entries(fields || {})) {
+    if (value === undefined || value === null || value === '') continue;
+    metadata[key] = value;
+  }
+  const message = { role: 'system', text };
+  if (timestamp !== undefined && timestamp !== null && timestamp !== '') {
+    message.timestamp = timestamp;
+  }
+  message.metadata = metadata;
+  return message;
+}
+
+function toolCallMessage({ provider, tool, callId, args, timestamp } = {}) {
+  const toolName = String(tool || '').trim() || 'tool';
+  let argsText = '';
+  if (typeof args === 'string') argsText = args;
+  else if (args !== undefined && args !== null) {
+    try { argsText = JSON.stringify(args); } catch { argsText = String(args); }
+  }
+  const preview = capText(argsText, ARGS_PREVIEW_CAP);
+  return buildMessage('tool_call', provider, `[Tool: ${toolName}]`, timestamp, {
+    tool: toolName,
+    callId,
+    argsPreview: preview.text,
+    truncated: preview.truncated || undefined,
+    originalBytes: preview.truncated ? preview.originalBytes : undefined,
+  });
+}
+
+function toolResultMessage({
+  provider, tool, callId, output, exitCode, durationMs,
+  filePath, structuredPatch, isError, timestamp,
+} = {}) {
+  const capped = capText(output, TOOL_RESULT_TEXT_CAP);
+  const label = String(tool || '').trim();
+  const text = `[Tool result${label ? `: ${label}` : ''}]${capped.text ? `\n${capped.text}` : ''}`;
+  const patch = summarizeStructuredPatch(structuredPatch);
+  return buildMessage('tool_result', provider, text, timestamp, {
+    tool: label || undefined,
+    callId,
+    exitCode: Number.isFinite(exitCode) ? exitCode : undefined,
+    durationMs: Number.isFinite(durationMs) ? durationMs : undefined,
+    filePath,
+    structuredPatch: patch ? patch.structuredPatch : undefined,
+    isError: isError === true || undefined,
+    truncated: (capped.truncated || (patch && patch.truncated)) || undefined,
+    originalBytes: capped.truncated ? capped.originalBytes : undefined,
+  });
+}
+
+function shellMessage({ provider, command, callId, timestamp } = {}) {
+  const commandText = Array.isArray(command) ? command.join(' ') : String(command == null ? '' : command);
+  const capped = capText(commandText, SHELL_COMMAND_CAP);
+  return buildMessage('shell', provider, `[Shell] ${capped.text}`, timestamp, {
+    command: capped.text,
+    callId,
+    truncated: capped.truncated || undefined,
+    originalBytes: capped.truncated ? capped.originalBytes : undefined,
+  });
+}
+
+function patchMessage({ provider, patchText, files, structuredPatch, filePath, callId, timestamp } = {}) {
+  const capped = capText(patchText, PATCH_TEXT_CAP);
+  const fileList = Array.isArray(files) && files.length
+    ? files
+    : (capped.text ? patchFilesFromText(capped.text) : []);
+  const header = fileList.length ? `[Patch] ${fileList.join(', ')}` : '[Patch]';
+  const patch = summarizeStructuredPatch(structuredPatch);
+  return buildMessage('patch', provider, `${header}${capped.text ? `\n${capped.text}` : ''}`, timestamp, {
+    files: fileList.length ? fileList : undefined,
+    filePath,
+    callId,
+    structuredPatch: patch ? patch.structuredPatch : undefined,
+    truncated: (capped.truncated || (patch && patch.truncated)) || undefined,
+    originalBytes: capped.truncated ? capped.originalBytes : undefined,
+  });
+}
+
+function reasoningMessage({ provider, text, encrypted, timestamp } = {}) {
+  if (encrypted && !String(text || '').trim()) {
+    return buildMessage('reasoning', provider, '[Reasoning (encrypted)]', timestamp, {
+      encrypted: true,
+    });
+  }
+  const capped = capText(text, REASONING_TEXT_CAP);
+  return buildMessage('reasoning', provider, `[Reasoning]${capped.text ? `\n${capped.text}` : ''}`, timestamp, {
+    truncated: capped.truncated || undefined,
+    originalBytes: capped.truncated ? capped.originalBytes : undefined,
+  });
+}
+
+function webSearchMessage({ provider, query, timestamp } = {}) {
+  const queryText = capText(query, ARGS_PREVIEW_CAP);
+  return buildMessage('web_search', provider, `[Web search] ${queryText.text}`.trim(), timestamp, {
+    query: queryText.text || undefined,
+  });
+}
+
+function compactBoundaryMessage({ provider, trigger, preTokens, logicalParentUuid, timestamp } = {}) {
+  return buildMessage('compact_boundary', provider, '[Conversation compacted]', timestamp, {
+    trigger: String(trigger || '').trim() || undefined,
+    preTokens: Number.isFinite(preTokens) ? preTokens : undefined,
+    logicalParentUuid: String(logicalParentUuid || '').trim() || undefined,
+  });
+}
+
+function compactSummaryMessage({ provider, text, timestamp } = {}) {
+  const capped = capText(text, COMPACT_SUMMARY_CAP);
+  return buildMessage('compact_summary', provider, capped.text, timestamp, {
+    truncated: capped.truncated || undefined,
+    originalBytes: capped.truncated ? capped.originalBytes : undefined,
+  });
+}
+
+// Forward-compat: an entry type the parser does not recognize. The capped raw
+// JSON keeps it inspectable in the UI instead of silently dropped.
+function unknownMessage({ provider, kindHint, raw, timestamp } = {}) {
+  let rawText = '';
+  if (typeof raw === 'string') rawText = raw;
+  else if (raw !== undefined && raw !== null) {
+    try { rawText = JSON.stringify(raw); } catch { rawText = String(raw); }
+  }
+  const capped = capText(rawText, RAW_JSON_CAP);
+  const hint = String(kindHint || '').trim();
+  return buildMessage('unknown', provider, `[Unrecorded event${hint ? `: ${hint}` : ''}]`, timestamp, {
+    kindHint: hint || undefined,
+    raw: capped.text || undefined,
+    truncated: capped.truncated || undefined,
+    originalBytes: capped.truncated ? capped.originalBytes : undefined,
+  });
+}
+
+module.exports = {
+  STRUCTURED_META_VERSION,
+  ARGS_PREVIEW_CAP,
+  TOOL_RESULT_TEXT_CAP,
+  REASONING_TEXT_CAP,
+  PATCH_TEXT_CAP,
+  COMPACT_SUMMARY_CAP,
+  STRUCTURED_PATCH_HUNK_LINE_CAP,
+  RAW_JSON_CAP,
+  SHELL_COMMAND_CAP,
+  structuredCaptureEnabled,
+  capText,
+  detectApplyPatch,
+  summarizeStructuredPatch,
+  toolCallMessage,
+  toolResultMessage,
+  shellMessage,
+  patchMessage,
+  reasoningMessage,
+  webSearchMessage,
+  compactBoundaryMessage,
+  compactSummaryMessage,
+  unknownMessage,
+};

package/template/claude-task-manager/lib/sync-io-census.js

@@ -0,0 +1,163 @@
+'use strict';
+
+// Synchronous-I/O census — the companion to lib/main-db-census.js for the OTHER half of the
+// boot freeze.
+//
+// THE PROBLEM IT SOLVES: after the DB title hog (rowForCtmId) was fixed, the boot CPU profile
+// went 87% IDLE during the freeze. "Idle" in a CPU profile means the main thread is blocked
+// in a synchronous I/O SYSCALL — off-CPU, so a CPU sampler structurally CANNOT name it. The
+// remaining 20s+ event-loop blocks are synchronous fs/child_process calls in the restore path
+// (readFileSync of cold JSONL, readdirSync/realpathSync tree walks, spawnSync git) that no
+// CPU profile will ever attribute. This census monkey-patches those sync syscalls (when armed)
+// to time them and name the CALL SITE of every slow one — turning "idle" into a ranked list.
+//
+// SAFETY: OFF by default. HARD RULE: this monkey-patches global fs, so it must NEVER run on
+// the primary — it only arms on a dev/staging instance (which sets DEV_CTM_PORT) with
+// CTM_FS_CENSUS=1. There is no primary-arming path. When disabled, nothing is patched — zero
+// overhead, zero behavior change. Uses performance.now() (no BigInt allocation) and only
+// captures a stack for ops slower than STACK_MS, so even when armed the per-call cost is tiny.
+
+const fs = require('fs');
+const child_process = require('child_process');
+const { performance } = require('perf_hooks');
+
+const STACK_MS = clampNum(process.env.CTM_FS_CENSUS_STACK_MS, 3, 0.1, 60000);
+const BUDGET_MS = clampNum(process.env.CTM_FS_CENSUS_BUDGET_MS, 100, 1, 600000);
+const MAX_KEYS = clampNum(process.env.CTM_FS_CENSUS_MAX_KEYS, 4000, 16, 100000);
+
+function clampNum(raw, dflt, lo, hi) {
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return dflt;
+  return Math.max(lo, Math.min(hi, n));
+}
+
+let _enabled = false;
+let _armedReason = '';
+let _patched = false;
+let _startedAt = 0;
+let _budgetWarnings = 0;
+const _byFn = new Map();    // fn → { count, sumMs, maxMs }   (every call, cheap)
+const _bySite = new Map();  // `fn @ callsite` → { fn, count, sumMs, maxMs, sampleArg, stack } (slow only)
+
+// HARD RULE: this census MONKEY-PATCHES the global fs/child_process sync methods — even more
+// invasive than the DB census. It must NEVER run on the primary. It only arms on a dev/staging
+// instance (which sets DEV_CTM_PORT). No primary-arming path (no sentinel) — staging only.
+function _shouldArm() {
+  if (!process.env.DEV_CTM_PORT) return ''; // primary: never arm, full stop
+  if (process.env.CTM_FS_CENSUS === '1') return 'env';
+  return '';
+}
+
+function _captureStack() {
+  const raw = new Error().stack || '';
+  return raw
+    .split('\n')
+    .slice(1)
+    .filter((l) => !l.includes('sync-io-census.js') && !l.includes('node:internal'))
+    .slice(0, 6)
+    .map((l) => l.trim())
+    .join(' <- ');
+}
+
+// Nearest CTM frame in the stack — the line of our code that issued the syscall.
+function _ctmCallSite() {
+  const raw = new Error().stack || '';
+  for (const line of raw.split('\n').slice(1)) {
+    if (line.includes('/claude-task-manager/') && !line.includes('/node_modules/') && !line.includes('sync-io-census.js')) {
+      return line.trim().replace(/^at\s+/, '').replace(/.*\/claude-task-manager\//, '');
+    }
+  }
+  return '(non-ctm)';
+}
+
+function _argHint(arg) {
+  if (typeof arg !== 'string') return '';
+  // Keep the tail of the path (most informative) without leaking the full home prefix.
+  return arg.length > 80 ? '…' + arg.slice(-80) : arg;
+}
+
+function _record(fn, ms, firstArg) {
+  let fnSt = _byFn.get(fn);
+  if (!fnSt) { fnSt = { count: 0, sumMs: 0, maxMs: 0 }; _byFn.set(fn, fnSt); }
+  fnSt.count += 1; fnSt.sumMs += ms; if (ms > fnSt.maxMs) fnSt.maxMs = ms;
+
+  if (ms >= STACK_MS) {
+    const site = _ctmCallSite();
+    const key = `${fn} @ ${site}`;
+    let st = _bySite.get(key);
+    if (!st) {
+      if (_bySite.size >= MAX_KEYS) return;
+      st = { fn, site, count: 0, sumMs: 0, maxMs: 0, sampleArg: _argHint(firstArg), stack: '' };
+      _bySite.set(key, st);
+    }
+    st.count += 1; st.sumMs += ms; if (ms > st.maxMs) { st.maxMs = ms; st.stack = _captureStack(); st.sampleArg = _argHint(firstArg); }
+    if (ms >= BUDGET_MS) {
+      _budgetWarnings += 1;
+      console.warn(`[fsio-budget] main-thread ${fn}(${st.sampleArg}) blocked ${Math.round(ms)}ms\n           ${st.stack}`);
+    }
+  }
+}
+
+// Wrap one sync function on a host object, timing every call. Transparent: same args, same
+// return, same throw behavior — only a timing side effect.
+function _wrap(host, name, label) {
+  const orig = host[name];
+  if (typeof orig !== 'function') return;
+  const wrapped = function (...args) {
+    const t0 = performance.now();
+    try {
+      return orig.apply(this, args);
+    } finally {
+      _record(label || name, performance.now() - t0, args[0]);
+    }
+  };
+  // Preserve sub-properties (e.g. fs.realpathSync.native).
+  for (const k of Object.keys(orig)) { try { wrapped[k] = orig[k]; } catch {} }
+  host[name] = wrapped;
+  return orig;
+}
+
+function arm() {
+  if (_enabled) return true;
+  const reason = _shouldArm();
+  if (!reason) return false;
+  _enabled = true;
+  _armedReason = reason;
+  _startedAt = Date.now();
+  if (!_patched) {
+    _patched = true;
+    for (const n of ['readFileSync', 'readdirSync', 'statSync', 'lstatSync', 'existsSync', 'realpathSync', 'writeFileSync', 'readlinkSync', 'openSync']) {
+      _wrap(fs, n);
+    }
+    // realpathSync.native is a hot path (it's its own function on the wrapper now).
+    try { if (fs.realpathSync && typeof fs.realpathSync.native === 'function') _wrap(fs.realpathSync, 'native', 'realpathSync.native'); } catch {}
+    for (const n of ['spawnSync', 'execSync', 'execFileSync']) { _wrap(child_process, n); }
+  }
+  console.warn(`[fsio-census] ARMED (${reason}) — timing synchronous fs/child_process syscalls; `
+    + `budget=${BUDGET_MS}ms stackThreshold=${STACK_MS}ms. GET /api/diagnostics/fs-census to read.`);
+  return true;
+}
+
+function getCensus({ limit = 60 } = {}) {
+  const sites = [..._bySite.values()]
+    .map((s) => ({ ...s, sumMs: +s.sumMs.toFixed(1), maxMs: +s.maxMs.toFixed(1) }))
+    .sort((a, b) => b.sumMs - a.sumMs)
+    .slice(0, Math.max(1, limit));
+  const byFn = [..._byFn.entries()]
+    .map(([fn, s]) => ({ fn, count: s.count, sumMs: +s.sumMs.toFixed(1), maxMs: +s.maxMs.toFixed(1) }))
+    .sort((a, b) => b.sumMs - a.sumMs);
+  return {
+    enabled: _enabled,
+    armedReason: _armedReason,
+    sinceMs: _startedAt ? Date.now() - _startedAt : 0,
+    budgetMs: BUDGET_MS,
+    stackThresholdMs: STACK_MS,
+    budgetWarnings: _budgetWarnings,
+    byFn,
+    topSites: sites,
+  };
+}
+
+function isEnabled() { return _enabled; }
+
+module.exports = { arm, getCensus, isEnabled };