amsd-pipeline-shared 0.5.43 → 0.5.44

package/docs/gateway-baseline-2.0.80.md5

@@ -1,3 +1,6 @@
+5349c655265a56795c62a0327ba4e73b  config/llm-defaults.claude.json
+5c2b348dbf4860aa6ad999eb7b882757  config/llm-defaults.mockserver.json
+c90ae290edde83ae4e13236edb1e8fb5  config/llm-defaults.openrouter.json
 33364f057aa890497019737c7004db57  config/model-pricing.json
 8a1bb4df2d1b6e7fd135f757423fb2f2  config/repo-artifacts.json
 7ab104b57abcbc8cb3cd890c753d5d67  config/resume-preserves.json

package/docs/gateway-files.txt

@@ -2,6 +2,9 @@ config/call-policy.json
 config/doctor-heavy-jobs.json
 config/doctor-signatures.json
 config/finding-contracts.json
+config/llm-defaults.claude.json
+config/llm-defaults.mockserver.json
+config/llm-defaults.openrouter.json
 config/model-pricing.json
 config/repo-artifacts.json
 config/resume-preserves.json
@@ -62,6 +65,8 @@ prompts/templates/phase-assessment-header.json
 prompts/templates/pipeline-tools-command.json
 prompts/templates/pipeline-tools-hosted.json
 prompts/templates/plan-corrective.json
+prompts/templates/plan-execute.json
+prompts/templates/plan-pass.json
 prompts/templates/plan-producer.json
 prompts/templates/plan-reviewer.json
 prompts/templates/post-failure-analyst.json
@@ -236,6 +241,7 @@ scripts/lib/pipeline-commit.sh
 scripts/lib/pipeline-tools-mcp.js
 scripts/lib/pipeline-tools.js
 scripts/lib/plan-hash.js
+scripts/lib/plan-mode.js
 scripts/lib/plan-of-record.sh
 scripts/lib/plan-scope.js
 scripts/lib/prd-change-review.sh

package/orchestrations/config/llm-defaults.claude.json

@@ -0,0 +1,236 @@
+{
+  "$comment": "THE CLAUDE PROVIDER SET — plain Claude Code on the operator's own tokens. The default stack.",
+  "$proven": "2026-08-25: plain `claude` honours ANTHROPIC_BASE_URL, reaches MockServer (POST /v1/messages in its request log) and PARSES the SSE it serves — is_error:false, result:'OK', stop_reason:'end_turn', RC=0.",
+  "$whyNotTheWrapper": "Plain `claude`, never codemie-claude. The wrapper authenticates through CodeMie SSO and spends CodeMie tokens; this set exists precisely because those are scarce and the operator has their own.",
+  "$whyTheSameLadders": "Deliberately identical to the codemie set. A rehearsal on different models proves the harness, not the run. Sharing the ladder means a mocked run climbs the chain a paid run would.",
+  "ladderTierOrder": [
+    "medium",
+    "high",
+    "highest"
+  ],
+  "ladders": {
+    "medium": {
+      "$why": "Enters cheap and tops out at Sonnet-5. A `mid` seam never reaches Opus: 14 seams resolve here, and measured turn counts are p50 4, p90 24 — work that does not need a frontier model.",
+      "startModel": "claude-haiku-4-5-20251001",
+      "modelLadder": [
+        {
+          "from": "claude-haiku-4-5-20251001",
+          "to": "claude-sonnet-5"
+        }
+      ],
+      "rungs": [
+        {
+          "rung": 0,
+          "maxIterations": 40,
+          "reasoningEffort": "medium"
+        },
+        {
+          "rung": 1,
+          "maxIterations": 120,
+          "reasoningEffort": "high"
+        }
+      ]
+    },
+    "high": {
+      "$why": "Same ENTRY as medium, higher CEILING. That is the 'different entry, same ceiling' rule applied between high and highest: what separates the tiers is how far they may climb, not where they start.",
+      "startModel": "claude-haiku-4-5-20251001",
+      "modelLadder": [
+        {
+          "from": "claude-haiku-4-5-20251001",
+          "to": "claude-sonnet-5"
+        },
+        {
+          "from": "claude-sonnet-5",
+          "to": "claude-opus-5-5"
+        }
+      ],
+      "rungs": [
+        {
+          "rung": 0,
+          "maxIterations": 40,
+          "reasoningEffort": "medium"
+        },
+        {
+          "rung": 1,
+          "maxIterations": 250,
+          "reasoningEffort": "high"
+        },
+        {
+          "rung": 2,
+          "maxIterations": 300,
+          "reasoningEffort": "high"
+        }
+      ]
+    },
+    "highest": {
+      "$why": "Skips Haiku. 25 seams resolve here and would waste a rung proving a small model cannot do the work. Same ceiling as high, entered two rungs up.",
+      "startModel": "claude-sonnet-5",
+      "modelLadder": [
+        {
+          "from": "claude-sonnet-5",
+          "to": "claude-opus-5-5"
+        }
+      ],
+      "rungs": [
+        {
+          "rung": 0,
+          "maxIterations": 250,
+          "reasoningEffort": "high"
+        },
+        {
+          "rung": 1,
+          "maxIterations": 250,
+          "reasoningEffort": "high"
+        },
+        {
+          "rung": 2,
+          "maxIterations": 300,
+          "reasoningEffort": "xhigh"
+        }
+      ]
+    }
+  },
+  "modelOverrides": {
+    "$whyAutoCompress": "150000 against a 200000 window is an OVERFLOW GUARD near the ceiling, never a token-saving device: compaction rewrites the prefix and destroys the prompt cache. Measured input is p50 13.3k, p90 19k, max 25.9k — about 13% of the window — so this should never fire. If it does, something has gone wrong upstream and that is worth knowing.",
+    "$whyNoTemperature": "codemie-claude exposes no temperature flag and Claude Code has no supported lever for it. Declaring one would be decoration. Deliberation is controlled by reasoningEffort and thinking instead.",
+    "$whyAdaptive": "Thinking is held STABLE per model. Anthropic's docs list effort and thinking-parameter changes as cache invalidators, so a config that changes between attempts discards the cache every retry — the opposite of what a 1h TTL is for.",
+    "claude-haiku-4-5": {
+      "matchOn": "model",
+      "matchSubstring": "claude-haiku-4-5",
+      "thinking": "adaptive",
+      "promptCacheTtl": "1h",
+      "autoCompressAt": 150000,
+      "maxOutputTokens": 32000,
+      "miniTier": true,
+      "charsPerToken": 4
+    },
+    "claude-sonnet-5": {
+      "matchOn": "model",
+      "matchSubstring": "claude-sonnet-5",
+      "thinking": "adaptive",
+      "promptCacheTtl": "1h",
+      "autoCompressAt": 150000,
+      "maxOutputTokens": 64000,
+      "charsPerToken": 4
+    },
+    "claude-opus-5-5": {
+      "matchOn": "model",
+      "matchSubstring": "claude-opus-5-5",
+      "thinking": "adaptive",
+      "promptCacheTtl": "1h",
+      "autoCompressAt": 150000,
+      "maxOutputTokens": 64000,
+      "charsPerToken": 4,
+      "$why": "Explicit, and BEFORE claude-opus-5: matching is by first substring hit, and 'claude-opus-5' is a substring of 'claude-opus-5-5' — without this entry Opus 5.5 silently took Opus 5's settings. Values as Opus 5; not vendor-checked."
+    },
+    "claude-opus-4-8": {
+      "matchOn": "model",
+      "matchSubstring": "claude-opus-4-8",
+      "thinking": "adaptive",
+      "promptCacheTtl": "1h",
+      "autoCompressAt": 150000,
+      "maxOutputTokens": 64000,
+      "charsPerToken": 4
+    },
+    "claude-opus-5": {
+      "matchOn": "model",
+      "matchSubstring": "claude-opus-5",
+      "thinking": "adaptive",
+      "promptCacheTtl": "1h",
+      "autoCompressAt": 150000,
+      "maxOutputTokens": 64000,
+      "charsPerToken": 4
+    },
+    "$miniTierWhy": "miniTier marks the cheap, fast rung — the models that are quick but limited in generation capacity. It was decided in engine code by sniffing vendor naming habits (-mini, -flash, -haiku, minimax-m2), which breaks in both directions: a cheap model named differently read as capable, and a capable model containing -flash read as cheap. The set that declares the model declares its tier.",
+    "$whyCharsPerToken": "INPUT CAPACITY IN CHARACTERS. autoCompressAt is the models input ceiling in TOKENS; callers that must size a payload measure it in characters. The ratio belongs with the model, because it is a property of that models tokenizer, not of any caller. Declared so a caller derives its budget instead of inventing one: the roster review carried a literal 60000 in code, which split a 276KB roster into six calls and failed the whole review whenever any one of them answered off-schema."
+  },
+  "finalFallback": {
+    "$why": "Applies after ladder exhaustion — the one point where the ladder has nothing left to say. Sonnet-5 differs from the top rung on high and highest, so it is a real second answer rather than a retry of the model that just failed.",
+    "model": "claude-sonnet-5",
+    "provider": "claude"
+  },
+  "runners": {
+    "claude": {
+      "siChannel": {
+        "flag": "--append-system-prompt-file"
+      },
+      "$whySiChannel": "Claude Code's own --append-system-prompt-file (claude --help, 2.1.282): the agent's SI as a system prompt, separate from the task on stdin.",
+      "$why": "Plain Claude Code. No CodeMie, no SSO, no spend.",
+      "alwaysFlags": [
+        "--setting-sources",
+        "",
+        "--strict-mcp-config",
+        "--disable-slash-commands",
+        "--settings",
+        "{\"includeGitInstructions\":false}"
+      ],
+      "$whyAlwaysFlags": "The agent receives the pipeline's SI and task, nothing of the host — through Claude Code's own interface, each piece by its own switch (proven on 2.1.310, 2026-10-24, with a CLAUDE.md canary in the working folder): --setting-sources \"\" loads no user, project or local settings (so none of the host's hooks, permissions or CLAUDE.md); CLAUDE_CODE_DISABLE_CLAUDE_MDS and CLAUDE_CODE_DISABLE_AUTO_MEMORY (env below) keep the working folder's CLAUDE.md and the host's auto-memory out; --disable-slash-commands drops the skills; includeGitInstructions:false drops the git status; --strict-mcp-config makes the pipeline's MCP server (hostedToolPlugins, lib/pipeline-tools-mcp.js) the ONLY server. --safe-mode did all of this in one switch and ALSO dropped every MCP server, --mcp-config included (proven: the tool was absent), so the pipeline's tools could not be the agent's tools under it. Sign-in survives (the subscription, not an API key); --bare would not.",
+      "env": {
+        "CLAUDE_CODE_DISABLE_CLAUDE_MDS": "hostClaudeMdOff",
+        "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "hostAutoMemoryOff",
+        "CLAUDE_CODE_PROMPT_CACHE_TTL": "promptCacheTtl",
+        "CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL": "promptCacheTtl"
+      },
+      "flags": {
+        "--effort": "reasoningEffort",
+        "--autocompact": "autoCompressAt"
+      },
+      "$whyFlags": "Checked against the installed CLI's own --help, not assumed: --effort takes (low, medium, high, xhigh, max) and --autocompact takes auto or a token count. These were declared as CLAUDE_CODE_* env vars that the CLI does not document and that nothing exported.",
+      "$whyNoTurnCap": "maxIterations is deliberately absent. It binds the ReAct loop in src/agent/AgentRunner.ts, which only the `epam run` arm enters; a --print call has no turn cap and the loop is Claude Code's own. Declaring one here would name a knob nothing can turn.",
+      "$whyNoOutputCap": "maxOutputTokens is deliberately unmapped: the installed CLI documents no flag or env for it. It stays declared in modelOverrides so the intent is visible, and is not routed anywhere pretending to work.",
+      "$whyNoSilentFlag": "-s is codemie-claude's silent flag and plain `claude` REJECTS it: `echo x | claude -s --print` exits 1 with \"error: unknown option '-s'\". Proven by running it, 2026-08-26, after a --help probe proved nothing (--help and --version short-circuit before option validation, so an invalid flag exits 0 there too). With -s declared, the hub passed it to plain claude, the call failed, and the arm's 2>/dev/null hid the reason — codeline-discovery reported only 'Empty response from ai-run.sh' and the mock3 run aborted with 'codeline scope could not be resolved'. The codemie runner keeps -s: codemie-claude --help documents it as -s, --silent.",
+      "unsetEnv": [
+        "ANTHROPIC_API_KEY",
+        "ANTHROPIC_AUTH_TOKEN"
+      ],
+      "$whyUnsetEnv": "THE SUBSCRIPTION PAYS, AND THAT IS WHY THIS PIPELINE SHELLS OUT TO THE CLI INSTEAD OF THE SDK. Claude Code prefers ANTHROPIC_API_KEY over the OAuth credentials at ~/.claude/.credentials.json. The repo .env declares ANTHROPIC_API_KEY and run-agent-orchestration.sh loads .env, so every run on this stack billed API CREDITS — the exact outcome invoking the CLI was meant to avoid. It surfaced on 2026-08-26 only when the credits ran out mid-run: \"No JSON in LLM response: Credit balance is too low\". Seven runs had already billed the wrong account.\n\nDeclared per RUNNER rather than scrubbed globally: openrouter needs its key, and the free-run guard only scrubs when a run is declared free — a PAID run on this stack had no equivalent because nobody expected the key to be present at all.",
+      "emitsTraces": true,
+      "toolNames": {
+        "read_file": [
+          "Read"
+        ],
+        "list_files": [
+          "Glob"
+        ],
+        "search": [
+          "Grep"
+        ],
+        "fetch_url": [
+          "WebFetch"
+        ],
+        "bash": [
+          "Bash"
+        ],
+        "write_file": [
+          "Write",
+          "Edit"
+        ]
+      },
+      "$whyToolNames": "A SEAM'S TOOL GRANT IS BOUND AT THE RUNNER, LIKE ITS SCHEMA AND ITS BUDGET. Every seam declares a grant kind (none, read-only, execute, write-file...) and it travels as EPAM_ALLOWED_TOOLS; that variable was read in ONE place, src/agent/AgentRunner.ts on the `epam run` arm, so on this runner it bound NOTHING and every seam ran `--print --dangerously-skip-permissions` with the CLI's whole tool set. Run 20260916T225207Z (skyscanner): project-roster-review, declared read-only, ran `find / -iname prd.json` and read five earlier runs' cassettes out of the pipeline repo, then refused the roster for disagreeing with them. The 2026-09-12 roster specialiser, declared write-file, spent ~350 shell calls copying a repository. This map is the runner's own vocabulary for the pipeline's tool names (`claude --help`: --tools takes built-in tool names; \"\" disables all). llm-handler.sh translates the grant through it and passes --tools when the installed CLI advertises the flag. A pipeline tool with no entry here does not exist on this runner and is dropped from the list, said aloud on stderr. A seam with NO grant (kind none) is passed nothing and keeps the CLI's default set: --tools \"\" may also remove the StructuredOutput tool --json-schema requires, and that has not been proven either way, so it is not done blind.",
+      "$emitsTraces": "Whether model calls made through this runner reach Langfuse. TRUE for every runner: traces are emitted by lib/cost-emitter.js at the cost seam — the point every arm passes through with its model, tokens, cost and timing resolved — not by the TypeScript provider decorator, which only the epam arm reaches. Verified end-to-end 2026-09-04 by driving the real emitter and reading the session back out of Langfuse.",
+      "$whyEnv": "Each name is a top-level setting of this stack (hostClaudeMdOff, hostAutoMemoryOff, promptCacheTtl), resolved by lib/llm-settings-resolve.js runnerValues and exported for the CLI; an operator overrides one with EPAM_RUNNER_VALUE_<name>. The cache TTL: Claude Code's subagent and workflow calls default to a 5-minute prompt cache; the pipeline's calls repeat the same SI and context for an hour or more, so the documented 1h TTL is declared for both (docs: prompt-caching).",
+      "hostedToolPlugins": [
+        "plugins/codegraph-plugin.js",
+        "plugins/codeline-context-plugin.js",
+        "plugins/dependency-contract-plugin.js",
+        "plugins/dependency-scan-plugin.js",
+        "plugins/secret-scan-plugin.js",
+        "plugins/verification-plugin.js"
+      ],
+      "mcpServer": "pipeline",
+      "$whyHostedToolPlugins": "The pipeline's own tool plugins — the same modules the codemie-web runner hosts — served to this runner's agents as Claude Code tools over MCP (lib/pipeline-tools-mcp.js; the hub passes --mcp-config). Before this an agent on this runner reached codegraph, the search and the package-symbol resolver only as shell scripts through Bash: a read-only seam could not call them at all, and plan mode denies such Bash calls. A 'safe' plugin tool is annotated read-only, which is what lets plan mode run it.",
+      "planModeChannel": {
+        "modeFlag": "--permission-mode",
+        "planValue": "plan",
+        "sessionFlag": "--session-id",
+        "resumeFlag": "--resume"
+      },
+      "$whyPlanModeChannel": "How a plan pass is made on this runner (llm-handler.sh; lib/plan-mode.js decides WHETHER a seam plans): Claude Code's own plan mode. Proven on 2.1.310 (2026-10-24): `--permission-mode plan` under --print returns the plan as the result and writes nothing — the agent may read, search and call read-only tools, so the plan is grounded; the answer is then made in the same session with `--resume <session-id>` and the ordinary permissions. A runner that declares no channel gets the hub's prose pass (the plan written with no tools)."
+    }
+  },
+  "$why": "Built from the mockserver set by REMOVING the redirect, because that set was already a plain-`claude` stack pointed at localhost — same ladders, same budgets, same runner. Its header records the proof: plain `claude` honours ANTHROPIC_BASE_URL, reaches the endpoint it is given, and parses the SSE served back (is_error:false, RC=0). Taking the endpoint away is the whole difference between rehearsing and running.",
+  "hostClaudeMdOff": "1",
+  "hostAutoMemoryOff": "1",
+  "promptCacheTtl": "1h",
+  "$whyHostContextOff": "Values for the claude runner's env declaration (see runners.claude.$whyEnv): the host's CLAUDE.md and auto-memory stay out of every agent call; the prompt cache lives 1h."
+}

