@indigoai-us/hq-cli 5.345.147 → 5.345.148

package/dist/lib/lanes/local-host-identity.js

@@ -0,0 +1,314 @@
+import { spawnSync } from "node:child_process";
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { LanesError } from "./errors.js";
+export const LANE_HOST_SCHEMA = "hq-lane-host.v1";
+export const LANE_HOST_FILENAME = "lane-host.json";
+const MAX_ALIASES = 32;
+/**
+ * mDNS and DHCP rename a machine by swapping only this suffix
+ * (`Mac.localdomain` → `Mac.lan`). The label before the first dot must match,
+ * and the entire remainder must be one of these. `ec2.internal` and public
+ * DNS names are not in the set.
+ *
+ * A lane stamped with the bare label (`Mac`) matches a current or recorded
+ * name whose first label is that same word (`Mac.lan`). Two different
+ * machines that share a short label and a lane store can still collide for
+ * an old hostname-stamped lane. New lanes record the stable id below, and a
+ * copied home directory remints that id when the hardware id differs.
+ */
+const LINK_LOCAL_SUFFIXES = new Set(["local", "localdomain", "lan", "home"]);
+const HOST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+export function laneHostIdentityPath(homedir) {
+    return path.join(homedir, ".hq", LANE_HOST_FILENAME);
+}
+function corruptIdentity(file, problem, details = {}) {
+    return new LanesError("host_identity_corrupt", `${problem} The lane host file is ${file}. Restore that file, or delete it if no lane's host id came from it, then retry. Do not edit a lane's host.id by hand.`, { path: file, ...details });
+}
+function assertHostId(file, id) {
+    const trimmed = id.trim();
+    if (!HOST_ID_PATTERN.test(trimmed)) {
+        throw corruptIdentity(file, `Lane host id ${JSON.stringify(id)} is not a stable host id.`);
+    }
+    return trimmed;
+}
+function linkLocalLabel(name) {
+    const trimmed = name.trim();
+    const dot = trimmed.indexOf(".");
+    if (dot <= 0)
+        return null;
+    const suffix = trimmed.slice(dot + 1);
+    if (!LINK_LOCAL_SUFFIXES.has(suffix))
+        return null;
+    const label = trimmed.slice(0, dot);
+    return label.length > 0 ? label : null;
+}
+function linkLocalSameMachine(recorded, current) {
+    const recordedLabel = linkLocalLabel(recorded);
+    const currentLabel = linkLocalLabel(current);
+    return recordedLabel !== null && recordedLabel === currentLabel;
+}
+function firstLabel(name) {
+    const trimmed = name.trim();
+    const dot = trimmed.indexOf(".");
+    return dot === -1 ? trimmed : trimmed.slice(0, dot);
+}
+/** A bare stamp (`Mac`) and a longer name with that first label (`Mac.lan`) are the same machine. */
+function bareLabelSameMachine(recorded, current) {
+    const left = recorded.trim();
+    const right = current.trim();
+    if (!left || !right || left === right)
+        return false;
+    const leftBare = !left.includes(".");
+    const rightBare = !right.includes(".");
+    if (leftBare === rightBare)
+        return false;
+    const bare = leftBare ? left : right;
+    const dotted = leftBare ? right : left;
+    return bare === firstLabel(dotted);
+}
+function sameMachineName(recorded, current) {
+    return linkLocalSameMachine(recorded, current) || bareLabelSameMachine(recorded, current);
+}
+/** True when `recordedId` is this machine's stable id, current hostname, or a known earlier hostname. */
+export function localHostIdsReferToSameMachine(recordedId, host) {
+    const recorded = recordedId.trim();
+    if (!recorded)
+        return false;
+    const hostname = host.hostname.trim();
+    if (hostname !== "" && recorded === hostname)
+        return true;
+    const machineId = host.machineId?.trim();
+    if (machineId && recorded === machineId)
+        return true;
+    const aliases = host.aliases ?? [];
+    if (aliases.some((alias) => alias.trim() === recorded))
+        return true;
+    if (hostname !== "" && sameMachineName(recorded, hostname))
+        return true;
+    return aliases.some((alias) => sameMachineName(recorded, alias));
+}
+function cleanedAliases(file, aliases) {
+    if (!Array.isArray(aliases)) {
+        throw corruptIdentity(file, "Lane host identity aliases must be a list.");
+    }
+    const cleaned = [];
+    for (const alias of aliases) {
+        if (typeof alias !== "string") {
+            throw corruptIdentity(file, "Lane host identity aliases must be strings.");
+        }
+        const trimmed = alias.trim();
+        if (!trimmed || cleaned.includes(trimmed))
+            continue;
+        cleaned.push(trimmed);
+    }
+    return cleaned;
+}
+function withHostname(aliases, hostname) {
+    const host = hostname.trim();
+    const next = [...aliases];
+    if (host && !next.includes(host))
+        next.push(host);
+    if (next.length <= MAX_ALIASES)
+        return next;
+    const kept = next.slice(next.length - MAX_ALIASES);
+    if (host && !kept.includes(host)) {
+        kept.shift();
+        kept.push(host);
+    }
+    return kept;
+}
+function normalizeHardwareId(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.length > 128 || /\s/.test(trimmed))
+        return null;
+    return trimmed;
+}
+function parseIdentity(file, raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw corruptIdentity(file, "Lane host identity file is not valid JSON.");
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw corruptIdentity(file, "Lane host identity file is not an object.");
+    }
+    const record = parsed;
+    if (record.schema_version !== LANE_HOST_SCHEMA) {
+        throw corruptIdentity(file, "Lane host identity file has the wrong schema.", {
+            schema_version: record.schema_version ?? null,
+        });
+    }
+    if (typeof record.id !== "string") {
+        throw corruptIdentity(file, "Lane host identity file is missing an id.");
+    }
+    let hardwareId;
+    if (record.hardware_id !== undefined) {
+        const normalized = normalizeHardwareId(record.hardware_id);
+        if (!normalized) {
+            throw corruptIdentity(file, "Lane host identity hardware id is not usable.");
+        }
+        hardwareId = normalized;
+    }
+    return {
+        schema_version: LANE_HOST_SCHEMA,
+        id: assertHostId(file, record.id),
+        aliases: cleanedAliases(file, record.aliases),
+        ...(hardwareId ? { hardware_id: hardwareId } : {}),
+    };
+}
+function serialize(identity) {
+    return `${JSON.stringify(identity, null, 2)}\n`;
+}
+function readIdentityFile(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    return parseIdentity(file, raw);
+}
+function sameAliases(left, right) {
+    return left.length === right.length && left.every((alias, index) => alias === right[index]);
+}
+function writeIdentity(file, identity) {
+    const dir = path.dirname(file);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = path.join(dir, `.${LANE_HOST_FILENAME}.${crypto.randomBytes(6).toString("hex")}.tmp`);
+    fs.writeFileSync(tmp, serialize(identity));
+    fs.renameSync(tmp, file);
+}
+function readTextFile(file) {
+    try {
+        const text = fs.readFileSync(file, "utf8").trim();
+        return text || null;
+    }
+    catch {
+        return null;
+    }
+}
+let cachedHardwareId;
+function readPlatformHardwareId() {
+    if (process.platform === "darwin") {
+        const result = spawnSync("ioreg", ["-rd1", "-c", "IOPlatformExpertDevice"], {
+            encoding: "utf8",
+            timeout: 2000,
+        });
+        if (result.error || result.status !== 0)
+            return null;
+        const match = (result.stdout ?? "").match(/"IOPlatformUUID"\s*=\s*"([^"]+)"/);
+        return match?.[1]?.trim() || null;
+    }
+    if (process.platform === "linux") {
+        return readTextFile("/etc/machine-id") ?? readTextFile("/var/lib/dbus/machine-id");
+    }
+    if (process.platform === "win32") {
+        const result = spawnSync("reg", ["query", "HKLM\\SOFTWARE\\Microsoft\\Cryptography", "/v", "MachineGuid"], {
+            encoding: "utf8",
+            timeout: 2000,
+        });
+        if (result.error || result.status !== 0)
+            return null;
+        const match = (result.stdout ?? "").match(/MachineGuid\s+REG_SZ\s+(\S+)/);
+        return match?.[1]?.trim() || null;
+    }
+    return null;
+}
+function currentHardwareId(readHardwareId) {
+    if (readHardwareId)
+        return normalizeHardwareId(safeRead(readHardwareId));
+    if (cachedHardwareId !== undefined)
+        return cachedHardwareId;
+    cachedHardwareId = normalizeHardwareId(safeRead(readPlatformHardwareId));
+    return cachedHardwareId;
+}
+function safeRead(read) {
+    try {
+        return read();
+    }
+    catch {
+        return null;
+    }
+}
+function mintIdentity(file, hostname, hardwareId, createId) {
+    return {
+        schema_version: LANE_HOST_SCHEMA,
+        id: assertHostId(file, (createId ?? (() => crypto.randomUUID()))()),
+        aliases: hostname ? [hostname] : [],
+        ...(hardwareId ? { hardware_id: hardwareId } : {}),
+    };
+}
+function alignStoredIdentity(file, existing, hostname, hardwareId, createId) {
+    if (hardwareId && existing.hardware_id && existing.hardware_id !== hardwareId) {
+        const reminted = mintIdentity(file, hostname, hardwareId, createId);
+        writeIdentity(file, reminted);
+        return reminted;
+    }
+    const aliases = withHostname(existing.aliases, hostname);
+    const next = {
+        ...existing,
+        aliases,
+        ...(hardwareId && !existing.hardware_id ? { hardware_id: hardwareId } : {}),
+    };
+    if (next.hardware_id === existing.hardware_id && sameAliases(aliases, existing.aliases))
+        return existing;
+    writeIdentity(file, next);
+    return next;
+}
+/**
+ * Read the stable id, creating it once. A lost race re-reads the winner
+ * instead of minting a second id that would strand the lanes just created.
+ * A stored hardware id that does not match this machine mints a new id so a
+ * cloned home directory does not keep the source machine's id.
+ */
+export function resolveLocalHostIdentity(input) {
+    const hostname = input.hostname.trim();
+    if (!hostname) {
+        throw new LanesError("host_identity_unknown", "Cannot resolve this host for lane placement", {});
+    }
+    const file = laneHostIdentityPath(input.homedir);
+    const hardwareId = currentHardwareId(input.readHardwareId);
+    const existing = readIdentityFile(file);
+    if (existing)
+        return alignStoredIdentity(file, existing, hostname, hardwareId, input.createId);
+    const created = mintIdentity(file, hostname, hardwareId, input.createId);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    try {
+        fs.writeFileSync(file, serialize(created), { flag: "wx" });
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err;
+        const raced = readIdentityFile(file);
+        if (!raced) {
+            throw corruptIdentity(file, "Lane host identity file disappeared while it was created.");
+        }
+        return alignStoredIdentity(file, raced, hostname, hardwareId, input.createId);
+    }
+    return created;
+}
+/**
+ * Read an existing identity. Does not create the file, record a hostname,
+ * or replace an id. A hardware mismatch returns null so a cloned id is not
+ * treated as this machine.
+ */
+export function observeLocalHostIdentity(input) {
+    const file = laneHostIdentityPath(input.homedir);
+    const existing = readIdentityFile(file);
+    if (!existing)
+        return null;
+    const hardwareId = currentHardwareId(input.readHardwareId);
+    if (hardwareId && existing.hardware_id && existing.hardware_id !== hardwareId)
+        return null;
+    return existing;
+}
+//# sourceMappingURL=local-host-identity.js.map

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

