brainclaw 1.20.3 → 1.21.0

package/dist/commands/switch.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { loadActiveProject, saveActiveProject, clearActiveProject } from '../core/active-project.js';
 import { buildOperationalIdentity, loadCurrentSession, loadSessionById, resolveCurrentSessionId, saveCurrentSession } from '../core/identity.js';
 import { memoryExists } from '../core/io.js';
-import { resolveProjectRef } from '../core/store-resolution.js';
+import { resolveEffectiveCwdInfo, resolveProjectRef } from '../core/store-resolution.js';
 import { resolveCrossProjectLinks, resolveProjectCwd } from '../core/cross-project.js';
 import { scanNestedBrainclawProjects } from '../core/workspace-projects.js';
 import { loadConfig } from '../core/config.js';
@@ -103,10 +103,17 @@ export function listAvailableProjectsForSession(cwd, sessionId) {
     if (!wsRoot) {
         throw new Error('No brainclaw workspace found.');
     }
-    const sessionActive = (sessionId ? loadSessionById(sessionId, cwd) : loadCurrentSession(cwd))?.active_project;
-    const globalActive = loadActiveProject(wsRoot);
-    const active = sessionActive ?? globalActive;
-    const activeSource = sessionActive ? 'session' : globalActive ? 'global' : 'none';
+    // ONE RESOLVER, not a second ladder. This recomputed session-then-global locally, so it
+    // could report only two of the seven rungs: an agent physically inside a child project
+    // (cwd_child), or one anchored by BRAINCLAW_CWD / BRAINCLAW_PROJECT, was marked against
+    // the GLOBAL pointer or against nothing at all — while its writes went elsewhere. That
+    // divergence between the reader that DISPLAYS and the resolver that WRITES is what kept
+    // the pln#648 bug invisible for weeks: green status, data beside it.
+    const effective = resolveEffectiveCwdInfo({ baseCwd: cwd, sessionId });
+    const activeSource = effective.active_source;
+    const active = effective.resolved_project
+        ? { path: effective.resolved_project.path, name: effective.resolved_project.name }
+        : undefined;
     const projects = [];
     const seen = new Set();
     const addProject = (project) => {
@@ -262,13 +269,33 @@ export function runSwitch(projectRef, options = {}) {
         console.log(`✔ Switched to ${switchedName ? `"${switchedName}" (${rel})` : rel}${scopeHint}`);
     }
 }
+/**
+ * pln#649 step 5 — status derives from the SAME call that routes a write.
+ *
+ * This used to walk its own session-then-global ladder, so it could only ever name two of
+ * the resolver's seven rungs. An agent inside a child project read back the workspace's
+ * GLOBAL pointer — a different project from the one its writes reached. Reporting a source
+ * the writer does not use is the exact shape of the defect this plan exists to close, and
+ * it is why that defect stayed invisible: the status surface kept saying the reassuring
+ * thing.
+ *
+ * `active_source` is now the resolver's own vocabulary, matching what the MCP surfaces
+ * already echo. `cwd` — the resolver's "nothing pointed anywhere, use the directory" rung —
+ * keeps the previous no-active-project output, so the operator-facing text is unchanged for
+ * the case it described.
+ */
 function showCurrent(wsRoot, cwd, json) {
-    // F5: prefer the session's own active project so an agent sees its own
-    // session-scoped switch, not just the shared global pointer.
-    const sessionActive = loadCurrentSession(cwd)?.active_project;
-    const globalActive = loadActiveProject(wsRoot);
-    const active = sessionActive ?? globalActive;
-    const source = sessionActive ? 'session' : globalActive ? 'global' : 'none';
+    const effective = resolveEffectiveCwdInfo({ baseCwd: cwd });
+    const source = effective.active_source;
+    // The pointer records carry switched_at / switched_by; the resolver carries authority.
+    // Read the metadata from whichever pointer actually won, and never from the other one.
+    const pointer = source === 'session'
+        ? loadCurrentSession(cwd)?.active_project
+        : source === 'global' ? loadActiveProject(wsRoot) : undefined;
+    const active = pointer
+        ?? (source === 'cwd' || !effective.resolved_project
+            ? undefined
+            : { path: effective.resolved_project.path, name: effective.resolved_project.name, switched_at: undefined });
     if (!active) {
         if (json) {
             console.log(JSON.stringify({ active: false, scope: 'none' }));
@@ -314,7 +341,9 @@ function listProjects(wsRoot, cwd, json) {
         const name = p.name ? `${p.name} (${p.relative_path})` : p.relative_path;
         console.log(`${marker}${name}`);
     }
-    if (result.active_source === 'none') {
+    // `cwd` is the resolver's equivalent of the old locally-computed 'none': no pointer won,
+    // so commands operate on the current directory (pln#649 step 5).
+    if (result.active_source === 'cwd') {
         console.log('\nNo active project. Use `brainclaw switch <project>` to set one.');
     }
 }

package/dist/core/actions.js

@@ -28,8 +28,32 @@ function actionStore(cwd) {
         sort: (a, b) => a.created_at.localeCompare(b.created_at),
     });
 }
+/**
+ * Honours the declared `| undefined` instead of throwing, which it did.
+ *
+ * `JsonStore.load` THROWS on a missing id (json-store.ts), so this function could never
+ * return undefined and every `if (!action)` branch downstream was unreachable —
+ * including the `throw new Error('ActionRequired not found')` in `resolveActionRequired`
+ * just below. `assignments.ts` documents this exact JsonStore contract and wraps it; this
+ * module did not. (Fable audit.)
+ *
+ * WHAT I VERIFIED BEFORE FIXING, because the finding was reported as a security-shaped
+ * bug and is not one: the audit claimed the self-approval guard in mcp-write-claims.ts was
+ * "skipped by the throw". It is not. That guard reads `if (pendingAction && pendingAction
+ * .agent === caller)`, and the throw only happens when the action does NOT exist — in which
+ * case there is nothing to self-approve and `resolveActionRequired` refuses anyway. The
+ * dead code was the truthiness test, never the ownership test. So the real cost was a lying
+ * signature plus a worse error message for a missing id, which is what this fixes.
+ */
 export function loadActionRequired(id, cwd) {
-    return actionStore(cwd).load(id);
+    const store = actionStore(cwd);
+    // `exists` rather than a try/catch: a bare catch would also swallow an UNPARSEABLE
+    // record and report it as "not found", which is a different fact and the kind of
+    // silent downgrade this codebase already got burned by. Absence answers undefined;
+    // a corrupt record still throws, as it should.
+    if (!store.exists(id))
+        return undefined;
+    return store.load(id);
 }
 /** Default TTL for pending actions (1 hour). */
 const ACTION_DEFAULT_TTL_MS = 60 * 60 * 1000;

package/dist/core/agent-files.js

@@ -322,6 +322,25 @@ const UNIVERSAL_SKILL_RELATIVE_PATH = '.agents/skills/brainclaw/SKILL.md';
  * Directories exclusively managed by brainclaw — safe to gitignore as a whole.
  * Individual files in these directories don't need separate gitignore entries.
  */
+/**
+ * pln#647 — coordination artifacts brainclaw writes at a WORKTREE ROOT, which must
+ * never be tracked and must not show up as untracked debris in a user's project.
+ *
+ * brainclaw's own repo lists these by hand (added after trp#546: a committed
+ * LANE-RESULT.json is inherited by every new worktree from HEAD and poisons
+ * dispatch-status into a false "completed" verdict). Nothing propagated them to a
+ * target project, so every OTHER repo got the debris — and `.brainclaw-heartbeat-*`
+ * was ignored nowhere at all, including here, which is what blocked worktree removal
+ * on 2026-08-04 (see removeWorktree).
+ */
+export const BRAINCLAW_PROTOCOL_ARTIFACT_IGNORES = [
+    'LANE-RESULT.json',
+    'REVIEW-FINDINGS.md',
+    'REVIEW_FINDINGS.md',
+    'TRIAGE-REPORT.json',
+    '.brainclaw-heartbeat-*',
+    '.brainclaw-worktree.json',
+];
 export const BRAINCLAW_EXCLUSIVE_DIRECTORIES = [
     '.roo/',
     '.kilo/',

package/dist/core/agentruns.js

@@ -7,8 +7,10 @@
  * @module
  */
 import fs from 'node:fs';
+import path from 'node:path';
 import { AgentRunSchema } from './schema.js';
-import { resolveEntityDir } from './io.js';
+import { resolveOwnerProjectId } from './config.js';
+import { entityRecordDirs, resolveEntityDir } from './io.js';
 import { mutate } from './mutation-pipeline.js';
 import { nowISO, generateIdWithLabel } from './ids.js';
 import { JsonStore } from './json-store.js';
@@ -25,9 +27,9 @@ function ensureAgentRunsDir(cwd) {
         fs.mkdirSync(dir, { recursive: true });
     }
 }
-function agentRunStore(cwd) {
+function agentRunStoreForDir(dirPath) {
     return new JsonStore({
-        dirPath: agentRunsDir(cwd, 'read'),
+        dirPath,
         documentType: 'agent_run',
         getId: (run) => run.id,
         sort: (a, b) => {
@@ -38,6 +40,9 @@ function agentRunStore(cwd) {
         },
     });
 }
+// NOTE: no single-directory reader remains. The helper that resolved ONE dir via the
+// hasContent heuristic is what let a legacy run stay invisible to the list while the by-id
+// loader found it; removing it stops the next reader from reintroducing that asymmetry.
 export function saveAgentRun(run, cwd) {
     mutate({ cwd }, () => {
         ensureAgentRunsDir(cwd);
@@ -53,18 +58,67 @@ export function saveAgentRun(run, cwd) {
         emitRegistryPostImage('agent_run', parsed, { created, agent: parsed.agent, agent_id: parsed.agent_id, session_id: parsed.session_id, cwd });
         registryFaultPoint('after_registry_journal');
         store.save(parsed);
+        // Converge the other layout (mirrors saveClaim / saveAssignment): leaving a legacy copy
+        // holding the stale status is what let a deleted record be resurrected by its own zombie.
+        const writeDir = agentRunsDir(cwd, 'write');
+        for (const dirPath of entityRecordDirs('runs', cwd ?? process.cwd())) {
+            if (dirPath === writeDir)
+                continue;
+            const legacyPath = path.join(dirPath, `${parsed.id}.json`);
+            try {
+                if (fs.existsSync(legacyPath))
+                    fs.unlinkSync(legacyPath);
+            }
+            catch { /* best effort — the dual-layout list keeps it visible */ }
+        }
     });
 }
 export function loadAgentRun(id, cwd) {
-    try {
-        return agentRunStore(cwd).load(id);
-    }
-    catch {
-        return undefined;
+    // Record-specific across both layouts (pln#649, shared io.ts primitive). Resolving
+    // a single directory made a legacy run invisible as soon as the canonical one held
+    // any file — the same defect reproduced twice on assignments, found here by a Fable
+    // audit before it reached a field report.
+    for (const dirPath of entityRecordDirs('runs', cwd ?? process.cwd())) {
+        try {
+            return new JsonStore({
+                dirPath,
+                documentType: 'agent_run',
+                getId: (run) => run.id,
+                sort: (a, b) => {
+                    const byAssignment = a.assignment_id.localeCompare(b.assignment_id);
+                    if (byAssignment !== 0)
+                        return byAssignment;
+                    return a.created_at.localeCompare(b.created_at);
+                },
+            }).load(id);
+        }
+        catch { /* not in this layout — try the other */ }
     }
+    return undefined;
 }
+/**
+ * BOTH LAYOUTS, canonical winning on a duplicate id (mirrors listClaims / listAssignments).
+ *
+ * This list is the one `nextAttemptIndex` and `findLatestAgentRunForAssignment` read, so a
+ * run visible by id but missing from the list is what lets an attempt index restart at 1
+ * and a run's FSM freeze. Reachability is LOW — agent runs postdate the partitioned layout,
+ * so brainclaw has never written them flat (measured: legacy=0 in the field) — which is why
+ * this is internal consistency, not a field fix.
+ */
 export function listAgentRuns(cwd, filter) {
-    let runs = agentRunStore(cwd).list();
+    const byId = new Map();
+    for (const dirPath of entityRecordDirs('runs', cwd ?? process.cwd())) {
+        for (const run of agentRunStoreForDir(dirPath).list()) {
+            if (!byId.has(run.id))
+                byId.set(run.id, run);
+        }
+    }
+    let runs = Array.from(byId.values()).sort((a, b) => {
+        const byAssignment = a.assignment_id.localeCompare(b.assignment_id);
+        if (byAssignment !== 0)
+            return byAssignment;
+        return a.created_at.localeCompare(b.created_at);
+    });
     if (filter?.status)
         runs = runs.filter((run) => run.status === filter.status);
     if (filter?.agent)
@@ -123,7 +177,9 @@ export function createAgentRun(options, cwd) {
     const run = AgentRunSchema.parse({
         schema_version: 1,
         id: options.id ?? generated.id,
-        short_label: options.short_label ?? generated.short_label,
+        // Same landmine as createAssignment: `generated` is undefined when the caller
+        // supplied an id, so `generated!` threw on "this id, derive the rest".
+        short_label: options.short_label ?? generated?.short_label ?? (options.id ?? generated.id),
         assignment_id: options.assignment_id,
         claim_id: options.claim_id,
         message_id: options.message_id,
@@ -134,6 +190,8 @@ export function createAgentRun(options, cwd) {
         agent: options.agent,
         agent_id: options.agent_id,
         session_id: options.session_id,
+        // OWNER project — same core-level capture as createAssignment (pln#649 step 1).
+        project_id: resolveOwnerProjectId(cwd),
         transport: options.transport,
         status: options.status ?? 'created',
         status_reason: options.status_reason,

package/dist/core/assignments.js

@@ -11,8 +11,10 @@
  * @module
  */
 import fs from 'node:fs';
+import path from 'node:path';
 import { AssignmentSchema } from './schema.js';
-import { resolveEntityDir } from './io.js';
+import { resolveOwnerProjectId } from './config.js';
+import { entityRecordDirs, resolveEntityDir } from './io.js';
 import { mutate } from './mutation-pipeline.js';
 import { nowISO, generateIdWithLabel } from './ids.js';
 import { JsonStore } from './json-store.js';
@@ -31,14 +33,18 @@ function ensureAssignmentsDir(cwd) {
         fs.mkdirSync(dir, { recursive: true });
     }
 }
-function assignmentStore(cwd) {
+function assignmentStoreForDir(dirPath) {
     return new JsonStore({
-        dirPath: assignmentsDir(cwd, 'read'),
+        dirPath,
         documentType: 'assignment',
         getId: (a) => a.id,
         sort: (a, b) => a.created_at.localeCompare(b.created_at),
     });
 }
+// NOTE: there is deliberately no single-directory reader left in this module. A helper that
+// resolved ONE dir via the `hasContent` heuristic is what made a legacy record invisible to
+// the list while the by-id loader could see it; removing it means the next reader cannot
+// reintroduce the asymmetry by reaching for the convenient function.
 // ── CRUD ─────────────────────────────────────────────────────
 export function saveAssignment(assignment, cwd) {
     mutate({ cwd }, () => {
@@ -55,21 +61,71 @@ export function saveAssignment(assignment, cwd) {
         emitRegistryPostImage('assignment', parsed, { created, agent: parsed.agent, agent_id: parsed.agent_id, session_id: parsed.session_id, cwd });
         registryFaultPoint('after_registry_journal');
         store.save(parsed);
+        // CONVERGE THE OTHER LAYOUT, exactly as saveClaim does. Without this, a save wrote
+        // canonical and LEFT a legacy copy holding the stale status: `loadAssignment` reads
+        // canonical first so the record looked right, but `deleteAssignment` removed only the
+        // canonical one and the stale copy became the record again — a zombie resurrection.
+        // Best effort on purpose: `listAssignments` reads both dirs, so a missed cleanup stays
+        // visible rather than silently dropping data. (Fable audit; claims.ts already had it.)
+        const writeDir = assignmentsDir(cwd, 'write');
+        for (const dirPath of entityRecordDirs('assignments', cwd ?? process.cwd())) {
+            if (dirPath === writeDir)
+                continue;
+            const legacyPath = path.join(dirPath, `${parsed.id}.json`);
+            try {
+                if (fs.existsSync(legacyPath))
+                    fs.unlinkSync(legacyPath);
+            }
+            catch { /* best effort — the dual-layout list keeps it visible */ }
+        }
     });
 }
 export function loadAssignment(id, cwd) {
     // JsonStore.load throws when the id is missing; honor the declared
     // "| undefined" return type so callers (e.g. transitionAssignment)
     // can emit their own 'Assignment not found' error with the right wording.
-    try {
-        return assignmentStore(cwd).load(id);
-    }
-    catch {
-        return undefined;
+    //
+    // RECORD-SPECIFIC ACROSS BOTH LAYOUTS (pln#649 step 3 review P1-2, reproduced).
+    // `assignmentStore` resolves a DIRECTORY via resolveEntityDir(..., 'read'), which
+    // picks the canonical one as soon as it holds ANY file — so in a store
+    // mid-migration a legacy `assignments/asgn_x.json` was invisible even though the
+    // step-2 locator had just found it. Locator said `found`, this said `not found`:
+    // the same defect one layer down. Asking "where is THIS record" needs both
+    // layouts, exactly as recordPaths does in the locator.
+    for (const dirPath of entityRecordDirs('assignments', cwd ?? process.cwd())) {
+        try {
+            return new JsonStore({
+                dirPath,
+                documentType: 'assignment',
+                getId: (a) => a.id,
+                sort: (a, b) => a.created_at.localeCompare(b.created_at),
+            }).load(id);
+        }
+        catch { /* not in this layout — try the other */ }
     }
+    return undefined;
 }
+/**
+ * BOTH LAYOUTS, canonical winning on a duplicate id (mirrors listClaims).
+ *
+ * The by-id loader was fixed to read both layouts while this list still read ONE
+ * directory, chosen by the `hasContent` heuristic — so three layers gave three answers
+ * about the same store. The concrete consequence: a legacy run/assignment invisible to
+ * the list while visible by id, which lets `nextAttemptIndex` restart at 1 and collide,
+ * and makes `getActiveAssignmentForAgent` miss a live assignment so the worker's implicit
+ * heartbeat stops proving liveness. Reachability is LOW (assignments postdate the
+ * partitioned layout, so brainclaw has never written them flat — measured: legacy=0 in
+ * the field), which is why this is internal consistency rather than a field fix.
+ */
 export function listAssignments(cwd, filter) {
-    let items = assignmentStore(cwd).list();
+    const byId = new Map();
+    for (const dirPath of entityRecordDirs('assignments', cwd ?? process.cwd())) {
+        for (const a of assignmentStoreForDir(dirPath).list()) {
+            if (!byId.has(a.id))
+                byId.set(a.id, a);
+        }
+    }
+    let items = Array.from(byId.values()).sort((a, b) => a.created_at.localeCompare(b.created_at));
     if (filter?.status)
         items = items.filter((a) => a.status === filter.status);
     if (filter?.agent)
@@ -82,21 +138,30 @@ export function listAssignments(cwd, filter) {
         items = items.filter((a) => a.sequence_id === filter.sequence_id);
     return items;
 }
+/**
+ * Deletes the record in EVERY layout, not just the canonical one.
+ *
+ * Checking only the write dir meant a record `loadAssignment` could find returned `false`
+ * from delete — and worse, deleting the canonical copy of a dual-layout record promoted
+ * the stale legacy copy back to being the record. Deleting one layout is not deleting.
+ */
 export function deleteAssignment(id, cwd) {
     return mutate({ cwd }, () => {
-        const writableStore = new JsonStore({
-            dirPath: assignmentsDir(cwd, 'write'),
-            documentType: 'assignment',
-            getId: (a) => a.id,
-            sort: (a, b) => a.created_at.localeCompare(b.created_at),
-        });
-        if (!writableStore.exists(id)) {
+        const dirs = entityRecordDirs('assignments', cwd ?? process.cwd());
+        const holders = dirs.filter((dirPath) => assignmentStoreForDir(dirPath).exists(id));
+        if (holders.length === 0) {
             return false;
         }
-        const assignment = writableStore.load(id);
+        // One tombstone for the record, from the copy that wins reads.
+        const assignment = assignmentStoreForDir(holders[0]).load(id);
         emitRegistryTombstone('assignment', assignment.id, { agent: assignment.agent, agent_id: assignment.agent_id, session_id: assignment.session_id, cwd });
         registryFaultPoint('after_registry_journal');
-        writableStore.delete(id);
+        for (const dirPath of holders) {
+            try {
+                assignmentStoreForDir(dirPath).delete(id);
+            }
+            catch { /* another layout already gone — the remaining ones still must go */ }
+        }
         return true;
     });
 }
@@ -295,7 +360,10 @@ export function recordProgress(id, options, cwd) {
 export function createAssignment(options, cwd) {
     const generated = options.id ? undefined : generateAssignmentId(cwd);
     const id = options.id ?? generated.id;
-    const short_label = options.short_label ?? generated.short_label;
+    // `generated` is undefined whenever the caller supplied an id, so the old
+    // `generated!.short_label` threw a TypeError on the perfectly reasonable call
+    // "give me this id, derive the rest". Found while pinning the layout primitive.
+    const short_label = options.short_label ?? generated?.short_label ?? id;
     const assignment = AssignmentSchema.parse({
         schema_version: 1,
         id,
@@ -309,6 +377,13 @@ export function createAssignment(options, cwd) {
         agent_id: options.agent_id,
         dispatcher_agent: options.dispatcher_agent,
         dispatcher_session_id: options.dispatcher_session_id,
+        // OWNER project, captured HERE in core (pln#649 step 1) rather than in the
+        // command layer: every caller — MCP, CLI, dispatcher, loop engine — writes
+        // into `cwd`, so deriving it here means no path can create an assignment
+        // without an owner. The claim surface does this in TWO command-layer sites
+        // that already disagree (mcp-write-claims.ts uses loadConfig(claimCwd),
+        // claim.ts uses actor.project_id); core is the one place that cannot drift.
+        project_id: resolveOwnerProjectId(cwd),
         scope: options.scope,
         description: options.description,
         lane: options.lane,

package/dist/core/claims.js

@@ -3,7 +3,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { ClaimSchema } from './schema.js';
-import { resolveEntityDir } from './io.js';
+import { entityRecordDirs, resolveEntityDir } from './io.js';
 import { mutate } from './mutation-pipeline.js';
 import { nowISO } from './ids.js';
 import { JsonStore } from './json-store.js';
@@ -33,12 +33,19 @@ function parseTtl(value) {
 function claimsDir(cwd, mode = 'read') {
     return resolveEntityDir('claims', cwd ?? process.cwd(), mode);
 }
+/**
+ * Both layouts a claim record can occupy, canonical first (pln#649).
+ *
+ * The previous shape — `Set([claimsDir(write), claimsDir(read)])` — LOOKED like it
+ * covered both and did not: `write` is always canonical, and `read` also returns
+ * canonical as soon as that directory holds any file, so the Set collapsed to ONE
+ * entry and a legacy claim went invisible mid-migration. Same defect as the one
+ * reproduced twice on assignments; found here by a Fable audit before it reached a
+ * field report. Now derived from the shared io.ts primitive, so there is one
+ * definition instead of four look-alikes.
+ */
 function claimDirs(cwd) {
-    const effectiveCwd = cwd ?? process.cwd();
-    return Array.from(new Set([
-        claimsDir(effectiveCwd, 'write'),
-        claimsDir(effectiveCwd, 'read'),
-    ]));
+    return entityRecordDirs('claims', cwd ?? process.cwd());
 }
 export function ensureClaimsDir(cwd) {
     const dir = claimsDir(cwd, 'write');

package/dist/core/config.js

@@ -88,6 +88,64 @@ export function loadConfig(cwd, preferredDirName) {
     const filepath = memoryPath(CONFIG_FILE, cwd, preferredDirName);
     return loadVersionedYamlFile('config', filepath).document;
 }
+/**
+ * pln#649 step 1 (dec#153) — the OWNER project of an execution entity: the
+ * `project_id` of the store the entity is being written into, captured once at
+ * creation and never re-derived.
+ *
+ * This is the anchor the entity-authoritative routing of dec#153 compares
+ * against: for any work unit, `owner_project` is fixed at creation and every
+ * read/mutation of that unit must reach THAT store — regardless of pid, cwd,
+ * session or the shared global pointer. Without a persisted owner there is
+ * nothing for the hard-refusal check to compare, and nothing for a worker to
+ * derive its project from.
+ *
+ * DELIBERATELY `project_id`, not a new field. `ClaimSchema` already carries BOTH
+ * `project_id` (a stable prj_* id) and `project` (a free-text namespace LABEL
+ * consumed by filters — mcp-read-handlers.ts / coordination.ts). Adding a third
+ * project-ish field would have been the same defect one level up, so this reuses
+ * the id and leaves the label alone. Operator decision, 2026-08-04.
+ *
+ * SWALLOWS ONLY "there is no store here" (ENOENT / ENOTDIR). Everything else —
+ * malformed YAML, schema-invalid config, permission denied, I/O failure — is
+ * RETHROWN (review P1-2). A catch-all was the first version and it was wrong in a
+ * way that defeated the whole point: a store with a corrupt config but writable
+ * coordination dirs would create entities with NO owner, and step 4 would then
+ * read the absent owner as "legacy", skip its refusal, and silently hand back the
+ * guarantee this field exists to provide. Degrading quietly is exactly the failure
+ * mode dec#153 is against.
+ *
+ * The field is optional on every schema so a record written before it existed
+ * stays loadable. (An earlier version of this comment claimed a zod-invalid record
+ * is DELETED on the next syncDirectory — that is false for the current code:
+ * state.ts preserves unparseable files precisely so a parse failure cannot corrupt
+ * data (trp#126). Required would make old records unloadable, not deleted.)
+ */
+export function resolveOwnerProjectId(cwd, options = {}) {
+    try {
+        return loadConfig(cwd).project_id;
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return undefined; // no store here
+        // A store that EXISTS but cannot be read (malformed YAML, schema-invalid,
+        // permission, I/O). Review P1-2 asked for a rethrow so a corrupt store could
+        // not quietly produce ownerless entities that a later refusal would wave
+        // through as "legacy". The intent is right and the placement was not: a
+        // rethrow HERE made `createAssignment` throw, the dispatcher swallowed it, and
+        // every dispatch silently lost its assignment_id — six CI jobs, caught only by
+        // the full suite. Breaking dispatch is worse than a missing owner.
+        //
+        // So the default is lenient — CREATION MUST NEVER FAIL because a config is
+        // corrupt — and the strictness moves to the consumer that actually needs it:
+        // pass `strict` from the refusal path (pln#649 step 4), where "I could not read
+        // the owner" must be a loud stop rather than an implicit "legacy".
+        if (options.strict)
+            throw err;
+        return undefined;
+    }
+}
 export function saveConfig(config, cwd, preferredDirName) {
     const filepath = memoryPath(CONFIG_FILE, cwd, preferredDirName);
     saveVersionedYamlFile('config', filepath, ConfigSchema.parse(config));

package/dist/core/context-diff.js

@@ -1,8 +1,7 @@
 import fs from 'node:fs';
-import path from 'node:path';
 import { readAuditLog } from './audit.js';
 import { listCandidates } from './candidates.js';
-import { resolveEntityDir } from './io.js';
+import { entityRecordPaths } from './io.js';
 import { loadVersionedJsonFile } from './migration.js';
 import { buildNotificationSummary, hasEventCursor, readUnseenEvents, seedCursorToEnd } from './event-log.js';
 import { SessionSnapshotSchema } from './schema.js';
@@ -28,17 +27,35 @@ export function resolveContextDiffSince(options) {
     // everyone's diff baseline.
     return {};
 }
+/**
+ * THE LAST BY-ID SITE THAT COULD ACTUALLY FIRE, and the only one with live two-layout
+ * data in the field: this store holds 173 sessions in the legacy layout next to 1019
+ * canonical ones (dec#153-T2's dual write). `resolveEntityDir(..., 'read')` answers a
+ * DIRECTORY question with a `hasContent` heuristic, so one canonical file made every
+ * legacy record invisible — the same malformed abstraction pln#649 removed from the
+ * entity locator and the by-id loaders, still here because nothing routed sessions.
+ *
+ * The consequence was a SILENT WRONG ANSWER, which is why this one was worth fixing
+ * while the sibling sites were not: an invisible snapshot falls through to the audit-log
+ * scan, and if that misses too `resolveContextDiffSince` returns no `since`, so
+ * `buildContextDiff` returns undefined and the caller is told "no changes" over a window
+ * where there were changes. An agent cannot tell that apart from a quiet period.
+ *
+ * Uses the shared primitive rather than a fourth hand-rolled pair of paths (io.ts).
+ */
 function loadSessionSnapshot(sessionId, cwd) {
-    const snapshotPath = path.join(resolveEntityDir('sessions', cwd ?? process.cwd(), 'read'), `${sessionId}.json`);
-    if (!fs.existsSync(snapshotPath)) {
-        return undefined;
-    }
-    try {
-        return SessionSnapshotSchema.parse(loadVersionedJsonFile('session_snapshot', snapshotPath).document);
-    }
-    catch {
-        return undefined;
+    for (const snapshotPath of entityRecordPaths('sessions', sessionId, cwd ?? process.cwd())) {
+        if (!fs.existsSync(snapshotPath))
+            continue;
+        try {
+            return SessionSnapshotSchema.parse(loadVersionedJsonFile('session_snapshot', snapshotPath).document);
+        }
+        catch {
+            // An unparseable record in one layout must not mask a good one in the other.
+            continue;
+        }
     }
+    return undefined;
 }
 export function buildContextDiff(options = {}) {
     const resolved = resolveContextDiffSince(options);