package/orchestrations/config/llm-defaults.mockserver.json

@@ -0,0 +1,295 @@
+{
+  "$comment": "THE MOCKSERVER PROVIDER SET — the CodeMie stack, answered by MockServer instead of a model. Same ladders and same budgets, so a rehearsal exercises the chain a paid run would climb; only the ENDPOINT differs.",
+  "$proven": "2026-08-25: plain `claude` honours ANTHROPIC_BASE_URL, reaches MockServer (POST /v1/messages in its request log) and PARSES the SSE it serves — is_error:false, result:'OK', stop_reason:'end_turn', RC=0.",
+  "$whyNotTheWrapper": "This runs PLAIN `claude`, not codemie-claude. The wrapper's --base-url selects an SSO PROFILE rather than redirecting, and fails with 'SSO credentials not found' for any URL it has no credentials for. A mocked run must authenticate against NOTHING, so it bypasses the wrapper entirely.",
+  "$whyTheSameLadders": "Deliberately identical to the codemie set. A rehearsal on different models proves the harness, not the run. Sharing the ladder means a mocked run climbs the chain a paid run would.",
+  "ladderTierOrder": [
+    "medium",
+    "high",
+    "highest"
+  ],
+  "ladders": {
+    "medium": {
+      "$why": "Enters cheap and tops out at Sonnet-5. A `mid` seam never reaches Opus: 14 seams resolve here, and measured turn counts are p50 4, p90 24 — work that does not need a frontier model.",
+      "startModel": "claude-haiku-4-5-20251001",
+      "modelLadder": [
+        {
+          "from": "claude-haiku-4-5-20251001",
+          "to": "claude-sonnet-5"
+        }
+      ],
+      "rungs": [
+        {
+          "rung": 0,
+          "maxIterations": 40,
+          "reasoningEffort": "medium"
+        },
+        {
+          "rung": 1,
+          "maxIterations": 120,
+          "reasoningEffort": "high"
+        }
+      ]
+    },
+    "high": {
+      "$why": "Same ENTRY as medium, higher CEILING. That is the 'different entry, same ceiling' rule applied between high and highest: what separates the tiers is how far they may climb, not where they start.",
+      "startModel": "claude-haiku-4-5-20251001",
+      "modelLadder": [
+        {
+          "from": "claude-haiku-4-5-20251001",
+          "to": "claude-sonnet-5"
+        },
+        {
+          "from": "claude-sonnet-5",
+          "to": "claude-opus-5"
+        }
+      ],
+      "rungs": [
+        {
+          "rung": 0,
+          "maxIterations": 40,
+          "reasoningEffort": "medium"
+        },
+        {
+          "rung": 1,
+          "maxIterations": 250,
+          "reasoningEffort": "high"
+        },
+        {
+          "rung": 2,
+          "maxIterations": 300,
+          "reasoningEffort": "high"
+        }
+      ]
+    },
+    "highest": {
+      "$why": "Skips Haiku. 25 seams resolve here and would waste a rung proving a small model cannot do the work. Same ceiling as high, entered two rungs up.",
+      "startModel": "claude-sonnet-5",
+      "modelLadder": [
+        {
+          "from": "claude-sonnet-5",
+          "to": "claude-opus-4-8"
+        },
+        {
+          "from": "claude-opus-4-8",
+          "to": "claude-opus-5"
+        }
+      ],
+      "rungs": [
+        {
+          "rung": 0,
+          "maxIterations": 250,
+          "reasoningEffort": "high"
+        },
+        {
+          "rung": 1,
+          "maxIterations": 250,
+          "reasoningEffort": "high"
+        },
+        {
+          "rung": 2,
+          "maxIterations": 300,
+          "reasoningEffort": "xhigh"
+        }
+      ]
+    }
+  },
+  "modelOverrides": {
+    "$whyAutoCompress": "150000 against a 200000 window is an OVERFLOW GUARD near the ceiling, never a token-saving device: compaction rewrites the prefix and destroys the prompt cache. Measured input is p50 13.3k, p90 19k, max 25.9k — about 13% of the window — so this should never fire. If it does, something has gone wrong upstream and that is worth knowing.",
+    "$whyNoTemperature": "codemie-claude exposes no temperature flag and Claude Code has no supported lever for it. Declaring one would be decoration. Deliberation is controlled by reasoningEffort and thinking instead.",
+    "$whyAdaptive": "Thinking is held STABLE per model. Anthropic's docs list effort and thinking-parameter changes as cache invalidators, so a config that changes between attempts discards the cache every retry — the opposite of what a 1h TTL is for.",
+    "claude-haiku-4-5": {
+      "matchOn": "model",
+      "matchSubstring": "claude-haiku-4-5",
+      "thinking": "adaptive",
+      "promptCacheTtl": "1h",
+      "autoCompressAt": 150000,
+      "maxOutputTokens": 32000,
+      "miniTier": true,
+      "charsPerToken": 4
+    },
+    "claude-sonnet-5": {
+      "matchOn": "model",
+      "matchSubstring": "claude-sonnet-5",
+      "thinking": "adaptive",
+      "promptCacheTtl": "1h",
+      "autoCompressAt": 150000,
+      "maxOutputTokens": 64000,
+      "charsPerToken": 4
+    },
+    "claude-opus-4-8": {
+      "matchOn": "model",
+      "matchSubstring": "claude-opus-4-8",
+      "thinking": "adaptive",
+      "promptCacheTtl": "1h",
+      "autoCompressAt": 150000,
+      "maxOutputTokens": 64000,
+      "charsPerToken": 4
+    },
+    "claude-opus-5": {
+      "matchOn": "model",
+      "matchSubstring": "claude-opus-5",
+      "thinking": "adaptive",
+      "promptCacheTtl": "1h",
+      "autoCompressAt": 150000,
+      "maxOutputTokens": 64000,
+      "charsPerToken": 4
+    },
+    "$miniTierWhy": "miniTier marks the cheap, fast rung — the models that are quick but limited in generation capacity. It was decided in engine code by sniffing vendor naming habits (-mini, -flash, -haiku, minimax-m2), which breaks in both directions: a cheap model named differently read as capable, and a capable model containing -flash read as cheap. The set that declares the model declares its tier.",
+    "$whyCharsPerToken": "INPUT CAPACITY IN CHARACTERS. autoCompressAt is the models input ceiling in TOKENS; callers that must size a payload measure it in characters. The ratio belongs with the model, because it is a property of that models tokenizer, not of any caller. Declared so a caller derives its budget instead of inventing one: the roster review carried a literal 60000 in code, which split a 276KB roster into six calls and failed the whole review whenever any one of them answered off-schema."
+  },
+  "finalFallback": {
+    "$why": "Applies after ladder exhaustion. The PROVIDER is plain `claude`, not codemie-claude, matching every other call this set makes — see $whyNotTheWrapper. That is CORRECT, not a paid escape: this set never talks to real Anthropic. runners.claude below declares ANTHROPIC_BASE_URL redirecting to MockServer and unsetEnv scrubbing every other vendor's credentials, and that redirect applies to every call routed under this set's own provider:\"claude\", finalFallback included — it never has a real endpoint to reach. Mockserver is a mock-LLM, no-pay testing mechanism by construction, not merely by convention (change-log/SEAM-CONSISTENCY-ANALYSIS.md Section 6, corrected 2026-09-03: the prior wording here mischaracterized this as an unresolved paid-escape risk).",
+    "$whyNotYetLive": "As of this writing, nothing in the runtime ladder-exhaustion path (llm-handler.sh, claude.sh, brownfield-repro-test-writer.sh) reads finalFallback — exhaustion retries the same rung instead. agent-check.js's dry-run cost estimator is the only reader, and even there this is unreachable while any ladder tier has a startModel (all of them do). Declared for correctness and for whenever that wiring exists.",
+    "model": "claude-sonnet-5",
+    "provider": "claude"
+  },
+  "runners": {
+    "claude": {
+      "siChannel": {
+        "flag": "--append-system-prompt-file"
+      },
+      "$whySiChannel": "Claude Code's own --append-system-prompt-file (claude --help, 2.1.282): the agent's SI as a system prompt, separate from the task on stdin.",
+      "$why": "Plain Claude Code. No CodeMie, no SSO, no spend.",
+      "$whyNoBaseUrlFlag": "--base-url is ABSENT on purpose: on the wrapper it means 'use this SSO profile'. The redirect is ANTHROPIC_BASE_URL, which plain claude honours.",
+      "alwaysFlags": [
+        "--setting-sources",
+        "",
+        "--strict-mcp-config",
+        "--disable-slash-commands",
+        "--settings",
+        "{\"includeGitInstructions\":false}"
+      ],
+      "$whyAlwaysFlags": "The agent receives the pipeline's SI and task, nothing of the host — through Claude Code's own interface, each piece by its own switch (proven on 2.1.310, 2026-10-24, with a CLAUDE.md canary in the working folder): --setting-sources \"\" loads no user, project or local settings (so none of the host's hooks, permissions or CLAUDE.md); CLAUDE_CODE_DISABLE_CLAUDE_MDS and CLAUDE_CODE_DISABLE_AUTO_MEMORY (env below) keep the working folder's CLAUDE.md and the host's auto-memory out; --disable-slash-commands drops the skills; includeGitInstructions:false drops the git status; --strict-mcp-config makes the pipeline's MCP server (hostedToolPlugins, lib/pipeline-tools-mcp.js) the ONLY server. --safe-mode did all of this in one switch and ALSO dropped every MCP server, --mcp-config included (proven: the tool was absent), so the pipeline's tools could not be the agent's tools under it. Sign-in survives (the subscription, not an API key); --bare would not.",
+      "env": {
+        "ANTHROPIC_BASE_URL": "mockBaseUrl",
+        "CLAUDE_CODE_DISABLE_CLAUDE_MDS": "hostClaudeMdOff",
+        "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "hostAutoMemoryOff",
+        "CLAUDE_CODE_PROMPT_CACHE_TTL": "promptCacheTtl",
+        "CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL": "promptCacheTtl"
+      },
+      "flags": {
+        "--effort": "reasoningEffort",
+        "--autocompact": "autoCompressAt"
+      },
+      "$whyFlags": "Checked against the installed CLI's own --help, not assumed: --effort takes (low, medium, high, xhigh, max) and --autocompact takes auto or a token count. These were declared as CLAUDE_CODE_* env vars that the CLI does not document and that nothing exported.",
+      "$whyNoTurnCap": "maxIterations is deliberately absent. It binds the ReAct loop in src/agent/AgentRunner.ts, which only the `epam run` arm enters; a --print call has no turn cap and the loop is Claude Code's own. Declaring one here would name a knob nothing can turn.",
+      "$whyNoOutputCap": "maxOutputTokens is deliberately unmapped: the installed CLI documents no flag or env for it. It stays declared in modelOverrides so the intent is visible, and is not routed anywhere pretending to work.",
+      "$whyEnvKept": "ANTHROPIC_BASE_URL is a real, load-bearing env var: it is the mock redirect. It was declared here and never exported, so a free run would have looked redirected and reached the paid endpoint.",
+      "$whyNoSilentFlag": "-s is codemie-claude's silent flag and plain `claude` REJECTS it: `echo x | claude -s --print` exits 1 with \"error: unknown option '-s'\". Proven by running it, 2026-08-26, after a --help probe proved nothing (--help and --version short-circuit before option validation, so an invalid flag exits 0 there too). With -s declared, the hub passed it to plain claude, the call failed, and the arm's 2>/dev/null hid the reason — codeline-discovery reported only 'Empty response from ai-run.sh' and the mock3 run aborted with 'codeline scope could not be resolved'. The codemie runner keeps -s: codemie-claude --help documents it as -s, --silent.",
+      "unsetEnv": [
+        "CODEMIE_API_KEY",
+        "CODEMIE_AUTH_TOKEN",
+        "CODEMIE_KEY",
+        "CODEMIE_TOKEN",
+        "COPILOT_API_KEY",
+        "COPILOT_AUTH_TOKEN",
+        "COPILOT_KEY",
+        "COPILOT_TOKEN",
+        "CURSOR_API_KEY",
+        "CURSOR_AUTH_TOKEN",
+        "CURSOR_KEY",
+        "CURSOR_TOKEN",
+        "DASHSCOPE_API_KEY",
+        "DASHSCOPE_AUTH_TOKEN",
+        "DASHSCOPE_KEY",
+        "DASHSCOPE_TOKEN",
+        "EPAM_API_KEY_ANTHROPIC",
+        "EPAM_API_KEY_CLAUDE",
+        "EPAM_API_KEY_CODEMIE",
+        "EPAM_API_KEY_COPILOT",
+        "EPAM_API_KEY_CURSOR",
+        "EPAM_API_KEY_DASHSCOPE",
+        "EPAM_API_KEY_GEMINI",
+        "EPAM_API_KEY_MINIMAX",
+        "EPAM_API_KEY_OPENAI",
+        "EPAM_API_KEY_OPENROUTER",
+        "GEMINI_API_KEY",
+        "GEMINI_AUTH_TOKEN",
+        "GEMINI_KEY",
+        "GEMINI_TOKEN",
+        "MINIMAX_API_KEY",
+        "MINIMAX_AUTH_TOKEN",
+        "MINIMAX_KEY",
+        "MINIMAX_TOKEN",
+        "OPENAI_API_KEY",
+        "OPENAI_AUTH_TOKEN",
+        "OPENAI_KEY",
+        "OPENAI_TOKEN",
+        "OPENROUTER_API_KEY",
+        "OPENROUTER_AUTH_TOKEN",
+        "OPENROUTER_KEY",
+        "OPENROUTER_TOKEN"
+      ],
+      "$whyUnsetEnv": "A REHEARSAL MUST NOT BE ABLE TO SPEND SOMEWHERE ELSE. Under this set the writer once ran provider=minimax with MINIMAX_API_KEY present: the mockBaseUrl redirect covers Anthropic traffic and nothing else, so any other vendor's credential is a live route out. Those are removed. ANTHROPIC_API_KEY and CLAUDE_* are deliberately NOT removed: Claude Code falls back to the OAuth credentials on disk when it finds no key, and that bills for real — the exact inversion this is meant to prevent, recorded in seam-the-subscription-pays-not-the-api-key. The operator's fake key stays, and the redirect is what makes it harmless. The vendors come from llm-channel.json's credentialPattern, so one added there is covered without editing this.",
+      "emitsTraces": true,
+      "$emitsTraces": "Whether model calls made through this runner reach Langfuse. TRUE for every runner: traces are emitted by lib/cost-emitter.js at the cost seam — the point every arm passes through with its model, tokens, cost and timing resolved — not by the TypeScript provider decorator, which only the epam arm reaches. Verified end-to-end 2026-09-04 by driving the real emitter and reading the session back out of Langfuse.",
+      "toolNames": {
+        "read_file": [
+          "Read"
+        ],
+        "list_files": [
+          "Glob"
+        ],
+        "search": [
+          "Grep"
+        ],
+        "fetch_url": [
+          "WebFetch"
+        ],
+        "bash": [
+          "Bash"
+        ],
+        "write_file": [
+          "Write",
+          "Edit"
+        ]
+      },
+      "$whyToolNames": "A SEAM'S TOOL GRANT IS BOUND AT THE RUNNER, LIKE ITS SCHEMA AND ITS BUDGET. Every seam declares a grant kind (none, read-only, execute, write-file...) and it travels as EPAM_ALLOWED_TOOLS; that variable was read in ONE place, src/agent/AgentRunner.ts on the `epam run` arm, so on this runner it bound NOTHING and every seam ran `--print --dangerously-skip-permissions` with the CLI's whole tool set. Run 20260916T225207Z (skyscanner): project-roster-review, declared read-only, ran `find / -iname prd.json` and read five earlier runs' cassettes out of the pipeline repo, then refused the roster for disagreeing with them. The 2026-09-12 roster specialiser, declared write-file, spent ~350 shell calls copying a repository. This map is the runner's own vocabulary for the pipeline's tool names (`claude --help`: --tools takes built-in tool names; \"\" disables all). llm-handler.sh translates the grant through it and passes --tools when the installed CLI advertises the flag. A pipeline tool with no entry here does not exist on this runner and is dropped from the list, said aloud on stderr. A seam with NO grant (kind none) is passed nothing and keeps the CLI's default set: --tools \"\" may also remove the StructuredOutput tool --json-schema requires, and that has not been proven either way, so it is not done blind.",
+      "writeTool": {
+        "name": "Write",
+        "path": "file_path",
+        "content": "content"
+      },
+      "$whyWriteTool": "The rehearsal's stand-in writer delivers by calling the runner's own file-writing tool, and this is that tool's vocabulary for plain Claude Code (recorded sessions: 'Write' {file_path, content}). Declared here so the harness never spells a tool name.",
+      "readTool": {
+        "name": "Read",
+        "path": "file_path"
+      },
+      "$whyReadTool": "Plain Claude Code's Write refuses a file the session has not read ('File has not been read yet. Read it first before writing to it.', £0 brownfield harness run 10, 2026-09-14): a brownfield story's deliverables exist, so the stand-in writer reads each existing one through this tool before it writes, as a model does. Declared beside writeTool so the harness never spells this name either.",
+      "structuredOutputTool": "StructuredOutput",
+      "$whyStructuredOutputTool": "Under --json-schema plain Claude Code declares a tool of this name and REQUIRES the reply to call it ('[structured-output-enforce] You MUST call the StructuredOutput tool', recorded 2026-09-14); a text reply costs a second, enforcement turn per seam and never exercises the runner's structured-output path — the one a real model takes. The rehearsal answers a request that declares this tool by calling it with the seam's stand-in payload.",
+      "$whyEnv": "Each name is a top-level setting of this stack (hostClaudeMdOff, hostAutoMemoryOff, promptCacheTtl), resolved by lib/llm-settings-resolve.js runnerValues and exported for the CLI; an operator overrides one with EPAM_RUNNER_VALUE_<name>. The cache TTL: Claude Code's subagent and workflow calls default to a 5-minute prompt cache; the pipeline's calls repeat the same SI and context for an hour or more, so the documented 1h TTL is declared for both (docs: prompt-caching).",
+      "hostedToolPlugins": [
+        "plugins/codegraph-plugin.js",
+        "plugins/codeline-context-plugin.js",
+        "plugins/dependency-contract-plugin.js",
+        "plugins/dependency-scan-plugin.js",
+        "plugins/secret-scan-plugin.js",
+        "plugins/verification-plugin.js"
+      ],
+      "mcpServer": "pipeline",
+      "$whyHostedToolPlugins": "The pipeline's own tool plugins — the same modules the codemie-web runner hosts — served to this runner's agents as Claude Code tools over MCP (lib/pipeline-tools-mcp.js; the hub passes --mcp-config). Before this an agent on this runner reached codegraph, the search and the package-symbol resolver only as shell scripts through Bash: a read-only seam could not call them at all, and plan mode denies such Bash calls. A 'safe' plugin tool is annotated read-only, which is what lets plan mode run it.",
+      "planModeChannel": {
+        "modeFlag": "--permission-mode",
+        "planValue": "plan",
+        "sessionFlag": "--session-id",
+        "resumeFlag": "--resume"
+      },
+      "$whyPlanModeChannel": "How a plan pass is made on this runner (llm-handler.sh; lib/plan-mode.js decides WHETHER a seam plans): Claude Code's own plan mode. Proven on 2.1.310 (2026-10-24): `--permission-mode plan` under --print returns the plan as the result and writes nothing — the agent may read, search and call read-only tools, so the plan is grounded; the answer is then made in the same session with `--resume <session-id>` and the ordinary permissions. A runner that declares no channel gets the hub's prose pass (the plan written with no tools)."
+    }
+  },
+  "mockBaseUrl": "http://localhost:1080",
+  "$mockBaseUrl": "Where MockServer listens. Declared here so no script spells it — the same rule every other value in this layer follows.",
+  "rehearsal": true,
+  "$rehearsalWhy": "A run on this set spends nothing and answers from recordings and stand-ins. Every recorder stamps its traces rehearsal:true (lib/langfuse-emit.js), and the mock loader never replays a rehearsal's own traces as captures — on 2026-09-13 a stand-in reply recorded by one rehearsal was served to the next as a 'recorded' turn, and the roster stage failed on its own echo three launches running.",
+  "wire": {
+    "$comment": "HOW THE STAND-IN PUTS A TOOL CALL ON THE WIRE. A vendor streams a tool call as many `function.arguments` (or `input_json_delta`) fragments, and the body reaches the client in HTTP chunks that end wherever the socket ends them — inside an event as often as not. Until 2026-09-15 the stand-in served every call whole, in one read: a shape no vendor sends and the one shape the client's stream parser could never fail on. Run 20260915T101555Z lost 32 write_file calls' arguments to exactly that parser ($4.18, nothing delivered) while every harness cell was green. argumentDeltaChars is the fragment size; chunkBytes is the HTTP chunk size. Both are deliberately unaligned with any event length so boundaries fall inside events.",
+    "argumentDeltaChars": 97,
+    "chunkBytes": 333
+  },
+  "hostClaudeMdOff": "1",
+  "hostAutoMemoryOff": "1",
+  "promptCacheTtl": "1h",
+  "$whyHostContextOff": "Values for the claude runner's env declaration (see runners.claude.$whyEnv): the host's CLAUDE.md and auto-memory stay out of every agent call; the prompt cache lives 1h."
+}

