@indigoai-us/hq-cli 5.202.1 → 5.204.0

package/dist/lib/lanes/spawn.js

@@ -12,6 +12,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { PROVIDER_HOME_ENV, accountStatus, isLoggedOut, resolveAccount, selectBalancedAccount, } from "./accounts.js";
+import { effectiveAccountHome } from "./account-home.js";
 import { COMPACTION_PROMPT, compactionAfterUsage, compactionDue, compactLaneSession, } from "./compaction.js";
 import { installDrainHook } from "./hooks-install.js";
 import { loadLanesConfig, providerAutoCompactTokens, providerCompactAfterMs, } from "./config.js";
@@ -112,7 +113,7 @@ function accountModelForSpawn(provider, accountId, config, pinnedModel, profileM
         providerModel: config.providers[provider].model,
     });
 }
-function supportsSpawnModel(provider, accountId, config, pinnedModel, profileModel, modelDeps) {
+function supportsSpawnModel(provider, accountId, config, pinnedModel, profileModel, modelDeps, hostname) {
     const account = config.providers[provider].accounts[accountId];
     if (account === undefined)
         return false;
@@ -120,7 +121,7 @@ function supportsSpawnModel(provider, accountId, config, pinnedModel, profileMod
     if (model === undefined)
         return true;
     try {
-        validateLaneModel(provider, model, account.home, modelDeps);
+        validateLaneModel(provider, model, effectiveAccountHome(account, hostname).home, modelDeps);
         return true;
     }
     catch (err) {
@@ -129,7 +130,7 @@ function supportsSpawnModel(provider, accountId, config, pinnedModel, profileMod
         throw err;
     }
 }
-function spawnModelFailure(provider, accountId, config, pinnedModel, profileModel, profileId, modelDeps) {
+function spawnModelFailure(provider, accountId, config, pinnedModel, profileModel, profileId, modelDeps, hostname) {
     const account = config.providers[provider].accounts[accountId];
     if (account === undefined)
         return new LanesError("unknown_account", `Unknown account ${accountId} for ${provider}`, { provider, account: accountId });
@@ -137,7 +138,7 @@ function spawnModelFailure(provider, accountId, config, pinnedModel, profileMode
     if (model === undefined)
         return null;
     try {
-        validateLaneModel(provider, model, account.home, modelDeps);
+        validateLaneModel(provider, model, effectiveAccountHome(account, hostname).home, modelDeps);
         return null;
     }
     catch (err) {
@@ -155,17 +156,18 @@ function spawnModelFailure(provider, accountId, config, pinnedModel, profileMode
     }
 }
 function selectSpawnAccount(input) {
-    const { hqRoot, lane, config, existsSync, accountDeps, modelDeps, pinnedModel, profileModel, currentModelValidated } = input;
+    const { hqRoot, lane, config, existsSync, accountDeps, modelDeps, pinnedModel, profileModel, currentModelValidated, hostname } = input;
     const context = {
         hqRoot,
         existsSync,
         accountDeps,
+        hostname,
         ...(pinnedModel ?? profileModel ? { model: pinnedModel ?? profileModel } : {}),
     };
     if (lane.account === undefined) {
         const modelSpecified = pinnedModel !== undefined || profileModel !== undefined;
         const allowedAccounts = modelSpecified
-            ? Object.keys(config.providers[lane.provider].accounts).filter((id) => supportsSpawnModel(lane.provider, id, config, pinnedModel, profileModel, modelDeps))
+            ? Object.keys(config.providers[lane.provider].accounts).filter((id) => supportsSpawnModel(lane.provider, id, config, pinnedModel, profileModel, modelDeps, hostname))
             : undefined;
         return {
             account: selectBalancedAccount(lane.provider, config, {
@@ -188,6 +190,7 @@ function selectSpawnAccount(input) {
     else {
         const status = accountStatus(lane.provider, lane.account, config, {
             existsSync,
+            hostname,
             ...(accountDeps?.probe ? { probe: accountDeps.probe } : {}),
             ...(accountDeps?.env ? { env: accountDeps.env } : {}),
         });
@@ -200,7 +203,7 @@ function selectSpawnAccount(input) {
                 resolveAccount(lane.provider, lane.account, config, context);
                 const modelFailure = currentModelValidated
                     ? null
-                    : spawnModelFailure(lane.provider, lane.account, config, pinnedModel, profileModel, lane.worker_profile, modelDeps);
+                    : spawnModelFailure(lane.provider, lane.account, config, pinnedModel, profileModel, lane.worker_profile, modelDeps, hostname);
                 if (modelFailure !== null) {
                     reason = "model_change";
                     refusal = modelFailure;
@@ -240,10 +243,11 @@ function selectSpawnAccount(input) {
         .filter(([id, account]) => id !== lane.account && account.enabled)
         .filter(([id]) => accountStatus(lane.provider, id, config, {
         existsSync,
+        hostname,
         ...(accountDeps?.probe ? { probe: accountDeps.probe } : {}),
         ...(accountDeps?.env ? { env: accountDeps.env } : {}),
     }).logged_in === true)
-        .filter(([id]) => supportsSpawnModel(lane.provider, id, config, pinnedModel, profileModel, modelDeps))
+        .filter(([id]) => supportsSpawnModel(lane.provider, id, config, pinnedModel, profileModel, modelDeps, hostname))
         .map(([id]) => id);
     try {
         return {
@@ -345,6 +349,8 @@ export async function retryLaneOnAlternateAccount(hqRoot, lane, reason, writer =
     const config = loadLanesConfig(hqRoot);
     const existsSync = deps.existsSync ?? ((p) => fs.existsSync(p));
     const env = deps.env ?? process.env;
+    const admissionHost = deps.admissionHost ?? resolveAdmissionHost();
+    const hostname = deps.hostname?.trim() || admissionHost.hostname.trim() || resolveAdmissionHost().hostname;
     const modelDeps = {
         ...deps.modelDeps,
         env: deps.modelDeps?.env ?? env,
@@ -353,7 +359,6 @@ export async function retryLaneOnAlternateAccount(hqRoot, lane, reason, writer =
         probe: modelDeps.probe ?? defaultProbe,
         env,
     };
-    const admissionHost = deps.admissionHost ?? resolveAdmissionHost();
     const profile = lane.worker_profile ? loadWorkerProfile(hqRoot, lane.worker_profile) : undefined;
     const profileModel = profile?.meta.provider === lane.provider ? profile.meta.model : undefined;
     const pinnedModel = lane.model_source === undefined || lane.model_source === "cli" ? lane.model : undefined;
@@ -362,15 +367,17 @@ export async function retryLaneOnAlternateAccount(hqRoot, lane, reason, writer =
         .filter(([id, account]) => id !== lane.account && !unavailableAccounts.has(id) && account.enabled)
         .filter(([id]) => accountStatus(lane.provider, id, config, {
         existsSync,
+        hostname,
         ...(accountDeps?.probe ? { probe: accountDeps.probe } : {}),
         ...(accountDeps?.env ? { env: accountDeps.env } : {}),
     }).logged_in === true)
-        .filter(([id]) => supportsSpawnModel(lane.provider, id, config, pinnedModel, profileModel, modelDeps))
+        .filter(([id]) => supportsSpawnModel(lane.provider, id, config, pinnedModel, profileModel, modelDeps, hostname))
         .map(([id]) => id);
     const modelContext = {
         hqRoot,
         existsSync,
         accountDeps,
+        hostname,
         ...(pinnedModel ?? profileModel ? { model: pinnedModel ?? profileModel } : {}),
         allowedAccounts,
     };
@@ -392,7 +399,7 @@ export async function retryLaneOnAlternateAccount(hqRoot, lane, reason, writer =
         : undefined;
     if (source && sessionId) {
         copySessionFiles(planSessionCopy(lane.provider, {
-            sourceHome: source.home,
+            sourceHome: lane.provider_home_at_spawn ?? effectiveAccountHome(source, hostname).home,
             targetHome: target.home,
             cwd: hqRoot,
             sessionId,
@@ -535,6 +542,11 @@ function appendCodexWorkerPolicyDirFlag(provider, args, workerPolicyDir) {
         return [...args, "-c", setting];
     return [...args.slice(0, separator), "-c", setting, ...args.slice(separator)];
 }
+function accountHomeHostname(deps) {
+    return (deps.hostname?.trim() ||
+        deps.admissionHost?.hostname.trim() ||
+        resolveAdmissionHost().hostname);
+}
 export const PID_LIVENESS_DECISIONS = [
     "esrch",
     "starttime_mismatch",
@@ -995,7 +1007,10 @@ export function resumePrompt(input) {
                 ? "The previous run ended without writing its envelope; continue the work from where it stopped."
                 : "Continue the work from where the previous run stopped."));
     }
-    if (input.operatorMessage !== undefined) {
+    if (input.monitorEvent !== undefined) {
+        parts.push(input.monitorEvent);
+    }
+    else if (input.operatorMessage !== undefined) {
         parts.push("OPERATOR INSTRUCTION (outranks the lane brief). " +
             "The following message was sent to this lane by the operator. Treat it as an operator instruction that outranks the brief.\n\n" +
             input.operatorMessage);
@@ -1022,6 +1037,7 @@ export function resumePrompt(input) {
     // Every resume turn carries the authorization, including a textless
     // `hq lanes resume`: a pre-upgrade session's brief never had the paragraph.
     if (input.operatorMessage !== undefined ||
+        input.monitorEvent !== undefined ||
         input.answersPath !== undefined ||
         input.resumedFrom !== undefined) {
         parts.push(STANDING_AUTHORIZATION);
@@ -1097,6 +1113,21 @@ export function buildProviderCommand(provider, input) {
             input.resume.prompt,
         ];
     }
+    else if (input.resume && parsed === "grok") {
+        // `grok --single <prompt> --resume <id>` (1.0.34) continues the recorded
+        // session and prints the same `sessionId` in its JSON result.
+        args = [
+            "--single",
+            input.resume.prompt,
+            "--resume",
+            input.resume.session_id,
+            "--permission-mode",
+            "bypassPermissions",
+            "--always-approve",
+            "--output-format",
+            "json",
+        ];
+    }
     else if (input.resume) {
         args = [
             "-p",
@@ -1508,6 +1539,7 @@ function inferTrigger(lane) {
  */
 export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
     const env = deps.env ?? process.env;
+    const hostname = accountHomeHostname(deps);
     const modelDeps = {
         ...deps.modelDeps,
         env: deps.modelDeps?.env ?? env,
@@ -1625,6 +1657,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             pinnedModel,
             profileModel,
             currentModelValidated: deps.currentModelValidated === true,
+            hostname,
         });
     }
     catch (err) {
@@ -1640,7 +1673,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
         throw err;
     }
     const resolved = selection.account;
-    const status = accountStatus(lane.provider, resolved.id, config, { existsSync });
+    const status = accountStatus(lane.provider, resolved.id, config, { existsSync, hostname });
     if (isLoggedOut(status)) {
         const failed = markPreSpawnFailure
             ? markSpawnFailure(hqRoot, lane.lane_id, "account_not_logged_in", {
@@ -1658,7 +1691,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             existing.provider_session_id &&
             providerSupportsSessionResume(existing.provider)) {
             copySessionFiles(planSessionCopy(existing.provider, {
-                sourceHome: source.home,
+                sourceHome: existing.provider_home_at_spawn ?? effectiveAccountHome(source, hostname).home,
                 targetHome: resolved.home,
                 cwd: hqRoot,
                 sessionId: existing.provider_session_id,
@@ -1672,7 +1705,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             cwd: hqRoot,
             targetHome: resolved.home,
             registeredHomes: Object.values(config.providers[existing.provider].accounts)
-                .map((account) => account.home),
+                .map((account) => effectiveAccountHome(account, hostname).home),
             providerHomeAtSpawn: existing.provider_home_at_spawn,
         });
     }
@@ -1745,11 +1778,18 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             session_id: plan.session_id,
             prompt: resumePrompt({
                 envelopePath,
-                operatorMessage: trigger.kind === "message"
+                operatorMessage: trigger.kind === "message" && trigger.monitor_event !== true
                     ? trigger.text
                     : trigger.kind === "resume"
                         ? trigger.text
-                        : pendingResume?.text,
+                        : pendingResume?.monitor_event === true
+                            ? undefined
+                            : pendingResume?.text,
+                monitorEvent: trigger.kind === "message" && trigger.monitor_event === true
+                    ? trigger.text
+                    : pendingResume?.monitor_event === true
+                        ? pendingResume.text
+                        : undefined,
                 resumedFrom: trigger.kind === "resume" ? trigger.from : pendingResume?.resumed_from,
                 answersPath: (trigger.kind === "answered_questions" || pendingResume?.trigger === "answered_questions") && existsSync(answersPath)
                     ? answersPath
@@ -1933,6 +1973,7 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
                 account: resolved.id,
                 trigger: pendingResume.trigger,
                 ...(pendingResume.message_id !== undefined ? { message_id: pendingResume.message_id } : {}),
+                ...(pendingResume.monitor_event === true ? { monitor_event: true } : {}),
                 ...(pendingResume.resumed_from !== undefined ? { resumed_from: pendingResume.resumed_from } : {}),
                 ...(pendingResume.text !== undefined ? { text: pendingResume.text } : {}),
                 ...(pendingResume.compact !== undefined ? { compact: pendingResume.compact } : {}),
@@ -1945,7 +1986,11 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
                 account: resolved.id,
                 trigger: trigger.kind,
                 ...(trigger.kind === "message"
-                    ? { message_id: trigger.message_id, text: trigger.text }
+                    ? {
+                        message_id: trigger.message_id,
+                        text: trigger.text,
+                        ...(trigger.monitor_event === true ? { monitor_event: true } : {}),
+                    }
                     : {}),
                 ...(launch.compact !== undefined ? { compact: launch.compact } : {}),
                 ...(trigger.kind === "resume"
@@ -2043,12 +2088,14 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
 }
 /**
  * `resume`: claude and codex continue the recorded session with the repair
- * prompt. `fresh_turn`: grok has no session resume, so the repair is a new
- * single-turn invocation of the same provider on the same account, whose
- * prompt carries the schema, the parser error and the raw failed output.
+ * prompt. `fresh_turn`: grok gets a new single-turn invocation on the same
+ * account, whose prompt carries the schema, the parser error and the raw
+ * failed output. Grok can resume a session (operator messages and
+ * `hq lanes resume` use it), but its repair turn stays a fresh turn: that
+ * path was built and proven that way, and a repair by resume has not been.
  */
 export function envelopeRepairMode(provider) {
-    return providerSupportsSessionResume(provider) ? "resume" : "fresh_turn";
+    return providerSupportsSessionResume(provider) && provider !== "grok" ? "resume" : "fresh_turn";
 }
 /**
  * Spec §4 repair turn. The lane is still `running` (the watcher has not
@@ -2062,6 +2109,7 @@ export function envelopeRepairMode(provider) {
  */
 export function spawnEnvelopeRepair(hqRoot, lane, input, deps = {}) {
     const env = deps.env ?? process.env;
+    const hostname = accountHomeHostname(deps);
     const existsSync = deps.existsSync ?? ((p) => fs.existsSync(p));
     const spawnProcess = deps.spawnProcess ?? defaultSpawnProcess;
     const proveDetached = deps.proveDetached ?? defaultProveDetached;
@@ -2108,6 +2156,7 @@ export function spawnEnvelopeRepair(hqRoot, lane, input, deps = {}) {
     const resolved = resolveAccount(lane.provider, lane.account, config, {
         hqRoot,
         existsSync,
+        hostname,
         model: pinnedModel ?? profileModel,
     });
     if (profileDefaultsApply && profileModel !== undefined && pinnedModel === undefined) {

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

@@ -514,6 +514,8 @@ export interface PendingResume {
     resumed_from?: "interrupted" | "done" | "blocked" | "failed";
     text?: string;
     message_id?: string;
+    /** The text is already framed as untrusted monitor data, not an operator instruction. */
+    monitor_event?: true;
     /** False when the command passed --no-compact; the deferred spawn honours it. */
     compact?: boolean;
     at: string;
@@ -534,6 +536,7 @@ export interface LaneResumeRecord {
     account?: string;
     trigger: "answered_questions" | "message" | "resume";
     message_id?: string;
+    monitor_event?: true;
     /**
      * `hq lanes resume` only: the state the lane was in when the operator
      * resumed it (`interrupted`, `done` or `blocked`) and the text they sent.
@@ -642,6 +645,8 @@ export interface LaneEnvelope {
 }
 export interface AccountConfig {
     home: string;
+    /** Optional account home overrides keyed by the owning host's hostname. */
+    hosts?: Record<string, AccountHostHome>;
     enabled: boolean;
     disabled_reason?: string;
     max_running?: number;
@@ -650,6 +655,9 @@ export interface AccountConfig {
     /** Default effort for this account. Beats the provider default; beaten by --effort. */
     effort?: string;
 }
+export interface AccountHostHome {
+    home: string;
+}
 export interface ProviderConfig {
     max_running: number;
     max_queued: number;

package/dist/lib/monitor.d.ts

@@ -0,0 +1,153 @@
+import type { LaneCompanyRef, LaneProvider } from "./lanes/types.js";
+export declare const MONITOR_SCHEMA_VERSION: "hq-monitor.v1";
+export declare const MONITOR_FLAG = "monitor.enabled";
+export declare const MONITOR_FLAG_DEFAULT = false;
+export declare const MONITOR_DEFAULT_TIMEOUT_MS: number;
+export declare const MONITOR_DEFAULT_CHECKIN_MS: number;
+export declare const MONITOR_PROMPT_CACHE_TTL_MS: number;
+export declare const MONITOR_BATCH_WINDOW_MS = 200;
+export declare const MONITOR_POLL_INTERVAL_MS = 1000;
+export declare const MONITOR_RATE_WINDOW_MS = 10000;
+/** Sustained stdout floods stop after 3 windows; the per-window cap can be overridden with HQ_MONITOR_MAX_EVENTS_PER_WINDOW. */
+export declare const MONITOR_MAX_EVENTS_PER_WINDOW = 60;
+export declare const MONITOR_MAX_FLOOD_WINDOWS = 3;
+export declare const MONITOR_LOCK_STALE_MS = 30000;
+export declare const MONITOR_MAX_TIMER_DELAY_MS = 2147000000;
+export type MonitorTarget = {
+    kind: "lane";
+    laneId: string;
+} | {
+    kind: "session";
+    provider: LaneProvider;
+    sessionId: string;
+};
+export interface MonitorProcessEntry {
+    pid: number;
+    ppid: number;
+    command: string;
+}
+export interface DetectMonitorTargetOptions {
+    env: NodeJS.ProcessEnv;
+    parentPid: number;
+    readProcess: (pid: number) => MonitorProcessEntry | null;
+}
+export interface NearestMonitorRuntime {
+    provider: LaneProvider;
+    pid: number;
+}
+export interface MonitorRuntimeIdentity extends NearestMonitorRuntime {
+    starttime: number;
+}
+export interface MonitorSessionOwner {
+    pid: number;
+    starttime: number | null;
+}
+export interface MonitorMetadata {
+    schema_version: typeof MONITOR_SCHEMA_VERSION;
+    monitor_id: string;
+    target: MonitorTarget;
+    target_key: string;
+    company: LaneCompanyRef | null;
+    description: string;
+    command: string | null;
+    argv: string[] | null;
+    cwd: string;
+    created_at: string;
+    timeout_ms: number | null;
+    persistent: boolean;
+    checkin_ms: number | null;
+    session_owner: MonitorSessionOwner | null;
+}
+export interface MonitorState {
+    status: "starting" | "running" | "stopping" | "terminal";
+    pid: number | null;
+    starttime: number | null;
+    child_pid?: number | null;
+    child_starttime?: number | null;
+    started_at?: string;
+    finished_at?: string;
+    exit_code?: number | null;
+    terminal_reason?: string;
+    event_count: number;
+    /** Last sequence written to events.jsonl, including undeliverable events. */
+    event_sequence?: number;
+}
+export interface MonitorEvent {
+    seq: number;
+    at: string;
+    text: string;
+    delivery: string;
+    reason?: string;
+}
+export interface MonitorTargetActivity {
+    last_delivery_ms: number;
+    last_delivery_kind: "monitor_event" | "checkin" | "start";
+    checkin_count: number;
+    last_activity_ms?: number;
+    last_checkin_attempt_ms?: number;
+}
+export interface MonitorCheckinDeps {
+    now: () => Date;
+    isWakeable: (targetKey: string) => boolean | Promise<boolean>;
+    readTargetActivityAt?: (targetKey: string) => number | null | Promise<number | null>;
+    deliver: (text: string, sequence: number) => Promise<{
+        delivered: boolean;
+        outcome: string;
+    }>;
+    pidIsAlive: (pid: number, starttime: number | null) => boolean;
+    readStarttime: (pid: number) => number | null;
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface MonitorCheckinResult {
+    sent: boolean;
+    sequence: number | null;
+    text: string | null;
+    outcome: string | null;
+}
+/** This guard is first in monitor start so a conflicting invocation has no side effects. */
+export declare function assertMonitorTimeoutCompatibility(persistent: boolean, timeoutProvided: boolean): void;
+export declare function parseMonitorDuration(value: string, kind: "timeout" | "checkin"): number;
+export declare function assertMonitorSessionId(sessionId: string): void;
+export declare function parseMonitorTarget(value: string): MonitorTarget;
+export declare function monitorTargetKey(target: MonitorTarget): string;
+export declare function detectMonitorTarget(options: DetectMonitorTargetOptions): MonitorTarget;
+/** The nearest runtime process in the caller chain, shared by target detection and hook mapping. */
+export declare function findNearestMonitorRuntime(options: {
+    parentPid: number;
+    readProcess: (pid: number) => MonitorProcessEntry | null;
+}): NearestMonitorRuntime | null;
+export declare function monitorSessionDir(hqRoot: string, provider: LaneProvider, sessionId: string): string;
+export declare function monitorSessionHasActiveMarkers(hqRoot: string, provider: LaneProvider, sessionId: string): boolean;
+export declare function monitorSessionHasActiveMarkerForOwner(hqRoot: string, provider: LaneProvider, sessionId: string, owner: MonitorRuntimeIdentity): boolean;
+export declare function monitorSessionHasInboxFile(hqRoot: string, provider: LaneProvider, sessionId: string): boolean;
+export declare function monitorSessionInboxHasEvents(hqRoot: string, provider: LaneProvider, sessionId: string): boolean;
+export declare function monitorSessionHasWork(hqRoot: string, provider: LaneProvider, sessionId: string): boolean;
+export declare function monitorDir(hqRoot: string, monitorId: string): string;
+export declare function makeMonitorId(): string;
+export declare function formatMonitorEvent(input: {
+    monitorId: string;
+    description: string;
+    sequence: number;
+    text: string;
+}): string;
+export declare function nextMonitorEventSequence(state: Pick<MonitorState, "event_sequence">): number;
+export declare function nextMonitorTimeoutDelay(timeoutMs: number, elapsedMs: number): number;
+export declare function recordMonitorEventState(state: MonitorState, event: MonitorEvent): MonitorState;
+/** Keep the supervisor alive until its command has closed so TERM escalation can run. */
+export declare function requestMonitorStop(childPid: number | null, terminate: () => void, finishWithoutChild: () => void): void;
+export declare function parseHookSessionId(payloadText: string): string;
+export declare function recordHookSessionMapping(hqRoot: string, provider: LaneProvider, environmentSessionId: string | undefined, payloadSessionId: string, runtime: MonitorRuntimeIdentity | undefined): void;
+export declare function resolveMappedSessionId(hqRoot: string, provider: LaneProvider, environmentSessionId: string, runtime: MonitorRuntimeIdentity | undefined): string;
+export declare function withMonitorTargetLock<T>(hqRoot: string, targetKey: string, operation: (activityPath: string) => Promise<T> | T, options?: {
+    now?: () => Date;
+    pidIsAlive?: (pid: number, starttime: number | null) => boolean;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<T>;
+export declare function recordMonitorTargetDelivery(hqRoot: string, targetKey: string, now?: () => Date, kind?: MonitorTargetActivity["last_delivery_kind"]): Promise<void>;
+export declare function recordMonitorTargetActivity(hqRoot: string, targetKey: string, now?: () => Date): Promise<void>;
+export declare function recordMonitorTargetDeliveryAtPath(activityPath: string, now?: () => Date, kind?: MonitorTargetActivity["last_delivery_kind"]): void;
+/** Elapsed idle time in whole units; live timers never land on exact multiples. */
+export declare function formatElapsed(ms: number): string;
+export declare function runMonitorCheckinTick(hqRoot: string, targetKey: string, deps: MonitorCheckinDeps): Promise<MonitorCheckinResult>;
+export declare function readMonitorPidLiveness(pid: number | null, starttime: number | null, readStarttime?: (pid: number) => number | null): boolean;
+//# sourceMappingURL=monitor.d.ts.map