@indigoai-us/hq-cli 5.345.147 → 5.345.149

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 ||

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

@@ -17,6 +17,14 @@ export declare const STARVATION_MAX_DEFERRALS = 10;
 export declare const STARVATION_MAX_MS: number;
 export declare const PROC_MEMINFO = "/proc/meminfo";
 export declare const VM_STAT_BIN = "/usr/bin/vm_stat";
+export declare const SYSCTL_BIN = "/usr/sbin/sysctl";
+/**
+ * The sysctls behind macOS `memory_pressure`: its "System-wide memory free
+ * percentage" is kern.memorystatus_level, and its pressure level is
+ * kern.memorystatus_vm_pressure_level (1 normal, 2 warn, 4 critical).
+ * hw.memsize turns the percentage into MiB for min_available_mem_mb.
+ */
+export declare const MEMORY_PRESSURE_SYSCTLS: readonly ["kern.memorystatus_level", "kern.memorystatus_vm_pressure_level", "hw.memsize"];
 export declare const LANES_CPU_BUSY_OVERRIDE = "HQ_LANES_CPU_BUSY_OVERRIDE";
 export declare const LANES_CPU_CHECK = "HQ_LANES_CPU_CHECK";
 export interface CpuTimes {
@@ -38,7 +46,8 @@ export interface ThrottleDeps {
     freemem: () => number;
     platform: () => NodeJS.Platform;
     /**
-     * Darwin only: read vm_stat when /proc/meminfo is absent. Unused on Linux.
+     * Darwin only: read the memory_pressure sysctls (vm_stat as a fallback) when
+     * /proc/meminfo is absent. Unused on Linux.
      */
     execFileSync: (file: string, args: readonly string[], options: {
         encoding: "utf8";
@@ -82,16 +91,45 @@ export declare function recordCpuBusyObservation(state: ThrottleState, observati
 export declare function parseMemAvailableKb(contents: string): number | null;
 /**
  * Available memory in MiB from darwin `vm_stat`: free + inactive + speculative
- * pages. That is the reclaimable set os.freemem() omits on macOS.
+ * pages. Only a fallback when the memory_pressure sysctls cannot be read: it
+ * leaves out purgeable and compressible memory, so it reads lower than
+ * `memory_pressure` on a Mac that is not under pressure.
  */
 export declare function parseVmStatAvailableMb(contents: string): number | null;
+export type MemoryPressureLevel = "normal" | "warn" | "critical";
+export type MemorySignalSource = "memory_pressure" | "vm_stat" | "meminfo" | "freemem";
+/** One memory reading and where it came from. */
+export interface MemorySignal {
+    source: MemorySignalSource;
+    available_mb: number;
+    /** memory_pressure only: "System-wide memory free percentage". */
+    free_percent?: number;
+    /** memory_pressure only: kern.memorystatus_vm_pressure_level. */
+    pressure_level?: MemoryPressureLevel;
+}
+/** The memory gate's reason for holding admission, shown to the user. */
+export interface MemoryHold extends MemorySignal {
+    threshold_mb: number;
+    message: string;
+}
+/**
+ * Parse `sysctl -n kern.memorystatus_level kern.memorystatus_vm_pressure_level
+ * hw.memsize`: one integer per line, in that order.
+ */
+export declare function parseMemoryPressureSysctl(contents: string): MemorySignal | null;
 /**
- * Available memory in MiB. Prefers kernel MemAvailable. On darwin without
- * /proc/meminfo, uses vm_stat (free+inactive+speculative) and never os.freemem().
- * Elsewhere, falls back to os.freemem() only where MemAvailable is absent.
- * Returning null skips the memory gate instead of holding every lane.
+ * Current memory reading for the admission gate. Prefers kernel MemAvailable.
+ * On darwin without /proc/meminfo, reads the same values `memory_pressure`
+ * prints (free percentage and pressure level), falls back to vm_stat, and never
+ * uses os.freemem(). Elsewhere, falls back to os.freemem() only where
+ * MemAvailable is absent. Returning null skips the memory gate instead of
+ * holding every lane.
  */
+export declare function readMemorySignal(deps?: ThrottleDeps): MemorySignal | null;
+/** Available memory in MiB from readMemorySignal; null skips the memory gate. */
 export declare function readAvailableMemMb(deps?: ThrottleDeps): number | null;
+/** Plain explanation of a memory hold: which signal, its value, and the threshold. */
+export declare function formatMemoryHoldMessage(signal: MemorySignal, thresholdMb: number): string;
 export interface ThrottleState {
     consecutiveDeferrals: number;
     lastAdmissionAt: string | null;
@@ -100,6 +138,8 @@ export interface ThrottleState {
     last_busy?: number | null;
     busy_source?: CpuBusySource;
     sampled_at?: string;
+    /** Set while the memory gate holds admission; cleared on the next admit or CPU hold. */
+    memory_hold?: MemoryHold;
 }
 export type ThrottleAdmitReason = "ok" | "starvation_bound" | "unreadable" | "cpu_check_disabled";
 export type ThrottleDeferReason = "cpu" | "memory";
@@ -111,12 +151,15 @@ export type ThrottleDecision = {
     reason: ThrottleDeferReason;
     busy?: number;
     availableMemMb?: number;
+    memory_hold?: MemoryHold;
 };
 export declare function emptyThrottleState(): ThrottleState;
 export declare function starvationBoundReached(state: ThrottleState, nowMs: number): boolean;
 export declare function evaluateThrottle(input: {
     busy: number | null;
     availableMemMb: number | null;
+    /** Where availableMemMb came from. Without it the reading is reported as MemAvailable. */
+    memory?: MemorySignal | null;
     cpuCheckEnabled: boolean;
     state: ThrottleState | "unreadable";
     throttle: ThrottleConfig;

package/dist/lib/lanes/throttle.js

@@ -22,6 +22,18 @@ export const STARVATION_MAX_MS = 30 * 60 * 1000;
 export const PROC_MEMINFO = "/proc/meminfo";
 export const VM_STAT_BIN = "/usr/bin/vm_stat";
 const VM_STAT_TIMEOUT_MS = 2_000;
+export const SYSCTL_BIN = "/usr/sbin/sysctl";
+/**
+ * The sysctls behind macOS `memory_pressure`: its "System-wide memory free
+ * percentage" is kern.memorystatus_level, and its pressure level is
+ * kern.memorystatus_vm_pressure_level (1 normal, 2 warn, 4 critical).
+ * hw.memsize turns the percentage into MiB for min_available_mem_mb.
+ */
+export const MEMORY_PRESSURE_SYSCTLS = [
+    "kern.memorystatus_level",
+    "kern.memorystatus_vm_pressure_level",
+    "hw.memsize",
+];
 export const LANES_CPU_BUSY_OVERRIDE = "HQ_LANES_CPU_BUSY_OVERRIDE";
 export const LANES_CPU_CHECK = "HQ_LANES_CPU_CHECK";
 function defaultSleep(ms) {
@@ -200,7 +212,9 @@ function parseVmStatPages(contents, label) {
 }
 /**
  * Available memory in MiB from darwin `vm_stat`: free + inactive + speculative
- * pages. That is the reclaimable set os.freemem() omits on macOS.
+ * pages. Only a fallback when the memory_pressure sysctls cannot be read: it
+ * leaves out purgeable and compressible memory, so it reads lower than
+ * `memory_pressure` on a Mac that is not under pressure.
  */
 export function parseVmStatAvailableMb(contents) {
     const pageSizeMatch = /page size of (\d+) bytes/i.exec(contents);
@@ -214,7 +228,53 @@ export function parseVmStatAvailableMb(contents) {
         return null;
     return ((free + inactive + speculative) * pageSize) / (1024 * 1024);
 }
-function readDarwinAvailableMemMb(deps) {
+const PRESSURE_LEVELS = {
+    1: "normal",
+    2: "warn",
+    4: "critical",
+};
+/**
+ * Parse `sysctl -n kern.memorystatus_level kern.memorystatus_vm_pressure_level
+ * hw.memsize`: one integer per line, in that order.
+ */
+export function parseMemoryPressureSysctl(contents) {
+    const lines = contents.split("\n").map((line) => line.trim()).filter((line) => line !== "");
+    if (lines.length !== MEMORY_PRESSURE_SYSCTLS.length)
+        return null;
+    if (!lines.every((line) => /^\d+$/.test(line)))
+        return null;
+    const [freePercent, level, memsize] = lines.map(Number);
+    const pressureLevel = PRESSURE_LEVELS[level];
+    if (!Number.isSafeInteger(freePercent) || freePercent < 0 || freePercent > 100 ||
+        pressureLevel === undefined ||
+        !Number.isSafeInteger(memsize) || memsize <= 0) {
+        return null;
+    }
+    return {
+        source: "memory_pressure",
+        available_mb: (memsize * (freePercent / 100)) / (1024 * 1024),
+        free_percent: freePercent,
+        pressure_level: pressureLevel,
+    };
+}
+function readDarwinMemoryPressure(deps) {
+    try {
+        const contents = deps.execFileSync(SYSCTL_BIN, ["-n", ...MEMORY_PRESSURE_SYSCTLS], {
+            encoding: "utf8",
+            timeout: VM_STAT_TIMEOUT_MS,
+        });
+        const signal = parseMemoryPressureSysctl(contents);
+        if (signal !== null)
+            return signal;
+        process.stderr.write("lanes throttle: darwin memory_pressure sysctls were unreadable; falling back to vm_stat\n");
+        return null;
+    }
+    catch (err) {
+        process.stderr.write(`lanes throttle: darwin memory_pressure sysctls failed: ${err instanceof Error ? err.message : String(err)}; falling back to vm_stat\n`);
+        return null;
+    }
+}
+function readDarwinVmStat(deps) {
     try {
         const contents = deps.execFileSync(VM_STAT_BIN, [], {
             encoding: "utf8",
@@ -222,7 +282,7 @@ function readDarwinAvailableMemMb(deps) {
         });
         const mb = parseVmStatAvailableMb(contents);
         if (mb !== null)
-            return mb;
+            return { source: "vm_stat", available_mb: mb };
         process.stderr.write("lanes throttle: darwin vm_stat output was unreadable; skipping the memory gate\n");
         return null;
     }
@@ -236,7 +296,7 @@ function readFreememMb(deps) {
         const bytes = deps.freemem();
         if (!Number.isFinite(bytes) || bytes < 0)
             return null;
-        return bytes / (1024 * 1024);
+        return { source: "freemem", available_mb: bytes / (1024 * 1024) };
     }
     catch (err) {
         process.stderr.write(`lanes throttle: freemem fallback failed: ${err instanceof Error ? err.message : String(err)}\n`);
@@ -244,17 +304,19 @@ function readFreememMb(deps) {
     }
 }
 /**
- * Available memory in MiB. Prefers kernel MemAvailable. On darwin without
- * /proc/meminfo, uses vm_stat (free+inactive+speculative) and never os.freemem().
- * Elsewhere, falls back to os.freemem() only where MemAvailable is absent.
- * Returning null skips the memory gate instead of holding every lane.
+ * Current memory reading for the admission gate. Prefers kernel MemAvailable.
+ * On darwin without /proc/meminfo, reads the same values `memory_pressure`
+ * prints (free percentage and pressure level), falls back to vm_stat, and never
+ * uses os.freemem(). Elsewhere, falls back to os.freemem() only where
+ * MemAvailable is absent. Returning null skips the memory gate instead of
+ * holding every lane.
  */
-export function readAvailableMemMb(deps = defaultThrottleDeps()) {
+export function readMemorySignal(deps = defaultThrottleDeps()) {
     try {
         const contents = deps.readFileSync(PROC_MEMINFO, "utf8");
         const kb = parseMemAvailableKb(contents);
         if (kb !== null)
-            return kb / 1024;
+            return { source: "meminfo", available_mb: kb / 1024 };
         // /proc/meminfo exists but has no MemAvailable (unusual). Fall back.
         process.stderr.write("lanes throttle: MemAvailable missing from /proc/meminfo; falling back to os.freemem()\n");
     }
@@ -264,11 +326,35 @@ export function readAvailableMemMb(deps = defaultThrottleDeps()) {
             process.stderr.write(`lanes throttle: failed to read ${PROC_MEMINFO}: ${err instanceof Error ? err.message : String(err)}\n`);
             return null;
         }
-        if (deps.platform() === "darwin")
-            return readDarwinAvailableMemMb(deps);
+        if (deps.platform() === "darwin") {
+            return readDarwinMemoryPressure(deps) ?? readDarwinVmStat(deps);
+        }
     }
     return readFreememMb(deps);
 }
+/** Available memory in MiB from readMemorySignal; null skips the memory gate. */
+export function readAvailableMemMb(deps = defaultThrottleDeps()) {
+    return readMemorySignal(deps)?.available_mb ?? null;
+}
+function formatMb(mb) {
+    return `${Math.round(mb)} MB`;
+}
+/** Plain explanation of a memory hold: which signal, its value, and the threshold. */
+export function formatMemoryHoldMessage(signal, thresholdMb) {
+    if (signal.source === "memory_pressure") {
+        const reading = `memory_pressure reports ${signal.free_percent}% free (about ${formatMb(signal.available_mb)}), pressure level ${signal.pressure_level}`;
+        if (signal.pressure_level !== "normal") {
+            return `Holding new lanes: ${reading}. Lanes wait while the level is warn or critical (throttle.min_available_mem_mb is ${thresholdMb}).`;
+        }
+        return `Holding new lanes: ${reading}, below throttle.min_available_mem_mb ${thresholdMb}.`;
+    }
+    const label = signal.source === "vm_stat"
+        ? "vm_stat free+inactive+speculative"
+        : signal.source === "meminfo"
+            ? "/proc/meminfo MemAvailable"
+            : "os.freemem()";
+    return `Holding new lanes: ${label} is ${formatMb(signal.available_mb)}, below throttle.min_available_mem_mb ${thresholdMb}.`;
+}
 export function emptyThrottleState() {
     return {
         consecutiveDeferrals: 0,
@@ -303,9 +389,17 @@ export function evaluateThrottle(input) {
             cpuBlocks = input.busy >= pause;
         }
     }
+    // On darwin the signal is memory_pressure's: a warn or critical level holds
+    // even above the threshold, and a normal level holds only below it.
     let memBlocks = false;
+    let memorySignal;
     if (minMem !== undefined && input.availableMemMb !== null) {
-        memBlocks = input.availableMemMb < minMem;
+        memorySignal = input.memory && input.memory.available_mb === input.availableMemMb
+            ? input.memory
+            : { source: "meminfo", available_mb: input.availableMemMb };
+        memBlocks = input.availableMemMb < minMem ||
+            memorySignal.pressure_level === "warn" ||
+            memorySignal.pressure_level === "critical";
     }
     if (!cpuBlocks && !memBlocks) {
         return {
@@ -323,27 +417,67 @@ export function evaluateThrottle(input) {
         admit: false,
         reason: "memory",
         availableMemMb: input.availableMemMb ?? undefined,
+        memory_hold: {
+            ...memorySignal,
+            threshold_mb: minMem,
+            message: formatMemoryHoldMessage(memorySignal, minMem),
+        },
     };
 }
 export function applyThrottleDecision(state, decision, nowMs) {
+    const { memory_hold: _previousHold, ...rest } = state;
     if (decision.admit) {
         return {
-            ...state,
+            ...rest,
             consecutiveDeferrals: 0,
             lastAdmissionAt: new Date(nowMs).toISOString(),
             cpuPaused: false,
         };
     }
     return {
-        ...state,
+        ...rest,
         consecutiveDeferrals: state.consecutiveDeferrals + 1,
         lastAdmissionAt: state.lastAdmissionAt,
         cpuPaused: decision.reason === "cpu" ? true : state.cpuPaused,
+        ...(decision.memory_hold !== undefined ? { memory_hold: decision.memory_hold } : {}),
     };
 }
 export function throttleStatePath(hqRoot) {
     return path.join(hqRoot, "workspace", "lanes-runs", "throttle-state.json");
 }
+const MEMORY_SIGNAL_SOURCES = [
+    "memory_pressure",
+    "vm_stat",
+    "meminfo",
+    "freemem",
+];
+/** A stored memory_hold is informational; a malformed one is dropped, not fatal. */
+function parseMemoryHold(value) {
+    if (value === undefined || value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const hold = value;
+    const finiteNonNegative = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0;
+    if (!MEMORY_SIGNAL_SOURCES.includes(hold.source) ||
+        !finiteNonNegative(hold.available_mb) ||
+        !finiteNonNegative(hold.threshold_mb) ||
+        typeof hold.message !== "string" || hold.message.trim() === "" ||
+        (hold.free_percent !== undefined && !finiteNonNegative(hold.free_percent)) ||
+        (hold.pressure_level !== undefined &&
+            !["normal", "warn", "critical"].includes(String(hold.pressure_level)))) {
+        return undefined;
+    }
+    return {
+        source: hold.source,
+        available_mb: hold.available_mb,
+        ...(hold.free_percent !== undefined ? { free_percent: hold.free_percent } : {}),
+        ...(hold.pressure_level !== undefined
+            ? { pressure_level: hold.pressure_level }
+            : {}),
+        threshold_mb: hold.threshold_mb,
+        message: hold.message,
+    };
+}
 export function readThrottleState(filePath, deps = defaultThrottleDeps()) {
     if (!deps.existsSync(filePath))
         return "missing";
@@ -410,10 +544,12 @@ export function readThrottleState(filePath, deps = defaultThrottleDeps()) {
             process.stderr.write(`lanes throttle: state ${filePath} has invalid sampled_at\n`);
             return "unreadable";
         }
+        const memoryHold = parseMemoryHold(obj.memory_hold);
         return {
             consecutiveDeferrals: obj.consecutiveDeferrals,
             lastAdmissionAt: obj.lastAdmissionAt,
             cpuPaused: obj.cpuPaused,
+            ...(memoryHold !== undefined ? { memory_hold: memoryHold } : {}),
             ...(cpuSnapshot !== undefined ? { cpu_snapshot: cpuSnapshot } : {}),
             ...(obj.last_busy !== undefined ? { last_busy: obj.last_busy } : {}),
             ...(obj.busy_source !== undefined ? { busy_source: obj.busy_source } : {}),
@@ -465,11 +601,12 @@ export async function decideAdmission(hqRoot, throttle = {}, deps = defaultThrot
     const busy = cpuBusyFraction === undefined
         ? observation?.busy ?? null
         : cpuBusyFraction;
-    const availableMemMb = readAvailableMemMb(deps);
+    const memory = readMemorySignal(deps);
     const nowMs = deps.now();
     const decision = evaluateThrottle({
         busy,
-        availableMemMb,
+        availableMemMb: memory?.available_mb ?? null,
+        memory,
         cpuCheckEnabled,
         state,
         throttle,

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

@@ -181,6 +181,17 @@ export declare const TERMINAL_LANE_STATES: readonly ["done", "failed", "interrup
 export type TerminalLaneState = (typeof TERMINAL_LANE_STATES)[number];
 export declare const LANE_PROVIDERS: readonly ["claude", "codex", "grok"];
 export type LaneProvider = (typeof LANE_PROVIDERS)[number];
+/**
+ * Who runs a lane's work. A process lane (the default, recorded by absence)
+ * is a provider process HQ spawned and watches. A subagent lane is a record
+ * only: an in-session Claude subagent does the work and reports through
+ * `hq lanes progress`, so admission, watchers, reapers and keep-alive skip it.
+ */
+export declare const LANE_RUNNERS: readonly ["process", "subagent"];
+export type LaneRunner = (typeof LANE_RUNNERS)[number];
+export declare function parseLaneRunner(value: unknown): LaneRunner;
+/** True when an in-session subagent, not an HQ-spawned process, runs this lane. */
+export declare function isSubagentLane(lane: Pick<LaneRecord, "runner">): boolean;
 export declare const QUEUED_REASONS: readonly ["cap", "provider_cap", "account_cap", "profile_cap", "queue_position", "throttle", "provider_binary_missing", "account_retry", "lead_reserve", "worker_profile_changed", "low_disk", "admit_failed"];
 export type QueuedReason = (typeof QUEUED_REASONS)[number];
 type QueuedDetails = {
@@ -616,6 +627,8 @@ export interface LaneRecord {
     /** How policy files were delivered on the most recent profile spawn. */
     worker_policy_delivery?: "hook" | "prompt";
     provider: LaneProvider;
+    /** `subagent` when an in-session subagent runs the work; absent for HQ-spawned process lanes. */
+    runner?: "subagent";
     /** Open each Claude turn as a named Remote Control session using account a's login. */
     remote_control?: boolean;
     /** Human-readable Remote Control name, fixed when the lane is created. Older lanes may lack it. */
@@ -1121,6 +1134,14 @@ export interface LanesConfig {
 }
 export declare function isIsoDateTime(value: string): boolean;
 export declare function parseMajorSchema(schemaVersion: string, expectedPrefix: string, expectedMajor: number): void;
-export declare function parseLaneEnvelope(raw: unknown): LaneEnvelope;
+export interface ParseLaneEnvelopeOptions {
+    /**
+     * False for a lane started with --no-story. Such a lane has no board story
+     * for story_status to describe, so a story_complete / story_status mismatch
+     * is repaired from story_complete instead of failing the envelope.
+     */
+    storyBound?: boolean;
+}
+export declare function parseLaneEnvelope(raw: unknown, options?: ParseLaneEnvelopeOptions): LaneEnvelope;
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/lib/lanes/types.js

@@ -106,6 +106,23 @@ export const TERMINAL_LANE_STATES = [
     "killed",
 ];
 export const LANE_PROVIDERS = ["claude", "codex", "grok"];
+/**
+ * Who runs a lane's work. A process lane (the default, recorded by absence)
+ * is a provider process HQ spawned and watches. A subagent lane is a record
+ * only: an in-session Claude subagent does the work and reports through
+ * `hq lanes progress`, so admission, watchers, reapers and keep-alive skip it.
+ */
+export const LANE_RUNNERS = ["process", "subagent"];
+export function parseLaneRunner(value) {
+    if (typeof value === "string" && LANE_RUNNERS.includes(value)) {
+        return value;
+    }
+    throw new LanesError("unknown_lane_runner", `Unknown lane runner ${JSON.stringify(value)}. Accepted: ${LANE_RUNNERS.join(", ")}`, { accepted: [...LANE_RUNNERS], value });
+}
+/** True when an in-session subagent, not an HQ-spawned process, runs this lane. */
+export function isSubagentLane(lane) {
+    return lane.runner === "subagent";
+}
 export const QUEUED_REASONS = [
     "cap",
     "provider_cap",
@@ -240,7 +257,7 @@ export const LANE_FIELD_WRITERS = {
     pickup_validation_pending_since: ["creator", "command", "spawn", "reconcile"],
     priority: ["command"], worker: ["creator", "command"], worker_path: ["creator", "command"], worker_pack: ["creator", "command"], worker_profile: ["creator", "command"], worker_profile_hash: ["creator", "command", "spawn"], registry_worker: ["creator", "command", "spawn"], registry_worker_approval_history: ["command", "watcher", "reconcile"], worker_profile_repin_history: ["command"], worker_profile_ignored: ["creator", "command", "spawn"], worker_policy_delivery: ["command", "spawn"],
     keep_alive: ["creator", "command"], keep_alive_standing: ["command"], keep_alive_opted_in_at: ["creator", "command"], keep_alive_blocked_reason: ["command", "reconcile"], keep_alive_resume_count: ["command", "reconcile", "spawn"], keep_alive_history: ["reconcile"], keep_alive_blocked_resume_streak: ["reconcile", "spawn", "watcher"], keep_alive_last_resume_at: ["command", "reconcile", "spawn"], keep_alive_next_eligible_at: ["command", "reconcile", "spawn"], keep_alive_exhausted_at: ["command", "reconcile", "spawn"], loop_mode: ["creator"],
-    provider: ["creator", "command"], remote_control: ["creator"], remote_control_title: ["creator"], provider_source: ["creator", "command"], account: ["creator", "spawn", "command", "watcher", "reconcile"], account_source: ["creator", "command"], profile_settings_pinned: ["command"], account_selection: ["creator", "command"], account_pick: ["creator"], admission_accounts: ["creator", "command"], account_history: ["command", "spawn", "watcher", "reconcile"], failed_resume_history: ["command"], fallback_question_cancellation_failures: ["command"], pending_resume: ["command", "spawn", "watcher", "reconcile"], placement_default: ["creator"], host: ["creator", "command"], origin_host: ["creator"], origin_host_source: ["creator"],
+    provider: ["creator", "command"], runner: ["creator"], remote_control: ["creator"], remote_control_title: ["creator"], provider_source: ["creator", "command"], account: ["creator", "spawn", "command", "watcher", "reconcile"], account_source: ["creator", "command"], profile_settings_pinned: ["command"], account_selection: ["creator", "command"], account_pick: ["creator"], admission_accounts: ["creator", "command"], account_history: ["command", "spawn", "watcher", "reconcile"], failed_resume_history: ["command"], fallback_question_cancellation_failures: ["command"], pending_resume: ["command", "spawn", "watcher", "reconcile"], placement_default: ["creator"], host: ["creator", "command"], origin_host: ["creator"], origin_host_source: ["creator"],
     version: ["creator"], created_at: ["creator"], updated_at: ["creator"], ended_at: ["reconcile"], envelope_summary: ["reconcile"], attribution_history: ["command", "watcher", "reconcile"], story_switch_pending: ["command", "watcher", "reconcile"], story_switch_unacknowledged: ["command", "watcher", "reconcile"],
     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: ["creator", "command"], status_gate: ["spawn", "watcher"], status_gate_history: ["watcher", "reconcile"], blocker_freshness_state: ["watcher"], kr_freshness_state: ["watcher"], last_compaction: ["spawn"], story_complete: ["watcher", "reconcile"], story_complete_reason: ["watcher", "reconcile"], story_status: ["watcher", "reconcile"],
@@ -288,7 +305,8 @@ export function parseMajorSchema(schemaVersion, expectedPrefix, expectedMajor) {
         throw new LaneSchemaError(`Unsupported ${expectedPrefix} major version ${major} (found ${schemaVersion})`, { schema_version: schemaVersion, major });
     }
 }
-export function parseLaneEnvelope(raw) {
+export function parseLaneEnvelope(raw, options = {}) {
+    const storyBound = options.storyBound !== false;
     if (!isPlainObject(raw)) {
         throw new LaneSchemaError("Lane envelope must be a JSON object");
     }
@@ -345,7 +363,7 @@ export function parseLaneEnvelope(raw) {
     else if (raw.blocked_reason !== undefined) {
         throw new LaneSchemaError('blocked_reason is present exactly when decision is "blocked"');
     }
-    const storyStatus = raw.story_status;
+    let storyStatus = raw.story_status;
     let storyComplete;
     let storyCompleteReason;
     if (raw.story_complete !== undefined) {
@@ -358,6 +376,12 @@ export function parseLaneEnvelope(raw) {
             raw.story_complete_reason.trim().length === 0) {
             throw new LaneSchemaError("story_complete_reason is required when story_complete is present", { field: "story_complete_reason" });
         }
+        if (!storyBound && raw.story_complete === true && storyStatus !== "done") {
+            storyStatus = "done";
+        }
+        else if (!storyBound && raw.story_complete === false && storyStatus === "done") {
+            storyStatus = "in_progress";
+        }
         if (raw.story_complete === true && storyStatus !== "done") {
             throw new LaneSchemaError("story_complete true requires story_status done", {
                 error: "story_complete_status_mismatch",