package/orchestrations/config/llm-defaults.openrouter.json

@@ -0,0 +1,279 @@
+{
+  "$comment": "THE OPENROUTER/MINIMAX PROVIDER SET. Set-SPECIFIC declarations only — which models, which ladders, which runner. Set-INDEPENDENT budgets (effortTiers, roleOverrides, outputTokenFloors) stay in llm-defaults.json and are shared by every set, so swapping providers never changes how much budget a tier gets.",
+  "$provenance": "ladders, ladderTierOrder and modelOverrides were MOVED VERBATIM from projects/metrolinx/llm-settings.json on 2026-08-25 — generated from that file, not retyped. metrolinx is the live client codeline, so its chain is the one the openrouter stack keeps. mock3, hello-dolly and skyscanner previously topped out at glm-5.2/5.1 and now inherit glm-5.3: a deliberate convergence, recorded here rather than discovered later.",
+  "ladderTierOrder": [
+    "medium",
+    "high",
+    "highest"
+  ],
+  "ladders": {
+    "high": {
+      "modelLadder": [
+        {
+          "from": "MiniMax-M2.5",
+          "to": "MiniMax-M3"
+        },
+        {
+          "from": "MiniMax-M3",
+          "to": "z-ai/glm-5.2"
+        },
+        {
+          "from": "z-ai/glm-5.1",
+          "to": "z-ai/glm-5.2"
+        },
+        {
+          "from": "z-ai/glm-5.2",
+          "to": "moonshotai/kimi-k3"
+        },
+        {
+          "from": "moonshotai/kimi-k2.5",
+          "to": "moonshotai/kimi-k3"
+        }
+      ],
+      "startModel": "MiniMax-M3"
+    },
+    "medium": {
+      "modelLadder": [
+        {
+          "from": "MiniMax-M2.7-highspeed",
+          "to": "MiniMax-M3"
+        },
+        {
+          "from": "MiniMax-M2.7",
+          "to": "MiniMax-M3"
+        },
+        {
+          "from": "MiniMax-M2.5",
+          "to": "MiniMax-M3"
+        },
+        {
+          "from": "MiniMax-M3",
+          "to": "z-ai/glm-5.3"
+        },
+        {
+          "from": "z-ai/glm-5.1",
+          "to": "z-ai/glm-5.3"
+        },
+        {
+          "from": "z-ai/glm-5.2",
+          "to": "z-ai/glm-5.3"
+        }
+      ],
+      "startModel": "MiniMax-M2.7-highspeed",
+      "_why": "M2.5 is legacy. M2.7 scores materially higher on multi-file and long-horizon work (NL2Repo 26.6 -> 39.8, MLE Bench Lite +15pts) and the -highspeed variant is documented as producing IDENTICAL results, only faster — so it is a free latency win, not a quality trade. The chain ends at glm-5.3 rather than 5.2 because 5.3's gains concentrate in agent-shaped tasks, which is what a seam that has already escalated twice is struggling with."
+    },
+    "highest": {
+      "modelLadder": [
+        {
+          "from": "z-ai/glm-5.3",
+          "to": "moonshotai/kimi-k3"
+        },
+        {
+          "from": "z-ai/glm-5.2",
+          "to": "z-ai/glm-5.3"
+        },
+        {
+          "from": "z-ai/glm-5.1",
+          "to": "z-ai/glm-5.3"
+        },
+        {
+          "from": "MiniMax-M2.7-highspeed",
+          "to": "MiniMax-M3"
+        },
+        {
+          "from": "MiniMax-M2.7",
+          "to": "MiniMax-M3"
+        },
+        {
+          "from": "MiniMax-M2.5",
+          "to": "MiniMax-M3"
+        },
+        {
+          "from": "MiniMax-M3",
+          "to": "z-ai/glm-5.3"
+        },
+        {
+          "from": "moonshotai/kimi-k2.5",
+          "to": "moonshotai/kimi-k3"
+        }
+      ],
+      "startModel": "z-ai/glm-5.3",
+      "_why": "glm-5.3 shares 5.2's base model; every gain is post-training on executable environments and long-horizon tasks — Terminal-Bench 3.0 4.6 -> 28.3, DeepSWE 46.2 -> 66.9, SWE-Marathon 19.4 -> 42.5. It also reaches a higher score with ~22% FEWER output tokens on hard work, which offsets most of the 45% higher per-token price. All vendor-reported: no independent reproduction exists yet."
+    }
+  },
+  "modelOverrides": {
+    "minimax-m2.5": {
+      "matchOn": "model",
+      "matchSubstring": "MiniMax-M2.5",
+      "reasoningEffort": "medium",
+      "maxIterations": 45,
+      "autoCompressAt": 64000,
+      "autoCompressEveryNIterations": 15,
+      "topP": 0.85,
+      "temperature": 0.2,
+      "miniTier": true,
+      "charsPerToken": 4,
+      "maxOutputTokens": 128000,
+      "outputPricePerMillion": 1.08
+    },
+    "minimax-m3": {
+      "matchOn": "model",
+      "matchSubstring": "MiniMax-M3",
+      "reasoningEffort": "high",
+      "maxIterations": 120,
+      "autoCompressAt": 180000,
+      "topP": 0.85,
+      "temperature": 0.2,
+      "charsPerToken": 4,
+      "maxOutputTokens": 512000,
+      "outputPricePerMillion": 1.2
+    },
+    "glm-5.2": {
+      "matchOn": "model",
+      "matchSubstring": "glm-5.2",
+      "reasoningEffort": "high",
+      "maxIterations": 120,
+      "autoCompressAt": 180000,
+      "topP": 0.95,
+      "temperature": 0.9,
+      "providerOrder": [
+        "CoreWeave"
+      ],
+      "charsPerToken": 4,
+      "maxOutputTokens": 131072,
+      "outputPricePerMillion": 2.0416
+    },
+    "kimi-k2.5": {
+      "matchOn": "model",
+      "matchSubstring": "kimi-k2.5",
+      "temperature": 1,
+      "reasoningEffort": "medium",
+      "maxIterations": 60,
+      "autoCompressAt": 128000,
+      "autoCompressEveryNIterations": 20,
+      "topP": 1,
+      "temperatureLocked": true,
+      "charsPerToken": 4,
+      "maxOutputTokens": 235929,
+      "outputPricePerMillion": 2.25
+    },
+    "kimi-k3": {
+      "matchOn": "model",
+      "matchSubstring": "kimi-k3",
+      "temperature": 1,
+      "reasoningEffort": "max",
+      "maxIterations": 150,
+      "autoCompressAt": 400000,
+      "topP": 1,
+      "temperatureLocked": true,
+      "providerOrder": [
+        "Moonshot AI"
+      ],
+      "charsPerToken": 4,
+      "maxOutputTokens": 943718,
+      "outputPricePerMillion": 15.0
+    },
+    "minimax-m2.7": {
+      "matchOn": "model",
+      "matchSubstring": "MiniMax-M2.7",
+      "_why": "Replaces MiniMax-M2.5 as the medium tier's start. maxIterations is 90, not M2.5's 45: 45 was the outlier in this file (M3 120, glm 120, kimi-k3 150) and M2.7's advantage is precisely on the long-horizon work that needs room to converge — capping the stronger model at the weaker one's budget would throw the upgrade away. autoCompressAt is 150000 against a 204800 context: compaction destroys the cacheable prefix, so it must be an overflow guard near the ceiling, never a token-saving device. Substring is 'MiniMax-M2.7' so it matches the -highspeed variant too.",
+      "reasoningEffort": "medium",
+      "maxIterations": 90,
+      "autoCompressAt": 150000,
+      "autoCompressEveryNIterations": 15,
+      "topP": 0.85,
+      "temperature": 0.2,
+      "miniTier": true,
+      "charsPerToken": 4,
+      "maxOutputTokens": 131072,
+      "outputPricePerMillion": 1.2
+    },
+    "glm-5.3": {
+      "matchOn": "model",
+      "matchSubstring": "glm-5.3",
+      "_why": "Mirrors glm-5.2's sampling (same base model, so temperature/topP carry over) with more iteration room at 150, because this is now the highest tier's start and has only ONE rung above it. autoCompressAt raised to 300000 against a 1048576 context — 5.2's 180000 was conservative and every compaction destroys the cache. providerOrder is Z.AI because OpenRouter lists exactly one endpoint for this model; copying 5.2's CoreWeave pin would have failed every call.",
+      "reasoningEffort": "high",
+      "maxIterations": 150,
+      "autoCompressAt": 300000,
+      "topP": 0.95,
+      "temperature": 0.9,
+      "providerOrder": [
+        "Z.AI"
+      ],
+      "charsPerToken": 4,
+      "maxOutputTokens": 131072,
+      "outputPricePerMillion": 2.64
+    },
+    "$miniTierWhy": "miniTier marks the cheap, fast rung — the models that are quick but limited in generation capacity. It was decided in engine code by sniffing vendor naming habits (-mini, -flash, -haiku, minimax-m2), which breaks in both directions: a cheap model named differently read as capable, and a capable model containing -flash read as cheap. The set that declares the model declares its tier.",
+    "$whyCharsPerToken": "INPUT CAPACITY IN CHARACTERS. autoCompressAt is the models input ceiling in TOKENS; callers that must size a payload measure it in characters. The ratio belongs with the model, because it is a property of that models tokenizer, not of any caller. Declared so a caller derives its budget instead of inventing one: the roster review carried a literal 60000 in code, which split a 276KB roster into six calls and failed the whole review whenever any one of them answered off-schema.",
+    "glm-5.1": {
+      "matchOn": "model",
+      "matchSubstring": "glm-5.1",
+      "maxOutputTokens": 128000,
+      "_why": "created by refresh-model-limits.sh: a ladder rung with no override is capped by its tier, which is how truncation returns for one rung while the others are free.",
+      "outputPricePerMillion": 3.036
+    }
+  },
+  "runners": {
+    "claude": {
+      "siChannel": {
+        "flag": "--append-system-prompt-file"
+      },
+      "$whySiChannel": "Claude Code's own --append-system-prompt-file (claude --help, 2.1.282): the agent's SI as a system prompt, separate from the task on stdin.",
+      "$whyFlags": "The same two knobs every stack exposes, so a seam's declared effort and compaction reach the runner here exactly as they do on the others. Naming them per set rather than in engine code is what makes a swap a config edit.",
+      "alwaysFlags": [
+        "--setting-sources",
+        "",
+        "--strict-mcp-config",
+        "--disable-slash-commands",
+        "--settings",
+        "{\"includeGitInstructions\":false}"
+      ],
+      "$whyAlwaysFlags": "The agent receives the pipeline's SI and task, nothing of the host — through Claude Code's own interface, each piece by its own switch (proven on 2.1.310, 2026-10-24, with a CLAUDE.md canary in the working folder): --setting-sources \"\" loads no user, project or local settings (so none of the host's hooks, permissions or CLAUDE.md); CLAUDE_CODE_DISABLE_CLAUDE_MDS and CLAUDE_CODE_DISABLE_AUTO_MEMORY (env below) keep the working folder's CLAUDE.md and the host's auto-memory out; --disable-slash-commands drops the skills; includeGitInstructions:false drops the git status; --strict-mcp-config makes the pipeline's MCP server (hostedToolPlugins, lib/pipeline-tools-mcp.js) the ONLY server. --safe-mode did all of this in one switch and ALSO dropped every MCP server, --mcp-config included (proven: the tool was absent), so the pipeline's tools could not be the agent's tools under it. Sign-in survives (the subscription, not an API key); --bare would not.",
+      "env": {
+        "CLAUDE_CODE_DISABLE_CLAUDE_MDS": "hostClaudeMdOff",
+        "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "hostAutoMemoryOff",
+        "CLAUDE_CODE_PROMPT_CACHE_TTL": "promptCacheTtl",
+        "CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL": "promptCacheTtl"
+      },
+      "flags": {
+        "--effort": "reasoningEffort",
+        "--autocompact": "autoCompressAt"
+      },
+      "$whyNoUnsetEnv": "Deliberately empty. Scrubbing ANTHROPIC_API_KEY sends Claude Code to the OAuth credentials on disk and bills for real — recorded in seam-the-subscription-pays-not-the-api-key. This stack authenticates with OPENROUTER_API_KEY and has no reason to take anything away.",
+      "unsetEnv": [],
+      "emitsTraces": true,
+      "$emitsTraces": "Whether model calls made through this runner reach Langfuse. TRUE for every runner: traces are emitted by lib/cost-emitter.js at the cost seam — the point every arm passes through with its model, tokens, cost and timing resolved — not by the TypeScript provider decorator, which only the epam arm reaches. Verified end-to-end 2026-09-04 by driving the real emitter and reading the session back out of Langfuse.",
+      "$whyEnv": "Each name is a top-level setting of this stack (hostClaudeMdOff, hostAutoMemoryOff, promptCacheTtl), resolved by lib/llm-settings-resolve.js runnerValues and exported for the CLI; an operator overrides one with EPAM_RUNNER_VALUE_<name>. The cache TTL: Claude Code's subagent and workflow calls default to a 5-minute prompt cache; the pipeline's calls repeat the same SI and context for an hour or more, so the documented 1h TTL is declared for both (docs: prompt-caching).",
+      "hostedToolPlugins": [
+        "plugins/codegraph-plugin.js",
+        "plugins/codeline-context-plugin.js",
+        "plugins/dependency-contract-plugin.js",
+        "plugins/dependency-scan-plugin.js",
+        "plugins/secret-scan-plugin.js",
+        "plugins/verification-plugin.js"
+      ],
+      "mcpServer": "pipeline",
+      "$whyHostedToolPlugins": "The pipeline's own tool plugins — the same modules the codemie-web runner hosts — served to this runner's agents as Claude Code tools over MCP (lib/pipeline-tools-mcp.js; the hub passes --mcp-config). Before this an agent on this runner reached codegraph, the search and the package-symbol resolver only as shell scripts through Bash: a read-only seam could not call them at all, and plan mode denies such Bash calls. A 'safe' plugin tool is annotated read-only, which is what lets plan mode run it.",
+      "planModeChannel": {
+        "modeFlag": "--permission-mode",
+        "planValue": "plan",
+        "sessionFlag": "--session-id",
+        "resumeFlag": "--resume"
+      },
+      "$whyPlanModeChannel": "How a plan pass is made on this runner (llm-handler.sh; lib/plan-mode.js decides WHETHER a seam plans): Claude Code's own plan mode. Proven on 2.1.310 (2026-10-24): `--permission-mode plan` under --print returns the plan as the result and writes nothing — the agent may read, search and call read-only tools, so the plan is grounded; the answer is then made in the same session with `--resume <session-id>` and the ordinary permissions. A runner that declares no channel gets the hub's prose pass (the plan written with no tools)."
+    }
+  },
+  "$whyRunners": "THE SWAP MUST NOT INHERIT THE PREVIOUS STACK'S RUNNER. apply_runner_settings is called with the BASENAME of CLAUDE_CMD, which is 'claude' under every set, so a set declaring no runner by that name resolves nothing and the flags, env and scrubs of whatever ran before are simply carried over. claude, codemie and mockserver each declared one; this set did not, which made hot swap 2 the one stack that silently kept another stack's settings.",
+  "finalFallback": {
+    "$why": "Applies after ladder exhaustion. The other 3 sets (claude, codemie, mockserver) all declare one; this set previously did not, an undocumented inconsistency (change-log/SEAM-CONSISTENCY-ANALYSIS.md Section 6). Routed WITHIN this set rather than escaping to paid claude: unlike mockserver (which is a no-pay mock endpoint by construction regardless of the provider string it declares — see its own finalFallback.$why), this is the live production openrouter/minimax stack, where a provider:\"claude\" fallback would be a real, unnoticed charge on a different vendor's account. MiniMax-M3 is chosen because it is a genuinely different model family from the top rung of every ladder here (high and highest both top out at moonshotai/kimi-k3, medium at z-ai/glm-5.3), so it is a real second answer rather than a retry of the model that just failed — mirroring the claude/codemie sets' own stated reasoning for choosing sonnet-5 over their own top rungs.",
+    "$whyNotYetLive": "As of this writing, nothing in the runtime ladder-exhaustion path (llm-handler.sh, claude.sh, brownfield-repro-test-writer.sh) reads finalFallback — exhaustion retries the same rung instead. agent-check.js's dry-run cost estimator is the only reader, and even there this is unreachable while any ladder tier has a startModel (all of them do). Declared for correctness and for whenever that wiring exists, not because a run can reach this today.",
+    "model": "MiniMax-M3",
+    "provider": "openrouter"
+  },
+  "$whyModelOutputLimits": "maxOutputTokens on each model override is the PROVIDER'S declared max_completion_tokens, written by scripts/refresh-model-limits.sh and never by hand. A cap below the model's own maximum has exactly one effect — truncation — because spend is bounded by costControls.storyBudgetHardLimitUsd, not by output length. Re-run the script when the provider's limits change.",
+  "hostClaudeMdOff": "1",
+  "hostAutoMemoryOff": "1",
+  "promptCacheTtl": "1h",
+  "$whyHostContextOff": "Values for the claude runner's env declaration (see runners.claude.$whyEnv): the host's CLAUDE.md and auto-memory stay out of every agent call; the prompt cache lives 1h."
+}

