agent-relay-server 0.121.5 → 0.122.1

package/runner/src/session-insights.ts

@@ -0,0 +1,118 @@
+// Provider-agnostic core for the #184 context-gathering signal (epic #183).
+//
+// The transcript *format* is provider-specific (Claude JSONL, Codex app-server items,
+// future providers), so each adapter normalizes its session into the same `SessionEvent`
+// stream via `collectSessionEvents`. Everything downstream — the gathering/action
+// classifier and the ratio math — lives here once and is shared, so a tool reclassified
+// for one provider is reclassified for all, and a new provider only implements the
+// normalization.
+//
+// The classifier is model-free and runs in the runner, so it costs zero agent tokens and
+// the agent can't game it.
+
+// A normalized, ordered session event. Order is significant: `leadingGather` counts the
+// run of gathering tools before the first action.
+export type SessionEvent =
+  // A tool invocation. Gathering-vs-action is decided here by `isGatheringTool(name)`.
+  | { type: "tool"; name: string }
+  // A failed tool result (paired outcome proxy — failures/workarounds the agent hit).
+  | { type: "tool_error" }
+  // A real user prompt (paired outcome proxy — more back-and-forth ~ clarification/correction).
+  | { type: "user_prompt" }
+  // A substantive assistant turn (one that produced text or a tool call).
+  | { type: "turn" };
+
+// Tools that acquire context without changing anything. Anything not matched here is
+// treated as an action (mutation, execution, or a delegation/direction decision) — Bash
+// counts as an action because it executes (a conservative, documented choice for v0;
+// `cat`/`ls` via Bash are misclassified, refine later if the data warrants it).
+const GATHERING_TOOLS = new Set([
+  "Read", "Grep", "Glob", "LS", "NotebookRead", "WebFetch", "WebSearch",
+]);
+const GATHERING_NAME = /(?:^|[._-])(read|get|list|search|grep|glob|find|fetch|query|browse|view|show|cat|status|inspect|lookup|symbols|snippet)/i;
+
+export function isGatheringTool(name: string): boolean {
+  if (GATHERING_TOOLS.has(name)) return true;
+  // MCP / custom tools: classify by name shape (e.g. mcp__callmux__searxng_web_search).
+  return GATHERING_NAME.test(name);
+}
+
+interface ContextRatioMetric {
+  /** Session-wide gathering fraction: gatheringCalls / totalToolCalls. The headline metric. */
+  ratio: number;
+  gatheringCalls: number;
+  actionCalls: number;
+  totalToolCalls: number;
+  /** Consecutive gathering calls before the first action — the "read N files before moving" signal. */
+  leadingGather: number;
+  /** Substantive assistant turns (turns that produced text or a tool call). */
+  turns: number;
+}
+
+interface SessionOutcomeProxy {
+  /** Real user prompts in the session — more back-and-forth ~ more clarification/correction. */
+  userPrompts: number;
+  /** tool_result blocks flagged is_error — failures/workarounds the agent hit. */
+  toolErrors: number;
+}
+
+export interface SessionAnalysis {
+  metric: ContextRatioMetric;
+  outcome: SessionOutcomeProxy;
+}
+
+/**
+ * Reduce a normalized event stream to the context-gathering ratio plus paired outcome
+ * proxies. Returns null when there's nothing substantive to measure (no tool calls) —
+ * trivial segments have nothing to learn from and shouldn't pollute the baselines.
+ *
+ * Per-segment by construction: callers pass only the events since the last capture
+ * boundary (compact/clear/restart/shutdown), so each result describes one work chunk.
+ */
+export function computeContextRatio(events: SessionEvent[]): SessionAnalysis | null {
+  let gatheringCalls = 0;
+  let actionCalls = 0;
+  let leadingGather = 0;
+  let sawAction = false;
+  let userPrompts = 0;
+  let toolErrors = 0;
+  let turns = 0;
+
+  for (const event of events) {
+    switch (event.type) {
+      case "user_prompt":
+        userPrompts++;
+        break;
+      case "tool_error":
+        toolErrors++;
+        break;
+      case "turn":
+        turns++;
+        break;
+      case "tool":
+        if (isGatheringTool(event.name)) {
+          gatheringCalls++;
+          if (!sawAction) leadingGather++;
+        } else {
+          actionCalls++;
+          sawAction = true;
+        }
+        break;
+    }
+  }
+
+  const totalToolCalls = gatheringCalls + actionCalls;
+  if (totalToolCalls === 0) return null;
+
+  return {
+    metric: {
+      ratio: gatheringCalls / totalToolCalls,
+      gatheringCalls,
+      actionCalls,
+      totalToolCalls,
+      leadingGather,
+      turns,
+    },
+    outcome: { userPrompts, toolErrors },
+  };
+}

