@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/lib/monitor.d.ts

@@ -0,0 +1,149 @@
+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_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 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;
+}
+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 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 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;
+export {};
+//# sourceMappingURL=monitor.d.ts.map

package/dist/lib/monitor.js

@@ -0,0 +1,519 @@
+import { createHash, randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { formatMonitorEvent as formatDropboxMonitorEvent } from "./lanes/dropbox.js";
+import { LanesError } from "./lanes/errors.js";
+import { readProcStarttime } from "./lanes/spawn.js";
+export const MONITOR_SCHEMA_VERSION = "hq-monitor.v1";
+export const MONITOR_FLAG = "monitor.enabled";
+export const MONITOR_FLAG_DEFAULT = false;
+export const MONITOR_DEFAULT_TIMEOUT_MS = 5 * 60_000;
+export const MONITOR_DEFAULT_CHECKIN_MS = 55 * 60_000;
+const MONITOR_PROMPT_CACHE_TTL_MS = 60 * 60_000;
+export const MONITOR_BATCH_WINDOW_MS = 200;
+export const MONITOR_POLL_INTERVAL_MS = 1_000;
+export const MONITOR_RATE_WINDOW_MS = 10_000;
+/** Sustained stdout floods stop after 3 windows; the per-window cap can be overridden with HQ_MONITOR_MAX_EVENTS_PER_WINDOW. */
+export const MONITOR_MAX_EVENTS_PER_WINDOW = 60;
+export const MONITOR_MAX_FLOOD_WINDOWS = 3;
+const MONITOR_LOCK_STALE_MS = 30_000;
+const MONITOR_MAX_TIMER_DELAY_MS = 2_147_000_000;
+const SESSION_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+const SAFE_LANE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const RUNTIME_ENV = {
+    claude: "CLAUDE_CODE_SESSION_ID",
+    codex: "CODEX_THREAD_ID",
+    grok: "GROK_SESSION_ID",
+};
+const RUNTIME_COMMANDS = new Set(["claude", "codex", "grok"]);
+function monitorError(error, message, details = {}) {
+    return new LanesError(error, message, details);
+}
+/** This guard is first in monitor start so a conflicting invocation has no side effects. */
+export function assertMonitorTimeoutCompatibility(persistent, timeoutProvided) {
+    if (persistent && timeoutProvided) {
+        throw monitorError("persistent_timeout_conflict", "--persistent cannot be used with --timeout.", {});
+    }
+}
+export function parseMonitorDuration(value, kind) {
+    const errorName = kind === "timeout" ? "monitor_timeout_invalid" : "monitor_checkin_invalid";
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/i.exec(value.trim());
+    if (!match) {
+        throw monitorError(errorName, `Invalid --${kind} duration ${JSON.stringify(value)}. Use a number with optional ms, s, m, or h suffix.`, { value });
+    }
+    const amount = Number(match[1]);
+    const unit = (match[2] ?? "ms").toLowerCase();
+    const multiplier = unit === "h" ? 3_600_000 : unit === "m" ? 60_000 : unit === "s" ? 1_000 : 1;
+    const milliseconds = amount * multiplier;
+    if (!Number.isFinite(milliseconds) || milliseconds <= 0 || milliseconds > Number.MAX_SAFE_INTEGER) {
+        throw monitorError(errorName, `Invalid --${kind} duration ${JSON.stringify(value)}. Duration must be positive and finite.`, { value });
+    }
+    const rounded = Math.ceil(milliseconds);
+    if (kind === "checkin" && rounded >= MONITOR_PROMPT_CACHE_TTL_MS) {
+        throw monitorError("checkin_exceeds_cache_ttl", "--checkin must be less than 60 minutes so the prompt cache can be reused.", { checkin_ms: rounded, cache_ttl_ms: MONITOR_PROMPT_CACHE_TTL_MS });
+    }
+    return rounded;
+}
+function assertLaneTargetId(laneId) {
+    if (!SAFE_LANE_ID_RE.test(laneId) || laneId === "." || laneId === "..") {
+        throw monitorError("monitor_target_invalid", `Invalid lane target ${JSON.stringify(laneId)}.`, { lane_id: laneId });
+    }
+}
+function assertMonitorSessionId(sessionId) {
+    if (!SESSION_ID_RE.test(sessionId)) {
+        throw monitorError("monitor_session_id_invalid", "Session ids must contain only letters, numbers, underscores, or hyphens and be 1–128 characters long.", { session_id: sessionId });
+    }
+}
+export function parseMonitorTarget(value) {
+    const laneMatch = /^lane:(.+)$/.exec(value);
+    if (laneMatch?.[1]) {
+        assertLaneTargetId(laneMatch[1]);
+        return { kind: "lane", laneId: laneMatch[1] };
+    }
+    const sessionMatch = /^session:(claude|codex|grok):(.+)$/.exec(value);
+    if (sessionMatch?.[1] && sessionMatch[2]) {
+        const provider = sessionMatch[1];
+        assertMonitorSessionId(sessionMatch[2]);
+        return { kind: "session", provider, sessionId: sessionMatch[2] };
+    }
+    throw monitorError("monitor_target_invalid", "--target must be lane:<lane-id> or session:<claude|codex|grok>:<session-id>.", { target: value });
+}
+export function monitorTargetKey(target) {
+    return target.kind === "lane"
+        ? `lane:${target.laneId}`
+        : `session:${target.provider}:${target.sessionId}`;
+}
+export function detectMonitorTarget(options) {
+    const laneId = options.env.HQ_LANE_ID?.trim();
+    if (laneId) {
+        assertLaneTargetId(laneId);
+        return { kind: "lane", laneId };
+    }
+    const runtime = findNearestMonitorRuntime({
+        parentPid: options.parentPid,
+        readProcess: options.readProcess,
+    });
+    if (runtime) {
+        const provider = runtime.provider;
+        const sessionId = options.env[RUNTIME_ENV[provider]]?.trim() ?? "";
+        if (!sessionId) {
+            throw monitorError("monitor_target_unresolved", `Found ${provider} in the parent process chain but ${RUNTIME_ENV[provider]} is unset; pass --target explicitly.`, { provider, env_var: RUNTIME_ENV[provider] });
+        }
+        assertMonitorSessionId(sessionId);
+        return { kind: "session", provider, sessionId };
+    }
+    throw monitorError("monitor_target_unresolved", "Could not find a Claude, Codex, or Grok session in the parent process chain; pass --target lane:<id> or --target session:<provider>:<id>.", {});
+}
+/** The nearest runtime process in the caller chain, shared by target detection and hook mapping. */
+export function findNearestMonitorRuntime(options) {
+    let pid = options.parentPid;
+    const visited = new Set();
+    while (Number.isInteger(pid) && pid > 1 && !visited.has(pid)) {
+        visited.add(pid);
+        const entry = options.readProcess(pid);
+        if (!entry)
+            return null;
+        const command = path.basename(entry.command).replace(/\.exe$/i, "").toLowerCase();
+        if (RUNTIME_COMMANDS.has(command))
+            return { provider: command, pid };
+        pid = entry.ppid;
+    }
+    return null;
+}
+export function monitorSessionDir(hqRoot, provider, sessionId) {
+    assertMonitorSessionId(sessionId);
+    return path.join(hqRoot, "workspace", "monitors", "sessions", `${provider}-${sessionId}`);
+}
+export function monitorSessionHasActiveMarkers(hqRoot, provider, sessionId) {
+    const activeDir = path.join(monitorSessionDir(hqRoot, provider, sessionId), "active");
+    try {
+        return fs.readdirSync(activeDir).some((name) => !name.startsWith("."));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+export function monitorSessionHasActiveMarkerForOwner(hqRoot, provider, sessionId, owner) {
+    const activeDir = path.join(monitorSessionDir(hqRoot, provider, sessionId), "active");
+    let names;
+    try {
+        names = fs.readdirSync(activeDir).filter((name) => !name.startsWith("."));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+    return names.some((name) => {
+        const marker = JSON.parse(fs.readFileSync(path.join(activeDir, name), "utf8"));
+        const markerOwner = marker.owner;
+        return markerOwner !== undefined && markerOwner !== null
+            && markerOwner.pid === owner.pid
+            && markerOwner.starttime === owner.starttime;
+    });
+}
+function monitorSessionHasInboxFile(hqRoot, provider, sessionId) {
+    return fs.existsSync(path.join(monitorSessionDir(hqRoot, provider, sessionId), "dropbox", "inbox.jsonl"));
+}
+export function monitorSessionInboxHasEvents(hqRoot, provider, sessionId) {
+    const inbox = path.join(monitorSessionDir(hqRoot, provider, sessionId), "dropbox", "inbox.jsonl");
+    try {
+        return fs.readFileSync(inbox, "utf8").split(/\r?\n/).some((line) => line.trim() !== "");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+export function monitorSessionHasWork(hqRoot, provider, sessionId) {
+    return monitorSessionHasActiveMarkers(hqRoot, provider, sessionId)
+        || monitorSessionHasInboxFile(hqRoot, provider, sessionId);
+}
+export function monitorDir(hqRoot, monitorId) {
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(monitorId)) {
+        throw monitorError("monitor_id_invalid", `Invalid monitor id ${JSON.stringify(monitorId)}.`, { monitor_id: monitorId });
+    }
+    return path.join(hqRoot, "workspace", "monitors", monitorId);
+}
+export function makeMonitorId() {
+    return `mon_${Date.now().toString(36)}_${randomUUID().replaceAll("-", "")}`;
+}
+export function formatMonitorEvent(input) {
+    return formatDropboxMonitorEvent({
+        text: input.text,
+        kind: "monitor_event",
+        monitor_id: input.monitorId,
+        description: input.description,
+        sequence: input.sequence,
+    });
+}
+export function nextMonitorEventSequence(state) {
+    return (state.event_sequence ?? 0) + 1;
+}
+export function nextMonitorTimeoutDelay(timeoutMs, elapsedMs) {
+    return Math.max(0, Math.min(timeoutMs - elapsedMs, MONITOR_MAX_TIMER_DELAY_MS));
+}
+export function recordMonitorEventState(state, event) {
+    return {
+        ...state,
+        event_sequence: event.seq,
+        event_count: state.event_count + (event.delivery === "delivered" ? 1 : 0),
+    };
+}
+/** Keep the supervisor alive until its command has closed so TERM escalation can run. */
+export function requestMonitorStop(childPid, terminate, finishWithoutChild) {
+    if (childPid === null) {
+        finishWithoutChild();
+        return;
+    }
+    terminate();
+}
+export function parseHookSessionId(payloadText) {
+    let payload;
+    try {
+        payload = JSON.parse(payloadText);
+    }
+    catch (err) {
+        throw monitorError("monitor_hook_payload_invalid", `Hook payload is not valid JSON: ${err instanceof Error ? err.message : String(err)}.`, {});
+    }
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        throw monitorError("monitor_hook_payload_invalid", "Hook payload must be a JSON object with session_id.", {});
+    }
+    const sessionId = payload.session_id;
+    if (typeof sessionId !== "string") {
+        throw monitorError("monitor_hook_session_id_missing", "Hook payload has no string session_id.", {});
+    }
+    assertMonitorSessionId(sessionId);
+    return sessionId;
+}
+export function recordHookSessionMapping(hqRoot, provider, environmentSessionId, payloadSessionId, runtime) {
+    assertMonitorSessionId(payloadSessionId);
+    const environmentId = environmentSessionId?.trim();
+    if (!environmentId || environmentId === payloadSessionId || !runtime || runtime.provider !== provider)
+        return;
+    assertMonitorSessionId(environmentId);
+    const mappingPath = sessionMappingPath(hqRoot, runtime);
+    writeJsonAtomic(mappingPath, {
+        provider,
+        runtime_pid: runtime.pid,
+        runtime_starttime: runtime.starttime,
+        environment_session_id: environmentId,
+        payload_session_id: payloadSessionId,
+    });
+}
+export function resolveMappedSessionId(hqRoot, provider, environmentSessionId, runtime) {
+    assertMonitorSessionId(environmentSessionId);
+    if (!runtime || runtime.provider !== provider)
+        return environmentSessionId;
+    const mappingPath = sessionMappingPath(hqRoot, runtime);
+    try {
+        const parsed = JSON.parse(fs.readFileSync(mappingPath, "utf8"));
+        const mapped = parsed.payload_session_id;
+        if (parsed.provider === provider &&
+            parsed.runtime_pid === runtime.pid &&
+            parsed.runtime_starttime === runtime.starttime &&
+            parsed.environment_session_id === environmentSessionId &&
+            typeof mapped === "string") {
+            assertMonitorSessionId(mapped);
+            return mapped;
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw monitorError("monitor_session_map_unreadable", `Could not read session map: ${err instanceof Error ? err.message : String(err)}.`, { path: mappingPath });
+        }
+    }
+    return environmentSessionId;
+}
+function sessionMappingPath(hqRoot, runtime) {
+    return path.join(hqRoot, "workspace", "monitors", "session-map", `${runtime.provider}-${runtime.pid}-${runtime.starttime}.json`);
+}
+function writeJsonAtomic(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    try {
+        fs.renameSync(tmp, filePath);
+    }
+    catch (err) {
+        fs.rmSync(tmp, { force: true });
+        throw err;
+    }
+}
+function readJson(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw monitorError("monitor_state_unreadable", `Could not read ${filePath}: ${err instanceof Error ? err.message : String(err)}.`, { path: filePath });
+    }
+}
+function targetStorageDir(hqRoot, targetKey) {
+    const key = createHash("sha256").update(targetKey).digest("hex");
+    return path.join(hqRoot, "workspace", "monitors", "targets", key);
+}
+function defaultPidIsAlive(pid, starttime, readStarttime) {
+    try {
+        process.kill(pid, 0);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ESRCH")
+            return false;
+        if (code !== "EPERM")
+            throw err;
+    }
+    if (starttime === null)
+        return true;
+    const current = readStarttime(pid);
+    return current === null || current === starttime;
+}
+async function acquireTargetLock(lockFile, deps) {
+    fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+    const token = randomUUID();
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const owner = { token, pid: process.pid, starttime: readProcStarttime(process.pid), at: deps.now().getTime() };
+        try {
+            fs.writeFileSync(lockFile, `${JSON.stringify(owner)}\n`, { flag: "wx", mode: 0o600 });
+            return { token, pid: owner.pid, starttime: owner.starttime };
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+        }
+        const existing = readJson(lockFile);
+        if (existing && Number.isInteger(existing.pid)) {
+            const start = typeof existing.starttime === "number" ? existing.starttime : null;
+            if (deps.pidIsAlive(existing.pid, start))
+                return null;
+        }
+        else {
+            try {
+                const age = deps.now().getTime() - fs.statSync(lockFile).mtimeMs;
+                if (age < MONITOR_LOCK_STALE_MS)
+                    return null;
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    continue;
+                throw err;
+            }
+        }
+        try {
+            fs.unlinkSync(lockFile);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+    }
+    return null;
+}
+function releaseTargetLock(lockFile, token) {
+    const current = readJson(lockFile);
+    if (current?.token !== token)
+        return;
+    try {
+        fs.unlinkSync(lockFile);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+}
+export async function withMonitorTargetLock(hqRoot, targetKey, operation, options = {}) {
+    const dir = targetStorageDir(hqRoot, targetKey);
+    const activityPath = path.join(dir, "activity.json");
+    const lockFile = path.join(dir, "activity.lock");
+    const deps = {
+        now: options.now ?? (() => new Date()),
+        pidIsAlive: options.pidIsAlive ?? ((pid, starttime) => defaultPidIsAlive(pid, starttime, readProcStarttime)),
+        sleep: options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    };
+    let owner = null;
+    for (let attempt = 0; attempt < 100 && owner === null; attempt += 1) {
+        owner = await acquireTargetLock(lockFile, deps);
+        if (owner === null)
+            await deps.sleep(10);
+    }
+    if (!owner)
+        throw monitorError("monitor_target_lock_busy", `Could not acquire target delivery lock for ${targetKey}.`, { target: targetKey });
+    try {
+        return await operation(activityPath);
+    }
+    finally {
+        releaseTargetLock(lockFile, owner.token);
+    }
+}
+export async function recordMonitorTargetDelivery(hqRoot, targetKey, now = () => new Date(), kind = "monitor_event") {
+    await withMonitorTargetLock(hqRoot, targetKey, (activityPath) => {
+        recordMonitorTargetDeliveryAtPath(activityPath, now, kind);
+    }, { now });
+}
+export async function recordMonitorTargetActivity(hqRoot, targetKey, now = () => new Date()) {
+    const target = parseMonitorTarget(targetKey);
+    if (target.kind === "session" && !monitorSessionHasWork(hqRoot, target.provider, target.sessionId))
+        return;
+    await withMonitorTargetLock(hqRoot, targetKey, (activityPath) => {
+        const current = readJson(activityPath);
+        const activityAt = now().getTime();
+        writeJsonAtomic(activityPath, current
+            ? { ...current, last_activity_ms: activityAt }
+            : {
+                last_delivery_ms: activityAt,
+                last_delivery_kind: "start",
+                checkin_count: 0,
+                last_activity_ms: activityAt,
+            });
+    }, { now });
+}
+export function recordMonitorTargetDeliveryAtPath(activityPath, now = () => new Date(), kind = "monitor_event") {
+    const current = readJson(activityPath);
+    writeJsonAtomic(activityPath, {
+        last_delivery_ms: now().getTime(),
+        last_delivery_kind: kind,
+        checkin_count: current?.checkin_count ?? 0,
+        ...(current?.last_activity_ms === undefined ? {} : { last_activity_ms: current.last_activity_ms }),
+        ...(current?.last_checkin_attempt_ms === undefined ? {} : { last_checkin_attempt_ms: current.last_checkin_attempt_ms }),
+    });
+}
+function monitorIsLive(state, deps) {
+    return state?.status === "running" && state.pid !== null &&
+        deps.pidIsAlive(state.pid, state.starttime);
+}
+function activeTargetMonitors(hqRoot, targetKey, deps) {
+    const root = path.join(hqRoot, "workspace", "monitors");
+    let names;
+    try {
+        names = fs.readdirSync(root, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && entry.name !== "sessions" && entry.name !== "targets")
+            .map((entry) => entry.name);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const monitors = [];
+    for (const name of names) {
+        const dir = path.join(root, name);
+        const meta = readJson(path.join(dir, "meta.json"));
+        const state = readJson(path.join(dir, "state.json"));
+        if (meta?.target_key !== targetKey || !monitorIsLive(state, deps))
+            continue;
+        monitors.push({ meta, state });
+    }
+    return monitors;
+}
+/** Elapsed idle time in whole units; live timers never land on exact multiples. */
+export function formatElapsed(ms) {
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes >= 60) {
+        const hours = Math.floor(minutes / 60);
+        const rest = minutes % 60;
+        return rest === 0 ? `${hours}h` : `${hours}h ${rest}m`;
+    }
+    if (minutes >= 1)
+        return `${minutes}m`;
+    return `${Math.max(0, Math.floor(ms / 1_000))}s`;
+}
+function formatCheckinText(elapsedMs, monitors) {
+    const descriptions = monitors.map(({ meta }) => meta.description).join(", ");
+    return `hq monitor check-in — idle for ${formatElapsed(elapsedMs)}; ${monitors.length} monitor(s) still armed: ${descriptions}. If you are idle, confirm nothing needs action and end your turn. If you are mid-task, ignore this and continue.`;
+}
+export async function runMonitorCheckinTick(hqRoot, targetKey, deps) {
+    if (!(await deps.isWakeable(targetKey)))
+        return { sent: false, sequence: null, text: null, outcome: null };
+    return withMonitorTargetLock(hqRoot, targetKey, async (activityPath) => {
+        const monitors = activeTargetMonitors(hqRoot, targetKey, deps);
+        const eligible = monitors.filter(({ meta }) => meta.checkin_ms !== null && meta.checkin_ms > 0);
+        if (monitors.length === 0 || eligible.length === 0) {
+            return { sent: false, sequence: null, text: null, outcome: null };
+        }
+        const shortestInterval = Math.min(...eligible.map(({ meta }) => meta.checkin_ms));
+        const nowMs = deps.now().getTime();
+        const activity = readJson(activityPath);
+        const targetActivityAt = await deps.readTargetActivityAt?.(targetKey) ?? null;
+        if (!activity) {
+            writeJsonAtomic(activityPath, {
+                last_delivery_ms: targetActivityAt ?? nowMs,
+                last_delivery_kind: "start",
+                checkin_count: 0,
+                ...(targetActivityAt === null ? {} : { last_activity_ms: targetActivityAt }),
+            });
+            return { sent: false, sequence: null, text: null, outcome: null };
+        }
+        const lastActivityMs = Math.max(activity.last_delivery_ms, activity.last_activity_ms ?? Number.NEGATIVE_INFINITY, targetActivityAt ?? Number.NEGATIVE_INFINITY);
+        const elapsed = nowMs - lastActivityMs;
+        if (elapsed < shortestInterval)
+            return { sent: false, sequence: null, text: null, outcome: null };
+        if (activity.last_checkin_attempt_ms !== undefined && nowMs - activity.last_checkin_attempt_ms < shortestInterval) {
+            return { sent: false, sequence: null, text: null, outcome: null };
+        }
+        const text = formatCheckinText(elapsed, monitors);
+        const sequence = activity.checkin_count + 1;
+        const delivery = await deps.deliver(text, sequence);
+        if (!delivery.delivered) {
+            writeJsonAtomic(activityPath, { ...activity, last_checkin_attempt_ms: nowMs });
+            return { sent: false, sequence: null, text, outcome: delivery.outcome };
+        }
+        writeJsonAtomic(activityPath, {
+            last_delivery_ms: nowMs,
+            last_delivery_kind: "checkin",
+            checkin_count: sequence,
+            last_checkin_attempt_ms: nowMs,
+        });
+        return { sent: true, sequence, text, outcome: delivery.outcome };
+    }, { now: deps.now, pidIsAlive: deps.pidIsAlive, sleep: deps.sleep });
+}
+export function readMonitorPidLiveness(pid, starttime, readStarttime = readProcStarttime) {
+    if (pid === null || !Number.isInteger(pid) || pid <= 0)
+        return false;
+    return defaultPidIsAlive(pid, starttime, readStarttime);
+}
+//# sourceMappingURL=monitor.js.map