package/orchestrations/prompts/templates/plan-execute.json

@@ -0,0 +1,16 @@
+{
+  "$why": [
+    "THE EXECUTE PASS — the fragment appended to the agent's task after its plan (llm-handler.sh). Moved out of the hub's printf lines 2026-10-24 with plan-pass.json."
+  ],
+  "body": "\n\n---\nYOUR PLAN (you wrote this a moment ago):\n__PLAN__\n\nNow produce the final answer, in exactly the format the task above\nrequires. If carrying out the plan showed it to be wrong, say so and\nanswer correctly rather than following it.\n",
+  "description": "Appended to an agent's task after its plan pass: the plan, and the instruction to answer now.",
+  "id": "plan-execute",
+  "placeholders": [
+    "__PLAN__"
+  ],
+  "version": 1,
+  "seams": [
+    "*"
+  ],
+  "layer": "engine"
+}

package/orchestrations/prompts/templates/plan-pass.json

@@ -0,0 +1,24 @@
+{
+  "$why": [
+    "THE PLAN PASS — the fragment appended to an agent's task when its call plans first (llm-handler.sh; lib/plan-mode.js decides whether).",
+    "",
+    "It lived as printf lines inside the hub since the plan pass was built; a prompt in code is a prompt nothing reviews (one prompt = one JSON file).",
+    "Moved here 2026-10-24 when the pass gained Claude Code's own plan mode: the tool note differs by how the plan is made — in plan mode the agent may",
+    "read and search for real (nothing it does there changes anything); in the prose pass it has no tools and must not pretend to."
+  ],
+  "bodies": {
+    "prompt": "\n\n---\nBEFORE YOU ANSWER: state your PLAN, and nothing else.\n\nSay what you believe the answer is going to be and WHY, name the\nspecific targets you will examine or produce, and state how you will\nknow if you are wrong. If the task above sets a requirement your\nanswer must satisfy, say in one line how your plan satisfies it.\n\nDo NOT produce the final answer yet. Do NOT emit the output format\nthe task asks for. Plain prose, at most 200 words.\n\n__TOOL_NOTE__",
+    "tool-note-plan-mode": "You are in plan mode: you may read, search and query to ground the plan, and nothing you do here changes anything. The answer that follows this plan is made in a second step, with your full tools.",
+    "tool-note-no-tools": "You have NO tools available for THIS plan and cannot call any — do not\nemit tool-call syntax (<tool_call>, <tool_use>, <function_call>) or\ninvent what a tool would return. Nothing executes it, so any such text\nis fiction, not evidence — state your INTENT to examine a target, not a\nfabricated result from having done so. If tools are available for the\nanswer that follows this plan, you will use them for real then."
+  },
+  "description": "Appended to an agent's task for the plan pass; the tool note names how this plan is made.",
+  "id": "plan-pass",
+  "placeholders": [
+    "__TOOL_NOTE__"
+  ],
+  "version": 1,
+  "seams": [
+    "*"
+  ],
+  "layer": "engine"
+}

