amsd-pipeline-shared 0.4.4 → 0.5.0

package/README.md

@@ -12,8 +12,11 @@ workflows (`amsd-pipeline-workflow`). A fix lands here, once, and both run the s
 | The Spec runner | `orchestrations/scripts/spec-mode-runner.js` | A failed mint re-proposal keeps the accepted roles and says so |
 | The KB synthesiser | `orchestrations/scripts/lib/kb-synthesizer.js` | Runs on its own seam's model |
 | Agent-to-agent messages | `orchestrations/scripts/lib/agent-messages.js` | send / receive / list / route on the pipeline's own bus format (`logs/messages/`, `agent-messages.jsonl`); "router" goes to the stage's router |
+| The shared pre-launch | `orchestrations/scripts/lib/prelaunch.js`, `lib/preflight.sh`, `preflight-check.sh`, `preflight-static.sh`, `preflight-prd-integrity.sh` | Every launch of every pipeline, before any model call: the pipeline's own pre-flight unchanged, then Langfuse (a trace read back under the run's session), seed (the seeded prompts and agent files are the launched ticket's), cache (both layers; at most `--max-rebuild` prompts to rebuild, named), cost (a priced ledger call; every ladder model priced), alone (nothing else on the install but its registered services), memory, no-timeout, and the 12-item checklist. `require_preflight` runs it for every bash launcher; `amsd-pipeline-shared prelaunch` for the workflows |
+| Codeline discovery's instructions | `orchestrations/prompts/templates/codeline-discovery.json` | A repository's `reason` describes the repository and its relation to the others, never the work it needs — the classifier reads it as the codeline's description (backlog B59) |
+| The price table | `orchestrations/config/model-pricing.json` | Claude Sonnet 5 and Opus 5.5 priced from Anthropic's pricing page, so a call whose session never reports a cost can still be priced |
 
-Every file sits at the path it has in a pipeline install. The first commit is the 35 gateway files exactly as released
+Every file sits at the path it has in a pipeline install. Each file is first committed exactly as released
 in amsd-pipeline 2.0.80 (`docs/gateway-baseline-2.0.80.md5`); every change since is its own commit with its tests.
 `docs/CONSUMER-REVIEW-B56.md` reads every caller of the gateway before and after the fix.
 
@@ -34,6 +37,16 @@ with the list. The replaced copies are kept in `<install>/.amsd-pipeline-shared/
 
 Needs: Node 20+, bash, jq.
 
+## The pre-launch from the shell
+
+```bash
+amsd-pipeline-shared prelaunch --install <install> --project <p> --run-id <id> --out <dir> \
+  [--ticket <KEY> --runs <a recorded run's runs dir>] [--codeline <cl>] [--set claude] [--max-rebuild <n>] [--prd <file>] [--preflight no]
+```
+
+Prints every check and the 12-item checklist, writes `<out>/prelaunch.json`; exit 0 all green, 1 any red. Nothing it does
+calls a model.
+
 ## Messages from the shell
 
 For the bash pipeline (backlog B55), one JSON line out:
@@ -56,6 +69,13 @@ The gateway, the reviewer, the mint re-proposal and the synthesiser each have a
 mutation-checked (md5 before and after). The install is tested on a copy of a 2.0.80 install: exactly the package's
 files change, an edited file is refused, an upgrade replaces only its own copies, revert gives back the release.
 
+## The pipeline doctor
+
+`amsd-pipeline-shared doctor validate|handle` and `orchestrations/scripts/lib/doctor/` — when a run stops on a defect in a pipeline's OWN code, the doctor reproduces it at £0, repairs it
+test-first (RED on the base, GREEN with the fix, proven by the doctor itself), reinstalls the component through its own installer, and restarts the run within a restart quota the operator gives.
+Off unless the pipeline's setting is `on`; Sonnet-class model only; never touches client code or the ticket; its own logs and cost ledger. Generic: every fact about a pipeline is its **profile**.
+See `docs/DOCTOR.md`.
+
 ## Version
 
 `amsd-pipeline-shared version`. Released with a git tag `v<version>` and the npm publish of the same version.

package/bin/amsd-pipeline-shared.js

@@ -6,6 +6,7 @@
 //   amsd-pipeline-shared verify  --into <install>   every file is this package's (exit 1 and the list when not)
 //   amsd-pipeline-shared revert  --into <install>   put back the files this package replaced
 //   amsd-pipeline-shared messages send|receive|list --dir <bus> …   the agent-to-agent bus (lib/agent-messages.js)
+//   amsd-pipeline-shared doctor validate|handle …   the pipeline doctor (lib/doctor/cli.js)
 //   amsd-pipeline-shared prelaunch --install <i> --project <p> --run-id <id> --out <dir> …   the shared pre-launch
 //   amsd-pipeline-shared version
 // A file is replaced only when the install holds the released copy this package was built from (docs/gateway-baseline-
@@ -26,6 +27,8 @@ const [cmd, ...rest] = process.argv.slice(2);
 if (cmd === 'version') { process.stdout.write(`${PKG.version}\n`); process.exit(0); }
 // THE SHARED PRE-LAUNCH, for every pipeline (lib/prelaunch.js): amsd-pipeline-shared prelaunch --install <i> --project <p> …
 if (cmd === 'prelaunch') process.exit(require(path.join(ROOT, 'orchestrations', 'scripts', 'lib', 'prelaunch.js')).prelaunchCli(rest));
+// THE PIPELINE DOCTOR (lib/doctor/): amsd-pipeline-shared doctor validate|handle … — repairs a pipeline component's own code when a run fails on a defect in it
+if (cmd === 'doctor') { require(path.join(ROOT, 'orchestrations', 'scripts', 'lib', 'doctor', 'cli.js')).doctorCli(rest).then((c) => process.exit(c)); return; }
 // THE MESSAGE BUS FOR SHELL CALLERS (the bash pipeline's adoption, backlog B55): one JSON line out
 if (cmd === 'messages') {
   const m = require(path.join(ROOT, 'orchestrations', 'scripts', 'lib', 'agent-messages.js'));

package/docs/gateway-files.txt

@@ -1,4 +1,7 @@
+config/doctor-heavy-jobs.json
+config/doctor-signatures.json
 config/model-pricing.json
+prompts/doctor-repair.md
 prompts/templates/codeline-discovery.json
 scripts/agent-attempt-analyst.sh
 scripts/lib/agent-contract.js
@@ -10,6 +13,15 @@ scripts/lib/constraint-sanity.js
 scripts/lib/content-retry.js
 scripts/lib/cost-emitter.js
 scripts/lib/cost-record.sh
+scripts/lib/doctor/agent.js
+scripts/lib/doctor/classify.js
+scripts/lib/doctor/cli.js
+scripts/lib/doctor/crash-record.js
+scripts/lib/doctor/handle.js
+scripts/lib/doctor/profile.js
+scripts/lib/doctor/repair.js
+scripts/lib/doctor/restarter.js
+scripts/lib/doctor/state.js
 scripts/lib/engine-prompt.js
 scripts/lib/env-file.sh
 scripts/lib/evidence-windows.js

package/orchestrations/config/doctor-heavy-jobs.json

@@ -0,0 +1,5 @@
+{
+  "$comment": "The jobs another launch must not share this host with (the operator's standing rule: check memory AND other heavy jobs before a launch) — host-wide, not any pipeline's. 'tokens' match a process's command-line entry by its exact file name; 'withFlag' matches a program started with a flag (a `claude -p` session, not an interactive `claude`).",
+  "tokens": ["vitest", "jest", "tsc", "flow.py"],
+  "withFlag": [{ "bin": "claude", "flag": "-p", "as": "claude -p" }]
+}

package/orchestrations/config/doctor-signatures.json

@@ -0,0 +1,11 @@
+{
+  "$comment": "What a failure LOOKS LIKE, per runtime the doctor's components are written in — data, not code, so a new runtime is a new entry and no pipeline's name or path is here. 'runtimeNames' and 'runtimeMessage' are the marks of a defect in the code itself; 'external' is what names the machine, the network, the model service or a kill instead; 'internalFrame' and 'dependencyDir' tell a stack frame that is the runtime's or a dependency's from the component's own. A pipeline's own deliberate refusals are NOT here: they are in its profile (classify.refusals).",
+  "node": {
+    "runtimeNames": ["TypeError", "ReferenceError", "SyntaxError", "RangeError"],
+    "runtimeMessage": "Unexpected token|is not valid JSON|Unexpected end of JSON|Cannot read propert|Cannot set propert|is not a function|is not defined|is not iterable|Cannot destructure|is not a constructor|Invalid array length|Maximum call stack",
+    "external": "\\bE(NOSPC|ACCES|PERM|MFILE|NOMEM|CONNRESET|CONNREFUSED|TIMEDOUT|NOTFOUND|AI_AGAIN|PIPE)\\b|bounded: cap|exited (137|143)\\b|\\b(401|403|429|500|502|503|529)\\b|overloaded|rate.?limit|credit|quota|<!DOCTYPE|<html|out of memory|killed",
+    "generalRefusal": "refused|usage:",
+    "internalFrame": "^node:",
+    "dependencyDir": "node_modules"
+  }
+}

package/orchestrations/config/model-pricing.json

@@ -35,12 +35,20 @@
       "outputPerMillion": 15
     },
     "claude-haiku-4-5": {
-      "inputPerMillion": 0.8,
-      "outputPerMillion": 4
+      "inputPerMillion": 1,
+      "outputPerMillion": 5,
+      "cacheReadPerMillion": 0.1,
+      "cacheWrite5mPerMillion": 1.25,
+      "cacheWrite1hPerMillion": 2,
+      "$why": "Checked against the vendor: https://platform.claude.com/docs/en/about-claude/pricing (read 2026-10-19) — $1 input / $5 output per MTok; cache $1.25 5-minute write, $2 1-hour write, $0.10 hit. Was $0.80/$4 (Haiku 3.5's price)."
     },
     "claude-haiku-4-5-20251001": {
-      "inputPerMillion": 0.8,
-      "outputPerMillion": 4
+      "inputPerMillion": 1,
+      "outputPerMillion": 5,
+      "cacheReadPerMillion": 0.1,
+      "cacheWrite5mPerMillion": 1.25,
+      "cacheWrite1hPerMillion": 2,
+      "$why": "Checked against the vendor: https://platform.claude.com/docs/en/about-claude/pricing (read 2026-10-19) — $1 input / $5 output per MTok; cache $1.25 5-minute write, $2 1-hour write, $0.10 hit. Was $0.80/$4 (Haiku 3.5's price)."
     },
     "claude-3-5-haiku-20241022": {
       "inputPerMillion": 0.8,

package/orchestrations/prompts/doctor-repair.md

@@ -0,0 +1,34 @@
+You are the pipeline doctor. A run of {{component}} ({{description}}) stopped on a defect in that component's OWN code. You repair that code, and only that code.
+
+THE FAILURE
+- Run: {{run}}   Attempt: {{attempt}}   Step the pipeline was in: {{step}}
+- What was thrown ({{errorName}}): {{errorMessage}}
+- Thrown at: {{throwSite}}
+- The crash record, the failing leg's output and the run's log tail are copies in: {{evidenceDir}}  (read them)
+- The run's preserved state, READ ONLY, never written: {{runDir}}   The install it ran from: {{install}}
+
+WHERE YOU WORK
+- Your working directory is a git work tree of {{component}} on branch {{branch}}. It is the only place you write.
+- You may change files under these directories only: {{repairDirs}} (the code) and {{testDirs}} (the tests). Nothing else in the repository, and nothing outside it.
+- Never touch: {{boundaries}}.
+
+AGENTIC FIRST — decide this before anything else
+- Ask: did an AGENT cause this abort — its answer, its instructions, the schema it must answer in, the hand-off between two agents — or is it a clear and outright coding bug (a throw, a wrong variable, an unhandled null, a bad path) in code that involves no agent's behaviour?
+- The agentic layer of {{component}} is: {{agenticDescription}}. It lives in: {{agenticDirs}}.
+- If an agent caused it, repair the AGENTIC layer: sharpen the instruction, the answer schema and its field descriptions, the hand-off contract between the agents — so the agent is asked in a way that gets the right answer. Do NOT add deterministic code that tolerates, repairs or re-parses a wrong agent answer, and do not add a guard that hides an agent's behaviour.
+- Only a clear and outright coding bug gets a deterministic fix.
+- This abort was classified as: {{abortKind}} ({{layerHint}}). An agentic abort MUST be repaired agentically. For a crash, say which layer you found and why.
+- An agentic repair is proven by REPLAY: replay the real reply or hand-off that failed — copy it into a fixture — against the schema, the contract or the rendered instruction in the RED test (it fails on the base, passes after), and assert on the rendered instruction or schema text that now prevents the abort.
+
+HOW YOU WORK — in this order
+1. Reason from the data flow to the exact input that makes the code fail. Name the file, the line and the wrong assumption BEFORE you run anything.
+2. Reproduce it at £0 from the preserved state: copy what you need into a scratch folder; never write into the run. No model calls, no network.
+3. Write the smallest RED test in the test directories that fails for exactly that reason: it executes the unit and asserts on the artefact it produced, and it has a negative case. Run only that file with: {{testCommand}}. Never a test file matching {{forbiddenTests}}, never a whole suite, never a whole test folder.
+4. Fix the code until that test is GREEN. Then a mutation check: undo the fix, see the test fail, restore the file, compare md5 before and after.
+5. Look for the same mistake elsewhere in the component (grep the pattern) and fix every instance the same way, each with a test.
+6. `git add` only the files you changed and `git commit` on this branch. Do not push. Do not publish. Do not install or fetch anything; no network command.
+
+YOU ARE WRONG UNTIL A TEST SAYS OTHERWISE. If you cannot reproduce the failure, or the cause is outside the component, say so and change nothing.
+
+END with exactly one JSON object and nothing after it:
+{"status":"repaired"|"cannot","layer":"code"|"agentic","layerWhy":"<which layer and why, in one sentence>","summary":"<what was wrong, in one sentence>","cause":"<file:line and the wrong assumption>","files":["<changed files>"],"tests":["<test files>"]}

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

@@ -0,0 +1,91 @@
+'use strict';
+// THE DOCTOR'S AGENT: one model family and nothing else (operator, 2026-10-20: "the agent only uses sonnet to work"). The family is the
+// profile's; the model id is read from the pipeline's OWN model configuration (profile.model.config) — never written here — and there is no
+// fallback to any other model: no model of that family there, no agent. The prompt is a template file (prompts/doctor-repair.md) filled from the
+// profile and the failure, every field or refused. buildCommand never runs anything; runAgent is the only place a model is called.
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { hostWrap, expand } = require('./repair.js');
+
+/** Every string value in a JSON document, in document order. */
+function strings(v, out = []) {
+  if (typeof v === 'string') out.push(v);
+  else if (Array.isArray(v)) v.forEach((x) => strings(x, out));
+  else if (v && typeof v === 'object') Object.values(v).forEach((x) => strings(x, out));
+  return out;
+}
+
+/** The first model id of the profile's family in the pipeline's model configuration (an id is a token with no spaces that names the family). */
+function modelFor(install, profile) {
+  const f = profile.model.config.replace('{install}', install);
+  let doc;
+  try { doc = JSON.parse(fs.readFileSync(f, 'utf8')); } catch (e) { throw new Error(`cannot read the model configuration ${f}: ${e.message}`); }
+  const fam = profile.model.family.toLowerCase();
+  const m = strings(doc).find((s) => /^[A-Za-z0-9._:/-]+$/.test(s) && s.toLowerCase().includes(fam));
+  if (!m) throw new Error(`no "${profile.model.family}" model in ${f}: the doctor works on that family only and does not fall back`);
+  return m;
+}
+
+/** The repair prompt with every {{field}} filled from the failure and the profile; a field left unfilled is an error, naming it. */
+function renderPrompt(vars, profile) {
+  const t = fs.readFileSync(path.join(__dirname, '..', '..', '..', 'prompts', 'doctor-repair.md'), 'utf8');
+  const all = {
+    ...vars, component: profile.component.name, description: profile.component.description,
+    repairDirs: profile.scope.repairDirs.join(', '), testDirs: profile.scope.testDirs.join(', '), boundaries: profile.boundaries.join('; '),
+    testCommand: expand(profile.test.command, { node: 'node', files: ['<test file>'] }).join(' '),
+    forbiddenTests: profile.scope.forbiddenTests.length ? profile.scope.forbiddenTests.map((r) => r.source).join(' or ') : '(none declared)',
+    agenticDescription: profile.agentic.description, agenticDirs: profile.agentic.dirs.join(', '),
+  };
+  const missing = new Set();
+  const out = t.replace(/\{\{(\w+)\}\}/g, (_, k) => { if (all[k] === undefined || all[k] === null || all[k] === '') { missing.add(k); return ''; } return String(all[k]); });
+  if (missing.size) throw new Error(`repair prompt field missing: ${[...missing].join(', ')}`);
+  return out;
+}
+
+/** 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);
+  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)] : [])];
+  return { cwd, argv, model };
+}
+
+/** The answer's shape: repaired / cannot with the fields — anything else is no answer. */
+function answerShape(v) {
+  if (!v || typeof v !== 'object') return null;
+  const strs = (a) => Array.isArray(a) && a.every((x) => typeof x === 'string');
+  if (!['repaired', 'cannot'].includes(v.status) || typeof v.summary !== 'string' || typeof v.cause !== 'string' || !strs(v.files) || !strs(v.tests)) return null;
+  // THE LAYER REPAIRED, AND WHY (operator, 2026-10-20: agentic first): a reply that does not say is not an answer
+  if (!['code', 'agentic'].includes(v.layer) || typeof v.layerWhy !== 'string' || !v.layerWhy.trim()) return null;
+  return { status: v.status, layer: v.layer, layerWhy: v.layerWhy, summary: v.summary, cause: v.cause, files: v.files, tests: v.tests };
+}
+
+/**
+ * The agent's answer: the LAST object anywhere in its reply that has the answer's shape — a bare document, a fenced block, or (as the first live
+ * session answered, 2026-10-20) a line of prose and then the object. Prose around it, a format example before it, braces inside its strings: none of
+ * that hides it; an object of the wrong shape is never taken for it.
+ */
+function readAnswer(text) {
+  const t = String(text || '');
+  const tryParse = (x) => { try { return answerShape(JSON.parse(x)); } catch { return null; } };
+  const opens = []; const closes = [];
+  for (let i = 0; i < t.length; i += 1) { if (t[i] === '{') opens.push(i); else if (t[i] === '}') closes.push(i); }
+  for (let a = opens.length - 1; a >= 0; a -= 1) for (let b = closes.length - 1; b >= 0 && closes[b] > opens[a]; b -= 1) { const v = tryParse(t.slice(opens[a], closes[b] + 1)); if (v) return v; }
+  return null;
+}
+
+/** 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 });
+  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; }
+  const session = out && out.session_id ? { sessionId: out.session_id, modelUsage: out.modelUsage || {}, totalCostUsd: out.total_cost_usd || 0 } : null;
+  const fam = profile.model.family.toLowerCase();
+  const otherFamily = session ? Object.keys(session.modelUsage).filter((m) => !m.toLowerCase().includes(fam)) : [];
+  return { exit: r.status, answer: out && typeof out.result === 'string' ? readAnswer(out.result) : null, session, otherFamily, model: cmd.model };
+}
+
+module.exports = { modelFor, renderPrompt, buildCommand, readAnswer, runAgent };

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

@@ -0,0 +1,56 @@
+'use strict';
+// WHEN THE DOCTOR RUNS (operator, 2026-10-20: "it has to be a REAL pipeline error"; "no false positives"). The doctor repairs one
+// component's own code, so it is called only when the leg's own evidence shows a defect in that code — and when the evidence is anything
+// less, the answer is "no" and the failure is reported. Precision over recall, by construction. Nothing here is about any pipeline: its
+// repairable directories and its deliberate refusals come from its profile (profile.js); what a failure looks like in its runtime comes
+// from the signature data (config/doctor-signatures.json).
+//   classify({ profile, portRoot, res, crash, aborted, since, signatures? }) → { call: boolean, kind, why }
+//     profile   the pipeline's compiled profile        portRoot  the component as installed (<install>/<profile.install.dest>)
+//     res       the leg's answer ({status, …})         crash     the leg's crash record (crash-record.js), if any
+//     aborted   the operator or a watcher ended the leg    since  the leg's start (ISO)
+const fs = require('fs');
+const path = require('path');
+
+const no = (kind, why) => ({ call: false, kind, why });
+const rxOf = (s) => new RegExp(s);
+
+/** The signature set of one runtime, compiled. An unknown runtime is an error, never a guess. */
+function signaturesFor(runtime, injected) {
+  const all = injected || JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', '..', 'config', 'doctor-signatures.json'), 'utf8'));
+  const s = all[runtime];
+  if (!s) throw new Error(`no signatures for runtime "${runtime}" (config/doctor-signatures.json knows: ${Object.keys(all).filter((k) => !k.startsWith('$')).join(', ')})`);
+  return { runtimeNames: new Set(s.runtimeNames), runtimeMessage: rxOf(s.runtimeMessage), external: rxOf(s.external), generalRefusal: rxOf(s.generalRefusal),
+    internalFrame: rxOf(s.internalFrame), dependencyDir: s.dependencyDir };
+}
+
+function classify({ profile, portRoot, res, crash, aborted, since, signatures }) {
+  const sig = signaturesFor(profile.classify.runtime, signatures);
+  if (!res || typeof res !== 'object') return no('no-result', 'the leg gave no result');
+  if (aborted) return no('aborted', 'the operator or a watcher ended the leg');
+  // AN AGENT-CAUSED ABORT (operator, 2026-10-20: look for the agentic solution first): a failed leg whose reason is one of the pipeline's own agent-caused
+  // messages (its profile) — an unreadable reply, a refused schema, an agent that gave no answer. It is evidenced by the message, so a failure that names the
+  // machine, the network or the model service is still external, and a lane's own verdict names no such message
+  if (res.status === 'failed') {
+    const reason = typeof res.reason === 'string' ? res.reason : '';
+    const hit = reason && profile.agentic.abortSignatures.find((r) => r.test(reason));
+    if (!hit) return no('not-a-crash', 'the leg failed on a verdict that names no agent-caused message — reported, not repaired');
+    if (sig.external.test(reason)) return no('external', 'the agent-caused message also names the machine, the network, the model service or a kill — not the pipeline');
+    return { call: true, kind: 'agentic-abort', layer: 'agentic', why: `an agent caused the abort: ${reason.slice(0, 200)}` };
+  }
+  if (res.status !== 'crashed') return no(res.status === 'no-answer' ? 'no-record' : 'not-a-crash', `the leg ended ${res.status}, not crashed — a kill, a verdict or a pause is reported, not repaired`);
+  if (!crash || typeof crash !== 'object') return no('no-record', 'no crash record: nothing proves a defect in the code');
+  if (!crash.at || !since || Date.parse(crash.at) < Date.parse(since)) return no('stale-record', 'the crash record is older than this leg');
+  const text = `${crash.name || ''}: ${crash.message || ''}`;
+  if (sig.external.test(text)) return no('external', 'the failure names the machine, the network, the model service or a kill — not the code');
+  if (sig.generalRefusal.test(text) || profile.classify.refusals.some((r) => r.test(text))) return no('refusal', 'the pipeline stopped on purpose');
+  const site = (crash.frames || []).find((f) => f && typeof f.file === 'string' && !sig.internalFrame.test(f.file)) || null;
+  if (!site) return no('outside-port', 'no frame of the stack is in any file');
+  const rel = path.relative(portRoot || '', site.file);
+  const parts = rel.split(path.sep);
+  const inPort = !!portRoot && !rel.startsWith('..') && !path.isAbsolute(rel) && profile.scope.repairDirs.includes(parts[0]) && !parts.includes(sig.dependencyDir);
+  if (!inPort) return no('outside-port', `the throw site ${site.file}:${site.line} is not the component's own code`);
+  if (!sig.runtimeNames.has(crash.name) && !sig.runtimeMessage.test(crash.message || '')) return no('ambiguous', `an Error in ${rel}:${site.line} with no sign of a code defect — reported`);
+  return { call: true, kind: 'port-defect', layer: 'code', why: `${crash.name}: ${String(crash.message).slice(0, 160)} — thrown at ${rel}:${site.line}${crash.step ? ` (step: ${crash.step})` : ''}` };
+}
+
+module.exports = { classify, signaturesFor };

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

@@ -0,0 +1,56 @@
+'use strict';
+// THE DOCTOR'S COMMAND LINE — for launchers that are not JavaScript (the bash pipeline): one JSON line out, and an exit code that says whether the
+// command ran, not what the doctor decided (read `handled` / `restarted` in the line).
+//   amsd-pipeline-shared doctor validate --profile <file>                 exit 0 ok · 1 the profile has problems (all named in the line)
+//   amsd-pipeline-shared doctor handle --profile <file> --run-dir <d> --out-dir <d> --install <i> --run-id <id> --leg-result <json file>
+//        [--crash-file <json file>] [--aborted yes] --since <ISO> --launch-values <json file> [--protected <dir>,<dir>…]
+//        --relaunch-cmd '<JSON array: the command, to which the profile's restart arguments are appended>' --need-mb <n> --reserve-mb <n>
+//        [--heavy-rules <json file>]                                       exit 0 it ran · 64 usage · 70 an error
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+const { load } = require('./profile.js');
+
+const REQUIRED = ['profile', 'runDir', 'outDir', 'install', 'runId', 'legResult', 'since', 'launchValues', 'relaunchCmd', 'needMb', 'reserveMb'];
+const flag = (k) => `--${k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
+
+function parse(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i += 2) { if (!argv[i].startsWith('--')) throw new Error(`unexpected argument ${argv[i]}`); opts[argv[i].slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = argv[i + 1]; }
+  return opts;
+}
+const readJson = (f) => JSON.parse(fs.readFileSync(f, 'utf8'));
+const out = (o) => process.stdout.write(`${JSON.stringify(o)}\n`);
+
+async function doctorCli(argv) {
+  const [sub, ...rest] = argv;
+  let opts;
+  try { opts = parse(rest); } catch (e) { process.stderr.write(`doctor: ${e.message}\n`); return 64; }
+  if (sub === 'validate') {
+    if (!opts.profile) { process.stderr.write('doctor validate: missing --profile\n'); return 64; }
+    const r = load(opts.profile); out({ ok: !r.problems.length, problems: r.problems });
+    return r.problems.length ? 1 : 0;
+  }
+  if (sub !== 'handle') { process.stderr.write('usage: amsd-pipeline-shared doctor validate --profile <file> | handle --profile <file> --run-dir <d> … (see lib/doctor/cli.js)\n'); return 64; }
+  const missing = REQUIRED.filter((k) => !opts[k]);
+  if (missing.length) { process.stderr.write(`doctor handle: missing ${missing.map(flag).join(', ')}\n`); return 64; }
+  try {
+    const pr = load(opts.profile);
+    if (pr.problems.length) { out({ ok: false, problems: pr.problems }); return 1; }
+    const { handle } = require('./handle.js'); const { runAgent } = require('./agent.js'); const { heavyJobs } = require('./restarter.js');
+    const lv = readJson(opts.launchValues);
+    const rules = opts.heavyRules ? readJson(opts.heavyRules) : undefined;
+    const cmd = JSON.parse(opts.relaunchCmd);
+    if (!Array.isArray(cmd) || !cmd.length || !cmd.every((x) => typeof x === 'string')) throw new Error('--relaunch-cmd must be a JSON array of strings');
+    const result = await handle({
+      profile: pr.profile, runDir: opts.runDir, outDir: opts.outDir, install: opts.install, values: lv.values || lv, runId: opts.runId,
+      res: readJson(opts.legResult), crash: opts.crashFile && fs.existsSync(opts.crashFile) ? readJson(opts.crashFile) : null, aborted: opts.aborted === 'yes', since: opts.since,
+      protectedRepos: (opts.protected || '').split(',').filter(Boolean),
+      agent: async ({ prompt, cwd, sessionDir, install, profile, budgetUsd }) => runAgent({ install, profile, prompt, cwd, sessionDir, budgetUsd }),
+      relaunch: async (args) => { const r = spawnSync(cmd[0], [...cmd.slice(1), ...args], { stdio: 'inherit' }); return { status: r.status }; },
+      needMb: Number(opts.needMb), reserveMb: Number(opts.reserveMb), heavyJobs: () => heavyJobs({ rules }),
+    });
+    out(result); return 0;
+  } catch (e) { process.stderr.write(`doctor handle: ${e.stack || e.message}\n`); return 70; }
+}
+
+module.exports = { doctorCli };

package/orchestrations/scripts/lib/doctor/crash-record.js

@@ -0,0 +1,62 @@
+'use strict';
+// THE CRASH RECORD (operator, 2026-10-20: "could be a crash listener"). A hard abort of a pipeline's driver — a throw nothing caught, a
+// promise rejected with nobody awaiting it — leaves (1) a record in the file the pipeline's profile names (crash.file) in its run directory:
+// what was thrown (name, message, stack, the stack's frames) and the step the driver was in, written whole or not at all; (2) an answer line
+// on stdout, {status:'crashed', exit:1, reason}, where the launcher reads a leg's outcome. The launcher decides from this record
+// (classify.js), never from a regex over stderr. A kill by a signal cannot be listened for: it leaves no record, and a leg with no
+// record is never taken for a defect in the code. The file name is the pipeline's: nothing here names any pipeline.
+const fs = require('fs');
+const path = require('path');
+
+let runDir = null;
+let fileName = null;
+let step = '';
+
+/** The step the driver is in, kept in the record. */
+function setStep(s) { step = String(s || ''); }
+
+/** "    at fn (/path/file.js:12:34)" and "    at /path/file.js:12:34" → {fn, file, line, column}. */
+function frames(stack) {
+  const out = [];
+  for (const l of String(stack || '').split('\n')) {
+    const m = l.match(/^\s*at (?:(.*?) \()?(.*?):(\d+):(\d+)\)?\s*$/);
+    if (m) out.push({ fn: m[1] || '', file: m[2], line: Number(m[3]), column: Number(m[4]) });
+  }
+  return out;
+}
+
+/** What was thrown, whatever it was: an Error, or anything a program may throw. */
+function describe(e) {
+  if (e instanceof Error) return { name: e.name || 'Error', message: String(e.message), stack: String(e.stack || '') };
+  let text; try { text = typeof e === 'string' ? e : JSON.stringify(e); } catch { text = String(e); }
+  return { name: 'NonError', message: String(text), stack: '' };
+}
+
+/** Writes <dir>/<file> whole (a temp file, then a rename); returns the record. */
+function write(dir, file, err, extra) {
+  const d = describe(err);
+  const rec = { at: new Date().toISOString(), pid: process.pid, ...d, frames: frames(d.stack), step, ...(extra || {}) };
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(dir, `${file}.${process.pid}.tmp`);
+  fs.writeFileSync(tmp, `${JSON.stringify(rec, null, 2)}\n`);
+  fs.renameSync(tmp, path.join(dir, file));
+  return rec;
+}
+
+/** The leg's answer for a crash, and the exit. Never throws: a crash handler that crashes hides the crash. */
+function die(e) {
+  let reason = 'crashed';
+  try { const rec = write(runDir, fileName, e); reason = `${rec.name}: ${rec.message}`.slice(0, 400); } catch (w) { reason = `crashed (the record could not be written: ${w.message})`; }
+  try { process.stdout.write(`${JSON.stringify({ status: 'crashed', exit: 1, reason })}\n`); } catch { /* nothing left to tell */ }
+  process.exit(1);
+}
+
+/** Listens for what nothing caught. */
+function install(opts) {
+  if (!opts || !opts.runDir || !opts.file) throw new Error('crash record: install needs { runDir, file } — the file name is the pipeline\'s (profile crash.file), never a default');
+  runDir = opts.runDir; fileName = opts.file;
+  process.on('uncaughtException', die);
+  process.on('unhandledRejection', (r) => die(r));
+}
+
+module.exports = { install, setStep, write, die, frames, describe };

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

@@ -0,0 +1,121 @@
+'use strict';
+// THE DOCTOR, WHOLE (operator, 2026-10-20): crash → classify → repair → verify → commit → reinstall → restart, for ANY pipeline — everything
+// about the pipeline is its profile (profile.js). Called by a launcher when a leg ends; it does nothing at all unless the pipeline's setting is
+// on, and calls the model only for a real defect in the component's own code (classify.js). It repairs ONLY the component's code, in a work tree
+// of the component's own repository: the repository must BE the profile's component and never one of the run's protected (client) repositories,
+// and those are snapshotted around the agent's session — any change in any of them refuses the whole repair. Every step is recorded in the
+// doctor's own folder (state.js) and every stop is alerted. The model session is injected (agent.js is the live one).
+//   handle({ profile, runDir, outDir, install, values, runId, res, crash, aborted, since, protectedRepos, agent, relaunch,
+//            needMb, reserveMb, availableMb?, heavyJobs? }) → { handled, restarted, stopped?, why }
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { classify } = require('./classify.js');
+const { settings, open } = require('./state.js');
+const { verifyRepair, reinstall, installedMismatches, checkComponent, snapshotRepos, repoChanges } = require('./repair.js');
+const { renderPrompt } = require('./agent.js');
+const { restart } = require('./restarter.js');
+
+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 ''; } };
+
+async function handle(a) {
+  const { profile, runDir, outDir, install, values, runId, res, crash, aborted, since, protectedRepos, agent, relaunch } = a;
+  const cfg = settings(values, profile);
+  const alert = (text) => { try { fs.mkdirSync(outDir, { recursive: true }); fs.appendFileSync(path.join(outDir, profile.logs.alerts), `${new Date().toISOString()} DOCTOR ${text}\n`); } catch { /* the doctor's own log has it */ } };
+  // the operator switched it on but it cannot run (no repository, no spending cap): said out loud, never silently off
+  if (!cfg.on) { if (cfg.problem) alert(`cannot run: ${cfg.problem}`); return { handled: false, why: cfg.problem || 'the doctor is off' }; }
+
+  const d = open(runDir, cfg, profile);
+  const portRoot = path.join(install, profile.install.dest);
+
+  const c = classify({ profile, portRoot, res, crash, aborted, since });
+  if (!c.call) { d.event('not-called', { kind: c.kind, why: c.why }); return { handled: false, kind: c.kind, why: c.why }; }
+  d.event('trigger', { kind: c.kind, layer: c.layer, why: c.why, step: (crash && crash.step) || '' });
+
+  let attempt = null;
+  const stop = (reason, why, extra) => {
+    d.event('stop', { reason, why }, attempt && attempt.n);
+    if (attempt) fs.writeFileSync(path.join(attempt.dir, 'verdict.json'), `${JSON.stringify({ status: 'stopped', reason, why }, null, 2)}\n`);
+    alert(`stopped (${reason}): ${why}`);
+    return { handled: true, restarted: false, stopped: reason, why, ...(extra || {}) };
+  };
+
+  // one repair per failure the restarts can follow: attempts = the quota the operator gave + 1 (the quota 0 still repairs once)
+  if (d.attemptsMade() >= cfg.restarts + 1) return stop('attempts', `${d.attemptsMade()} repair attempt(s) already made for a quota of ${cfg.restarts} restart(s)`);
+
+  const comp = checkComponent({ repo: cfg.repo, profile, protectedRepos });
+  if (!comp.ok) return stop('not-the-component', comp.why);
+  const repo = comp.root;
+  const stale = installedMismatches({ repo, branch: 'HEAD', install, profile });
+  if (stale.length) return stop('repo-not-installed', `the repository's HEAD is not what is installed (${stale.slice(0, 6).join(', ')}) — a repair on it would overwrite the install with other code`);
+
+  attempt = d.nextAttempt();
+  const A = attempt.dir;
+  fs.writeFileSync(path.join(A, 'trigger.json'), `${JSON.stringify({ res, crash, classified: c, run: runId }, null, 2)}\n`);
+  const ev = path.join(A, 'evidence'); fs.mkdirSync(ev, { recursive: true });
+  // a crash leaves its record; an abort an agent caused leaves only the leg's result — that is then the evidence
+  if (crash) fs.writeFileSync(path.join(ev, profile.crash.file), `${JSON.stringify(crash, null, 2)}\n`);
+  else fs.writeFileSync(path.join(ev, 'leg-result.json'), `${JSON.stringify(res, null, 2)}\n`);
+  for (const f of profile.logs.evidence) fs.writeFileSync(path.join(ev, path.basename(f)), tail(path.join(runDir, f), profile.logs.evidenceTailLines));
+
+  const base = git(repo, 'rev-parse', 'HEAD').stdout.trim();
+  const branch = `${profile.branch.prefix}${runId}-${attempt.n}`;
+  const wt = path.join(A, 'wt');
+  const mk = git(repo, 'worktree', 'add', '-b', branch, wt, 'HEAD');
+  if (mk.status !== 0) return stop('worktree', `cannot make the repair's work tree: ${mk.stderr.trim()}`);
+  try {
+    const top = crash && (crash.frames || []).find((f) => f && typeof f.file === 'string' && !/^node:/.test(f.file));
+    const prompt = renderPrompt({ run: runId, attempt: attempt.n, step: (crash && crash.step) || 'unknown',
+      errorName: crash ? crash.name : 'agentic-abort', errorMessage: String(crash ? crash.message : res.reason).slice(0, 400),
+      throwSite: crash ? (top ? `${top.file}:${top.line}` : 'unknown') : 'no throw — an abort an agent caused', evidenceDir: ev, runDir, install, branch,
+      abortKind: c.kind, layerHint: c.layer }, profile);
+    fs.writeFileSync(path.join(A, 'prompt.txt'), prompt);
+
+    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 });
+    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
+    const touched = repoChanges(before, snapshotRepos(protectedRepos || []));
+    if (touched.length) { d.event('client-code-touched', { repos: touched }, attempt.n); return stop('client-code-touched', `the session changed protected client code — ${touched.join('; ')} — the repair is refused and nothing is installed`); }
+
+    if (!r.answer || !['code', 'agentic'].includes(r.answer.layer)) return stop('no-answer', `the agent gave no readable answer, or one that names no layer (exit ${r.exit})`);
+    if (r.answer.status === 'cannot') return stop('cannot', `the agent could not repair it: ${r.answer.summary}`);
+    if (git(wt, 'status', '--porcelain', '--untracked-files=no').stdout.trim()) return stop('uncommitted', 'the agent left changes to tracked files uncommitted');
+
+    const layer = r.answer.layer;
+    const v = verifyRepair({ repo, base, branch, profile, layer, abortKind: c.kind });
+    fs.writeFileSync(path.join(A, 'red.txt'), v.red || ''); fs.writeFileSync(path.join(A, 'green.txt'), v.green || '');
+    fs.writeFileSync(path.join(A, 'patch.diff'), git(repo, 'diff', `${base}..${branch}`).stdout);
+    if (!v.ok) { d.event('repair-rejected', { why: v.why }, attempt.n); return stop('rejected', v.why); }
+    d.event('verified', { layer, layerWhy: r.answer.layerWhy, files: v.files, why: v.why }, attempt.n);
+
+    // AGENTIC FIRST (operator, 2026-10-20): an agentic repair changes how agents are instructed or wired; where the pipeline's profile does not let such a
+    // repair apply itself, it is verified, kept on its branch, and left for the operator — said out loud
+    if (layer === 'agentic' && !profile.agentic.autoApply) {
+      const why = `an agentic repair is verified but the pipeline's profile does not let it apply itself (agentic.autoApply is false)`;
+      fs.writeFileSync(path.join(A, 'verdict.json'), `${JSON.stringify({ status: 'verified-not-installed', layer, layerWhy: r.answer.layerWhy, summary: r.answer.summary, cause: r.answer.cause, files: v.files, branch }, null, 2)}\n`);
+      d.event('agentic-awaits-approval', { branch, layerWhy: r.answer.layerWhy }, attempt.n);
+      alert(`AGENTIC repair verified on branch ${branch} — NOT installed: ${r.answer.summary} (${r.answer.layerWhy}); the operator decides`);
+      return { handled: true, repaired: true, restarted: false, stopped: 'agentic-awaits-approval', why, branch };
+    }
+
+    const ri = reinstall({ repo, branch, install, run: runId, attempt: attempt.n, files: v.files, profile });
+    fs.writeFileSync(path.join(A, 'reinstall.txt'), `${ri.installer || ''}\n${ri.why}\n${(ri.mismatches || []).join('\n')}\n`);
+    if (!ri.ok) return stop('reinstall-failed', ri.why);
+    d.event('reinstalled', { layer, commit: ri.commit, files: v.files }, attempt.n);
+
+    fs.writeFileSync(path.join(A, 'verdict.json'), `${JSON.stringify({ status: 'repaired', layer, layerWhy: r.answer.layerWhy, summary: r.answer.summary, cause: r.answer.cause, files: v.files, branch, commit: ri.commit }, null, 2)}\n`);
+    d.event('repaired', { layer, layerWhy: r.answer.layerWhy, summary: r.answer.summary, cause: r.answer.cause, branch, commit: ri.commit }, attempt.n);
+    alert(`repaired${layer === 'agentic' ? ' (AGENTIC LAYER — how agents are instructed or wired changed, not only code)' : ''}: ${r.answer.summary} (${r.answer.cause}) — branch ${branch}, ${v.files.length} file(s), installed`);
+
+    const rs = await restart({ state: d, profile, runDir, needMb: a.needMb, reserveMb: a.reserveMb, availableMb: a.availableMb, heavyJobs: a.heavyJobs, launch: relaunch });
+    if (!rs.restarted) alert(`not restarted: ${rs.why}`);
+    return { handled: true, repaired: true, restarted: rs.restarted, why: rs.why, branch, result: rs.result };
+  } finally { git(repo, 'worktree', 'remove', '--force', wt); git(repo, 'worktree', 'prune'); }
+}
+
+module.exports = { handle };

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

