@teamvibe/poller 0.6.0 → 0.7.0

package/dist/brain-manager.d.ts

@@ -1,8 +1,23 @@
+export declare function withBrainLock<T>(brainId: string, fn: () => Promise<T>): Promise<T>;
 interface BrainConfig {
     brainId: string;
     gitRepoUrl: string;
     branch: string;
 }
+/**
+ * Remove stale git lock files (tv#76) so an orphaned lock from a killed
+ * process (e.g. the 2026-05-01 outage) doesn't block brain updates/pushes
+ * indefinitely. Fresh locks (younger than the threshold) are left alone —
+ * they may belong to a git operation that's genuinely still running.
+ * A missing lock (stat fails) is a silent no-op. A genuine removal failure
+ * (unlink fails, e.g. permission denied) is logged via logger.warn with the
+ * path and error — that's the exact "lock exists but can't be cleared"
+ * scenario this fix exists to make visible.
+ *
+ * Exported for testing — production call sites go through updateBrain /
+ * pushBrainChanges below.
+ */
+export declare function cleanupStaleLocks(brainDir: string): Promise<void>;
 export declare function getBrainPath(brain?: BrainConfig, channelId?: string, workspaceId?: string): Promise<string>;
 /**
  * Update a brain repo (respects cooldown). Exported for testing — production
@@ -18,11 +33,38 @@ export declare function ensureBaseBrain(): Promise<void>;
  * Get the path to the base brain directory.
  */
 export declare function getBaseBrainPath(): string;
+/**
+ * Scan the commits about to be pushed for blobs over `maxBytes`. Returns the
+ * offending paths/sizes, or an empty array if everything is under the limit.
+ *
+ * Scans `@{u}..HEAD` when an upstream exists (the actual new content being
+ * pushed); falls back to all objects reachable from HEAD for a branch's first
+ * push (no upstream yet), which is equivalent since nothing has been pushed.
+ */
+export declare function findOversizedBlobs(brainDir: string, maxBytes: number): Promise<Array<{
+    path: string;
+    size: number;
+}>>;
 /**
  * Commit and push any changes in a brain repo.
  * Silently skips if there are no changes or no remote.
+ *
+ * On non-fast-forward rejection (tv#232 push-race — remote advanced between
+ * local commit and push, e.g. a concurrent session or scheduled-tick already
+ * pushed), fetch+rebase and retry, bounded by BRAIN_PUSH_RETRY_MAX. A genuine
+ * rebase conflict (or an autostash pop that silently leaves changes stashed —
+ * git does not surface that as a rebase error) is treated as a hard failure
+ * needing manual sync, not retried further.
+ *
+ * `retryOptions` defaults to the BRAIN_PUSH_RETRY_* config; exposed as a
+ * parameter (rather than reading `config` directly inline) so tests can
+ * exercise the retry-exhaustion boundary deterministically without relying on
+ * process-wide env/module-load-order tricks.
  */
-export declare function pushBrainChanges(brainDir: string, brainId: string, workspaceId?: string): Promise<void>;
+export declare function pushBrainChanges(brainDir: string, brainId: string, workspaceId?: string, retryOptions?: {
+    maxAttempts?: number;
+    backoffMs?: number;
+}): Promise<void>;
 /**
  * Ensure base paths exist
  */

package/dist/brain-manager.js

@@ -1,7 +1,8 @@
 import { exec } from 'child_process';
 import { promisify } from 'util';
 import { existsSync, mkdirSync } from 'fs';
-import { join } from 'path';
+import { readdir, stat, unlink } from 'fs/promises';
+import { join, basename } from 'path';
 import { config } from './config.js';
 import { logger } from './logger.js';
 import { emitError } from './event-queue.js';
