@indigoai-us/hq-cli 5.345.10 → 5.345.12

package/dist/lib/core-utils/worktree-resume.js

@@ -5,6 +5,7 @@ import * as path from "node:path";
 import { randomBytes } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { serializeJqJson } from "./jq-json-serializer.js";
+import { shellDisplayPath } from "./shell-display-path.js";
 export const WORKTREE_GC_ASSET = "core/scripts/worktree-gc.sh";
 export const CLEAN_HANDOFF_ASSET = "core/scripts/clean-worktree-reconcile-handoff.sh";
 export const RESUME_LOCK_ASSET = "core/scripts/resume-thread-lock.sh";
@@ -13,6 +14,7 @@ const stdout = (io, value) => (io.stdout ?? ((v) => process.stdout.write(v)))(va
 const stderr = (io, value) => (io.stderr ?? ((v) => process.stderr.write(v)))(value);
 const envOf = (io) => io.env ?? process.env;
 const nowOf = (io) => (io.now ?? (() => new Date()))();
+const randomBytesOf = (io, size) => (io.randomBytes ?? randomBytes)(size);
 const stripTrailingNewlines = (value) => value.replace(/\n+$/u, "");
 function git(args, options = {}) {
     const childEnv = options.env;
@@ -61,6 +63,23 @@ function fileExists(file) {
         return false;
     }
 }
+function sameDirectory(left, right) {
+    try {
+        const a = fs.statSync(left), b = fs.statSync(right);
+        if (a.dev !== 0 && b.dev !== 0 && a.ino !== 0 && b.ino !== 0)
+            return a.dev === b.dev && a.ino === b.ino;
+    }
+    catch { /* compare canonical spellings below */ }
+    const canonical = (value) => path.resolve(value).replace(/^\\\\\?\\/u, "").replaceAll("/", "\\").toLowerCase();
+    return canonical(left) === canonical(right);
+}
+function shellJsonPath(value) {
+    const display = shellDisplayPath(value);
+    if (process.platform !== "win32")
+        return display;
+    const match = /^\/([a-z])\/(.*)$/u.exec(display);
+    return match?.[1] && match[2] !== undefined ? `${match[1].toUpperCase()}:/${match[2]}` : display;
+}
 function statMtime(file) {
     try {
         return Math.floor(fs.statSync(file).mtimeMs / 1000);
@@ -119,7 +138,10 @@ function sessionReferences(hqRoot, worktree) {
         path.join(hqRoot, "workspace/threads/handoff.json"),
         path.join(hqRoot, "workspace/locks"),
     ];
-    const needle = Buffer.from(worktree, "utf8");
+    // The shell receives the Git Bash spelling of this path. Session references
+    // written by shell hooks use that spelling too, while Node's win32 path is
+    // drive-letter based. Compare the representation the shell actually sees.
+    const needle = Buffer.from(shellDisplayPath(worktree), "utf8");
     const visit = (target) => {
         let info;
         try {
@@ -187,7 +209,16 @@ function duSizeKb(root) {
             return;
         if (info.isFile())
             seen.add(inode);
-        bytes += typeof info.blocks === "number" ? info.blocks * 512 : info.size;
+        // Windows Git Bash du counts file payloads in 1 KiB units. Node's Windows
+        // directory sizes include metadata that du does not count, so omit those
+        // directory entries and round file payloads as du -sk does.
+        bytes += process.platform === "win32" && info.isDirectory()
+            ? 0
+            : typeof info.blocks === "number" && !(process.platform === "win32" && info.blocks === 0)
+                ? info.blocks * 512
+                : process.platform === "win32"
+                    ? Math.max(1, Math.ceil(info.size / 1024)) * 1024
+                    : info.size;
         if (info.isDirectory()) {
             let children;
             try {
@@ -338,9 +369,9 @@ export function runWorktreeGc(args, hqRoot, io = {}) {
     const skip = (wt, repo, branch, isHqRoot, ageDays, sizeKb, reason) => {
         skipped++;
         if (reason === "remove-failed")
-            record({ path: wt, repo, branch, hq_root: isHqRoot, age_days: ageDays, size_kb: sizeKb, action: "skipped", reason });
+            record({ path: shellJsonPath(wt), repo: shellJsonPath(repo), branch, hq_root: isHqRoot, age_days: ageDays, size_kb: sizeKb, action: "skipped", reason });
         if (!json)
-            stdout(io, `  skip  [${reason}] ${wt}\n`);
+            stdout(io, `  skip  [${reason}] ${shellDisplayPath(wt)}\n`);
     };
     const runFetch = (repo) => {
         const timeoutName = executableOnPath("timeout", env) ? "timeout" : executableOnPath("gtimeout", env) ? "gtimeout" : undefined;
@@ -372,11 +403,7 @@ export function runWorktreeGc(args, hqRoot, io = {}) {
             skip(wt, "", "", false, null, null, "git-error");
             continue;
         }
-        let isHqRoot = false;
-        try {
-            isHqRoot = fs.realpathSync(mainRepo) === fs.realpathSync(hqRoot);
-        }
-        catch { /* both paths are already resolved by the core root resolver */ }
+        const isHqRoot = sameDirectory(mainRepo, hqRoot);
         const branchResult = gitText(["-C", wt, "symbolic-ref", "--short", "HEAD"]);
         const branch = branchResult.status === 0 ? commandOutput(branchResult) : "";
         const headResult = gitText(["-C", wt, "rev-parse", "HEAD"]);
@@ -401,7 +428,9 @@ export function runWorktreeGc(args, hqRoot, io = {}) {
             continue;
         }
         let createdEpoch = wtMtime;
-        const stampFile = path.join(metaDir, `${worktreeGcPathKey(wt)}.json`);
+        // worktree-gc.sh hashes the path as Bash/Git Bash spells it. On Windows a
+        // native path (C:\...) and the shell path (/c/...) have different keys.
+        const stampFile = path.join(metaDir, `${worktreeGcPathKey(shellDisplayPath(wt))}.json`);
         if (fileExists(stampFile)) {
             try {
                 const stamp = JSON.parse(fs.readFileSync(stampFile, "utf8"));
@@ -465,9 +494,9 @@ export function runWorktreeGc(args, hqRoot, io = {}) {
         if (!apply) {
             would++;
             reclaimedKb += sizeKb;
-            record({ path: wt, repo: mainRepo, branch, hq_root: isHqRoot, age_days: ageDays, size_kb: sizeKb, action: "would-remove", reason: "safe" });
+            record({ path: shellJsonPath(wt), repo: shellJsonPath(mainRepo), branch, hq_root: isHqRoot, age_days: ageDays, size_kb: sizeKb, action: "would-remove", reason: "safe" });
             if (!json)
-                stdout(io, `  DRY   would remove (${Math.floor(sizeKb / 1024)} MB, ${ageDays}d) ${wt}\n`);
+                stdout(io, `  DRY   would remove (${Math.floor(sizeKb / 1024)} MB, ${ageDays}d) ${shellDisplayPath(wt)}\n`);
             continue;
         }
         if (wtGit(mainRepo, isHqRoot, ["worktree", "remove", wt]).status !== 0) {
@@ -483,9 +512,9 @@ export function runWorktreeGc(args, hqRoot, io = {}) {
         catch { /* rm -f */ }
         removed++;
         reclaimedKb += sizeKb;
-        record({ path: wt, repo: mainRepo, branch, hq_root: isHqRoot, age_days: ageDays, size_kb: sizeKb, action: "removed", reason: "safe" });
+        record({ path: shellJsonPath(wt), repo: shellJsonPath(mainRepo), branch, hq_root: isHqRoot, age_days: ageDays, size_kb: sizeKb, action: "removed", reason: "safe" });
         if (!json)
-            stdout(io, `  GC    removed (${Math.floor(sizeKb / 1024)} MB, ${ageDays}d) ${wt}\n`);
+            stdout(io, `  GC    removed (${Math.floor(sizeKb / 1024)} MB, ${ageDays}d) ${shellDisplayPath(wt)}\n`);
     }
     const reclaimedGb = Number((reclaimedKb / 1024 / 1024).toFixed(2));
     if (json) {
@@ -554,18 +583,18 @@ export function runCleanWorktreeReconcileHandoff(args, io = {}) {
     }
     const rawRoot = args[0] ?? "";
     const branch = args[1] ?? "";
-    if (!rawRoot.startsWith("/")) {
+    if (!rawRoot.startsWith("/") && !(process.platform === "win32" && path.win32.isAbsolute(rawRoot))) {
         stderr(io, `ERROR: HQ root must be an absolute path\n`);
         cleanUsage(io);
         return 64;
     }
     if (!fileExists(rawRoot) || !fs.statSync(rawRoot).isDirectory()) {
-        return cleanGitError(io, `ERROR: HQ root is not a directory: ${rawRoot}`);
+        return cleanGitError(io, `ERROR: HQ root is not a directory: ${shellDisplayPath(rawRoot)}`);
     }
     const hqRoot = realPathOrResolved(rawRoot);
     const top = gitText(["-C", hqRoot, "rev-parse", "--show-toplevel"]);
     if (top.status !== 0)
-        return cleanGitError(io, `ERROR: HQ root is not a Git worktree: ${hqRoot}`);
+        return cleanGitError(io, `ERROR: HQ root is not a Git worktree: ${shellDisplayPath(hqRoot)}`);
     const topLevel = realPathOrResolved(commandOutput(top));
     if (topLevel !== hqRoot)
         return cleanGitError(io, `ERROR: supplied path is not the Git worktree root: ${hqRoot}`);
@@ -640,7 +669,7 @@ export function runCleanWorktreeReconcileHandoff(args, io = {}) {
         let movedFile = "";
         try {
             for (let attempt = 0; attempt < 10; attempt++) {
-                const candidate = path.join(destinationDir, `.clean-worktree-handoff.${randomBytes(4).toString("hex").slice(0, 6)}`);
+                const candidate = path.join(destinationDir, `.clean-worktree-handoff.${randomBytesOf(io, 4).toString("hex").slice(0, 6)}`);
                 try {
                     fs.writeFileSync(candidate, "", { flag: "wx", mode: 0o600 });
                     movedFile = candidate;
@@ -769,12 +798,12 @@ function lockState(threadId, relativeLockPath, lockDir, recordPath, staleSeconds
     }
     return locked(record.session_id, record.resumed_at, record.generation);
 }
-function writeLockRecord(lockDir, recordPath, threadId, sessionId, now) {
+function writeLockRecord(lockDir, recordPath, threadId, sessionId, now, io) {
     const epoch = Math.floor(now.getTime() / 1000);
     const timestamp = now.toISOString().replace(/\.\d{3}Z$/u, "Z");
     let temporary = "";
     for (let attempt = 0; attempt < 10; attempt++) {
-        const generation = `.current.${randomBytes(8).toString("base64url").slice(0, 6)}`;
+        const generation = `.current.${randomBytesOf(io, 8).toString("base64url").slice(0, 6)}`;
         const candidate = path.join(lockDir, generation);
         try {
             fs.writeFileSync(candidate, serializeJqJson({ version: 1, thread_id: threadId, session_id: sessionId, resumed_at: timestamp, resumed_epoch: epoch, generation }, "compact"), { flag: "wx", mode: 0o600 });
@@ -858,7 +887,7 @@ export function runResumeThreadLock(args, hqRoot, io = {}) {
     fs.mkdirSync(locksDir, { recursive: true });
     try {
         fs.mkdirSync(lockDir);
-        const generation = writeLockRecord(lockDir, recordPath, threadId, sessionId, now());
+        const generation = writeLockRecord(lockDir, recordPath, threadId, sessionId, now(), io);
         emit({ status: "acquired", thread_id: threadId, lock_path: relativeLockPath, session_id: sessionId, lock_generation: generation });
         return 0;
     }
@@ -915,7 +944,7 @@ export function runResumeThreadLock(args, hqRoot, io = {}) {
             emit(current);
             return 4;
         }
-        const generation = writeLockRecord(lockDir, recordPath, threadId, sessionId, now());
+        const generation = writeLockRecord(lockDir, recordPath, threadId, sessionId, now(), io);
         emit({ status: "acquired", thread_id: threadId, lock_path: relativeLockPath, session_id: sessionId, lock_generation: generation });
         return 0;
     }
@@ -1008,7 +1037,7 @@ async function drainResponseBody(response) {
 export async function runVerifyStoryDeliverables(args, hqRoot, io = {}) {
     const env = envOf(io);
     let prdPath = "", storyId = "", repo = "";
-    let json = false, strict = false, write = false;
+    let json = false, strict = false, write = false, repoExplicit = false;
     let evidenceJson = "[]", commitsJson = "[]";
     let offline = env.HQ_DELIVERABLES_OFFLINE ?? "0";
     for (let index = 0; index < args.length;) {
@@ -1021,8 +1050,10 @@ export async function runVerifyStoryDeliverables(args, hqRoot, io = {}) {
                 prdPath = value;
             else if (arg === "--story")
                 storyId = value;
-            else if (arg === "--repo")
+            else if (arg === "--repo") {
                 repo = value;
+                repoExplicit = true;
+            }
             else if (arg === "--evidence-json")
                 evidenceJson = value;
             else
@@ -1058,9 +1089,12 @@ export async function runVerifyStoryDeliverables(args, hqRoot, io = {}) {
         stderr(io, `usage: --prd <prd.json> --story <id> [--repo <path>]\n`);
         return 2;
     }
+    const displayedPrdPath = process.platform === "win32" && path.win32.isAbsolute(prdPath)
+        ? shellDisplayPath(prdPath)
+        : prdPath;
     const prdFilePath = path.resolve(hqRoot, prdPath);
     if (!isReadable(prdFilePath)) {
-        stderr(io, `verify-story-deliverables: cannot read ${prdPath}\n`);
+        stderr(io, `verify-story-deliverables: cannot read ${displayedPrdPath}\n`);
         return 2;
     }
     let prd;
@@ -1073,7 +1107,7 @@ export async function runVerifyStoryDeliverables(args, hqRoot, io = {}) {
     const userStories = Array.isArray(prd.userStories) ? prd.userStories : [];
     const story = userStories.find((item) => item && item.id === storyId);
     if (!story) {
-        stderr(io, `verify-story-deliverables: story ${storyId} not in ${prdPath}\n`);
+        stderr(io, `verify-story-deliverables: story ${storyId} not in ${displayedPrdPath}\n`);
         return 2;
     }
     if (!repo) {
@@ -1081,7 +1115,10 @@ export async function runVerifyStoryDeliverables(args, hqRoot, io = {}) {
             ? prd.metadata : {};
         repo = jqText(metadata.repoPath);
     }
-    if (repo && !repo.startsWith("/"))
+    // The shell sees Git Bash's /c/... spelling, which remains absolute. Native
+    // receives the corresponding Win32 C:\\... path; preserve that absolute
+    // location instead of prefixing HQ_ROOT and pointing at a nonexistent path.
+    if (repo && !repo.startsWith("/") && !(repoExplicit && path.win32.isAbsolute(repo)))
         repo = `${hqRoot}/${repo}`;
     const evidence = jsonDecode(evidenceJson);
     if (!jqArrayCheck(evidence)) {
@@ -1099,7 +1136,7 @@ export async function runVerifyStoryDeliverables(args, hqRoot, io = {}) {
         // deliverables are left to jq's normal processing behavior.
         const refsRaw = declaredRaw;
         if (!Array.isArray(refsRaw)) {
-            stderr(io, `verify-story-deliverables: story ${storyId} not in ${prdPath}\n`);
+            stderr(io, `verify-story-deliverables: story ${storyId} not in ${displayedPrdPath}\n`);
             return 2;
         }
     }
@@ -1138,11 +1175,11 @@ export async function runVerifyStoryDeliverables(args, hqRoot, io = {}) {
         else if (kind === "repo-path")
             ok = Boolean(repo) && fileExists(`${repo}/${value}`);
         else if (kind === "branch" && repo && fileExists(repo)) {
-            ok = git(["-C", repo, "show-ref", "--verify", "--quiet", `refs/heads/${value}`]).status === 0 ||
-                git(["-C", repo, "show-ref", "--verify", "--quiet", `refs/remotes/origin/${value}`]).status === 0;
+            ok = git(["-C", repo, "show-ref", "--verify", "--quiet", `refs/heads/${value}`], { env }).status === 0 ||
+                git(["-C", repo, "show-ref", "--verify", "--quiet", `refs/remotes/origin/${value}`], { env }).status === 0;
         }
         else if (kind === "commit" && repo && fileExists(repo)) {
-            ok = git(["-C", repo, "cat-file", "-e", `${value}^{commit}`]).status === 0;
+            ok = git(["-C", repo, "cat-file", "-e", `${value}^{commit}`], { env }).status === 0;
         }
         else if (kind === "url")
             ok = offline === "1" || await urlIsPresent(value);

package/dist/lib/daemon/catalog.d.ts

@@ -65,6 +65,16 @@ export interface UnitPlan {
     drainSignal?: "SIGUSR2";
     /** A new CLI version alone does not restart this unit; it restarts itself when idle. */
     keepAcrossCliUpdates?: true;
+    /**
+     * Scheduled units only: before each timed run the supervisor asks
+     * `SupervisorDeps.runGuard` whether there is work. `spawn` runs as usual,
+     * `idle` runs at most once per `idleIntervalSec`, `skip` does not run. A
+     * guard error, or no guard in the supervisor, runs as usual.
+     */
+    runGuard?: {
+        name: "lanes-reconcile";
+        idleIntervalSec: number;
+    };
 }
 export interface PlanContext {
     machineType: MachineType;

package/dist/lib/daemon/catalog.js

@@ -230,10 +230,18 @@ function planService(service, ctx) {
             return [
                 base(service, {
                     kind: "scheduled",
+                    // Polls every 15 s so keep-alive resumes are admitted on time (#1396).
+                    // Each pass is a fresh `hq` node process (~1.8 s CPU, ~200 MB RSS), so
+                    // desktops first check the lane store in-process
+                    // (lanes-reconcile-guard.ts) and fall back to the pre-#1396 60 s
+                    // cadence, or no run, when no lane can need the 15 s poll.
                     intervalSec: 15,
                     initialDelaySec: 30,
                     command: { type: "hq", args: ["lanes", "reconcile"] },
                     env: ctx.hqRoot ? { HQ_ROOT: ctx.hqRoot } : {},
+                    ...(ctx.machineType === "desktop"
+                        ? { runGuard: { name: "lanes-reconcile", idleIntervalSec: 60 } }
+                        : {}),
                     blocked: firstBlock([[!ctx.hqRoot, NO_HQ_ROOT]]),
                 }),
             ];

package/dist/lib/daemon/lanes-reconcile-guard.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pre-spawn check for the desktop `lanes-reconcile` unit.
+ *
+ * Every reconcile pass is a fresh `hq` node process (~1.8 s CPU, ~200 MB RSS),
+ * so a 15-second poll costs about 12% of a core even when the lane store holds
+ * nothing to do. This check reads the lane store in-process (readdir + small
+ * JSON reads, no child process) and tells the supervisor how urgent the next
+ * pass is:
+ *
+ * - `spawn`: something the 15-second cadence exists for may be due — lane
+ *   admission, a running lane's heartbeat, or a keep-alive resume (#1396).
+ * - `idle`: only work that ran on the pre-#1396 60-second cadence remains
+ *   (terminal lanes, worker-profile resumes, question aging, Codex rollout
+ *   retention, lead-autopilot registry). The supervisor runs it at most once
+ *   per `idleIntervalSec`.
+ * - `skip`: the store holds no lane or question records, no lead registry and
+ *   no lanes config, so a reconcile pass has no input to act on.
+ *
+ * Any error reading the store returns `spawn` (fail open), as does any record
+ * this check does not understand.
+ *
+ * The paths below mirror `LANES_STORE_REL`, `LANE_RECORDS_DIR`,
+ * `QUESTION_RECORDS_DIR` (lanes/store.ts), `LANES_CONFIG_REL` (lanes/config.ts)
+ * and `LEAD_REGISTRY_REL` (lanes/autopilot-registry.ts). They are copied, not
+ * imported, so the daemon does not load the lanes modules; a test pins them to
+ * the originals.
+ */
+import type { UnitPlan } from "./catalog.js";
+export type LanesReconcileVerdict = "spawn" | "idle" | "skip";
+export declare const LANES_STORE_DIR: string;
+export declare const LANE_RECORDS_SUBDIR = "lanes";
+export declare const QUESTION_RECORDS_SUBDIR = "questions";
+export declare const LANES_CONFIG_FILE: string;
+export declare const LEAD_REGISTRY_FILE: string;
+export interface LanesReconcileGuardFs {
+    readdirSync: (dir: string) => string[];
+    readFileSync: (file: string, encoding: "utf8") => string;
+    existsSync: (file: string) => boolean;
+}
+export declare function lanesReconcileVerdict(hqRoot: string | undefined, fsDeps?: LanesReconcileGuardFs): LanesReconcileVerdict;
+/** The supervisor's `runGuard`: dispatches on the unit's declared guard. */
+export declare function daemonRunGuard(unit: Pick<UnitPlan, "runGuard" | "env">): LanesReconcileVerdict;
+//# sourceMappingURL=lanes-reconcile-guard.d.ts.map

package/dist/lib/daemon/lanes-reconcile-guard.js

@@ -0,0 +1,115 @@
+/**
+ * Pre-spawn check for the desktop `lanes-reconcile` unit.
+ *
+ * Every reconcile pass is a fresh `hq` node process (~1.8 s CPU, ~200 MB RSS),
+ * so a 15-second poll costs about 12% of a core even when the lane store holds
+ * nothing to do. This check reads the lane store in-process (readdir + small
+ * JSON reads, no child process) and tells the supervisor how urgent the next
+ * pass is:
+ *
+ * - `spawn`: something the 15-second cadence exists for may be due — lane
+ *   admission, a running lane's heartbeat, or a keep-alive resume (#1396).
+ * - `idle`: only work that ran on the pre-#1396 60-second cadence remains
+ *   (terminal lanes, worker-profile resumes, question aging, Codex rollout
+ *   retention, lead-autopilot registry). The supervisor runs it at most once
+ *   per `idleIntervalSec`.
+ * - `skip`: the store holds no lane or question records, no lead registry and
+ *   no lanes config, so a reconcile pass has no input to act on.
+ *
+ * Any error reading the store returns `spawn` (fail open), as does any record
+ * this check does not understand.
+ *
+ * The paths below mirror `LANES_STORE_REL`, `LANE_RECORDS_DIR`,
+ * `QUESTION_RECORDS_DIR` (lanes/store.ts), `LANES_CONFIG_REL` (lanes/config.ts)
+ * and `LEAD_REGISTRY_REL` (lanes/autopilot-registry.ts). They are copied, not
+ * imported, so the daemon does not load the lanes modules; a test pins them to
+ * the originals.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const LANES_STORE_DIR = path.join("workspace", "lanes");
+export const LANE_RECORDS_SUBDIR = "lanes";
+export const QUESTION_RECORDS_SUBDIR = "questions";
+export const LANES_CONFIG_FILE = path.join("personal", "lanes", "config.json");
+export const LEAD_REGISTRY_FILE = path.join("workspace", "lane-briefs", "juniors.json");
+/**
+ * Lane states that reconcile admission, heartbeats and liveness never act on.
+ * `blocked` is listed because reconcile only resumes a blocked lane when it is
+ * keep-alive, which is checked separately.
+ */
+const QUIET_LANE_STATES = new Set(["done", "failed", "interrupted", "cancelled", "killed", "blocked"]);
+const realFs = {
+    readdirSync: (dir) => fs.readdirSync(dir),
+    readFileSync: (file, encoding) => fs.readFileSync(file, encoding),
+    existsSync: (file) => fs.existsSync(file),
+};
+/** Same filter reconcile's `readDirJsonIds` applies. */
+function recordNames(fsDeps, dir) {
+    let names;
+    try {
+        names = fsDeps.readdirSync(dir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    return names.filter((name) => name.endsWith(".json") && !name.startsWith(".") && !name.includes(".conflict-"));
+}
+function readRecord(fsDeps, file) {
+    const parsed = JSON.parse(fsDeps.readFileSync(file, "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`${file} is not a JSON object`);
+    }
+    return parsed;
+}
+/** A lane that may need the 15-second cadence. Unknown shapes count as urgent. */
+function laneIsUrgent(lane) {
+    if (typeof lane.state !== "string" || !QUIET_LANE_STATES.has(lane.state))
+        return true;
+    if (lane.keep_alive === true)
+        return true;
+    if (lane.pending_resume !== undefined)
+        return true;
+    return false;
+}
+export function lanesReconcileVerdict(hqRoot, fsDeps = realFs) {
+    try {
+        if (!hqRoot)
+            return "spawn";
+        const store = path.join(hqRoot, LANES_STORE_DIR);
+        const laneDir = path.join(store, LANE_RECORDS_SUBDIR);
+        const questionDir = path.join(store, QUESTION_RECORDS_SUBDIR);
+        const laneNames = recordNames(fsDeps, laneDir);
+        const questionNames = recordNames(fsDeps, questionDir);
+        for (const name of laneNames) {
+            if (laneIsUrgent(readRecord(fsDeps, path.join(laneDir, name))))
+                return "spawn";
+        }
+        for (const name of questionNames) {
+            const question = readRecord(fsDeps, path.join(questionDir, name));
+            if (typeof question.status !== "string" || question.status === "pending")
+                return "spawn";
+        }
+        if (laneNames.length === 0 &&
+            questionNames.length === 0 &&
+            !fsDeps.existsSync(path.join(hqRoot, LEAD_REGISTRY_FILE)) &&
+            !fsDeps.existsSync(path.join(hqRoot, LANES_CONFIG_FILE))) {
+            return "skip";
+        }
+        return "idle";
+    }
+    catch {
+        return "spawn";
+    }
+}
+/** The supervisor's `runGuard`: dispatches on the unit's declared guard. */
+export function daemonRunGuard(unit) {
+    switch (unit.runGuard?.name) {
+        case "lanes-reconcile":
+            return lanesReconcileVerdict(unit.env.HQ_ROOT);
+        default:
+            return "spawn";
+    }
+}
+//# sourceMappingURL=lanes-reconcile-guard.js.map

package/dist/lib/daemon/ops/journal.d.ts

@@ -9,7 +9,6 @@
  * <project>/journal/ is used, and one is opened (same template as
  * `journal.sh open`) when none exists.
  */
-export declare const JOURNAL_SECTIONS: Record<string, string>;
 export declare class JournalOpError extends Error {
     readonly code: string;
     constructor(code: string, message: string);

package/dist/lib/daemon/ops/journal.js

@@ -12,7 +12,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 const SLUG_RE = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/;
-export const JOURNAL_SECTIONS = {
+const JOURNAL_SECTIONS = {
     decisions: "## Decisions",
     open: "## Open threads",
     findings: "## Findings",

package/dist/lib/daemon/ops/mcp.d.ts

@@ -12,7 +12,6 @@ export interface McpToolResult {
     isError?: boolean;
 }
 export declare function jsonResult(value: unknown): McpToolResult;
-export declare const HQ_MCP_HTTP_TIMEOUT_MS = 30000;
 export declare function resolveHqMcpEndpoint(env?: NodeJS.ProcessEnv): URL;
 export declare function defaultMcpToken(): Promise<string>;
 export interface HqMcpBridgeOptions {

package/dist/lib/daemon/ops/mcp.js

@@ -16,7 +16,7 @@ export function jsonResult(value) {
     const structured = value && typeof value === "object" && !Array.isArray(value) ? value : { value };
     return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], structuredContent: structured };
 }
-export const HQ_MCP_HTTP_TIMEOUT_MS = 30_000;
+const HQ_MCP_HTTP_TIMEOUT_MS = 30_000;
 export function resolveHqMcpEndpoint(env = process.env) {
     try {
         return resolveEndpoint(env);

package/dist/lib/daemon/ops/policy.d.ts

@@ -61,13 +61,6 @@ export interface PolicyCheckResult {
         version: number;
     };
 }
-/**
- * The scope authorizer reads the session's company from
- * workspace/sessions/<sid>/meta.yaml (or scope-capability.json). hqd binds a
- * session id of its own per company + caller, so a check never borrows the
- * binding of an unrelated session.
- */
-export declare function bindCheckSession(hqRoot: string, company: string | undefined, callerSession: string | undefined, now: Date): string;
 export interface PolicyCheckDeps {
     hqRoot: string;
     index: PolicyIndex;

package/dist/lib/daemon/ops/policy.js

@@ -160,7 +160,7 @@ function runScript(script, payload, env, cwd, timeoutMs) {
  * session id of its own per company + caller, so a check never borrows the
  * binding of an unrelated session.
  */
-export function bindCheckSession(hqRoot, company, callerSession, now) {
+function bindCheckSession(hqRoot, company, callerSession, now) {
     const caller = (callerSession ?? "default").replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 80) || "default";
     const scope = company ?? "personal";
     const sid = `hqd-${scope}-${caller}`;

package/dist/lib/daemon/run.js

@@ -45,6 +45,7 @@ import { adoptChild, createChildTracker, finishSuccession, handoffEligible, read
 import { listSyncRunnerProcesses, readWatchRunnerOwnerStatus, syncHeartbeatTimeoutMs, syncRunnerNodeOptions, watchRunnerOwnerStatusPath, } from "./sync-runner.js";
 import { STOP_ESCALATION_MS, createSupervisor, } from "./supervisor.js";
 import { userToolDirs } from "./tools.js";
+import { daemonRunGuard } from "./lanes-reconcile-guard.js";
 export const LOG_ROTATE_BYTES = 5 * 1024 * 1024;
 /** Exit code for "restart me": non-zero so every service manager relaunches (Windows tasks only restart on failure). */
 export const RESTART_EXIT_CODE = 75;
@@ -788,6 +789,7 @@ export async function runDaemon(opts) {
             return takeControlRequests(paths.requestsDir);
         },
         restartDaemon: () => restartDaemon(),
+        runGuard: daemonRunGuard,
         writeState: (state) => writeJsonAtomic(paths.statePath, state),
         log,
         syncOwnerBlockReason: () => {

package/dist/lib/daemon/supervisor.d.ts

@@ -111,6 +111,8 @@ export interface SupervisorDeps {
     cliVersion?: string;
     /** Services to take over from the previous daemon instead of starting them. */
     adopt?: readonly AdoptedUnit[];
+    /** Pre-run check for scheduled units that declare `runGuard`; a throw counts as `spawn`. */
+    runGuard?: (unit: UnitPlan) => "spawn" | "idle" | "skip";
 }
 export interface Supervisor {
     start(): void;

package/dist/lib/daemon/supervisor.js

@@ -56,6 +56,9 @@ export function planKey(plan, cliVersion) {
         plan.command,
         plan.env,
     ];
+    // Only units that declare a guard carry it, so existing keys stay unchanged.
+    if (plan.runGuard !== undefined)
+        fields.push({ runGuard: plan.runGuard });
     if (cliVersion !== undefined && plan.command?.type === "hq" && !plan.keepAcrossCliUpdates)
         fields.push(cliVersion);
     return JSON.stringify(fields);
@@ -554,6 +557,27 @@ export function createSupervisor(deps) {
             runScheduled(slot);
         }, delayMs);
     };
+    /** True when the unit's run guard says this timed run has nothing to do. Fails open. */
+    const guardSaysWait = (slot) => {
+        const guard = slot.plan.runGuard;
+        if (!guard || !deps.runGuard)
+            return false;
+        let verdict;
+        try {
+            verdict = deps.runGuard(slot.plan);
+        }
+        catch (err) {
+            deps.log("warn", `${slot.plan.id} run check failed, running anyway: ${errorMessage(err)}`);
+            return false;
+        }
+        if (verdict === "skip")
+            return true;
+        if (verdict === "idle") {
+            const last = slot.state.lastRunAt;
+            return last !== undefined && now() - last < guard.idleIntervalSec * 1000;
+        }
+        return false;
+    };
     const runScheduled = (slot, manual = false) => {
         if (stopped)
             return;
@@ -564,6 +588,10 @@ export function createSupervisor(deps) {
             emit();
             return;
         }
+        if (!manual && guardSaysWait(slot)) {
+            emit();
+            return;
+        }
         slot.busy = true;
         slot.state.lastRunAt = now();
         const command = slot.plan.command;

package/dist/lib/doctor/checks/sync-health.d.ts

@@ -105,8 +105,6 @@ export interface SyncHealthDeps {
  * outside `companies/`.
  */
 export declare function isSafeCompanySlug(slug: string): boolean;
-/** True when `hqRoot/companies/<slug>` exists as a directory. Never throws. */
-export declare function defaultLocalCompanyExists(hqRoot: string, slug: string): boolean;
 /** True when this journal slug names a company rather than the personal tree. */
 export declare function isCompanyJournalSlug(slug: string): boolean;
 /** Company slug from a `sync.journal.<slug>` check id, or null if not one. */

package/dist/lib/doctor/checks/sync-health.js

@@ -68,7 +68,7 @@ export function isSafeCompanySlug(slug) {
     return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(slug);
 }
 /** True when `hqRoot/companies/<slug>` exists as a directory. Never throws. */
-export function defaultLocalCompanyExists(hqRoot, slug) {
+function defaultLocalCompanyExists(hqRoot, slug) {
     if (!isSafeCompanySlug(slug))
         return false;
     try {

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

@@ -6,8 +6,6 @@ export interface AdmissionHost {
 }
 export type AdmissionCapReason = "provider_cap" | "account_cap" | "profile_cap";
 export declare const ADMISSION_LOCK_STALE_MS = 30000;
-export declare const ADMISSION_LOCK_TIMEOUT_MS = 5000;
-export declare const ADMISSION_RESERVATION_GRACE_MS = 30000;
 export declare function withLaneAdmissionLock<T>(hqRoot: string, provider: LaneRecord["provider"], fn: () => Promise<T>, sleep?: (ms: number) => Promise<void>): Promise<T>;
 export declare function withAllLaneAdmissionLocks<T>(hqRoot: string, fn: () => Promise<T>, sleep?: (ms: number) => Promise<void>): Promise<T>;
 export declare function laneRunsOnHost(lane: LaneRecord, host: AdmissionHost): boolean;

package/dist/lib/lanes/admission.js

@@ -5,8 +5,8 @@ import { LanesError } from "./errors.js";
 import { quotaBlockFor } from "./quota.js";
 import { isTerminalLaneState } from "./types.js";
 export const ADMISSION_LOCK_STALE_MS = 30_000;
-export const ADMISSION_LOCK_TIMEOUT_MS = 5_000;
-export const ADMISSION_RESERVATION_GRACE_MS = 30_000;
+const ADMISSION_LOCK_TIMEOUT_MS = 5_000;
+const ADMISSION_RESERVATION_GRACE_MS = 30_000;
 function defaultAdmissionSleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }