@teamvibe/poller 0.6.0 → 0.7.0

package/dist/claude-spawner.js

@@ -6,6 +6,7 @@ import { config } from './config.js';
 import { logger } from './logger.js';
 import { getBaseBrainPath } from './brain-manager.js';
 import { getPollerId } from './auth-provider.js';
+import { sendSlackMessage } from './slack-client.js';
 import { emitError } from './event-queue.js';
 import { createWorktree, removeWorktree, isWorktreeIsolationEnabled } from './worktree-manager.js';
 import { fetchSecretsForSpawn, buildSecretsReminder } from './secrets-client.js';
@@ -119,6 +120,32 @@ async function countPriorThreadMessages(botToken, channel, threadTs, currentMess
         return 0;
     }
 }
+// tv#32 Layer B: given the agent's own estimate (via the set_expected_duration
+// MCP tool) of how long a task will take, return which minute-marks should
+// get a progress notification. Tiers per design discussion with Marosh
+// (2026-07-30): a wrong estimate only costs a mistimed status ping, never a
+// safety issue, so self-report is fine here (unlike the Layer A kill-deadline,
+// which must stay driven by the objective compact_boundary signal only).
+export function progressNotificationMarks(estimateMinutes) {
+    if (estimateMinutes <= 5)
+        return [];
+    if (estimateMinutes <= 10)
+        return [5];
+    if (estimateMinutes <= 15)
+        return [5, 10];
+    return [5, 10, 15];
+}
+// tv#32 Layer A: the idle-watchdog kill deadline on a compact_boundary event.
+// max(original 10min-from-silence-start deadline, event-arrival + 5min grace) —
+// an early compact_boundary (well before the original deadline) causes no
+// extension; a late one gets a small fixed grace period. Never a large
+// speculative ceiling, since compact_boundary only proves compaction STARTED,
+// never that it finishes in bounded time (design revision per Marosh 2026-07-31,
+// after anthropics/claude-code#19567 — a real 26+ hour hung compaction — showed
+// a flat large ceiling would itself be an unfounded guess).
+export function computeCompactionKillDeadline(previousActivityTime, now, idleKillMs, graceMs) {
+    return Math.max(previousActivityTime + idleKillMs, now + graceMs);
+}
 // Select and render the context hint that goes into the prompt. Pure aside
 // from the injected counters — extracted from runClaudeCode so the branching
 // (resume vs. thread-context vs. no-hint) can be unit tested without spinning