package/orchestrations/scripts/lib/llm-settings-resolve.js

@@ -269,6 +269,10 @@ function resolveRunner(runnerName, { projectConfigDir, defaultsFile } = {}) {
     siChannel: declared.siChannel && typeof declared.siChannel === 'object' ? declared.siChannel : null,
     // the pipeline's own tool plugins this runner hosts (plugins/*-plugin.js), served to the agent as its tools (lib/pipeline-tools-mcp.js)
     hostedToolPlugins: Array.isArray(declared.hostedToolPlugins) ? declared.hostedToolPlugins : [],
+    // the MCP server name the hub registers for those plugins (--mcp-config); a tool is then granted as mcp__<server>__<tool>
+    mcpServer: typeof declared.mcpServer === 'string' ? declared.mcpServer : '',
+    // how a plan pass is made on this runner (the CLI's own plan mode and session resume), or null for the hub's prose pass
+    planModeChannel: declared.planModeChannel && typeof declared.planModeChannel === 'object' ? declared.planModeChannel : null,
   };
 }
 /** Every runner the active stack declares, by name. */
@@ -331,8 +335,20 @@ function runnerValues(runnerName, { projectConfigDir, defaultsFile } = {}) {
   // silently skipped, so the declaration named knobs nothing could fill.
   // unsetEnv carries NAMES ONLY — there is no value to resolve, because the whole point is
   // that the variable must not be there. It passes through untouched.
+  // THE PIPELINE'S OWN TOOLS, BY THE NAME THE CLI KNOWS THEM. A runner that hosts the pipeline's tool plugins over an MCP
+  // server (lib/pipeline-tools-mcp.js) is granted them as mcp__<server>__<tool> — derived from the plugins it declares, so a
+  // seam's grant 'codegraph_query' reaches the CLI's --tools without anyone listing the name twice.
+  const toolNames = { ...runner.toolNames };
+  if (runner.mcpServer && runner.hostedToolPlugins.length) {
+    // eslint-disable-next-line global-require
+    const { toolsOf } = require('./pipeline-tools-mcp.js');
+    const orch = path.join(__dirname, '..', '..');
+    for (const t of toolsOf(runner.hostedToolPlugins.map((m) => path.resolve(orch, m)))) {
+      if (!toolNames[t.name]) toolNames[t.name] = [`mcp__${runner.mcpServer}__${t.name}`];
+    }
+  }
   const out = { env: {}, flags: {}, alwaysFlags: runner.alwaysFlags, unsetEnv: runner.unsetEnv,
-                envNames: {}, flagNames: {}, toolNames: runner.toolNames, siChannel: runner.siChannel };
+                envNames: {}, flagNames: {}, toolNames, siChannel: runner.siChannel, mcpServer: runner.mcpServer, hostedToolPlugins: runner.hostedToolPlugins };
   for (const [k, name] of Object.entries(runner.env)) { out.env[k] = valueFor(name); out.envNames[k] = name; }
   for (const [k, name] of Object.entries(runner.flags)) { out.flags[k] = valueFor(name); out.flagNames[k] = name; }
   return out;

