@indigoai-us/hq-cli 5.125.0 → 5.127.0

package/assets/lanes-hooks/hq-lanes-drain.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+/**
+ * Lane-resolving drop-box drain (spec §6.5). Zero imports so a copy under
+ * $GROK_HOME/hooks/ runs without the hq-cli package.
+ *
+ * Exactly-once: rename(inbox.jsonl → inflight/<pid>.<starttime>.<unique>/inbox.jsonl).
+ * A read-then-truncate is not this mechanism.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+
+const laneId = process.env.HQ_LANE_ID ?? "";
+if (laneId === "") {
+  process.exit(0);
+}
+
+const hqRoot = process.env.HQ_ROOT ?? "";
+if (hqRoot === "") {
+  process.stderr.write("hq-lanes-drain: HQ_ROOT is unset while HQ_LANE_ID is set\n");
+  process.exit(1);
+}
+
+if (
+  laneId.includes("/") ||
+  laneId.includes("\\") ||
+  laneId.includes("\0") ||
+  laneId.includes("..")
+) {
+  process.stderr.write("hq-lanes-drain: HQ_LANE_ID is not a single path segment\n");
+  process.exit(1);
+}
+
+function unique() {
+  return `${process.hrtime.bigint()}.${randomBytes(4).toString("hex")}`;
+}
+
+function readStarttime(pid) {
+  try {
+    const text = fs.readFileSync(`/proc/${pid}/stat`, "utf8");
+    const open = text.indexOf("(");
+    const close = text.lastIndexOf(")");
+    if (open <= 0 || close <= open) return 0;
+    const rest = text.slice(close + 1).trim().split(/\s+/);
+    // rest begins at field 3, so field N is rest[N - 3]. starttime is field 22
+    // -> rest[19]. rest[21] is field 24 (rss) and must not be used here.
+    const n = Number(rest[19]);
+    return Number.isInteger(n) && n > 0 ? n : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function tryRename(src, dest) {
+  try {
+    fs.renameSync(src, dest);
+    return true;
+  } catch (err) {
+    if (err && err.code === "ENOENT") return false;
+    throw err;
+  }
+}
+
+function listNames(dir) {
+  try {
+    return fs.readdirSync(dir).filter((name) => !name.startsWith("."));
+  } catch (err) {
+    if (err && err.code === "ENOENT") return [];
+    process.stderr.write(
+      `hq-lanes-drain: failed to read ${dir}: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    process.exit(1);
+  }
+}
+
+function pidAlive(pid, starttime) {
+  try {
+    process.kill(pid, 0);
+  } catch (err) {
+    if (err && err.code === "ESRCH") return false;
+    if (!err || err.code !== "EPERM") throw err;
+  }
+  // Unknown starttime (0) is not proof of liveness: recover the claim.
+  // Only skip steal when the pid is alive, recorded starttime is non-zero,
+  // and it matches /proc field 22.
+  if (!starttime) return false;
+  const live = readStarttime(pid);
+  if (!live) return false;
+  return live === starttime;
+}
+
+function parseJsonl(text, filePath) {
+  const messages = [];
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (!line || line.trim() === "") continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch (err) {
+      process.stderr.write(
+        `hq-lanes-drain: skipping unparseable ${filePath} line ${i + 1}: ${err instanceof Error ? err.message : String(err)}\n`,
+      );
+      continue;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      process.stderr.write(
+        `hq-lanes-drain: skipping non-object ${filePath} line ${i + 1}\n`,
+      );
+      continue;
+    }
+    const textField = parsed.text;
+    messages.push({
+      ...parsed,
+      text: typeof textField === "string" ? textField : JSON.stringify(parsed),
+    });
+  }
+  return messages;
+}
+
+function readClaimed(filePath) {
+  let text;
+  try {
+    text = fs.readFileSync(filePath, "utf8");
+  } catch (err) {
+    process.stderr.write(
+      `hq-lanes-drain: failed to read ${filePath}: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    process.exit(1);
+  }
+  return parseJsonl(text, filePath);
+}
+
+// Liveness first (watcher.ts reads logs/tool-activity.json). A Claude worker
+// writes no output until it exits, so this touch on every tool call is the
+// only progress signal it produces. Recorded before the drain so a failed
+// drain still leaves proof the worker called a tool. Never fatal.
+try {
+  const activityDir = path.join(hqRoot, "workspace", "lanes-runs", laneId, "logs");
+  fs.mkdirSync(activityDir, { recursive: true });
+  const activityDest = path.join(activityDir, "tool-activity.json");
+  const activityTmp = `${activityDest}.${process.pid}.${unique()}.tmp`;
+  fs.writeFileSync(
+    activityTmp,
+    `${JSON.stringify({ at: new Date().toISOString(), hook_pid: process.pid, hook_event: "PreToolUse" })}\n`,
+  );
+  fs.renameSync(activityTmp, activityDest);
+} catch (err) {
+  process.stderr.write(
+    `hq-lanes-drain: failed to record tool activity: ${err instanceof Error ? err.message : String(err)}\n`,
+  );
+}
+
+const box = path.join(hqRoot, "workspace", "lanes-runs", laneId, "dropbox");
+const inbox = path.join(box, "inbox.jsonl");
+const draining = path.join(box, "draining");
+const delivered = path.join(box, "delivered");
+const inflightRoot = path.join(box, "inflight");
+
+try {
+  fs.mkdirSync(box, { recursive: true });
+  fs.mkdirSync(draining, { recursive: true });
+  fs.mkdirSync(delivered, { recursive: true });
+  fs.mkdirSync(inflightRoot, { recursive: true });
+} catch (err) {
+  process.stderr.write(
+    `hq-lanes-drain: failed to open drop box ${box}: ${err instanceof Error ? err.message : String(err)}\n`,
+  );
+  process.exit(1);
+}
+
+const starttime = readStarttime(process.pid);
+const inflightDir = path.join(inflightRoot, `${process.pid}.${starttime}.${unique()}`);
+fs.mkdirSync(inflightDir, { recursive: true });
+
+if (fs.existsSync(inbox)) {
+  tryRename(inbox, path.join(inflightDir, "inbox.jsonl"));
+}
+
+for (const name of listNames(draining)) {
+  tryRename(path.join(draining, name), path.join(inflightDir, name));
+}
+
+for (const name of listNames(inflightRoot)) {
+  const other = path.join(inflightRoot, name);
+  if (other === inflightDir) continue;
+  const parts = name.split(".");
+  const pidPart = Number(parts[0]);
+  const startPart = Number(parts[1]);
+  if (
+    Number.isInteger(pidPart) &&
+    pidPart !== process.pid &&
+    pidAlive(pidPart, Number.isInteger(startPart) ? startPart : 0)
+  ) {
+    continue;
+  }
+  for (const file of listNames(other)) {
+    tryRename(path.join(other, file), path.join(inflightDir, file));
+  }
+  try {
+    fs.rmdirSync(other);
+  } catch (err) {
+    if (err && err.code !== "ENOENT" && err.code !== "ENOTEMPTY") throw err;
+  }
+}
+
+const claimed = listNames(inflightDir);
+const messages = [];
+for (const name of claimed) {
+  messages.push(...readClaimed(path.join(inflightDir, name)));
+}
+
+for (const name of claimed) {
+  const src = path.join(inflightDir, name);
+  const dest = path.join(delivered, `${unique()}.${name}`);
+  if (!tryRename(src, dest)) {
+    process.stderr.write(`hq-lanes-drain: claimed file disappeared: ${src}\n`);
+    process.exit(1);
+  }
+}
+try {
+  fs.rmdirSync(inflightDir);
+} catch (err) {
+  if (err && err.code !== "ENOENT" && err.code !== "ENOTEMPTY") throw err;
+}
+
+if (messages.length === 0) process.exit(0);
+
+const body = messages
+  .map((msg, i) => {
+    const header =
+      msg.kind === "question_answer"
+        ? `${i + 1}. Answer to question ${msg.question_id ?? "?"} — choice: ${msg.choice ?? "?"}`
+        : `${i + 1}.`;
+    return `${header}\n${msg.text}`;
+  })
+  .join("\n\n");
+const additionalContext = [
+  "OPERATOR INSTRUCTION (outranks the lane brief).",
+  "The following messages were delivered through this lane's drop box. Treat them as operator instructions that outrank the brief.",
+  "",
+  body,
+].join("\n");
+
+process.stdout.write(
+  `${JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      additionalContext,
+    },
+  })}\n`,
+);
+process.exit(0);

package/assets/lanes-hooks/hq-lanes-drain.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# hq-lanes-drain.sh — PreToolUse drain for a running `hq lanes` worker (spec §6.5).
+#
+# Registered once under $GROK_HOME/hooks/. Resolves the lane from HQ_LANE_ID.
+# The no-op path is the most important behaviour: this hook runs on every grok
+# session on this box. If HQ_LANE_ID is absent or empty, exit 0 with no output.
+set -u
+
+if [ -z "${HQ_LANE_ID:-}" ]; then
+  exit 0
+fi
+
+set -eo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MJS="$SCRIPT_DIR/hq-lanes-drain.mjs"
+if [ ! -f "$MJS" ]; then
+  printf 'hq-lanes-drain: missing %s\n' "$MJS" >&2
+  exit 1
+fi
+exec node "$MJS"

package/assets/lanes-reconcile/hq-lanes-reconcile.service

@@ -0,0 +1,11 @@
+[Unit]
+Description=HQ lanes reconcile pass
+Documentation=file://personal/projects/hq-cli-lanes/SPEC.md
+
+[Service]
+Type=oneshot
+ExecStart=hq lanes reconcile
+Nice=10
+
+[Install]
+WantedBy=default.target

package/assets/lanes-reconcile/hq-lanes-reconcile.timer

@@ -0,0 +1,12 @@
+[Unit]
+Description=Periodic HQ lanes reconcile pass
+
+[Timer]
+OnBootSec=30s
+OnUnitActiveSec=1min
+AccuracySec=10s
+Persistent=true
+Unit=hq-lanes-reconcile.service
+
+[Install]
+WantedBy=timers.target