wicked-crew 0.3.2 → 0.5.0

package/dist/core/adapter.js

@@ -1,18 +1,34 @@
 import { createRequire } from 'node:module';
-import { execFile } from 'node:child_process';
 import { mkdir, access, readFile, writeFile, chmod, rm } from 'node:fs/promises';
+import { existsSync, readdirSync, readFileSync, renameSync } from 'node:fs';
 import { join, dirname, resolve, isAbsolute, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
-import { promisify } from 'node:util';
 import { randomUUID } from 'node:crypto';
 import { DEFAULT_SETTINGS } from './types.js';
-const execFileAsync = promisify(execFile);
+import { execCapped } from './exec.js';
 /** Resolved path under the user's home directory. */
 function wickedDir(...parts) {
     const home = process.env.HOME ?? process.env.USERPROFILE ?? '/tmp';
     return join(home, '.wicked', ...parts);
 }
+/**
+ * Parse a JSON string a napi binding returned. The bindings type their return loosely (`unknown`
+ * until a `ts_return_type` regen), so guard BOTH a non-string return and invalid JSON with an error
+ * that names the method — a bare `JSON.parse` throw is an unactionable "Unexpected token" (crew#227
+ * review). At the current engine contract `raw` is always a valid JSON string.
+ */
+function parseEngineJson(raw, method) {
+    if (typeof raw !== 'string') {
+        throw new Error(`${method}: expected a JSON string from the engine, got ${typeof raw}`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`${method}: engine returned invalid JSON (${e instanceof Error ? e.message : String(e)})`);
+    }
+}
 /**
  * Workflow overlay directory — mirrors the Rust `workflow_overlay_dir()` logic in
  * `pipeline.rs`. The Rust actor reads drop-in workflow JSONs from this path at startup
@@ -30,6 +46,40 @@ function workflowOverlayDir() {
 function settingsFilePath() {
     return join(homedir(), '.config', 'wicked-core', 'settings.json');
 }
+/** Read user-registered workflow overlays from `dir` (the same dir `registerWorkflow` writes to).
+ *
+ * Skips: files whose id matches a built-in (those are `_writeBuiltinOverlay` artifacts written FOR
+ * the Rust actor, not user workflows — including them would duplicate a built-in in `listWorkflows`),
+ * non-`.json` files, and any file that does not parse into a `{id, phases[]}` shape (the Rust actor
+ * skips an unreadable overlay too, so crew must not surface one it can't). A missing dir yields `[]`.
+ *
+ * Exported so the FINDING-002 restart-hydration path is unit-testable without spawning a Core. */
+export function readOverlayWorkflows(dir, builtinIds) {
+    let files;
+    try {
+        files = readdirSync(dir);
+    }
+    catch {
+        return []; // no overlay dir yet → nothing registered
+    }
+    const out = [];
+    for (const file of files) {
+        if (!file.endsWith('.json'))
+            continue;
+        const id = file.slice(0, -'.json'.length);
+        if (builtinIds.has(id))
+            continue; // a built-in overlay, not a user workflow
+        try {
+            const def = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+            if (def && typeof def.id === 'string' && Array.isArray(def.phases))
+                out.push(def);
+        }
+        catch {
+            // Unparseable overlay — core would skip it at load, so crew skips it too.
+        }
+    }
+    return out;
+}
 /** Find the wicked-core standalone binary for the gate-hook command.
  * Checks common install locations so the Rust actor can build a correct
  * hook command even when loaded as a napi addon (where current_exe() = node).
@@ -61,10 +111,46 @@ const require = createRequire(import.meta.url);
 const { Core } = require('wicked-core-ts');
 // ── Built-in workflow definitions (crew#44) ──────────────────────────────────
 // Static mirrors of wicked-core workflow defs: feature, bug, migration, survey-repo,
-// repo-graph, domain-graph-slice, memories, onboarding, and chat.
+// domain-graph-slice, memories, collab, onboarding, chat, and domain-extraction.
 // Swap for `this.core.listWorkflowsJson()` / `this.core.getWorkflowJson(id)` once
 // the wicked-core-ts NAPI methods land.
-const BUILTIN_WORKFLOWS = [
+/**
+ * The ids wicked-core seeds itself, in `WorkflowRegistry::with_defaults()`.
+ *
+ * `launchRun`'s generic drop-in overlay write SKIPS every id in this set (`onboarding` is written
+ * by the onboarding path instead — see the end of this comment, it is the one deliberate exception).
+ * A file in that dir shadows the compiled built-in
+ * *wholesale* — `register` overwrites by id and `load_dir` runs after `with_defaults` — so writing
+ * this hand-transcribed mirror over the real def silently replaces it with a copy missing whatever
+ * the def has grown since the mirror was transcribed. That is not hypothetical: the mirror predated
+ * the evidence floors, so the write took `validator_pin` back off `feature.adversarial-review`,
+ * `bug.verify` and `migration.verify` — the entire content of core's gate-floor change, undone by a
+ * file write, with no error and a workflow still reporting the right id and phases (FINDING-049).
+ *
+ * The write exists for the ids core does NOT seed (chat, survey-repo, domain-graph-slice,
+ * memories, domain-extraction): for those the overlay is the only reason they resolve at all, so
+ * it stays.
+ *
+ * The exception: `onboarding` is core-seeded AND still written, by the onboarding path rather than
+ * by the generic one. Deliberate — that def's executor cmds are baked with runtime `--db` paths, so
+ * it shadows core's copy with a real customization rather than a stale transcription. It is the one
+ * shadow that earns its keep, and the reason this set gates the generic write specifically.
+ */
+const CORE_SEEDED_WORKFLOWS = new Set(['feature', 'bug', 'migration', 'onboarding', 'collab']);
+/**
+ * The content-address of core's built-in evidence floor (`builtin_floors::EVIDENCE_FLOOR_PIN`),
+ * carried on the Evaluator phase of feature/bug/migration.
+ *
+ * Duplicating a hash is a real cost, paid because the alternative is worse. What `listWorkflows()`
+ * serves IS what `GET /api/v1/workflows` and the work-mode selector show, and a `null` here reads
+ * as "this phase is ungated" — the opposite of the truth for the three phases core gates. Reporting
+ * a gate that exists is the honest failure direction; the drift guard in
+ * `tests/armed-workflow-served.test.ts` fails loudly on a developer machine the moment core's value
+ * moves. This is display only: as of FINDING-049 these defs are never written to core's overlay dir
+ * (see CORE_SEEDED_WORKFLOWS), so a stale value here cannot reach the engine.
+ */
+const EVIDENCE_FLOOR_PIN = '2fcde907d57f3ee2';
+export const BUILTIN_WORKFLOWS = [
     {
         id: 'chat',
         is_system: true,
@@ -76,9 +162,19 @@ const BUILTIN_WORKFLOWS = [
         id: 'onboarding',
         is_system: true,
         phases: [
-            { id: 'index', executor: { type: 'tool', cmd: ['wicked-estate', 'index'] }, kind: 'recon', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: [], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
-            { id: 'annotate', executor: { type: 'tool', cmd: ['wicked-estate', 'clusters', '--annotate'] }, kind: 'recon', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['index'], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
-            { id: 'domain', executor: { type: 'tool', cmd: ['wicked-core', 'domain-graph'] }, kind: 'recon', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['annotate'], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
+            { id: 'index', executor: { type: 'tool', cmd: ['wicked-estate', 'index', '{repo_root}', '--db', '{code_graph_db}'] }, kind: 'recon', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: [], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
+            { id: 'annotate', executor: { type: 'tool', cmd: ['wicked-estate', 'clusters', '--annotate', '--db', '{code_graph_db}'] }, kind: 'recon', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['index'], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
+            // index → annotate, and NOT a third `domain` phase running `wicked-core domain-graph`. That
+            // phase could never pass: domain-graph fails closed below 1.0 front-half coverage, and nothing
+            // in this workflow annotates a single symbol, so coverage was 0.0 on every repo — every
+            // registration ended sessionFailed after the two phases that matter had both succeeded
+            // (FINDING-068). domain-graph belongs to `domain-extraction`, downstream of the agentic
+            // extract+coverage phases that produce its precondition. Mirrors core's `onboarding_def()`.
+            //
+            // The `{repo_root}` / `{code_graph_db}` placeholders are core's, substituted per run from the
+            // launch's `repoRef` (wicked-core#179). This package used to bake absolute paths in here and
+            // write the result to one shared overlay file per launch — which concurrent registrations
+            // raced, indexing one repo's tree under another repo's name (FINDING-075, #196).
         ],
     },
     {
@@ -87,7 +183,7 @@ const BUILTIN_WORKFLOWS = [
             { id: 'clarify', kind: 'recon', gate_type: 'value', gate: { human_confirm: { unconditional: false } }, executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: [], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
             { id: 'design', kind: 'recon', gate_type: 'strategy', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['clarify'], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
             { id: 'build', kind: 'build', gate_type: 'execution', gate: 'auto', executes_code: true, verified_evidence: false, required_deliverables: [], depends_on: ['design'], role: 'creator', skill_ref: null, allowed_skills: [], validator_pin: null },
-            { id: 'adversarial-review', kind: 'review', gate_type: 'execution', gate: { human_confirm: { unconditional: false } }, executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['build'], role: 'evaluator', skill_ref: null, allowed_skills: [], validator_pin: null },
+            { id: 'adversarial-review', kind: 'review', gate_type: 'execution', gate: { human_confirm: { unconditional: false } }, executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['build'], role: 'evaluator', skill_ref: null, allowed_skills: [], validator_pin: EVIDENCE_FLOOR_PIN },
             { id: 'test', kind: 'test', gate_type: 'execution', gate: { human_confirm_if: 'verdict_not_pass' }, executes_code: false, verified_evidence: true, required_deliverables: [], depends_on: ['build'], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
             { id: 'review', kind: 'review', gate_type: 'execution', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['test'], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
         ],
@@ -98,7 +194,7 @@ const BUILTIN_WORKFLOWS = [
             { id: 'triage', kind: 'recon', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: [], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
             { id: 'reproduce', kind: 'test', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['triage'], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
             { id: 'fix', kind: 'build', gate_type: 'execution', gate: 'auto', executes_code: true, verified_evidence: false, required_deliverables: [], depends_on: ['reproduce'], role: 'creator', skill_ref: null, allowed_skills: [], validator_pin: null },
-            { id: 'verify', kind: 'test', gate_type: 'execution', gate: { human_confirm_if: 'verdict_not_pass' }, executes_code: false, verified_evidence: true, required_deliverables: [], depends_on: ['fix'], role: 'evaluator', skill_ref: null, allowed_skills: [], validator_pin: null },
+            { id: 'verify', kind: 'test', gate_type: 'execution', gate: { human_confirm_if: 'verdict_not_pass' }, executes_code: false, verified_evidence: true, required_deliverables: [], depends_on: ['fix'], role: 'evaluator', skill_ref: null, allowed_skills: [], validator_pin: EVIDENCE_FLOOR_PIN },
         ],
     },
     {
@@ -107,25 +203,24 @@ const BUILTIN_WORKFLOWS = [
             { id: 'plan', kind: 'recon', gate_type: 'strategy', gate: { human_confirm: { unconditional: false } }, executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: [], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
             { id: 'execute', kind: 'build', gate_type: 'execution', gate: 'auto', executes_code: true, verified_evidence: false, required_deliverables: [], depends_on: ['plan'], role: 'creator', skill_ref: null, allowed_skills: [], validator_pin: null },
             { id: 'cutover', kind: 'build', gate_type: 'execution', gate: { human_confirm: { unconditional: true } }, executes_code: true, verified_evidence: false, required_deliverables: [], depends_on: ['execute'], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
-            { id: 'verify', kind: 'test', gate_type: 'execution', gate: { human_confirm_if: 'verdict_not_pass' }, executes_code: false, verified_evidence: true, required_deliverables: [], depends_on: ['cutover'], role: 'evaluator', skill_ref: null, allowed_skills: [], validator_pin: null },
+            { id: 'verify', kind: 'test', gate_type: 'execution', gate: { human_confirm_if: 'verdict_not_pass' }, executes_code: false, verified_evidence: true, required_deliverables: [], depends_on: ['cutover'], role: 'evaluator', skill_ref: null, allowed_skills: [], validator_pin: EVIDENCE_FLOOR_PIN },
             { id: 'cleanup', kind: 'build', gate_type: null, gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['verify'], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
         ],
     },
     {
-        id: 'repo-graph',
-        is_system: true,
-        phases: [
-            { id: 'index', executor: { type: 'tool', cmd: ['wicked-estate', 'index'] }, kind: 'recon', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: [], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
-            { id: 'annotate', executor: { type: 'tool', cmd: ['wicked-estate', 'clusters', '--annotate'] }, kind: 'recon', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['index'], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
-        ],
-    },
-    {
+        // MUST stay byte-identical to wicked-core/workflows/survey-repo.json — crew's overlay write is the
+        // ONLY def the engine resolves at runtime (core does not seed survey-repo), so a stale mirror here
+        // silently runs the OLD def. The pre-fix mirror carried 3 phases with no `instructions` and no
+        // `synthesize`, so survey-repo ran 3 near-identical prompts and produced no run-level synthesis —
+        // exactly FINDING-011, still live because the fix only landed in the core JSON the runtime ignores.
+        // Guarded by builtin-overlay-shadow.test.ts (survey-repo is now in MIRRORED_IDS).
         id: 'survey-repo',
         is_system: true,
         phases: [
-            { id: 'structure', kind: 'recon', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: [], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
-            { id: 'stack', kind: 'recon', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['structure'], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
-            { id: 'conventions', kind: 'recon', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['stack'], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
+            { id: 'structure', kind: 'recon', instructions: 'Map the repository layout only: top-level directories, entry points, and where source, tests, config, and docs live. Do not analyze languages, dependencies, or conventions — later phases cover those.', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: [], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
+            { id: 'stack', kind: 'recon', instructions: 'Identify the technology stack from the manifests (package.json, Cargo.toml, pyproject.toml, ...): languages, frameworks, build tools, key dependencies. Build on the structure summary provided as prior context; do not re-map the layout.', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['structure'], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
+            { id: 'conventions', kind: 'recon', instructions: 'Identify the working conventions: naming, module boundaries, test placement and style, lint/format configuration, CI expectations. Build on the prior phases\' outputs provided as context; do not re-survey structure or stack.', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['stack'], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
+            { id: 'synthesize', kind: 'recon', instructions: 'Do not re-survey the repository. Merge the three prior phase outputs provided as context into one coherent survey — structure, then stack, then conventions — resolving overlaps and flagging any contradictions between them.', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['structure', 'stack', 'conventions'], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
         ],
     },
     {
@@ -155,7 +250,132 @@ const BUILTIN_WORKFLOWS = [
             { id: 'verdict', kind: 'review', gate_type: 'value', gate: { human_confirm: { unconditional: false } }, executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['revise'], role: 'evaluator', skill_ref: null, allowed_skills: [], validator_pin: null },
         ],
     },
+    // The one workflow that ARMS the dual-validator gate: `coverage` carries an approved
+    // `validator_pin`, so layer 1 is live here and inert in every entry above. Transcribed
+    // field-for-field from the source of truth, `wicked-core/workflows/domain-extraction.json`
+    // (core ships it as a *drop-in*, not a seeded built-in, and exposes no dump command — hence a
+    // hand-transcribed mirror, like every other entry in this array).
+    //
+    // The pin is a content hash over the validator's criterion + script + approved flag. Core
+    // re-derives it in `domain_extraction.rs` and fails its own test if it drifts; if that test ever
+    // forces core's constant to change, THIS literal must change with it or crew will write an
+    // overlay that fails closed at plan time.
+    //
+    // Running it needs a one-time, idempotent `wicked-core seed-domain-validators` to vault + approve
+    // that validator. That step is deliberately manual — approval is an audited act a human/council
+    // owns, not something a daemon does unattended — and until it is run, a launch fails CLOSED at
+    // plan time rather than running the phase ungated. Not `is_system`: this is an operator-selectable
+    // work mode, unlike the dedicated-entry-point workflows above.
+    {
+        id: 'domain-extraction',
+        phases: [
+            // required_deliverables reconciled with core (wicked-core/workflows/domain-extraction.json):
+            // survey/analyze/extract annotate the estate STORE and domain-graph now PERSISTS the graph
+            // into the store (not a JSON file), so their evidence is DB state — verified by the coverage
+            // gate (reads the store) and domain-graph's fail-closed-on-coverage<1.0 — not a worktree file.
+            // Only coverage emits a genuine standalone report the deterministic floor reads. Declaring
+            // phantom files failed every phase under core's FINDING-101 deliverable gate.
+            { id: 'survey', kind: 'recon', gate_type: null, gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: [], role: 'neutral', skill_ref: 'wicked-garden-domain', allowed_skills: [], validator_pin: null },
+            { id: 'analyze', kind: 'recon', gate_type: null, gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['survey'], role: 'neutral', skill_ref: 'wicked-garden-domain', allowed_skills: [], validator_pin: null },
+            { id: 'extract', kind: 'recon', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['analyze'], role: 'creator', skill_ref: 'wicked-garden-domain-extractor', allowed_skills: [], validator_pin: null },
+            { id: 'coverage', kind: 'test', gate_type: 'execution', gate: { human_confirm_if: 'verdict_not_pass' }, executes_code: false, verified_evidence: true, required_deliverables: ['coverage-report.json'], depends_on: ['extract'], role: 'evaluator', skill_ref: 'wicked-garden-domain-coverage', allowed_skills: [], validator_pin: '49b61ba3ab5264e4' },
+            // domain-graph is a DETERMINISTIC Tool that runs `wicked-core domain-graph`, which PERSISTS the
+            // domain/requirement/rule graph into the repo store (core#237) — not an LLM skill that could hit
+            // a non-persisting hermetic fallback. Mirrors wicked-core/workflows/domain-extraction.json.
+            { id: 'domain-graph', executor: { type: 'tool', cmd: ['wicked-core', 'domain-graph', '--db', '{code_graph_db}', '--out', 'requirements_graph.json'] }, kind: 'build', gate_type: 'strategy', gate: { human_confirm: { unconditional: false } }, executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['coverage'], role: 'neutral', skill_ref: null, allowed_skills: [], validator_pin: null },
+        ],
+    },
 ];
+/**
+ * Chat is not available in this deployment at all — a capability gap, never a bad request.
+ *
+ * It arrives two ways and both mean the same thing to an operator: the addon predates the binding
+ * (no method to call), or the engine was spawned without the ACP runner and says so when called.
+ * Only the first is knowable before the call, which is why this is a thrown type rather than a
+ * capability flag.
+ *
+ * Typed rather than left to the caller to sniff out of the message text: the route used to regex
+ * the message for one of the two phrasings, so the other fell through to `400` and told an operator
+ * to fix a request that was already correct.
+ */
+export class ChatUnsupportedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ChatUnsupportedError';
+    }
+}
+/**
+ * `resolveElicitation` is not available in this deployment — the NAPI binding has not
+ * landed in the installed `wicked-core-ts` yet (DES-002 §4 P-1 stub).
+ *
+ * Routes map this to HTTP 501 so an operator knows to upgrade rather than to fix a
+ * call that was already correct.
+ */
+export class ElicitationUnsupportedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ElicitationUnsupportedError';
+    }
+}
+/** The engine's own way of reporting a build that cannot do chat, raised at call time. */
+const ENGINE_CHAT_UNSUPPORTED = /chat unsupported/i;
+/**
+ * Quarantine a pre-#197 `onboarding.json` left in the overlay dir.
+ *
+ * This package used to write that file on every launch, baked with ONE repo's absolute paths. It no
+ * longer does — core declares `{repo_root}` / `{code_graph_db}` and binds them per run
+ * (wicked-core#179). But the overlay dir is PERSISTENT STATE, and the engine's `load_dir` registers
+ * whatever it finds there, replacing a compiled def by id, wholesale.
+ *
+ * So an upgraded deployment keeps running the last file the old code wrote. Not intermittently:
+ * EVERY onboarding run indexes whichever repo happened to be registered last before the upgrade.
+ * Observed exactly that on this host after #197 merged — three fresh registrations in three
+ * different orgs all indexed `agentic-products/eliza`, the last repo seeded before the fix.
+ *
+ * Renamed rather than deleted. The file is almost certainly machine-written, but the overlay dir is
+ * an operator-facing extension point and silently destroying something out of it is not this
+ * process's call. The rename is enough to stop the shadow, and leaves the evidence in place.
+ */
+function quarantineStaleOnboardingOverlay() {
+    const stale = join(workflowOverlayDir(), 'onboarding.json');
+    if (!existsSync(stale))
+        return; // the ordinary case on a clean install
+    // Only a PRE-#197 artifact, never an operator's override. `registerWorkflow()` writes user
+    // definitions into this same directory, and parking one on every boot would delete a deliberate
+    // customization each time it was re-registered.
+    //
+    // The signature is specific: old crew baked one repo's ABSOLUTE paths into the tool commands. A
+    // def carrying `{repo_root}` / `{code_graph_db}`, or agent phases, or relative commands, is not
+    // what this is looking for and is left alone. An operator who hand-writes absolute paths into a
+    // shared def has written the same bug, and gets the same treatment for the same reason.
+    let bakedPaths;
+    try {
+        const def = JSON.parse(readFileSync(stale, 'utf8'));
+        bakedPaths = (def.phases ?? [])
+            .flatMap((p) => (p.executor?.type === 'tool' ? (p.executor.cmd ?? []) : []))
+            .filter((arg) => arg.startsWith('/'));
+    }
+    catch {
+        // Unparseable: not ours to judge. The engine reports its own load failure.
+        return;
+    }
+    if (bakedPaths.length === 0)
+        return;
+    const parked = `${stale}.superseded-by-crew197`;
+    try {
+        renameSync(stale, parked);
+        console.warn(`[onboarding] removed a stale overlay that would have hijacked every onboarding run: ` +
+            `${stale} → ${parked}. It baked ${bakedPaths[0]} into a def shared by every repo, which is ` +
+            `what a pre-#197 crew wrote; the engine resolves it in preference to the built-in ` +
+            `(FINDING-075).`);
+    }
+    catch (err) {
+        // Loud, and non-fatal: the daemon still starts, but every onboarding on this host is wrong
+        // until the file goes, so the operator has to be told rather than left to discover it.
+        console.error(`[onboarding] FAILED to remove the stale overlay at ${stale}: ${err instanceof Error ? err.message : String(err)}. Until it is removed by hand, every onboarding run will index the repo baked into it, ` +
+            `whatever repo the run names (FINDING-075).`);
+    }
+}
 /**
  * The single isolation boundary over wicked-core-ts. It holds the ONE `Core`
  * handle, makes the ONE `subscribe()` call for the whole process, parses each
@@ -163,6 +383,21 @@ const BUILTIN_WORKFLOWS = [
  * endpoint and the WS fan-out funnel through this stable API — so when the
  * in-flight core-ts subscribe/teardown signature lands, only this file changes.
  */
+/** The ids of a workflow's phases that carry a HUMAN gate (`human_confirm` unconditional, or the
+ * conditional `human_confirm_if`) — i.e. the phases that will PAUSE for a person.
+ *
+ * FINDING-023 (residual): core#208 made a workflow's phase gate deliberately WIN over a run-level
+ * `humanConfirm: none` (it pauses, with a self-disclosing note), but there was no way to learn a
+ * workflow's gates BEFORE launching it — an operator picking `none` for an unattended run only found
+ * out when it paused. Surfacing this on `GET /workflows/:id` is that missing launch-time signal.
+ * `'auto'` (the string form) is NOT a human gate. */
+export function humanGatePhaseIds(wf) {
+    return wf.phases
+        .filter((p) => typeof p.gate === 'object' &&
+        p.gate !== null &&
+        ('human_confirm' in p.gate || 'human_confirm_if' in p.gate))
+        .map((p) => p.id);
+}
 export class CoreAdapter {
     core;
     subscription;
@@ -181,6 +416,9 @@ export class CoreAdapter {
         // it publishes `task.dispatched` / consumes `task.completed` around WHATEVER step runner the engine
         // wires (the production wrapped-CLI runner OR the deterministic stub), so a stub engine can arm it
         // for a fast, offline, deterministic proof of the event path.
+        // BEFORE the Core spawns: the actor reads the overlay dir at startup, so a stale
+        // `onboarding.json` has to be out of the way by then or it shadows the built-in def.
+        quarantineStaleOnboardingOverlay();
         const armExec = opts.engineExec === true;
         if (armExec) {
             if (!opts.busDbPath || opts.busDbPath.length === 0) {
@@ -254,11 +492,17 @@ export class CoreAdapter {
             opts.repoRef = input.repoRef;
         if (input.workflow !== undefined) {
             opts.workflow = input.workflow;
-            // Ensure built-in workflow definitions are present in the Rust overlay dir on first use.
+            // Ensure DROP-IN workflow definitions are present in the Rust overlay dir on first use.
             // Uses a dedicated helper (not registerWorkflow) to avoid adding built-ins to userWorkflows,
             // which would duplicate them in listWorkflows(). The write is skipped after the first call
             // per process lifetime.
-            const builtinDef = BUILTIN_WORKFLOWS.find((w) => w.id === input.workflow);
+            //
+            // Ids core seeds itself are excluded: writing them shadows the real def with this stale
+            // mirror — see CORE_SEEDED_WORKFLOWS. Core resolves those from its own registry, so there is
+            // nothing to write and never was.
+            const builtinDef = CORE_SEEDED_WORKFLOWS.has(input.workflow)
+                ? undefined
+                : BUILTIN_WORKFLOWS.find((w) => w.id === input.workflow);
             if (builtinDef && !this._builtinOverlayWritten.has(input.workflow)) {
                 // Mark before await so concurrent launchRun() calls for the same builtin
                 // don't both pass the has() check and race to write the same file.
@@ -287,6 +531,23 @@ export class CoreAdapter {
         }
         return this.core.injectWorkerMessage(runId, message, target);
     }
+    /**
+     * A run's recorded event history, oldest first — or `null` when this wicked-core build has no
+     * event-log read binding.
+     *
+     * `null` rather than `[]` on purpose. An empty history is a real, ordinary answer (a run that
+     * emitted nothing, or one predating the log), and collapsing "nothing happened" into "I cannot
+     * tell you what happened" is how a missing capability gets reported to an operator as an absent
+     * gate — the FINDING-050 shape, distinct causes wearing one message. Callers branch on it.
+     */
+    async runEvents(runId) {
+        if (typeof this.core.runEvents !== 'function')
+            return null;
+        // `RecordedEvent`, not `CoreEvent`: the binding's contract is the `/ws` frame PLUS a capture-time
+        // `ts` and an ordering `seq`, and consumers (the evidence bundle) need both. Typing this as the
+        // bare frame made every caller widen or cast to get at fields the engine always sends.
+        return JSON.parse(await this.core.runEvents(runId));
+    }
     /** Run ids on the store. */
     async sessions() {
         return JSON.parse(await this.core.sessions());
@@ -327,14 +588,84 @@ export class CoreAdapter {
     async workOutput(unitId) {
         return JSON.parse(await this.core.workOutput(unitId));
     }
+    // ── Chat sessions (core#134 / crew#165) ────────────────────────────────────
+    async chatOpen(chatId, clis, cwd) {
+        const raw = await this.core.chatOpen(chatId, JSON.stringify(clis), cwd ?? null);
+        return JSON.parse(raw);
+    }
+    async chatSend(chatId, text, targets, cwd) {
+        const raw = await this.core.chatSend(chatId, text, targets === undefined ? null : JSON.stringify(targets), cwd ?? null);
+        return JSON.parse(raw);
+    }
+    async chatSeats(chatId) {
+        return JSON.parse(await this.core.chatSeats(chatId));
+    }
+    /**
+     * Every live chat, so an operator can find the ones nothing is going to close (FINDING-027).
+     *
+     * Chat sessions are a warm pool that deliberately outlives the page, and the only client that
+     * knew a chat's id is the tab that minted it. Without this an orphaned seat is unreclaimable
+     * short of restarting the daemon — the leak is real but invisible, which is the worse half.
+     *
+     * `idleSecs` is `number | null`, not `number`. The Rust side uses `u64::MAX` for "no activity
+     * timestamp"; as an f64 that arrives as 18446744073709552000, which no caller can test for by
+     * equality and every caller can accidentally do arithmetic on. The binding maps it to `null`.
+     */
+    async chatList() {
+        const list = this.core.chatList;
+        if (typeof list !== 'function') {
+            throw new ChatUnsupportedError('Listing chats is not yet supported by this wicked-core build');
+        }
+        try {
+            return JSON.parse(await list.call(this.core));
+        }
+        catch (err) {
+            // A build without the ACP runner has the binding and refuses at call time, so the presence
+            // check above cannot catch it. Classified here rather than at the route because this file is
+            // the only one that touches the addon (DES-STUDIO-001 §5.2) — matching engine wording anywhere
+            // else would spread that coupling.
+            const text = err instanceof Error ? err.message : String(err);
+            if (ENGINE_CHAT_UNSUPPORTED.test(text))
+                throw new ChatUnsupportedError(text);
+            throw err;
+        }
+    }
+    async chatClose(chatId) {
+        await this.core.chatClose(chatId);
+    }
+    /**
+     * Forward the operator's elicitation response to the actor (DES-002 §4 P-1).
+     *
+     * NAPI flat signature: `resolve_elicitation(run_id, elicitation_id, action, response)`.
+     * `response` is `null` for `decline` and `cancel` actions; a non-empty string for `accept`.
+     *
+     * Throws `ElicitationUnsupportedError` until the NAPI binding is present in the installed
+     * `wicked-core-ts`. Routes map that to HTTP 501.
+     */
+    async resolveElicitation(_runId, _elicitationId, _action, _response) {
+        // Consume stub params to satisfy @typescript-eslint/no-unused-vars; the
+        // parameter names are part of the public interface and must not be dropped.
+        void _runId;
+        void _elicitationId;
+        void _action;
+        void _response;
+        // The NAPI binding (`this.core.resolveElicitation`) will land with the actor-side
+        // work in a follow-on. Until then, every call throws so the route surfaces 501 and
+        // an operator knows to upgrade rather than to keep retrying.
+        throw new ElicitationUnsupportedError('resolveElicitation is not yet bound in this wicked-core build; upgrade wicked-core-ts to enable it');
+    }
     /** repo id → onboarding run id (in-memory; graph persists on disk across restarts). */
     repoOnboardRunIds = new Map();
-    /** repo ids with an onboarding run in flight — guards against concurrent double-launch. */
-    onboardingInFlight = new Set();
-    /** Serializes onboarding launches: they rewrite the SHARED 'onboarding' overlay with
-     *  repo-specific paths, so two repos launching concurrently must not interleave between
-     *  overlay registration and launchRun (after launch the def is baked into the run's units). */
-    _onboardingChain = Promise.resolve();
+    /**
+     * repo id → the in-flight launch, so a concurrent caller joins it instead of starting a second.
+     *
+     * A `Set` of ids was not enough. The id was added here but the run id was only recorded in
+     * `repoOnboardRunIds` AFTER the launch resolved, so a second caller arriving mid-flight saw
+     * "in flight" with no run id to return, fell through, and launched a DUPLICATE run against the
+     * same repo. Holding the promise makes the second caller await the first and receive its run id —
+     * the dedup the `Set` was named for.
+     */
+    onboardingInFlight = new Map();
     /** Register a local git repo → the persisted `RepoEntry`. */
     async registerRepo(name, rootPath) {
         return JSON.parse(await this.core.registerRepo(name, rootPath));
@@ -393,7 +724,7 @@ export class CoreAdapter {
         catch { /* not yet cloned */ }
         if (needsClone) {
             try {
-                await execFileAsync('git', ['clone', '--', gitUrl, cloneDir], {
+                await execCapped('git', ['clone', '--', gitUrl, cloneDir], {
                     timeout: 5 * 60 * 1000,
                 });
             }
@@ -421,63 +752,52 @@ export class CoreAdapter {
      * Returns the run id so the UI can navigate directly to it.
      */
     async launchOnboardingRun(repoId, repoName) {
-        if (this.onboardingInFlight.has(repoId)) {
-            const existing = this.repoOnboardRunIds.get(repoId);
-            if (existing)
-                return existing;
-        }
-        this.onboardingInFlight.add(repoId);
+        // Join an in-flight launch for THIS repo rather than starting a second one. Concurrency across
+        // DIFFERENT repos is the point and is untouched; two launches for the SAME repo are a duplicate.
+        const inFlight = this.onboardingInFlight.get(repoId);
+        if (inFlight)
+            return inFlight;
         const runId = randomUUID();
-        const chained = this._onboardingChain.then(() => this._doOnboardingLaunch(repoId, repoName, runId));
-        this._onboardingChain = chained.catch(() => undefined);
+        // Launches are NOT serialized. They used to be, through an `_onboardingChain` promise, because
+        // each rewrote the shared `onboarding` overlay before launching. That chain never worked: its
+        // own comment claimed "after launch the def is baked into the run's units", and the def is
+        // actually resolved at DISPATCH — after the launch call returns. So it serialized the writer and
+        // left the reader racing, which is how three concurrent registrations indexed one repo under
+        // three names (FINDING-075, #196).
+        //
+        // Nothing is shared now: core binds each run's repo into its own units from `repoRef`
+        // (wicked-core#179). Concurrent registration is the point — it is a requirement of the corpus
+        // this platform is tested against, not an optimisation.
+        const launch = this._doOnboardingLaunch(repoId, repoName, runId).then(() => runId);
+        this.onboardingInFlight.set(repoId, launch);
         try {
-            await chained;
-            return runId;
+            return await launch;
         }
         finally {
             this.onboardingInFlight.delete(repoId);
         }
     }
     async _doOnboardingLaunch(repoId, repoName, runId) {
-        {
-            // Bake THIS repo's absolute paths into the onboarding def (core#120). The static def's
-            // relative commands are triple-wrong at runtime: the run's workdir is the per-run WORKTREE
-            // (not the root the graph endpoint reads), and estate's default db location/name
-            // (.wicked-estate/graph.db) differs from the endpoint's (.codegraph/estate.db). Rewritten
-            // per launch and hot-registered so the running actor sees it — never restart-dependent.
-            const repoEntries = await this.listRepos();
-            const repoEntry = repoEntries.find((r) => r.id === repoId);
-            if (!repoEntry)
-                throw new Error(`repo ${repoId} not registered`);
-            const dbPath = join(repoEntry.root_path, '.codegraph', 'estate.db');
-            const base = BUILTIN_WORKFLOWS.find((w) => w.id === 'onboarding');
-            const requirementsGraphPath = join(repoEntry.root_path, '.wicked-estate', 'requirements', 'requirements_graph.json');
-            const CMDS = {
-                index: ['wicked-estate', 'index', repoEntry.root_path, '--db', dbPath],
-                annotate: ['wicked-estate', 'clusters', '--annotate', '--db', dbPath],
-                // The real domain front-end (writes what /repos/:id/domain-graph reads). Fails
-                // closed with an actionable message until the domain-extraction front-half has
-                // annotated the graph — that message surfacing in the unit output is correct.
-                domain: ['wicked-core', 'domain-graph', '--db', dbPath, '--out', requirementsGraphPath],
-            };
-            const def = {
-                ...base,
-                phases: base.phases.map((ph) => CMDS[ph.id] ? { ...ph, executor: { type: 'tool', cmd: CMDS[ph.id] } } : ph),
-            };
-            // _writeBuiltinOverlay persists the overlay AND hot-registers it in the actor.
-            await this._writeBuiltinOverlay(def);
-            // Mark the builtin as written BEFORE launchRun: its generic once-guard would otherwise
-            // see 'onboarding' as unwritten and clobber the baked def with the static mirror in the
-            // window between this write and the engine resolving the workflow (observed live).
-            this._builtinOverlayWritten.add('onboarding');
-            await this.launchRun({
-                problem: `Onboard repository: ${repoName}`,
-                sessionId: runId,
-                clisJson: JSON.stringify(CoreAdapter.roster()),
-                workflow: 'onboarding',
-                repoRef: repoId,
-            });
-        }
+        // No overlay write. This used to rewrite core's `onboarding` def with THIS repo's absolute paths
+        // and persist it to one shared file (`~/.config/wicked-core/workflows/onboarding.json`), then
+        // hot-register it — the one place a core-seeded id was deliberately shadowed.
+        //
+        // That shadow was the defect. The engine resolves a workflow at DISPATCH time, after this call
+        // returns, so concurrent launches raced on the single file and the last writer won: two repos in
+        // two different orgs had a third org's tree indexed into a third org's database, each reported
+        // under its own name (FINDING-075, #196). Serializing the writes does not fix it — the chain
+        // serializes the producer and leaves the consumer racing.
+        //
+        // Core now declares `{repo_root}` / `{code_graph_db}` on the phases and binds them per run from
+        // `repoRef`, which this call already passes (wicked-core#179). Nothing is shared, so nothing can
+        // be raced, and onboarding launches may run concurrently.
+        await this.launchRun({
+            problem: `Onboard repository: ${repoName}`,
+            sessionId: runId,
+            clisJson: JSON.stringify(CoreAdapter.roster()),
+            workflow: 'onboarding',
+            repoRef: repoId,
+        });
         this.repoOnboardRunIds.set(repoId, runId);
     }
     /** Return the onboarding run id for a repo (undefined if not launched this session). */
@@ -505,6 +825,25 @@ export class CoreAdapter {
     async getCoverageReport() {
         return JSON.parse(await this.core.getCoverageReport());
     }
+    /**
+     * Coverage for ONE registered repo, computed over that repo's OWN code graph (FINDING-009). Unlike
+     * {@link getCoverageReport} — which reads the daemon store and reports a vacuous `coverage: 1.0` that
+     * names no repo — this resolves `repoRef` in the registry and recomputes over its `code_graph_db`.
+     * The core rejects an unknown repo (never a silent vacuous report), so this throws for a bad ref.
+     */
+    async getCoverageReportForRepo(repoRef) {
+        // The napi binding returns a JSON string (`serde_json::to_string`); parse it with a guard that
+        // names the method on either a non-string return or invalid JSON (Copilot #227).
+        return parseEngineJson(await this.core.getCoverageReportForRepo(repoRef), 'getCoverageReportForRepo');
+    }
+    /**
+     * Node-count-by-kind summary of ONE registered repo's code graph, over that repo's OWN store
+     * (#122) — what the estate graph actually holds for the repo, so an operator can see it was
+     * populated. The core rejects an unknown repo, so this throws for a bad ref.
+     */
+    async getGraphKindsForRepo(repoRef) {
+        return parseEngineJson(await this.core.getGraphKindsForRepo(repoRef), 'getGraphKindsForRepo');
+    }
     // ── Governance writes (crew#42) ────────────────────────────────────────────
     /** Upsert a governance policy via the single-writer actor. */
     async upsertPolicy(policy) {
@@ -514,6 +853,28 @@ export class CoreAdapter {
     async upsertConformanceRule(rule) {
         await this.core.upsertConformanceRule(JSON.stringify(rule));
     }
+    /**
+     * Withdraw a policy from enforcement. Resolves `true` if a policy with that id existed.
+     *
+     * Retire, not delete (FINDING-038): the node stays readable so a past decision citing this id is
+     * still explicable, but governance stops selecting it. The boolean is what lets the route answer
+     * 404 instead of reporting a success that removed nothing.
+     */
+    async retirePolicy(id) {
+        const retire = this.core.retirePolicy;
+        if (typeof retire !== 'function') {
+            throw new Error('Retiring a policy is not yet supported by this wicked-core build');
+        }
+        return JSON.parse(await retire.call(this.core, id));
+    }
+    /** Withdraw a conformance rule from recall. Same contract as {@link retirePolicy}. */
+    async retireConformanceRule(id) {
+        const retire = this.core.retireConformanceRule;
+        if (typeof retire !== 'function') {
+            throw new Error('Retiring a conformance rule is not yet supported by this wicked-core build');
+        }
+        return JSON.parse(await retire.call(this.core, id));
+    }
     /** Recall conformance rules matching a facet query (read-only, does not block actor). */
     async recallRulesPreview(query) {
         const cleanQuery = {};
@@ -531,7 +892,28 @@ export class CoreAdapter {
     // workflows are added to `userWorkflows` and persisted to disk; the Rust actor
     // picks them up via `register_workflow` NAPI (when available) for immediate use.
     userWorkflows = new Map();
+    /** Whether {@link hydrateFromOverlay} has run this process lifetime. */
+    overlayHydrated = false;
+    /** Load user-registered workflows persisted to the overlay dir into `userWorkflows`, ONCE.
+     *
+     * FINDING-002 residual: `registerWorkflow` writes each def to the overlay dir AND to the in-memory
+     * `userWorkflows` Map, but the Map is process-local and empty on every daemon restart, and nothing
+     * read the dir back. So after a restart the Rust actor (which DOES load the overlay dir at startup)
+     * would launch a user workflow that `listWorkflows()`/`GET /workflows` no longer showed — it
+     * vanished from the registry while remaining runnable. Hydrating from the same dir the writer uses
+     * makes the two views agree again. */
+    hydrateFromOverlay() {
+        if (this.overlayHydrated)
+            return;
+        this.overlayHydrated = true;
+        const builtinIds = new Set(BUILTIN_WORKFLOWS.map((w) => w.id));
+        for (const def of readOverlayWorkflows(workflowOverlayDir(), builtinIds)) {
+            if (!this.userWorkflows.has(def.id))
+                this.userWorkflows.set(def.id, def);
+        }
+    }
     listWorkflows() {
+        this.hydrateFromOverlay();
         // Builtins first (stable ordering), but user-registered workflows take precedence when
         // ids conflict — consistent with getWorkflow() which prefers userWorkflows.get().
         const seen = new Set();
@@ -552,6 +934,7 @@ export class CoreAdapter {
         return result;
     }
     getWorkflow(id) {
+        this.hydrateFromOverlay();
         return this.userWorkflows.get(id) ?? BUILTIN_WORKFLOWS.find((w) => w.id === id) ?? null;
     }
     /** Write a built-in workflow definition to the Rust overlay dir (and hot-register when possible).
@@ -561,11 +944,29 @@ export class CoreAdapter {
         await mkdir(dir, { recursive: true });
         const overlayDef = { ...def };
         delete overlayDef.is_system;
-        await writeFile(join(dir, `${def.id}.json`), JSON.stringify(overlayDef, null, 2), 'utf8');
+        const json = JSON.stringify(overlayDef);
         const core = this.core;
-        if (typeof core['registerWorkflow'] === 'function') {
-            await core['registerWorkflow'](JSON.stringify(overlayDef));
+        const register = core['registerWorkflow'];
+        // Same validate-before-persist ordering as registerWorkflow (FINDING-002). This path had the
+        // identical defect — write first, validate last — which is the P3 shape this campaign keeps
+        // finding: N paths, one hardened. A mirror that drifted far enough for core to reject it would
+        // otherwise leave an unparseable *.json in the dispatch overlay dir, and core would skip it at
+        // the next load. Letting the rejection propagate instead fails the launch with core's own
+        // reason, which beats dispatching against a workflow core will silently drop.
+        if (typeof register === 'function') {
+            await register.call(this.core, json);
         }
+        // Deliberately NOT the refusal registerWorkflow makes when the binding is absent, and the
+        // difference is the input, not the caller:
+        //   - a user def is arbitrary runtime input no test has ever seen, so unvalidatable means
+        //     unsafe to persist;
+        //   - a built-in mirror is asserted field-for-field against wicked-core's own
+        //     workflows/<id>.json by tests/builtin-overlay-shadow.test.ts, so its parseability is
+        //     established at build time rather than needing a runtime check.
+        // Refusing here would also break DELIVERY: this write is the only way core resolves a drop-in
+        // id, so a refusal turns a silent ungating into a hard "unknown workflow" — exactly the
+        // regression FINDING-084's first attempted fix caused.
+        await writeFile(join(dir, `${def.id}.json`), JSON.stringify(overlayDef, null, 2), 'utf8');
     }
     /**
      * Register a user-authored workflow: persist to the Rust workflow overlay dir
@@ -585,14 +986,36 @@ export class CoreAdapter {
         // field and silently drops any workflow whose JSON it cannot fully deserialise.
         const overlayDef = { ...def };
         delete overlayDef.is_system;
-        await writeFile(path, JSON.stringify(overlayDef, null, 2), 'utf8');
-        this.userWorkflows.set(def.id, def);
-        // Hot-register in the Rust actor when the NAPI method is available.
-        // Falls back gracefully if running against an older core build.
+        const json = JSON.stringify(overlayDef);
+        // VALIDATE BEFORE PERSISTING (FINDING-002). This ordering is the whole fix.
+        //
+        // The write used to come first and `registerWorkflow` last, so core's parser — the only thing
+        // that actually knows the overlay schema — ran AFTER the state was already mutated. Observed
+        // end to end: POST /api/v1/workflows answered
+        //   400 invalid workflow JSON: unknown field `name`, expected `id` or `phases`
+        // and the file was on disk anyway, `name` included, and served from `userWorkflows` as though
+        // registered. On the next daemon start core could not deserialise its own overlay file:
+        //   wicked-core: skipping workflow file .../probe-002-persist.json
+        // and the workflow VANISHED while its file remained. That is FINDING-002's root cause: not
+        // "registration is not durable" but "a rejected request persisted a def core cannot read".
+        //
+        // Core's parser is the authority, so it is what we ask. Enumerating the accepted fields in TS
+        // instead would be a second copy of core's schema — the exact drift this codebase keeps paying
+        // for, and `is_system` above is already one hand-maintained instance of it.
         const core = this.core;
-        if (typeof core['registerWorkflow'] === 'function') {
-            await core['registerWorkflow'](JSON.stringify(overlayDef));
+        const register = core['registerWorkflow'];
+        if (typeof register !== 'function') {
+            // No validator, so no safe way to persist: an unvalidated def written here is a file core
+            // may silently skip at load. Refusing is the honest outcome — and it is loud, unlike the
+            // vanishing act it replaces. `registerWorkflow` has been declared (non-optional) in
+            // wicked-core-ts since 0.4.0, so this is a real floor, not a routine path.
+            throw new Error('this wicked-core build exposes no registerWorkflow binding, so a workflow cannot be ' +
+                'validated before it is written; refusing to persist an unvalidated definition');
         }
+        // Throws on a def core rejects — before anything is written or registered.
+        await register.call(this.core, json);
+        await writeFile(path, JSON.stringify(overlayDef, null, 2), 'utf8');
+        this.userWorkflows.set(def.id, def);
         return def.id;
     }
     /**