alvin-bot 4.12.1 → 4.12.3

package/test/file-permissions.test.ts

@@ -0,0 +1,130 @@
+/**
+ * v4.12.2 — File permissions hardening.
+ *
+ * Sensitive files (.env, sessions.json, memory files) must be chmod 0o600
+ * so that on multi-user Dev-Server installations, other users on the same
+ * machine can't read Alvin's secrets or conversation history.
+ *
+ * This module provides pure helpers for ensuring files get 0o600 on write,
+ * plus a startup repair routine that fixes permissions on existing files.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import os from "os";
+import { resolve } from "path";
+import { ensureSecureMode, writeSecure, auditSensitiveFiles } from "../src/services/file-permissions.js";
+
+const TEST_DIR = resolve(os.tmpdir(), `alvin-fileperm-${process.pid}-${Date.now()}`);
+
+beforeEach(() => {
+  if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true, force: true });
+  fs.mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterEach(() => {
+  try { fs.rmSync(TEST_DIR, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+describe("file-permissions (v4.12.2)", () => {
+  describe("writeSecure", () => {
+    it("creates a file with mode 0o600", () => {
+      const file = resolve(TEST_DIR, "secret.txt");
+      writeSecure(file, "sensitive content");
+      const mode = fs.statSync(file).mode & 0o777;
+      expect(mode).toBe(0o600);
+      expect(fs.readFileSync(file, "utf-8")).toBe("sensitive content");
+    });
+
+    it("overwrites an existing file and enforces mode 0o600 even if it was 0o644", () => {
+      const file = resolve(TEST_DIR, "existing.txt");
+      fs.writeFileSync(file, "old content", "utf-8");
+      fs.chmodSync(file, 0o644);
+
+      writeSecure(file, "new content");
+
+      const mode = fs.statSync(file).mode & 0o777;
+      expect(mode).toBe(0o600);
+      expect(fs.readFileSync(file, "utf-8")).toBe("new content");
+    });
+
+    it("accepts Buffer content", () => {
+      const file = resolve(TEST_DIR, "buf.bin");
+      writeSecure(file, Buffer.from([1, 2, 3]));
+      expect(fs.statSync(file).mode & 0o777).toBe(0o600);
+    });
+  });
+
+  describe("ensureSecureMode", () => {
+    it("returns 'already-secure' when file is already 0o600", () => {
+      const file = resolve(TEST_DIR, "f.txt");
+      fs.writeFileSync(file, "x");
+      fs.chmodSync(file, 0o600);
+      const result = ensureSecureMode(file);
+      expect(result.status).toBe("already-secure");
+    });
+
+    it("repairs a file that is too permissive (0o644 → 0o600)", () => {
+      const file = resolve(TEST_DIR, "f.txt");
+      fs.writeFileSync(file, "x");
+      fs.chmodSync(file, 0o644);
+      const result = ensureSecureMode(file);
+      expect(result.status).toBe("repaired");
+      expect(result.previousMode).toBe("644");
+      expect(fs.statSync(file).mode & 0o777).toBe(0o600);
+    });
+
+    it("returns 'missing' for a nonexistent file without erroring", () => {
+      const result = ensureSecureMode(resolve(TEST_DIR, "nope.txt"));
+      expect(result.status).toBe("missing");
+    });
+
+    it("is idempotent: calling twice on a 0o644 file still ends at 0o600", () => {
+      const file = resolve(TEST_DIR, "f.txt");
+      fs.writeFileSync(file, "x");
+      fs.chmodSync(file, 0o644);
+      ensureSecureMode(file);
+      const second = ensureSecureMode(file);
+      expect(second.status).toBe("already-secure");
+    });
+
+    it("does NOT try to loosen a stricter-than-needed mode (e.g. 0o400)", () => {
+      const file = resolve(TEST_DIR, "f.txt");
+      fs.writeFileSync(file, "x");
+      fs.chmodSync(file, 0o400);
+      const result = ensureSecureMode(file);
+      expect(result.status).toBe("already-secure");
+      expect(fs.statSync(file).mode & 0o777).toBe(0o400);
+    });
+  });
+
+  describe("auditSensitiveFiles", () => {
+    it("reports a list of files checked and their status", () => {
+      const envFile = resolve(TEST_DIR, ".env");
+      const stateFile = resolve(TEST_DIR, "sessions.json");
+      fs.writeFileSync(envFile, "SECRET=1");
+      fs.chmodSync(envFile, 0o644); // insecure
+      fs.writeFileSync(stateFile, "{}");
+      fs.chmodSync(stateFile, 0o600); // secure
+
+      const report = auditSensitiveFiles([envFile, stateFile]);
+      expect(report).toHaveLength(2);
+
+      const env = report.find(r => r.path === envFile);
+      const state = report.find(r => r.path === stateFile);
+      expect(env!.status).toBe("repaired");
+      expect(state!.status).toBe("already-secure");
+
+      expect(fs.statSync(envFile).mode & 0o777).toBe(0o600);
+    });
+
+    it("skips nonexistent files gracefully", () => {
+      const report = auditSensitiveFiles([
+        resolve(TEST_DIR, "nope.env"),
+        resolve(TEST_DIR, "also-nope.json"),
+      ]);
+      expect(report).toHaveLength(2);
+      expect(report[0].status).toBe("missing");
+      expect(report[1].status).toBe("missing");
+    });
+  });
+});

package/test/session-pending-background.test.ts

@@ -0,0 +1,59 @@
+/**
+ * v4.12.3 — UserSession.pendingBackgroundCount
+ *
+ * When Claude launches an Agent/Task tool with run_in_background: true,
+ * the SDK's CLI subprocess stays alive until the task-notification is
+ * ready to deliver. During that window the main Telegram session is
+ * effectively blocked — isProcessing=true, all new user messages get
+ * queued. For 5-minute+ background tasks that's unacceptable UX.
+ *
+ * v4.12.3 tracks the count of pending background agents on each session
+ * so the handler can detect the blocked state and bypass the SDK resume
+ * (start a fresh SDK session for the new user message while the old
+ * session drains in the background).
+ *
+ * The count is incremented by the message handler on async_launched
+ * tool_result and decremented by the async-agent-watcher when it
+ * delivers the sub-agent's result.
+ */
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+beforeEach(() => vi.resetModules());
+
+describe("UserSession.pendingBackgroundCount (v4.12.3)", () => {
+  it("new session starts with pendingBackgroundCount=0", async () => {
+    const { getSession } = await import("../src/services/session.js");
+    const s = getSession("test-user-new");
+    expect(s.pendingBackgroundCount).toBe(0);
+  });
+
+  it("incrementing on the session persists across getSession calls", async () => {
+    const { getSession } = await import("../src/services/session.js");
+    const s1 = getSession("test-user-inc");
+    s1.pendingBackgroundCount = 2;
+    const s2 = getSession("test-user-inc");
+    expect(s2.pendingBackgroundCount).toBe(2);
+    expect(s1).toBe(s2);
+  });
+
+  it("resetSession zeroes pendingBackgroundCount", async () => {
+    const { getSession, resetSession } = await import("../src/services/session.js");
+    const s = getSession("test-user-reset");
+    s.pendingBackgroundCount = 3;
+    resetSession("test-user-reset");
+    expect(s.pendingBackgroundCount).toBe(0);
+  });
+
+  it("count can be decremented without going negative via explicit guard", async () => {
+    // The handler/watcher code is responsible for not decrementing below
+    // zero. This test just documents that the field is a plain number
+    // with no built-in guard — decrement logic lives in the consumers.
+    const { getSession } = await import("../src/services/session.js");
+    const s = getSession("test-user-dec");
+    s.pendingBackgroundCount = 1;
+    s.pendingBackgroundCount = Math.max(0, s.pendingBackgroundCount - 1);
+    expect(s.pendingBackgroundCount).toBe(0);
+    s.pendingBackgroundCount = Math.max(0, s.pendingBackgroundCount - 1);
+    expect(s.pendingBackgroundCount).toBe(0);
+  });
+});

