@indigoai-us/hq-cli 5.277.0 → 5.278.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## [Unreleased]
 
+## [5.278.0] — 2026-09-29
+
+### Changed
+
+- The CI and no-hermes pull request checks use read-only repository access, and CI pins its third-party actions to fixed commits. The fast-route benchmark workflow is pinned in a follow-up.
+
+### Added
+
+- Reconcile can stop an over-budget same-user search process descended from a
+  running lane when `rg`, `grep`, `ugrep`, or `ag` disables ignores on a broad
+  HQ root, or `find` searches a broad root without a shallow-depth or prune
+  exemption. The `lanes.runaway-tool-guard` hq-flags key is off by default. A
+  stopped search records its command and duration, then gets a notice to narrow
+  the search.
+
+- Add the default-off `checkpoint.ontology.hub-mention-floor` hq-flags key.
+  When it is on, checkpoint ontology apply rejects a knowledge link to a
+  non-person entity that 50 or more other entity files link to when the input
+  names it fewer than 2 times in the text the model read (the chunk's line
+  range of the annotation-stripped copy when there is one). Concept links
+  redirected to a project are checked the same way. The rejection is reported
+  as `hub_under_mentioned`.
+
 ## [5.277.0] — 2026-09-29
 
 ### Fixed

package/dist/lib/checkpoint-ontology/apply.js

@@ -30,6 +30,10 @@ export const MIN_CREATE_CONFIDENCE = 0.7;
 const DOMINANT_SIBLING_RATIO = 3;
 /** Inbound links the dominant sibling must have before a redirect. */
 const DOMINANT_SIBLING_MIN_INBOUND = 5;