package/orchestrations/scripts/lib/plan-mode.js

@@ -0,0 +1,36 @@
+'use strict';
+// WHETHER THIS AGENT'S CALL PLANS FIRST (operator, 2026-10-24: "Plan mode can be used for any agent not just writer" / "If plan
+// mode helps use it"). One answer for every seam, read from three places, highest first:
+//   1. EPAM_PLAN_EXECUTE_SEAMS   the operator's list of seams or agents that plan, comma-separated (a run's config.env)
+//   2. the registry              the seam's own `planMode: true|false` (agents/invocation-profiles.json)
+//   3. EPAM_PLAN_EXECUTE         the project-wide switch the hub has always read (installs set 0 since 2026-09-08)
+// How the plan is made is the RUNNER's fact (the declaration's planModeChannel — Claude Code's own --permission-mode plan and
+// --resume, or the hub's prose pass where a runner has none); this module only answers whether.
+const CLI = process.argv[1] === __filename;
+
+function planModeFor(agent, { env = process.env, registryFile } = {}) {
+  const listed = String(env.EPAM_PLAN_EXECUTE_SEAMS || '').split(',').map((s) => s.trim()).filter(Boolean);
+  let seam = '';
+  try {
+    // eslint-disable-next-line global-require
+    const si = require('./seam-invocation.js');
+    const file = registryFile || si.registryPath();
+    seam = agent ? si.resolveSeam(agent, file) : '';
+    if (listed.length && (listed.includes(agent) || listed.includes(seam))) return { plan: true, why: `EPAM_PLAN_EXECUTE_SEAMS names ${listed.includes(agent) ? agent : seam}` };
+    const profile = seam ? ((JSON.parse(require('fs').readFileSync(file, 'utf8')).profiles || {})[seam] || {}) : {};
+    if (profile.planMode === true || profile.planMode === false) return { plan: profile.planMode, why: `the registry: seam ${seam} planMode=${profile.planMode}` };
+  } catch (e) {
+    if (listed.length && listed.includes(agent)) return { plan: true, why: `EPAM_PLAN_EXECUTE_SEAMS names ${agent}` };
+    // an unresolved seam answers from the project-wide switch, as the hub always did
+  }
+  const global = String(env.EPAM_PLAN_EXECUTE === undefined ? '1' : env.EPAM_PLAN_EXECUTE) === '1';
+  return { plan: global, why: `EPAM_PLAN_EXECUTE=${env.EPAM_PLAN_EXECUTE === undefined ? '(unset → 1)' : env.EPAM_PLAN_EXECUTE}` };
+}
+
+if (CLI) {
+  const r = planModeFor(process.argv[2] || process.env.EPAM_AGENT_NAME || '');
+  process.stdout.write(r.plan ? '1' : '0');
+  if (process.argv.includes('--why')) process.stderr.write(`${r.why}\n`);
+}
+
+module.exports = { planModeFor };

package/orchestrations/scripts/llm-handler.sh

