@indigoai-us/hq-cli 5.345.146 → 5.345.148

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

package/dist/lib/lanes/watcher.js

@@ -33,7 +33,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { LanesError } from "./errors.js";
+import { LaneSchemaError, LanesError } from "./errors.js";
 import { compareEnvelopeNames } from "./envelope-sequence.js";
 import { questionRecordRefusalCode, raiseEnvelopeQuestions, resolveQuestionCompanyWithFallback, } from "./questions.js";
 import { isTerminalLaneState, ENVELOPE_INVALID_REASON, parseLaneEnvelope, STORY_STATUSES, LANE_PROVIDERS, } from "./types.js";
@@ -738,7 +738,7 @@ export function readLatestEnvelopeFile(hqRoot, laneId, minName) {
             ref,
             path: filePath,
             text,
-            envelope: parseLaneEnvelope(JSON.parse(text)),
+            envelope: parseLaneEnvelopeForLane(hqRoot, laneId, JSON.parse(text)),
             error: null,
         };
     }
@@ -752,6 +752,31 @@ export function readLatestEnvelopeFile(hqRoot, laneId, minName) {
         };
     }
 }
+/**
+ * Parse strictly first. Only a story_complete / story_status mismatch reads the
+ * lane record: a --no-story lane (no_story_reason set) has no board story, so
+ * that mismatch is repaired instead of failing the lane. An unreadable lane
+ * record keeps the strict error.
+ */
+function parseLaneEnvelopeForLane(hqRoot, laneId, raw) {
+    try {
+        return parseLaneEnvelope(raw);
+    }
+    catch (err) {
+        if (!(err instanceof LaneSchemaError) || err.details.error !== "story_complete_status_mismatch")
+            throw err;
+        let noStory = false;
+        try {
+            noStory = readLane(hqRoot, laneId).no_story_reason !== undefined;
+        }
+        catch {
+            throw err;
+        }
+        if (!noStory)
+            throw err;
+        return parseLaneEnvelope(raw, { storyBound: false });
+    }
+}
 /** A descriptor for this run's manifest slot when no envelope file was written. */
 export function missingExpectedEnvelopeFile(hqRoot, laneId, envelopePath) {
     if (!envelopePath || !path.isAbsolute(envelopePath))

package/dist/lib/lanes/worker-continuity.d.ts

@@ -5,6 +5,8 @@ export interface WorkerContinuityLookup {
     provider: LaneProvider;
     company: LaneRecord["company"];
     freshThread?: boolean;
+    /** When set, a live lane on another machine names that machine and how to free the worker. */
+    runsHere?: (lane: LaneRecord) => boolean;
 }
 export interface WorkerContinuityResult {
     previous?: LaneRecord;

package/dist/lib/lanes/worker-continuity.js

@@ -14,6 +14,22 @@ function sameCompany(left, right) {
 function compareNewest(left, right) {
     return right.created_at.localeCompare(left.created_at) || right.lane_id.localeCompare(left.lane_id);
 }
+function workerBusyError(lookup, lane, lead, extra = {}) {
+    const remote = lookup.runsHere !== undefined && lookup.runsHere(lane) === false;
+    const fix = `hq lanes stop ${lane.lane_id}`;
+    const message = remote
+        ? `${lead} on ${lane.host.kind}:${lane.host.id} (state ${lane.state}). That lane is on another machine. Free the worker on that machine with \`${fix}\`.`
+        : `${lead} (state ${lane.state}). Free the worker with \`${fix}\`.`;
+    return new LanesError("worker_lane_busy", message, {
+        worker: lookup.worker,
+        lane_id: lane.lane_id,
+        state: lane.state,
+        host: lane.host,
+        remote,
+        fix_command: fix,
+        ...extra,
+    });
+}
 export function sameLaneHost(left, right) {
     return left.kind === right.kind && left.id === right.id;
 }
@@ -25,11 +41,7 @@ export function findWorkerContinuityLane(lanes, lookup) {
         .sort(compareNewest);
     const live = scoped.find((lane) => !isTerminalLaneState(lane.state));
     if (live) {
-        throw new LanesError("worker_lane_busy", `Worker ${lookup.worker} already has live lane ${live.lane_id}`, {
-            worker: lookup.worker,
-            lane_id: live.lane_id,
-            state: live.state,
-        });
+        throw workerBusyError(lookup, live, `Worker ${lookup.worker} already has live lane ${live.lane_id}`);
     }
     const previous = scoped[0];
     if (!previous)
@@ -45,12 +57,7 @@ export function findWorkerContinuityLane(lanes, lookup) {
             (lane.state === "queued" || lane.state === "running"))
             .sort(compareNewest)[0];
         if (liveDescendant) {
-            throw new LanesError("worker_lane_busy", `Provider thread lineage is active in lane ${liveDescendant.lane_id}`, {
-                worker: lookup.worker,
-                lane_id: liveDescendant.lane_id,
-                state: liveDescendant.state,
-                provider_session_id: previousSessionId,
-            });
+            throw workerBusyError(lookup, liveDescendant, `Provider thread lineage is active in lane ${liveDescendant.lane_id}`, { provider_session_id: previousSessionId });
         }
     }
     // Only clean, resumable terminal outcomes are safe for automatic reuse.

package/dist/lib/manifest-disabled.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The kill switch hq-cloud's manifest pass honours. Restated locally (rather
+ * than imported) for two reasons: it lives in the same unreleased module as
+ * the manifest exports, and — more importantly — we must be able to read it
+ * BEFORE deciding to do any work at all.
+ *
+ * Kept in its own leaf module so `hq doctor` can read the switch without
+ * loading `hq sync manifest` and its imports.
+ */
+export declare const MANIFEST_DISABLED_ENV = "HQ_SYNC_MANIFEST_DISABLED";
+/** True when the kill switch is set to anything other than empty/0/false. */
+export declare function manifestUploadsDisabled(env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=manifest-disabled.d.ts.map

package/dist/lib/manifest-disabled.js

@@ -0,0 +1,19 @@
+/**
+ * The kill switch hq-cloud's manifest pass honours. Restated locally (rather
+ * than imported) for two reasons: it lives in the same unreleased module as
+ * the manifest exports, and — more importantly — we must be able to read it
+ * BEFORE deciding to do any work at all.
+ *
+ * Kept in its own leaf module so `hq doctor` can read the switch without
+ * loading `hq sync manifest` and its imports.
+ */
+export const MANIFEST_DISABLED_ENV = "HQ_SYNC_MANIFEST_DISABLED";
+/** True when the kill switch is set to anything other than empty/0/false. */
+export function manifestUploadsDisabled(env = process.env) {
+    const raw = env[MANIFEST_DISABLED_ENV];
+    if (raw === undefined)
+        return false;
+    const value = raw.trim().toLowerCase();
+    return value !== "" && value !== "0" && value !== "false";
+}
+//# sourceMappingURL=manifest-disabled.js.map

package/dist/lib/service-manager/launchd.d.ts

@@ -62,6 +62,7 @@ export declare const LAUNCHD_BOOTSTRAP_BACKOFF_MS: readonly number[];
 /** Bootstrap attempts after bootout (first try + EIO retries). */
 export declare const LAUNCHD_BOOTSTRAP_ATTEMPTS: number;
 export declare const defaultRunCommand: RunCommand;
+export declare function blockingSleep(ms: number): void;
 export declare function launchdServiceTarget(plistPath: string, uid?: number): string;
 /** ProgramArguments from a LaunchAgent plist. */
 export declare function launchdPlistProgramArguments(plist: string): string[];

package/dist/lib/service-manager/launchd.js

@@ -177,7 +177,7 @@ export const defaultRunCommand = (cmd, args) => {
         stderr: r.error ? r.error.message : (typeof r.stderr === "string" ? r.stderr : ""),
     };
 };
-function blockingSleep(ms) {
+export function blockingSleep(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 function guiDomain(uid = os.userInfo().uid) {