greprag 5.82.1 → 5.83.1

package/dist/deploy-locks.js

@@ -47,6 +47,7 @@ exports.lockSession = lockSession;
 exports.lockOwnership = lockOwnership;
 exports.describeLockOwner = describeLockOwner;
 exports.gitDir = gitDir;
+exports.commonGitDir = commonGitDir;
 exports.lockPath = lockPath;
 exports.deployLockPath = deployLockPath;
 exports.mergeLockPath = mergeLockPath;
@@ -117,9 +118,23 @@ function gitDir(cwd) {
         throw new Error('not a git checkout');
     return String(result.stdout).trim();
 }
-/** Locks live inside `.git`, so they are never tree dirt and can never be committed. */
+/** The repository's one shared `.git`, the same directory from every linked worktree.
+ *  `gitDir` is per-worktree (`.git/worktrees/<name>`), which is right for MERGE_HEAD and
+ *  wrong for anything two worktrees must agree on: on 2026-10-06 a merge lock acquired
+ *  from a linked worktree landed in that worktree's private dir, and the merge guard,
+ *  reading the canonical checkout, refused the holder's own merge. */
+function commonGitDir(cwd) {
+    const result = (0, proc_1.safeSpawnSync)('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+        encoding: 'utf8', cwd, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0)
+        throw new Error('not a git checkout');
+    return path.resolve(String(result.stdout).trim());
+}
+/** Locks live inside the shared `.git`, so they are never tree dirt, can never be
+ *  committed, and name the same file whichever worktree takes or reads them. */
 function lockPath(cwd, name) {
-    return path.join(gitDir(cwd), `${PREFIX}-${name}.lock`);
+    return path.join(commonGitDir(cwd), `${PREFIX}-${name}.lock`);
 }
 function deployLockPath(cwd, target) {
     return lockPath(cwd, `deploy-${target}`);
@@ -236,7 +251,7 @@ function releaseLock(file) {
  *  recorded a claim and then vanished would otherwise wedge the checkout. */
 exports.CLAIM_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 function landedClaimsPath(cwd) {
-    return path.join(gitDir(cwd), `${PREFIX}-landed.json`);
+    return path.join(commonGitDir(cwd), `${PREFIX}-landed.json`);
 }
 /** True when `sha` is reachable from HEAD. False for an orphan, a rewritten commit,
  *  or one that never existed — the caller distinguishes those with `commitExists`. */

package/dist/doc-mirror-client.js

@@ -1,10 +1,11 @@
 "use strict";
 /** Client-side project document mirror helpers.
  *
- * One rule set feeds:
+ * One rule set (eligibility + path root) feeds:
  * - `greprag doc mirror sync` / `greprag doc update`
  * - Stop-hook touched-doc upserts
  * - `greprag load` / `greprag status` freshness warnings
+ * - the doc-pointer capture, backfill and SessionStart reconcile
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -46,6 +47,7 @@ exports.isDocMirrorEligible = isDocMirrorEligible;
 exports.titleFromMarkdown = titleFromMarkdown;
 exports.tagsFromPath = tagsFromPath;
 exports.docContentHash = docContentHash;
+exports.docPathRoot = docPathRoot;
 exports.collectDocMirrorInventory = collectDocMirrorInventory;
 exports.collectTouchedDocMirrorDocs = collectTouchedDocMirrorDocs;
 exports.computeDocMirrorFreshness = computeDocMirrorFreshness;
@@ -67,6 +69,12 @@ function normalizeDocRel(input) {
         .replace(/\/+/g, '/')
         .trim();
 }
+/** The project doc lists (this mirror and the doc pointers) hold project
+ *  state. Skill trees are procedure that `greprag load`
+ *  serves itself, so they never enter it: every harness keeps skills under a
+ *  `skill/` or `skills/` folder (the bundled source and its templates included),
+ *  and a `SKILL.md` marks a skill package wherever it sits.
+ *  adr: adr/doc-mirror-state-only.md */
 function isDocMirrorEligible(relPath) {
     const p = normalizeDocRel(relPath);
     if (!p.toLowerCase().endsWith('.md'))
@@ -74,7 +82,7 @@ function isDocMirrorEligible(relPath) {
     const segments = p.split('/');
     const base = segments[segments.length - 1] || '';
     const lowerBase = base.toLowerCase();
-    if (lowerBase === 'claude.md' || lowerBase === 'memory.md')
+    if (lowerBase === 'claude.md' || lowerBase === 'memory.md' || lowerBase === 'skill.md')
         return false;
     for (const seg of segments.slice(0, -1)) {
         if (!seg)
@@ -83,6 +91,8 @@ function isDocMirrorEligible(relPath) {
             return false;
         if (seg === 'node_modules' || seg === 'dist' || seg === 'build' || seg === 'vendor')
             return false;
+        if (seg === 'skill' || seg === 'skills')
+            return false;
     }
     return true;
 }
@@ -105,6 +115,22 @@ function tagsFromPath(relPath) {
 function docContentHash(content) {
     return crypto.createHash('sha256').update(content).digest('hex');
 }
+/** The folder every project doc path is relative to: the checkout's top level,
+ *  so a session opened in a subfolder records and reconciles the same paths as
+ *  one at the root. A folder outside git is its own root.
+ *  adr: adr/doc-mirror-state-only.md */
+function docPathRoot(cwd) {
+    try {
+        const out = (0, proc_1.safeExecFileSync)('git', ['rev-parse', '--show-toplevel'], {
+            cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const root = String(out).trim();
+        if (root)
+            return path.resolve(root);
+    }
+    catch { /* not a git checkout */ }
+    return path.resolve(cwd);
+}
 function gitLsFiles(cwd) {
     try {
         const out = (0, proc_1.safeExecFileSync)('git', ['ls-files'], {
@@ -152,9 +178,9 @@ function walkMarkdownFiles(cwd, maxDocs = MAX_FILESYSTEM_DOCS) {
     visit(cwd);
     return { files, truncated };
 }
-function touchedToRel(cwd, filePath) {
+function touchedToRel(root, cwd, filePath) {
     const abs = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
-    const rel = normalizeDocRel(path.relative(cwd, abs));
+    const rel = normalizeDocRel(path.relative(root, abs));
     if (!rel || rel.startsWith('../') || path.isAbsolute(rel))
         return null;
     return rel;
@@ -201,20 +227,22 @@ function buildCollection(cwd, relPaths, source, presentForRefs, gitAvailable, tr
     };
 }
 function collectDocMirrorInventory(cwd) {
-    const tracked = gitLsFiles(cwd);
+    const root = docPathRoot(cwd);
+    const tracked = gitLsFiles(root);
     if (tracked) {
-        return buildCollection(cwd, tracked.filter(isDocMirrorEligible), 'git', new Set(tracked), true);
+        return buildCollection(root, tracked.filter(isDocMirrorEligible), 'git', new Set(tracked), true);
     }
-    const walked = walkMarkdownFiles(cwd);
-    return buildCollection(cwd, walked.files, 'filesystem', new Set(), false, walked.truncated);
+    const walked = walkMarkdownFiles(root);
+    return buildCollection(root, walked.files, 'filesystem', new Set(), false, walked.truncated);
 }
 function collectTouchedDocMirrorDocs(filesTouched, cwd) {
-    const tracked = gitLsFiles(cwd);
+    const root = docPathRoot(cwd);
+    const tracked = gitLsFiles(root);
     const presentForRefs = tracked ? new Set(tracked) : new Set();
     const rels = filesTouched
-        .map((f) => touchedToRel(cwd, f))
+        .map((f) => touchedToRel(root, cwd, f))
         .filter((f) => !!f && isDocMirrorEligible(f));
-    return buildCollection(cwd, rels, tracked ? 'git' : 'filesystem', presentForRefs, !!tracked);
+    return buildCollection(root, rels, tracked ? 'git' : 'filesystem', presentForRefs, !!tracked);
 }
 function computeDocMirrorFreshness(local, remoteDocs) {
     const remote = new Map();

package/dist/hook.js

@@ -91,6 +91,7 @@ const persona_1 = require("./commands/persona");
 const app_settings_1 = require("./app-settings");
 const inbox_primer_reminder_1 = require("./commands/inbox-primer-reminder");
 const skill_activation_manifest_1 = require("./skill-activation-manifest");
+const native_adapter_refresh_1 = require("./native-adapter-refresh");
 const worktree_state_1 = require("./worktree-state");
 // Ingress-trigger bridge, Adapter A (LOCAL/state half) — the Stop hook computes
 // the deterministic state values (stress / turnCount / keyword-seen) from the
@@ -644,37 +645,18 @@ function capField(text) {
 //
 // The Document Pointer System's detect half. No new hook: the Stop hook already
 // sees every file the turn touched (filesTouched), so .md writes ride the same
-// event — a deterministic path filter here, the Flash-Lite worthiness judge
-// server-side. Best-effort end to end: a docptr failure never blocks a turn.
-/** Deterministic pre-filter — the cheap gate BEFORE the LLM judge. Rejects the
- *  obvious never-index classes so they don't even cost a judge call: non-.md,
- *  dot-directories (.tmp-*, .claude/, .github/ — harness/scratch, not project
- *  docs), dependency/build trees, and the harness-owned CLAUDE.md/MEMORY.md
- *  (always injected anyway — indexing them is circular noise). Judge-worthy
- *  ambiguity (drafts, beats, plans) is the JUDGE's call, not this filter's. */
-function isDocPathEligible(relPath) {
-    const p = relPath.replace(/\\/g, '/');
-    if (!p.toLowerCase().endsWith('.md'))
-        return false;
-    const segments = p.split('/');
-    const base = segments[segments.length - 1];
-    if (base === 'CLAUDE.md' || base === 'MEMORY.md')
-        return false;
-    for (const seg of segments.slice(0, -1)) {
-        if (seg.startsWith('.'))
-            return false;
-        if (seg === 'node_modules' || seg === 'dist' || seg === 'build' || seg === 'vendor')
-            return false;
-    }
-    return true;
-}
+// event — the doc mirror's eligibility rule here (isDocMirrorEligible: project
+// state only, never skill trees or harness followers), the Flash-Lite worthiness
+// judge server-side. Paths are relative to the checkout root (docPathRoot), the
+// same root the mirror uses. Best-effort end to end: a docptr failure never
+// blocks a turn.
 /** Head-snippet cap posted to the judge (server re-caps defensively). */
 const DOC_EVENT_SNIPPET_CHARS = 2_000;
 /** Max doc events per turn (mirrors the server's MAX_EVENTS_PER_POST). */
 const DOC_EVENTS_PER_TURN = 8;
 /** Turn's touched files → judge-ready doc events: project-relative eligible
  *  .md paths + head snippets + a CLIENT-CONFIRMED reference manifest. Files
- *  outside cwd (scratchpad, other repos) and unreadable files (deleted later in
+ *  outside the checkout (scratchpad, other repos) and unreadable files (deleted later in
  *  the turn) are skipped silently.
  *
  *  The manifest is built HERE, on the side that has the tree (docs/doc-pointer-
@@ -684,15 +666,16 @@ const DOC_EVENTS_PER_TURN = 8;
  *  LLM ref-extraction is retired to a back-compat fallback (old CLIs send no
  *  refs). Tree unavailable → empty manifests (docs read fresh — bias-to-keep). */
 function collectDocEvents(filesTouched, cwd) {
+    const root = (0, doc_mirror_client_1.docPathRoot)(cwd);
     const staged = [];
     const seen = new Set();
     for (const abs of filesTouched) {
         if (staged.length >= DOC_EVENTS_PER_TURN)
             break;
-        const rel = path.relative(cwd, abs).replace(/\\/g, '/');
+        const rel = path.relative(root, abs).replace(/\\/g, '/');
         if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
             continue;
-        if (!isDocPathEligible(rel) || seen.has(rel))
+        if (!(0, doc_mirror_client_1.isDocMirrorEligible)(rel) || seen.has(rel))
             continue;
         try {
             const snippet = fs.readFileSync(abs, 'utf-8').slice(0, DOC_EVENT_SNIPPET_CHARS);
@@ -709,14 +692,14 @@ function collectDocEvents(filesTouched, cwd) {
     let present = new Set();
     try {
         const all = (0, proc_1.safeExecSync)('git ls-files', {
-            cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
+            cwd: root, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
         });
         present = new Set(all.split('\n').map((s) => s.trim().replace(/\\/g, '/')).filter(Boolean));
     }
     catch { /* not a git repo — manifests stay empty */ }
     return staged.map((e) => ({
         ...e,
-        refs: present.size ? (0, docptr_refs_1.extractDocRefs)(e.snippet, e.path, cwd, present) : [],
+        refs: present.size ? (0, docptr_refs_1.extractDocRefs)(e.snippet, e.path, root, present) : [],
     }));
 }
 // ---------- Procedure span observer (docs/procedure-system.md) --------------
@@ -975,12 +958,13 @@ async function fetchDocPointers(apiUrl, apiKey, anchor, cwd) {
         let presentPaths; // eligible .md — the existence sweep
         let trackedAll; // ALL tracked files — the manifest oracle
         try {
+            const root = (0, doc_mirror_client_1.docPathRoot)(cwd);
             const md = (0, proc_1.safeExecSync)('git ls-files -- "*.md"', {
-                cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
+                cwd: root, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
             });
-            presentPaths = md.split('\n').map(s => s.trim()).filter(s => isDocPathEligible(s));
+            presentPaths = md.split('\n').map(s => s.trim()).filter(s => (0, doc_mirror_client_1.isDocMirrorEligible)(s));
             const all = (0, proc_1.safeExecSync)('git ls-files', {
-                cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
+                cwd: root, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
             });
             trackedAll = new Set(all.split('\n').map(s => s.trim().replace(/\\/g, '/')).filter(Boolean));
         }
@@ -1624,7 +1608,9 @@ async function recap(input, mode = 'plain', opts = {}) {
     const skillGainsPromise = fetchAndLandSkillGains(cfg.apiUrl, cfg.apiKey, anchor, cwd);
     // Tier-3 skill activation manifest (docs/load-system.md): fetch canonical
     // full descriptions, then omit skills this harness already advertises
-    // natively. Best-effort; the renderer remains pure.
+    // natively. Best-effort; the renderer remains pure. The same roster is what
+    // installed adapters are checked against, so keeping them at canon costs no
+    // extra round trip unless one is stale. adr: adr/skill-bundle-shape.md
     const mirroredSkillsPromise = (async () => {
         try {
             const params = new URLSearchParams({ scope: 'effective', projectId: anchor.projectId });
@@ -1634,8 +1620,12 @@ async function recap(input, mode = 'plain', opts = {}) {
             if (!res.ok)
                 return undefined;
             const data = await res.json();
+            const rows = data.skills || [];
+            await (0, native_adapter_refresh_1.refreshNativeAdapters)({
+                platform, rows, apiUrl: cfg.apiUrl, apiKey: cfg.apiKey, homeDir: os.homedir(), projectDir: cwd,
+            }).catch(() => undefined);
             return (0, skill_activation_manifest_1.activationFromApiRows)({
-                rows: data.skills || [],
+                rows,
                 platform,
                 cwd,
                 homeDir: process.env.HOME || process.env.USERPROFILE || '',
@@ -2203,10 +2193,16 @@ function validateChip(title, prompt) {
             `"Chip: Fix stale README badge" or "Chip B: Build freshness engine". ` +
             `The prefix distinguishes chip-spawned sessions from IDE/human sessions in FleetView.`);
     }
-    if (!/\bgit\s+worktree\s+add\b/.test(prompt)) {
-        violations.push(`prompt missing worktree setup. ` +
-            `Block 1 requires the chip to open with: \`git worktree add .claude/worktrees/<slug> -b chip/<slug>\` ` +
-            `then \`cd\` into it. Chips never edit the main checkout.`);
+    // Block 1 carries both steps: `git branch -m` keeps the fresh worktree the
+    // desktop app already gave the chip, `git worktree add` makes one on a local
+    // start. `git worktree add` alone is the old Block 1, which built a second
+    // worktree beside the app's — reject it so no stale copy brings that back.
+    if (!/\bgit\s+worktree\s+add\b/.test(prompt) || !/\bgit\s+branch\s+-m\b/.test(prompt)) {
+        violations.push(`prompt missing the current worktree setup. ` +
+            `Paste Block 1 verbatim from \`greprag load chip-spawn\`: it keeps the worktree the desktop app ` +
+            `already gave the chip (renaming its fresh branch to chip/<slug>) and runs ` +
+            `\`git worktree add .claude/worktrees/<slug> -b chip/<slug>\` only on a local start. ` +
+            `Chips never edit the main checkout.`);
     }
     // NO report-back check. Chips report to the parent with native
     // `SendMessage to: "<parent-name>"`, which needs no greprag address and no
@@ -2220,7 +2216,7 @@ function validateChip(title, prompt) {
  *  dropped by the CCD harness for MCP `spawn_task` calls (see
  *  adr/spawn-task-hook-mode.md 2026-05-27 entry — Tier 2 augmentation
  *  attempt). `permissionDecision: deny` IS honored, so the validator
- *  catches missing Block 1 / Block 2 markers; the agent re-composes the
+ *  catches a missing title prefix or Block 1 marker; the agent re-composes the
  *  call with the templates from `greprag load chip-spawn`. */
 function handlePreSpawnCheck(input) {
     if (input.tool_name !== 'mcp__ccd_session__spawn_task')

package/dist/index.js

@@ -325,16 +325,16 @@ async function runDesk(args) {
     process.exitCode = 1;
 }
 async function inbox(args) {
+    const sub = args[0];
+    if (sub === '--help' || sub === '-h' || sub === 'help') {
+        console.log(args[1] === 'watch' ? INBOX_WATCH_HELP : INBOX_HELP);
+        return;
+    }
     const cfg = getConfig();
     if (!cfg.apiKey) {
         console.error('Not configured. Run: greprag init');
         process.exit(1);
     }
-    const sub = args[0];
-    if (sub === '--help' || sub === '-h' || sub === 'help') {
-        console.log(INBOX_HELP);
-        return;
-    }
     // A non-flag first arg that isn't a known subcommand is a typo — do NOT fall
     // through to list mode (which auto-marks every message read). The classic
     // slip is `inbox send` (the real reply command is top-level `greprag send`).
@@ -351,13 +351,6 @@ async function inbox(args) {
     }
     if (sub === 'watch') {
         const subArgs = args.slice(1);
-        // --help MUST be checked before launching the watch. Pre-fix, `inbox
-        // watch --help` started a live SSE watch instead of printing help (smell
-        // 3d908baa) — the help flag silently armed a watcher. Print and return.
-        if (subArgs.includes('--help') || subArgs.includes('-h')) {
-            console.log(INBOX_WATCH_HELP);
-            return;
-        }
         // The Assistant role was removed 2026-09-03 (adr/assistant-role.md). Fail
         // loudly rather than silently arming a stock watcher — 5.44.0 already
         // shipped a build where `--assistant` was dropped without error and the
@@ -1059,16 +1052,16 @@ async function send(args) {
 }
 /** greprag discord <pair|unpair|me> — Discord DM bridge to inbox. */
 async function discord(args) {
-    const cfg = getConfig();
-    if (!cfg.apiKey) {
-        console.error('Not configured. Run: greprag init');
-        process.exit(1);
-    }
     const sub = args[0];
     if (!sub || sub === 'help' || sub === '--help') {
         console.log(discord_1.DISCORD_HELP);
         return;
     }
+    const cfg = getConfig();
+    if (!cfg.apiKey) {
+        console.error('Not configured. Run: greprag init');
+        process.exit(1);
+    }
     if (sub === 'pair') {
         const anchor = (0, project_anchor_1.readAnchor)(process.cwd());
         if (!anchor.projectId) {
@@ -1318,7 +1311,10 @@ Commands:
                                    parent of repo root). Each becomes inbox-addressable.
   status [--json] [--claude|--codex|--opencode|--grok]
                                   Installation, auth, platform hooks/plugins, and project state
-  codex doctor                    Diagnose Codex hooks, trust setup, and current thread
+  announce [--session <8hex>] [--path]
+                                  Print the full SessionStart announce (the harness
+                                  inlines only ~2KB; the rest is parked on disk)
+  codex doctor                   Diagnose Codex hooks, trust setup, and current thread
   project-id                       Print the current project_id
   session-id [--full]              Print this session's id (8-hex, 16-hex for UUIDv7, or full UUID with --full).
   discover [--json]                Tenant-wide structure: every project, per-shape row counts,
@@ -1526,11 +1522,12 @@ Corpus (upload + search arbitrary text — books, codebases, references):
                                 Single-store search. <store> is a UUID or name.
   corpus search "<intent>" --all|--store <ref>...  [--kind K] [--limit 8]
                                 Multistore search (RRF-fused). --all = every store.
-  corpus section <store> "<heading>"
+  corpus section <store> "<heading>" [--max-chars N]
                                 Every node under a heading (forgiving: any depth,
                                 dash/case-insensitive).
-  corpus walk <store> <nodeId> [--before 2 --after 2]
-                                Show a node and its surrounding context.
+  corpus walk <store> <nodeId> [--before 2 --after 2] [--max-chars N]
+                                Show a node and its surrounding context. Both
+                                print full node text; --max-chars N cuts each node.
   corpus status <store>         Write-side enrichment progress (per-node vocab bridge).
   corpus refresh <store>        Manually re-check a tracked source (re-ingest changed blocks).
   corpus sources <store>        Freshness state: source, policy, last change, next check.
@@ -1650,12 +1647,15 @@ Examples:
   greprag send "Bug in auth flow — repro at line 42" --to alice@greprag.com/abc12345 \
     --file src/auth.ts:42 --artifact commit:abc123
 `.trim();
-/** Groups that ship their own detailed `--help`. `help --all` invokes each one
+/** Groups that ship their own detailed `--help`. A help flag anywhere after one
+ *  of these prints it (printCommandHelp), and `help --all` invokes each one
  *  live and captures its output, so the assembled guide is rendered from the
  *  exact printers an agent gets via `greprag <group> --help` — it cannot drift
- *  from them. New group with its own --help? Add it here. (The help-coverage
- *  test flags any dispatched command that never appears in a help surface.) */
-const HELP_ALL_GROUPS = [
+ *  from them. Each is called as fn(['--help', ...words]) and must print and
+ *  return. New group with its own --help? Add it here, or its --help shows the
+ *  overview. (The help-coverage test flags any dispatched command that never
+ *  appears in a help surface.) */
+const HELP_GROUPS = [
     ['inbox', inbox],
     ['email', email_1.runEmail],
     ['memory', memory_1.runMemory],
@@ -1680,6 +1680,18 @@ const HELP_ALL_GROUPS = [
     ['opencode', opencode],
     ['crush', crush_1.runCrush],
     ['archive', archive_1.runArchive],
+    ['init', () => { console.log(INIT_HELP); }],
+    ['app', app_1.runApp],
+    ['announce', runAnnounce],
+    ['search', search_1.runSearch],
+    ['session', session_1.runSession],
+    ['context', context_governor_1.runContext],
+    ['repodoc', repodoc_1.runRepoDoc],
+    ['parity', parity_1.runParity],
+    ['grok', grok_spawn_1.runGrok],
+    ['docptr', docptr_1.runDocPtr],
+    ['loadout', loadout_1.runLoadout],
+    ['skillgain', skillgain_1.runSkillGain],
 ];
 const OPENCODE_HELP = `greprag opencode — bridge greprag inbox into a running opencode desktop
 session, plus a file-watching capture pipeline for episodic memory.
@@ -1805,6 +1817,8 @@ Run under a long-lived shell loop or as a Windows service:
 async function opencode(args) {
     const sub = args[0];
     if (!sub || sub === '--help' || sub === '-h' || sub === 'help') {
+        if (args[1] === 'chip')
+            return (0, opencode_chip_1.runOpencodeChip)(['--help', ...args.slice(2)]);
         console.log(OPENCODE_HELP);
         return;
     }
@@ -1859,13 +1873,25 @@ async function captureOutput(fn) {
 async function printHelpAll() {
     const bar = '═'.repeat(72);
     const parts = [HELP];
-    for (const [name, fn] of HELP_ALL_GROUPS) {
+    for (const [name, fn] of HELP_GROUPS) {
         const body = (await captureOutput(() => fn(['--help']))).trim();
         if (body)
             parts.push(`${bar}\n  greprag ${name}\n${bar}\n${body}`);
     }
     console.log(parts.join('\n\n'));
 }
+/** Help for `greprag <command> ... --help`. The words before the first flag let
+ *  a group show the part of its help they name (`inbox watch --help` → the
+ *  watch guide); a command without help of its own gets the overview. */
+async function printCommandHelp(command, subArgs) {
+    const group = HELP_GROUPS.find(([name]) => name === command);
+    if (!group) {
+        console.log(HELP);
+        return;
+    }
+    const words = subArgs.slice(0, subArgs.findIndex(arg => arg.startsWith('-')));
+    await group[1](['--help', ...words]);
+}
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
@@ -1881,6 +1907,16 @@ async function main() {
         console.log(HELP);
         return;
     }
+    const subArgs = args.slice(1);
+    // A help flag anywhere after the command asks for help, so the command never
+    // runs. Each group parses its own argv and looks for help only in its first
+    // slot, so one further along fell through into a real run: `skill mirror
+    // sync --help` dropped the flag and synced every harness, `skill edit --help`
+    // sent "--help" to the API as a skill name. adr: adr/cli-help-dispatch.md
+    if (subArgs.some(arg => arg === '--help' || arg === '-h')) {
+        await printCommandHelp(command, subArgs);
+        return;
+    }
     // Load ~/.greprag/.env ONCE for every command. Commands that read
     // process.env.GREPRAG_API_KEY directly (load, loadout, …) used to work only
     // in shells with the var exported — a fresh terminal got "GREPRAG_API_KEY
@@ -1888,7 +1924,6 @@ async function main() {
     // config themselves) worked fine (field incident 2026-07-12, tenant tanya).
     // Dispatch-level ensureEnv kills the whole per-command-forgot-env class.
     ensureEnv();
-    const subArgs = args.slice(1);
     switch (command) {
         case 'app':
         case 'dashboard': return (0, app_1.runApp)(subArgs);

package/dist/native-adapter-refresh.js

@@ -0,0 +1,114 @@
+"use strict";
+/** Keep installed native skill adapters at canon.
+ *
+ *  Adapters were written only by explicit syncs (init, `skill mirror sync`,
+ *  `--only`), so a canon change made anywhere — `skill mirror apply`, another
+ *  session, another machine — left them behind until someone re-synced by hand.
+ *
+ *  SessionStart calls this with the mirror roster it already fetched. Detection
+ *  is local: each managed adapter's stamps against the roster. Only a stale
+ *  adapter costs a fetch, and every write goes through the writer the sync
+ *  commands use, so the ownership ledger and the divergence guard still decide
+ *  what may be replaced. Refresh-only: no adapter is created or removed here.
+ */
+// adr: adr/skill-bundle-shape.md
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readAdapterStamps = readAdapterStamps;
+exports.staleNativeAdapters = staleNativeAdapters;
+exports.refreshNativeAdapters = refreshNativeAdapters;
+const claude_lifecycle_cutover_1 = require("./claude-lifecycle-cutover");
+const native_skill_mirror_1 = require("./native-skill-mirror");
+const skill_mirror_files_1 = require("./skill-mirror-files");
+/** The identity stamps a generated adapter carries in its frontmatter. */
+function readAdapterStamps(content) {
+    const frontmatter = /^---\n([\s\S]*?)\n---/.exec(content.replace(/\r\n?/g, '\n'))?.[1] || '';
+    const field = (key) => new RegExp(`^${key}:[ \\t]*(\\S+)`, 'm').exec(frontmatter)?.[1];
+    const revision = field('greprag_revision');
+    return {
+        skillId: field('greprag_skill_id'),
+        contentHash: field('greprag_content_hash'),
+        revision: revision === undefined ? undefined : Number(revision),
+        format: field('greprag_adapter_format'),
+    };
+}
+/** Managed adapters whose canon or renderer has moved since they were written.
+ *  An adapter edited locally, so its bytes no longer match the ledger, stays
+ *  with the divergence guard and costs no fetch. A missing one stays missing. */
+function staleNativeAdapters(params) {
+    const globalRoot = (0, native_skill_mirror_1.nativeSkillRoot)(params.platform, params.homeDir);
+    const roots = [globalRoot];
+    // Claude adapters live only in the home root (claude-lifecycle-cutover.ts).
+    const projectRoot = params.projectDir && params.platform !== 'claude-code'
+        ? (0, native_skill_mirror_1.writerOwnedProjectSkillRoot)(params.platform, params.projectDir, params.homeDir)
+        : null;
+    if (projectRoot)
+        roots.push(projectRoot);
+    const byId = new Map();
+    for (const row of params.rows) {
+        if (typeof row.skillName === 'string' && typeof row.skillId === 'string') {
+            byId.set(row.skillId, row);
+        }
+    }
+    const format = (0, native_skill_mirror_1.nativeAdapterFormat)(params.platform);
+    const stale = [];
+    for (const root of roots) {
+        for (const [skillName, managed] of Object.entries((0, native_skill_mirror_1.readState)(root).skills)) {
+            let files;
+            try {
+                files = (0, native_skill_mirror_1.readManagedFiles)((0, native_skill_mirror_1.targetPath)(root, skillName), managed);
+            }
+            catch {
+                continue;
+            }
+            if (!files?.length || (0, skill_mirror_files_1.computeSkillFileHash)(files) !== managed.hash)
+                continue;
+            const stamps = readAdapterStamps(files.find(file => file.path === 'SKILL.md')?.content || '');
+            const row = byId.get(stamps.skillId || (root === globalRoot ? `global:${skillName}` : ''));
+            if (!row || row.skillName !== skillName)
+                continue;
+            // The content hash is canon's identity. Revision only decides for a row
+            // that predates content hashes; comparing it otherwise would fight writers
+            // that do not know the revision.
+            const canonMoved = row.contentHash
+                ? row.contentHash !== stamps.contentHash
+                : typeof row.revision === 'number' && row.revision !== stamps.revision;
+            if (canonMoved || stamps.format !== format)
+                stale.push({ root, row });
+        }
+    }
+    return stale;
+}
+/** Rewrite each stale managed adapter of this harness from canon, through the
+ *  writer the sync commands use. One adapter per write, so a diverged one holds
+ *  back no other. A harness without native adapters is a no-op. */
+async function refreshNativeAdapters(params) {
+    const platform = params.platform;
+    if (platform !== 'claude-code' && platform !== 'codex' && platform !== 'opencode') {
+        return { refreshed: 0, blocked: 0 };
+    }
+    const stale = staleNativeAdapters({ ...params, platform });
+    const skills = await Promise.all(stale.map(({ row }) => (0, native_skill_mirror_1.fetchNativeMirroredSkill)(params.apiUrl, params.apiKey, row).catch(() => null)));
+    let refreshed = 0;
+    let blocked = 0;
+    for (const skill of skills) {
+        if (!skill)
+            continue; // canon unreachable: the next session start retries
+        try {
+            const result = platform === 'claude-code'
+                ? (0, claude_lifecycle_cutover_1.applyClaudeLifecycleCutover)({ skills: [skill], names: [skill.skillName], homeDir: params.homeDir })
+                : (0, native_skill_mirror_1.applyNativeSkillMirror)({
+                    platform,
+                    skills: [skill],
+                    homeDir: params.homeDir,
+                    projectDir: params.projectDir,
+                    prune: false,
+                });
+            refreshed += result.updated;
+            blocked += result.blocked;
+        }
+        catch {
+            blocked++;
+        }
+    }
+    return { refreshed, blocked };
+}