@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/commands/monitor.js

@@ -0,0 +1,980 @@
+import { spawn, spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readLanesRegistryFlag } from "../lib/lanes/registry-flag.js";
+import { resolveProcessFlagCompanyContext } from "../lib/flag-registry.js";
+import { resolveLanesHqRoot } from "../lib/lanes/hq-root.js";
+import { LanesError } from "../lib/lanes/errors.js";
+import { readToolActivity, tryReadLane } from "../lib/lanes/index.js";
+import { appendDropboxMessageAtPath, drainDropboxAtPath, formatDropboxMessages } from "../lib/lanes/dropbox.js";
+import { dispatchLaneDelivery } from "../lib/lanes/delivery-core.js";
+import { MONITOR_FLAG, MONITOR_FLAG_DEFAULT, MONITOR_DEFAULT_CHECKIN_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_POLL_INTERVAL_MS, MONITOR_BATCH_WINDOW_MS, MONITOR_MAX_EVENTS_PER_WINDOW, MONITOR_MAX_FLOOD_WINDOWS, MONITOR_RATE_WINDOW_MS, MONITOR_SCHEMA_VERSION, monitorDir, monitorSessionDir, monitorSessionHasActiveMarkerForOwner, monitorSessionHasActiveMarkers, monitorSessionHasWork, monitorSessionInboxHasEvents, monitorTargetKey, assertMonitorTimeoutCompatibility, parseMonitorDuration, parseMonitorTarget, detectMonitorTarget, findNearestMonitorRuntime, makeMonitorId, recordMonitorTargetDelivery, recordMonitorTargetActivity, recordMonitorTargetDeliveryAtPath, runMonitorCheckinTick, readMonitorPidLiveness, recordHookSessionMapping, resolveMappedSessionId, parseHookSessionId, withMonitorTargetLock, nextMonitorEventSequence, recordMonitorEventState, requestMonitorStop, nextMonitorTimeoutDelay } from "../lib/monitor.js";
+import { readProcStarttime } from "../lib/lanes/spawn.js";
+const RUNTIME_ENV = {
+    claude: "CLAUDE_CODE_SESSION_ID",
+    codex: "CODEX_THREAD_ID",
+    grok: "GROK_SESSION_ID",
+};
+function fail(error) {
+    const value = error instanceof LanesError
+        ? error.toJSON()
+        : { error: "internal", message: error instanceof Error ? error.message : String(error) };
+    process.stderr.write(`${JSON.stringify(value)}\n`);
+    process.exit(1);
+}
+function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+function readJson(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw new LanesError("monitor_state_unreadable", `Could not read ${filePath}: ${err instanceof Error ? err.message : String(err)}.`, { path: filePath });
+    }
+}
+function writeJsonAtomic(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.${process.pid}.${Date.now()}.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 statePath(hqRoot, id) {
+    return path.join(monitorDir(hqRoot, id), "state.json");
+}
+function errorPath(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function writeStderr(text) {
+    process.stderr.write(text);
+}
+function waitSleep(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function procEntry(pid) {
+    try {
+        const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf8");
+        const close = stat.lastIndexOf(")");
+        const fields = stat.slice(close + 2).split(/\s+/);
+        const ppid = Number(fields[1]);
+        const commandLine = fs.readFileSync(`/proc/${pid}/cmdline`, "utf8").split("\0").filter(Boolean);
+        const command = commandLine[0] ?? fs.readFileSync(`/proc/${pid}/comm`, "utf8").trim();
+        if (!Number.isInteger(ppid) || !command)
+            return null;
+        return { pid, ppid, command };
+    }
+    catch (err) {
+        if (err.code === "ENOENT" || err.code === "ESRCH")
+            return null;
+        throw err;
+    }
+}
+export function findSessionOwner(target, deps = {}) {
+    if (target.kind !== "session")
+        return null;
+    const env = deps.env ?? process.env;
+    let pid = deps.parentPid ?? process.ppid;
+    const readProcess = deps.readProcess ?? procEntry;
+    const readStarttime = deps.readStarttime ?? readProcStarttime;
+    const seen = new Set();
+    while (pid > 1 && !seen.has(pid)) {
+        seen.add(pid);
+        const entry = readProcess(pid);
+        if (!entry)
+            return null;
+        const command = path.basename(entry.command).replace(/\.exe$/i, "").toLowerCase();
+        if (command === target.provider && env[RUNTIME_ENV[target.provider]]?.trim() === target.sessionId) {
+            return { pid, starttime: readStarttime(pid) };
+        }
+        pid = entry.ppid;
+    }
+    return null;
+}
+export function sessionOwnerTarget(discovered, resolved) {
+    return discovered.kind === "session" ? discovered : resolved;
+}
+function processCompanyRef() {
+    const context = resolveProcessFlagCompanyContext();
+    if (!context.companyUid && !context.companySlug)
+        return null;
+    return { uid: context.companyUid ?? "", slug: context.companySlug ?? "" };
+}
+async function monitorEnabled(company = processCompanyRef()) {
+    return readLanesRegistryFlag(MONITOR_FLAG, {
+        company,
+    });
+}
+export async function runMonitorEnabledCommand(deps = {}) {
+    let enabled = false;
+    try {
+        enabled = await (deps.readFlag ?? ((company) => monitorEnabled(company)))(processCompanyRef());
+    }
+    catch (error) {
+        const name = error instanceof Error ? error.name : "UnknownError";
+        (deps.writeError ?? ((text) => process.stderr.write(text)))(`${JSON.stringify({
+            event: "monitor.enabled.flag_read_failed",
+            flag: MONITOR_FLAG,
+            error: name,
+            fallback: false,
+        })}\n`);
+    }
+    (deps.writeOut ?? ((text) => process.stdout.write(text)))(`${enabled ? "true" : "false"}\n`);
+    return enabled ? 0 : 1;
+}
+function ensureEnabled(company) {
+    return monitorEnabled(company).then((enabled) => {
+        if (!enabled)
+            throw new LanesError("monitor_disabled", "hq monitor is disabled by the monitor.enabled feature flag.", { flag: MONITOR_FLAG, default: MONITOR_FLAG_DEFAULT });
+    });
+}
+function targetWakeDescription(target) {
+    if (target.kind === "lane")
+        return "lane dropbox while running; lane resume when done or blocked with a recorded provider session";
+    if (target.provider === "claude")
+        return "Claude session inbox on the next tool call or user message, and the async Stop waiter while idle";
+    // Grok discards UserPromptSubmit hook output, so its events arrive only on a tool call.
+    if (target.provider === "grok")
+        return "grok session inbox on the next tool call; idle wake is not available";
+    return `${target.provider} session inbox on the next tool call or user message; idle wake is not available`;
+}
+export function armText(meta) {
+    const lifetime = meta.persistent
+        ? `persistent: runs until \`hq monitor stop ${meta.monitor_id}\`, the script exits, or the target ends`
+        : `expires in ${formatDuration(meta.timeout_ms ?? MONITOR_DEFAULT_TIMEOUT_MS)} unless the command exits first`;
+    const cache = meta.persistent || (meta.timeout_ms ?? 0) > 60 * 60_000
+        ? meta.checkin_ms === null
+            ? "\nPrompt caching only works within an hour. With check-ins off, the next turn may read uncached."
+            : `\nPrompt caching only works within an hour. hq monitor checks in every ${formatDuration(meta.checkin_ms)} while you are idle so your next turn reads from cache; keep check-in turns short.`
+        : "";
+    return `Monitor started (task ${meta.monitor_id}, ${lifetime}). You will be notified on each event. Target wake path: ${targetWakeDescription(meta.target)}.${cache}\nKeep working — do not poll or sleep. Events may arrive while you are waiting for the user — an event is not their reply.`;
+}
+function formatDuration(milliseconds) {
+    if (milliseconds % 3_600_000 === 0)
+        return `${milliseconds / 3_600_000}h`;
+    if (milliseconds % 60_000 === 0)
+        return `${milliseconds / 60_000}m`;
+    if (milliseconds % 1_000 === 0)
+        return `${milliseconds / 1_000}s`;
+    return `${milliseconds}ms`;
+}
+function monitorTimeout(timeoutMs, onTimeout) {
+    const startedAt = performance.now();
+    let timer = null;
+    let cancelled = false;
+    const schedule = () => {
+        if (cancelled)
+            return;
+        const elapsedMs = performance.now() - startedAt;
+        const delayMs = nextMonitorTimeoutDelay(timeoutMs, elapsedMs);
+        if (delayMs <= 0) {
+            onTimeout();
+            return;
+        }
+        timer = setTimeout(schedule, delayMs);
+    };
+    schedule();
+    return {
+        clear: () => {
+            cancelled = true;
+            if (timer)
+                clearTimeout(timer);
+        },
+    };
+}
+function sessionEnvironmentId(provider) {
+    return process.env[RUNTIME_ENV[provider]]?.trim() || undefined;
+}
+function nearestRuntimeIdentityInProcessChain() {
+    const nearest = findNearestMonitorRuntime({ parentPid: process.ppid, readProcess: procEntry });
+    if (!nearest)
+        return undefined;
+    const starttime = readProcStarttime(nearest.pid);
+    return starttime === null ? undefined : { ...nearest, starttime };
+}
+export function resolveMonitorStartTarget(hqRoot, discovered, explicitlyProvided, runtime) {
+    if (explicitlyProvided || discovered.kind !== "session" || discovered.provider !== "codex")
+        return discovered;
+    return { ...discovered, sessionId: resolveMappedSessionId(hqRoot, discovered.provider, discovered.sessionId, runtime) };
+}
+async function startMonitor(options, argv = []) {
+    // Keep this ahead of flag reads, target detection and every filesystem write.
+    assertMonitorTimeoutCompatibility(options.persistent === true, options.timeout !== undefined);
+    if (!options.description?.trim())
+        throw new LanesError("monitor_description_required", "--description must be non-empty.", {});
+    const timeoutMs = options.persistent
+        ? null
+        : options.timeout === undefined
+            ? MONITOR_DEFAULT_TIMEOUT_MS
+            : parseMonitorDuration(options.timeout, "timeout");
+    const checkinMs = options.checkin?.trim().toLowerCase() === "off"
+        ? null
+        : options.checkin === undefined
+            ? MONITOR_DEFAULT_CHECKIN_MS
+            : parseMonitorDuration(options.checkin, "checkin");
+    if (Boolean(options.command?.trim()) === (argv.length > 0)) {
+        throw new LanesError("monitor_command_required", "Provide exactly one of --command or argv after --.", {});
+    }
+    const env = process.env;
+    const hqRoot = resolveLanesHqRoot({ env, cwd: process.cwd() });
+    const discovered = options.target
+        ? parseMonitorTarget(options.target)
+        : detectMonitorTarget({ env, parentPid: process.ppid, readProcess: procEntry });
+    const runtime = options.target === undefined ? nearestRuntimeIdentityInProcessChain() : undefined;
+    const target = resolveMonitorStartTarget(hqRoot, discovered, options.target !== undefined, runtime);
+    const targetLane = target.kind === "lane" ? tryReadLane(hqRoot, target.laneId) : null;
+    if (target.kind === "lane" && !targetLane) {
+        throw new LanesError("monitor_lane_not_found", `Lane ${target.laneId} was not found.`, { lane_id: target.laneId });
+    }
+    const company = target.kind === "lane" ? targetLane?.company ?? null : processCompanyRef();
+    await ensureEnabled(company);
+    const cliEntrypoint = process.argv[1];
+    if (!cliEntrypoint)
+        throw new LanesError("monitor_cli_path_missing", "Could not locate the hq CLI entry point for the detached supervisor.", {});
+    const id = makeMonitorId();
+    const dir = monitorDir(hqRoot, id);
+    const meta = {
+        schema_version: MONITOR_SCHEMA_VERSION,
+        monitor_id: id,
+        target,
+        target_key: monitorTargetKey(target),
+        company,
+        description: options.description.trim(),
+        command: options.command?.trim() || null,
+        argv: argv.length ? argv : null,
+        cwd: process.cwd(),
+        created_at: new Date().toISOString(),
+        timeout_ms: timeoutMs,
+        persistent: options.persistent === true,
+        checkin_ms: checkinMs,
+        session_owner: findSessionOwner(sessionOwnerTarget(discovered, target)),
+    };
+    fs.mkdirSync(path.dirname(dir), { recursive: true, mode: 0o700 });
+    fs.mkdirSync(dir, { recursive: false, mode: 0o700 });
+    fs.writeFileSync(path.join(dir, "meta.json"), `${JSON.stringify(meta, null, 2)}\n`, { mode: 0o600 });
+    fs.writeFileSync(path.join(dir, "events.jsonl"), "", { mode: 0o600 });
+    fs.writeFileSync(path.join(dir, "stderr.log"), "", { mode: 0o600 });
+    writeJsonAtomic(statePath(hqRoot, id), {
+        status: "starting",
+        pid: null,
+        starttime: null,
+        event_count: 0,
+        event_sequence: 0,
+    });
+    if (target.kind === "session") {
+        const activeDir = path.join(monitorSessionDir(hqRoot, target.provider, target.sessionId), "active");
+        fs.mkdirSync(activeDir, { recursive: true });
+        fs.writeFileSync(path.join(activeDir, id), `${JSON.stringify({ monitor_id: id, owner: meta.session_owner })}\n`, { mode: 0o600 });
+    }
+    await recordMonitorTargetDelivery(hqRoot, meta.target_key, () => new Date(), "start");
+    const child = spawn(process.execPath, [cliEntrypoint, "monitor", "_run", id], {
+        cwd: meta.cwd,
+        env: { ...env, HQ_ROOT: hqRoot },
+        detached: true,
+        windowsHide: true,
+        stdio: "ignore",
+    });
+    child.once("error", (err) => {
+        const current = readJson(statePath(hqRoot, id));
+        if (current)
+            writeJsonAtomic(statePath(hqRoot, id), { ...current, status: "terminal", finished_at: new Date().toISOString(), terminal_reason: "supervisor_spawn_failed" });
+        if (meta.target.kind === "session")
+            fs.rmSync(path.join(monitorSessionDir(hqRoot, meta.target.provider, meta.target.sessionId), "active", id), { force: true });
+        process.stderr.write(`hq monitor: supervisor spawn failed: ${err.message}\n`);
+    });
+    child.unref();
+    if (!child.pid)
+        throw new LanesError("monitor_supervisor_spawn_failed", "The detached monitor supervisor did not start.", {});
+    const running = {
+        status: "running",
+        pid: child.pid,
+        starttime: readProcStarttime(child.pid),
+        started_at: new Date().toISOString(),
+        event_count: 0,
+    };
+    const latest = readJson(statePath(hqRoot, id));
+    writeJsonAtomic(statePath(hqRoot, id), latest?.pid === child.pid ? latest : running);
+    if (options.json)
+        printJson({ ok: true, monitor_id: id, target, state: running, message: armText(meta) });
+    else
+        process.stdout.write(`${armText(meta)}\n`);
+}
+function monitorIds(hqRoot) {
+    const root = path.join(hqRoot, "workspace", "monitors");
+    try {
+        return fs.readdirSync(root, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && !["sessions", "targets", "session-map"].includes(entry.name))
+            .map((entry) => entry.name);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+}
+function stateForDisplay(hqRoot, id, raw) {
+    if (!raw || raw.status === "terminal" || raw.pid === null)
+        return raw;
+    if (readMonitorPidLiveness(raw.pid, raw.starttime))
+        return raw;
+    return { ...raw, status: "terminal", terminal_reason: "supervisor_died", finished_at: raw.finished_at ?? new Date().toISOString() };
+}
+async function listMonitors(options) {
+    const hqRoot = resolveLanesHqRoot();
+    const rows = monitorIds(hqRoot).flatMap((id) => {
+        const meta = readJson(path.join(monitorDir(hqRoot, id), "meta.json"));
+        const state = stateForDisplay(hqRoot, id, readJson(statePath(hqRoot, id)));
+        if (!meta || !state || (!options.all && state.status !== "running"))
+            return [];
+        return [{ monitor_id: id, description: meta.description, target: meta.target, state }];
+    });
+    if (options.json)
+        printJson({ monitors: rows });
+    else
+        for (const row of rows)
+            process.stdout.write(`${row.monitor_id}\t${row.state.status}\t${row.description}\t${monitorTargetKey(row.target)}${row.state.terminal_reason ? `\t${row.state.terminal_reason}` : ""}\n`);
+}
+async function showMonitor(id, json) {
+    const hqRoot = resolveLanesHqRoot();
+    const dir = monitorDir(hqRoot, id);
+    const meta = readJson(path.join(dir, "meta.json"));
+    const state = stateForDisplay(hqRoot, id, readJson(statePath(hqRoot, id)));
+    if (!meta || !state)
+        throw new LanesError("monitor_not_found", `Monitor ${id} was not found.`, { monitor_id: id });
+    const events = [];
+    for (const line of fs.readFileSync(path.join(dir, "events.jsonl"), "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+            continue;
+        events.push(parsed);
+    }
+    if (json)
+        printJson({ meta, state, events });
+    else
+        process.stdout.write(`${JSON.stringify({ meta, state, events }, null, 2)}\n`);
+}
+async function stopMonitor(id) {
+    const hqRoot = resolveLanesHqRoot();
+    const dir = monitorDir(hqRoot, id);
+    const meta = readJson(path.join(dir, "meta.json"));
+    const state = readJson(statePath(hqRoot, id));
+    if (!meta || !state)
+        throw new LanesError("monitor_not_found", `Monitor ${id} was not found.`, { monitor_id: id });
+    if (state.status !== "terminal" && state.pid !== null && readMonitorPidLiveness(state.pid, state.starttime)) {
+        try {
+            process.kill(state.pid, "SIGTERM");
+        }
+        catch (err) {
+            if (err.code !== "ESRCH")
+                throw err;
+        }
+    }
+    else if (state.status !== "terminal") {
+        writeJsonAtomic(statePath(hqRoot, id), { ...state, status: "terminal", terminal_reason: "supervisor_died", finished_at: new Date().toISOString() });
+        removeActiveMarker(hqRoot, meta);
+    }
+    const deadline = Date.now() + 5_000;
+    let current = readJson(statePath(hqRoot, id));
+    while (current && current.status !== "terminal" && Date.now() < deadline) {
+        await waitSleep(50);
+        current = readJson(statePath(hqRoot, id));
+    }
+    if (current?.status !== "terminal") {
+        throw new LanesError("monitor_stop_timeout", `Monitor ${id} did not record its stopped state within five seconds.`, { monitor_id: id });
+    }
+    process.stdout.write(`Monitor ${id} stopped.\n`);
+}
+async function monitorLogs(id, stderr) {
+    const hqRoot = resolveLanesHqRoot();
+    const filePath = path.join(monitorDir(hqRoot, id), stderr ? "stderr.log" : "events.jsonl");
+    if (!fs.existsSync(filePath))
+        throw new LanesError("monitor_not_found", `Monitor ${id} was not found.`, { monitor_id: id });
+    process.stdout.write(fs.readFileSync(filePath, "utf8"));
+}
+function appendEventRecord(hqRoot, id, state, event) {
+    const dir = monitorDir(hqRoot, id);
+    fs.appendFileSync(path.join(dir, "events.jsonl"), `${JSON.stringify(event)}\n`, { mode: 0o600 });
+    const next = recordMonitorEventState(state, event);
+    writeJsonAtomic(statePath(hqRoot, id), next);
+    return next;
+}
+function removeActiveMarker(hqRoot, meta) {
+    if (meta.target.kind !== "session")
+        return;
+    fs.rmSync(path.join(monitorSessionDir(hqRoot, meta.target.provider, meta.target.sessionId), "active", meta.monitor_id), { force: true });
+}
+async function deliverLaneEvent(hqRoot, meta, sequence, text) {
+    if (meta.target.kind !== "lane")
+        throw new LanesError("monitor_lane_target_required", "Lane delivery requires a lane target.");
+    const lane = tryReadLane(hqRoot, meta.target.laneId);
+    if (!lane)
+        return { delivered: false, outcome: "lane_not_found" };
+    let dispatched;
+    try {
+        dispatched = await dispatchLaneDelivery(lane, {
+            dropbox: () => invokeLaneMonitorMessage(hqRoot, meta, sequence, text),
+            resume: () => invokeLaneMonitorMessage(hqRoot, meta, sequence, text),
+        });
+    }
+    catch (err) {
+        if (err instanceof LanesError && err.error === "lane_not_accepting_messages")
+            return { delivered: false, outcome: `undeliverable:${err.message}` };
+        throw err;
+    }
+    return { ...dispatched.value, outcome: `${dispatched.mechanism}:${dispatched.value.outcome}` };
+}
+function invokeLaneMonitorMessage(hqRoot, meta, sequence, text) {
+    if (meta.target.kind !== "lane")
+        throw new LanesError("monitor_lane_target_required", "Lane delivery requires a lane target.");
+    const cliEntrypoint = process.argv[1];
+    if (!cliEntrypoint)
+        throw new LanesError("monitor_cli_path_missing", "Could not locate the hq CLI entry point for lane delivery.");
+    const result = spawnSync(process.execPath, [cliEntrypoint, "lanes", "_monitor-message", meta.target.laneId], {
+        cwd: meta.cwd,
+        env: { ...process.env, HQ_ROOT: hqRoot },
+        input: JSON.stringify({ text, monitor_id: meta.monitor_id, description: meta.description, sequence }),
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0) {
+        let error = `lane_delivery_exit_${result.status ?? "unknown"}`;
+        try {
+            const parsed = JSON.parse(result.stdout.trim());
+            if (typeof parsed.error === "string")
+                error = parsed.error;
+        }
+        catch (err) {
+            if (!(err instanceof SyntaxError))
+                throw err;
+        }
+        return { delivered: false, outcome: error };
+    }
+    try {
+        const output = JSON.parse(result.stdout.trim());
+        return { delivered: output.accepted === true, outcome: String(output.delivery_status ?? output.delivery ?? "accepted") };
+    }
+    catch (err) {
+        throw new LanesError("monitor_lane_delivery_invalid_response", `The lane delivery command returned invalid JSON: ${errorPath(err)}.`, {});
+    }
+}
+function deliverSessionEvent(hqRoot, meta, sequence, text) {
+    if (meta.target.kind !== "session")
+        throw new LanesError("monitor_session_target_required", "Session delivery requires a session target.");
+    const box = path.join(monitorSessionDir(hqRoot, meta.target.provider, meta.target.sessionId), "dropbox");
+    appendDropboxMessageAtPath(box, {
+        at: new Date().toISOString(),
+        kind: "monitor_event",
+        monitor_id: meta.monitor_id,
+        description: meta.description,
+        sequence,
+        text,
+    });
+    return { delivered: true, outcome: "session_inbox" };
+}
+async function deliverTargetEvent(hqRoot, meta, sequence, text) {
+    return meta.target.kind === "lane"
+        ? deliverLaneEvent(hqRoot, meta, sequence, text)
+        : deliverSessionEvent(hqRoot, meta, sequence, text);
+}
+export async function deliverNormalEvent(hqRoot, meta, state, rawText) {
+    return withMonitorTargetLock(hqRoot, meta.target_key, async (activityPath) => {
+        const current = readJson(statePath(hqRoot, meta.monitor_id)) ?? state;
+        const sequence = nextMonitorEventSequence(current);
+        const outcome = await deliverTargetEvent(hqRoot, meta, sequence, rawText);
+        const event = { seq: sequence, at: new Date().toISOString(), text: rawText, delivery: outcome.delivered ? "delivered" : `undeliverable:${outcome.outcome}` };
+        const next = appendEventRecord(hqRoot, meta.monitor_id, current, event);
+        if (outcome.delivered)
+            recordMonitorTargetDeliveryAtPath(activityPath);
+        return next;
+    });
+}
+function targetEnded(hqRoot, meta) {
+    if (meta.target.kind === "session") {
+        return meta.session_owner !== null && !readMonitorPidLiveness(meta.session_owner.pid, meta.session_owner.starttime);
+    }
+    const lane = tryReadLane(hqRoot, meta.target.laneId);
+    return !lane || ["killed", "cancelled", "failed"].includes(lane.state);
+}
+async function monitorCheckin(hqRoot, meta, state) {
+    await runMonitorCheckinTick(hqRoot, meta.target_key, {
+        now: () => new Date(),
+        isWakeable: async (targetKey) => {
+            const monitor = activeTargetMeta(hqRoot, targetKey)[0];
+            if (!monitor)
+                return false;
+            if (monitor.target.kind === "session")
+                return monitor.target.provider === "claude";
+            const lane = tryReadLane(hqRoot, monitor.target.laneId);
+            return lane !== null && (lane.state === "running" ||
+                ((lane.state === "done" || lane.state === "blocked") && Boolean(lane.provider_session_id)));
+        },
+        readTargetActivityAt: (targetKey) => {
+            if (meta.target.kind !== "lane" || targetKey !== meta.target_key)
+                return null;
+            const activityAt = readToolActivity(hqRoot, meta.target.laneId)?.at;
+            if (!activityAt)
+                return null;
+            const parsed = Date.parse(activityAt);
+            return Number.isFinite(parsed) ? parsed : null;
+        },
+        deliver: async (text) => {
+            const monitor = activeTargetMeta(hqRoot, meta.target_key)[0];
+            if (!monitor)
+                return { delivered: false, outcome: "no_live_monitor" };
+            const monitorState = readJson(statePath(hqRoot, monitor.monitor_id)) ?? state;
+            const sequence = nextMonitorEventSequence(monitorState);
+            const outcome = await deliverTargetEvent(hqRoot, monitor, sequence, text);
+            const event = { seq: sequence, at: new Date().toISOString(), text, delivery: outcome.delivered ? "delivered" : `undeliverable:${outcome.outcome}` };
+            appendEventRecord(hqRoot, monitor.monitor_id, monitorState, event);
+            return outcome;
+        },
+        pidIsAlive: readMonitorPidLiveness,
+        readStarttime: readProcStarttime,
+    });
+    return readJson(statePath(hqRoot, meta.monitor_id)) ?? state;
+}
+function activeTargetMeta(hqRoot, targetKey) {
+    return monitorIds(hqRoot).flatMap((id) => {
+        const meta = readJson(path.join(monitorDir(hqRoot, id), "meta.json"));
+        const state = readJson(statePath(hqRoot, id));
+        return meta?.target_key === targetKey && state?.status === "running" && state.pid !== null && readMonitorPidLiveness(state.pid, state.starttime) ? [meta] : [];
+    });
+}
+export async function runSupervisor(id, deps = {}) {
+    const hqRoot = (deps.resolveRoot ?? resolveLanesHqRoot)();
+    const dir = monitorDir(hqRoot, id);
+    const meta = readJson(path.join(dir, "meta.json"));
+    const stateAtStart = readJson(statePath(hqRoot, id));
+    if (!meta || !stateAtStart)
+        throw new LanesError("monitor_not_found", `Monitor ${id} was not found.`, { monitor_id: id });
+    if (!(await (deps.monitorEnabled ?? monitorEnabled)(meta.company))) {
+        writeJsonAtomic(statePath(hqRoot, id), { ...stateAtStart, status: "terminal", finished_at: new Date().toISOString(), terminal_reason: "monitor_disabled" });
+        removeActiveMarker(hqRoot, meta);
+        return;
+    }
+    let state = { ...stateAtStart, status: "running", pid: process.pid, starttime: readProcStarttime(process.pid), started_at: new Date().toISOString() };
+    writeJsonAtomic(statePath(hqRoot, id), state);
+    let commandChild = null;
+    let finished = false;
+    let finishing = false;
+    let terminalReason = null;
+    let timeoutTimer = null;
+    let pollTimer = null;
+    let batchTimer = null;
+    let killEscalationTimer = null;
+    let buffered = "";
+    let batchLines = [];
+    let deliveryQueue = Promise.resolve();
+    let windowStartedAt = Date.now();
+    let windowEvents = 0;
+    let suppressed = 0;
+    let floodWindows = 0;
+    let checkinRunning = false;
+    const deliver = deps.deliver ?? deliverNormalEvent;
+    const perWindowCap = (() => {
+        const candidate = Number.parseInt(process.env.HQ_MONITOR_MAX_EVENTS_PER_WINDOW ?? "", 10);
+        return Number.isInteger(candidate) && candidate > 0 ? candidate : MONITOR_MAX_EVENTS_PER_WINDOW;
+    })();
+    const writeStderr = (chunk) => fs.appendFileSync(path.join(dir, "stderr.log"), chunk);
+    const killCommand = () => {
+        if (!commandChild?.pid)
+            return;
+        try {
+            process.kill(-commandChild.pid, "SIGTERM");
+        }
+        catch (err) {
+            if (err.code !== "ESRCH")
+                throw err;
+        }
+        if (!killEscalationTimer) {
+            killEscalationTimer = setTimeout(() => {
+                if (!commandChild?.pid)
+                    return;
+                try {
+                    process.kill(-commandChild.pid, "SIGKILL");
+                }
+                catch (err) {
+                    if (err.code !== "ESRCH")
+                        writeStderr(`command kill escalation failed: ${errorPath(err)}\n`);
+                }
+            }, 1_500);
+        }
+    };
+    const flushBatch = () => {
+        if (batchTimer)
+            clearTimeout(batchTimer);
+        batchTimer = null;
+        const batch = batchLines.splice(0, batchLines.length);
+        batchLines = [];
+        if (batch.length === 0 || finished)
+            return deliveryQueue;
+        deliveryQueue = deliveryQueue.then(async () => {
+            const now = Date.now();
+            if (now - windowStartedAt >= MONITOR_RATE_WINDOW_MS) {
+                const windowsPassed = Math.floor((now - windowStartedAt) / MONITOR_RATE_WINDOW_MS);
+                if (suppressed > 0) {
+                    state = await deliver(hqRoot, meta, state, `[monitor ${id} suppressed ${suppressed} events — output rate exceeded]`);
+                    floodWindows += 1;
+                    suppressed = 0;
+                }
+                else {
+                    floodWindows = 0;
+                }
+                windowStartedAt += windowsPassed * MONITOR_RATE_WINDOW_MS;
+                windowEvents = 0;
+                if (floodWindows >= MONITOR_MAX_FLOOD_WINDOWS) {
+                    terminalReason = "rate_exceeded";
+                    killCommand();
+                }
+            }
+            const remaining = Math.max(0, perWindowCap - windowEvents);
+            const permitted = batch.slice(0, remaining);
+            suppressed += batch.length - permitted.length;
+            windowEvents += permitted.length;
+            if (permitted.length > 0)
+                state = await deliver(hqRoot, meta, state, permitted.join("\n"));
+            if (floodWindows >= MONITOR_MAX_FLOOD_WINDOWS) {
+                terminalReason = "rate_exceeded";
+                killCommand();
+            }
+        }).catch((err) => {
+            writeStderr(`event delivery failed: ${errorPath(err)}\n`);
+        });
+        return deliveryQueue;
+    };
+    const finish = async (exitCode) => {
+        if (finished || finishing)
+            return;
+        finishing = true;
+        timeoutTimer?.clear();
+        if (pollTimer)
+            clearInterval(pollTimer);
+        if (batchTimer)
+            clearTimeout(batchTimer);
+        if (killEscalationTimer)
+            clearTimeout(killEscalationTimer);
+        if (buffered.length > 0)
+            batchLines.push(buffered);
+        buffered = "";
+        if (batchLines.length > 0)
+            flushBatch();
+        await deliveryQueue;
+        finished = true;
+        const reason = terminalReason ?? (exitCode === null ? "supervisor_died" : "script_exit");
+        const priorEvents = state.event_count;
+        if (reason !== "stopped" && reason !== "target_ended" && reason !== "supervisor_died") {
+            const terminalText = reason === "expired"
+                ? `[hq monitor ${id} expired after ${formatDuration(meta.timeout_ms ?? MONITOR_DEFAULT_TIMEOUT_MS)} with ${priorEvents} events delivered. Re-arm with \`hq monitor start ...\` if you still need the watch — and widen the filter if silence was unexpected.]`
+                : reason === "rate_exceeded"
+                    ? `[hq monitor ${id} stopped: rate_exceeded after suppressing sustained output.]`
+                    : `[hq monitor ${id} ${JSON.stringify(meta.description)} exited with code ${exitCode ?? 1} after ${priorEvents} events]`;
+            try {
+                state = await deliver(hqRoot, meta, state, terminalText);
+            }
+            catch (err) {
+                writeStderr(`terminal event delivery failed: ${errorPath(err)}\n`);
+            }
+        }
+        state = { ...state, status: "terminal", finished_at: new Date().toISOString(), exit_code: exitCode, terminal_reason: reason };
+        writeJsonAtomic(statePath(hqRoot, id), state);
+        removeActiveMarker(hqRoot, meta);
+    };
+    const stop = () => {
+        terminalReason = "stopped";
+        requestMonitorStop(commandChild?.pid ?? null, killCommand, () => {
+            void finish(null).catch((err) => { writeStderr(`supervisor shutdown failed: ${errorPath(err)}\n`); process.exitCode = 1; });
+        });
+    };
+    process.on("SIGTERM", stop);
+    process.on("SIGINT", stop);
+    pollTimer = setInterval(() => {
+        if (targetEnded(hqRoot, meta)) {
+            terminalReason = "target_ended";
+            killCommand();
+        }
+        if (!checkinRunning) {
+            checkinRunning = true;
+            void monitorCheckin(hqRoot, meta, state)
+                .then((next) => { state = next; })
+                .catch((err) => writeStderr(`check-in failed: ${errorPath(err)}\n`))
+                .finally(() => { checkinRunning = false; });
+        }
+    }, MONITOR_POLL_INTERVAL_MS);
+    if (meta.timeout_ms !== null)
+        timeoutTimer = monitorTimeout(meta.timeout_ms, () => {
+            terminalReason = "expired";
+            killCommand();
+        });
+    const childArgs = meta.command !== null ? ["-c", meta.command] : (meta.argv ?? []);
+    const executable = meta.command !== null ? "bash" : childArgs[0];
+    const args = meta.command !== null ? childArgs : childArgs.slice(1);
+    if (!executable)
+        throw new LanesError("monitor_command_required", "No command was recorded for this monitor.");
+    commandChild = (deps.spawn ?? spawn)(executable, args, { cwd: meta.cwd, env: process.env, detached: true, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+    if (commandChild.pid) {
+        state = { ...state, child_pid: commandChild.pid, child_starttime: readProcStarttime(commandChild.pid) };
+        writeJsonAtomic(statePath(hqRoot, id), state);
+    }
+    commandChild.stdout?.on("data", (chunk) => {
+        buffered += chunk.toString("utf8");
+        const lines = buffered.split(/\r?\n/);
+        buffered = lines.pop() ?? "";
+        batchLines.push(...lines.filter((line) => line.length > 0));
+        if (batchLines.length > 0 && !batchTimer)
+            batchTimer = setTimeout(() => { void flushBatch().catch((err) => writeStderr(`event delivery failed: ${errorPath(err)}\n`)); }, MONITOR_BATCH_WINDOW_MS);
+    });
+    commandChild.stderr?.on("data", writeStderr);
+    commandChild.once("error", (err) => {
+        writeStderr(`command start failed: ${err.message}\n`);
+        void finish(127).catch((cause) => { writeStderr(`supervisor finish failed: ${errorPath(cause)}\n`); process.exitCode = 1; });
+    });
+    commandChild.once("close", (code) => {
+        void finish(code).catch((err) => { writeStderr(`supervisor finish failed: ${errorPath(err)}\n`); process.exitCode = 1; });
+    });
+    await new Promise((resolve) => {
+        const done = setInterval(() => {
+            if (finished) {
+                clearInterval(done);
+                resolve();
+            }
+        }, 50);
+        done.unref();
+    });
+    process.off("SIGTERM", stop);
+    process.off("SIGINT", stop);
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function runMonitorHookSafely(kind, operation, writeError = writeStderr) {
+    try {
+        return await operation();
+    }
+    catch (err) {
+        writeError(`hq monitor ${kind}: ${errorPath(err)}\n`);
+        return { stdout: "", exitCode: 0 };
+    }
+}
+export async function drainSession(provider, event, deps = {}) {
+    if (!(await (deps.monitorEnabled ?? (() => monitorEnabled()))()))
+        return { stdout: "", exitCode: 0 };
+    const hqRoot = (deps.resolveRoot ?? resolveLanesHqRoot)();
+    const payloadId = parseHookSessionId(await (deps.readStdin ?? readStdin)());
+    const envId = (deps.sessionEnvironmentId ?? sessionEnvironmentId)(provider);
+    const runtime = (deps.nearestRuntimeIdentity ?? nearestRuntimeIdentityInProcessChain)();
+    const codexRuntimeOwnsMapping = provider === "codex" && envId !== undefined && runtime?.provider === "codex";
+    const payloadHasWork = monitorSessionHasWork(hqRoot, provider, payloadId);
+    const sessionIds = new Set();
+    if (payloadHasWork)
+        sessionIds.add(payloadId);
+    if (codexRuntimeOwnsMapping && envId !== payloadId && runtime) {
+        const mappedSessionId = resolveMappedSessionId(hqRoot, provider, envId, runtime);
+        const ownsRuntimeTarget = monitorSessionHasActiveMarkerForOwner(hqRoot, provider, envId, runtime);
+        if (ownsRuntimeTarget || mappedSessionId === payloadId) {
+            if (monitorSessionHasWork(hqRoot, provider, envId))
+                sessionIds.add(envId);
+        }
+    }
+    if (sessionIds.size === 0)
+        return { stdout: "", exitCode: 0 };
+    if (codexRuntimeOwnsMapping && envId && runtime?.provider === "codex" && payloadId !== envId
+        && (payloadHasWork || sessionIds.has(envId))) {
+        recordHookSessionMapping(hqRoot, provider, envId, payloadId, runtime);
+    }
+    const messages = [];
+    for (const sessionId of sessionIds) {
+        const targetKey = monitorTargetKey({ kind: "session", provider, sessionId });
+        await (deps.recordActivity ?? recordMonitorTargetActivity)(hqRoot, targetKey);
+        const box = path.join(monitorSessionDir(hqRoot, provider, sessionId), "dropbox");
+        messages.push(...(deps.drainDropbox ?? drainDropboxAtPath)(box));
+    }
+    messages.sort((left, right) => (left.at ?? "").localeCompare(right.at ?? ""));
+    const stdout = messages.length > 0
+        ? `${JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: formatDropboxMessages(messages) } })}\n`
+        : "";
+    return { stdout, exitCode: 0 };
+}
+function sessionMonitorIds(hqRoot, provider, sessionId) {
+    const activeDir = path.join(monitorSessionDir(hqRoot, provider, sessionId), "active");
+    try {
+        return fs.readdirSync(activeDir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+}
+function waiterIsCurrent(waiterPath, token) {
+    const current = readJson(waiterPath);
+    return current?.token === token;
+}
+function waitMonitorPoll(sleep = waitSleep) {
+    return sleep(MONITOR_POLL_INTERVAL_MS);
+}
+export async function waitForSession(provider, deps = {}) {
+    if (!(await (deps.monitorEnabled ?? (() => monitorEnabled()))()))
+        return { stdout: "", exitCode: 0 };
+    const hqRoot = (deps.resolveRoot ?? resolveLanesHqRoot)();
+    const payloadId = parseHookSessionId(await (deps.readStdin ?? readStdin)());
+    if (!monitorSessionHasActiveMarkers(hqRoot, provider, payloadId)
+        && !monitorSessionInboxHasEvents(hqRoot, provider, payloadId)) {
+        return { stdout: "", exitCode: 0 };
+    }
+    const sessionId = payloadId;
+    await (deps.recordActivity ?? recordMonitorTargetActivity)(hqRoot, monitorTargetKey({ kind: "session", provider, sessionId }));
+    const sessionDir = monitorSessionDir(hqRoot, provider, payloadId);
+    const box = path.join(sessionDir, "dropbox");
+    const waiterDir = path.join(sessionDir, "waiters");
+    const waiterPath = path.join(waiterDir, "claude-stop.json");
+    const token = `${process.pid}-${Date.now()}`;
+    writeJsonAtomic(waiterPath, { token, pid: process.pid, starttime: readProcStarttime(process.pid), at: new Date().toISOString() });
+    while (waiterIsCurrent(waiterPath, token)) {
+        const messages = (deps.drainDropbox ?? drainDropboxAtPath)(box, { canDrain: () => waiterIsCurrent(waiterPath, token) });
+        if (messages.length > 0) {
+            return { stdout: `${formatDropboxMessages(messages)}\n`, exitCode: 2 };
+        }
+        const ids = reapStaleSessionMarkers(hqRoot, provider, payloadId);
+        if (ids.length === 0 && !fs.existsSync(path.join(box, "inbox.jsonl")))
+            return { stdout: "", exitCode: 0 };
+        if (ids.length === 0 || sessionOwnersGone(hqRoot, ids) || !waiterIsCurrent(waiterPath, token))
+            return { stdout: "", exitCode: 0 };
+        await waitMonitorPoll(deps.sleep);
+    }
+    return { stdout: "", exitCode: 0 };
+}
+function reapStaleSessionMarkers(hqRoot, provider, sessionId) {
+    const ids = sessionMonitorIds(hqRoot, provider, sessionId);
+    const live = [];
+    for (const id of ids) {
+        const state = readJson(statePath(hqRoot, id));
+        const meta = readJson(path.join(monitorDir(hqRoot, id), "meta.json"));
+        if (state?.status === "running" && state.pid !== null && !readMonitorPidLiveness(state.pid, state.starttime)) {
+            writeJsonAtomic(statePath(hqRoot, id), { ...state, status: "terminal", terminal_reason: "supervisor_died", finished_at: new Date().toISOString() });
+            if (meta)
+                removeActiveMarker(hqRoot, meta);
+            continue;
+        }
+        if (state?.status === "terminal") {
+            if (meta)
+                removeActiveMarker(hqRoot, meta);
+            continue;
+        }
+        live.push(id);
+    }
+    return live;
+}
+function sessionOwnersGone(hqRoot, ids) {
+    const owners = ids.flatMap((id) => {
+        const meta = readJson(path.join(monitorDir(hqRoot, id), "meta.json"));
+        return meta?.session_owner ? [meta.session_owner] : [];
+    });
+    return owners.length > 0 && owners.every((owner) => !readMonitorPidLiveness(owner.pid, owner.starttime));
+}
+export function registerMonitorCommand(parent) {
+    const monitor = parent.command("monitor").description("Run detached monitors and deliver their output into agent context");
+    monitor.command("enabled", { hidden: true }).action(async () => {
+        process.exitCode = await runMonitorEnabledCommand();
+    });
+    monitor.command("start")
+        .description("Start a detached monitor script")
+        .requiredOption("--description <text>", "Why this monitor exists")
+        .option("--command <sh>", "Run one shell command under bash -c")
+        .option("--timeout <duration>", "Deadline; bare numbers are milliseconds")
+        .option("--persistent", "Run until the script exits, the target ends, or stopped")
+        .option("--target <target>", "lane:<id> or session:<provider>:<session-id>")
+        .option("--checkin <duration|off>", "Per-target check-in interval; defaults to 55m")
+        .option("--json", "Emit JSON")
+        .argument("[argv...]", "Executable and arguments after --")
+        .action(async (argv, options) => {
+        try {
+            await startMonitor(options, argv ?? []);
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    monitor.command("list").description("List active monitors").option("--all", "Include terminal monitors").option("--json", "Emit JSON")
+        .action(async (options) => { try {
+        await listMonitors(options);
+    }
+    catch (err) {
+        fail(err);
+    } });
+    monitor.command("show").description("Show monitor metadata, state and events").argument("<monitor-id>")
+        .option("--json", "Emit JSON").action(async (id, options) => { try {
+        await showMonitor(id, options.json);
+    }
+    catch (err) {
+        fail(err);
+    } });
+    monitor.command("stop").description("Stop a running monitor").argument("<monitor-id>")
+        .action(async (id) => { try {
+        await stopMonitor(id);
+    }
+    catch (err) {
+        fail(err);
+    } });
+    monitor.command("logs").description("Read monitor events or stderr").argument("<monitor-id>")
+        .option("--stderr", "Read stderr.log instead of events").action(async (id, options) => { try {
+        await monitorLogs(id, options.stderr === true);
+    }
+    catch (err) {
+        fail(err);
+    } });
+    monitor.command("_run", { hidden: true }).argument("<monitor-id>").action(async (id) => {
+        try {
+            await runSupervisor(id);
+        }
+        catch (err) {
+            process.stderr.write(`hq monitor supervisor: ${errorPath(err)}\n`);
+            process.exitCode = 1;
+        }
+    });
+    monitor.command("drain", { hidden: true }).requiredOption("--provider <provider>").requiredOption("--event <event>")
+        .action(async (options) => {
+        const result = await runMonitorHookSafely("drain", async () => {
+            if (!["claude", "codex", "grok"].includes(options.provider))
+                throw new LanesError("monitor_provider_invalid", "--provider must be claude, codex, or grok.");
+            if (!["PreToolUse", "UserPromptSubmit"].includes(options.event))
+                throw new LanesError("monitor_hook_event_invalid", "--event must be PreToolUse or UserPromptSubmit.");
+            return drainSession(options.provider, options.event);
+        });
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+        process.exitCode = result.exitCode;
+    });
+    monitor.command("wait", { hidden: true }).requiredOption("--provider <provider>")
+        .action(async (options) => {
+        const result = await runMonitorHookSafely("wait", async () => {
+            if (options.provider !== "claude")
+                throw new LanesError("monitor_wait_provider_unsupported", "Only Claude Stop hooks can wait for session monitor events.", { provider: options.provider });
+            return waitForSession(options.provider);
+        });
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+        process.exitCode = result.exitCode;
+    });
+    return monitor;
+}
+//# sourceMappingURL=monitor.js.map