@indigoai-us/hq-cli 5.345.62 → 5.345.64

package/dist/lib/lanes/links.js

@@ -0,0 +1,450 @@
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { appendDropboxMessageAtPath } from "./dropbox.js";
+export const LANE_SESSION_LINKS_FLAG = "lanes.session-links";
+const ID_PATTERN = /^[A-Za-z0-9._-]+$/;
+export class LaneLinkError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "LaneLinkError";
+    }
+}
+function safeId(value) {
+    return Boolean(value && value !== "." && value !== ".." && ID_PATTERN.test(value));
+}
+export function resolveLinkSessionId(root, explicit, env = process.env) {
+    if (explicit !== undefined && explicit !== "") {
+        if (!safeId(explicit))
+            throw new LaneLinkError("invalid_session_id", `Invalid session id: ${explicit}`);
+        return explicit;
+    }
+    for (const key of ["HQ_SESSION_ID", "CLAUDE_CODE_SESSION_ID", "CLAUDE_SESSION_ID", "CODEX_SESSION_ID", "CODEX_THREAD_ID", "GROK_SESSION_ID"]) {
+        const candidate = env[key]?.replace(/\s/g, "");
+        if (safeId(candidate))
+            return candidate;
+    }
+    try {
+        const candidate = fs.readFileSync(path.join(root, "workspace/sessions/.current"), "utf8").replace(/\s/g, "");
+        if (safeId(candidate))
+            return candidate;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    throw new LaneLinkError("session_id_missing", "Cannot resolve this session's id; pass --session-id");
+}
+function rootDir(root) {
+    return path.join(root, "workspace", "lanes-links");
+}
+function pointerPath(root, sid) {
+    return path.join(rootDir(root), "by-session", sid);
+}
+function readPointer(root, sid) {
+    try {
+        const [role, link, name] = fs.readFileSync(pointerPath(root, sid), "utf8").trim().split(/\s+/);
+        if ((role !== "conductor" && role !== "child") || !safeId(link))
+            return null;
+        return role === "child" && safeId(name) ? { role, link, name } : { role, link };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function atomicJson(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(value)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new LaneLinkError("link_not_found", `No such link: ${path.basename(path.dirname(file))}`);
+        throw error;
+    }
+}
+function linkPath(root, link) {
+    if (!safeId(link))
+        throw new LaneLinkError("link_invalid", "Invalid or missing --link");
+    const target = path.join(rootDir(root), link);
+    if (!fs.existsSync(path.join(target, "meta.json")))
+        throw new LaneLinkError("link_not_found", `No such link: ${link}`);
+    if (readJson(path.join(target, "meta.json")).closed)
+        throw new LaneLinkError("link_closed", `The link was closed: ${link}`);
+    return target;
+}
+/** Cheap hook guard used before remote flag lookup or queue access. */
+export function linkedSessionIdFromHookInput(input) {
+    try {
+        const payload = JSON.parse(input);
+        const value = payload.session_id ?? payload.sessionId;
+        return typeof value === "string" && safeId(value) ? value : "";
+    }
+    catch {
+        return "";
+    }
+}
+export function isLinkedSession(root, sid) {
+    return Boolean(safeId(sid) && readPointer(root, sid));
+}
+function activeChild(root, link, name) {
+    const childDir = path.join(rootDir(root), link, "children", name);
+    try {
+        const meta = readJson(path.join(childDir, "meta.json"));
+        const pointer = typeof meta.session_id === "string" ? readPointer(root, meta.session_id) : undefined;
+        return Boolean(pointer?.role === "child" && pointer.link === link && pointer.name === name);
+    }
+    catch {
+        return false;
+    }
+}
+function resolvePointer(root, sid, role, options) {
+    const pointer = readPointer(root, sid);
+    if (!pointer)
+        throw new LaneLinkError("session_unlinked", "This session is not part of a conduct link");
+    if (pointer.role !== role)
+        throw new LaneLinkError("link_role_invalid", `This session is a ${pointer.role} on ${pointer.link}, not a ${role}`);
+    return { link: options.link || pointer.link, child: options.child || pointer.name };
+}
+function queueDir(root, link, child) {
+    return path.join(rootDir(root), link, child ? "children" : "up", ...(child ? [child] : []), "inbox");
+}
+function sendQueue(root, link, child, text) {
+    const inbox = queueDir(root, link, child);
+    const pending = path.join(inbox, "pending");
+    fs.mkdirSync(pending, { recursive: true });
+    // Reuse hq monitor's session-inbox append primitive; the pending directory is
+    // still claimed as a whole below, keeping conduct-inbox's no-loss handoff.
+    const cleanText = text.replaceAll("\0", "").replaceAll("\u000b", "").replaceAll("\u000c", "").replaceAll("\r", "");
+    appendDropboxMessageAtPath(pending, { at: new Date().toISOString(), text: cleanText });
+}
+/** Claims pending files by renaming the whole queue, matching conduct-inbox's no-loss drain. */
+export function drainLinkQueue(inbox) {
+    const pending = path.join(inbox, "pending");
+    const claimedRoot = path.join(inbox, "claimed");
+    // Recover claims interrupted before the delivery result was committed. This is
+    // at-least-once: a crash after provider output may replay the same message.
+    if (fs.existsSync(claimedRoot))
+        for (const oldClaim of fs.readdirSync(claimedRoot)) {
+            const oldPath = path.join(claimedRoot, oldClaim);
+            if (fs.existsSync(path.join(oldPath, ".consumed")))
+                continue;
+            const payload = path.join(oldPath, "inbox.jsonl");
+            if (!fs.existsSync(payload))
+                continue;
+            fs.mkdirSync(pending, { recursive: true });
+            const existing = path.join(pending, "inbox.jsonl");
+            const oldText = fs.readFileSync(payload, "utf8");
+            const currentText = fs.existsSync(existing) ? fs.readFileSync(existing, "utf8") : "";
+            fs.writeFileSync(existing, `${oldText}${currentText && !currentText.endsWith("\n") ? "\n" : ""}${currentText}`, { mode: 0o600 });
+            fs.writeFileSync(path.join(oldPath, ".consumed"), "recovered\n", { mode: 0o600 });
+        }
+    if (!fs.existsSync(pending) || fs.readdirSync(pending).length === 0)
+        return "";
+    fs.mkdirSync(claimedRoot, { recursive: true });
+    const claim = path.join(claimedRoot, `${Date.now()}-${process.pid}-${randomBytes(4).toString("hex")}`);
+    try {
+        fs.renameSync(pending, claim);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return "";
+        throw error;
+    }
+    fs.mkdirSync(pending, { recursive: true });
+    const payload = path.join(claim, "inbox.jsonl");
+    if (!fs.existsSync(payload))
+        return "";
+    const messages = fs.readFileSync(payload, "utf8").split(/\r?\n/).filter(Boolean).flatMap((line) => {
+        try {
+            const message = JSON.parse(line);
+            return typeof message.text === "string" && message.text ? [message.text] : [];
+        }
+        catch {
+            return [];
+        }
+    }).join("\n");
+    fs.writeFileSync(path.join(claim, ".consumed"), "delivered\n", { mode: 0o600 });
+    return messages;
+}
+function countPending(inbox) {
+    const payload = path.join(inbox, "pending", "inbox.jsonl");
+    try {
+        return fs.readFileSync(payload, "utf8").split(/\r?\n/).filter(Boolean).length;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return 0;
+        throw error;
+    }
+}
+function readText(options) {
+    if (options.textFile) {
+        try {
+            return fs.readFileSync(options.textFile, "utf8");
+        }
+        catch {
+            throw new LaneLinkError("text_file_not_found", `No such file: ${options.textFile}`);
+        }
+    }
+    return options.text ?? "";
+}
+function ensureText(options) {
+    const text = readText(options);
+    if (!text.trim())
+        throw new LaneLinkError("message_empty", "Refusing to send an empty message");
+    return text;
+}
+function setChildState(childDir, state, note, now) {
+    if (!["working", "blocked", "idle", "done"].includes(state)) {
+        throw new LaneLinkError("state_invalid", "--state must be working, blocked, idle or done");
+    }
+    const file = path.join(childDir, "meta.json");
+    atomicJson(file, { ...readJson(file), state, note: note ?? "", updated: now.toISOString() });
+}
+function companyForSession(root, sid) {
+    try {
+        const text = fs.readFileSync(path.join(root, "workspace", "sessions", sid, "meta.yaml"), "utf8");
+        return /^\s*company_slug:\s*["']?([^\s"'#]+)["']?\s*$/m.exec(text)?.[1] ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+function listChildren(root, dir) {
+    const children = path.join(dir, "children");
+    if (!fs.existsSync(children))
+        return [];
+    return fs.readdirSync(children, { withFileTypes: true }).filter((entry) => entry.isDirectory()).flatMap((entry) => {
+        const cdir = path.join(children, entry.name);
+        const metaPath = path.join(cdir, "meta.json");
+        if (!fs.existsSync(metaPath))
+            return [];
+        const unread = countPending(path.join(cdir, "inbox"));
+        return [{ ...readJson(metaPath), undelivered: unread }];
+    });
+}
+async function waitForReport(dir, timeoutSeconds, sleep) {
+    if (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 0)
+        throw new LaneLinkError("timeout_invalid", "--timeout must be whole seconds");
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    for (;;) {
+        if (!fs.existsSync(dir))
+            throw new LaneLinkError("link_closed", "The link was closed");
+        if (countPending(path.join(dir, "up", "inbox")) > 0) {
+            return { output: { pending: true }, exitCode: 0 };
+        }
+        if (Date.now() >= deadline)
+            return { output: { pending: false, timeout: true }, exitCode: 3 };
+        await sleep(Math.min(3000, Math.max(1, deadline - Date.now())));
+    }
+}
+function hookMessage(root, pointer) {
+    linkPath(root, pointer.link);
+    if (pointer.role === "conductor")
+        return { inbox: queueDir(root, pointer.link), role: "conductor" };
+    if (!pointer.name)
+        throw new LaneLinkError("link_pointer_invalid", "Child link pointer has no child name");
+    return { inbox: queueDir(root, pointer.link, pointer.name), role: "child", child: pointer.name };
+}
+export async function runLaneLink(subcommand, options) {
+    const now = options.now ?? (() => new Date());
+    const env = options.env ?? process.env;
+    const root = options.hqRoot;
+    let sid = "";
+    if (subcommand === "_deliver") {
+        sid = (() => {
+            let payload = {};
+            try {
+                payload = JSON.parse(options.input ?? "{}");
+            }
+            catch { /* malformed hooks are inert */ }
+            const value = payload.session_id ?? payload.sessionId;
+            return typeof value === "string" && safeId(value) ? value : "";
+        })();
+    }
+    const requireSid = () => sid || (sid = resolveLinkSessionId(root, options.sessionId, env));
+    const links = rootDir(root);
+    if (subcommand === "_deliver") {
+        if (!sid || !["PostToolUse", "Stop", "SubagentStop"].includes(options.event ?? ""))
+            return {};
+        if (["Stop", "SubagentStop"].includes(options.event ?? "") && env.HQ_STOP_DECISION_DELIVERABLE === "0")
+            return {};
+        const pointer = readPointer(root, sid);
+        if (!pointer)
+            return {};
+        const target = hookMessage(root, pointer);
+        const messages = drainLinkQueue(target.inbox);
+        if (!messages)
+            return {};
+        const body = target.role === "conductor"
+            ? `[conduct] Sessions you are conducting reported while you were working.\nEach report names the session it came from. Relay what the operator needs to know, and answer a session with: hq lanes link send --child <name> --text '...'\n\n${messages}`
+            : `[conduct] The session conducting you sent this while you were working.\nTreat it as a new instruction from the operator, taking precedence over your current task where the two conflict. When you have something to tell the conductor - a result, a blocker, a question - send it with: hq lanes link report --state <working|blocked|idle|done> --text '...'\n\n${messages}`;
+        return options.event === "PostToolUse"
+            ? { output: { hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: body } } }
+            : { output: { decision: "block", reason: body } };
+    }
+    if (subcommand === "open") {
+        const sessionId = requireSid();
+        const p = readPointer(root, sessionId);
+        if (p) {
+            if (p.role !== "conductor")
+                throw new LaneLinkError("session_already_child", `This session is already a child of ${p.link}; leave first`);
+            return { output: { link: p.link, join: `/conduct-join ${p.link}` } };
+        }
+        const date = now().toISOString().slice(0, 10).replaceAll("-", "");
+        const link = `cl-${date}-${randomBytes(3).toString("hex")}`;
+        const dir = path.join(links, link);
+        fs.mkdirSync(path.join(dir, "children"), { recursive: true });
+        fs.mkdirSync(path.join(dir, "up", "inbox", "pending"), { recursive: true });
+        atomicJson(path.join(dir, "meta.json"), { link, conductor_session: sessionId, conductor_host_session: options.hostSession ?? "", engine: options.engine || "claude", created: now().toISOString() });
+        const bySession = path.join(links, "by-session");
+        fs.mkdirSync(bySession, { recursive: true });
+        fs.writeFileSync(pointerPath(root, sessionId), `conductor ${link}\n`, { mode: 0o600, flag: "wx" });
+        return { output: { link, join: `/conduct-join ${link}` } };
+    }
+    if (subcommand === "join") {
+        const sessionId = requireSid();
+        const dir = linkPath(root, options.link);
+        if (readPointer(root, sessionId))
+            throw new LaneLinkError("session_already_linked", "This session is already linked; leave first");
+        const name = options.name || `s-${sessionId.replace(/[^A-Za-z0-9]/g, "").slice(0, 8)}`;
+        if (!safeId(name) || name === "all")
+            throw new LaneLinkError("child_name_invalid", `Invalid or reserved --name: ${name}`);
+        const cdir = path.join(dir, "children", name);
+        try {
+            fs.mkdirSync(cdir);
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                throw new LaneLinkError("child_name_taken", `A child named ${name} is already on ${options.link}; pick another --name`);
+            throw error;
+        }
+        try {
+            fs.mkdirSync(path.join(cdir, "inbox", "pending"), { recursive: true });
+            const at = now().toISOString();
+            atomicJson(path.join(cdir, "meta.json"), { name, session_id: sessionId, host_session: options.hostSession ?? "", engine: options.engine || "claude", title: options.title ?? "", company: companyForSession(root, sessionId), state: "idle", note: "", joined: at, updated: at });
+            fs.mkdirSync(path.join(links, "by-session"), { recursive: true });
+            fs.writeFileSync(pointerPath(root, sessionId), `child ${options.link} ${name}\n`, { mode: 0o600, flag: "wx" });
+            sendQueue(root, options.link, undefined, `[${name} joined] ${options.title || "untitled session"} (engine ${options.engine || "claude"}${companyForSession(root, sessionId) ? `, company ${companyForSession(root, sessionId)}` : ""})`);
+            const meta = readJson(path.join(dir, "meta.json"));
+            return { output: { link: options.link, name, conductor_host_session: meta.conductor_host_session ?? "" } };
+        }
+        catch (error) {
+            fs.rmSync(pointerPath(root, sessionId), { force: true });
+            fs.rmSync(cdir, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    if (subcommand === "send") {
+        const resolved = options.link ? { link: options.link } : resolvePointer(root, requireSid(), "conductor", options);
+        const dir = linkPath(root, resolved.link);
+        const child = options.child;
+        if (!child)
+            throw new LaneLinkError("child_required", "--child <name|all> is required");
+        const body = ensureText(options);
+        const children = child === "all" ? fs.readdirSync(path.join(dir, "children"), { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).filter((name) => activeChild(root, resolved.link, name)) : [child];
+        if (child !== "all" && (!safeId(child) || !activeChild(root, resolved.link, child)))
+            throw new LaneLinkError("child_not_found", `No active child named ${child} on ${resolved.link}`);
+        if (!children.length)
+            throw new LaneLinkError("children_empty", `No children on ${resolved.link}`);
+        for (const name of children)
+            sendQueue(root, resolved.link, name, body);
+        return { output: { queued: true, children: children.length } };
+    }
+    if (subcommand === "report") {
+        const resolved = resolvePointer(root, requireSid(), "child", options);
+        const dir = linkPath(root, resolved.link);
+        const child = resolved.child;
+        if (!child)
+            throw new LaneLinkError("link_pointer_invalid", "Child link pointer has no name");
+        const body = ensureText(options);
+        if (options.state)
+            setChildState(path.join(dir, "children", child), options.state, options.note, now());
+        sendQueue(root, resolved.link, undefined, `[from ${child}${options.state ? ` · ${options.state}` : ""}]\n${body}`);
+        const meta = readJson(path.join(dir, "meta.json"));
+        return { output: { queued: true, conductor_host_session: meta.conductor_host_session ?? "" } };
+    }
+    if (subcommand === "status") {
+        if (!options.state)
+            throw new LaneLinkError("state_required", "--state is required");
+        const resolved = resolvePointer(root, requireSid(), "child", options);
+        if (!resolved.child)
+            throw new LaneLinkError("link_pointer_invalid", "Child link pointer has no name");
+        setChildState(path.join(linkPath(root, resolved.link), "children", resolved.child), options.state, options.note, now());
+        return { output: { name: resolved.child, state: options.state } };
+    }
+    if (subcommand === "inbox" || subcommand === "read") {
+        const role = subcommand === "inbox" ? "child" : "conductor";
+        const pointer = role === "child" || !options.link
+            ? resolvePointer(root, requireSid(), role, options)
+            : { link: options.link, child: options.child };
+        const resolved = options.link ? { ...pointer, link: options.link } : pointer;
+        const text = drainLinkQueue(queueDir(root, resolved.link, role === "child" ? resolved.child : undefined));
+        return { output: { messages: text } };
+    }
+    if (subcommand === "wait") {
+        const resolved = options.link ? { link: options.link } : resolvePointer(root, requireSid(), "conductor", options);
+        return await waitForReport(linkPath(root, resolved.link), options.timeout ?? 1800, options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))));
+    }
+    if (subcommand === "list") {
+        let link = options.link;
+        if (!link)
+            link = readPointer(root, requireSid())?.link;
+        if (!link)
+            return { output: { link: null, children: [] } };
+        const dir = linkPath(root, link);
+        const meta = readJson(path.join(dir, "meta.json"));
+        const unread = countPending(path.join(dir, "up", "inbox"));
+        return { output: { ...meta, unread_reports: unread, children: listChildren(root, dir) } };
+    }
+    if (subcommand === "leave") {
+        const sessionId = requireSid();
+        const pointer = readPointer(root, sessionId);
+        const resolved = resolvePointer(root, sessionId, "child", options);
+        const dir = linkPath(root, resolved.link);
+        const child = resolved.child;
+        sendQueue(root, resolved.link, undefined, `[${child} left the link]`);
+        setChildState(path.join(dir, "children", child), "done", "left", now());
+        fs.rmSync(pointerPath(root, sessionId), { force: true });
+        if (fs.existsSync(path.dirname(pointerPath(root, sessionId))) && fs.readdirSync(path.dirname(pointerPath(root, sessionId))).length === 0)
+            fs.rmdirSync(path.dirname(pointerPath(root, sessionId)));
+        return { output: { link: pointer.link, left: child } };
+    }
+    if (subcommand === "close") {
+        const pointer = resolvePointer(root, requireSid(), "conductor", options);
+        const resolved = options.link ? { link: options.link } : pointer;
+        if (resolved.link !== pointer.link)
+            throw new LaneLinkError("link_role_invalid", "A conductor can only close its own link");
+        const dir = linkPath(root, resolved.link);
+        const bySession = path.join(links, "by-session");
+        if (fs.existsSync(bySession))
+            for (const file of fs.readdirSync(bySession)) {
+                const [role, pointerLink] = fs.readFileSync(path.join(bySession, file), "utf8").trim().split(/\s+/);
+                if ((role === "conductor" || role === "child") && pointerLink === resolved.link)
+                    fs.rmSync(path.join(bySession, file), { force: true });
+            }
+        if (fs.existsSync(bySession) && fs.readdirSync(bySession).length === 0)
+            fs.rmdirSync(bySession);
+        const meta = readJson(path.join(dir, "meta.json"));
+        atomicJson(path.join(dir, "meta.json"), { ...meta, closed: now().toISOString() });
+        return { output: { link: resolved.link, closed: true } };
+    }
+    throw new LaneLinkError("subcommand_unknown", `Unknown lanes link subcommand: ${subcommand}`);
+}
+/** Apply the default-on feature gate contract at the command boundary. */
+export async function runLaneLinkWithFlag(subcommand, options, enabled) {
+    if (!enabled)
+        return subcommand === "_deliver" ? {} : { output: { error: "link_disabled" }, exitCode: 1 };
+    return runLaneLink(subcommand, options);
+}
+//# sourceMappingURL=links.js.map

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

@@ -128,6 +128,7 @@ interface StoredEnvelope {
     envelope_id: string;
     queued_at: string;
     deadline_budget_seconds?: number;
+    stall_attempts?: number;
     envelope: LoopEnvelope;
 }
 /** Validate both hq-cli phase envelopes and the conduct protocol §8 shape. */
@@ -155,10 +156,14 @@ export declare function interruptLoopQueue(runDir: string): {
     withdrawn: string[];
     already_picked_up: string[];
 };
-export declare function interruptLoopQueueForStory(runDir: string, storyId: string, phase?: string): {
+export declare function interruptLoopQueueForStory(runDir: string, storyId: string, phase?: string, hooks?: {
+    beforePendingRead?: (file: string) => void;
+    beforePendingRename?: (file: string) => void;
+}): {
     withdrawn: string[];
     already_picked_up: string[];
 };
+export declare function findLoopStallResult(runDir: string, questionId: string): LoopResult | undefined;
 export declare function applyLoopStallAnswer(input: {
     runDir: string;
     questionId: string;
@@ -168,7 +173,7 @@ export declare function applyLoopStallAnswer(input: {
 }): {
     lane_id: string;
     envelope_id: string;
-    action: "requeued" | "parked";
+    action: "requeued" | "parked" | "already_applied";
 } | undefined;
 export declare function loopStatus(runDir: string, laneId: string): LoopStatus;
 export declare function setLoopControllerPid(runDir: string, laneId: string, pid: number | undefined): void;