@@ -1,4 +1,4 @@
-import type { LaneRecord } from "./types.js";
+import { type LaneRecord } from "./types.js";
 import { type LegacyPoolFinding } from "./legacy-pool.js";
 export declare const DEFAULT_REAP_MIN_AGE_MINUTES = 120;
 export declare const REAP_SINGLE_FLIGHT_LOCK_STALE_MS: number;

package/dist/lib/lanes/reaper.js

@@ -8,6 +8,7 @@ import { laneRunsOnHost } from "./admission.js";
 import { laneRunDir, isPidRecordAlive, readPidRecord, readProcStarttime } from "./spawn.js";
 import { readAllLanes, readLane } from "./store.js";
 import { LanesError } from "./errors.js";
+import { isSubagentLane } from "./types.js";
 import { findLegacyPoolLanes, stopLegacyPoolLane } from "./legacy-pool.js";
 export const DEFAULT_REAP_MIN_AGE_MINUTES = 120;
 export const REAP_SINGLE_FLIGHT_LOCK_STALE_MS = 60 * 60 * 1000;
@@ -220,6 +221,12 @@ export async function classifyLocalLanes(root, now, minAgeMinutes, deps = {}) {
         const ageMs = now.getTime() - Date.parse(lane.created_at);
         const age = Number.isFinite(ageMs) ? Math.max(0, Math.floor(ageMs / 60_000)) : 0;
         const finding = { lane_id: lane.lane_id, orphaned: false, reason: "not_a_candidate", age_minutes: age };
+        if (isSubagentLane(lane)) {
+            // A subagent lane has no process tree to reap; its senior session owns it.
+            finding.reason = "subagent_runner";
+            result.push(finding);
+            continue;
+        }
         const laneRunDirectory = laneRunDir(root, lane.lane_id);
         const workerRecord = readPidRecord(path.join(laneRunDirectory, "worker.pid"));
         const watcherRecord = readPidRecord(path.join(laneRunDirectory, "watcher.pid"));

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

@@ -87,6 +87,10 @@ export interface ReconcileSummary {
 export interface ReconcileHost {
     hostname: string;
     outpostId: string | null;
+    /** Stable id from ~/.hq/lane-host.json, when this process has read one. */
+    machineId?: string;
+    /** Hostnames this machine has already used. */
+    aliases?: readonly string[];
 }
 export interface ReconcileDeps {
     now: () => Date;

package/dist/lib/lanes/reconcile.js

@@ -22,7 +22,7 @@ import { terminalChildResumeHireGrantError, withHireGrantAdmission, } from "./gr
 import { classifySessionLiveness, defaultLivenessDeps, loadLivenessIndex, readDaemonPresenceConnected, unindexedClaudeSessionLiveness, } from "./liveness.js";
 import { ANSWERED_QUESTIONS_FILE, armLaneWatcher, envelopeRepairMode, isPidRecordAlive, laneRunDir, nextEnvelopePath, readPidRecord, readProcStarttime, readSpawnManifest, markSpawnFailure, stopLaneProcesses, spawnEnvelopeRepair, spawnLaneWorker, retryLaneOnAlternateAccount, } from "./spawn.js";
 import { appendCappedHistory, lanesStoreRoot, parseLaneRecord, parseQuestionRecord, readLane, retryUpdateLane, readQuestion, listQuestionIds, updateLane, updateQuestion, } from "./store.js";
-import { applyThrottleDecision, decideAdmission, defaultThrottleDeps, emptyThrottleState, evaluateThrottle, isCpuCheckEnabled, readAvailableMemMb, readThrottleState, resolveCpuBusyFraction, sampleCpuBusyObservation, recordCpuBusyObservation, throttleStatePath, writeThrottleState, } from "./throttle.js";
+import { applyThrottleDecision, decideAdmission, defaultThrottleDeps, emptyThrottleState, evaluateThrottle, isCpuCheckEnabled, readMemorySignal, readThrottleState, resolveCpuBusyFraction, sampleCpuBusyObservation, recordCpuBusyObservation, throttleStatePath, writeThrottleState, } from "./throttle.js";
 import { readLanesRegistryFlag, readLanesRegistryFlagFailOff, readLanesRegistryFlagFailOpen } from "./registry-flag.js";
 import { LANE_BLOCKED_ESCALATION_FLAG, LANE_HIRE_GRANT_FINISHED_LANES_FLAG, LANE_KEEP_ALIVE_DUE_WAKE_PRECISE_FLAG, LANE_LEAD_ADMISSION_PRIORITY_FLAG, LANE_QUOTA_ACCOUNT_FAILOVER_FLAG, LANE_ENVELOPE_REPAIR_GUIDANCE_FLAG, } from "./flag-keys.js";
 import { checkLaneDiskSpace, configuredCodexRolloutHomes, laneDiskAccount, retainCodexRollouts } from "./disk-guard.js";
@@ -32,7 +32,7 @@ import { monitorSessionDir } from "../monitor.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_RESUME_BLOCKED_FLAG, LEAD_LANE_KEEP_ALIVE_IMMEDIATE_FIRST_RESUME_FLAG, LEAD_LANE_KEEP_ALIVE_FIRST_RESUME_SETTLE_MS, LEAD_LANE_KEEP_ALIVE_BLOCKED_GRACE_MS, LEAD_LANE_KEEP_ALIVE_BLOCKED_RESUME_TEXT, queueLaneTerminalResume, 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, dueKeepAliveNextCheckMs, hasPendingKeepAliveWork, keepAliveNextCheckAtMs, keepAliveExclusion, loadRetiredLaneIds, leadLaneKeepAliveBackoffMs, undeliveredAnsweredQuestions, } from "./keep-alive.js";
 import { isFailedQuotaKeepAliveLane, providerSupportsSessionResume } from "./delivery.js";
-import { LANE_PROVIDERS, isIsoDateTime, isTerminalLaneState } from "./types.js";
+import { LANE_PROVIDERS, isIsoDateTime, isSubagentLane, isTerminalLaneState } from "./types.js";
 import { applyDefaultQuotaHold, clearAccountQuotaAfterSuccessfulTurnBestEffort, readQuotaSignal, recordAccountQuota, } from "./quota.js";
 import { deliverQuotaNotice, quotaLaneNotice } from "./quota-notice.js";
 import { answeredQuestionEntries, questionRecordRefusalCode, raiseEnvelopeQuestions, resolveQuestionCompanyWithFallback, } from "./questions.js";
@@ -1586,6 +1586,10 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
     for (const lane of lanes) {
         if (lane.state !== "running")
             continue;
+        // No HQ process backs a subagent lane, so a missing pid is not a dead
+        // worker. Its senior session reports progress and the final envelope.
+        if (isSubagentLane(lane))
+            continue;
         const local = laneRunsHere(lane, deps.host);
         if (local) {
             const runDir = laneRunDir(hqRoot, lane.lane_id);
@@ -2097,11 +2101,12 @@ async function admitQueued(hqRoot, lanes, summary, deps, now, onlyLaneIds, exclu
     const busy = deps.cpuBusyFraction !== undefined
         ? deps.cpuBusyFraction
         : await resolveCpuBusyFraction(throttleDeps);
-    const availableMemMb = readAvailableMemMb(throttleDeps);
+    const memory = readMemorySignal(throttleDeps);
     const nowMs = now.getTime();
     const decision = evaluateThrottle({
         busy,
-        availableMemMb,
+        availableMemMb: memory?.available_mb ?? null,
+        memory,
         cpuCheckEnabled: isCpuCheckEnabled(throttleDeps.env),
         state: throttleState,
         throttle: config.throttle,
@@ -3570,11 +3575,14 @@ async function resumeAwaiting(hqRoot, lanes, questions, summary, deps, onlyLaneI
     if (deps.dryRun) {
         const loaded = readThrottleState(throttleStatePath(hqRoot), throttleDeps);
         const state = loaded === "missing" ? emptyThrottleState() : loaded;
+        const busy = deps.cpuBusyFraction !== undefined
+            ? deps.cpuBusyFraction
+            : deps.cpuObservation?.busy ?? await resolveCpuBusyFraction(throttleDeps);
+        const memory = readMemorySignal(throttleDeps);
         throttleDecision = evaluateThrottle({
-            busy: deps.cpuBusyFraction !== undefined
-                ? deps.cpuBusyFraction
-                : deps.cpuObservation?.busy ?? await resolveCpuBusyFraction(throttleDeps),
-            availableMemMb: readAvailableMemMb(throttleDeps),
+            busy,
+            availableMemMb: memory?.available_mb ?? null,
+            memory,
             cpuCheckEnabled: isCpuCheckEnabled(throttleDeps.env),
             state,
             throttle: config.throttle,

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

@@ -190,6 +190,17 @@ export declare const STANDING_AUTHORIZATION: string;
  * turn while it was still running; nothing in the brief said not to.
  */
 export declare const FOREGROUND_ONLY_RULE: string;
+/**
+ * Temp-home rule carried in every composed brief, for every provider. Lanes
+ * that ran tests under a raw mktemp HOME re-downloaded the Rust toolchain and
+ * pnpm store (1.4-1.8 GB) per run and never deleted the folder; on 2026-10-18
+ * that refilled about 45 GB of disk.
+ *
+ * The wrapper path is absolute because a worker's cwd is often a repo, not
+ * the HQ root. The wrapper ships in hq-core (hq-core-staging#1420); until an
+ * install has it, the command fails with "No such file".
+ */
+export declare function tempHomeRule(hqRoot: string): string;
 /**
  * The answers as written by the reconcile pass (`answered-questions.json`),
  * reduced to id + choice. A malformed file reads as no inline answers; the
@@ -288,6 +299,15 @@ export declare function markSpawnFailure(hqRoot: string, laneId: string, reasonR
  * Must run before the worker is spawned.
  */
 export declare function refuseOutpostSelfTarget(hqRoot: string, lane: LaneRecord, deps: SpawnLaneDeps): void;
+/**
+ * The hq CLI entry a watcher runs internal `hq lanes` commands through. A
+ * watcher admits queued lanes and retries accounts from its own process,
+ * where process.argv[1] is watcher-main.js rather than the CLI. Recording that
+ * path made envelope repair run `watcher-main.js lanes _spawn-envelope-repair`,
+ * which started a watcher for a lane named "lanes". A runner script in argv[1]
+ * is replaced by the CLI entry that ships beside this module.
+ */
+export declare function resolveHqCliEntry(override: string | undefined, argvEntry?: string | undefined, existsSync?: (file: string) => boolean): string | undefined;
 /** Arm (or re-arm) the detached per-lane watcher. */
 export declare function armLaneWatcher(hqRoot: string, laneId: string, deps?: SpawnLaneDeps): number;
 export interface SpawnManifestFile {

package/dist/lib/lanes/spawn.js

@@ -33,6 +33,7 @@ import { managerStatusGateHeartbeat } from "./manager-status-gate.js";
 import { LANE_QUOTA_ACCOUNT_FAILOVER_FLAG } from "./flag-keys.js";
 import { readLanesRegistryFlagFailOff } from "./registry-flag.js";
 import { LANE_WORKER_EXIT_PATH_ENV } from "./worker-process.js";
+import { isLaneRunnerEntry } from "./envelope-repair-dispatch.js";
 import { laneCompanyUidSource, resolveLaneCompany } from "./lane-company.js";
 import { LEAD_LANE_KEEP_ALIVE_BLOCKED_RESUME_TEXT } from "./keep-alive.js";
 import { copySessionFiles, planSessionCopy } from "./move-account.js";
@@ -45,7 +46,7 @@ import { resolveAdmissionHost } from "./admission-host.js";
 import { offlineFingerprint } from "../fingerprint/offline.js";
 import { SESSION_ID_ENV_VARS } from "../fingerprint/self-core.js";
 import { checkLaneDiskSpace, laneDiskAccount } from "./disk-guard.js";
-import { LANE_ENVELOPE_JSON_SCHEMA, ENVELOPE_INVALID_REASON, parseLaneProvider, } from "./types.js";
+import { LANE_ENVELOPE_JSON_SCHEMA, ENVELOPE_INVALID_REASON, isSubagentLane, parseLaneProvider, } from "./types.js";
 export const LANES_RUNS_REL = path.join("workspace", "lanes-runs");
 /** Written by reconcile before a resume spawn; the worker prompt names this path. */
 export const ANSWERED_QUESTIONS_FILE = "answered-questions.json";
@@ -1225,6 +1226,12 @@ function proveDetachedViaPs(pid) {
         return null;
     }
 }
+/** Refuse to start a provider process or watcher for a lane a subagent runs. */
+function assertProcessRunner(lane) {
+    if (!isSubagentLane(lane))
+        return;
+    throw new LanesError("subagent_lane_not_spawnable", `Lane ${lane.lane_id} is run by an in-session subagent; HQ does not start a process for it`, { lane_id: lane.lane_id, runner: "subagent" });
+}
 export function nextEnvelopePath(runDir) {
     const dir = path.join(runDir, "envelopes");
     let names = new Set();
@@ -1280,6 +1287,25 @@ export const FOREGROUND_ONLY_RULE = "FOREGROUND ONLY. Run every command, test su
     "Never background a process and end the turn while it is still running. " +
     "A turn that ends before the envelope is written is classified interrupted, " +
     "and whatever the background process produces afterwards is not read.";
+/**
+ * Temp-home rule carried in every composed brief, for every provider. Lanes
+ * that ran tests under a raw mktemp HOME re-downloaded the Rust toolchain and
+ * pnpm store (1.4-1.8 GB) per run and never deleted the folder; on 2026-10-18
+ * that refilled about 45 GB of disk.
+ *
+ * The wrapper path is absolute because a worker's cwd is often a repo, not
+ * the HQ root. The wrapper ships in hq-core (hq-core-staging#1420); until an
+ * install has it, the command fails with "No such file".
+ */
+export function tempHomeRule(hqRoot) {
+    const wrapper = path.join(path.resolve(hqRoot), "core", "scripts", "with-temp-home.sh");
+    const quoted = /^[\w./-]+$/.test(wrapper) ? wrapper : `'${wrapper.replace(/'/g, `'\\''`)}'`;
+    return ("TEMP HOME. When a command needs a throwaway $HOME, run it as " +
+        `\`bash ${quoted} -- <command>\`. ` +
+        "Never assign HOME from mktemp directly (HOME=$(mktemp -d) <command>, or export HOME the same way): " +
+        "each fresh home re-downloads the Rust toolchain and pnpm store and is never deleted. " +
+        "The wrapper keeps the real caches and removes the temp home when the command exits.");
+}
 /**
  * The answers as written by the reconcile pass (`answered-questions.json`),
  * reduced to id + choice. A malformed file reads as no inline answers; the
@@ -2036,15 +2062,34 @@ function writeSpawnManifest(runDir, input) {
             : {}),
     }, null, 2)}\n`);
 }
+/**
+ * The hq CLI entry a watcher runs internal `hq lanes` commands through. A
+ * watcher admits queued lanes and retries accounts from its own process,
+ * where process.argv[1] is watcher-main.js rather than the CLI. Recording that
+ * path made envelope repair run `watcher-main.js lanes _spawn-envelope-repair`,
+ * which started a watcher for a lane named "lanes". A runner script in argv[1]
+ * is replaced by the CLI entry that ships beside this module.
+ */
+export function resolveHqCliEntry(override, argvEntry = process.argv[1], existsSync = fs.existsSync) {
+    const explicit = override?.trim();
+    if (explicit)
+        return explicit;
+    const fromArgv = argvEntry?.trim();
+    if (fromArgv && !isLaneRunnerEntry(fromArgv))
+        return fromArgv;
+    const packaged = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../dist/index.js");
+    return existsSync(packaged) ? packaged : undefined;
+}
 /** Arm (or re-arm) the detached per-lane watcher. */
 export function armLaneWatcher(hqRoot, laneId, deps = {}) {
     const env = deps.env ?? process.env;
     const spawnProcess = deps.spawnProcess ?? defaultSpawnProcess;
     const proveDetached = deps.proveDetached ?? defaultProveDetached;
+    assertProcessRunner(readLane(hqRoot, laneId));
     const runDir = laneRunDir(hqRoot, laneId);
     const logsDir = path.join(runDir, "logs");
     ensureDir(logsDir);
-    const cliEntry = deps.hqCliEntry?.trim() || process.argv[1]?.trim();
+    const cliEntry = resolveHqCliEntry(deps.hqCliEntry);
     if (!cliEntry) {
         throw new LanesError("watcher_cli_entry_unavailable", "Cannot arm the lane watcher without the current hq CLI entrypoint", { lane_id: laneId });
     }
@@ -2167,6 +2212,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
     const runDir = laneRunDir(hqRoot, lane.lane_id);
     const previousSpawn = readSpawnManifest(runDir);
     const stored = readLane(hqRoot, lane.lane_id);
+    assertProcessRunner(stored);
     const recoveredSessionId = (typeof stored.provider_session_id === "string" && stored.provider_session_id.trim()
         ? stored.provider_session_id
         : undefined) ??

package/dist/lib/lanes/status-fields.js

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { assertNoSecretText } from "./text-scan.js";
 import { compareEnvelopeNames } from "./envelope-sequence.js";
-import { isTerminalLaneState } from "./types.js";
+import { isSubagentLane, isTerminalLaneState } from "./types.js";
 const OUTPUT_TAIL_BYTES = 64 * 1024;
 const INBOX_TAIL_BYTES = 32 * 1024;
 const PR_URL = /https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/pull\/\d+/g;
@@ -115,6 +115,11 @@ function startTimeMs(lane, runDir) {
         if (Number.isFinite(parsed) && parsed > 0)
             return parsed;
     }
+    if (isSubagentLane(lane)) {
+        // No worker.pid exists; the subagent started when its lane was registered.
+        const created = Date.parse(lane.created_at);
+        return Number.isFinite(created) ? created : null;
+    }
     try {
         return fs.statSync(path.join(runDir, "worker.pid")).mtimeMs;
     }

package/dist/lib/lanes/store.js

@@ -16,7 +16,7 @@ import { generateUlid } from "../mesh/live/ulid.js";
 import { resolveLanesHqRoot } from "./hq-root.js";
 import { readOutpostIdentity } from "./admission-host.js";
 import { LaneNotFoundError, LaneSchemaError, LaneVersionConflict, LanesError, isLaneVersionConflict, } from "./errors.js";
-import { HISTORY_CAP, HOST_KINDS, LANE_STORY_STATUSES, LANE_SCHEMA_VERSION, QUESTION_SCHEMA_VERSION, SENIOR_KINDS, isHostKind, isLaneProvider, isQueuedReason, isLaneState, isQuestionStatus, isSeniorKind, isTerminalLaneState, parseMajorSchema, REQUIRED_LANE_RECORD_FIELDS, LANE_FIELD_WRITERS, LANE_WRITERS, } from "./types.js";
+import { HISTORY_CAP, HOST_KINDS, LANE_STORY_STATUSES, LANE_SCHEMA_VERSION, QUESTION_SCHEMA_VERSION, SENIOR_KINDS, isHostKind, isLaneProvider, isQueuedReason, isLaneState, isQuestionStatus, isSeniorKind, isTerminalLaneState, parseMajorSchema, REQUIRED_LANE_RECORD_FIELDS, LANE_FIELD_WRITERS, LANE_RUNNERS, LANE_WRITERS, } from "./types.js";
 import { laneStories } from "./stories.js";
 import { laneStoryLedgerEnabled, syncLaneToProjectStoryLedger, validateProjectStories, } from "./story-ledger.js";
 export const LANES_STORE_REL = path.join("workspace", "lanes");
@@ -433,6 +433,13 @@ export function parseLaneRecord(raw, filePath) {
             value: raw.remote_control,
         });
     }
+    if (raw.runner !== undefined && raw.runner !== "subagent") {
+        throw new LaneSchemaError(`Unknown lane runner ${JSON.stringify(raw.runner)}. Accepted: ${LANE_RUNNERS.join(", ")}`, {
+            path: filePath,
+            field: "runner",
+            value: raw.runner,
+        });
+    }
     if (raw.remote_control_title !== undefined && (raw.remote_control !== true ||
         typeof raw.remote_control_title !== "string" ||
         raw.remote_control_title.trim() !== raw.remote_control_title ||