@teamvibe/poller 0.6.2 → 0.7.1

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,11 +59,180 @@ 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;
 }>;
 export declare function getActiveProcessCount(): number;
+export declare function getLastSessionEndTs(): number;
 /**
  * Kill a zombie process for a given thread ID.
  * Returns true if a process was found and killed.
@@ -66,3 +240,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;