[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M73NSD3J6PYB46F9FSC94G7P":3,"skill-same:01M73NSD3J6PYB46F9FSC94G7P":60},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":28,"repositoryHtmlUrl":29,"repositoryHomepageUrl":6,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M73NSD3J6PYB46F9FSC94G7P","hq-heal",null,"Triage and repair HQ session errors such as hook crashes, sync conflicts, or MCP failures.","indigoai-us\u002Fhq-core","indigoai-us","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F122242446?v=4","01M71DTQ5NGD10GT1Z7E6XKWC5","HQ","01M71DTQ6BKSYYBNC9RAKT3YDK",95,"MIT","https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fhq-heal\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: hq-heal\ndescription: Triage and repair HQ session errors such as hook crashes, sync conflicts, or MCP failures.\nallowed-tools: Read, Write, Edit, Bash, Bash(bash core\u002Fscripts\u002Fgit-pack-extension-check.sh:*), Bash(bash core\u002Fscripts\u002Fgit-icon-file-check.sh:*), Bash(bash core\u002Fscripts\u002Fhq-root-git-reinit.sh:*), Glob, Grep, AskUserQuestion\n---\n\n# HQ Heal — Session Error Triage\n\nWhen a Claude Code or Codex session in HQ surfaces an error, run this skill to classify the error, run targeted diagnostics, and either apply a safe fix automatically or surface a numbered fix proposal for confirmation. Writes a heal report under `workspace\u002Freports\u002Fhq-heal\u002F`.\n\n**User input:** `$ARGUMENTS`\n\n## Arguments\n\nThe first argument shapes how the error is collected. Everything after the flag (or the whole string if no flag is present) is treated as the error text.\n\n- `(no args)` → use `AskUserQuestion` to ask the user to paste the error text.\n- `\u003Cfree text>` → treat the entire argument string as the error text.\n- `--last-session` → scan the most recent JSONL under `~\u002F.claude\u002Fprojects\u002F-Users-*-Documents-HQ\u002F` for the trailing error (uses the streaming Python pattern from `.claude\u002Fskills\u002Frecover-session\u002FSKILL.md` step 3 — never read the full file).\n- `--class \u003Cname>` → skip classification and jump straight to the diagnostics recipe for that class. Valid: `autocompact`, `hook`, `sandbox-network`, `sync`, `work-registry`, `denylist`, `mcp`, `qmd`, `reindex`, `symlink`, `git-root`, `git-object-store`, `plan-mode`, `unknown`.\n- `--dry-run` → diagnose and propose but do not apply any fix.\n- `--no-bug` → suppress the automatic `\u002Fhq-bug` filing step. By default, every heal run files a bug so HQ engineering accumulates signal on which error classes are recurring (see Step 6).\n- `--allow-core` → permit the apply step to edit files under `core\u002F` (the hook-protected mirror) by prefixing the offending Write\u002FEdit\u002FBash call with `HQ_BYPASS_CORE_PROTECT=1`. Off by default — heal will refuse a core edit and require this flag to be passed, even when the user confirms the numbered fix. Always documented in the heal report and the filed bug (see Step 5 + Step 6).\n\n## Process\n\n### 1. Capture the error text\n\nIf `$ARGUMENTS` is empty, ask: *\"Paste the error message you're seeing (or describe what went wrong).\"* Wait for response, treat that as the error text.\n\nIf `--last-session`, run a Python streaming extract that scans the last 200 lines of the most recently modified JSONL for any of these signals: `Prompt is too long`, `Conversation too long`, `Error during compaction`, `Autocompact is thrashing`, `permission denied`, `EACCES`, `hook .* failed`, `block-hq-root-git-mutation`, `MCP server .* failed`, `qmd: error`, `reindex.sh.*abort` (legacy `master-sync.sh.*abort`), `FILES_PRESIGN_STALE_UPLOAD_FORBIDDEN`, `resend_full_scheduled`, `manifest.*throttled`, `fetch failed`, `connect EPERM`, `EPERM`, or `WORK_REGISTRY_DISABLED`. Capture the matched line plus 2 lines of surrounding context. Truncate to 2 KB.\n\nStore the resulting text in a local variable called `ERR`.\n\n### 2. Classify the error\n\nUnless `--class` is set, walk the pattern table top-to-bottom; first match wins. The classifier is pure pattern matching on `ERR` — do not load any other HQ context yet.\n\n| Class | Triggers (case-insensitive substring or regex on `ERR`) |\n|---|---|\n| `autocompact` | `Autocompact is thrashing`, `Prompt is too long`, `Conversation too long`, `Error during compaction`, `context refilled to the limit` |\n| `hook` | `hook .* failed`, `PreToolUse .* blocked`, `PostToolUse hook`, `hook-gate.sh`, `non-zero exit from hook` |\n| `sandbox-network` | `connect EPERM`, `EPERM .*:443`, `CODEX_SANDBOX_NETWORK_DISABLED`, `sandbox.*(network|egress)` — the OS refused an outbound HTTPS connect, or a write outside the workspace, under a Codex or ChatGPT desktop app sandbox. A bare `fetch failed` with no EPERM underneath is NOT this class: it stays with `sync` (offline, refused, timeout) |\n| `sync` | `hq sync .* conflict`, `conflictPath`, `resolve-conflicts`, `hq-sync.*error`, `originalPath.*conflict`, `FILES_PRESIGN_STALE_UPLOAD_FORBIDDEN`, `resend_full_scheduled`, `manifest.*throttled` |\n| `work-registry` | `WORK_REGISTRY_DISABLED`, `work-mesh.*register.*AUTH_DENIED`, `register.*quarantined.*AUTH_DENIED` — a work-mesh session register was refused. Older hq-cli versions (before 5.345.150) recorded the company's work registry being off as `AUTH_DENIED` in the outbox |\n| `access` | `caller lacks '.*' on '.*'`, `403 Forbidden`, `Access denied`, `AccessDenied`, `no such key`, `NoSuchKey`, `not found` (when the path is under `companies\u002F`) |\n| `denylist` | `Read access blocked`, `denied by settings`, `~\u002F.ssh`, `~\u002F.aws\u002Fcredentials`, `~\u002F.zshrc`, `permission rule .* deny` |\n| `mcp` | `MCP server .* (failed|disconnected|timeout)`, `Error connecting to MCP`, `tool .* not found` (when the tool name matches a known MCP) |\n| `qmd` | `qmd: error`, `qmd .* index`, `collection .* not found`, `qmd update` failures |\n| `reindex` | `reindex.sh`, `master-sync.sh`, `duplicate worker id`, `personal\u002F\u003Ctype>\u002F\u003Centry>.*already exists` |\n| `symlink` | `Too many levels of symbolic links`, `ELOOP`, `dangling symlink`, `readlink: .* No such file` |\n| `git-object-store` | `unable to read tree`, `bad tree object`, `cannot read commit object`, `invalid sha1 pointer`, `fatal: bad object`, `object file .* is empty`, `packfile .* (cannot|does not)`, `Error building trees`, `invalid object [0-7]+ [0-9a-f]+`, `badRefName`, `bad sha1 file`, `Icon\\r` |\n| `git-root` | `block-hq-root-git-mutation`, `git .* blocked from HQ root`, `HQ_ALLOW_HQ_ROOT_GIT` |\n| `plan-mode` | `plan mode`, `ExitPlanMode required`, `cannot Edit in plan mode` |\n| `unknown` | (no match) |\n\nBind `CLASS` to the matched class name.\n\n### 3. Run the diagnostics recipe for `CLASS`\n\nEach recipe is intentionally narrow: a small, parallel set of reads and shell probes that gather just enough state to propose a fix. Never load company knowledge, INDEX.md, or `companies\u002Fmanifest.yaml` here — heal stays HQ-internal.\n\n#### `autocompact`\nParallel checks:\n- `wc -l ~\u002F.claude\u002Fprojects\u002F-Users-*-Documents-HQ\u002F*.jsonl 2>\u002Fdev\u002Fnull | tail -5` — recent session sizes\n- `du -sh ~\u002F.claude\u002Fprojects\u002F-Users-*-Documents-HQ\u002F 2>\u002Fdev\u002Fnull` — total session bloat\n- `ls -lhS workspace\u002Fthreads\u002F*.json 2>\u002Fdev\u002Fnull | head -3` — large thread files\n- If `--last-session` was used, identify the single largest tool result in the matched JSONL (Python streaming, return tool name + size only)\n\nFix proposals (ranked):\n1. `\u002Fclear` and resume work — fastest if the session has accumulated stale tool results\n2. `\u002Frecover-session --session \u003Cuuid>` — reconstruct a thread from the dead JSONL, then start fresh\n3. Identify the offending tool call and recommend a smaller-scope alternative (e.g. `qmd search -c hq-infra \u003Cterm>` instead of reading a multi-MB INDEX, or `Read` with `offset:`\u002F`limit:` instead of full-file reads)\n4. If a file repeatedly bloats context, propose moving it out of auto-load paths (e.g. very large `INDEX.md`, `quick-reference.md`)\n\n#### `hook`\nFirst diagnostic step — run `hq doctor`, the authoritative hook wiring\u002Ffiring\ndiagnostic (US-012):\n- `hq doctor` (or `hq doctor --json` for machine-readable findings) — it enumerates\n  every hook registration across Claude\u002FCodex\u002FGrok, verifies the referenced\n  scripts exist and are executable, checks three-profile membership, and reports\n  via the runtime probe whether hooks actually fired this session. Read its\n  `FAIL`\u002F`UNKNOWN` results and their `remediation` fields to target the checks\n  below. For a deeper confirmation that a specific guard actually blocks, run\n  `hq doctor --deep-test`.\n- If `hq doctor` is unavailable (older HQ without the CLI command), fall back to\n  `bash core\u002Fscripts\u002Fcheck-hq-hooks.sh --root . --require-ledger`, which degrades\n  to the same check inline.\n\nThen the targeted parallel checks:\n- `cat .claude\u002Fsettings.json | grep -E '\"(PreToolUse|PostToolUse|SessionStart|Stop|PreCompact)\"' | head` — confirm hook chain is intact\n- `echo \"HQ_HOOK_PROFILE=$HQ_HOOK_PROFILE  HQ_DISABLED_HOOKS=$HQ_DISABLED_HOOKS\"`\n- Grep `ERR` for the hook script name; if found, `ls -la .claude\u002Fhooks\u002F\u003Cname>.sh` and read its first 40 lines\n- **Stale shadowing CLI install** (feedback e49ce279): if `ERR` says `unknown command 'lanes'`, `needs hq-cli >= X (found Y)`, or `hq CLI is missing from PATH`, run `command -v hq`, `ls -l \"$(command -v hq)\"` and `HQ_NO_UPDATE_CHECK=1 hq --version`. A wrapper such as `~\u002F.local\u002Fbin\u002Fhq` that execs `$HOME\u002FLibrary\u002Fpnpm\u002Fhq` means two installs exist (pnpm and npm-global, or a stale `~\u002F.local` copy next to the auto-updated one). List them: `pnpm ls -g @indigoai-us\u002Fhq-cli 2>\u002Fdev\u002Fnull`, `npm ls -g @indigoai-us\u002Fhq-cli --depth=0 2>\u002Fdev\u002Fnull`, `ls \"$HOME\u002FLibrary\u002FApplication Support\u002FIndigo HQ\u002Ftoolchain\u002Fnpm-global\u002Fbin\u002Fhq\" 2>\u002Fdev\u002Fnull`. The copy that `command -v hq` resolves to is the one the hooks run; `hq doctor`'s self-update only refreshes the npm copy, so updating a different install leaves the floor check failing.\n\nFix proposals:\n1. If `hq doctor` flagged a mechanical wiring defect (a lost executable bit, a hook missing from some gate profiles, an unregistered on-disk hook), propose `hq doctor --fix` — it applies only the allowlisted safe repairs behind a backup, a diff preview, and a dirty-tree refusal, then re-checks\n2. Temporarily disable the failing hook: `export HQ_DISABLED_HOOKS=\u003Cname>` for the next session — emit the export line, do not run it\n3. Switch profile: `export HQ_HOOK_PROFILE=minimal` — useful for hook-storm scenarios\n4. Patch the hook script if the bug is local and obvious (e.g. missing `2>\u002Fdev\u002Fnull`, unquoted path, missing `mkdir -p`) — apply via Edit only if the fix is one or two lines, otherwise propose\n5. If the failing hook is `reindex.sh` (or legacy `master-sync.sh`), escalate to the `reindex` recipe instead\n6. **CLI restore (supply-chain):** if `ERR` mentions `hq-pnpm-min-release-age-supply-chain`, `block-unsafe-package-install`, or a blocked `npm install -g @indigoai-us\u002Fhq-cli`, the CLI is missing or was removed as a duplicate. Do **not** retry npm — PreToolUse blocks it because npm cannot honor `minimumReleaseAge`. Restore with:\n\n   ```\n   pnpm add -g @indigoai-us\u002Fhq-cli@latest --config.minimumReleaseAge=1440\n   ```\n\n   Then confirm `command -v hq` and `HQ_NO_UPDATE_CHECK=1 hq --version`. If pnpm is missing, install pnpm first. An explicit version pin (`npm install -g @indigoai-us\u002Fhq-cli@\u003Cx.y.z>`) is the only npm fallback; `@latest` is never the restore command.\n7. **Stale shadowing install** (the diagnostic above found two copies): update the install that `command -v hq` resolves to. A pnpm wrapper takes the pnpm restore command from item 6; an npm-global or toolchain copy takes the explicit version pin. Do not update the other copy and re-run the check, and do not delete the wrapper unless the user confirms; record both paths and versions in the heal report.\n\n#### `sandbox-network`\n\n`fetch failed` from `hq sync`, `\u002Fhq-sync`, `\u002Fhq-share`, or any `hq` cloud command, with\n`connect EPERM …:443` underneath it, is not an outage. It is the host sandbox denying\noutbound network. DNS resolves, the TCP connect is refused by the OS, and Node's fetch\nwraps it as `fetch failed`. The same sandbox denies writes outside the workspace, which\nis why `~\u002F.hq` lock, package-use lease, and telemetry warnings arrive together with it.\n\nFirst rule out a real outage. If `ERR` carries `ENOTFOUND`, `EAI_AGAIN`, `ECONNREFUSED`,\n`ETIMEDOUT`, `ECONNRESET`, or `EHOSTUNREACH` and no `EPERM`, this is not the sandbox:\nreclassify as `sync` and follow that recipe's transient-network advice (run `\u002Fhq-sync`\nagain after connectivity recovers). The same applies to a bare `fetch failed` with no\ncode underneath: treat it as `sync` unless a host check below proves the sandbox.\n\nOnly with `EPERM` on `connect` (or `CODEX_SANDBOX_NETWORK_DISABLED` set) continue here,\nand do not propose a retry. Confirm the host first:\n\n- `env | grep -E '^CODEX_(SANDBOX|SESSION_ID|SANDBOX_NETWORK_DISABLED)'`\n- `bash core\u002Fscripts\u002Flib\u002Fdetect-codex.sh; echo \"codex-host exit: $?\"`\n- `grep -nE '^(sandbox_mode|approval_policy)|network_access' .codex\u002Fconfig.toml`\n- `HQ_NO_UPDATE_CHECK=1 hq whoami 2>&1 | tail -3` (a `fetch failed` here confirms every HTTPS call is blocked, not just sync)\n\nWhen the host is Codex or the ChatGPT desktop app, report the cause in one line and\npropose exactly these fixes, in this order:\n\n1. In the ChatGPT desktop app, open the permission control under the message box for\n   this chat and switch it to **Full access**, then run `\u002Fhq-sync` again. Ask for\n   approval and Approve for me run commands in the `workspace-write` sandbox, which\n   keeps network off; on macOS the `network_access = true` key in HQ's\n   `.codex\u002Fconfig.toml` is not honored by that sandbox. Full access is the mode HQ\n   ships in its own config (`sandbox_mode = \"danger-full-access\"`).\n2. If Full access is greyed out or the user prefers not to change the chat mode, run\n   the sync outside the sandbox: `hq sync` in Terminal, or the HQ Sync menubar app.\n   Both use the same sync engine and are never sandboxed.\n\nIf the host is not Codex and the error still carries `EPERM` on `connect`, name the\nblocker instead: a corporate proxy, VPN, or endpoint agent that refuses outbound 443\nfor `node`. Point the user at their network admin with the host and port from the\nerror, and do not claim the sync will succeed on retry.\n\n#### `sync`\n\nBranch the recovery on the actual sync signal. First inspect the conflict ledger:\n\n- `[ -f workspace\u002Fsync\u002Fconflicts.json ] && wc -l workspace\u002Fsync\u002Fconflicts.json`\n- `ls workspace\u002Fsync\u002Fconflicts\u002F 2>\u002Fdev\u002Fnull | head`\n\nWhen the ledger contains conflict paths, report the count and sample paths, then\npropose `\u002Fresolve-conflicts`. Apply the *learned rule* from charter: keep local\nwhen `originalPath` is a symlink or an auto-generated artifact (registries,\nINDEX).\n\n`FILES_PRESIGN_STALE_UPLOAD_FORBIDDEN`, `resend_full_scheduled`, and\n`manifest.*throttled` can occur without any conflict-ledger row. In that case,\ndo not propose `\u002Fresolve-conflicts` as the repair. Use `\u002Fhq-sync` to inspect the\n`all-complete` summary and each company's status; `partial` plus `transient`\ndiagnostics identifies retryable interruption. For a transient network result,\ntell the user to run `\u002Fhq-sync` again after connectivity recovers. Report any\nremaining non-complete company status instead of claiming success.\n\n#### `work-registry`\nThe company's work registry is off, so HQ refuses to register work sessions for it. This is a company setting, not a permission problem with the user. It defaults to off until a company owner turns it on. Older hq-cli versions reported it as `AUTH_DENIED`.\n\nDiagnostics:\n- `hq company --company \u003Cslug> settings get` shows both work tracking switches to an owner or admin (`workRegistryEnabled` and `workMeshLiveEnabled`).\n- `hq members list` confirms whether the user is the company owner.\n\nFix proposals:\n1. If the user is the company owner: `hq company --company \u003Cslug> settings set --work-registry-enabled true`. Work tracking also needs live tracking on; if `settings get` shows it off, add `--work-mesh-live-enabled true`. Then each person runs `hq mesh context requeue` once to resend the sessions held on their machine.\n2. If the user is not the owner: tell them the company's work registry is off and only a company owner can turn it on with the command above. Do not retry or requeue until it is on; the ops will be refused again.\n\n#### `access`\n\nA vault path could not be found or opened. Do not diagnose this by hand — the\n`\u002Fhq-access` skill owns the full ladder.\n\nRun `\u002Fhq-access \u003Cpath>` (or `hq access \u003Cpath> --json` directly). It resolves the\ntarget, reports one of `never-existed`, `local`, `not-synced`, or `no-access`,\nfetches and pins the file when the caller has access, repairs sync when the\nfetch fails, and asks the prefix owner for a read grant after exactly one\nconfirmation. Record its outcome in the heal report and stop; there is no\nseparate heal fix for this class.\n\n#### `denylist`\nChecks:\n- Extract the blocked path from `ERR`\n- `grep -nE '\"deny\"|\"Read\"' .claude\u002Fsettings.json | head -20`\n\nFix proposal: explain the rule (`Sensitive Path Deny Lists` from charter), and offer a safe alternative — e.g. ask the user to paste the value, use `hq-secrets`, or for rc-file edits use append-only `printf >>` \u002F pattern-delete `sed '\u002Fpat\u002Fd'`. Never propose removing the deny rule.\n\n#### `mcp`\nChecks:\n- `[ -f .mcp.json ] && jq -r '.mcpServers | keys[]' .mcp.json 2>\u002Fdev\u002Fnull`\n- `ps aux | grep -iE 'mcp|claude' | grep -v grep | head -5`\n- Pull the MCP name from `ERR` if present\n\nFix proposals:\n1. Restart the MCP server (instructions depend on the server — `superhuman-mail`, `vyg-db-mcp`, `Claude_Preview`, etc.)\n2. Re-auth if the failure is `401 \u002F unauthorized`\n3. If the server isn't listed in `.mcp.json`, surface that it isn't configured for this project\n\n#### `qmd`\nChecks:\n- `which qmd && qmd --version 2>\u002Fdev\u002Fnull`\n- `qmd collections 2>\u002Fdev\u002Fnull | head -20`\n- `[ -d .qmd ] && du -sh .qmd 2>\u002Fdev\u002Fnull`\n\nFix proposal: `qmd update 2>\u002Fdev\u002Fnull || true`. If a specific collection is missing, surface its expected path and offer to re-add it.\n\n#### `reindex`\nApply the learned rule from charter: trace `core\u002F\u003Ctype>` symlinks back to `personal\u002F\u003Ctype>\u002F` and look for `find -L` recursion into `_overrides\u002F` or other stale mirrored snapshots.\n\nChecks:\n- `find -L core\u002Fworkers core\u002Fpolicies -maxdepth 3 -type d -name '_overrides' 2>\u002Fdev\u002Fnull | head`\n- `ls -la personal\u002Fworkers\u002F personal\u002Fpolicies\u002F 2>\u002Fdev\u002Fnull | head -20`\n- `tail -30 workspace\u002Flogs\u002Freindex.log 2>\u002Fdev\u002Fnull` (if present)\n\nFix proposal: remove stale `_overrides\u002F` snapshots (with `--dry-run` first), or patch `core\u002Fscripts\u002Fgenerate-workers-registry.sh` to skip `*\u002F_overrides\u002F*` if not already patched. Surface the exact rm command for user confirmation — do not auto-remove.\n\n#### `symlink`\nChecks:\n- Grep `ERR` for the broken path; if found, `ls -la \u003Cpath>` and `readlink \u003Cpath>`\n- Common legitimate HQ symlinks to verify: `AGENTS.md` and `.claude\u002Fskills\u002Fpersonal:*`\n- Company knowledge under `companies\u002F*\u002Fknowledge\u002F` must be a plain real directory with no embedded Git metadata or symlink. Personal knowledge may be a real directory with embedded Git. Under `core\u002Fknowledge\u002F`, a package-managed link into `core\u002Fpackages\u002F*\u002Fknowledge\u002F` is valid; a link to a separate git repository is a migration violation.\n\nFix proposal: for legitimate non-knowledge links, re-create the symlink with an absolute path under `$HOME\u002FDocuments\u002FHQ\u002F` only if the target is unambiguous. For knowledge, materialize the content at the canonical path and verify it is not a symlink.\n\n#### `git-object-store`\nThese errors read like history loss, so the instinct is to reach for `git gc`, a reclone, or `--prune`. Do NOT start there — check for a mechanical cause first, because the most common one destroys nothing and is repaired by a rename.\n\n**macOS `Icon\\r` files inside `.git`.** If `ERR` mentions `Error building trees`, `invalid object`, `badRefName`, `bad sha1 file`, or `Icon\\r`, run this probe before the pack check (report-only; it never deletes without `--fix`):\n\n```bash\nbash core\u002Fscripts\u002Fgit-icon-file-check.sh --root .\n```\n\nFinder writes a file named `Icon` plus a carriage return into folders with a custom icon, and iCloud Desktop & Documents sync copies them into `.git\u002Frefs`, `.git\u002Fobjects\u002Fxx` and `.git\u002Flogs`. The working-tree `.gitignore` does not reach inside `.git`. Git then reports `badRefName` and `bad sha1 file`, and when a loose object went missing at the same time every commit fails with `invalid object ... Error building trees`.\n\n- Exit 0 → no `Icon\\r` files and no index entry is missing its object. Continue with the pack check that follows.\n- Exit 2 → show the user the reported files and missing objects and propose `--fix` as a numbered fix. On confirmation, run `bash core\u002Fscripts\u002Fgit-icon-file-check.sh --root . --fix`. It deletes only files named exactly `Icon\\r` under `.git`, runs `git fsck`, and restores a missing blob with `git hash-object -w` only when the working file hashes to exactly that id. It never writes an object from a file that differs. Exit 0 means `git fsck` is clean; exit 2 lists what is still broken. Do not run `git gc --prune` on what remains.\n- Never hand-roll `find .git -name 'Icon*' -delete`: that glob also matches real files such as `Icons`.\n- When the probe prints `warning: ... iCloud`, tell the user the files will come back until the HQ folder moves out of Desktop and Documents (for example to `~\u002Fhq`) or \"Desktop & Documents Folders\" is turned off in iCloud Drive settings.\n\nThen run the pack probe (report-only; it never renames without `--fix`):\n\n```bash\nbash core\u002Fscripts\u002Fgit-pack-extension-check.sh --root .\n```\n\nA packfile set is three files sharing a basename — `pack-\u003Csha>.pack`, `.idx`, `.rev` — and git pairs them **by extension**. If any one of them loses its extension, git stops seeing the whole set: the objects are still on disk byte for byte, but they become unreachable, and git reports them as missing. `git fsck` will agree they are gone and `git gc` cannot help, because nothing is corrupt.\n\n- Exit 0 → the pack set is intact; this is a different problem. Go on to `git fsck --full`, check `.git\u002Fobjects\u002Finfo\u002Falternates`, and look for genuinely truncated or zero-length loose objects.\n- Exit 2 → an orphan was found. Show the user the reported filename and propose the rename as a numbered fix. On confirmation, re-run with `--fix`, then verify with `git -C \u003Croot> fsck` and `git -C \u003Croot> status`.\n\nIf the probe is clean but the index still reports a stale cached tree, `git read-tree HEAD` rebuilds the index from HEAD without touching working files (it does unstage anything currently staged).\n\nWorth surfacing to the user: git never writes an extensionless `pack-*` file, so if one exists, something outside git renamed it. On macOS that usually means a folder-level sync or backup agent walking the tree — the same class of tool that scatters `Icon\\r` files. Ask whether the HQ root sits inside iCloud Drive, Dropbox, or a backup target, since the repair will not hold if the cause is still running.\n\n#### `git-root`\nRead first 30 lines of `.claude\u002Fhooks\u002Fblock-hq-root-git-mutation.sh` to surface the rule. Show the user the correct invocation form: `git -C \u002Fabs\u002Fpath \u003Ccmd>` or `( cd \u002Fabs\u002Fpath && git \u003Ccmd> )` or `gh ... -R owner\u002Frepo`. For sanctioned HQ-internal git work, surface `HQ_ALLOW_HQ_ROOT_GIT=1 git ...`. No file mutations.\n\nIf the HQ root's `.git` is missing, or the HQ root records nested company or project repos as gitlinks (mode `160000`), never hand-roll `git init && git add -A`: that records every nested repo as a gitlink with no `.gitmodules`. Use the helper instead:\n\n```bash\nbash core\u002Fscripts\u002Fhq-root-git-reinit.sh --check    # report gitlinks (exit 2 when found)\nbash core\u002Fscripts\u002Fhq-root-git-reinit.sh --reinit   # .git is missing: init, exclude nested repos, commit\nbash core\u002Fscripts\u002Fhq-root-git-reinit.sh --repair   # gitlinks already recorded: index-only removal + exclude\n```\n\nPropose `--reinit` or `--repair` as a numbered fix and run it only after the user confirms. Nested repos are listed in `.git\u002Finfo\u002Fexclude`; their files and history are not touched.\n\n#### `plan-mode`\nSurface: in plan mode, the model can Read\u002FGlob\u002FGrep but cannot Edit\u002FWrite. To exit, call `ExitPlanMode` (deferred tool — load via ToolSearch). No file mutations needed; this is purely an explainer.\n\n#### `unknown`\nRun a minimal triage:\n- `bash core\u002Fscripts\u002Fhq-session.sh 2>\u002Fdev\u002Fnull` (if present) to dump session context\n- `git -C . status --short | head -10`\n- `hq whoami 2>\u002Fdev\u002Fnull` to confirm identity\n\nThen ask the user three numbered follow-up questions via `AskUserQuestion`:\n1. When did the error first appear (this turn \u002F earlier in session \u002F right at session start)?\n2. Has anything in HQ changed recently (`\u002Fupdate-hq`, new hook, new policy)?\n3. Does the error reproduce in a fresh session (run `bash .claude\u002Fskills\u002Fhq-heal\u002Fhq-heal.sh --bare \"\u003Cerror>\"` to test)?\n\n### 4. Propose the fix\n\nFormat the proposal as a numbered list (1-4 options max), one option per line, with the safest option first. Always include an explicit \"Do nothing — just save report\" choice.\n\nIf `--dry-run` was passed, skip the apply step entirely; report the proposed fix and stop.\n\nOtherwise, use `AskUserQuestion` to surface the numbered options. Wait for the answer. Apply the chosen fix only.\n\n**Safety rules for the apply step:**\n- Never auto-edit policies, hooks, or `core.yaml` without explicit user confirmation\n- Never delete files — surface the rm command and let the user run it\n- Never run `git push`, `git reset --hard`, or any rc-file rewrite\n- Never read sensitive deny-listed paths even to diagnose\n- For multi-step fixes, apply one step, re-run a minimal diagnostic, then proceed\n\n**Core-divergence handling (`core\u002F` mirror):**\n- HQ's `core\u002F` tree is mechanically write-blocked by `.claude\u002Fhooks\u002Fblock-core-writes.sh` because it is a downstream mirror of `hq-core`. Heal usually routes fixes through `personal\u002F\u003Ctype>\u002F\u003Cname>\u002F` (read directly from `personal\u002F` — the old symlink mirror into `core\u002F` was retired) or co-locates with a skill (`.claude\u002Fskills\u002F\u003Cname>\u002F`) — never into `core\u002F` directly.\n- Genuine exception: the failing artifact *is* a core file (a broken `core\u002Fscripts\u002F*.sh` hook helper, a stale `core\u002Fpolicies\u002F\u003Cname>.md`, etc.) and the fix cannot land anywhere else. In that case:\n  1. The numbered proposal must call out that the fix diverges from upstream — exact files listed\n  2. The user must have passed `--allow-core` (the flag is the explicit acknowledgment that this divergence is intentional)\n  3. Each individual Write\u002FEdit\u002FBash call that touches a `core\u002F` path must be prefixed with `HQ_BYPASS_CORE_PROTECT=1`\n  4. The heal report (Step 5) gets a `## Core divergence` section listing every `core\u002F` path touched, the old content (first 30 lines), and the new content (first 30 lines)\n  5. The auto-filed bug (Step 6) is escalated from `bug` to `feature` if the divergence implies a policy \u002F hook change upstream wants — the body explicitly names which upstream file needs the corresponding patch in `hq-core`\n- If `--allow-core` is missing and the only viable fix is a `core\u002F` edit, do not apply anything — surface the proposed diff in the report (as a *would-have-applied* block) and stop with a one-liner telling the user to re-invoke `\u002Fhq-heal --allow-core \u003Csame args>`.\n\n### 5. Write the heal report\n\nPath: `workspace\u002Freports\u002Fhq-heal\u002F{YYYYMMDD-HHMMSS}-{class}.md`.\n\nTemplate:\n\n```markdown\n# HQ Heal Report — {class}\n\nTimestamp: {iso8601}\nSession: {session_id_or_unknown}\nTriggered by: \u002Fhq-heal {$ARGUMENTS first 80 chars}\n\n## Error captured\n\n```\n{ERR, max 2 KB}\n```\n\n## Classification\n\n{class} — matched on `{trigger_phrase}`\n\n## Diagnostics\n\n{output of the recipe checks, max 3 KB}\n\n## Fix proposed\n\n{numbered options shown to user}\n\n## Fix applied\n\n{user's chosen option, or \"dry-run — none applied\" if --dry-run}\n\n## Outcome\n\n{1-3 sentences: did the proposed fix resolve, was a follow-up needed, what to watch next session}\n\n## Core divergence\n\n{omit this section unless --allow-core was passed AND a core\u002F path was touched. List every core\u002F file touched, the old content (first 30 lines), the new content (first 30 lines), and a 1-line justification for why the fix could not land in personal\u002F or a co-located skill folder.}\n```\n\nAppend a one-line entry to `workspace\u002Freports\u002Fhq-heal\u002FINDEX.md` (create if missing) with the timestamp, class, and outcome status.\n\n### 6. File an HQ bug (default on)\n\nUnless `--no-bug` was passed, file a bug report via the `\u002Fhq-bug` skill so HQ engineering accumulates signal on which error classes are recurring and which heal flows actually fixed them. This step runs **after** the heal report has been written so the report path can be referenced from the bug body.\n\nBuild the bug as follows:\n\n- **Type**: `bug` by default. Escalate to `feature` if the fix touched `core\u002F` (i.e. the `## Core divergence` section is non-empty) — the engineering follow-up needed is an upstream patch, which is a feature ask, not a bug report\n- **Title**: `hq-heal: {class} — {one-line summary of the fix applied}` (truncate the summary to keep the whole title under 80 chars)\n- **Body sections** (the `\u002Fhq-bug` skill assembles its own four-section template; heal augments by setting `$ARGUMENTS` to a single line so the skill captures the right title, and by ensuring the rendered body references the heal report path verbatim):\n  - The heal report path: `workspace\u002Freports\u002Fhq-heal\u002F{filename}.md` — engineering reads this for the raw error, classification, diagnostics, and applied fix\n  - The error class\n  - The fix that was applied (or `dry-run — none applied`)\n  - If `## Core divergence` was set, the list of `core\u002F` files touched + the upstream `hq-core` path they map to (e.g. `core\u002Fscripts\u002F\u003Cname>.sh` → `https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002Fcore\u002Fscripts\u002F\u003Cname>.sh`)\n\nInvocation: call the `\u002Fhq-bug` skill via the `Skill` tool with the bug type and title as args. Do not shell out to `hq feedback` directly — `\u002Fhq-bug` already wraps the CLI with the right body-file allocation, CWD capture, and session-context assembly.\n\nIf the `\u002Fhq-bug` skill is missing on this HQ (e.g. running an older release), fall back to a single-line stderr notice in the heal report's `## Outcome` section: *\"hq-bug filing skipped — `\u002Fhq-bug` skill not installed.\"* Do not block the heal flow on bug-filing failure — heal report is the durable artifact, bug filing is secondary signal.\n\nIf `--dry-run` was passed at invocation, also skip the bug-filing step — dry-run is observation only.\n\n### 7. Surface the next step\n\nPrint a short, four-line summary to the user:\n\n```\nHeal complete — class: {class}\nApplied: {what was done, or \"nothing — dry-run\"}\nReport:  workspace\u002Freports\u002Fhq-heal\u002F{filename}.md\nBug:     {hq-bug URL or 'skipped (--no-bug)' or 'skipped (dry-run)' or 'skipped (\u002Fhq-bug missing)'}\n```\n\nIf `--allow-core` was used and the `## Core divergence` section was written, append one extra line: *\"Core divergence noted — `{N}` `core\u002F` files touched. Upstream patch needed in hq-core.\"*\n\nIf the proposed fix requires re-launching the session (e.g. autocompact, reindex), append: *\"Re-launch suggestion: `bash .claude\u002Fskills\u002Fhq-heal\u002Fhq-heal.sh --resume`\"* and stop.\n\n## Rules\n\n- Heal stays HQ-internal — never load `companies\u002F*\u002Fknowledge\u002F`, `companies\u002Fmanifest.yaml` body, INDEX.md, or `handoff.json`\n- Never read sensitive deny-listed paths under any circumstance, even when classifying a `denylist` error\n- Recipe context budget is 5 KB per class — if a probe would return more, summarize\n- The classifier is pure pattern matching — do not run subagents or do any HQ-wide search before classification\n- Never auto-apply fixes for `denylist`, `git-root`, `reindex`, or `git-object-store` classes — always require user confirmation, the consequences are too broad. For `git-object-store` the probe is safe to run unattended because it only reports; it is the `--fix` rename that needs confirmation\n- Never restore the `hq` CLI with `npm install -g @indigoai-us\u002Fhq-cli@latest`. That command is blocked by `hq-pnpm-min-release-age-supply-chain`. Use `pnpm add -g @indigoai-us\u002Fhq-cli@latest --config.minimumReleaseAge=1440`.\n- The heal report is the single durable artifact — it is what `\u002Fhandoff` and future `\u002Fhq-heal` invocations consult to detect repeat failures\n- The `\u002Fhq-bug` filing in Step 6 is the *signal* artifact — durable artifact stays local, signal goes to HQ engineering so recurring error classes get systemized fixes upstream. `--no-bug` suppresses the filing only; the report still writes\n- Core-mirror writes are off by default. The `--allow-core` flag is required even when the user explicitly confirms a fix that touches `core\u002F`. This is intentional friction — the bypass should be auditable per-invocation, not implicit\n- This skill must remain runnable in `--bare` mode (no hooks, no MCPs) so it stays usable when hooks or MCPs are the failure mode being diagnosed\n- Companion to `\u002Frecover-session` (post-mortem on a dead JSONL) — `\u002Fhq-heal` is mid-session triage and may invoke `\u002Frecover-session` as its fix for the `autocompact` class\n- Promotion: this skill lives at `.claude\u002Fskills\u002Fhq-heal\u002F` locally; to ship it to other HQs, stage it in the hq-core staging repo and publish via `\u002Fpromote-hq-core` per the `staging-promotion-required` policy\n- The launcher `hq-heal.sh` is co-located with the skill (`.claude\u002Fskills\u002Fhq-heal\u002Fhq-heal.sh`) rather than placed under `core\u002Fscripts\u002F`, because `core\u002F` is hook-protected (`block-core-writes`) — promotion happens via the staging hop, not direct writes\n\n## Why this exists\n\nHQ users hit a recurring class of errors that look scary but are well-understood once classified — autocompact thrashing, hook crashes, sync conflicts, deny-list blocks, reindex aborts. Without a healer, the recovery path is for the user to switch terminals, paste the error into a fresh Claude session, and hope the new session figures out what to do. `\u002Fhq-heal` collapses that into one slash command with a known-good triage recipe per error class, and a companion launcher (`.claude\u002Fskills\u002Fhq-heal\u002Fhq-heal.sh`) for the case where the current session is too wedged to invoke the slash command at all.\n\n## See also\n\n- `\u002Fresolve-conflicts` — pick local\u002Fcloud on a conflict\n- `\u002Frecover-session` — restore a lost session\n","# HQ Heal — Session Error Triage\n\nWhen a Claude Code or Codex session in HQ surfaces an error, run this skill to classify the error, run targeted diagnostics, and either apply a safe fix automatically or surface a numbered fix proposal for confirmation. Writes a heal report under `workspace\u002Freports\u002Fhq-heal\u002F`.\n\n**User input:** `$ARGUMENTS`\n\n## Arguments\n\nThe first argument shapes how the error is collected. Everything after the flag (or the whole string if no flag is present) is treated as the error text.\n\n- `(no args)` → use `AskUserQuestion` to ask the user to paste the error text.\n- `\u003Cfree text>` → treat the entire argument string as the error text.\n- `--last-session` → scan the most recent JSONL under `~\u002F.claude\u002Fprojects\u002F-Users-*-Documents-HQ\u002F` for the trailing error (uses the streaming Python pattern from `.claude\u002Fskills\u002Frecover-session\u002FSKILL.md` step 3 — never read the full file).\n- `--class \u003Cname>` → skip classification and jump straight to the diagnostics recipe for that class. Valid: `autocompact`, `hook`, `sandbox-network`, `sync`, `work-registry`, `denylist`, `mcp`, `qmd`, `reindex`, `symlink`, `git-root`, `git-object-store`, `plan-mode`, `unknown`.\n- `--dry-run` → diagnose and propose but do not apply any fix.\n- `--no-bug` → suppress the automatic `\u002Fhq-bug` filing step. By default, every heal run files a bug so HQ engineering accumulates signal on which error classes are recurring (see Step 6).\n- `--allow-core` → permit the apply step to edit files under `core\u002F` (the hook-protected mirror) by prefixing the offending Write\u002FEdit\u002FBash call with `HQ_BYPASS_CORE_PROTECT=1`. Off by default — heal will refuse a core edit and require this flag to be passed, even when the user confirms the numbered fix. Always documented in the heal report and the filed bug (see Step 5 + Step 6).\n\n## Process\n\n### 1. Capture the error text\n\nIf `$ARGUMENTS` is empty, ask: *\"Paste the error message you're seeing (or describe what went wrong).\"* Wait for response, treat that as the error text.\n\nIf `--last-session`, run a Python streaming extract that scans the last 200 lines of the most recently modified JSONL for any of these signals: `Prompt is too long`, `Conversation too long`, `Error during compaction`, `Autocompact is thrashing`, `permission denied`, `EACCES`, `hook .* failed`, `block-hq-root-git-mutation`, `MCP server .* failed`, `qmd: error`, `reindex.sh.*abort` (legacy `master-sync.sh.*abort`), `FILES_PRESIGN_STALE_UPLOAD_FORBIDDEN`, `resend_full_scheduled`, `manifest.*throttled`, `fetch failed`, `connect EPERM`, `EPERM`, or `WORK_REGISTRY_DISABLED`. Capture the matched line plus 2 lines of surrounding context. Truncate to 2 KB.\n\nStore the resulting text in a local variable called `ERR`.\n\n### 2. Classify the error\n\nUnless `--class` is set, walk the pattern table top-to-bottom; first match wins. The classifier is pure pattern matching on `ERR` — do not load any other HQ context yet.\n\n| Class | Triggers (case-insensitive substring or regex on `ERR`) |\n|---|---|\n| `autocompact` | `Autocompact is thrashing`, `Prompt is too long`, `Conversation too long`, `Error during compaction`, `context refilled to the limit` |\n| `hook` | `hook .* failed`, `PreToolUse .* blocked`, `PostToolUse hook`, `hook-gate.sh`, `non-zero exit from hook` |\n| `sandbox-network` | `connect EPERM`, `EPERM .*:443`, `CODEX_SANDBOX_NETWORK_DISABLED`, `sandbox.*(network|egress)` — the OS refused an outbound HTTPS connect, or a write outside the workspace, under a Codex or ChatGPT desktop app sandbox. A bare `fetch failed` with no EPERM underneath is NOT this class: it stays with `sync` (offline, refused, timeout) |\n| `sync` | `hq sync .* conflict`, `conflictPath`, `resolve-conflicts`, `hq-sync.*error`, `originalPath.*conflict`, `FILES_PRESIGN_STALE_UPLOAD_FORBIDDEN`, `resend_full_scheduled`, `manifest.*throttled` |\n| `work-registry` | `WORK_REGISTRY_DISABLED`, `work-mesh.*register.*AUTH_DENIED`, `register.*quarantined.*AUTH_DENIED` — a work-mesh session register was refused. Older hq-cli versions (before 5.345.150) recorded the company's work registry being off as `AUTH_DENIED` in the outbox |\n| `access` | `caller lacks '.*' on '.*'`, `403 Forbidden`, `Access denied`, `AccessDenied`, `no such key`, `NoSuchKey`, `not found` (when the path is under `companies\u002F`) |\n| `denylist` | `Read access blocked`, `denied by settings`, `~\u002F.ssh`, `~\u002F.aws\u002Fcredentials`, `~\u002F.zshrc`, `permission rule .* deny` |\n| `mcp` | `MCP server .* (failed|disconnected|timeout)`, `Error connecting to MCP`, `tool .* not found` (when the tool name matches a known MCP) |\n| `qmd` | `qmd: error`, `qmd .* index`, `collection .* not found`, `qmd update` failures |\n| `reindex` | `reindex.sh`, `master-sync.sh`, `duplicate worker id`, `personal\u002F\u003Ctype>\u002F\u003Centry>.*already exists` |\n| `symlink` | `Too many levels of symbolic links`, `ELOOP`, `dangling symlink`, `readlink: .* No such file` |\n| `git-object-store` | `unable to read tree`, `bad tree object`, `cannot read commit object`, `invalid sha1 pointer`, `fatal: bad object`, `object file .* is empty`, `packfile .* (cannot|does not)`, `Error building trees`, `invalid object [0-7]+ [0-9a-f]+`, `badRefName`, `bad sha1 file`, `Icon\\r` |\n| `git-root` | `block-hq-root-git-mutation`, `git .* blocked from HQ root`, `HQ_ALLOW_HQ_ROOT_GIT` |\n| `plan-mode` | `plan mode`, `ExitPlanMode required`, `cannot Edit in plan mode` |\n| `unknown` | (no match) |\n\nBind `CLASS` to the matched class name.\n\n### 3. Run the diagnostics recipe for `CLASS`\n\nEach recipe is intentionally narrow: a small, parallel set of reads and shell probes that gather just enough state to propose a fix. Never load company knowledge, INDEX.md, or `companies\u002Fmanifest.yaml` here — heal stays HQ-internal.\n\n#### `autocompact`\nParallel checks:\n- `wc -l ~\u002F.claude\u002Fprojects\u002F-Users-*-Documents-HQ\u002F*.jsonl 2>\u002Fdev\u002Fnull | tail -5` — recent session sizes\n- `du -sh ~\u002F.claude\u002Fprojects\u002F-Users-*-Documents-HQ\u002F 2>\u002Fdev\u002Fnull` — total session bloat\n- `ls -lhS workspace\u002Fthreads\u002F*.json 2>\u002Fdev\u002Fnull | head -3` — large thread files\n- If `--last-session` was used, identify the single largest tool result in the matched JSONL (Python streaming, return tool name + size only)\n\nFix proposals (ranked):\n1. `\u002Fclear` and resume work — fastest if the session has accumulated stale tool results\n2. `\u002Frecover-session --session \u003Cuuid>` — reconstruct a thread from the dead JSONL, then start fresh\n3. Identify the offending tool call and recommend a smaller-scope alternative (e.g. `qmd search -c hq-infra \u003Cterm>` instead of reading a multi-MB INDEX, or `Read` with `offset:`\u002F`limit:` instead of full-file reads)\n4. If a file repeatedly bloats context, propose moving it out of auto-load paths (e.g. very large `INDEX.md`, `quick-reference.md`)\n\n#### `hook`\nFirst diagnostic step — run `hq doctor`, the authoritative hook wiring\u002Ffiring\ndiagnostic (US-012):\n- `hq doctor` (or `hq doctor --json` for machine-readable findings) — it enumerates\n  every hook registration across Claude\u002FCodex\u002FGrok, verifies the referenced\n  scripts exist and are executable, checks three-profile membership, and reports\n  via the runtime probe whether hooks actually fired this session. Read its\n  `FAIL`\u002F`UNKNOWN` results and their `remediation` fields to target the checks\n  below. For a deeper confirmation that a specific guard actually blocks, run\n  `hq doctor --deep-test`.\n- If `hq doctor` is unavailable (older HQ without the CLI command), fall back to\n  `bash core\u002Fscripts\u002Fcheck-hq-hooks.sh --root . --require-ledger`, which degrades\n  to the same check inline.\n\nThen the targeted parallel checks:\n- `cat .claude\u002Fsettings.json | grep -E '\"(PreToolUse|PostToolUse|SessionStart|Stop|PreCompact)\"' | head` — confirm hook chain is intact\n- `echo \"HQ_HOOK_PROFILE=$HQ_HOOK_PROFILE  HQ_DISABLED_HOOKS=$HQ_DISABLED_HOOKS\"`\n- Grep `ERR` for the hook script name; if found, `ls -la .claude\u002Fhooks\u002F\u003Cname>.sh` and read its first 40 lines\n- **Stale shadowing CLI install** (feedback e49ce279): if `ERR` says `unknown command 'lanes'`, `needs hq-cli >= X (found Y)`, or `hq CLI is missing from PATH`, run `command -v hq`, `ls -l \"$(command -v hq)\"` and `HQ_NO_UPDATE_CHECK=1 hq --version`. A wrapper such as `~\u002F.local\u002Fbin\u002Fhq` that execs `$HOME\u002FLibrary\u002Fpnpm\u002Fhq` means two installs exist (pnpm and npm-global, or a stale `~\u002F.local` copy next to the auto-updated one). List them: `pnpm ls -g @indigoai-us\u002Fhq-cli 2>\u002Fdev\u002Fnull`, `npm ls -g @indigoai-us\u002Fhq-cli --depth=0 2>\u002Fdev\u002Fnull`, `ls \"$HOME\u002FLibrary\u002FApplication Support\u002FIndigo HQ\u002Ftoolchain\u002Fnpm-global\u002Fbin\u002Fhq\" 2>\u002Fdev\u002Fnull`. The copy that `command -v hq` resolves to is the one the hooks run; `hq doctor`'s self-update only refreshes the npm copy, so updating a different install leaves the floor check failing.\n\nFix proposals:\n1. If `hq doctor` flagged a mechanical wiring defect (a lost executable bit, a hook missing from some gate profiles, an unregistered on-disk hook), propose `hq doctor --fix` — it applies only the allowlisted safe repairs behind a backup, a diff preview, and a dirty-tree refusal, then re-checks\n2. Temporarily disable the failing hook: `export HQ_DISABLED_HOOKS=\u003Cname>` for the next session — emit the export line, do not run it\n3. Switch profile: `export HQ_HOOK_PROFILE=minimal` — useful for hook-storm scenarios\n4. Patch the hook script if the bug is local and obvious (e.g. missing `2>\u002Fdev\u002Fnull`, unquoted path, missing `mkdir -p`) — apply via Edit only if the fix is one or two lines, otherwise propose\n5. If the failing hook is `reindex.sh` (or legacy `master-sync.sh`), escalate to the `reindex` recipe instead\n6. **CLI restore (supply-chain):** if `ERR` mentions `hq-pnpm-min-release-age-supply-chain`, `block-unsafe-package-install`, or a blocked `npm install -g @indigoai-us\u002Fhq-cli`, the CLI is missing or was removed as a duplicate. Do **not** retry npm — PreToolUse blocks it because npm cannot honor `minimumReleaseAge`. Restore with:\n\n   ```\n   pnpm add -g @indigoai-us\u002Fhq-cli@latest --config.minimumReleaseAge=1440\n   ```\n\n   Then confirm `command -v hq` and `HQ_NO_UPDATE_CHECK=1 hq --version`. If pnpm is missing, install pnpm first. An explicit version pin (`npm install -g @indigoai-us\u002Fhq-cli@\u003Cx.y.z>`) is the only npm fallback; `@latest` is never the restore command.\n7. **Stale shadowing install** (the diagnostic above found two copies): update the install that `command -v hq` resolves to. A pnpm wrapper takes the pnpm restore command from item 6; an npm-global or toolchain copy takes the explicit version pin. Do not update the other copy and re-run the check, and do not delete the wrapper unless the user confirms; record both paths and versions in the heal report.\n\n#### `sandbox-network`\n\n`fetch failed` from `hq sync`, `\u002Fhq-sync`, `\u002Fhq-share`, or any `hq` cloud command, with\n`connect EPERM …:443` underneath it, is not an outage. It is the host sandbox denying\noutbound network. DNS resolves, the TCP connect is refused by the OS, and Node's fetch\nwraps it as `fetch failed`. The same sandbox denies writes outside the workspace, which\nis why `~\u002F.hq` lock, package-use lease, and telemetry warnings arrive together with it.\n\nFirst rule out a real outage. If `ERR` carries `ENOTFOUND`, `EAI_AGAIN`, `ECONNREFUSED`,\n`ETIMEDOUT`, `ECONNRESET`, or `EHOSTUNREACH` and no `EPERM`, this is not the sandbox:\nreclassify as `sync` and follow that recipe's transient-network advice (run `\u002Fhq-sync`\nagain after connectivity recovers). The same applies to a bare `fetch failed` with no\ncode underneath: treat it as `sync` unless a host check below proves the sandbox.\n\nOnly with `EPERM` on `connect` (or `CODEX_SANDBOX_NETWORK_DISABLED` set) continue here,\nand do not propose a retry. Confirm the host first:\n\n- `env | grep -E '^CODEX_(SANDBOX|SESSION_ID|SANDBOX_NETWORK_DISABLED)'`\n- `bash core\u002Fscripts\u002Flib\u002Fdetect-codex.sh; echo \"codex-host exit: $?\"`\n- `grep -nE '^(sandbox_mode|approval_policy)|network_access' .codex\u002Fconfig.toml`\n- `HQ_NO_UPDATE_CHECK=1 hq whoami 2>&1 | tail -3` (a `fetch failed` here confirms every HTTPS call is blocked, not just sync)\n\nWhen the host is Codex or the ChatGPT desktop app, report the cause in one line and\npropose exactly these fixes, in this order:\n\n1. In the ChatGPT desktop app, open the permission control under the message box for\n   this chat and switch it to **Full access**, then run `\u002Fhq-sync` again. Ask for\n   approval and Approve for me run commands in the `workspace-write` sandbox, which\n   keeps network off; on macOS the `network_access = true` key in HQ's\n   `.codex\u002Fconfig.toml` is not honored by that sandbox. Full access is the mode HQ\n   ships in its own config (`sandbox_mode = \"danger-full-access\"`).\n2. If Full access is greyed out or the user prefers not to change the chat mode, run\n   the sync outside the sandbox: `hq sync` in Terminal, or the HQ Sync menubar app.\n   Both use the same sync engine and are never sandboxed.\n\nIf the host is not Codex and the error still carries `EPERM` on `connect`, name the\nblocker instead: a corporate proxy, VPN, or endpoint agent that refuses outbound 443\nfor `node`. Point the user at their network admin with the host and port from the\nerror, and do not claim the sync will succeed on retry.\n\n#### `sync`\n\nBranch the recovery on the actual sync signal. First inspect the conflict ledger:\n\n- `[ -f workspace\u002Fsync\u002Fconflicts.json ] && wc -l workspace\u002Fsync\u002Fconflicts.json`\n- `ls workspace\u002Fsync\u002Fconflicts\u002F 2>\u002Fdev\u002Fnull | head`\n\nWhen the ledger contains conflict paths, report the count and sample paths, then\npropose `\u002Fresolve-conflicts`. Apply the *learned rule* from charter: keep local\nwhen `originalPath` is a symlink or an auto-generated artifact (registries,\nINDEX).\n\n`FILES_PRESIGN_STALE_UPLOAD_FORBIDDEN`, `resend_full_scheduled`, and\n`manifest.*throttled` can occur without any conflict-ledger row. In that case,\ndo not propose `\u002Fresolve-conflicts` as the repair. Use `\u002Fhq-sync` to inspect the\n`all-complete` summary and each company's status; `partial` plus `transient`\ndiagnostics identifies retryable interruption. For a transient network result,\ntell the user to run `\u002Fhq-sync` again after connectivity recovers. Report any\nremaining non-complete company status instead of claiming success.\n\n#### `work-registry`\nThe company's work registry is off, so HQ refuses to register work sessions for it. This is a company setting, not a permission problem with the user. It defaults to off until a company owner turns it on. Older hq-cli versions reported it as `AUTH_DENIED`.\n\nDiagnostics:\n- `hq company --company \u003Cslug> settings get` shows both work tracking switches to an owner or admin (`workRegistryEnabled` and `workMeshLiveEnabled`).\n- `hq members list` confirms whether the user is the company owner.\n\nFix proposals:\n1. If the user is the company owner: `hq company --company \u003Cslug> settings set --work-registry-enabled true`. Work tracking also needs live tracking on; if `settings get` shows it off, add `--work-mesh-live-enabled true`. Then each person runs `hq mesh context requeue` once to resend the sessions held on their machine.\n2. If the user is not the owner: tell them the company's work registry is off and only a company owner can turn it on with the command above. Do not retry or requeue until it is on; the ops will be refused again.\n\n#### `access`\n\nA vault path could not be found or opened. Do not diagnose this by hand — the\n`\u002Fhq-access` skill owns the full ladder.\n\nRun `\u002Fhq-access \u003Cpath>` (or `hq access \u003Cpath> --json` directly). It resolves the\ntarget, reports one of `never-existed`, `local`, `not-synced`, or `no-access`,\nfetches and pins the file when the caller has access, repairs sync when the\nfetch fails, and asks the prefix owner for a read grant after exactly one\nconfirmation. Record its outcome in the heal report and stop; there is no\nseparate heal fix for this class.\n\n#### `denylist`\nChecks:\n- Extract the blocked path from `ERR`\n- `grep -nE '\"deny\"|\"Read\"' .claude\u002Fsettings.json | head -20`\n\nFix proposal: explain the rule (`Sensitive Path Deny Lists` from charter), and offer a safe alternative — e.g. ask the user to paste the value, use `hq-secrets`, or for rc-file edits use append-only `printf >>` \u002F pattern-delete `sed '\u002Fpat\u002Fd'`. Never propose removing the deny rule.\n\n#### `mcp`\nChecks:\n- `[ -f .mcp.json ] && jq -r '.mcpServers | keys[]' .mcp.json 2>\u002Fdev\u002Fnull`\n- `ps aux | grep -iE 'mcp|claude' | grep -v grep | head -5`\n- Pull the MCP name from `ERR` if present\n\nFix proposals:\n1. Restart the MCP server (instructions depend on the server — `superhuman-mail`, `vyg-db-mcp`, `Claude_Preview`, etc.)\n2. Re-auth if the failure is `401 \u002F unauthorized`\n3. If the server isn't listed in `.mcp.json`, surface that it isn't configured for this project\n\n#### `qmd`\nChecks:\n- `which qmd && qmd --version 2>\u002Fdev\u002Fnull`\n- `qmd collections 2>\u002Fdev\u002Fnull | head -20`\n- `[ -d .qmd ] && du -sh .qmd 2>\u002Fdev\u002Fnull`\n\nFix proposal: `qmd update 2>\u002Fdev\u002Fnull || true`. If a specific collection is missing, surface its expected path and offer to re-add it.\n\n#### `reindex`\nApply the learned rule from charter: trace `core\u002F\u003Ctype>` symlinks back to `personal\u002F\u003Ctype>\u002F` and look for `find -L` recursion into `_overrides\u002F` or other stale mirrored snapshots.\n\nChecks:\n- `find -L core\u002Fworkers core\u002Fpolicies -maxdepth 3 -type d -name '_overrides' 2>\u002Fdev\u002Fnull | head`\n- `ls -la personal\u002Fworkers\u002F personal\u002Fpolicies\u002F 2>\u002Fdev\u002Fnull | head -20`\n- `tail -30 workspace\u002Flogs\u002Freindex.log 2>\u002Fdev\u002Fnull` (if present)\n\nFix proposal: remove stale `_overrides\u002F` snapshots (with `--dry-run` first), or patch `core\u002Fscripts\u002Fgenerate-workers-registry.sh` to skip `*\u002F_overrides\u002F*` if not already patched. Surface the exact rm command for user confirmation — do not auto-remove.\n\n#### `symlink`\nChecks:\n- Grep `ERR` for the broken path; if found, `ls -la \u003Cpath>` and `readlink \u003Cpath>`\n- Common legitimate HQ symlinks to verify: `AGENTS.md` and `.claude\u002Fskills\u002Fpersonal:*`\n- Company knowledge under `companies\u002F*\u002Fknowledge\u002F` must be a plain real directory with no embedded Git metadata or symlink. Personal knowledge may be a real directory with embedded Git. Under `core\u002Fknowledge\u002F`, a package-managed link into `core\u002Fpackages\u002F*\u002Fknowledge\u002F` is valid; a link to a separate git repository is a migration violation.\n\nFix proposal: for legitimate non-knowledge links, re-create the symlink with an absolute path under `$HOME\u002FDocuments\u002FHQ\u002F` only if the target is unambiguous. For knowledge, materialize the content at the canonical path and verify it is not a symlink.\n\n#### `git-object-store`\nThese errors read like history loss, so the instinct is to reach for `git gc`, a reclone, or `--prune`. Do NOT start there — check for a mechanical cause first, because the most common one destroys nothing and is repaired by a rename.\n\n**macOS `Icon\\r` files inside `.git`.** If `ERR` mentions `Error building trees`, `invalid object`, `badRefName`, `bad sha1 file`, or `Icon\\r`, run this probe before the pack check (report-only; it never deletes without `--fix`):\n\n```bash\nbash core\u002Fscripts\u002Fgit-icon-file-check.sh --root .\n```\n\nFinder writes a file named `Icon` plus a carriage return into folders with a custom icon, and iCloud Desktop & Documents sync copies them into `.git\u002Frefs`, `.git\u002Fobjects\u002Fxx` and `.git\u002Flogs`. The working-tree `.gitignore` does not reach inside `.git`. Git then reports `badRefName` and `bad sha1 file`, and when a loose object went missing at the same time every commit fails with `invalid object ... Error building trees`.\n\n- Exit 0 → no `Icon\\r` files and no index entry is missing its object. Continue with the pack check that follows.\n- Exit 2 → show the user the reported files and missing objects and propose `--fix` as a numbered fix. On confirmation, run `bash core\u002Fscripts\u002Fgit-icon-file-check.sh --root . --fix`. It deletes only files named exactly `Icon\\r` under `.git`, runs `git fsck`, and restores a missing blob with `git hash-object -w` only when the working file hashes to exactly that id. It never writes an object from a file that differs. Exit 0 means `git fsck` is clean; exit 2 lists what is still broken. Do not run `git gc --prune` on what remains.\n- Never hand-roll `find .git -name 'Icon*' -delete`: that glob also matches real files such as `Icons`.\n- When the probe prints `warning: ... iCloud`, tell the user the files will come back until the HQ folder moves out of Desktop and Documents (for example to `~\u002Fhq`) or \"Desktop & Documents Folders\" is turned off in iCloud Drive settings.\n\nThen run the pack probe (report-only; it never renames without `--fix`):\n\n```bash\nbash core\u002Fscripts\u002Fgit-pack-extension-check.sh --root .\n```\n\nA packfile set is three files sharing a basename — `pack-\u003Csha>.pack`, `.idx`, `.rev` — and git pairs them **by extension**. If any one of them loses its extension, git stops seeing the whole set: the objects are still on disk byte for byte, but they become unreachable, and git reports them as missing. `git fsck` will agree they are gone and `git gc` cannot help, because nothing is corrupt.\n\n- Exit 0 → the pack set is intact; this is a different problem. Go on to `git fsck --full`, check `.git\u002Fobjects\u002Finfo\u002Falternates`, and look for genuinely truncated or zero-length loose objects.\n- Exit 2 → an orphan was found. Show the user the reported filename and propose the rename as a numbered fix. On confirmation, re-run with `--fix`, then verify with `git -C \u003Croot> fsck` and `git -C \u003Croot> status`.\n\nIf the probe is clean but the index still reports a stale cached tree, `git read-tree HEAD` rebuilds the index from HEAD without touching working files (it does unstage anything currently staged).\n\nWorth surfacing to the user: git never writes an extensionless `pack-*` file, so if one exists, something outside git renamed it. On macOS that usually means a folder-level sync or backup agent walking the tree — the same class of tool that scatters `Icon\\r` files. Ask whether the HQ root sits inside iCloud Drive, Dropbox, or a backup target, since the repair will not hold if the cause is still running.\n\n#### `git-root`\nRead first 30 lines of `.claude\u002Fhooks\u002Fblock-hq-root-git-mutation.sh` to surface the rule. Show the user the correct invocation form: `git -C \u002Fabs\u002Fpath \u003Ccmd>` or `( cd \u002Fabs\u002Fpath && git \u003Ccmd> )` or `gh ... -R owner\u002Frepo`. For sanctioned HQ-internal git work, surface `HQ_ALLOW_HQ_ROOT_GIT=1 git ...`. No file mutations.\n\nIf the HQ root's `.git` is missing, or the HQ root records nested company or project repos as gitlinks (mode `160000`), never hand-roll `git init && git add -A`: that records every nested repo as a gitlink with no `.gitmodules`. Use the helper instead:\n\n```bash\nbash core\u002Fscripts\u002Fhq-root-git-reinit.sh --check    # report gitlinks (exit 2 when found)\nbash core\u002Fscripts\u002Fhq-root-git-reinit.sh --reinit   # .git is missing: init, exclude nested repos, commit\nbash core\u002Fscripts\u002Fhq-root-git-reinit.sh --repair   # gitlinks already recorded: index-only removal + exclude\n```\n\nPropose `--reinit` or `--repair` as a numbered fix and run it only after the user confirms. Nested repos are listed in `.git\u002Finfo\u002Fexclude`; their files and history are not touched.\n\n#### `plan-mode`\nSurface: in plan mode, the model can Read\u002FGlob\u002FGrep but cannot Edit\u002FWrite. To exit, call `ExitPlanMode` (deferred tool — load via ToolSearch). No file mutations needed; this is purely an explainer.\n\n#### `unknown`\nRun a minimal triage:\n- `bash core\u002Fscripts\u002Fhq-session.sh 2>\u002Fdev\u002Fnull` (if present) to dump session context\n- `git -C . status --short | head -10`\n- `hq whoami 2>\u002Fdev\u002Fnull` to confirm identity\n\nThen ask the user three numbered follow-up questions via `AskUserQuestion`:\n1. When did the error first appear (this turn \u002F earlier in session \u002F right at session start)?\n2. Has anything in HQ changed recently (`\u002Fupdate-hq`, new hook, new policy)?\n3. Does the error reproduce in a fresh session (run `bash .claude\u002Fskills\u002Fhq-heal\u002Fhq-heal.sh --bare \"\u003Cerror>\"` to test)?\n\n### 4. Propose the fix\n\nFormat the proposal as a numbered list (1-4 options max), one option per line, with the safest option first. Always include an explicit \"Do nothing — just save report\" choice.\n\nIf `--dry-run` was passed, skip the apply step entirely; report the proposed fix and stop.\n\nOtherwise, use `AskUserQuestion` to surface the numbered options. Wait for the answer. Apply the chosen fix only.\n\n**Safety rules for the apply step:**\n- Never auto-edit policies, hooks, or `core.yaml` without explicit user confirmation\n- Never delete files — surface the rm command and let the user run it\n- Never run `git push`, `git reset --hard`, or any rc-file rewrite\n- Never read sensitive deny-listed paths even to diagnose\n- For multi-step fixes, apply one step, re-run a minimal diagnostic, then proceed\n\n**Core-divergence handling (`core\u002F` mirror):**\n- HQ's `core\u002F` tree is mechanically write-blocked by `.claude\u002Fhooks\u002Fblock-core-writes.sh` because it is a downstream mirror of `hq-core`. Heal usually routes fixes through `personal\u002F\u003Ctype>\u002F\u003Cname>\u002F` (read directly from `personal\u002F` — the old symlink mirror into `core\u002F` was retired) or co-locates with a skill (`.claude\u002Fskills\u002F\u003Cname>\u002F`) — never into `core\u002F` directly.\n- Genuine exception: the failing artifact *is* a core file (a broken `core\u002Fscripts\u002F*.sh` hook helper, a stale `core\u002Fpolicies\u002F\u003Cname>.md`, etc.) and the fix cannot land anywhere else. In that case:\n  1. The numbered proposal must call out that the fix diverges from upstream — exact files listed\n  2. The user must have passed `--allow-core` (the flag is the explicit acknowledgment that this divergence is intentional)\n  3. Each individual Write\u002FEdit\u002FBash call that touches a `core\u002F` path must be prefixed with `HQ_BYPASS_CORE_PROTECT=1`\n  4. The heal report (Step 5) gets a `## Core divergence` section listing every `core\u002F` path touched, the old content (first 30 lines), and the new content (first 30 lines)\n  5. The auto-filed bug (Step 6) is escalated from `bug` to `feature` if the divergence implies a policy \u002F hook change upstream wants — the body explicitly names which upstream file needs the corresponding patch in `hq-core`\n- If `--allow-core` is missing and the only viable fix is a `core\u002F` edit, do not apply anything — surface the proposed diff in the report (as a *would-have-applied* block) and stop with a one-liner telling the user to re-invoke `\u002Fhq-heal --allow-core \u003Csame args>`.\n\n### 5. Write the heal report\n\nPath: `workspace\u002Freports\u002Fhq-heal\u002F{YYYYMMDD-HHMMSS}-{class}.md`.\n\nTemplate:\n\n```markdown\n# HQ Heal Report — {class}\n\nTimestamp: {iso8601}\nSession: {session_id_or_unknown}\nTriggered by: \u002Fhq-heal {$ARGUMENTS first 80 chars}\n\n## Error captured\n\n```\n{ERR, max 2 KB}\n```\n\n## Classification\n\n{class} — matched on `{trigger_phrase}`\n\n## Diagnostics\n\n{output of the recipe checks, max 3 KB}\n\n## Fix proposed\n\n{numbered options shown to user}\n\n## Fix applied\n\n{user's chosen option, or \"dry-run — none applied\" if --dry-run}\n\n## Outcome\n\n{1-3 sentences: did the proposed fix resolve, was a follow-up needed, what to watch next session}\n\n## Core divergence\n\n{omit this section unless --allow-core was passed AND a core\u002F path was touched. List every core\u002F file touched, the old content (first 30 lines), the new content (first 30 lines), and a 1-line justification for why the fix could not land in personal\u002F or a co-located skill folder.}\n```\n\nAppend a one-line entry to `workspace\u002Freports\u002Fhq-heal\u002FINDEX.md` (create if missing) with the timestamp, class, and outcome status.\n\n### 6. File an HQ bug (default on)\n\nUnless `--no-bug` was passed, file a bug report via the `\u002Fhq-bug` skill so HQ engineering accumulates signal on which error classes are recurring and which heal flows actually fixed them. This step runs **after** the heal report has been written so the report path can be referenced from the bug body.\n\nBuild the bug as follows:\n\n- **Type**: `bug` by default. Escalate to `feature` if the fix touched `core\u002F` (i.e. the `## Core divergence` section is non-empty) — the engineering follow-up needed is an upstream patch, which is a feature ask, not a bug report\n- **Title**: `hq-heal: {class} — {one-line summary of the fix applied}` (truncate the summary to keep the whole title under 80 chars)\n- **Body sections** (the `\u002Fhq-bug` skill assembles its own four-section template; heal augments by setting `$ARGUMENTS` to a single line so the skill captures the right title, and by ensuring the rendered body references the heal report path verbatim):\n  - The heal report path: `workspace\u002Freports\u002Fhq-heal\u002F{filename}.md` — engineering reads this for the raw error, classification, diagnostics, and applied fix\n  - The error class\n  - The fix that was applied (or `dry-run — none applied`)\n  - If `## Core divergence` was set, the list of `core\u002F` files touched + the upstream `hq-core` path they map to (e.g. `core\u002Fscripts\u002F\u003Cname>.sh` → `https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002Fcore\u002Fscripts\u002F\u003Cname>.sh`)\n\nInvocation: call the `\u002Fhq-bug` skill via the `Skill` tool with the bug type and title as args. Do not shell out to `hq feedback` directly — `\u002Fhq-bug` already wraps the CLI with the right body-file allocation, CWD capture, and session-context assembly.\n\nIf the `\u002Fhq-bug` skill is missing on this HQ (e.g. running an older release), fall back to a single-line stderr notice in the heal report's `## Outcome` section: *\"hq-bug filing skipped — `\u002Fhq-bug` skill not installed.\"* Do not block the heal flow on bug-filing failure — heal report is the durable artifact, bug filing is secondary signal.\n\nIf `--dry-run` was passed at invocation, also skip the bug-filing step — dry-run is observation only.\n\n### 7. Surface the next step\n\nPrint a short, four-line summary to the user:\n\n```\nHeal complete — class: {class}\nApplied: {what was done, or \"nothing — dry-run\"}\nReport:  workspace\u002Freports\u002Fhq-heal\u002F{filename}.md\nBug:     {hq-bug URL or 'skipped (--no-bug)' or 'skipped (dry-run)' or 'skipped (\u002Fhq-bug missing)'}\n```\n\nIf `--allow-core` was used and the `## Core divergence` section was written, append one extra line: *\"Core divergence noted — `{N}` `core\u002F` files touched. Upstream patch needed in hq-core.\"*\n\nIf the proposed fix requires re-launching the session (e.g. autocompact, reindex), append: *\"Re-launch suggestion: `bash .claude\u002Fskills\u002Fhq-heal\u002Fhq-heal.sh --resume`\"* and stop.\n\n## Rules\n\n- Heal stays HQ-internal — never load `companies\u002F*\u002Fknowledge\u002F`, `companies\u002Fmanifest.yaml` body, INDEX.md, or `handoff.json`\n- Never read sensitive deny-listed paths under any circumstance, even when classifying a `denylist` error\n- Recipe context budget is 5 KB per class — if a probe would return more, summarize\n- The classifier is pure pattern matching — do not run subagents or do any HQ-wide search before classification\n- Never auto-apply fixes for `denylist`, `git-root`, `reindex`, or `git-object-store` classes — always require user confirmation, the consequences are too broad. For `git-object-store` the probe is safe to run unattended because it only reports; it is the `--fix` rename that needs confirmation\n- Never restore the `hq` CLI with `npm install -g @indigoai-us\u002Fhq-cli@latest`. That command is blocked by `hq-pnpm-min-release-age-supply-chain`. Use `pnpm add -g @indigoai-us\u002Fhq-cli@latest --config.minimumReleaseAge=1440`.\n- The heal report is the single durable artifact — it is what `\u002Fhandoff` and future `\u002Fhq-heal` invocations consult to detect repeat failures\n- The `\u002Fhq-bug` filing in Step 6 is the *signal* artifact — durable artifact stays local, signal goes to HQ engineering so recurring error classes get systemized fixes upstream. `--no-bug` suppresses the filing only; the report still writes\n- Core-mirror writes are off by default. The `--allow-core` flag is required even when the user explicitly confirms a fix that touches `core\u002F`. This is intentional friction — the bypass should be auditable per-invocation, not implicit\n- This skill must remain runnable in `--bare` mode (no hooks, no MCPs) so it stays usable when hooks or MCPs are the failure mode being diagnosed\n- Companion to `\u002Frecover-session` (post-mortem on a dead JSONL) — `\u002Fhq-heal` is mid-session triage and may invoke `\u002Frecover-session` as its fix for the `autocompact` class\n- Promotion: this skill lives at `.claude\u002Fskills\u002Fhq-heal\u002F` locally; to ship it to other HQs, stage it in the hq-core staging repo and publish via `\u002Fpromote-hq-core` per the `staging-promotion-required` policy\n- The launcher `hq-heal.sh` is co-located with the skill (`.claude\u002Fskills\u002Fhq-heal\u002Fhq-heal.sh`) rather than placed under `core\u002Fscripts\u002F`, because `core\u002F` is hook-protected (`block-core-writes`) — promotion happens via the staging hop, not direct writes\n\n## Why this exists\n\nHQ users hit a recurring class of errors that look scary but are well-understood once classified — autocompact thrashing, hook crashes, sync conflicts, deny-list blocks, reindex aborts. Without a healer, the recovery path is for the user to switch terminals, paste the error into a fresh Claude session, and hope the new session figures out what to do. `\u002Fhq-heal` collapses that into one slash command with a known-good triage recipe per error class, and a companion launcher (`.claude\u002Fskills\u002Fhq-heal\u002Fhq-heal.sh`) for the case where the current session is too wedged to invoke the slash command at all.\n\n## See also\n\n- `\u002Fresolve-conflicts` — pick local\u002Fcloud on a conflict\n- `\u002Frecover-session` — restore a lost session\n",{"name":5,"description":7,"allowed-tools":24},"Read, Write, Edit, Bash, Bash(bash core\u002Fscripts\u002Fgit-pack-extension-check.sh:*), Bash(bash core\u002Fscripts\u002Fgit-icon-file-check.sh:*), Bash(bash core\u002Fscripts\u002Fhq-root-git-reinit.sh:*), Glob, Grep, AskUserQuestion","main","205cf61728a27ef15e9153aa38df5856fc8d82f5",".claude\u002Fskills\u002Fhq-heal",18,"https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core","https:\u002F\u002Fgithub.com\u002Findigoai-us","https:\u002F\u002Fhqforwork.com\u002F","The AI Context Layer for Teams","2026-11-12 06:53:38",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add indigoai-us\u002Fhq-core --skill hq-heal",{"tool":40,"command":41},"bunx","bunx skills add indigoai-us\u002Fhq-core --skill hq-heal",{"tool":43,"command":44},"pnpm","pnpm dlx skills add indigoai-us\u002Fhq-core --skill hq-heal","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fhq-heal\u002FSKILL.md",true,[48,54],{"path":49,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":52,"sourceHtmlUrl":53},"agents\u002Fopenai.yaml","REFERENCE","参考文档",133,"https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fhq-heal\u002Fagents\u002Fopenai.yaml",{"path":55,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":58,"sourceHtmlUrl":59},"hq-heal.sh","SCRIPT","脚本",5213,"https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fhq-heal\u002Fhq-heal.sh",[61,68,75,82,89,96],{"skillNo":62,"name":63,"nameZh":6,"description":64,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":65,"categories":66,"keywords":67,"publishedAt":19},"01M73NTNKZ3T2KJNDP2ZF23645","job","Deprecated alias for \u002Fschedule — Outpost recurring agent jobs. Prefer \u002Fschedule.","https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fjob\u002FSKILL.md",[],[],{"skillNo":69,"name":70,"nameZh":6,"description":71,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":72,"categories":73,"keywords":74,"publishedAt":19},"01M73NTE0H9DQTT6DNHDKRWTXW","import-claude","Deprecated alias for \u002Fimport-context — bootstrap HQ from your prior AI footprint (Claude Code, Codex, Grok, claude.ai history plus on-disk artifacts).","https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fimport-claude\u002FSKILL.md",[],[],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M73NT67433KKX96CCJWDQQ0X","hq-whoami","Show current HQ Cognito identity and session expiry.","https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fhq-whoami\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M73NT17SVXZV2QPT14C2RPJP","hq-share","Share HQ vault paths through single-use links or direct ACL grants.","https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fhq-share\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":19},"01M73NSXYFMD7EHGT8TFDZA3C8","hq-secrets","Use HQ CLI secrets safely through env injection or one-off exec.","https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fhq-secrets\u002FSKILL.md",[],[],{"skillNo":97,"name":98,"nameZh":6,"description":99,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":19},"01M73NSWCXJK29Q8CNG8AS3ZZQ","hq-logout","Sign out of HQ Cognito and clear local tokens.","https:\u002F\u002Fgithub.com\u002Findigoai-us\u002Fhq-core\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Fhq-logout\u002FSKILL.md",[],[]]