claude-code-session-manager 0.82.0 → 0.84.0

package/src/main/lib/__tests__/telemetryBoot.test.cjs

@@ -0,0 +1,125 @@
+/**
+ * telemetryBoot.test.cjs — unit tests for the boot-time telemetry send rules:
+ * the machine-profile heartbeat (version-change OR 30-day liveness) and the
+ * boot/version-change flush triggers.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/telemetryBoot.test.cjs
+ */
+'use strict';
+
+import { test, expect } from 'vitest';
+const { bootSequence } = require('../telemetryBoot.cjs');
+const telemetrySettings = require('../telemetrySettings.cjs');
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function fakeDeps({ settings } = {}) {
+  let saved = { ...telemetrySettings.DEFAULTS, ...settings };
+  const flushCalls = [];
+  return {
+    state: () => saved,
+    flushCalls,
+    deps: {
+      telemetrySettings: {
+        load: async () => saved,
+        save: async (next) => { saved = { ...saved, ...next }; return saved; },
+        isMachineReportDue: telemetrySettings.isMachineReportDue,
+      },
+      telemetryClient: {
+        flush: async (reason) => { flushCalls.push(reason); return { sent: [], failed: [], reason }; },
+        track: async (name, props) => ({ accepted: true, name, props }),
+      },
+      buildMachineProfile: async () => ({ appVersion: '1.0.0', platform: 'linux', arch: 'x64', machineDigest: 'abc123' }),
+      telemetryCounters: { trackAppLaunch: () => {} },
+    },
+  };
+}
+
+test('a second boot at the same version within 30 days sends nothing', async () => {
+  const now = Date.now();
+  const priorReportAt = new Date(now - DAY_MS).toISOString();
+  const { deps, state } = fakeDeps({
+    settings: { lastMachineReportAt: priorReportAt, lastMachineReportVersion: '1.0.0' },
+  });
+  const seen = [];
+  deps.telemetryClient.track = async (name, props) => { seen.push({ name, props }); return { accepted: true }; };
+
+  await bootSequence({ now, appVersion: '1.0.0', deps });
+
+  expect(seen.filter((e) => e.name === 'install.machine')).toHaveLength(0);
+  expect(state().lastMachineReportAt).toBe(priorReportAt);
+});
+
+test('a version bump sends the machine profile exactly once', async () => {
+  const now = Date.now();
+  const { deps, state } = fakeDeps({
+    settings: { lastMachineReportAt: new Date(now - DAY_MS).toISOString(), lastMachineReportVersion: '1.0.0' },
+  });
+  const seen = [];
+  deps.telemetryClient.track = async (name, props) => { seen.push({ name, props }); return { accepted: true }; };
+
+  await bootSequence({ now, appVersion: '2.0.0', deps });
+
+  const installEvents = seen.filter((e) => e.name === 'install.machine');
+  expect(installEvents.length).toBe(1);
+  expect(state().lastMachineReportVersion).toBe('2.0.0');
+});
+
+test('31 days on an unchanged version sends the machine profile exactly once (liveness heartbeat)', async () => {
+  const now = Date.now();
+  const { deps, state } = fakeDeps({
+    settings: { lastMachineReportAt: new Date(now - 31 * DAY_MS).toISOString(), lastMachineReportVersion: '1.0.0' },
+  });
+  const seen = [];
+  deps.telemetryClient.track = async (name, props) => { seen.push({ name, props }); return { accepted: true }; };
+
+  await bootSequence({ now, appVersion: '1.0.0', deps });
+
+  const installEvents = seen.filter((e) => e.name === 'install.machine');
+  expect(installEvents.length).toBe(1);
+  expect(state().lastMachineReportAt).toBe(new Date(now).toISOString());
+});
+
+test('the install.machine event appVersion prop equals the appVersion stamped on a sibling error record', async () => {
+  const now = Date.now();
+  const { deps } = fakeDeps({ settings: { lastMachineReportVersion: '', lastMachineReportAt: null } });
+  const seen = [];
+  deps.telemetryClient.track = async (name, props) => { seen.push({ name, props }); return { accepted: true }; };
+  // Sibling error record stamped by the SAME process's telemetryClient with the same appVersion.
+  const siblingErrorStampAppVersion = '1.0.0';
+
+  await bootSequence({ now, appVersion: '1.0.0', deps });
+
+  const [install] = seen.filter((e) => e.name === 'install.machine');
+  expect(install.props.appVersion).toBe(siblingErrorStampAppVersion);
+});
+
+test('on app ready, flush("boot") always runs', async () => {
+  const now = Date.now();
+  const { deps, flushCalls } = fakeDeps({ settings: { lastMachineReportVersion: '1.0.0', lastMachineReportAt: new Date(now).toISOString() } });
+  await bootSequence({ now, appVersion: '1.0.0', deps });
+  expect(flushCalls).toContain('boot');
+});
+
+test('on a detected app-version change, flush("version-change") also runs', async () => {
+  const now = Date.now();
+  const { deps, flushCalls } = fakeDeps({ settings: { lastMachineReportVersion: '1.0.0', lastMachineReportAt: new Date(now).toISOString() } });
+  await bootSequence({ now, appVersion: '2.0.0', deps });
+  expect(flushCalls).toEqual(['boot', 'version-change']);
+});
+
+test('with no version change, flush("version-change") does NOT run', async () => {
+  const now = Date.now();
+  const { deps, flushCalls } = fakeDeps({ settings: { lastMachineReportVersion: '1.0.0', lastMachineReportAt: new Date(now).toISOString() } });
+  await bootSequence({ now, appVersion: '1.0.0', deps });
+  expect(flushCalls).toEqual(['boot']);
+});
+
+test('fires app.launch via telemetryCounters with installChannel + appVersion', async () => {
+  const now = Date.now();
+  const { deps } = fakeDeps({ settings: { lastMachineReportVersion: '1.0.0', lastMachineReportAt: new Date(now).toISOString() } });
+  const calls = [];
+  deps.telemetryCounters = { trackAppLaunch: (props) => calls.push(props) };
+  await bootSequence({ now, appVersion: '1.0.0', installChannel: 'npx', deps });
+  expect(calls).toEqual([{ installChannel: 'npx', appVersion: '1.0.0' }]);
+});

