impulso 0.21.1 → 0.23.0

package/README.md

@@ -206,7 +206,7 @@ tokensave init        # build the tokensave index (once per repo)
 ### Maintenance
 
 ```bash
-./doctor.sh                          # health check: binaries, symlinks, configs, MCP
+impulso-hub doctor                   # health check: binaries, symlinks, configs, MCP
 ./harnesses/claude/uninstall.sh      # reverse the claude install (targeted, safe)
 ./harnesses/opencode/uninstall.sh    # remove the opencode profile
 ```
@@ -300,7 +300,7 @@ in the `opencode` block only.
 opencode ships logical aliases, not concrete model IDs. Every agent in the
 `opencode` block resolves through an `llm/<key>` alias that must be mapped in
 your opencode provider config — Impulso provides no fallback. An undefined alias
-fails at dispatch. `doctor.sh` warns when aliases are active (spec §7).
+fails at dispatch. `impulso-hub doctor` warns when aliases are active (spec §7).
 
 | Agent                | Shipped alias              |
 | -------------------- | -------------------------- |
@@ -390,7 +390,6 @@ impulso/
 ├── .mcp.json              # tokensave MCP (plugin route + project-local)
 ├── run_here.sh            # boots opencode against this repo
 ├── run_here_claude.sh     # boots Claude Code against this repo
-├── doctor.sh              # health checks: binaries, symlinks, configs, MCP
 ├── opencode/              # self-boot config: opencode.jsonc + AGENTS.md -> shared/ + symlinks
 ├── claude/                # self-boot config: settings.json + CLAUDE.md + AGENTS.md -> shared/ + symlinks
 ├── skills/                # harness-agnostic skill files (SKILL.md per dir)

package/harnesses/claude/README.md

@@ -33,7 +33,7 @@ content, never `rm -rf`'s `~/.claude`:
 Health check for the whole harness (binaries, symlinks, configs, MCP):
 
 ```bash
-./doctor.sh
+impulso-hub doctor
 ```
 
 Launch with the isolated profile:

package/harnesses/claude/hooks/telematics.cjs