package/test/subagent-toolset-allowlist.test.ts

@@ -0,0 +1,146 @@
+/**
+ * v4.12.2 — Sub-agent toolset allowlist (Task G).
+ *
+ * Sub-agents can now be spawned with a toolset preset that restricts which
+ * tools Claude has access to:
+ *   - "full"     — all tools (default, matches pre-v4.12.2 behavior)
+ *   - "readonly" — Read, Glob, Grep (analyze, no write, no shell, no net)
+ *   - "research" — Read, Glob, Grep, WebSearch, WebFetch (no write, no shell)
+ *
+ * This test verifies that the preset → allowedTools mapping is correct
+ * and that the provider honors the override. The integration path
+ * (spawnSubAgent → registry.queryWithFallback → claude-sdk-provider) is
+ * exercised via mocked SDK.
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { StreamChunk } from "../src/providers/types.js";
+
+beforeEach(() => vi.resetModules());
+
+describe("claude-sdk-provider honors options.allowedTools (v4.12.2)", () => {
+  it("uses the default full toolset when options.allowedTools is undefined", async () => {
+    let capturedOpts: Record<string, unknown> | undefined;
+    vi.doMock("../src/find-claude-binary.js", () => ({
+      findClaudeBinary: () => "/usr/bin/false",
+    }));
+    vi.doMock("@anthropic-ai/claude-agent-sdk", () => ({
+      query: (opts: { options: Record<string, unknown> }) => {
+        capturedOpts = opts.options;
+        return (async function* () {
+          yield { type: "system", subtype: "init", session_id: "s1" };
+          yield { type: "result", session_id: "s1", total_cost_usd: 0, usage: null };
+        })();
+      },
+    }));
+
+    const { ClaudeSDKProvider } = await import("../src/providers/claude-sdk-provider.js");
+    const provider = new ClaudeSDKProvider();
+
+    for await (const _c of provider.query({ prompt: "test", systemPrompt: "test" })) {
+      void _c;
+    }
+
+    expect(capturedOpts).toBeDefined();
+    expect(capturedOpts!.allowedTools).toEqual([
+      "Read", "Write", "Edit", "Bash", "Glob", "Grep",
+      "WebSearch", "WebFetch", "Task",
+    ]);
+  });
+
+  it("overrides allowedTools when caller passes a restricted list (readonly preset)", async () => {
+    let capturedOpts: Record<string, unknown> | undefined;
+    vi.doMock("../src/find-claude-binary.js", () => ({
+      findClaudeBinary: () => "/usr/bin/false",
+    }));
+    vi.doMock("@anthropic-ai/claude-agent-sdk", () => ({
+      query: (opts: { options: Record<string, unknown> }) => {
+        capturedOpts = opts.options;
+        return (async function* () {
+          yield { type: "system", subtype: "init", session_id: "s1" };
+          yield { type: "result", session_id: "s1", total_cost_usd: 0, usage: null };
+        })();
+      },
+    }));
+
+    const { ClaudeSDKProvider } = await import("../src/providers/claude-sdk-provider.js");
+    const provider = new ClaudeSDKProvider();
+
+    const readonlyTools = ["Read", "Glob", "Grep"];
+    for await (const _c of provider.query({
+      prompt: "test",
+      systemPrompt: "test",
+      allowedTools: readonlyTools,
+    })) {
+      void _c;
+    }
+
+    expect(capturedOpts!.allowedTools).toEqual(readonlyTools);
+    // Critically: Bash, Write, Edit are NOT in the list
+    expect(capturedOpts!.allowedTools).not.toContain("Bash");
+    expect(capturedOpts!.allowedTools).not.toContain("Write");
+    expect(capturedOpts!.allowedTools).not.toContain("Edit");
+  });
+
+  it("overrides allowedTools with research preset (adds web tools)", async () => {
+    let capturedOpts: Record<string, unknown> | undefined;
+    vi.doMock("../src/find-claude-binary.js", () => ({
+      findClaudeBinary: () => "/usr/bin/false",
+    }));
+    vi.doMock("@anthropic-ai/claude-agent-sdk", () => ({
+      query: (opts: { options: Record<string, unknown> }) => {
+        capturedOpts = opts.options;
+        return (async function* () {
+          yield { type: "system", subtype: "init", session_id: "s1" };
+          yield { type: "result", session_id: "s1", total_cost_usd: 0, usage: null };
+        })();
+      },
+    }));
+
+    const { ClaudeSDKProvider } = await import("../src/providers/claude-sdk-provider.js");
+    const provider = new ClaudeSDKProvider();
+
+    const researchTools = ["Read", "Glob", "Grep", "WebSearch", "WebFetch"];
+    for await (const _c of provider.query({
+      prompt: "test",
+      systemPrompt: "test",
+      allowedTools: researchTools,
+    })) {
+      void _c;
+    }
+
+    expect(capturedOpts!.allowedTools).toEqual(researchTools);
+    expect(capturedOpts!.allowedTools).toContain("WebSearch");
+    expect(capturedOpts!.allowedTools).not.toContain("Bash");
+  });
+
+  it("empty allowedTools array is honored as such (no tools at all)", async () => {
+    let capturedOpts: Record<string, unknown> | undefined;
+    vi.doMock("../src/find-claude-binary.js", () => ({
+      findClaudeBinary: () => "/usr/bin/false",
+    }));
+    vi.doMock("@anthropic-ai/claude-agent-sdk", () => ({
+      query: (opts: { options: Record<string, unknown> }) => {
+        capturedOpts = opts.options;
+        return (async function* () {
+          yield { type: "system", subtype: "init", session_id: "s1" };
+          yield { type: "result", session_id: "s1", total_cost_usd: 0, usage: null };
+        })();
+      },
+    }));
+
+    const { ClaudeSDKProvider } = await import("../src/providers/claude-sdk-provider.js");
+    const provider = new ClaudeSDKProvider();
+
+    for await (const _c of provider.query({
+      prompt: "test",
+      systemPrompt: "test",
+      allowedTools: [],
+    })) {
+      void _c;
+    }
+
+    // Empty array → no tools. Note: JS ?? operator treats [] as truthy,
+    // so this IS honored as "empty allowlist" not "use default".
+    expect(capturedOpts!.allowedTools).toEqual([]);
+  });
+});

package/test/subagents-toolset.test.ts

@@ -21,7 +21,7 @@ vi.mock("../src/engine.js", () => ({
   }),
 }));
 
-describe("sub-agents toolset (G1)", () => {
+describe("sub-agents toolset (G1, extended v4.12.2)", () => {
   it("accepts toolset='full'", async () => {
     const mod = await import("../src/services/subagents.js");
     const id = await mod.spawnSubAgent({
@@ -38,13 +38,33 @@ describe("sub-agents toolset (G1)", () => {
     expect(typeof id).toBe("string");
   });
 
+  it("accepts toolset='readonly' (v4.12.2 — read-only sub-agents)", async () => {
+    const mod = await import("../src/services/subagents.js");
+    const id = await mod.spawnSubAgent({
+      name: "tool-readonly",
+      prompt: "hi",
+      toolset: "readonly",
+    });
+    expect(typeof id).toBe("string");
+  });
+
+  it("accepts toolset='research' (v4.12.2 — readonly + web)", async () => {
+    const mod = await import("../src/services/subagents.js");
+    const id = await mod.spawnSubAgent({
+      name: "tool-research",
+      prompt: "hi",
+      toolset: "research",
+    });
+    expect(typeof id).toBe("string");
+  });
+
   it("rejects unknown toolset values at runtime", async () => {
     const mod = await import("../src/services/subagents.js");
     await expect(
       mod.spawnSubAgent({
         name: "tool-bogus",
         prompt: "hi",
-        toolset: "readonly" as unknown as "full",
+        toolset: "nonsense-preset" as unknown as "full",
       }),
     ).rejects.toThrow(/toolset/i);
   });

package/test/timing-safe-bearer.test.ts

@@ -0,0 +1,65 @@
+/**
+ * v4.12.2 — Timing-safe bearer token comparison.
+ *
+ * The webhook auth check at src/web/server.ts:127 previously used naive
+ * string equality on the Authorization header. That's vulnerable (in
+ * principle) to timing side-channel attacks where an attacker measures
+ * response times to leak the token character by character.
+ *
+ * Real-world exploitability over network is low due to jitter, but
+ * crypto.timingSafeEqual is the right tool regardless.
+ *
+ * This test covers the pure helper; the integration is in server.ts.
+ */
+import { describe, it, expect } from "vitest";
+import { timingSafeBearerMatch } from "../src/services/timing-safe-bearer.js";
+
+describe("timing-safe bearer token comparison (v4.12.2)", () => {
+  it("matches a correct token", () => {
+    expect(timingSafeBearerMatch("Bearer abc123xyz", "abc123xyz")).toBe(true);
+  });
+
+  it("rejects an incorrect token", () => {
+    expect(timingSafeBearerMatch("Bearer wrong", "abc123xyz")).toBe(false);
+  });
+
+  it("rejects when Bearer prefix is missing", () => {
+    expect(timingSafeBearerMatch("abc123xyz", "abc123xyz")).toBe(false);
+  });
+
+  it("rejects when auth header is empty", () => {
+    expect(timingSafeBearerMatch("", "abc123xyz")).toBe(false);
+  });
+
+  it("rejects when auth header is undefined", () => {
+    expect(timingSafeBearerMatch(undefined, "abc123xyz")).toBe(false);
+  });
+
+  it("rejects when expected token is empty (prevents accidental auth bypass)", () => {
+    expect(timingSafeBearerMatch("Bearer anything", "")).toBe(false);
+    expect(timingSafeBearerMatch("Bearer ", "")).toBe(false);
+    expect(timingSafeBearerMatch("", "")).toBe(false);
+  });
+
+  it("rejects tokens of different lengths without revealing prefix match", () => {
+    expect(timingSafeBearerMatch("Bearer abc", "abcdefg")).toBe(false);
+    expect(timingSafeBearerMatch("Bearer abcdefg", "abc")).toBe(false);
+  });
+
+  it("handles unicode tokens (not that we'd use them, but correctness)", () => {
+    expect(timingSafeBearerMatch("Bearer 🔒xyz", "🔒xyz")).toBe(true);
+    expect(timingSafeBearerMatch("Bearer 🔒xyz", "🔒xYz")).toBe(false);
+  });
+
+  it("case-sensitive comparison (tokens are opaque)", () => {
+    expect(timingSafeBearerMatch("Bearer AbCdEf", "abcdef")).toBe(false);
+    expect(timingSafeBearerMatch("Bearer AbCdEf", "AbCdEf")).toBe(true);
+  });
+
+  it("rejects Bearer with leading/trailing whitespace mismatches the expected format", () => {
+    // RFC 6750 says: Authorization: Bearer <token>
+    // Exactly one space between "Bearer" and the token.
+    expect(timingSafeBearerMatch("Bearer  abc", "abc")).toBe(false); // double space
+    expect(timingSafeBearerMatch(" Bearer abc", "abc")).toBe(false); // leading space
+  });
+});