@@ -203,6 +230,240 @@ export function resolveModel(brainSettingsModel, ddbConfig, envDefaultModel) {
 // WeakMap auto-cleans when proc is GC'd. Module-scope is required because
 // killZombieForThread fires outside the runClaudeCode closure.
 const killReasonByProc = new WeakMap();
+// Grace period between a group SIGTERM and the follow-up group SIGKILL sweep
+// on the *normal* (successful) completion path — see the `proc.on('close', ...)`
+// handler below. Deliberately shorter than the 5s grace used on the
+// timeout/idle/network/shutdown kill paths: this sweep runs on every single
+// session close (the hot path), not just the relatively rare forced-kill
+// paths, so we don't want to accumulate long-lived timers under load.
+const CLOSE_SWEEP_GRACE_MS = 2000;
+// PR#308 round-3 review item 2: poll interval for sweepProcessGroup()'s
+// post-SIGTERM wait (see below). No existing sub-second polling-interval
+// constant elsewhere in this package to match (checked config.ts /
+// event-queue.ts / auth-provider.ts / inbox-watcher.ts — all *_INTERVAL_MS
+// there are >=30s cron/heartbeat-style intervals, a different scale of
+// problem). 200ms is within DevGuru's suggested 100-250ms range: fine-
+// grained enough that the common "died quickly after SIGTERM" case (the one
+// that matters most — see sweepProcessGroup's doc comment) resolves close to
+// its real death time instead of the full grace period, without probing so
+// often it adds meaningful overhead during shutdown, when this sweep can run
+// for every still-active session concurrently.
+const PROCESS_GROUP_POLL_INTERVAL_MS = 200;
+/**
+ * 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 function killProcessGroup(proc, signal) {
+    if (proc.pid === undefined) {
+        // Spawn itself failed (or never produced a pid) — nothing to signal.
+        return;
+    }
+    try {
+        process.kill(-proc.pid, signal);
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code !== 'ESRCH') {
+            logger.warn(`killProcessGroup: unexpected error sending ${signal} to group -${proc.pid}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // ESRCH ("no such process") means the group is already gone — expected,
+        // not an error worth logging (this is the common case for the follow-up
+        // SIGKILL sweep after a clean exit).
+    }
+}
+/**
+ * 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 function isProcessGroupAlive(pid) {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code !== 'ESRCH') {
+            logger.warn(`isProcessGroupAlive: unexpected error probing group -${pid}: ${err instanceof Error ? err.message : String(err)}`);
+            return true;
+        }
+        return false;
+    }
+}
+/**
+ * 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 function sweepProcessGroup(proc, graceMs, options = {}) {
+    return new Promise((resolve) => {
+        if (proc.pid === undefined || !isProcessGroupAlive(proc.pid)) {
+            resolve();
+            return;
+        }
+        const pid = proc.pid;
+        killProcessGroup(proc, 'SIGTERM');
+        const deadline = Date.now() + graceMs;
+        let settled = false;
+        const poll = setInterval(() => {
+            if (settled)
+                return;
+            if (!isProcessGroupAlive(pid)) {
+                settled = true;
+                clearInterval(poll);
+                resolve();
+                return;
+            }
+            if (Date.now() >= deadline) {
+                settled = true;
+                clearInterval(poll);
+                options.onGraceExpired?.();
+                killProcessGroup(proc, 'SIGKILL');
+                resolve();
+            }
+            // Otherwise: still alive, deadline not yet reached — keep polling.
+        }, Math.min(PROCESS_GROUP_POLL_INTERVAL_MS, graceMs));
+        if (options.unref) {
+            poll.unref?.();
+        }
+    });
+}
+/**
+ * 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 function buildSpawnEnv(params) {
+    return {
+        // Secrets platform (#105) injection — SOLE call site of
+        // `SpawnSecretsEnvelope.unwrap()` in the entire poller codebase.
+        // Placed FIRST so subsequent spreads can overwrite. Belt-and-
+        // suspenders: even if the API's reserved-prefix validator fails
+        // (`AWS_`, `TEAMVIBE_`, `SLACK_`, `CLAUDE_CODE_`, `ANTHROPIC_`)
+        // a name collision is silently won by the platform variable
+        // explicit field below.
+        //
+        // Phase 2 of teamvibe.ai#215 (poller v0.5.1): the explicit
+        // `SLACK_BOT_TOKEN: msg.teamvibe.botToken` injection that used
+        // to live here was removed. `SLACK_BOT_TOKEN` now sources from
+        // the `/secrets/spawn` platform overlay (the spread above) —
+        // backend v0.2.2+ resolves it via the `Channel → SlackBot`
+        // relation. Requires backend on Phase 1; pollers on 0.5.0 still
+        // read the explicit field, so split rollout is safe.
+        ...params.spawnSecretsEnv,
+        ...params.processEnv,
+        CLAUDECODE: undefined,
+        // teamvibeai/teamvibe.ai#73 follow-up: strip the poller's own
+        // memory-tuning flags so they don't leak into `claude` — see docstring
+        // above.
+        NODE_OPTIONS: undefined,
+        PATH: params.envPath,
+        CI: 'true',
+        CLAUDE_CONFIG_DIR: params.claudeConfigDir,
+        ...(params.persistentStoragePath && {
+            PERSISTENT_STORAGE_PATH: params.persistentStoragePath,
+        }),
+        ...(params.slackContext && {
+            SLACK_CHANNEL: params.slackContext.channel,
+            SLACK_THREAD_TS: params.slackContext.thread_ts,
+            SLACK_MESSAGE_TS: params.slackContext.message_ts,
+        }),
+        // TeamVibe API env vars for scheduled messages MCP server
+        TEAMVIBE_API_URL: params.teamvibeApiUrl,
+        TEAMVIBE_POLLER_TOKEN: params.teamvibePollerToken,
+        TEAMVIBE_WORKSPACE_ID: params.teamvibeWorkspaceId,
+        TEAMVIBE_CHANNEL_ID: params.teamvibeChannelId,
+        TEAMVIBE_BOT_ID: params.teamvibeBotId,
+        TEAMVIBE_POLLER_ID: params.teamvibePollerId,
+        INBOX_THREAD_ID: params.inboxThreadId,
+        // Stable main-brain path (pre-worktree-rebind `cwd`), NOT `cwd` above —
+        // when worktree isolation is on, `cwd` here is the ephemeral
+        // `.worktrees/<thread_id>/` dir that's removed right after the
+        // session ends. bg-task-runner.mjs writes its .inbox/ checkpoint
+        // drops against this var so they land somewhere still being
+        // watched after the session (and worktree) is gone. See tv#265.
+        POLLER_BRAIN_PATH: params.brainPath,
+    };
+}
 export function buildPrompt(msg, contextHint) {
     const isEmail = msg.source === 'email';
     const isWebhook = msg.source === 'webhook';
@@ -276,6 +537,80 @@ export function buildPrompt(msg, contextHint) {
     }
     return prompt;
 }
+/**
+ * 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 function buildSpawnStdinPlan(prompt, inlineImages, now = Date.now()) {
+    const images = (inlineImages ?? []).filter((img) => img.data || img.url);
+    if (images.length === 0) {
+        // Identical to the single `proc.stdin?.write(prompt)` call that existed
+        // before inline-image support — no extra args, one chunk, no trailing
+        // newline added.
+        return { extraArgs: [], stdinChunks: [prompt] };
+    }
+    const content = [{ type: 'text', text: prompt }];
+    for (const img of images) {
+        if (img.data) {
+            content.push({
+                type: 'image',
+                source: { type: 'base64', media_type: img.mediaType, data: img.data },
+            });
+        }
+        else if (img.url) {
+            // DevGuru review round 1 (non-blocking): the 15-minute presigned-URL
+            // TTL (PRESIGNED_IMAGE_URL_TTL_SECONDS) assumes this session consumes
+            // the URL within seconds of ingest, but SQS FIFO blocks an entire
+            // message group behind one in-flight message — a poller outage or
+            // backlog could leave this message queued long enough for the URL to
+            // expire before it's ever used. A dead URL request would likely just
+            // fail unhelpfully (the `url` source-type sub-path was never
+            // spike-tested end to end — see this function's docstring), so check
+            // expiry here and degrade to a text note instead of sending a URL
+            // that's already dead.
+            // DevGuru review round 2: `new Date(invalid).getTime()` is `NaN`, and
+            // `NaN <= now` is `false` — so a malformed (not missing) `expiresAt`
+            // used to pass through as "fresh" and send a URL whose real freshness
+            // is unknown. Only a genuinely absent `expiresAt` should be trusted
+            // as fresh (see the "no expiresAt at all" defensive case below); an
+            // unparseable one is treated the same as an expired one — fail
+            // toward the text-note degrade, not toward silently sending a URL
+            // that might already be dead.
+            const expiresAtMs = img.expiresAt ? new Date(img.expiresAt).getTime() : undefined;
+            if (expiresAtMs !== undefined && (Number.isNaN(expiresAtMs) || expiresAtMs <= now)) {
+                content.push({
+                    type: 'text',
+                    text: '[inline image expired before it could be sent]',
+                });
+                continue;
+            }
+            // Presigned-URL fallback (email-received.ts Part A step 5). This
+            // `url` source-type sub-path was NOT exercised by the earlier spike
+            // that verified the stream-json plumbing end to end (that spike only
+            // covered `type: 'base64'`) — implemented purely from the documented
+            // Anthropic API content-block shape. Flagged for reviewer attention.
+            content.push({
+                type: 'image',
+                source: { type: 'url', url: img.url },
+            });
+        }
+    }
+    const line = JSON.stringify({ type: 'user', message: { role: 'user', content } });
+    return { extraArgs: ['--input-format', 'stream-json'], stdinChunks: [line, '\n'] };
+}
 function truncateOutput(output, maxLen = 200) {
     const outputStr = typeof output === 'string' ? output : JSON.stringify(output);
     if (outputStr.includes('"type":"base64"') ||
@@ -332,7 +667,39 @@ function formatStreamEvent(event) {
             return null;
     }
 }
-async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = true, lastMessageTs, onMessageSent, typingIndicator) {
+// teamvibe.ai#284: pure extraction of the plain-text portion of an `assistant`
+// stream-json event, so the end-of-turn guard's "what would we deliver as a
+// fallback" logic is unit-testable without spinning up child_process. Mirrors
+// the `case 'assistant':` branch in formatStreamEvent (same content-array
+// shape), but keeps only `text` blocks — `tool_use` blocks are irrelevant
+// here since tool calls are tracked separately via `sawSendMessageCall`.
+// Returns undefined (not '') for "nothing to report" so callers can use a
+// single truthiness check.
+export function extractAssistantText(event) {
+    if (event?.type !== 'assistant' || !Array.isArray(event.message?.content)) {
+        return undefined;
+    }
+    const textParts = event.message.content
+        .filter((c) => c?.type === 'text' && typeof c.text === 'string')
+        .map((c) => c.text);
+    const combined = textParts.join('\n').trim();
+    return combined.length > 0 ? combined : undefined;
+}
+// teamvibe.ai#284 review fix: pure check for whether an `assistant`
+// stream-json event contains a tool_use block calling `toolName`. Mirrors
+// extractAssistantText's content-array parsing — `claude --output-format
+// stream-json` never emits a standalone top-level `tool_use` event; tool_use
+// blocks live nested in `event.message.content[]` (see formatStreamEvent's
+// `case 'assistant':` branch for the same shape). A prior version of this
+// check looked for `event.type === 'tool_use'` directly, which never matches
+// against the real stream shape.
+export function assistantCalledTool(event, toolName) {
+    if (event?.type !== 'assistant' || !Array.isArray(event.message?.content)) {
+        return false;
+    }
+    return event.message.content.some((c) => c?.type === 'tool_use' && c.name === toolName);
+}
+async function runClaudeCode(msg, sessionLog, cwd, brainPath, sessionId, isFirstMessage = true, lastMessageTs, onMessageSent, typingIndicator) {
     const slackContext = msg.response_context.slack;
     const isCronMessage = msg.source === 'cron';
     const isMaintenance = msg.source === 'maintenance';
@@ -381,6 +748,10 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
     });
     return new Promise((resolve) => {
         const prompt = buildPrompt(msg, contextHint);
+        // teamvibe.ai#293 bug 2: decides plain-text vs. stream-json stdin. Empty
+        // `extraArgs`/single-chunk `stdinChunks` (the overwhelming majority of
+        // sessions — no inline images) reproduces the exact prior behavior.
+        const spawnStdinPlan = buildSpawnStdinPlan(prompt, msg.inlineImages);
         // MCP server config passed via --mcp-config flag (no temp files needed)
         const mcpServerPath = join(getBaseBrainPath(), 'mcp', 'slack.mjs');
         const teamvibeApiServerPath = join(getBaseBrainPath(), 'mcp', 'teamvibe-api.mjs');
@@ -397,6 +768,7 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
             '--verbose',
             '--output-format',
             'stream-json',
+            ...spawnStdinPlan.extraArgs,
             '--max-turns',
             '50',
             '--mcp-config',
@@ -442,65 +814,99 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
         sessionLog.info(`Spawning Claude Code with args: ${JSON.stringify(args)}`);
         sessionLog.info(`Working directory: ${cwd}`);
         sessionLog.info(`Prompt length: ${prompt.length} chars`);
+        // Always log the human-readable text prompt only — never the raw
+        // stream-json stdin chunks, which can carry base64 image data that
+        // would otherwise bloat the session log file.
         sessionLog.logPrompt(prompt);
+        if (spawnStdinPlan.extraArgs.length > 0) {
+            const imageCount = (msg.inlineImages ?? []).filter((img) => img.data || img.url).length;
+            sessionLog.info(`Inline image content: ${imageCount} image(s) sent via stream-json stdin (not logged)`);
+        }
         // Prepend persistent bin dir to PATH if configured
         const envPath = config.PERSISTENT_STORAGE_PATH
             ? `${config.PERSISTENT_STORAGE_PATH}/bin:${process.env['PATH'] || ''}`
             : process.env['PATH'];
         const proc = spawn(config.CLAUDE_CLI_PATH, args, {
             cwd,
-            env: {
-                // Secrets platform (#105) injection — SOLE call site of
-                // `SpawnSecretsEnvelope.unwrap()` in the entire poller codebase.
-                // Placed FIRST so subsequent spreads can overwrite. Belt-and-
-                // suspenders: even if the API's reserved-prefix validator fails
-                // (`AWS_`, `TEAMVIBE_`, `SLACK_`, `CLAUDE_CODE_`, `ANTHROPIC_`)
-                // a name collision is silently won by the platform variable
-                // explicit field below.
-                //
-                // Phase 2 of teamvibe.ai#215 (poller v0.5.1): the explicit
-                // `SLACK_BOT_TOKEN: msg.teamvibe.botToken` injection that used
-                // to live here was removed. `SLACK_BOT_TOKEN` now sources from
-                // the `/secrets/spawn` platform overlay (the spread above) —
-                // backend v0.2.2+ resolves it via the `Channel → SlackBot`
-                // relation. Requires backend on Phase 1; pollers on 0.5.0 still
-                // read the explicit field, so split rollout is safe.
-                ...spawnSecrets.env.unwrap(),
-                ...process.env,
-                CLAUDECODE: undefined,
-                PATH: envPath,
-                CI: 'true',
-                CLAUDE_CONFIG_DIR: getBaseBrainPath(),
-                ...(config.PERSISTENT_STORAGE_PATH && {
-                    PERSISTENT_STORAGE_PATH: config.PERSISTENT_STORAGE_PATH,
-                }),
-                ...(slackContext && {
-                    SLACK_CHANNEL: slackContext.channel,
-                    SLACK_THREAD_TS: slackContext.thread_ts,
-                    SLACK_MESSAGE_TS: slackContext.message_ts,
-                }),
-                // TeamVibe API env vars for scheduled messages MCP server
-                TEAMVIBE_API_URL: config.TEAMVIBE_API_URL,
-                TEAMVIBE_POLLER_TOKEN: config.TEAMVIBE_POLLER_TOKEN || '',
-                TEAMVIBE_WORKSPACE_ID: msg.teamvibe.workspaceId,
-                TEAMVIBE_CHANNEL_ID: msg.teamvibe.channelId,
-                TEAMVIBE_BOT_ID: msg.teamvibe.botId,
-                TEAMVIBE_POLLER_ID: getPollerId() || '',
-                INBOX_THREAD_ID: msg.thread_id,
-            },
+            env: buildSpawnEnv({
+                spawnSecretsEnv: spawnSecrets.env.unwrap(),
+                processEnv: process.env,
+                envPath,
+                claudeConfigDir: getBaseBrainPath(),
+                persistentStoragePath: config.PERSISTENT_STORAGE_PATH,
+                slackContext,
+                teamvibeApiUrl: config.TEAMVIBE_API_URL,
+                teamvibePollerToken: config.TEAMVIBE_POLLER_TOKEN || '',
+                teamvibeWorkspaceId: msg.teamvibe.workspaceId,
+                teamvibeChannelId: msg.teamvibe.channelId,
+                teamvibeBotId: msg.teamvibe.botId,
+                teamvibePollerId: getPollerId() || '',
+                inboxThreadId: msg.thread_id,
+                brainPath,
+            }),
             stdio: ['pipe', 'pipe', 'pipe'],
+            // teamvibeai/teamvibe.ai#73: run `claude` (via setsid) as the leader of
+            // its own new process group, separate from the poller's. This is what
+            // makes `killProcessGroup()` below able to reach the MCP server child
+            // processes `claude` itself spawns — signaling `proc` alone never did.
+            // Same trick poller-brain's bg-task.mjs background-task mechanism
+            // already relies on to escape session teardown; orthogonal here since
+            // that mechanism detaches *from* a `claude` session, not `claude`
+            // itself.
+            detached: true,
         });
         // Track active process by message ID and thread ID
         activeProcesses.set(msg.id, proc);
         activeProcessesByThread.set(msg.thread_id, proc);
-        proc.stdin?.write(prompt);
+        for (const chunk of spawnStdinPlan.stdinChunks) {
+            proc.stdin?.write(chunk);
+        }
         proc.stdin?.end();
         let stdout = '';
         let stderr = '';
         let stdoutBuffer = '';
         let metrics;
+        // teamvibe.ai#284 (poller-brain#235): end-of-turn guard state — tracked
+        // across the whole run so the `close` handler can tell poller.ts whether
+        // a successful turn actually delivered anything to Slack.
+        let sawSendMessageCall = false;
+        let lastPlainTextContent;
         let lastActivityTime = Date.now();
         let networkErrorStart = null; // timestamp when continuous network errors began
+        // Set on the first `compact_boundary` system event and held fixed until a
+        // subsequent non-compaction event confirms normal work resumed. While set,
+        // the idle watchdog's kill decision uses this absolute deadline instead of
+        // the default IDLE_WATCHDOG_KILL_MS window — legitimate context compaction
+        // (tv#32) produces no stdout for minutes and must not be killed as a hang.
+        // The deadline is max(original IDLE_WATCHDOG_KILL_MS-from-silence-start,
+        // compact_boundary-arrival-time + IDLE_WATCHDOG_COMPACTION_GRACE_MS) — an
+        // early compact_boundary (well before the original deadline) causes no
+        // extension at all; a late one gets a small fixed grace period instead of
+        // a large speculative ceiling, since compact_boundary only proves
+        // compaction STARTED, never that it will finish in bounded time (a stuck
+        // compaction can hang indefinitely — see anthropics/claude-code#19567).
+        // It never moves further on repeat compact_boundary events in the same run.
+        let compactionKillDeadline = null;
+        // tv#32 Layer B: pending progress-notification timers, and whether a
+        // schedule has already been installed (by the agent's own estimate, or by
+        // the compact_boundary floor-correction below). Cleared on reply/close so
+        // a "still working" ping never fires after the answer already landed.
+        const notificationTimers = [];
+        let notificationScheduleInstalled = false;
+        const clearNotificationTimers = () => {
+            for (const t of notificationTimers)
+                clearTimeout(t);
+            notificationTimers.length = 0;
+        };
+        const scheduleProgressNotifications = (marks) => {
+            for (const minutes of marks) {
+                notificationTimers.push(setTimeout(() => {
+                    sendSlackMessage(msg, `Still working on this — about ${minutes} min in so far.`).catch((err) => {
+                        sessionLog.warn(`[Watchdog] Failed to send progress notification: ${err instanceof Error ? err.message : err}`);
+                    });
+                }, minutes * 60000));
+            }
+        };
         proc.stdout.on('data', (data) => {
             const chunk = data.toString();
             stdout += chunk;
@@ -514,8 +920,41 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
             for (const line of lines) {
                 try {
                     const event = JSON.parse(line);
+                    // Capture the pre-event activity timestamp BEFORE the unconditional
+                    // overwrite below — needed to compute the "original 10min deadline
+                    // from silence start" for a compact_boundary line, since that line
+                    // is itself stdout activity and would otherwise clobber the very
+                    // timestamp the deadline math depends on.
+                    const previousActivityTime = lastActivityTime;
                     // Track activity for idle watchdog
                     lastActivityTime = Date.now();
+                    // tv#32: recognize context compaction so the idle watchdog doesn't
+                    // kill a legitimately-slow (not hung) session. First compact_boundary
+                    // extends the kill deadline (see comment above compactionKillDeadline
+                    // for the max() formula); further compact_boundary events in the same
+                    // run do NOT push it out further. Any other event after one arrives
+                    // means compaction ended — revert to normal idle-from-last-activity
+                    // kill behavior.
+                    if (event.type === 'system' && event.subtype === 'compact_boundary') {
+                        if (compactionKillDeadline === null) {
+                            compactionKillDeadline = computeCompactionKillDeadline(previousActivityTime, Date.now(), config.IDLE_WATCHDOG_KILL_MS, config.IDLE_WATCHDOG_COMPACTION_GRACE_MS);
+                            sessionLog.info(`[Watchdog] Context compaction detected (trigger: ${event.trigger ?? 'unknown'}), ` +
+                                `kill deadline set to ${new Date(compactionKillDeadline).toISOString()}`);
+                        }
+                        // Layer B floor-correction: compaction is objective proof this run
+                        // is legitimately slow. If the agent never called
+                        // set_expected_duration (or hasn't yet), make sure the user still
+                        // gets at least one progress ping instead of relying solely on the
+                        // agent's own — possibly too-optimistic or absent — estimate.
+                        if (!notificationScheduleInstalled) {
+                            notificationScheduleInstalled = true;
+                            scheduleProgressNotifications([5]); // floor: at least one ping, matches the 5-10min tier
+                        }
+                    }
+                    else if (compactionKillDeadline !== null) {
+                        sessionLog.info('[Watchdog] Activity resumed after compaction, reverting to normal idle watchdog');
+                        compactionKillDeadline = null;
+                    }
                     // Extract metrics from result event
                     if (event.type === 'result') {
                         metrics = {
@@ -538,11 +977,32 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
                     if (formatted) {
                         sessionLog.claude('stdout', formatted);
                     }
+                    // teamvibe.ai#284: track the last non-empty plain-text assistant
+                    // content seen, regardless of tool calls — candidate for the
+                    // end-of-turn guard's fallback delivery.
+                    const assistantText = extractAssistantText(event);
+                    if (assistantText) {
+                        lastPlainTextContent = assistantText;
+                    }
                     // Detect when Claude sends a Slack message and clear typing indicator
-                    if (onMessageSent &&
-                        event.type === 'tool_use' &&
-                        event.name === 'mcp__slack__send_message') {
-                        onMessageSent();
+                    if (assistantCalledTool(event, 'mcp__slack__send_message')) {
+                        sawSendMessageCall = true;
+                        onMessageSent?.();
+                        // tv#32 Layer B: the reply landed, no need for further "still
+                        // working" pings for this run.
+                        clearNotificationTimers();
+                    }
+                    // tv#32 Layer B: agent's own estimate of how long this task will
+                    // take drives the progress-notification schedule (never the Layer A
+                    // kill-deadline — see progressNotificationMarks doc comment).
+                    if (event.type === 'tool_use' &&
+                        event.name === 'mcp__slack__set_expected_duration' &&
+                        !notificationScheduleInstalled) {
+                        const minutes = Number(event.input?.minutes);
+                        if (Number.isFinite(minutes) && minutes > 0) {
+                            notificationScheduleInstalled = true;
+                            scheduleProgressNotifications(progressNotificationMarks(minutes));
+                        }
                     }
                     // Auto-update typing indicator status based on tool usage
                     if (typingIndicator) {
@@ -589,8 +1049,10 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
                 channelId: msg.teamvibe.channelId,
             });
             killReasonByProc.set(proc, 'timeout');
-            proc.kill('SIGTERM');
-            setTimeout(() => proc.kill('SIGKILL'), 5000);
+            // #73: signal the whole process group (claude + its MCP children), not
+            // just claude itself.
+            killProcessGroup(proc, 'SIGTERM');
+            setTimeout(() => killProcessGroup(proc, 'SIGKILL'), 5000);
         }, config.CLAUDE_TIMEOUT_MS);
         // Idle watchdog: kill if no stdout activity for too long
         let idleWarned = false;
@@ -607,21 +1069,32 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
                         channelId: msg.teamvibe.channelId,
                     });
                     killReasonByProc.set(proc, 'network');
-                    proc.kill('SIGTERM');
-                    setTimeout(() => proc.kill('SIGKILL'), 5000);
+                    // #73: signal the whole process group, not just claude itself.
+                    killProcessGroup(proc, 'SIGTERM');
+                    setTimeout(() => killProcessGroup(proc, 'SIGKILL'), 5000);
                     return;
                 }
             }
-            if (idleMs > config.IDLE_WATCHDOG_KILL_MS) {
+            // tv#32: while a compaction deadline is set, kill on that fixed absolute
+            // timestamp instead of the idle-from-last-activity window — compaction
+            // legitimately produces no stdout for minutes.
+            const isPastKillDeadline = compactionKillDeadline !== null
+                ? Date.now() >= compactionKillDeadline
+                : idleMs > config.IDLE_WATCHDOG_KILL_MS;
+            if (isPastKillDeadline) {
                 const idleMin = Math.round(idleMs / 60000);
-                logger.error(`Claude Code idle for ${idleMin} minutes, killing process`);
-                emitError('session', `Claude Code idle for ${idleMin} minutes — killing hung process`, {
+                const reason = compactionKillDeadline !== null
+                    ? `idle for ${idleMin} minutes past the compaction ceiling`
+                    : `idle for ${idleMin} minutes`;
+                logger.error(`Claude Code ${reason}, killing process`);
+                emitError('session', `Claude Code ${reason} — killing hung process`, {
                     context: { channelId: msg.teamvibe.channelId, threadId: msg.thread_id },
                     channelId: msg.teamvibe.channelId,
                 });
                 killReasonByProc.set(proc, 'idle');
-                proc.kill('SIGTERM');
-                setTimeout(() => proc.kill('SIGKILL'), 5000);
+                // #73: signal the whole process group, not just claude itself.
+                killProcessGroup(proc, 'SIGTERM');
+                setTimeout(() => killProcessGroup(proc, 'SIGKILL'), 5000);
             }
             else if (!idleWarned && idleMs > config.IDLE_WATCHDOG_WARN_MS) {
                 const idleMin = Math.round(idleMs / 60000);
@@ -631,14 +1104,38 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
                     context: { channelId: msg.teamvibe.channelId, threadId: msg.thread_id },
                     channelId: msg.teamvibe.channelId,
                 });
+                // Surface a visible status so the user isn't left with a stale/generic
+                // indicator during long silent stretches (e.g. context compaction).
+                typingIndicator?.updateStatus('Still working on a long response...');
                 idleWarned = true;
             }
         }, 30000); // Check every 30 seconds
-        proc.on('close', (code) => {
+        proc.on('close', (code, signal) => {
             clearTimeout(timeout);
             clearInterval(idleWatchdog);
+            clearNotificationTimers();
             activeProcesses.delete(msg.id);
             activeProcessesByThread.delete(msg.thread_id);
+            // #73 gap 2 (flagged independently by two reviews): `close` firing means
+            // `claude` itself has exited, but its MCP server children — spawned
+            // into the same detached process group, see `spawn()` above — are not
+            // guaranteed to have exited with it (e.g. one that doesn't clean up on
+            // stdin EOF). This is the *ordinary successful-completion* path, which
+            // none of the timeout/idle/network/zombie kill paths above cover, and
+            // production evidence (a RAM staircase that only resets on container
+            // restart, i.e. grows on every session, not just forced-kill ones)
+            // points at leaks happening here too. Always sweep, even when a kill
+            // path above already ran for this proc — killProcessGroup() is a safe
+            // ESRCH no-op once the group is actually already gone.
+            // Round-2 review item 2: this is a hot path (every session close, not
+            // just rare forced kills) — the ordinary case is `claude` exiting
+            // cleanly and taking its MCP children with it, so the group is
+            // already gone. sweepProcessGroup()'s isProcessGroupAlive() fast-path
+            // skips both the (now-redundant) SIGTERM and the grace-period wait
+            // entirely in that case instead of always paying CLOSE_SWEEP_GRACE_MS.
+            // Fire-and-forget (unref'd) — this is the ordinary-completion path,
+            // not something shutdown() awaits.
+            void sweepProcessGroup(proc, CLOSE_SWEEP_GRACE_MS, { unref: true });
             const killReason = killReasonByProc.get(proc);
             const result = {
                 success: code === 0,
@@ -646,6 +1143,8 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
                 exitCode: code,
                 metrics,
                 modelSource,
+                sawSendMessageCall,
+                lastPlainTextContent,
                 ...(killReason ? { killedByPoller: killReason } : {}),
             };
             if (killReason === 'timeout') {
@@ -661,7 +1160,16 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
                 result.error = 'Killed as zombie process (stale session lock)';
             }
             else if (code !== 0) {
-                result.error = stderr || `Process exited with code ${code}`;
+                // `signal` matters here specifically: a process terminated by a
+                // signal reports `code: null`, not a numeric exit code — e.g. a
+                // cgroup OOM killer's SIGKILL. Before this PR that collapsed into
+                // "Process exited with code null", indistinguishable in logs from
+                // any other unsignaled null-code exit. Now that NODE_OPTIONS no
+                // longer leaks the poller's tiny heap cap into `claude` (see
+                // buildSpawnEnv above), a future OOM is more likely to surface this
+                // way — a cgroup-level SIGKILL — rather than as a V8-level FATAL
+                // ERROR visible in stderr, so this is the replacement visibility.
+                result.error = stderr || (signal ? `Process was killed by signal ${signal}` : `Process exited with code ${code}`);
             }
             resolve(result);
         });
@@ -679,6 +1187,8 @@ async function runClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = t
                 output: stdout,
                 exitCode: null,
                 error: error.message,
+                sawSendMessageCall,
+                lastPlainTextContent,
             });
         });
     });
@@ -691,6 +1201,25 @@ const ISOLATED_SOURCES = new Set(['cron', 'maintenance']);
 function shouldIsolateInWorktree(msg) {
     return isWorktreeIsolationEnabled() && ISOLATED_SOURCES.has(msg.source);
 }
+/**
+ * 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 function finalizeSpawnResult(retryResult, isFirstMessage, effectiveSessionId) {
+    if (isFirstMessage && retryResult.success && effectiveSessionId) {
+        return { ...retryResult, newSessionId: effectiveSessionId };
+    }
+    return retryResult;
+}
 export async function spawnClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMessage = true, lastMessageTs, onMessageSent, typingIndicator) {
     // Worktree isolation: spawned (non-foreground) sessions run in
     // <brain>/.worktrees/<thread_id>/ so the sync-watchdog's reset --hard on
@@ -709,29 +1238,32 @@ export async function spawnClaudeCode(msg, sessionLog, cwd, sessionId, isFirstMe
         }
     }
     try {
-        const result = await runClaudeCode(msg, sessionLog, effectiveCwd, sessionId, isFirstMessage, lastMessageTs, onMessageSent, typingIndicator);
+        // First-message spawns always mint a fresh session ID rather than
+        // recycling whatever placeholder DynamoDB currently holds for this
+        // thread (teamvibe.ai#77) — --resume on non-first messages is unchanged.
+        let effectiveSessionId = sessionId;
+        if (isFirstMessage) {
+            const { randomUUID } = await import('crypto');
+            effectiveSessionId = randomUUID();
+        }
+        const result = await runClaudeCode(msg, sessionLog, effectiveCwd, cwd, effectiveSessionId, 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) {
+        if (!result.success && effectiveSessionId && !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);
+            retryResult = await runClaudeCode(msg, sessionLog, effectiveCwd, cwd, effectiveSessionId, 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));
-            }
+        // If session ID is "already in use" (stale lock file), retry immediately with a
+        // fresh ID — no zombie kill first. Zombie cleanup is #73's concern, not spawn
+        // retry's (teamvibe.ai#77 acceptance criteria: "no zombie kill needed first").
+        if (!retryResult.success && effectiveSessionId && retryResult.error?.includes('already in use')) {
             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 };
+            const freshResult = await runClaudeCode(msg, sessionLog, effectiveCwd, cwd, freshId, true, lastMessageTs, onMessageSent, typingIndicator);
+            return finalizeSpawnResult(freshResult, true, freshId);
         }
-        return retryResult;
+        return finalizeSpawnResult(retryResult, isFirstMessage, effectiveSessionId);
     }
     finally {
         if (worktreeOwner) {
@@ -759,12 +1291,14 @@ export function killZombieForThread(threadId) {
     logger.warn(`Killing zombie process for thread ${threadId} (pid: ${proc.pid})`);
     emitError('session', `Killing zombie process for thread ${threadId}`, { severity: 'warn' });
     killReasonByProc.set(proc, 'zombie');
-    proc.kill('SIGTERM');
-    setTimeout(() => {
-        if (proc.exitCode === null) {
-            proc.kill('SIGKILL');
-        }
-    }, 5000);
+    // #73: signal the whole process group, not just claude itself. The
+    // follow-up SIGKILL sweep always fires after the grace period — it is
+    // NOT gated on `proc.exitCode` here, because `claude` itself can look
+    // exited while its MCP server children are still alive in the same
+    // group (killProcessGroup() is a safe ESRCH no-op if the group is
+    // actually already fully gone by then).
+    killProcessGroup(proc, 'SIGTERM');
+    setTimeout(() => killProcessGroup(proc, 'SIGKILL'), 5000);
     return true;
 }
 export function isAtCapacity() {
@@ -774,23 +1308,87 @@ export function killAllActiveProcesses() {
     if (activeProcesses.size === 0)
         return Promise.resolve();
     logger.info(`Killing ${activeProcesses.size} active Claude process(es)...`);
-    const killPromises = Array.from(activeProcesses.entries()).map(([id, proc]) => new Promise((resolve) => {
-        if (proc.exitCode !== null) {
-            resolve();
-            return;
-        }
-        const forceKillTimer = setTimeout(() => {
-            logger.warn(`Process ${id} did not exit after SIGTERM, sending SIGKILL`);
-            emitError('session', `Process ${id} did not exit after SIGTERM, sending SIGKILL`, { severity: 'warn' });
-            proc.kill('SIGKILL');
-        }, 5000);
-        proc.once('close', () => {
-            clearTimeout(forceKillTimer);
-            resolve();
+    // DevGuru PR#308 round-1 review (non-blocking item 2): both branches below
+    // used to `resolve()` as soon as `claude` itself was observed dead
+    // (immediately, or on `close`), WITHOUT waiting for the scheduled
+    // group-SIGKILL sweep — so the comments here promised a cleanup guarantee
+    // ("leaving any of them running is exactly the leak #73 tracks") that the
+    // actual control flow didn't provide: poller.ts's `shutdown()` typically
+    // reaches `releaseAllActiveLocks()` → drain loop → `process.exit()` in
+    // well under the 5s sweep grace window, so the sweep's own timer would
+    // often die with the process before it ever fired. Fixed by actually
+    // AWAITING the sweep (resolving only once it has run) instead of loosening
+    // the comment to "best-effort" — `shutdown()` already has slack for this:
+    // a 30s drain-loop timeout on the normal path, and a 15s hard cap even on
+    // the circuit-breaker path (poller.ts's `Promise.race([shutdown(...),
+    // sleep(15000)])`), both comfortably above this ~5s, run-once-in-parallel
+    // (not per-process) addition.
+    const killPromises = Array.from(activeProcesses.entries()).map(([id, proc]) => {
+        // The retry-classification fix in poller.ts (round-2 review item 1)
+        // reads this to distinguish an in-flight iteration killed by poller
+        // shutdown from a genuine application failure — without it, a message
+        // caught mid-flight by shutdown could get counted toward MAX_RETRIES
+        // and eventually dropped instead of retried.
+        //
+        // Round-3 review item 3: only set 'shutdown' if no reason is already
+        // recorded for this process. A process can already be marked with a
+        // more specific reason (e.g. 'timeout') whose `close` event just
+        // hasn't fired yet when shutdown begins — unconditionally overwriting
+        // it here would replace the specific reason with the generic one,
+        // surfacing a "Poller is restarting" notice instead of the more
+        // accurate (and deliberately legacy-shaped) timeout message.
+        if (!killReasonByProc.has(proc))
+            killReasonByProc.set(proc, 'shutdown');
+        // Round-2 review item 2: sweepProcessGroup()'s isProcessGroupAlive()
+        // fast-path resolves immediately when the group is already provably
+        // empty, instead of always paying the full 5s grace-period wait — this
+        // matters here specifically because shutdown() (poller.ts) awaits this
+        // whole function BEFORE releaseAllActiveLocks(), and delaying that
+        // costs the next message on the same thread a 15-minute stale-lock
+        // wait. This promise still resolves only once a real sweep has
+        // actually run for a genuinely-still-alive group — not merely once
+        // `claude` itself closes — so the caller genuinely waits out the grace
+        // window instead of racing it. `killProcessGroup()` is a safe ESRCH
+        // no-op if the group is actually already fully gone by the time a
+        // scheduled SIGKILL fires.
+        //
+        // `proc.exitCode !== null` (claude itself already exited before
+        // shutdown started) only suppresses the "didn't fully exit" warning
+        // below — per #73, that alone does NOT mean its MCP server children
+        // (same detached process group) are gone too, so the sweep (and its
+        // fast-path probe) still runs unconditionally either way.
+        const claudeAlreadyExited = proc.exitCode !== null;
+        return sweepProcessGroup(proc, 5000, {
+            onGraceExpired: claudeAlreadyExited
+                ? undefined
+                : () => {
+                    logger.warn(`Process ${id} group did not fully exit after SIGTERM, sending group SIGKILL`);
+                    emitError('session', `Process ${id} group did not fully exit after SIGTERM, sending group SIGKILL`, { severity: 'warn' });
+                },
         });
-        proc.kill('SIGTERM');
-    }));
+    });
     return Promise.all(killPromises).then(() => {
         logger.info('All active processes terminated');
     });
 }
+// Exported for testing only (PR#308 round-3 review item 3). `activeProcesses`
+// and `killReasonByProc` have no other external mutators/readers — production
+// code only ever populates them via the real spawnClaudeCode()/kill-path
+// call sites above. These let a test put a fake process into
+// killAllActiveProcesses()'s input set with a reason already recorded
+// (mirroring the exact race DevGuru described: a process killed for a more
+// specific reason whose `close` handler hasn't run yet when shutdown starts)
+// and then read the reason back afterward, without invoking any real spawn.
+// Same pattern as poller.ts's __setShuttingDownForTest.
+export function __setActiveProcessForTest(id, proc) {
+    activeProcesses.set(id, proc);
+}
+export function __clearActiveProcessesForTest() {
+    activeProcesses.clear();
+}
+export function __setKillReasonForTest(proc, reason) {
+    killReasonByProc.set(proc, reason);
+}
+export function __getKillReasonForTest(proc) {
+    return killReasonByProc.get(proc);
+}