@@ -0,0 +1,216 @@
+// impulso passive telematics adapter — Claude Code
+//
+// Reads Claude hook JSON from stdin, maps it to telematics events, and emits
+// to the local NDJSON log. Never writes stdout, never blocks, never throws.
+// Telemetry is disabled by default — requires { telematics: { enabled: true } }
+// in <IMPULSO_HOME>/config.json (IMPULSO_HOME or ~/.impulso).
+// See shared/telematics.cjs for config format.
+//
+// Hook event type passed via IMPULSO_HOOK_EVENT env var. See
+// claude/settings.json and hooks/hooks.json for dual-registration entries.
+
+'use strict';
+
+const os = require('node:os');
+const path = require('node:path');
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+const { createTelematics } = require(path.join(__dirname, '../../../shared/telematics.cjs'));
+
+const hookEvent = process.env.IMPULSO_HOOK_EVENT || 'unknown';
+
+const chunks = [];
+let done = false;
+process.stdin.setEncoding('utf8');
+process.stdin.on('readable', function () {
+  let c;
+  while ((c = process.stdin.read()) !== null) chunks.push(c);
+});
+
+function finish(raw) {
+  if (done) return;
+  done = true;
+  clearTimeout(timer);
+
+  let input;
+  try {
+    input = JSON.parse(raw || '{}');
+  } catch (_) {
+    process.exit(0);
+    return;
+  }
+
+  // Resolve impulso home: IMPULSO_HOME env, else ~/.impulso
+  let impulsoHome = process.env.IMPULSO_HOME;
+  if (!impulsoHome || impulsoHome.length === 0) {
+    impulsoHome = path.join(os.homedir(), '.impulso');
+  }
+
+  let t;
+  try {
+    t = createTelematics({
+      harness: 'claude',
+      sessionId: input.session_id || null,
+      processId: process.pid,
+      cwd: input.cwd || process.cwd(),
+      home: impulsoHome,
+      now: function () {
+        return new Date().toISOString();
+      },
+      uuid: function () {
+        return crypto.randomUUID();
+      },
+      fs: fs,
+    });
+  } catch (_) {
+    process.exit(0);
+    return;
+  }
+
+  if (!t.enabled) {
+    process.exit(0);
+    return;
+  }
+
+  // Emit session.started once per native session across separate hook
+  // processes. Uses a lock file (<IMPULSO_HOME>/telematics-locks/<sid>.started)
+  // with atomic O_CREAT|O_EXCL to coordinate. If another process already
+  // locked this session, skip. If lock creation fails for any reason, skip
+  // (best-effort, passive — session.started is supplementary telemetry).
+  let lockFd = null;
+  try {
+    const locksDir = path.join(impulsoHome, 'telematics-locks');
+    const lockFile = path.join(locksDir, t.sessionId + '.started');
+    fs.mkdirSync(locksDir, { recursive: true, mode: 0o700 });
+    try {
+      fs.chmodSync(locksDir, 0o700);
+    } catch (_) {
+      /* best effort */
+    }
+    // wx = write + exclusive — fails with EEXIST if lock already held
+    lockFd = fs.openSync(lockFile, 'wx', 0o600);
+    fs.writeSync(lockFd, String(process.pid));
+    // Lock acquired — emit session.started
+    try {
+      t.emit('session.started', {
+        nativeSessionId: input.session_id || null,
+        sessionIdSource: input.session_id ? 'native' : 'generated',
+      });
+    } catch (_) {
+      /* silent */
+    }
+  } catch (_) {
+    // EEXIST or any fs failure → lock not acquired, skip session.started
+  } finally {
+    if (lockFd !== null) {
+      try {
+        fs.closeSync(lockFd);
+      } catch (_) {
+        /* silent */
+      }
+    }
+  }
+
+  try {
+    const event = mapEvent(hookEvent, input, t);
+    if (event) {
+      t.emit(event.eventType, event.data);
+    }
+  } catch (_) {
+    /* silent */
+  }
+
+  try {
+    t.close();
+  } catch (_) {
+    /* silent */
+  }
+
+  process.exit(0);
+}
+
+process.stdin.on('end', function () {
+  finish(chunks.join(''));
+});
+const timer = setTimeout(function () {
+  finish(chunks.join(''));
+}, 1000);
+
+// ----------------------------------------------------------------
+// event mapping — direct host-payload translation per spec
+// ----------------------------------------------------------------
+function mapEvent(hook, input) {
+  switch (hook) {
+    case 'UserPromptSubmit':
+      return {
+        eventType: 'message.submitted',
+        data: {
+          message: typeof input.prompt === 'string' ? input.prompt : '',
+          messageId: input.session_id || undefined,
+        },
+      };
+    case 'PreToolUse':
+      return {
+        eventType: 'tool.requested',
+        data: {
+          toolName: input.tool_name || '',
+          toolUseId: input.tool_use_id || undefined,
+          input: input.tool_input || {},
+        },
+      };
+    case 'PostToolUse':
+      return {
+        eventType: 'tool.completed',
+        data: {
+          toolName: input.tool_name || '',
+          toolUseId: input.tool_use_id || undefined,
+          output: input.tool_response || {},
+          status: getToolStatus(input.tool_response),
+        },
+      };
+    case 'SubagentStart':
+      return {
+        eventType: 'lifecycle',
+        data: {
+          name: 'subagent',
+          phase: 'started',
+          details: { agent_type: input.agent_type || null },
+        },
+      };
+    case 'SubagentStop':
+      // Best-effort session.ended from SubagentStop
+      return {
+        eventType: 'session.ended',
+        data: {
+          reason: 'subagent_stopped',
+        },
+      };
+    case 'Notification':
+      // Error/notification events from host
+      return {
+        eventType: 'error',
+        data: {
+          operation: input.operation || undefined,
+          name: input.name || undefined,
+          message: input.message || undefined,
+          stack: input.stack || undefined,
+        },
+      };
+    default:
+      return null;
+  }
+}
+
+function getToolStatus(response) {
+  if (!response) return 'unknown';
+  if (typeof response.exitCode === 'number') {
+    return response.exitCode === 0 ? 'success' : 'error';
+  }
+  if (typeof response.exit_code === 'number') {
+    return response.exit_code === 0 ? 'success' : 'error';
+  }
+  return 'completed';
+}
+
+// export for testing
+module.exports = { mapEvent, getToolStatus };