package/src/main/lib/__tests__/telemetryConsent.test.cjs

@@ -0,0 +1,130 @@
+/**
+ * telemetryConsent.test.cjs — unit tests for the telemetry:set-config
+ * handler's write path (PRD 1142).
+ *
+ * Run: timeout 300 npx vitest run src/main/lib/__tests__/telemetryConsent.test.cjs
+ */
+'use strict';
+
+import { test, expect, beforeEach, afterEach, vi } from 'vitest';
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+
+const tmpDirs = [];
+let originalHome;
+
+beforeEach(() => {
+  originalHome = process.env.HOME;
+});
+
+afterEach(async () => {
+  if (originalHome !== undefined) process.env.HOME = originalHome; else delete process.env.HOME;
+  vi.unstubAllGlobals();
+  while (tmpDirs.length) {
+    const d = tmpDirs.pop();
+    await fsp.rm(d, { recursive: true, force: true });
+  }
+});
+
+async function mkHome() {
+  const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-telemetry-consent-home-'));
+  tmpDirs.push(dir);
+  return dir;
+}
+
+function freshModules(home) {
+  process.env.HOME = home;
+  for (const p of ['../telemetryConsent.cjs', '../telemetryClient.cjs', '../telemetrySettings.cjs', '../machineProfile.cjs', '../../config.cjs']) {
+    const resolved = require.resolve(p);
+    delete require.cache[resolved];
+  }
+  const telemetryConsent = require('../telemetryConsent.cjs');
+  const telemetrySettings = require('../telemetrySettings.cjs');
+  const telemetryClient = require('../telemetryClient.cjs');
+  telemetryClient._setMachineProfileBuilder(async () => ({
+    appVersion: '0.83.0', platform: 'linux', arch: 'x64', machineDigest: 'abc123', installChannel: 'dev',
+  }));
+  return { telemetryConsent, telemetrySettings, telemetryClient };
+}
+
+test('turning telemetry off persists enabled:false and telemetrySettings.isEnabled() reflects it', async () => {
+  const home = await mkHome();
+  const { telemetryConsent, telemetrySettings } = freshModules(home);
+  const cfg = await telemetrySettings.load();
+  expect(cfg.enabled).toBe(true);
+
+  const saved = await telemetryConsent.applyConsentUpdate({ ...cfg, enabled: false });
+  expect(saved.enabled).toBe(false);
+  expect(telemetrySettings.isEnabled(saved)).toBe(false);
+});
+
+test('after turning off, telemetryClient drops subsequent records at ingress', async () => {
+  const home = await mkHome();
+  const { telemetryConsent, telemetrySettings, telemetryClient } = freshModules(home);
+  const cfg = await telemetrySettings.load();
+  await telemetryConsent.applyConsentUpdate({ ...cfg, enabled: false });
+
+  const res = await telemetryClient.track('some.event', { a: 1 });
+  expect(res).toEqual({ accepted: false, reason: 'disabled' });
+  telemetryClient.shutdown();
+});
+
+test('turning off clears the pending queue file so a re-enable never resends it', async () => {
+  const home = await mkHome();
+  const { telemetryConsent, telemetrySettings, telemetryClient } = freshModules(home);
+
+  // Accumulate a record while still enabled.
+  const accepted = await telemetryClient.reportError({ name: 'BoomError', msg: 'kaboom', stack: 'at x' });
+  expect(accepted.accepted).toBe(true);
+  const beforeQueue = await fsp.readFile(telemetryClient.queuePath(), 'utf8');
+  expect(beforeQueue.trim().length).toBeGreaterThan(0);
+
+  const cfg = await telemetrySettings.load();
+  await telemetryConsent.applyConsentUpdate({ ...cfg, enabled: false });
+
+  const afterQueue = await fsp.readFile(telemetryClient.queuePath(), 'utf8');
+  expect(afterQueue.trim()).toBe('');
+  telemetryClient.shutdown();
+});
+
+test('turning off does NOT clear telemetry-sent.json or the watermarks — re-enabling later does not resend delivered history', async () => {
+  const home = await mkHome();
+  const { telemetryConsent, telemetrySettings, telemetryClient } = freshModules(home);
+
+  telemetryClient._setFetchImpl(async () => ({ ok: true, status: 200 }));
+  await telemetryClient.reportError({ name: 'SentError', msg: 'already delivered', stack: 'at y' });
+  await telemetryClient.flush('manual');
+  const sentPathContent = await fsp.readFile(telemetryClient.sentPath(), 'utf8');
+  expect(JSON.parse(sentPathContent).ids.length).toBeGreaterThan(0);
+
+  // Also seed a watermarks file to prove opt-out leaves it untouched.
+  const watermarksDir = path.join(home, '.config', 'session-manager');
+  await fsp.mkdir(watermarksDir, { recursive: true });
+  const watermarksPath = path.join(watermarksDir, 'telemetry-watermarks.json');
+  const watermarksBefore = { 'abc123/errors-2026-01-01.jsonl': { bytesEnqueued: 100, bytesConfirmed: 100 } };
+  await fsp.writeFile(watermarksPath, JSON.stringify(watermarksBefore));
+
+  const cfg = await telemetrySettings.load();
+  await telemetryConsent.applyConsentUpdate({ ...cfg, enabled: false });
+
+  const sentAfter = await fsp.readFile(telemetryClient.sentPath(), 'utf8');
+  expect(sentAfter).toBe(sentPathContent);
+  const watermarksAfter = await fsp.readFile(watermarksPath, 'utf8');
+  expect(JSON.parse(watermarksAfter)).toEqual(watermarksBefore);
+  telemetryClient.shutdown();
+});
+
+test('turning telemetry on (already enabled) is a no-op on the queue', async () => {
+  const home = await mkHome();
+  const { telemetryConsent, telemetrySettings, telemetryClient } = freshModules(home);
+  await telemetryClient.reportError({ name: 'KeptError', msg: 'still queued', stack: 'at z' });
+  const before = await fsp.readFile(telemetryClient.queuePath(), 'utf8');
+
+  const cfg = await telemetrySettings.load();
+  await telemetryConsent.applyConsentUpdate({ ...cfg, enabled: true });
+
+  const after = await fsp.readFile(telemetryClient.queuePath(), 'utf8');
+  expect(after).toBe(before);
+  telemetryClient.shutdown();
+});

