brainclaw 1.7.0 → 1.7.2

package/README.md

@@ -343,11 +343,42 @@ npm run test:coverage      # with coverage report
 
 ## Changelog
 
-For older releases (v0.x and the early v1.0 launch series), `git log` on `master` is the source of truth — every release commit follows the `chore(release): bump version to <semver>` convention, and the matching feature/fix commits reference their plan id (e.g. `feat(mcp): self-heal ... (pln#478)`).
-
-### v1.5.3
-
-- **Cross-project canonical grammar + CLI parity** (pln#359, all phases) — the canonical grammar (`bclaw_find / get / create / update / remove / transition`), `bclaw_context`, and `bclaw_coordinate` now accept an optional `project: <name>` argument that routes the operation to a linked project. Two link kinds are recognised: `cross_project_links` (sibling/peer projects in `config.yaml`, `brainclaw link list`) and workspace store-chain children. Arbitrary directory paths are rejected — adoption requires an explicit link, which gives the user a single point of control over what an agent can reach. Identity is sourced from the caller's home registry; entity writes + audit log entries land in the target. Unknown project names throw `validation_error` with a hint listing the configured links — no silent fallback. Cross-project `bclaw_coordinate` is **inbox-only**: claim/assignment/message all land in the target, the target agent picks the brief up async via its own `bclaw_work`, and auto-spawn from the source process is force-disabled because the spawn cwd / worktree are tied to the target's git repo (a warning surfaces in `FacadeResponse.warnings`). The CLI exposes the same as a global `--project <name>` flag, mutually exclusive with `--cwd`. Refs: helper `resolveProjectCwd` in `src/core/cross-project.ts`, MCP write/read handler dispatch in `src/commands/mcp.ts` and `src/commands/mcp-read-handlers.ts`, `--project` plumbing in `src/cli.ts` preAction, surface advertisement in `src/core/instruction-templates.ts`, plus tests in `tests/unit/cross-project.test.ts` (10 unit cases on the helper), `tests/unit/bclaw-coordinate.test.ts` (4 cross-project routing cases), and `tests/cli-cross-project.test.ts` (5 e2e cases). Closes the `--cwd` workaround pattern that had been the day-to-day shape of multi-project sessions.
+For older releases (v0.x and the early v1.0 launch series), `git log` on `master` is the source of truth — every release commit follows the `chore(release): bump version to <semver>` convention, and the matching feature/fix commits reference their plan id (e.g. `feat(mcp): self-heal ... (pln#478)`).
+
+### v1.7.2
+
+- **Sequence MCP tools are agent-first by default** — sequence creation,
+  listing, update, and deletion tools are now in the default MCP catalog, with
+  explicit lane item schemas (`planId`, optional `stepId`, `rank`,
+  dependencies, lane metadata) and matching canonical CRUD validation for
+  `entity="sequence"`.
+
+### v1.7.1
+
+- **MCP project context isolation fix** — `bclaw_switch` now keeps MCP switches
+  session-scoped even when the agent session has to be resolved or created on
+  the fly. Session lookup honors explicit session IDs, avoids adopting another
+  live process's session, detects Codex via native `CODEX_*` runtime variables,
+  and `bclaw_switch(list=true)` reports the session active project with
+  `active_source`.
+
+### v1.7.0
+
+- **Dispatch reliability + scope-aware dirty guard** — evidence-first
+  `agent_run` reconciliation avoids false terminal states, `bclaw_coordinate`
+  accepts pinned refs and a scope-aware `allow_dirty` guard, and the Hermes
+  agent integration joins the supported surfaces.
+
+### v1.6.0
+
+- **Bootstrap loop + cross-project agent workflow** — the bootstrap ideation
+  preset can materialize `PROJECT.md`, `bclaw_init_project` initializes and links
+  arbitrary project paths, and `project=` routing reaches `bclaw_work` /
+  `bclaw_loop` for linked-project operations.
+
+### v1.5.3
+
+- **Cross-project canonical grammar + CLI parity** (pln#359, all phases) — the canonical grammar (`bclaw_find / get / create / update / remove / transition`), `bclaw_context`, and `bclaw_coordinate` now accept an optional `project: <name>` argument that routes the operation to a linked project. Two link kinds are recognised: `cross_project_links` (sibling/peer projects in `config.yaml`, `brainclaw link list`) and workspace store-chain children. Arbitrary directory paths are rejected — adoption requires an explicit link, which gives the user a single point of control over what an agent can reach. Identity is sourced from the caller's home registry; entity writes + audit log entries land in the target. Unknown project names throw `validation_error` with a hint listing the configured links — no silent fallback. Cross-project `bclaw_coordinate` is **inbox-only**: claim/assignment/message all land in the target, the target agent picks the brief up async via its own `bclaw_work`, and auto-spawn from the source process is force-disabled because the spawn cwd / worktree are tied to the target's git repo (a warning surfaces in `FacadeResponse.warnings`). The CLI exposes the same as a global `--project <name>` flag, mutually exclusive with `--cwd`. Refs: helper `resolveProjectCwd` in `src/core/cross-project.ts`, MCP write/read handler dispatch in `src/commands/mcp.ts` and `src/commands/mcp-read-handlers.ts`, `--project` plumbing in `src/cli.ts` preAction, surface advertisement in `src/core/instruction-templates.ts`, plus tests in `tests/unit/cross-project.test.ts` (10 unit cases on the helper), `tests/unit/bclaw-coordinate.test.ts` (4 cross-project routing cases), and `tests/cli-cross-project.test.ts` (5 e2e cases). Closes the `--cwd` workaround pattern that had been the day-to-day shape of multi-project sessions.
 - **Site facts contract** (umbrella `pln_7fdfd70d` sprint 0) — new `scripts/emit-site-facts.mjs` emits `dist/facts.{js,json}` from `MCP_TOOL_NAMES` + `ENTITY_NAMES` so the brainclaw-site (and any consumer) can pull live tool/entity counts at build time without forking the values into a hand-maintained config. The package `files` list ships `dist/facts.json`; build:cli runs the emitter as part of the chain.
 
 ### v1.5.2

package/dist/cli.js

@@ -30,7 +30,7 @@ import { runInstruction } from './commands/instruction.js';
 import { runListAgents } from './commands/list-agents.js';
 import { runSurfaceTaskResource } from './commands/surface-task-resource.js';
 import { runListInstructions } from './commands/list-instructions.js';
-import { runDoctor } from './commands/doctor.js';
+import { runDoctor, runDoctorSpawnCheck } from './commands/doctor.js';
 import { runRepair } from './commands/repair.js';
 import { runStale } from './commands/stale.js';
 import { runRebuild } from './commands/rebuild.js';
@@ -681,7 +681,13 @@ program
     .option('--repair', 'Rebuild dist/ when the MCP runtime is missing or stale')
     .option('--after-migration', 'Run the v1.0 post-migration health check only (exits non-zero on any failure)')
     .option('--dispatch', 'Run dispatch-health diagnostic only: reconcile open agent_runs and report stuck/unverified/silent failures (pln#496 step stp_8c072d75)')
-    .action((options) => {
+    .option('--spawn-check', 'Real spawn round-trip per installed agent before dispatch (pln#520 step 2): validates delivery + handshake on this host, exits non-zero on any installed-agent failure')
+    .option('--spawn-check-timeout <ms>', 'Per-agent timeout for --spawn-check (default 15000)', parseInt)
+    .action(async (options) => {
+    if (options.spawnCheck) {
+        await runDoctorSpawnCheck({ cwd: options.cwd, json: options.json, timeoutMs: options.spawnCheckTimeout });
+        return;
+    }
     runDoctor({ ...options, afterMigration: options.afterMigration, dispatch: options.dispatch });
 });
 // --- repair (Phase 4 Sprint 2 Lane C / pln#397) ---
@@ -1441,6 +1447,8 @@ dispatchCmd
     .option('--agents <names>', 'Comma-separated list of agents to dispatch to')
     .option('--lanes <names>', 'Comma-separated list of lanes to dispatch')
     .option('--max <n>', 'Maximum assignments', parseInt)
+    .option('--max-concurrency <n>', 'Opt-in cap on concurrent instances per host-binary (default: unlimited)', parseInt)
+    .option('--model <name>', 'Model to run, decoupled from agent identity (e.g. --model sonnet)')
     .option('--dry', 'Preview assignments without sending messages')
     .option('--spawn', 'Autonomously launch CLI agents with invoke templates')
     .option('--agent <name>', 'Dispatcher agent name')
@@ -1450,6 +1458,8 @@ dispatchCmd
         agents: options.agents,
         lanes: options.lanes,
         max: options.max,
+        maxConcurrency: options.maxConcurrency,
+        model: options.model,
         dry: options.dry,
         spawn: options.spawn,
         agent: options.agent,

package/dist/commands/dispatch.js

@@ -87,6 +87,8 @@ export async function runDispatch(options) {
         dryRun: options.dry,
         dispatcherAgent,
         autoExecute: options.spawn,
+        maxConcurrency: options.maxConcurrency,
+        model: options.model,
     }, effectiveCwd);
     if (!result) {
         console.log('No active sequence found.');

package/dist/commands/doctor.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import * as childProcess from 'node:child_process';
 import { reconcileAllOpenRuns } from '../core/agentrun-reconciler.js';
+import { runSpawnCheck, renderSpawnCheckReport } from '../core/spawn-check.js';
 import { loadAgentRun } from '../core/agentruns.js';
 import { listAgentIdentities, resolveCurrentAgentIdentity } from '../core/agent-registry.js';
 import { listCapabilities as listRegistryCapabilities, listTools as listRegistryTools } from '../core/registries.js';
@@ -565,6 +566,22 @@ function renderDispatchHealthHumanReport(report) {
     }
     return lines.join('\n');
 }
+/**
+ * pln#520 step 2 — `brainclaw doctor --spawn-check`. Real spawn round-trip per
+ * installed agent on the current host. Exits non-zero if any installed agent
+ * fails (so it gates CI / a pre-dispatch pre-flight).
+ */
+export async function runDoctorSpawnCheck(options = {}) {
+    const report = await runSpawnCheck(options);
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log(renderSpawnCheckReport(report));
+    }
+    if (report.exit_code !== 0)
+        process.exit(report.exit_code);
+}
 export function runDoctor(options = {}) {
     if (options.dispatch) {
         const report = runDispatchHealthCheck(options);

package/dist/commands/mcp.js

@@ -57,6 +57,30 @@ export const SCHEMA_VERSION = '1.0.0';
 export const MCP_PROTOCOL_VERSIONS = ['2025-11-25', '2024-11-05'];
 export const MCP_SERVER_NOT_INITIALIZED = -32002;
 const MCP_RUNTIME_REPAIR_COMMAND = 'brainclaw doctor --repair';
+const SEQUENCE_ITEM_INPUT_SCHEMA = {
+    type: 'object',
+    description: 'Sequence lane item. planId is required; stepId optionally narrows dispatch/readiness to a specific plan step.',
+    properties: {
+        planId: { type: 'string', minLength: 1, description: 'Plan item ID referenced by this sequence item.' },
+        stepId: { type: 'string', minLength: 1, description: 'Optional plan step ID inside planId for step-level dispatch/readiness.' },
+        rank: { type: 'number', minimum: 1, description: 'Positive integer ordering key. Ranks must be unique within a sequence.' },
+        hard_after: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Sequence item planId values that must complete before this item becomes ready.',
+        },
+        soft_after: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Advisory predecessor planId values; they inform ordering but do not block readiness.',
+        },
+        lane: { type: 'string', description: 'Optional lane label used for parallel dispatch grouping and filtering.' },
+        scope_hint: { type: 'string', description: 'Optional file/path scope hint for claim and brief generation.' },
+        rationale: { type: 'string', description: 'Optional explanation for this item or dependency placement.' },
+    },
+    required: ['planId', 'rank'],
+    additionalProperties: false,
+};
 const { $defs: loopPhaseDefs, ...loopPhaseItemSchema } = generatedSchemas.LoopPhase;
 const loopSlotInputItemSchema = generatedSchemas.LoopSlotInput;
 export const MCP_READ_TOOLS = [
@@ -160,7 +184,7 @@ export const MCP_READ_TOOLS = [
     {
         name: 'bclaw_list_sequences',
         description: 'List coordination sequences with optional filters on status and id.',
-        annotations: { tier: 'advanced', category: 'coordination', headlessApproval: 'auto' },
+        annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'auto' },
         inputSchema: {
             type: 'object',
             properties: {
@@ -624,7 +648,7 @@ const MCP_WRITE_TOOLS = [
     {
         name: 'bclaw_create_sequence',
         description: 'Create a coordination sequence shared by agents.',
-        annotations: { tier: 'advanced', category: 'coordination', headlessApproval: 'prompt' },
+        annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'prompt' },
         inputSchema: {
             type: 'object',
             properties: {
@@ -632,7 +656,7 @@ const MCP_WRITE_TOOLS = [
                 description: { type: 'string', description: 'Optional sequence description.' },
                 status: { type: 'string', description: 'Status: draft, active, archived.' },
                 owner: { type: 'string', description: 'Optional sequence owner.' },
-                items: { type: 'array', description: 'Sequence items in rank order.', items: { type: 'object' } },
+                items: { type: 'array', description: 'Sequence items in rank order.', items: SEQUENCE_ITEM_INPUT_SCHEMA },
                 tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags.' },
                 agent: { type: 'string', description: 'Agent name.' },
                 agentId: { type: 'string', description: 'Registered agent id.' },
@@ -643,7 +667,7 @@ const MCP_WRITE_TOOLS = [
     {
         name: 'bclaw_update_sequence',
         description: 'Update a coordination sequence status, metadata, or items.',
-        annotations: { tier: 'advanced', category: 'coordination', headlessApproval: 'prompt' },
+        annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'prompt' },
         inputSchema: {
             type: 'object',
             properties: {
@@ -652,7 +676,7 @@ const MCP_WRITE_TOOLS = [
                 description: { type: 'string', description: 'Optional new description.' },
                 status: { type: 'string', description: 'Status: draft, active, archived.' },
                 owner: { type: 'string', description: 'Optional sequence owner.' },
-                items: { type: 'array', description: 'Optional replacement items array.', items: { type: 'object' } },
+                items: { type: 'array', description: 'Optional replacement items array.', items: SEQUENCE_ITEM_INPUT_SCHEMA },
                 tags: { type: 'array', items: { type: 'string' }, description: 'Optional replacement tags.' },
                 agent: { type: 'string', description: 'Agent name.' },
                 agentId: { type: 'string', description: 'Registered agent id.' },
@@ -754,7 +778,7 @@ const MCP_WRITE_TOOLS = [
     {
         name: 'bclaw_delete_sequence',
         description: 'Delete a sequence by ID. Requires trusted or curator trust level.',
-        annotations: { tier: 'advanced', category: 'coordination', headlessApproval: 'prompt' },
+        annotations: { tier: 'standard', category: 'coordination', headlessApproval: 'prompt' },
         inputSchema: {
             type: 'object',
             properties: {
@@ -1092,7 +1116,7 @@ const MCP_WRITE_TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
-                entity: { type: 'string', description: 'Entity name: plan | decision | constraint | trap | handoff | runtime_note | candidate | claim | action | assignment | agent_run | cross_project_link. Others not yet wired.' },
+                entity: { type: 'string', description: 'Entity name: plan | decision | constraint | trap | handoff | runtime_note | candidate | sequence | claim | action | assignment | agent_run | cross_project_link. Others not yet wired.' },
                 filter: { type: 'object', description: 'Filter keys: status, tag (single tag), tags (array, any-match), author, plan_id, source, auto_generated, limit, offset, includeLegacy (bool, default false), minAutoReflectConfidence (0-1, default 0.6). entity=agent_run also accepts assignment_id, claim_id, message_id.' },
                 project: { type: 'string', description: 'Optional: name (or path/basename) of a linked project to query. Defaults to the current project. Only cross_project_links (config.yaml) and workspace store-chain children are accepted — list with `brainclaw link list`.' },
             },

package/dist/commands/switch.js

@@ -1,9 +1,9 @@
 import path from 'node:path';
 import { loadActiveProject, saveActiveProject, clearActiveProject } from '../core/active-project.js';
-import { loadCurrentSession, saveCurrentSession } from '../core/identity.js';
+import { buildOperationalIdentity, loadCurrentSession, saveCurrentSession } from '../core/identity.js';
 import { memoryExists } from '../core/io.js';
 import { resolveProjectRef } from '../core/store-resolution.js';
-import { resolveProjectCwd } from '../core/cross-project.js';
+import { resolveCrossProjectLinks, resolveProjectCwd } from '../core/cross-project.js';
 import { scanNestedBrainclawProjects } from '../core/workspace-projects.js';
 import { loadConfig } from '../core/config.js';
 /**
@@ -43,8 +43,12 @@ export function switchProject(projectRef, options = {}) {
     }
     catch { /* name is optional */ }
     const now = new Date().toISOString();
-    const session = loadCurrentSession(cwd);
     const sessionOnly = options.sessionOnly ?? true;
+    let session = loadCurrentSession(cwd);
+    if (!session && sessionOnly) {
+        buildOperationalIdentity(undefined, cwd, { persistImplicitSession: true });
+        session = loadCurrentSession(cwd);
+    }
     if (session && sessionOnly) {
         saveCurrentSession({
             ...session,
@@ -52,6 +56,9 @@ export function switchProject(projectRef, options = {}) {
         }, cwd);
         return { switched: true, path: resolved, name: projectName, scope: 'session', workspace_root: wsRoot };
     }
+    if (sessionOnly) {
+        throw new Error('Cannot switch project without an active agent session. Start with bclaw_work or bclaw_session_start first.');
+    }
     if (session) {
         // Also write to session even when not sessionOnly
         saveCurrentSession({
@@ -75,15 +82,30 @@ export function listAvailableProjects(cwd) {
     if (!wsRoot) {
         throw new Error('No brainclaw workspace found.');
     }
-    const active = loadActiveProject(wsRoot);
+    const sessionActive = loadCurrentSession(cwd)?.active_project;
+    const globalActive = loadActiveProject(wsRoot);
+    const active = sessionActive ?? globalActive;
+    const activeSource = sessionActive ? 'session' : globalActive ? 'global' : 'none';
     const projects = [];
+    const seen = new Set();
+    const addProject = (project) => {
+        const projectPath = path.resolve(project.path);
+        if (seen.has(projectPath))
+            return;
+        seen.add(projectPath);
+        projects.push({
+            ...project,
+            path: projectPath,
+            active: active?.path ? path.resolve(active.path) === projectPath : false,
+        });
+    };
     if (memoryExists(wsRoot)) {
         try {
             const config = loadConfig(wsRoot);
-            projects.push({ name: config.project_name, path: wsRoot, relative_path: '.', active: active?.path === wsRoot });
+            addProject({ name: config.project_name, path: wsRoot, relative_path: '.' });
         }
         catch {
-            projects.push({ path: wsRoot, relative_path: '.', active: active?.path === wsRoot });
+            addProject({ path: wsRoot, relative_path: '.' });
         }
     }
     const children = scanNestedBrainclawProjects(wsRoot, 7);
@@ -92,9 +114,19 @@ export function listAvailableProjects(cwd) {
         if (childPath === wsRoot)
             continue;
         const rel = path.relative(wsRoot, childPath) || '.';
-        projects.push({ name: child.project_name, path: childPath, relative_path: rel, active: active?.path === childPath });
+        addProject({ name: child.project_name, path: childPath, relative_path: rel });
+    }
+    for (const link of resolveCrossProjectLinks(wsRoot)) {
+        if (!link.available)
+            continue;
+        const linkPath = path.resolve(link.absolutePath);
+        addProject({
+            name: link.projectName,
+            path: linkPath,
+            relative_path: path.relative(wsRoot, linkPath) || '.',
+        });
     }
-    return { workspace_root: wsRoot, projects };
+    return { workspace_root: wsRoot, active_source: activeSource, projects };
 }
 export function runSwitch(projectRef, options = {}) {
     // Use real cwd, not effective cwd — switch must see the full workspace

package/dist/core/agent-capability.js

@@ -46,6 +46,10 @@ const PROFILES = {
         invoke_binary: 'claude',
         invoke_review_template: 'claude -p --allowedTools "Read,Glob,Grep" {prompt}',
         invoke_consult_template: 'claude -p --allowedTools "Read,Glob,Grep" {prompt}',
+        // pln#520 step 3: model is selectable via `--model` — no need for a
+        // per-model pseudo-identity. `claude-sonnet` below is now redundant
+        // (run `claude-code --model sonnet`) and kept only for back-compat.
+        model_flag: '--model',
     },
     'claude-sonnet': {
         name: 'claude-sonnet', category: 'code-agent', workflowModel: 'interactive',
@@ -323,6 +327,63 @@ export function getCapabilityProfile(name) {
     const resolved = resolveAgentAlias(name);
     return _customProfiles.get(resolved) ?? PROFILES[resolved];
 }
+/**
+ * pln#520 step 3 — concurrency is a resolvable execution-config value, NOT a
+ * structural constant baked into agent identity.
+ *
+ * The host resource a concurrency cap actually protects is the binary on the
+ * machine (its API quota / its RAM/CPU footprint), not the agent label.
+ * `resolveResourceKey` returns that shared key so callers count usage across
+ * every identity that drives one binary. This kills the can_dc4e4a11 bug:
+ * `claude-code` and `claude-sonnet` are the SAME `claude` binary on the SAME
+ * host but were counted separately (3 + 6 → up to 9 concurrent `claude`
+ * processes, oversubscribing the machine + API).
+ */
+export function resolveResourceKey(name) {
+    const profile = getCapabilityProfile(name);
+    return profile?.invoke_binary ?? resolveAgentAlias(name);
+}
+/**
+ * Resolve the concurrency limit for an agent. `Infinity` = unlimited.
+ *
+ * Resolution chain (highest priority first), decoupled from agent identity:
+ *   1. explicit `override` (e.g. `brainclaw dispatch --max-concurrency N`)
+ *   2. host opt-in cap via `BRAINCLAW_MAX_CONCURRENCY` (protect one machine / quota)
+ *   3. structural floor — agents that cannot run headless in parallel
+ *      (IDE / desktop agents, i.e. not CLI-spawnable) stay hard-capped at their
+ *      profile `max_concurrent_tasks` (you can't spawn N IDE windows headlessly)
+ *   4. default for parallelizable CLI agents: UNLIMITED. There is no arbitrary
+ *      per-identity throttle — the operator opts into a cap when they want one.
+ *
+ * When a finite cap applies it is enforced per host-binary resource
+ * (see `resolveResourceKey`), so all variants of one binary share the pool.
+ */
+export function resolveConcurrencyLimit(name, opts = {}) {
+    if (opts.override !== undefined && opts.override > 0)
+        return opts.override;
+    const envCap = Number(process.env.BRAINCLAW_MAX_CONCURRENCY);
+    if (Number.isFinite(envCap) && envCap > 0)
+        return envCap;
+    const profile = getCapabilityProfile(name);
+    if (!profile?.runtime?.canBeSpawnedCli)
+        return profile?.max_concurrent_tasks ?? 1;
+    return Infinity;
+}
+/** JSON-safe rendering of a concurrency limit: `Infinity` → `null` (= unlimited). */
+export function serializeConcurrencyLimit(limit) {
+    return Number.isFinite(limit) ? limit : null;
+}
+/**
+ * pln#520 step 3 — resolve the model for a dispatch, decoupled from agent
+ * identity. Chain (highest priority first): explicit override (e.g.
+ * `dispatch --model`) → lane model → identity model → profile default.
+ * Returns `undefined` when nothing in the chain specifies one (the agent's
+ * template default applies).
+ */
+export function resolveModel(name, opts = {}) {
+    const profile = getCapabilityProfile(name);
+    return opts.override ?? opts.lane ?? opts.identity ?? profile?.default_model;
+}
 /**
  * Escape a string for safe use as a double-quoted shell argument.
  * Escapes characters that have special meaning inside double-quotes
@@ -490,6 +551,12 @@ export function buildInvokeCommand(name, prompt, options = {}) {
     const rawTokens = parseTemplateString(templateStr);
     if (rawTokens.length === 0)
         return undefined;
+    // pln#520 step 3: inject the resolved model right after the binary so model
+    // choice is decoupled from agent identity. Only when the profile declares a
+    // `model_flag` and the template doesn't already pin a model (don't double it).
+    if (options.model && profile.model_flag && !rawTokens.includes(profile.model_flag)) {
+        rawTokens.splice(1, 0, profile.model_flag, options.model);
+    }
     const executable = rawTokens[0];
     const interpolatedTokens = rawTokens.slice(1).map((tok) => tok === '{prompt}' ? embeddedPrompt : tok);
     // ── 5. Build the args array ───────────────────────────────────────────────