package/harnesses/opencode/plugin.js

@@ -17,6 +17,7 @@ import { registerCommands } from './commands-loader.js';
 import { ImpulsoDirectSpeechPlugin } from './directspeech/plugin.js';
 import { ImpulsoOrchestrationPlugin } from './orchestration/index.js';
 import { ImpulsoSessionNamePlugin } from './session-name/plugin.js';
+import { ImpulsoTelematicsPlugin } from './telematics/plugin.js';
 import { installHub } from '../../scripts/install-hub.js';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
@@ -56,6 +57,9 @@ export const ImpulsoPlugin = async (ctx) => {
   // Session-name plugin (X-Session-Name header for proxy cache locality)
   sub.push(await ImpulsoSessionNamePlugin(ctx));
 
+  // Telematics plugin — passive observer, must be last to observe final permission state
+  sub.push(await ImpulsoTelematicsPlugin(ctx));
+
   const hooks = composeHooks(sub);
 
   // Wrap the composed config hook with our own skills/commands registration.

package/harnesses/opencode/telematics/plugin.js

@@ -0,0 +1,175 @@
+// impulso — opencode passive telematics observer plugin
+//
+// Observes runtime hooks and emits NDJSON telemetry events via the shared
+// writer. Passive only: never calls a model, never injects chat/system content,
+// never modifies request/response or hook output, never invokes impulso-hub,
+// never spawns tools. Zero model-token impact.
+//
+// Hooks:
+//   chat.message        → message.submitted / message.received (by role)
+//   tool.execute.before → tool.requested
+//   tool.execute.after  → tool.completed (with paired durationMs)
+//   permission.ask      → permission.requested + permission.resolved
+//   event               → lifecycle
+//
+// Initialize once for plugin lifetime; config read exactly once.
+
+import os from 'node:os';
+import { createRequire } from 'node:module';
+
+const require_ = createRequire(import.meta.url);
+
+function defaultCreateTelematics(ctx) {
+  const { createTelematics } = require_('../../../shared/telematics.cjs');
+  const fs = require_('node:fs');
+  const crypto = require_('node:crypto');
+
+  const home = process.env.IMPULSO_HOME || require_('node:path').join(os.homedir(), '.impulso');
+
+  // Record the raw sessionId before sanitization for sessionIdSource
+  const rawSessionId = ctx.sessionID || null;
+
+  return {
+    telematics: createTelematics({
+      harness: 'opencode',
+      sessionId: ctx.sessionID || null,
+      processId: process.pid,
+      cwd: ctx.directory || process.cwd(),
+      home,
+      now: () => new Date().toISOString(),
+      uuid: () => crypto.randomUUID(),
+      fs,
+    }),
+    rawSessionId,
+  };
+}
+
+export async function ImpulsoTelematicsPlugin(ctx, _createTelematics) {
+  const createTel = _createTelematics || defaultCreateTelematics;
+
+  // One-time construct: create the telematics instance
+  const { telematics: t, rawSessionId } = createTel(ctx);
+
+  // Duration trackers — keyed by callID for tools, session-permission pair for perms
+  const toolStarts = new Map(); // callID → timestamp ms
+  const permStarts = new Map(); // `${sessionID}::${permission}` → timestamp ms
+
+  // Emit session.started on init
+  if (t.enabled) {
+    t.emit('session.started', {
+      nativeSessionId: rawSessionId || null,
+      sessionIdSource: rawSessionId ? 'native' : 'generated',
+    });
+  }
+
+  const hooks = {};
+
+  // ---- event ---------------------------------------------------
+  hooks.event = async (input) => {
+    if (!t.enabled) return;
+    t.emit('lifecycle', {
+      name: (input && input.type) || 'unknown',
+      phase: input && input.phase,
+      details: input,
+    });
+  };
+
+  // ---- chat.message --------------------------------------------
+  hooks['chat.message'] = async (input, _output) => {
+    if (!t.enabled) return;
+    if (!input) return;
+
+    // Determine direction from input.role
+    // user → submitted, assistant/system → received
+    const role = input.role || 'unknown';
+    if (role === 'user') {
+      t.emit('message.submitted', {
+        message: input,
+        messageId: input.id,
+      });
+    } else {
+      t.emit('message.received', {
+        message: input,
+        messageId: input.id,
+        role: input.role,
+      });
+    }
+  };
+
+  // ---- tool.execute.before -------------------------------------
+  hooks['tool.execute.before'] = async (input, _output) => {
+    if (!t.enabled) return;
+    if (!input) return;
+
+    // Record start time for duration pairing
+    if (input.callID) {
+      toolStarts.set(input.callID, Date.now());
+    }
+
+    t.emit('tool.requested', {
+      toolName: input.tool,
+      toolUseId: input.callID,
+      input: input.args,
+    });
+  };
+
+  // ---- tool.execute.after --------------------------------------
+  hooks['tool.execute.after'] = async (input, output) => {
+    if (!t.enabled) return;
+    if (!input) return;
+
+    const start = input.callID ? toolStarts.get(input.callID) : undefined;
+    if (input.callID) {
+      toolStarts.delete(input.callID);
+    }
+
+    const durationMs = start != null ? Date.now() - start : undefined;
+
+    let status;
+    if (output && output.metadata && output.metadata.exitCode !== undefined) {
+      status = output.metadata.exitCode === 0 ? 'success' : 'error';
+    }
+
+    t.emit('tool.completed', {
+      toolName: input.tool,
+      toolUseId: input.callID,
+      output,
+      durationMs,
+      status,
+    });
+  };
+
+  // ---- permission.ask ------------------------------------------
+  hooks['permission.ask'] = async (input, output) => {
+    if (!t.enabled) return;
+    if (!input) return;
+
+    const start = Date.now();
+
+    // Record start so we can compute duration
+    const permKey = `${input.sessionID || ''}::${input.permission || ''}`;
+    permStarts.set(permKey, start);
+
+    t.emit('permission.requested', {
+      permission: input.permission,
+      request: input,
+    });
+
+    // Observe output.decision synchronously after our handler runs
+    // (telematics plugin is composed last, so output is in final state)
+    const decision = output && output.decision;
+
+    const durationMs = Date.now() - start;
+    permStarts.delete(permKey);
+
+    t.emit('permission.resolved', {
+      permission: input.permission,
+      decision,
+      durationMs,
+    });
+  };
+
+  return hooks;
+}
+
+export default ImpulsoTelematicsPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impulso",
-  "version": "0.21.1",
+  "version": "0.23.0",
   "description": "Impulso — plugin bundle for opencode and Claude Code: Plannotator skills + Impulso-DirectSpeech (rethemed ex-Caveman). Harness-neutral repo; per-harness glue under harnesses/.",
   "type": "module",
   "main": "harnesses/opencode/plugin.js",
@@ -19,7 +19,6 @@
     "install:claude": "harnesses/claude/install.sh",
     "uninstall:opencode": "harnesses/opencode/uninstall.sh",
     "uninstall:claude": "harnesses/claude/uninstall.sh",
-    "doctor": "./doctor.sh",
     "sync:commands": "node harnesses/opencode/sync-commands.js && prettier --write commands/",
     "sync:agents": "node scripts/sync-agents.cjs",
     "check:canaries": "node scripts/check-canaries.cjs",
@@ -64,7 +63,9 @@
     "shared/tokensave-freshness.cjs",
     "skills",
     "package.json",
-    "README.md"
+    "README.md",
+    "harnesses/opencode/telematics/",
+    "shared/telematics.cjs"
   ],
   "dependencies": {
     "@opencode-ai/plugin": "^1.17.14"

package/shared/telematics.cjs

@@ -0,0 +1,444 @@
+'use strict';
+// impulso — shared secure telematics writer
+//
+// NDJSON append-only event log. Config is loaded once from
+// <home>/config.json. All emit failures are silent —
+// telematics must never throw or disrupt the harness.
+//
+// Interfaces:
+//   loadTelematicsConfig(home, _fs?) -> { enabled, sensitiveKeys }
+//   redact(value, sensitiveKeys) -> redacted copy
+//   sanitizeId(raw) -> string
+//   createTelematics({ harness, sessionId, processId, cwd, home,
+//                      now, uuid, fs })
+//     -> { enabled, sessionId, emit(eventType, payload), close() }
+
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+// ----------------------------------------------------------------
+// BUILTIN_SENSITIVE_KEYS — always active, case-insensitive.
+// Matches common credential / token / secret key names across
+// providers. Supplemented by config telematics.sensitiveKeys.
+// ----------------------------------------------------------------
+const BUILTIN_SENSITIVE_KEYS = [
+  'apiKey',
+  'api_key',
+  'authorization',
+  'token',
+  'accessToken',
+  'refreshToken',
+  'secret',
+  'password',
+  'passwd',
+  'credential',
+  'cookie',
+  'set-cookie',
+  'privateKey',
+  'clientSecret',
+];
+
+// ----------------------------------------------------------------
+// Pattern-based redaction. Applied to string values during walk.
+// ----------------------------------------------------------------
+const PATTERN_REDACTIONS = [
+  // Bearer tokens: "Bearer eyJ..." -> "Bearer [REDACTED]"
+  { pattern: /\bBearer\s+([^\s"',;)}\]]+)/gi, replace: 'Bearer [REDACTED]' },
+  // OpenAI / similar sk- keys: sk-<40+ chars>
+  { pattern: /\bsk-[a-zA-Z0-9_-]{20,}\b/g, replace: '[REDACTED_SK_KEY]' },
+  // GitHub classic tokens: ghp_xxx, gho_xxx, ghu_xxx, ghs_xxx, ghr_xxx
+  { pattern: /\bgh[pousr]_[a-zA-Z0-9]{36,}\b/g, replace: '[REDACTED_GH_TOKEN]' },
+  // AWS access key IDs: AKIA... (20 uppercase alphanumeric)
+  { pattern: /\bAKIA[A-Z0-9]{16}\b/g, replace: '[REDACTED_AWS_KEY]' },
+  // PEM private key blocks (detect header line)
+  {
+    pattern:
+      /-----BEGIN (?:RSA |EC |DSA |OPENSSH |ENCRYPTED )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |DSA |OPENSSH |ENCRYPTED )?PRIVATE KEY-----/g,
+    replace: '[REDACTED_PEM]',
+  },
+];
+
+// ----------------------------------------------------------------
+// loadTelematicsConfig
+//
+// Reads <home>/config.json. Returns { enabled, sensitiveKeys }.
+// Missing file, malformed JSON, absent telematics key,
+// telematics.enabled !== true → disabled.
+// telematics.sensitiveKeys: string array or absent.
+// Unknown keys ignored. Never writes or repairs config.
+// ----------------------------------------------------------------
+function loadTelematicsConfig(homeDir, _fs, _path) {
+  const fs = _fs || require('node:fs');
+  const p = _path || path;
+  const configPath = p.join(homeDir, 'config.json');
+  try {
+    if (!fs.existsSync(configPath)) {
+      return { enabled: false, sensitiveKeys: [] };
+    }
+    const raw = fs.readFileSync(configPath, 'utf8');
+    const cfg = JSON.parse(raw);
+    if (!cfg || typeof cfg !== 'object') {
+      return { enabled: false, sensitiveKeys: [] };
+    }
+    const telematics = cfg.telematics;
+    if (!telematics || typeof telematics !== 'object') {
+      return { enabled: false, sensitiveKeys: [] };
+    }
+    if (telematics.enabled !== true) {
+      return { enabled: false, sensitiveKeys: [] };
+    }
+    // Parse sensitiveKeys: optional array of nonempty strings
+    let extra = [];
+    if (Array.isArray(telematics.sensitiveKeys)) {
+      extra = telematics.sensitiveKeys
+        .filter(function (k) {
+          return typeof k === 'string' && k.length > 0;
+        })
+        .map(function (k) {
+          return k.toLowerCase();
+        });
+    }
+    return { enabled: true, sensitiveKeys: extra };
+  } catch (_) {
+    return { enabled: false, sensitiveKeys: [] };
+  }
+}
+
+// ----------------------------------------------------------------
+// sanitizeId
+//
+// Trims whitespace and strips everything except [A-Za-z0-9._-].
+// Rejects `.`, `..`, and empty results to prevent path traversal
+// when the ID is used as a directory name in path.join.
+// Returns empty string when input is null/undefined or result is
+// empty/rejected after filtering.
+// ----------------------------------------------------------------
+function sanitizeId(raw) {
+  if (raw == null || typeof raw !== 'string') return '';
+  const cleaned = raw.trim().replace(/[^A-Za-z0-9._-]/g, '');
+  // Reject dot, dot-dot, and empty — these cause path.join traversal
+  if (cleaned === '.' || cleaned === '..' || cleaned.length === 0) return '';
+  return cleaned;
+}
+
+// ----------------------------------------------------------------
+// redact
+//
+// Deep-walks value without mutation.
+// 1. Key name matching (case-insensitive) → "[REDACTED]", no descent.
+// 2. String pattern scanning for secrets (Bearer, sk-, GitHub, AWS, PEM).
+// 3. key=value pairs: if key matches sensitive set, redact value.
+// 4. JSON/query strings: URL query-style &key=value redaction.
+// 5. Cycles, unsupported values, getters/proxies →
+//    "[UNSERIALIZABLE]"; never throws.
+//
+// Returns a redacted deep copy.
+// ----------------------------------------------------------------
+function redact(value, sensitiveKeys) {
+  // Built-ins always apply. Configured keys are additive.
+  const extraLen = Array.isArray(sensitiveKeys) ? sensitiveKeys.length : 0;
+
+  const keySet = new Set();
+  for (let i = 0; i < BUILTIN_SENSITIVE_KEYS.length; i++) {
+    keySet.add(BUILTIN_SENSITIVE_KEYS[i].toLowerCase());
+  }
+  for (let j = 0; j < extraLen; j++) {
+    keySet.add(String(sensitiveKeys[j]).toLowerCase());
+  }
+
+  const seen = new WeakSet(); // cycle detection
+
+  function walk(v, depth) {
+    if (depth === undefined) depth = 0;
+    if (depth > 100) return '[UNSERIALIZABLE]'; // depth guard
+    if (v === null || v === undefined) return v;
+    if (typeof v !== 'object') {
+      if (typeof v === 'string') {
+        return redactString(v, keySet);
+      }
+      return v;
+    }
+
+    // Cycle / unsupported check
+    if (typeof v === 'object') {
+      try {
+        // Detect getters/proxies by attempting key enumeration
+        Object.keys(v);
+      } catch (_) {
+        return '[UNSERIALIZABLE]';
+      }
+      try {
+        if (seen.has(v)) return '[UNSERIALIZABLE]';
+        seen.add(v);
+      } catch (_) {
+        return '[UNSERIALIZABLE]';
+      }
+    }
+
+    if (Array.isArray(v)) {
+      const arrOut = [];
+      for (let ai = 0; ai < v.length; ai++) {
+        try {
+          arrOut.push(walk(v[ai], depth + 1));
+        } catch (_) {
+          arrOut.push('[UNSERIALIZABLE]');
+        }
+      }
+      return arrOut;
+    }
+
+    // Object
+    const out = {};
+    let keys;
+    try {
+      keys = Object.keys(v);
+    } catch (_) {
+      return '[UNSERIALIZABLE]';
+    }
+    for (let ki = 0; ki < keys.length; ki++) {
+      const k = keys[ki];
+      const klower = String(k).toLowerCase();
+      try {
+        if (keySet.has(klower)) {
+          out[k] = '[REDACTED]';
+        } else {
+          out[k] = walk(v[k], depth + 1);
+        }
+      } catch (_) {
+        out[k] = '[UNSERIALIZABLE]';
+      }
+    }
+    return out;
+  }
+
+  return walk(value);
+}
+
+// ----------------------------------------------------------------
+// redactString — apply pattern redactions to string values
+// ----------------------------------------------------------------
+function redactString(str, keySet) {
+  let result = str;
+  for (let i = 0; i < PATTERN_REDACTIONS.length; i++) {
+    result = result.replace(PATTERN_REDACTIONS[i].pattern, PATTERN_REDACTIONS[i].replace);
+  }
+
+  // Redact key=value pairs where key matches sensitive set.
+  // Matches sequences like: key=value, key="value", key='value'
+  // in URLs, headers, JSON-embedded query strings.
+  const eqPattern = /([\w.-]+)\s*=\s*("[^"]*"|'[^']*'|[^\s&;,}'"\]]+)/gi;
+  result = result.replace(eqPattern, function (_match, key, _value) {
+    const lower = key.toLowerCase();
+    if (keySet.has(lower)) {
+      return key + '=[REDACTED]';
+    }
+    return _match;
+  });
+
+  return result;
+}
+
+// ----------------------------------------------------------------
+// createTelematics
+//
+// Factory. Loads config exactly once during construction. Returns
+// a telematics instance:
+//
+//   .enabled    boolean — false when config absent/disabled
+//   .sessionId  string | null — sanitised session id (null when disabled)
+//   .emit(eventType, payload)   writes a single NDJSON envelope; never throws
+//   .close()    closes the underlying fd; never throws
+//
+// Envelope keys per spec:
+//   schemaVersion  — integer 1
+//   eventId        — UUID per event
+//   eventType      — string
+//   timestamp      — UTC ISO-8601
+//   monotonicMs    — ms since construction
+//   harness        — "claude" | "opencode"
+//   sessionId      — sanitised session id
+//   processId      — numeric PID
+//   cwd            — current working directory
+//   payload        — redacted event payload
+// ----------------------------------------------------------------
+function createTelematics(deps) {
+  const harness = deps.harness;
+  const sessionId = deps.sessionId;
+  const processId = deps.processId;
+  const cwd = deps.cwd;
+  const home = deps.home;
+  const now = deps.now;
+  const uuidFn = deps.uuid;
+  const fs = deps.fs;
+
+  // One-time config load
+  const cfg = loadTelematicsConfig(home, fs, path);
+
+  if (!cfg.enabled) {
+    return {
+      enabled: false,
+      sessionId: null,
+      emit: function () {
+        /* noop */
+      },
+      close: function () {
+        /* noop */
+      },
+    };
+  }
+
+  // Build effective sensitive key set
+  const sensitiveKeys = [];
+  for (let i = 0; i < BUILTIN_SENSITIVE_KEYS.length; i++) {
+    if (sensitiveKeys.indexOf(BUILTIN_SENSITIVE_KEYS[i].toLowerCase()) === -1) {
+      sensitiveKeys.push(BUILTIN_SENSITIVE_KEYS[i].toLowerCase());
+    }
+  }
+  if (Array.isArray(cfg.sensitiveKeys)) {
+    for (let j = 0; j < cfg.sensitiveKeys.length; j++) {
+      const ek = String(cfg.sensitiveKeys[j]).toLowerCase();
+      if (sensitiveKeys.indexOf(ek) === -1) {
+        sensitiveKeys.push(ek);
+      }
+    }
+  }
+
+  // Sanitize sessionId or generate one
+  let sid = sanitizeId(sessionId);
+  if (!sid) {
+    if (typeof uuidFn === 'function') {
+      sid = sanitizeId(String(uuidFn()));
+    }
+    if (!sid) {
+      sid = 'gen-' + Date.now() + '-' + Math.random().toString(36).slice(2, 10);
+      sid = sanitizeId(sid);
+    }
+  }
+  if (!sid) {
+    sid = 'gen-' + Date.now();
+  }
+
+  // Construction timestamp for monotonicMs baseline
+  const startMs = Date.now();
+
+  // Log directory: <home>/logs/<sanitized-session-id>/
+  const logDir = path.join(home, 'logs', sid);
+  const logFile = path.join(logDir, 'events.ndjson');
+
+  let fd = null;
+  let ensured = false;
+
+  // ----------------------------------------------------------------
+  // ensureLogDir — create dir mode 0700, open file mode 0600
+  // Refuses symlinks, nonregular files, and paths that resolve
+  // outside <home>/logs/. Fails closed: if we can't secure it,
+  // telemetry stays disabled for the process (emit becomes noop
+  // after failed ensure).
+  // ----------------------------------------------------------------
+  function ensureLogDir() {
+    if (ensured) return fd !== null;
+    ensured = true;
+    try {
+      // Resolve logDir and verify it stays under <home>/logs/
+      const resolved = path.resolve(logDir);
+      const logsPrefix = path.resolve(home, 'logs') + path.sep;
+      if (!resolved.startsWith(logsPrefix)) {
+        return false; // path escaped the logs sandbox — fail closed
+      }
+
+      // Create log directory chain with 0700
+      fs.mkdirSync(logDir, { recursive: true, mode: 0o700 });
+      // Explicit chmod to counter umask
+      fs.chmodSync(logDir, 0o700);
+
+      // Check if log file exists and is regular + not symlink
+      let stat;
+      let exists = false;
+      try {
+        stat = fs.lstatSync(logFile);
+        exists = true;
+      } catch (_) {
+        /* file does not exist — ok */
+      }
+
+      if (exists) {
+        // Refuse nonregular targets or symlinks
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+          return false; // fail closed
+        }
+        // Chmod existing file before use
+        fs.chmodSync(logFile, 0o600);
+      }
+
+      // Open for append
+      fd = fs.openSync(logFile, 'a', 0o600);
+      // Chmod again after open (best-effort)
+      try {
+        fs.fchmodSync(fd, 0o600);
+      } catch (_) {
+        /* best effort */
+      }
+      return true;
+    } catch (_) {
+      return false; // fail closed
+    }
+  }
+
+  function emit(eventType, payload) {
+    try {
+      if (!ensureLogDir()) return;
+      const monotonicMs = Date.now() - startMs;
+      let eventId;
+      try {
+        eventId = uuidFn ? String(uuidFn()) : crypto.randomUUID();
+      } catch (_) {
+        eventId = 'fallback-' + Date.now() + '-' + Math.random().toString(36).slice(2, 10);
+      }
+      const redactedPayload = redact(payload, sensitiveKeys);
+      const envelope = {
+        schemaVersion: 1,
+        eventId: eventId,
+        eventType: eventType,
+        timestamp: typeof now === 'function' ? now() : new Date().toISOString(),
+        monotonicMs: monotonicMs,
+        harness: harness,
+        sessionId: sid,
+        processId: processId,
+        cwd: cwd,
+        payload: redactedPayload,
+      };
+      const line = JSON.stringify(envelope) + '\n';
+      if (fd !== null) {
+        fs.writeSync(fd, line);
+      }
+    } catch (_) {
+      // Silent — telematics must never throw
+    }
+  }
+
+  function close() {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch (_) {
+        /* silent */
+      }
+      fd = null;
+    }
+  }
+
+  return {
+    enabled: true,
+    sessionId: sid,
+    emit: emit,
+    close: close,
+  };
+}
+
+module.exports = {
+  createTelematics: createTelematics,
+  redact: redact,
+  loadTelematicsConfig: loadTelematicsConfig,
+  sanitizeId: sanitizeId,
+  BUILTIN_SENSITIVE_KEYS: BUILTIN_SENSITIVE_KEYS,
+};