@@ -0,0 +1,130 @@
+'use strict';
+// THE DOCTOR'S PROFILE — what a pipeline declares so the doctor holds none of that pipeline's facts (operator, 2026-10-20: "no
+// hardcoding … there will be multiple pipelines in play now"). The doctor repairs the code of ONE component of a pipeline when a run
+// fails on a defect in it; everything that is about that component — its repairable directories, how its tests run, how it is
+// installed, what it must never touch, the names of its settings and logs — is read from its profile. A pipeline's own facts are
+// never defaulted: a profile with anything missing or wrong is refused, every problem named by its field, all at once.
+//   validate(object) → { problems: string[], profile: compiled | null }        load(file) → the same, from a JSON file
+const fs = require('fs');
+
+const SECTIONS = ['component', 'scope', 'test', 'install', 'crash', 'classify', 'settings', 'restart', 'model', 'logs', 'branch', 'boundaries', 'agentic'];
+const ENV_NAME = /^[A-Z][A-Z0-9_]*$/;
+const MANIFESTS = ['package.json#files'];       // how the files a component ships are listed (the only manifest the doctor can read)
+
+function validate(input) {
+  const problems = [];
+  const p = input && typeof input === 'object' && !Array.isArray(input) ? input : {};
+  const out = {};
+  const bad = (field, why) => problems.push(`${field}: ${why}`);
+  const has = (o, k) => o && typeof o === 'object' && Object.prototype.hasOwnProperty.call(o, k);
+
+  const str = (path, v) => { if (typeof v !== 'string' || !v.trim()) { bad(path, 'a non-empty string is required'); return null; } return v; };
+  const strs = (path, v, { nonEmpty }) => {
+    if (!Array.isArray(v) || !v.every((x) => typeof x === 'string' && x.trim())) { bad(path, 'a list of non-empty strings is required'); return null; }
+    if (nonEmpty && !v.length) { bad(path, 'at least one entry is required'); return null; }
+    return v;
+  };
+  const rel = (path, v) => { // a path inside a folder: relative, no climbing out
+    const s = str(path, v); if (s === null) return null;
+    if (s.startsWith('/') || s.split('/').includes('..')) { bad(path, `"${s}" must be relative and stay inside its folder`); return null; }
+    return s;
+  };
+  const file = (path, v) => { const s = str(path, v); if (s === null) return null; if (s.includes('/') || s === '..' || s === '.') { bad(path, `"${s}" must be a plain file name`); return null; } return s; };
+  const rx = (path, v) => {
+    if (typeof v !== 'string') { bad(path, 'a pattern string is required'); return null; }
+    if (!v) { bad(path, 'a non-empty pattern is required'); return null; }
+    try { return new RegExp(v); } catch (e) { bad(path, `not a valid pattern (${e.message})`); return null; }
+  };
+  const rxs = (path, v) => { if (!Array.isArray(v)) { bad(path, 'a list of patterns is required'); return null; } return v.map((x, i) => rx(`${path}[${i}]`, x)).filter(Boolean); };
+  const section = (k) => { if (!has(p, k)) { bad(k, 'this section is required'); return null; } return p[k]; };
+  const need = (sec, o, k) => { if (!has(o, k)) { bad(`${sec}.${k}`, 'this field is required'); return false; } return true; };
+
+  for (const k of SECTIONS) section(k);
+  const c = p.component; if (c) { for (const k of ['name', 'package', 'description']) if (need('component', c, k)) str(`component.${k}`, c[k]); out.component = { ...c }; }
+
+  const s = p.scope;
+  if (s) {
+    out.scope = {};
+    if (need('scope', s, 'repairDirs')) { const v = strs('scope.repairDirs', s.repairDirs, { nonEmpty: true }); if (v) { v.forEach((d, i) => rel(`scope.repairDirs[${i}]`, d)); out.scope.repairDirs = v; } }
+    if (need('scope', s, 'testDirs')) { const v = strs('scope.testDirs', s.testDirs, { nonEmpty: true }); if (v) { v.forEach((d, i) => rel(`scope.testDirs[${i}]`, d)); out.scope.testDirs = v; } }
+    if (need('scope', s, 'testFile')) out.scope.testFile = rx('scope.testFile', s.testFile);
+    if (need('scope', s, 'forbiddenTests')) out.scope.forbiddenTests = rxs('scope.forbiddenTests', s.forbiddenTests);
+  }
+
+  const t = p.test;
+  if (t) {
+    out.test = {};
+    if (need('test', t, 'command')) { const v = strs('test.command', t.command, { nonEmpty: true }); if (v) { if (!v.includes('{files}')) bad('test.command', 'must contain {files} as an entry of its own, where the test files go'); out.test.command = v; } }
+    if (need('test', t, 'envUnset')) out.test.envUnset = strs('test.envUnset', t.envUnset, { nonEmpty: false });
+    if (need('test', t, 'greenPatterns')) { if (Array.isArray(t.greenPatterns) && !t.greenPatterns.length) bad('test.greenPatterns', 'at least one pattern is required'); out.test.greenPatterns = rxs('test.greenPatterns', t.greenPatterns); }
+    if (need('test', t, 'failedPattern')) out.test.failedPattern = rx('test.failedPattern', t.failedPattern);
+  }
+
+  const i = p.install;
+  if (i) {
+    out.install = {};
+    if (need('install', i, 'dest')) out.install.dest = rel('install.dest', i.dest);
+    if (need('install', i, 'requires')) { const v = strs('install.requires', i.requires, { nonEmpty: false }); if (v) { v.forEach((d, n) => rel(`install.requires[${n}]`, d)); out.install.requires = v; } }
+    if (need('install', i, 'command')) { const v = strs('install.command', i.command, { nonEmpty: true }); if (v) { for (const ph of ['{worktree}', '{install}']) if (!v.some((x) => x.includes(ph))) bad('install.command', `must contain ${ph}`); out.install.command = v; } }
+    if (need('install', i, 'manifest')) { if (!MANIFESTS.includes(i.manifest)) bad('install.manifest', `must be one of: ${MANIFESTS.join(', ')}`); else out.install.manifest = i.manifest; }
+    if (need('install', i, 'patchRecord')) out.install.patchRecord = file('install.patchRecord', i.patchRecord);
+  }
+
+  if (p.crash) { if (need('crash', p.crash, 'file')) out.crash = { file: file('crash.file', p.crash.file) }; }
+
+  const cl = p.classify;
+  if (cl) {
+    out.classify = {};
+    if (need('classify', cl, 'runtime')) out.classify.runtime = str('classify.runtime', cl.runtime);
+    if (need('classify', cl, 'refusals')) out.classify.refusals = rxs('classify.refusals', cl.refusals);
+  }
+
+  const se = p.settings;
+  if (se) {
+    out.settings = {};
+    for (const k of ['on', 'restarts', 'repo', 'budget']) if (need('settings', se, k)) { const v = str(`settings.${k}`, se[k]); if (v !== null && !ENV_NAME.test(v)) bad(`settings.${k}`, `"${v}" must be an environment variable name (A-Z, 0-9, _)`); else out.settings[k] = v; }
+    const names = ['on', 'restarts', 'repo', 'budget'].map((k) => se[k]).filter(Boolean);
+    if (new Set(names).size !== names.length) bad('settings', 'the four setting names must be different');
+  }
+
+  if (p.restart) { if (need('restart', p.restart, 'args')) out.restart = { args: strs('restart.args', p.restart.args, { nonEmpty: true }) }; }
+
+  const m = p.model;
+  if (m) { out.model = {}; for (const k of ['family', 'config']) if (need('model', m, k)) out.model[k] = str(`model.${k}`, m[k]); }
+
+  const lg = p.logs;
+  if (lg) {
+    out.logs = {};
+    if (need('logs', lg, 'dir')) out.logs.dir = rel('logs.dir', lg.dir);
+    if (need('logs', lg, 'alerts')) out.logs.alerts = file('logs.alerts', lg.alerts);
+    if (need('logs', lg, 'evidence')) { const v = strs('logs.evidence', lg.evidence, { nonEmpty: false }); if (v) { v.forEach((d, n) => rel(`logs.evidence[${n}]`, d)); out.logs.evidence = v; } }
+    if (need('logs', lg, 'evidenceTailLines')) { if (!Number.isInteger(lg.evidenceTailLines) || lg.evidenceTailLines < 1) bad('logs.evidenceTailLines', 'a positive whole number is required'); else out.logs.evidenceTailLines = lg.evidenceTailLines; }
+  }
+
+  // THE AGENTIC LAYER (operator, 2026-10-20: look for the agentic solution before the deterministic one; an agentic abort is repaired agentically):
+  // where the pipeline's agents are instructed and wired — prompts, answer schemas, agent definitions, hand-offs between agents — inside the repairable
+  // directories; which leg messages mean an AGENT caused the abort (patterns); whether a verified agentic repair is applied without waiting for the operator
+  const ag = p.agentic;
+  if (ag) {
+    out.agentic = {};
+    if (need('agentic', ag, 'dirs')) { const v = strs('agentic.dirs', ag.dirs, { nonEmpty: true }); if (v) { v.forEach((d, i) => { if (rel(`agentic.dirs[${i}]`, d) !== null && out.scope && out.scope.repairDirs && !out.scope.repairDirs.includes(d.split('/')[0])) bad(`agentic.dirs[${i}]`, `"${d}" must be inside one of scope.repairDirs`); }); out.agentic.dirs = v; } }
+    if (need('agentic', ag, 'abortSignatures')) out.agentic.abortSignatures = rxs('agentic.abortSignatures', ag.abortSignatures);
+    if (need('agentic', ag, 'autoApply')) { if (typeof ag.autoApply !== 'boolean') bad('agentic.autoApply', 'true or false is required'); else out.agentic.autoApply = ag.autoApply; }
+    if (need('agentic', ag, 'description')) out.agentic.description = str('agentic.description', ag.description);
+  }
+
+  if (p.branch) { if (need('branch', p.branch, 'prefix')) out.branch = { prefix: str('branch.prefix', p.branch.prefix) }; }
+  if (has(p, 'boundaries')) out.boundaries = strs('boundaries', p.boundaries, { nonEmpty: true });
+
+  return problems.length ? { problems, profile: null } : { problems, profile: out };
+}
+
+function load(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch (e) { return { problems: [`cannot read ${file}: ${e.message}`], profile: null }; }
+  let obj;
+  try { obj = JSON.parse(text); } catch (e) { return { problems: [`${file} is not JSON: ${e.message}`], profile: null }; }
+  return validate(obj);
+}
+
+module.exports = { validate, load, SECTIONS, MANIFESTS };

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

