@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/lib/triggers/webhook.d.ts

@@ -0,0 +1,85 @@
+/**
+ * GitHub webhook trigger receiver for routines.
+ *
+ * A routine may declare a `trigger` block instead of (or alongside) a cron
+ * `schedule` (see `JobConfig.trigger` in `../routines.ts`). This module turns
+ * an incoming GitHub webhook into the set of routines it should fire, and
+ * dispatches those routines through the exact same path a cron fire uses
+ * (`executeJobDetached`).
+ *
+ * The matching logic (`matchJobsToWebhook`) is a pure, side-effect-free
+ * function so it can be unit-tested without a running daemon or http server.
+ * The optional http listener (`startWebhookServer`) is a thin adapter over it.
+ */
+import * as http from 'http';
+import type { JobConfig, RunMeta } from '../routines.js';
+/**
+ * A parsed GitHub webhook: the event name (from the `X-GitHub-Event` HTTP
+ * header) plus the decoded JSON body. Kept deliberately loose (`payload` is an
+ * arbitrary object) because callers may hand us any of GitHub's event shapes.
+ */
+export interface GithubWebhook {
+    /** The GitHub event name, e.g. `pull_request`, `push`, `issue_comment`. */
+    event: string;
+    /** The decoded JSON request body. */
+    payload: Record<string, unknown>;
+}
+/** Read `repository.full_name` (`owner/name`) from a webhook payload, if present. */
+export declare function webhookRepo(payload: Record<string, unknown>): string | null;
+/**
+ * Extract every candidate branch a webhook payload references, per event type.
+ * A trigger's `branch` matches if it equals any of these. Different events
+ * carry the branch in different places:
+ *   - push:          `ref` (refs/heads/<b>)
+ *   - pull_request:  base + head refs of the PR
+ *   - workflow_run:  `workflow_run.head_branch`
+ *   - issue_comment: no branch (comments aren't branch-scoped)
+ */
+export declare function webhookBranches(event: string, payload: Record<string, unknown>): string[];
+/** True when a single job's trigger matches the given webhook. Pure. */
+export declare function jobMatchesWebhook(job: JobConfig, webhook: GithubWebhook): boolean;
+/**
+ * Pure matcher: given a set of jobs and an incoming webhook, return the jobs
+ * whose `trigger` matches (event + optional repo + optional branch). Jobs
+ * without a trigger (schedule-only routines) are never selected — proving
+ * time-based jobs are unaffected by webhook delivery.
+ */
+export declare function matchJobsToWebhook(jobs: JobConfig[], webhook: GithubWebhook): JobConfig[];
+/** Options for firing webhook-matched jobs (dispatch is injectable for tests). */
+export interface FireWebhookOptions {
+    /** Job source. Defaults to all persisted routines (`listJobs()`). */
+    jobs?: JobConfig[];
+    /**
+     * How to dispatch a matched job. Defaults to `executeJobDetached` — the SAME
+     * path a cron fire uses (see `daemon.ts`). Injectable so tests can assert
+     * matching without spawning real agent processes.
+     */
+    dispatch?: (config: JobConfig) => Promise<RunMeta>;
+}
+/** Result of firing one matched job. */
+export interface FiredJob {
+    jobName: string;
+    runId: string;
+}
+/**
+ * Match an incoming webhook against the persisted routines and fire each match
+ * through the cron dispatch path. Returns one entry per fired job.
+ */
+export declare function fireWebhookJobs(webhook: GithubWebhook, options?: FireWebhookOptions): Promise<FiredJob[]>;
+/** Options for the local webhook http listener. */
+export interface WebhookServerOptions {
+    port?: number;
+    host?: string;
+    /** Override the fire options (mainly for tests). */
+    fire?: FireWebhookOptions;
+    /** Called after each delivery is handled (mainly for tests/observability). */
+    onDelivery?: (event: string, fired: FiredJob[]) => void;
+}
+/**
+ * Start a minimal local webhook receiver. POSTs are read as JSON, the GitHub
+ * event is taken from the `X-GitHub-Event` header, and matching routines are
+ * fired via {@link fireWebhookJobs}. Returns the underlying server so callers
+ * can `close()` it. The heavy lifting is the pure matcher above; this is only
+ * the transport.
+ */
+export declare function startWebhookServer(options?: WebhookServerOptions): http.Server;

