@kinqs/brainrouter-cli 0.3.5 → 0.3.6

package/dist/state/workflowArtifacts.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { getCliStateFile, getWorkspaceLocalDir, isPathInside, readJsonFile, writeJsonFile } from './cliState.js';
+import { getCliStateFile, getSessionStateFile, getWorkspaceLocalDir, isPathInside, readJsonFile, writeJsonFile } from './cliState.js';
 /**
  * Canonical home for durable workflow artifacts produced by the multi-agent
  * commands (/feature-dev, /spec, /review, /implement-plan).
@@ -18,12 +18,42 @@ import { getCliStateFile, getWorkspaceLocalDir, isPathInside, readJsonFile, writ
  * team shares them, and (b) the agent's `write_file` tool only accepts paths
  * relative to the workspace root. Personal CLI state (sessions, hooks,
  * memories, preferences) lives in `~/.brainrouter/workspaces/<encoded>/` and
- * never touches the project tree. The current-workflow pointer is still per-
- * user (it tracks which workflow YOU are focused on right now) so it lives
- * with the CLI state, not the workspace.
+ * never touches the project tree.
+ *
+ * **Workflows do NOT carry goal state.** Earlier 0.3.6 (Item 3) stored a
+ * `goal.json` inside each workflow folder so switching workflows would
+ * "carry the goal with it." That conflated two different concerns — a goal
+ * is **per-session runtime intent** (let the agent run autonomously until
+ * complete) while a workflow is **durable storage** (committed artifacts
+ * shared across users and CLIs). The conflation produced a cross-session
+ * goal leak (two CLIs in the same workspace bound to the same workflow
+ * shared a goal). The decoupling lives in goalStore.ts's `resolveGoalScope`
+ * — goals are always session-scoped, workflows are pure navigation. The
+ * per-session `workflow.json` pointer here is for "which folder am I
+ * writing artifacts to RIGHT NOW", not "which goal am I working on."
  */
 const WORKFLOWS_SUBDIR = 'workflows';
+/**
+ * Workspace-level "last used workflow" pointer. Pre-9d-bugfix this was
+ * BOTH the source of truth for "which workflow is the current CLI
+ * session bound to" AND the display-only "what was the last workflow
+ * touched in this workspace" hint. The two responsibilities are now
+ * split: this file is the hint (any CLI in this workspace can see it),
+ * while `SESSION_POINTER_FILE` carries the per-session binding that
+ * actually drives goal scoping. The hint is still useful for the
+ * `/workflows` listing and for surfacing "you were last on X" in a
+ * fresh CLI without auto-binding it to that workflow's goal.
+ */
 const CURRENT_POINTER_FILE = 'current-workflow.json';
