@indigoai-us/hq-cli 5.126.0 → 5.128.0

package/CHANGELOG.md

@@ -2,6 +2,224 @@
 
 ## [Unreleased]
 
+## [5.128.0] — 2026-09-22
+
+### Fixed
+
+- Expected hook-timeout warnings are counted as Sentry metrics, so a slow hook
+  does not create its own Sentry issue. Genuine timeouts use stable grouping.
+
+## [5.127.0] — 2026-09-22
+
+### Added
+
+- Every composed lane brief and every resume turn carries a foreground-only
+  rule after the standing authorization: run every command, test suite and
+  check in the foreground and wait for it; a turn that ends before the envelope
+  is written is classified interrupted.
+- The spec §4 envelope repair turn now runs for grok as well. A provider with
+  no session resume gets one fresh single-turn invocation on the same account
+  carrying the schema, the parser error and the raw failed output. The lane
+  records `envelope_repair.mode` as `resume` (claude, codex) or `fresh_turn`
+  (grok) and `hq lanes show` prints it as `envelope_repair_mode`.
+- Lane records now reject omissions of required `hq-lane.v1` fields, and lane
+  mutations enforce the durable field-writer ownership map at the store boundary.
+  The map grants `reconcile` the quota fields it writes during dead-host
+  recovery, the outpost pickup account bind carries the `spawn` writer, and
+  `terminal_details` and `outpost_command_id` are typed and owned. The writer
+  argument is a required writer name; the function-form call that skipped the
+  ownership check is gone. The updater receives a deep clone and the check
+  compares against the pre-update snapshot, so mutating the argument in place
+  cannot bypass ownership.
+- Answer notes reach a resumed lane: `answered-questions.json` carries the
+  operator's `--notes` text read from the lane's own body store, and the resume
+  prompt renders each answer as its choice followed by the notes.
+- Every lane brief and every resume turn carries a standing authorization
+  paragraph: the brief authorises completing every item it lists, and a
+  `decision: ask` envelope is only for a decision the brief does not settle.
+- A question whose options are only continue and stop is recorded with
+  `question_kind: "continue"` and `hq lanes questions list` prints it with
+  `flag: "continue-loop"`. Nothing answers it automatically.
+- `hq lanes list` reports `senior_lost: true` for a running lane whose senior
+  session is absent, ended, or lost, without mutating the lane.
+- `hq lanes questions answer --freeform <text>` answers a question that offered
+  options with free text and records `answer_kind: freeform`.
+- `hq lanes resume <lane-id> [--text <message>]` resumes an `interrupted`,
+  `done` or `blocked` lane on its recorded provider session and records
+  `resumed_from`. Codex lanes record their session id at spawn and resume with
+  `codex exec resume`, so `hq lanes message` and the envelope repair turn now
+  work for exited Codex lanes as they do for Claude.
+- Lanes now report to the work mesh from the watcher, not only at create. A
+  lane that finishes posts a completion event and moves its story to review;
+  one that stops to ask posts the question ids; one that is blocked posts the
+  reason. While a lane is working, the watcher posts a progress event when it
+  sees a new tool call or new output, at most once per five minutes per lane
+  (`providers.<provider>.progress_event_min_interval_ms` in
+  `personal/lanes/config.json`), and never for silence. The watcher signs in
+  the same way the session hooks do and never opens a browser; when it cannot
+  reach the mesh it writes `mesh_event_failed` to the lane's watcher log and
+  the lane's state is unchanged. On the wire, lane events use the mesh's
+  existing activity, question, and note kinds, because the server rejects
+  unknown kinds.
+- A lane whose final output is not a valid envelope gets one repair turn: the
+  same session is resumed with the schema, the parser error, and the raw text,
+  and asked for the corrected JSON only. If that also fails the lane is
+  `failed` with reason `envelope_invalid`, and `envelope_repair` on the record
+  carries both errors. Codex and Grok lanes cannot be resumed after exit, so
+  they still fail on the first parse error; the record says why no repair ran.
+- A worker with `verification.approval_required` or `human_checkpoints` now
+  briefs its lane to stop at each checkpoint with a `decision: ask` envelope
+  naming the checkpoint. The resume prompt after the answer carries the answer
+  inline as well as naming the answers file.
+- `hq lanes ask` retries delivery three times, waiting 5 s then 15 s, when the
+  CLI is being replaced under it. On final failure it writes
+  `ask_delivery_failed.json` and returns `ask_delivery_failed`; the lane's
+  state is never changed.
+- You can hand a piece of work off to run on its own, and it keeps going after
+  you close the window. If it hits something only you can decide, it stops and
+  asks instead of guessing, and picks up again the moment you answer — you no
+  longer have to sit and watch it. If it goes quiet for twenty minutes, you are
+  told. Work sent to a second machine that would have landed back on the one
+  that asked is stopped before it starts.
+- `hq lanes create --model` records the model on the lane and passes the
+  provider's own flag (`--model` for Claude, `-m` for Codex and Grok).
+  Account and provider `model` keys in `personal/lanes/config.json` are
+  defaults; `--model` wins. An empty `--model` is refused.
+- Lane envelopes may include `story_complete` and `story_complete_reason`.
+  `story_complete true` requires `story_status done`; `false` forbids it.
+  Both are copied onto the lane record when an envelope is ingested.
+- `hq lanes create --effort <level>` sets reasoning effort per provider
+  (`--effort` for Claude, `-c model_reasoning_effort` for Codex,
+  `--reasoning-effort` for Grok), validated against each provider's own set.
+  `effort` on an account or provider in `personal/lanes/config.json` is the
+  default; with nothing set, an Opus or Fable model runs at `low`.
+- A resumed Claude lane whose last message is older than `compact_after_ms`
+  (default one hour) is compacted with `/compact` before the resume, and the
+  lane records the outcome and the before/after context size. `hq lanes
+  message --no-compact` skips it once. `accounts list` and `show` report
+  model, effort and the last compaction.
+- `--worker` resolves workers from `core/workers`, `personal/workers`,
+  `companies/<co>/workers`, and packages mounted by `hq core scan-packages`.
+  A worker id present in two trees is refused; a pack worker that is declared
+  but not mounted is `package_workers_unmounted`.
+- A provider 429 is recorded per account and model in
+  `personal/lanes/quota.json` (`account_quota_exhausted` with the reset time,
+  or `account_model_unavailable` when a model needs credits). The balancer
+  skips only what cannot run and never rewrites the operator's `enabled`.
+- `hq mesh story` accepts `--assignee <uid|me|none>` with or without `--status`.
+  `me` uses the authenticated person or agent and refuses the synthetic session
+  identity. `none` clears the assignee. The command does not send an actor.
+- `hq mesh project set <projectId> --company <slug>` now reads and merges the
+  current Board view before replacing it, so a name or description update keeps
+  existing stories and repository bindings. It accepts repository bindings from
+  PRD `metadata.repos`, `--repos-json`, or repeatable `--repo <path[@branch]>`.
+  `hq mesh project register <projectId> --company <slug>` registers the Board's
+  deterministic project channel and genesis thread without raw API calls.
+- A work-context session-state lock or directory creation failure is reported
+  as not tracking (exit 3) instead of an uncaught filesystem error.
+- The Work Mesh daemon now distinguishes an explicit device-default membership
+  revocation from malformed or unavailable membership lookups. Temporary
+  failures preserve attribution and retry later; explicit denials clear only
+  the unchanged device-default binding through the shared session-state lock,
+  so concurrent rebinds are preserved. Transcript-start discovery also leaves
+  unavailable lookups unstarted and retries with bounded backoff.
+
+### Fixed
+
+- `hq agents status` no longer tells you to sign in to a brain that is already
+  signed in. A device pairing file can outlive the sign-in it started, so the
+  box sign-in probe now decides whether the prompt is shown. Grok and Codex
+  prompts are matched to their own brain slot; a Claude prompt has no slot and
+  is unaffected.
+- Lane watcher mesh calls now time out, progress events only follow new
+  activity, and a persisted progress timestamp prevents duplicate events after
+  a watcher restart. Invalid-envelope repair is limited to one attempt even
+  when the repair writes a different envelope filename.
+- Completion mesh delivery attempts the thread event and story review update
+  independently. Repair prompts cap inlined malformed JSON while retaining the
+  raw envelope path.
+
+- `hq lanes reconcile install --enable` now enables the systemd user timer; the
+  generated unit uses `KillMode=process` so admitted lanes survive the pass, and
+  its PATH carries the directories of the resolved provider binaries. A provider
+  binary missing from PATH at spawn leaves the lane `queued` with
+  `provider_binary_missing` instead of failing it.
+- A provider binary missing from PATH re-queues a lane only on admission. An
+  answered-question or operator-message resume keeps the lane's recorded state
+  and returns `provider_binary_missing` with the searched PATH, so the next
+  reconcile resumes the recorded session instead of starting a fresh run and
+  the operator message is not lost.
+- `hq lanes reconcile install` succeeds on a box with only one provider
+  installed. The unit PATH carries the providers that resolve; the result lists
+  `providers_resolved`, `providers_unresolved`, and a `warnings` line per
+  missing provider. It refuses with `provider_binary_unresolved` only when no
+  enabled provider resolves.
+- `hq lanes questions answer` treats a whitespace-only `--freeform` as absent,
+  so `--choice` is validated against the options and recorded as an option
+  answer instead of an empty freeform answer.
+- A synced question conflict sidecar whose `answer_history` is not an array is
+  skipped like any other unreadable sidecar instead of failing every read of
+  the question.
+- `hq lanes resume` now keeps terminal lanes terminal when account binding
+  fails, records project or story attribution without requiring `--text`, and
+  rejects a concurrent resume that has already become running. Blocked mesh
+  notes use the accepted `audit` note kind and include their reason in text so
+  the server preserves the marker.
+
+- `hq agents list` shows an agent whose removal is under way as `removing`
+  rather than the runtime status it had before the removal started. An agent
+  that never finished setting up and is then removed used to keep reading
+  `provisioning` until the teardown completed, so a removal that stalled
+  looked like a removal that was never accepted. A finished teardown reads
+  `removed`; every other agent is unchanged.
+- `hq lanes accounts list` treats Claude as logged in when
+  `.credentials.json` exists. Missing Claude credentials are reported as
+  unknown, not logged out. Codex and Grok still use `auth.json`.
+- With no `--account`, a lane is assigned the least-loaded enabled
+  logged-in account rather than `default_account`.
+- A lane watcher now writes a JSON line to `logs/watcher.out` for each
+  decision that changes what it believes: a liveness transition, a silence
+  deadline, an envelope appearing, the exit classification, and the
+  terminal record write. `hq lanes logs` reports each stream's path, size
+  in bytes, and lines, so an empty log file is distinguishable from a
+  missing lane. `watcher.out` is capped at 256 KiB by dropping the oldest
+  complete lines. `hq lanes message` refuses a lane that will never read
+  the drop box (`awaiting_input`, `blocked`, and every terminal state) and
+  still accepts a queued lane. After the HQ root is resolved, `hq lanes`
+  chdirs into it; relative `--brief-file` and `--payload-file` paths still
+  resolve against the caller's original directory.
+- `hq lanes` no longer treats a git worktree's `.claude` folder as the HQ
+  root, and it honours `$HQ_ROOT` the same way the watcher and reconcile
+  timer already did. Listing or creating a lane from a worktree talks to
+  the real store, or fails out loud — it does not return an empty success
+  against a directory nothing else reads.
+- Creating a lane with `--outpost` now pushes it through `hq outposts exec`
+  instead of leaving a queued row that no machine will pick up. If the
+  Outpost is unreachable, the lane is failed, not queued.
+- A lane that finishes by asking a question now actually queues that question,
+  so someone can answer it and the lane can continue. Stopping a lane now
+  stops the process, not only the record. The drain hook that delivers
+  mid-run answers is installed into the account home instead of sitting unused
+  in the package. The periodic reconcile timer now names this HQ tree, so it
+  does not wander into `$HOME/.claude`. A live lane heartbeats from its
+  watcher; a dead watcher is started again; a reused PID is not treated as
+  the worker still running; a malformed drop-box line no longer wedges every
+  tool call.
+- `hq mesh start` now resolves its claimant from the token that authenticates
+  the request before considering a same-identity cache entry. This prevents an
+  agent from claiming work as a cached human and stops locally before creating
+  a thread when no authenticated claimant can be established.
+
+- `hq mesh context backfill-held` no longer reports `reconciled: 0` when
+  `--dry-run` predicts non-zero reconcilable sessions. The check that decides
+  whether reconcile produced a durable company binding now recognises a
+  persisted `companySlug` as sufficient — the daemon resolves the uid on its
+  next retry — instead of requiring `companyUid`, which is absent when the
+  reconciler runs without a network membership call. Sessions that have no
+  company evidence at all now appear in a separate `noEvidence` counter so
+  operators can tell them apart from sessions that were genuinely reconciled
+  as slug-only bindings.
+
 ## [5.126.0] — 2026-09-21
 
 ### Fixed

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

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${HOME}/.grok/hooks/hq-lanes-drain.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

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