@indigoai-us/hq-cli 5.125.0 → 5.127.0

package/CHANGELOG.md

@@ -2,6 +2,335 @@
 
 ## [Unreleased]
 
+## [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
+
+- `hq mesh start` works for people again. It was sending your email address as
+  the claimant, and the server compares that to your person id, so every human
+  start failed with "claimedBy must match the authenticated author" and left
+  the thread unclaimed. Claims now carry your resolved person id (bots keep
+  their agent id).
+
+### Changed
+
+- On Windows, the mesh daemon's Scheduled Task now names the HQ root it was
+  installed for right in the task command (`mesh daemon run --hq-root <path>`)
+  instead of relying on a remembered list of roots. Install only wraps the
+  daemon in `conhost.exe --headless` when the machine is new enough to support
+  it (Windows 10 1809 or later) and says which mode it chose. `hq mesh daemon
+  status` now reports when the task's last start failed, and reminds you that
+  the task only runs while you are logged on. macOS and Linux are unchanged.
+
+- `hq mesh daemon install` no longer mistakes a code repo for your HQ. It
+  accepts `--hq-root <path>`, otherwise uses `HQ_ROOT`, otherwise walks up
+  from the current folder to the nearest real HQ tree (one with
+  `companies/manifest.yaml` and `core/`, `.claude/`, or `personal/`). A folder
+  that only has `.claude/` does not count. If nothing qualifies, install stops
+  and tells you to pass `--hq-root` instead of recording the wrong root. The
+  install confirmation now leads with the root it chose and how, and `hq mesh
+  daemon status` prints the root the task actually carries and warns when that
+  folder has since moved or been deleted.
+
+- The setup bot now recognises when you have joined a company that someone
+  else already built. Instead of asking what kind of business you own and
+  offering to connect apps your team connected months ago, it shows you what
+  is already there in real names and counts, answers one real question from
+  your company's own memory, asks what you do there, and offers only what is
+  missing for you. Things only an owner can do now name the owner instead of
+  failing.
+
+- The setup bot asks which tools you actually use and connects each one
+  however that tool needs it, after recommending the few things a business
+  like yours should set up. It no longer works from a fixed list of apps.
+
+- Setup no longer asks for your name when you are already signed in, and no
+  longer offers to skip itself.
+
+### Fixed
+
+- The desktop grok bot talks to grok 0.2.56 again. That CLI dropped
+  `--output-format streaming-messages-json` (only `plain`, `json`, and
+  `streaming-json` remain). The bot now reads the value from `grok --help`
+  once and caches it, retries with `streaming-json` if grok rejects the old
+  flag, and concatenates `streaming-json` text deltas for the reply instead
+  of treating them as Anthropic Messages events.
+
+- `hq core scan-packages` writes pack-mount symlinks relative to the host
+  directory, so they survive a tree moving between machines. A leftover
+  absolute link from another host, or an absolute link that still points at
+  this pack's payload, is rewritten to the relative form on the next scan; a
+  correct relative link is left alone.
+
+- Work Mesh reconcile now owns company attribution explicitly on the acked
+  path for every register where `resolvedCompany.uid` is set, not only fully
+  bound sessions. Previously the non-bound acked path had no reconcile-owned
+  attribution write and relied on an incidental side effect of
+  `writeAckedRegisterState` → `writeAcknowledgedRegisterBinding`; that side
+  effect already wrote `companyUid`/`companySlug` for ops carrying a uid, so
+  the tenant was not dropped in practice, but any future acked path that
+  preceded or skipped that call would silently lose it. The fix makes
+  attribution explicit: a company-only ack is projected as `needs_project`
+  with its tenant intact, the write reflects the true classification, and no
+  `projectId`, `taskId`, or binding episode is fabricated on partial paths.
+  Note: a company resolved by slug only (no uid) is still not attributed on
+  either path.
+
+- The setup bot no longer posts the same question twice when a turn takes a
+  while: a question asked in an interim update is held back if the final
+  answer repeats it.
+
+- On Windows, the work-context config safety check now inspects the file's
+  Windows ACL instead of POSIX mode bits, so `hq mesh context reconcile` no
+  longer refuses every run with "unsafe permissions 666" and session state and
+  register operations are written again. The config file and its directory must
+  be writable only by the current user, SYSTEM, and Administrators; any other
+  principal with write access is rejected, matched by SID so localized account
+  names do not matter, and named in the error. When the ACL cannot be read
+  at all (icacls missing, non-NTFS volume), the check follows a documented
+  reduced-guarantee path: it prints one diagnostic that the config is
+  unprotected on this platform and continues rather than blocking. macOS and
+  Linux behaviour is unchanged.
+
+### Added
+
+- `hq mesh daemon install` now works on Windows. It registers a per-user
+  Scheduled Task (`ai.getindigo.hq-mesh-daemon`) that starts the mesh daemon at
+  logon, hidden, with no execution time limit and a restart-on-failure policy,
+  and starts it right away. `hq mesh daemon status` reports whether the task is
+  registered and running, `hq mesh daemon uninstall` ends and removes it, and a
+  CLI update restarts it like the macOS and Linux services. Before this the
+  three commands answered "No service manager integration on this platform",
+  so the session-event spool never drained on Windows. The task definition is
+  written as XML under `~/.hq/work-mesh/daemon/` and registered with
+  `schtasks.exe`; no new dependencies. macOS and Linux behaviour is unchanged.
+
+- `hq bot list --json` reports `busy` and `busySince` for each bot on this
+  computer, and `hq bot status` shows an `answering:` line. Apps use this to
+  keep a "thinking" indicator up for a whole turn, rather than ending it the
+  moment the bot posts a progress note.
+
+- Library layer for `hq lanes` (`src/lib/lanes/`): lane/question record store
+  with compare-and-set writes, provider-account resolution, CPU/memory throttle,
+  session liveness from the work-mesh spool, and path-keyed worker tenancy.
+
+- `hq lanes` command surface: create/list/show/message/reparent/logs/stop,
+  non-blocking ask, questions list/show/answer/escalate/cancel, accounts
+  list/login/enable/disable, and sessions list/show. Create admits against
+  provider caps, the bounded queue, and the host throttle, then leaves the
+  lane queued — process spawn is an explicit not-implemented seam.
+
 ## [5.125.0] — 2026-09-20
 
 ### Fixed

