wicked-crew 0.2.1 → 0.3.1

package/dist/core/adapter.js

@@ -1,10 +1,161 @@
 import { createRequire } from 'node:module';
+import { execFile } from 'node:child_process';
+import { mkdir, access, readFile, writeFile, chmod, rm } from 'node:fs/promises';
+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);
+/** 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);
+}
+/**
+ * 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
+ * and (with registerWorkflow NAPI) at runtime. TS must write to the same location so
+ * the files are picked up on the next daemon start.
+ *   • `$WICKED_WORKFLOWS_DIR`  — explicit override (matches Rust env check)
+ *   • `~/.config/wicked-core/workflows`  — default (matches Rust default)
+ */
+function workflowOverlayDir() {
+    if (process.env.WICKED_WORKFLOWS_DIR)
+        return process.env.WICKED_WORKFLOWS_DIR;
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? '/tmp';
+    return join(home, '.config', 'wicked-core', 'workflows');
+}
+function settingsFilePath() {
+    return join(homedir(), '.config', 'wicked-core', 'settings.json');
+}
+/** 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).
+ */
+function locateWickedCoreExe() {
+    const exeName = process.platform === 'win32' ? 'wicked-core.exe' : 'wicked-core';
+    const candidates = [];
+    // User-local install (cargo install / manual).
+    const home = process.env.HOME ?? process.env.USERPROFILE;
+    if (home) {
+        candidates.push(join(home, '.local', 'bin', exeName));
+        candidates.push(join(home, '.cargo', 'bin', exeName));
+    }
+    // Monorepo dev build.
+    candidates.push(join(dirname(fileURLToPath(import.meta.url)), '../../..', 'wicked-core', 'target', 'release', exeName));
+    // PATH lookup.
+    const pathDirs = (process.env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':');
+    for (const dir of pathDirs) {
+        candidates.push(join(dir, exeName));
+    }
+    const { existsSync } = require('node:fs');
+    return candidates.find((p) => existsSync(p));
+}
 // The native addon is a CommonJS cdylib (`index.node`); load it with a CJS
 // require even though this daemon is ESM. This module is the ONLY place that
 // touches wicked-core-ts (DES-STUDIO-001 §5.2/§5.3), so the FINALIZING
 // `subscribe` seam has a blast radius of exactly one file.
 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.