package/test/watcher-pending-count.test.ts

@@ -0,0 +1,228 @@
+/**
+ * v4.12.3 — async-agent watcher ↔ session.pendingBackgroundCount wiring.
+ *
+ * Contract:
+ *   - registerPendingAgent takes an optional `sessionKey` so the watcher
+ *     can locate the right UserSession later.
+ *   - When the watcher delivers a result (completed/failed/timeout), the
+ *     session's pendingBackgroundCount MUST be decremented so the main
+ *     handler knows it's safe to resume SDK-session-based queries.
+ *   - Decrement is clamped at 0 — the counter never goes negative even
+ *     if decoupled operations drift.
+ *   - The handler is responsible for INCREMENTING when it registers.
+ *     The watcher only decrements.
+ *
+ * These tests use the shared in-memory session Map from session.ts so
+ * they exercise the actual wiring, not a mock.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import fs from "fs";
+import os from "os";
+import { resolve } from "path";
+
+const TEST_DATA_DIR = resolve(
+  os.tmpdir(),
+  `alvin-watcher-pending-${process.pid}-${Date.now()}`,
+);
+
+beforeEach(async () => {
+  if (fs.existsSync(TEST_DATA_DIR)) {
+    fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true });
+  }
+  fs.mkdirSync(TEST_DATA_DIR, { recursive: true });
+  process.env.ALVIN_DATA_DIR = TEST_DATA_DIR;
+  vi.resetModules();
+  vi.doMock("../src/services/subagent-delivery.js", () => ({
+    deliverSubAgentResult: async () => {},
+    attachBotApi: () => {},
+    __setBotApiForTest: () => {},
+  }));
+});
+
+afterEach(async () => {
+  try {
+    const mod = await import("../src/services/async-agent-watcher.js");
+    mod.stopWatcher();
+    mod.__resetForTest();
+  } catch {
+    /* ignore */
+  }
+});
+
+function writeCompletedJsonl(path: string, finalText: string): void {
+  const lines =
+    [
+      JSON.stringify({
+        type: "user",
+        isSidechain: true,
+        agentId: "x",
+        message: { role: "user", content: "do it" },
+      }),
+      JSON.stringify({
+        type: "assistant",
+        isSidechain: true,
+        agentId: "x",
+        message: {
+          role: "assistant",
+          content: [{ type: "text", text: finalText }],
+          stop_reason: "end_turn",
+          usage: { input_tokens: 10, output_tokens: 5 },
+        },
+      }),
+    ].join("\n") + "\n";
+  fs.mkdirSync(resolve(path, ".."), { recursive: true });
+  fs.writeFileSync(path, lines, "utf-8");
+}
+
+describe("watcher ↔ session.pendingBackgroundCount (v4.12.3)", () => {
+  it("completed delivery decrements pendingBackgroundCount on the right session", async () => {
+    const { getSession } = await import("../src/services/session.js");
+    const watcher = await import("../src/services/async-agent-watcher.js");
+
+    const sessionKey = "v412-session-a";
+    const session = getSession(sessionKey);
+    session.pendingBackgroundCount = 1;
+
+    const outPath = `${TEST_DATA_DIR}/out-a.jsonl`;
+    watcher.registerPendingAgent({
+      agentId: "a",
+      outputFile: outPath,
+      description: "research",
+      prompt: "p",
+      chatId: 42,
+      userId: 42,
+      toolUseId: null,
+      sessionKey,
+    });
+
+    writeCompletedJsonl(outPath, "result");
+    await watcher.pollOnce();
+
+    expect(session.pendingBackgroundCount).toBe(0);
+  });
+
+  it("timeout delivery also decrements the counter", async () => {
+    const { getSession } = await import("../src/services/session.js");
+    const watcher = await import("../src/services/async-agent-watcher.js");
+
+    const sessionKey = "v412-session-timeout";
+    const session = getSession(sessionKey);
+    session.pendingBackgroundCount = 2;
+
+    watcher.registerPendingAgent({
+      agentId: "timed-out",
+      outputFile: `${TEST_DATA_DIR}/never-written.jsonl`,
+      description: "slow task",
+      prompt: "p",
+      chatId: 42,
+      userId: 42,
+      toolUseId: null,
+      sessionKey,
+      giveUpAt: Date.now() - 1000,
+    });
+
+    await watcher.pollOnce();
+
+    expect(session.pendingBackgroundCount).toBe(1);
+  });
+
+  it("failure delivery decrements the counter", async () => {
+    const { getSession } = await import("../src/services/session.js");
+    const watcher = await import("../src/services/async-agent-watcher.js");
+
+    const sessionKey = "v412-session-fail";
+    const session = getSession(sessionKey);
+    session.pendingBackgroundCount = 3;
+
+    const outPath = `${TEST_DATA_DIR}/fail.jsonl`;
+    // Write a malformed "error" state — a single invalid line that will
+    // fall through the parser and stay in "running" state. Then mark
+    // the session as a timeout by moving giveUpAt into the past.
+    // Actually easier: use giveUpAt again as the trigger.
+    watcher.registerPendingAgent({
+      agentId: "fail-via-timeout",
+      outputFile: outPath,
+      description: "will fail",
+      prompt: "p",
+      chatId: 42,
+      userId: 42,
+      toolUseId: null,
+      sessionKey,
+      giveUpAt: Date.now() - 1000,
+    });
+
+    await watcher.pollOnce();
+
+    expect(session.pendingBackgroundCount).toBe(2);
+  });
+
+  it("decrement is clamped at 0 — counter never goes negative", async () => {
+    const { getSession } = await import("../src/services/session.js");
+    const watcher = await import("../src/services/async-agent-watcher.js");
+
+    const sessionKey = "v412-session-drift";
+    const session = getSession(sessionKey);
+    session.pendingBackgroundCount = 0; // drift scenario
+
+    const outPath = `${TEST_DATA_DIR}/drift.jsonl`;
+    watcher.registerPendingAgent({
+      agentId: "drift",
+      outputFile: outPath,
+      description: "drift",
+      prompt: "p",
+      chatId: 42,
+      userId: 42,
+      toolUseId: null,
+      sessionKey,
+    });
+    writeCompletedJsonl(outPath, "done");
+    await watcher.pollOnce();
+
+    expect(session.pendingBackgroundCount).toBe(0);
+  });
+
+  it("missing sessionKey is handled gracefully — no throw, no crash", async () => {
+    const watcher = await import("../src/services/async-agent-watcher.js");
+    const outPath = `${TEST_DATA_DIR}/orphan.jsonl`;
+    watcher.registerPendingAgent({
+      agentId: "orphan",
+      outputFile: outPath,
+      description: "orphan",
+      prompt: "p",
+      chatId: 42,
+      userId: 42,
+      toolUseId: null,
+      // sessionKey intentionally omitted
+    });
+    writeCompletedJsonl(outPath, "done");
+    await expect(watcher.pollOnce()).resolves.not.toThrow();
+  });
+
+  it("multiple agents for the same session all decrement", async () => {
+    const { getSession } = await import("../src/services/session.js");
+    const watcher = await import("../src/services/async-agent-watcher.js");
+
+    const sessionKey = "v412-session-multi";
+    const session = getSession(sessionKey);
+    session.pendingBackgroundCount = 3;
+
+    for (const id of ["m1", "m2", "m3"]) {
+      const outPath = `${TEST_DATA_DIR}/${id}.jsonl`;
+      watcher.registerPendingAgent({
+        agentId: id,
+        outputFile: outPath,
+        description: `task ${id}`,
+        prompt: "p",
+        chatId: 42,
+        userId: 42,
+        toolUseId: null,
+        sessionKey,
+      });
+      writeCompletedJsonl(outPath, `result ${id}`);
+    }
+
+    await watcher.pollOnce();
+
+    expect(session.pendingBackgroundCount).toBe(0);
+  });
+});