@indigoai-us/hq-cli 5.345.170 → 5.345.172

package/dist/lib/index-render/index.d.ts

@@ -1,5 +1,14 @@
 import { RenderContext, RenderResult } from "./shared.js";
 export type IndexTarget = "all" | "companies" | "company-knowledge" | "orchestrator" | "projects" | "public-knowledge" | "reports" | "social-drafts" | "threads" | "workers";
+/**
+ * `all` accepts `--company <slug>` (repeatable). Without it, `all` keeps the
+ * every-company rebuild; the command layer decides whether that is allowed.
+ * Slugs are validated before any child runs, so a bad slug writes nothing.
+ */
+/** `all` option: run the companies child without --company (the pre-scoping behavior). */
+export declare const UNSCOPED_COMPANIES_INDEX = "--unscoped-companies-index";
+/** `all` option: skip every company child (companies, projects, company-knowledge). */
+export declare const SKIP_COMPANY_INDEXES = "--skip-company-indexes";
 /**
  * One-line summaries for targets without their own option grammar. The CLI,
  * the renderer and the bundled shell fallbacks all print the same help text.

package/dist/lib/index-render/index.js

@@ -10,6 +10,54 @@ import { renderSocialDrafts } from "./social-drafts.js";
 import { renderThreads } from "./threads.js";
 import { renderWorkers } from "./workers.js";
 const allOrder = ["threads", "orchestrator", "companies", "projects", "company-knowledge", "public-knowledge", "workers", "reports", "social-drafts"];
+const companyChildren = new Set(["companies", "company-knowledge", "projects"]);
+/**
+ * `all` accepts `--company <slug>` (repeatable). Without it, `all` keeps the
+ * every-company rebuild; the command layer decides whether that is allowed.
+ * Slugs are validated before any child runs, so a bad slug writes nothing.
+ */
+/** `all` option: run the companies child without --company (the pre-scoping behavior). */
+export const UNSCOPED_COMPANIES_INDEX = "--unscoped-companies-index";
+/** `all` option: skip every company child (companies, projects, company-knowledge). */
+export const SKIP_COMPANY_INDEXES = "--skip-company-indexes";
+function allCompanyScope(root, args) {
+    const companies = [];
+    let unscopedCompanies = false;
+    let skipCompanyIndexes = false;
+    for (let i = 0; i < args.length; i += 1) {
+        let value = args[i];
+        if (value === UNSCOPED_COMPANIES_INDEX) {
+            unscopedCompanies = true;
+            continue;
+        }
+        if (value === SKIP_COMPANY_INDEXES) {
+            skipCompanyIndexes = true;
+            continue;
+        }
+        if (value === "--company")
+            value = args[++i] ?? "";
+        else if (value.startsWith("--company="))
+            value = value.slice("--company=".length);
+        else
+            throw new CompanyIndexUserError(`rebuild-index all: unknown option ${value}`);
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(value))
+            throw new CompanyIndexUserError("rebuild-index all: --company requires a valid company slug");
+        let real = false;
+        try {
+            const stat = fs.lstatSync(path.join(root, "companies", value));
+            real = stat.isDirectory() && !stat.isSymbolicLink();
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        if (!real)
+            throw new CompanyIndexUserError(`rebuild-index all: no company directory named "${value}"`);
+        if (!companies.includes(value))
+            companies.push(value);
+    }
+    return { companies: companies.length > 0 ? companies : undefined, unscopedCompanies, skipCompanyIndexes };
+}
 function companyScope(target, context, args) {
     let company;
     for (let i = 0; i < args.length; i += 1) {
@@ -82,15 +130,27 @@ export function renderIndexTarget(target, context, args = []) {
         case "threads": return renderThreads(context, args);
         case "workers": return renderWorkers(context);
         case "all": {
+            const { companies, unscopedCompanies, skipCompanyIndexes } = allCompanyScope(context.root, args);
             const written = [];
             let errors = 0;
             for (const child of allOrder) {
-                try {
-                    written.push(...renderIndexTarget(child, context).written);
+                if (skipCompanyIndexes && companyChildren.has(child)) {
+                    context.log?.(`rebuild-all-indexes: skip rebuild-${child}-index.sh (no company in this session's scope)`);
+                    continue;
                 }
-                catch (_error) {
-                    errors += 1;
-                    context.log?.(`rebuild-all-indexes: ERROR in rebuild-${child}-index.sh`);
+                // With --company, the per-company children rebuild only those companies.
+                const scoped = companies !== undefined && companyChildren.has(child) && !(child === "companies" && unscopedCompanies);
+                const runs = scoped
+                    ? companies.map((slug) => (child === "companies" ? ["--company", slug] : [slug]))
+                    : [[]];
+                for (const childArgs of runs) {
+                    try {
+                        written.push(...renderIndexTarget(child, context, childArgs).written);
+                    }
+                    catch (_error) {
+                        errors += 1;
+                        context.log?.(`rebuild-all-indexes: ERROR in rebuild-${child}-index.sh`);
+                    }
                 }
             }
             // The shell sorts and deduplicates the `wrote` paths before JSON output.

package/dist/lib/index-render/session-scope.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Session company scope for `hq core rebuild-index`.
+ *
+ * The renderers in this folder are pure: with no company they rebuild every
+ * company. The command layer must not inherit that default inside a
+ * company-bound session. A session bound to one or more companies may only
+ * rebuild those companies' indexes, so a lane working on one company can never
+ * rewrite another company's INDEX.md.
+ *
+ * The bound set is exactly what `core/scripts/hq-session.sh get company_slugs`
+ * prints for the session. The HQ tree's own script is run when it exists,
+ * otherwise the copy bundled with this CLI (in-tree implementation). On top of
+ * that, any session state that cannot be read or does not add up (unreadable
+ * metadata, a primary company that no longer resolves to a real directory, a
+ * lock set that names a symlinked company) is indeterminate and refuses the
+ * rebuild. It never counts as unbound.
+ *
+ * An unbound session keeps the every-company rebuild that automation
+ * (cleanup --reindex, rebuild-all-indexes.sh) relies on, with a warning.
+ *
+ * planScopedRebuild() runs before any write. Every refusal it raises is a
+ * CompanyIndexUserError raised before the first renderer call.
+ */
+import { type IndexTarget } from "./index.js";
+export interface PlannedRebuild {
+    target: IndexTarget;
+    args: string[];
+}
+export interface RebuildPlan {
+    runs: PlannedRebuild[];
+    /** Printed to stderr before the rebuild runs. */
+    warning?: string;
+}
+export type SessionCompanyState = {
+    kind: "unbound";
+} | {
+    kind: "bound";
+    companies: string[];
+};
+export declare const ALL_COMPANIES_FLAG = "--all-companies";
+/** Appended to the help of the company targets (projects, company-knowledge, companies). */
+export declare const SESSION_SCOPE_HELP: string;
+export declare const UNBOUND_ALL_COMPANIES_WARNING = "hq: rebuild-index: this session is not bound to a company, so every company's index is rebuilt. Pass --company <slug> to rebuild one.";
+export declare const COMPANY_SCOPE_FLAG_OFF_WARNING = "hq: rebuild-index: cli.rebuild-index-company-scope is off, so the company root indexes (companies/<slug>/INDEX.md) are rebuilt for every company, as before scoping.";
+export declare const PERSONAL_ALL_NOTE = "hq: rebuild-index all: this session is bound to personal; company indexes are skipped and the rest are rebuilt.";
+/**
+ * The session's bound company set, as `hq-session.sh get company_slugs`
+ * reports it. Throws CompanyIndexUserError when the state is indeterminate.
+ */
+export declare function sessionCompanyState(root: string, env?: NodeJS.ProcessEnv): SessionCompanyState;
+export interface PlanOptions {
+    /** cli.rebuild-index-company-scope: whether `companies` may be rebuilt for a single company. */
+    companyIndexScopeEnabled: boolean;
+}
+/**
+ * Decide which renderer calls a rebuild may make, before any of them runs.
+ *
+ * - Bound session: no company means exactly the bound companies; a company
+ *   outside the set, and --all-companies, are refused.
+ * - Unbound session: an explicit company is used as given; otherwise every
+ *   company is rebuilt, with a warning unless --all-companies was passed.
+ * - Indeterminate session state: refused.
+ * - `companies` for one company needs cli.rebuild-index-company-scope, whether
+ *   the company came from the caller or from the bound set. Under `all` the
+ *   companies child is skipped instead when the flag is off.
+ * - Every company is checked to be a real directory before anything runs.
+ */
+export declare function planScopedRebuild(target: IndexTarget, args: readonly string[], root: string, env: NodeJS.ProcessEnv, options: PlanOptions): RebuildPlan;
+//# sourceMappingURL=session-scope.d.ts.map

package/dist/lib/index-render/session-scope.js

@@ -0,0 +1,279 @@
+/**
+ * Session company scope for `hq core rebuild-index`.
+ *
+ * The renderers in this folder are pure: with no company they rebuild every
+ * company. The command layer must not inherit that default inside a
+ * company-bound session. A session bound to one or more companies may only
+ * rebuild those companies' indexes, so a lane working on one company can never
+ * rewrite another company's INDEX.md.
+ *
+ * The bound set is exactly what `core/scripts/hq-session.sh get company_slugs`
+ * prints for the session. The HQ tree's own script is run when it exists,
+ * otherwise the copy bundled with this CLI (in-tree implementation). On top of
+ * that, any session state that cannot be read or does not add up (unreadable
+ * metadata, a primary company that no longer resolves to a real directory, a
+ * lock set that names a symlinked company) is indeterminate and refuses the
+ * rebuild. It never counts as unbound.
+ *
+ * An unbound session keeps the every-company rebuild that automation
+ * (cleanup --reindex, rebuild-all-indexes.sh) relies on, with a warning.
+ *
+ * planScopedRebuild() runs before any write. Every refusal it raises is a
+ * CompanyIndexUserError raised before the first renderer call.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { sessionIdFromEnv, validSessionId } from "../core-utils/session-id.js";
+import { resolveBundledAsset } from "../../utils/hq-roots-core.js";
+import { CompanyIndexUserError } from "./companies.js";
+import { SKIP_COMPANY_INDEXES, UNSCOPED_COMPANIES_INDEX } from "./index.js";
+const COMPANY_TARGETS = new Set(["all", "companies", "company-knowledge", "projects"]);
+export const ALL_COMPANIES_FLAG = "--all-companies";
+/** Appended to the help of the company targets (projects, company-knowledge, companies). */
+export const SESSION_SCOPE_HELP = "\nCompany scope: in a company-bound session, a run with no company rebuilds only the bound companies\n" +
+    "(core/scripts/hq-session.sh get company_slugs), and a company outside that set is refused.\n" +
+    `An unbound session keeps the every-company rebuild (or pass --company <slug>); ${ALL_COMPANIES_FLAG} states that explicitly.\n`;
+export const UNBOUND_ALL_COMPANIES_WARNING = "hq: rebuild-index: this session is not bound to a company, so every company's index is rebuilt. Pass --company <slug> to rebuild one.";
+export const COMPANY_SCOPE_FLAG_OFF_WARNING = "hq: rebuild-index: cli.rebuild-index-company-scope is off, so the company root indexes (companies/<slug>/INDEX.md) are rebuilt for every company, as before scoping.";
+export const PERSONAL_ALL_NOTE = "hq: rebuild-index all: this session is bound to personal; company indexes are skipped and the rest are rebuilt.";
+/**
+ * The caller's session id. "" means no session at all: no id in the
+ * environment and no workspace/sessions/.current. A .current that exists but
+ * cannot be read or does not hold a valid id is indeterminate, not unbound.
+ */
+function callerSessionId(root, env) {
+    const fromEnv = sessionIdFromEnv(env);
+    if (fromEnv)
+        return fromEnv;
+    let current;
+    try {
+        current = fs.readFileSync(path.join(root, "workspace", "sessions", ".current"), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "";
+        indeterminate("workspace/sessions/.current is unreadable");
+    }
+    const id = current.replace(/[\t\n\v\f\r ]/g, "");
+    if (!validSessionId(id))
+        indeterminate("workspace/sessions/.current does not hold a valid session id");
+    return id;
+}
+function indeterminate(detail) {
+    throw new CompanyIndexUserError(`rebuild-index: cannot determine this session's bound companies (${detail}). Nothing was written.`);
+}
+function realCompanyDirectory(root, slug) {
+    try {
+        const stat = fs.lstatSync(path.join(root, "companies", slug));
+        return stat.isDirectory() && !stat.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function metaPrimary(contents) {
+    for (const line of contents.split(/\r?\n/)) {
+        const m = /^\s*company_slug:[\t ]*(.*)$/.exec(line);
+        if (m)
+            return m[1].replace(/^"|"$/g, "").trim();
+    }
+    return "";
+}
+/** The hq-session.sh to ask: the HQ tree's own, else the bundled in-tree copy. */
+function sessionScript(root) {
+    const own = path.join(root, "core", "scripts", "hq-session.sh");
+    try {
+        if (fs.statSync(own).isFile())
+            return { script: own, bundled: false };
+    }
+    catch { /* fall through to the bundled copy */ }
+    return { script: resolveBundledAsset("core/scripts/hq-session.sh"), bundled: true };
+}
+/**
+ * The session's bound company set, as `hq-session.sh get company_slugs`
+ * reports it. Throws CompanyIndexUserError when the state is indeterminate.
+ */
+export function sessionCompanyState(root, env = process.env) {
+    const sessionId = callerSessionId(root, env);
+    if (!sessionId)
+        return { kind: "unbound" };
+    const sessionDir = path.join(root, "workspace", "sessions", sessionId);
+    const metaPath = path.join(sessionDir, "meta.yaml");
+    const capabilityPath = path.join(sessionDir, "scope-capability.json");
+    let meta;
+    try {
+        const stat = fs.lstatSync(metaPath);
+        if (!stat.isFile())
+            indeterminate("session metadata is not a regular file");
+        meta = fs.readFileSync(metaPath, "utf8");
+    }
+    catch (error) {
+        if (error instanceof CompanyIndexUserError)
+            throw error;
+        if (error.code !== "ENOENT")
+            indeterminate("session metadata is unreadable");
+    }
+    const hasCapability = fs.existsSync(capabilityPath);
+    if (meta === undefined && !hasCapability)
+        return { kind: "unbound" };
+    const { script, bundled } = sessionScript(root);
+    const result = spawnSync("bash", [script, "--session-id", sessionId, "get", "company_slugs"], {
+        cwd: root,
+        encoding: "utf8",
+        env: { ...env, HQ_ROOT: root, ...(bundled ? { HQ_HQ_SESSION_NO_CLI: "1" } : {}) },
+        timeout: 60_000,
+    });
+    if (result.error || result.status !== 0)
+        indeterminate("hq-session.sh get company_slugs failed");
+    const slugs = result.stdout.trim() ? result.stdout.trim().split(",").map((s) => s.trim()) : [];
+    const primary = meta === undefined ? "" : metaPrimary(meta);
+    if (slugs.length === 0) {
+        // A recorded company or capability that resolves to nothing is a broken
+        // bind (for example a symlinked or removed company directory), not "unbound".
+        if (primary || hasCapability)
+            indeterminate("the recorded company does not resolve to a real company directory");
+        return { kind: "unbound" };
+    }
+    if (slugs.some((slug) => !/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(slug)))
+        indeterminate("the lock set is malformed");
+    if (slugs.some((slug) => slug !== "personal" && !realCompanyDirectory(root, slug))) {
+        indeterminate("a bound company is not a real company directory");
+    }
+    return { kind: "bound", companies: slugs };
+}
+/**
+ * Pull the scope out of the arguments. Positional slugs count as a company for
+ * the targets whose grammar accepts them (projects, company-knowledge); for
+ * companies and all only --company does.
+ */
+function parseScope(target, args) {
+    const explicit = [];
+    const rest = [];
+    let allCompanies = false;
+    const positional = target === "projects" || target === "company-knowledge";
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === ALL_COMPANIES_FLAG) {
+            allCompanies = true;
+            continue;
+        }
+        if (arg === "--company") {
+            const value = args[i + 1];
+            if (value !== undefined && !value.startsWith("-")) {
+                explicit.push(value);
+                i += 1;
+                continue;
+            }
+            rest.push(arg);
+            continue;
+        }
+        if (arg.startsWith("--company=")) {
+            const value = arg.slice("--company=".length);
+            if (value) {
+                explicit.push(value);
+                continue;
+            }
+            rest.push(arg);
+            continue;
+        }
+        if (positional && !arg.startsWith("-")) {
+            explicit.push(arg);
+            continue;
+        }
+        rest.push(arg);
+    }
+    return { explicit, allCompanies, rest };
+}
+function companyArgs(target, slug) {
+    return target === "companies" ? ["--company", slug] : [slug];
+}
+/**
+ * Decide which renderer calls a rebuild may make, before any of them runs.
+ *
+ * - Bound session: no company means exactly the bound companies; a company
+ *   outside the set, and --all-companies, are refused.
+ * - Unbound session: an explicit company is used as given; otherwise every
+ *   company is rebuilt, with a warning unless --all-companies was passed.
+ * - Indeterminate session state: refused.
+ * - `companies` for one company needs cli.rebuild-index-company-scope, whether
+ *   the company came from the caller or from the bound set. Under `all` the
+ *   companies child is skipped instead when the flag is off.
+ * - Every company is checked to be a real directory before anything runs.
+ */
+export function planScopedRebuild(target, args, root, env, options) {
+    if (!COMPANY_TARGETS.has(target))
+        return { runs: [{ target, args: args.filter((arg) => arg !== ALL_COMPANIES_FLAG) }] };
+    const { explicit, allCompanies, rest } = parseScope(target, args);
+    const label = `rebuild-index ${target}`;
+    // Argument errors first, in the renderers' own words, before the session is read.
+    const bad = rest[0];
+    if (bad !== undefined) {
+        const missingSlug = bad === "--company" || bad === "--company=";
+        if (target === "projects" || target === "company-knowledge") {
+            throw new CompanyIndexUserError(`${label}: expected a company slug; unknown or incomplete option`);
+        }
+        throw new CompanyIndexUserError(missingSlug ? `${label}: --company requires a company slug` : `${label}: unknown option ${bad}`);
+    }
+    if (allCompanies && explicit.length > 0) {
+        throw new CompanyIndexUserError(`${label}: pass either --company <slug> or ${ALL_COMPANIES_FLAG}, not both. Nothing was written.`);
+    }
+    if (target !== "all" && explicit.length > 1) {
+        throw new CompanyIndexUserError(target === "companies" ? `${label}: --company may be supplied once` : `${label}: supply only one company slug`);
+    }
+    const state = sessionCompanyState(root, env);
+    let companies;
+    let warning;
+    if (explicit.length > 0) {
+        if (state.kind === "bound") {
+            const outside = explicit.filter((slug) => !state.companies.includes(slug));
+            if (outside.length > 0) {
+                throw new CompanyIndexUserError(`${label}: "${outside[0]}" is outside this session's bound companies (${state.companies.join(", ")}). Nothing was written. Add it with core/scripts/hq-session.sh add company <slug> if this work is meant to span companies.`);
+            }
+        }
+        companies = [...new Set(explicit)];
+    }
+    else if (state.kind === "bound") {
+        if (allCompanies) {
+            throw new CompanyIndexUserError(`${label}: ${ALL_COMPANIES_FLAG} is not allowed in a session bound to ${state.companies.join(", ")}. Nothing was written.`);
+        }
+        companies = state.companies.filter((slug) => slug !== "personal");
+        if (companies.length === 0) {
+            // A personal session still rebuilds the indexes that belong to no company.
+            if (target === "all")
+                return { runs: [{ target, args: [SKIP_COMPANY_INDEXES] }], warning: PERSONAL_ALL_NOTE };
+            throw new CompanyIndexUserError(`${label}: this session is bound to personal, which has no company index to rebuild. Nothing was written.`);
+        }
+    }
+    else if (!allCompanies) {
+        warning = UNBOUND_ALL_COMPANIES_WARNING;
+    }
+    if (companies === undefined)
+        return { runs: [{ target, args: [] }], warning };
+    // Validate every company before the first write.
+    // A single caller-named company in an unbound session is left to the
+    // renderer, which reports a bad slug or directory in its own words before it
+    // writes. Anything that fans out to several renderer calls is checked here.
+    if (companies.length > 1 || target === "all") {
+        for (const slug of companies) {
+            if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(slug) || !realCompanyDirectory(root, slug)) {
+                throw new CompanyIndexUserError(`${label}: "${slug}" is not a real company directory. Nothing was written.`);
+            }
+        }
+    }
+    // cli.rebuild-index-company-scope is a kill switch (default on). Off, the
+    // companies root-index rebuild goes back to its pre-scoping behavior
+    // (every company) with a warning, instead of being refused or skipped.
+    const gateOff = !options.companyIndexScopeEnabled;
+    if (target === "companies" && gateOff && explicit.length === 0) {
+        return { runs: [{ target, args: [] }], warning: COMPANY_SCOPE_FLAG_OFF_WARNING };
+    }
+    if (target === "all") {
+        return {
+            runs: [{ target, args: [...companies.flatMap((slug) => ["--company", slug]), ...(gateOff ? [UNSCOPED_COMPANIES_INDEX] : [])] }],
+            warning: gateOff ? COMPANY_SCOPE_FLAG_OFF_WARNING : warning,
+        };
+    }
+    return { runs: companies.map((slug) => ({ target, args: companyArgs(target, slug) })), warning };
+}
+//# sourceMappingURL=session-scope.js.map

package/dist/lib/lanes/admission.js

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { accountMaxRunning } from "./config.js";
 import { LanesError } from "./errors.js";
+import { liveOwnerMaxMs, lockFileContents, reclaimStaleLock } from "./stale-lock.js";
 import { localHostIdsReferToSameMachine } from "./local-host-identity.js";
 import { quotaBlockFor } from "./quota.js";
 import { isSubagentLane, isTerminalLaneState } from "./types.js";
@@ -32,7 +33,7 @@ async function withAdmissionLock(lockPath, fn, sleep) {
             fd = fs.openSync(lockPath, "wx");
             const ownedStat = fs.fstatSync(fd);
             try {
-                fs.writeSync(fd, Buffer.from(`${process.pid}\n${Date.now()}\n`, "utf8"));
+                fs.writeSync(fd, Buffer.from(lockFileContents(), "utf8"));
             }
             catch (err) {
                 fs.closeSync(fd);
@@ -70,26 +71,12 @@ async function withAdmissionLock(lockPath, fn, sleep) {
                 throw new LanesError("store_lock_timeout", `Timed out waiting for admission lock ${lockPath}`, { path: lockPath });
             }
             try {
-                const raw = fs.readFileSync(lockPath, "utf8");
-                const [ownerLine, timestampLine] = raw.split("\n");
-                const ownerPid = ownerLine ? Number(ownerLine) : NaN;
-                const timestamp = timestampLine ? Number(timestampLine) : NaN;
-                if (Number.isSafeInteger(ownerPid) &&
-                    ownerPid > 0 &&
-                    Number.isFinite(timestamp) &&
-                    Date.now() - timestamp > ADMISSION_LOCK_STALE_MS &&
-                    !admissionLockOwnerAlive(ownerPid)) {
-                    if (fs.readFileSync(lockPath, "utf8") !== raw)
-                        continue;
-                    try {
-                        fs.unlinkSync(lockPath);
-                    }
-                    catch (unlinkErr) {
-                        if (unlinkErr.code !== "ENOENT")
-                            throw unlinkErr;
-                    }
+                if (reclaimStaleLock(lockPath, {
+                    staleMs: ADMISSION_LOCK_STALE_MS,
+                    liveOwnerMaxMs: liveOwnerMaxMs(),
+                    label: "hq lanes admission",
+                }, { isAlive: admissionLockOwnerAlive }))
                     continue;
-                }
             }
             catch (probeErr) {
                 if (probeErr.code !== "ENOENT") {

package/dist/lib/lanes/reconcile.js

@@ -44,6 +44,7 @@ import { activeLaneStories, laneStories, terminalEnvelopeStoryStatus } from "./s
 import { applyStorySwitchEnvelope } from "./story-switch.js";
 import { readProjectStoryStates } from "./story-ledger.js";
 import { decideEnvelopeRepair, envelopeQuestionIds, routeProviderFailure } from "./watcher.js";
+import { liveOwnerMaxMs, lockFileContents, reclaimStaleLock } from "./stale-lock.js";
 import { PROVIDER_REJECTED_REASON, providerRejectionDetails, readProviderRejection, } from "./provider-rejection.js";
 /** Spec §9: unanswered at the current hop for 60 minutes → one hop. */
 export const QUESTION_AGE_MS = 60 * 60 * 1000;
@@ -916,8 +917,10 @@ async function withReconcileLock(hqRoot, fn) {
         let fd;
         try {
             fd = fs.openSync(lockPath, "wx");
+            let held;
             try {
-                fs.writeSync(fd, Buffer.from(`${process.pid}\n${Date.now()}\n`, "utf8"));
+                fs.writeSync(fd, Buffer.from(lockFileContents(), "utf8"));
+                held = fs.fstatSync(fd);
             }
             catch (err) {
                 fs.closeSync(fd);
@@ -935,7 +938,10 @@ async function withReconcileLock(hqRoot, fn) {
                     process.stderr.write(`hq lanes reconcile: lock close failed: ${err instanceof Error ? err.message : String(err)}\n`);
                 }
                 try {
-                    fs.unlinkSync(lockPath);
+                    // Unlink only our own lock; a reclaimer may have replaced it.
+                    const current = fs.statSync(lockPath);
+                    if (current.dev === held.dev && current.ino === held.ino)
+                        fs.unlinkSync(lockPath);
                 }
                 catch (err) {
                     const code = err.code;
@@ -953,20 +959,12 @@ async function withReconcileLock(hqRoot, fn) {
                 throw new LanesError("store_lock_timeout", `Timed out waiting for reconcile lock ${lockPath}`, { path: lockPath });
             }
             try {
-                const raw = fs.readFileSync(lockPath, "utf8");
-                const tsLine = raw.split("\n")[1];
-                const ts = tsLine ? Number(tsLine) : NaN;
-                if (Number.isFinite(ts) && Date.now() - ts > RECONCILE_LOCK_STALE_MS) {
-                    try {
-                        fs.unlinkSync(lockPath);
-                    }
-                    catch (unlinkErr) {
-                        const unlinkCode = unlinkErr.code;
-                        if (unlinkCode !== "ENOENT")
-                            throw unlinkErr;
-                    }
+                if (reclaimStaleLock(lockPath, {
+                    staleMs: RECONCILE_LOCK_STALE_MS,
+                    liveOwnerMaxMs: liveOwnerMaxMs(),
+                    label: "hq lanes reconcile",
+                }))
                     continue;
-                }
             }
             catch (statErr) {
                 const statCode = statErr.code;

package/dist/lib/lanes/stale-lock.d.ts

@@ -0,0 +1,50 @@
+import * as fs from "node:fs";
+/**
+ * Shared stale-lock reclaim for the lanes store. A lock file holds
+ * `<pid>\n<epoch-ms>\n<hostname>\n`, written right after an exclusive create.
+ *
+ * Reclaim rules:
+ * - Same-host owner pid that no longer exists: reclaim at once.
+ * - Same-host owner pid that is alive, cannot be signalled, or is this process
+ *   (an async holder in this process): keep it until
+ *   the live-owner ceiling, which only guards against pid reuse and a hung
+ *   holder. A live holder is never reclaimed by the ordinary stale window.
+ * - Legacy lock with no host line whose pid is alive here: same ceiling.
+ * - Owner that cannot be verified here (empty, unparseable, foreign or missing
+ *   host): reclaim once older than the stale window.
+ *
+ * Age is the larger of the timestamp age and the file mtime age, so an empty
+ * lock or a future timestamp still ages out. Reclaim is atomic: the lock is
+ * renamed to a unique name that only one reclaimer can win, and a fresh lock
+ * displaced by a lost race is linked back into place.
+ */
+export interface StaleLockIo {
+    statSync?: (p: string) => fs.Stats;
+    readFileSync?: (p: string, enc: "utf8") => string;
+    renameSync?: (from: string, to: string) => void;
+    unlinkSync?: (p: string) => void;
+    linkSync?: (from: string, to: string) => void;
+    hostname?: () => string;
+    isAlive?: (pid: number) => boolean;
+}
+export interface StaleLockOptions {
+    /** Window after which an unverifiable owner is presumed gone. */
+    staleMs: number;
+    /** Ceiling after which even a live same-host owner is presumed hung or reused. */
+    liveOwnerMaxMs: number;
+    /** When false, only a verified dead same-host owner is reclaimed. */
+    reclaimByAge?: boolean;
+    /** Prefix for stderr notices. */
+    label?: string;
+}
+export declare const DEFAULT_LIVE_OWNER_MAX_MS: number;
+/** HQ_LANES_LOCK_LIVE_OWNER_MAX_MS overrides the live-owner ceiling. */
+export declare function liveOwnerMaxMs(env?: NodeJS.ProcessEnv): number;
+export declare function lockOwnerPidAlive(pid: number): boolean;
+/** Contents to write into a freshly created lock file. */
+export declare function lockFileContents(hostname?: string): string;
+/** Decide whether the lock content/age describes an abandoned lock. */
+export declare function lockIsStale(raw: string, mtimeMs: number, now: number, hostname: string, isAlive: (pid: number) => boolean, options: StaleLockOptions): boolean;
+/** Remove an abandoned lock atomically. Returns true when this call reclaimed it. */
+export declare function reclaimStaleLock(lockPath: string, options: StaleLockOptions, io?: StaleLockIo): boolean;
+//# sourceMappingURL=stale-lock.d.ts.map