@@ -0,0 +1,166 @@
+'use strict';
+// THE REPAIR, ACCEPTED ONLY ON EVIDENCE, REINSTALLED THROUGH THE COMPONENT'S OWN INSTALLER, AND CLIENT CODE NEVER TOUCHED (operator,
+// 2026-10-20: "crash - fix - test - commit - reinstall - restart"; "doctor can ONLY change pipeline related code - not client codeline
+// code"). The agent that repairs is a model; what accepts its work is not: the doctor re-runs the test itself — RED on the base with only the
+// test added, GREEN with the fix — and reads the diff's file list. A repair that proves nothing, touches anything outside the component's
+// repairable directories, or leans on a monolithic test is refused, and the install is never touched. Every fact about the pipeline —
+// its directories, how its tests run and read, its installer, where it installs, what its patch record is called — is its profile's.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const git = (repo, ...a) => spawnSync('git', ['-C', repo, ...a], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+const bad = (why, extra) => ({ ok: false, why, ...(extra || {}) });
+
+/** The host's memory wrapper (every process memory-bounded — the operator's standing rule), when the host has one: AMSD_BOUNDED, else ~/.claude/bin/bounded. */
+function hostWrap() {
+  const b = process.env.AMSD_BOUNDED || path.join(os.homedir(), '.claude', 'bin', 'bounded');
+  return fs.existsSync(b) ? [b, '--want', '2048', '--'] : [];
+}
+
+/** A profile command with its placeholders filled; an entry that is exactly {files} becomes the files. */
+function expand(command, vars) {
+  return command.flatMap((tok) => (tok === '{files}' ? vars.files : [tok.replace(/\{(node|worktree|install)\}/g, (_, k) => vars[k])]));
+}
+
+/** The component's tests in a work tree; the output is the evidence. */
+function runTests(wt, files, profile) {
+  const c = [...hostWrap(), ...expand(profile.test.command, { node: process.execPath, files })];
+  // a test run started inside another test run inherits that runner's context and then reports "passed" whatever happened: the run under
+  // judgement gets the environment the profile names it needs clean, so its exit code is its own
+  const env = { ...process.env }; for (const k of profile.test.envUnset) delete env[k];
+  const r = spawnSync(c[0], c.slice(1), { cwd: wt, env, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  return { status: r.status, out: `${r.stdout || ''}${r.stderr || ''}` };
+}
+
+/** A throwaway work tree of <rev>; removed by the caller's finally. */
+function worktree(repo, rev) {
+  const wt = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-wt-'));
+  fs.rmSync(wt, { recursive: true, force: true });
+  const r = git(repo, 'worktree', 'add', '--detach', '-q', wt, rev);
+  if (r.status !== 0) throw new Error(`worktree of ${rev}: ${r.stderr}`);
+  return wt;
+}
+const drop = (repo, wt) => { git(repo, 'worktree', 'remove', '--force', wt); git(repo, 'worktree', 'prune'); fs.rmSync(wt, { recursive: true, force: true }); };
+
+function verifyRepair({ repo, base, branch, profile, layer, abortKind }) {
+  // the layer the agent says it repaired and how the abort was classified: both required, neither defaulted
+  if (!['code', 'agentic'].includes(layer)) throw new Error(`verifyRepair needs layer 'code' or 'agentic', got ${JSON.stringify(layer)}`);
+  if (typeof abortKind !== 'string' || !abortKind) throw new Error('verifyRepair needs abortKind (how the abort was classified)');
+  const d = git(repo, 'diff', '--name-only', `${base}..${branch}`);
+  if (d.status !== 0) return bad(`cannot read the repair's diff: ${d.stderr.trim()}`);
+  const files = d.stdout.split('\n').filter(Boolean);
+  if (!files.length) return bad('the repair changed nothing');
+  const { repairDirs, testDirs, testFile, forbiddenTests } = profile.scope;
+  const out = files.filter((f) => { const n = path.posix.normalize(f); return n.startsWith('..') || path.isAbsolute(n) || ![...repairDirs, ...testDirs].includes(n.split('/')[0]); });
+  if (out.length) return bad(`outside the component: ${out.join(', ')} — only ${[...repairDirs, ...testDirs].join(', ')} may change`, { files });
+  const tests = files.filter((f) => testFile.test(f));
+  // AGENTIC FIRST (operator, 2026-10-20): an abort an agent caused is repaired in the agentic layer; a repair that calls itself agentic changes only that layer
+  if (abortKind === 'agentic-abort' && layer !== 'agentic') return bad('an agentic abort is repaired agentically: a deterministic (code) change for an abort an agent caused only hides the agent\'s behaviour', { files });
+  if (layer === 'agentic') {
+    const inLayer = (f) => profile.agentic.dirs.some((d) => f === d || f.startsWith(`${d}/`));
+    const outside = files.filter((f) => !tests.includes(f) && !testDirs.includes(f.split('/')[0]) && !inLayer(f));
+    if (outside.length) return bad(`outside the agentic layer (${profile.agentic.dirs.join(', ')}): ${outside.join(', ')} — an agentic repair changes how agents are instructed and wired, nothing else`, { files });
+  }
+  const src = files.filter((f) => repairDirs.includes(f.split('/')[0]));
+  if (!src.length) return bad('no change to the component itself: only tests changed', { files });
+  if (!tests.length) return bad('no test: a repair without a test that fails first proves nothing', { files });
+  const mono = tests.filter((f) => forbiddenTests.some((r) => r.test(f)));
+  if (mono.length) return bad(`monolithic test(s): ${mono.join(', ')} — targeted tests only (operator rule)`, { files });
+
+  let wtBase = null; let wtTip = null;
+  try {
+    // RED: the base, with ONLY the repair's tests added — they must fail there (a test that cannot even load is caught by the GREEN run)
+    wtBase = worktree(repo, base);
+    const co = git(wtBase, 'checkout', branch, '--', ...tests);
+    if (co.status !== 0) return bad(`cannot place the tests on the base: ${co.stderr.trim()}`, { files });
+    const red = runTests(wtBase, tests, profile);
+    if (red.status === 0) return bad('the test passes without the fix: it is not RED, so it proves nothing', { files, red: red.out });
+    // GREEN: the branch's tip
+    wtTip = worktree(repo, branch);
+    const green = runTests(wtTip, tests, profile);
+    if (green.status !== 0 || !profile.test.greenPatterns.every((r) => r.test(green.out))) return bad('the test fails with the fix: not GREEN', { files, red: red.out, green: green.out });
+    return { ok: true, why: 'RED on the base, GREEN with the fix', files, tests, red: red.out, green: green.out };
+  } finally { if (wtBase) drop(repo, wtBase); if (wtTip) drop(repo, wtTip); }
+}
+
+// ── the reinstall: the component's own installer, then every packaged file compared byte for byte ─────────────────────
+const show = (repo, rev, rel) => spawnSync('git', ['-C', repo, 'show', `${rev}:${rel}`], { encoding: 'buffer', maxBuffer: 64 * 1024 * 1024 });
+
+/** The files the component ships at <branch>: the manifest's entries expanded from the branch's tree, plus the manifest file itself. */
+function packaged(repo, branch) {
+  const pj = show(repo, branch, 'package.json'); if (pj.status !== 0) return [];
+  const prefixes = (JSON.parse(pj.stdout.toString()).files || []).map((f) => f.replace(/\/$/, ''));
+  const all = git(repo, 'ls-tree', '-r', '--name-only', branch).stdout.split('\n').filter(Boolean);
+  return [...new Set([...all.filter((f) => prefixes.some((p) => f === p || f.startsWith(`${p}/`))), 'package.json'])].sort();
+}
+
+/** The packaged files that are not byte-identical under <install>/<dest> (missing counts). */
+function installedMismatches({ repo, branch, install, profile }) {
+  const dest = path.join(install, profile.install.dest);
+  return packaged(repo, branch).filter((rel) => {
+    const want = show(repo, branch, rel); const f = path.join(dest, rel);
+    return want.status !== 0 || !fs.existsSync(f) || !want.stdout.equals(fs.readFileSync(f));
+  });
+}
+
+function reinstall({ repo, branch, install, run, attempt, files, profile }) {
+  const missing = profile.install.requires.filter((r) => !fs.existsSync(path.join(install, r)));
+  if (missing.length) return bad(`${install} is not an install of this pipeline (missing: ${missing.join(', ')})`);
+  const dest = path.join(install, profile.install.dest);
+  let prev = []; try { prev = JSON.parse(fs.readFileSync(path.join(dest, profile.install.patchRecord), 'utf8')).patches || []; } catch { prev = []; }
+  const commit = git(repo, 'rev-parse', branch).stdout.trim();
+  let wt = null;
+  try {
+    wt = worktree(repo, branch);
+    const c = expand(profile.install.command, { node: process.execPath, worktree: wt, install });
+    const r = spawnSync(c[0], c.slice(1), { cwd: wt, encoding: 'utf8' });
+    if (r.status !== 0) return bad(`the component's installer failed: ${(r.stderr || r.stdout).slice(-600)}`);
+    const mismatches = installedMismatches({ repo, branch, install, profile });
+    if (mismatches.length) return bad(`installed files differ from the branch: ${mismatches.join(', ')}`, { mismatches, installer: r.stdout });
+    const patches = [...prev, { at: new Date().toISOString(), run, attempt, branch, commit, files: files || [] }];
+    fs.writeFileSync(path.join(dest, profile.install.patchRecord), `${JSON.stringify({ note: 'this install carries repairs made by the pipeline doctor that are not in a release', patches }, null, 2)}\n`);
+    return { ok: true, why: 'reinstalled through the component\'s installer; every packaged file matches the branch', mismatches: [], installer: r.stdout, commit };
+  } finally { if (wt) drop(repo, wt); }
+}
+
+// ── client code is never the doctor's ───────────────────────────────────────────────────────────────────────────────────
+const real = (p) => { try { return fs.realpathSync(p); } catch { return null; } };
+
+/** The repository to repair must BE the profile's component, and never a protected (client) repository or one that holds or sits inside one. */
+function checkComponent({ repo, profile, protectedRepos }) {
+  const top = git(repo, 'rev-parse', '--show-toplevel');
+  if (top.status !== 0) return bad(`${repo} is not a git repository`);
+  const root = real(top.stdout.trim());
+  let name = null; try { name = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name; } catch { name = null; }
+  if (name !== profile.component.package) return bad(`${root} is not the component: its package is "${name}", the profile's is "${profile.component.package}"`);
+  for (const p of (protectedRepos || [])) {
+    const q = real(p); if (!q) continue;
+    if (root === q || root.startsWith(`${q}${path.sep}`) || q.startsWith(`${root}${path.sep}`)) return bad(`${root} is protected client code (${q}): the doctor never works there`);
+  }
+  return { ok: true, why: 'the profile\'s component, not client code', root };
+}
+
+/** Everything that identifies a repository's state — its HEAD, every ref, and its status including untracked files. */
+function snapshotRepos(repos) {
+  const out = {};
+  for (const r of repos) {
+    if (!fs.existsSync(r)) { out[r] = { missing: true }; continue; }
+    out[r] = { head: git(r, 'rev-parse', 'HEAD').stdout.trim(), refs: git(r, 'for-each-ref', '--format=%(refname) %(objectname)').stdout, status: git(r, 'status', '--porcelain', '--untracked-files=all').stdout };
+  }
+  return out;
+}
+
+/** The protected repositories whose state differs between two snapshots, each named with what changed. */
+function repoChanges(before, after) {
+  const out = [];
+  for (const r of Object.keys(before)) {
+    const a = before[r]; const b = after[r] || { missing: true };
+    const what = ['head', 'refs', 'status', 'missing'].filter((k) => a[k] !== b[k]);
+    if (what.length) out.push(`${r}: ${what.join(', ')} changed`);
+  }
+  return out;
+}
+
+module.exports = { verifyRepair, reinstall, installedMismatches, packaged, checkComponent, snapshotRepos, repoChanges, expand, hostWrap };

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

@@ -0,0 +1,58 @@
+'use strict';
+// THE RESTARTER (operator, 2026-10-20: "the doctor has to be able to restart so maybe a restart agent as well"). Not an agent and not the
+// doctor: the relaunch of a leg is a launch, and a launch obeys the rules of every launch — the quota the operator gave, the memory a
+// launch needs on this host, no other heavy job running — so it is deterministic, and every check it makes is in its own log
+// (<run>/<profile.logs.dir>/restarter.jsonl). A restart is counted only when it is taken; the run's recorded launch settings are replayed by the
+// pipeline's own resume (the profile's restart.args).
+const fs = require('fs');
+const path = require('path');
+
+/** The jobs another launch must not share the host with (operator rule) — the rules are data (config/doctor-heavy-jobs.json), not code. */
+function heavyJobs({ exclude, rules } = {}) {
+  const R = rules || JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', '..', 'config', 'doctor-heavy-jobs.json'), 'utf8'));
+  const skip = new Set([...(exclude || []), process.pid]);
+  // this process's ancestors are the launcher's own shell and tools, never "another job"
+  for (let p = process.ppid, n = 0; p > 1 && n < 64; n += 1) { skip.add(p); let st; try { st = fs.readFileSync(`/proc/${p}/stat`, 'utf8'); } catch { break; } p = Number(st.slice(st.lastIndexOf(')') + 2).split(' ')[1]); }
+  const out = [];
+  for (const d of fs.readdirSync('/proc').filter((x) => /^\d+$/.test(x))) {
+    const pid = Number(d); if (skip.has(pid)) continue;
+    let argv; try { argv = fs.readFileSync(`/proc/${d}/cmdline`, 'utf8').split('\0').filter(Boolean); } catch { continue; }
+    const names = argv.map((t) => path.basename(t));
+    let what = names.find((t) => R.tokens.includes(t)) || null;
+    if (!what) for (const f of R.withFlag) { const i = names.findIndex((t) => t === f.bin); if (i >= 0 && argv.slice(i + 1).includes(f.flag)) { what = f.as || `${f.bin} ${f.flag}`; break; } }
+    if (what) out.push(`${what} (pid ${pid})`);
+  }
+  return out;
+}
+
+const availableMbNow = () => { const m = fs.readFileSync('/proc/meminfo', 'utf8').match(/MemAvailable:\s+(\d+)/); return m ? Math.floor(Number(m[1]) / 1024) : 0; };
+
+async function restart({ state, profile, runDir, needMb, reserveMb, availableMb, heavyJobs: heavy, launch }) {
+  const logf = path.join(runDir, profile.logs.dir, 'restarter.jsonl');
+  const note = (check, ok, detail) => { fs.mkdirSync(path.dirname(logf), { recursive: true }); fs.appendFileSync(logf, `${JSON.stringify({ at: new Date().toISOString(), check, ok, detail })}\n`); state.event(`restarter-${check}`, { ok, detail }); };
+  const refuse = (check, detail) => { note(check, false, detail); return { restarted: false, why: `${check}: ${detail}` }; };
+
+  const q = state.quota();
+  if (q.left < 1) return refuse('quota', `given ${q.given}, used ${q.used} — no restart left`);
+  note('quota', true, `given ${q.given}, used ${q.used}, ${q.left} left`);
+
+  const avail = (availableMb || availableMbNow)(); const room = avail - reserveMb;
+  if (room < needMb) return refuse('memory', `${avail} MB available − ${reserveMb} MB kept for the host = ${room} MB for the run; a launch needs ${needMb} MB`);
+  note('memory', true, `${avail} MB available − ${reserveMb} MB kept = ${room} MB for the run; needs ${needMb} MB`);
+
+  const jobs = (heavy || heavyJobs)();
+  if (jobs.length) return refuse('heavy-jobs', `another heavy job is running: ${jobs.join(', ')}`);
+  note('heavy-jobs', true, 'none');
+
+  state.useRestart();                                    // counted when it is taken, not before
+  try {
+    const result = await launch(profile.restart.args);
+    note('launch', true, JSON.stringify(result).slice(0, 300));
+    return { restarted: true, why: 'relaunched with the profile\'s restart arguments', result };
+  } catch (e) {
+    note('launch', false, e.message);
+    return { restarted: false, why: `launch: ${e.message}` };
+  }
+}
+
+module.exports = { restart, heavyJobs };

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

@@ -0,0 +1,65 @@
+'use strict';
+// THE DOCTOR'S SETTINGS, QUOTA AND ITS OWN LOGS (operator, 2026-10-20). Everything the doctor does is recorded under <run>/<profile.logs.dir>/
+// and nowhere else: the run's own logs and ledgers are never written, so the run's cost and the doctor's can never be confused.
+//   events.jsonl  append-only, one line per action (seq, at, attempt, type, data)     doctor.log  the same, readable — the file to tail
+//   cost.jsonl    every model call the doctor made, with a running total             quota.json  given, used, left
+//   <n>/          one folder per repair attempt (the evidence: trigger, diagnosis, red, green, patch, reinstall, verdict)
+const fs = require('fs');
+const path = require('path');
+
+/** The doctor's launch settings, from the run's recorded launch values, under the NAMES the pipeline's profile gives them. Anything not exactly right is the safe value. */
+function settings(values, profile) {
+  const v = values || {}; const n = profile.settings;
+  const restarts = /^\d+$/.test(String(v[n.restarts] || '')) ? Number(v[n.restarts]) : 0;
+  const repo = v[n.repo] ? String(v[n.repo]) : null;
+  // THE SPENDING CAP of one repair session (a launch setting the operator gives): without a usable one the doctor does not spend — it is not on
+  const budget = /^\d+(\.\d+)?$/.test(String(v[n.budget] || '')) && Number(v[n.budget]) > 0 ? Number(v[n.budget]) : null;
+  const wants = v[n.on] === 'on';
+  const lacks = [!repo && `${n.repo} — the checkout of ${profile.component.package} it repairs`, !budget && `${n.budget} — a spending cap in dollars for one repair session (a positive number)`].filter(Boolean);
+  const problem = wants && lacks.length ? `${n.on}=on needs ${lacks.join(' and ')}` : null;
+  return { on: wants && !!repo && !!budget, restarts, repo, budget, problem };
+}
+
+const readJson = (f, dflt) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return dflt; } };
+const jsonl = (f) => { try { return fs.readFileSync(f, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l)); } catch { return []; } };
+
+/** Opens (or re-opens, on a resume) the doctor's folder in a run directory. */
+function open(runDir, cfg, profile) {
+  const dir = path.join(runDir, profile.logs.dir);
+  fs.mkdirSync(dir, { recursive: true });
+  const files = { events: path.join(dir, 'events.jsonl'), log: path.join(dir, 'doctor.log'), cost: path.join(dir, 'cost.jsonl'), quota: path.join(dir, 'quota.json') };
+  let seq = jsonl(files.events).reduce((m, e) => Math.max(m, e.seq || 0), 0);
+  let total = jsonl(files.cost).reduce((m, r) => Math.max(m, r.totalUsd || 0), 0);
+  let used = (readJson(files.quota, {}) || {}).used || 0;
+  const given = cfg.restarts || 0;
+
+  const writeQuota = () => fs.writeFileSync(files.quota, `${JSON.stringify({ given, used, left: Math.max(0, given - used) })}\n`);
+  writeQuota();
+
+  function event(type, data, attempt) {
+    seq += 1;
+    const rec = { seq, at: new Date().toISOString(), attempt: attempt || 0, type, data: data || {} };
+    fs.appendFileSync(files.events, `${JSON.stringify(rec)}\n`);
+    fs.appendFileSync(files.log, `${rec.at} #${seq}${attempt ? ` [attempt ${attempt}]` : ''} ${type} ${JSON.stringify(rec.data)}\n`);
+    return rec;
+  }
+  function cost(row) {
+    total += Number(row.costUsd) || 0;
+    fs.appendFileSync(files.cost, `${JSON.stringify({ at: new Date().toISOString(), ...row, totalUsd: total })}\n`);
+    return total;
+  }
+  function useRestart() {
+    if (used >= given) { event('quota-exhausted', { given, used }); return false; }
+    used += 1; writeQuota(); event('restart-counted', { given, used });
+    return true;
+  }
+  function nextAttempt() {
+    const n = fs.readdirSync(dir).filter((x) => /^\d+$/.test(x)).reduce((m, x) => Math.max(m, Number(x)), 0) + 1;
+    const d = path.join(dir, String(n)); fs.mkdirSync(d, { recursive: true });
+    return { n, dir: d };
+  }
+  const attemptsMade = () => fs.readdirSync(dir).filter((x) => /^\d+$/.test(x)).length;
+  return { dir, files, event, cost, spent: () => total, useRestart, nextAttempt, attemptsMade, quota: () => ({ given, used, left: Math.max(0, given - used) }) };
+}
+
+module.exports = { settings, open };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amsd-pipeline-shared",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "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": {