@@ -20,8 +21,84 @@ if (config.PERSISTENT_STORAGE_PATH) {
 function gitExec(command, options) {
     return execAsync(command, { ...options, env: gitEnv });
 }
+// Node's child_process.exec() defaults to a 1MB stdout cap. This bounds the
+// text output of a git plumbing command (e.g. one line per object listed),
+// not any single blob's size -- it has no relationship to
+// config.BRAIN_MAX_BLOB_BYTES and must stay its own named constant so the
+// two don't drift into looking coupled just because they're both 50MB today.
+const GIT_SCAN_MAX_BUFFER_BYTES = 50 * 1024 * 1024;
 // Cooldown tracker per brain
 const lastUpdateTimes = new Map();
+// Per-brainId mutex serializing updateBrain/pushBrainChanges for a given
+// brain. Two threads of the SAME brain running concurrently in this process
+// share one brainDir (tv#76/tv#277 review) — without this, cleanupStaleLocks()
+// can unlink a git lock file that a still-in-flight sibling call's own git
+// operation legitimately holds, corrupting the index. Poller instances never
+// share a physical brainDir across processes/machines (BRAINS_PATH is
+// $HOME-derived and each poller is a single process — see tv#287), so this
+// in-process mutex fully closes the race; no DynamoDB-level lock is needed.
+const brainLocks = new Map();
+// Exported for testing — production call sites go through updateBrain / pushBrainChanges above.
+export function withBrainLock(brainId, fn) {
+    const prior = brainLocks.get(brainId) ?? Promise.resolve();
+    const run = prior.then(fn, fn);
+    brainLocks.set(brainId, run.then(() => undefined, () => undefined));
+    return run;
+}
+/**
+ * Remove stale git lock files (tv#76) so an orphaned lock from a killed
+ * process (e.g. the 2026-05-01 outage) doesn't block brain updates/pushes
+ * indefinitely. Fresh locks (younger than the threshold) are left alone —
+ * they may belong to a git operation that's genuinely still running.
+ * A missing lock (stat fails) is a silent no-op. A genuine removal failure
+ * (unlink fails, e.g. permission denied) is logged via logger.warn with the
+ * path and error — that's the exact "lock exists but can't be cleared"
+ * scenario this fix exists to make visible.
+ *
+ * Exported for testing — production call sites go through updateBrain /
+ * pushBrainChanges below.
+ */
+export async function cleanupStaleLocks(brainDir) {
+    const candidates = [
+        { path: join(brainDir, '.git', 'index.lock'), maxAgeMs: config.GIT_LOCK_MAX_AGE_MS },
+    ];
+    const modulesDir = join(brainDir, '.git', 'modules');
+    try {
+        const entries = await readdir(modulesDir, { recursive: true });
+        for (const entry of entries) {
+            if (basename(entry) === 'config.lock') {
+                candidates.push({ path: join(modulesDir, entry), maxAgeMs: config.GIT_SUBMODULE_LOCK_MAX_AGE_MS });
+            }
+        }
+    }
+    catch {
+        // No .git/modules dir (no submodules yet) — nothing to scan.
+    }
+    for (const { path: lockPath, maxAgeMs } of candidates) {
+        let lockStat;
+        try {
+            lockStat = await stat(lockPath);
+        }
+        catch {
+            // Lock doesn't exist — normal no-op, nothing worth logging.
+            continue;
+        }
+        const ageMs = Date.now() - lockStat.mtimeMs;
+        if (ageMs <= maxAgeMs)
+            continue;
+        try {
+            await unlink(lockPath);
+            logger.warn(`Removed stale git lock: ${lockPath} (age: ${Math.round(ageMs / 1000)}s, threshold: ${Math.round(maxAgeMs / 1000)}s)`);
+        }
+        catch (error) {
+            // Real removal failure (e.g. permission denied) — this is the exact
+            // 2026-05-01 outage scenario, so it must leave a diagnostic trail
+            // instead of silently skipping like a plain "lock doesn't exist".
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.warn(`Failed to remove stale git lock: ${lockPath} (age: ${Math.round(ageMs / 1000)}s): ${errorMessage}`);
+        }
+    }
+}
 /**
  * Get or clone brain repo. Returns the working directory path.
  */
@@ -94,6 +171,9 @@ export async function getBrainPath(brain, channelId, workspaceId) {
  * call sites should go through `getBrainPath` / `ensureBaseBrain`.
  */
 export async function updateBrain(brainDir, brainId, branch) {
+    return withBrainLock(brainId, () => updateBrainLocked(brainDir, brainId, branch));
+}
+async function updateBrainLocked(brainDir, brainId, branch) {
     const now = Date.now();
     const lastUpdate = lastUpdateTimes.get(brainId) || 0;
     if (now - lastUpdate < config.BRAIN_UPDATE_COOLDOWN_MS) {
@@ -137,6 +217,7 @@ export async function updateBrain(brainDir, brainId, branch) {
         logger.warn(`Brain ${brainId} pre-check failed, skipping update: ${errorMessage}`);
         return;
     }
+    await cleanupStaleLocks(brainDir);
     try {
         logger.info(`Updating brain ${brainId} at ${brainDir}...`);
         await gitExec(`git fetch origin ${branch} && git reset --hard origin/${branch} && git submodule update --init --recursive`, {
@@ -173,11 +254,73 @@ export async function ensureBaseBrain() {
 export function getBaseBrainPath() {
     return config.BASE_BRAIN_PATH;
 }
+// Matches git's non-fast-forward push rejection ("! [rejected] ... (fetch first)"
+// or "... (non-fast-forward)"). Distinguishes a push-race (remote advanced,
+// reconcilable via rebase) from other push failures (network, auth, oversized
+// blob pre-receive decline — see tv#246) which retrying can never fix.
+const NON_FF_REJECTION_RE = /\[rejected\][\s\S]*(fetch first|non-fast-forward)/;
+async function gitStashList(brainDir) {
+    const { stdout } = await gitExec('git stash list', { cwd: brainDir });
+    return stdout.trim();
+}
+/**
+ * Scan the commits about to be pushed for blobs over `maxBytes`. Returns the
+ * offending paths/sizes, or an empty array if everything is under the limit.
+ *
+ * Scans `@{u}..HEAD` when an upstream exists (the actual new content being
+ * pushed); falls back to all objects reachable from HEAD for a branch's first
+ * push (no upstream yet), which is equivalent since nothing has been pushed.
+ */
+export async function findOversizedBlobs(brainDir, maxBytes) {
+    let range = 'HEAD';
+    try {
+        await gitExec('git rev-parse @{u}', { cwd: brainDir });
+        range = '@{u}..HEAD';
+    }
+    catch {
+        // No upstream tracking ref yet — first push for this branch, scan all of HEAD.
+    }
+    // A full-HEAD scan (the fallback path this guard needs to work on) can
+    // exceed Node's default 1MB stdout cap on a repo with many objects.
+    // Without a larger maxBuffer the scan throws ENOBUFS and the guard
+    // silently disables itself (see catch below) on exactly the histories most
+    // likely to contain an oversized blob.
+    const { stdout } = await gitExec(`git rev-list --objects ${range} | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)'`, { cwd: brainDir, maxBuffer: GIT_SCAN_MAX_BUFFER_BYTES });
+    const oversized = [];
+    for (const line of stdout.split('\n')) {
+        if (!line.trim())
+            continue;
+        const [type, , sizeStr, ...pathParts] = line.split(' ');
+        if (type !== 'blob')
+            continue;
+        const size = Number(sizeStr);
+        if (size > maxBytes) {
+            oversized.push({ path: pathParts.join(' ') || '(unknown path)', size });
+        }
+    }
+    return oversized;
+}
 /**
  * Commit and push any changes in a brain repo.
  * Silently skips if there are no changes or no remote.
+ *
+ * On non-fast-forward rejection (tv#232 push-race — remote advanced between
+ * local commit and push, e.g. a concurrent session or scheduled-tick already
+ * pushed), fetch+rebase and retry, bounded by BRAIN_PUSH_RETRY_MAX. A genuine
+ * rebase conflict (or an autostash pop that silently leaves changes stashed —
+ * git does not surface that as a rebase error) is treated as a hard failure
+ * needing manual sync, not retried further.
+ *
+ * `retryOptions` defaults to the BRAIN_PUSH_RETRY_* config; exposed as a
+ * parameter (rather than reading `config` directly inline) so tests can
+ * exercise the retry-exhaustion boundary deterministically without relying on
+ * process-wide env/module-load-order tricks.
  */
-export async function pushBrainChanges(brainDir, brainId, workspaceId) {
+export async function pushBrainChanges(brainDir, brainId, workspaceId, retryOptions) {
+    return withBrainLock(brainId, () => pushBrainChangesLocked(brainDir, brainId, workspaceId, retryOptions));
+}
+async function pushBrainChangesLocked(brainDir, brainId, workspaceId, retryOptions) {
+    await cleanupStaleLocks(brainDir);
     try {
         // Check if this is a git repo with a remote
         try {
@@ -203,11 +346,121 @@ export async function pushBrainChanges(brainDir, brainId, workspaceId) {
             logger.debug(`Brain ${brainId} has no unpushed commits`);
             return;
         }
+        // Guard: refuse to push if any blob about to be pushed exceeds the size limit.
+        // GitHub hard-rejects blobs over its limit, and once such a blob is committed
+        // the push can never succeed by retrying — it needs a history rewrite (tv#246).
+        // Skipping the push here keeps the brain retrying safely (and alerting) instead
+        // of hammering GitHub with a doomed push and losing the failure into poller.error.
+        try {
+            const oversized = await findOversizedBlobs(brainDir, config.BRAIN_MAX_BLOB_BYTES);
+            if (oversized.length > 0) {
+                const limitMb = (config.BRAIN_MAX_BLOB_BYTES / (1024 * 1024)).toFixed(0);
+                const details = oversized.map((o) => `${o.path} (${(o.size / (1024 * 1024)).toFixed(1)} MB)`).join(', ');
+                const message = `Brain ${brainId} push blocked — blob(s) over ${limitMb}MB limit in unpushed commits: ${details}`;
+                logger.error(message);
+                emitError('brain', message, { context: { brainId, oversizedPaths: oversized.map((o) => o.path) } });
+                return;
+            }
+        }
+        catch (error) {
+            // Guard itself failed (e.g. git plumbing hiccup) — don't block a legitimate
+            // push on that; fall through to the push attempt as before this guard existed.
+            // Still surface it as an error (not just a warn log): a silently-disabled
+            // guard defeats the whole point of tv#246, so it needs the same alerting
+            // visibility as the case it's meant to catch.
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const message = `Brain ${brainId} oversized-blob guard failed, proceeding without it: ${errorMessage}`;
+            logger.error(message);
+            emitError('brain', message, { context: { brainId } });
+        }
         const branch = (await gitExec('git branch --show-current', { cwd: brainDir })).stdout.trim() || 'main';
-        await gitExec(`git push -u origin ${branch}`, { cwd: brainDir });
-        logger.info(`Brain ${brainId} changes pushed successfully`);
-        if (workspaceId)
-            reportBrainSync(brainId, workspaceId, 'pushed');
+        const maxAttempts = retryOptions?.maxAttempts ?? config.BRAIN_PUSH_RETRY_MAX;
+        const backoffMs = retryOptions?.backoffMs ?? config.BRAIN_PUSH_RETRY_BACKOFF_MS;
+        let attempt = 0;
+        let lastErrorMessage = '';
+        while (attempt < maxAttempts) {
+            attempt++;
+            try {
+                await gitExec(`git push -u origin ${branch}`, { cwd: brainDir });
+                if (attempt > 1) {
+                    logger.info(`Brain ${brainId} push-race auto-resolved after ${attempt} attempts`);
+                    emitError('brain', `Brain ${brainId} push-race auto-resolved after ${attempt} attempts`, {
+                        severity: 'warn',
+                        context: { brainId, errorCode: 'PUSH_RACE_CONVERGED', attempts: attempt },
+                    });
+                }
+                else {
+                    logger.info(`Brain ${brainId} changes pushed successfully`);
+                }
+                if (workspaceId)
+                    reportBrainSync(brainId, workspaceId, 'pushed');
+                return;
+            }
+            catch (error) {
+                lastErrorMessage = error instanceof Error ? error.message : String(error);
+                if (!NON_FF_REJECTION_RE.test(lastErrorMessage) || attempt >= maxAttempts)
+                    break;
+                logger.info(`Brain ${brainId} push rejected (non-fast-forward), rebasing and retrying (attempt ${attempt}/${maxAttempts})...`);
+                try {
+                    await gitExec(`git fetch origin ${branch}`, { cwd: brainDir });
+                }
+                catch (fetchError) {
+                    // No rebase has started yet at this point, so `git rebase --abort`
+                    // below would itself fail ("no rebase in progress") and mislabel a
+                    // plain network/fetch failure as PUSH_RACE_ABORT_FAILED. Keep fetch
+                    // failures in their own errorCode instead.
+                    const fetchMessage = fetchError instanceof Error ? fetchError.message : String(fetchError);
+                    logger.error(`Brain ${brainId} push-race: git fetch failed: ${fetchMessage}`);
+                    emitError('brain', `Brain ${brainId} push-race: fetch failed, cannot rebase: ${fetchMessage}`, {
+                        severity: 'error',
+                        context: { brainId, errorCode: 'PUSH_RACE_FETCH_FAILED', attempts: attempt },
+                    });
+                    return;
+                }
+                const stashBefore = await gitStashList(brainDir);
+                try {
+                    await gitExec(`git rebase --autostash origin/${branch}`, { cwd: brainDir });
+                    // `git rebase --autostash` does NOT surface a stash-pop conflict as a
+                    // rebase error — it just leaves the change stashed and warns on
+                    // stderr. Detect that silently-failed pop by diffing the stash list;
+                    // otherwise the loop would proceed to push with local work missing.
+                    const stashAfter = await gitStashList(brainDir);
+                    if (stashAfter !== stashBefore) {
+                        logger.error(`Brain ${brainId} push-race: autostash pop left changes stashed after rebase, treating as conflict`);
+                        emitError('brain', `Brain ${brainId} push-race autostash pop conflict — manual sync needed (stash: ${stashAfter.split('\n')[0]})`, { severity: 'error', context: { brainId, errorCode: 'PUSH_RACE_CONFLICT', attempts: attempt, reason: 'autostash_pop_conflict' } });
+                        return;
+                    }
+                }
+                catch (rebaseError) {
+                    try {
+                        await gitExec('git rebase --abort', { cwd: brainDir });
+                    }
+                    catch (abortError) {
+                        const abortMessage = abortError instanceof Error ? abortError.message : String(abortError);
+                        logger.error(`Brain ${brainId} push-race: git rebase --abort itself failed, repo may be left mid-rebase: ${abortMessage}`);
+                        emitError('brain', `Brain ${brainId} push-race: rebase abort failed, repo possibly stuck mid-rebase: ${abortMessage}`, {
+                            severity: 'error',
+                            context: { brainId, errorCode: 'PUSH_RACE_ABORT_FAILED', attempts: attempt },
+                        });
+                        return;
+                    }
+                    const rebaseMessage = rebaseError instanceof Error ? rebaseError.message : String(rebaseError);
+                    logger.error(`Brain ${brainId} push-race rebase conflict: ${rebaseMessage}`);
+                    emitError('brain', `Brain ${brainId} push-race rebase conflict — manual sync needed: ${rebaseMessage}`, {
+                        severity: 'error',
+                        context: { brainId, errorCode: 'PUSH_RACE_CONFLICT', attempts: attempt },
+                    });
+                    return;
+                }
+                await new Promise((resolve) => setTimeout(resolve, backoffMs * attempt));
+            }
+        }
+        const errorCode = NON_FF_REJECTION_RE.test(lastErrorMessage) ? 'PUSH_RACE_UNRESOLVED' : 'PUSH_FAILED';
+        logger.warn(`Failed to push brain ${brainId} changes: ${lastErrorMessage}`);
+        emitError('brain', `Failed to push brain ${brainId} changes: ${lastErrorMessage}`, {
+            severity: errorCode === 'PUSH_RACE_UNRESOLVED' ? 'error' : 'warn',
+            context: { brainId, errorCode, attempts: attempt },
+        });
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);

package/dist/classify-failed-iteration.d.ts

@@ -1,4 +1,4 @@
-export type KilledByPoller = 'timeout' | 'idle' | 'zombie' | 'network';
+export type KilledByPoller = 'timeout' | 'idle' | 'zombie' | 'network' | 'shutdown';
 export interface FailedIterationInput {
     error?: string;
     exitCode: number | null;

package/dist/classify-failed-iteration.js

@@ -1,7 +1,7 @@
 // Decides how to surface a failed claude-spawner iteration to the user.
 //
 // Background (teamvibe.ai#193): poller-induced kills (timeout, idle watchdog,
-// network watchdog, zombie cleanup) used to leak as generic
+// network watchdog, zombie cleanup, poller shutdown) used to leak as generic
 // "Error processing your request: Process exited with code 143" via
 // sendSlackError. The explicit `killedByPoller` intent marker (set by the
 // spawner before SIGTERM) lets us emit a neutral 1-sentence notice instead —
@@ -33,6 +33,38 @@ export function classifyFailedIteration(result) {
                 text: 'Network connectivity lost — send another message to retry.',
                 reaction: 'satellite_antenna',
             };
+        case 'shutdown':
+            // PR#308 round-6 review: "will resume automatically" (round-5 wording)
+            // is still not reliably true even after the requeue-to-new/ fix in
+            // poller.ts. Requeuing correctly makes the message file findable in
+            // new/ again, but checkInboxForNewSessions() (inbox-watcher.ts) never
+            // scans the filesystem — it iterates getTrackedBrains(), an in-memory
+            // Map populated only by registerBrain() (maintenance-cron.ts), which
+            // only runs when the poller processes an SQS message for that brain
+            // (poller.ts ~line 578). On a fresh poller start, that map is empty
+            // and nothing hydrates it from disk, so a brain with no cron job and
+            // no incoming traffic can have its requeued message sit untouched
+            // until *some* SQS activity for that brain re-registers it — tracked
+            // separately as teamvibe.ai#310 (trackedBrains not hydrated from disk
+            // at startup). Deliberately not "fixed" here per DevGuru round-6: that
+            // hydration gap is a separate, deeper issue.
+            //
+            // "Some SQS activity" isn't only a human message — a user-created
+            // scheduled message (`source: 'cron'`, e.g. create_scheduled_message)
+            // also goes through the same registerBrain() call, so it re-registers
+            // the brain and would surface the requeued message just as well. This
+            // does NOT extend to the poller's own internal maintenance-cron jobs
+            // (`source: 'maintenance'`) — registerBrain() explicitly skips those
+            // (maintenance-cron.ts) — so a maintenance run alone will not unstick
+            // a requeued message. The text below names the two real paths (human
+            // message, user-scheduled run) instead of implying a human reply is
+            // the only way, while still not claiming guaranteed/automatic
+            // resumption for a brain with neither.
+            return {
+                kind: 'neutral',
+                text: "Poller is restarting — your message is saved and will resume with your next message, or this brain's next scheduled run.",
+                reaction: 'arrows_counterclockwise',
+            };
         case 'timeout':
         case undefined: {
             // 'timeout' keeps the legacy ":warning: Session timed out after N

package/dist/claude-spawner.d.ts

@@ -1,8 +1,11 @@
+import { type ChildProcess } from 'child_process';
 import type { TeamVibeQueueMessage, SessionMetrics } from './types.js';
 import { type SessionLogger } from './logger.js';
-import type { TypingIndicator } from './slack-client.js';
+import { type TypingIndicator } from './slack-client.js';
 import { type ResolvedModelConfig } from './config-client.js';
 import type { KilledByPoller } from './classify-failed-iteration.js';
+export declare function progressNotificationMarks(estimateMinutes: number): number[];
+export declare function computeCompactionKillDeadline(previousActivityTime: number, now: number, idleKillMs: number, graceMs: number): number;
 export interface ContextHintParams {
     isFirstMessage: boolean;
     lastMessageTs?: string;
@@ -22,6 +25,8 @@ export interface SpawnResult {
     error?: string;
     metrics?: SessionMetrics;
     killedByPoller?: KilledByPoller;
+    sawSendMessageCall?: boolean;
+    lastPlainTextContent?: string;
     modelSource?: ModelSource;
 }
 /**
@@ -54,7 +59,175 @@ export declare function resolveModel(brainSettingsModel: string | undefined, ddb
     model: string | undefined;
     modelSource: ModelSource;
 };
+/**
+ * teamvibeai/teamvibe.ai#73: `claude` is spawned with `detached: true`, which
+ * (via `setsid`) makes it the leader of its own new process group, distinct
+ * from the poller's. `claude` itself spawns MCP server child processes under
+ * that same group. Signaling `proc` alone (`proc.kill()`) only reaches
+ * `claude` — its MCP children are never signaled and can survive as orphans,
+ * leaking RAM (the Railway staircase-memory pattern that motivated #73).
+ *
+ * This sends the signal to the whole process group instead (negative pid is
+ * the `kill(2)` convention for "signal the group", see `man 2 kill`). The
+ * group id equals `claude`'s own pid because `setsid` was used to create it.
+ *
+ * Group membership survives the leader's own exit — as long as at least one
+ * process (e.g. a lingering MCP server) is still alive in the group, `-pid`
+ * remains a valid target even after `claude` itself has already exited. This
+ * is what makes it safe to call from the `close` handler too (#73 gap 2),
+ * not just from the pre-exit timeout/idle/shutdown kill paths.
+ *
+ * Unlike `ChildProcess#kill()` (a safe no-op on an already-dead process),
+ * `process.kill(-pid, ...)` throws `ESRCH` once the whole group is gone —
+ * expected and common (the group is often already fully reaped by the time
+ * the follow-up SIGKILL sweep fires), so it's caught and swallowed here
+ * rather than propagating into an uncaught exception that would crash the
+ * poller.
+ */
+export declare function killProcessGroup(proc: ChildProcess, signal: NodeJS.Signals): void;
+/**
+ * DevGuru PR#308 round-2 review (item 2): the group-SIGKILL sweeps below
+ * (`killAllActiveProcesses()` and the `close`-handler sweep) used to always
+ * pay their full fixed grace period (5s / `CLOSE_SWEEP_GRACE_MS`) before
+ * resolving, even in the overwhelmingly common case where `claude` exited
+ * cleanly and took its MCP children down with it — i.e. the group is already
+ * empty and there is nothing left to sweep. That matters specifically for
+ * `killAllActiveProcesses()`: `poller.ts`'s `shutdown()` awaits it BEFORE
+ * `releaseAllActiveLocks()`, and delaying that release costs the next
+ * message on the same thread a 15-minute stale-lock wait.
+ *
+ * Cheap fast-path: probe the group with signal `0` — a pure existence check
+ * per `man 2 kill`, it never actually signals anything. `ESRCH` means the
+ * group is provably already gone, so the caller can skip the grace-period
+ * wait entirely instead of always paying it. Any other outcome (including an
+ * unexpected errno) is treated as "still alive" — fail toward the existing,
+ * safe wait+SIGKILL behavior rather than skipping a real cleanup wait.
+ *
+ * Known limitation (DevGuru PR#308 round-4 review, deliberately deferred to
+ * teamvibeai/teamvibe.ai#309 rather than fixed here): a zombie (defunct,
+ * unreaped) process still answers this signal-0 probe without `ESRCH` — the
+ * process table entry is still present, it just has no live task behind it —
+ * so a group containing only zombies is still reported "alive." That makes
+ * the fast-path above silently miss and fall back to the fixed-cost
+ * wait+SIGKILL sequence instead of resolving immediately. This is a safe
+ * fallback (no hang, just no speedup), not a correctness bug — but it does
+ * mean the fast-path quietly stops paying off on a container that has
+ * accumulated zombies. What actually removes the limitation is giving the
+ * container a real init process (e.g. `tini`) as PID 1: unlike a bare `node`
+ * entrypoint, a real init reaps orphaned zombies as they appear, so they
+ * never accumulate and confuse this probe in the first place. See #309 for
+ * the tracked Docker-bake/tini follow-up.
+ */
+export declare function isProcessGroupAlive(pid: number): boolean;
+export interface SweepProcessGroupOptions {
+    onGraceExpired?: () => void;
+    unref?: boolean;
+}
+/**
+ * Shared group-kill grace-period sweep: SIGTERM, then either resolve
+ * immediately via the `isProcessGroupAlive()` fast-path (group already
+ * provably empty — see its doc comment) or wait up to `graceMs` before
+ * escalating to SIGKILL and resolving. Extracted so both call sites
+ * (`killAllActiveProcesses()` and the `close`-handler sweep) share one
+ * tested implementation instead of duplicating the wait+escalate logic.
+ *
+ * PR#308 round-3 review item 2: the up-front `isProcessGroupAlive()` probe
+ * above only fast-paths the "already dead before we even started" case. The
+ * case that matters most — the group IS alive right this instant, which is
+ * always true during a real shutdown with an active session, exactly when
+ * `releaseAllActiveLocks()` is waiting on this — used to still unconditionally
+ * pay the *entire* fixed `graceMs` even if `claude` died 50ms after its
+ * SIGTERM. Fixed by polling `isProcessGroupAlive()` every
+ * `PROCESS_GROUP_POLL_INTERVAL_MS` after the SIGTERM instead of relying on a
+ * single fixed-delay timer to both wait AND escalate: whichever fires first —
+ * a poll observing ESRCH, or the grace period elapsing — resolves/escalates.
+ * `graceMs` remains the hard upper bound on how long this ever waits (a
+ * safety ceiling, unchanged from before); this only shortens the *common*
+ * case where the group dies well before that ceiling.
+ */
+export declare function sweepProcessGroup(proc: ChildProcess, graceMs: number, options?: SweepProcessGroupOptions): Promise<void>;
+export interface BuildSpawnEnvParams {
+    spawnSecretsEnv: NodeJS.ProcessEnv;
+    processEnv: NodeJS.ProcessEnv;
+    envPath: string | undefined;
+    claudeConfigDir: string;
+    persistentStoragePath?: string;
+    slackContext?: {
+        channel: string;
+        thread_ts: string;
+        message_ts: string;
+    };
+    teamvibeApiUrl: string;
+    teamvibePollerToken: string;
+    teamvibeWorkspaceId: string;
+    teamvibeChannelId: string;
+    teamvibeBotId: string;
+    teamvibePollerId: string;
+    inboxThreadId: string;
+    brainPath: string;
+}
+/**
+ * Pure construction of the env object passed to the spawned `claude` child
+ * process. Extracted out of the `spawn()` call site so the "what does the
+ * child actually inherit" logic is unit-testable without spinning up a real
+ * process tree or mocking `fetchSecretsForSpawn`/DDB config.
+ *
+ * `NODE_OPTIONS` is explicitly stripped (same convention as `CLAUDECODE`
+ * below): the poller's own Railway start command sets
+ * `NODE_OPTIONS='--max-old-space-size=128 --max-semi-space-size=2'` to cap
+ * the *poller's* own idle V8 heap — a thin SQS-listener process is fine at
+ * 128MB. That var lives in `process.env` at the poller-process level, so
+ * without this override it would leak via the `...processEnv` spread below
+ * into the spawned `claude` CLI process. `claude` needs real headroom to do
+ * actual agentic work (parsing files, holding conversation context, etc.) —
+ * the poller's own tuned-for-idle heap cap is simply the wrong number for
+ * what that process does, independent of what any specific OOM failure
+ * would look like if left uncapped.
+ */
+export declare function buildSpawnEnv(params: BuildSpawnEnvParams): NodeJS.ProcessEnv;
 export declare function buildPrompt(msg: TeamVibeQueueMessage, contextHint?: string): string;
+export interface SpawnStdinPlan {
+    /** Extra CLI args to append. Empty for the plain-text path — this is the exact pre-tv293-bug2 behavior, unconditionally. */
+    extraArgs: string[];
+    /** Exact chunks written to the child process's stdin, in order, before `.end()`. */
+    stdinChunks: string[];
+}
+/**
+ * Decides how the built prompt reaches the `claude` CLI: the default
+ * plain-text stdin path (unchanged from before teamvibe.ai#293 bug 2 — this
+ * covers essentially all production traffic: every Slack message, every
+ * text-only email, cron, maintenance) or a `stream-json` structured-content
+ * path carrying inline image blocks, used only when `inlineImages` is
+ * present on the incoming message (populated by email-received.ts' Part A
+ * — see packages/modules-teamvibe/src/utils/email-inline-images.ts).
+ *
+ * Pure function — no child_process/spawn access — so the no-image path's
+ * exact output (and thus "no behavior change for non-image sessions") is
+ * directly unit-testable without mocking `spawn` at all. See
+ * claude-spawner.test.ts's "no-image path is unchanged" coverage.
+ *
+ * `now` is injectable (defaults to `Date.now()`) purely so tests can assert
+ * both sides of the `expiresAt` check deterministically — see below.
+ */
+export declare function buildSpawnStdinPlan(prompt: string, inlineImages: TeamVibeQueueMessage['inlineImages'], now?: number): SpawnStdinPlan;
+export declare function extractAssistantText(event: any): string | undefined;
+export declare function assistantCalledTool(event: any, toolName: string): boolean;
+/**
+ * Decides whether a spawn attempt should report its session ID back to the
+ * caller (poller.ts) for persistence to DynamoDB via updateSessionId().
+ *
+ * First-message spawns always mint a fresh session ID locally (see
+ * spawnClaudeCode below, teamvibe.ai#77) instead of recycling whatever
+ * placeholder DynamoDB currently holds — so on ANY successful first-message
+ * spawn (not just the "already in use" collision-retry path), the ID actually
+ * used by Claude Code must be surfaced here. Otherwise DynamoDB keeps the
+ * createSession() placeholder forever and the thread's next message does
+ * `--resume <id-claude-code-never-used>`, which fails 100% of the time.
+ * (teamvibe.ai#77, DevGuru review round)
+ */
+export declare function finalizeSpawnResult(retryResult: SpawnResult, isFirstMessage: boolean, effectiveSessionId: string | undefined): SpawnResult & {
+    newSessionId?: string;
+};
 export declare function spawnClaudeCode(msg: TeamVibeQueueMessage, sessionLog: SessionLogger, cwd: string, sessionId?: string, isFirstMessage?: boolean, lastMessageTs?: string, onMessageSent?: () => void, typingIndicator?: TypingIndicator): Promise<SpawnResult & {
     newSessionId?: string;
 }>;
@@ -66,3 +239,7 @@ export declare function getActiveProcessCount(): number;
 export declare function killZombieForThread(threadId: string): boolean;
 export declare function isAtCapacity(): boolean;
 export declare function killAllActiveProcesses(): Promise<void>;
+export declare function __setActiveProcessForTest(id: string, proc: ChildProcess): void;
+export declare function __clearActiveProcessesForTest(): void;
+export declare function __setKillReasonForTest(proc: ChildProcess, reason: KilledByPoller): void;
+export declare function __getKillReasonForTest(proc: ChildProcess): KilledByPoller | undefined;