brainclaw 1.8.0 → 1.9.1

package/dist/core/events/registry-post-image.js

@@ -0,0 +1,110 @@
+/**
+ * Registry / coordination family post-images (pln#568, phase 1.5).
+ *
+ * The 5 memory families (constraint/decision/trap/handoff/plan) journal full
+ * post-images via state.ts `emitPerEntityJournalRecords`. The registry /
+ * coordination families persist through their own JsonStore chokepoints and
+ * historically reached the journal envelope-only (registry-lifecycle, 0
+ * payload) or not at all (trp_2a89ae97) — so the observer could never rebuild
+ * them from the journal and had to seed them from an MCP `board_summary`.
+ *
+ * This is their post-image emit, mirroring the memory path: ONE entity-state
+ * `create`/`update` record carrying the byte-faithful prepared document (the
+ * same bytes JsonStore.save writes to the projection file) plus a
+ * journal-assigned `entity_rev`. Because the materialize reducer already
+ * upserts ANY entity-state record (materialize.ts `applyRecordsToLive`), no
+ * reducer change is needed — the families light up the moment these records
+ * appear.
+ *
+ * I2 — JOURNAL BEFORE PROJECTION. Callers MUST invoke {@link emitRegistryPostImage}
+ * BEFORE writing the projection file (and inside the same mutation lock), so a
+ * crash mid-persist can only leave the journal AHEAD of the projection (the one
+ * direction lazy-reconcile can recover), never the projection ahead. Use
+ * {@link registryFaultPoint} between the emit and the file write to test it.
+ *
+ * The journal `item_type` deliberately matches the observer's `ARRAY_SLOT`
+ * keys (vscode-extension/src/board-projection.ts) so a post-image flows
+ * straight into the right board slot with no consumer change. Note the one
+ * non-obvious mapping: action_required entities journal under item_type
+ * `state` (the slot the observer already reserved for them), not `action`.
+ *
+ * @module
+ */
+import { appendJournalRecords, resolveJournalMode } from './journal.js';
+import { preparePersistedDocument } from '../migration.js';
+/**
+ * The registry / coordination families that journal entity-state post-images.
+ * `action`'s journal item_type is `state` (not `action`) to match the slot the
+ * observer reserved for action_required entities.
+ */
+export const REGISTRY_FAMILIES = {
+    claim: { journalItemType: 'claim', docType: 'claim' },
+    assignment: { journalItemType: 'assignment', docType: 'assignment' },
+    agent_run: { journalItemType: 'agent_run', docType: 'agent_run' },
+    action: { journalItemType: 'state', docType: 'action_required' },
+    candidate: { journalItemType: 'candidate', docType: 'candidate' },
+    runtime_note: { journalItemType: 'runtime_note', docType: 'runtime_note' },
+    sequence: { journalItemType: 'sequence', docType: 'sequence' },
+};
+/**
+ * Journal item_types that carry a registry post-image. The dual-write envelope
+ * suppression (event-log.ts) keys off this so these families appear in the v2
+ * journal ONLY as post-images, never as the legacy envelope-only lifecycle
+ * record. Derived from REGISTRY_FAMILIES so the two can never drift.
+ */
+export const REGISTRY_POST_IMAGE_ITEM_TYPES = new Set(Object.values(REGISTRY_FAMILIES)
+    .map((spec) => spec.journalItemType)
+    // `state` is excluded: the coarse persist store_marker also uses item_type
+    // `state` (without an item_id) and must keep dual-writing its journal_note.
+    // The action post-image is disambiguated by its item_id, so its OWN emit
+    // path (emitRegistryPostImage) is what journals it — not the envelope.
+    .filter((itemType) => itemType !== 'state'));
+/**
+ * Emit ONE entity-state post-image for a registry/coordination entity. No-op
+ * when the journal is off. Failures are swallowed inside appendJournalRecords
+ * (dual mode: the v1 projection remains the source of truth).
+ */
+export function emitRegistryPostImage(family, item, opts = {}) {
+    if (resolveJournalMode(opts.cwd) === 'off')
+        return;
+    const spec = REGISTRY_FAMILIES[family];
+    appendJournalRecords([{
+            action: opts.created ? 'create' : 'update',
+            item_type: spec.journalItemType,
+            item_id: item.id,
+            agent: opts.agent ?? 'system',
+            agent_id: opts.agent_id,
+            session_id: opts.session_id,
+            payload: preparePersistedDocument(spec.docType, item),
+        }], opts.cwd);
+}
+/**
+ * Emit a tombstone for a registry entity whose projection file is removed
+ * (e.g. a candidate that left the pending inbox). No-op when the journal is off.
+ */
+export function emitRegistryTombstone(family, id, opts = {}) {
+    if (resolveJournalMode(opts.cwd) === 'off')
+        return;
+    const spec = REGISTRY_FAMILIES[family];
+    appendJournalRecords([{
+            action: 'delete',
+            item_type: spec.journalItemType,
+            item_id: id,
+            agent: opts.agent ?? 'system',
+            agent_id: opts.agent_id,
+            session_id: opts.session_id,
+        }], opts.cwd);
+}
+/**
+ * Test-only crash injection (mirrors state.ts `faultPoint`). No-op unless
+ * BRAINCLAW_FAULT_POINT matches — then it throws, simulating a process death at
+ * that exact point so the I2 journal-before-projection ordering can be tested
+ * deterministically. Callers place it BETWEEN the post-image emit and the
+ * projection file write.
+ */
+export function registryFaultPoint(label) {
+    if (process.env.BRAINCLAW_FAULT_POINT === label) {
+        throw new Error(`fault-injection: crashed at "${label}" (BRAINCLAW_FAULT_POINT)`);
+    }
+}
+//# sourceMappingURL=registry-post-image.js.map

