@indigoai-us/hq-cli 5.276.0 → 5.278.0

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/spawn.js

@@ -1726,9 +1726,11 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
     const recordedModel = repairRecordedAccount && existing.model_source === "account"
         ? existing.model
         : undefined;
-    let pinnedModel = existing.model_source === undefined || existing.model_source === "cli" || existing.model_source === "preserved"
+    // `hq lanes set` on a running lane leaves the change pending until this spawn.
+    const pendingSettings = existing.pending_settings;
+    let pinnedModel = pendingSettings?.model ?? (existing.model_source === undefined || existing.model_source === "cli" || existing.model_source === "preserved"
         ? existing.model
-        : undefined;
+        : undefined);
     const accountDeps = {
         probe: modelDeps.probe ?? defaultProbe,
         env,
@@ -1860,13 +1862,15 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
         providerModel: config.providers[lane.provider].model,
     });
     const pendingResumeEffort = pendingResume !== undefined
-        ? {
-            ...(existing.effort !== undefined ? { effort: existing.effort } : {}),
-            source: existing.effort_source ?? "none",
-        }
+        ? pendingSettings?.effort !== undefined
+            ? { effort: pendingSettings.effort, source: "cli" }
+            : {
+                ...(existing.effort !== undefined ? { effort: existing.effort } : {}),
+                source: existing.effort_source ?? "none",
+            }
         : undefined;
     const effort = launch.effort ?? pendingResumeEffort ?? resolveLaneEffort({
-        cliEffort: existing.effort_source === "cli" ? existing.effort : undefined,
+        cliEffort: pendingSettings?.effort ?? (existing.effort_source === "cli" ? existing.effort : undefined),
         profileEffort,
         accountEffort: accountCfg?.effort,
         providerEffort: config.providers[lane.provider].effort,
@@ -2026,15 +2030,18 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             terminal_details: undefined,
             // An account move's reservation ends with the claim.
             pending_resume: undefined,
+            pending_settings: undefined,
             account: resolved.id,
             provider_home_at_spawn: resolved.home,
             ...(model !== undefined ? { model } : {}),
             ...(model !== undefined
                 ? {
                     model_source: pinnedModel !== undefined
-                        ? preservedAccountModel !== undefined || existing.model_source === "preserved"
-                            ? "preserved"
-                            : "cli"
+                        ? preservedAccountModel === undefined && pendingSettings?.model !== undefined
+                            ? "cli"
+                            : preservedAccountModel !== undefined || existing.model_source === "preserved"
+                                ? "preserved"
+                                : "cli"
                         : profileModel !== undefined
                             ? "profile"
                             : accountCfg?.model !== undefined

package/dist/lib/lanes/store.js

@@ -475,6 +475,7 @@ export function parseLaneRecord(raw, filePath) {
         "keep_alive_next_eligible_at",
         "keep_alive_exhausted_at",
         "interrupted_at",
+        "last_run_usage_at",
     ]) {
         if (raw[field] !== undefined)
             requireTimestamp(raw[field], field, filePath);
@@ -694,6 +695,40 @@ export function parseLaneRecord(raw, filePath) {
             requireTimestamp(entry.at, `${field}.at`, filePath);
         }
     }
+    if (raw.settings_history !== undefined) {
+        if (!Array.isArray(raw.settings_history)) {
+            throw new LaneSchemaError("settings_history must be an array when present", {
+                path: filePath,
+                field: "settings_history",
+            });
+        }
+        for (const [index, entry] of raw.settings_history.entries()) {
+            const field = `settings_history[${index}]`;
+            if (!isPlainObject(entry) ||
+                Object.keys(entry).some((key) => !["at", "actor", "model", "effort", "reason"].includes(key)) ||
+                (entry.model === undefined && entry.effort === undefined)) {
+                throw new LaneSchemaError(`${field} must be a settings history entry`, { path: filePath, field });
+            }
+            requireTimestamp(entry.at, `${field}.at`, filePath);
+            if (typeof entry.actor !== "string" || entry.actor.trim() === "") {
+                throw new LaneSchemaError(`${field}.actor must be a non-empty string`, { path: filePath, field });
+            }
+            if (entry.reason !== undefined && (typeof entry.reason !== "string" || entry.reason.trim() === "")) {
+                throw new LaneSchemaError(`${field}.reason must be a non-empty string when present`, { path: filePath, field });
+            }
+            for (const key of ["model", "effort"]) {
+                const change = entry[key];
+                if (change === undefined)
+                    continue;
+                if (!isPlainObject(change) ||
+                    Object.keys(change).some((k) => k !== "from" && k !== "to") ||
+                    typeof change.to !== "string" || change.to.trim() === "" ||
+                    (change.from !== null && typeof change.from !== "string")) {
+                    throw new LaneSchemaError(`${field}.${key} must be a {from, to} change`, { path: filePath, field });
+                }
+            }
+        }
+    }
     if (raw.worker_profile_repin_history !== undefined) {
         if (!Array.isArray(raw.worker_profile_repin_history)) {
             throw new LaneSchemaError("worker_profile_repin_history must be an array when present", {
@@ -751,7 +786,7 @@ function parseLaneAccountSelection(value, filePath) {
     const selection = value;
     if (typeof selection.account !== "string" || selection.account.trim() === "")
         throw failure("account");
-    if (selection.signal !== "usage" && selection.signal !== "lane_count" && selection.signal !== "explicit")
+    if (selection.signal !== "usage" && selection.signal !== "recent_usage" && selection.signal !== "lane_count" && selection.signal !== "explicit")
         throw failure("signal");
     if (selection.reason !== "least_loaded" && selection.reason !== "explicit")
         throw failure("reason");
@@ -773,6 +808,10 @@ function parseLaneAccountSelection(value, filePath) {
             throw failure(`considered.${index}`);
         if (row.ineligible_reason !== undefined && typeof row.ineligible_reason !== "string")
             throw failure(`considered.${index}.ineligible_reason`);
+        if (row.recent_usage_at !== undefined && row.recent_usage_at !== null &&
+            (typeof row.recent_usage_at !== "string" || !Number.isFinite(Date.parse(row.recent_usage_at)))) {
+            throw failure(`considered.${index}.recent_usage_at`);
+        }
         if (row.usage !== null) {
             if (!isPlainObject(row.usage))
                 throw failure(`considered.${index}.usage`);
@@ -1015,6 +1054,11 @@ export function mergeLaneRecords(live, sidecars) {
                 failed_resume_history: unionHistory(all.map((record) => record.failed_resume_history ?? []), entryIdentity, base.failed_resume_history ?? []),
             }
             : {}),
+        ...(all.some((record) => record.settings_history !== undefined)
+            ? {
+                settings_history: unionHistory(all.map((record) => record.settings_history ?? []), entryIdentity, base.settings_history ?? []),
+            }
+            : {}),
         ...(all.some((record) => record.stop_history !== undefined)
             ? {
                 stop_history: unionHistory(all.map((record) => record.stop_history ?? []), entryIdentity, base.stop_history ?? []),

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

@@ -253,12 +253,14 @@ export interface LaneAccountSelectionConsidered {
         weekly_percent?: number;
         sampled_at?: string;
     } | null;
+    /** Latest completed run in the recent-usage window, when lane snapshots are complete. */
+    recent_usage_at?: string | null;
     hosts: LaneAccountSelectionHostCount[];
 }
 /** Decision evidence saved with a Claude lane when account balancing is active. */
 export interface LaneAccountSelection {
     account: string;
-    signal: "usage" | "lane_count" | "explicit";
+    signal: "usage" | "recent_usage" | "lane_count" | "explicit";
     reason: "least_loaded" | "explicit";
     target_host: LaneHost;
     selected_at: string;
@@ -287,6 +289,20 @@ export interface LaneStopHistoryEntry {
     at: string;
     reason: string;
 }
+/** One `hq lanes set` change; it takes effect when the lane next resumes. */
+export interface LaneSettingsHistoryEntry {
+    at: string;
+    actor: string;
+    model?: {
+        from: string | null;
+        to: string;
+    };
+    effort?: {
+        from: string | null;
+        to: string;
+    };
+    reason?: string;
+}
 /** Evidence for a senior-authorized Outpost worker-profile content re-pin. */
 export interface WorkerProfileRepinHistoryEntry {
     old_hash: string | null;
@@ -564,6 +580,17 @@ export interface LaneRecord {
     terminal_reason?: string;
     /** Reasons supplied to explicit stop commands, retained independently of optional project ledgers. */
     stop_history?: LaneStopHistoryEntry[];
+    /** Model and effort changes made with `hq lanes set`. */
+    settings_history?: LaneSettingsHistoryEntry[];
+    /**
+     * Model or effort from `hq lanes set` on a running lane. The running turn
+     * keeps its launched values (quota classification reads `model`); the next
+     * spawn applies these and clears them.
+     */
+    pending_settings?: {
+        model?: string;
+        effort?: string;
+    };
     /** Classification time when this lane entered interrupted; stable across later metadata writes. */
     interrupted_at?: string;
     /**
@@ -598,6 +625,8 @@ export interface LaneRecord {
     last_resume?: LaneResumeRecord;
     /** Cache counters from the last exited run's result. Nothing else from the payload. */
     last_run_usage?: LaneRunUsage;
+    /** Completion time paired with last_run_usage; written by the watcher. */
+    last_run_usage_at?: string;
     /**
      * Spec §4: one repair turn per expected envelope slot when the final output
      * is invalid or missing. Written before repair spawn and updated on repair
@@ -862,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>;
@@ -870,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/types.js

@@ -230,9 +230,9 @@ export const LANE_FIELD_WRITERS = {
     last_envelope: ["watcher", "reconcile"], model: ["creator", "spawn", "command"], model_source: ["creator", "spawn", "command"], effort: ["creator", "spawn", "command"], effort_source: ["creator", "spawn", "command"], fast_mode: ["spawn"],
     last_message_at: ["command"], status_gate: ["spawn", "watcher"], status_gate_history: ["watcher"], blocker_freshness_state: ["watcher"], kr_freshness_state: ["watcher"], last_compaction: ["spawn"], story_complete: ["watcher", "reconcile"], story_complete_reason: ["watcher", "reconcile"], story_status: ["watcher", "reconcile"],
     overdue: ["reconcile"], overdue_at: ["reconcile"], last_host_report_at: ["watcher", "spawn", "reconcile"], stalled: ["watcher"], stalled_at: ["watcher"], stalled_reason: ["watcher"],
-    admitted_reason: ["command", "reconcile"], terminal_reason: ["command", "watcher", "spawn", "reconcile"], stop_history: ["command"], interrupted_at: ["watcher", "reconcile"], terminal_details: ["command", "spawn", "watcher", "reconcile"],
+    admitted_reason: ["command", "reconcile"], terminal_reason: ["command", "watcher", "spawn", "reconcile"], stop_history: ["command"], settings_history: ["command"], pending_settings: ["command", "spawn"], interrupted_at: ["command", "watcher", "reconcile"], terminal_details: ["command", "spawn", "watcher", "reconcile"],
     quota_reset_at: ["watcher", "reconcile"], model_quota_marker: ["watcher", "reconcile"], outpost_command_id: ["command"],
-    provider_session_id: ["watcher", "command", "spawn"], provider_session_id_absent: ["watcher", "command"], provider_home_at_spawn: ["spawn"], last_resume: ["spawn"], last_run_usage: ["watcher"], envelope_repair: ["watcher", "reconcile"], envelope_validation_errors: ["watcher"], last_progress_event_at: ["watcher"],
+    provider_session_id: ["watcher", "command", "spawn"], provider_session_id_absent: ["watcher", "command"], provider_home_at_spawn: ["spawn"], last_resume: ["spawn"], last_run_usage: ["watcher"], last_run_usage_at: ["watcher"], envelope_repair: ["watcher", "reconcile"], envelope_validation_errors: ["watcher"], last_progress_event_at: ["watcher"],
 };
 function isPlainObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);

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");
 }
@@ -245,7 +255,7 @@ export function notifySlotFreed(_input) {
  * or unparseable id is recorded as absent with its reason, never invented.
  * Non-resumable providers return null and the record is left as it was.
  */
-function runResultFields(hqRoot, lane) {
+function runResultFields(hqRoot, lane, at) {
     const runDir = laneRunDir(hqRoot, lane.lane_id);
     const result = readWorkerRunResult(runDir, lane.provider, readSpawnManifest(runDir).worker_out_offset ?? 0);
     if (result === null)
@@ -255,6 +265,7 @@ function runResultFields(hqRoot, lane) {
             cache_read_input_tokens: result.cache_read_input_tokens,
             cache_creation_input_tokens: result.cache_creation_input_tokens,
         },
+        last_run_usage_at: at,
     };
     if (result.session_id !== null) {
         fields.provider_session_id = result.session_id;
@@ -366,7 +377,7 @@ export function applyTerminalToLaneWithResult(hqRoot, laneId, classification, op
         }
         const next = {
             ...current,
-            ...runResultFields(hqRoot, current),
+            ...runResultFields(hqRoot, current, at),
             state: effectiveClassification.state,
             queued_reason: undefined,
             stalled: undefined,

package/dist/secrets-env-fast-path.d.ts

@@ -0,0 +1,5 @@
+import type { ParsedSecretsEnvFastRequest } from "./fast-scaffold.js";
+import type { SecretsEnvFastResult } from "./secrets-env-fast-route.js";
+/** Run the shared secret action without importing the full CLI command graph. */
+export declare function runSecretsEnvFastPath(request: ParsedSecretsEnvFastRequest): Promise<SecretsEnvFastResult>;
+//# sourceMappingURL=secrets-env-fast-path.d.ts.map

package/dist/secrets-env-fast-path.js

@@ -0,0 +1,16 @@
+/** Run the shared secret action without importing the full CLI command graph. */
+export async function runSecretsEnvFastPath(request) {
+    if (process.env.HQ_AGENT_DIR?.trim()) {
+        const [os, { agentKitPaths }, { adoptAgentIdentityEnv }] = await Promise.all([
+            import("node:os"),
+            import("./lib/agent-kit/paths.js"),
+            import("./lib/agent-kit/adopt-identity.js"),
+        ]);
+        adoptAgentIdentityEnv(agentKitPaths(os.homedir(), process.env), process.env);
+    }
+    const { runSecretsEnvCommand } = await import("./commands/secrets.js");
+    return runSecretsEnvCommand(request.options, request.scope, {
+        fallbackOnAuthFailure: true,
+    });
+}
+//# sourceMappingURL=secrets-env-fast-path.js.map

package/dist/secrets-env-fast-route.d.ts

@@ -0,0 +1,18 @@
+/** Default-off hq-flags gate for the `secrets env` entry fast path. */
+import type { ParsedSecretsEnvFastRequest } from "./fast-scaffold.js";
+export declare const CLI_SECRETS_ENV_FAST_PATH_FLAG = "cli.secrets-env-fast-path";
+export type SecretsEnvFastResult = "handled" | "fallback";
+export interface SecretsEnvFastDispatchDeps {
+    isEnabled: () => Promise<boolean>;
+    runFast: () => Promise<SecretsEnvFastResult>;
+    runCurrent: () => Promise<void>;
+}
+/** Keep the existing command graph in control when the gate is off or declines. */
+export declare function dispatchSecretsEnvFastRequest(_request: ParsedSecretsEnvFastRequest, deps: SecretsEnvFastDispatchDeps): Promise<void>;
+/**
+ * Fast routes only use an explicit local override or the latest company flag
+ * snapshot. A missing company, stale snapshot, or unreadable cache leaves the
+ * current CLI path in control; it never performs a registry network request.
+ */
+export declare function secretsEnvFastRouteEnabled(request: ParsedSecretsEnvFastRequest, env?: NodeJS.ProcessEnv): Promise<boolean>;
+//# sourceMappingURL=secrets-env-fast-route.d.ts.map