+/** checkpoint.ontology.hub-mention-floor: other entity files that must link here before the floor applies. */
+const HUB_MIN_INBOUND = 50;
+/** checkpoint.ontology.hub-mention-floor: whole-word canonical-name mentions required to keep the link. */
+const HUB_MIN_MENTIONS = 2;
 export class ApplyError extends Error {
     constructor(message) {
         super(message);
@@ -67,6 +71,16 @@ export function parseCandidate(raw) {
         evidence: typeof c.evidence === "string" ? c.evidence : "",
     };
 }
+function escapeRegExp(name) {
+    return name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Whole-word, any-case matches of `name` in `text`, with Unicode letters and digits as word characters. Empty or whitespace-only names match nothing. */
+function countMentions(text, name) {
+    if (name.trim() === "")
+        return 0;
+    const pattern = new RegExp(`(?<![\\p{L}\\p{N}])${escapeRegExp(name)}(?![\\p{L}\\p{N}])`, "giu");
+    return text.match(pattern)?.length ?? 0;
+}
 /**
  * checkpoint.ontology.named-evidence: true when `evidence` holds one of
  * `names` as a word, matching case. A name inside a path, domain, handle, tag
@@ -305,8 +319,11 @@ export function applyOntologyRun(options) {
             if (types.size > 1)
                 crossTypeNames.add(name);
     }
-    // checkpoint.ontology.dominant-sibling-link: cross-type names, and how many other entity files link to each.
-    const inbound = plan.dominant_sibling_link === true ? countInboundLinks(company.dir, index) : new Map();
+    // checkpoint.ontology.dominant-sibling-link and checkpoint.ontology.hub-mention-floor:
+    // how many other entity files link to each entity.
+    const inbound = plan.dominant_sibling_link === true || plan.hub_mention_floor === true
+        ? countInboundLinks(company.dir, index)
+        : new Map();
     const siblings = new Map();
     if (plan.dominant_sibling_link === true) {
         const grouped = new Map();
@@ -347,6 +364,32 @@ export function applyOntologyRun(options) {
     const ownCompanyRel = `ontology/entities/company/${company.slug}.md`;
     const isOwnCompany = (entity, rel) => entity.type === "company" && (rel === ownCompanyRel || crossTypeKey(entity.canonical_name) === crossTypeKey(company.slug));
     const inputs = liveInputs(options.hqRoot, company, plan);
+    const inputTexts = new Map();
+    // The text the model was given for this input: the annotation-stripped copy
+    // when there is one, cut to the chunk's line range.
+    const inputText = (input) => {
+        const cached = inputTexts.get(input.id);
+        if (cached !== undefined)
+            return cached;
+        if (input.read_path !== undefined && input.read_path.split("/").includes("..")) {
+            throw new ApplyError("ontology plan read_path leaves the run directory");
+        }
+        const file = input.read_path !== undefined
+            ? path.join(options.runDir, input.read_path)
+            : path.join(company.dir, input.path);
+        let text = fs.readFileSync(file, "utf8");
+        if (input.lines !== null)
+            text = text.split("\n").slice(input.lines[0] - 1, input.lines[1]).join("\n");
+        inputTexts.set(input.id, text);
+        return text;
+    };
+    // checkpoint.ontology.hub-mention-floor: the final target of a knowledge link is a
+    // non-person entity many files link to, and the input names it fewer than twice.
+    const underMentionedHub = (input, rel, entity) => plan.hub_mention_floor === true &&
+        input.kind === "knowledge" &&
+        entity.type !== "person" &&
+        (inbound.get(rel) ?? 0) >= HUB_MIN_INBOUND &&
+        countMentions(inputText(input), entity.canonical_name) < HUB_MIN_MENTIONS;
     const blocked = new Set();
     const updates = new Map();
     const update = (rel) => {
@@ -414,6 +457,10 @@ export function applyOntologyRun(options) {
                 note(report.rejected, "unnamed_in_evidence");
                 continue;
             }
+            if (underMentionedHub(input, targetRel, targetEntity)) {
+                note(report.rejected, "hub_under_mentioned");
+                continue;
+            }
             report.matched += 1;
             report.links.push({
                 input: candidate.input,
@@ -470,6 +517,10 @@ export function applyOntologyRun(options) {
                     continue;
                 }
                 const linked = index.byRel.get(projects[0]);
+                if (underMentionedHub(input, projects[0], linked)) {
+                    note(report.rejected, "hub_under_mentioned");
+                    continue;
+                }
                 report.matched += 1;
                 report.links.push({ input: candidate.input, action: "link", type: linked.type, canonical_name: linked.canonical_name, path: projects[0] });
                 continue;

package/dist/lib/checkpoint-ontology/plan.d.ts

@@ -81,6 +81,14 @@ export declare const SKIP_AMBIGUOUS_CONCEPT_LINKS_FLAG = "checkpoint.ontology.sk
  * and recall from 0.784 to 0.816, and never changed a create.
  */
 export declare const DOMINANT_SIBLING_LINK_FLAG = "checkpoint.ontology.dominant-sibling-link";
+/**
+ * A knowledge link to a non-person entity that 50 or more
+ * other entity files link to is rejected as `hub_under_mentioned` when the
+ * input names it fewer than 2 times (whole word, any case, canonical name
+ * only). The plan carries `hub_mention_floor: true`. CO-62: a replay of six
+ * runs raised knowledge precision from 0.753 to 0.781 at the same recall.
+ */
+export declare const HUB_MENTION_FLOOR_FLAG = "checkpoint.ontology.hub-mention-floor";
 /**
  * A knowledge concept candidate whose name is an alias of more than one
  * entity, and which apply would defer as `ambiguous_alias`, links instead to
@@ -186,6 +194,8 @@ export interface OntologyPlan {
     skip_ambiguous_concept_links?: true;
     /** Set by checkpoint.ontology.dominant-sibling-link: apply redirects a knowledge link from a weak cross-type sibling to the one other files link to. */
     dominant_sibling_link?: true;
+    /** Set by checkpoint.ontology.hub-mention-floor: apply rejects a knowledge link to an under-mentioned non-person hub. */
+    hub_mention_floor?: true;
     /** Set by checkpoint.ontology.concept-project-link: apply links a knowledge concept with an ambiguous alias to the one project of that canonical name. */
     concept_project_link?: true;
     /** Set by checkpoint.ontology.named-evidence: apply rejects a knowledge link to the company's own entity, or a concept-project-link redirect, whose evidence does not name it as a word. */

package/dist/lib/checkpoint-ontology/plan.js

@@ -86,6 +86,14 @@ export const SKIP_AMBIGUOUS_CONCEPT_LINKS_FLAG = "checkpoint.ontology.skip-ambig
  * and recall from 0.784 to 0.816, and never changed a create.
  */
 export const DOMINANT_SIBLING_LINK_FLAG = "checkpoint.ontology.dominant-sibling-link";
+/**
+ * A knowledge link to a non-person entity that 50 or more
+ * other entity files link to is rejected as `hub_under_mentioned` when the
+ * input names it fewer than 2 times (whole word, any case, canonical name
+ * only). The plan carries `hub_mention_floor: true`. CO-62: a replay of six
+ * runs raised knowledge precision from 0.753 to 0.781 at the same recall.
+ */
+export const HUB_MENTION_FLOOR_FLAG = "checkpoint.ontology.hub-mention-floor";
 /**
  * A knowledge concept candidate whose name is an alias of more than one
  * entity, and which apply would defer as `ambiguous_alias`, links instead to
@@ -317,6 +325,7 @@ export async function planOntologyRun(options) {
     const firstNamePeople = await options.readFlag(FIRST_NAME_PEOPLE_FLAG, company);
     const skipAmbiguousConceptLinks = await options.readFlag(SKIP_AMBIGUOUS_CONCEPT_LINKS_FLAG, company);
     const dominantSiblingLink = await options.readFlag(DOMINANT_SIBLING_LINK_FLAG, company);
+    const hubMentionFloor = await options.readFlag(HUB_MENTION_FLOOR_FLAG, company);
     const conceptProjectLink = await options.readFlag(CONCEPT_PROJECT_LINK_FLAG, company);
     const namedEvidence = await options.readFlag(NAMED_EVIDENCE_FLAG, company);
     const queuedTouchesOn = borrowed || (await options.readFlag(QUEUED_TOUCHES_FLAG, company));
@@ -441,6 +450,7 @@ export async function planOntologyRun(options) {
         ...(firstNamePeople ? { first_name_people: true } : {}),
         ...(skipAmbiguousConceptLinks ? { skip_ambiguous_concept_links: true } : {}),
         ...(dominantSiblingLink ? { dominant_sibling_link: true } : {}),
+        ...(hubMentionFloor ? { hub_mention_floor: true } : {}),
         ...(conceptProjectLink ? { concept_project_link: true } : {}),
         ...(namedEvidence ? { named_evidence: true } : {}),
         inputs,

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,
@@ -417,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) {
@@ -440,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,
@@ -484,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/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

package/dist/lib/lanes/runaway-tool-guard.js

@@ -0,0 +1,284 @@
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { readProcStarttime } from "./spawn.js";
+export const RUNAWAY_TOOL_GUARD_FLAG = "lanes.runaway-tool-guard";
+const SEARCH_COMMANDS = new Set(["rg", "grep", "ugrep", "ag", "find"]);
+const VALUE_OPTIONS = new Set([
+    "-A", "--after-context", "-B", "--before-context", "-C", "--context",
+    "-e", "--regexp", "-f", "--file", "-g", "--glob", "-t", "--type",
+    "-T", "--type-not", "-M", "--max-count", "-m", "--max-count",
+    "-j", "--threads", "--ignore-file", "--include", "--exclude",
+    "--exclude-dir", "--exclude-from", "--encoding", "--sort",
+]);
+function commandName(command) {
+    return path.basename(command).toLowerCase();
+}
+function hasNoIgnoreFlag(command, args) {
+    if (command === "rg" || command === "ag") {
+        return args.some((arg) => ["--no-ignore", "--no-ignore-vcs", "--unrestricted", "--skip-vcs-ignores"].includes(arg) ||
+            /^-[A-Za-z]*u[A-Za-z]*$/.test(arg));
+    }
+    if (command === "grep" || command === "ugrep") {
+        return args.some((arg) => ["--recursive", "--dereference-recursive"].includes(arg) ||
+            /^-[A-Za-z]*[rR][A-Za-z]*$/.test(arg));
+    }
+    return false;
+}
+function findDepth(args) {
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] !== "-maxdepth")
+            continue;
+        const value = Number(args[index + 1]);
+        return Number.isInteger(value) && value >= 0 ? value : null;
+    }
+    return null;
+}
+function positionalArgs(command, args) {
+    if (command === "find") {
+        let index = 0;
+        while (index < args.length) {
+            const arg = args[index];
+            if (["-H", "-L", "-P"].includes(arg) || /^-O\d+$/.test(arg)) {
+                index += 1;
+                continue;
+            }
+            if (arg === "-D") {
+                index += 2;
+                continue;
+            }
+            if (/^-D.+/.test(arg)) {
+                index += 1;
+                continue;
+            }
+            break;
+        }
+        const paths = [];
+        for (; index < args.length; index += 1) {
+            const arg = args[index];
+            if (arg.startsWith("-"))
+                break;
+            paths.push(arg);
+        }
+        return paths;
+    }
+    const positionals = [];
+    let explicitPattern = false;
+    let afterTerminator = false;
+    let listFiles = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (afterTerminator) {
+            positionals.push(arg);
+            continue;
+        }
+        if (arg === "--") {
+            afterTerminator = true;
+            continue;
+        }
+        if (arg === "--files") {
+            listFiles = true;
+            continue;
+        }
+        if (VALUE_OPTIONS.has(arg)) {
+            if (["-e", "--regexp", "-f", "--file"].includes(arg))
+                explicitPattern = true;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--")) {
+            if (arg.startsWith("--regexp=") || arg.startsWith("--file="))
+                explicitPattern = true;
+            continue;
+        }
+        if (arg.startsWith("-") && arg.length > 1) {
+            if (/^-e.+$/.test(arg) || /^-f.+$/.test(arg))
+                explicitPattern = true;
+            continue;
+        }
+        positionals.push(arg);
+    }
+    if (listFiles || explicitPattern)
+        return positionals;
+    return positionals.slice(1);
+}
+function canonicalPath(candidate) {
+    try {
+        return fs.realpathSync(candidate);
+    }
+    catch {
+        return path.resolve(candidate);
+    }
+}
+function searchesBroadRoot(hqRoot, processInfo, command, args) {
+    const roots = new Set([
+        canonicalPath(hqRoot),
+        canonicalPath(path.join(hqRoot, "workspace")),
+        canonicalPath(os.homedir()),
+        path.parse(path.resolve("/")).root,
+    ]);
+    const operands = positionalArgs(command, args);
+    const candidates = operands.length > 0
+        ? operands.map((operand) => path.resolve(processInfo.cwd || ".", operand))
+        : [processInfo.cwd || "."];
+    return candidates.some((candidate) => roots.has(canonicalPath(candidate)));
+}
+function isUnboundedSearch(hqRoot, processInfo, findMaxdepthExempt) {
+    const command = commandName(processInfo.command);
+    if (!SEARCH_COMMANDS.has(command))
+        return false;
+    const args = processInfo.argv.slice(1);
+    if (command === "find") {
+        if (args.includes("-prune"))
+            return false;
+        const depth = findDepth(args);
+        if (depth !== null && depth <= findMaxdepthExempt)
+            return false;
+        return searchesBroadRoot(hqRoot, processInfo, command, args);
+    }
+    if (!hasNoIgnoreFlag(command, args))
+        return false;
+    return searchesBroadRoot(hqRoot, processInfo, command, args);
+}
+function laneAncestor(processInfo, processByPid, laneByPid, currentUid) {
+    let parentPid = processInfo.ppid;
+    const visited = new Set([processInfo.pid]);
+    for (let depth = 0; depth < 128; depth += 1) {
+        const laneId = laneByPid.get(parentPid);
+        if (laneId)
+            return laneId;
+        if (parentPid <= 1 || visited.has(parentPid))
+            return null;
+        visited.add(parentPid);
+        const parent = processByPid.get(parentPid);
+        if (!parent || parent.uid !== currentUid)
+            return null;
+        parentPid = parent.ppid;
+    }
+    return null;
+}
+function errorName(error) {
+    return error instanceof Error ? error.name : "UnknownError";
+}
+export function runRunawayToolGuard(input) {
+    const processByPid = new Map();
+    for (const processInfo of input.processes) {
+        if (Number.isSafeInteger(processInfo.pid) && processInfo.pid > 1) {
+            processByPid.set(processInfo.pid, processInfo);
+        }
+    }
+    const laneByPid = new Map();
+    const ambiguousPids = new Set();
+    for (const lane of input.lanes) {
+        const agent = processByPid.get(lane.agentPid);
+        if (!agent ||
+            !Number.isSafeInteger(lane.agentStarttime) ||
+            agent.starttime !== lane.agentStarttime ||
+            agent.uid !== input.currentUid ||
+            agent.pid === agent.ppid)
+            continue;
+        if (laneByPid.has(lane.agentPid))
+            ambiguousPids.add(lane.agentPid);
+        else
+            laneByPid.set(lane.agentPid, lane.laneId);
+    }
+    for (const pid of ambiguousPids)
+        laneByPid.delete(pid);
+    let stopped = 0;
+    for (const processInfo of input.processes) {
+        if (processInfo.uid !== input.currentUid ||
+            !Number.isFinite(processInfo.elapsedSeconds) ||
+            processInfo.elapsedSeconds <= input.config.max_age_seconds ||
+            processInfo.starttime === null ||
+            !isUnboundedSearch(input.hqRoot, processInfo, input.config.find_maxdepth_exempt))
+            continue;
+        const laneId = laneAncestor(processInfo, processByPid, laneByPid, input.currentUid);
+        if (!laneId || !input.isCurrentProcess(processInfo.pid, processInfo.starttime))
+            continue;
+        try {
+            input.signal(processInfo.pid, "SIGTERM");
+        }
+        catch (error) {
+            if (error.code !== "ESRCH") {
+                input.reportError("signal", errorName(error));
+            }
+            continue;
+        }
+        const command = commandName(processInfo.command);
+        const durationSeconds = Math.floor(processInfo.elapsedSeconds);
+        stopped += 1;
+        try {
+            input.recordEvent(laneId, {
+                event: "runaway_search_stopped",
+                at: input.now.toISOString(),
+                pid: processInfo.pid,
+                command,
+                duration_seconds: durationSeconds,
+            });
+        }
+        catch (error) {
+            input.reportError("record", errorName(error));
+        }
+        try {
+            input.notifyLane(laneId, `runaway-search-guard stopped ${command} after ${durationSeconds}s. Narrow the search to the smallest repo path that holds the answer and keep ignore rules on.`);
+        }
+        catch (error) {
+            input.reportError("notify", errorName(error));
+        }
+    }
+    return { stopped };
+}
+/** Read the host process table once. argv and cwd are read only for search tools. */
+export function listHostProcesses() {
+    if (process.platform !== "linux")
+        return [];
+    let output;
+    try {
+        output = execFileSync("ps", ["-eo", "pid=,ppid=,etimes=,uid=,comm="], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2_000,
+            maxBuffer: 8 * 1024 * 1024,
+            windowsHide: true,
+        });
+    }
+    catch {
+        throw new Error("ps process-table read failed");
+    }
+    const processes = [];
+    for (const line of output.split("\n")) {
+        const match = line.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(.+)$/);
+        if (!match)
+            continue;
+        const pid = Number(match[1]);
+        const ppid = Number(match[2]);
+        const elapsedSeconds = Number(match[3]);
+        const uid = Number(match[4]);
+        const command = match[5].trim();
+        if (![pid, ppid, elapsedSeconds, uid].every(Number.isSafeInteger) || !command)
+            continue;
+        let argv = [];
+        let cwd = "";
+        let starttime = null;
+        if (SEARCH_COMMANDS.has(commandName(command))) {
+            try {
+                const commandLine = fs.readFileSync(`/proc/${pid}/cmdline`);
+                argv = commandLine.toString("utf8").split("\0");
+                if (argv.at(-1) === "")
+                    argv.pop();
+                cwd = fs.readlinkSync(`/proc/${pid}/cwd`);
+                starttime = readProcStarttime(pid);
+            }
+            catch {
+                argv = [];
+                cwd = "";
+                starttime = null;
+            }
+        }
+        processes.push({ pid, ppid, elapsedSeconds, uid, command, argv, cwd, starttime });
+    }
+    return processes;
+}
+export { DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG } from "./config.js";
+//# sourceMappingURL=runaway-tool-guard.js.map

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

