@indigoai-us/hq-cli 5.204.0 → 5.206.0

package/dist/lib/lanes/reconcile.js

@@ -14,18 +14,22 @@ import { effectiveAccountHome } from "./account-home.js";
 import { loadLanesConfig, providerQuotaDefaultHoldMs } from "./config.js";
 import { MAX_LANE_DEPTH } from "./constants.js";
 import { AccountResolutionError, LanesError, isLaneVersionConflict } from "./errors.js";
+import { LANE_HIRE_GRANTS_FLAG, terminalChildResumeHireGrantError, withHireGrantAdmission, } from "./hire-grants.js";
 import { loadWorkerProfile } from "./profile.js";
 import { classifySessionLiveness, defaultLivenessDeps, loadLivenessIndex, readDaemonPresenceConnected, unindexedClaudeSessionLiveness, } from "./liveness.js";
 import { ANSWERED_QUESTIONS_FILE, armLaneWatcher, envelopeRepairMode, isPidRecordAlive, laneRunDir, readPidRecord, readSpawnManifest, markSpawnFailure, spawnEnvelopeRepair, spawnLaneWorker, retryLaneOnAlternateAccount, } from "./spawn.js";
 import { appendCappedHistory, lanesStoreRoot, parseLaneRecord, parseQuestionRecord, readLane, readQuestion, updateLane, updateQuestion, } from "./store.js";
 import { applyThrottleDecision, decideAdmission, defaultThrottleDeps, emptyThrottleState, evaluateThrottle, isCpuCheckEnabled, readAvailableMemMb, readThrottleState, resolveCpuBusyFraction, throttleStatePath, writeThrottleState, } from "./throttle.js";
+import { readLanesRegistryFlag } from "./registry-flag.js";
+import { LEAD_LANE_KEEP_ALIVE_FLAG, LEAD_LANE_KEEP_ALIVE_MAX_RESUMES, LEAD_LANE_KEEP_ALIVE_RESUME_TEXT, leadLaneKeepAliveBackoffMs, } from "./keep-alive.js";
+import { providerSupportsSessionResume } from "./delivery.js";
 import { applyDefaultQuotaHold, readQuotaSignal, recordAccountQuota } from "./quota.js";
 import { answeredQuestionEntries, raiseEnvelopeQuestions } from "./questions.js";
-import { SILENCE_MS, classifyLaneExit, isPidAlive, missingExpectedEnvelopeFile, readLatestEnvelopeFile, readLatestEnvelopeRecord, } from "./watcher.js";
+import { SILENCE_MS, classifyLaneExit, isPidAlive, missingExpectedEnvelopeFile, readLatestEnvelopeFile, readLatestEnvelopeRecord, watcherEventsPath, writeWatcherDecision, } from "./watcher.js";
 import { createLaneMesh, emitLaneDecisionEvents, emitLaneTerminalStateEvent, laneMeshCompany, } from "./mesh-events.js";
 import { laneStories, storyStatusForEnvelope } from "./stories.js";
 import { decideEnvelopeRepair, envelopeQuestionIds, routeProviderFailure } from "./watcher.js";
-import { providerRejectionDetails, readProviderRejection, } from "./provider-rejection.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;
 /** Spec §6.6 + §9: a depth-3 worker has two hops to age toward the user. */
@@ -792,11 +796,51 @@ export async function runPassBody(hqRoot, deps) {
             });
         }
     }