package/dist/core/events/verify.js

@@ -0,0 +1,109 @@
+/**
+ * Projection-vs-journal verification (pln#543 cutover gate).
+ *
+ * Lives in its OWN module (not materialize.ts) on purpose: it needs `loadState`
+ * (projection read) AND the journal materializer. If this dependency sat in
+ * materialize.ts, the materialize -> state edge would close a cycle
+ * state -> events/checkpoint -> events/materialize -> state once the checkpoint
+ * read path is wired into loadState — a module-init TDZ class (trp_187e42e9).
+ * Keeping verify here means materialize never imports state; verify.ts is
+ * imported only by doctor + tests, never by state.
+ *
+ * @module
+ */
+import { loadState } from '../state.js';
+import { MEMORY_FAMILIES, materializeMemoryStateFromJournal, materializeRegistryFromJournal } from './materialize.js';
+import { listClaims } from '../claims.js';
+import { listAssignments } from '../assignments.js';
+import { listAgentRuns } from '../agentruns.js';
+import { listActionRequired } from '../actions.js';
+import { listCandidates } from '../candidates.js';
+import { listSequences } from '../sequence.js';
+import { listSharedJournaledRuntimeNotes } from '../runtime.js';
+import { REGISTRY_FAMILIES } from './registry-post-image.js';
+import { preparePersistedDocument } from '../migration.js';
+function stable(value) {
+    return JSON.stringify(value, (_k, v) => {
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            return Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b)));
+        }
+        return v;
+    });
+}
+/**
+ * Compare projection-read state (the truth in dual mode) against the
+ * journal-materialized state. Empty drift = the dual-write is faithful and
+ * the journal can be trusted as a read substrate — the cutover gate
+ * (`brainclaw doctor --verify-journal`).
+ */
+export function verifyProjectionsAgainstJournal(cwd) {
+    const projection = loadState(cwd);
+    const journal = materializeMemoryStateFromJournal(cwd);
+    const drift = [];
+    for (const { itemType, collection } of MEMORY_FAMILIES) {
+        const projItems = new Map(projection[collection].map(i => [i.id, i]));
+        const jrnItems = new Map(journal[collection].map(i => [i.id, i]));
+        for (const [id, projItem] of projItems) {
+            const jrnItem = jrnItems.get(id);
+            if (!jrnItem)
+                drift.push({ item_type: itemType, item_id: id, kind: 'missing_in_journal' });
+            else if (stable(projItem) !== stable(jrnItem))
+                drift.push({ item_type: itemType, item_id: id, kind: 'mismatch' });
+        }
+        for (const id of jrnItems.keys()) {
+            if (!projItems.has(id))
+                drift.push({ item_type: itemType, item_id: id, kind: 'missing_in_projection' });
+        }
+    }
+    return drift;
+}
+/**
+ * The registry / coordination families covered by the registry verification
+ * (pln#568). Each maps its `RegistryFamily` (→ journal item_type + doc type) to
+ * the projection reader. Scoped to the coordination-class families wired in
+ * slice 1 plus the remaining pln#568-wired families. Runtime notes are scoped
+ * to shared visibility because private/machine notes deliberately do not enter
+ * the shared journal.
+ */
+const VERIFIED_REGISTRY_FAMILIES = [
+    { family: 'claim', list: listClaims },
+    { family: 'assignment', list: listAssignments },
+    { family: 'agent_run', list: listAgentRuns },
+    { family: 'action', list: listActionRequired },
+    // Only PENDING candidates are journaled (archive emits a tombstone, pln#568),
+    // so verify compares the pending projection against the journal live set.
+    { family: 'candidate', list: (cwd) => listCandidates('pending', cwd) },
+    { family: 'runtime_note', list: listSharedJournaledRuntimeNotes },
+    { family: 'sequence', list: listSequences },
+];
+/**
+ * Compare the registry projections (the dual-mode source of truth) against the
+ * journal-materialized registry post-images (pln#568). Empty drift = the
+ * registry dual-write is faithful and the observer can trust the journal for
+ * these families — the registry half of the cutover gate, mirroring
+ * {@link verifyProjectionsAgainstJournal} for the memory families. The
+ * comparison runs both sides through `preparePersistedDocument` so a projection
+ * item and its journal payload (which is exactly that) compare like-for-like.
+ */
+export function verifyRegistryAgainstJournal(cwd) {
+    const journal = materializeRegistryFromJournal(cwd);
+    const drift = [];
+    for (const { family, list } of VERIFIED_REGISTRY_FAMILIES) {
+        const spec = REGISTRY_FAMILIES[family];
+        const projItems = new Map(list(cwd).map((i) => [i.id, preparePersistedDocument(spec.docType, i)]));
+        const jrnItems = new Map((journal.get(spec.journalItemType) ?? []).map((e) => [e.item_id, e.payload]));
+        for (const [id, projItem] of projItems) {
+            const jrnItem = jrnItems.get(id);
+            if (!jrnItem)
+                drift.push({ item_type: spec.journalItemType, item_id: id, kind: 'missing_in_journal' });
+            else if (stable(projItem) !== stable(jrnItem))
+                drift.push({ item_type: spec.journalItemType, item_id: id, kind: 'mismatch' });
+        }
+        for (const id of jrnItems.keys()) {
+            if (!projItems.has(id))
+                drift.push({ item_type: spec.journalItemType, item_id: id, kind: 'missing_in_projection' });
+        }
+    }
+    return drift;
+}
+//# sourceMappingURL=verify.js.map

