@indigoai-us/hq-cli 5.312.2-beta.0 → 5.314.0

package/dist/commands/monitor.js

@@ -1,980 +0,0 @@
-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