+    const readRegistryFlag = deps.readRegistryFlag ?? readLanesRegistryFlag;
+    const keepAliveFlagCompanies = new Map();
+    const keepAliveHireGrantFlagCompanies = new Map();
+    for (const lane of lanes) {
+        if (lane.state !== "done" ||
+            lane.keep_alive !== true ||
+            !laneRunsHere(lane, deps.host) ||
+            lane.terminal_reason === PROVIDER_REJECTED_REASON ||
+            lane.terminal_reason === "account_not_logged_in" ||
+            !providerSupportsSessionResume(lane.provider) ||
+            !(lane.provider_session_id ?? lane.last_resume?.session_id))
+            continue;
+        const envelope = readLatestEnvelopeRecord(hqRoot, lane.lane_id)?.envelope;
+        if (!envelope || envelope.decision !== "done" || envelope.story_complete === true)
+            continue;
+        const key = keepAliveCompanyKey(lane.company);
+        keepAliveFlagCompanies.set(key, lane.company);
+        if (lane.senior.kind === "lane" && lane.senior.id) {
+            keepAliveHireGrantFlagCompanies.set(key, lane.company);
+        }
+    }
+    const keepAliveFlagByCompany = new Map();
+    const keepAliveHireGrantFlagByCompany = new Map();
+    const env = deps.env ?? process.env;
+    await Promise.all([
+        ...[...keepAliveFlagCompanies.entries()].map(async ([key, company]) => {
+            keepAliveFlagByCompany.set(key, await readRegistryFlag(LEAD_LANE_KEEP_ALIVE_FLAG, {
+                company: company ?? undefined,
+                env,
+            }));
+        }),
+        ...[...keepAliveHireGrantFlagCompanies.entries()].map(async ([key, company]) => {
+            keepAliveHireGrantFlagByCompany.set(key, await readRegistryFlag(LANE_HIRE_GRANTS_FLAG, {
+                company: company ?? undefined,
+                env,
+            }));
+        }),
+    ]);
     await withAllLaneAdmissionLocks(hqRoot, async () => {
         const freshLanes = loadLaneRecords(hqRoot, summary);
+        resumeDoneKeepAlive(hqRoot, freshLanes, summary, deps, now, keepAliveFlagByCompany, keepAliveHireGrantFlagByCompany);
+        const drainLanes = loadLaneRecords(hqRoot, summary);
         const freshQuestions = loadQuestionRecords(hqRoot, summary);
-        await admitQueued(hqRoot, freshLanes, summary, deps, now);
-        await resumeAwaiting(hqRoot, freshLanes, freshQuestions, summary, deps);
+        await admitQueued(hqRoot, drainLanes, summary, deps, now);
+        await resumeAwaiting(hqRoot, drainLanes, freshQuestions, summary, deps);
     });
     if (!deps.dryRun && summary.errors.length === 0) {
         try {
@@ -1322,6 +1366,231 @@ async function admitQueued(hqRoot, lanes, summary, deps, now) {
         writeThrottleState(filePath, applyThrottleDecision(base, applied, nowMs), throttleDeps);
     }
 }
+function keepAliveCompanyKey(company) {
+    return JSON.stringify([company?.uid ?? null, company?.slug ?? null]);
+}
+function hasKeepAliveProgress(lane) {
+    return (lane.keep_alive_resume_count ?? 0) !== 0 ||
+        lane.keep_alive_last_resume_at !== undefined ||
+        lane.keep_alive_next_eligible_at !== undefined ||
+        lane.keep_alive_exhausted_at !== undefined;
+}
+function clearedKeepAliveProgress(lane) {
+    return {
+        ...lane,
+        keep_alive_resume_count: 0,
+        keep_alive_last_resume_at: undefined,
+        keep_alive_next_eligible_at: undefined,
+        keep_alive_exhausted_at: undefined,
+    };
+}
+function keepAliveProgressResetByHuman(lane) {
+    const count = lane.keep_alive_resume_count ?? 0;
+    const lastAutoMs = Date.parse(lane.keep_alive_last_resume_at ?? "");
+    if (count > 0 && !Number.isFinite(lastAutoMs))
+        return true;
+    const messageMs = Date.parse(lane.last_message_at ?? "");
+    const resumeMs = lane.last_resume?.text === LEAD_LANE_KEEP_ALIVE_RESUME_TEXT
+        ? Number.NaN
+        : Date.parse(lane.last_resume?.at ?? "");
+    return Number.isFinite(lastAutoMs) &&
+        ((Number.isFinite(messageMs) && messageMs > lastAutoMs) ||
+            (Number.isFinite(resumeMs) && resumeMs > lastAutoMs));
+}
+function recordKeepAliveEvent(hqRoot, laneId, summary, event) {
+    try {
+        writeWatcherDecision(watcherEventsPath(hqRoot, laneId), {
+            lane_id: laneId,
+            ...event,
+        });
+    }
+    catch (err) {
+        markDirty(summary, {
+            kind: "lane",
+            id: laneId,
+            why: `keep-alive event write failed: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
+}
+function resumeDoneKeepAlive(hqRoot, lanes, summary, deps, now, flagByCompany, hireGrantFlagByCompany) {
+    const nowMs = now.getTime();
+    const nowIso = now.toISOString();
+    const config = loadLanesConfig(hqRoot);
+    for (const lane of lanes) {
+        if (lane.state !== "done" ||
+            lane.keep_alive !== true ||
+            !laneRunsHere(lane, deps.host))
+            continue;
+        const latest = readLatestEnvelopeRecord(hqRoot, lane.lane_id);
+        const envelope = latest?.envelope;
+        if (!envelope || envelope.decision !== "done")
+            continue;
+        if (envelope.story_complete === true) {
+            if (hasKeepAliveProgress(lane)) {
+                casLaneIf(hqRoot, lane.lane_id, (current) => current.version === lane.version &&
+                    current.state === "done" &&
+                    current.keep_alive === true, (current) => clearedKeepAliveProgress(current), deps.dryRun);
+            }
+            continue;
+        }
+        if (lane.terminal_reason === PROVIDER_REJECTED_REASON ||
+            lane.terminal_reason === "account_not_logged_in" ||
+            !providerSupportsSessionResume(lane.provider) ||
+            !(lane.provider_session_id ?? lane.last_resume?.session_id))
+            continue;
+        if (flagByCompany.get(keepAliveCompanyKey(lane.company)) !== true)
+            continue;
+        const current = readLane(hqRoot, lane.lane_id);
+        if (current.version !== lane.version ||
+            current.state !== "done" ||
+            current.keep_alive !== true ||
+            !laneRunsHere(current, deps.host))
+            continue;
+        const currentEnvelope = readLatestEnvelopeRecord(hqRoot, current.lane_id)?.envelope;
+        if (!currentEnvelope || currentEnvelope.decision !== "done")
+            continue;
+        if (currentEnvelope.story_complete === true) {
+            if (hasKeepAliveProgress(current)) {
+                casLaneIf(hqRoot, current.lane_id, (latestLane) => latestLane.version === current.version &&
+                    latestLane.state === "done" &&
+                    latestLane.keep_alive === true, (latestLane) => clearedKeepAliveProgress(latestLane), deps.dryRun);
+            }
+            continue;
+        }
+        const providerSessionId = current.provider_session_id ?? current.last_resume?.session_id;
+        if (current.terminal_reason === PROVIDER_REJECTED_REASON ||
+            current.terminal_reason === "account_not_logged_in" ||
+            typeof providerSessionId !== "string" ||
+            providerSessionId.trim().length === 0)
+            continue;
+        const resetByHuman = keepAliveProgressResetByHuman(current);
+        const attempts = resetByHuman ? 0 : current.keep_alive_resume_count ?? 0;
+        if (attempts >= LEAD_LANE_KEEP_ALIVE_MAX_RESUMES) {
+            if (current.keep_alive_exhausted_at !== undefined)
+                continue;
+            const exhausted = casLaneIf(hqRoot, current.lane_id, (latestLane) => latestLane.version === current.version &&
+                latestLane.state === "done" &&
+                latestLane.keep_alive === true &&
+                (latestLane.keep_alive_resume_count ?? 0) >= LEAD_LANE_KEEP_ALIVE_MAX_RESUMES &&
+                latestLane.keep_alive_exhausted_at === undefined, (latestLane) => ({ ...latestLane, keep_alive_exhausted_at: nowIso }), deps.dryRun);
+            if (exhausted.changed && !deps.dryRun) {
+                recordKeepAliveEvent(hqRoot, current.lane_id, summary, {
+                    event: "keep_alive_exhausted",
+                    at: nowIso,
+                    attempt: attempts,
+                });
+            }
+            continue;
+        }
+        const attempt = attempts + 1;
+        const doneAtMs = Date.parse(current.updated_at);
+        const attemptEligibleMs = doneAtMs + leadLaneKeepAliveBackoffMs(attempt);
+        const storedNextMs = resetByHuman
+            ? Number.NaN
+            : Date.parse(current.keep_alive_next_eligible_at ?? "");
+        const nextEligibleMs = Number.isFinite(storedNextMs)
+            ? Math.max(attemptEligibleMs, storedNextMs)
+            : attemptEligibleMs;
+        if (nowMs < nextEligibleMs) {
+            if (resetByHuman && hasKeepAliveProgress(current)) {
+                casLaneIf(hqRoot, current.lane_id, (latestLane) => latestLane.version === current.version &&
+                    latestLane.state === "done" &&
+                    latestLane.keep_alive === true, (latestLane) => clearedKeepAliveProgress(latestLane), deps.dryRun);
+            }
+            continue;
+        }
+        const nextEligibleAt = new Date(nowMs + leadLaneKeepAliveBackoffMs(attempt + 1)).toISOString();
+        const queuedCount = loadLaneRecords(hqRoot, summary).filter((queuedLane) => queuedLane.state === "queued" &&
+            queuedLane.provider === current.provider &&
+            laneRunsHere(queuedLane, deps.host) &&
+            !hasFreshAdmissionReservation(queuedLane, nowMs)).length;
+        const maxQueued = config.providers[current.provider].max_queued;
+        if (queuedCount >= maxQueued) {
+            summary.skipped.push({
+                kind: "lane",
+                id: current.lane_id,
+                why: `lane_queue_full: ${current.provider} queue has ${queuedCount}/${maxQueued} lanes`,
+            });
+            continue;
+        }
+        const queue = (expectedSeniorId) => casLaneIf(hqRoot, current.lane_id, (latestLane) => latestLane.version === current.version &&
+            latestLane.state === "done" &&
+            latestLane.keep_alive === true &&
+            (expectedSeniorId === undefined ||
+                (latestLane.senior.kind === "lane" && latestLane.senior.id === expectedSeniorId)), (latestLane) => ({
+            ...latestLane,
+            state: "queued",
+            queued_reason: undefined,
+            queued_at: nowIso,
+            admission_reserved_at: undefined,
+            terminal_reason: undefined,
+            terminal_details: undefined,
+            pending_resume: {
+                session_id: providerSessionId,
+                trigger: "resume",
+                resumed_from: "done",
+                text: LEAD_LANE_KEEP_ALIVE_RESUME_TEXT,
+                compact: true,
+                at: nowIso,
+            },
+            keep_alive_resume_count: attempt,
+            keep_alive_last_resume_at: nowIso,
+            keep_alive_next_eligible_at: nextEligibleAt,
+            keep_alive_exhausted_at: undefined,
+        }), deps.dryRun);
+        const seniorId = current.senior.kind === "lane" ? current.senior.id : undefined;
+        let queued;
+        if (seniorId &&
+            hireGrantFlagByCompany.get(keepAliveCompanyKey(current.company)) === true) {
+            try {
+                queued = withHireGrantAdmission(hqRoot, seniorId, (snapshot) => {
+                    const latestLane = readLane(hqRoot, current.lane_id);
+                    if (latestLane.version !== current.version ||
+                        latestLane.senior.kind !== "lane" ||
+                        latestLane.senior.id !== seniorId)
+                        return { changed: false, record: latestLane };
+                    const refusal = terminalChildResumeHireGrantError(latestLane, snapshot);
+                    if (refusal !== null) {
+                        summary.skipped.push({
+                            kind: "lane",
+                            id: current.lane_id,
+                            why: `keep_alive_hire_admission: ${refusal.error}: ${refusal.message}`,
+                        });
+                        return { changed: false, record: latestLane };
+                    }
+                    return queue(seniorId);
+                });
+            }
+            catch (err) {
+                markDirty(summary, {
+                    kind: "lane",
+                    id: current.lane_id,
+                    why: `keep-alive hire admission failed: ${err instanceof Error ? err.message : String(err)}`,
+                });
+                continue;
+            }
+        }
+        else {
+            queued = queue(seniorId);
+        }
+        if (!queued.changed)
+            continue;
+        summary.resumed.push({
+            id: current.lane_id,
+            from: "done",
+            to: "queued",
+            reason: "keep_alive",
+        });
+        if (!deps.dryRun) {
+            recordKeepAliveEvent(hqRoot, current.lane_id, summary, {
+                event: "keep_alive_resume",
+                at: nowIso,
+                attempt,
+                next_eligible_at: nextEligibleAt,
+            });
+        }
+    }
+}
 async function resumeAwaiting(hqRoot, lanes, questions, summary, deps, onlyLaneIds) {
     const config = loadLanesConfig(hqRoot);
     const awaiting = lanes.filter((lane) => lane.state === "awaiting_input" &&

package/dist/lib/lanes/store.js

@@ -402,6 +402,31 @@ export function parseLaneRecord(raw, filePath) {
             value: raw.hire_grant,
         });
     }
+    if (raw.keep_alive !== undefined && typeof raw.keep_alive !== "boolean") {
+        throw new LaneSchemaError("keep_alive must be a boolean", {
+            path: filePath,
+            field: "keep_alive",
+            value: raw.keep_alive,
+        });
+    }
+    if (raw.keep_alive_resume_count !== undefined &&
+        (typeof raw.keep_alive_resume_count !== "number" ||
+            !Number.isSafeInteger(raw.keep_alive_resume_count) ||
+            raw.keep_alive_resume_count < 0 || raw.keep_alive_resume_count > 24)) {
+        throw new LaneSchemaError("keep_alive_resume_count must be an integer from 0 through 24", {
+            path: filePath,
+            field: "keep_alive_resume_count",
+            value: raw.keep_alive_resume_count,
+        });
+    }
+    for (const field of [
+        "keep_alive_last_resume_at",
+        "keep_alive_next_eligible_at",
+        "keep_alive_exhausted_at",
+    ]) {
+        if (raw[field] !== undefined)
+            requireTimestamp(raw[field], field, filePath);
+    }
     requireString(raw.project_id, "project_id");
     if (typeof raw.story_id !== "string" ||
         (raw.story_id.trim() === "" && raw.no_story_reason === undefined)) {

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

@@ -354,6 +354,16 @@ export interface LaneRecord {
     worker_pack?: string;
     /** Personal worker profile id applied to every spawn. */
     worker_profile?: string;
+    /** Whether this lead lane should resume completed turns while its story is open. */
+    keep_alive?: boolean;
+    /** Consecutive automatic keep-alive resumes since the last human reset. */
+    keep_alive_resume_count?: number;
+    /** Time the most recent automatic keep-alive resume was queued. */
+    keep_alive_last_resume_at?: string;
+    /** Earliest time the next consecutive automatic resume may be queued. */
+    keep_alive_next_eligible_at?: string;
+    /** Time the automatic resume cap was reached for this run of the story. */
+    keep_alive_exhausted_at?: string;
     /** Maximum number of direct child lanes this lane may keep alive; old records default to 0. */
     hire_grant?: number;
     /** Content hash of the profile last applied to this lane. */

package/dist/lib/lanes/types.js

@@ -224,6 +224,7 @@ export const LANE_FIELD_WRITERS = {
     pickup_validation_pending: ["creator", "command", "spawn", "reconcile"],
     pickup_validation_pending_since: ["creator", "command", "spawn", "reconcile"],
     priority: ["command"], worker: ["creator", "command"], worker_path: ["creator", "command"], worker_pack: ["creator", "command"], worker_profile: ["creator", "command"], worker_profile_hash: ["creator", "command", "spawn"], worker_profile_ignored: ["creator", "command", "spawn"], worker_policy_delivery: ["command", "spawn"],
+    keep_alive: ["creator", "command"], keep_alive_resume_count: ["command", "reconcile"], keep_alive_last_resume_at: ["command", "reconcile"], keep_alive_next_eligible_at: ["command", "reconcile"], keep_alive_exhausted_at: ["command", "reconcile"],
     provider: ["creator"], account: ["creator", "spawn", "command", "watcher", "reconcile"], account_selection: ["creator", "command"], admission_accounts: ["creator", "command"], account_history: ["command", "spawn", "watcher", "reconcile"], pending_resume: ["command", "spawn", "watcher", "reconcile"], placement_default: ["creator"], host: ["creator", "command"], origin_host: ["creator"], origin_host_source: ["creator"],
     version: ["creator"], created_at: ["creator"], updated_at: ["creator"], attribution_history: ["command"],
     last_envelope: ["watcher", "reconcile"], model: ["creator", "spawn", "command"], model_source: ["creator", "spawn", "command"], effort: ["creator", "spawn", "command"], effort_source: ["creator", "spawn", "command"], fast_mode: ["spawn"],

package/dist/startup-registration.js

@@ -158,6 +158,7 @@ export async function registerCommandsWithRecovery(args) {
                 waitedMs: result.waitedMs,
                 sawLock: result.sawLock,
                 sawRetired: result.sawRetired,
+                retiredSiblingPresent: result.retiredSiblingPresent,
                 sawTreeChange: result.sawTreeChange,
                 lockHeldAtEnd: result.lockHeldAtEnd,
                 lockedMs: result.lockedMs,
@@ -188,6 +189,7 @@ export async function registerCommandsWithRecovery(args) {
                 waitedMs: result.waitedMs,
                 sawLock: result.sawLock,
                 sawRetired: result.sawRetired,
+                retiredSiblingPresent: result.retiredSiblingPresent,
                 sawTreeChange: result.sawTreeChange,
                 lockTool: result.lockTool,
             });

package/dist/utils/install-tree-torn.d.ts

@@ -39,8 +39,9 @@
  */
 export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND" | "ENOENT" | "EVAL_THROW";
 /**
- * The closed set of resolution-failure dialects, verified on Node v22.23.1 (the
- * @sentry/node import-in-the-middle hook does not change the shapes):
+ * The closed set of resolution-failure dialects, verified on Node v22.23.1 and
+ * the observed Node 24 synchronous ESM loader shape (the @sentry/node
+ * import-in-the-middle hook does not change the stack transfer):
  *   - `esm-path`:    ESM importer, an absolute file (or legacyMainResolve dir)
  *                    target — `err.url` set, or `Cannot find package '<abs>'…`.
  *   - `esm-package`: ESM importer, a bare specifier — `Cannot find package
@@ -62,7 +63,7 @@ export type ModuleNotFoundCode = "ERR_MODULE_NOT_FOUND" | "MODULE_NOT_FOUND" | "
  *                    held in Module._pathCache) and gone at READ, so the CJS
  *                    loader's source read (defaultLoadImpl/loadSource, or the older
  *                    Module._extensions..js handler) raises ENOENT with syscall
- *                    'open' and a cjs/loader frame but NO esm/load frame. `err.path`
+ *                    'open' and a cjs/loader frame but NO ESM source-read frame. `err.path`
  *                    is the vanished file.
  *   - `resolve-enoent`: ESM/CJS RESOLVE-time ENOENT (HQ-CLI-1S) — a path component
  *                    stat'ed OK, then vanished before realpathSync's lstat, so the
@@ -179,6 +180,13 @@ export interface InstallTreeFs {
     existsSync(p: string): boolean;
     statSync(p: string): {
         isDirectory(): boolean;
+        isSymbolicLink?(): boolean;
+        size?: number;
+        mtimeMs?: number;
+    };
+    lstatSync?(p: string): {
+        isDirectory(): boolean;
+        isSymbolicLink?(): boolean;
         size?: number;
         mtimeMs?: number;
     };
@@ -264,6 +272,8 @@ export interface WaitForInstallTreeSettledResult {
     sawTreeChange?: boolean;
     /** True when the lock-free tree stayed unchanged for `staleProbeMs`. */
     staleTree?: boolean;
+    /** Presence on the final poll; null means the sibling directory was unreadable. */
+    retiredSiblingPresent?: boolean | null;
 }
 export declare const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1500;
 /**
@@ -278,10 +288,11 @@ export declare const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1500;
  * app, the box's update timer, another `hq`) cannot make a legitimately-in-progress
  * reinstall look stale:
  *   - UNLOCKED time — wall time observed with no fresh foreign lock — is bounded
- *     by `deadlineMs`. If the target is still missing, no lock or retired sibling
- *     is present, and the observed tree stays unchanged for `staleProbeMs`, the
- *     wait returns `staleTree` early. Any observed tree change keeps the ordinary
- *     settle deadline in force. `deadlineMs === 0` evaluates readiness once.
+ *     by `deadlineMs`. If the target is still missing and the observed tree,
+ *     including retired sibling names and mtimes, stays unchanged for
+ *     `staleProbeMs`, the wait returns `staleTree` early. Any observed tree
+ *     change keeps the ordinary settle deadline in force. `deadlineMs === 0`
+ *     evaluates readiness once.
  *   - LOCKED time — wall time observed under a fresh foreign lock held by a live
  *     pid — is bounded SEPARATELY by `lockWaitMs` (default the lock contract's own
  *     10-minute staleness window) and does NOT consume the settle budget. When
@@ -342,6 +353,8 @@ export type InstallTreeTornDiagnostics = {
     /** The bounded `tool` of the last fresh foreign lock seen, or "". */
     lockTool: string;
     node: string;
+    /** Presence on the final poll when the scope directory could be observed. */
+    retiredSiblingPresent?: boolean;
     /** The thrown error's `name` for the eval-throw dialect (HQ-CLI-1T), else "". */
     errorName: string;
 };
@@ -363,6 +376,8 @@ export interface InstallTreeTornInit {
     lockedMs?: number;
     /** The last fresh foreign lock's `tool`, bounded on construction (default ""). */
     lockTool?: string;
+    /** Final retired sibling presence, or null when the scope directory was unreadable. */
+    retiredSiblingPresent?: boolean | null;
 }
 /**
  * A torn-install failure that stays VISIBLE in Sentry with bounded, hq-derived