@@ -38,6 +38,7 @@ declare -F resolve_operator_cli >/dev/null 2>&1 && CLAUDE_CMD="$(resolve_operato
 # Providers that are plugins (config/providers.json runnerPlugin) — see lib/provider-plugin.sh.
 . "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/provider-plugin.sh"
 . "$_SCRIPT_DIR_AIRUN/lib/story-retry-state.sh"
+. "$_SCRIPT_DIR_AIRUN/lib/render-engine-prompt.sh"
 # THE HUB READS ITS OWN CLOCKS. Every call path used EPAM_TIMEOUT_SECS / EPAM_PLAN_TIMEOUT_SECS and
 # relied on the CALLER having loaded them; a caller that had not (a harness, a one-off, a seam run
 # outside the orchestrator) died under `set -u` before the runner was reached. They are loaded
@@ -255,6 +256,18 @@ run_provider_once() {
   local model_args=()
   [ -n "$AI_MODEL" ] && model_args=(--model "$AI_MODEL")
 
+  # HOW THIS CALL IS PERMITTED. The plan pass of a runner with a plan-mode channel (its declaration, resolved by the parent
+  # into EPAM_PLAN_CHANNEL) runs in the CLI's own plan mode under a session id the parent minted — the CLI then returns the
+  # plan and changes nothing; the answer is made in that session (resume) with the ordinary permissions.
+  local _perm_args=(--dangerously-skip-permissions)
+  local _pm_mode _pm_value _pm_session _pm_resume
+  read -r _pm_mode _pm_value _pm_session _pm_resume <<< "${EPAM_PLAN_CHANNEL:-}"
+  if [ -n "${EPAM_PLAN_SESSION_NEW:-}" ] && [ -n "$_pm_mode" ]; then
+    _perm_args=("$_pm_mode" "$_pm_value" "$_pm_session" "$EPAM_PLAN_SESSION_NEW")
+  elif [ -n "${EPAM_PLAN_SESSION_RESUME:-}" ] && [ -n "$_pm_resume" ]; then
+    _perm_args+=("$_pm_resume" "$EPAM_PLAN_SESSION_RESUME")
+  fi
+
   # WHAT THE STACK DECLARED FOR THIS RUNNER — through the SHIM, not a second copy of it.
   #
   # lib/runner-settings.sh already resolves a runner declaration into exported env and a
@@ -345,6 +358,29 @@ run_provider_once() {
       fi
     fi
 
+    # THE PIPELINE'S OWN TOOLS AS THE CLI'S TOOLS (operator, 2026-10-24: "not using the proper interface is not permitted").
+    # A runner that hosts the pipeline's tool plugins over an MCP server (its declaration: hostedToolPlugins + mcpServer;
+    # lib/pipeline-tools-mcp.js) is handed that server with the flag the installed CLI advertises; the seam's grant names
+    # the tools (mcp__<server>__<tool>, derived in lib/llm-settings-resolve.js). The config names the runner, the project
+    # and this node, nothing of the host. --strict-mcp-config (the declaration's alwaysFlags) keeps it the ONLY server.
+    local _mcp_runner _mcp_file=""
+    _mcp_runner="$(runner_name_for "${PRIMARY_PROVIDER:-}" "$(basename "$CLAUDE_CMD")")"
+    # the declaration first (a file read), the CLI's --help only for a runner that declares a server
+    if [ -n "$_mcp_runner" ] \
+       && EPAM_RUNNER="$_mcp_runner" "${NODE_BIN:-node}" -e 'const r = require(process.argv[1] + "/lib/llm-settings-resolve.js").resolveRunner(process.env.EPAM_RUNNER, { projectConfigDir: process.env.EPAM_PROJECT_CONFIG_DIR || undefined }); process.exit(r && r.mcpServer && r.hostedToolPlugins.length ? 0 : 1);' "$_SCRIPT_DIR_AIRUN" 2>/dev/null \
+       && "$(runner_bin_for "${PRIMARY_PROVIDER:-}" "$CLAUDE_CMD")" --help 2>/dev/null | grep -q -- '--mcp-config'; then
+      _mcp_file="$(EPAM_RUNNER="$_mcp_runner" "${NODE_BIN:-node}" -e '
+        const r = require(process.argv[1] + "/lib/llm-settings-resolve.js").resolveRunner(process.env.EPAM_RUNNER, { projectConfigDir: process.env.EPAM_PROJECT_CONFIG_DIR || undefined });
+        if (!r || !r.mcpServer || !r.hostedToolPlugins.length) process.exit(0);
+        const fs = require("fs"); const path = require("path");
+        const dir = process.env.LOG_DIR && fs.existsSync(process.env.LOG_DIR) ? process.env.LOG_DIR : require("os").tmpdir();
+        const file = path.join(dir, `pipeline-mcp-${process.env.EPAM_RUNNER}.json`);
+        fs.writeFileSync(file, JSON.stringify(require(process.argv[1] + "/lib/pipeline-tools-mcp.js").mcpConfig(process.env.EPAM_RUNNER, process.execPath)));
+        process.stdout.write(file);
+      ' "$_SCRIPT_DIR_AIRUN" 2>/dev/null)" || _mcp_file=""
+      [ -n "$_mcp_file" ] && runner_args+=(--mcp-config "$_mcp_file")
+    fi
+
 
   # A PROVIDER THAT IS A PLUGIN answers through its plugin (config/providers.json runnerPlugin;
   # lib/provider-plugin.sh). Its vendor facts live in the plugin; this names no provider. The result
@@ -383,7 +419,7 @@ run_provider_once() {
           # aborted three steps later on "codeline scope could not be resolved". The actual
           # message was `error: unknown option '-s'`.
           local _cc_err; _cc_err="$(mktemp "${TMPDIR:-/tmp}/claude-err-XXXXXX")"
-          "$CLAUDE_CMD" --print --output-format json --dangerously-skip-permissions "${model_args[@]}" ${runner_args[@]+"${runner_args[@]}"} \
+          "$CLAUDE_CMD" --print --output-format json "${_perm_args[@]}" "${model_args[@]}" ${runner_args[@]+"${runner_args[@]}"} \
               < "$PROMPT_FILE" > "$_json_out" 2>"$_cc_err"
           local _cc_rc=$?
           if [ ! -s "$_json_out" ] && [ -s "$_cc_err" ]; then
@@ -399,7 +435,7 @@ run_provider_once() {
           # are kept first; then the CLI's own status is the arm's.
           [ "$_cc_rc" -eq 0 ] || return "$_cc_rc"
         else
-          "$CLAUDE_CMD" --print --output-format text --dangerously-skip-permissions "${model_args[@]}" ${runner_args[@]+"${runner_args[@]}"} < "$PROMPT_FILE"
+          "$CLAUDE_CMD" --print --output-format text "${_perm_args[@]}" "${model_args[@]}" ${runner_args[@]+"${runner_args[@]}"} < "$PROMPT_FILE"
         fi
       fi
       ;;
@@ -419,7 +455,7 @@ run_provider_once() {
         # or budget failure, not a format one)" and aborted the run, when the real fault was a
         # one-line parse error visible right here.
         local _cm_err; _cm_err="$(mktemp "${TMPDIR:-/tmp}/codemie-err-XXXXXX")"
-        codemie-claude --print --output-format json --dangerously-skip-permissions "${model_args[@]}" ${runner_args[@]+"${runner_args[@]}"} \
+        codemie-claude --print --output-format json "${_perm_args[@]}" "${model_args[@]}" ${runner_args[@]+"${runner_args[@]}"} \
             < "$PROMPT_FILE" > "$_cm_json" 2>"$_cm_err"
         local _cm_rc=$?
 
@@ -468,7 +504,7 @@ run_provider_once() {
         # are kept first; then the CLI's own status is the arm's.
         [ "$_cm_rc" -eq 0 ] || return "$_cm_rc"
       else
-        codemie-claude --print --output-format text --dangerously-skip-permissions "${model_args[@]}" ${runner_args[@]+"${runner_args[@]}"} < "$PROMPT_FILE"
+        codemie-claude --print --output-format text "${_perm_args[@]}" "${model_args[@]}" ${runner_args[@]+"${runner_args[@]}"} < "$PROMPT_FILE"
       fi
       ;;
     codex)
@@ -742,92 +778,73 @@ if [ -n "$_LADDER_AGENT" ] && [ -n "${LOG_DIR:-}" ] && [ "${_EPAM_IN_PLAN_PASS:-
 fi
 
 _plan_cost_json=""
-if [ "${EPAM_PLAN_EXECUTE:-1}" = "1" ] && [ "${_EPAM_IN_PLAN_PASS:-0}" != "1" ]; then
+# WHETHER THIS AGENT PLANS FIRST is one answer for every seam (lib/plan-mode.js: the operator's EPAM_PLAN_EXECUTE_SEAMS, the
+# seam's registry planMode, then EPAM_PLAN_EXECUTE). HOW is the runner's fact: a declared planModeChannel is Claude Code's own
+# plan mode — the plan made with the seam's read tools under a session the hub mints, the answer made in that session — and
+# a runner without one gets the prose pass (the plan written with no tools), as before.
+_plan_on="$("${NODE_BIN:-node}" "$_SCRIPT_DIR_AIRUN/lib/plan-mode.js" "${EPAM_AGENT_NAME:-}" 2>/dev/null || printf '%s' "${EPAM_PLAN_EXECUTE:-1}")"
+if [ "$_plan_on" = "1" ] && [ "${_EPAM_IN_PLAN_PASS:-0}" != "1" ]; then
+  _plan_channel=""; _plan_session=""
+  _plan_runner="$(runner_name_for "${PRIMARY_PROVIDER:-}" "$(basename "${CLAUDE_CMD:-claude}")" 2>/dev/null || true)"
+  if [ -n "$_plan_runner" ]; then
+    _plan_channel="$(EPAM_RUNNER="$_plan_runner" "${NODE_BIN:-node}" -e '
+      const r = require(process.argv[1] + "/lib/llm-settings-resolve.js").resolveRunner(process.env.EPAM_RUNNER, { projectConfigDir: process.env.EPAM_PROJECT_CONFIG_DIR || undefined });
+      const c = r && r.planModeChannel; if (!c || !c.modeFlag || !c.planValue || !c.sessionFlag || !c.resumeFlag) process.exit(0);
+      process.stdout.write([c.modeFlag, c.planValue, c.sessionFlag, c.resumeFlag].join(" "));' "$_SCRIPT_DIR_AIRUN" 2>/dev/null || true)"
+    if [ -n "$_plan_channel" ] && "$(runner_bin_for "${PRIMARY_PROVIDER:-}" "${CLAUDE_CMD:-claude}")" --help 2>/dev/null | grep -q -- "${_plan_channel%% *}"; then
+      _plan_session="$(uuidgen 2>/dev/null || "${NODE_BIN:-node}" -e 'process.stdout.write(require("crypto").randomUUID())')"
+    else
+      _plan_channel=""
+    fi
+  fi
+  _plan_vals="$(mktemp)"; printf '{}' > "$_plan_vals"
+  if [ -n "$_plan_session" ]; then _plan_note="$(render_engine_prompt plan-pass "$_plan_vals" tool-note-plan-mode)"; else _plan_note="$(render_engine_prompt plan-pass "$_plan_vals" tool-note-no-tools)"; fi
+  jq -n --arg n "$_plan_note" '{__TOOL_NOTE__: $n}' > "$_plan_vals"
   _plan_file="$(mktemp)"
-  {
-    cat "$PROMPT_FILE"
-    printf '\n\n---\n'
-    printf 'BEFORE YOU ANSWER: state your PLAN, and nothing else.\n\n'
-    printf 'Say what you believe the answer is going to be and WHY, name the\n'
-    printf 'specific targets you will examine or produce, and state how you will\n'
-    printf 'know if you are wrong. If the task above sets a requirement your\n'
-    printf 'answer must satisfy, say in one line how your plan satisfies it.\n\n'
-    printf 'Do NOT produce the final answer yet. Do NOT emit the output format\n'
-    printf 'the task asks for. Plain prose, at most 200 words.\n\n'
-    printf 'You have NO tools available for THIS plan and cannot call any — do not\n'
-    printf 'emit tool-call syntax (<tool_call>, <tool_use>, <function_call>) or\n'
-    printf 'invent what a tool would return. Nothing executes it, so any such text\n'
-    printf 'is fiction, not evidence — state your INTENT to examine a target, not a\n'
-    printf 'fabricated result from having done so. If tools are available for the\n'
-    printf 'answer that follows this plan, you will use them for real then.\n'
-  } > "$_plan_file"
-
+  { cat "$PROMPT_FILE"; render_engine_prompt plan-pass "$_plan_vals"; } > "$_plan_file"
   _plan_json=""
   [ -n "${ORCH_JSON_RESULT:-}" ] && _plan_json="$(mktemp)"
-
-  # The plan pass is an ordinary invocation with planning suppressed, so it
-  # cannot recurse.
-  # A distinct agent label, so the planning call is a separate, identifiable
-  # generation in Langfuse instead of a second trace with the same name. Both
-  # passes previously inherited EPAM_AGENT_NAME, which made plan and answer
-  # indistinguishable in the one place their cost and latency are comparable.
-  # NO TOOLS, and its own short deadline.
-  #
-  # Inheriting the tool budget made the detective explore twice — seven calls to
-  # plan, seven more to answer — for work already done. And because the agent's
-  # timeout wraps this whole script, a second exploration pushed agents toward
-  # deadlines set for one pass, manufacturing timeouts that read as model
-  # failures.
-  #
-  # It does not need them: the prompt already carries pre-seeded CodeGraph
-  # output, so a hypothesis can be formed without spending a call — and a plan
-  # made BEFORE looking is the more useful artefact, because the answer can be
-  # checked against it. The execute pass keeps the full budget.
-  # The plan pass is this same agent: named "<agent>:plan", and told the SI file it inherits is its own.
+  # The plan pass is an ordinary invocation with planning suppressed, so it cannot recurse. Its own agent label
+  # ("<agent>:plan") keeps plan and answer apart in Langfuse and the ledger. In plan mode the seam's read tools stay (plan mode
+  # itself permits nothing else); in the prose pass it has NO tools and its own short deadline (the detective explored twice).
   _plan_agent="${EPAM_AGENT_NAME:-agent}:plan"
+  _plan_tools_env=(EPAM_ALLOWED_TOOLS= EPAM_MAX_TOOL_CALLS=0)
+  [ -n "$_plan_session" ] && _plan_tools_env=(EPAM_PLAN_SESSION_NEW="$_plan_session" EPAM_PLAN_CHANNEL="$_plan_channel")
   _plan_text="$(
-    _EPAM_IN_PLAN_PASS=1 \
+    env _EPAM_IN_PLAN_PASS=1 \
     EPAM_SI_AGENT="$_plan_agent" \
     EPAM_AGENT_NAME="$_plan_agent" \
-    EPAM_ALLOWED_TOOLS="" \
-    EPAM_MAX_TOOL_CALLS=0 \
+    "${_plan_tools_env[@]}" \
     ORCH_JSON_RESULT="$_plan_json" \
     PROMPT_FILE="$_plan_file" \
     bash "$0" ${PRIMARY_PROVIDER:+--provider "$PRIMARY_PROVIDER"} ${AI_MODEL:+--model "$AI_MODEL"} \
       < "$_plan_file" 2>/dev/null || true
   )"
   rm -f "$_plan_file"
-
   if [ -n "$_plan_text" ]; then
     _plan_cost_json="$_plan_json"
-
-    # Langfuse is off in mock1 and in any run without LANGFUSE_* configured, so
-    # the plan is also written somewhere that always exists. Runs 8 and 9
-    # produced byte-identical logs and different answers; without the plans
-    # there is nothing to compare. Best-effort: a plan that cannot be recorded
-    # must never break the agent call it belongs to.
+    # Recorded where it always exists (Langfuse is off in mock runs): runs 8 and 9 had identical logs and different answers.
     if [ -n "${LOG_DIR:-}" ] && [ -d "$LOG_DIR" ]; then
       jq -cn --arg agent "${EPAM_AGENT_NAME:-agent}" \
              --arg story "${EPAM_STORY_ID:-}" \
              --arg model "${AI_MODEL:-}" \
              --arg phase "${PHASE:-unknown}" \
              --arg plan  "$_plan_text" \
-             '{ts:(now|todate), agent:$agent, story:$story, model:$model, phase:$phase, plan:$plan}' \
+             --arg session "$_plan_session" \
+             --arg mode "$([ -n "$_plan_session" ] && echo plan-mode || echo prose)" \
+             '{ts:(now|todate), agent:$agent, story:$story, model:$model, phase:$phase, mode:$mode, session:$session, plan:$plan}' \
         >> "$LOG_DIR/plans-${PHASE:-unknown}.jsonl" 2>/dev/null || true
     fi
+    jq -n --arg p "$_plan_text" '{__PLAN__: $p}' > "$_plan_vals"
     _exec_file="$(mktemp)"
-    {
-      cat "$PROMPT_FILE"
-      printf '\n\n---\n'
-      printf 'YOUR PLAN (you wrote this a moment ago):\n%s\n\n' "$_plan_text"
-      printf 'Now produce the final answer, in exactly the format the task above\n'
-      printf 'requires. If carrying out the plan showed it to be wrong, say so and\n'
-      printf 'answer correctly rather than following it.\n'
-    } > "$_exec_file"
+    { cat "$PROMPT_FILE"; render_engine_prompt plan-execute "$_plan_vals"; } > "$_exec_file"
     mv "$_exec_file" "$PROMPT_FILE"
+    # the answer is made in the plan's session, with the ordinary permissions
+    if [ -n "$_plan_session" ]; then export EPAM_PLAN_SESSION_RESUME="$_plan_session" EPAM_PLAN_CHANNEL="$_plan_channel"; fi
   else
     [ -n "$_plan_json" ] && rm -f "$_plan_json"
   fi
+  rm -f "$_plan_vals"
 fi
 
 # The plan pass billed real money. Fold its cost into the result the caller

package/orchestrations/scripts/spec-mode-runner.js

@@ -5327,33 +5327,18 @@ async function reviewRoster({
       + (d.length ? d.join(', ') : '(no manifest configuration)');
   }).join('\n');
 
-  // THE WHOLE TICKET, not a summary. The reviewer decides whether a brief serves the work that
-  // was actually asked for, so it needs the same view of the request the mint had: components
-  // (which say how far the work reaches), the links, and the untruncated description.
-  const ticketBlock = (Array.isArray(tickets) ? tickets : []).map((t) => {
-    const head = '- ' + (t.jiraKey || t.id || '') + ': ' + (t.title || '');
-    const comps = Array.isArray(t.components) && t.components.length
-      ? '\n  Components: ' + t.components.join(', ') : '';
-    const links = (Array.isArray(t.ticketLinks) ? t.ticketLinks : [])
-      .map((l) => (typeof l === 'string' ? l : (l && l.url))).filter(Boolean);
-    const linkLine = links.length ? '\n  Links: ' + links.join(' , ') : '';
-    return head + comps + '\n  ' + String(t.description || '').replace(/\s+/g, ' ') + linkLine;
-  }).join('\n');
-
-  // THE DOCUMENTS THE BRIEFS WERE DERIVED FROM. Without them the reviewer can tell that a brief
-  // disagrees with the repository, but not WHY — and the why decides the remedy. A brief that
-  // followed the vendor's current guide into a symbol this pinned version lacks needs the
-  // version-correct instruction; one that simply invented something needs deleting.
-  const docBlock = (Array.isArray(referencedDocs) ? referencedDocs : [])
-    .filter((d) => d && d.fetchStatus === 'fetched')
-    .map((d) => {
-      if (Array.isArray(d.quotes) && d.quotes.length) {
-        return '- ' + d.url + '\n' + d.quotes.map((q) => '    "' + String(q).replace(/\s+/g, ' ') + '"').join('\n');
-      }
-      let body = typeof d.body === 'string' ? d.body : '';
-      if (!body && d.path) { try { body = fs.readFileSync(d.path, 'utf8'); } catch { body = ''; } }
-      return body ? '- ' + d.url + '\n' + body : '- ' + d.url + ' (retrieved, no readable text)';
-    }).join('\n\n');
+  // THE WORK'S SHAPE, NOT ITS WORDS — the same rule as the mint's (mintProjectAgents). This reviewer was handed THE WHOLE TICKET
+  // to judge coverage, and its findings were the mint's corrective context: live 2026-10-24 (zero-story-references P1, four
+  // cycles) a finding read "the ticket (AMSD-2974) asks for accessibility enhancements to Toast Notification pop-ups … the roster
+  // needs an implementer scoped to the cx-shared ToastNotification component", the re-mint wrote exactly that brief, and the
+  // next cycle indicted it for naming the ticket's subject. A roster is kept with the codelines and reused for every later
+  // ticket on them; whether THIS ticket's stories find a role is the assignment stage's question. The reviewer judges the
+  // briefs against the codelines: true, owned tests, every codeline the work reaches covered by the kinds it needs.
+  const _rvTickets = Array.isArray(tickets) ? tickets : [];
+  const ticketBlock = `${_rvTickets.length} ticket(s) from the tracker reach the codelines listed. You are not told what they ask for: this roster is kept
+with the codelines and serves every later ticket on them, so judge each brief against ITS CODELINE, not against any one piece of work.`;
+  const docBlock = '';
+  void referencedDocs;
 
   const toolLine = toolGrant
     ? 'Your tools: ' + toolGrant + '. Open the repositories. Resolve the packages and symbols these '

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amsd-pipeline-shared",
-  "version": "0.5.43",
+  "version": "0.5.44",
   "description": "The AMSD pipeline's shared components, one source for the bash pipeline and its Claude workflows: the model-call gateway (llm-handler.sh — retry, ladder, self-heal, cost) and the libraries it runs.",
   "license": "UNLICENSED",
   "bin": {