+// Swap for `this.core.listWorkflowsJson()` / `this.core.getWorkflowJson(id)` once
+// the wicked-core-ts NAPI methods land.
+const BUILTIN_WORKFLOWS = [
+    {
+        id: 'chat',
+        is_system: true,
+        phases: [
+            { id: 'explore', 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: '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: 'feature',
+        phases: [
+            { 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: '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 },
+        ],
+    },
+    {
+        id: 'bug',
+        phases: [
+            { 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: 'migration',
+        phases: [
+            { 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: '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 },
+        ],
+    },
+    {
+        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: 'domain-graph-slice',
+        is_system: true,
+        phases: [
+            { id: 'identify', 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: 'extract', kind: 'build', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['identify'], role: 'creator', skill_ref: null, allowed_skills: [], validator_pin: null },
+            { id: 'validate', kind: 'review', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['extract'], role: 'evaluator', skill_ref: null, allowed_skills: [], validator_pin: null },
+        ],
+    },
+    {
+        id: 'memories',
+        is_system: true,
+        phases: [
+            { id: 'gather', 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: 'store', kind: 'build', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['gather'], role: 'creator', skill_ref: null, allowed_skills: [], validator_pin: null },
+        ],
+    },
+    {
+        id: 'collab',
+        is_system: true,
+        phases: [
+            { id: 'propose', kind: 'recon', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: [], role: 'creator', skill_ref: null, allowed_skills: [], validator_pin: null },
+            { id: 'critique', kind: 'review', gate_type: 'value', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['propose'], role: 'evaluator', skill_ref: null, allowed_skills: [], validator_pin: null },
+            { id: 'revise', kind: 'recon', gate_type: 'strategy', gate: 'auto', executes_code: false, verified_evidence: false, required_deliverables: [], depends_on: ['critique'], role: 'creator', skill_ref: null, allowed_skills: [], validator_pin: null },
+            { 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 single isolation boundary over wicked-core-ts. It holds the ONE `Core`
  * handle, makes the ONE `subscribe()` call for the whole process, parses each
@@ -17,6 +168,8 @@ export class CoreAdapter {
     subscription;
     listeners = new Set();
     closed = false;
+    /** Built-in workflow ids whose overlay JSON has been written this process lifetime. */
+    _builtinOverlayWritten = new Set();
     /** `true` when this adapter armed the event-driven exec seam (for readiness/reporting). */
     engineExec;
     /** The bus db the exec seam runs over when armed (else `undefined`). */
@@ -38,6 +191,15 @@ export class CoreAdapter {
         }
         this.engineExec = armExec;
         this.busDbPath = armExec ? opts.busDbPath : undefined;
+        // Give the Rust actor the path to the wicked-core standalone binary so the gate-hook
+        // command works when wicked-core is loaded as a napi-rs addon (where current_exe()
+        // returns the Node.js interpreter, not wicked-core). The actor checks WICKED_CORE_EXE
+        // first, so this env wins over the current_exe() fallback.
+        if (!process.env['WICKED_CORE_EXE']) {
+            const wcExe = locateWickedCoreExe();
+            if (wcExe)
+                process.env['WICKED_CORE_EXE'] = wcExe;
+        }
         this.core = opts.stub ? Core.spawnStub(opts.dbPath) : Core.spawn(opts.dbPath);
         // The ONE subscribe() for the process. Error-first callback (index.d.ts:56):
         // one JSON string per CoreEvent, in emission order. A throw in a listener is
@@ -78,7 +240,7 @@ export class CoreAdapter {
         return this.core.ping();
     }
     /** Launch an interactive, resumable run → the run id. */
-    launchRun(input) {
+    async launchRun(input) {
         const opts = {
             problem: input.problem,
             sessionId: input.sessionId,
@@ -90,6 +252,20 @@ export class CoreAdapter {
             opts.humanConfirm = input.humanConfirm;
         if (input.repoRef !== undefined)
             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.
+            // 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);
+            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.
+                this._builtinOverlayWritten.add(input.workflow);
+                await this._writeBuiltinOverlay(builtinDef);
+            }
+        }
         return this.core.launchRun(opts);
     }
     /** Resume a run from its persisted cursor → the status token. */
@@ -104,26 +280,336 @@ export class CoreAdapter {
     cancelRun(runId) {
         return this.core.cancelRun(runId);
     }
+    /** Inject an operator message into a run's active PTY worker(s). target="all" or a CLI key. */
+    injectWorkerMessage(runId, message, target) {
+        if (typeof this.core.injectWorkerMessage !== 'function') {
+            return Promise.reject(new Error('Operator message injection is not yet supported by this wicked-core build'));
+        }
+        return this.core.injectWorkerMessage(runId, message, target);
+    }
     /** Run ids on the store. */
     async sessions() {
         return JSON.parse(await this.core.sessions());
     }
     /** Every run + its ordered units. */
     async sessionsDetail() {
-        return JSON.parse(await this.core.sessionsDetail());
+        const views = JSON.parse(await this.core.sessionsDetail());
+        // The Rust core always stores workflow_id as 'wf-<session-uuid>' (an instance ID, not the
+        // definition name). Patch it back to the definition name so the studio's chat/work filters work.
+        // phase_ref is only set on executed units and uses format 'wf-<uuid>:unit-N' (not the phase id).
+        // The phase id is reliably embedded in the unit id as '<session-uuid>:<phase-id>'.
+        for (const view of views) {
+            if (view.session.workflow_id?.startsWith('wf-')) {
+                const phases = [...view.units].sort((a, b) => a.ord - b.ord).map((u) => {
+                    const colonIdx = u.id.indexOf(':');
+                    return colonIdx >= 0 ? u.id.slice(colonIdx + 1) : '';
+                });
+                if (view.units.length === 1) {
+                    // Single-unit chat sessions have phase id 'explore' (from the chat workflow def).
+                    // 'u1' is ambiguous — it appears on any single-unit run without an explicit workflow,
+                    // including Do Work runs, so we leave those unpatched rather than misclassify them.
+                    const phase = phases[0] ?? '';
+                    if (phase === 'explore')
+                        view.session.workflow_id = 'chat';
+                }
+                else {
+                    // Multi-unit: match against builtin workflow defs by phase sequence
+                    const match = BUILTIN_WORKFLOWS.find((def) => def.phases.length === phases.length &&
+                        def.phases.every((p, i) => p.id === phases[i]));
+                    if (match)
+                        view.session.workflow_id = match.id;
+                }
+            }
+        }
+        return views;
     }
     /** A unit's captured transcript (string, or `null`). */
     async workOutput(unitId) {
         return JSON.parse(await this.core.workOutput(unitId));
     }
-    /** Register a git repo → the persisted `RepoEntry`. */
+    /** 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();
+    /** Register a local git repo → the persisted `RepoEntry`. */
     async registerRepo(name, rootPath) {
         return JSON.parse(await this.core.registerRepo(name, rootPath));
     }
+    /**
+     * Clone a remote git URL, register it, then launch an `onboarding` workflow run.
+     * `checkoutPath` overrides the default clone destination (`~/.wicked/repos/<name>`).
+     */
+    async cloneAndRegisterRepo(name, gitUrl, checkoutPath) {
+        const reposRoot = wickedDir('repos');
+        let cloneDir;
+        if (checkoutPath) {
+            // Expand leading ~/ so callers can use home-relative paths.
+            const expanded = checkoutPath.startsWith('~/')
+                ? join(homedir(), checkoutPath.slice(2))
+                : checkoutPath;
+            if (!isAbsolute(expanded)) {
+                throw new Error('checkoutPath must be an absolute path (or start with ~/)');
+            }
+            cloneDir = resolve(expanded);
+        }
+        else {
+            cloneDir = join(reposRoot, name);
+            // Defense-in-depth: name validated by schema, but guard direct calls too.
+            // Use relative() instead of startsWith(root+'/') so this works cross-platform
+            // (Windows uses backslash separators, making a literal '/' suffix check unreliable).
+            const rel = relative(reposRoot, cloneDir);
+            if (rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel)) {
+                throw new Error('Unsafe repo name: would escape the repos directory');
+            }
+        }
+        // Ensure the parent exists (first-run, nested checkoutPath, etc.) before the
+        // atomic create below — recursive mkdir is safe for parents since we are not
+        // the intended owner of those directories.
+        await mkdir(resolve(cloneDir, '..'), { recursive: true });
+        // Atomic exclusive mkdir: succeeds only if we created the directory, throws
+        // EEXIST if it already existed. This is race-safe — recursive mkdir would
+        // silently succeed for existing dirs, making weMadeDir unreliable.
+        let weMadeDir = false;
+        try {
+            await mkdir(cloneDir);
+            weMadeDir = true;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== 'EEXIST')
+                throw err;
+            // Directory already existed — verify it is actually a directory (not a file).
+            await access(join(cloneDir, '.'));
+        }
+        let needsClone = true;
+        try {
+            await access(join(cloneDir, '.git'));
+            needsClone = false;
+        }
+        catch { /* not yet cloned */ }
+        if (needsClone) {
+            try {
+                await execFileAsync('git', ['clone', '--', gitUrl, cloneDir], {
+                    timeout: 5 * 60 * 1000,
+                });
+            }
+            catch (err) {
+                // Cleanup is best-effort: swallow any cleanup error so the original
+                // clone failure is what the caller sees.
+                if (weMadeDir) {
+                    await rm(cloneDir, { recursive: true, force: true }).catch(() => { });
+                }
+                else {
+                    // Pre-existing dir: remove a partially-written .git so the next call
+                    // doesn't incorrectly skip cloning against a broken working tree.
+                    await rm(join(cloneDir, '.git'), { recursive: true, force: true }).catch(() => { });
+                }
+                throw err;
+            }
+        }
+        const entry = await this.registerRepo(name, cloneDir);
+        const runId = await this.launchOnboardingRun(entry.id, name);
+        return { repoId: entry.id, runId };
+    }
+    /**
+     * Launch the built-in `onboarding` workflow for a registered repo.
+     * The run's `workdir` = the repo root; Tool phases run estate commands there.
+     * 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);
+        const runId = randomUUID();
+        const chained = this._onboardingChain.then(() => this._doOnboardingLaunch(repoId, repoName, runId));
+        this._onboardingChain = chained.catch(() => undefined);
+        try {
+            await chained;
+            return runId;
+        }
+        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,
+            });
+        }
+        this.repoOnboardRunIds.set(repoId, runId);
+    }
+    /** Return the onboarding run id for a repo (undefined if not launched this session). */
+    getOnboardRunId(repoId) {
+        return this.repoOnboardRunIds.get(repoId);
+    }
     /** List every registered repo. */
     async listRepos() {
         return JSON.parse(await this.core.listRepos());
     }
+    // ── Governance reads (crew#40) ──────────────────────────────────────────────
+    /** All registered governance policies. */
+    async listPolicies() {
+        return JSON.parse(await this.core.listPolicies());
+    }
+    /** All conformance rules on the store. */
+    async listConformanceRules() {
+        return JSON.parse(await this.core.listConformanceRules());
+    }
+    /** All recorded conformance claims (governance decisions). */
+    async listConformanceClaims() {
+        return JSON.parse(await this.core.listConformanceClaims());
+    }
+    /** Front-half coverage gate report; null when the store has no graph nodes. */
+    async getCoverageReport() {
+        return JSON.parse(await this.core.getCoverageReport());
+    }
+    // ── Governance writes (crew#42) ────────────────────────────────────────────
+    /** Upsert a governance policy via the single-writer actor. */
+    async upsertPolicy(policy) {
+        await this.core.upsertPolicy(JSON.stringify(policy));
+    }
+    /** Upsert a conformance rule via the single-writer actor. */
+    async upsertConformanceRule(rule) {
+        await this.core.upsertConformanceRule(JSON.stringify(rule));
+    }
+    /** Recall conformance rules matching a facet query (read-only, does not block actor). */
+    async recallRulesPreview(query) {
+        const cleanQuery = {};
+        for (const [k, v] of Object.entries(query)) {
+            // Fastify may parse duplicate params as arrays — take the first string value only.
+            const scalar = Array.isArray(v) ? v[0] : v;
+            if (typeof scalar === 'string' && scalar.length > 0)
+                cleanQuery[k] = scalar;
+        }
+        const json = await this.core.recallRulesPreview(JSON.stringify(cleanQuery));
+        return JSON.parse(json);
+    }
+    // ── Workflow viewer + builder (crew#44) ────────────────────────────────────
+    // Built-ins are static TypeScript mirrors of workflow.rs. User-registered
+    // 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();
+    listWorkflows() {
+        // Builtins first (stable ordering), but user-registered workflows take precedence when
+        // ids conflict — consistent with getWorkflow() which prefers userWorkflows.get().
+        const seen = new Set();
+        const result = [];
+        for (const w of BUILTIN_WORKFLOWS) {
+            const override = this.userWorkflows.get(w.id);
+            if (!seen.has(w.id)) {
+                seen.add(w.id);
+                result.push(override ?? w);
+            }
+        }
+        for (const w of this.userWorkflows.values()) {
+            if (!seen.has(w.id)) {
+                seen.add(w.id);
+                result.push(w);
+            }
+        }
+        return result;
+    }
+    getWorkflow(id) {
+        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).
+     *  Unlike registerWorkflow(), this does NOT touch userWorkflows, avoiding duplicates in listWorkflows(). */
+    async _writeBuiltinOverlay(def) {
+        const dir = workflowOverlayDir();
+        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 core = this.core;
+        if (typeof core['registerWorkflow'] === 'function') {
+            await core['registerWorkflow'](JSON.stringify(overlayDef));
+        }
+    }
+    /**
+     * Register a user-authored workflow: persist to the Rust workflow overlay dir
+     * (`~/.config/wicked-core/workflows/<id>.json` or `$WICKED_WORKFLOWS_DIR`),
+     * update the in-memory registry, and (when core supports it) register in the
+     * Rust actor so runs using this workflow work immediately without a restart.
+     */
+    async registerWorkflow(def) {
+        const SAFE_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+        if (!SAFE_ID.test(def.id) || def.id.length > 128) {
+            throw new Error('workflow id must start with a letter/digit and contain only letters, digits, dots, hyphens, and underscores');
+        }
+        const dir = workflowOverlayDir();
+        await mkdir(dir, { recursive: true });
+        const path = join(dir, `${def.id}.json`);
+        // Strip `is_system` before writing — the Rust core's overlay format does not recognise that
+        // 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 core = this.core;
+        if (typeof core['registerWorkflow'] === 'function') {
+            await core['registerWorkflow'](JSON.stringify(overlayDef));
+        }
+        return def.id;
+    }
+    /**
+     * Save an inline script to `~/.wicked/scripts/<name>.<ext>`, make it executable,
+     * and return the absolute path. Tool-executor phases use this path as their command.
+     */
+    async saveScript(name, content, lang) {
+        const ext = lang === 'python' ? 'py' : 'sh';
+        const dir = wickedDir('scripts');
+        await mkdir(dir, { recursive: true });
+        const filename = `${name.replace(/[^a-z0-9_-]/gi, '_')}.${ext}`;
+        const path = join(dir, filename);
+        const shebang = lang === 'python' ? '#!/usr/bin/env python3\n' : '#!/usr/bin/env bash\n';
+        await writeFile(path, shebang + content, 'utf8');
+        await chmod(path, 0o755);
+        return path;
+    }
     // ── PTY terminal sessions (DES-TERMINAL-001 §6) ────────────────────────────
     // Thin wrappers over the four core-ts terminal methods. Output does NOT return
     // here — it arrives as `terminalOutput` CoreEvents on the single subscription
@@ -150,6 +636,31 @@ export class CoreAdapter {
     closeTerminal(id) {
         return this.core.closeTerminal(id);
     }
+    // ── System settings ───────────────────────────────────────────────────────
+    async getSettings() {
+        try {
+            const raw = await readFile(settingsFilePath(), 'utf8');
+            const parsed = JSON.parse(raw);
+            // Validate numeric fields; drop anything out-of-range rather than propagate bad values.
+            if ('graphNodeLimit' in parsed) {
+                const v = parsed.graphNodeLimit;
+                if (typeof v !== 'number' || !Number.isInteger(v) || v < 1 || v > 10000)
+                    delete parsed.graphNodeLimit;
+            }
+            return { ...DEFAULT_SETTINGS, ...parsed };
+        }
+        catch {
+            return { ...DEFAULT_SETTINGS };
+        }
+    }
+    async updateSettings(patch) {
+        const current = await this.getSettings();
+        const next = { ...current, ...patch };
+        const path = settingsFilePath();
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, JSON.stringify(next, null, 2), 'utf8');
+        return next;
+    }
     /**
      * Tear down the single subscription (stop delivery, release the pump thread +
      * callback) so the process can exit cleanly. Idempotent.