package/assets/bot-workers/setup/skills/joining-a-team.md

@@ -0,0 +1,125 @@
+---
+name: joining-a-team
+title: Joining a team
+description: Set up someone who installed HQ into a company that already exists, by showing them what they just inherited and adding what is missing for them.
+---
+
+# Joining a team
+
+Most people who install HQ from here on are not founders. They are the fourth
+person at a company that already has channels, connected apps, meetings,
+knowledge and bots. Their setup is not "build an HQ". It is "here is the HQ you
+just walked into, and here is what I will add for you."
+
+Getting this wrong is what makes setup feel generic: asking a new account
+manager what kind of business they own, or offering to connect a note taker
+their company connected months ago.
+
+## 1. Work out that this is an existing company, before you ask anything
+
+Their companies come from the "Owner context" block at the top of their
+message. Never use your own `hq` membership for this; that describes you, the
+bot.
+
+When the block names a company, look at how much is already in it. Quiet
+reads, one message of output for them at the end, never a transcript of the
+looking:
+
+- People: `hq members list` (and `hq people list`) for the company.
+- Conversations: `hq channels`.
+- Apps the company already connected: `hq integrations list`.
+- Bots already working there: `hq agents list`, and `hq bot list --remote`.
+- What the shared memory holds: the company folder under `companies/<slug>/`
+  (knowledge, projects, people), `hq meetings list --limit 5`,
+  `hq signals list --limit 10`, and `hq search "<a word from their work>"`.
+
+Then decide which of these you are in:
+
+- **A company with things in it** (more than one person, or any connected app,
+  bot, meeting or knowledge). This skill is the whole middle of their setup.
+- **A company that is empty** (they were invited, but nothing has been set up
+  yet). Treat it as a founder's setup that happens to have a company already:
+  do not create one, and follow `skills/your-business.md` as written.
+- **No company.** This skill does not apply. Go back to
+  `skills/first-company.md`.
+
+If the owner-context check failed, say you could not check right now. Never
+treat an unreadable check as "you are alone".
+
+## 2. Give them the tour, grounded in what is actually there
+
+One short message. Real names and counts from the reads above, never a
+description of HQ as a product:
+
+> You're in **Northwind** with Sara, Ali and two others. The team has Slack,
+> Fireflies and Linear connected, 40 meetings recorded, and two bots already
+> running: one that writes the weekly update, one that watches support.
+
+Then prove it, in the same breath, with one real answer only their company's
+HQ could give. Pull it yourself and show the answer, not the method:
+
+> From last week: the team decided to push the pricing change to November and
+> to keep the legacy plan for existing customers.
+
+That single line is what makes the product land. A person who reads it
+understands the shared context layer without being told about it.
+
+Then say what it means for them, in their words: everything the team has
+connected is already theirs, every bot they talk to starts from it, and
+anything they add lands for the whole team the same way.
+
+Never invent any of this. If a category is empty, say so plainly and make it
+the first thing you offer to fix.
+
+## 3. Ask about them, not about the business
+
+You already know the business. Confirm it in half a sentence rather than
+asking. What you do not know is where they fit, so ask that, one question, in
+plain words:
+
+> What do you do at Northwind, day to day?
+
+Their answer decides everything you offer next. Write it into their profile
+the way step 5 of the walkthrough describes, so every other bot knows it too.
+
+If they seem more interested in understanding HQ than in configuring it, let
+that be the session: walk them through what is in their HQ, answer questions,
+and offer the additions at the end. Familiarity is a legitimate outcome of
+setup for a joiner.
+
+## 4. Offer what is missing for them, not for the company
+
+Check what exists before offering anything, and say plainly what they already
+have rather than offering it again:
+
+> Fireflies is already connected, so your meetings are in here from today.
+
+Then offer only the gaps, three at most, each with a reason tied to what they
+just told you:
+
+- **Their own tools on this Mac**: the coding tool they use, signed in.
+- **Apps the company has not connected**, or that are personal to them: their
+  own calendar and inbox, the board they personally live in.
+- **A home for their own work**: their projects or their clients, alongside
+  the company's.
+- **Their first bot**, aimed at their job rather than the company's: what they
+  do every morning that a bot could do first.
+
+## 5. Things only an owner can do
+
+Inviting people, company-wide credentials and some company files may not be
+theirs to change. When they ask for one, do not attempt it and fail. Say who
+can do it, by name, from the members list, and offer to send that person the
+request from them:
+
+> Sara owns Northwind, so the invite has to come from her. Want me to message
+> her and ask?
+
+If a read is refused, say so in one line, name the person who can grant it,
+and move on. Never retry, and never guess at what the file said.
+
+## 6. Finish
+
+Close the way the walkthrough closes, with their version of it: what they
+inherited, what you added today, and the one thing worth trying tomorrow. If
+they have a bot now, hand them over to it.