@indigoai-us/hq-cli 5.345.156 → 5.345.160

package/dist/lib/lanes/store.js

@@ -24,7 +24,13 @@ export const LANES_STORE_REL = path.join("workspace", "lanes");
 export const LANE_RECORDS_DIR = "lanes";
 export const QUESTION_RECORDS_DIR = "questions";
 export const PENDING_INDEX_DIR = path.join("questions", "index", "pending");
-const LOCK_STALE_MS = 30_000;
+const DEFAULT_LOCK_STALE_MS = 30_000;
+/** Lock age after which any holder is presumed gone. HQ_LANES_LOCK_STALE_MS overrides it. */
+function lockStaleMs(env = process.env) {
+    const raw = env.HQ_LANES_LOCK_STALE_MS;
+    const parsed = raw === undefined ? NaN : Number(raw);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : DEFAULT_LOCK_STALE_MS;
+}
 const LOCK_RETRY_MS = 10;
 const LOCK_TIMEOUT_MS = 5_000;
 function defaultStoreDeps() {
@@ -153,16 +159,104 @@ function wait(ms) {
 function lockPathFor(recordPath) {
     return `${recordPath}.lock`;
 }
-function withRecordLock(recordPath, deps, fn) {
+function lockOwnerAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code !== "ESRCH";
+    }
+}
+function sameFile(a, b) {
+    return a.ino === b.ino && a.dev === b.dev;
+}
+/**
+ * Remove a record lock that no live process holds, and report whether it was
+ * removed. A lock is stale when it was written on this host and its owner pid
+ * no longer exists, or when it is older than the stale window. Age is the
+ * larger of the timestamp age and the file mtime age, so a future or
+ * unparseable timestamp still ages out through mtime.
+ *
+ * Removal is atomic: the lock is renamed to a unique name, which only one
+ * reclaimer can win. If the renamed file is not the lock that was inspected
+ * (another process reclaimed it and took a fresh lock in between), the fresh
+ * lock is linked back into place and nothing is reclaimed.
+ */
+function recordLockIsStale(lockPath, deps) {
+    const statSync = deps.statSync ?? ((p) => fs.statSync(p));
+    const linkSync = deps.linkSync ?? fs.linkSync.bind(fs);
+    const before = statSync(lockPath);
+    const raw = deps.readFileSync(lockPath, "utf8");
+    const [pidLine, tsLine, hostLine] = raw.split("\n");
+    const pid = pidLine ? Number(pidLine) : NaN;
+    const ts = tsLine ? Number(tsLine) : NaN;
+    const pidKnown = Number.isSafeInteger(pid) && pid > 0;
+    // A pid is only meaningful on the host that wrote it. A lock with a foreign
+    // or missing host falls back to the age rule.
+    const sameHost = hostLine !== undefined && hostLine.trim() !== "" && hostLine.trim() === deps.hostname();
+    const now = Date.now();
+    const mtimeAge = now - before.mtimeMs;
+    const age = Number.isFinite(ts) ? Math.max(now - ts, mtimeAge) : mtimeAge;
+    const stale = (pidKnown && sameHost && pid !== process.pid && !lockOwnerAlive(pid)) ||
+        age > lockStaleMs();
+    if (!stale)
+        return false;
+    const parked = `${lockPath}.stale.${process.pid}.${randomBytes(6).toString("hex")}`;
+    try {
+        deps.renameSync(lockPath, parked);
+    }
+    catch (renameErr) {
+        // Another reclaimer won the rename, or the holder released it.
+        if (renameErr.code === "ENOENT")
+            return false;
+        throw renameErr;
+    }
+    const removeParked = () => {
+        try {
+            deps.unlinkSync(parked);
+        }
+        catch (unlinkErr) {
+            if (unlinkErr.code !== "ENOENT")
+                throw unlinkErr;
+        }
+    };
+    let reclaimed;
+    try {
+        reclaimed = sameFile(statSync(parked), before) && deps.readFileSync(parked, "utf8") === raw;
+        if (!reclaimed) {
+            // The parked file is a live holder's fresh lock. Put it back.
+            try {
+                linkSync(parked, lockPath);
+            }
+            catch (linkErr) {
+                if (linkErr.code !== "EEXIST")
+                    throw linkErr;
+                process.stderr.write(`lanes store: could not restore displaced lock ${lockPath}; a newer lock already exists\n`);
+            }
+        }
+    }
+    catch (err) {
+        removeParked();
+        throw err;
+    }
+    removeParked();
+    return reclaimed;
+}
+function withRecordLock(recordPath, deps, fn, timeoutMs = LOCK_TIMEOUT_MS) {
     const lockPath = lockPathFor(recordPath);
+    const statSync = deps.statSync ?? ((p) => fs.statSync(p));
+    const fstatSync = deps.fstatSync ?? ((fd) => fs.fstatSync(fd));
     ensureDir(path.dirname(recordPath), deps);
     const started = Date.now();
     while (true) {
         let fd;
         try {
             fd = deps.openSync(lockPath, "wx");
+            let held;
             try {
-                fs.writeSync(fd, Buffer.from(`${process.pid}\n${Date.now()}\n`, "utf8"));
+                fs.writeSync(fd, Buffer.from(`${process.pid}\n${Date.now()}\n${deps.hostname()}\n`, "utf8"));
+                held = fstatSync(fd);
             }
             catch (err) {
                 deps.closeSync(fd);
@@ -180,7 +274,10 @@ function withRecordLock(recordPath, deps, fn) {
                     process.stderr.write(`lanes store: lock close failed for ${lockPath}: ${err instanceof Error ? err.message : String(err)}\n`);
                 }
                 try {
-                    deps.unlinkSync(lockPath);
+                    // Unlink only our own lock. If it was reclaimed and replaced while
+                    // fn ran, the file at lockPath belongs to the successor.
+                    if (sameFile(statSync(lockPath), held))
+                        deps.unlinkSync(lockPath);
                 }
                 catch (err) {
                     const code = err.code;
@@ -194,24 +291,12 @@ function withRecordLock(recordPath, deps, fn) {
             const code = err.code;
             if (code !== "EEXIST")
                 throw err;
-            if (Date.now() - started > LOCK_TIMEOUT_MS) {
+            if (Date.now() - started > timeoutMs) {
                 throw new LanesError("store_lock_timeout", `Timed out waiting for lock ${lockPath}`, { path: lockPath });
             }
             try {
-                const raw = deps.readFileSync(lockPath, "utf8");
-                const tsLine = raw.split("\n")[1];
-                const ts = tsLine ? Number(tsLine) : NaN;
-                if (Number.isFinite(ts) && Date.now() - ts > LOCK_STALE_MS) {
-                    try {
-                        deps.unlinkSync(lockPath);
-                    }
-                    catch (unlinkErr) {
-                        const unlinkCode = unlinkErr.code;
-                        if (unlinkCode !== "ENOENT")
-                            throw unlinkErr;
-                    }
+                if (recordLockIsStale(lockPath, deps))
                     continue;
-                }
             }
             catch (statErr) {
                 const statCode = statErr.code;
@@ -223,6 +308,10 @@ function withRecordLock(recordPath, deps, fn) {
         }
     }
 }
+/** Test seam: run withRecordLock with overridden deps and a shorter timeout. */
+export function withRecordLockForTests(recordPath, overrides, fn, timeoutMs) {
+    return withRecordLock(recordPath, { ...defaultStoreDeps(), ...overrides }, fn, timeoutMs);
+}
 /** Run a lane-owned file read/modify/write transaction under its sidecar lock. */
 export function withLaneRecordFileLock(recordPath, fn) {
     return withRecordLock(recordPath, defaultStoreDeps(), fn);

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

@@ -1029,6 +1029,8 @@ export interface LaneEnvelope {
     fingerprint?: string | null;
 }
 export interface AccountConfig {
+    /** Company slug or UID owning this account. Untagged accounts are personal. */
+    company?: string;
     home: string;
     /** Optional account home overrides keyed by the owning host's hostname. */
     hosts?: Record<string, AccountHostHome>;

package/dist/lib/lanes/watch.js

@@ -1,3 +1,7 @@
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { loopControllerIsAlive, loopStatus } from "./loop.js";
+import { laneRunDir } from "./spawn.js";
 import { expandLocalLaneIdPrefix, listQuestionIds, readLane, readQuestion, } from "./store.js";
 import { LaneNotFoundError, LanesError } from "./errors.js";
 import { providerSupportsSessionResume } from "./delivery.js";
@@ -118,6 +122,7 @@ export async function runLaneWatch(hqRoot, laneIds, deps = {}) {
     while (true) {
         polls += 1;
         const records = [];
+        const activeLoops = new Set();
         for (const laneId of watchedIds) {
             let record = null;
             try {
@@ -131,9 +136,27 @@ export async function runLaneWatch(hqRoot, laneIds, deps = {}) {
                 continue;
             }
             records.push(record);
-            if (previousStates.get(laneId) !== record.state) {
-                emit(`lane ${record.lane_id}: state=${record.state}${isTerminalLaneState(record.state) ? " (terminal)" : ""}`);
-                previousStates.set(laneId, record.state);
+            if (record.loop_mode === true) {
+                try {
+                    const runDir = laneRunDir(hqRoot, record.lane_id);
+                    // loopStatus defaults missing metadata to waiting; that is not
+                    // evidence of a controller after a failed admission or launch.
+                    if (fs.existsSync(path.join(runDir, "loop", "loop.json"))) {
+                        const status = loopStatus(runDir, record.lane_id);
+                        if (status.state !== "stopped" && status.state !== "failed" && loopControllerIsAlive(runDir))
+                            activeLoops.add(record.lane_id);
+                    }
+                }
+                catch (err) {
+                    unreadable("loop", laneId, err);
+                }
+            }
+            // A phase can be done while its loop controller awaits more work.
+            const terminal = isTerminalLaneState(record.state) && !activeLoops.has(record.lane_id);
+            const stateKey = `${record.state}:${terminal}`;
+            if (previousStates.get(laneId) !== stateKey) {
+                emit(`lane ${record.lane_id}: state=${record.state}${terminal ? " (terminal)" : ""}`);
+                previousStates.set(laneId, stateKey);
             }
         }
         const keepAliveWaiting = new Set();
@@ -175,7 +198,7 @@ export async function runLaneWatch(hqRoot, laneIds, deps = {}) {
         }
         if (deps.readAccountStatuses !== undefined) {
             const accountLanes = records.filter((record) => record.account !== undefined &&
-                (!isTerminalLaneState(record.state) || keepAliveWaiting.has(record.lane_id)));
+                (!isTerminalLaneState(record.state) || activeLoops.has(record.lane_id) || keepAliveWaiting.has(record.lane_id)));
             let statuses;
             try {
                 statuses = await deps.readAccountStatuses(accountLanes);
@@ -242,7 +265,7 @@ export async function runLaneWatch(hqRoot, laneIds, deps = {}) {
                     previousAccountLogin.set(key, status.logged_in);
             }
         }
-        if (records.every((record) => isTerminalLaneState(record.state) && !keepAliveWaiting.has(record.lane_id))) {
+        if (records.every((record) => isTerminalLaneState(record.state) && !activeLoops.has(record.lane_id) && !keepAliveWaiting.has(record.lane_id))) {
             return { polls, lines, suppressed };
         }
         await sleep(intervalMs);

package/dist/lib/lanes/watcher-main.js

@@ -12,6 +12,7 @@ import { isMainModule } from "../../utils/is-main-module.js";
 import { runWatcherLoop } from "./watcher.js";
 import { spawnEnvelopeRepairViaCurrentCli, } from "./envelope-repair-dispatch.js";
 import { LanesError } from "./errors.js";
+import { liveNodeBinary } from "./node-binary.js";
 import { openMeshTransport } from "../mesh/client.js";
 import { CompanySelectionError } from "../../utils/company-selection-error.js";
 export function watcherMainDeps(hqRoot, laneId, env = process.env, repairDispatchDeps = {}) {
@@ -21,7 +22,7 @@ export function watcherMainDeps(hqRoot, laneId, env = process.env, repairDispatc
         spawnRepair: (root, lane, input) => spawnEnvelopeRepairViaCurrentCli(root, lane, input, { ...repairDispatchDeps, env }),
         deliverLaneSeniorMessage: async (seniorLaneId, text) => deliverLaneSeniorMessage(cliEntry, seniorLaneId, text),
         recoverQueuedMessages: async () => {
-            const result = spawnSync(process.execPath, [cliEntry, "lanes", "_recover-queued-messages", laneId], {
+            const result = spawnSync(liveNodeBinary(), [cliEntry, "lanes", "_recover-queued-messages", laneId], {
                 env,
                 encoding: "utf8",
                 timeout: 120_000,
@@ -34,7 +35,7 @@ export function watcherMainDeps(hqRoot, laneId, env = process.env, repairDispatc
         },
         scheduleTerminalKeepAlive: async ({ laneId: scheduledLaneId, version, dueAt }) => {
             await new Promise((resolve, reject) => {
-                const child = spawn(process.execPath, [
+                const child = spawn(liveNodeBinary(), [
                     cliEntry,
                     "lanes",
                     "_keep-alive-terminal-trigger",
@@ -54,7 +55,7 @@ export function watcherMainDeps(hqRoot, laneId, env = process.env, repairDispatc
     };
 }
 function deliverLaneSeniorMessage(cliEntry, laneId, text) {
-    const result = spawnSync(process.execPath, [cliEntry, "lanes", "message", laneId, "--text", text], {
+    const result = spawnSync(liveNodeBinary(), [cliEntry, "lanes", "message", laneId, "--text", text], {
         env: process.env,
         encoding: "utf8",
         timeout: 120_000,

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

@@ -201,6 +201,8 @@ export interface WatcherLoopDeps {
     progressEventMinIntervalMs?: number;
     /** Bound a hung mesh request so watcher liveness polling continues. */
     meshRequestTimeoutMs?: number;
+    /** Bound on waiting for an older run's watcher to release the claim. */
+    claimWaitMs?: number;
     /** Spec §4 repair spawn. Default: `spawnEnvelopeRepair`. */
     spawnRepair?: (hqRoot: string, lane: LaneRecord, input: EnvelopeRepairSpawnInput) => number;
     /** Rebind and respawn after a provider quota or authentication refusal. */
@@ -247,6 +249,8 @@ export interface WatcherLoopDeps {
 export declare function emitMeshSoft(event: string, logDecision: (record: Record<string, unknown>) => void, at: string, fn: (signal: AbortSignal) => Promise<void>, timeoutMs?: number): Promise<boolean>;
 /** Question ids an ask envelope raised, as `raiseEnvelopeQuestions` mints them. */
 export declare function envelopeQuestionIds(laneId: string, envelopeRef: string, envelope: LaneEnvelope, questionIndexes?: readonly number[]): string[];
+/** How long a new phase watcher waits for an older phase's watcher to let go. */
+export declare const WATCHER_CLAIM_WAIT_MS = 60000;
 /** Detached and synchronous classifiers share one process-identity claim. */
 export declare function runWatcherLoop(hqRoot: string, laneId: string, deps?: WatcherLoopDeps): Promise<void>;
 export type EnvelopeRepairDecision = {

package/dist/lib/lanes/watcher.js

@@ -825,7 +825,7 @@ async function settleManagerStatusGate(hqRoot, lane, manifestTurnId, at, deps, l
         written = false;
     }
     if (written) {
-        return retryUpdateLane(hqRoot, lane.lane_id, "watcher", (current) => {
+        return updateLaneFollowup(hqRoot, lane.lane_id, deps, (current) => {
             if (current.status_gate?.turn_id !== gate.turn_id || current.status_gate.consecutive_misses === 0)
                 return current;
             return { ...current, status_gate: { ...current.status_gate, consecutive_misses: 0 } };
@@ -837,7 +837,7 @@ async function settleManagerStatusGate(hqRoot, lane, manifestTurnId, at, deps, l
         path: gate.status_path,
         at,
         identified_by: target.identified_by ?? "juniors",
-    }, resumeText);
+    }, resumeText, (current) => followupRunMoved(hqRoot, lane.lane_id, deps, current));
     const miss = updated.status_gate_history?.find((entry) => entry.event === "status_missed" && entry.turn_id === gate.turn_id);
     if (miss) {
         logDecision({
@@ -876,7 +876,7 @@ async function settleBlockerFreshness(hqRoot, lane, manifestTurnId, at, deps, me
     if (resolution.stale.length === 0) {
         if (lane.blocker_freshness_state === undefined)
             return lane;
-        return retryUpdateLane(hqRoot, lane.lane_id, "watcher", (current) => current.blocker_freshness_state === undefined
+        return updateLaneFollowup(hqRoot, lane.lane_id, deps, (current) => current.blocker_freshness_state === undefined
             ? current
             : { ...current, blocker_freshness_state: undefined });
     }
@@ -895,7 +895,7 @@ async function settleBlockerFreshness(hqRoot, lane, manifestTurnId, at, deps, me
             ? findBlockerFreshnessSessionInbox(hqRoot, lane.senior.id)
             : { reason: "The session senior has no session id" }
         : undefined;
-    let updated = retryUpdateLane(hqRoot, lane.lane_id, "watcher", (current) => {
+    let updated = updateLaneFollowup(hqRoot, lane.lane_id, deps, (current) => {
         deliverEscalation = false;
         deliverFallback = false;
         retryUndeliverable = false;
@@ -1014,7 +1014,7 @@ async function settleBlockerFreshness(hqRoot, lane, manifestTurnId, at, deps, me
                 kind: "blocker_stale_escalation_undeliverable",
                 text: `${escalationText} The session senior inbox is unavailable (${reason}); this escalation is recorded in the lane inbox for its next turn.`,
             });
-            updated = retryUpdateLane(hqRoot, lane.lane_id, "watcher", (current) => {
+            updated = updateLaneFollowup(hqRoot, lane.lane_id, deps, (current) => {
                 const state = current.blocker_freshness_state;
                 if (state === undefined)
                     return current;
@@ -1037,7 +1037,7 @@ async function settleBlockerFreshness(hqRoot, lane, manifestTurnId, at, deps, me
             const message = error instanceof Error ? error.message : String(error);
             process.stderr.write(`hq lanes watcher: blocker freshness fallback delivery failed for ${lane.lane_id}: ${message}\n`);
             logDecision({ event: "blocker_stale_escalation_fallback_failed", at, turn_id: turnId, fingerprint, error: message });
-            updated = retryUpdateLane(hqRoot, lane.lane_id, "watcher", (current) => {
+            updated = updateLaneFollowup(hqRoot, lane.lane_id, deps, (current) => {
                 const state = current.blocker_freshness_state;
                 const failureReason = `${undeliverableReason ?? `Session ${lane.senior.id ?? "unknown"} has no monitor-session inbox`}; lane inbox fallback failed: ${message}`;
                 return {
@@ -1080,7 +1080,7 @@ async function settleBlockerFreshness(hqRoot, lane, manifestTurnId, at, deps, me
             }
             logDecision({ event: "blocker_stale_escalation_delivered", at, turn_id: turnId, senior_kind: lane.senior.kind });
             if (retryUndeliverable) {
-                updated = retryUpdateLane(hqRoot, lane.lane_id, "watcher", (current) => {
+                updated = updateLaneFollowup(hqRoot, lane.lane_id, deps, (current) => {
                     const state = current.blocker_freshness_state;
                     const failedFallbackStillOpen = (current.status_gate_history ?? []).some((entry) => entry.event === "blocker_stale_escalation_undeliverable" &&
                         entry.fingerprint === fingerprint && entry.delivery_failed === true &&
@@ -1104,7 +1104,7 @@ async function settleBlockerFreshness(hqRoot, lane, manifestTurnId, at, deps, me
             const message = error instanceof Error ? error.message : String(error);
             process.stderr.write(`hq lanes watcher: blocker freshness escalation delivery failed for ${lane.lane_id}: ${message}\n`);
             logDecision({ event: "blocker_stale_escalation_delivery_failed", at, turn_id: turnId, error: message });
-            updated = retryUpdateLane(hqRoot, lane.lane_id, "watcher", (current) => {
+            updated = updateLaneFollowup(hqRoot, lane.lane_id, deps, (current) => {
                 const state = current.blocker_freshness_state;
                 if (state?.escalated_fingerprint !== fingerprint)
                     return current;
@@ -1151,7 +1151,7 @@ async function settleKrFreshness(hqRoot, lane, manifestTurnId, at, deps, logDeci
     if (stalled.length === 0) {
         if (lane.kr_freshness_state === undefined)
             return lane;
-        return retryUpdateLane(hqRoot, lane.lane_id, "watcher", (current) => current.kr_freshness_state === undefined
+        return updateLaneFollowup(hqRoot, lane.lane_id, deps, (current) => current.kr_freshness_state === undefined
             ? current
             : { ...current, kr_freshness_state: undefined });
     }
@@ -1159,7 +1159,7 @@ async function settleKrFreshness(hqRoot, lane, manifestTurnId, at, deps, logDeci
     const names = stalled.map((kpi) => kpi.name);
     const turnId = manifestTurnId ?? lane.status_gate?.turn_id ?? `unknown-${at}`;
     const resumeText = `These KPIs in ${resolution.statusPath} were not re-measured in the last ${resolution.windowHours}h: ${names.join(", ")}. Measure each one now, update value and measured_at, then end the turn.`;
-    return retryUpdateLane(hqRoot, lane.lane_id, "watcher", (current) => {
+    return updateLaneFollowup(hqRoot, lane.lane_id, deps, (current) => {
         const history = current.status_gate_history ?? [];
         if (history.some((entry) => entry.event === "kr_stalled" && entry.turn_id === turnId))
             return current;
@@ -1297,6 +1297,38 @@ function defaultSleep(ms) {
     });
 }
 const WATCHER_LOOP_OWNER_FILE = "watcher-loop.pid";
+/** Run identity (spawn manifest envelope path) of the current claimant. */
+const WATCHER_LOOP_RUN_FILE = "watcher-loop.run";
+/** How long a new phase watcher waits for an older phase's watcher to let go. */
+export const WATCHER_CLAIM_WAIT_MS = 60_000;
+const WATCHER_CLAIM_RETRY_MS = 250;
+/** Identifies one worker run of a lane; changes on every resume. */
+function watcherRunId(runDir) {
+    try {
+        return readSpawnManifest(runDir).envelope_path ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+/** True when the lane has moved on to a run this watcher does not own. */
+function followupRunMoved(hqRoot, laneId, deps, current) {
+    if (deps.followupRun === undefined)
+        return false;
+    return current.state === "running" || watcherRunId(laneRunDir(hqRoot, laneId)) !== deps.followupRun;
+}
+/** Watcher lane write that is a no-op once the lane belongs to a newer run. */
+function updateLaneFollowup(hqRoot, laneId, deps, updater) {
+    return retryUpdateLane(hqRoot, laneId, "watcher", (current) => followupRunMoved(hqRoot, laneId, deps, current) ? current : updater(current));
+}
+function readClaimRunId(runDir) {
+    try {
+        return fs.readFileSync(path.join(runDir, WATCHER_LOOP_RUN_FILE), "utf8").trim();
+    }
+    catch {
+        return null;
+    }
+}
 function claimWatcherLoop(hqRoot, laneId, deps) {
     const runDir = laneRunDir(hqRoot, laneId);
     const ownerPath = path.join(runDir, WATCHER_LOOP_OWNER_FILE);
@@ -1310,6 +1342,7 @@ function claimWatcherLoop(hqRoot, laneId, deps) {
         }
         if (existing !== null)
             fs.unlinkSync(ownerPath);
+        fs.writeFileSync(path.join(runDir, WATCHER_LOOP_RUN_FILE), `${watcherRunId(runDir)}\n`, "utf8");
         writePidRecord(ownerPath, {
             pid: process.pid,
             starttime: readStarttime(process.pid) ?? readProcStarttime(process.pid) ?? undefined,
@@ -1319,7 +1352,11 @@ function claimWatcherLoop(hqRoot, laneId, deps) {
     });
     if (owner === null)
         return null;
+    let released = false;
     return () => {
+        if (released)
+            return;
+        released = true;
         withLaneHireLocks(hqRoot, [laneId], () => {
             try {
                 const current = fs.statSync(ownerPath);
@@ -1391,7 +1428,7 @@ async function maybeContinueAfterMissingEnvelopeRepair(hqRoot, lane, envelope, e
     }
     if (!enabled)
         return lane;
-    const queued = retryUpdateLane(hqRoot, lane.lane_id, "watcher", (current) => {
+    const queued = updateLaneFollowup(hqRoot, lane.lane_id, deps, (current) => {
         if (current.version !== lane.version ||
             (current.state !== "done" && current.state !== "blocked") ||
             current.last_envelope?.ref !== envelopeRef ||
@@ -1421,17 +1458,59 @@ async function maybeContinueAfterMissingEnvelopeRepair(hqRoot, lane, envelope, e
 }
 /** Detached and synchronous classifiers share one process-identity claim. */
 export async function runWatcherLoop(hqRoot, laneId, deps = {}) {
-    const release = claimWatcherLoop(hqRoot, laneId, deps);
-    if (release === null)
-        return;
+    let release = claimWatcherLoop(hqRoot, laneId, deps);
+    if (release === null) {
+        // A live claimant from an older run (e.g. the previous phase's watcher
+        // still finishing its post-terminal mesh call) lets go soon. Wait for it
+        // instead of leaving this run unwatched. A claimant on the same run is a
+        // true duplicate and this watcher exits at once.
+        const sleep = deps.sleep ?? defaultSleep;
+        const now = deps.now ?? (() => Date.now());
+        const runDir = laneRunDir(hqRoot, laneId);
+        const myRun = watcherRunId(runDir);
+        const waitMs = deps.claimWaitMs ?? WATCHER_CLAIM_WAIT_MS;
+        const started = now();
+        let claimantRun = readClaimRunId(runDir);
+        while (release === null && claimantRun !== myRun && now() - started < waitMs) {
+            await sleep(WATCHER_CLAIM_RETRY_MS);
+            release = claimWatcherLoop(hqRoot, laneId, deps);
+            if (release === null)
+                claimantRun = readClaimRunId(runDir);
+        }
+        if (release === null) {
+            let claimantPid = null;
+            try {
+                claimantPid = readPidRecord(path.join(runDir, WATCHER_LOOP_OWNER_FILE))?.pid ?? null;
+            }
+            catch {
+                claimantPid = null;
+            }
+            const record = {
+                event: "watcher_claim_lost",
+                at: new Date(now()).toISOString(),
+                claimant_pid: claimantPid,
+                claimant_run: claimantRun,
+                run: myRun,
+                waited_ms: now() - started,
+            };
+            try {
+                writeWatcherDecision(deps.watcherOutPath ?? watcherOutLogPath(hqRoot, laneId), record, deps.watcherOutMaxBytes ?? WATCHER_OUT_MAX_BYTES);
+            }
+            catch {
+                // Logging is best effort; stderr below still records the loss.
+            }
+            process.stderr.write(`hq lanes watcher: claim lost for ${laneId} to pid ${claimantPid ?? "unknown"}\n`);
+            return;
+        }
+    }
     try {
-        await runWatcherLoopOwned(hqRoot, laneId, deps);
+        await runWatcherLoopOwned(hqRoot, laneId, deps, release);
     }
     finally {
         release();
     }
 }
-async function runWatcherLoopOwned(hqRoot, laneId, deps) {
+async function runWatcherLoopOwned(hqRoot, laneId, deps, releaseClaim = () => { }) {
     const sleep = deps.sleep ?? defaultSleep;
     const now = deps.now ?? (() => Date.now());
     const isAlive = deps.isAlive ?? isPidAlive;
@@ -1459,6 +1538,7 @@ async function runWatcherLoopOwned(hqRoot, laneId, deps) {
     const mesh = deps.mesh === undefined ? createLaneMesh({ interactive: false }) : deps.mesh;
     const storyStatusSuppressions = new Set();
     const meshRequestTimeoutMs = deps.meshRequestTimeoutMs ?? 10_000;
+    const ownRun = watcherRunId(runDir);
     const initialLane = readLaneSoft(hqRoot, laneId);
     if (mesh && initialLane) {
         // Every armed watcher refreshes the server descriptor. This migrates old
@@ -1889,6 +1969,12 @@ async function runWatcherLoopOwned(hqRoot, laneId, deps) {
                     state: updated.state,
                     version: updated.version,
                 });
+                // The lane is classified and this watcher stops polling after this
+                // tick. Let go of the single-owner claim before the slow mesh and
+                // follow-up awaits, so a watcher armed for the next phase can claim.
+                if (tick.done)
+                    releaseClaim();
+                const followupDeps = tick.done ? { ...deps, followupRun: ownRun } : deps;
                 // Spec §8 terminal rows: done → lane_done + story review; blocked →
                 // lane_blocked; ask → lane_ask with the queue ids. After the state
                 // write, so a mesh failure can never leave the lane unclassified.
@@ -1914,9 +2000,9 @@ async function runWatcherLoopOwned(hqRoot, laneId, deps) {
                     }
                 }
                 if (terminalWrite.changed) {
-                    updated = await settleManagerStatusGate(hqRoot, updated, manifest.turn_id, tick.emit.at, deps, logDecision);
-                    updated = await settleBlockerFreshness(hqRoot, updated, manifest.turn_id, tick.emit.at, deps, mesh, logDecision);
-                    updated = await settleKrFreshness(hqRoot, updated, manifest.turn_id, tick.emit.at, deps, logDecision);
+                    updated = await settleManagerStatusGate(hqRoot, updated, manifest.turn_id, tick.emit.at, followupDeps, logDecision);
+                    updated = await settleBlockerFreshness(hqRoot, updated, manifest.turn_id, tick.emit.at, followupDeps, mesh, logDecision);
+                    updated = await settleKrFreshness(hqRoot, updated, manifest.turn_id, tick.emit.at, followupDeps, logDecision);
                 }
                 const managerStatusFollowupQueued = manifest.turn_id !== undefined &&
                     updated.status_gate_history?.some((entry) => "turn_id" in entry && entry.turn_id === manifest.turn_id &&
@@ -1924,11 +2010,14 @@ async function runWatcherLoopOwned(hqRoot, laneId, deps) {
                             (entry.event === "blocker_stale" && entry.resume_queued === true) ||
                             (entry.event === "kr_stalled" && entry.resume_queued === true))) === true;
                 if (terminalWrite.changed && !managerStatusFollowupQueued) {
-                    updated = await maybeContinueAfterMissingEnvelopeRepair(hqRoot, updated, effectiveEnvelope ?? null, latest?.ref, tick.emit.at, deps, logDecision);
+                    updated = await maybeContinueAfterMissingEnvelopeRepair(hqRoot, updated, effectiveEnvelope ?? null, latest?.ref, tick.emit.at, followupDeps, logDecision);
                 }
                 if (terminalWrite.changed && deps.recoverQueuedMessages && !managerStatusFollowupQueued && updated.state !== "queued") {
                     try {
-                        if (dropboxInboxHasMessages(hqRoot, laneId)) {
+                        if (followupRunMoved(hqRoot, laneId, followupDeps, readLane(hqRoot, laneId))) {
+                            logDecision({ event: "message_recovery_skipped", at: tick.emit.at, reason: "newer_run" });
+                        }
+                        else if (dropboxInboxHasMessages(hqRoot, laneId)) {
                             await deps.recoverQueuedMessages(updated);
                             logDecision({
                                 event: "message_recovery",

package/dist/lib/mesh/api.d.ts

@@ -176,6 +176,38 @@ export declare function putProjectView(token: string, companyUid: string, projec
 }): Promise<MeshProjectView>;
 /** Register the project genesis thread and deterministic project channel. */
 export declare function registerMeshProject(token: string, companyUid: string, projectId: string, channelId?: string): Promise<MeshProjectRegistration>;
+export declare const PROJECT_LIFECYCLE_STATUSES: readonly ["active", "completed", "archived"];
+export type MeshProjectLifecycleStatus = (typeof PROJECT_LIFECYCLE_STATUSES)[number];
+/** One row of the server's PROJECT_LIFECYCLE record for a project. */
+export interface MeshProjectLifecycle {
+    projectId: string;
+    status: MeshProjectLifecycleStatus;
+    /** OCC version of the lifecycle row (not the Board version). */
+    version: number;
+    updatedAt: string;
+    updatedBy: string;
+}
+/**
+ * List every lifecycle row for a company (follows the 25-row server pages).
+ * A project with no row has never left `active` and is not listed.
+ */
+export declare function listProjectLifecycles(token: string, companyUid: string): Promise<MeshProjectLifecycle[]>;
+/** The lifecycle row for one project, or null when it has never been changed. */
+export declare function getProjectLifecycle(token: string, companyUid: string, projectId: string): Promise<MeshProjectLifecycle | null>;
+/**
+ * PATCH /v1/work-mesh/projects/{id}/lifecycle. `expectedVersion` is the
+ * current lifecycle row version (0 when the project has no row yet). The
+ * server answers 409 BOARD_NONEMPTY when archiving a Board that still has
+ * stories unless `confirmNonempty` is set, and a plain 409 on a version
+ * mismatch. Nothing is deleted: stories, folder, channel, members and
+ * history stay; the project only leaves the active list and the organize
+ * candidates.
+ */
+export declare function setProjectLifecycle(token: string, companyUid: string, projectId: string, change: {
+    status: MeshProjectLifecycleStatus;
+    expectedVersion: number;
+    confirmNonempty?: boolean;
+}): Promise<MeshProjectLifecycle>;
 export declare function pairDmUidsFromInbox(inbox: unknown): string[];
 export interface WarmCacheResult {
     directory: boolean;