@teamvibe/poller 0.4.2 → 0.4.3

package/dist/base-brain-metadata.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Read the current HEAD commit SHA of a git repo. Returns null on any error
+ * (not a git repo, git missing, dir missing, etc.) so callers can attach a
+ * best-effort metric without breaking the report flow.
+ */
+export declare function getBaseBrainCommitSha(repoDir: string): Promise<string | null>;
+/**
+ * Age of the base-brain checkout in hours.
+ *
+ * Defined as: now - max(commitDate of HEAD, mtime of .git/FETCH_HEAD).
+ * FETCH_HEAD mtime catches the case where `git pull` runs but the upstream
+ * has nothing new (or the fast-forward silently fails) — commitDate only
+ * advances on a successful integration, FETCH_HEAD on every pull attempt.
+ * Taking the max gives the most defensible "freshness" signal.
+ *
+ * Returns null on any error.
+ */
+export declare function getBaseBrainAgeHours(repoDir: string): Promise<number | null>;

package/dist/base-brain-metadata.js

@@ -0,0 +1,52 @@
+import { stat } from 'fs/promises';
+import { join } from 'path';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
+/**
+ * Read the current HEAD commit SHA of a git repo. Returns null on any error
+ * (not a git repo, git missing, dir missing, etc.) so callers can attach a
+ * best-effort metric without breaking the report flow.
+ */
+export async function getBaseBrainCommitSha(repoDir) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: repoDir });
+        const sha = stdout.trim();
+        return sha || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Age of the base-brain checkout in hours.
+ *
+ * Defined as: now - max(commitDate of HEAD, mtime of .git/FETCH_HEAD).
+ * FETCH_HEAD mtime catches the case where `git pull` runs but the upstream
+ * has nothing new (or the fast-forward silently fails) — commitDate only
+ * advances on a successful integration, FETCH_HEAD on every pull attempt.
+ * Taking the max gives the most defensible "freshness" signal.
+ *
+ * Returns null on any error.
+ */
+export async function getBaseBrainAgeHours(repoDir) {
+    try {
+        const { stdout } = await execFileAsync('git', ['log', '-1', '--format=%cI', 'HEAD'], { cwd: repoDir });
+        const commitDateMs = new Date(stdout.trim()).getTime();
+        if (Number.isNaN(commitDateMs))
+            return null;
+        let fetchHeadMs = 0;
+        try {
+            const s = await stat(join(repoDir, '.git', 'FETCH_HEAD'));
+            fetchHeadMs = s.mtimeMs;
+        }
+        catch {
+            // .git/FETCH_HEAD absent on a never-pulled clone — fall back to commitDate
+        }
+        const freshestMs = Math.max(commitDateMs, fetchHeadMs);
+        return (Date.now() - freshestMs) / 3_600_000;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/claude-spawner.js

@@ -7,6 +7,7 @@ import { logger } from './logger.js';
 import { getBaseBrainPath } from './brain-manager.js';
 import { getPollerId } from './auth-provider.js';
 import { emitError } from './event-queue.js';
+import { createWorktree, removeWorktree, isWorktreeIsolationEnabled } from './worktree-manager.js';
 /**
  * Maps tool names (or prefixes) to human-readable status messages.
  * More specific patterns are checked first.
@@ -527,30 +528,63 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
         });
     });
 }
+/**
+ * Sources whose sessions should run in an isolated git worktree (teamvibe.ai#120).
+ * Foreground Slack messages always run in the main working dir.
+ */
+const ISOLATED_SOURCES = new Set(['cron', 'heartbeat', 'maintenance']);
+function shouldIsolateInWorktree(msg) {
+    return isWorktreeIsolationEnabled() && ISOLATED_SOURCES.has(msg.source);
+}
 export async function spawnClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = true, lastMessageTs, onMessageSent, typingIndicator) {
-    const result = await runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage, lastMessageTs, onMessageSent, typingIndicator);
-    // If --resume failed, retry as a fresh session (session files may have been lost on container restart)
-    let retryResult = result;
-    if (!result.success && sessionId && !isFirstMessage) {
-        sessionLog.info('Resume failed, retrying as fresh session (session files may have been lost)');
-        retryResult = await runClaudeCode(msg, sessionLog, cwd, sessionId, true, lastMessageTs, onMessageSent, typingIndicator);
+    // Worktree isolation: spawned (non-foreground) sessions run in
+    // <brain>/.worktrees/<thread_id>/ so the sync-watchdog's reset --hard on
+    // the main working dir can't trample in-flight writes or pre-push commits.
+    // See teamvibe.ai#120. cwd remains the main brain path on fallback / failure.
+    let effectiveCwd = cwd;
+    let worktreeOwner;
+    if (shouldIsolateInWorktree(msg)) {
+        try {
+            effectiveCwd = await createWorktree(cwd, msg.thread_id);
+            worktreeOwner = { brainPath: cwd, id: msg.thread_id };
+            sessionLog.info(`[Worktree] Spawned session running in ${effectiveCwd}`);
+        }
+        catch (err) {
+            sessionLog.warn(`[Worktree] Failed to create worktree, falling back to main brain dir: ${err instanceof Error ? err.message : err}`);
+        }
     }
-    // If session ID is "already in use" (stale lock file), kill any zombie and retry with fresh ID
-    if (!retryResult.success && sessionId && retryResult.error?.includes('already in use')) {
-        // Kill zombie process for this thread if still alive
-        const killed = killZombieForThread(msg.thread_id);
-        if (killed) {
-            sessionLog.info('Killed zombie process before fresh session retry');
-            // Give the process a moment to fully exit and release lock files
-            await new Promise((resolve) => setTimeout(resolve, 2000));
+    try {
+        const result = await runClaudeCode(msg, sessionLog, effectiveCwd, sessionId, isFirstMessage, lastMessageTs, onMessageSent, typingIndicator);
+        // If --resume failed, retry as a fresh session (session files may have been lost on container restart)
+        let retryResult = result;
+        if (!result.success && sessionId && !isFirstMessage) {
+            sessionLog.info('Resume failed, retrying as fresh session (session files may have been lost)');
+            retryResult = await runClaudeCode(msg, sessionLog, effectiveCwd, sessionId, true, lastMessageTs, onMessageSent, typingIndicator);
+        }
+        // If session ID is "already in use" (stale lock file), kill any zombie and retry with fresh ID
+        if (!retryResult.success && sessionId && retryResult.error?.includes('already in use')) {
+            // Kill zombie process for this thread if still alive
+            const killed = killZombieForThread(msg.thread_id);
+            if (killed) {
+                sessionLog.info('Killed zombie process before fresh session retry');
+                // Give the process a moment to fully exit and release lock files
+                await new Promise((resolve) => setTimeout(resolve, 2000));
+            }
+            sessionLog.info('Session ID already in use (stale lock), retrying with fresh session ID');
+            const { randomUUID } = await import('crypto');
+            const freshId = randomUUID();
+            const freshResult = await runClaudeCode(msg, sessionLog, effectiveCwd, freshId, true, lastMessageTs, onMessageSent, typingIndicator);
+            return { ...freshResult, newSessionId: freshId };
+        }
+        return retryResult;
+    }
+    finally {
+        if (worktreeOwner) {
+            removeWorktree(worktreeOwner.brainPath, worktreeOwner.id).catch((err) => {
+                sessionLog.warn(`[Worktree] Cleanup failed (will be retried by orphan janitor): ${err instanceof Error ? err.message : err}`);
+            });
         }
-        sessionLog.info('Session ID already in use (stale lock), retrying with fresh session ID');
-        const { randomUUID } = await import('crypto');
-        const freshId = randomUUID();
-        const freshResult = await runClaudeCode(msg, sessionLog, cwd, freshId, true, lastMessageTs, onMessageSent, typingIndicator);
-        return { ...freshResult, newSessionId: freshId };
     }
-    return retryResult;
 }
 const activeProcesses = new Map();
 const activeProcessesByThread = new Map();

package/dist/config.d.ts

@@ -28,6 +28,7 @@ declare const configSchema: z.ZodObject<{
     BASE_BRAIN_PATH: z.ZodDefault<z.ZodString>;
     BRAIN_AUTO_UPDATE: z.ZodEffects<z.ZodDefault<z.ZodString>, boolean, string | undefined>;
     BRAIN_UPDATE_COOLDOWN_MS: z.ZodDefault<z.ZodNumber>;
+    POLLER_TZ: z.ZodDefault<z.ZodString>;
     HEARTBEAT_CRON: z.ZodDefault<z.ZodString>;
     MAINTENANCE_CRON: z.ZodDefault<z.ZodString>;
     MAINTENANCE_ENABLED: z.ZodEffects<z.ZodDefault<z.ZodString>, boolean, string | undefined>;
@@ -58,6 +59,7 @@ declare const configSchema: z.ZodObject<{
     BASE_BRAIN_PATH: string;
     BRAIN_AUTO_UPDATE: boolean;
     BRAIN_UPDATE_COOLDOWN_MS: number;
+    POLLER_TZ: string;
     HEARTBEAT_CRON: string;
     MAINTENANCE_CRON: string;
     MAINTENANCE_ENABLED: boolean;
@@ -94,6 +96,7 @@ declare const configSchema: z.ZodObject<{
     BASE_BRAIN_PATH?: string | undefined;
     BRAIN_AUTO_UPDATE?: string | undefined;
     BRAIN_UPDATE_COOLDOWN_MS?: number | undefined;
+    POLLER_TZ?: string | undefined;
     HEARTBEAT_CRON?: string | undefined;
     MAINTENANCE_CRON?: string | undefined;
     MAINTENANCE_ENABLED?: string | undefined;
@@ -127,6 +130,7 @@ export declare const config: {
     BASE_BRAIN_PATH: string;
     BRAIN_AUTO_UPDATE: boolean;
     BRAIN_UPDATE_COOLDOWN_MS: number;
+    POLLER_TZ: string;
     HEARTBEAT_CRON: string;
     MAINTENANCE_CRON: string;
     MAINTENANCE_ENABLED: boolean;

package/dist/config.js

@@ -44,8 +44,13 @@ const configSchema = z.object({
         .transform((v) => v.toLowerCase() === 'true'),
     BRAIN_UPDATE_COOLDOWN_MS: z.coerce.number().default(300000), // 5 minutes
     // Brain heartbeat & maintenance (cron-based)
+    // POLLER_TZ: IANA timezone used to interpret HEARTBEAT_CRON & MAINTENANCE_CRON.
+    // Default Europe/Prague — current fleet is CZ-based; ensures `30 3 * * *`
+    // means "03:30 local night," not "03:30 UTC = 05:30 CEST." DST is handled
+    // by croner automatically. Override with `POLLER_TZ=UTC` (or any IANA name).
+    POLLER_TZ: z.string().default('Europe/Prague'),
     HEARTBEAT_CRON: z.string().default('0 */6 * * *'), // Every 6 hours
-    MAINTENANCE_CRON: z.string().default('30 3 * * *'), // Daily at 03:30 UTC
+    MAINTENANCE_CRON: z.string().default('30 3 * * *'), // Daily at 03:30 in POLLER_TZ
     MAINTENANCE_ENABLED: z.string().default('true').transform((v) => v.toLowerCase() === 'true'),
     // Auto-update settings
     AUTO_UPDATE_POLICY: z.enum(['patch', 'minor', 'off']).default('patch'),

package/dist/heartbeat-manager.js

@@ -114,13 +114,13 @@ export function startHeartbeatLoop(processMessageFn) {
         return;
     }
     // Heartbeat cron — frequent, lightweight
-    logger.info(`[Heartbeat] Starting heartbeat cron: "${config.HEARTBEAT_CRON}"`);
-    heartbeatJob = new Cron(config.HEARTBEAT_CRON, { timezone: 'UTC', protect: true }, async () => {
+    logger.info(`[Heartbeat] Starting heartbeat cron: "${config.HEARTBEAT_CRON}" (tz: ${config.POLLER_TZ})`);
+    heartbeatJob = new Cron(config.HEARTBEAT_CRON, { timezone: config.POLLER_TZ, protect: true }, async () => {
         await runHeartbeatJob(processMessageFn);
     });
     // Maintenance cron — daily, heavy (consolidation, memory cleanup)
-    logger.info(`[Maintenance] Starting maintenance cron: "${config.MAINTENANCE_CRON}"`);
-    maintenanceJob = new Cron(config.MAINTENANCE_CRON, { timezone: 'UTC', protect: true }, async () => {
+    logger.info(`[Maintenance] Starting maintenance cron: "${config.MAINTENANCE_CRON}" (tz: ${config.POLLER_TZ})`);
+    maintenanceJob = new Cron(config.MAINTENANCE_CRON, { timezone: config.POLLER_TZ, protect: true }, async () => {
         await runMaintenanceJob(processMessageFn);
     });
 }

package/dist/logger.d.ts

@@ -5,6 +5,7 @@ export declare class SessionLogger {
     private write;
     info(message: string): void;
     error(message: string): void;
+    warn(message: string): void;
     claude(stream: 'stdout' | 'stderr', message: string): void;
     logPrompt(prompt: string): void;
     getLogFile(): string;

package/dist/logger.js

@@ -56,6 +56,12 @@ export class SessionLogger {
         this.write('ERROR', message, ts);
         writeToFile('ERROR', `[${this.sessionId}] ${message}`, ts);
     }
+    warn(message) {
+        const ts = now();
+        console.warn(`[${ts}] [${this.sessionId}] ${message}`);
+        this.write('WARN', message, ts);
+        writeToFile('WARN', `[${this.sessionId}] ${message}`, ts);
+    }
     claude(stream, message) {
         const ts = now();
         const prefix = `[Claude ${stream}]`;

package/dist/maintenance-reporter.js

@@ -1,10 +1,11 @@
-import { readdir, readFile, unlink } from 'fs/promises';
+import { readdir, readFile, unlink, writeFile } from 'fs/promises';
 import { join } from 'path';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import { config } from './config.js';
+import { config, POLLER_VERSION } from './config.js';
 import { logger } from './logger.js';
 import { emitError } from './event-queue.js';
+import { getBaseBrainCommitSha, getBaseBrainAgeHours } from './base-brain-metadata.js';
 const execFileAsync = promisify(execFile);
 const OPERATION_TO_EVENT_TYPE = {
     consolidation: 'maintenance.consolidation',
@@ -25,8 +26,14 @@ export async function postMaintenanceReports(brainPath, channelId) {
         if (jsonFiles.length === 0)
             return;
         logger.info(`[MaintenanceReporter] Found ${jsonFiles.length} JSON report(s) in ${reportsDir}`);
+        // Fleet visibility fields — sampled once per run. See teamvibe.ai#129.
+        const [baseBrainCommitSha, baseBrainAgeHours] = await Promise.all([
+            getBaseBrainCommitSha(config.BASE_BRAIN_PATH),
+            getBaseBrainAgeHours(config.BASE_BRAIN_PATH),
+        ]);
         const postedFiles = [];
         const removedFiles = [];
+        let consolidationGuardTouched = false;
         for (const file of jsonFiles) {
             const filePath = join(reportsDir, file);
             try {
@@ -50,6 +57,9 @@ export async function postMaintenanceReports(brainPath, channelId) {
                 const payload = {
                     eventType,
                     channelId,
+                    pollerVersion: POLLER_VERSION,
+                    baseBrainCommitSha,
+                    baseBrainAgeHours,
                     metadata: report,
                 };
                 const response = await fetch(`${config.TEAMVIBE_API_URL}/events`, {
@@ -64,6 +74,23 @@ export async function postMaintenanceReports(brainPath, channelId) {
                     logger.info(`[MaintenanceReporter] Posted ${file} as ${eventType}`);
                     await unlink(filePath).catch(() => { });
                     postedFiles.push(`reports/${file}`);
+                    // Touch the consolidation guard file so the poller-local
+                    // `daysSinceMaintenance` metric reflects this successful run.
+                    // The metric reads `stat(memory/.last_consolidation).mtimeMs`, so any
+                    // skip of the consolidation skill's "update timestamp" step causes
+                    // silent drift. See poller-brain#109, poller-brain-eval#150.
+                    if (report.operationType === 'consolidation') {
+                        const guardPath = join(brainPath, 'memory', '.last_consolidation');
+                        const today = new Date().toISOString().slice(0, 10);
+                        try {
+                            await writeFile(guardPath, `${today}\n`);
+                            consolidationGuardTouched = true;
+                            logger.info(`[MaintenanceReporter] Touched ${guardPath}`);
+                        }
+                        catch (err) {
+                            logger.warn(`[MaintenanceReporter] Failed to touch ${guardPath}: ${err instanceof Error ? err.message : err}`);
+                        }
+                    }
                 }
                 else {
                     const errorBody = await response.text().catch(() => 'unknown');
@@ -76,13 +103,24 @@ export async function postMaintenanceReports(brainPath, channelId) {
                 emitError('maintenance', `Error processing report ${file}: ${err instanceof Error ? err.message : String(err)}`, { severity: 'warn', channelId });
             }
         }
-        // Remove posted/invalid JSON reports from git so they don't resurrect on next pull
+        // Remove posted/invalid JSON reports from git so they don't resurrect on next pull,
+        // and stage the consolidation guard file if it was touched this run.
         const allRemovedFromGit = [...postedFiles, ...removedFiles];
-        if (allRemovedFromGit.length > 0) {
+        if (allRemovedFromGit.length > 0 || consolidationGuardTouched) {
             try {
-                await execFileAsync('git', ['rm', '--cached', '--ignore-unmatch', ...allRemovedFromGit], { cwd: brainPath });
-                await execFileAsync('git', ['commit', '-m', 'chore: remove processed maintenance reports'], { cwd: brainPath });
-                logger.info(`[MaintenanceReporter] Committed removal of ${allRemovedFromGit.length} report(s) from git`);
+                if (allRemovedFromGit.length > 0) {
+                    await execFileAsync('git', ['rm', '--cached', '--ignore-unmatch', ...allRemovedFromGit], { cwd: brainPath });
+                }
+                if (consolidationGuardTouched) {
+                    await execFileAsync('git', ['add', 'memory/.last_consolidation'], { cwd: brainPath });
+                }
+                const message = consolidationGuardTouched && allRemovedFromGit.length > 0
+                    ? 'chore: process maintenance reports and refresh consolidation guard'
+                    : consolidationGuardTouched
+                        ? 'chore: refresh consolidation guard'
+                        : 'chore: remove processed maintenance reports';
+                await execFileAsync('git', ['commit', '-m', message], { cwd: brainPath });
+                logger.info(`[MaintenanceReporter] Committed ${allRemovedFromGit.length} report removal(s)${consolidationGuardTouched ? ' + guard refresh' : ''}`);
             }
             catch (err) {
                 logger.debug(`[MaintenanceReporter] Could not git-rm reports (may not be a git repo): ${err instanceof Error ? err.message : err}`);

package/dist/poller.d.ts

@@ -1,3 +1,8 @@
+interface ReleaseLogger {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+}
+export declare function releaseAllActiveLocks(locks: Map<string, string>, release: (threadId: string, lockToken: string) => Promise<void>, log?: ReleaseLogger): Promise<void>;
 /**
  * Run the auto-update cron handler with telemetry instrumentation (#119).
  * Exported for tests that fire the handler manually.
@@ -9,3 +14,4 @@
  */
 export declare function runAutoUpdateJob(checkForUpdateFn?: () => Promise<boolean>): Promise<void>;
 export declare function startPoller(): Promise<void>;
+export {};

package/dist/poller.js

@@ -5,6 +5,7 @@ import { spawnClaudeCode, isAtCapacity, getActiveProcessCount, killAllActiveProc
 import { sendSlackError, addReaction, getUserInfo, startTypingIndicator } from './slack-client.js';
 import { acquireSessionLock, releaseSessionLock, updateSessionId } from './session-store.js';
 import { getBrainPath, ensureDirectories, ensureBaseBrain, pushBrainChanges } from './brain-manager.js';
+import { cleanupOrphanWorktreesForAllBrains, isWorktreeIsolationEnabled } from './worktree-manager.js';
 import { postMaintenanceReports } from './maintenance-reporter.js';
 import { initAuth, stopRefresh } from './auth-provider.js';
 import { registerBrain, startHeartbeatLoop, stopHeartbeatLoop } from './heartbeat-manager.js';
@@ -21,6 +22,23 @@ import { platform } from 'os';
 const execAsync = promisify(exec);
 // Track active message processing
 const processingMessages = new Set();
+// Track DynamoDB session locks held by in-flight runInboxLoop iterations.
+// On SIGTERM/SIGINT, shutdown() releases these so the next message arriving for
+// the same thread doesn't block on the 15-min STALE_LOCK_TIMEOUT_MS.
+// teamvibe.ai#106 (Tier 1)
+const activeLocks = new Map();
+// Exported for testing. Releases every entry in `locks` via `release`,
+// using Promise.allSettled so one bad release doesn't abort the others.
+// `locks` is cleared on completion regardless of per-entry outcome.
+export async function releaseAllActiveLocks(locks, release, log = logger) {
+    if (locks.size === 0)
+        return;
+    log.info(`Releasing ${locks.size} active session lock(s)...`);
+    await Promise.allSettled(Array.from(locks.entries()).map(([threadId, lockToken]) => release(threadId, lockToken).catch((err) => {
+        log.warn(`Failed to release lock for ${threadId} during shutdown: ${err instanceof Error ? err.message : err}`);
+    })));
+    locks.clear();
+}
 // Poller auto-update cron (separate from brain heartbeats)
 let autoUpdateJob = null;
 /**
@@ -127,6 +145,9 @@ async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
             }
         }
         const { session, lockToken } = lockResult;
+        if (lockToken) {
+            activeLocks.set(threadId, lockToken);
+        }
         let currentSessionId = session.session_id || undefined;
         while (true) {
             const message = pickNextMessage(kbPath, threadId);
@@ -239,11 +260,13 @@ async function runInboxLoop(threadId, kbPath, queueMessage, sessionLog) {
         if (lockToken) {
             const lastMessageTs = queueMessage.response_context.slack?.message_ts;
             await releaseSessionLock(threadId, lockToken, 'idle', lastMessageTs);
+            activeLocks.delete(threadId);
         }
         sessionLog.info(`[Loop] Complete. Iterations: ${iteration}`);
     }
     finally {
         activeLoops.delete(threadId);
+        activeLocks.delete(threadId);
     }
 }
 async function processMessage(received) {
@@ -484,6 +507,10 @@ async function shutdown(signal, exitCode = 0) {
     stopEventQueue();
     // Kill all active Claude child processes
     await killAllActiveProcesses();
+    // Release any DynamoDB session locks held by interrupted runInboxLoop
+    // iterations. Without this, the next message arriving for the same thread
+    // would block until STALE_LOCK_TIMEOUT_MS (15 min) elapses. teamvibe.ai#106
+    await releaseAllActiveLocks(activeLocks, (threadId, lockToken) => releaseSessionLock(threadId, lockToken, 'idle'));
     // Wait for processingMessages to drain (with timeout)
     const shutdownTimeout = 30000;
     const startTime = Date.now();
@@ -517,6 +544,11 @@ export async function startPoller() {
     startEventQueue();
     await ensureDirectories();
     await ensureBaseBrain();
+    if (isWorktreeIsolationEnabled()) {
+        logger.info('   Worktree isolation: ENABLED (POLLER_USE_WORKTREES=true)');
+        const sweep = await cleanupOrphanWorktreesForAllBrains(config.BRAINS_PATH);
+        logger.info(`   Orphan worktree sweep: scanned ${sweep.scanned} brains, removed ${sweep.removed} stale worktrees`);
+    }
     startHeartbeatLoop(processMessage);
     startAutoUpdateCron();
     startMetricsCron();

package/dist/worktree-manager.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Create a fresh worktree for a spawned session. Returns the absolute path of
+ * the worktree, which the caller should use as the spawned process's `cwd`.
+ *
+ * Idempotent against existing worktrees at the same path: if one is found,
+ * it's removed and recreated to guarantee a clean start.
+ */
+export declare function createWorktree(brainPath: string, sessionId: string, branch?: string): Promise<string>;
+/**
+ * Remove a worktree by session ID. Force-removes so dirty state from a crashed
+ * session doesn't block cleanup — the contract is that any session work the
+ * caller wanted to preserve has already been pushed to `origin/<branch>`.
+ */
+export declare function removeWorktree(brainPath: string, sessionId: string): Promise<void>;
+/**
+ * Sweep orphan worktrees left behind by crashed sessions. Removes every
+ * worktree under `<brainPath>/.worktrees/` whose directory mtime is older
+ * than `maxAgeMs`. Intended to run once at poller startup.
+ */
+export declare function cleanupOrphanWorktrees(brainPath: string, maxAgeMs?: number): Promise<{
+    removed: string[];
+}>;
+/**
+ * Sweep orphan worktrees across every brain directory under `brainsRoot`.
+ * Intended to run once at poller startup. Tolerates the entries that aren't
+ * brain repos (no `.git` subdir) by skipping them silently.
+ */
+export declare function cleanupOrphanWorktreesForAllBrains(brainsRoot: string, maxAgeMs?: number): Promise<{
+    scanned: number;
+    removed: number;
+}>;
+/**
+ * Whether the spawner should isolate spawned sessions in worktrees. Gated by
+ * env var `POLLER_USE_WORKTREES`; defaults off until the rollout is verified.
+ */
+export declare function isWorktreeIsolationEnabled(): boolean;

package/dist/worktree-manager.js

@@ -0,0 +1,147 @@
+import { mkdir, readdir, stat, appendFile, readFile } from 'fs/promises';
+import { join } from 'path';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
+const WORKTREES_SUBDIR = '.worktrees';
+const EXCLUDE_ENTRY = `${WORKTREES_SUBDIR}/\n`;
+/**
+ * Spawned (non-foreground) Claude sessions run in isolated git worktrees off
+ * the brain repo to avoid the sync-watchdog race in teamvibe.ai#120.
+ *
+ * Layout:
+ *
+ *   <brainPath>/                            ← main working dir (foreground)
+ *   <brainPath>/.worktrees/<sessionId>/     ← detached-HEAD worktree (spawned)
+ *
+ * The worktree is created from the current `origin/<branch>` tip in detached
+ * HEAD so the spawned session can commit + `git push origin HEAD:<branch>`
+ * without conflicting with the main worktree's branch checkout. The sync
+ * watchdog runs only against the main worktree and never traverses
+ * `.worktrees/*`, so commits + in-flight tool writes in a worktree are safe.
+ */
+async function ensureExclude(brainPath) {
+    const excludePath = join(brainPath, '.git', 'info', 'exclude');
+    let current = '';
+    try {
+        current = await readFile(excludePath, 'utf-8');
+    }
+    catch {
+        // .git/info/exclude may not exist (rare); fall back to creating it
+    }
+    if (!current.split('\n').includes(WORKTREES_SUBDIR + '/')) {
+        await appendFile(excludePath, EXCLUDE_ENTRY);
+    }
+}
+/**
+ * Create a fresh worktree for a spawned session. Returns the absolute path of
+ * the worktree, which the caller should use as the spawned process's `cwd`.
+ *
+ * Idempotent against existing worktrees at the same path: if one is found,
+ * it's removed and recreated to guarantee a clean start.
+ */
+export async function createWorktree(brainPath, sessionId, branch = 'main') {
+    await mkdir(join(brainPath, WORKTREES_SUBDIR), { recursive: true });
+    await ensureExclude(brainPath);
+    const worktreePath = join(brainPath, WORKTREES_SUBDIR, sessionId);
+    // Defensive cleanup in case a previous attempt left an orphan
+    try {
+        await execFileAsync('git', ['worktree', 'remove', '--force', worktreePath], { cwd: brainPath });
+    }
+    catch {
+        // Not registered as a worktree — fine
+    }
+    await execFileAsync('git', ['fetch', 'origin', branch, '--quiet'], { cwd: brainPath });
+    await execFileAsync('git', ['worktree', 'add', '--detach', worktreePath, `origin/${branch}`], { cwd: brainPath });
+    return worktreePath;
+}
+/**
+ * Remove a worktree by session ID. Force-removes so dirty state from a crashed
+ * session doesn't block cleanup — the contract is that any session work the
+ * caller wanted to preserve has already been pushed to `origin/<branch>`.
+ */
+export async function removeWorktree(brainPath, sessionId) {
+    const worktreePath = join(brainPath, WORKTREES_SUBDIR, sessionId);
+    try {
+        await execFileAsync('git', ['worktree', 'remove', '--force', worktreePath], { cwd: brainPath });
+    }
+    catch {
+        // Already gone, or never registered — fine
+    }
+    // Prune any stale administrative bookkeeping in .git/worktrees/
+    try {
+        await execFileAsync('git', ['worktree', 'prune'], { cwd: brainPath });
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * Sweep orphan worktrees left behind by crashed sessions. Removes every
+ * worktree under `<brainPath>/.worktrees/` whose directory mtime is older
+ * than `maxAgeMs`. Intended to run once at poller startup.
+ */
+export async function cleanupOrphanWorktrees(brainPath, maxAgeMs = 24 * 60 * 60 * 1000) {
+    const worktreesDir = join(brainPath, WORKTREES_SUBDIR);
+    const removed = [];
+    let entries = [];
+    try {
+        entries = await readdir(worktreesDir);
+    }
+    catch {
+        return { removed }; // dir doesn't exist yet — nothing to do
+    }
+    const cutoffMs = Date.now() - maxAgeMs;
+    for (const entry of entries) {
+        const path = join(worktreesDir, entry);
+        try {
+            const s = await stat(path);
+            if (s.mtimeMs < cutoffMs) {
+                await removeWorktree(brainPath, entry);
+                removed.push(entry);
+            }
+        }
+        catch {
+            // skip entries we can't stat
+        }
+    }
+    return { removed };
+}
+/**
+ * Sweep orphan worktrees across every brain directory under `brainsRoot`.
+ * Intended to run once at poller startup. Tolerates the entries that aren't
+ * brain repos (no `.git` subdir) by skipping them silently.
+ */
+export async function cleanupOrphanWorktreesForAllBrains(brainsRoot, maxAgeMs = 24 * 60 * 60 * 1000) {
+    let entries = [];
+    try {
+        entries = await readdir(brainsRoot);
+    }
+    catch {
+        return { scanned: 0, removed: 0 };
+    }
+    let scanned = 0;
+    let removed = 0;
+    for (const entry of entries) {
+        const brainPath = join(brainsRoot, entry);
+        try {
+            const gitStat = await stat(join(brainPath, '.git'));
+            if (!gitStat.isDirectory())
+                continue;
+        }
+        catch {
+            continue; // not a brain repo
+        }
+        scanned++;
+        const { removed: gone } = await cleanupOrphanWorktrees(brainPath, maxAgeMs);
+        removed += gone.length;
+    }
+    return { scanned, removed };
+}
+/**
+ * Whether the spawner should isolate spawned sessions in worktrees. Gated by
+ * env var `POLLER_USE_WORKTREES`; defaults off until the rollout is verified.
+ */
+export function isWorktreeIsolationEnabled() {
+    return (process.env['POLLER_USE_WORKTREES'] || '').toLowerCase() === 'true';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamvibe/poller",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {