amsd-pipeline-shared 0.5.28 → 0.5.30

package/bin/amsd-pipeline-shared.js

@@ -64,12 +64,15 @@ if (cmd === 'verify') {
 
 if (cmd === 'revert') {
   if (!fs.existsSync(path.join(STATE, 'installed.json'))) fail(`nothing to revert: no amsd-pipeline-shared install recorded in ${STATE}`);
+  // a file the install did not have when this package went in (its own file, or one a pipeline release no longer carries): removed again
+  let ABSENT = []; try { ABSENT = JSON.parse(fs.readFileSync(path.join(STATE, 'installed.json'), 'utf8')).absent || []; } catch { ABSENT = []; }
+  const hadNone = (f) => !BASE[f] || ABSENT.includes(f);
   for (const f of FILES) {
     const b = path.join(BACKUP, f);
     if (fs.existsSync(b)) fs.copyFileSync(b, path.join(ORCH, f));
-    else if (!BASE[f]) fs.rmSync(path.join(ORCH, f), { force: true });   // this package's own file: the release has none
+    else if (hadNone(f)) fs.rmSync(path.join(ORCH, f), { force: true });
   }
-  const back = FILES.filter((f) => (BASE[f] ? !known(f, md5(path.join(ORCH, f))) : fs.existsSync(path.join(ORCH, f))));
+  const back = FILES.filter((f) => (hadNone(f) ? fs.existsSync(path.join(ORCH, f)) : !known(f, md5(path.join(ORCH, f)))));
   if (back.length) fail(`revert incomplete — not the released copy:\n  ${back.join('\n  ')}`);
   fs.rmSync(STATE, { recursive: true, force: true });
   process.stdout.write(`amsd-pipeline-shared: reverted ${FILES.length} file(s) to the released copies\n`);
@@ -82,8 +85,11 @@ let PREV = {}; try { PREV = JSON.parse(fs.readFileSync(path.join(STATE, 'install
 const plan = FILES.map((f) => {
   const now = md5(path.join(ORCH, f)); const ours = md5(path.join(ROOT, 'orchestrations', f));
   if (now && now !== ours && PREV[f] === now) return { f, now, ours, state: 'previous' };
-  // a file the release never had (this package's own, e.g. lib/agent-messages.js): installed where absent
-  if (!BASE[f]) return { f, now, ours, state: now === ours ? 'current' : (now === null ? 'new' : 'other') };
+  // ABSENT FROM THE INSTALL: installed — this package's own file, or one a pipeline release no longer carries because this package holds it
+  // (operator, 2026-10-23: "move it … and remove in bash pipeline" — one copy, in this package)
+  if (now === null) return { f, now, ours, state: 'new' };
+  // a file the release never had (this package's own, e.g. lib/agent-messages.js), present with other bytes
+  if (!BASE[f]) return { f, now, ours, state: now === ours ? 'current' : 'other' };
   return { f, now, ours, state: now === ours ? 'current' : (known(f, now) ? 'released' : 'other') };
 });
 const other = plan.filter((p) => p.state === 'other');
@@ -103,7 +109,10 @@ for (const p of plan.filter((x) => ['released', 'new', 'previous'].includes(x.st
   fs.chmodSync(dst, mode);
 }
 fs.mkdirSync(STATE, { recursive: true });
+// what the install did not have before this package (kept across re-installs, so a revert removes exactly those)
+let WAS_ABSENT = []; try { WAS_ABSENT = JSON.parse(fs.readFileSync(path.join(STATE, 'installed.json'), 'utf8')).absent || []; } catch { WAS_ABSENT = []; }
+const absent = [...new Set([...WAS_ABSENT, ...plan.filter((p) => p.state === 'new').map((p) => p.f)])].sort();
 fs.writeFileSync(path.join(STATE, 'installed.json'), `${JSON.stringify({ package: PKG.name, version: PKG.version,
-  files: Object.fromEntries(FILES.map((f) => [f, md5(path.join(ROOT, 'orchestrations', f))])) }, null, 2)}\n`);
+  files: Object.fromEntries(FILES.map((f) => [f, md5(path.join(ROOT, 'orchestrations', f))])), absent }, null, 2)}\n`);
 const n = plan.filter((x) => ['released', 'new', 'previous'].includes(x.state)).length;
 process.stdout.write(`amsd-pipeline-shared ${PKG.version} → ${ORCH}: ${n} file(s) replaced, ${FILES.length - n} already current\n`);

package/docs/gateway-baseline-2.0.80.md5

@@ -245,3 +245,5 @@ fac1b26443bb52ba45ba072f4d654920  scripts/lib/story-guards.sh
 ada237373615a26d924226184ed7614b  scripts/lib/prd-change-review.sh
 c2dfd2381db0242fdbc487a948fd7feb  scripts/lib/agent-si.js
 03bde875977ab741c54c3b38a236a496  scripts/pre-run-reset.sh
+7600f6665c5a9f24dde8969b4c013aa4  scripts/lib/failure-healing.sh
+f5f3f2ffcf1da723455115e856dc173f  scripts/lib/kb_schema.py

package/docs/gateway-files.txt

@@ -1,3 +1,4 @@
+config/call-policy.json
 config/doctor-heavy-jobs.json
 config/doctor-signatures.json
 config/model-pricing.json
@@ -154,6 +155,8 @@ scripts/lib/agent-ladder.sh
 scripts/lib/agent-messages.js
 scripts/lib/agent-si.js
 scripts/lib/agent-si.js
+scripts/lib/call-attempts.js
+scripts/lib/call-failed.sh
 scripts/lib/checkpoints.sh
 scripts/lib/codeline-lanes.sh
 scripts/lib/codeline-packages.js
@@ -172,6 +175,7 @@ scripts/lib/doctor/cli.js
 scripts/lib/doctor/crash-record.js
 scripts/lib/doctor/handle.js
 scripts/lib/doctor/profile.js
+scripts/lib/doctor/release.js
 scripts/lib/doctor/repair.js
 scripts/lib/doctor/restarter.js
 scripts/lib/doctor/state.js
@@ -180,6 +184,7 @@ scripts/lib/engine-paths.sh
 scripts/lib/engine-prompt.js
 scripts/lib/env-file.sh
 scripts/lib/evidence-windows.js
+scripts/lib/failure-healing.sh
 scripts/lib/failure-signature.js
 scripts/lib/flags.sh
 scripts/lib/git-ops.sh
@@ -212,6 +217,7 @@ scripts/lib/kb-arbitration.js
 scripts/lib/kb-cli.js
 scripts/lib/kb-store.js
 scripts/lib/kb-synthesizer.js
+scripts/lib/kb_schema.py
 scripts/lib/langfuse-emit.js
 scripts/lib/llm-settings-resolve.js
 scripts/lib/mint-and-spec.sh

package/orchestrations/config/call-policy.json

@@ -0,0 +1,4 @@
+{
+  "$comment": "HOW MANY TIMES ONE AGENTIC CALL IS ASKED — one value, read by every gateway through scripts/lib/call-attempts.js: the bash hub (llm-handler.sh), the failed-call step (lib/call-failed.sh), the doctor's repair agent (lib/doctor/handle.js), codeline discovery's wall-clock bound, and the Claude workflow's gateway and workflow runner (amsd-pipeline-workflow generator/gateway.js callMaxAttempts). EPAM_CALL_MAX_ATTEMPTS, when a run sets it, wins (an operator's knob for one run, never a second default).",
+  "maxAttempts": 3
+}

package/orchestrations/prompts/templates/spec-review-criteria.json

@@ -8,7 +8,8 @@
     "observable checks live in verificationCriteria. Asked anyway, the reviewer reported the",
     "empty array as a hallucination or a persistence failure and lowered qualityScore for it,",
     "which is a gate blocking on a policy it was not told about.",
-    "v2 (operator, 2026-10-22): plan and criteria are reconciled before pause 2 — run 11's gotransit plan said 'no change' while its own criterion asked for a toast longer than 5 s; nothing checked one against the other."
+    "v2 (operator, 2026-10-22): plan and criteria are reconciled before pause 2 — run 11's gotransit plan said 'no change' while its own criterion asked for a toast longer than 5 s; nothing checked one against the other.",
+    "v3 (operator, 2026-10-23): the unmet criteria are a required list in the answer (unmetCriteria) — live, 1 of 3 real reviews of run 13 flagged the same contrast gap as advisory under its own name, and nothing corrected it."
   ],
   "description": "The criteria a spec-review coordinator judges a story's collaborative spec work against.",
   "id": "spec-review-criteria",
@@ -16,9 +17,9 @@
     "spec-coordinator"
   ],
   "placeholders": [],
-  "version": 2,
+  "version": 3,
   "bodies": {
-    "brownfield": "For each story, evaluate the quality of the collaborative spec work:\n1. Did both agents add meaningful, non-overlapping value?\n2. Flag any story needing human review.\n3. PLAN ALIGNMENT — where planAlignmentEvidence is present, it tells you what the\n   code-graph-detective SAID it would investigate (detectivePlan) and a deterministic,\n   cheap signal (aligned: true/false) for whether the final fixSiteAnalysis shares any\n   named symbol/file with that plan. This signal is NOT your verdict — it is evidence, the\n   same as MANIFEST EVIDENCE below. A plan can legitimately turn out wrong once real\n   exploration starts. Read detectivePlan and fixSiteAnalysis yourself and judge: did the\n   detective explain WHY it moved from its plan to its final answer (a stated pivot,\n   reasoning that connects the two), or did the answer just change with no explanation?\n   The latter is a real defect (a fix has shipped that shared no term with the detective's\n   own stated plan, with no explanation, more than once on the same ticket) — set\n   planAlignment to justified_deviation when the detective justifies its pivot, or\n   unexplained_mismatch when it does not, and say why in reviewNotes. aligned:true needs\n   no action.\n\n(Brownfield tickets never split and their acceptance criteria are immutable —\ndo not evaluate split quality or AC completeness; there is nothing there for\neither agent to have changed.\n\nEXPECTED, NOT A DEFECT: an agent's notes may describe acceptance criteria it\nauthored while the story's acceptanceCriteria array is empty, and report\nacceptanceChanged=false. That is this pipeline REDACTING them on purpose: on a\nbrownfield ticket the ACs are the ticket's own, and a thin ticket legitimately\nhas none. The observable checks live in verificationCriteria — judge THOSE.\nDo not report the mismatch as a hallucination, a persistence failure or a\nmetadata inconsistency, and do not lower qualityScore for it. An empty\nacceptanceCriteria array on a brownfield story is correct by policy.)\n\nEVERY VERIFICATION CRITERION HAS A PLANNED CHANGE THAT MAKES IT TRUE. For each verification criterion, name what in the plan makes it observable in this codeline: a fix site whose changeRequired is true, this codeline's own change or update in overallPlanForThisCodeline, or — where this codeline consumes another's package — the provider's change it receives, which its Writer is tested against through the provider's build the pipeline places in this codeline. A criterion nothing planned makes true cannot be met by the writer: flag it as criterion-without-planned-change, severity blocking, with a why that quotes the criterion and names the change that would meet it, or says that the criterion asks for something this story does not change and should be dropped. Do not approve a spec with such a criterion.\n",
-    "greenfield": "For each story, evaluate the quality of the collaborative spec work:\n1. Did both agents add meaningful, non-overlapping value?\n2. Are the acceptance criteria complete, testable, and non-overlapping?\n3. Are story splits logical and properly scoped?\n4. Flag any story needing human review.\n\nEVERY VERIFICATION CRITERION HAS A PLANNED CHANGE THAT MAKES IT TRUE. For each verification criterion, name what in the plan makes it observable in this codeline: a fix site whose changeRequired is true, this codeline's own change or update in overallPlanForThisCodeline, or — where this codeline consumes another's package — the provider's change it receives, which its Writer is tested against through the provider's build the pipeline places in this codeline. A criterion nothing planned makes true cannot be met by the writer: flag it as criterion-without-planned-change, severity blocking, with a why that quotes the criterion and names the change that would meet it, or says that the criterion asks for something this story does not change and should be dropped. Do not approve a spec with such a criterion.\n"
+    "brownfield": "For each story, evaluate the quality of the collaborative spec work:\n1. Did both agents add meaningful, non-overlapping value?\n2. Flag any story needing human review.\n3. PLAN ALIGNMENT — where planAlignmentEvidence is present, it tells you what the\n   code-graph-detective SAID it would investigate (detectivePlan) and a deterministic,\n   cheap signal (aligned: true/false) for whether the final fixSiteAnalysis shares any\n   named symbol/file with that plan. This signal is NOT your verdict — it is evidence, the\n   same as MANIFEST EVIDENCE below. A plan can legitimately turn out wrong once real\n   exploration starts. Read detectivePlan and fixSiteAnalysis yourself and judge: did the\n   detective explain WHY it moved from its plan to its final answer (a stated pivot,\n   reasoning that connects the two), or did the answer just change with no explanation?\n   The latter is a real defect (a fix has shipped that shared no term with the detective's\n   own stated plan, with no explanation, more than once on the same ticket) — set\n   planAlignment to justified_deviation when the detective justifies its pivot, or\n   unexplained_mismatch when it does not, and say why in reviewNotes. aligned:true needs\n   no action.\n\n(Brownfield tickets never split and their acceptance criteria are immutable —\ndo not evaluate split quality or AC completeness; there is nothing there for\neither agent to have changed.\n\nEXPECTED, NOT A DEFECT: an agent's notes may describe acceptance criteria it\nauthored while the story's acceptanceCriteria array is empty, and report\nacceptanceChanged=false. That is this pipeline REDACTING them on purpose: on a\nbrownfield ticket the ACs are the ticket's own, and a thin ticket legitimately\nhas none. The observable checks live in verificationCriteria — judge THOSE.\nDo not report the mismatch as a hallucination, a persistence failure or a\nmetadata inconsistency, and do not lower qualityScore for it. An empty\nacceptanceCriteria array on a brownfield story is correct by policy.)\n\nEVERY VERIFICATION CRITERION HAS A PLANNED CHANGE THAT MAKES IT TRUE. For each verification criterion, name what in the plan makes it observable in this codeline: a fix site whose changeRequired is true, this codeline's own change or update in overallPlanForThisCodeline, or — where this codeline consumes another's package — the provider's change it receives, which its Writer is tested against through the provider's build the pipeline places in this codeline. A criterion nothing planned makes true cannot be met by the writer: flag it as criterion-without-planned-change, severity blocking, with a why that quotes the criterion and names the change that would meet it, or says that the criterion asks for something this story does not change and should be dropped. Do not approve a spec with such a criterion. List every such criterion in unmetCriteria — the criterion quoted, and why — for every story you review; an empty list states that every criterion has a planned change behind it.\n",
+    "greenfield": "For each story, evaluate the quality of the collaborative spec work:\n1. Did both agents add meaningful, non-overlapping value?\n2. Are the acceptance criteria complete, testable, and non-overlapping?\n3. Are story splits logical and properly scoped?\n4. Flag any story needing human review.\n\nEVERY VERIFICATION CRITERION HAS A PLANNED CHANGE THAT MAKES IT TRUE. For each verification criterion, name what in the plan makes it observable in this codeline: a fix site whose changeRequired is true, this codeline's own change or update in overallPlanForThisCodeline, or — where this codeline consumes another's package — the provider's change it receives, which its Writer is tested against through the provider's build the pipeline places in this codeline. A criterion nothing planned makes true cannot be met by the writer: flag it as criterion-without-planned-change, severity blocking, with a why that quotes the criterion and names the change that would meet it, or says that the criterion asks for something this story does not change and should be dropped. Do not approve a spec with such a criterion. List every such criterion in unmetCriteria — the criterion quoted, and why — for every story you review; an empty list states that every criterion has a planned change behind it.\n"
   }
 }

package/orchestrations/scripts/lib/call-attempts.js

@@ -0,0 +1,32 @@
+'use strict';
+/**
+ * HOW MANY TIMES ONE AGENTIC CALL IS ASKED — the one reader of config/call-policy.json (see that file). Every gateway calls it.
+ *
+ *   callMaxAttempts(env = process.env) → an integer >= 1: EPAM_CALL_MAX_ATTEMPTS when the environment sets it, else the policy's maxAttempts
+ *   node call-attempts.js              → prints it; exit 1 with the reason when it cannot be read
+ *
+ * A value that is not a whole number of at least one, or a policy file it cannot read, is a stated error — never a default of its own.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const POLICY = path.join(__dirname, '..', '..', 'config', 'call-policy.json');
+
+function whole(v, where) {
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 1) throw new Error(`the call attempt count ${where} is '${v}', not a whole number of at least 1`);
+  return n;
+}
+
+function callMaxAttempts(env = process.env) {
+  if (env.EPAM_CALL_MAX_ATTEMPTS !== undefined && env.EPAM_CALL_MAX_ATTEMPTS !== '') return whole(env.EPAM_CALL_MAX_ATTEMPTS, 'in EPAM_CALL_MAX_ATTEMPTS');
+  let policy;
+  try { policy = JSON.parse(fs.readFileSync(POLICY, 'utf8')); } catch (e) { throw new Error(`the call policy ${POLICY} is not readable JSON: ${e.message}`); }
+  return whole(policy.maxAttempts, `in ${POLICY} (maxAttempts)`);
+}
+
+if (require.main === module) {
+  try { process.stdout.write(`${callMaxAttempts()}\n`); } catch (e) { process.stderr.write(`${e.message}\n`); process.exit(1); }
+}
+
+module.exports = { callMaxAttempts, POLICY };

package/orchestrations/scripts/lib/call-failed.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# THE FAILED-CALL STEP, ONCE, FOR EVERY AGENTIC CALL (operator, 2026-10-23: "All agentic calls - need self heal integration and retries - all - no
+# exceptions"). An agent call that gave no usable answer, as the pipeline's gateway takes it (llm-handler.sh "UNIFORM CALL RESILIENCE"), by the
+# pipeline's own functions: the failure on the agent's ladder and the next rung (lib/agent-ladder.sh, the chains exported by lib/model-ladders.sh
+# from the project's settings), the previous-refusal block for the next prompt (engine template previous-refusal), and the KB episode
+# (lib/kb-apply.sh) so self-heal learns from it. No AI.
+#   call-failed.sh        env CALL_AGENT (the agent), CALL_MODEL (the model just used), CALL_STORY, CALL_REASON, CALL_ATTEMPT,
+#                         CALL_STATE (the folder its ladder state and records live in), EPAM_PROJECT_CONFIG_DIR (the project's settings; optional)
+# Prints {"model", "decision": "escalating|top|no-chain", "block", "episode": bool, "line"} and appends the same as one call-failed event to
+# $CALL_STATE/events.jsonl; "line" is the hub's own attempt line, out of the call policy's count (lib/call-attempts.js). On a library that
+# does not load, or a count it cannot read: {"error": true, "reason"}.
+set -uo pipefail
+S="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+: "${CALL_AGENT:?}" "${CALL_STATE:?}" "${CALL_MODEL:=}" "${CALL_STORY:=global}" "${CALL_REASON:=the agent produced no usable answer}" "${CALL_ATTEMPT:=1}"
+export LOG_DIR="$CALL_STATE"; mkdir -p "$LOG_DIR"
+export NODE_BIN="${NODE_BIN:-$(command -v node)}"
+_log="$LOG_DIR/call-failed.log"
+{
+  # shellcheck source=/dev/null
+  . "$S/lib/model-ladders.sh"
+  # the project's chains (EPAM_MODEL_LADDER_<TIER>); none when no project settings are named — the agent then keeps its model
+  if [ -n "${EPAM_PROJECT_CONFIG_DIR:-}" ] && [ -f "$EPAM_PROJECT_CONFIG_DIR/llm-settings.json" ]; then export_model_ladders "$EPAM_PROJECT_CONFIG_DIR/llm-settings.json"; fi
+  # shellcheck source=/dev/null
+  . "$S/lib/agent-ladder.sh"
+  # shellcheck source=/dev/null
+  . "$S/lib/kb-apply.sh"
+} >>"$_log" 2>&1 || { jq -cn --rawfile m "$_log" '{error:true, reason:"the pipeline ladder/KB libraries did not load", message:$m}'; exit 0; }
+declare -F agent_ladder_model >/dev/null || { jq -cn '{error:true, reason:"agent_ladder_model is not defined"}'; exit 0; }
+max="$("$NODE_BIN" "$S/lib/call-attempts.js" 2>>"$_log")" || { jq -cn --rawfile m "$_log" '{error:true, reason:"no call attempt count", message:$m}'; exit 0; }
+
+agent_ladder_record_failure "$CALL_AGENT" "$CALL_STORY"
+next="$(agent_ladder_model "$CALL_AGENT" "$CALL_STORY" "$CALL_MODEL" 2>>"$_log")"
+# after a recorded failure the ladder either names the next rung or none — its top, or no chain for the tier — and the same rung is retried;
+# said as the hub says it (llm-handler.sh "UNIFORM CALL RESILIENCE")
+n="$((CALL_ATTEMPT + 1))/${max}"
+if [ -n "$next" ] && [ "$next" != "$CALL_MODEL" ]; then
+  decision=escalating; line="[ai-run] attempt ${n} for '${CALL_AGENT}' — escalating ${CALL_MODEL} -> ${next}"
+elif agent_ladder_exhausted "$CALL_AGENT" "$CALL_STORY" "$CALL_MODEL" 2>>"$_log"; then
+  decision=top; next="$CALL_MODEL"; line="[ai-run] attempt ${n} for '${CALL_AGENT}' — at the top of its declared chain (${CALL_MODEL:-default}), retrying the same rung"
+else
+  decision=no-chain; next="$CALL_MODEL"; line="[ai-run] attempt ${n} for '${CALL_AGENT}' — no chain declared for this agent's tier, retrying on ${CALL_MODEL:-default}"
+fi
+
+# the hub's _ai_prompt_with_failure: never a credential in a prompt; bounded, the tail kept
+why="$(printf '%s' "$CALL_REASON" | sed -E 's/(sk-[A-Za-z0-9_-]{8,}|ey[A-Za-z0-9_-]{20,}|[A-Za-z0-9_-]{32,})/[REDACTED]/g' | tail -c 1200)"
+block="$("$NODE_BIN" -e '
+  try {
+    const { renderEngineTemplate } = require(process.argv[1] + "/lib/engine-prompt.js");
+    process.stdout.write(renderEngineTemplate("previous-refusal", { __REASON__: process.argv[2], __ARTEFACT__: process.argv[3] || "answer" }));
+  } catch (e) { process.stdout.write(""); }
+' "$S" "$why" "$CALL_AGENT" 2>>"$_log")"
+
+# a block that did not render is said, never sent silently empty (the renderer needs the install's seam registry beside these scripts)
+[ -n "$block" ] || { jq -cn --arg agent "$CALL_AGENT" --rawfile m "$_log" '{error:true, reason:("the previous-refusal block did not render for " + $agent + " — is this the installed component, with its seam registry?"), message:$m}'; exit 0; }
+# kb_record_episode never fails its caller (losing an episode must not fail a run); it records only when the KB tool is installed beside it —
+# so that is what "episode" says (a write error inside the store is swallowed by the pipeline's own function, by its design)
+printf '%s' "$CALL_REASON" | kb_record_episode "$CALL_STORY" "$CALL_AGENT" "model call produced no usable output" 2>>"$_log"
+episode=$([ -f "$S/lib/kb-cli.js" ] && echo true || echo false)
+printf '%s\n' "$line" >>"$_log"
+jq -cn --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg agent "$CALL_AGENT" --arg story "$CALL_STORY" --argjson attempt "$CALL_ATTEMPT" \
+  --arg from "$CALL_MODEL" --arg to "$next" --arg decision "$decision" --argjson episode "$episode" --arg reason "$CALL_REASON" \
+  '{ts:$ts, kind:"call-failed", agent:$agent, story:$story, attempt:$attempt, from:$from, to:$to, decision:$decision, episode:$episode, reason:$reason}' \
+  >> "$LOG_DIR/events.jsonl"
+jq -cn --arg model "$next" --arg decision "$decision" --arg block "$block" --argjson episode "$episode" --arg line "$line" \
+  '{model:$model, decision:$decision, block:$block, episode:$episode, line:$line}'

package/orchestrations/scripts/lib/doctor/agent.js

@@ -44,8 +44,9 @@ function renderPrompt(vars, profile) {
 }
 
 /** The command, prepared and not started: the CLI in print mode on the profile's family, in the work tree, memory-bounded when the host has the wrapper. */
-function buildCommand({ install, profile, prompt, cwd, claudeBin, budgetUsd }) {
-  const model = modelFor(install, profile);
+function buildCommand({ install, profile, prompt, cwd, claudeBin, budgetUsd, model: rung }) {
+  // a rung the failed-call step moved to is taken only within the profile's family; otherwise the family's own model
+  const model = rung && rung.toLowerCase().includes(profile.model.family.toLowerCase()) ? rung : modelFor(install, profile);
   const argv = [...hostWrap(), claudeBin || process.env.CLAUDE_BIN || 'claude', '-p', prompt, '--model', model, '--output-format', 'json',
     '--setting-sources', 'project', '--permission-mode', 'bypassPermissions',
     ...(budgetUsd ? ['--max-budget-usd', String(budgetUsd)] : [])];
@@ -77,8 +78,8 @@ function readAnswer(text) {
 }
 
 /** Runs the session (the only model call the doctor makes). Returns the answer, the session's cost record and any model of another family it used. */
-function runAgent({ install, profile, prompt, cwd, sessionDir, env, claudeBin, budgetUsd }) {
-  const cmd = buildCommand({ install, profile, prompt, cwd, claudeBin, budgetUsd });
+function runAgent({ install, profile, prompt, cwd, sessionDir, env, claudeBin, budgetUsd, model }) {
+  const cmd = buildCommand({ install, profile, prompt, cwd, claudeBin, budgetUsd, model });
   const r = spawnSync(cmd.argv[0], cmd.argv.slice(1), { cwd: cmd.cwd, stdio: ['ignore', 'pipe', 'pipe'], env: { CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS: '0', ...process.env, ...(env || {}) }, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
   try { fs.mkdirSync(sessionDir, { recursive: true }); fs.writeFileSync(path.join(sessionDir, 'agent.stderr'), String(r.stderr || '')); fs.writeFileSync(path.join(sessionDir, 'agent.stdout'), String(r.stdout || '')); } catch { /* evidence only */ }
   let out = null; try { out = JSON.parse(r.stdout); } catch { out = null; }

package/orchestrations/scripts/lib/doctor/handle.js

@@ -15,9 +15,19 @@ const { settings, open } = require('./state.js');
 const { verifyRepair, reinstall, installedMismatches, checkComponent, snapshotRepos, repoChanges, promote } = require('./repair.js');
 const { renderPrompt } = require('./agent.js');
 const { restart } = require('./restarter.js');
+const { callMaxAttempts } = require('../call-attempts.js');   // the hub's count: the call policy's one value
 
 const git = (repo, ...a) => spawnSync('git', ['-C', repo, ...a], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
 const tail = (file, n) => { try { return fs.readFileSync(file, 'utf8').split('\n').slice(-n - 1).join('\n'); } catch { return ''; } };
+/** The shared failed-call step for one failed session (lib/call-failed.sh): the project's KB when the run names a project, else the doctor's own folder. */
+function callFailed({ agent, model, story, attempt, reason, state, values }) {
+  const proj = (values && values.EPAM_PROJECT_CONFIG_DIR) || '';
+  const env = { ...process.env, CALL_AGENT: agent, CALL_MODEL: model, CALL_STORY: story, CALL_ATTEMPT: String(attempt), CALL_REASON: reason, CALL_STATE: state,
+    NODE_BIN: process.execPath, ...(proj ? { EPAM_PROJECT_CONFIG_DIR: proj } : { KB_ROOT: path.join(state, 'kb') }) };
+  if (!proj) delete env.EPAM_PROJECT_CONFIG_DIR;
+  const r = spawnSync('bash', [path.join(__dirname, '..', 'call-failed.sh')], { env, encoding: 'utf8' });
+  try { return JSON.parse(String(r.stdout).trim().split('\n').pop()); } catch { return { error: true, reason: `the failed-call step gave no result (exit ${r.status}): ${String(r.stderr).slice(-300)}` }; }
+}
 
 async function handle(a) {
   const { profile, runDir, outDir, install, values, runId, res, crash, aborted, since, protectedRepos, agent, relaunch } = a;
@@ -78,8 +88,22 @@ async function handle(a) {
 
     const before = snapshotRepos(protectedRepos || []);
     d.event('agent', { branch, base }, attempt.n);
-    const r = await agent({ prompt, cwd: wt, sessionDir: A, install, profile, budgetUsd: cfg.budget });
-    if (r.session) for (const [model, u] of Object.entries(r.session.modelUsage || {})) d.cost({ attempt: attempt.n, model, tokensIn: u.inputTokens || 0, tokensOut: u.outputTokens || 0, costUsd: u.costUSD || 0 });
+    // SELF-HEAL FOR THE DOCTOR'S OWN AGENT (operator, 2026-10-23: "All agentic calls - need self heal integration and retries - all - no
+    // exceptions"): a session that gave no readable answer goes to the shared failed-call step (lib/call-failed.sh — the ladder, the
+    // previous-refusal block, the KB episode), and is asked again with that block on the rung it names, up to EPAM_CALL_MAX_ATTEMPTS
+    const attempts = callMaxAttempts();
+    const healDir = path.join(A, 'call-failed');
+    let r; let p = prompt; let rung;
+    for (let i = 1; ; i += 1) {
+      r = await agent({ prompt: p, cwd: wt, sessionDir: A, install, profile, budgetUsd: cfg.budget, ...(rung ? { model: rung } : {}) });
+      if (r.session) for (const [model, u] of Object.entries(r.session.modelUsage || {})) d.cost({ attempt: attempt.n, call: i, model, tokensIn: u.inputTokens || 0, tokensOut: u.outputTokens || 0, costUsd: u.costUSD || 0 });
+      if (r.answer || i >= attempts) break;
+      const h = callFailed({ agent: `${profile.component.name}-doctor`, model: r.model, story: runId, attempt: i,
+        reason: `the repair session ended without a readable answer (exit ${r.exit})`, state: healDir, values });
+      d.event('call-failed', { attempt: i, decision: h.decision, from: r.model, to: h.model || '', episode: !!h.episode, error: h.error ? h.reason : undefined }, attempt.n);
+      if (h.model) rung = h.model;
+      p = prompt + (h.block || '');
+    }
     if (r.otherFamily && r.otherFamily.length) { d.event('non-family-model', { models: r.otherFamily }, attempt.n); alert(`warning: the session used a model that is not ${profile.model.family}: ${r.otherFamily.join(', ')}`); }
 
     // CLIENT CODE IS NEVER THE DOCTOR'S: any change in any protected repository during the session refuses the whole repair