brainclaw 1.6.0 → 1.7.1

package/dist/core/dirty-scope.js

@@ -0,0 +1,242 @@
+/**
+ * Scope-aware dirty-working-tree guard for dispatch (pln#520 Tier 2, trp#371).
+ *
+ * The original guard (can_30c295b4) refused review/assign/consult/ideate the
+ * moment ANY uncommitted file existed in the source repo — repo-global, no
+ * comparison to the dispatch scope. In multi-agent use (codex/claude leave
+ * uncommitted files around) that hard-blocks legitimate dispatches, and the
+ * coordination store itself (`.brainclaw/`) is rewritten on every dispatch so
+ * a second `bclaw_coordinate` in the same session ALWAYS saw a dirty tree.
+ *
+ * This helper makes the decision scope-aware. The cardinal rule (converged
+ * across the Tier 2 ideation loop lop_5fc24cc8707992ea): never turn a noisy,
+ * visible false-positive (block a legitimate dispatch) into a SILENT
+ * false-negative (let a worker review/edit stale code with no signal). So
+ * when the scope cannot be proven disjoint from the dirty files, we still
+ * block — `allow_dirty=true` remains the explicit, auditable override.
+ *
+ * Empirical grounding: of ~450 real claim scopes in the store, only 4 contain
+ * a glob and ~60% are not resolvable to paths at all (plan-ids, loop-refs,
+ * prose). So the resolver optimises for the path-prefix case and treats
+ * anything ambiguous as `unknown` (→ conservative block when dirty), rather
+ * than building a glob engine. The rare real globs are delegated to git.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+/** Top-level directories that read as code paths even when not yet on disk. */
+const KNOWN_TOP_LEVEL = new Set([
+    'src', 'lib', 'docs', 'doc', 'test', 'tests', 'packages', 'app', 'apps',
+    'scripts', 'bin', 'public', 'assets', 'examples', 'config',
+]);
+/** Entity-id / loop-ref prefixes that are never file paths. */
+const ENTITY_ID_RE = /^(pln|clm|asg|asgn|run|lop|dec|cst|con|trp|han|can|rtn|rn|seq|sess|agt|art|lsl)[_#]/i;
+function defaultRunGit(cwd, args) {
+    try {
+        const probe = spawnSync('git', ['-C', cwd, ...args], { encoding: 'utf8', timeout: 5000 });
+        if (probe.status !== 0 || typeof probe.stdout !== 'string') {
+            return { ok: false, stdout: '' };
+        }
+        return { ok: true, stdout: probe.stdout };
+    }
+    catch {
+        // Never block a dispatch because git hiccuped — surface as "not probeable".
+        return { ok: false, stdout: '' };
+    }
+}
+/** True for coordination/store paths that are dirty as a side effect of dispatching. */
+export function isSystemDirtyPath(p) {
+    const norm = p.replace(/\\/g, '/');
+    return norm === '.brainclaw'
+        || norm.startsWith('.brainclaw/')
+        || norm === '.git'
+        || norm.startsWith('.git/');
+}
+/**
+ * Parse `git status --porcelain=v1 -z` output into a flat list of paths.
+ *
+ * NUL-separated entries avoid the quoting/newline pitfalls of line parsing.
+ * Rename/copy entries (`R`/`C`) carry the NEW path in the status field and the
+ * ORIGINAL path in the following NUL field — we keep BOTH, because a move out
+ * of scope that creates a file in scope (or vice versa) is a relevant change.
+ */
+export function parsePorcelainZ(stdout) {
+    const parts = stdout.split('\0').filter((p) => p.length > 0);
+    const paths = [];
+    for (let i = 0; i < parts.length; i++) {
+        const entry = parts[i];
+        if (entry.length < 4)
+            continue; // malformed; "XY p" is the minimum
+        const status = entry.slice(0, 2);
+        const newPath = entry.slice(3); // skip "XY " (2 status chars + 1 separator)
+        paths.push(newPath);
+        if (status[0] === 'R' || status[0] === 'C') {
+            const origPath = parts[i + 1];
+            if (origPath !== undefined) {
+                paths.push(origPath);
+                i++; // consume the original-path field
+            }
+        }
+    }
+    return paths;
+}
+/**
+ * Resolve a free-string scope into git pathspecs, or `unknown` when it cannot
+ * be proven to denote file paths. All-or-nothing across comma-separated
+ * tokens: a single unresolvable token marks the whole scope unknown, so the
+ * guard never blocks on a partial (and therefore misleading) view.
+ */
+export function resolveScopeToPathspecs(scope, cwd) {
+    if (!scope || !scope.trim()) {
+        return { kind: 'unknown', reason: 'no scope provided' };
+    }
+    const tokens = scope.split(',').map((t) => t.trim()).filter(Boolean);
+    if (tokens.length === 0) {
+        return { kind: 'unknown', reason: 'empty scope' };
+    }
+    const pathspecs = [];
+    for (const token of tokens) {
+        if (ENTITY_ID_RE.test(token) || /^review-loop:/i.test(token)) {
+            return { kind: 'unknown', reason: `token "${token}" is an entity id, not a path` };
+        }
+        if (/\s/.test(token)) {
+            return { kind: 'unknown', reason: `token "${token}" contains whitespace (prose, not a path)` };
+        }
+        const normalized = token.replace(/\\/g, '/').replace(/^\.\//, '');
+        if (/[*?[\]]/.test(normalized)) {
+            // Delegate the rare real glob to git's native pathspec matcher.
+            pathspecs.push(`:(glob)${normalized}`);
+            continue;
+        }
+        const exists = fs.existsSync(path.resolve(cwd, normalized));
+        const topLevel = normalized.split('/')[0];
+        if (exists || KNOWN_TOP_LEVEL.has(topLevel)) {
+            pathspecs.push(normalized);
+            continue;
+        }
+        return {
+            kind: 'unknown',
+            reason: `token "${token}" is not a resolvable path (no such file/dir and not a known top-level)`,
+        };
+    }
+    return { kind: 'pathspecs', pathspecs };
+}
+/** Cap a file list for human-readable messages. */
+function summariseFiles(files, max = 10) {
+    if (files.length <= max)
+        return files.join(', ');
+    return `${files.slice(0, max).join(', ')} (and ${files.length - max} more)`;
+}
+/**
+ * Decide whether a dispatch may proceed given the source repo's dirty state and
+ * the dispatch scope. See the module header for the cardinal rule.
+ */
+export function assessDirtyDispatchGuard(input) {
+    const runGit = input.runGit ?? defaultRunGit;
+    const resolution = resolveScopeToPathspecs(input.scope, input.cwd);
+    // 1. Global probe — is the tree dirty at all (ignoring the coordination store)?
+    const global = runGit(input.cwd, ['status', '--porcelain=v1', '-z', '--untracked-files=normal']);
+    if (!global.ok) {
+        return {
+            decision: 'allow',
+            reason: 'source cwd is not a git repo (or git is unavailable) — dirty guard skipped',
+            dirtyCount: 0,
+            overlapping: [],
+            ignoredSystemDirty: [],
+            scopeResolution: resolution.kind,
+        };
+    }
+    const allPaths = parsePorcelainZ(global.stdout);
+    const ignoredSystemDirty = allPaths.filter(isSystemDirtyPath);
+    const realDirty = allPaths.filter((p) => !isSystemDirtyPath(p));
+    if (realDirty.length === 0) {
+        return {
+            decision: 'allow',
+            reason: ignoredSystemDirty.length > 0
+                ? `working tree clean apart from ${ignoredSystemDirty.length} coordination-store file(s) (.brainclaw/, .git/) which the worker rebuilds itself`
+                : 'working tree clean',
+            dirtyCount: 0,
+            overlapping: [],
+            ignoredSystemDirty,
+            scopeResolution: resolution.kind,
+        };
+    }
+    // 2. Explicit ref → the worktree is built from that ref (the dispatch path
+    //    forces resetExistingWorktreeBranch so a pre-existing branch is reset to
+    //    the ref, not silently reused), so uncommitted working-tree changes are
+    //    intentionally out of scope. Only bypass when the ref actually resolves —
+    //    a bogus/unresolvable ref must NOT widen the allow; fall through to the
+    //    scope-aware check below so a dirty in-scope file still blocks.
+    if (input.checkoutRef) {
+        const refResolves = runGit(input.cwd, ['rev-parse', '--verify', '--quiet', `${input.checkoutRef}^{commit}`]).ok;
+        if (refResolves) {
+            return {
+                decision: 'allow',
+                reason: `dispatch builds its worktree from explicit ref "${input.checkoutRef}"; ${realDirty.length} uncommitted working-tree file(s) are intentionally out of scope`,
+                dirtyCount: realDirty.length,
+                overlapping: [],
+                ignoredSystemDirty,
+                scopeResolution: resolution.kind,
+            };
+        }
+        // else: ref does not resolve → continue to the scope-aware evaluation.
+    }
+    // 3. Scope-aware intersection (delegated to git for glob + segment-boundary correctness).
+    if (resolution.kind === 'pathspecs') {
+        const scoped = runGit(input.cwd, [
+            'status', '--porcelain=v1', '-z', '--untracked-files=normal',
+            '--', ...resolution.pathspecs, ':(exclude).brainclaw/', ':(exclude).git/',
+        ]);
+        // If the scoped probe fails for any reason, fall back conservatively:
+        // treat the whole real-dirty set as potentially overlapping.
+        const overlapping = scoped.ok ? parsePorcelainZ(scoped.stdout).filter((p) => !isSystemDirtyPath(p)) : realDirty;
+        if (overlapping.length === 0) {
+            return {
+                decision: 'allow',
+                reason: `${realDirty.length} uncommitted file(s) but none overlap the dispatch scope`,
+                dirtyCount: realDirty.length,
+                overlapping: [],
+                ignoredSystemDirty,
+                scopeResolution: resolution.kind,
+            };
+        }
+        if (input.allowDirty) {
+            return {
+                decision: 'warn',
+                reason: `allow_dirty=true: proceeding despite ${overlapping.length} dirty file(s) overlapping the dispatch scope: ${summariseFiles(overlapping)}`,
+                dirtyCount: realDirty.length,
+                overlapping,
+                ignoredSystemDirty,
+                scopeResolution: resolution.kind,
+            };
+        }
+        return {
+            decision: 'block',
+            reason: `${overlapping.length} uncommitted file(s) overlap the dispatch scope and the worker spawns from HEAD, so it will not see them: ${summariseFiles(overlapping)}. Commit or stash these, or pass allow_dirty=true to override.`,
+            dirtyCount: realDirty.length,
+            overlapping,
+            ignoredSystemDirty,
+            scopeResolution: resolution.kind,
+        };
+    }
+    // 4. Scope not resolvable to paths → cannot prove disjointness → conservative.
+    if (input.allowDirty) {
+        return {
+            decision: 'warn',
+            reason: `allow_dirty=true: proceeding despite ${realDirty.length} uncommitted file(s); dispatch scope is not resolvable to paths (${resolution.reason}) so overlap could not be ruled out`,
+            dirtyCount: realDirty.length,
+            overlapping: [],
+            ignoredSystemDirty,
+            scopeResolution: resolution.kind,
+        };
+    }
+    return {
+        decision: 'block',
+        reason: `${realDirty.length} uncommitted file(s) and the dispatch scope is not resolvable to file paths (${resolution.reason}), so overlap cannot be ruled out; the worker spawns from HEAD and will not see them: ${summariseFiles(realDirty)}. Commit or stash, pass a resolvable file scope, or pass allow_dirty=true to override.`,
+        dirtyCount: realDirty.length,
+        overlapping: [],
+        ignoredSystemDirty,
+        scopeResolution: resolution.kind,
+    };
+}
+//# sourceMappingURL=dirty-scope.js.map

package/dist/core/facade-schema.js

@@ -64,7 +64,23 @@ export const CoordinateRequestSchema = z.object({
      * dispatched work doesn't depend on the dirty files, or when running
      * tests). Has no effect when the source cwd is not a git repo.
      */
-    allow_dirty: z.boolean().optional(),
+    allow_dirty: z.preprocess(
+    // MCP clients that don't know allow_dirty is a boolean (it was previously
+    // absent from the published inputSchema) send the string "true"/"false".
+    // Coerce those so the documented escape hatch actually works; leave real
+    // booleans and undefined untouched.
+    (value) => (typeof value === 'string' ? value.trim().toLowerCase() === 'true' : value), z.boolean().optional()),
+    /**
+     * pln#520 Tier 2 (P2c) — explicit git ref (commit / branch / tag) the
+     * dispatched worker should build its worktree from, instead of the default
+     * HEAD. When set on a worktree-creating intent (assign / review / reroute),
+     * the worktree is checked out at this ref, so uncommitted working-tree
+     * changes in the source are intentionally out of scope and the scope-aware
+     * dirty guard allows the dispatch. Passed through to
+     * createCoordinatorClaim's worktreeBaseRef. Ignored by intents that don't
+     * create a worktree (consult / ideate / summarize).
+     */
+    ref: z.string().min(1).optional(),
     /**
      * pln#511 step 2 — loop preset selector. When set on intent='ideate',
      * the handler bypasses the kind-default ideation phases and opens the

package/dist/core/identity.js

@@ -2,6 +2,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { detectAiAgent } from './ai-agent-detection.js';
 import { requireRegisteredAgentIdentity } from './agent-registry.js';
 import { loadConfig } from './config.js';
 import { resolveCurrentHostId } from './host.js';
@@ -75,31 +76,42 @@ export function loadCurrentSession(cwd) {
     const dir = sessionsDir(cwd);
     const currentUser = resolveCurrentUser();
     const currentAgent = resolveCurrentAgentName();
-    // 1. Look in sessions/ directory for a matching session
+    const explicitSessionId = resolveExplicitSessionId();
+    const ttlMs = parseDurationToMs(loadConfigSafe(cwd)?.implicit_session_ttl ?? '4h');
+    const now = Date.now();
+    if (explicitSessionId) {
+        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 ttlMs = parseDurationToMs(loadConfigSafe(cwd)?.implicit_session_ttl ?? '4h');
-        const now = Date.now();
+        const legacyPidlessCandidates = [];
         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,
-                };
+                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;
-                const alive = (now - Date.parse(session.last_seen_at)) <= ttlMs;
-                if (userMatch && alive) {
+                if (!userMatch || !isSessionAlive(session, ttlMs, now))
+                    continue;
+                if (session.pid === process.pid) {
                     return session;
                 }
+                if (session.pid === undefined) {
+                    legacyPidlessCandidates.push(session);
+                }
             }
             catch {
                 // skip invalid session files
             }
         }
+        if (legacyPidlessCandidates.length === 1) {
+            return legacyPidlessCandidates[0];
+        }
     }
     // 2. Legacy fallback: .current-session
     const legacyPath = path.join(memoryDir(cwd), LEGACY_SESSION_FILE);
@@ -246,9 +258,24 @@ function resolveCurrentUser() {
 function resolveCurrentAgentName() {
     if (process.env.BRAINCLAW_AGENT_NAME)
         return process.env.BRAINCLAW_AGENT_NAME;
-    if (process.env.CLAUDE_CODE_VERSION)
-        return 'claude-code';
-    return undefined;
+    return detectAiAgent()?.name;
+}
+function resolveExplicitSessionId(env = process.env) {
+    return env.BRAINCLAW_SESSION_ID?.trim()
+        || env.OPENCLAW_SESSION_ID?.trim()
+        || env.CLAUDE_SESSION_ID?.trim()
+        || env.COPILOT_SESSION_ID?.trim()
+        || undefined;
+}
+function loadSessionFile(filepath) {
+    const migration = loadVersionedJsonFile('current_session', filepath);
+    return {
+        ...CurrentSessionStateSchema.parse(migration.document),
+        schema_version: migration.metadata.currentVersion,
+    };
+}
+function isSessionAlive(session, ttlMs, now) {
+    return now - Date.parse(session.last_seen_at) <= ttlMs;
 }
 function loadConfigSafe(cwd) {
     try {

package/dist/core/schema.js

@@ -1166,6 +1166,8 @@ export const AgentIntegrationNameSchema = z.enum([
     'continue',
     'roo',
     'kilocode',
+    'mistral-vibe',
+    'hermes',
     'openclaw',
     'nanoclaw',
     'nemoclaw',

package/dist/core/worktree.js

@@ -94,6 +94,64 @@ export function hasGitLock(cwd) {
     const lockPath = path.join(gitDir.stdout.trim(), 'index.lock');
     return fs.existsSync(lockPath);
 }
+/**
+ * Re-points an EXISTING worktree to `ref` via a hard reset of its checked-out
+ * branch + working tree. Used when a dispatch reuses an existing claim/worktree
+ * but pins a base ref: the worktree must reflect that ref, not stale state,
+ * otherwise the dirty-guard ref bypass would let the worker run on stale code
+ * (pln#520 Tier 2 / codex r2). Returns ok=false (with stderr) rather than
+ * throwing, so callers surface a visible warning instead of a hard failure.
+ */
+export function resetWorktreeToRef(worktreePath, ref) {
+    if (!fs.existsSync(worktreePath)) {
+        return { ok: false, stderr: `worktree path does not exist: ${worktreePath}` };
+    }
+    if (hasGitLock(worktreePath)) {
+        return { ok: false, stderr: 'git index.lock present — another git operation is in progress' };
+    }
+    const res = runGit(['reset', '--hard', ref], worktreePath);
+    if (!res.ok) {
+        return { ok: false, stderr: res.stderr };
+    }
+    // `reset --hard` realigns HEAD + tracked files, but leaves UNTRACKED residue
+    // from a prior use of the worktree — files the worker could still compile or
+    // test against even though they don't exist at the pinned ref (codex r3).
+    // We do NOT auto-delete (a blind `git clean` would also remove the brainclaw
+    // sidecar and gitignored shared symlinks); instead we detect non-system
+    // untracked files and report them so the caller surfaces a visible warning
+    // rather than letting the stale state pass silently. Ignored files (e.g.
+    // node_modules) are not listed by --untracked-files=normal, so the symlinked
+    // shared paths are unaffected.
+    const status = runGit(['status', '--porcelain=v1', '-z', '--untracked-files=normal'], worktreePath);
+    if (!status.ok) {
+        // The reset succeeded but we cannot confirm the worktree is residue-free -
+        // surface it rather than silently reporting a clean reset (cardinal rule).
+        return {
+            ok: false,
+            stderr: `reset to ${ref} succeeded but the untracked-residue check (git status) failed: ${status.stderr.trim()}`,
+        };
+    }
+    if (status.stdout.length > 0) {
+        const residue = status.stdout
+            .split('\0')
+            .filter((entry) => entry.startsWith('?? '))
+            .map((entry) => entry.slice(3))
+            .filter((p) => {
+            const norm = p.replace(/\\/g, '/');
+            return norm !== '.brainclaw-worktree.json'
+                && !norm.startsWith('.brainclaw/')
+                && !norm.startsWith('.git/');
+        });
+        if (residue.length > 0) {
+            const sample = residue.slice(0, 5).join(', ');
+            return {
+                ok: false,
+                stderr: `reset to ${ref} succeeded but ${residue.length} untracked file(s) remain from prior worktree use (e.g. ${sample}) — the worker may see state absent at the ref. Remove them or dispatch with a fresh scope.`,
+            };
+        }
+    }
+    return { ok: true, stderr: '' };
+}
 /**
  * Detects whether multiple distinct brainclaw sessions are using the same
  * physical worktree directory (shared-checkout risk).