package/src/main/lib/__tests__/telemetryCounters.test.cjs

@@ -0,0 +1,57 @@
+/**
+ * telemetryCounters.test.cjs — unit tests for the single shared emission
+ * point behind 'app.launch' / 'session.open' / 'epic.create' /
+ * 'scheduler.job.finish'. Each real call site (pty.cjs, epicMint.cjs,
+ * scheduleJobTransitions.cjs, telemetryBoot.cjs) delegates here, so this is
+ * where the event name + prop-key shape is verified once.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/telemetryCounters.test.cjs
+ */
+'use strict';
+
+import { test, expect } from 'vitest';
+const counters = require('../telemetryCounters.cjs');
+
+function fakeClient() {
+  const calls = [];
+  return { calls, deps: { telemetryClient: { track: (name, props) => { calls.push({ name, props }); } } } };
+}
+
+test('trackAppLaunch fires app.launch once with installChannel + appVersion', () => {
+  const { calls, deps } = fakeClient();
+  counters.trackAppLaunch({ installChannel: 'npx', appVersion: '0.83.0' }, deps);
+  expect(calls).toHaveLength(1);
+  expect(calls[0].name).toBe('app.launch');
+  expect(Object.keys(calls[0].props).sort()).toEqual(['appVersion', 'installChannel'].sort());
+});
+
+test('trackSessionOpen fires session.open once', () => {
+  const { calls, deps } = fakeClient();
+  counters.trackSessionOpen(deps);
+  expect(calls).toHaveLength(1);
+  expect(calls[0].name).toBe('session.open');
+});
+
+test('trackEpicCreate fires epic.create once', () => {
+  const { calls, deps } = fakeClient();
+  counters.trackEpicCreate(deps);
+  expect(calls).toHaveLength(1);
+  expect(calls[0].name).toBe('epic.create');
+});
+
+test('trackSchedulerJobFinish fires scheduler.job.finish once with a status-only prop', () => {
+  const { calls, deps } = fakeClient();
+  counters.trackSchedulerJobFinish({ status: 'completed' }, deps);
+  expect(calls).toHaveLength(1);
+  expect(calls[0].name).toBe('scheduler.job.finish');
+  expect(Object.keys(calls[0].props)).toEqual(['status']);
+  expect(calls[0].props.status).toBe('completed');
+});
+
+test('a throwing telemetryClient.track never escapes any counter function', () => {
+  const deps = { telemetryClient: { track: () => { throw new Error('boom'); } } };
+  expect(() => counters.trackAppLaunch({ installChannel: 'dev', appVersion: '1.0.0' }, deps)).not.toThrow();
+  expect(() => counters.trackSessionOpen(deps)).not.toThrow();
+  expect(() => counters.trackEpicCreate(deps)).not.toThrow();
+  expect(() => counters.trackSchedulerJobFinish({ status: 'failed' }, deps)).not.toThrow();
+});