package/dist/lib/triggers/webhook.js

@@ -0,0 +1,141 @@
+/**
+ * GitHub webhook trigger receiver for routines.
+ *
+ * A routine may declare a `trigger` block instead of (or alongside) a cron
+ * `schedule` (see `JobConfig.trigger` in `../routines.ts`). This module turns
+ * an incoming GitHub webhook into the set of routines it should fire, and
+ * dispatches those routines through the exact same path a cron fire uses
+ * (`executeJobDetached`).
+ *
+ * The matching logic (`matchJobsToWebhook`) is a pure, side-effect-free
+ * function so it can be unit-tested without a running daemon or http server.
+ * The optional http listener (`startWebhookServer`) is a thin adapter over it.
+ */
+import * as http from 'http';
+import { listJobs } from '../routines.js';
+import { executeJobDetached } from '../runner.js';
+/** Read `repository.full_name` (`owner/name`) from a webhook payload, if present. */
+export function webhookRepo(payload) {
+    const repo = payload?.repository;
+    const fullName = repo?.full_name;
+    return typeof fullName === 'string' && fullName.length > 0 ? fullName : null;
+}
+/** Strip a `refs/heads/` (or `refs/tags/`) prefix to the short branch/tag name. */
+function shortRef(ref) {
+    return ref.replace(/^refs\/(heads|tags)\//, '');
+}
+/**
+ * Extract every candidate branch a webhook payload references, per event type.
+ * A trigger's `branch` matches if it equals any of these. Different events
+ * carry the branch in different places:
+ *   - push:          `ref` (refs/heads/<b>)
+ *   - pull_request:  base + head refs of the PR
+ *   - workflow_run:  `workflow_run.head_branch`
+ *   - issue_comment: no branch (comments aren't branch-scoped)
+ */
+export function webhookBranches(event, payload) {
+    const branches = new Set();
+    const add = (v) => {
+        if (typeof v === 'string' && v.length > 0)
+            branches.add(shortRef(v));
+    };
+    switch (event) {
+        case 'push':
+            add(payload.ref);
+            break;
+        case 'pull_request': {
+            const pr = payload.pull_request;
+            add(pr?.base?.ref);
+            add(pr?.head?.ref);
+            break;
+        }
+        case 'workflow_run': {
+            const run = payload.workflow_run;
+            add(run?.head_branch);
+            break;
+        }
+        default:
+            break;
+    }
+    return [...branches];
+}
+/** True when a single job's trigger matches the given webhook. Pure. */
+export function jobMatchesWebhook(job, webhook) {
+    const trigger = job.trigger;
+    if (!trigger || trigger.type !== 'github_event')
+        return false;
+    if (trigger.event !== webhook.event)
+        return false;
+    if (trigger.repo) {
+        const repo = webhookRepo(webhook.payload);
+        if (!repo || repo.toLowerCase() !== trigger.repo.toLowerCase())
+            return false;
+    }
+    if (trigger.branch) {
+        const branches = webhookBranches(webhook.event, webhook.payload);
+        if (!branches.some((b) => b === trigger.branch))
+            return false;
+    }
+    return true;
+}
+/**
+ * Pure matcher: given a set of jobs and an incoming webhook, return the jobs
+ * whose `trigger` matches (event + optional repo + optional branch). Jobs
+ * without a trigger (schedule-only routines) are never selected — proving
+ * time-based jobs are unaffected by webhook delivery.
+ */
+export function matchJobsToWebhook(jobs, webhook) {
+    return jobs.filter((job) => job.enabled !== false && jobMatchesWebhook(job, webhook));
+}
+/**
+ * Match an incoming webhook against the persisted routines and fire each match
+ * through the cron dispatch path. Returns one entry per fired job.
+ */
+export async function fireWebhookJobs(webhook, options = {}) {
+    const jobs = options.jobs ?? listJobs();
+    const dispatch = options.dispatch ?? executeJobDetached;
+    const matched = matchJobsToWebhook(jobs, webhook);
+    const fired = [];
+    for (const job of matched) {
+        const meta = await dispatch(job);
+        fired.push({ jobName: job.name, runId: meta.runId });
+    }
+    return fired;
+}
+/**
+ * Start a minimal local webhook receiver. POSTs are read as JSON, the GitHub
+ * event is taken from the `X-GitHub-Event` header, and matching routines are
+ * fired via {@link fireWebhookJobs}. Returns the underlying server so callers
+ * can `close()` it. The heavy lifting is the pure matcher above; this is only
+ * the transport.
+ */
+export function startWebhookServer(options = {}) {
+    const server = http.createServer((req, res) => {
+        if (req.method !== 'POST') {
+            res.writeHead(405, { 'content-type': 'text/plain' });
+            res.end('method not allowed');
+            return;
+        }
+        const event = req.headers['x-github-event'] ?? '';
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => {
+            void (async () => {
+                try {
+                    const raw = Buffer.concat(chunks).toString('utf-8');
+                    const payload = raw ? JSON.parse(raw) : {};
+                    const fired = await fireWebhookJobs({ event, payload }, options.fire);
+                    options.onDelivery?.(event, fired);
+                    res.writeHead(200, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: true, fired: fired.map((f) => f.jobName) }));
+                }
+                catch (err) {
+                    res.writeHead(400, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: err.message }));
+                }
+            })();
+        });
+    });
+    server.listen(options.port ?? 0, options.host ?? '127.0.0.1');
+    return server;
+}