package/runner/src/session-scratch.ts

@@ -0,0 +1,271 @@
+import { execFileSync } from "node:child_process";
+import { accessSync, appendFileSync, constants, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+
+const SCRATCH_DIR_NAME = ".agent-relay";
+// The local-ignore entry. Leading + trailing slash scopes it to the dir at the
+// base, matching git's gitignore semantics.
+const EXCLUDE_ENTRY = "/.agent-relay/";
+const LAUNCHER_DIR = join(tmpdir(), `agent-relay-launchers-${typeof process.getuid === "function" ? process.getuid() : "user"}`);
+const DEFAULT_LAUNCHER_SWEEP_MIN_AGE_MS = 24 * 60 * 60 * 1000;
+
+export interface SessionScratchLayout {
+  baseDir: string; // dir that contains .agent-relay (cwd, or fallback base dir)
+  rootDir: string; // <base>/.agent-relay
+  sessionsDir: string; // <base>/.agent-relay/sessions
+  sessionDir: string; // <base>/.agent-relay/sessions/<id>
+  tmpDir: string; // <base>/.agent-relay/sessions/<id>/tmp
+  replyFile: string; // <tmp>/reply.md
+}
+
+interface SessionScratchTarget {
+  agentId: string;
+  cwd: string;
+  // Orchestrator base dir, used only when cwd is not writable. NEVER home — a
+  // home fallback would place scratch above the orchestrator base dir and break
+  // cwd containment.
+  fallbackBaseDir?: string;
+}
+
+interface SessionLauncherTarget {
+  launcherScript?: string;
+  launcherDir?: string;
+  tmuxSession?: string;
+}
+
+function isWritableDir(dir: string): boolean {
+  try {
+    if (!statSync(dir).isDirectory()) return false;
+    accessSync(dir, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Prefer cwd; fall back to the orchestrator base dir only when cwd is not a
+// writable dir. Returns cwd as a last resort so callers can still attempt mkdir
+// (and surface the real error) rather than silently picking an unrelated path.
+export function resolveScratchBase(cwd: string, fallbackBaseDir?: string): string {
+  if (isWritableDir(cwd)) return cwd;
+  if (fallbackBaseDir && isWritableDir(fallbackBaseDir)) return fallbackBaseDir;
+  return cwd;
+}
+
+function sessionScratchLayout(baseDir: string, agentId: string): SessionScratchLayout {
+  const rootDir = join(baseDir, SCRATCH_DIR_NAME);
+  const sessionsDir = join(rootDir, "sessions");
+  const sessionDir = join(sessionsDir, agentId);
+  const tmpDir = join(sessionDir, "tmp");
+  return { baseDir, rootDir, sessionsDir, sessionDir, tmpDir, replyFile: join(tmpDir, "reply.md") };
+}
+
+// Resolve git's exclude file for baseDir, correctly handling plain repos,
+// worktrees, and submodules (git rev-parse returns the shared commondir's
+// info/exclude). Returns null when baseDir is not inside a git work tree.
+function gitExcludePath(baseDir: string): string | null {
+  try {
+    const out = execFileSync("git", ["-C", baseDir, "rev-parse", "--git-path", "info/exclude"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (!out) return null;
+    return isAbsolute(out) ? out : resolve(baseDir, out);
+  } catch {
+    return null;
+  }
+}
+
+// Idempotently append EXCLUDE_ENTRY to an ignore file (grep-before-write).
+function appendIgnoreEntry(file: string): void {
+  let existing = "";
+  try {
+    existing = readFileSync(file, "utf8");
+  } catch {}
+  const wanted = EXCLUDE_ENTRY.trim();
+  if (existing.split("\n").some((line) => line.trim() === wanted)) return;
+  mkdirSync(dirname(file), { recursive: true });
+  const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  appendFileSync(file, `${prefix}${EXCLUDE_ENTRY}\n`);
+}
+
+// Ensure `.agent-relay/` is locally ignored. Prefers .git/info/exclude (git's
+// local, uncommitted ignore list) so no tracked file is ever modified; falls
+// back to .gitignore only when baseDir is not a git repo. Returns which file was
+// used (for logging/tests).
+export function ensureScratchIgnored(baseDir: string): "exclude" | "gitignore" {
+  const excludePath = gitExcludePath(baseDir);
+  if (excludePath) {
+    appendIgnoreEntry(excludePath);
+    return "exclude";
+  }
+  appendIgnoreEntry(join(baseDir, ".gitignore"));
+  return "gitignore";
+}
+
+// SessionStart: create the session tmp dir and ensure local ignore. Dir
+// creation is the load-bearing part; ignore setup is best-effort.
+export function ensureSessionScratch(target: SessionScratchTarget): SessionScratchLayout {
+  const base = resolveScratchBase(target.cwd, target.fallbackBaseDir);
+  const layout = sessionScratchLayout(base, target.agentId);
+  mkdirSync(layout.tmpDir, { recursive: true });
+  try {
+    ensureScratchIgnored(base);
+  } catch {
+    // best-effort: a missing ignore entry never pollutes git because the dir is
+    // already created and the entry is the only thing at risk.
+  }
+  return layout;
+}
+
+function resolveLauncherDir(launcherDir?: string): string {
+  return launcherDir ?? LAUNCHER_DIR;
+}
+
+export function launcherScriptPathForSession(sessionName: string, launcherDir?: string): string {
+  const sanitized = sanitizeFsName(sessionName, { replacement: "-", collapse: false });
+  return join(resolveLauncherDir(launcherDir), `${sanitized}.sh`);
+}
+
+function dedupeBases(bases: Array<string | undefined>): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const b of bases) {
+    if (!b || seen.has(b)) continue;
+    seen.add(b);
+    out.push(b);
+  }
+  return out;
+}
+
+function dedupePaths(paths: Array<string | undefined>): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const path of paths) {
+    if (!path || seen.has(path)) continue;
+    seen.add(path);
+    out.push(path);
+  }
+  return out;
+}
+
+// SessionEnd: remove this session's dir from every candidate base.
+export function reapSessionScratch(target: SessionScratchTarget): void {
+  for (const base of dedupeBases([target.cwd, target.fallbackBaseDir])) {
+    const { sessionDir } = sessionScratchLayout(base, target.agentId);
+    try {
+      rmSync(sessionDir, { recursive: true, force: true });
+    } catch {}
+  }
+}
+
+// Claude headless sessions externalize their provider launch command into a
+// per-session script under /tmp. Remove it on runner shutdown alongside the
+// scratch dir reap to avoid leaking one file per spawn.
+export function reapSessionLauncher(target: SessionLauncherTarget): string[] {
+  const removed: string[] = [];
+  for (const path of dedupePaths([
+    target.launcherScript,
+    target.tmuxSession ? launcherScriptPathForSession(target.tmuxSession, target.launcherDir) : undefined,
+  ])) {
+    try {
+      const exists = statSync(path).isFile();
+      rmSync(path, { force: true });
+      if (exists) removed.push(path);
+    } catch {}
+  }
+  return removed;
+}
+
+interface SweepOptions {
+  cwd: string;
+  fallbackBaseDir?: string;
+  // Agent ids to keep (currently-known agents + self). Any session dir whose id
+  // is not in this set AND older than minAgeMs is removed.
+  keepAgentIds: Set<string>;
+  now: number;
+  minAgeMs?: number;
+}
+
+interface LauncherSweepOptions {
+  // Agent ids to keep (currently-known agents + self). Launcher scripts embed
+  // AGENT_RELAY_ID, so a stale sweep can safely remove only scripts whose agent
+  // is no longer live.
+  keepAgentIds: Set<string>;
+  launcherDir?: string;
+  now: number;
+  minAgeMs?: number;
+}
+
+function maybeShellUnquote(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("'") || !trimmed.endsWith("'")) return trimmed;
+  return trimmed.slice(1, -1).replace(/'\\''/g, "'");
+}
+
+function launcherAgentId(scriptPath: string): string | null {
+  try {
+    const match = readFileSync(scriptPath, "utf8").match(/^export AGENT_RELAY_ID=(.+)$/m);
+    if (!match) return null;
+    const agentId = maybeShellUnquote(match[1] ?? "");
+    return agentId || null;
+  } catch {
+    return null;
+  }
+}
+
+// Periodic sweep of leftover session dirs from agents no longer known to the
+// relay. The minAgeMs grace avoids racing a peer that just created its dir but
+// has not yet appeared in the agent list.
+export function sweepStaleSessions(opts: SweepOptions): string[] {
+  const minAge = opts.minAgeMs ?? 60 * 60 * 1000;
+  const removed: string[] = [];
+  for (const base of dedupeBases([opts.cwd, opts.fallbackBaseDir])) {
+    const sessionsDir = join(base, SCRATCH_DIR_NAME, "sessions");
+    let ids: string[];
+    try {
+      ids = readdirSync(sessionsDir);
+    } catch {
+      continue;
+    }
+    for (const id of ids) {
+      if (opts.keepAgentIds.has(id)) continue;
+      const dir = join(sessionsDir, id);
+      try {
+        if (opts.now - statSync(dir).mtimeMs < minAge) continue;
+        rmSync(dir, { recursive: true, force: true });
+        removed.push(dir);
+      } catch {}
+    }
+  }
+  return removed;
+}
+
+// Periodic sweep of leaked per-spawn launcher scripts. Old scripts whose agent
+// id is no longer live are safe to prune; old unparsable files are treated as
+// stale too so the next run clears historical buildup without manual cleanup.
+export function sweepStaleLaunchers(opts: LauncherSweepOptions): string[] {
+  const minAge = opts.minAgeMs ?? DEFAULT_LAUNCHER_SWEEP_MIN_AGE_MS;
+  const removed: string[] = [];
+  const launcherDir = resolveLauncherDir(opts.launcherDir);
+  let entries: string[];
+  try {
+    entries = readdirSync(launcherDir);
+  } catch {
+    return removed;
+  }
+  for (const entry of entries) {
+    const scriptPath = join(launcherDir, entry);
+    try {
+      if (!statSync(scriptPath).isFile()) continue;
+      if (opts.now - statSync(scriptPath).mtimeMs < minAge) continue;
+      const agentId = launcherAgentId(scriptPath);
+      if (agentId && opts.keepAgentIds.has(agentId)) continue;
+      rmSync(scriptPath, { force: true });
+      removed.push(scriptPath);
+    } catch {}
+  }
+  return removed;
+}

package/runner/src/template-resolver.ts

@@ -0,0 +1,29 @@
+import type { RelayHttpClient } from "agent-relay-sdk";
+import { RUNNER_PROMPT_TEMPLATE_DEFAULTS } from "agent-relay-sdk/prompt-template-defaults";
+
+const RUNNER_DEFAULTS = new Map<string, string>(RUNNER_PROMPT_TEMPLATE_DEFAULTS.map((template) => [template.slug, template.defaultTemplate]));
+const templateCache = new Map<string, string>();
+
+function renderValue(value: string | undefined): string {
+  return value ?? "";
+}
+
+function applyVariables(template: string, vars: Record<string, string>): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key: string) => renderValue(vars[key]));
+}
+
+export async function initializeRunnerTemplates(http: RelayHttpClient): Promise<void> {
+  try {
+    const templates = await http.listPromptTemplates();
+    templateCache.clear();
+    for (const template of templates) templateCache.set(template.slug, template.template);
+  } catch {
+    templateCache.clear();
+  }
+}
+
+export function renderRunnerTemplate(slug: string, vars: Record<string, string> = {}): string {
+  const template = templateCache.get(slug) ?? RUNNER_DEFAULTS.get(slug);
+  if (template === undefined) throw new Error(`unknown runner prompt template slug: ${slug}`);
+  return applyVariables(template, vars);
+}