package/dist/core/execution-adapters.js

@@ -45,6 +45,25 @@ export function resolveBinaryOnPath(binary) {
         return undefined;
     }
 }
+/**
+ * Git author identity for a dispatched worker (pln#562 step 5). The email is
+ * a deterministic non-routable address so `git log --author` can filter by
+ * agent. Committer mirrors author so neither field lies about provenance.
+ */
+export function buildGitAttributionEnv(agent) {
+    const name = agent?.trim();
+    if (!name)
+        return {};
+    const slug = name.toLowerCase().replace(/[^a-z0-9._-]+/g, '-');
+    const display = `${name} (via brainclaw)`;
+    const email = `${slug}@agents.brainclaw.dev`;
+    return {
+        GIT_AUTHOR_NAME: display,
+        GIT_AUTHOR_EMAIL: email,
+        GIT_COMMITTER_NAME: display,
+        GIT_COMMITTER_EMAIL: email,
+    };
+}
 function buildManualEnvPrefix(claimId) {
     // pln#496 step stp_a9afe59d: the cross-platform / cross-shell logic
     // now lives in execution-profile.ts:buildClaimEnvPrefix. Keep this
@@ -80,6 +99,10 @@ export class CliExecutionAdapter {
         const isWin32 = process.platform === 'win32';
         const env = {
             ...process.env,
+            // pln#562 step 5 — truthful attribution: every commit a dispatched
+            // worker makes is authored as the AGENT, not as the human whose
+            // git config happens to be on the machine. invoke.env may override.
+            ...buildGitAttributionEnv(options.agent),
             ...(invoke.env ?? {}),
             ...(options.claimId ? { BRAINCLAW_CLAIM_ID: options.claimId } : {}),
         };

package/dist/core/execution.js

@@ -161,7 +161,7 @@ export async function attemptExecution(invoke, options) {
     // claim was reused/re-dispatched without one), REFUSE to spawn instead of
     // falling back to options.cwd — which is the integration repo, where the
     // worker would edit the main tree directly (dangerous for an autonomous fleet,
-    // debrief LeaseUp). Return the command for manual, isolated execution.
+    // a cross-project field debrief). Return the command for manual, isolated execution.
     if (options.requireWorktree && !options.worktreePath) {
         appendAuditEntry({
             actor: options.dispatcherAgent,

package/dist/core/facade-schema.js

@@ -15,6 +15,13 @@ export const WorkRequestSchema = z.object({
     contextTarget: z.string().optional(),
     project: z.string().optional(),
     compact: z.boolean().optional().default(true),
+    /**
+     * Approximate token budget for the context payload (agent-ux, pln#542).
+     * Relevance-ranked fill: the highest-scoring items are kept until the
+     * budget is reached (~4 chars/token heuristic). Applies to both compact
+     * and full payloads.
+     */
+    budget_tokens: z.number().int().positive().optional(),
 });
 export const CoordinateRequestSchema = z.object({
     intent: CoordinateIntentSchema,
@@ -128,6 +135,19 @@ export const VerifyWithSchema = z.object({
     /** Doc pointer for the diagnostic flow when the check fails. */
     see_also: z.string(),
 });
+/**
+ * Self-teaching affordance (agent-ux, pln#542): each response carries the
+ * recommended next call(s) with exact shapes, generalizing the verify_with
+ * pattern. Protocol teaching lives in responses, not the instruction file.
+ */
+export const NextActionSchema = z.object({
+    /** Tool to call next, e.g. "bclaw_release_claim". */
+    tool: z.string(),
+    /** Exact argument shape for the call (literal values where known, <placeholders> otherwise). */
+    args: z.record(z.string(), z.unknown()).optional(),
+    /** When this action applies, e.g. "when implementation is complete". */
+    when: z.string().optional(),
+});
 export const FacadeResponseSchema = z.object({
     status: z.enum(['ok', 'error', 'partial']),
     intent: z.string(),
@@ -151,6 +171,18 @@ export const FacadeResponseSchema = z.object({
      * Additive: existing callers that don't read it are unaffected.
      */
     bootstrap_recommended: z.boolean().optional(),
+    /**
+     * pln#557 step 3 — composite verdict behind `bootstrap_recommended`:
+     *   'bootstrap' → no PROJECT.md AND sparse store: from-scratch entry-point
+     *     (extract route or bootstrap loop per the shared empty-memory rule);
+     *   'refresh'   → PROJECT.md missing on a RICH store, or fossil relative
+     *     to recent commit/store activity: regenerate via
+     *     bclaw_bootstrap(refresh: true), never from-scratch;
+     *   'none'      → PROJECT.md present and current.
+     * `bootstrap_recommended` stays the boolean projection (verdict !== 'none')
+     * for backward compatibility.
+     */
+    bootstrap_verdict: z.enum(['bootstrap', 'refresh', 'none']).optional(),
     /**
      * pln#513 step 1 — literal MCP call to surface as the bootstrap entry-point
      * when `bootstrap_recommended` is true. Carries the canonical-grammar text
@@ -158,5 +190,11 @@ export const FacadeResponseSchema = z.object({
      * CLI doesn't have to reconstruct it.
      */
     next_action: z.string().optional(),
+    /**
+     * agent-ux (pln#542): recommended follow-up calls with exact shapes —
+     * the generalized affordance channel. `next_action` (singular, string)
+     * remains for the bootstrap hint; new consumers should read this array.
+     */
+    next_actions: z.array(NextActionSchema).optional(),
 });
 //# sourceMappingURL=facade-schema.js.map

package/dist/core/gc-semantic.js

@@ -91,12 +91,10 @@ export function compact(options = {}) {
     const purgeSessionNotes = options.purgeSessionNotes ?? true;
     const dedupHandoffs = options.dedupHandoffs ?? true;
     const cutoff = new Date(Date.now() - minAgeDays * 24 * 60 * 60 * 1000).toISOString();
-    // Extensions (pln#436): file-direct sweeps, independent of mutateState
-    // since claims and runtime_notes live in their own stores.
-    const claimsArchived = purgeReleasedClaims ? archiveReleasedClaims(cwd, minAgeDays, dryRun) : 0;
-    const sessionNotesArchived = purgeSessionNotes ? archiveSessionNotes(cwd, minAgeDays, dryRun) : 0;
-    const handoffsDeduped = dedupHandoffs ? dedupAutoHandoffs(cwd, dryRun) : 0;
     if (dryRun) {
+        const claimsArchived = purgeReleasedClaims ? archiveReleasedClaims(cwd, minAgeDays, true) : 0;
+        const sessionNotesArchived = purgeSessionNotes ? archiveSessionNotes(cwd, minAgeDays, true) : 0;
+        const handoffsDeduped = dedupHandoffs ? dedupAutoHandoffs(cwd, true) : 0;
         const state = loadState(cwd);
         const eligible = collectEligible(state, cutoff);
         const selected = eligible.slice(0, maxItems);
@@ -112,6 +110,11 @@ export function compact(options = {}) {
         };
     }
     return mutateState((state) => {
+        // Direct file-store GC participates in the same store-wide mutation lock as
+        // state compaction so a stale snapshot cannot race against these deletes.
+        const claimsArchived = purgeReleasedClaims ? archiveReleasedClaims(cwd, minAgeDays, false) : 0;
+        const sessionNotesArchived = purgeSessionNotes ? archiveSessionNotes(cwd, minAgeDays, false) : 0;
+        const handoffsDeduped = dedupHandoffs ? dedupAutoHandoffs(cwd, false) : 0;
         const eligible = collectEligible(state, cutoff);
         const selected = eligible.slice(0, maxItems);
         if (selected.length === 0) {
@@ -418,6 +421,128 @@ function archiveSessionNotes(cwd, minAgeDays, dryRun) {
     }
     return eligible.length;
 }
+/**
+ * pln#564 step B — autonomous runtime-note retention.
+ *
+ * The runtime-note tree (`coordination/runtime/<agent>/*.json`) is fully
+ * scanned by buildContext on every read (trp_439fec51). It accumulates
+ * unbounded because the only existing GC (archiveSessionNotes) runs solely
+ * inside the LLM-driven compaction phase, which is rarely triggered — so
+ * 1000s of write-only lifecycle notes bury the real signal and drive a ~11s
+ * read. This pass runs cheaply on session-start (full maintenance) with NO
+ * LLM gate, capping the redundant classes while preserving genuine captures.
+ *
+ * Classification (priority order):
+ *  - `fakehome`     — scope points at a Temp/bclaw-fakehome worktree: test
+ *                     leakage referencing dead paths. Archived unconditionally.
+ *  - `lifecycle`    — carries an `event_type` (run_, assignment_, lane_ …):
+ *                     dispatch telemetry already in the event journal.
+ *  - `session`      — note_type session_start/session_end or tagged `session`:
+ *                     session markers already in the audit log + journal.
+ *  - `observation`  — genuine human/agent capture. NEVER archived.
+ *
+ * `session` and `lifecycle` are capped to the newest `keepPerAgent` per agent;
+ * the rest are parked (backed up to gc-backups, then unlinked).
+ */
+const RUNTIME_FAKEHOME_RE = /bclaw-fakehome|[\\/]Temp[\\/]/i;
+const DEFAULT_RUNTIME_NOTE_KEEP_PER_AGENT = 20;
+function classifyRuntimeNote(parsed) {
+    const scope = typeof parsed.scope === 'string' ? parsed.scope : '';
+    if (scope && RUNTIME_FAKEHOME_RE.test(scope))
+        return 'fakehome';
+    if (typeof parsed.event_type === 'string' && parsed.event_type.length > 0)
+        return 'lifecycle';
+    const noteType = parsed.note_type;
+    const tags = Array.isArray(parsed.tags) ? parsed.tags : [];
+    if (noteType === 'session_start' || noteType === 'session_end' || tags.includes('session')) {
+        return 'session';
+    }
+    return 'observation';
+}
+/**
+ * Enforce runtime-note retention across all agent dirs. Best-effort and
+ * idempotent: archiving older/excess notes is safe against a concurrent
+ * reader (it just sees fewer notes) and every removed file is parked under
+ * `.brainclaw/gc-backups/` first, so nothing is lost.
+ */
+export function enforceRuntimeNoteRetention(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const keepPerAgent = options.keepPerAgent ?? DEFAULT_RUNTIME_NOTE_KEEP_PER_AGENT;
+    const dryRun = options.dryRun ?? false;
+    const by_class = { observation: 0, session: 0, lifecycle: 0, fakehome: 0 };
+    const result = { scanned: 0, archived: 0, kept: 0, by_class };
+    const runtimeDir = path.join(cwd, '.brainclaw', 'coordination', 'runtime');
+    if (!fs.existsSync(runtimeDir))
+        return result;
+    const toArchive = [];
+    for (const agent of fs.readdirSync(runtimeDir)) {
+        const agentDir = path.join(runtimeDir, agent);
+        let isDir = false;
+        try {
+            isDir = fs.statSync(agentDir).isDirectory();
+        }
+        catch { /* skip */ }
+        if (!isDir)
+            continue;
+        // Capped classes are grouped per agent so we keep the newest N each.
+        const capped = {
+            session: [],
+            lifecycle: [],
+        };
+        for (const file of fs.readdirSync(agentDir)) {
+            if (!file.endsWith('.json'))
+                continue;
+            const filePath = path.join(agentDir, file);
+            let content;
+            let parsed;
+            try {
+                content = fs.readFileSync(filePath, 'utf-8');
+                parsed = JSON.parse(content);
+            }
+            catch {
+                continue; // unparseable — leave it alone
+            }
+            result.scanned += 1;
+            const cls = classifyRuntimeNote(parsed);
+            by_class[cls] += 1;
+            if (cls === 'observation') {
+                result.kept += 1;
+                continue;
+            }
+            if (cls === 'fakehome') {
+                toArchive.push({ filePath, content });
+                continue;
+            }
+            const createdAt = typeof parsed.created_at === 'string' ? parsed.created_at : '';
+            capped[cls].push({ filePath, content, createdAt });
+        }
+        for (const cls of ['session', 'lifecycle']) {
+            const entries = capped[cls];
+            entries.sort((a, b) => b.createdAt.localeCompare(a.createdAt)); // newest first
+            result.kept += Math.min(entries.length, keepPerAgent);
+            for (const extra of entries.slice(keepPerAgent)) {
+                toArchive.push({ filePath: extra.filePath, content: extra.content });
+            }
+        }
+    }
+    if (dryRun || toArchive.length === 0) {
+        result.archived = toArchive.length;
+        return result;
+    }
+    const timestamp = nowISO().replace(/[:.]/g, '-');
+    const backupPath = path.join(cwd, '.brainclaw', 'gc-backups', `runtime-note-retention-${timestamp}.jsonl`);
+    fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+    for (const { filePath, content } of toArchive) {
+        try {
+            fs.appendFileSync(backupPath, content.trim() + '\n', 'utf-8');
+            fs.unlinkSync(filePath);
+            result.archived += 1;
+        }
+        catch { /* best-effort: a failed unlink just leaves the note in place */ }
+    }
+    result.backup_path = backupPath;
+    return result;
+}
 /**
  * Deduplicate auto-generated session-end handoffs. These carry the same
  * commits list when several sessions close on the same project state, so the

package/dist/core/handoff-snapshot.js

@@ -0,0 +1,68 @@
+/**
+ * Auto-handoff diff snapshot capping (pln#569, décision E).
+ *
+ * Session-end auto-handoffs carried the FULL uncommitted git diff in
+ * `snapshot.diff` (~450 KB each), which made handoffs 53 MB of a 55 MB journal
+ * (524 handoffs, trp_2ca4b87b) — yet:
+ *   - no consumer ever reads more than a bounded prefix (the dispatch review
+ *     brief slices 5 000 chars; `bclaw_find`/`bclaw_get` bound to
+ *     DEFAULT_FIND_CHAR_BUDGET = 40 000), and
+ *   - the canonical full diff lives on the worktree branch — the read path
+ *     already tells the reader to "read the worktree branch for the full diff".
+ *
+ * So the inline diff is a CONVENIENCE PREVIEW, not the source of truth. This
+ * caps it to a generous preview and records a digest of the full diff when
+ * truncated, so nothing is silently lost (a reader knows the inline diff is a
+ * prefix and by how much) without paying the ~450 KB per handoff.
+ *
+ * @module
+ */
+import crypto from 'node:crypto';
+/**
+ * Max chars of the inline diff preview kept on a handoff. Chosen ABOVE every
+ * consumer's read budget except the rare large-budget `find`/`get` (40 000) —
+ * the review brief (5 000) is served in full, and the worktree branch carries
+ * the canonical diff for anything larger. ~30× smaller than a typical 450 KB
+ * uncommitted diff.
+ */
+export const HANDOFF_DIFF_PREVIEW_CHARS = 16_384;
+function safePreviewEnd(fullDiff) {
+    const end = HANDOFF_DIFF_PREVIEW_CHARS;
+    const last = fullDiff.charCodeAt(end - 1);
+    const next = fullDiff.charCodeAt(end);
+    return last >= 0xd800 && last <= 0xdbff && next >= 0xdc00 && next <= 0xdfff ? end - 1 : end;
+}
+/**
+ * Build a handoff `snapshot` from a full diff: keep an inline preview, and when
+ * the diff exceeds the preview cap, record a digest of the FULL diff
+ * (`full_bytes` + `sha256` + `truncated`) so the truncation is explicit and a
+ * re-fetched full diff is verifiable. Returns `undefined` for an absent/empty
+ * diff (no snapshot at all).
+ */
+export function capHandoffDiff(fullDiff) {
+    if (!fullDiff)
+        return undefined;
+    if (fullDiff.length <= HANDOFF_DIFF_PREVIEW_CHARS) {
+        return { diff: fullDiff };
+    }
+    // Buffer round-trip forces a FLAT independent copy: a bare `slice()` returns a
+    // V8 SlicedString that pins the whole ~450 KB parent in memory, defeating the
+    // cap (the parent never gets freed) — the same trap trimForProjection hit
+    // (trp_2ca4b87b).
+    const preview = Buffer.from(fullDiff.slice(0, safePreviewEnd(fullDiff)), 'utf8').toString('utf8');
+    return {
+        diff: preview,
+        diff_digest: {
+            full_bytes: Buffer.byteLength(fullDiff, 'utf8'),
+            sha256: crypto.createHash('sha256').update(fullDiff, 'utf8').digest('hex'),
+            truncated: true,
+        },
+    };
+}
+export function handoffDiffPreviewNote(snapshot) {
+    const digest = snapshot?.diff_digest;
+    if (!digest?.truncated)
+        return undefined;
+    return `… [preview — full diff is ${digest.full_bytes} bytes on the worktree branch]`;
+}
+//# sourceMappingURL=handoff-snapshot.js.map

package/dist/core/ids.js

@@ -2,6 +2,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { withLock } from './lock.js';
+import { writeFileAtomic } from './io.js';
 const PREFIXES = {
     active_constraints: 'cst',
     bootstrap_seeds: 'bsd',
@@ -18,10 +19,15 @@ const PREFIXES = {
     runs: 'run',
     actions: 'act',
     runtime_events: 'evt',
+    // can_b8d53d18: without an explicit entry, 'runtime_note' fell through to the
+    // slice(0,3) fallback = 'run', colliding with agent_run ids and breaking
+    // prefix-based routing (dispatch_status). Canonical prefix is 'rtn'.
+    runtime_note: 'rtn',
+    runtime_notes: 'rtn',
 };
 const ID_COUNTER_FILE = '.id-counter.json';
-function counterPath(cwd) {
-    return path.join(cwd ?? process.cwd(), '.brainclaw', ID_COUNTER_FILE);
+function counterPath(cwd, preferredDirName = '.brainclaw') {
+    return path.join(cwd ?? process.cwd(), preferredDirName, ID_COUNTER_FILE);
 }
 /** Generate a concurrence-safe prefixed ID using 4 random bytes. */
 export function generateId(section) {
@@ -33,17 +39,22 @@ export function generateId(section) {
  * Atomically increment the per-prefix counter and return the next short label.
  * Best-effort: if the counter file is unavailable the call still succeeds.
  */
-export function getNextShortLabel(prefix, cwd) {
-    const fp = counterPath(cwd);
+export function getNextShortLabel(prefix, cwd, preferredDirName) {
+    const fp = counterPath(cwd, preferredDirName);
     return withLock(fp, () => {
         let counter = {};
         try {
             counter = JSON.parse(fs.readFileSync(fp, 'utf-8'));
         }
-        catch { /* first use or missing file */ }
+        catch (error) {
+            if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') {
+                throw new Error(`Could not read short-label counter ${fp}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
         const next = (counter[prefix] ?? 0) + 1;
         counter[prefix] = next;
-        fs.writeFileSync(fp, JSON.stringify(counter), 'utf-8');
+        fs.mkdirSync(path.dirname(fp), { recursive: true });
+        writeFileAtomic(fp, `${JSON.stringify(counter, null, 2)}\n`);
         return `${prefix}#${next}`;
     });
 }
@@ -51,10 +62,10 @@ export function getNextShortLabel(prefix, cwd) {
  * Generate both a concurrence-safe hash ID and a human-readable short label.
  * The hash ID is the canonical storage key; the short label is for display and aliased lookups.
  */
-export function generateIdWithLabel(section, cwd) {
+export function generateIdWithLabel(section, cwd, preferredDirName) {
     const id = generateId(section);
     const prefix = PREFIXES[section] ?? section.slice(0, 3);
-    const short_label = getNextShortLabel(prefix, cwd);
+    const short_label = getNextShortLabel(prefix, cwd, preferredDirName);
     return { id, short_label };
 }
 export function nowISO() {