@indigoai-us/hq-cli 5.276.0 → 5.278.0

package/dist/lib/lanes/claude-balance.d.ts

@@ -3,6 +3,7 @@ import type { HostCapacityAccount, HostCapacitySnapshot } from "./host-capacity.
 import type { LaneHost, LaneRecord, LanesConfig } from "./types.js";
 export declare const BALANCE_LIVE_STATES: readonly ["running", "queued", "awaiting_input"];
 export declare const BALANCE_MOVABLE_STATES: readonly ["interrupted", "done", "awaiting_input"];
+export declare const CLAUDE_RECENT_USAGE_WINDOW_MS: number;
 export interface BalanceHostSnapshot {
     capacity: HostCapacitySnapshot;
     lanes: readonly LaneRecord[];
@@ -39,11 +40,12 @@ export interface ClaudeAccountLoad {
     live_lanes: number;
     counts_complete: boolean;
     usage: NonNullable<HostCapacityAccount["usage"]> | null;
+    recent_usage_at: string | null;
     hosts: AccountHostLoad[];
 }
 export interface ClaudeAccountSelection {
     account: string;
-    signal: "usage" | "lane_count" | "explicit";
+    signal: "usage" | "recent_usage" | "lane_count" | "explicit";
     reason: "least_loaded" | "explicit";
     target_host: LaneHost;
     considered: ClaudeAccountLoad[];
@@ -72,6 +74,9 @@ export declare function selectClaudeAccount(input: {
     model?: string;
     /** Keep the recorded account eligible for its already-running CLI model. */
     recordedModelAccount?: string;
+    /** Recent completed-run tiebreak; callers pass the default-off hq-flags result. */
+    recentUsageEnabled?: boolean;
+    now?: Date;
     explicitAccount?: string;
     unavailableHosts?: readonly BalanceHostGap[];
 }): ClaudeAccountSelection;

package/dist/lib/lanes/claude-balance.js

@@ -1,6 +1,7 @@
 import { LanesError } from "./errors.js";
 export const BALANCE_LIVE_STATES = ["running", "queued", "awaiting_input"];
 export const BALANCE_MOVABLE_STATES = ["interrupted", "done", "awaiting_input"];
+export const CLAUDE_RECENT_USAGE_WINDOW_MS = 5 * 60 * 60 * 1000;
 function sameHost(a, b) {
     return a.kind === b.kind && a.id === b.id;
 }
@@ -74,10 +75,31 @@ function usageScore(usage) {
         return null;
     return Math.max(usage.five_hour_percent, usage.weekly_percent);
 }
-function selectionSignal(loads) {
-    return loads.length > 0 && loads.every((load) => usageScore(load.usage) !== null)
-        ? "usage"
-        : "lane_count";
+function recentUsageAt(hosts, account, now) {
+    if (hosts.some((host) => !host.laneListAvailable))
+        return null;
+    const nowMs = now.getTime();
+    const cutoff = nowMs - CLAUDE_RECENT_USAGE_WINDOW_MS;
+    let latestAt = null;
+    let latestMs = cutoff - 1;
+    for (const host of hosts) {
+        for (const lane of host.lanes) {
+            if (lane.provider !== "claude" || lane.account !== account ||
+                lane.last_run_usage === undefined || lane.last_run_usage_at === undefined)
+                continue;
+            const atMs = Date.parse(lane.last_run_usage_at);
+            if (!Number.isFinite(atMs) || atMs < cutoff || atMs > nowMs || atMs <= latestMs)
+                continue;
+            latestMs = atMs;
+            latestAt = lane.last_run_usage_at;
+        }
+    }
+    return latestAt;
+}
+function selectionSignal(loads, recentUsageEnabled, laneSnapshotsComplete) {
+    if (loads.length > 0 && loads.every((load) => usageScore(load.usage) !== null))
+        return "usage";
+    return recentUsageEnabled && laneSnapshotsComplete ? "recent_usage" : "lane_count";
 }
 function targetIneligibilityReason(accountId, globalEnabled, allowedAccounts, target) {
     if (!globalEnabled)
@@ -120,6 +142,7 @@ function buildLoads(input) {
             live_lanes: knownCounts.reduce((sum, count) => sum + count, 0),
             counts_complete: hosts.every((host) => host.live_lanes !== null && host.count_source !== "capacity_partial"),
             usage: input.target.capacity.providers.claude.accounts[account]?.usage ?? null,
+            recent_usage_at: recentUsageAt(input.hosts, account, input.now),
             hosts,
         };
     });
@@ -133,7 +156,8 @@ export function selectClaudeAccount(input) {
             unavailable_hosts: input.unavailableHosts ?? [],
         });
     }
