brainclaw 1.26.0 → 1.26.2

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 { isSessionSnapshotRecordFilename, 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 = listCurrentSessionFiles(dir);
-        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,49 +151,61 @@ export function loadCurrentSession(cwd) {
  * Load a specific session by ID.
  */
 export function loadSessionById(sessionId, cwd) {
-    let filepath;
-    try {
-        filepath = sessionFilePath(sessionId, cwd);
-    }
-    catch {
-        // Reserved '.snapshot' alias id — such a current_session record can never exist.
-        return undefined;
-    }
-    if (!fs.existsSync(filepath))
-        return undefined;
-    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.
-        return session.session_id === sessionId ? session : undefined;
-    }
-    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 = listCurrentSessionFiles(dir);
+    // 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));
@@ -191,40 +221,62 @@ export function saveCurrentSession(session, cwd) {
     // 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 legacy `<id>.json` can still hold a pre-split snapshot (the old
-    // 'read'-mode write bug parked snapshots in this directory). Only overwrite
-    // a record that PROVES it is this exact current_session entry (codex review).
-    if (fs.existsSync(filepath) && !loadSessionById(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. A filename is never enough authority to
-        // delete a record (codex review P1): the '.snapshot' alias id throws in
-        // sessionFilePath (caught → no-op), and an existing file is only unlinked
-        // when loadSessionById PROVES it is this exact current_session record —
-        // never a pre-split snapshot parked under a plain `<id>.json`.
-        try {
-            if (loadSessionById(sessionId, cwd)) {
-                fs.unlinkSync(sessionFilePath(sessionId, cwd));
+    // 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);
@@ -238,43 +290,95 @@ 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 = listCurrentSessionFiles(dir);
-    for (const file of files) {
-        const filepath = path.join(dir, file);
-        try {
-            // 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++;
+    // 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 {
+                // 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 {
-            // An unidentifiable record is not proven stale current_session state —
-            // preserving it beats risking the deletion of a legacy snapshot.
         }
     }
     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
@@ -294,7 +398,11 @@ function listCurrentSessionFiles(dir) {
 function isCurrentSessionFilename(sessionId) {
     return !isSessionSnapshotRecordFilename(`${sessionId}.json`);
 }
-function sessionFilePath(sessionId, cwd) {
+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
@@ -302,7 +410,10 @@ function sessionFilePath(sessionId, cwd) {
     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(sessionsDir(cwd), `${sessionId}.json`);
+    return path.join(dir, `${sessionId}.json`);
+}
+function sessionFilePath(sessionId, cwd) {
+    return sessionFilePathIn(sessionsDir(cwd), sessionId);
 }
 function resolveCurrentUser() {
     return process.env.USER || process.env.USERNAME || os.userInfo().username || undefined;
@@ -321,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);