package/src/main/lib/__tests__/telemetryCountersMetadataColumn.test.cjs

@@ -0,0 +1,89 @@
+/**
+ * telemetryCountersMetadataColumn.test.cjs — the event channel has no version
+ * column (telemetryClient.test.cjs's "funnel_events has no version column"
+ * test covers the generic case); this asserts the same survives specifically
+ * for each of the four counter events this PRD adds, once serialized the way
+ * the /api/telemetry/event route persists it into `metadata`.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/telemetryCountersMetadataColumn.test.cjs
+ */
+'use strict';
+
+import { test, expect, afterEach } from 'vitest';
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+
+const counters = require('../telemetryCounters.cjs');
+
+const tmpDirs = [];
+let originalHome;
+
+afterEach(async () => {
+  if (originalHome !== undefined) process.env.HOME = originalHome;
+  while (tmpDirs.length) {
+    const d = tmpDirs.pop();
+    await fsp.rm(d, { recursive: true, force: true });
+  }
+});
+
+async function mkHome() {
+  originalHome = process.env.HOME;
+  const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-telemetry-counters-home-'));
+  tmpDirs.push(dir);
+  process.env.HOME = dir;
+  return dir;
+}
+
+function freshClient() {
+  for (const p of ['../telemetryClient.cjs', '../../config.cjs', '../telemetrySettings.cjs', '../machineProfile.cjs']) {
+    const resolved = require.resolve(p);
+    delete require.cache[resolved];
+  }
+  const client = require('../telemetryClient.cjs');
+  client._setMachineProfileBuilder(async () => ({
+    appVersion: '0.83.0', platform: 'linux', arch: 'x64', machineDigest: 'deadbeefcafe',
+  }));
+  return client;
+}
+
+async function readQueueLines(client) {
+  const fs = require('node:fs/promises');
+  try {
+    const raw = await fs.readFile(client.queuePath(), 'utf8');
+    return raw.split('\n').filter(Boolean).map((l) => JSON.parse(l));
+  } catch (e) {
+    if (e.code === 'ENOENT') return [];
+    throw e;
+  }
+}
+
+function asPersistedMetadata(rec) {
+  // Mirrors exactly what the deployed /api/telemetry/event INSERT persists
+  // into the `metadata` column (see telemetryClient.test.cjs).
+  return JSON.parse(JSON.stringify(rec.wire.props));
+}
+
+test('every counter event still yields appVersion + machineDigest once persisted into metadata', async () => {
+  await mkHome();
+  const client = freshClient();
+  const deps = { telemetryClient: client };
+
+  counters.trackAppLaunch({ installChannel: 'npx', appVersion: '0.83.0' }, deps);
+  counters.trackSessionOpen(deps);
+  counters.trackEpicCreate(deps);
+  counters.trackSchedulerJobFinish({ status: 'completed' }, deps);
+
+  // track() ingress does real (albeit fast) fs I/O before it resolves; wait a
+  // tick since the counter functions fire it without awaiting the promise.
+  await new Promise((r) => setTimeout(r, 50));
+
+  const recs = await readQueueLines(client);
+  expect(recs.length).toBe(4);
+  for (const rec of recs) {
+    const meta = asPersistedMetadata(rec);
+    expect(meta.appVersion).toBe('0.83.0');
+    expect(meta.machineDigest).toBe('deadbeefcafe');
+  }
+  client.shutdown();
+});

