@haposoft/cafekit 0.18.1 → 0.18.2

package/src/claude/hooks/privacy-block.cjs

@@ -14,32 +14,22 @@
  * Exit: 0 (the JSON hook output carries the permission decision)
  */
 
-try {
-  const fs = require('fs');
-  const path = require('path');
-  const { commandAccess } = require('./lib/privacy-command-analysis.cjs');
+const EVALUATION_FAILURE = 'Sensitive access could not be evaluated safely.';
 
-  const RESTRICTED_PATTERNS = [
-    /^\.env(?:[.\[*?{]|$)/i,
-    /^credentials/i,
-    /secrets?\.(ya?ml|json)$/i,
-    /\.pem$/i,
-    /\.key$/i,
-    /\.p12$/i,
-    /\.pfx$/i,
-    /^id_(rsa|ed25519|ecdsa|dsa)$/i,
-    /\.netrc$/i,
-    /\.pgpass$/i,
-    /kubeconfig/i,
-    /\.keystore$/i,
-    /\.jks$/i,
-    /auth\.json$/i,
-    /token(s)?\.json$/i
-  ];
+function askForPermission(reason) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'ask',
+      permissionDecisionReason: reason
+    }
+  }) + '\n');
+}
 
-  const ALLOWED_EXEMPTIONS = [
-    /\.env\.(example|sample|template|test)$/i
-  ];
+try {
+  const fs = require('fs');
+  const { sensitivePaths, displayNames } = require('./lib/privacy-paths.cjs');
+  const { projectRoot: resolveProjectRoot } = require('./lib/project-root.cjs');
 
   const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
   function readRuntime(cwd) {
@@ -51,199 +41,27 @@ try {
     }
   }
 
-  function isSafe(filePath) {
-    const base = path.basename(filePath);
-    return ALLOWED_EXEMPTIONS.some((rule) => rule.test(base) || rule.test(filePath));
-  }
-
-  function isSensitive(filePath) {
-    const base = path.basename(filePath);
-    return RESTRICTED_PATTERNS.some((rule) => rule.test(base) || rule.test(filePath));
-  }
-
-  /**
-   * Resolve a symlink to its real target so a harmless-looking name that points
-   * at a sensitive file cannot slip through the basename check. Returns null
-   * when the path cannot be resolved (missing file, broken link) — fail-open to
-   * the original-path check in that case. See isSymlinkToSensitive for dangling handling.
-   */
-  function resolveTarget(filePath, cwd) {
-    try {
-      const requested = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
-      return fs.realpathSync(requested);
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * When realpath fails, check whether the requested path is a symlink (or chain)
-   * whose lexical target is sensitive. Dangling link to protected target -> true (fail-closed ask);
-   * dangling benign link or link to allowed example/template -> false (allow).
-   * Limit hops to avoid loops; malformed/looping -> fail closed.
-   * TOCTOU note: check and use are not atomic; target could be swapped between this check and the actual read.
-   * This is a best-effort guardrail, not an arbitrary-shell security boundary. For strong isolation use OS sandbox.
-   */
-  function isSymlinkToSensitive(filePath, cwd) {
-    try {
-      const requested = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
-      let current = requested;
-      let hops = 0;
-      const MAX_HOPS = 8;
-      while (hops < MAX_HOPS) {
-        let stat;
-        try {
-          stat = fs.lstatSync(current);
-        } catch {
-          return false;
-        }
-        if (!stat.isSymbolicLink()) return false;
-        let linkTarget;
-        try {
-          linkTarget = fs.readlinkSync(current);
-        } catch {
-          return true;
-        }
-        if (isSensitive(linkTarget) && !isSafe(linkTarget)) return true;
-        if (isSafe(linkTarget)) return false;
-        const next = path.isAbsolute(linkTarget) ? linkTarget : path.resolve(path.dirname(current), linkTarget);
-        if (next === current) return true;
-        try {
-          const real = fs.realpathSync(next);
-          if (isSensitive(real) && !isSafe(real)) return true;
-          if (isSafe(real)) return false;
-          return false;
-        } catch {
-          current = next;
-          hops += 1;
-          continue;
-        }
-      }
-      return true;
-    } catch {
-      return true;
-    }
-  }
-
-  function extractBashPaths(command) {
-    // The analyzer parses the command and returns the operands of every reading
-    // command it recognises, nested shells and `find -exec` included. Treating
-    // every unresolved expansion as sensitive, as this did before, asked on
-    // `cat $FILE`, `wc -l *.cjs` and `cat ~/.zshrc` alike. Noise is what trains
-    // people to click through the prompt that matters.
-    // A heredoc whose delimiter is quoted (<<'BODY') is inert: the shell
-    // expands nothing inside it, so no word in the body is ever read. The
-    // analyzer has no notion of heredocs and parses the body as shell, so prose
-    // that quotes a command -- a PR body carrying `cat .env` in backticks --
-    // came back as a real command substitution. Blank those bodies out first.
-    // An unquoted delimiter (<<BODY) does expand, so it is left to the
-    // analyzer.
-    const scrubbed = String(command).replace(
-      /(<<-?[ \t]*)(['"])([A-Za-z_]\w*)\2[^\n]*\n[\s\S]*?\n[ \t]*\3\b/g,
-      '$1$2$3$2'
-    );
-
-    const paths = new Set(commandAccess(scrubbed).paths);
-
-    // Two shapes the analyzer cannot return. It drops any word carrying an
-    // expansion, so `~/.ssh/id_rsa` and `certs/*.pem` still have to be matched
-    // by name. And it only walks commands it recognises, so an unknown tool
-    // handed a secret through a file-shaped option, such as
-    // `docker compose --env-file .env`, is invisible to it.
-    const FILE_OPTION = /^--?[\w-]*(?:file|config|key|cert|identity)$/i;
-    const tokens = scrubbed.split(/[\s|;&<>"'()`]+/);
-    for (let index = 0; index < tokens.length; index += 1) {
-      const token = tokens[index];
-      const shaped = /^~|[*?[{]/.test(token);
-      const optionFed = index > 0 && FILE_OPTION.test(tokens[index - 1]);
-      if (!shaped && !optionFed) continue;
-      const value = token.replace(/^~/, '').replace(/^["'()`]+|["'(),]+$/g, '');
-      if (value && isSensitive(value) && !isSafe(value)) paths.add(value);
-    }
-
-    return [...paths];
-  }
-
-  function extractPaths(toolName, input) {
-    const paths = [];
-    if (!input) return paths;
-
-    for (const key of ['file_path', 'path']) {
-      if (typeof input[key] === 'string' && input[key].trim()) {
-        paths.push(input[key].trim());
-      }
-    }
-
-    for (const key of ['paths', 'search_paths']) {
-      if (Array.isArray(input[key])) {
-        paths.push(...input[key].filter(Boolean));
-      }
-    }
-
-    if (toolName === 'Bash' && typeof input.command === 'string') {
-      paths.push(...extractBashPaths(input.command));
-    }
-
-    return paths.filter(Boolean);
-  }
-
-  function askForPermission(filePath) {
-    const basename = path.basename(filePath);
-    process.stdout.write(JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: 'PreToolUse',
-        permissionDecision: 'ask',
-        permissionDecisionReason: `Sensitive file access requires approval: ${basename}`
-      }
-    }) + '\n');
-  }
-
   const stdin = fs.readFileSync(0, 'utf8').trim();
-  if (!stdin) process.exit(0);
+  if (!stdin) {
+    askForPermission(EVALUATION_FAILURE);
+    process.exit(0);
+  }
 
   const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
   const data = normalizeHookPayload(JSON.parse(stdin));
   const toolName = data.tool_name || '';
   const toolInput = data.tool_input || {};
   const cwd = typeof data.cwd === 'string' && data.cwd.trim() ? data.cwd : process.cwd();
-  const runtime = readRuntime(cwd);
+  const projectRoot = resolveProjectRoot(data);
+  const runtime = readRuntime(projectRoot);
 
   if (runtime.privacyBlock === false) process.exit(0);
 
-  const paths = extractPaths(toolName, toolInput);
-  if (!paths.length) process.exit(0);
-
-  for (const filePath of paths) {
-    const target = resolveTarget(filePath, cwd);
-
-    // The real target is authoritative: an exempt-looking alias must not hide
-    // a sensitive target, while a real .env.example target remains safe.
-    if (target) {
-      if (isSensitive(target) && !isSafe(target)) {
-        askForPermission(filePath);
-        process.exit(0);
-      }
-      if (isSafe(target)) continue;
-    } else {
-      if (isSymlinkToSensitive(filePath, cwd)) {
-        askForPermission(filePath);
-        process.exit(0);
-      }
-    }
-
-    if (isSafe(filePath) || !isSensitive(filePath)) continue;
-    askForPermission(filePath);
-    process.exit(0);
-  }
+  const paths = sensitivePaths(toolName, toolInput, cwd);
+  if (paths.length) askForPermission(`Sensitive file access requires approval: ${displayNames(paths)}`);
 
   process.exit(0);
 } catch (_) {
-  process.stdout.write(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: 'PreToolUse',
-      permissionDecision: 'ask',
-      permissionDecisionReason: 'Sensitive access could not be evaluated safely.'
-    }
-  }) + '\n');
+  askForPermission(EVALUATION_FAILURE);
   process.exit(0);
 }

package/src/claude/hooks/rules.cjs

@@ -11,12 +11,12 @@
  */
 
 try {
-  const crypto = require('crypto');
   const fs   = require('fs');
-  const os   = require('os');
   const path = require('path');
 
   const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
+  const { projectRoot } = require('./lib/project-root.cjs');
+  const { reserveSession } = require('./lib/rules-reservation.cjs');
   function readRuntime(cwd) {
     try {
       const p = runtimePath(cwd, 'runtime.json');
@@ -24,26 +24,6 @@ try {
     } catch { return null; }
   }
 
-  /** Reserve one injection slot per session. Returns null on reservation errors. */
-  function reserveSession(sessionId) {
-    if (!sessionId) return null;
-    try {
-      const key = crypto.createHash('sha256')
-        .update(String(sessionId))
-        .digest('hex')
-        .slice(0, 16);
-      const file = path.join(os.tmpdir(), `cafekit-rules-${key}.json`);
-      fs.writeFileSync(file, JSON.stringify({ sessionId: String(sessionId) }), {
-        encoding: 'utf8',
-        flag: 'wx',
-        mode: 0o600
-      });
-      return true;
-    } catch (error) {
-      return error.code === 'EEXIST' ? false : null;
-    }
-  }
-
   // ── Main ──────────────────────────────────────────────────────────────────
 
   const stdin = fs.readFileSync(0, 'utf8').trim();
@@ -52,22 +32,20 @@ try {
   const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
   const payload   = normalizeHookPayload(JSON.parse(stdin));
   const sessionId = payload.session_id || null;
-  const payloadCwd = typeof payload.cwd === 'string' ? payload.cwd.trim() : '';
-  const cwd       = payloadCwd || process.env.PROJECT_ROOT || process.cwd();
+  const root = projectRoot(payload);
+  const runtime = readRuntime(root);
+  if (runtime === null) process.exit(0);
 
   // No session identity or reservation means no injection. Fail open.
   if (reserveSession(sessionId) !== true) process.exit(0);
 
-  const runtime = readRuntime(cwd);
-  if (runtime === null) process.exit(0);
-
   // Language
   const thinkLang   = runtime.locale?.thinkingLanguage || '';
   const respondLang = runtime.locale?.responseLanguage || '';
   const effectThink = thinkLang || (respondLang ? 'en' : '');
 
   // Paths
-  const baseDir   = cwd;
+  const baseDir   = root;
   const plansPath = path.join(baseDir, runtime.paths?.plans || 'plans');
   const docsPath  = path.join(baseDir, runtime.paths?.docs  || 'docs');
   const specsPath = path.join(baseDir, runtime.paths?.specs || 'specs');

package/src/claude/hooks/session.cjs

@@ -11,11 +11,24 @@
  * Exit: 0 always (fail-open)
  */
 
+function logCrash(error) {
+  try {
+    const fs = require('fs'), path = require('path');
+    const dir = require('./lib/hook-state-dir.cjs').hookStateDir();
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(path.join(dir, 'hook-log.jsonl'),
+      JSON.stringify({ ts: new Date().toISOString(), hook: 'session', status: 'crash', error: error.message }) + '\n');
+  } catch (_) {}
+}
+
 try {
   const fs   = require('fs');
   const path = require('path');
   const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
   const os   = require('os');
+  const { projectRoot } = require('./lib/project-root.cjs');
+  const { checkCafeKitUpdate } = require('./lib/update-check.cjs');
+  const { clearSessionReservation } = require('./lib/rules-reservation.cjs');
   const { execSync } = require('child_process');
 
   // ── Utilities ─────────────────────────────────────────────────────────────
@@ -41,21 +54,6 @@ try {
     } catch { /* fail-open */ }
   }
 
-  function projectRoot() {
-    const configured = typeof process.env.CLAUDE_PROJECT_DIR === 'string'
-      ? process.env.CLAUDE_PROJECT_DIR.trim()
-      : '';
-    if (configured) {
-      try { return fs.realpathSync(path.resolve(configured)); } catch { /* continue */ }
-    }
-
-    const installedRoot = path.resolve(__dirname, '..', '..');
-    const installedHook = runtimePath(installedRoot, 'hooks', path.basename(__filename));
-    if (fs.existsSync(installedHook)) return installedRoot;
-
-    try { return fs.realpathSync(process.cwd()); } catch { return path.resolve(process.cwd()); }
-  }
-
   /** Read <runtime>/runtime.json config */
   function readRuntime(cwd) {
     try {
@@ -104,94 +102,6 @@ try {
     return '';
   }
 
-  // ── CafeKit Update Check ──────────────────────────────────────────────────
-
-  /**
-   * Fetch the latest published version of @haposoft/cafekit from the npm registry.
-   * Returns a string (e.g. "0.11.2") or null on any failure. Timeout: 3 s.
-   */
-  function fetchLatestVersion() {
-    try {
-      const https = require('https');
-      return new Promise((resolve) => {
-        const req = https.get(
-          'https://registry.npmjs.org/@haposoft/cafekit/latest',
-          { timeout: 3000, headers: { Accept: 'application/json' } },
-          (res) => {
-            let body = '';
-            res.on('data', (chunk) => { body += chunk; });
-            res.on('end', () => {
-              try { resolve(JSON.parse(body).version || null); }
-              catch { resolve(null); }
-            });
-          }
-        );
-        req.on('error', () => resolve(null));
-        req.on('timeout', () => { req.destroy(); resolve(null); });
-      });
-    } catch { return Promise.resolve(null); }
-  }
-
-  /** Simple semver compare: returns true when b > a. */
-  function isNewer(a, b) {
-    const n = (v) => String(v).split('.').map((x) => parseInt(x, 10) || 0);
-    const [aN, bN] = [n(a), n(b)];
-    for (let i = 0; i < 3; i++) {
-      if (bN[i] > aN[i]) return true;
-      if (bN[i] < aN[i]) return false;
-    }
-    return false;
-  }
-
-  /**
-   * Read the installed CafeKit version from <runtime>/cafekit.json.
-   * Returns null if not found.
-   */
-  function getInstalledVersion(cwd) {
-    try {
-      const p = runtimePath(cwd, 'cafekit.json');
-      if (!fs.existsSync(p)) return null;
-      const meta = JSON.parse(fs.readFileSync(p, 'utf8'));
-      return typeof meta.version === 'string' ? meta.version : null;
-    } catch { return null; }
-  }
-
-  /**
-   * Check for a newer CafeKit version and return an update notice string,
-   * or an empty string if already up to date or check fails.
-   * Result is cached in <runtime>/.cafekit-update-cache.json for 12 hours.
-   */
-  async function checkCafeKitUpdate(cwd) {
-    const installed = getInstalledVersion(cwd);
-    if (!installed) return '';
-
-    const CACHE_TTL = 12 * 60 * 60 * 1000; // 12 hours
-    const cachePath = runtimePath(cwd, '.cafekit-update-cache.json');
-
-    // Return cached result if still fresh.
-    try {
-      if (fs.existsSync(cachePath)) {
-        const cache = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
-        if (Date.now() - (cache.ts || 0) < CACHE_TTL) {
-          return cache.notice || '';
-        }
-      }
-    } catch { /* stale or corrupt — refetch */ }
-
-    // Fetch from npm registry.
-    const latest = await fetchLatestVersion();
-    const notice = (latest && isNewer(installed, latest))
-      ? `\n⚡ CafeKit update available: ${installed} → ${latest}\n   Run: npx @haposoft/cafekit\n`
-      : '';
-
-    // Persist cache (fail-open if write fails).
-    try {
-      fs.writeFileSync(cachePath, JSON.stringify({ ts: Date.now(), notice }), 'utf8');
-    } catch { /* fail-open */ }
-
-    return notice;
-  }
-
   // ── Main ──────────────────────────────────────────────────────────────────
 
   (async () => {
@@ -199,12 +109,13 @@ try {
   const { normalizeHookPayload } = require('./lib/hook-payload.cjs');
   const payload = stdin ? normalizeHookPayload(JSON.parse(stdin)) : {};
   const source  = payload.source || 'unknown';
+  if (source === 'compact') clearSessionReservation(payload.session_id);
   const envFile = process.env.CLAUDE_ENV_FILE;
-  const cwd     = projectRoot();
+  const cwd     = projectRoot(payload);
   const runtime = readRuntime(cwd);
 
   // Check CafeKit update in parallel with project detection (async, fail-open).
-  const updateCheckPromise = checkCafeKitUpdate(cwd);
+  const updateCheckPromise = checkCafeKitUpdate(runtimeDir(cwd)).catch(() => '');
 
   // Project detection
   const projectType = runtime.project?.type !== 'auto'
@@ -221,7 +132,6 @@ try {
 
   // Static environment
   const gitBranch  = run('git branch --show-current', '', cwd);
-  const gitUrl     = run('git remote get-url origin', '', cwd);
   const gitRoot    = run('git rev-parse --show-toplevel', '', cwd);
   const nodeVer    = process.version;
   const pythonVer  = run('python3 --version', '', cwd) || run('python --version', '', cwd);
@@ -235,7 +145,6 @@ try {
     writeEnv(envFile, 'PACKAGE_MANAGER', packageManager);
     writeEnv(envFile, 'FRAMEWORK',       framework);
     writeEnv(envFile, 'GIT_BRANCH',      gitBranch);
-    writeEnv(envFile, 'GIT_URL',         gitUrl);
     writeEnv(envFile, 'GIT_ROOT',        gitRoot);
     writeEnv(envFile, 'NODE_VERSION',    nodeVer);
     writeEnv(envFile, 'PYTHON_VERSION',  pythonVer);
@@ -262,6 +171,14 @@ try {
 
   console.log(`Session ${source}. ${parts.length ? parts.join(' | ') : 'No project info detected.'}${updateNotice}`);
 
+  if (typeof payload.cwd === 'string' && payload.cwd) {
+    let sessionCwd = path.resolve(payload.cwd);
+    try { sessionCwd = fs.realpathSync(sessionCwd); } catch { /* lexical fallback */ }
+    if (sessionCwd !== cwd) {
+      console.log(`CafeKit project root: ${cwd} (session working directory: ${sessionCwd}).`);
+    }
+  }
+
   // Compact warning — context compaction can lose pending approval state
   if (source === 'compact') {
     console.log('\n🚨 SESSION COMPRESSED — VERIFY PENDING AUTHORIZATIONS:');
@@ -274,8 +191,11 @@ try {
     // bearings, and nothing more.
     try {
       const fs2 = require('fs'), p2 = require('path');
-      const file = p2.join(require('./lib/hook-state-dir.cjs').hookStateDir(), 'compact-recovery.json');
+      if (typeof payload.session_id !== 'string' || !payload.session_id.trim()) process.exit(0);
+      const key = require('crypto').createHash('sha256').update(payload.session_id).digest('hex');
+      const file = p2.join(require('./lib/hook-state-dir.cjs').hookStateDir(), `compact-recovery-${key}.json`);
       const record = JSON.parse(fs2.readFileSync(file, 'utf8'));
+      if (record.session_id !== payload.session_id) process.exit(0);
       const parts = [];
       if (record.branch) parts.push(`branch ${record.branch}`);
       if (record.head) parts.push(`HEAD ${record.head}`);
@@ -297,15 +217,12 @@ try {
   }
 
   process.exit(0);
-  })(); // end async IIFE
+  })().catch((error) => {
+    logCrash(error);
+    process.exit(0);
+  });
 
-} catch (e) {
-  try {
-    const fs = require('fs'), p = require('path');
-    const d = require('./lib/hook-state-dir.cjs').hookStateDir();
-    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
-    fs.appendFileSync(p.join(d, 'hook-log.jsonl'),
-      JSON.stringify({ ts: new Date().toISOString(), hook: 'session', status: 'crash', error: e.message }) + '\n');
-  } catch (_) {}
+} catch (error) {
+  logCrash(error);
   process.exit(0);
 }

package/src/claude/hooks/spec-gate.cjs

@@ -16,32 +16,7 @@
 const fs = require('fs');
 const path = require('path');
 const { runtimeDirName, runtimeDir, runtimePath } = require('./lib/runtime-dir.cjs');
-
-function projectRoot(payload = {}) {
-  const configured = typeof process.env.CLAUDE_PROJECT_DIR === 'string'
-    ? process.env.CLAUDE_PROJECT_DIR.trim()
-    : '';
-  if (configured) {
-    try { return fs.realpathSync(path.resolve(configured)); } catch { /* continue */ }
-  }
-
-  const installedRoot = path.resolve(__dirname, '..', '..');
-  const installedHook = runtimePath(installedRoot, 'hooks', path.basename(__filename));
-  if (fs.existsSync(installedHook)) return installedRoot;
-
-  const sourceFixture = typeof process.env.PROJECT_ROOT === 'string'
-    ? process.env.PROJECT_ROOT.trim()
-    : '';
-  if (sourceFixture) {
-    try { return fs.realpathSync(path.resolve(sourceFixture)); } catch { /* continue */ }
-  }
-
-  const legacy = typeof payload.cwd === 'string' ? payload.cwd.trim() : '';
-  if (legacy) {
-    try { return fs.realpathSync(path.resolve(legacy)); } catch { /* continue */ }
-  }
-  try { return fs.realpathSync(process.cwd()); } catch { return path.resolve(process.cwd()); }
-}
+const { projectRoot } = require('./lib/project-root.cjs');
 
 function logCrash(error) {
   try {
@@ -68,6 +43,7 @@ function sessionIdentity(payload) {
   return candidates.find((value) => typeof value === 'string' && value.trim() !== '') || null;
 }
 
+let hasDoneTasks = false;
 try {
   const policyPath = path.join(__dirname, '..', 'scripts', 'workflow-policy.cjs');
 
@@ -132,6 +108,8 @@ try {
   }
   if (!resolved) process.exit(0);
   if (resolved.layoutKind === 'process-v3-completed-set') {
+    hasDoneTasks = resolved.candidates.some(candidate =>
+      Object.values(candidate.taskRegistry || {}).some(task => task?.status === 'done'));
     const configuredGate = runtime.spec?.completion_gate;
     if (configuredGate !== undefined && configuredGate !== true) {
       emitBlock('Completion gate: runtime.spec.completion_gate is a worker-writable flag, not an authorization; no completion-gate bypass is supported. Remove the flag and satisfy the gate.');
@@ -178,6 +156,7 @@ try {
 
   const featureName = resolved.featureName;
   const specsPath = resolved.specsDir;
+  hasDoneTasks = Object.values(resolved.taskRegistry || {}).some(task => task?.status === 'done');
   const runtimeContext = POLICY.deriveRuntimeContext({
     projectRoot: baseDir,
     specsRoot: specsPath,
@@ -250,6 +229,10 @@ try {
   process.exit(0);
 
 } catch (e) {
+  if (e.code === 'no_git_history') {
+    if (hasDoneTasks) emitBlock('Completion gate: repo has no commits yet; create the first commit, then record Base/Head after it.');
+    process.exit(0);
+  }
   logCrash(e);
   emitBlock(`Completion gate controlled failure: ${e.message}. Completion is blocked until the hook is repaired.`);
   process.exit(0);