switchroom 0.18.12 → 0.18.13

package/telegram-plugin/worktree-watch-cwds.ts

@@ -90,13 +90,30 @@ function defaultDeriveName(agentDir: string): string {
   return leaf;
 }
 
+/**
+ * Two-tier owner-identity resolution shared by `ownedWorktreeCwds` and
+ * `refreshOwnedWorktreeHeartbeats`:
+ *   Tier 1 — env fast path (`SWITCHROOM_AGENT_NAME`).
+ *   Tier 2 — durable fallback derived from the agent's OWN directory basename.
+ * Returns "" when neither source yields a usable identity — callers MUST treat
+ * "" as fail-closed (never guess ownership).
+ */
+export function resolveOwnerIdentity(
+  self: string | undefined,
+  agentDir: string | null | undefined,
+  deriveName?: (agentDir: string) => string,
+): string {
+  let resolved: string = self != null ? self : "";
+  if (resolved === "" && agentDir != null && agentDir !== "") {
+    const derive = deriveName ?? defaultDeriveName;
+    resolved = derive(agentDir) || "";
+  }
+  return resolved;
+}
+
 export function ownedWorktreeCwds(opts: OwnedWorktreeCwdsOptions): string[] {
   // Tier 1: env fast path. Tier 2: durable agentDir-derived fallback.
-  let resolved: string = opts.self != null ? opts.self : "";
-  if (resolved === "" && opts.agentDir != null && opts.agentDir !== "") {
-    const derive = opts.deriveName ?? defaultDeriveName;
-    resolved = derive(opts.agentDir) || "";
-  }
+  const resolved = resolveOwnerIdentity(opts.self, opts.agentDir, opts.deriveName);
 
   if (resolved === "") {
     // Both env and durable config unavailable. Keep the historical
@@ -133,3 +150,175 @@ export function ownedWorktreeCwds(opts: OwnedWorktreeCwdsOptions): string[] {
     return [];
   }
 }
+
+/**
+ * Default minimum interval (ms) between heartbeat writes for the same
+ * worktree record. The gateway invokes the refresh on every ~1s rescan tick;
+ * writing every tick would be needless churn. Refreshing at most every 2 min
+ * keeps every live claim's heartbeat FAR fresher than the reaper's 10-min
+ * `STALE_THRESHOLD_MS`, so a live claim never reads as stale, while a dead
+ * gateway (no ticks) lets the heartbeat age out and become reap-eligible.
+ */
+export const DEFAULT_HEARTBEAT_REFRESH_INTERVAL_MS = 2 * 60_000;
+
+/** Minimal record shape needed to refresh a worktree heartbeat. */
+export interface WorktreeHeartbeatRecord {
+  id: string;
+  ownerAgent?: string;
+  /** ISO 8601 timestamp of the record's current heartbeat (for throttling). */
+  heartbeatAt?: string;
+}
+
+export interface RefreshOwnedHeartbeatsOptions {
+  /** The agent's identity — `process.env.SWITCHROOM_AGENT_NAME` (fast path). */
+  self: string | undefined;
+  /** Durable, non-env identity fallback: the agent's OWN directory. */
+  agentDir?: string | null;
+  /** Host-global registry read (`listRecords` from src/worktree/registry). */
+  listRecords: () => WorktreeHeartbeatRecord[];
+  /** Advance one record's heartbeat (`touchHeartbeat` from the registry). */
+  touchHeartbeat: (id: string) => void;
+  /**
+   * Skip a touch while the record's heartbeat is younger than this (ms).
+   * Defaults to `DEFAULT_HEARTBEAT_REFRESH_INTERVAL_MS`. Set to 0 to always
+   * touch (used by tests).
+   */
+  minRefreshIntervalMs?: number;
+  /** `Date.now` override for tests. */
+  now?: () => number;
+  /** Injectable name derivation (defaults to `path.basename`). */
+  deriveName?: (agentDir: string) => string;
+  /** Best-effort error sink. */
+  log?: (msg: string) => void;
+}
+
+/**
+ * Refresh the heartbeat of every worktree THIS agent owns.
+ *
+ * This is the production driver that keeps `touchHeartbeat` (previously dead —
+ * F1/H3) alive: the gateway calls it on the same rescan tick that re-derives
+ * the watched worktree cwds, so a claim held by a LIVE agent has its heartbeat
+ * advanced continuously and never trips the reaper's staleness gate. When the
+ * owning gateway dies, the ticks stop, the heartbeat ages past
+ * `STALE_THRESHOLD_MS`, and the (now fail-safe) reaper can reclaim the truly
+ * abandoned claim.
+ *
+ * Fail-CLOSED, mirroring `ownedWorktreeCwds`:
+ *   - Unresolved identity ⇒ touch nothing (never guess ownership).
+ *   - Ownerless records (`ownerAgent` undefined) are NEVER matched — we must
+ *     not advance another agent's / an unattributable claim's heartbeat.
+ *   - A registry read failure ⇒ touch nothing.
+ *   - A per-record touch failure is swallowed (logged) — one bad record must
+ *     not abort the rest, and this runs on the hot watch loop.
+ *
+ * @returns the number of heartbeats actually advanced this call.
+ */
+export function refreshOwnedWorktreeHeartbeats(
+  opts: RefreshOwnedHeartbeatsOptions,
+): number {
+  const identity = resolveOwnerIdentity(opts.self, opts.agentDir, opts.deriveName);
+  if (identity === "") return 0; // fail-closed: never guess ownership
+
+  const nowMs = (opts.now ?? Date.now)();
+  const minInterval =
+    opts.minRefreshIntervalMs ?? DEFAULT_HEARTBEAT_REFRESH_INTERVAL_MS;
+
+  let records: WorktreeHeartbeatRecord[];
+  try {
+    records = opts.listRecords();
+  } catch {
+    return 0;
+  }
+
+  let touched = 0;
+  for (const r of records) {
+    if (r.ownerAgent !== identity) continue; // ownerless never matched
+    // Throttle: skip if the heartbeat is still comfortably fresh.
+    if (minInterval > 0 && r.heartbeatAt != null) {
+      const age = nowMs - new Date(r.heartbeatAt).getTime();
+      if (Number.isFinite(age) && age >= 0 && age < minInterval) continue;
+    }
+    try {
+      opts.touchHeartbeat(r.id);
+      touched++;
+    } catch (err) {
+      opts.log?.(
+        `worktree heartbeat refresh failed for ${r.id}: ${(err as Error).message}`,
+      );
+    }
+  }
+  return touched;
+}
+
+/** A registry record carrying everything both watch operations need. */
+export type WorktreeWatchRecord = WorktreeOwnershipRecord & WorktreeHeartbeatRecord;
+
+export interface WorktreeWatchProviderOptions {
+  /** The agent's identity — `process.env.SWITCHROOM_AGENT_NAME` (fast path). */
+  self: string | undefined;
+  /** Durable, non-env identity fallback: the agent's OWN directory. */
+  agentDir?: string | null;
+  /** Host-global registry read (`listRecords` from src/worktree/registry). */
+  listRecords: () => WorktreeWatchRecord[];
+  /** Advance one record's heartbeat (`touchHeartbeat` from the registry). */
+  touchHeartbeat: (id: string) => void;
+  /** Injectable realpath for the cwd derivation (defaults to fs.realpathSync). */
+  realpath?: (p: string) => string;
+  /** Injectable name derivation from `agentDir` (defaults to path.basename). */
+  deriveName?: (agentDir: string) => string;
+  /** Heartbeat throttle window (ms); see refreshOwnedWorktreeHeartbeats. */
+  minRefreshIntervalMs?: number;
+  /** `Date.now` override for tests. */
+  now?: () => number;
+  /** Best-effort log sink shared by both operations. */
+  log?: (msg: string) => void;
+}
+
+/**
+ * Build the `extraWatchCwdsProvider` closure the gateway installs on the
+ * subagent watcher.
+ *
+ * The provider is invoked on every ~1s rescan tick and does TWO things on that
+ * single tick:
+ *   1. advances the heartbeat of every worktree THIS agent owns
+ *      (`refreshOwnedWorktreeHeartbeats` — the production driver that keeps
+ *      `touchHeartbeat` alive; without it every claim reads "stale" 10 min
+ *      after creation and the reaper's staleness guarantee collapses), AND
+ *   2. returns the set of owned worktree cwds for the watcher to also watch
+ *      (`ownedWorktreeCwds`).
+ *
+ * It is extracted from the gateway (rather than inlined) SO THAT the wiring —
+ * specifically that the provider actually DRIVES heartbeats, not merely returns
+ * cwds — is under direct unit test. Deleting the heartbeat refresh here is
+ * caught by the provider's behaviour test (it would return cwds but stop
+ * advancing heartbeats), which the pre-extraction inline closure could not
+ * assert against.
+ *
+ * Both operations use the SAME two-tier identity (env fast path + agentDir
+ * fallback), so a single `agentDir` kill-switch on the caller governs both.
+ * Fully best-effort: neither operation throws out of the returned closure.
+ */
+export function makeWorktreeWatchProvider(
+  opts: WorktreeWatchProviderOptions,
+): () => string[] {
+  return () => {
+    refreshOwnedWorktreeHeartbeats({
+      self: opts.self,
+      agentDir: opts.agentDir,
+      listRecords: opts.listRecords,
+      touchHeartbeat: opts.touchHeartbeat,
+      minRefreshIntervalMs: opts.minRefreshIntervalMs,
+      now: opts.now,
+      deriveName: opts.deriveName,
+      log: opts.log,
+    });
+    return ownedWorktreeCwds({
+      self: opts.self,
+      agentDir: opts.agentDir,
+      listRecords: opts.listRecords,
+      realpath: opts.realpath,
+      deriveName: opts.deriveName,
+      log: opts.log,
+    });
+  };
+}

package/telegram-plugin/secret-detect/secretlint-source.ts

@@ -1,95 +0,0 @@
-/**
- * Secretlint wrapper — adapts `@secretlint/core` + the recommend preset into
- * our `Detection` shape so it can merge with the vendored pattern engine.
- *
- * Secretlint is async (it loads rules, applies preset config, walks the
- * source). This module exposes `detectViaSecretlint(text)` returning a
- * Promise. The synchronous `detectSecrets()` path in `index.ts` stays the
- * fast default; callers that want the full engine use `detectSecretsAsync()`
- * which fans out both and merges.
- *
- * Slug derivation: Secretlint rules don't give us a clean LHS (KEY=value),
- * so we derive from the rule id (e.g. `@secretlint/secretlint-rule-slack`
- * becomes the slug `@secretlint-rule-slack_YYYYMMDD` via `deriveSlug`'s
- * rule_id + date fallback path).
- *
- * Confidence tier: Secretlint is a curated engine with checksum-validated
- * rules for most providers, so every hit is `high`.
- */
-
-import { lintSource } from '@secretlint/core'
-import { creator as presetRecommendCreator } from '@secretlint/secretlint-rule-preset-recommend'
-import type { Detection } from './index.js'
-import { deriveSlug } from './slug.js'
-import { isSuppressed } from './suppressor.js'
-
-/**
- * Map a single Secretlint rule id to a short rule slug used as the
- * `Detection.rule_id`. The full `@secretlint/secretlint-rule-foo` names are
- * long; we strip the scope/prefix to keep rule_ids readable in logs.
- */
-function normalizeRuleId(secretlintRuleId: string): string {
-  // "@secretlint/secretlint-rule-slack" → "secretlint_slack"
-  // "secretlint-rule-custom-thing"       → "secretlint_custom_thing"
-  const stripped = secretlintRuleId
-    .replace(/^@secretlint\//, '')
-    .replace(/^secretlint-rule-/, '')
-    .replace(/[^A-Za-z0-9]+/g, '_')
-    .replace(/_+/g, '_')
-    .replace(/^_+|_+$/g, '')
-  return `secretlint_${stripped || 'unknown'}`
-}
-
-export async function detectViaSecretlint(text: string): Promise<Detection[]> {
-  if (!text || text.length === 0) return []
-
-  let result
-  try {
-    result = await lintSource({
-      source: {
-        content: text,
-        filePath: 'message.txt',
-        ext: '.txt',
-        contentType: 'text',
-      },
-      options: {
-        config: {
-          rules: [
-            {
-              id: '@secretlint/secretlint-rule-preset-recommend',
-              rule: presetRecommendCreator,
-            },
-          ],
-        },
-        noPhysicFilePath: true,
-      },
-    })
-  } catch {
-    // Fail-open: Secretlint crashes must never break the detector path.
-    return []
-  }
-
-  const existing = new Set<string>()
-  const out: Detection[] = []
-  for (const msg of result.messages) {
-    const [start, end] = msg.range
-    if (typeof start !== 'number' || typeof end !== 'number' || end <= start) continue
-    const matched_text = text.slice(start, end)
-    if (!matched_text) continue
-    const rule_id = normalizeRuleId(msg.ruleId)
-    const suggested_slug = deriveSlug({ rule_id }, existing)
-    existing.add(suggested_slug)
-    out.push({
-      rule_id,
-      matched_text,
-      start,
-      end,
-      confidence: 'high',
-      suppressed: isSuppressed(text, start, end),
-      suggested_slug,
-    })
-  }
-  return out
-}
-
-export { normalizeRuleId as __normalizeRuleId }

package/telegram-plugin/tests/secret-detect-secretlint.test.ts

@@ -1,105 +0,0 @@
-import { describe, it, expect } from 'vitest'
-import {
-  detectViaSecretlint,
-  detectSecretsAsync,
-} from '../secret-detect/index.js'
-
-// All three fixtures are assembled at runtime so the source file never
-// contains a contiguous token pattern. Matches the corresponding
-// secretlint regex when evaluated; evades GitHub Push Protection's
-// static-text scan. See CLAUDE.md "Secrets in tests".
-const SLACK_FIXTURE = ['xoxb', '0000000000', '0000000000000', 'FIXTURE0NOTAREALTOKEN000'].join('-')
-const GITHUB_FIXTURE = 'ghp' + '_' + '16C7e42F292c6912E7710c838347Ae178B4a'
-const NPM_FIXTURE = 'npm' + '_' + 'AbCdEfGhIjKlMnOpQrStUvWxYz0123456789'
-
-describe('secretlint-source.detectViaSecretlint', () => {
-  it('catches a realistic-looking Slack bot token', async () => {
-    const text = 'Slack: ' + SLACK_FIXTURE
-    const hits = await detectViaSecretlint(text)
-    expect(hits.length).toBeGreaterThan(0)
-    const slack = hits.find((h) => h.rule_id.includes('slack'))
-    expect(slack).toBeDefined()
-    expect(slack!.confidence).toBe('high')
-    expect(slack!.suppressed).toBe(false)
-    // rule_id normalized from @secretlint/secretlint-rule-slack → secretlint_slack
-    expect(slack!.rule_id).toMatch(/^secretlint_/)
-    expect(slack!.rule_id).toContain('slack')
-    // Matched text should be the actual token bytes.
-    expect(slack!.matched_text.startsWith('xoxb-')).toBe(true)
-    // Slug derived from rule_id + date (rule_id fallback path).
-    expect(slack!.suggested_slug).toMatch(/^secretlint_slack_\d{8}/)
-  })
-
-  it('catches a GitHub personal access token', async () => {
-    const text = 'token=' + GITHUB_FIXTURE + ' rest of message'
-    const hits = await detectViaSecretlint(text)
-    const gh = hits.find((h) => h.rule_id.includes('github'))
-    expect(gh).toBeDefined()
-    expect(gh!.confidence).toBe('high')
-    expect(gh!.matched_text.startsWith('ghp_')).toBe(true)
-    expect(gh!.rule_id).toContain('github')
-  })
-
-  it('catches an NPM access token', async () => {
-    const text = 'NPM_TOKEN=' + NPM_FIXTURE
-    const hits = await detectViaSecretlint(text)
-    const npm = hits.find((h) => h.rule_id.includes('npm'))
-    expect(npm).toBeDefined()
-    expect(npm!.confidence).toBe('high')
-    expect(npm!.matched_text.startsWith('npm_')).toBe(true)
-  })
-
-  it('returns empty for empty input', async () => {
-    expect(await detectViaSecretlint('')).toEqual([])
-  })
-
-  it('returns empty for text with no secrets', async () => {
-    expect(await detectViaSecretlint('hello how are you today')).toEqual([])
-  })
-
-  it('marks nearby test/mock markers as suppressed', async () => {
-    const text = 'test example: ' + SLACK_FIXTURE
-    const hits = await detectViaSecretlint(text)
-    const slack = hits.find((h) => h.rule_id.includes('slack'))
-    expect(slack).toBeDefined()
-    expect(slack!.suppressed).toBe(true)
-  })
-})
-
-describe('detectSecretsAsync merge', () => {
-  it('merges Secretlint hits with vendored pattern hits, deduped by range', async () => {
-    // Slack token that matches both the vendored anchored pattern AND Secretlint.
-    const text = 'a ' + SLACK_FIXTURE + ' end'
-    const hits = await detectSecretsAsync(text)
-    // One entry for the Slack token — not two. Vendored wins on ties.
-    const slackHits = hits.filter(
-      (h) => h.matched_text.startsWith('xoxb-'),
-    )
-    expect(slackHits).toHaveLength(1)
-    // Vendored rule id wins on exact-range ties (listed first in merge).
-    expect(slackHits[0]!.rule_id).toBe('slack_token')
-  })
-
-  it('detects a Shopify token via the async (Secretlint-augmented) path', async () => {
-    // Shopify is now ALSO a vendored PROVIDER_PATTERN (shopify_shared_secret),
-    // so on this span the merge prefers the vendored high hit over the
-    // Secretlint one — both are valid Shopify classifications. Secretlint
-    // remains the fallback for the long tail of providers we don't vendor;
-    // this asserts the async path still detects + classifies the token.
-    const text = 'SHOPIFY=shpss_1234567890abcdef1234567890abcdef and go'
-    const hits = await detectSecretsAsync(text)
-    const shopify = hits.find((h) => h.matched_text.startsWith('shpss_'))
-    expect(shopify).toBeDefined()
-    expect(shopify!.rule_id).toMatch(/shopify/)
-    expect(shopify!.confidence).toBe('high')
-  })
-
-  it('produces unique slugs across the merged detection list', async () => {
-    const text =
-      'tok1=' + GITHUB_FIXTURE +
-      ' and tok2=' + SLACK_FIXTURE
-    const hits = await detectSecretsAsync(text)
-    const slugs = hits.map((h) => h.suggested_slug)
-    expect(new Set(slugs).size).toBe(slugs.length)
-  })
-})