package/dist/lib/versions.d.ts

@@ -121,6 +121,12 @@ export declare function getBinaryPath(agent: AgentId, version: string): string;
 export declare function getVersionHomePath(agent: AgentId, version: string): string;
 /**
  * Check if a specific version is installed.
+ *
+ * Probes the actual launch binary (the same executable the shims run), not just
+ * the version dir or the node_modules/.bin/<cli> wrapper. For npm agents that
+ * means statting the package's real `bin` target (getPackageBinaryPath), so a
+ * present-but-gutted install (vendor auto-updater destroyed the binary) reports
+ * as NOT installed and `agents add` re-runs its install step to repair it.
  */
 export declare function isVersionInstalled(agent: AgentId, version: string): boolean;
 /**
@@ -346,6 +352,23 @@ export declare function listRepoNames(): string[];
  * exactly as an unscoped full reconcile does.
  */
 export declare function buildRepoScopedSelection(repo: string, cwd?: string): ResourceSelection;
+/**
+ * Union several ResourceSelections into one, deduping names per kind. Pure — no
+ * FS — so the merge logic is unit-tested without a DotAgents layout. `memory` is
+ * a whole-file merge of the user+system layers, not a per-repo artifact: pass
+ * `includeMemory` to request a full memory write (`'all'`), else the skip
+ * sentinel (`[]`) is kept.
+ */
+export declare function unionResourceSelections(selections: ResourceSelection[], includeMemory: boolean): ResourceSelection;
+/**
+ * Build one selection spanning several DotAgent repos — the source set an
+ * interactive `agents sync` picker collects. Each repo is scoped via
+ * `buildRepoScopedSelection`, then unioned. Memory is written whole when the
+ * `user` or `system` layer is among the selected repos (that's where the memory
+ * file's content comes from); a project-only / alias-only pick leaves it
+ * untouched.
+ */
+export declare function mergeRepoScopedSelections(repos: string[], cwd?: string): ResourceSelection;
 /**
  * Sync central resources (~/.agents/) into a specific version's config directory.
  * Copies selected resources from central storage into {versionHome}/.{agent}/.

package/dist/lib/versions.js

@@ -34,6 +34,7 @@ import { parseMcpServerConfig } from './mcp.js';
 import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink } from './shims.js';
 import { importInstallScriptBinary } from './import.js';
 import { IS_WINDOWS } from './platform/index.js';
+import { pruneVersionHomeHookEntriesFromSettings } from './hooks.js';
 import { supports, explainSkip } from './capabilities.js';
 import { discoverPlugins } from './plugins.js';
 import { loadManifest, saveManifest, buildManifest as buildSyncManifest, isStale } from './staleness/index.js';
@@ -840,12 +841,65 @@ export function getBinaryPath(agent, version) {
 export function getVersionHomePath(agent, version) {
     return path.join(getVersionDir(agent, version), 'home');
 }
+/**
+ * Resolve the REAL launch binary for an npm-package agent version: the file the
+ * installed package's `bin` entry points to — e.g.
+ * node_modules/@anthropic-ai/claude-code/bin/claude.exe on Windows. This is the
+ * executable that the node_modules/.bin/<cli>.cmd wrapper ultimately execs (and
+ * what `agents run` spawns), NOT the wrapper itself.
+ *
+ * The distinction is load-bearing: npm leaves the tiny node_modules/.bin/<cli>
+ * and <cli>.cmd wrappers in place even after a vendor auto-updater destroys the
+ * multi-hundred-MB real binary the wrapper points at. Keying "installed" on the
+ * wrapper (getBinaryPath) — or on the version dir — therefore reports a gutted
+ * install as healthy, and `agents run` then dies at spawn with
+ * "'...claude.exe' is not recognized".
+ *
+ * Returns null for agents without an npm package (grok/droid/installScript,
+ * whose getBinaryPath already resolves the real per-host binary) or when the
+ * installed package.json can't be read/parsed — callers fall back to the
+ * generic getBinaryPath check in those cases.
+ */
+function getPackageBinaryPath(agent, version) {
+    const agentConfig = AGENTS[agent];
+    if (!agentConfig.npmPackage)
+        return null;
+    const pkgRoot = path.join(getVersionDir(agent, version), 'node_modules', agentConfig.npmPackage);
+    let bin;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf-8'));
+        bin = pkg.bin;
+    }
+    catch {
+        return null;
+    }
+    let rel;
+    if (typeof bin === 'string') {
+        rel = bin;
+    }
+    else if (bin && typeof bin === 'object') {
+        const map = bin;
+        // Prefer the entry named after our launch command; else the first bin.
+        rel = map[agentConfig.cliCommand] ?? Object.values(map)[0];
+    }
+    if (!rel || typeof rel !== 'string')
+        return null;
+    return path.join(pkgRoot, rel);
+}
 /**
  * Check if a specific version is installed.
+ *
+ * Probes the actual launch binary (the same executable the shims run), not just
+ * the version dir or the node_modules/.bin/<cli> wrapper. For npm agents that
+ * means statting the package's real `bin` target (getPackageBinaryPath), so a
+ * present-but-gutted install (vendor auto-updater destroyed the binary) reports
+ * as NOT installed and `agents add` re-runs its install step to repair it.
  */
 export function isVersionInstalled(agent, version) {
-    const binaryPath = getBinaryPath(agent, version);
-    return fs.existsSync(binaryPath);
+    const packageBinary = getPackageBinaryPath(agent, version);
+    if (packageBinary !== null)
+        return fs.existsSync(packageBinary);
+    return fs.existsSync(getBinaryPath(agent, version));
 }
 /**
  * Get the latest available version from npm for an agent.
@@ -936,8 +990,10 @@ export function listInstalledVersions(agent) {
     const versions = [];
     for (const entry of entries) {
         if (entry.isDirectory()) {
-            const binaryPath = getBinaryPath(agent, entry.name);
-            if (fs.existsSync(binaryPath)) {
+            // Probe the real launch binary (isVersionInstalled), not just the
+            // node_modules/.bin wrapper — a gutted install must not count as healthy
+            // in the balanced account/version picker.
+            if (isVersionInstalled(agent, entry.name)) {
                 versions.push(entry.name);
             }
         }
@@ -966,7 +1022,7 @@ export function listInstalledVersionDirs(agent) {
             continue;
         out.push({
             version: entry.name,
-            hasBinary: fs.existsSync(getBinaryPath(agent, entry.name)),
+            hasBinary: isVersionInstalled(agent, entry.name),
         });
     }
     return out.sort((a, b) => compareVersions(a.version, b.version));
@@ -1117,7 +1173,7 @@ export async function installVersion(agent, version, onProgress) {
             };
         }
         onProgress?.(`Installing ${packageSpec}...`);
-        const { stdout } = await execFileAsync('npm', ['install', packageSpec], { cwd: versionDir, shell: winShell });
+        const { stdout } = await execFileAsync('npm', ['install', packageSpec, '--ignore-scripts'], { cwd: versionDir, shell: winShell });
         // Determine the actual installed version
         let installedVersion = version;
         if (version === 'latest') {
@@ -1311,16 +1367,20 @@ export function removeVersion(agent, version) {
     }
     // Remove versioned alias (e.g., claude@2.0.65)
     removeVersionedAlias(agent, version);
-    // Clear default if it was the removed version - user must explicitly pick a new one
+    // If the removed version was the global default, keep launchers working:
+    // reassign the default to the newest remaining version, or clear it outright
+    // only when nothing is left. Leaving a dangling default pointer here is what
+    // broke every launcher after removing the pinned default.
     if (getGlobalDefault(agent) === version) {
-        const meta = readMeta();
-        if (meta.agents?.[agent]) {
-            delete meta.agents[agent];
-            writeMeta(meta);
-        }
         const remaining = listInstalledVersions(agent);
         if (remaining.length > 0) {
-            console.log(chalk.yellow(`Default version removed. Run: agents use ${agent}@<version> to set a new default`));
+            const newestRemaining = remaining[remaining.length - 1];
+            setGlobalDefault(agent, newestRemaining);
+            console.log(chalk.yellow(`Default ${agent} was ${version} (removed); reassigned to ${newestRemaining}. Change it with: agents use ${agent}@<version>`));
+        }
+        else {
+            setGlobalDefault(agent, undefined);
+            console.log(chalk.yellow(`Removed the last installed ${agent} version and cleared its default. Reinstall with: agents add ${agent}, then set one with: agents use ${agent}@<version>`));
         }
     }
     // Clean up dangling config symlink if it pointed to the removed version
@@ -1334,6 +1394,18 @@ export function removeVersion(agent, version) {
             // Ignore if already gone
         }
     }
+    // Clear dead per-version hook entries the removed version left behind in the
+    // remaining versions' settings. Their command paths point under the now-gone
+    // version home, so they error on every tool call until the next sync. Scoped
+    // to the Claude-family settings.json format (claude + droid) — the surface
+    // where per-version guard hooks accumulate; other agents self-heal on sync.
+    if (agent === 'claude' || agent === 'droid') {
+        const configDir = agentConfigDirName(agent);
+        for (const remaining of listInstalledVersions(agent)) {
+            const settingsPath = path.join(getVersionHomePath(agent, remaining), configDir, 'settings.json');
+            pruneVersionHomeHookEntriesFromSettings(settingsPath, agent, version);
+        }
+    }
     emit('version.remove', { agent, version });
     return true;
 }
@@ -1715,6 +1787,40 @@ export function buildRepoScopedSelection(repo, cwd = process.cwd()) {
     selection.memory = 'all';
     return selection;
 }
+/**
+ * Union several ResourceSelections into one, deduping names per kind. Pure — no
+ * FS — so the merge logic is unit-tested without a DotAgents layout. `memory` is
+ * a whole-file merge of the user+system layers, not a per-repo artifact: pass
+ * `includeMemory` to request a full memory write (`'all'`), else the skip
+ * sentinel (`[]`) is kept.
+ */
+export function unionResourceSelections(selections, includeMemory) {
+    const merged = {};
+    const kinds = ['commands', 'skills', 'hooks', 'subagents', 'permissions', 'mcp', 'plugins', 'workflows'];
+    for (const sel of selections) {
+        for (const kind of kinds) {
+            const names = sel[kind];
+            if (!Array.isArray(names) || names.length === 0)
+                continue;
+            const existing = merged[kind] ?? [];
+            merged[kind] = Array.from(new Set([...existing, ...names]));
+        }
+    }
+    merged.memory = includeMemory ? 'all' : [];
+    return merged;
+}
+/**
+ * Build one selection spanning several DotAgent repos — the source set an
+ * interactive `agents sync` picker collects. Each repo is scoped via
+ * `buildRepoScopedSelection`, then unioned. Memory is written whole when the
+ * `user` or `system` layer is among the selected repos (that's where the memory
+ * file's content comes from); a project-only / alias-only pick leaves it
+ * untouched.
+ */
+export function mergeRepoScopedSelections(repos, cwd = process.cwd()) {
+    const includeMemory = repos.includes('user') || repos.includes('system');
+    return unionResourceSelections(repos.map((r) => buildRepoScopedSelection(r, cwd)), includeMemory);
+}
 /**
  * Sync central resources (~/.agents/) into a specific version's config directory.
  * Copies selected resources from central storage into {versionHome}/.{agent}/.

package/dist/lib/watchdog/index.d.ts

@@ -0,0 +1,3 @@
+export * from './watchdog.js';
+export * from './watchdogTail.js';
+export * from './read.js';

package/dist/lib/watchdog/index.js

@@ -0,0 +1,5 @@
+// Watchdog stall-detection + nudge-decision core. Pure logic ported from
+// Swarmify; terminal-injection delivery and menu-bar wiring live elsewhere.
+export * from './watchdog.js';
+export * from './watchdogTail.js';
+export * from './read.js';

package/dist/lib/watchdog/read.d.ts

@@ -0,0 +1,35 @@
+/** Default watchdog thresholds, mirrored from the Swarmify VS Code runtime. */
+export declare const WATCHDOG_TAIL_LINES = 20;
+export declare const WATCHDOG_STALL_MS = 300000;
+export declare const WATCHDOG_COOLDOWN_MS = 1200000;
+export declare const WATCHDOG_DORMANT_MS = 3600000;
+/**
+ * Read the last `maxLines` non-empty lines of a JSONL transcript by seeking
+ * backward from EOF in 64KB chunks. A tail that begins mid-line yields one
+ * malformed leading line, which the callers' per-line JSON try/catch tolerates.
+ * Returns `[]` on any read error or empty file.
+ */
+export declare function readTailLines(filePath: string, maxLines: number): string[];
+/**
+ * Given candidate transcript-root directories, find the transcript file for a
+ * session. Handles the flat Claude layout (`<sessionId>.jsonl` inside a
+ * per-project `<enc>/` subfolder), Codex-style names that merely embed the uuid
+ * (`rollout-…-<sessionId>.jsonl`), and — critically — the DEEP date partitions
+ * Codex/Droid use (`sessions/YYYY/MM/DD/rollout-…-<uuid>.jsonl`). The scan is
+ * fully recursive via `walkForFiles` (the same walker session/discover.ts uses),
+ * so no fixed number of subdir levels is assumed — a hand-rolled one-level scan
+ * silently missed every Codex transcript. Newest mtime wins when a uuid appears
+ * in more than one root (e.g. across version homes). Pure over its `dirs`
+ * argument, so it is testable without touching the real home directory.
+ */
+export declare function findSessionJsonlIn(dirs: string[], sessionId: string, ext?: string): string | undefined;
+/**
+ * Resolve a session transcript path from its id + agent, reusing the CLI's
+ * per-version transcript roots. Returns `undefined` if no transcript is found.
+ */
+export declare function resolveWatchdogSessionPath(sessionId: string, agent: string): string | undefined;
+/**
+ * Read the last `maxLines` JSONL lines for a session by id + agent. Returns
+ * `[]` when the transcript cannot be located or read.
+ */
+export declare function readWatchdogTail(sessionId: string, agent: string, maxLines?: number): string[];