package/src/main/lib/crashTelemetry.cjs

@@ -0,0 +1,37 @@
+'use strict';
+
+/**
+ * crashTelemetry.cjs — the electron-free tap crashDiagnostics.cjs's
+ * render-process-gone / child-process-gone hooks and unclean-shutdown
+ * postmortem call into. Split out so it's unit-testable under plain vitest —
+ * crashDiagnostics.cjs itself requires 'electron' at module scope (it always
+ * has; that's why it has never had a unit test), so the tap logic lives here
+ * instead of inline in that file.
+ *
+ * Named 'crash.<reason>' so an OOM report (reason: 'oom'), a renderer segfault
+ * (reason: 'crashed'), and the unclean-shutdown postmortem (reason:
+ * 'unclean-shutdown') are distinguishable in aggregate without parsing free
+ * text. telemetryClient.reportError already stamps the full attribution
+ * (appVersion/platform/arch/machineDigest) on every record — that's the
+ * whole reason this module exists: these reports are frequently the ONLY
+ * thing ever received from a machine that just got OOM-killed, so losing the
+ * build/spec attribution on them is close to useless.
+ */
+
+function reportCrash({ reason, meta, deps } = {}) {
+  try {
+    const telemetryClient = (deps && deps.telemetryClient) || require('./telemetryClient.cjs');
+    // Returned (not awaited here) so callers/tests can await delivery
+    // acceptance; telemetryClient.reportError is itself fail-inert, so a
+    // rejected/throwing implementation still can't escape this try/catch.
+    return telemetryClient.reportError({
+      name: `crash.${reason || 'unknown'}`,
+      msg: String(reason || 'unknown'),
+      context: meta || {},
+    });
+  } catch {
+    return undefined; // crash diagnostics must never break on a telemetry failure
+  }
+}
+
+module.exports = { reportCrash };