package/runner/src/version.ts

@@ -0,0 +1,43 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONTRACT_VERSIONS } from "agent-relay-sdk";
+import { getManifest } from "agent-relay-providers";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8")) as { name?: string; version?: string };
+
+export const PACKAGE_NAME = pkg.name || "agent-relay-runner";
+export const VERSION = pkg.version || "0.0.0";
+// Protocol versions are owned by the SDK (CONTRACT_VERSIONS) — derive, never redeclare.
+export const RUNNER_PROTOCOL_VERSION = CONTRACT_VERSIONS.runnerProtocol;
+export const PROVIDER_PLUGIN_PROTOCOL_VERSION = CONTRACT_VERSIONS.providerPluginProtocol;
+
+export const CONTRACTS = {
+  runnerProtocol: RUNNER_PROTOCOL_VERSION,
+  providerPluginProtocol: PROVIDER_PLUGIN_PROTOCOL_VERSION,
+} as const;
+
+export const RUNTIME_CAPABILITIES = {
+  relayCommandBus: true,
+  managedRegistration: true,
+  lifecycleCommands: true,
+  claimRenewal: true,
+  deliveryRetry: true,
+} as const;
+
+export function runtimeMetadata(provider?: string) {
+  const manifest = provider ? getManifest(provider) : undefined;
+  return {
+    package: {
+      name: PACKAGE_NAME,
+      version: VERSION,
+    },
+    contracts: CONTRACTS,
+    capabilities: {
+      ...RUNTIME_CAPABILITIES,
+      ...(manifest?.provisioning?.bundledPlugin ? { bundledPlugin: true } : {}),
+      ...(manifest?.provisioning?.bundledSkills ? { bundledSkills: true } : {}),
+    },
+  };
+}