+/**
+ * Per-session workflow binding (the actual source of truth for goal
+ * scoping). Lives under the session state directory so two CLIs in the
+ * same workspace can have independent workflows bound — fixes the
+ * "session A's `/feature-dev` automatically becomes session B's active
+ * workflow + active goal" leak that reintroduced Item 1's cross-session
+ * leak via the Item 3 workspace pointer.
+ */
+const SESSION_POINTER_FILE = 'workflow.json';
 /** Canonical artifact names. Use the constants rather than hard-coded strings so a future rename is one edit. */
 export const ARTIFACT = {
     spec: 'spec.md',
@@ -58,6 +88,16 @@ export function getWorkflowDir(workspaceRoot, slug) {
     fs.mkdirSync(dir, { recursive: true });
     return dir;
 }
+/**
+ * Create (or reopen) a workflow folder + bind it as the current
+ * workflow.
+ *
+ * `sessionKey` is threaded through to `setCurrentWorkflow` so that the
+ * created workflow is bound to THIS session (not to every other CLI
+ * session in the workspace via the workspace-level pointer). Legacy
+ * callers without a session context fall through to workspace-level
+ * binding only — same back-compat path `setCurrentWorkflow` provides.
+ */
 export function createWorkflow(workspaceRoot, input) {
     const slug = slugify(input.slug ?? input.title);
     const dir = getWorkflowDir(workspaceRoot, slug);
@@ -81,7 +121,7 @@ export function createWorkflow(workspaceRoot, input) {
             meta.kind = input.kind;
     }
     writeJsonFile(metaPath, meta);
-    setCurrentWorkflow(workspaceRoot, slug);
+    setCurrentWorkflow(workspaceRoot, slug, input.sessionKey);
     return meta;
 }
 export function updateWorkflowStatus(workspaceRoot, slug, status) {
@@ -111,13 +151,85 @@ export function listWorkflows(workspaceRoot) {
     }
     return out.sort((a, b) => (b.updatedAt ?? '').localeCompare(a.updatedAt ?? ''));
 }
-export function setCurrentWorkflow(workspaceRoot, slug) {
-    writeJsonFile(getCliStateFile(workspaceRoot, CURRENT_POINTER_FILE), { slug, at: new Date().toISOString() });
+/**
+ * Bind a workflow to the current CLI session AND update the workspace-
+ * level "last used" hint. When `sessionKey` is omitted (legacy callers,
+ * some first-run paths), only the workspace pointer is written — those
+ * callers don't have a session context yet, so per-session binding
+ * doesn't apply.
+ *
+ * The workspace pointer is updated unconditionally because we still
+ * want a fresh CLI in the same workspace to be ABLE to see "X is the
+ * last workflow that was touched here" — for display via
+ * `getLastUsedWorkflow`, for the `/workflows` listing's `★` marker, and
+ * for the post-9d "do you want to switch to <X>?" UX (the latter not
+ * yet shipped, tracked separately).
+ */
+export function setCurrentWorkflow(workspaceRoot, slug, sessionKey) {
+    const ts = new Date().toISOString();
+    writeJsonFile(getCliStateFile(workspaceRoot, CURRENT_POINTER_FILE), { slug, at: ts });
+    if (sessionKey) {
+        writeJsonFile(getSessionStateFile(workspaceRoot, sessionKey, SESSION_POINTER_FILE), { slug, at: ts });
+    }
 }
-export function getCurrentWorkflow(workspaceRoot) {
+/**
+ * Which workflow is bound to THIS CLI session?
+ *
+ * - With `sessionKey`: reads ONLY the session-level pointer. A fresh
+ *   CLI session has no session-level pointer → returns `undefined`,
+ *   even when a workspace-level "last used" hint exists. This is the
+ *   load-bearing fix: new sessions don't auto-inherit another session's
+ *   workflow binding (which previously dragged that workflow's goal
+ *   into the new session via `resolveGoalScope`).
+ * - Without `sessionKey` (legacy / display-only callers): falls back
+ *   to the workspace-level pointer for back-compat.
+ *
+ * Display surfaces that want to show "the last workflow touched here,
+ * regardless of session binding" should call `getLastUsedWorkflow`
+ * instead so the distinction stays explicit.
+ */
+export function getCurrentWorkflow(workspaceRoot, sessionKey) {
+    if (sessionKey) {
+        const sessionPtr = readJsonFile(getSessionStateFile(workspaceRoot, sessionKey, SESSION_POINTER_FILE), null);
+        return sessionPtr?.slug || undefined;
+    }
+    const ptr = readJsonFile(getCliStateFile(workspaceRoot, CURRENT_POINTER_FILE), null);
+    return ptr?.slug;
+}
+/**
+ * Display-only "last workflow used in this workspace" lookup. Reads
+ * the workspace-level pointer unconditionally — never consults the
+ * session-level binding. Use when you want to render a hint like
+ * "you were last on workflow X" without implying that the current
+ * session is bound to it.
+ */
+export function getLastUsedWorkflow(workspaceRoot) {
     const ptr = readJsonFile(getCliStateFile(workspaceRoot, CURRENT_POINTER_FILE), null);
     return ptr?.slug;
 }
+/**
+ * Clear the session-level workflow binding (workspace-level hint
+ * preserved). Used by `/new` and `/fork` so a freshly-forked session
+ * doesn't drag the parent's binding along.
+ */
+export function clearSessionWorkflow(workspaceRoot, sessionKey) {
+    const pointerPath = getSessionStateFile(workspaceRoot, sessionKey, SESSION_POINTER_FILE);
+    try {
+        fs.unlinkSync(pointerPath);
+    }
+    catch { /* idempotent — no file to remove is fine */ }
+}
+/**
+ * True iff a workflow folder with the given slug exists (and carries a
+ * meta.json). Used by `/workflow switch <slug>` to surface "no such
+ * workflow" without the side-effect mkdir that `getWorkflowDir` performs.
+ */
+export function workflowExists(workspaceRoot, slug) {
+    const safeSlug = slugify(slug);
+    const root = getWorkflowsRoot(workspaceRoot);
+    const candidate = path.join(root, safeSlug, 'meta.json');
+    return fs.existsSync(candidate);
+}
 /**
  * Path (relative to workspace root) the LLM should `write_file` to for a
  * given artifact. We return a workspace-relative path because that's the

package/dist/tests/_helpers.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared fixtures + harness for the split-up CLI test suites.
+ *
+ * Lives under `src/tests/` alongside the actual `*.test.ts` files. The
+ * leading underscore is convention only — the test runner picks up files by
+ * the `*.test.js` glob, so a non-test filename is enough to keep node:test
+ * from trying to execute this module as a suite.
+ *
+ * Everything here was lifted verbatim out of the original `src/agent.test.ts`
+ * during the split. Don't add new fixtures unless they're used by ≥2 files.
+ */
+import { Agent } from '../agent/agent.js';
+/**
+ * Construct an Agent without touching MCP or the LLM. Only safe for tests
+ * that exercise pure state-machine extensions (model, accessMode, history,
+ * fork, refreshSystemPrompt) — anything that triggers `bootstrapSession`
+ * will hit the stub MCP and either no-op or surface a misleading error.
+ */
+export declare function makeAgent(workspace: string): Agent;
+/**
+ * Run a synchronous test body inside a fresh temp workspace. Restores cwd,
+ * BRAINROUTER_WORKSPACE, and BRAINROUTER_HOME afterwards. BRAINROUTER_HOME
+ * is also pinned to a sibling tmp dir so tests never touch the real
+ * `~/.brainrouter` on the developer's machine.
+ */
+export declare function withTempWorkspace(fn: (workspace: string) => void): void;
+/**
+ * Async sibling of `withTempWorkspace`. Same restore semantics; awaits the
+ * body so promise rejections still tear the workspace down.
+ */
+export declare function withTempWorkspaceAsync<T>(fn: (workspace: string) => Promise<T>): Promise<T>;

package/dist/tests/_helpers.js

@@ -0,0 +1,91 @@
+/**
+ * Shared fixtures + harness for the split-up CLI test suites.
+ *
+ * Lives under `src/tests/` alongside the actual `*.test.ts` files. The
+ * leading underscore is convention only — the test runner picks up files by
+ * the `*.test.js` glob, so a non-test filename is enough to keep node:test
+ * from trying to execute this module as a suite.
+ *
+ * Everything here was lifted verbatim out of the original `src/agent.test.ts`
+ * during the split. Don't add new fixtures unless they're used by ≥2 files.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Agent } from '../agent/agent.js';
+/**
+ * Construct an Agent without touching MCP or the LLM. Only safe for tests
+ * that exercise pure state-machine extensions (model, accessMode, history,
+ * fork, refreshSystemPrompt) — anything that triggers `bootstrapSession`
+ * will hit the stub MCP and either no-op or surface a misleading error.
+ */
+export function makeAgent(workspace) {
+    const stubMcp = {
+        listTools: async () => ({ tools: [] }),
+        callTool: async () => ({ content: [{ text: '{}' }] }),
+        close: async () => { },
+    };
+    const llm = { provider: 'openai', apiKey: 'k', model: 'test-model' };
+    return new Agent(stubMcp, llm, {
+        workspaceRoot: workspace,
+        launchCwd: workspace,
+        sessionKey: 'session:test',
+        silent: true, // skip bootstrap + briefing so we don't touch MCP at all
+    });
+}
+/**
+ * Run a synchronous test body inside a fresh temp workspace. Restores cwd,
+ * BRAINROUTER_WORKSPACE, and BRAINROUTER_HOME afterwards. BRAINROUTER_HOME
+ * is also pinned to a sibling tmp dir so tests never touch the real
+ * `~/.brainrouter` on the developer's machine.
+ */
+export function withTempWorkspace(fn) {
+    const previousCwd = process.cwd();
+    const previousWorkspace = process.env.BRAINROUTER_WORKSPACE;
+    const previousHome = process.env.BRAINROUTER_HOME;
+    const workspace = fs.mkdtempSync(path.join(os.tmpdir(), 'brainrouter-cli-'));
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), 'brainrouter-home-'));
+    try {
+        delete process.env.BRAINROUTER_WORKSPACE;
+        process.env.BRAINROUTER_HOME = home;
+        process.chdir(workspace);
+        fn(workspace);
+    }
+    finally {
+        process.chdir(previousCwd);
+        if (previousWorkspace === undefined)
+            delete process.env.BRAINROUTER_WORKSPACE;
+        else
+            process.env.BRAINROUTER_WORKSPACE = previousWorkspace;
+        if (previousHome === undefined)
+            delete process.env.BRAINROUTER_HOME;
+        else
+            process.env.BRAINROUTER_HOME = previousHome;
+        fs.rmSync(workspace, { recursive: true, force: true });
+        fs.rmSync(home, { recursive: true, force: true });
+    }
+}
+/**
+ * Async sibling of `withTempWorkspace`. Same restore semantics; awaits the
+ * body so promise rejections still tear the workspace down.
+ */
+export async function withTempWorkspaceAsync(fn) {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'brainrouter-test-'));
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), 'brainrouter-home-'));
+    const previousCwd = process.cwd();
+    const previousHome = process.env.BRAINROUTER_HOME;
+    process.env.BRAINROUTER_HOME = home;
+    process.chdir(tmp);
+    try {
+        return await fn(tmp);
+    }
+    finally {
+        process.chdir(previousCwd);
+        if (previousHome === undefined)
+            delete process.env.BRAINROUTER_HOME;
+        else
+            process.env.BRAINROUTER_HOME = previousHome;
+        fs.rmSync(tmp, { recursive: true, force: true });
+        fs.rmSync(home, { recursive: true, force: true });
+    }
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@kinqs/brainrouter-cli",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Memory-native terminal coding agent. Talks to the BrainRouter MCP cognitive engine for recall, skills, capture, persona, focus scenes, and contradiction tracking.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "brainrouter": "dist/index.js"
+    "brainrouter": "bin/cli.cjs"
   },
   "files": [
+    "bin",
     "dist",
     "README.md",
     ".env.example"
@@ -21,8 +22,8 @@
     "prepack": "npm run build && find dist -name '*.test.*' -delete"
   },
   "dependencies": {
-    "@kinqs/brainrouter-sdk": "^0.3.5",
-    "@kinqs/brainrouter-types": "^0.3.5",
+    "@kinqs/brainrouter-sdk": "^0.3.6",
+    "@kinqs/brainrouter-types": "^0.3.6",
     "@modelcontextprotocol/sdk": "^1.11.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",