brainclaw 1.26.0 → 1.26.2

package/README.md

@@ -46,7 +46,7 @@ It sits alongside your coding agents and gives them a shared state layer they ca
 | **Agent-ready context**          | compact, prompt-sized context built from real workspace state instead of stale instructions                                                                                                         |
 | **Code Map**                     | a Tree-sitter symbol + import index (11 languages — JS/TS, Python, PHP, Java, Go, Rust, C#, Ruby, C, C++) so agents ask "where is X / what should I read first" before editing, with related decisions/traps attached — `bclaw_code_find` / `bclaw_code_brief`, see [code map](docs/code-map.md) |
 | **Native agent files**           | auto-writes `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursor/rules/`, `.windsurfrules`, and similar local guidance                                                                         |
-| **Multi-turn loops**             | review and ideation loops with structured phases, iteration semantics, and per-phase memory filters — see[loop engine](docs/concepts/loop-engine.md) and [ideation loop](docs/concepts/ideation-loop.md) |
+| **Multi-turn loops**             | review, ideation, implementation, research, and debug workflows with structured phases, iteration semantics, verification gates, and per-phase memory filters — see [loop engine](docs/concepts/loop-engine.md) |
 | **Machine AI surface discovery** | detects local coding agents plus desktop AI work surfaces such as ChatGPT Desktop and Gemini CLI                                                                                                    |
 | **Queued surface tasks**         | stores project-scoped requests for other local AI surfaces, such as visual generation, drafting, summaries, or research                                                                             |
 | **Local-first storage**          | plain text + JSON, Git-friendly, no mandatory cloud, no telemetry by default                                                                                                                        |
@@ -263,14 +263,29 @@ bclaw_loop({ intent: "get", loop_id: "lop_abc" }); // inspect status any time
 
 ## The Loop Engine (Multi-Turn Workflows)
 
-Brainclaw's Loop Engine moves beyond manual ping-pong by formalizing multi-turn workflows (review, ideation, testing). It features two distinct review modes:
-
-- **Asymmetric Mode**: The classic author→reviewer handoff. The reviewer creates findings, and the original author must apply the fixes.
-- **Symmetric Mode**: Eliminates unnecessary round-trips. Both the author and reviewer slots can apply fixes directly, drastically speeding up spec and documentation reviews.
-
-Each loop maintains a structured lifecycle, explicit phases, iteration bounds, and per-phase memory filters, executed seamlessly via `bclaw_loop`.
-
-**Autonomous convergence (pln#628 Focus 4B + pln#630):** a dispatched reviewer doesn't need to be driven by hand. It writes its verdict (`review_verdict: approve | request_changes`) into its `LANE-RESULT.json`; when the coordinator harvests the lane, brainclaw records the verdict on the loop and **auto-closes it on approve** — the review loop reaches `reviewer_green` with no human ping-pong. On `request_changes`, brainclaw **runs the fix→re-review cycle autonomously**: it bumps the round, retains the worktree, and re-dispatches — through an exactly-once turn-attempt state machine (immutable attempt records behind an atomic launch fence, on by default; kill-switch `BRAINCLAW_TURN_OWNED_REVIEW=0`) so a turn is never double-spawned, with a bounded round cap that lands on `blocked` instead of looping forever.
+Brainclaw's Loop Engine formalizes repeated multi-turn work so agents can
+resume, automate, and audit it rather than relying on manual ping-pong. It is
+one engine with five shipped default workflows: **review, ideation,
+implementation, research, and debug**.
+
+| Workflow | Typical outcome | Normal entry point |
+| --- | --- | --- |
+| Review | accepted verdict or bounded fix cycle | `bclaw_coordinate(intent="review", open_loop=true)` |
+| Ideation | memory-confronted plan draft or synthesis | `bclaw_coordinate(intent="ideate")` |
+| Implementation | green verification and handoff | `bclaw_loop(intent="open", kind="implementation", allow_orphan=true)`, then `bind` |
+| Research | evidence-backed synthesis | `bclaw_loop(intent="open", kind="research", allow_orphan=true)` |
+| Debug | reproduced, verified fix and handoff | `bclaw_loop(intent="open", kind="debug", allow_orphan=true)` |
+
+Every loop has structured phases, bounded iteration, explicit artifacts, and
+per-phase memory filters. The shared controls are `open`, `turn`,
+`complete_turn`, `advance`, `add_artifact`, `pause`, `resume`, and `close`;
+implementation also adds `bind` and `verify`. `request_input` /
+`provide_input` are cross-cutting clarification primitives for any workflow.
+
+Review is a useful specialized path, not the definition of the engine. It has
+asymmetric and symmetric modes and can auto-close on an approved verdict; the
+other workflows use the same lifecycle to converge on a plan, synthesis,
+handoff, or verified fix. See the [Loop Engine guide](docs/concepts/loop-engine.md).
 
 ## Enterprise Ready: Mono-repo & Micro-services
 
@@ -310,7 +325,7 @@ Recent releases have moved a lot of multi-agent parallel work from "risky" to "s
 
 - **Per-claim auto-worktree** — each dispatched lane gets its own isolated git worktree; the coordinator integrates with an octopus merge.
 - **Sequenced parallel execute** — `bclaw_dispatch(intent="execute")` fans out independent lanes across several agent instances and integrates the result.
-- **Symmetric review-fix loops** — `bclaw_coordinate(intent="review", open_loop=true, review_mode="symmetric")` runs an alternating review-and-fix conversation across two slots without shared-checkout collisions. The reviewer's verdict is harvested from `LANE-RESULT.json` and the loop **auto-closes on approve** — no manual round-trip to converge the approve path.
+- **Loop Engine protocols** — review, ideation, implementation, research, and debug workflows share a persisted lifecycle. Review offers a symmetric auto-fix shortcut; implementation and debug bind verification to the work; ideation and research converge on durable syntheses.
 - **Cross-platform spawn** — OS-aware prompt delivery (stdin pipe / inline arg) plus a brief-ack file handshake, so spawned workers can be detected and timed out reliably on Windows and Unix.
 - **Worktree GC is scope-bounded** — symlinks and junctions are no longer followed during cleanup, so post-merge sweeps can't wipe `node_modules` or other neighboring directories.
 - **MCP runtime self-heal** — when the runtime is corrupted, the server logs an actionable repair pointer; `brainclaw doctor --repair` rebuilds dist in one step.
@@ -327,8 +342,9 @@ Recommended use today:
 
 1. for parallel work, dispatch a sequence with `bclaw_dispatch(intent="execute")` — each lane gets its own worktree
 2. for sequential work in the same project, let one agent claim at a time and rely on handoffs
-3. when reviewing or fixing across agents, prefer symmetric review loops over manual ping-pong
-4. keep multi-machine workflows on a single source of truth until federation lands
+3. choose the loop by outcome: ideation for a plan, implementation or debug for a verified handoff, research for a synthesis, and review for a verdict
+4. when reviewing or fixing across agents, prefer symmetric review loops over manual ping-pong
+5. keep multi-machine workflows on a single source of truth until federation lands
 
 ---
 

package/dist/commands/session-start.js

@@ -2,9 +2,9 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
-import { isSessionSnapshotRecordFilename, memoryExists, resolveEntityDir, sessionSnapshotRecordPaths } from '../core/io.js';
+import { assertSafeSessionId, isSessionSnapshotRecordFilename, memoryExists, resolveEntityDir, sessionSnapshotRecordPaths } from '../core/io.js';
 import { loadVersionedJsonFile, saveVersionedJsonFile } from '../core/migration.js';
-import { buildOperationalIdentity, loadAllSessions, saveCurrentSession } from '../core/identity.js';
+import { buildOperationalIdentity, describeIgnoredSessionIdEnv, loadAllSessions, saveCurrentSession } from '../core/identity.js';
 import { requireMinimumTrustLevel, resolveCurrentModel, resolveOrAutoRegisterAgentIdentity } from '../core/agent-registry.js';
 import { buildContext, renderContextPromptTemplate } from '../core/context.js';
 import { writeContextMarker } from '../core/freshness.js';
@@ -35,8 +35,39 @@ function sessionSnapshotWriteDir(cwd) {
     return resolveEntityDir('sessions', cwd ?? process.cwd(), 'write');
 }
 function sessionSnapshotPath(sessionId, cwd) {
+    // pln#672 review P1 — THE SECOND WRITER. This builder was unguarded while
+    // sessionFilePathIn / sessionSnapshotRecordPaths were hardened, so an
+    // env-controlled traversal still escaped the store HERE, before the
+    // current_session write refused it (reproduced by the reviewer:
+    // `ESCAPED.snapshot.json` landed outside, and the later throw did not undo
+    // the escaped write). A guard on some builders is not a guard.
+    assertSafeSessionId(sessionId);
     return path.join(sessionSnapshotWriteDir(cwd), `${sessionId}.snapshot.json`);
 }
+/**
+ * pln#672 review P2 — the snapshot write needs the same positive proof the
+ * current_session write already has. On a case-insensitive filesystem
+ * `CaseSnapshot` and `casesnapshot` name the SAME file, so a second session
+ * silently overwrote the first one's snapshot. Refuse to replace a record
+ * that names a different session; identical-id rewrites (heartbeat, restart)
+ * stay allowed.
+ */
+function assertSnapshotSlotFree(filepath, sessionId) {
+    if (!fs.existsSync(filepath))
+        return;
+    try {
+        const raw = JSON.parse(fs.readFileSync(filepath, 'utf-8'));
+        if (typeof raw.session_id === 'string' && raw.session_id !== sessionId) {
+            throw new Error(`Refusing to overwrite the session_snapshot of '${raw.session_id}' at '${filepath}' with '${sessionId}' — the two ids resolve to the same filename on this filesystem`);
+        }
+    }
+    catch (err) {
+        // A deliberate refusal propagates; an unreadable record does not block a
+        // fresh write (it is not proof that another session owns the slot).
+        if (err instanceof Error && err.message.startsWith('Refusing to overwrite'))
+            throw err;
+    }
+}
 /**
  * pln#670 — lazy migration of pre-split snapshot records: rename `<id>.json` to
  * `<id>.snapshot.json` in the CANONICAL sessions directory only. The legacy
@@ -145,6 +176,11 @@ export async function runSessionStart(options = {}) {
         if (snapshot.stale_surfaces) {
             console.warn(`⚠ ${snapshot.stale_surfaces.message}`);
         }
+        // pln#672 — a dropped env session id must reach the human too: the whole
+        // point of the warning is that the session identity is NOT the one asked for.
+        if (snapshot.invalid_session_id_ignored) {
+            console.warn(`⚠ ${snapshot.invalid_session_id_ignored.message}`);
+        }
         // Fifth instance of the computed-then-dropped class, caught by the new seam
         // guard on its first run: built since the shared-checkout detection landed,
         // read by nothing. Two agents editing one checkout is precisely what a human
@@ -202,7 +238,9 @@ export async function startSession(options = {}) {
     const dir = sessionSnapshotWriteDir(options.cwd);
     if (!fs.existsSync(dir))
         fs.mkdirSync(dir, { recursive: true });
-    saveVersionedJsonFile('session_snapshot', sessionSnapshotPath(snapshot.session_id, options.cwd), SessionSnapshotSchema.parse(snapshot));
+    const snapshotPath = sessionSnapshotPath(snapshot.session_id, options.cwd);
+    assertSnapshotSlotFree(snapshotPath, snapshot.session_id);
+    saveVersionedJsonFile('session_snapshot', snapshotPath, SessionSnapshotSchema.parse(snapshot));
     // Resolve git branch and worktree for session tracking
     let currentBranch;
     let currentWorktreePath;
@@ -371,6 +409,18 @@ export async function startSession(options = {}) {
         staleSurfaces = staleSurfaceWarning(freshness, currentVersion);
     }
     catch { /* non-fatal */ }
+    // pln#672 — report a DROPPED env session id. Never echo the raw value: it is
+    // attacker-influenced and would land straight in logs; the variable name and
+    // its length are enough to diagnose.
+    let invalidSessionIdIgnored;
+    const droppedSessionEnv = describeIgnoredSessionIdEnv();
+    if (droppedSessionEnv) {
+        invalidSessionIdIgnored = {
+            code: 'invalid_session_id_ignored',
+            message: `${droppedSessionEnv.variable} carries a session id that cannot be a record filename (${droppedSessionEnv.length} chars) — it was ignored and this session runs under '${snapshot.session_id}'. Unset or fix the variable to resume the intended session.`,
+            data: { variable: droppedSessionEnv.variable, length: droppedSessionEnv.length, effective_session_id: snapshot.session_id },
+        };
+    }
     // Materialize incoming federation signals from linked projects (Phase 0 — local)
     if (maintenanceMode === 'full') {
         try {
@@ -406,6 +456,7 @@ export async function startSession(options = {}) {
         ...(staleClaimsReleased ? { stale_claims_released: staleClaimsReleased } : {}),
         ...(memoryPressure ? { memory_pressure: memoryPressure } : {}),
         ...(staleSurfaces ? { stale_surfaces: toWarningDetail(staleSurfaces) } : {}),
+        ...(invalidSessionIdIgnored ? { invalid_session_id_ignored: toWarningDetail(invalidSessionIdIgnored) } : {}),
         ...(autoRegistered ? { auto_registered: true } : {}),
     };
 }

package/dist/core/agent-files.js

@@ -3,7 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import yaml from 'yaml';
-import { MCP_HEADLESS_AUTO_TOOL_NAMES, MCP_CANONICAL_GRAMMAR_TOOL_NAMES, REMOVED_IN_V1_TOOLS } from './protocol-tool-policy.js';
+import { MCP_HEADLESS_AUTO_TOOL_NAMES, MCP_CANONICAL_GRAMMAR_TOOL_NAMES, MCP_HERMES_WORKFLOW_TOOL_NAMES, REMOVED_IN_V1_TOOLS } from './protocol-tool-policy.js';
 import { renderToml, tomlArrayTableHasEntry } from './toml-writer.js';
 import { PROTOCOL_SKILLS, renderProtocolSkill } from './protocol-skills.js';
 import { getInstalledBrainclawVersion } from './brainclaw-version.js';
@@ -364,7 +364,6 @@ export const LOCAL_ONLY_AGENT_WORKSPACE_FILES = [
     KILOCODE_MCP_RELATIVE_PATH,
     KILOCODE_CONFIG_RELATIVE_PATH,
     MISTRAL_VIBE_CONFIG_RELATIVE_PATH,
-    HERMES_CONFIG_RELATIVE_PATH,
     CONTINUE_CONFIG_RELATIVE_PATH,
     OPENCODE_CONFIG_RELATIVE_PATH,
     WINDSURF_MCP_RELATIVE_PATH,
@@ -1553,25 +1552,22 @@ export function ensureMistralVibeMcpConfig(cwd) {
         relativePath: MISTRAL_VIBE_CONFIG_RELATIVE_PATH,
     };
 }
-// Hermes' MCP `tools.include` array — narrow canonical-grammar surface. Derived
-// from MCP_CANONICAL_GRAMMAR_TOOL_NAMES (which is itself ALL_TOOLS-derived) so
-// new facade tools or canonical grammar verbs propagate without a manual edit
-// here (pln#546 step 2). REMOVED_IN_V1_TOOLS are stripped so deprecated names
-// don't reappear in user-facing configs.
-//
-// LAZY (pln#564 coordinator fix): computed on first call, NOT at module init.
-// agent-files.ts ↔ commands/mcp.ts form an import cycle; reading the imported
-// MCP_CANONICAL_GRAMMAR_TOOL_NAMES at module-eval time threw a TDZ
-// ("Cannot access 'MCP_CANONICAL_GRAMMAR_TOOL_NAMES' before initialization")
-// when agent-files loaded mid-mcp-init — which broke the MCP server. tsc does
-// not catch this (runtime-only). Deferring the read to call time fixes it.
-let hermesBrainclawMcpToolsCache;
 function getHermesBrainclawMcpTools() {
-    if (!hermesBrainclawMcpToolsCache) {
-        hermesBrainclawMcpToolsCache = MCP_CANONICAL_GRAMMAR_TOOL_NAMES
-            .filter((name) => !REMOVED_IN_V1_TOOLS.has(name));
-    }
-    return hermesBrainclawMcpToolsCache;
+    return MCP_HERMES_WORKFLOW_TOOL_NAMES
+        .filter((name) => !REMOVED_IN_V1_TOOLS.has(name));
+}
+function hasExactMcpToolList(value, expected) {
+    return Array.isArray(value)
+        && value.length === expected.length
+        && value.every((tool, index) => tool === expected[index]);
+}
+function isLegacyHermesBrainclawMcpTools(value) {
+    // The original Hermes writer emitted precisely the canonical seven-tool
+    // list. Upgrade that known managed value, but preserve every other list as
+    // an explicit user customization.
+    const legacyTools = MCP_CANONICAL_GRAMMAR_TOOL_NAMES
+        .filter((name) => !REMOVED_IN_V1_TOOLS.has(name));
+    return hasExactMcpToolList(value, legacyTools);
 }
 export function ensureHermesMcpConfig(homeDir, workspacePath) {
     if (!homeDir)
@@ -1617,6 +1613,8 @@ export function ensureHermesMcpConfig(homeDir, workspacePath) {
         }
     }
     const mcpCmd = getBrainclawMcpCommand();
+    const existingInclude = currentTools.include;
+    const managedInclude = getHermesBrainclawMcpTools();
     const desiredEntry = {
         ...current,
         command: typeof current.command === 'string' ? current.command : mcpCmd.command,
@@ -1627,7 +1625,9 @@ export function ensureHermesMcpConfig(homeDir, workspacePath) {
         },
         tools: {
             ...currentTools,
-            include: Array.isArray(currentTools.include) ? currentTools.include : getHermesBrainclawMcpTools(),
+            include: Array.isArray(existingInclude) && !isLegacyHermesBrainclawMcpTools(existingInclude)
+                ? existingInclude
+                : managedInclude,
             prompts: typeof currentTools.prompts === 'boolean' ? currentTools.prompts : false,
             resources: typeof currentTools.resources === 'boolean' ? currentTools.resources : false,
         },