@@ -891,6 +891,12 @@ export interface TrackerChecksConfig {
     kpi_value_max_age_ms: number;
     directive_ack_timeout_ms: number;
 }
+export interface RunawaySearchGuardConfig {
+    /** Wall-time threshold before an unbounded descendant search is stopped. */
+    max_age_seconds: number;
+    /** `find` searches at this depth or less are left alone. */
+    find_maxdepth_exempt: number;
+}
 export interface LanesConfig {
     schema_version: typeof CONFIG_SCHEMA_VERSION | string;
     providers: Record<LaneProvider, ProviderConfig>;
@@ -899,6 +905,7 @@ export interface LanesConfig {
     tracker: {
         checks: TrackerChecksConfig;
     };
+    runaway_search_guard?: RunawaySearchGuardConfig;
     /** Seconds an unanswered question waits at a session audience before advancing. */
     session_question_timeout_secs: number;
     /** Age in hours after which an open manager blocker must be re-verified. */

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

@@ -130,6 +130,8 @@ export declare function watcherEventsPath(hqRoot: string, laneId: string): strin
 export declare function watcherOutLogPath(hqRoot: string, laneId: string): string;
 export declare function appendCappedLog(filePath: string, line: string, maxBytes?: number): void;
 export declare function writeWatcherDecision(filePath: string, record: Record<string, unknown>, maxBytes?: number): void;
+/** Append a decision to the shared event stream without a read-modify-write. */
+export declare function appendWatcherEvent(filePath: string, record: Record<string, unknown>, appendLine?: (target: string, line: string) => void): void;
 export declare function watcherLastSignalPath(hqRoot: string, laneId: string): string;
 export declare function appendWatcherSignal(hqRoot: string, laneId: string, signal: WatcherSignal): void;
 /**

package/dist/lib/lanes/watcher.js

@@ -223,6 +223,16 @@ export function writeWatcherDecision(filePath, record, maxBytes = WATCHER_OUT_MA
     }
     appendCappedLog(filePath, JSON.stringify(compact), maxBytes);
 }
+/** Append a decision to the shared event stream without a read-modify-write. */
+export function appendWatcherEvent(filePath, record, appendLine = (target, line) => fs.appendFileSync(target, line, "utf8")) {
+    const compact = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (value !== undefined)
+            compact[key] = value;
+    }
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    appendLine(filePath, `${JSON.stringify(compact)}\n`);
+}
 export function watcherLastSignalPath(hqRoot, laneId) {
     return path.join(laneRunDir(hqRoot, laneId), "watcher", "last-signal.json");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.277.0",
+  "version": "5.278.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {