switchroom 0.5.0

package/telegram-plugin/tests/foreman-write-ops.test.ts

@@ -0,0 +1,214 @@
+/**
+ * Tests for Phase 3b foreman write operations:
+ *   - handleRestartCommand (mocked execFileSync)
+ *   - handleDeleteCommand + executeDeleteAgent (mocked exec + FS)
+ *   - handleUpdateCommand (mocked combined exec)
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import {
+  handleRestartCommand,
+  handleDeleteCommand,
+  executeDeleteAgent,
+  handleUpdateCommand,
+  type SwitchroomExecFn,
+} from '../foreman/foreman-handlers.js'
+import type { execFileSync } from 'child_process'
+
+// ─── /restart ─────────────────────────────────────────────────────────────
+
+describe('foreman: handleRestartCommand — input validation', () => {
+  it('returns usage when no agent specified', () => {
+    const result = handleRestartCommand('')
+    expect(result.ok).toBe(false)
+    expect(result.text).toContain('Usage')
+  })
+
+  it('rejects invalid agent name', () => {
+    const execFile = vi.fn()
+    // 'BadName' has uppercase — first token is invalid
+    const result = handleRestartCommand('BadName', execFile as never)
+    expect(result.ok).toBe(false)
+    expect(result.text).toBe('Invalid agent name.')
+    expect(execFile).not.toHaveBeenCalled()
+  })
+
+  it('rejects path traversal', () => {
+    const execFile = vi.fn()
+    const result = handleRestartCommand('../etc/passwd', execFile as never)
+    expect(result.ok).toBe(false)
+    expect(execFile).not.toHaveBeenCalled()
+  })
+
+  it('rejects agent name with colon', () => {
+    const execFile = vi.fn()
+    const result = handleRestartCommand('bad:name', execFile as never)
+    expect(result.ok).toBe(false)
+    expect(execFile).not.toHaveBeenCalled()
+  })
+})
+
+describe('foreman: handleRestartCommand — execFileSync calls', () => {
+  it('calls systemctl --user restart with correct unit name', () => {
+    const execFile = vi.fn().mockReturnValue('')
+    const result = handleRestartCommand('gymbro', execFile as never)
+
+    expect(result.ok).toBe(true)
+    expect(execFile).toHaveBeenCalledOnce()
+    const [cmd, args] = execFile.mock.calls[0] as [string, string[]]
+    expect(cmd).toBe('systemctl')
+    expect(args).toContain('--user')
+    expect(args).toContain('restart')
+    expect(args).toContain('switchroom-gymbro')
+    // Must NOT be a shell string — second arg must be an array
+    expect(Array.isArray(args)).toBe(true)
+  })
+
+  it('uses execFileSync not execSync (no shell)', () => {
+    const execFile = vi.fn().mockReturnValue('')
+    handleRestartCommand('gymbro', execFile as never)
+    // The function is called with 3 args (cmd, args[], opts) not a shell string
+    const [, args] = execFile.mock.calls[0] as [string, string[], object]
+    expect(Array.isArray(args)).toBe(true)
+  })
+
+  it('includes agent name in success reply', () => {
+    const execFile = vi.fn().mockReturnValue('')
+    const result = handleRestartCommand('gymbro', execFile as never)
+    expect(result.ok).toBe(true)
+    expect(result.text).toContain('gymbro')
+  })
+
+  it('returns error text when systemctl fails', () => {
+    const execFile = vi.fn().mockImplementation(() => {
+      throw Object.assign(new Error('unit not found'), { stderr: 'Unit switchroom-gymbro.service not found.' })
+    })
+    const result = handleRestartCommand('gymbro', execFile as never)
+    expect(result.ok).toBe(false)
+    expect(result.text).toContain('restart failed')
+    expect(result.text).toContain('gymbro')
+  })
+
+  it('handles agent name with hyphen', () => {
+    const execFile = vi.fn().mockReturnValue('')
+    handleRestartCommand('my-agent', execFile as never)
+    const [, args] = execFile.mock.calls[0] as [string, string[]]
+    expect(args).toContain('switchroom-my-agent')
+  })
+
+  it('escapes HTML in error output', () => {
+    const execFile = vi.fn().mockImplementation(() => {
+      throw Object.assign(new Error('err'), { stderr: 'Error: <unit> not found' })
+    })
+    const result = handleRestartCommand('gymbro', execFile as never)
+    expect(result.text).not.toContain('<unit>')
+  })
+})
+
+// ─── /delete first step ───────────────────────────────────────────────────
+
+describe('foreman: handleDeleteCommand — prompt', () => {
+  it('returns usage when no agent specified', () => {
+    const result = handleDeleteCommand('')
+    expect(result.replies[0].text).toContain('Usage')
+    expect(result.needsConfirm).toBeFalsy()
+  })
+
+  it('rejects invalid agent name', () => {
+    // 'BadAgent' has uppercase — invalid
+    const result = handleDeleteCommand('BadAgent')
+    expect(result.replies[0].text).toBe('Invalid agent name.')
+    expect(result.needsConfirm).toBeFalsy()
+  })
+
+  it('returns confirmation prompt for valid agent', () => {
+    const result = handleDeleteCommand('gymbro')
+    expect(result.replies[0].text).toContain('gymbro')
+    expect(result.replies[0].text).toContain('YES')
+    expect(result.needsConfirm).toBe(true)
+    expect(result.agentForConfirm).toBe('gymbro')
+  })
+
+  it('escapes HTML in agent name in prompt', () => {
+    // valid name, but let's use one that could trip HTML — actually all valid names
+    // are alphanumeric so no HTML risk; just verify the name appears
+    const result = handleDeleteCommand('my-agent')
+    expect(result.replies[0].text).toContain('my-agent')
+    expect(result.replies[0].html).toBe(true)
+  })
+})
+
+// ─── executeDeleteAgent ───────────────────────────────────────────────────
+
+describe('foreman: executeDeleteAgent — execution', () => {
+  it('runs CLI destroy with --yes flag', () => {
+    const switchroomExec: SwitchroomExecFn = vi.fn().mockReturnValue('Removed unit.')
+    const execFile = vi.fn().mockReturnValue('')
+    const tmpDir = '/tmp/fake-agents-dir'
+
+    const result = executeDeleteAgent('gymbro', switchroomExec, execFile as never, tmpDir)
+    expect(switchroomExec).toHaveBeenCalledWith(['agent', 'destroy', '--yes', 'gymbro'])
+    expect(result.replies[0].text).toContain('gymbro')
+  })
+
+  it('reports success without archive when dir does not exist', () => {
+    const switchroomExec: SwitchroomExecFn = vi.fn().mockReturnValue('done')
+    const result = executeDeleteAgent('gymbro', switchroomExec, vi.fn() as never, '/nonexistent-agents-dir')
+    // No archive reported (dir didn't exist)
+    expect(result.replies[0].text).not.toContain('Archived')
+  })
+
+  it('rejects invalid agent name without calling CLI', () => {
+    const switchroomExec: SwitchroomExecFn = vi.fn()
+    const result = executeDeleteAgent('bad name!', switchroomExec, vi.fn() as never, '/tmp')
+    expect(result.replies[0].text).toBe('Invalid agent name.')
+    expect(switchroomExec).not.toHaveBeenCalled()
+  })
+
+  it('reports CLI error but notes archive succeeded', () => {
+    const switchroomExec: SwitchroomExecFn = vi.fn().mockImplementation(() => {
+      throw Object.assign(new Error('destroy failed'), { stderr: 'switchroom error' })
+    })
+    // Use a dir that definitely doesn't exist so no actual rename
+    const result = executeDeleteAgent('gymbro', switchroomExec, vi.fn() as never, '/nonexistent-agents-12345')
+    expect(result.replies[0].text).toContain('CLI destroy failed')
+  })
+})
+
+// ─── /update ──────────────────────────────────────────────────────────────
+
+describe('foreman: handleUpdateCommand', () => {
+  it('calls switchroomExec with ["update"]', () => {
+    const exec: SwitchroomExecFn = vi.fn().mockReturnValue('Updated successfully.')
+    handleUpdateCommand(exec)
+    expect(exec).toHaveBeenCalledWith(['update'])
+  })
+
+  it('returns output in a pre block', () => {
+    const exec: SwitchroomExecFn = vi.fn().mockReturnValue('Pulled abc123. Reconciled 2 agents.')
+    const result = handleUpdateCommand(exec)
+    expect(result.replies[0].text).toContain('Pulled abc123')
+    expect(result.replies[0].html).toBe(true)
+  })
+
+  it('returns error message when CLI throws', () => {
+    const exec: SwitchroomExecFn = vi.fn().mockImplementation(() => {
+      throw Object.assign(new Error('not a git repo'), { stderr: 'fatal: not a git repository' })
+    })
+    const result = handleUpdateCommand(exec)
+    expect(result.replies[0].text).toContain('update failed')
+  })
+
+  it('returns no-output message when CLI returns empty', () => {
+    const exec: SwitchroomExecFn = vi.fn().mockReturnValue('   \n')
+    const result = handleUpdateCommand(exec)
+    expect(result.replies[0].text).toContain('Update complete')
+  })
+
+  it('paginates output > 3 KB', () => {
+    const bigOutput = 'x'.repeat(4000)
+    const exec: SwitchroomExecFn = vi.fn().mockReturnValue(bigOutput)
+    const result = handleUpdateCommand(exec)
+    expect(result.replies.length).toBeGreaterThan(1)
+  })
+})

package/telegram-plugin/tests/gateway-409-retry-banner.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect } from "vitest";
+
+/**
+ * Regression guard for the false-restart banner bug observed on
+ * 2026-04-22.
+ *
+ * Incident: klanker user received 4+ "⚡ Recovered from unexpected
+ * restart" banners in a 2-minute window while `journalctl --user -u
+ * switchroom-klanker-gateway.service` showed the process PID constant
+ * (1939077 throughout) and zero lifecycle events. The only signal
+ * correlating with the banner-bursts was a stream of 409 Conflict
+ * errors from grammY's long-poll, triggering the gateway's outer
+ * `for (let attempt = 1; ; attempt++)` retry loop to re-enter its
+ * `try { ... }` block. That try-block contains the boot-time
+ * "crash recovery" banner send, so every retry re-posted the banner.
+ *
+ * Fix: a `didOneTimeSetup` boolean guards the one-shot startup blocks
+ * (restart follow-up, crash recovery, pin sweep, setInterval for
+ * auto-fallback poll, bot-command registration). Retries bypass the
+ * guard and go straight to `run(bot)` again.
+ *
+ * These tests model the retry loop's gating contract abstractly so we
+ * can't regress without the test failing. The real retry loop lives
+ * in telegram-plugin/gateway/gateway.ts and telegram-plugin/server.ts.
+ */
+
+/**
+ * Minimal model of the gated retry loop. Returns how many times
+ * each of the two code paths ran over a simulated sequence of
+ * retry attempts.
+ */
+function simulateGatedRetryLoop(numAttempts: number): {
+  oneTimeRuns: number;
+  pollerStartRuns: number;
+} {
+  let didOneTimeSetup = false;
+  let oneTimeRuns = 0;
+  let pollerStartRuns = 0;
+  for (let attempt = 1; attempt <= numAttempts; attempt++) {
+    if (!didOneTimeSetup) {
+      didOneTimeSetup = true;
+      oneTimeRuns += 1; // banner send, pin sweep, setInterval, etc.
+    }
+    pollerStartRuns += 1; // grammY runner.task() — always re-tried
+  }
+  return { oneTimeRuns, pollerStartRuns };
+}
+
+describe("gateway 409-retry banner suppression", () => {
+  it("runs one-shot setup exactly once across many 409 retries", () => {
+    // Matches the 2026-04-22 klanker incident: 4 retries observed.
+    const result = simulateGatedRetryLoop(4);
+    expect(result.oneTimeRuns).toBe(1);
+    expect(result.pollerStartRuns).toBe(4);
+  });
+
+  it("runs one-shot setup exactly once on first attempt (no prior retries)", () => {
+    const result = simulateGatedRetryLoop(1);
+    expect(result.oneTimeRuns).toBe(1);
+    expect(result.pollerStartRuns).toBe(1);
+  });
+
+  it("still only posts once even under a long 409 storm", () => {
+    const result = simulateGatedRetryLoop(100);
+    expect(result.oneTimeRuns).toBe(1);
+    expect(result.pollerStartRuns).toBe(100);
+  });
+
+  it("regression: without the guard, a naive loop would banner-spam", () => {
+    // Models the pre-fix code path. Kept as a sanity check that our
+    // simulator actually distinguishes the two shapes — i.e. the bug
+    // is real and the fix is load-bearing.
+    let oneTimeRuns = 0;
+    for (let attempt = 1; attempt <= 4; attempt++) {
+      oneTimeRuns += 1; // no guard
+    }
+    expect(oneTimeRuns).toBe(4); // matches the 4 banners the user saw
+  });
+});
+
+/**
+ * Direct source-level guard: assert the gating variable exists in
+ * the two files that own the retry loop. Catches refactors that
+ * silently drop the guard.
+ */
+describe("source-level guard present", () => {
+  it("gateway.ts declares didOneTimeSetup before the retry loop", async () => {
+    const fs = await import("node:fs");
+    const src = fs.readFileSync(
+      new URL("../gateway/gateway.ts", import.meta.url),
+      "utf8",
+    );
+    expect(src).toContain("let didOneTimeSetup = false");
+    // After the runWithRetry wire-in, the gate lives inside beforeRun as
+    // `if (didOneTimeSetup) return` (early-exit). Accept either shape so
+    // this guard stays meaningful across refactors.
+    expect(
+      /if\s*\(!didOneTimeSetup\)/.test(src) ||
+        /if\s*\(didOneTimeSetup\)\s*return/.test(src),
+    ).toBe(true);
+    // Sanity-check the banner still exists — fix is gating, not deleting.
+    expect(src).toContain("Recovered from unexpected restart");
+  });
+
+  // #235 Wave 3 F4: server.ts monolith removed; the source-level guard
+  // for `didOneTimeSetup` now only applies to gateway.ts (the single
+  // source of truth). The pre-F4 server.ts `it` block is gone.
+});
+
+/**
+ * Regression guard for the 2026-04-22 banner-cascade bug. Root cause:
+ * server.ts's dual-mode probe used to call rmSync(_gatewaySocket) when
+ * Bun.connect failed, even when the failure was transient and the
+ * gateway was actually alive. Deleting the socket file orphaned the
+ * live listener — every subsequent sidecar spawn then saw
+ * existsSync===false, entered legacy monolith mode, sent a spurious
+ * "⚡ Recovered from unexpected restart" banner, and started polling
+ * the bot token. That polling conflicted with the real gateway's
+ * long-poll (→ 409 Conflict storm) and produced the banner spam the
+ * user saw while PID/systemd were unchanged.
+ *
+ * Fix: the probe logs and falls through on failure, but NEVER deletes
+ * the socket. The gateway owns its socket's lifecycle (ipc-server.ts
+ * already calls unlinkSync at startup for genuine stale-socket
+ * recovery). This test pins that contract at the source level.
+ */
+describe("server.ts dual-mode probe must not delete live gateway socket", () => {
+  it("never calls rmSync on the gateway socket path in the probe block", async () => {
+    const fs = await import("node:fs");
+    const src = fs.readFileSync(
+      new URL("../server.ts", import.meta.url),
+      "utf8",
+    );
+
+    // Isolate the dual-mode block. We key off the block's distinctive
+    // comment header so a rename/move doesn't silently neuter the check.
+    // After Wave 3 F4 (server.ts monolith deleted), the dual-mode block
+    // is essentially the entire file body, so the slice runs to EOF.
+    const blockStart = src.indexOf("─── Dual-mode detection ───");
+    expect(blockStart).toBeGreaterThan(-1);
+    const block = src.slice(blockStart);
+
+    // The probe must not attempt to delete the gateway socket under
+    // any circumstance. rmSync / unlinkSync against _gatewaySocket are
+    // both banned here — the gateway owns lifecycle.
+    expect(block).not.toMatch(/rmSync\s*\(\s*_gatewaySocket/);
+    expect(block).not.toMatch(/unlinkSync\s*\(\s*_gatewaySocket/);
+
+    // The probe must still run (we haven't accidentally removed the
+    // liveness check entirely and reverted to "existsSync → bridge").
+    expect(block).toContain("Bun.connect");
+    expect(block).toContain("_gatewayLive = true");
+  });
+
+  it("documents the no-delete posture in a comment so future edits understand why", async () => {
+    const fs = await import("node:fs");
+    const src = fs.readFileSync(
+      new URL("../server.ts", import.meta.url),
+      "utf8",
+    );
+    // Keep this loose — intent, not exact wording. Any comment in the
+    // dual-mode block mentioning "rmSync" + "never" (or equivalent)
+    // satisfies the guard. We pin at least the rmSync keyword so a
+    // future maintainer grepping for the symbol lands here.
+    const blockStart = src.indexOf("─── Dual-mode detection ───");
+    const blockEnd = src.indexOf(
+      "import { type DraftStreamHandle }",
+      blockStart,
+    );
+    const block = src.slice(blockStart, blockEnd);
+    expect(block).toMatch(/never rmSync/i);
+  });
+});

package/telegram-plugin/tests/gateway-boot-marker-clear.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Structural pin for the boot-time turn-active marker cleanup
+ * (regression coverage for the 2026-05-01 flap-loop incident).
+ *
+ * What broke: an interrupted turn left `<stateDir>/turn-active.json`
+ * on disk. The next gateway boot saw the orphan; the watchdog read its
+ * mtime, computed `age >= TURN_HANG_SECS` (300s default), and
+ * restarted the agent — which killed the gateway mid-cleanup, leaving
+ * the marker again. Result: 2-min flap loop, observed live on `clerk`.
+ *
+ * The fix: gateway calls `removeTurnActiveMarker(STATE_DIR)` once at
+ * boot, inside the `!didOneTimeSetup` block (so it runs only on the
+ * first poll-loop entry, not on every retry attempt). By definition
+ * no turn can be in flight when the gateway just started — any
+ * leftover marker is from a turn that didn't complete.
+ *
+ * The unit tests in `turn-active-marker.test.ts` already cover the
+ * primitive's behaviour. This test pins the *call site* — fails
+ * loudly if a future refactor moves or removes the boot-time clear.
+ */
+
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const GATEWAY_SRC = readFileSync(
+  resolve(__dirname, '..', 'gateway', 'gateway.ts'),
+  'utf8',
+)
+
+describe('gateway boot — clear stale turn-active marker', () => {
+  it('removeTurnActiveMarker is called exactly once inside the !didOneTimeSetup block', () => {
+    // Locate the one-time setup block. It's gated on `!didOneTimeSetup`
+    // and runs after the first successful `bot.api.getMe()` so the
+    // clear only happens once per process lifetime.
+    const setupBlockStart = GATEWAY_SRC.indexOf('if (!didOneTimeSetup)')
+    expect(setupBlockStart).toBeGreaterThan(0)
+
+    // The clear should land near the top of that block — before
+    // pin-sweep, before any boot-card emission. Bound the search
+    // window to ~5KB so we don't pick up the unrelated
+    // `removeTurnActiveMarker` call in the onTurnComplete handler
+    // way down at the bottom of the file.
+    const setupWindow = GATEWAY_SRC.slice(setupBlockStart, setupBlockStart + 5000)
+    const clearMatches = setupWindow.match(/removeTurnActiveMarker\s*\(\s*STATE_DIR\s*\)/g) ?? []
+    expect(clearMatches.length).toBe(1)
+  })
+
+  it('clear is wrapped in try/catch so a disk error never blocks boot', () => {
+    // The clear is best-effort — a transient EBUSY or permission glitch
+    // must not prevent the gateway from coming up. Pin the try-wrapping
+    // to make sure a future refactor doesn't drop it.
+    const setupBlockStart = GATEWAY_SRC.indexOf('if (!didOneTimeSetup)')
+    const setupWindow = GATEWAY_SRC.slice(setupBlockStart, setupBlockStart + 5000)
+    expect(setupWindow).toMatch(/try\s*\{\s*removeTurnActiveMarker\(STATE_DIR\)\s*\}\s*catch/)
+  })
+
+  it('clear runs before the boot-time pin sweep (not after)', () => {
+    // Ordering pin: pin sweep can be slow (many chats × API calls).
+    // Clearing the marker first means the watchdog sees a clean slate
+    // immediately, even if pin sweep takes 30s+ to finish.
+    const setupBlockStart = GATEWAY_SRC.indexOf('if (!didOneTimeSetup)')
+    const setupWindow = GATEWAY_SRC.slice(setupBlockStart, setupBlockStart + 5000)
+    const clearIdx = setupWindow.indexOf('removeTurnActiveMarker(STATE_DIR)')
+    const pinSweepIdx = setupWindow.indexOf('Boot-time pin sweep')
+    expect(clearIdx).toBeGreaterThan(0)
+    expect(pinSweepIdx).toBeGreaterThan(0)
+    expect(clearIdx).toBeLessThan(pinSweepIdx)
+  })
+})