metame-cli 1.5.8 → 1.5.10

package/scripts/daemon-task-scheduler.js

@@ -180,7 +180,6 @@ function createTaskScheduler(deps) {
     CLAUDE_BIN,
     spawn: _spawn,
     execSync,
-    execFileSync,
     parseInterval,
     loadState,
     saveState,
@@ -201,6 +200,60 @@ function createTaskScheduler(deps) {
 
   // Max characters from precondition context to inject into prompts (prevents token bombs)
   const MAX_PRECONDITION_CHARS = 4000;
+  // Cap stdout buffer to prevent memory growth in long-running tasks (output_preview uses 200 chars anyway)
+  const MAX_STDOUT_BYTES = 1024 * 1024;
+
+  // Shared primitive: spawn a single claude -p invocation with silence watchdog.
+  // Resolves to { ok, output, error } — never rejects.
+  // label is used only for log messages (e.g. "Task foo" or "Workflow bar step 2").
+  function spawnClaude(args, prompt, timeoutMs, cwdPath, label) {
+    const env = { ...process.env, ...getDaemonProviderEnv(), CLAUDECODE: undefined, METAME_INTERNAL_PROMPT: '1' };
+    return new Promise((resolve) => {
+      const child = spawn(CLAUDE_BIN, args, {
+        cwd: cwdPath || undefined,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        detached: process.platform !== 'win32',
+        env,
+      });
+
+      let stdout = '';
+      let stderr = '';
+      let timedOut = false;
+      let lastActivity = Date.now();
+      let sigkillTimer = null;
+
+      const watchdog = setInterval(() => {
+        if (Date.now() - lastActivity >= timeoutMs) {
+          clearInterval(watchdog);
+          timedOut = true;
+          log('WARN', `${label} silent for ${timeoutMs / 1000}s — killing`);
+          try { process.kill(-child.pid, 'SIGTERM'); } catch { child.kill('SIGTERM'); }
+          sigkillTimer = setTimeout(() => {
+            try { process.kill(-child.pid, 'SIGKILL'); } catch { try { child.kill('SIGKILL'); } catch { } }
+          }, 5000);
+        }
+      }, Math.min(timeoutMs, 30000));
+
+      child.stdin.write(prompt);
+      child.stdin.end();
+      child.stdout.on('data', (d) => { lastActivity = Date.now(); if (stdout.length < MAX_STDOUT_BYTES) stdout += d.toString(); });
+      child.stderr.on('data', (d) => { lastActivity = Date.now(); stderr += d.toString(); });
+
+      child.on('close', (code) => {
+        clearInterval(watchdog);
+        if (sigkillTimer) clearTimeout(sigkillTimer);
+        const output = stdout.trim();
+        if (timedOut) return resolve({ ok: false, error: 'silent_timeout', output });
+        if (code !== 0) return resolve({ ok: false, error: (stderr || `Exit code ${code}`).slice(0, 200), output: '' });
+        resolve({ ok: true, output, stderr });
+      });
+
+      child.on('error', (err) => {
+        clearInterval(watchdog);
+        resolve({ ok: false, error: err.message, output: '' });
+      });
+    });
+  }
 
   // On Windows, resolve .cmd → actual Node.js entry to avoid cmd.exe flash
   function _resolveNodeEntry(cmdPath) {
@@ -476,110 +529,46 @@ function createTaskScheduler(deps) {
       log('INFO', `Executing task: ${task.name} (model: ${model}${mcpConfig ? ', mcp: ' + path.basename(mcpConfig) : ''})`);
     }
 
-    // Use spawnClaudeAsync (non-blocking spawn with process-group kill) instead of
-    // execFileSync (sync, blocks event loop, can't kill sub-agents).
-    // executeTask now returns a Promise — callers must handle it with .then() or await.
-    const timeoutMs = resolveTimeoutMs(task.timeout, 120);
-    const asyncArgs = [...claudeArgs];
-    const asyncEnv = {
-      ...process.env,
-      ...getDaemonProviderEnv(),
-      CLAUDECODE: undefined,
-      METAME_INTERNAL_PROMPT: '1',
-    };
-
-    return new Promise((resolve) => {
-      const child = spawn(CLAUDE_BIN, asyncArgs, {
-        cwd: cwd || undefined,
-        stdio: ['pipe', 'pipe', 'pipe'],
-        detached: process.platform !== 'win32', // process groups are POSIX-only
-        env: asyncEnv,
-      });
+    const timeoutMs = resolveTimeoutMs(task.timeout, 1800);
+    return spawnClaude(claudeArgs, fullPrompt, timeoutMs, cwd, `Task ${task.name}`).then((result) => {
+      const { output } = result;
+      const prevSid = state.tasks[task.name]?.session_id;
+      const prevCreatedAt = state.tasks[task.name]?.session_created_at;
+      const sessionFields = { ...(prevSid && { session_id: prevSid }), ...(prevCreatedAt && { session_created_at: prevCreatedAt }) };
 
-      let stdout = '';
-      let stderr = '';
-      let timedOut = false;
-
-      const timer = setTimeout(() => {
-        timedOut = true;
-        log('WARN', `Task ${task.name} timeout (${timeoutMs / 1000}s) — killing process group`);
-        try { process.kill(-child.pid, 'SIGTERM'); } catch { child.kill('SIGTERM'); }
-        setTimeout(() => {
-          try { process.kill(-child.pid, 'SIGKILL'); } catch { try { child.kill('SIGKILL'); } catch { } }
-        }, 5000);
-      }, timeoutMs);
-
-      child.stdin.write(fullPrompt);
-      child.stdin.end();
-      child.stdout.on('data', (d) => { stdout += d.toString(); });
-      child.stderr.on('data', (d) => { stderr += d.toString(); });
-
-      child.on('close', (code) => {
-        clearTimeout(timer);
-        const output = stdout.trim();
-        if (timedOut) {
-          const prevSid = state.tasks[task.name]?.session_id;
-          const prevCreatedAt = state.tasks[task.name]?.session_created_at;
-          state.tasks[task.name] = {
-            last_run: new Date().toISOString(),
-            status: 'timeout',
-            error: 'Task exceeded timeout',
-            ...(prevSid && { session_id: prevSid }),
-            ...(prevCreatedAt && { session_created_at: prevCreatedAt }),
-          };
+      if (!result.ok) {
+        if (result.error === 'silent_timeout') {
+          state.tasks[task.name] = { last_run: new Date().toISOString(), status: 'error', error: `Task silent for ${timeoutMs / 1000}s`, ...sessionFields };
           saveState(state);
-          return resolve({ success: false, error: 'timeout', output: '' });
+          return { success: false, error: 'silent_timeout', output: output || '' };
         }
-        if (code !== 0) {
-          const errMsg = (stderr || `Exit code ${code}`).slice(0, 200);
-          // Persistent session expired: reset so next run creates a new one
-          if (task.persistent_session && (errMsg.includes('not found') || errMsg.includes('No session'))) {
-            log('WARN', `Persistent session for ${task.name} expired, will create new on next run`);
-            state.tasks[task.name] = { last_run: new Date().toISOString(), status: 'session_reset', error: 'Session expired' };
-            saveState(state);
-            return resolve({ success: false, error: 'session_expired', output: '' });
-          }
-          log('ERROR', `Task ${task.name} failed (exit ${code}): ${errMsg}`);
-          const prevSid = state.tasks[task.name]?.session_id;
-          const prevCreatedAt = state.tasks[task.name]?.session_created_at;
-          state.tasks[task.name] = {
-            last_run: new Date().toISOString(),
-            status: 'error',
-            error: errMsg,
-            ...(prevSid && { session_id: prevSid }),
-            ...(prevCreatedAt && { session_created_at: prevCreatedAt }),
-          };
+        const errMsg = result.error;
+        // Persistent session expired: reset so next run creates a new one
+        if (task.persistent_session && (errMsg.includes('not found') || errMsg.includes('No session'))) {
+          log('WARN', `Persistent session for ${task.name} expired, will create new on next run`);
+          state.tasks[task.name] = { last_run: new Date().toISOString(), status: 'session_reset', error: 'Session expired' };
           saveState(state);
-          return resolve({ success: false, error: errMsg, output: '' });
+          return { success: false, error: 'session_expired', output: '' };
         }
-        const estimatedTokens = Math.ceil((fullPrompt.length + output.length) / 4);
-        recordTokens(state, estimatedTokens, { category: classifyTaskUsage(task) });
-        const prevSessionId = state.tasks[task.name]?.session_id;
-        const prevCreatedAt = state.tasks[task.name]?.session_created_at;
-        state.tasks[task.name] = {
-          last_run: new Date().toISOString(),
-          status: 'success',
-          output_preview: output.slice(0, 200),
-          ...(prevSessionId && { session_id: prevSessionId }),
-          ...(prevCreatedAt && { session_created_at: prevCreatedAt }),
-        };
+        log('ERROR', `Task ${task.name} failed: ${errMsg}`);
+        state.tasks[task.name] = { last_run: new Date().toISOString(), status: 'error', error: errMsg, ...sessionFields };
         saveState(state);
-        maybeSaveTaskMemory(task, output, estimatedTokens, prevSessionId || '');
-        log('INFO', `Task ${task.name} completed (est. ${estimatedTokens} tokens)`);
-        resolve({ success: true, output, tokens: estimatedTokens });
-      });
+        return { success: false, error: errMsg, output: '' };
+      }
 
-      child.on('error', (err) => {
-        clearTimeout(timer);
-        log('ERROR', `Task ${task.name} spawn error: ${err.message}`);
-        resolve({ success: false, error: err.message, output: '' });
-      });
+      const estimatedTokens = Math.ceil((fullPrompt.length + output.length) / 4);
+      recordTokens(state, estimatedTokens, { category: classifyTaskUsage(task) });
+      state.tasks[task.name] = { last_run: new Date().toISOString(), status: 'success', output_preview: output.slice(0, 200), ...sessionFields };
+      saveState(state);
+      maybeSaveTaskMemory(task, output, estimatedTokens, prevSid || '');
+      log('INFO', `Task ${task.name} completed (est. ${estimatedTokens} tokens)`);
+      return { success: true, output, tokens: estimatedTokens };
     });
   }
 
   // parseInterval — imported from ./utils
 
-  function executeWorkflow(task, config, precheck) {
+  async function executeWorkflow(task, config, precheck) {
     const state = loadState();
     if (!checkBudget(config, state)) {
       log('WARN', `Budget exceeded, skipping workflow: ${task.name}`);
@@ -622,30 +611,19 @@ function createTaskScheduler(deps) {
       args.push(i === 0 ? '--session-id' : '--resume', sessionId);
 
       log('INFO', `Workflow ${task.name} step ${i + 1}/${steps.length}: ${step.skill || 'prompt'}`);
-      try {
-        const output = execFileSync(CLAUDE_BIN, args, {
-          input: prompt,
-          encoding: 'utf8',
-          timeout: resolveTimeoutMs(step.timeout, 300),
-          maxBuffer: 5 * 1024 * 1024,
-          cwd,
-          ...(process.platform === 'win32' ? { windowsHide: true } : {}),
-          env: {
-            ...process.env,
-            ...getDaemonProviderEnv(),
-            CLAUDECODE: undefined,
-            METAME_INTERNAL_PROMPT: '1',
-          },
-          ...(process.platform === 'win32' ? { shell: process.env.COMSPEC || true, windowsHide: true } : {}),
-        }).trim();
+      // Steps share a session and must run sequentially
+      const stepResult = await spawnClaude(args, prompt, resolveTimeoutMs(step.timeout, 1800), cwd, `Workflow ${task.name} step ${i + 1}`);
+      if (stepResult.ok) {
+        const output = stepResult.output;
         const tk = Math.ceil((prompt.length + output.length) / 4);
         totalTokens += tk;
         outputs.push({ step: i + 1, skill: step.skill || null, output: output.slice(0, 500), tokens: tk });
         log('INFO', `Workflow ${task.name} step ${i + 1} done (${tk} tokens)`);
         if (!checkBudget(config, loopState)) { log('WARN', 'Budget exceeded mid-workflow'); break; }
-      } catch (e) {
-        log('ERROR', `Workflow ${task.name} step ${i + 1} failed: ${e.message.slice(0, 200)}`);
-        outputs.push({ step: i + 1, skill: step.skill || null, error: e.message.slice(0, 200) });
+      } else {
+        const errMsg = stepResult.error.slice(0, 200);
+        log('ERROR', `Workflow ${task.name} step ${i + 1} failed: ${errMsg}`);
+        outputs.push({ step: i + 1, skill: step.skill || null, error: errMsg });
         if (!step.optional) {
           recordTokens(loopState, totalTokens, { category: classifyTaskUsage(task) });
           state.tasks[task.name] = { last_run: new Date().toISOString(), status: 'error', error: `Step ${i + 1} failed`, steps_completed: i, steps_total: steps.length };

package/scripts/daemon-utils.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * daemon-utils.js
+ *
+ * Shared normalization helpers used across daemon modules.
+ * Single source of truth — no other module should redefine these.
+ */
+
+function normalizeEngineName(name, defaultEngine = 'claude') {
+  const n = String(name || '').trim().toLowerCase();
+  return n === 'codex' ? 'codex' : (typeof defaultEngine === 'function' ? defaultEngine() : defaultEngine);
+}
+
+function normalizeCodexSandboxMode(value, fallback = null) {
+  const text = String(value || '').trim().toLowerCase();
+  if (!text) return fallback;
+  if (text === 'read-only' || text === 'readonly') return 'read-only';
+  if (text === 'workspace-write' || text === 'workspace') return 'workspace-write';
+  if (
+    text === 'danger-full-access'
+    || text === 'dangerous'
+    || text === 'full-access'
+    || text === 'full'
+    || text === 'bypass'
+    || text === 'writable'
+  ) return 'danger-full-access';
+  return fallback;
+}
+
+function normalizeCodexApprovalPolicy(value, fallback = null) {
+  const text = String(value || '').trim().toLowerCase();
+  if (!text) return fallback;
+  if (text === 'never' || text === 'no' || text === 'none') return 'never';
+  if (text === 'on-failure' || text === 'on_failure' || text === 'failure') return 'on-failure';
+  if (text === 'on-request' || text === 'on_request' || text === 'request') return 'on-request';
+  if (text === 'untrusted') return 'untrusted';
+  return fallback;
+}
+
+function mergeAgentMaps(cfg) {
+  return {
+    ...(cfg.telegram ? cfg.telegram.chat_agent_map : {}),
+    ...(cfg.feishu ? cfg.feishu.chat_agent_map : {}),
+    ...(cfg.imessage ? cfg.imessage.chat_agent_map : {}),
+    ...(cfg.siri_bridge ? cfg.siri_bridge.chat_agent_map : {}),
+  };
+}
+
+module.exports = {
+  normalizeEngineName,
+  normalizeCodexSandboxMode,
+  normalizeCodexApprovalPolicy,
+  mergeAgentMaps,
+};

package/scripts/daemon-warm-pool.js

@@ -0,0 +1,162 @@
+'use strict';
+
+/**
+ * daemon-warm-pool.js
+ *
+ * Persistent Claude CLI process pool for eliminating cold-start latency.
+ *
+ * Problem: Each `claude -p --print` spawns a new process → ~11s cold start (CLI init + API first-token).
+ * Solution: After a turn completes, keep the process alive. Next message writes to stdin → ~3s response.
+ *
+ * Architecture:
+ *   - Pool keyed by sessionChatId (not raw chatId — same session key used by daemon-session-store)
+ *   - Each warm entry holds a live child process spawned with `--input-format stream-json`
+ *   - `acquireWarm(key)` → returns child process (removes from pool to prevent double-use)
+ *   - `storeWarm(key, child, meta)` → parks process in pool with idle timeout
+ *   - Idle timeout kills unused warm processes (default: 5 minutes)
+ *   - Process death auto-cleans pool entry
+ *
+ * Only for Claude engine. Codex does not support `--input-format stream-json`.
+ */
+
+function createWarmPool(deps) {
+  const { log } = deps;
+
+  // Pool: sessionKey -> { child, sessionId, cwd, idleTimer }
+  const pool = new Map();
+  const IDLE_TIMEOUT_MS = 5 * 60 * 1000;
+
+  /**
+   * Acquire a warm process for the given session key.
+   * Returns { child, sessionId, cwd } or null.
+   * The entry is REMOVED from the pool (caller owns the process now).
+   */
+  function acquireWarm(sessionKey) {
+    const entry = pool.get(sessionKey);
+    if (!entry) return null;
+
+    // Check if process is still alive
+    if (entry.child.killed || entry.child.exitCode !== null) {
+      _cleanup(sessionKey);
+      return null;
+    }
+
+    // Remove from pool — caller now owns this process
+    if (entry.idleTimer) clearTimeout(entry.idleTimer);
+    pool.delete(sessionKey);
+    log('INFO', `[WarmPool] Acquired warm process pid=${entry.child.pid} for ${sessionKey}`);
+    return { child: entry.child, sessionId: entry.sessionId, cwd: entry.cwd };
+  }
+
+  /**
+   * Park a process in the pool for future reuse.
+   * The process must have been spawned with --input-format stream-json.
+   * Previous entry for the same key is killed.
+   */
+  function storeWarm(sessionKey, child, meta = {}) {
+    // Kill existing warm process for this key (if any)
+    const existing = pool.get(sessionKey);
+    if (existing) {
+      _killEntry(existing);
+      pool.delete(sessionKey);
+    }
+
+    // Don't store dead processes
+    if (child.killed || child.exitCode !== null) {
+      log('INFO', `[WarmPool] Not storing dead process for ${sessionKey}`);
+      return;
+    }
+
+    // Set idle timeout
+    const idleTimer = setTimeout(() => {
+      const e = pool.get(sessionKey);
+      if (e && e.child === child) {
+        log('INFO', `[WarmPool] Idle timeout, killing warm process pid=${child.pid} for ${sessionKey}`);
+        _killEntry(e);
+        pool.delete(sessionKey);
+      }
+    }, IDLE_TIMEOUT_MS);
+    if (typeof idleTimer.unref === 'function') idleTimer.unref();
+
+    // Auto-cleanup on unexpected death
+    const onExit = () => {
+      const e = pool.get(sessionKey);
+      if (e && e.child === child) {
+        if (e.idleTimer) clearTimeout(e.idleTimer);
+        pool.delete(sessionKey);
+        log('INFO', `[WarmPool] Process died unexpectedly for ${sessionKey}`);
+      }
+    };
+    child.once('close', onExit);
+    child.once('error', onExit);
+
+    pool.set(sessionKey, {
+      child,
+      sessionId: meta.sessionId || '',
+      cwd: meta.cwd || '',
+      idleTimer,
+    });
+    log('INFO', `[WarmPool] Stored warm process pid=${child.pid} for ${sessionKey} (pool size: ${pool.size})`);
+  }
+
+  /**
+   * Kill and remove a specific warm process.
+   */
+  function releaseWarm(sessionKey) {
+    const entry = pool.get(sessionKey);
+    if (!entry) return;
+    _killEntry(entry);
+    pool.delete(sessionKey);
+    log('INFO', `[WarmPool] Released ${sessionKey}`);
+  }
+
+  /**
+   * Kill all warm processes (used during daemon shutdown).
+   */
+  function releaseAll() {
+    for (const [_key, entry] of pool) {
+      _killEntry(entry);
+    }
+    const count = pool.size;
+    pool.clear();
+    if (count > 0) log('INFO', `[WarmPool] Released all (${count} processes)`);
+  }
+
+  function _killEntry(entry) {
+    if (entry.idleTimer) clearTimeout(entry.idleTimer);
+    try {
+      process.kill(-entry.child.pid, 'SIGTERM');
+    } catch {
+      try { entry.child.kill('SIGTERM'); } catch { /* */ }
+    }
+  }
+
+  function _cleanup(sessionKey) {
+    const entry = pool.get(sessionKey);
+    if (entry && entry.idleTimer) clearTimeout(entry.idleTimer);
+    pool.delete(sessionKey);
+  }
+
+  /**
+   * Build the stream-json user message for stdin.
+   */
+  function buildStreamMessage(prompt, sessionId) {
+    return JSON.stringify({
+      type: 'user',
+      message: { role: 'user', content: prompt },
+      session_id: sessionId || 'default',
+      parent_tool_use_id: null,
+    }) + '\n';
+  }
+
+  return {
+    acquireWarm,
+    storeWarm,
+    releaseWarm,
+    releaseAll,
+    buildStreamMessage,
+    _pool: pool,
+  };
+}
+
+module.exports = { createWarmPool };

package/scripts/daemon-worktrees.js

@@ -0,0 +1,129 @@
+'use strict';
+
+/**
+ * daemon-worktrees.js — Isolated worktree per actor
+ *
+ * Every entity that runs Claude (real chatId, virtual _agent_*, _scope_*, _bound_*)
+ * gets its own git worktree branching from the project repo.
+ * This eliminates cross-contamination of checkpoints and working-tree state
+ * between parallel agents — with a single, unified code path.
+ *
+ * Directory layout:
+ *   ~/.metame/worktrees/<proj-basename>/<actor-key>/
+ *
+ * Branch convention:
+ *   agent/<actor-key>   (created from parent HEAD if new)
+ */
+
+function createWorktreeUtils(deps) {
+  const { fs, path, log, HOME } = deps;
+  const { execFileSync } = require('child_process');
+
+  const WIN_HIDE = process.platform === 'win32' ? { windowsHide: true } : {};
+  const WORKTREES_BASE = path.join(HOME, '.metame', 'worktrees');
+
+  /**
+   * Derive a stable, filesystem-safe actor key from chatId.
+   * This is the ONLY place in the codebase that distinguishes virtual vs real.
+   */
+  function resolveWorktreeKey(chatId) {
+    const s = String(chatId || '');
+    if (s.startsWith('_agent_'))  return s.slice(7);
+    if (s.startsWith('_scope_'))  return s.slice(7).split('__')[0];
+    if (s.startsWith('_bound_'))  return `bound_${s.slice(7)}`;
+    return `chat_${s.replace(/[^a-zA-Z0-9_\-]/g, '_')}`;
+  }
+
+  function _sanitizeKey(key) {
+    return String(key).replace(/[^a-zA-Z0-9_\-]/g, '_').slice(0, 60);
+  }
+
+  /** Walk up directories to find the git root containing .git */
+  function _findGitRoot(dir) {
+    let cur = path.resolve(dir);
+    const root = path.parse(cur).root;
+    while (cur !== root) {
+      if (fs.existsSync(path.join(cur, '.git'))) return cur;
+      cur = path.dirname(cur);
+    }
+    return null;
+  }
+
+  /**
+   * Get or create an isolated worktree for the given actor.
+   *
+   * @param {string} parentCwd  - Project's main working directory (git repo root or subdir)
+   * @param {string} worktreeKey - Actor identifier (from resolveWorktreeKey or member.key)
+   * @returns {string|null} Path to the worktree, or null on unrecoverable failure
+   */
+  function getOrCreateWorktree(parentCwd, worktreeKey) {
+    if (!parentCwd || !worktreeKey) return null;
+    const safeKey = _sanitizeKey(worktreeKey);
+    if (!safeKey) return null;
+
+    const projBasename = path.basename(path.resolve(parentCwd));
+    const worktreePath = path.join(WORKTREES_BASE, projBasename, safeKey);
+
+    // Fast path: already exists (worktree or legacy plain repo)
+    if (fs.existsSync(worktreePath)) {
+      return worktreePath;
+    }
+
+    const gitRoot = _findGitRoot(parentCwd);
+
+    // Ensure parent directory for the worktree
+    try {
+      fs.mkdirSync(path.join(WORKTREES_BASE, projBasename), { recursive: true });
+    } catch (e) {
+      log('WARN', `[worktrees] mkdir failed: ${e.message}`);
+      return null;
+    }
+
+    if (!gitRoot) {
+      // Not a git repo — plain mkdir + git init (fallback)
+      try {
+        fs.mkdirSync(worktreePath, { recursive: true });
+        execFileSync('git', ['init', '-q'], { cwd: worktreePath, stdio: 'ignore', timeout: 5000, ...WIN_HIDE });
+        log('INFO', `[worktrees] plain dir (no parent git): ${worktreePath}`);
+      } catch (e) {
+        log('WARN', `[worktrees] fallback git init failed: ${e.message}`);
+      }
+      return fs.existsSync(worktreePath) ? worktreePath : null;
+    }
+
+    // Git repo — create a proper linked worktree
+    const branchName = `agent/${safeKey}`;
+    try {
+      // Does the branch already exist? (e.g. worktree was removed but branch remains)
+      let branchExists = false;
+      try {
+        execFileSync('git', ['rev-parse', '--verify', branchName],
+          { cwd: gitRoot, stdio: 'ignore', timeout: 3000, ...WIN_HIDE });
+        branchExists = true;
+      } catch { /* branch is new */ }
+
+      const addArgs = branchExists
+        ? ['worktree', 'add', worktreePath, branchName]
+        : ['worktree', 'add', '-b', branchName, worktreePath];
+
+      execFileSync('git', addArgs,
+        { cwd: gitRoot, stdio: 'ignore', timeout: 15000, ...WIN_HIDE });
+
+      log('INFO', `[worktrees] created: ${worktreePath} → branch ${branchName}`);
+    } catch (e) {
+      log('WARN', `[worktrees] git worktree add failed (${e.message}); falling back to plain dir`);
+      try {
+        if (!fs.existsSync(worktreePath)) {
+          fs.mkdirSync(worktreePath, { recursive: true });
+          execFileSync('git', ['init', '-q'], { cwd: worktreePath, stdio: 'ignore', timeout: 5000, ...WIN_HIDE });
+        }
+      } catch { /* best-effort */ }
+    }
+
+    return fs.existsSync(worktreePath) ? worktreePath : null;
+  }
+
+  return { resolveWorktreeKey, getOrCreateWorktree };
+}
+
+module.exports = { createWorktreeUtils };