brainclaw 1.8.0 → 1.9.0

package/dist/core/dispatcher.js

@@ -43,8 +43,8 @@ import { memoryDir } from './io.js';
 import { loadVersionedJsonFile } from './migration.js';
 import fs from 'node:fs';
 import path from 'node:path';
-import { buildInvokeCommand, resolveBriefMode, getCapabilityProfile, dispatchHasMcp, resolveConcurrencyLimit, resolveResourceKey, resolveModel, serializeConcurrencyLimit } from './agent-capability.js';
-import { getRuntimeSignalPath } from './runtime-signals.js';
+import { buildInvokeCommand, resolveBriefMode, getCapabilityProfile, dispatchHasMcp, dispatchCanCommit, isSandboxedSpawn, resolveConcurrencyLimit, resolveResourceKey, resolveModel, serializeConcurrencyLimit } from './agent-capability.js';
+import { getRuntimeSignalPath, getWorktreeHeartbeatPath } from './runtime-signals.js';
 import { attemptExecution } from './execution.js';
 import { createAssignment, transitionAssignment, generateAssignmentId, patchAssignmentMessageId } from './assignments.js';
 import { createAgentRun, transitionAgentRun } from './agentruns.js';
@@ -211,12 +211,28 @@ export function analyzeSequence(cwd) {
  * heartbeat. This is the worker-side half of the liveness contract whose
  * engine-side floor is the wrapper + reconciler (steps 4 + 1).
  */
-export function buildLivenessSection(cwd, assignmentId) {
-    const hbPath = getRuntimeSignalPath(cwd, assignmentId, 'heartbeat');
+export function buildLivenessSection(cwd, assignmentId, worktreePath, opts) {
+    // sprint 1.5 (dogfooding): the project-root signal path is NOT writable from
+    // inside worker sandboxes (Claude Code restricts writes to its working dirs;
+    // codex workspace-write roots exclude the project root) — the brief was
+    // demanding a heartbeat the worker could not write. When the worker has a
+    // worktree, point step 0 at a worktree-local heartbeat instead; every reader
+    // (reconciler, sweeper, dispatch_status fs-activity) checks both locations.
+    //
+    // pln#554 step 4 — sandbox-aware: codex workspace-write refuses even absolute
+    // paths in some configurations (cnd_asgn_7336aa79_heartbeat_sandbox /
+    // can_asgn_b0169fd8_heartbeat). When the execution adapter KNOWS the worker is
+    // sandboxed, point the write command at a worktree-RELATIVE path (the sandbox
+    // cwd is the worktree root) — same file, sandbox-proof spelling.
+    const sandboxRelative = opts?.sandboxed === true && !!worktreePath;
+    const hbPath = worktreePath
+        ? getWorktreeHeartbeatPath(worktreePath, assignmentId)
+        : getRuntimeSignalPath(cwd, assignmentId, 'heartbeat');
+    const targetPath = sandboxRelative ? `.brainclaw-heartbeat-${assignmentId}` : hbPath;
     const isWin = process.platform === 'win32';
     const writeCmd = isWin
-        ? `echo work_loop_reached ${assignmentId} > "${hbPath}"`
-        : `printf 'work_loop_reached ${assignmentId} %s' "$(date +%s)" > "${hbPath}"`;
+        ? `echo work_loop_reached ${assignmentId} > "${targetPath}"`
+        : `printf 'work_loop_reached ${assignmentId} %s' "$(date +%s)" > "${targetPath}"`;
     return [
         '## Liveness — DO THIS FIRST (step 0)',
         'Before ANY other action, prove you reached your work loop by writing a heartbeat,',
@@ -228,7 +244,28 @@ export function buildLivenessSection(cwd, assignmentId) {
         '```sh',
         writeCmd,
         '```',
-        `Heartbeat file (absolute, writable): ${hbPath}`,
+        sandboxRelative
+            ? `Heartbeat file (worktree-RELATIVE — run it from the worktree root, your sandbox cwd; sandboxes refuse the absolute coordination path): ${targetPath}`
+            : `Heartbeat file (absolute, writable from your sandbox): ${hbPath}`,
+        ...(worktreePath ? ['If that write is denied, use any file edit in your worktree as your liveness signal and continue — do NOT stall on the heartbeat.'] : []),
+        '',
+    ].join('\n');
+}
+/**
+ * pln#554 step 4 — working defaults baked into every generated brief, distilled
+ * from the 2026-06-10 session: (a) incremental commits so a worker death costs
+ * one step max (the orphaned recoveries that night lost zero work ONLY because
+ * the diff was still on disk); (b) a split validation bar so parallel workers
+ * don't pile full test suites onto a memory-pressured machine.
+ */
+export function buildWorkingDefaultsSection(opts) {
+    const commitRule = opts.canCommit
+        ? '- **Incremental commits**: commit after EACH completed step (conventional message). Never hold more than one step uncommitted — a worker death then costs at most one step, and the coordinator can harvest everything already on the branch.'
+        : '- **Incremental delivery**: your sandbox cannot `git commit` — finish steps in order and keep every file saved as you complete each step; the coordinator commits the worktree on your behalf at harvest. Never leave a step half-edited.';
+    return [
+        '## Working defaults',
+        commitRule,
+        '- **Validation bar**: run `tsc --noEmit` (or the project typecheck) + the targeted unit tests for the files you touched ONLY. Do NOT run the full default test suite — the coordinator runs the full gate after harvest (prevents test-suite pileups when several workers run in parallel).',
         '',
     ].join('\n');
 }
@@ -364,12 +401,18 @@ export function generateBrief(plan, item, cwd, briefMode, options) {
     if (plan.estimated_effort)
         parts.push(`Estimated effort: ${plan.estimated_effort} minutes`);
     parts.push('');
+    // Capability profile drives the sandbox-aware liveness path + the working
+    // defaults' commit rule (pln#554 step 4) and the transport addendum below.
+    const briefProfile = options?.agent ? getCapabilityProfile(options.agent) : undefined;
+    const briefSandboxed = briefProfile ? isSandboxedSpawn(briefProfile) : false;
     // pln#520 step 5 — liveness heartbeat instruction, first actionable block so
     // the worker writes work_loop_reached before anything else. Only when an
     // assignment id is known (the heartbeat is keyed by it).
     if (options?.assignmentId) {
-        parts.push(buildLivenessSection(cwd, options.assignmentId));
+        parts.push(buildLivenessSection(cwd, options.assignmentId, options.worktreePath, { sandboxed: briefSandboxed }));
     }
+    // pln#554 step 4 — working defaults (incremental commits + validation bar).
+    parts.push(buildWorkingDefaultsSection({ canCommit: briefProfile ? dispatchCanCommit(briefProfile) : true }));
     // Steps if any
     if (plan.steps?.length) {
         parts.push('## Steps');
@@ -435,7 +478,6 @@ export function generateBrief(plan, item, cwd, briefMode, options) {
     // so the reconciler-independent path is preserved; this addendum disambiguates
     // the transport rather than stripping the section — the full compact reversal
     // is a separate human-owned call on the May-vs-June MCP-availability conflict.)
-    const briefProfile = options?.agent ? getCapabilityProfile(options.agent) : undefined;
     if (briefProfile && !dispatchHasMcp(briefProfile)) {
         parts.push('## ⚠ Transport: sandboxed run (no MCP, no commit)');
         parts.push('Your runtime is sandboxed — the brainclaw MCP server is NOT reachable and `git commit` is unavailable (.git is outside the sandbox root). Any `bclaw_*` MCP instruction above does NOT apply to you. Report your outcome via the FILE protocol only — it is authoritative for this run:');
@@ -468,6 +510,15 @@ export function generateDispatchBrief(options) {
     if (options.worktreePath)
         parts.push(`Worktree: ${options.worktreePath}`);
     parts.push('');
+    const taskBriefProfile = options.agent ? getCapabilityProfile(options.agent) : undefined;
+    const taskSandboxed = taskBriefProfile ? isSandboxedSpawn(taskBriefProfile) : false;
+    // sprint 1.5 — task-based briefs get the same step-0 liveness contract as
+    // plan-based briefs (worktree-local heartbeat, writable from any sandbox).
+    if (options.assignmentId && options.worktreePath) {
+        parts.push(buildLivenessSection(options.worktreePath, options.assignmentId, options.worktreePath, { sandboxed: taskSandboxed }));
+    }
+    // pln#554 step 4 — working defaults (incremental commits + validation bar).
+    parts.push(buildWorkingDefaultsSection({ canCommit: taskBriefProfile ? dispatchCanCommit(taskBriefProfile) : true }));
     if (briefMode === 'full') {
         parts.push(buildProtocolSection({
             claimId: options.claimId,
@@ -476,7 +527,6 @@ export function generateDispatchBrief(options) {
         }));
     }
     // pln#528 — transport-aware addendum for sandboxed agents (see generateBrief).
-    const taskBriefProfile = options.agent ? getCapabilityProfile(options.agent) : undefined;
     if (taskBriefProfile && !dispatchHasMcp(taskBriefProfile)) {
         parts.push('## ⚠ Transport: sandboxed run (no MCP, no commit)');
         parts.push('Your runtime is sandboxed — the brainclaw MCP server is NOT reachable and `git commit` is unavailable (.git is outside the sandbox root). Any `bclaw_*` MCP instruction above does NOT apply to you. Report your outcome via the FILE protocol only — it is authoritative for this run:');
@@ -679,7 +729,7 @@ export async function dispatch(options, cwd) {
             const invokeCmd = buildInvokeCommand(targetAgent, brief, { model: resolveModel(targetAgent, { override: options.model }) });
             if (invokeCmd) {
                 const cmdPrefix = buildEnvPrefix(claimId);
-                result.commands.push({ agent: targetAgent, lane: readyItem.lane, command: `${cmdPrefix}${invokeCmd.bashCommand}`, shell: process.platform === 'win32' ? 'cmd' : (invokeCmd.shell ? 'bash' : 'sh') });
+                result.commands.push({ agent: targetAgent, lane: readyItem.lane, plan_id: readyItem.plan.id, command: `${cmdPrefix}${invokeCmd.bashCommand}`, shell: process.platform === 'win32' ? 'cmd' : (invokeCmd.shell ? 'bash' : 'sh') });
             }
             const deliveryEntry = { agent: targetAgent, plan_id: readyItem.plan.id, message_id: '(dry-run)', lane: readyItem.lane, channel: 'inbox', claim_id: claimId };
             result.delivery_plan.push(deliveryEntry);
@@ -738,6 +788,7 @@ export async function dispatch(options, cwd) {
             result.commands.push({
                 agent: targetAgent,
                 lane: readyItem.lane,
+                plan_id: readyItem.plan.id,
                 command: `${cmdPrefix}${invokeCmd.bashCommand}`,
                 shell: process.platform === 'win32' ? 'cmd' : (invokeCmd.shell ? 'bash' : 'sh'),
             });
@@ -881,6 +932,7 @@ export async function dispatch(options, cwd) {
                             status_reason: 'CLI spawn launched by dispatcher',
                             tags: ['dispatch-run', ...(entry.lane ? [`lane:${entry.lane}`] : [])],
                         }, cwd);
+                        entry.run_id = run.id;
                         transitionAgentRun(run.id, 'failed', {
                             actor: options.dispatcherAgent,
                             actor_id: options.dispatcherAgentId,
@@ -928,6 +980,7 @@ export async function dispatch(options, cwd) {
                         status_reason: execResult.error,
                         tags: ['dispatch-run', ...(entry.lane ? [`lane:${entry.lane}`] : [])],
                     }, cwd);
+                    entry.run_id = run.id;
                     if (execResult.execution_status === 'delivered_and_started') {
                         transitionAgentRun(run.id, 'launching', {
                             actor: options.dispatcherAgent,

package/dist/core/entity-operations.js

@@ -12,14 +12,15 @@
  * until later slices wire them in.
  */
 import path from 'node:path';
-import { loadState, persistState } from './state.js';
+import { loadState, mutateState } from './state.js';
 import { archiveCandidate, listCandidates, loadCandidate, saveCandidate, } from './candidates.js';
 import { addCrossProjectLink, removeCrossProjectLink, resolveCrossProjectLinks, } from './cross-project.js';
-import { listClaims } from './claims.js';
+import { listClaims, loadClaim, saveClaim } from './claims.js';
 import { listActionRequired } from './actions.js';
 import { deleteAssignment, listAssignments, loadAssignment, saveAssignment, transitionAssignment } from './assignments.js';
 import { listAgentRuns } from './agentruns.js';
 import { reconcileAgentRun, reconcileDeadPidRunningAgentRunAtRead, TERMINAL_STATUSES } from './agentrun-reconciler.js';
+import { isObserverMode } from './observer-mode.js';
 import { deleteRuntimeNote, listRuntimeNotes, saveRuntimeNote, } from './runtime.js';
 import { createSequence, deleteSequence, listSequences, updateSequence, } from './sequence.js';
 import { createConstraint, createDecision, createTrap, } from './operations/memory-write.js';
@@ -102,6 +103,12 @@ export class InvalidTransitionError extends Error {
  */
 function loadAgentRunsWithReconciliation(cwd) {
     const runs = listAgentRuns(cwd);
+    // Observer mode (BRAINCLAW_OBSERVER=1) suppresses the lazy reconciliation
+    // pass. A dashboard reading agent_run records must never transition them —
+    // that loop drove the 2026-06-10 lock storm (every poll could mutate every
+    // non-terminal run, holding the mutation lock under each transition).
+    if (isObserverMode())
+        return runs;
     for (const run of runs) {
         if (run.status === 'running') {
             try {
@@ -441,6 +448,20 @@ export function updateEntity(name, id, patch, cwd) {
             saveAssignment(patched, cwd);
             return { entity: name, id };
         }
+        case 'claim': {
+            // sprint 1.5 — description + worktree_path (manual-worktree registration).
+            // Status changes still go through bclaw_transition / release flows.
+            let claim;
+            try {
+                claim = loadClaim(id, cwd);
+            }
+            catch {
+                throw new EntityNotFoundError(name, id);
+            }
+            const patched = { ...claim, ...patch };
+            saveClaim(patched, cwd);
+            return { entity: name, id };
+        }
         case 'candidate': {
             // Note: `candidate.type` is intentionally create-only (not in
             // candidate.updatable at entity-registry.ts) — no validation needed.
@@ -561,8 +582,9 @@ export function transitionEntity(name, id, to, cwd, _reason) {
     if (!spec.statusField) {
         throw new Error(`${name} has no lifecycle (statusField is undefined)`);
     }
+    const statusField = spec.statusField;
     const current = getEntity(name, id, cwd);
-    const from = current[spec.statusField];
+    const from = current[statusField];
     if (!from) {
         throw new Error(`${name} '${id}' has no '${spec.statusField}' field set`);
     }
@@ -579,15 +601,15 @@ export function transitionEntity(name, id, to, cwd, _reason) {
         case 'decision':
         case 'constraint':
         case 'trap': {
-            const state = loadState(cwd);
-            const bucket = name === 'decision' ? state.recent_decisions
-                : name === 'constraint' ? state.active_constraints
-                    : state.known_traps;
-            const item = bucket.find((x) => x.id === id);
-            if (!item)
-                throw new EntityNotFoundError(name, id);
-            item[spec.statusField] = to;
-            persistState(state, cwd);
+            mutateState((state) => {
+                const bucket = name === 'decision' ? state.recent_decisions
+                    : name === 'constraint' ? state.active_constraints
+                        : state.known_traps;
+                const item = bucket.find((x) => x.id === id);
+                if (!item)
+                    throw new EntityNotFoundError(name, id);
+                item[statusField] = to;
+            }, cwd);
             return { entity: name, id, from, to, side_effects: sideEffects };
         }
         case 'candidate': {
@@ -618,20 +640,19 @@ export function transitionEntity(name, id, to, cwd, _reason) {
 // ─── Helpers ──────────────────────────────────────────────────────────
 /**
  * Stamp provenance on a state-resident record (plan, decision, constraint, trap)
- * immediately after create. Writes one extra persistState call; acceptable for
- * v1 since create is infrequent compared to reads.
+ * immediately after create.
  */
 function stampProvenanceOnStateItem(name, id, provenance, cwd) {
-    const state = loadState(cwd);
-    const bucket = name === 'plan' ? state.plan_items
-        : name === 'decision' ? state.recent_decisions
-            : name === 'constraint' ? state.active_constraints
-                : state.known_traps;
-    const item = bucket.find((x) => x.id === id);
-    if (!item)
-        return;
-    item.provenance = provenance;
-    persistState(state, cwd);
+    mutateState((state) => {
+        const bucket = name === 'plan' ? state.plan_items
+            : name === 'decision' ? state.recent_decisions
+                : name === 'constraint' ? state.active_constraints
+                    : state.known_traps;
+        const item = bucket.find((x) => x.id === id);
+        if (!item)
+            return;
+        item.provenance = provenance;
+    }, cwd);
 }
 function requireString(data, field) {
     const value = data[field];

package/dist/core/entity-registry.js

@@ -44,7 +44,7 @@ const step = {
     name: 'step',
     shortLabelPrefix: 'stp',
     schema: PlanStepSchema,
-    updatable: ['text', 'assignee'],
+    updatable: ['text', 'assignee', 'estimated_effort', 'actual_effort'],
     statusField: 'status',
     transitions: {
         todo: ['in_progress', 'blocked', 'done'],
@@ -63,7 +63,9 @@ const claim = {
     name: 'claim',
     shortLabelPrefix: 'clm',
     schema: ClaimSchema,
-    updatable: ['description'],
+    // worktree_path: sprint 1.5 — coordinators register manual worktrees (or fix
+    // stale paths) so harvest/dispatch_status can resolve LANE-RESULT locations.
+    updatable: ['description', 'worktree_path'],
     statusField: 'status',
     transitions: {
         active: ['released', 'stale'],
@@ -107,7 +109,16 @@ const decision = {
     name: 'decision',
     shortLabelPrefix: 'dec',
     schema: DecisionSchema,
-    updatable: ['text', 'tags', 'outcome', 'scope', 'related_paths', 'verified_at', 'verify_cmd'],
+    updatable: [
+        'text', 'tags', 'outcome', 'scope', 'related_paths', 'verified_at', 'verify_cmd',
+        // pln#544 lifecycle (touched via memory-lifecycle.ts recordMemoryEvent;
+        // exposing them here keeps bclaw_update straight-through for tests and
+        // operator backfills).
+        'last_confirmed_at', 'last_infirmed_at',
+        'confirmation_count', 'infirmation_count',
+        'saved_me_count', 'misled_me_count',
+        'confirmations',
+    ],
     statusField: 'outcome',
     transitions: {
         pending: ['approved', 'rejected', 'deferred'],
@@ -121,7 +132,14 @@ const constraint = {
     name: 'constraint',
     shortLabelPrefix: 'cst',
     schema: ConstraintSchema,
-    updatable: ['text', 'tags', 'category', 'scope', 'related_paths', 'expires_at'],
+    updatable: [
+        'text', 'tags', 'category', 'scope', 'related_paths', 'expires_at',
+        // pln#544 lifecycle — see decision.updatable.
+        'last_confirmed_at', 'last_infirmed_at',
+        'confirmation_count', 'infirmation_count',
+        'saved_me_count', 'misled_me_count',
+        'confirmations',
+    ],
     statusField: 'status',
     transitions: {
         active: ['resolved', 'expired'],
@@ -137,7 +155,15 @@ const trap = {
     name: 'trap',
     shortLabelPrefix: 'trp',
     schema: TrapSchema,
-    updatable: ['text', 'tags', 'severity', 'scope', 'related_paths', 'expires_at', 'platform_scope', 'verified_at', 'verify_cmd'],
+    updatable: [
+        'text', 'tags', 'severity', 'scope', 'related_paths', 'expires_at', 'platform_scope',
+        'verified_at', 'verify_cmd',
+        // pln#544 lifecycle — see decision.updatable.
+        'last_confirmed_at', 'last_infirmed_at',
+        'confirmation_count', 'infirmation_count',
+        'saved_me_count', 'misled_me_count',
+        'confirmations',
+    ],
     statusField: 'status',
     transitions: {
         active: ['resolved', 'expired'],

package/dist/core/event-log.js

@@ -3,15 +3,18 @@ import path from 'node:path';
 import { memoryDir } from './io.js';
 import { nowISO } from './ids.js';
 import { logger } from './logger.js';
+import { isObserverMode } from './observer-mode.js';
+import { appendJournalRecords, resolveJournalMode } from './events/journal.js';
+import { REGISTRY_POST_IMAGE_ITEM_TYPES } from './events/registry-post-image.js';
 const EVENT_LOG_FILE = 'events.jsonl';
 const CURSORS_DIR = '.cursors';
-// --- Writer ---
-export function appendEvent(event, cwd) {
+export function appendEvent(event, cwd, options = {}) {
     try {
         const full = {
             ts: event.ts ?? nowISO(),
             agent: event.agent ?? 'unknown',
             agent_id: event.agent_id,
+            session_id: event.session_id ?? (process.env.BRAINCLAW_SESSION_ID?.trim() || undefined),
             user: event.user ?? process.env.USER ?? process.env.USERNAME,
             action: event.action,
             item_type: event.item_type,
@@ -25,6 +28,56 @@ export function appendEvent(event, cwd) {
     catch (err) {
         logger.debug('Failed to write event log entry:', err);
     }
+    if (options.journalDualWrite !== false) {
+        dualWriteToJournal(event, cwd);
+    }
+}
+/**
+ * v2 journal dual-write (pln#543 step 2). Mirrors every v1 emission into
+ * the segmented journal when BRAINCLAW_JOURNAL_MODE=dual; a no-op when off.
+ * Mapping per spec §2.1.1: the coarse `update/upgrade/rollback : state`
+ * store event becomes a `journal_note` kind `store_marker` (the per-entity
+ * events it stands for arrive with step 3 dirty-tracking).
+ */
+function dualWriteToJournal(event, cwd) {
+    try {
+        if (resolveJournalMode(cwd) === 'off')
+            return;
+        const base = {
+            agent: event.agent,
+            agent_id: event.agent_id,
+            session_id: event.session_id,
+            user: event.user,
+            summary: event.summary,
+            ts: event.ts,
+        };
+        if (event.item_type === 'state') {
+            appendJournalRecords([{
+                    ...base,
+                    action: 'journal_note',
+                    item_type: 'journal',
+                    payload: { kind: 'store_marker', op: event.action, detail: event.summary },
+                }], cwd);
+            return;
+        }
+        // pln#568 — registry/coordination families now journal full entity-state
+        // post-images on their persist chokepoint (emitRegistryPostImage). Their
+        // legacy envelope-only dual-write here would be redundant noise (a
+        // registry-lifecycle record materialize ignores), so suppress it: in the v2
+        // journal these families appear ONLY as post-images. events.jsonl (above)
+        // still records the v1 lifecycle event for existing consumers.
+        if (REGISTRY_POST_IMAGE_ITEM_TYPES.has(event.item_type))
+            return;
+        appendJournalRecords([{
+                ...base,
+                action: event.action,
+                item_type: event.item_type,
+                item_id: event.item_id,
+            }], cwd);
+    }
+    catch (err) {
+        logger.debug('journal dual-write skipped:', err);
+    }
 }
 // --- Reader ---
 export function readAllEvents(cwd) {
@@ -43,39 +96,96 @@ export function readAllEvents(cwd) {
     }
     return events;
 }
+function normalizeReader(reader) {
+    return typeof reader === 'string' ? { agent: reader } : reader;
+}
 function cursorsDir(cwd) {
     return path.join(memoryDir(cwd), CURSORS_DIR);
 }
-function cursorPath(agent, cwd) {
-    return path.join(cursorsDir(cwd), `${agent}.json`);
+/** Cursor files are keyed by session_id when present, else by agent name. */
+function cursorKey(reader) {
+    return reader.session_id?.trim() || reader.agent;
 }
-function loadCursor(agent, cwd) {
-    const fp = cursorPath(agent, cwd);
-    if (!fs.existsSync(fp))
-        return { offset: 0, last_read: '' };
-    try {
-        return JSON.parse(fs.readFileSync(fp, 'utf-8'));
+function cursorPath(key, cwd) {
+    return path.join(cursorsDir(cwd), `${key}.json`);
+}
+function loadCursor(reader, cwd) {
+    const fp = cursorPath(cursorKey(reader), cwd);
+    if (fs.existsSync(fp)) {
+        try {
+            return JSON.parse(fs.readFileSync(fp, 'utf-8'));
+        }
+        catch {
+            return { offset: 0, last_read: '' };
+        }
     }
-    catch {
-        return { offset: 0, last_read: '' };
+    // name→instance migration: a session-keyed cursor that does not exist yet
+    // seeds from the legacy name-keyed cursor, so an upgraded instance does not
+    // replay the whole log. Cursors are caches — worst case is a re-read.
+    if (reader.session_id?.trim()) {
+        const legacy = cursorPath(reader.agent, cwd);
+        if (fs.existsSync(legacy)) {
+            try {
+                return JSON.parse(fs.readFileSync(legacy, 'utf-8'));
+            }
+            catch { /* fall through to fresh cursor */ }
+        }
     }
+    return { offset: 0, last_read: '' };
 }
-function saveCursor(agent, cursor, cwd) {
+function saveCursor(reader, cursor, cwd) {
     const dir = cursorsDir(cwd);
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
-    fs.writeFileSync(cursorPath(agent, cwd), JSON.stringify(cursor), 'utf-8');
+    fs.writeFileSync(cursorPath(cursorKey(reader), cwd), JSON.stringify(cursor), 'utf-8');
+}
+/**
+ * True when this reader already has a cursor — session-keyed, or the legacy
+ * name-keyed cursor a session reader would migrate from. Absence means first
+ * contact: the reader has never consumed this store's event log.
+ */
+export function hasEventCursor(reader, cwd) {
+    const effectiveReader = normalizeReader(reader);
+    if (fs.existsSync(cursorPath(cursorKey(effectiveReader), cwd)))
+        return true;
+    if (effectiveReader.session_id?.trim()) {
+        return fs.existsSync(cursorPath(effectiveReader.agent, cwd));
+    }
+    return false;
+}
+/**
+ * Seed the reader's cursor at the current end of the event log WITHOUT
+ * reading it. First-contact path: a fresh agent on a mature store must not
+ * replay the whole history (its one chance to triage would be consumed by
+ * noise) — the arrival digest informs instead, and the diff becomes
+ * incremental from here. Returns the byte offset that was sealed.
+ */
+export function seedCursorToEnd(reader, cwd) {
+    const effectiveReader = normalizeReader(reader);
+    const logPath = eventLogPath(cwd);
+    let size = 0;
+    try {
+        size = fs.statSync(logPath).size;
+    }
+    catch { /* missing log → offset 0 */ }
+    saveCursor(effectiveReader, { offset: size, last_read: nowISO() }, cwd);
+    return size;
 }
 /**
- * Read events unseen by this agent since their last read.
+ * Read events unseen by this reader since their last read.
  * Updates the cursor after reading.
+ *
+ * Self-exclusion is by SESSION when both sides carry one (pln#562 step 4):
+ * an instance skips only its own events, not those of a same-named sibling.
+ * Events or readers without session info fall back to name exclusion.
  */
-export function readUnseenEvents(agent, cwd) {
+export function readUnseenEvents(reader, cwd) {
+    const effectiveReader = normalizeReader(reader);
     const logPath = eventLogPath(cwd);
     if (!fs.existsSync(logPath))
         return [];
-    const cursor = loadCursor(agent, cwd);
+    const cursor = loadCursor(effectiveReader, cwd);
     const stat = fs.statSync(logPath);
     if (stat.size <= cursor.offset)
         return [];
@@ -90,8 +200,10 @@ export function readUnseenEvents(agent, cwd) {
     for (const line of lines) {
         try {
             const evt = JSON.parse(line);
-            // Exclude events from self
-            if (evt.agent !== agent) {
+            const isSelf = effectiveReader.session_id && evt.session_id
+                ? evt.session_id === effectiveReader.session_id
+                : evt.agent === effectiveReader.agent;
+            if (!isSelf) {
                 events.push(evt);
             }
         }
@@ -99,8 +211,13 @@ export function readUnseenEvents(agent, cwd) {
             // skip
         }
     }
-    // Update cursor
-    saveCursor(agent, { offset: stat.size, last_read: nowISO() }, cwd);
+    // Update cursor. Observer mode (BRAINCLAW_OBSERVER=1) skips this — the
+    // dashboard impersonating an agent must not consume that agent's cursor
+    // (the 2026-06-10 leak where the extension drained Juan's claude-code
+    // unseen-events queue on every poll).
+    if (!isObserverMode()) {
+        saveCursor(effectiveReader, { offset: stat.size, last_read: nowISO() }, cwd);
+    }
     return events;
 }
 /**