package/dist/lib/watchdog/read.js

@@ -0,0 +1,149 @@
+// Watchdog tail reader: locate a session transcript from its id + agent and
+// pull the last N raw JSONL lines. The raw lines feed the pure detectors in
+// watchdog.ts (isLikelyTrulyBlocked / renderWatchdogPrompt) and the pure
+// summarizer in watchdogTail.ts.
+//
+// Adapted from Swarmify's readTailLines (extension/src/vscode/sessions.vscode.ts)
+// to agents-cli's session layout. Path resolution REUSES getAgentSessionDirs()
+// from src/lib/session/discover.ts — the same resolver the rest of the CLI uses
+// to enumerate per-version transcript roots — instead of hardcoding
+// ~/.agents/.history/versions/<agent>/.../projects/<enc>/<sessionId>.jsonl.
+import * as fs from 'fs';
+import * as path from 'path';
+import { getAgentSessionDirs } from '../session/discover.js';
+import { walkForFiles } from '../fs-walk.js';
+/** Default watchdog thresholds, mirrored from the Swarmify VS Code runtime. */
+export const WATCHDOG_TAIL_LINES = 20;
+export const WATCHDOG_STALL_MS = 300_000; // 5m — stallSeconds default
+export const WATCHDOG_COOLDOWN_MS = 1_200_000; // 20m — cooldownSeconds default
+export const WATCHDOG_DORMANT_MS = 3_600_000; // 1h — DORMANT_MS
+const CHUNK_SIZE = 64 * 1024;
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+/** Cap on files walked per transcript root — matches session/discover.ts. */
+const WATCHDOG_WALK_CAP = 100_000;
+/**
+ * Per-agent transcript layout, mirroring the `getAgentSessionDirs()` call sites
+ * in session/discover.ts so the resolver never diverges from the rest of the CLI:
+ * Claude keeps per-project folders under `projects/` (discover.ts:486); Codex and
+ * Droid date-/work-partition rollout `.jsonl` deep under `sessions/`
+ * (discover.ts:665, :1673); Gemini nests chat `.json` under `tmp/<hash>/chats/`
+ * (discover.ts:820). Subdir + extension are driven from this table instead of the
+ * old hardcoded `codex ? 'sessions' : 'projects'` ternary, which sent every
+ * non-Codex agent (Gemini included) to the wrong root.
+ */
+const WATCHDOG_SESSION_LAYOUT = {
+    claude: { subdir: 'projects', ext: '.jsonl' },
+    codex: { subdir: 'sessions', ext: '.jsonl' },
+    droid: { subdir: 'sessions', ext: '.jsonl' },
+    gemini: { subdir: 'tmp', ext: '.json' },
+};
+const WATCHDOG_SESSION_LAYOUT_DEFAULT = { subdir: 'projects', ext: '.jsonl' };
+/**
+ * Read the last `maxLines` non-empty lines of a JSONL transcript by seeking
+ * backward from EOF in 64KB chunks. A tail that begins mid-line yields one
+ * malformed leading line, which the callers' per-line JSON try/catch tolerates.
+ * Returns `[]` on any read error or empty file.
+ */
+export function readTailLines(filePath, maxLines) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+    }
+    catch {
+        return [];
+    }
+    try {
+        const fileSize = fs.fstatSync(fd).size;
+        if (fileSize === 0)
+            return [];
+        let position = fileSize;
+        let buffer = '';
+        let collected = [];
+        while (position > 0 && collected.length <= maxLines) {
+            const readSize = Math.min(CHUNK_SIZE, position);
+            position -= readSize;
+            const chunk = Buffer.alloc(readSize);
+            fs.readSync(fd, chunk, 0, readSize, position);
+            buffer = chunk.toString('utf-8') + buffer;
+            collected = buffer.split(/\r?\n/).filter((l) => l.trim());
+        }
+        return collected.slice(-maxLines);
+    }
+    catch {
+        return [];
+    }
+    finally {
+        try {
+            fs.closeSync(fd);
+        }
+        catch {
+            /* fd already gone */
+        }
+    }
+}
+/**
+ * Given candidate transcript-root directories, find the transcript file for a
+ * session. Handles the flat Claude layout (`<sessionId>.jsonl` inside a
+ * per-project `<enc>/` subfolder), Codex-style names that merely embed the uuid
+ * (`rollout-…-<sessionId>.jsonl`), and — critically — the DEEP date partitions
+ * Codex/Droid use (`sessions/YYYY/MM/DD/rollout-…-<uuid>.jsonl`). The scan is
+ * fully recursive via `walkForFiles` (the same walker session/discover.ts uses),
+ * so no fixed number of subdir levels is assumed — a hand-rolled one-level scan
+ * silently missed every Codex transcript. Newest mtime wins when a uuid appears
+ * in more than one root (e.g. across version homes). Pure over its `dirs`
+ * argument, so it is testable without touching the real home directory.
+ */
+export function findSessionJsonlIn(dirs, sessionId, ext = '.jsonl') {
+    if (!sessionId)
+        return undefined;
+    const matches = (name) => {
+        if (!name.endsWith(ext))
+            return false;
+        const stem = name.slice(0, -ext.length);
+        if (stem === sessionId)
+            return true;
+        // Codex embeds the uuid in a longer filename (rollout-<ts>-<uuid>.jsonl).
+        return name.includes(sessionId) || (UUID_RE.test(sessionId) && stem.includes(sessionId));
+    };
+    let best;
+    for (const dir of dirs) {
+        for (const file of walkForFiles(dir, ext, WATCHDOG_WALK_CAP)) {
+            if (!matches(path.basename(file)))
+                continue;
+            let mtime;
+            try {
+                mtime = fs.statSync(file).mtimeMs;
+            }
+            catch {
+                continue;
+            }
+            if (!best || mtime > best.mtime)
+                best = { file, mtime };
+        }
+    }
+    return best?.file;
+}
+/**
+ * Resolve a session transcript path from its id + agent, reusing the CLI's
+ * per-version transcript roots. Returns `undefined` if no transcript is found.
+ */
+export function resolveWatchdogSessionPath(sessionId, agent) {
+    // Subdir + transcript extension are driven per-agent from WATCHDOG_SESSION_LAYOUT
+    // (which mirrors the getAgentSessionDirs() convention in session/discover.ts),
+    // not a hardcoded `codex ? 'sessions' : 'projects'` — that ternary sent Codex to
+    // a root it only scanned one level deep, and every other agent (Gemini included)
+    // to the wrong subdir entirely.
+    const layout = WATCHDOG_SESSION_LAYOUT[agent] ?? WATCHDOG_SESSION_LAYOUT_DEFAULT;
+    const dirs = getAgentSessionDirs(agent, layout.subdir);
+    return findSessionJsonlIn(dirs, sessionId, layout.ext);
+}
+/**
+ * Read the last `maxLines` JSONL lines for a session by id + agent. Returns
+ * `[]` when the transcript cannot be located or read.
+ */
+export function readWatchdogTail(sessionId, agent, maxLines = WATCHDOG_TAIL_LINES) {
+    const filePath = resolveWatchdogSessionPath(sessionId, agent);
+    if (!filePath)
+        return [];
+    return readTailLines(filePath, maxLines);
+}