-    const { loads, skipped } = buildLoads({ ...input, target });
+    const now = input.now ?? new Date();
+    const { loads, skipped } = buildLoads({ ...input, target, now });
     if (input.explicitAccount !== undefined) {
         const selected = loads.find((load) => load.account === input.explicitAccount);
         if (!selected || !selected.eligible) {
@@ -173,14 +197,28 @@ export function selectClaudeAccount(input) {
             unavailable_hosts: input.unavailableHosts ?? [],
         });
     }
-    const signal = selectionSignal(eligible);
+    const signal = selectionSignal(eligible, input.recentUsageEnabled === true, input.hosts.every((host) => host.laneListAvailable) && (input.unavailableHosts?.length ?? 0) === 0);
     eligible.sort((a, b) => {
         if (signal === "usage") {
             const byUsage = usageScore(a.usage) - usageScore(b.usage);
             if (byUsage !== 0)
                 return byUsage;
         }
-        return a.live_lanes - b.live_lanes || a.account.localeCompare(b.account);
+        const byLiveLanes = a.live_lanes - b.live_lanes;
+        if (byLiveLanes !== 0)
+            return byLiveLanes;
+        if (signal === "recent_usage") {
+            if (a.recent_usage_at === null && b.recent_usage_at !== null)
+                return -1;
+            if (a.recent_usage_at !== null && b.recent_usage_at === null)
+                return 1;
+            if (a.recent_usage_at !== null && b.recent_usage_at !== null) {
+                const byRecentUsage = Date.parse(a.recent_usage_at) - Date.parse(b.recent_usage_at);
+                if (byRecentUsage !== 0)
+                    return byRecentUsage;
+            }
+        }
+        return a.account.localeCompare(b.account);
     });
     return {
         account: eligible[0].account,
@@ -196,7 +234,7 @@ export function accountLoadsForReport(input) {
     const first = input.hosts[0];
     if (!first)
         return [];
-    return buildLoads({ hosts: input.hosts, target: first, config: input.config }).loads.map((load) => ({
+    return buildLoads({ hosts: input.hosts, target: first, config: input.config, now: new Date() }).loads.map((load) => ({
         ...load,
         eligible: false,
         ineligible_reason: undefined,

package/dist/lib/lanes/config.d.ts

@@ -7,7 +7,7 @@
  * that resolve to the same home are refused (identity-keyed-cap rule).
  */
 import * as fs from "node:fs";
-import { type AccountConfig, type LaneProvider, type LanesConfig, type LivenessWindows, type ProviderConfig, type TrackerChecksConfig } from "./types.js";
+import { type AccountConfig, type LaneProvider, type LanesConfig, type RunawaySearchGuardConfig, type LivenessWindows, type ProviderConfig, type TrackerChecksConfig } from "./types.js";
 export declare const LANES_CONFIG_REL: string;
 export declare const DEFAULT_MAX_QUEUED = 3;
 export declare const DEFAULT_CPU_BUSY_PAUSE = 0.85;
@@ -44,6 +44,7 @@ export declare const DEFAULT_BLOCKER_FRESHNESS_HOURS = 4;
 /** Manager key results must be re-measured within six hours by default. */
 export declare const DEFAULT_KR_FRESHNESS_HOURS = 6;
 export declare const DEFAULT_TRACKER_CHECKS: TrackerChecksConfig;
+export declare const DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG: RunawaySearchGuardConfig;
 export declare const DEFAULT_LIVENESS_WINDOWS: LivenessWindows;
 export declare const DEFAULT_PROVIDER_MAX_RUNNING: Record<LaneProvider, number>;
 export declare const DEFAULT_ACCOUNT_HOMES: Record<LaneProvider, string>;

package/dist/lib/lanes/config.js

@@ -56,6 +56,10 @@ export const DEFAULT_TRACKER_CHECKS = {
     kpi_value_max_age_ms: 24 * 60 * 60 * 1000,
     directive_ack_timeout_ms: 30 * 60 * 1000,
 };
+export const DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG = {
+    max_age_seconds: 20,
+    find_maxdepth_exempt: 3,
+};
 export const DEFAULT_LIVENESS_WINDOWS = {
     live_within_ms: DEFAULT_LIVE_WITHIN_MS,
     turn_start_lost_ms: DEFAULT_TURN_START_LOST_MS,
@@ -252,6 +256,21 @@ function parsePreferredAccounts(provider, value, accounts) {
     return [...preferred];
 }
 export function assertUniqueAccountHomes(provider, accounts) {
+    // An override must not let one account reuse another account's shared default home.
+    const declaredHomes = new Map();
+    for (const [id, account] of Object.entries(accounts)) {
+        const homes = new Set([
+            account.home,
+            ...Object.values(account.hosts ?? {}).map(({ home }) => home),
+        ]);
+        for (const home of homes) {
+            const prior = declaredHomes.get(home);
+            if (prior !== undefined && prior !== id) {
+                throw new LanesConfigError("duplicate_account_home", `providers.${provider} accounts ${JSON.stringify(prior)} and ${JSON.stringify(id)} declare the same home ${home}`, { provider, accounts: [prior, id], home });
+            }
+            declaredHomes.set(home, id);
+        }
+    }
     const hostnames = new Set(Object.values(accounts).flatMap((account) => Object.keys(account.hosts ?? {})));
     const check = (hostname) => {
         const seen = new Map();
@@ -402,6 +421,16 @@ function parseTrackerChecks(raw) {
         directive_ack_timeout_ms: positiveInt(checks.directive_ack_timeout_ms, "tracker.checks.directive_ack_timeout_ms", DEFAULT_TRACKER_CHECKS.directive_ack_timeout_ms),
     };
 }
+function parseRunawaySearchGuard(raw) {
+    const guard = raw === undefined ? {} : raw;
+    if (!isPlainObject(guard)) {
+        throw new LanesConfigError("invalid_config", "runaway_search_guard must be an object");
+    }
+    return {
+        max_age_seconds: positiveInt(guard.max_age_seconds, "runaway_search_guard.max_age_seconds", DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG.max_age_seconds),
+        find_maxdepth_exempt: positiveInt(guard.find_maxdepth_exempt, "runaway_search_guard.find_maxdepth_exempt", DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG.find_maxdepth_exempt),
+    };
+}
 export function documentedDefaultConfig(deps = defaultDeps()) {
     const providers = {};
     for (const provider of LANE_PROVIDERS) {
@@ -425,6 +454,7 @@ export function documentedDefaultConfig(deps = defaultDeps()) {
         },
         liveness: { ...DEFAULT_LIVENESS_WINDOWS },
         tracker: { checks: { ...DEFAULT_TRACKER_CHECKS } },
+        runaway_search_guard: { ...DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG },
         session_question_timeout_secs: DEFAULT_SESSION_QUESTION_TIMEOUT_SECS,
         blocker_freshness_hours: DEFAULT_BLOCKER_FRESHNESS_HOURS,
         kr_freshness_hours: DEFAULT_KR_FRESHNESS_HOURS,
@@ -469,6 +499,7 @@ export function parseLanesConfig(raw, deps = defaultDeps()) {
         throttle: parseThrottle(raw.throttle),
         liveness: parseLiveness(raw.liveness),
         tracker: { checks: parseTrackerChecks(raw.tracker) },
+        runaway_search_guard: parseRunawaySearchGuard(raw.runaway_search_guard),
         session_question_timeout_secs: positiveInt(raw.session_question_timeout_secs, "session_question_timeout_secs", DEFAULT_SESSION_QUESTION_TIMEOUT_SECS),
         blocker_freshness_hours: positiveNumber(raw.blocker_freshness_hours, "blocker_freshness_hours", DEFAULT_BLOCKER_FRESHNESS_HOURS),
         kr_freshness_hours: positiveNumber(raw.kr_freshness_hours, "kr_freshness_hours", DEFAULT_KR_FRESHNESS_HOURS),

package/dist/lib/lanes/hire-grant-dispatch.d.ts

@@ -18,6 +18,8 @@ export interface OutpostHireGrantContext {
     superseded_message_caller_id?: string;
     superseded_message_session_id?: string;
 }
+/** Select the owner records needed to reproduce the primary's grant hierarchy. */
+export declare function selectOutpostHireGrantHierarchy(targetLaneId: string, lanes: readonly LaneRecord[]): LaneRecord[];
 /** Encode only the owner-relevant hierarchy from the primary's complete store. */
 export declare function createOutpostHireGrantContext(target: LaneRecord, lanes: readonly LaneRecord[], supersededMessageCallerId?: string, supersededMessageSessionId?: string): string;
 /** Decode and validate an owner grant context, binding it to the target lane. */

package/dist/lib/lanes/hire-grant-dispatch.js

@@ -15,6 +15,47 @@ function copySenior(senior) {
         ? { kind: senior.kind }
         : { kind: senior.kind, id: senior.id };
 }
+// Terminal relatives are included so the owner's final state overwrites a stale
+// primary copy; the context builder counts only alive children afterwards.
+function directChildren(lanes, parentLaneId) {
+    return lanes.filter((lane) => lane.senior.kind === "lane" && lane.senior.id === parentLaneId);
+}
+/** Select the owner records needed to reproduce the primary's grant hierarchy. */
+export function selectOutpostHireGrantHierarchy(targetLaneId, lanes) {
+    const current = lanes.find((lane) => lane.lane_id === targetLaneId);
+    if (!current)
+        return [];
+    const relevant = new Set([current.lane_id]);
+    if (current.senior.kind === "lane" && current.senior.id) {
+        relevant.add(current.senior.id);
+        for (const sibling of directChildren(lanes, current.senior.id)) {
+            relevant.add(sibling.lane_id);
+        }
+    }
+    for (const child of directChildren(lanes, current.lane_id)) {
+        relevant.add(child.lane_id);
+    }
+    const companyUid = current.company?.uid;
+    const projectId = current.project_id;
+    if (companyUid && projectId) {
+        // A superseded-message caller must be checked against the same project and
+        // company rows that the complete hierarchy builder sees.
+        for (const candidate of lanes) {
+            if (candidate.company?.uid === companyUid && candidate.project_id === projectId) {
+                relevant.add(candidate.lane_id);
+            }
+        }
+    }
+    if (current.senior.kind === "session" && companyUid) {
+        for (const candidate of lanes) {
+            if (candidate.company?.uid === companyUid && ((current.worker_profile !== undefined && candidate.worker_profile === current.worker_profile) ||
+                (projectId !== undefined && candidate.project_id === projectId && (candidate.hire_grant ?? 0) > 0))) {
+                relevant.add(candidate.lane_id);
+            }
+        }
+    }
+    return lanes.filter((lane) => relevant.has(lane.lane_id));
+}
 function snapshot(lane) {
     return {
         lane_id: lane.lane_id,

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

@@ -10,7 +10,7 @@ export type { AdmissionCapReason, AdmissionHost } from "./admission.js";
 export { buildHostCapacitySnapshot, chooseHostForLane, parseHostCapacitySnapshot, } from "./host-capacity.js";
 export type { HostCapacityAccount, HostCapacityProvider, HostCapacitySnapshot, HostPlacementChoice, } from "./host-capacity.js";
 export { CONFIG_SCHEMA_VERSION, ENVELOPE_DECISIONS, ENVELOPE_SCHEMA_VERSION, HISTORY_CAP, HOST_KINDS, LANE_PROVIDERS, LANE_SCHEMA_VERSION, LANE_STORY_STATUSES, LANE_STATES, LIVENESS_STATES, QUESTION_BODY_STORES, QUESTION_SCHEMA_VERSION, QUESTION_STATUSES, QUEUED_REASONS, RAISED_VIA, ROUTING_REASONS, SENIOR_KINDS, STORY_STATUSES, TERMINAL_LANE_STATES, isEnvelopeDecision, isHostKind, isLaneProvider, isLaneState, isLivenessState, isQuestionStatus, isSeniorKind, isTerminalLaneState, parseLaneEnvelope, parseLaneProvider, parseLaneState, parseLivenessState, parseMajorSchema, parseQuestionStatus, parseSeniorKind, } from "./types.js";
-export type { AccountConfig, AttributionHistoryEntry, EnvelopeDecision, EnvelopeQuestion, HostKind, LaneCompanyRef, LaneAccountSelection, LaneAccountSelectionConsidered, LaneAccountSelectionHostCount, LaneEnvelope, LaneHost, LaneProvider, LanePlacementPolicy, LaneRecord, LaneStory, LaneStoryStatus, PendingResume, AccountHistoryEntry, LaneState, LanesConfig, LastEnvelopeRef, LivenessState, LivenessWindows, ProviderConfig, QuestionAnswer, QuestionBodyRef, QuestionRecord, QuestionStatus, QueuedReason, RaisedVia, RoutingHistoryEntry, RoutingReason, SeniorHistoryEntry, SeniorKind, SeniorRef, WorkerProfileRepinHistoryEntry, StoryStatus, TerminalLaneState, ThrottleConfig, } from "./types.js";
+export type { AccountConfig, AttributionHistoryEntry, EnvelopeDecision, EnvelopeQuestion, HostKind, LaneCompanyRef, LaneAccountSelection, LaneAccountSelectionConsidered, LaneAccountSelectionHostCount, LaneEnvelope, LaneHost, LaneProvider, LanePlacementPolicy, LaneRecord, LaneStory, LaneStoryStatus, PendingResume, AccountHistoryEntry, LaneState, LanesConfig, LastEnvelopeRef, LivenessState, LivenessWindows, ProviderConfig, QuestionAnswer, QuestionBodyRef, QuestionRecord, QuestionStatus, QueuedReason, RaisedVia, RoutingHistoryEntry, RoutingReason, SeniorHistoryEntry, SeniorKind, SeniorRef, WorkerProfileRepinHistoryEntry, LaneSettingsHistoryEntry, StoryStatus, TerminalLaneState, ThrottleConfig, } from "./types.js";
 export { ACTIVE_LANE_STORY_STATUSES, activeLaneStories, laneStories, laneStory, storyKey, storyStatusForEnvelope, storyWarning, withCurrentStory, withLaneStories, } from "./stories.js";
 export { DEFAULT_ACCOUNT_HOMES, DEFAULT_AUTO_COMPACT_TOKENS, DEFAULT_COMPACT_AFTER_MS, DEFAULT_CPU_BUSY_PAUSE, DEFAULT_CPU_BUSY_RESUME, DEFAULT_LIVE_WITHIN_MS, DEFAULT_LIVENESS_WINDOWS, DEFAULT_MAX_QUEUED, DEFAULT_MIN_AVAILABLE_MEM_MB, DEFAULT_PROVIDER_MAX_RUNNING, DEFAULT_SILENT_LOST_MS, DEFAULT_TURN_START_LOST_MS, LANES_CONFIG_REL, accountMaxRunning, canonicalizeHome, documentedDefaultConfig, expandHome, lanesConfigPath, loadLanesConfig, parseLanesConfig, providerCompactAfterMs, providerAutoCompactTokens, providerQuotaDefaultHoldMs, DEFAULT_QUOTA_HOLD_MS, writeLanesConfig, } from "./config.js";
 export type { ConfigLoadDeps, ConfigWriteDeps } from "./config.js";

package/dist/lib/lanes/keep-alive.d.ts

@@ -4,6 +4,9 @@ export declare const LEAD_LANE_KEEP_ALIVE_DEFAULT_ENABLED = false;
 /** Missing or unreadable registry values retain the legacy supersession behavior. */
 export declare const LANE_SUPERSESSION_LINEAGE_AWARE_FLAG = "lanes.supersession-lineage-aware";
 export declare const LANE_SUPERSESSION_LINEAGE_AWARE_DEFAULT_ENABLED = false;
+/** Missing or unreadable registry values keep rejecting superseded messages. */
+export declare const LANE_RUNNING_SUPERSEDED_MESSAGE_DELIVERY_FLAG = "lanes.running-superseded-message-delivery";
+export declare const LANE_RUNNING_SUPERSEDED_MESSAGE_DELIVERY_DEFAULT_ENABLED = false;
 export declare const LEAD_LANE_KEEP_ALIVE_MAX_RESUMES = 24;
 export declare const LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS: number;
 export declare const LEAD_LANE_KEEP_ALIVE_MAX_BACKOFF_MS: number;

package/dist/lib/lanes/keep-alive.js

@@ -8,6 +8,9 @@ export const LEAD_LANE_KEEP_ALIVE_DEFAULT_ENABLED = false;
 /** Missing or unreadable registry values retain the legacy supersession behavior. */
 export const LANE_SUPERSESSION_LINEAGE_AWARE_FLAG = "lanes.supersession-lineage-aware";
 export const LANE_SUPERSESSION_LINEAGE_AWARE_DEFAULT_ENABLED = false;
+/** Missing or unreadable registry values keep rejecting superseded messages. */
+export const LANE_RUNNING_SUPERSEDED_MESSAGE_DELIVERY_FLAG = "lanes.running-superseded-message-delivery";
+export const LANE_RUNNING_SUPERSEDED_MESSAGE_DELIVERY_DEFAULT_ENABLED = false;
 export const LEAD_LANE_KEEP_ALIVE_MAX_RESUMES = 24;
 export const LEAD_LANE_KEEP_ALIVE_BASE_BACKOFF_MS = 5 * 60 * 1000;
 export const LEAD_LANE_KEEP_ALIVE_MAX_BACKOFF_MS = 60 * 60 * 1000;

package/dist/lib/lanes/outpost-dispatch.d.ts

@@ -82,6 +82,10 @@ export declare function buildOutpostCapacityCommand(): string;
 /** Read lane records owned by an Outpost, using its configured HQ binary when set. */
 export declare function buildOutpostLaneListCommand(input?: {
     hqBinary?: string;
+    laneIds?: readonly string[];
+    active?: boolean;
+    hierarchy?: string;
+    snapshot?: boolean;
 }): string;
 /** Read questions on one Outpost, scoped to a company when supplied. */
 export declare function buildOutpostQuestionListCommand(input?: {

package/dist/lib/lanes/outpost-dispatch.js

@@ -67,12 +67,21 @@ export function buildOutpostCapacityCommand() {
 }
 /** Read lane records owned by an Outpost, using its configured HQ binary when set. */
 export function buildOutpostLaneListCommand(input = {}) {
-    return withRemoteHqDir(joinCommandParts([
+    const args = [
         input.hqBinary?.trim() || "hq",
         "lanes",
         "list",
         "--json",
-    ]));
+    ];
+    for (const laneId of input.laneIds ?? [])
+        args.push("--lane", laneId);
+    if (input.active)
+        args.push("--active");
+    if (input.hierarchy !== undefined)
+        args.push("--hierarchy", input.hierarchy);
+    if (input.snapshot)
+        args.push("--snapshot");
+    return withRemoteHqDir(joinCommandParts(args));
 }
 /** Read questions on one Outpost, scoped to a company when supplied. */
 export function buildOutpostQuestionListCommand(input = {}) {

package/dist/lib/lanes/reconcile.d.ts

@@ -9,6 +9,7 @@ import { type LivenessDeps } from "./liveness.js";
 import { type EnvelopeRepairSpawnInput, type SpawnLaneDeps } from "./spawn.js";
 import { type ThrottleDeps } from "./throttle.js";
 import { readLanesRegistryFlag } from "./registry-flag.js";
+import { type RunawayProcessInfo } from "./runaway-tool-guard.js";
 import { type KeepAliveBlockedReason } from "./keep-alive.js";
 import type { LaneCompanyRef, LaneRecord, LivenessState, QueuedReason, QuestionRecord, SeniorRef } from "./types.js";
 import { type LaneMesh } from "./mesh-events.js";
@@ -91,6 +92,14 @@ export interface ReconcileDeps {
     meshEmitTimeoutMs?: number;
     /** Fresh keep-alive eligibility read; injected to exercise opt-in changes before queueing. */
     readKeepAliveRecheckLane?: (hqRoot: string, laneId: string) => LaneRecord;
+    /** Process-table snapshot seam for the opt-in runaway-search guard. */
+    runawayToolProcessLister?: () => readonly RunawayProcessInfo[];
+    /** Test seam: prevent real process signals while exercising the guard. */
+    runawayToolProcessSignal?: (pid: number, signal: NodeJS.Signals) => void;
+    /** Test seam for interleaving a watcher signal with an append-only guard event. */
+    runawayToolEventAppend?: (target: string, line: string) => void;
+    /** Test seam for validating a candidate PID against its process-table starttime. */
+    runawayToolProcessIsCurrent?: (pid: number, expectedStarttime: number) => boolean;
     /**
      * Awaited after lane/question records and liveness are loaded, before any
      * CAS write. Test seam so two in-process passes can share a snapshot.

package/dist/lib/lanes/reconcile.js

@@ -18,16 +18,18 @@ import { AccountResolutionError, LanesError, isLaneVersionConflict } from "./err
 import { loadWorkerProfile } from "./profile.js";
 import { terminalChildResumeHireGrantError, withHireGrantAdmission, } from "./grants.js";
 import { classifySessionLiveness, defaultLivenessDeps, loadLivenessIndex, readDaemonPresenceConnected, unindexedClaudeSessionLiveness, } from "./liveness.js";
-import { ANSWERED_QUESTIONS_FILE, armLaneWatcher, envelopeRepairMode, isPidRecordAlive, laneRunDir, readPidRecord, readSpawnManifest, markSpawnFailure, spawnEnvelopeRepair, spawnLaneWorker, retryLaneOnAlternateAccount, } from "./spawn.js";
+import { ANSWERED_QUESTIONS_FILE, armLaneWatcher, envelopeRepairMode, isPidRecordAlive, laneRunDir, readPidRecord, readProcStarttime, readSpawnManifest, markSpawnFailure, spawnEnvelopeRepair, spawnLaneWorker, retryLaneOnAlternateAccount, } from "./spawn.js";
 import { appendCappedHistory, lanesStoreRoot, parseLaneRecord, parseQuestionRecord, readLane, readQuestion, updateLane, updateQuestion, } from "./store.js";
 import { applyThrottleDecision, decideAdmission, defaultThrottleDeps, emptyThrottleState, evaluateThrottle, isCpuCheckEnabled, readAvailableMemMb, readThrottleState, resolveCpuBusyFraction, throttleStatePath, writeThrottleState, } from "./throttle.js";
 import { readLanesRegistryFlag } from "./registry-flag.js";
 import { resolveLaneCompany } from "./lane-company.js";
+import { appendDropboxMessage } from "./dropbox.js";
+import { DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG, listHostProcesses, runRunawayToolGuard, RUNAWAY_TOOL_GUARD_FLAG, } from "./runaway-tool-guard.js";
 import { LEAD_LANE_KEEP_ALIVE_FLAG, LEAD_LANE_KEEP_ALIVE_INTERRUPTED_RESUME_TEXT, LEAD_LANE_KEEP_ALIVE_MAX_RESUMES, LEAD_LANE_KEEP_ALIVE_RESUME_TEXT, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, doneKeepAliveVerdict, hasPendingKeepAliveWork, keepAliveExclusion, loadRetiredLaneIds, leadLaneKeepAliveBackoffMs, undeliveredAnsweredQuestions, } from "./keep-alive.js";
 import { providerSupportsSessionResume } from "./delivery.js";
 import { applyDefaultQuotaHold, readQuotaSignal, recordAccountQuota } from "./quota.js";
 import { answeredQuestionEntries, questionRecordRefusalCode, raiseEnvelopeQuestions, resolveQuestionCompanyWithFallback, } from "./questions.js";
-import { SILENCE_MS, classifyLaneExit, isPidAlive, missingExpectedEnvelopeFile, readLatestEnvelopeFile, readLatestEnvelopeRecord, watcherEventsPath, watcherOutLogPath, writeWatcherDecision, } from "./watcher.js";
+import { SILENCE_MS, appendWatcherEvent, classifyLaneExit, isPidAlive, missingExpectedEnvelopeFile, readLatestEnvelopeFile, readLatestEnvelopeRecord, watcherEventsPath, watcherOutLogPath, writeWatcherDecision, } from "./watcher.js";
 import { createLaneMesh, emitLaneDecisionEvents, emitLaneTerminalStateEvent, laneMeshCompany, } from "./mesh-events.js";
 import { laneStories, storyStatusForEnvelope } from "./stories.js";
 import { resolveManagerStatusGateForLane } from "./manager-status-gate.js";
@@ -658,6 +660,128 @@ function classifyDeadLocalLane(hqRoot, laneId, now) {
         lane,
     };
 }
+function runawayGuardCompanyKey(company) {
+    return company
+        ? `${company.uid ?? ""}\u0000${company.slug ?? ""}`
+        : "unresolved-company";
+}
+function reportRunawayGuardError(summary, stage, error) {
+    summary.ok = false;
+    summary.errors.push({
+        code: `runaway_tool_guard_${stage}_failed`,
+        message: `runaway search guard ${stage} failed; no additional search processes were stopped`,
+    });
+    process.stderr.write(`${JSON.stringify({
+        event: "lanes.runaway_tool_guard.failed",
+        stage,
+        error: error instanceof Error ? error.name : "UnknownError",
+        fallback: "continue_without_argv",
+    })}\n`);
+}
+async function runRunawayToolGuardPass(hqRoot, lanes, config, deps, now, summary) {
+    if (deps.dryRun)
+        return;
+    const localRunningLanes = lanes.filter((lane) => lane.state === "running" && laneRunsHere(lane, deps.host));
+    if (localRunningLanes.length === 0)
+        return;
+    const groups = new Map();
+    for (const lane of localRunningLanes) {
+        let worker;
+        try {
+            worker = readPidRecord(path.join(laneRunDir(hqRoot, lane.lane_id), "worker.pid"));
+            if (!worker ||
+                worker.starttime === undefined ||
+                !isPidRecordAlive(worker, deps.isAlive))
+                continue;
+        }
+        catch (error) {
+            reportRunawayGuardError(summary, "worker_pid_read", error);
+            continue;
+        }
+        let company;
+        try {
+            company = resolveLaneCompany(hqRoot, lane).company;
+        }
+        catch (error) {
+            reportRunawayGuardError(summary, "company_resolution", error);
+            continue;
+        }
+        const key = runawayGuardCompanyKey(company);
+        const group = groups.get(key) ?? { company, lanes: [] };
+        group.lanes.push({ laneId: lane.lane_id, agentPid: worker.pid, agentStarttime: worker.starttime });
+        groups.set(key, group);
+    }
+    if (groups.size === 0)
+        return;
+    const readRegistryFlag = deps.readRegistryFlag ?? readLanesRegistryFlag;
+    const enabledGroups = new Set();
+    const env = deps.env ?? process.env;
+    await Promise.all([...groups.entries()].map(async ([key, group]) => {
+        try {
+            const enabled = await readRegistryFlag(RUNAWAY_TOOL_GUARD_FLAG, {
+                company: group.company ?? undefined,
+                env,
+            });
+            if (enabled)
+                enabledGroups.add(key);
+        }
+        catch (error) {
+            reportRunawayGuardError(summary, "flag_read", error);
+        }
+    }));
+    if (enabledGroups.size === 0)
+        return;
+    const laneProcesses = [...groups.entries()]
+        .filter(([key]) => enabledGroups.has(key))
+        .flatMap(([, group]) => group.lanes);
+    if (laneProcesses.length === 0)
+        return;
+    let processes;
+    try {
+        processes = (deps.runawayToolProcessLister ?? listHostProcesses)();
+    }
+    catch (error) {
+        reportRunawayGuardError(summary, "process_table_read", error);
+        return;
+    }
+    const runawayConfig = config.runaway_search_guard ?? DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG;
+    try {
+        runRunawayToolGuard({
+            hqRoot,
+            lanes: laneProcesses,
+            processes,
+            config: runawayConfig,
+            now,
+            currentUid: process.getuid?.() ?? -1,
+            isCurrentProcess: deps.runawayToolProcessIsCurrent ??
+                ((pid, expectedStarttime) => readProcStarttime(pid) === expectedStarttime),
+            signal: deps.runawayToolProcessSignal ?? ((pid, signal) => process.kill(pid, signal)),
+            recordEvent: (laneId, event) => appendWatcherEvent(watcherEventsPath(hqRoot, laneId), event, deps.runawayToolEventAppend),
+            notifyLane: (laneId, text) => appendDropboxMessage(hqRoot, laneId, {
+                at: now.toISOString(),
+                message_id: `runaway-search-guard:${laneId}:${now.getTime()}`,
+                kind: "system_notice",
+                text,
+            }),
+            reportError: (stage, errorName) => {
+                summary.ok = false;
+                summary.errors.push({
+                    code: `runaway_tool_guard_${stage}_failed`,
+                    message: `runaway search guard could not ${stage} a stopped process (${errorName})`,
+                });
+                process.stderr.write(`${JSON.stringify({
+                    event: "lanes.runaway_tool_guard.failed",
+                    stage,
+                    error: errorName,
+                    fallback: "continue_without_argv",
+                })}\n`);
+            },
+        });
+    }
+    catch (error) {
+        reportRunawayGuardError(summary, "execution", error);
+    }
+}
 /** Unlocked pass body. `runReconcilePass` takes the process lock around this. */
 export async function runPassBody(hqRoot, deps) {
     const now = deps.now();
@@ -728,6 +852,7 @@ export async function runPassBody(hqRoot, deps) {
         : QUESTION_AGE_MS;
     if (deps.afterLoad)
         await deps.afterLoad();
+    await runRunawayToolGuardPass(hqRoot, lanes, config, deps, now, summary);
     const startDeps = await prepareManagerStatusGateStarts(hqRoot, lanes, deps, summary);
     markOverdueLanes(hqRoot, lanes, summary, deps, now);
     await heartbeatAndDeadHosts(hqRoot, lanes, summary, startDeps, now);

package/dist/lib/lanes/runaway-tool-guard.d.ts

@@ -0,0 +1,38 @@
+import type { RunawaySearchGuardConfig } from "./types.js";
+export declare const RUNAWAY_TOOL_GUARD_FLAG = "lanes.runaway-tool-guard";
+export interface RunawayProcessInfo {
+    pid: number;
+    ppid: number;
+    elapsedSeconds: number;
+    uid: number;
+    command: string;
+    argv: readonly string[];
+    cwd: string;
+    starttime: number | null;
+}
+export interface RunawayLaneProcess {
+    laneId: string;
+    agentPid: number;
+    agentStarttime: number;
+}
+export interface RunawayToolGuardInput {
+    hqRoot: string;
+    lanes: readonly RunawayLaneProcess[];
+    processes: readonly RunawayProcessInfo[];
+    config: RunawaySearchGuardConfig;
+    now: Date;
+    currentUid: number;
+    isCurrentProcess: (pid: number, expectedStarttime: number) => boolean;
+    signal: (pid: number, signal: NodeJS.Signals) => void;
+    recordEvent: (laneId: string, event: Record<string, unknown>) => void;
+    notifyLane: (laneId: string, text: string) => void;
+    reportError: (stage: "signal" | "record" | "notify", errorName: string) => void;
+}
+export interface RunawayToolGuardResult {
+    stopped: number;
+}
+export declare function runRunawayToolGuard(input: RunawayToolGuardInput): RunawayToolGuardResult;
+/** Read the host process table once. argv and cwd are read only for search tools. */
+export declare function listHostProcesses(): RunawayProcessInfo[];
+export { DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG } from "./config.js";
+//# sourceMappingURL=runaway-tool-guard.d.ts.map