greprag 5.80.0 → 5.82.0

package/dist/repodoc-client.js

@@ -0,0 +1,296 @@
+"use strict";
+/** Keep a repository's chunk index rebuilt as its documents change.
+ *
+ *  The chunks are a DERIVED index, not a second copy of the truth: the document
+ *  is authoritative, the node graph beside it records what the document looked
+ *  like last time, and the chunks are regenerated from those two. A derived
+ *  thing maintained by hand drifts from its source and starts behaving like a
+ *  second truth, which is what `greprag repodoc push` was on its way to
+ *  becoming — correct only for as long as someone remembered to run it.
+ *
+ *  So this rides the Stop hook, exactly as the skill mirror and doc pointers do.
+ *  No new hook: the hook already knows every file the turn wrote, so a markdown
+ *  write is already an event. For each touched document the graph decides
+ *  whether anything moved (its body hash plus the fingerprints), and only what
+ *  moved is rebuilt and shipped. An unchanged document costs one read and one
+ *  hash, and no network at all.
+ *
+ *  Best-effort throughout. A failure here must never fail a turn — a stale chunk
+ *  index is a worse search result, while a thrown Stop hook is lost work.
+ *
+ *  adr: adr/node-identity-port.md
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isGeneratedAdapter = void 0;
+exports.isRepoDocEligible = isRepoDocEligible;
+exports.maybeRebuildChunks = maybeRebuildChunks;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const skill_mirror_files_1 = require("./skill-mirror-files");
+let cachedEngine;
+/** Loaded lazily and at most once. A missing bundle means a partial build, not
+ *  a reason to fail a turn, so it resolves to null and every caller no-ops. */
+function engine() {
+    if (cachedEngine !== undefined)
+        return cachedEngine;
+    try {
+        const p = path.join(__dirname, 'node-identity.bundle.js');
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        cachedEngine = fs.existsSync(p) ? require(p) : null;
+    }
+    catch {
+        cachedEngine = null;
+    }
+    return cachedEngine;
+}
+// ---------- repo gating -------------------------------------------------------
+/** The directory holding a repository's node graphs. Its EXISTENCE is the
+ *  opt-in: a repository nobody has indexed is never touched, so an agent
+ *  wandering through an unrelated checkout cannot start writing graphs into it.
+ *  Opting in stays a deliberate `greprag repodoc index <path> --write`. */
+const GRAPH_DIR = path.join('.greprag', 'node-identity');
+function findRepoRoot(start) {
+    let dir = path.resolve(start);
+    for (;;) {
+        if (fs.existsSync(path.join(dir, '.git')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** Repository name, from git's COMMON directory so a worktree writes into the
+ *  same store as the checkout it was cut from. Mirrors `commands/repodoc.ts`. */
+function repoName(repoRoot) {
+    try {
+        const common = (0, child_process_1.execFileSync)('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+            cwd: repoRoot, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        if (common)
+            return path.basename(path.dirname(common));
+    }
+    catch { /* not a checkout, or git absent */ }
+    return path.basename(repoRoot);
+}
+/** THE eligibility filter. `commands/repodoc.ts` imports this rather than
+ *  keeping its own, because the two disagreeing is a drift generator: the
+ *  command would index a document the hook then refuses to maintain, leaving it
+ *  frozen at whatever it said the day it was indexed. Whatever can be indexed
+ *  must be maintainable, and that is one predicate, in one place.
+ *
+ *  Rejects the same never-index classes the doc-pointer filter does: harness and
+ *  scratch directories, dependency and build trees, and CLAUDE.md / MEMORY.md,
+ *  which are injected into every session anyway. */
+function isRepoDocEligible(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;
+}
+/** A generated launcher, not skill content.
+ *
+ *  About half the skills on disk are disposable adapters that greprag itself
+ *  writes — a few lines telling the harness to run `greprag load <name>`, with
+ *  the real body served from the skill mirror. Indexing them would fill the
+ *  store with near-identical stubs that match almost any query about skills
+ *  while containing no skill, and re-generating one would churn its chunks for
+ *  no reason. One recogniser, shared with the mirror's upload and load paths. */
+var skill_mirror_files_2 = require("./skill-mirror-files");
+Object.defineProperty(exports, "isGeneratedAdapter", { enumerable: true, get: function () { return skill_mirror_files_2.isGeneratedSkillAdapter; } });
+// ---------- rebuild -----------------------------------------------------------
+/** Ceiling on documents rebuilt per turn. A turn that rewrote hundreds of files
+ *  is a bulk edit; that is `greprag repodoc push`'s job, with its progress
+ *  output, rather than something to do silently inside a Stop hook. */
+const MAX_DOCS_PER_TURN = 25;
+const NOTHING = { rebuilt: 0, unchanged: 0, deferred: 0 };
+/** Rebuild the chunk index for whichever documents this turn actually changed.
+ *
+ *  Returns counts for logging. Never throws. */
+async function maybeRebuildChunks(params) {
+    try {
+        if (!params.apiKey || params.filesTouched.length === 0)
+            return NOTHING;
+        const eng = engine();
+        if (!eng)
+            return NOTHING;
+        // Group by each file's OWN repository, not the session's.
+        //
+        // A turn routinely writes outside the directory it started in: editing a
+        // skill under ~/.claude while working in a project is the ordinary case, and
+        // that is exactly the content most worth keeping fresh. Resolving one root
+        // from cwd would discard every such write as "outside the repo", so skills
+        // would go stale the moment they were indexed — the failure this whole
+        // mechanism exists to prevent.
+        const byRepo = new Map();
+        for (const abs of params.filesTouched) {
+            const root = findRepoRoot(path.dirname(abs));
+            if (!root)
+                continue;
+            // The opt-in gate, per repository. No graphs, no involvement.
+            if (!fs.existsSync(path.join(root, GRAPH_DIR)))
+                continue;
+            const group = byRepo.get(root);
+            if (group)
+                group.push(abs);
+            else
+                byRepo.set(root, [abs]);
+        }
+        if (byRepo.size === 0)
+            return NOTHING;
+        const totals = { rebuilt: 0, unchanged: 0, deferred: 0 };
+        for (const [root, files] of byRepo) {
+            const one = await rebuildOne(eng, root, files, params.apiUrl, params.apiKey);
+            totals.rebuilt += one.rebuilt;
+            totals.unchanged += one.unchanged;
+            totals.deferred += one.deferred;
+        }
+        return totals;
+    }
+    catch {
+        return NOTHING;
+    }
+}
+/** One repository's share of a turn. Isolated so a failure in one repository
+ *  cannot cost another its rebuild. */
+async function rebuildOne(eng, repoRoot, filesTouched, apiUrl, apiKey) {
+    try {
+        const documents = [];
+        const pending = [];
+        let unchanged = 0;
+        let deferred = 0;
+        const seen = new Set();
+        for (const abs of filesTouched) {
+            const rel = path.relative(repoRoot, abs).replace(/\\/g, '/');
+            if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+                continue;
+            if (!isRepoDocEligible(rel) || seen.has(rel))
+                continue;
+            seen.add(rel);
+            if (documents.length >= MAX_DOCS_PER_TURN) {
+                deferred++;
+                continue;
+            }
+            const sidecarRel = eng.sidecarPathFor(rel);
+            if (!sidecarRel)
+                continue;
+            let body;
+            try {
+                body = fs.readFileSync(abs, 'utf-8');
+            }
+            catch {
+                // Written then deleted within the turn. The store keeps its chunks until
+                // the document is retired explicitly; see the ADR's known gap.
+                continue;
+            }
+            if ((0, skill_mirror_files_1.isGeneratedSkillAdapter)(body))
+                continue;
+            const sidecarAbs = path.join(repoRoot, sidecarRel);
+            let stored = null;
+            try {
+                if (fs.existsSync(sidecarAbs)) {
+                    stored = eng.parseNodeGraph(fs.readFileSync(sidecarAbs, 'utf-8'));
+                }
+            }
+            catch {
+                stored = null;
+            }
+            const result = eng.reconcile(stored, eng.markdownToBlocks(body), { path: rel, body });
+            // The change gate. Nothing moved means nothing to write and nothing to
+            // ship — the whole point of storing a graph rather than re-deriving one.
+            if (!result.changed) {
+                unchanged++;
+                continue;
+            }
+            documents.push({ path: rel, blocks: result.blocks });
+            pending.push({ sidecar: sidecarAbs, text: eng.serializeNodeGraph(result.graph) });
+        }
+        if (documents.length === 0)
+            return { rebuilt: 0, unchanged, deferred };
+        // Ship first, then persist the graphs. If the push fails the graphs stay as
+        // they were, so the next turn sees the same documents as still-changed and
+        // tries again. Writing the graphs first would mark them current against a
+        // store that never received them, and the drift would be permanent.
+        await pushDocuments(apiUrl, apiKey, repoName(repoRoot), documents);
+        for (const p of pending) {
+            try {
+                fs.mkdirSync(path.dirname(p.sidecar), { recursive: true });
+                fs.writeFileSync(p.sidecar, p.text, 'utf-8');
+            }
+            catch { /* unwritable — next turn retries */ }
+        }
+        return { rebuilt: documents.length, unchanged, deferred };
+    }
+    catch {
+        return NOTHING;
+    }
+}
+async function pushDocuments(apiUrl, apiKey, project, documents) {
+    const res = await fetch(`${apiUrl}/v1/repodoc/${encodeURIComponent(project)}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
+        body: JSON.stringify({
+            documents: documents.map(d => ({
+                path: d.path,
+                blocks: d.blocks.map(b => ({
+                    id: b.id,
+                    position: b.position,
+                    type: b.type,
+                    text: b.text,
+                    parentPosition: b.parentPosition,
+                    ordinalInParent: b.ordinalInParent,
+                    ...(b.level !== undefined ? { level: b.level } : {}),
+                    ...(b.language !== undefined ? { language: b.language } : {}),
+                    headingPath: b.headingPath,
+                })),
+            })),
+        }),
+    });
+    if (!res.ok) {
+        throw new Error(`repodoc push ${res.status}`);
+    }
+}

package/dist/session-id.js

@@ -205,8 +205,8 @@ function buildSessionIdContext(short, alias = null) {
  *  made the wrapper unsafe before. The layers: this loop relaunches a dead
  *  SUPERVISOR; the supervisor respawns a dead SSE CHILD; EPIPE-terminal stops
  *  everything when the consumer leaves. adr: adr/monitor-resilience.md */
-function armMonitorCommand(short, ownerPid, assistant = false, mechanic = false, platform) {
-    const role = mechanic ? ' --mechanic' : (assistant ? ' --assistant' : '');
+function armMonitorCommand(short, ownerPid, mechanic = false, platform) {
+    const role = mechanic ? ' --mechanic' : '';
     // Grok monitor merges stderr into wake events and does not restart on exit.
     // Bare quiet watch: JSON mail on stdout only. No bash wrapper, no --owner-pid.
     // adr: adr/grok-platform.md
@@ -217,10 +217,9 @@ function armMonitorCommand(short, ownerPid, assistant = false, mechanic = false,
     }
     // --owner-pid is stamped for audit continuity only; the count-cap never reads it.
     const owner = ownerPid ? ` --owner-pid ${ownerPid}` : '';
-    // --assistant elevates the watcher to the tenant's Assistant subscription
-    // (session ∪ inbound-email arrivals) — added ONLY for the designated assistant
-    // project (isAssistantProject), so a normal session arms a stock watcher.
-    // adr: adr/assistant-role.md
+    // --mechanic elevates the watcher to the live-Mechanic subscription (session ∪
+    // tenant mechanic_friction) — added ONLY for the designated mechanic project,
+    // so a normal session arms a stock watcher. adr: adr/assistant-role.md
     const watch = `greprag inbox watch --session ${short} --json${owner}${role}`;
     // Break on 0 (consumer-gone / clean / signal) and 64 (FATAL: bad key) — both are
     // intentional terminals; relaunch on any other code (a crash). `sleep 1` floors
@@ -230,9 +229,9 @@ function armMonitorCommand(short, ownerPid, assistant = false, mechanic = false,
 /** Backward-compatible copyable watcher directive for older hook consumers.
  *  Current hooks use the detection-gated reminder registry, but keeping this
  *  pure formatter exported preserves the public helper and older integrations. */
-function buildArmDirective(short, alias = null, ownerPid, assistant = false, mechanic = false) {
+function buildArmDirective(short, alias = null, ownerPid, mechanic = false) {
     const reply = `${alias || '<handle>'}@greprag.com/${short}`;
-    const command = armMonitorCommand(short, ownerPid, assistant, mechanic, undefined);
+    const command = armMonitorCommand(short, ownerPid, mechanic, undefined);
     return 'STOP IMMEDIATELY AND READ THIS. '
         + `No live inbox watcher is armed for ${reply}. `
         + 'ToolSearch query "select:Monitor" and arm a persistent:true Monitor '

package/dist/skill-landing.js

@@ -64,16 +64,18 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_FUSES_PER_SKILL = exports.LEARNINGS_RELPATH = exports.LEARNED_DIR_RELPATH = exports.BUNDLED_SKILLS = void 0;
+exports.isGeneratedAdapter = exports.MAX_FUSES_PER_SKILL = exports.LEARNINGS_RELPATH = exports.LEARNED_DIR_RELPATH = exports.BUNDLED_SKILLS = void 0;
 exports.resolveSkillDir = resolveSkillDir;
 exports.hasGainStamp = hasGainStamp;
 exports.countFuses = countFuses;
 exports.buildFuseLine = buildFuseLine;
+exports.buildLoadFuseBlock = buildLoadFuseBlock;
 exports.landBriefcase = landBriefcase;
 exports.removeLandedGain = removeLandedGain;
 exports.landPendingGains = landPendingGains;
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
+const skill_mirror_files_1 = require("./skill-mirror-files");
 /** Skills that ship FROM the greprag repo — their canonical source is
  *  packages/cli/skill/<name>/; the installed copy is overwritten at init. */
 exports.BUNDLED_SKILLS = ['greprag', 'commander', 'content-advisor', 'mechanic'];
@@ -112,12 +114,53 @@ function countFuses(skillMdContent) {
  *  names the learning; the mass lives in the doc), carrying the exact
  *  schematic for the next invocation. PURE — unit-tested. */
 function buildFuseLine(gain, docRelPath, projectName, dateISO) {
+    // The anchor is the attribution, shown. A gain claims THIS skill by quoting
+    // this skill's own purpose back; printing that quote turns "is this even
+    // mine?" into a one-glance check instead of a trip through the learned doc.
+    // The 2026-09-03 field audit found 7 of 8 fuses on the wrong skill, and
+    // nothing on the line said why any of them belonged there.
+    // adr: adr/skill-gain-attribution.md
+    const claim = gain.anchor
+        ? `Claims this skill via its purpose: "${gain.anchor}". `
+        : '';
     return (`⚙ SKILL UPDATE PENDING (${gain.gainType}) — ${gain.oneLiner} `
+        + claim
         + `→ BEFORE working: read ${docRelPath.replace(/\\/g, '/')}, fold the learning into this `
         + `skill where it belongs (one small edit, keep it lean), then DELETE this line and the doc. `
-        + `Bogus? \`greprag skillgain reject ${gain.nodeId}\` instead. `
+        + `Doesn't belong to this skill, or bogus? \`greprag skillgain reject ${gain.nodeId}\` instead. `
         + `<!-- skillgain:${gain.nodeId} ${dateISO.slice(0, 10)} project:${projectName} -->`);
 }
+/** Render pending gains for a mirror-managed skill into its `greprag load`
+ *  payload — the fuse's replacement for skills whose SKILL.md is a generated
+ *  adapter nothing local may write to.
+ *
+ *  Carries strictly more than the fuse line did: the learning doc is inlined
+ *  rather than pointed at, because a managed skill has no local docs/learned/
+ *  to read. Empty string when there is nothing pending, so the caller can
+ *  append unconditionally. PURE — unit-tested. adr: adr/skill-fuse-delivery.md */
+function buildLoadFuseBlock(skill, gains) {
+    const usable = gains.filter(g => g.oneLiner && g.skill === skill);
+    if (usable.length === 0)
+        return '';
+    const head = usable.length === 1
+        ? `⚙ 1 PENDING SKILL UPDATE for ${skill} — fold it in before acting on this skill.`
+        : `⚙ ${usable.length} PENDING SKILL UPDATES for ${skill} — fold them in before acting on this skill.`;
+    const items = usable.map((g, i) => {
+        const claim = g.anchor
+            ? `\n   Claims this skill via its purpose: "${g.anchor}"`
+            : '';
+        const doc = g.docBody ? `\n\n${g.docBody.trim()}\n` : '';
+        return (`${i + 1}. (${g.gainType}) ${g.oneLiner}${claim}${doc}\n`
+            + `   Digest: make the edit, then \`greprag skillgain done ${g.nodeId}\`.\n`
+            + `   Doesn't belong to this skill, or bogus? \`greprag skillgain reject ${g.nodeId}\`.`);
+    });
+    return `\n---\n\n${head}\n\n${items.join('\n\n')}\n`;
+}
+/** A generated mirror adapter is machine-owned: regenerated from the mirror on
+ *  any sync, hash-locked against edits in between. One recogniser for the whole
+ *  CLI lives in `skill-mirror-files`. */
+var skill_mirror_files_2 = require("./skill-mirror-files");
+Object.defineProperty(exports, "isGeneratedAdapter", { enumerable: true, get: function () { return skill_mirror_files_2.isGeneratedSkillAdapter; } });
 /** Land ONE briefcase: write the learned doc + append the fuse to SKILL.md.
  *  Deterministic file work only — never throws (failure defers the gain). */
 function landBriefcase(gain, cwd, homeDir, projectName) {
@@ -137,6 +180,18 @@ function landBriefcase(gain, cwd, homeDir, projectName) {
         }
         if (hasGainStamp(body, gain.nodeId))
             return 'already-landed';
+        // A mirror-managed skill's SKILL.md is a GENERATED adapter: the mirror
+        // regenerates it on every sync and hash-locks it in between. Appending a
+        // fuse there makes two writers own one file — the fuse is wiped by the next
+        // sync, or (worse) the divergence guard refuses the sync and the operator
+        // has to untangle it by hand. Happened twice on 2026-09-04.
+        //
+        // For these skills the fuse is served by `greprag load` instead, which is
+        // the payload the adapter tells the agent to read — same arrival moment,
+        // one writer. The gain stays PENDING so the load path keeps surfacing it
+        // until it is digested. adr: adr/skill-fuse-delivery.md
+        if ((0, skill_mirror_files_1.isGeneratedSkillAdapter)(body))
+            return 'served-by-load';
         if (countFuses(body) >= exports.MAX_FUSES_PER_SKILL)
             return 'capped';
         // Doc first (a fuse pointing at a missing doc is the one broken state).

package/dist/skill-mirror-client.js

@@ -295,6 +295,20 @@ async function maybeMirrorSkill(params) {
         const files = collectSkillFiles(dir);
         if (!files)
             return 'skipped';
+        // The disk copy of an already-mirrored skill is the generated ADAPTER that
+        // `materializeLocally` wrote below — a launcher whose whole body says "run
+        // `greprag load <name>`". Uploading it makes it canon, and `greprag load`
+        // then serves the launcher back to the agent that was told to run it: the
+        // skill's real instructions are gone and nothing errors. That loop closed
+        // here, one turn after every first mirror, and had already eaten the
+        // canonical body of skills including anti-ai, chrome, gmail and root-cause.
+        //
+        // An adapter is never a mirror source. Canon changes through the guarded
+        // edit path (`greprag skill edit` / `skill mirror apply`), never by
+        // shadowing a file greprag itself generated. adr: adr/skill-adapter-never-canon.md
+        const main = files.find(file => file.path === 'SKILL.md');
+        if (main && (0, skill_mirror_files_1.isGeneratedSkillAdapter)(main.content))
+            return 'skipped';
         const hash = computeMirrorHash(files);
         const state = readMirrorState();
         const localLease = state.skills[params.skill]?.hash;

package/dist/skill-mirror-files.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.computeSkillFileHash = computeSkillFileHash;
+exports.isGeneratedSkillAdapter = isGeneratedSkillAdapter;
 exports.isSafeMirroredSkillFile = isSafeMirroredSkillFile;
 const crypto = __importStar(require("node:crypto"));
 function computeSkillFileHash(files) {
@@ -43,6 +44,23 @@ function computeSkillFileHash(files) {
     }
     return hash.digest('hex');
 }
+/** The heading every generated mirror adapter carries. A file with this in its
+ *  header is machine-owned: a disposable launcher that tells the agent to run
+ *  `greprag load <name>`, never canonical skill content. */
+const GENERATED_ADAPTER_MARKER = '## GENERATED ADAPTER — NEVER EDIT';
+/** True when this SKILL.md is a generated adapter rather than a real skill body.
+ *
+ *  Checked against the HEAD of the body, after the YAML frontmatter: the marker
+ *  is a header, and a document that merely discusses adapters further down is
+ *  real content. Frontmatter must be stripped first — an adapter's `description`
+ *  block alone can run past any fixed byte window, which is how 53 adapters
+ *  slipped past a raw first-400-bytes check. PURE.
+ *
+ *  adr: adr/skill-adapter-never-canon.md */
+function isGeneratedSkillAdapter(skillMdBody) {
+    const body = skillMdBody.replace(/^?---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
+    return body.slice(0, 400).includes(GENERATED_ADAPTER_MARKER);
+}
 function isSafeMirroredSkillFile(file) {
     if (file.path === 'SKILL.md')
         return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "greprag",
-  "version": "5.80.0",
+  "version": "5.82.0",
   "description": "Private GrepRAG client for existing Claude Code, Codex, OpenCode, and Grok Build tenants.",
   "main": "dist/index.js",
   "bin": {
@@ -9,7 +9,7 @@
     "greprag-codex-hook": "dist/codex-fast-hook.js"
   },
   "scripts": {
-    "build": "rimraf dist && tsc && node scripts/bundle-opencode-plugin.mjs",
+    "build": "rimraf dist && tsc && node scripts/bundle-opencode-plugin.mjs && node scripts/bundle-node-identity.mjs",
     "clean": "rimraf dist",
     "postinstall": "node scripts/postinstall.js"
   },

package/scripts/bundle-node-identity.mjs

@@ -0,0 +1,47 @@
+/**
+ * bundle-node-identity.mjs — compile the edit-surviving matcher into a single
+ * self-contained artifact the CLI can require at runtime.
+ *
+ * WHY THIS EXISTS — the CLI is a zero-dependency tsc artifact and cannot import
+ * @greprag/core (see the note at the top of commands/crush.ts, which had to
+ * hand-copy core logic for the same reason and now carries the drift risk that
+ * creates). node-identity is pure TypeScript with no runtime imports outside
+ * itself, so it can simply be built from core's source on every CLI build. That
+ * is strictly better than a copy: there is one source of truth, and a change to
+ * the matcher cannot silently fail to reach the CLI.
+ *
+ * The entry is inline rather than a file in core, because what the CLI needs is
+ * a CLI concern — the matcher plus the walker that feeds it — and core should
+ * not carry a module that exists only to shape someone else's bundle.
+ *
+ * Nothing but Node builtins is external because nothing else is reachable: the
+ * whole import graph is node-graph + node-identity, both dependency-free.
+ *
+ * adr: adr/node-identity-port.md
+ */
+import { build } from 'esbuild';
+import { fileURLToPath } from 'url';
+import path from 'path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const cliRoot = path.resolve(__dirname, '..');
+const coreSrc = path.resolve(cliRoot, '..', 'core', 'src');
+
+await build({
+  stdin: {
+    contents: `
+      export { markdownToBlocks } from ${JSON.stringify(path.join(coreSrc, 'node-graph', 'index'))};
+      export * from ${JSON.stringify(path.join(coreSrc, 'node-identity', 'index'))};
+    `,
+    resolveDir: coreSrc,
+    loader: 'ts',
+  },
+  outfile: path.join(cliRoot, 'dist', 'node-identity.bundle.js'),
+  bundle: true,
+  platform: 'node',
+  format: 'cjs',
+  target: 'node18',
+  logLevel: 'warning',
+});
+
+console.log('bundled node-identity -> dist/node-identity.bundle.js');

package/skill/templates/chip-spawn.md

@@ -53,6 +53,10 @@ Your parent session is named `<parent-name>`. When you finish, report to it with
 ---
 ````
 
+**Get `<parent-name>` from `ListAgents` BEFORE composing.** It prints "This session is `<name>`" — that name is the chip's reply address. It is not your greprag 8-hex.
+
+**Worktree launch failed? START THE CHIP LOCALLY instead.** The harness creates the worktree before your Block 1 ever runs, and when that fails the spawning session sees nothing — no error, no exit code, only the operator reporting it is stuck. A local start is safe and self-correcting: Block 1 creates the worktree itself as its first action, so nothing is lost and nothing is done twice. If the same slug fails again, change the slug — you cannot see harness-side worktree errors, so elimination is the only tool you have.
+
 **Multi-chip mission (`greprag load chip-leader`)?** The spawn title alone does NOT reach FleetView's watcher registry — that title is auto-generated by gpt-5.4-nano from your opening turn. So the leader will have you **stamp your registry title in Block 1**, right after the `cd` into the worktree:
 
 ```bash
@@ -75,6 +79,8 @@ Close the task body with this (substitute `<slug>` + `<parent-name>`):
 
 The parent is a live session on this machine — no greprag address, no watcher. If `SendMessage` errors because the parent has ended, stop and leave the commit on the branch; the parent picks it up at merge.
 
+**Then close yourself:** once the report has landed, run `/close`. It takes the chip path automatically (it recognises a `chip/` branch), so it sends no question and touches nothing outside this worktree — it commits any stragglers, confirms the report, and archives the session, which removes this worktree. Your branch survives for the parent to merge. If the report failed because the parent is gone, do NOT close — leave the worktree standing.
+
 **Cleanup discipline (HARD RULE):** chip prompts forbid `git clean`, `git reset --hard`, `git worktree remove`, `git checkout <other>`, raw `rm -rf` outside the worktree's tracked files.
 ````
 
@@ -94,6 +100,6 @@ Chips never `npm run deploy` (or Wrangler / another provider deploy) from the wo
 
 ## Parent merge discipline — prune at the merge (HARD RULE)
 
-When you (the parent) merge a chip branch — through the canonical commit path or a profile-declared merge — prune in the same breath: junction guard (`~/.claude/skills/commit/guard-junctions.sh <worktree>`), `git worktree remove .claude/worktrees/<slug>`, and `git branch -d chip/<slug>` once merged. Deferred cleanup = stale worktrees piling up (field state 2026-06-10: 3 leftovers). Multi-chip missions: worktree dies at the integration-branch merge; the branch lives until the configured default-branch merge (chip-leader Phase 4).
+When you (the parent) merge a chip branch — through the canonical commit path or a profile-declared merge — prune in the same breath: junction guard (`~/.claude/skills/commit/guard-junctions.sh <worktree>`), `git worktree remove .claude/worktrees/<slug>`, and `git branch -d chip/<slug>` once merged. A chip that closed itself has already removed its own worktree, so that path will be gone — delete the branch and move on, don't go hunting for it. Deferred cleanup = stale worktrees piling up (field state 2026-06-10: 3 leftovers). Multi-chip missions: worktree dies at the integration-branch merge; the branch lives until the configured default-branch merge (chip-leader Phase 4).
 
 **FIX chips report to the mission owner.** A `greprag fix spawn` mission is the source of truth for FIX behavior. `fix spawn` detects usable Git history and emits `workspaceMode`: Git uses an isolated worktree; non-Git, unavailable Git, or no commit uses the project-local task with serialized writes. Dispatch honors that mode without trying a worktree first. The FIX chip identifies the exact friction, makes the smallest durable root-cause fix, verifies and commits useful work, then reports the commit/result and cleanup parameters to the parent mission owner. It creates no human landing gate. If no live parent exists and the chip carries the full-goal mission, it follows the repo profile as mission owner.