package/src/agent-card-projection.ts

@@ -9,6 +9,7 @@
 import { isRecord } from "agent-relay-sdk";
 import { attachBranchState } from "./agent-branch-state";
 import { deriveAgentBusyHealth } from "./agent-busy-health";
+import { attachCommandActivity } from "./agent-command-activity";
 import { attachIssueRepo } from "./agent-issue-repo";
 import type { AgentCard } from "./types";
 
@@ -28,8 +29,11 @@ const OMITTED_STATUS_WORKSPACE_KEYS = new Set([
 /** Enrich an AgentCard with the derived fields the dashboard expects on every surface. */
 export function projectAgentCard(agent: AgentCard): AgentCard {
   const projected = attachIssueRepo(attachBranchState(agent));
+  // busy-health derives from the RAW provider status, so read it before the #1004 command-busy
+  // overlay — a running background command must not make the agent look stuck-busy.
   const busyHealth = deriveAgentBusyHealth(projected);
-  return busyHealth ? { ...projected, meta: { ...(projected.meta ?? {}), busyHealth } } : projected;
+  const enriched = busyHealth ? { ...projected, meta: { ...(projected.meta ?? {}), busyHealth } } : projected;
+  return attachCommandActivity(enriched);
 }
 
 function projectStatusMeta(meta: AgentCard["meta"]): AgentCard["meta"] | undefined {

package/src/agent-command-activity.ts

@@ -0,0 +1,39 @@
+// #1004 — the single home for the running-command → busy DISPLAY rule.
+//
+// A background command scheduled via relay_schedule_timer runs on the creating agent's behalf
+// (on an orchestrator). The provider reports that agent `idle` the instant its own turn ends,
+// so the still-running command is invisible on the dashboard — it reads idle while a real shell
+// command (e.g. a release) executes. Reflect it as `busy` for the command's lifetime.
+//
+// Every agent-card serialization boundary routes through here — the SSE projection
+// (agent-card-projection.ts) AND the REST reads (routes/agents.ts) — mirroring how
+// attachBranchState/attachIssueRepo enrich at those same boundaries, so live ticks and polls
+// agree. A prompt-wakeup timer (no command) is a plain future alarm and never triggers this.
+//
+// Override only a resting `idle`/`online`: never mask a genuine offline/stale/error, and never
+// fabricate work the provider itself already reports (busy stays busy). The busy-ness is derived
+// live from the timer/command rows (the source of truth via agentHasRunningCommandTimer), not a
+// duplicated status flag — so it self-heals when the command settles and can't leak a
+// permanently-busy agent. It is a display overlay only: the stored provider status the reconcilers
+// read (getAgent/listAgents) is untouched, so stuck-busy health and lifecycle gating are unaffected.
+import { agentHasRunningCommandTimer, agentsWithRunningCommandTimers } from "./db";
+import type { AgentCard } from "./types";
+
+function applyCommandBusy(agent: AgentCard, running: boolean): AgentCard {
+  if (!running) return agent;
+  if (agent.status !== "idle" && agent.status !== "online") return agent;
+  return { ...agent, status: "busy" };
+}
+
+/** Overlay running-command busy on a single card (SSE projection + REST get-by-id). */
+export function attachCommandActivity(agent: AgentCard): AgentCard {
+  return applyCommandBusy(agent, agentHasRunningCommandTimer(agent.id));
+}
+
+/** Batch variant for list endpoints: one query, then map (REST get-many). */
+export function attachCommandActivities(agents: AgentCard[]): AgentCard[] {
+  if (agents.length === 0) return agents;
+  const running = agentsWithRunningCommandTimers();
+  if (running.size === 0) return agents;
+  return agents.map((agent) => applyCommandBusy(agent, running.has(agent.id)));
+}

package/src/automations/reconcile.ts

@@ -202,7 +202,7 @@ function maybeFailNeverReadyOfflineTarget(run: AutomationRun, task: Task, now: n
       automationTargetNeverReady: true,
       agentId,
     },
-  });
+  }, { privileged: true });
   const updatedTask = taskResult.task ?? getTask(task.id) ?? task;
   updateRun(run.id, {
     status: "failed",
@@ -248,7 +248,7 @@ function maybeTimeoutRuntimeBudget(run: AutomationRun, task: Task, now: number):
       maxRuntimeMs: budget.maxRuntimeMs,
       deadlineAt: deadline,
     },
-  });
+  }, { privileged: true });
   const updatedTask = taskResult.task ?? getTask(task.id) ?? task;
   const command = requestOnDemandAgentShutdown(run, updatedTask, now, "runtime-budget-timeout");
   updateRun(run.id, {

package/src/cli/workspace.ts

@@ -150,7 +150,9 @@ export async function handleWorkspaceCommand(args: string[]): Promise<void> {
   }
 
   if (action === "cleanup-stale") {
-    const result = await apiRequest("POST", "/api/workspaces/actions/cleanup-stale", { repoRoot: repo, dryRun: !execute, ...(idExplicit && id ? { workspaceId: id } : {}) });
+    // #965 — --force discards an abandoned offline-owner worktree even when its git state is a
+    // conflict/unlanded (the land-safety gate is right for live work, wrong for a dead branch).
+    const result = await apiRequest("POST", "/api/workspaces/actions/cleanup-stale", { repoRoot: repo, dryRun: !execute, force, ...(idExplicit && id ? { workspaceId: id } : {}) });
     console.log(JSON.stringify(result, null, 2));
     return;
   }

package/src/config.ts

@@ -65,7 +65,16 @@ export const STUCK_BUSY_STARTUP_MS = envPositiveInt("AGENT_RELAY_STUCK_BUSY_STAR
 export const STUCK_BUSY_RECONNECT_MS = envPositiveInt("AGENT_RELAY_STUCK_BUSY_RECONNECT_MS", STUCK_BUSY_THRESHOLD_MS);
 export const STUCK_BUSY_SHUTDOWN_MS = envPositiveInt("AGENT_RELAY_STUCK_BUSY_SHUTDOWN_MS", STUCK_BUSY_THRESHOLD_MS);
 export const EVENT_LOOP_LAG_SAMPLE_MS = envPositiveInt("AGENT_RELAY_EVENT_LOOP_LAG_SAMPLE_MS", 1_000);
-export const EVENT_LOOP_LAG_WINDOW_SAMPLES = envPositiveInt("AGENT_RELAY_EVENT_LOOP_LAG_WINDOW_SAMPLES", 60);
+// #1055 invariant: retain STRICTLY MORE than one reaper interval of lag history. The
+// stale/bus reaper reads the cumulative lag grace once per REAP_INTERVAL_MS; if the ring
+// held only one interval's worth (the old 60×1s == 60s == REAP_INTERVAL coincidence),
+// the oldest stall samples could rotate out the instant before the first post-recovery
+// reaper run and collapse the grace exactly when it's needed. Keep a half-interval margin
+// (1.5× reaper interval) so recent overload always survives to the next reaper tick.
+export const EVENT_LOOP_LAG_WINDOW_SAMPLES = envPositiveInt(
+  "AGENT_RELAY_EVENT_LOOP_LAG_WINDOW_SAMPLES",
+  Math.ceil((REAP_INTERVAL_MS / EVENT_LOOP_LAG_SAMPLE_MS) * 1.5),
+);
 export const EVENT_LOOP_LAG_WARN_MS = envNonNegativeNumber("AGENT_RELAY_EVENT_LOOP_LAG_WARN_MS", 250);
 export const EVENT_LOOP_LAG_LOG_MS = envNonNegativeNumber("AGENT_RELAY_EVENT_LOOP_LAG_LOG_MS", EVENT_LOOP_LAG_WARN_MS);
 // #713 — provider-token silence ALONE is not a wedge signal for Claude (long turns, extended