package/src/main/lib/delegationReadiness.cjs

@@ -30,6 +30,8 @@ const PRD_WRITE_GUARD_SCRIPT = path.resolve(__dirname, '..', '..', '..', 'script
 const PRD_WRITE_GUARD_MATCHER = 'Write|Edit|NotebookEdit';
 const DESTRUCTIVE_GIT_GUARD_SCRIPT = path.resolve(__dirname, '..', '..', '..', 'scripts', 'hooks', 'guard-destructive-git.cjs');
 const DESTRUCTIVE_GIT_GUARD_MATCHER = 'Bash';
+const INLINE_IMPLEMENTATION_GUARD_SCRIPT = path.resolve(__dirname, '..', '..', '..', 'scripts', 'hooks', 'guard-inline-implementation.cjs');
+const INLINE_IMPLEMENTATION_GUARD_MATCHER = 'Write|Edit|NotebookEdit';
 const LIVE_PROBE_TIMEOUT_MS = 10_000;
 const LIVE_PROBE_TTL_MS = 60_000;
 const REQUIRED_LIVE_TOOLS = ['scheduler_create_prd', 'session_manager_help'];
@@ -446,6 +448,12 @@ async function installPrdWriteGuard({ cwd }) {
     // the human has in there.
     return { ok: false, action: 'error', error: `${settingsPath} is not valid JSON — fix it by hand before installing the guard` };
   }
+  if (!fs.existsSync(PRD_WRITE_GUARD_SCRIPT)) {
+    // Writing a hook that points at a script that doesn't exist would report
+    // installed while silently guarding nothing (a non-zero-without-2 exit is
+    // a non-blocking error to the harness) — refuse instead of lying.
+    return { ok: false, action: 'error', error: `${PRD_WRITE_GUARD_SCRIPT} does not exist — cannot install a guard hook that points at a missing script` };
+  }
   const settings = (existing && typeof existing === 'object' && !Array.isArray(existing)) ? existing : {};
 
   const command = `node ${PRD_WRITE_GUARD_SCRIPT}`;
@@ -546,6 +554,9 @@ async function installDestructiveGitGuard({ cwd }) {
   if (existing === undefined) {
     return { ok: false, action: 'error', error: `${settingsPath} is not valid JSON — fix it by hand before installing the guard` };
   }
+  if (!fs.existsSync(DESTRUCTIVE_GIT_GUARD_SCRIPT)) {
+    return { ok: false, action: 'error', error: `${DESTRUCTIVE_GIT_GUARD_SCRIPT} does not exist — cannot install a guard hook that points at a missing script` };
+  }
   const settings = (existing && typeof existing === 'object' && !Array.isArray(existing)) ? existing : {};
 
   const command = `node ${DESTRUCTIVE_GIT_GUARD_SCRIPT}`;
@@ -585,7 +596,110 @@ async function installDestructiveGitGuard({ cwd }) {
 }
 
 /**
- * Runs all seven delegation-readiness checks for `cwd`. Every filesystem read
+ * `ok` must mean "a hook that will actually run", not "the settings file
+ * mentions guard-inline-implementation somewhere" — same rationale as
+ * checkPrdWriteGuard above. Note this guard is deliberately a NUDGE that
+ * fails OPEN twice over (see guard-inline-implementation.cjs's header), not
+ * an ownership law like guard-prd-writes — this check's label/detail must
+ * not imply it's a hard gate.
+ */
+function checkInlineImplementationGuard({ cwd }) {
+  const settings = readJsonSafe(path.join(cwd, '.claude', 'settings.json'), null);
+  const preToolUse = Array.isArray(settings?.hooks?.PreToolUse) ? settings.hooks.PreToolUse : [];
+
+  let mentioned = false;
+  let resolvedScript = null;
+  for (const matcher of preToolUse) {
+    if (!Array.isArray(matcher?.hooks)) continue;
+    for (const h of matcher.hooks) {
+      if (typeof h?.command !== 'string' || !h.command.includes('guard-inline-implementation')) continue;
+      mentioned = true;
+      const raw = extractGuardScriptPath(h.command, 'guard-inline-implementation.cjs');
+      if (!raw) continue;
+      const abs = path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
+      if (fs.existsSync(abs)) { resolvedScript = abs; break; }
+    }
+    if (resolvedScript) break;
+  }
+
+  const ok = !!resolvedScript;
+  let detail;
+  if (ok) detail = `guard-inline-implementation PreToolUse hook found in ${cwd}/.claude/settings.json, resolving to ${resolvedScript}`;
+  else if (mentioned) detail = `guard-inline-implementation PreToolUse hook in ${cwd}/.claude/settings.json names a script that does not exist — it would silently guard nothing`;
+  else detail = `no guard-inline-implementation PreToolUse hook in ${cwd}/.claude/settings.json — this is a nudge, not a hard gate`;
+
+  return {
+    id: 'inline-implementation-guard',
+    label: 'Inline-implementation guard hook installed',
+    ok,
+    detail,
+    fix: ok
+      ? null
+      : `Add a PreToolUse hook to ${cwd}/.claude/settings.json matching Write|Edit|NotebookEdit that runs node ${INLINE_IMPLEMENTATION_GUARD_SCRIPT} (a nudge, not a hard gate)`,
+    fixAction: ok ? null : 'install-inline-implementation-guard',
+  };
+}
+
+/**
+ * Install the inline-implementation guard into `<cwd>/.claude/settings.json`.
+ * Same reference-not-vendor rationale and merge/repair/idempotence behaviour
+ * as installPrdWriteGuard above — see that function's header. Unlike
+ * installDestructiveGitGuard, this guard shares installPrdWriteGuard's
+ * matcher (`Write|Edit|NotebookEdit`), so this appends into that SAME
+ * matcher's `hooks` array when it already exists, rather than pushing a new
+ * matcher entry.
+ */
+async function installInlineImplementationGuard({ cwd }) {
+  const settingsPath = path.join(cwd, '.claude', 'settings.json');
+  addAllowedRoot(cwd);
+
+  const existing = fs.existsSync(settingsPath) ? readJsonSafe(settingsPath, undefined) : {};
+  if (existing === undefined) {
+    return { ok: false, action: 'error', error: `${settingsPath} is not valid JSON — fix it by hand before installing the guard` };
+  }
+  if (!fs.existsSync(INLINE_IMPLEMENTATION_GUARD_SCRIPT)) {
+    return { ok: false, action: 'error', error: `${INLINE_IMPLEMENTATION_GUARD_SCRIPT} does not exist — cannot install a guard hook that points at a missing script` };
+  }
+  const settings = (existing && typeof existing === 'object' && !Array.isArray(existing)) ? existing : {};
+
+  const command = `node ${INLINE_IMPLEMENTATION_GUARD_SCRIPT}`;
+  const hooks = (settings.hooks && typeof settings.hooks === 'object') ? settings.hooks : {};
+  const preToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse.slice() : [];
+
+  if (checkInlineImplementationGuard({ cwd }).ok) {
+    return { ok: true, action: 'already-installed', settingsPath, command };
+  }
+
+  let repaired = false;
+  for (const matcher of preToolUse) {
+    if (!Array.isArray(matcher?.hooks)) continue;
+    for (const h of matcher.hooks) {
+      if (typeof h?.command === 'string' && h.command.includes('guard-inline-implementation')) {
+        h.command = command;
+        h.type = 'command';
+        repaired = true;
+      }
+    }
+  }
+
+  if (!repaired) {
+    const target = preToolUse.find((m) => m?.matcher === INLINE_IMPLEMENTATION_GUARD_MATCHER);
+    if (target) {
+      target.hooks = Array.isArray(target.hooks) ? target.hooks : [];
+      target.hooks.push({ type: 'command', command });
+    } else {
+      preToolUse.push({ matcher: INLINE_IMPLEMENTATION_GUARD_MATCHER, hooks: [{ type: 'command', command }] });
+    }
+  }
+
+  const next = { ...settings, hooks: { ...hooks, PreToolUse: preToolUse } };
+  await writeJson(settingsPath, next);
+
+  return { ok: true, action: repaired ? 'repaired' : 'installed', settingsPath, command };
+}
+
+/**
+ * Runs all eight delegation-readiness checks for `cwd`. Every filesystem read
  * is wrapped (readJsonSafe / try-catch) so a missing or unparseable file
  * yields ok:false with a detail, never a thrown exception. Async because
  * scheduler-mcp-live genuinely spawns a process and waits on it (bounded by
@@ -608,6 +722,7 @@ async function checkDelegationReadiness({ cwd, homeDir = os.homedir() }) {
     checkAgentPersonas({ cwd, homeDir }),
     checkPrdWriteGuard({ cwd }),
     checkDestructiveGitGuard({ cwd }),
+    checkInlineImplementationGuard({ cwd }),
   ].map((c) => ({ fixAction: null, warn: false, ...c }));
 
   return {
@@ -620,10 +735,13 @@ module.exports = {
   checkDelegationReadiness,
   installPrdWriteGuard,
   installDestructiveGitGuard,
+  installInlineImplementationGuard,
   probeSchedulerMcpLive,
   clearLiveProbeCache,
   PRD_WRITE_GUARD_SCRIPT,
   PRD_WRITE_GUARD_MATCHER,
   DESTRUCTIVE_GIT_GUARD_SCRIPT,
   DESTRUCTIVE_GIT_GUARD_MATCHER,
+  INLINE_IMPLEMENTATION_GUARD_SCRIPT,
+  INLINE_IMPLEMENTATION_GUARD_MATCHER,
 };

package/src/main/lib/epicMint.cjs

@@ -35,6 +35,7 @@ const { resolveEpicPrdWriteDir } = require('./prdLocations.cjs');
 const { assertOpsWrite } = require('./opsOwnership.cjs');
 const { appendAuditEvent } = require('./auditLog.cjs');
 const { mirrorEpicStatus, removeEpicMirror } = require('./epicStatusMirror.cjs');
+const telemetryCounters = require('./telemetryCounters.cjs');
 // Required as the module object (not destructured) so a test can
 // monkeypatch promptSessionSchema.assertValidPromptSession in place to
 // simulate a corrupted construction — the real construction below is
@@ -380,6 +381,7 @@ function ensureEpic(cwd, { goalText, tag, epicId: explicitEpicId, status = 'prop
 
     const prdDir = resolveEpicPrdWriteDir(cwd, epicId);
     fs.mkdirSync(prdDir, { recursive: true });
+    telemetryCounters.trackEpicCreate();
     return { epicId, prdDir, created: true };
   });
 }