brainclaw 1.25.0 → 1.26.1

package/dist/core/code-map/work-section.js

@@ -18,7 +18,7 @@
  *                      bclaw_work beyond that bounded wait (rule §6 rule 8).
  */
 import { readManifest } from './store.js';
-import { withCoarse } from './freshness.js';
+import { withFreshness } from './freshness.js';
 import { readCodeLock, isLockAbandoned } from './lock.js';
 import { codeMapDir, lockPath } from './paths.js';
 import { JsonlBackend } from './backend.js';
@@ -108,9 +108,9 @@ export async function codeMapWorkSection(cwd, opts = {}) {
                     return {
                         enabled: true,
                         matches: out.matches,
-                        freshness_badge: withCoarse({
+                        freshness_badge: withFreshness({
                             status: 'partial',
-                            details: { partial_reason: 'code_map_lock_active', lock_wait_ms: lockWaitMs },
+                            details: { spot_check: { status: 'partial', partial_reason: 'code_map_lock_active' }, lock_wait_ms: lockWaitMs },
                         }),
                         lock_wait_ms: lockWaitMs,
                     };
@@ -122,9 +122,9 @@ export async function codeMapWorkSection(cwd, opts = {}) {
             return {
                 enabled: true,
                 matches: [],
-                freshness_badge: withCoarse({
+                freshness_badge: withFreshness({
                     status: 'partial',
-                    details: { partial_reason: 'code_map_lock_active', lock_wait_ms: lockWaitMs },
+                    details: { spot_check: { status: 'partial', partial_reason: 'code_map_lock_active' }, lock_wait_ms: lockWaitMs },
                 }),
                 lock_wait_ms: lockWaitMs,
             };
@@ -136,7 +136,7 @@ export async function codeMapWorkSection(cwd, opts = {}) {
             enabled: true,
             missing_index: 'Code Map index is empty for this project. Run `brainclaw code-map refresh --all` (or bclaw_code_refresh) before relying on find/brief.',
             matches: [],
-            freshness_badge: withCoarse({ status: 'missing_index', details: {} }),
+            freshness_badge: withFreshness({ status: 'missing_index', details: {} }),
             ...(lockWaitMs !== undefined ? { lock_wait_ms: lockWaitMs } : {}),
         };
     }
@@ -144,16 +144,14 @@ export async function codeMapWorkSection(cwd, opts = {}) {
     // lazy read-path check (§6.1) returns the true freshness badge, so stale
     // results are surfaced WITH the stale badge rather than hidden.
     if (!query) {
+        // Use the same read-only index observation as bclaw_code_status. This keeps
+        // bclaw_work aligned with status/find/brief for git-HEAD drift too, while
+        // still avoiding any lazy refresh or source parsing.
+        const status = await backend.status({ cwd: ctx.cwd, preferredDirName: ctx.preferredDirName });
         return {
             enabled: true,
             matches: [],
-            freshness_badge: withCoarse({
-                status: manifest.freshness.status,
-                details: {
-                    stale_file_count: manifest.freshness.stale_file_count,
-                    partial_reason: manifest.freshness.partial_reason,
-                },
-            }),
+            freshness_badge: status.freshness_badge,
             ...(lockWaitMs !== undefined ? { lock_wait_ms: lockWaitMs } : {}),
         };
     }
@@ -193,7 +191,7 @@ export function codeMapRefreshNextActions(section) {
             },
         ];
     }
-    if (section.freshness_badge?.status?.startsWith('stale_')) {
+    if (section.freshness_badge?.freshness === 'stale') {
         return [
             {
                 tool: 'bclaw_code_refresh',

package/dist/core/context-diff.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import { readAuditLog } from './audit.js';
 import { listCandidates } from './candidates.js';
-import { entityRecordPaths } from './io.js';
+import { sessionSnapshotRecordPaths } from './io.js';
 import { loadVersionedJsonFile } from './migration.js';
 import { buildNotificationSummary, hasEventCursor, readUnseenEvents, seedCursorToEnd } from './event-log.js';
 import { SessionSnapshotSchema } from './schema.js';
@@ -44,11 +44,25 @@ export function resolveContextDiffSince(options) {
  * Uses the shared primitive rather than a fourth hand-rolled pair of paths (io.ts).
  */
 function loadSessionSnapshot(sessionId, cwd) {
-    for (const snapshotPath of entityRecordPaths('sessions', sessionId, cwd ?? process.cwd())) {
+    // pln#670 — snapshots carry a type-suffixed name (`<id>.snapshot.json`);
+    // the helper also probes the pre-split `<id>.json` layouts.
+    for (const snapshotPath of sessionSnapshotRecordPaths(sessionId, cwd ?? process.cwd())) {
         if (!fs.existsSync(snapshotPath))
             continue;
         try {
-            return SessionSnapshotSchema.parse(loadVersionedJsonFile('session_snapshot', snapshotPath).document);
+            // Deliberately NOT type-strict (pln#649 + pln#670): this reader answers
+            // "when did session X start" to anchor the diff window, and a
+            // current_session record for the same id is an equally authoritative
+            // source of `started_at`. The suffixed probes come first, so a real
+            // snapshot (richer: context_target, git_sha) still wins when both exist.
+            // Contrast with session-start's loadSessionSnapshot, which must stay
+            // strict — its consumers treat the record as a genuine snapshot.
+            const snapshot = SessionSnapshotSchema.parse(loadVersionedJsonFile('session_snapshot', snapshotPath).document);
+            // A suffix-bearing lookup can construct another snapshot's path (codex
+            // review). Its started_at is useful only when the stored identity matches.
+            if (snapshot.session_id !== sessionId)
+                continue;
+            return snapshot;
         }
         catch {
             // An unparseable record in one layout must not mask a good one in the other.

package/dist/core/entity-operations.js

@@ -28,7 +28,7 @@ import { deleteAssignment, listAssignments, loadAssignment, saveAssignment, tran
 import { listAgentRuns } from './agentruns.js';
 import { reconcileAgentRun, reconcileDeadPidRunningAgentRunAtRead, reconcileStrandedFailureClaimAtRead, TERMINAL_STATUSES } from './agentrun-reconciler.js';
 import { isObserverMode } from './observer-mode.js';
-import { deleteRuntimeNote, listRuntimeNotes, saveRuntimeNote, } from './runtime.js';
+import { deleteRuntimeNote, listRuntimeNotes, parkRuntimeNoteBackup, saveRuntimeNote, } from './runtime.js';
 import { createSequence, deleteSequence, listSequences, updateSequence, } from './sequence.js';
 import { createConstraint, createDecision, createTrap, } from './operations/memory-write.js';
 import { deleteMemoryItem, findMemoryItemInChain, updateMemoryItem, } from './operations/memory-mutation.js';
@@ -853,10 +853,22 @@ export function removeEntity(name, id, cwd, purge = false) {
             const note = notes.find((n) => n.id === id);
             if (!note)
                 throw new EntityNotFoundError(name, id);
+            // trp_dc9ca61e — the tool contract says "archives by default", but this
+            // path hard-deleted regardless of `purge` (runtime_note has no lifecycle,
+            // so there was no soft state to land in). Default remove now parks the
+            // raw record under gc-backups — the same net the retention sweeps use —
+            // and fails CLOSED when the park is impossible: silently downgrading an
+            // archive into a hard-delete is the defect being fixed.
+            if (!purge) {
+                const backupPath = parkRuntimeNoteBackup(note, cwd);
+                if (!backupPath) {
+                    throw new Error(`runtime_note '${id}' could not be archived to gc-backups; pass purge:true to hard-delete`);
+                }
+            }
             const ok = deleteRuntimeNote(note, cwd);
             if (!ok)
                 throw new EntityNotFoundError(name, id);
-            return { entity: name, id, archived: false, purged: true };
+            return { entity: name, id, archived: !purge, purged: purge };
         }
         case 'candidate': {
             // Remove = archive to rejected. `purge` would delete the file; not exposed yet.

package/dist/core/hint-aging.js

@@ -123,7 +123,10 @@ export function ageStaleWarnings(warnings, cwd, options = {}) {
             const overflow = ids.length - shown.length;
             return `${ids.length} ${entity}${ids.length === 1 ? '' : 's'}: ${shown.join(', ')}${overflow > 0 ? ` +${overflow} more` : ''}`;
         });
-        aggregate = `${folded.length} stale item${folded.length === 1 ? '' : 's'} you've already been offered (${parts.join('; ')}) — bclaw_get each id to review, or bclaw_transition to retire.`;
+        // trp_dc9ca61e — do not recommend bclaw_transition for runtime_notes: they
+        // have no lifecycle and the call errors. bclaw_remove (archive by default)
+        // is their retirement path.
+        aggregate = `${folded.length} stale item${folded.length === 1 ? '' : 's'} you've already been offered (${parts.join('; ')}) — bclaw_get each id to review; retire with bclaw_transition, or bclaw_remove for runtime_notes (no lifecycle).`;
     }
     return { warnings: detail, aggregate, served_ids, folded_ids };
 }

package/dist/core/identity.js

@@ -6,18 +6,19 @@ import { detectAiAgent } from './ai-agent-detection.js';
 import { requireRegisteredAgentIdentity } from './agent-registry.js';
 import { loadConfig } from './config.js';
 import { resolveCurrentHostId } from './host.js';
-import { memoryDir } from './io.js';
+import { assertSafeSessionId, findSessionAnchorRoot, isSafeSessionId, isSessionSnapshotRecordFilename, memoryDir } from './io.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from './migration.js';
 import { CurrentSessionStateSchema } from './schema.js';
 const SESSIONS_DIR = 'sessions';
 const LEGACY_SESSION_FILE = '.current-session';
 // --- Public API ---
 export function resolveCurrentSessionId(env = process.env, cwd, options = {}) {
-    const value = env.BRAINCLAW_SESSION_ID?.trim()
-        || env.OPENCLAW_SESSION_ID?.trim()
-        || env.CLAUDE_SESSION_ID?.trim()
-        || env.COPILOT_SESSION_ID?.trim();
-    if (value && value.length > 0) {
+    // pln#672 review P1: ONE validated resolution for the env session id. This
+    // used to re-read the variables raw, so an unsafe value bypassed the
+    // boundary here and reached startSession's snapshot write — the traversal
+    // stayed exploitable through a second writer (reproduced by the reviewer).
+    const value = resolveExplicitSessionId(env);
+    if (value) {
         return value;
     }
     const agentName = options.agentName?.trim();
@@ -73,7 +74,6 @@ export function resolveEventSessionId(event) {
  * Checks sessions/ directory first, falls back to legacy .current-session.
  */
 export function loadCurrentSession(cwd) {
-    const dir = sessionsDir(cwd);
     const currentUser = resolveCurrentUser();
     const currentAgent = resolveCurrentAgentName();
     const explicitSessionId = resolveExplicitSessionId();
@@ -83,34 +83,52 @@ export function loadCurrentSession(cwd) {
         const explicit = loadSessionById(explicitSessionId, cwd);
         return explicit && isSessionAlive(explicit, ttlMs, now) ? explicit : undefined;
     }
-    // 1. Look in sessions/ directory for the session owned by this process.
-    // Multiple parallel agents can have the same agent name/user in one repo;
-    // a live different PID is a different agent instance, not our session.
-    if (fs.existsSync(dir) && currentAgent) {
-        const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
-        const legacyPidlessCandidates = [];
-        for (const file of files) {
-            try {
-                const session = loadSessionFile(path.join(dir, file));
-                // Strict match: agent name must match, user must match (when both are known)
-                if (session.agent !== currentAgent)
-                    continue;
-                const userMatch = !session.user || !currentUser || session.user === currentUser;
-                if (!userMatch || !isSessionAlive(session, ttlMs, now))
-                    continue;
-                if (session.pid === process.pid) {
-                    return session;
+    // 1. Look in the sessions read-chain (workspace anchor first, then the
+    // pre-anchor legacy location — pln#648) for the session owned by this
+    // process. Multiple parallel agents can have the same agent name/user in
+    // one repo; a live different PID is a different agent instance, not our
+    // session. Pidless legacy candidates are deduped by id: during relocation a
+    // record can transiently exist in both locations, and a duplicate must not
+    // inflate the candidate count.
+    if (currentAgent) {
+        const currentHostId = resolveCurrentHostId();
+        const legacyPidlessCandidates = new Map();
+        for (const dir of sessionsDirs(cwd)) {
+            if (!fs.existsSync(dir))
+                continue;
+            for (const file of listCurrentSessionFiles(dir)) {
+                try {
+                    const session = loadSessionFile(path.join(dir, file));
+                    // Strict match: agent name must match, user must match (when both are known)
+                    if (session.agent !== currentAgent)
+                        continue;
+                    const userMatch = !session.user || !currentUser || session.user === currentUser;
+                    if (!userMatch || !isSessionAlive(session, ttlMs, now))
+                        continue;
+                    if (session.pid === process.pid) {
+                        return session;
+                    }
+                    // Legacy pidless adoption, HOST-GUARDED (pln#648 anchoring follow-up):
+                    // anchoring parks every session of the workspace at one directory, so
+                    // the historical weak adoption — agent name + user only — would now
+                    // see records it never saw before, including another instance's
+                    // stale intent (the exact hijack the P1-1/P1-2 review pins forbid on
+                    // the resolver's added probes). A pidless record is only adoptable
+                    // when it was written by THIS host; foreign-instance records need
+                    // strong identity (named id or pid) everywhere.
+                    if (session.pid === undefined
+                        && (!session.host_id || session.host_id === currentHostId)
+                        && !legacyPidlessCandidates.has(session.session_id)) {
+                        legacyPidlessCandidates.set(session.session_id, session);
+                    }
                 }
-                if (session.pid === undefined) {
-                    legacyPidlessCandidates.push(session);
+                catch {
+                    // skip invalid session files
                 }
             }
-            catch {
-                // skip invalid session files
-            }
         }
-        if (legacyPidlessCandidates.length === 1) {
-            return legacyPidlessCandidates[0];
+        if (legacyPidlessCandidates.size === 1) {
+            return [...legacyPidlessCandidates.values()][0];
         }
     }
     // 2. Legacy fallback: .current-session
@@ -133,39 +151,61 @@ export function loadCurrentSession(cwd) {
  * Load a specific session by ID.
  */
 export function loadSessionById(sessionId, cwd) {
-    const filepath = sessionFilePath(sessionId, cwd);
-    if (!fs.existsSync(filepath))
-        return undefined;
-    try {
-        const migration = loadVersionedJsonFile('current_session', filepath);
-        return {
-            ...CurrentSessionStateSchema.parse(migration.document),
-            schema_version: migration.metadata.currentVersion,
-        };
-    }
-    catch {
+    // A READ answers "no such record" rather than throwing: an unsafe id
+    // (traversal — pln#672) or the reserved '.snapshot' alias (pln#670) simply
+    // cannot name a current_session record. The throwing guard stays in
+    // sessionFilePathIn for the write paths.
+    if (!isSafeSessionId(sessionId) || !isCurrentSessionFilename(sessionId))
         return undefined;
+    // pln#648 read-chain: anchor first, then the pre-anchor legacy location. A
+    // bad record in one location must not mask a good one in the other.
+    for (const dir of sessionsDirs(cwd)) {
+        const filepath = sessionFilePathIn(dir, sessionId);
+        if (!fs.existsSync(filepath))
+            continue;
+        try {
+            const migration = loadVersionedJsonFile('current_session', filepath);
+            const session = {
+                ...CurrentSessionStateSchema.parse(migration.document),
+                schema_version: migration.metadata.currentVersion,
+            };
+            // The filename is only an index, never an identity (codex review): do not
+            // adopt a record whose payload names a different session.
+            if (session.session_id === sessionId)
+                return session;
+        }
+        catch {
+            // fall through to the next location
+        }
     }
+    return undefined;
 }
 /**
  * Load ALL sessions (active + stale) from the sessions/ directory.
  */
 export function loadAllSessions(cwd) {
-    const dir = sessionsDir(cwd);
-    if (!fs.existsSync(dir))
-        return [];
-    const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+    // pln#648 read-chain: anchored records win over a transient pre-anchor copy
+    // of the same session (dedup by id, anchor scanned first).
+    const seen = new Set();
     const sessions = [];
-    for (const file of files) {
-        try {
-            const migration = loadVersionedJsonFile('current_session', path.join(dir, file));
-            sessions.push({
-                ...CurrentSessionStateSchema.parse(migration.document),
-                schema_version: migration.metadata.currentVersion,
-            });
-        }
-        catch {
-            // skip invalid
+    for (const dir of sessionsDirs(cwd)) {
+        if (!fs.existsSync(dir))
+            continue;
+        for (const file of listCurrentSessionFiles(dir)) {
+            try {
+                const migration = loadVersionedJsonFile('current_session', path.join(dir, file));
+                const session = {
+                    ...CurrentSessionStateSchema.parse(migration.document),
+                    schema_version: migration.metadata.currentVersion,
+                };
+                if (seen.has(session.session_id))
+                    continue;
+                seen.add(session.session_id);
+                sessions.push(session);
+            }
+            catch {
+                // skip invalid
+            }
         }
     }
     return sessions.sort((a, b) => b.last_seen_at.localeCompare(a.last_seen_at));
@@ -178,30 +218,65 @@ export function saveCurrentSession(session, cwd) {
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
+    // sessionFilePath throws on a '.snapshot' alias id — a write must never
+    // construct a snapshot filename (codex review P1).
     const filepath = sessionFilePath(session.session_id, cwd);
+    // A plain `<id>.json` can still hold a pre-split snapshot (the old
+    // 'read'-mode write bug parked snapshots in session directories). Only
+    // overwrite THIS path when its record proves to be this exact
+    // current_session entry (codex review, made path-local by pln#648: the
+    // proof must be about the file being replaced, not about any location).
+    if (fs.existsSync(filepath) && !isProvenCurrentSessionAt(filepath, session.session_id)) {
+        throw new Error(`Refusing to overwrite non-current_session record at '${filepath}'`);
+    }
     saveVersionedJsonFile('current_session', filepath, CurrentSessionStateSchema.parse(session));
+    // pln#648 relocation: a pre-anchor copy of the SAME session under the
+    // effective cwd would linger until TTL decay — remove it once the anchored
+    // write has landed, on positive proof only. Best effort: the read-chain and
+    // the GC cover any leftover. legacySessionsDir normalizes exactly like the
+    // anchor (codex review P1): a relative cwd must never make the SAME
+    // directory compare unequal — the unlink below would delete the record
+    // this function just wrote.
+    const legacyDir = legacySessionsDir(cwd);
+    if (legacyDir !== dir) {
+        try {
+            const legacyPath = sessionFilePathIn(legacyDir, session.session_id);
+            if (fs.existsSync(legacyPath) && isProvenCurrentSessionAt(legacyPath, session.session_id)) {
+                fs.unlinkSync(legacyPath);
+            }
+        }
+        catch { /* best effort */ }
+    }
 }
 /**
  * Clear a session. If sessionId is provided, only clear that specific session.
  */
 export function clearCurrentSession(cwd, sessionId) {
-    if (sessionId) {
-        // Remove specific session file
-        const filepath = sessionFilePath(sessionId, cwd);
-        try {
-            fs.unlinkSync(filepath);
+    // A filename is never enough authority to delete a record (codex review P1):
+    // the '.snapshot' alias id throws in sessionFilePathIn (caught → no-op), and
+    // a file is only unlinked when it PROVES to be this exact current_session
+    // record — never a pre-split snapshot parked under a plain `<id>.json`.
+    // pln#648: the record can live at the anchor OR at the pre-anchor legacy
+    // location — clear wherever it proves.
+    const unlinkProven = (id) => {
+        for (const dir of sessionsDirs(cwd)) {
+            try {
+                const filepath = sessionFilePathIn(dir, id);
+                if (fs.existsSync(filepath) && isProvenCurrentSessionAt(filepath, id)) {
+                    fs.unlinkSync(filepath);
+                }
+            }
+            catch { /* ignore */ }
         }
-        catch { /* ignore */ }
+    };
+    if (sessionId) {
+        unlinkProven(sessionId);
         return;
     }
     // Clear the session for the current agent+user
     const session = loadCurrentSession(cwd);
     if (session) {
-        const filepath = sessionFilePath(session.session_id, cwd);
-        try {
-            fs.unlinkSync(filepath);
-        }
-        catch { /* ignore */ }
+        unlinkProven(session.session_id);
     }
     // Also clean legacy file
     const legacyPath = path.join(memoryDir(cwd), LEGACY_SESSION_FILE);
@@ -215,42 +290,130 @@ export function clearCurrentSession(cwd, sessionId) {
  * Returns the number of sessions removed.
  */
 export function gcStaleSessions(cwd, ttlOverride) {
-    const dir = sessionsDir(cwd);
-    if (!fs.existsSync(dir))
-        return 0;
     const ttlMs = parseDurationToMs(ttlOverride ?? loadConfigSafe(cwd)?.implicit_session_ttl ?? '4h');
     const now = Date.now();
     let removed = 0;
-    const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
-    for (const file of files) {
-        try {
-            const migration = loadVersionedJsonFile('current_session', path.join(dir, file));
-            const session = {
-                ...CurrentSessionStateSchema.parse(migration.document),
-                schema_version: migration.metadata.currentVersion,
-            };
-            if (now - Date.parse(session.last_seen_at) > ttlMs) {
-                fs.unlinkSync(path.join(dir, file));
-                removed++;
-            }
-        }
-        catch {
-            // Remove unparseable files too
+    // pln#648: sweep the whole read-chain — pre-anchor legacy records are
+    // exactly what this GC must decay.
+    for (const dir of sessionsDirs(cwd)) {
+        if (!fs.existsSync(dir))
+            continue;
+        for (const file of listCurrentSessionFiles(dir)) {
+            const filepath = path.join(dir, file);
             try {
-                fs.unlinkSync(path.join(dir, file));
-                removed++;
+                // POSITIVE proof before deletion (codex review): a bare `<id>.json` in
+                // this directory can still be a pre-split snapshot (old 'read'-mode
+                // write bug). Only a record carrying the current_session discriminant
+                // may be collected; anything unidentifiable is preserved, never deleted.
+                const raw = JSON.parse(fs.readFileSync(filepath, 'utf-8'));
+                if (typeof raw.last_seen_at !== 'string')
+                    continue;
+                const migration = loadVersionedJsonFile('current_session', filepath);
+                const session = {
+                    ...CurrentSessionStateSchema.parse(migration.document),
+                    schema_version: migration.metadata.currentVersion,
+                };
+                if (now - Date.parse(session.last_seen_at) > ttlMs) {
+                    fs.unlinkSync(filepath);
+                    removed++;
+                }
+            }
+            catch {
+                // An unidentifiable record is not proven stale current_session state —
+                // preserving it beats risking the deletion of a legacy snapshot.
             }
-            catch { /* ignore */ }
         }
     }
     return removed;
 }
 // --- Internal helpers ---
+/**
+ * pln#648 (a) — the session record must live at a STABLE, workspace-unique
+ * location. Anchored on the effective cwd, the record landed under the store
+ * of the project being LEFT at session-start, and every switch moved the
+ * truth out of the resolver's reach (the reproduced P0: status said api,
+ * writes went to web). The anchor is the outermost .brainclaw/ above cwd —
+ * a pure filesystem answer, independent of active-project state, so every
+ * probe of the same workspace derives the SAME directory.
+ */
+function sessionAnchorCwd(cwd) {
+    // path.resolve BEFORE anchoring (codex review P1): the anchor and the legacy
+    // location below are compared for equality — a relative cwd ('.') must not
+    // make the SAME directory look like two, or the relocation would unlink the
+    // record it just wrote. Role-aware walk: the nearest declared workspace wins,
+    // so sibling workspaces under a parent store stay isolated (review P1 #2).
+    const base = path.resolve(cwd ?? process.cwd());
+    return findSessionAnchorRoot(base) ?? base;
+}
+/** The write + primary read location for current_session records. */
 function sessionsDir(cwd) {
-    return path.join(memoryDir(cwd), SESSIONS_DIR);
+    return path.join(memoryDir(sessionAnchorCwd(cwd)), SESSIONS_DIR);
+}
+/** The pre-anchor legacy location, NORMALIZED the same way as the anchor. */
+function legacySessionsDir(cwd) {
+    return path.join(memoryDir(path.resolve(cwd ?? process.cwd())), SESSIONS_DIR);
+}
+/**
+ * Read-chain (pln#648 migration): anchor first, then the pre-anchor location
+ * under the effective cwd where existing records still live. Sessions expire
+ * within the implicit TTL (4h), so the legacy probe decays naturally — no
+ * rewrite migration; saveCurrentSession relocates its own record on the next
+ * heartbeat and the GC sweeps both. Deduped when both resolve to the same
+ * directory (single-project stores — the common case).
+ */
+function sessionsDirs(cwd) {
+    const anchored = sessionsDir(cwd);
+    const legacy = legacySessionsDir(cwd);
+    return anchored === legacy ? [anchored] : [anchored, legacy];
+}
+/**
+ * Positive proof that the file at `filepath` is THE current_session record for
+ * `sessionId` (pln#670 discipline: a filename is never authority to delete or
+ * overwrite — a plain `<id>.json` can be a pre-split snapshot).
+ */
+function isProvenCurrentSessionAt(filepath, sessionId) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(filepath, 'utf-8'));
+        return typeof raw.last_seen_at === 'string' && raw.session_id === sessionId;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * pln#670 — current_session scanners must be type-strict: session_snapshot
+ * records use the `<id>.snapshot.json` suffix and can share a directory with
+ * current_session records. Without this exclusion, gcStaleSessions would
+ * delete a stray snapshot as "unparseable" and loadCurrentSession could adopt
+ * one as a session candidate.
+ */
+function listCurrentSessionFiles(dir) {
+    // Case-insensitive on purpose (codex review P1): Windows filesystems match
+    // names case-insensitively, so `X.SNAPSHOT.json` IS the snapshot path a
+    // lower-case probe resolves — excluding only the exact-case suffix would let
+    // gcStaleSessions delete it as an unparseable current_session.
+    return fs.readdirSync(dir).filter(f => f.toLowerCase().endsWith('.json') && !isSessionSnapshotRecordFilename(f));
+}
+/** True when `<sessionId>.json` cannot collide with a session_snapshot filename. */
+function isCurrentSessionFilename(sessionId) {
+    return !isSessionSnapshotRecordFilename(`${sessionId}.json`);
+}
+function sessionFilePathIn(dir, sessionId) {
+    // pln#672 — PATH SAFETY first: the id is env-controlled and becomes a
+    // filename, so a traversal ('../../evil') must never build a path. This is
+    // the choke point for save / load / clear alike.
+    assertSafeSessionId(sessionId);
+    // pln#670 review fix (codex P1): a session id ending in ".snapshot" would
+    // produce `<base>.snapshot.json` — the snapshot filename of session <base>
+    // in a shared directory. Refuse the alias instead of silently colliding
+    // across record types; readers treat the throw as "no such record".
+    if (!isCurrentSessionFilename(sessionId)) {
+        throw new Error(`session id '${sessionId}' is reserved for session_snapshot records — the '.snapshot' suffix would collide across record types`);
+    }
+    return path.join(dir, `${sessionId}.json`);
 }
 function sessionFilePath(sessionId, cwd) {
-    return path.join(sessionsDir(cwd), `${sessionId}.json`);
+    return sessionFilePathIn(sessionsDir(cwd), sessionId);
 }
 function resolveCurrentUser() {
     return process.env.USER || process.env.USERNAME || os.userInfo().username || undefined;
@@ -269,11 +432,41 @@ function resolveCurrentAgentName() {
  * resolution from a store the agent never named.
  */
 export function resolveExplicitSessionId(env = process.env) {
-    return env.BRAINCLAW_SESSION_ID?.trim()
+    const named = env.BRAINCLAW_SESSION_ID?.trim()
         || env.OPENCLAW_SESSION_ID?.trim()
         || env.CLAUDE_SESSION_ID?.trim()
         || env.COPILOT_SESSION_ID?.trim()
         || undefined;
+    // pln#672 — this value becomes a FILENAME (`<id>.json`). An id that cannot
+    // safely do so is IGNORED, not honoured: falling back to the implicit
+    // session is safe, while using it walks out of the store (reproduced on
+    // disk with '../../../ESCAPED'). Refusing to run at all would be worse —
+    // a stale exported variable would break every command in the shell — so
+    // the boundary drops the value here and the filename builders below refuse
+    // loudly for any other caller. The drop is NOT silent: session
+    // establishment surfaces it (see describeIgnoredSessionIdEnv).
+    return named && isSafeSessionId(named) ? named : undefined;
+}
+/**
+ * Name the env variable whose session id was DROPPED as unsafe, if any
+ * (pln#672 review — the availability-first fallback must not silently change
+ * the agent's identity: continuing under an implicit session while the caller
+ * believes it resumed the supplied one is exactly the kind of silent
+ * divergence this project refuses).
+ *
+ * Returns the VARIABLE NAME and a non-sensitive reason only — never the raw
+ * value, which is attacker-influenced and would land in logs.
+ */
+export function describeIgnoredSessionIdEnv(env = process.env) {
+    for (const variable of ['BRAINCLAW_SESSION_ID', 'OPENCLAW_SESSION_ID', 'CLAUDE_SESSION_ID', 'COPILOT_SESSION_ID']) {
+        const raw = env[variable]?.trim();
+        if (!raw)
+            continue;
+        // The first variable that carries a value decides — same precedence as
+        // resolveExplicitSessionId, so the report names the one actually used.
+        return isSafeSessionId(raw) ? undefined : { variable, length: raw.length };
+    }
+    return undefined;
 }
 function loadSessionFile(filepath) {
     const migration = loadVersionedJsonFile('current_session', filepath);