@deftai/directive-core 0.55.0

package/dist/swarm/routing-verify-cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { EXIT_CONFIG_ERROR } from "./constants.js";
+import { SWARM_WORKER_ROLES } from "./routing.js";
+import { verifyRouting } from "./routing-verify.js";
+export function routingVerifyMain(argv = process.argv.slice(2)) {
+    let projectRoot = ".";
+    let advise = false;
+    let provider = null;
+    const roles = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === "--project-root" && argv[i + 1] !== undefined) {
+            projectRoot = argv[i + 1] ?? ".";
+            i += 1;
+        }
+        else if (arg === "--advise") {
+            advise = true;
+        }
+        else if (arg === "--provider" && argv[i + 1] !== undefined) {
+            provider = argv[i + 1] ?? null;
+            i += 1;
+        }
+        else if (arg === "--roles" && argv[i + 1] !== undefined) {
+            for (const role of (argv[i + 1] ?? "").split(",")) {
+                if (role.trim().length > 0) {
+                    roles.push(role.trim());
+                }
+            }
+            i += 1;
+        }
+    }
+    for (const role of roles) {
+        if (!SWARM_WORKER_ROLES.includes(role)) {
+            process.stderr.write(`Error: unknown role '${role}' (one of: ${SWARM_WORKER_ROLES.join(", ")}).\n`);
+            return EXIT_CONFIG_ERROR;
+        }
+    }
+    const result = verifyRouting({
+        projectRoot,
+        advise,
+        provider,
+        roles: roles.length > 0 ? roles : undefined,
+    });
+    process.stdout.write(`${result.report}\n`);
+    return result.exitCode;
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exit(routingVerifyMain());
+}
+//# sourceMappingURL=routing-verify-cli.js.map

package/dist/swarm/routing-verify.d.ts

@@ -0,0 +1,20 @@
+export declare const ROUTING_SET_CMD = "task swarm:routing-set -- --role <role> --model <slug>   (or --harness-default)";
+/** Roles the pre-dispatch gate checks by default: the actual model lever. */
+export declare const DEFAULT_GATED_ROLES: readonly ["leaf-implementation"];
+export interface VerifyRoutingOptions {
+    projectRoot: string;
+    environ?: NodeJS.ProcessEnv;
+    roles?: readonly string[];
+    /** Session-start posture: surface, never block. */
+    advise?: boolean;
+    /** Override the resolved provider (else derived from the runtime). */
+    provider?: string | null;
+    /** Inject the runtime descriptor (else getPlatformCapabilities().runtimeMode). */
+    runtimeProbe?: () => string;
+}
+export interface VerifyRoutingResult {
+    exitCode: number;
+    report: string;
+}
+export declare function verifyRouting(options: VerifyRoutingOptions): VerifyRoutingResult;
+//# sourceMappingURL=routing-verify.d.ts.map

package/dist/swarm/routing-verify.js

@@ -0,0 +1,104 @@
+/**
+ * verify:routing gate (#1739). Two postures over the same route file:
+ *   - advise (session-start): surface unset routing as a disclosure line,
+ *     never blocks (always exit 0).
+ *   - enforce (pre-dispatch): a hard gate in the pre-`start_agent` /
+ *     `swarm:launch` gate stack. Three-state exit:
+ *       0 = every in-scope role is decided (pinned or explicit harness-default)
+ *       1 = at least one in-scope role is undecided / not dispatchable
+ *       2 = config error (unreadable / malformed route file)
+ */
+import { getPlatformCapabilities } from "../intake/platform-capabilities.js";
+import { EXIT_CONFIG_ERROR, EXIT_GATE_FAILED, EXIT_OK } from "./constants.js";
+import { dispatchProviderFromRuntime, HARNESS_BOUND_PROVIDERS, loadRoutingFile, ROUTING_MODE_HARNESS_DEFAULT, resolveModelRoute, resolveRoutingPath, } from "./routing.js";
+export const ROUTING_SET_CMD = "task swarm:routing-set -- --role <role> --model <slug>   (or --harness-default)";
+/** Roles the pre-dispatch gate checks by default: the actual model lever. */
+export const DEFAULT_GATED_ROLES = ["leaf-implementation"];
+function resolveProvider(options) {
+    if (options.provider !== undefined && options.provider !== null && options.provider.length > 0) {
+        return options.provider;
+    }
+    const probe = options.runtimeProbe ?? (() => getPlatformCapabilities().runtimeMode);
+    let runtimeMode = "";
+    try {
+        runtimeMode = probe();
+    }
+    catch {
+        runtimeMode = "";
+    }
+    return dispatchProviderFromRuntime(runtimeMode);
+}
+export function verifyRouting(options) {
+    const roles = options.roles && options.roles.length > 0 ? options.roles : DEFAULT_GATED_ROLES;
+    const provider = resolveProvider(options);
+    const routingPath = resolveRoutingPath(options.projectRoot, options.environ);
+    const { data, error } = loadRoutingFile(routingPath);
+    if (error !== null) {
+        if (options.advise) {
+            return {
+                exitCode: EXIT_OK,
+                report: `[deft routing] route file unreadable (${error}); pre-dispatch gate will block until fixed.`,
+            };
+        }
+        return { exitCode: EXIT_CONFIG_ERROR, report: `routing gate misconfigured: ${error}` };
+    }
+    const undecided = [];
+    const invalid = [];
+    const resolvedLines = [];
+    const harnessBound = HARNESS_BOUND_PROVIDERS.has(provider);
+    for (const role of roles) {
+        const resolution = resolveModelRoute(data, provider, role);
+        if (!resolution.decided) {
+            undecided.push(role);
+            continue;
+        }
+        if (resolution.source === "invalid") {
+            invalid.push(`${role}: ${resolution.error ?? "invalid decision"}`);
+            continue;
+        }
+        if (harnessBound && resolution.mode !== ROUTING_MODE_HARNESS_DEFAULT) {
+            invalid.push(`${role}: provider '${provider}' is harness-bound -- only mode=harness-default is recordable (cannot pin model '${resolution.model ?? ""}').`);
+            continue;
+        }
+        const modelText = resolution.model ?? "<runtime default>";
+        resolvedLines.push(`  ${role}: model ${modelText} (resolved-via ${resolution.source})`);
+    }
+    if (invalid.length > 0 && !options.advise) {
+        return {
+            exitCode: EXIT_CONFIG_ERROR,
+            report: `routing gate misconfigured for provider '${provider}':\n${invalid.map((l) => `  - ${l}`).join("\n")}`,
+        };
+    }
+    if (options.advise) {
+        if (undecided.length === 0 && invalid.length === 0) {
+            return {
+                exitCode: EXIT_OK,
+                report: `[deft routing] provider '${provider}': all ${roles.length} gated role(s) decided.`,
+            };
+        }
+        const parts = [];
+        if (undecided.length > 0) {
+            parts.push(`undecided role(s): ${undecided.join(", ")}`);
+        }
+        if (invalid.length > 0) {
+            parts.push(`invalid: ${invalid.length}`);
+        }
+        return {
+            exitCode: EXIT_OK,
+            report: `[deft routing] provider '${provider}' -- ${parts.join("; ")}. Decide before swarm dispatch: ${ROUTING_SET_CMD}`,
+        };
+    }
+    if (undecided.length > 0) {
+        return {
+            exitCode: EXIT_GATE_FAILED,
+            report: `routing gate: provider '${provider}' has undecided role(s): ${undecided.join(", ")}.\n` +
+                "Every dispatched role needs an explicit decision (pin a model or choose the harness default).\n" +
+                `Decide: ${ROUTING_SET_CMD}`,
+        };
+    }
+    return {
+        exitCode: EXIT_OK,
+        report: `routing gate: provider '${provider}' -- all gated role(s) decided.\n${resolvedLines.join("\n")}`,
+    };
+}
+//# sourceMappingURL=routing-verify.js.map

package/dist/swarm/routing.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The fixed worker-role vocabulary (reused from #1531). No separate tier
+ * vocabulary to start; decisions are strictly per-role.
+ */
+export declare const SWARM_WORKER_ROLES: readonly ["leaf-implementation", "orchestrator", "review-monitor", "merge-release"];
+export type SwarmWorkerRole = (typeof SWARM_WORKER_ROLES)[number];
+export declare const ROUTING_MODE_PINNED = "pinned";
+export declare const ROUTING_MODE_HARNESS_DEFAULT = "harness-default";
+export declare const ROUTING_FILENAME = "routing.local.json";
+/** Providers whose model is harness-bound -- deft cannot pin or verify a slug. */
+export declare const HARNESS_BOUND_PROVIDERS: Set<string>;
+export interface RouteDecision {
+    model: string | null;
+    mode?: string;
+    decidedAt?: string;
+}
+export type RoutingFile = Record<string, Record<string, RouteDecision>>;
+export interface RouteResolution {
+    /** true when the (provider, role) key is present -- a decision exists. */
+    decided: boolean;
+    /** pinned slug, or null for an explicit harness-default / undecided. */
+    model: string | null;
+    /** "pinned" | "harness-default" | null (undecided/invalid). */
+    mode: string | null;
+    /** "<provider>-route" | "harness-default explicit" | "undecided" | "invalid". */
+    source: string;
+    error: string | null;
+}
+/**
+ * Resolve the route-file path. Honors the `DEFT_ROUTING_PATH` override first
+ * (keeps both maintainer and consumer testable), then reads from the MAIN
+ * worktree root via `git rev-parse --git-common-dir` -> parent. The main-root
+ * read is deliberate: gitignored/untracked files are NOT copied into
+ * `git worktree add` directories, and swarm dispatches leaf coders from
+ * worktrees, so every worktree in a cohort must share the one local file.
+ */
+export declare function resolveRoutingPath(startDir: string, environ?: NodeJS.ProcessEnv): string;
+export declare function loadRoutingFile(path: string): {
+    data: RoutingFile | null;
+    error: string | null;
+};
+/**
+ * Resolve a (provider, role) route. Tri-state by KEY PRESENCE:
+ *   - key present, model "<slug>"      -> pinned
+ *   - key present, model null          -> explicit harness-default (a decision)
+ *   - key absent                       -> undecided (fail loud upstream)
+ */
+export declare function resolveModelRoute(file: RoutingFile | null, provider: string, role: string): RouteResolution;
+/** Map a runtime descriptor (platform-capabilities.runtimeMode) to a route key. */
+export declare function dispatchProviderFromRuntime(runtimeMode: string): string;
+/**
+ * Write a decision back to the route file (create-if-missing). Stamps
+ * `decidedAt` when the caller did not supply one. Used by the interactive
+ * resolver path (resolver step 5) and the `swarm:routing-set` task.
+ */
+export declare function writeModelDecision(path: string, provider: string, role: string, decision: RouteDecision): void;
+//# sourceMappingURL=routing.d.ts.map

package/dist/swarm/routing.js

@@ -0,0 +1,173 @@
+/**
+ * Operator-specifiable coding sub-agent model routing (#1739).
+ *
+ * The selection lives in a per-project, per-machine, gitignored route file
+ * (`.deft/routing.local.json`) keyed by (dispatch_provider, worker_role) -> a
+ * decision object. Unlike the superseded `swarmSubagentBackend` enum (#1531 /
+ * #1735), which recorded intent but was never threaded into the spawn call,
+ * the resolved model is stamped into the launch manifest so the dispatch path
+ * can actually honor it.
+ *
+ * Load-bearing rule: "decided?" is tested by KEY PRESENCE, never by value
+ * truthiness -- an explicit `model: null` (mode: harness-default) is a
+ * decision, not absence. Testing truthiness would re-nag every session on an
+ * explicit default.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+/**
+ * The fixed worker-role vocabulary (reused from #1531). No separate tier
+ * vocabulary to start; decisions are strictly per-role.
+ */
+export const SWARM_WORKER_ROLES = [
+    "leaf-implementation",
+    "orchestrator",
+    "review-monitor",
+    "merge-release",
+];
+export const ROUTING_MODE_PINNED = "pinned";
+export const ROUTING_MODE_HARNESS_DEFAULT = "harness-default";
+export const ROUTING_FILENAME = "routing.local.json";
+/** Providers whose model is harness-bound -- deft cannot pin or verify a slug. */
+export const HARNESS_BOUND_PROVIDERS = new Set(["grok"]);
+/**
+ * Resolve the route-file path. Honors the `DEFT_ROUTING_PATH` override first
+ * (keeps both maintainer and consumer testable), then reads from the MAIN
+ * worktree root via `git rev-parse --git-common-dir` -> parent. The main-root
+ * read is deliberate: gitignored/untracked files are NOT copied into
+ * `git worktree add` directories, and swarm dispatches leaf coders from
+ * worktrees, so every worktree in a cohort must share the one local file.
+ */
+export function resolveRoutingPath(startDir, environ = process.env) {
+    const override = environ.DEFT_ROUTING_PATH;
+    if (override !== undefined && override.trim().length > 0) {
+        return resolve(override.trim());
+    }
+    let root = resolve(startDir);
+    try {
+        const out = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+            cwd: startDir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (out.length > 0) {
+            const commonDir = isAbsolute(out) ? out : resolve(startDir, out);
+            root = dirname(commonDir);
+        }
+    }
+    catch {
+        // Not a git work tree -- fall back to startDir.
+    }
+    return join(root, ".deft", ROUTING_FILENAME);
+}
+export function loadRoutingFile(path) {
+    if (!existsSync(path)) {
+        return { data: null, error: null };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (exc) {
+        return { data: null, error: `${path}: invalid JSON (${String(exc)}).` };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { data: null, error: `${path}: routing file must be a JSON object.` };
+    }
+    return { data: parsed, error: null };
+}
+function providerBlockOf(file, provider) {
+    if (file === null) {
+        return null;
+    }
+    const block = file[provider];
+    if (typeof block !== "object" || block === null || Array.isArray(block)) {
+        return null;
+    }
+    return block;
+}
+/**
+ * Resolve a (provider, role) route. Tri-state by KEY PRESENCE:
+ *   - key present, model "<slug>"      -> pinned
+ *   - key present, model null          -> explicit harness-default (a decision)
+ *   - key absent                       -> undecided (fail loud upstream)
+ */
+export function resolveModelRoute(file, provider, role) {
+    const block = providerBlockOf(file, provider);
+    if (block === null || !(role in block)) {
+        return { decided: false, model: null, mode: null, source: "undecided", error: null };
+    }
+    const decision = block[role];
+    if (typeof decision !== "object" || decision === null || Array.isArray(decision)) {
+        return {
+            decided: true,
+            model: null,
+            mode: null,
+            source: "invalid",
+            error: `routing[${provider}][${role}] must be a decision object.`,
+        };
+    }
+    const model = decision.model;
+    const mode = typeof decision.mode === "string" && decision.mode.length > 0 ? decision.mode : null;
+    if (model === null) {
+        return {
+            decided: true,
+            model: null,
+            mode: mode ?? ROUTING_MODE_HARNESS_DEFAULT,
+            source: "harness-default explicit",
+            error: null,
+        };
+    }
+    if (typeof model === "string" && model.trim().length > 0) {
+        return {
+            decided: true,
+            model: model.trim(),
+            mode: mode ?? ROUTING_MODE_PINNED,
+            source: `${provider}-route`,
+            error: null,
+        };
+    }
+    return {
+        decided: true,
+        model: null,
+        mode,
+        source: "invalid",
+        error: `routing[${provider}][${role}].model must be a non-empty string or explicit null.`,
+    };
+}
+/** Map a runtime descriptor (platform-capabilities.runtimeMode) to a route key. */
+export function dispatchProviderFromRuntime(runtimeMode) {
+    const normalized = runtimeMode.trim().toLowerCase();
+    if (normalized.length === 0) {
+        return "unknown";
+    }
+    if (normalized.includes("grok")) {
+        return "grok";
+    }
+    if (normalized.includes("cursor")) {
+        return "cursor";
+    }
+    return normalized;
+}
+/**
+ * Write a decision back to the route file (create-if-missing). Stamps
+ * `decidedAt` when the caller did not supply one. Used by the interactive
+ * resolver path (resolver step 5) and the `swarm:routing-set` task.
+ */
+export function writeModelDecision(path, provider, role, decision) {
+    const { data } = loadRoutingFile(path);
+    const file = data ?? {};
+    const existing = providerBlockOf(file, provider);
+    const block = existing ?? {};
+    block[role] = {
+        model: decision.model,
+        mode: decision.mode ??
+            (decision.model === null ? ROUTING_MODE_HARNESS_DEFAULT : ROUTING_MODE_PINNED),
+        decidedAt: decision.decidedAt ?? new Date().toISOString(),
+    };
+    file[provider] = block;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`, "utf8");
+}
+//# sourceMappingURL=routing.js.map

package/dist/swarm/subagent-backend.d.ts

@@ -0,0 +1,22 @@
+import { LEAF_CODING_WORKER_ROLE } from "./constants.js";
+export declare const KNOWN_SUBAGENT_BACKEND_IDS: Set<string>;
+export interface SubagentBackendDescriptor {
+    readonly backend_id: string;
+    readonly display_name: string;
+    readonly roles: readonly string[];
+    readonly available: boolean;
+}
+export interface SwarmSubagentBackendResult {
+    readonly backend_id: string | null;
+    readonly source: string;
+    readonly error: string | null;
+}
+export declare function probeSubagentBackends(environ?: NodeJS.ProcessEnv): SubagentBackendDescriptor[];
+export declare function resolveSwarmSubagentBackend(projectRoot: string): SwarmSubagentBackendResult;
+export declare function dispatchProviderFor(backendId: string): string;
+export declare function enforceSubagentBackendPolicy(projectRoot: string, environ?: NodeJS.ProcessEnv): {
+    backend: SubagentBackendDescriptor | null;
+    error: string | null;
+};
+export { LEAF_CODING_WORKER_ROLE };
+//# sourceMappingURL=subagent-backend.d.ts.map

package/dist/swarm/subagent-backend.js

@@ -0,0 +1,162 @@
+import { loadProjectDefinition } from "../policy/resolve.js";
+import { LEAF_CODING_WORKER_ROLE, SUBAGENT_BACKEND_SET_CMD } from "./constants.js";
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+export const KNOWN_SUBAGENT_BACKEND_IDS = new Set(["composer", "grok-build", "cursor-cloud"]);
+const SUBAGENT_BACKEND_CATALOG = {
+    composer: {
+        display_name: "Composer-class coding agent",
+        roles: ["leaf-implementation"],
+    },
+    "grok-build": {
+        display_name: "Grok Build (spawn_subagent)",
+        roles: ["leaf-implementation", "review-monitor"],
+    },
+    "cursor-cloud": {
+        display_name: "Cursor / cloud agent",
+        roles: ["leaf-implementation", "orchestrator", "review-monitor"],
+    },
+};
+function isTruthy(value) {
+    return value !== undefined && TRUTHY.has(value.trim().toLowerCase());
+}
+function probeBackendAvailable(backendId, environ = process.env) {
+    const envKey = `DEFT_PROBE_${backendId.toUpperCase().replace(/-/g, "_")}`;
+    const override = environ[envKey];
+    if (override !== undefined) {
+        return isTruthy(override);
+    }
+    if (backendId === "grok-build") {
+        const runtime = environ.DEFT_AGENT_RUNTIME?.trim().toLowerCase() ?? "";
+        return isTruthy(environ.GROK_BUILD) || runtime === "grok-build";
+    }
+    if (backendId === "composer") {
+        return isTruthy(environ.CURSOR_COMPOSER);
+    }
+    if (backendId === "cursor-cloud") {
+        return isTruthy(environ.CURSOR_AGENT);
+    }
+    return false;
+}
+export function probeSubagentBackends(environ = process.env) {
+    return [...KNOWN_SUBAGENT_BACKEND_IDS].sort().map((backendId) => {
+        const meta = SUBAGENT_BACKEND_CATALOG[backendId];
+        return {
+            backend_id: backendId,
+            display_name: meta?.display_name ?? backendId,
+            roles: meta?.roles ?? [],
+            available: probeBackendAvailable(backendId, environ),
+        };
+    });
+}
+function getPolicyBlock(data) {
+    const plan = data.plan;
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        return {};
+    }
+    const policy = plan.policy;
+    if (typeof policy !== "object" || policy === null || Array.isArray(policy)) {
+        return {};
+    }
+    return policy;
+}
+export function resolveSwarmSubagentBackend(projectRoot) {
+    const [data, err] = loadProjectDefinition(projectRoot);
+    if (data === null) {
+        return { backend_id: null, source: "default", error: err };
+    }
+    const policyBlock = getPolicyBlock(data);
+    if (!("swarmSubagentBackend" in policyBlock)) {
+        return { backend_id: null, source: "default", error: null };
+    }
+    const raw = policyBlock.swarmSubagentBackend;
+    if (raw === null) {
+        return {
+            backend_id: null,
+            source: "typed",
+            error: "plan.policy.swarmSubagentBackend is explicitly null.",
+        };
+    }
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        return {
+            backend_id: null,
+            source: "typed",
+            error: `plan.policy.swarmSubagentBackend must be a non-empty string; got ${typeof raw}`,
+        };
+    }
+    const bid = raw.trim();
+    if (!KNOWN_SUBAGENT_BACKEND_IDS.has(bid)) {
+        return {
+            backend_id: bid,
+            source: "typed",
+            error: `plan.policy.swarmSubagentBackend must be one of ` +
+                `${JSON.stringify([...KNOWN_SUBAGENT_BACKEND_IDS].sort())}; got ${JSON.stringify(bid)}`,
+        };
+    }
+    return { backend_id: bid, source: "typed", error: null };
+}
+function formatProbedBackends(backends) {
+    return backends
+        .map((entry) => {
+        const avail = entry.available ? "available" : "unavailable";
+        return `  ${entry.backend_id} (${avail}; roles=[${entry.roles.join(", ")}])`;
+    })
+        .join("\n");
+}
+const DISPATCH_PROVIDER_BY_BACKEND = {
+    composer: "cursor",
+    "grok-build": "grok",
+    "cursor-cloud": "cursor",
+};
+export function dispatchProviderFor(backendId) {
+    return DISPATCH_PROVIDER_BY_BACKEND[backendId] ?? backendId;
+}
+export function enforceSubagentBackendPolicy(projectRoot, environ = process.env) {
+    const result = resolveSwarmSubagentBackend(projectRoot);
+    const probed = probeSubagentBackends(environ);
+    if (result.backend_id === null) {
+        const detail = result.error ?? "plan.policy.swarmSubagentBackend is not set.";
+        const listing = formatProbedBackends(probed);
+        return {
+            backend: null,
+            error: `${detail}\n` +
+                "Select a coding sub-agent backend before headless dispatch:\n" +
+                `${listing}\n` +
+                "Probe harness availability: task policy:subagent-backends\n" +
+                `Persist a choice: ${SUBAGENT_BACKEND_SET_CMD.replace("{backend_id}", "<id>")}`,
+        };
+    }
+    const selected = probed.find((e) => e.backend_id === result.backend_id) ?? null;
+    if (selected === null) {
+        const known = probed.map((e) => e.backend_id).join(", ");
+        return {
+            backend: null,
+            error: `plan.policy.swarmSubagentBackend=${JSON.stringify(result.backend_id)} is not a ` +
+                `known backend id (known: ${known}).\n` +
+                `Persist a valid choice: ${SUBAGENT_BACKEND_SET_CMD.replace("{backend_id}", "<id>")}`,
+        };
+    }
+    if (!selected.available) {
+        const availableIds = probed.filter((e) => e.available).map((e) => e.backend_id);
+        const availText = availableIds.length > 0 ? availableIds.join(", ") : "(none)";
+        return {
+            backend: null,
+            error: `plan.policy.swarmSubagentBackend=${JSON.stringify(result.backend_id)} is ` +
+                "unavailable in the current harness.\n" +
+                `Available backend ids: ${availText}\n` +
+                `Choose a different backend: ${SUBAGENT_BACKEND_SET_CMD.replace("{backend_id}", "<id>")}`,
+        };
+    }
+    if (!selected.roles.includes(LEAF_CODING_WORKER_ROLE)) {
+        const rolesText = selected.roles.length > 0 ? selected.roles.join(", ") : "(none)";
+        return {
+            backend: null,
+            error: `plan.policy.swarmSubagentBackend=${JSON.stringify(result.backend_id)} does not ` +
+                `support worker role ${JSON.stringify(LEAF_CODING_WORKER_ROLE)} ` +
+                `(roles=[${rolesText}]).\n` +
+                `Choose a leaf-implementation backend: ${SUBAGENT_BACKEND_SET_CMD.replace("{backend_id}", "<id>")}`,
+        };
+    }
+    return { backend: selected, error: null };
+}
+export { LEAF_CODING_WORKER_ROLE };
+//# sourceMappingURL=subagent-backend.js.map

package/dist/swarm/subprocess.d.ts

@@ -0,0 +1,10 @@
+export interface TextCaptureResult {
+    readonly returncode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** UTF-8-safe subprocess capture — mirrors scripts/_safe_subprocess.run_text (#1366). */
+export declare function runText(command: readonly string[], options?: {
+    cwd?: string;
+}): TextCaptureResult;
+//# sourceMappingURL=subprocess.d.ts.map

package/dist/swarm/subprocess.js

@@ -0,0 +1,34 @@
+import { execFileSync } from "node:child_process";
+import { SUBPROCESS_MAX_BUFFER } from "../subprocess/max-buffer.js";
+/** UTF-8-safe subprocess capture — mirrors scripts/_safe_subprocess.run_text (#1366). */
+export function runText(command, options = {}) {
+    if (command.length === 0) {
+        return { returncode: -1, stdout: "", stderr: "empty command" };
+    }
+    const [binary, ...args] = command;
+    try {
+        const stdout = execFileSync(binary ?? "", args, {
+            cwd: options.cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            maxBuffer: SUBPROCESS_MAX_BUFFER,
+        });
+        return {
+            returncode: 0,
+            stdout: typeof stdout === "string" ? stdout : "",
+            stderr: "",
+        };
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT") {
+            return { returncode: -1, stdout: "", stderr: String(e.message ?? "command not found") };
+        }
+        return {
+            returncode: typeof e.status === "number" ? e.status : -1,
+            stdout: typeof e.stdout === "string" ? e.stdout : "",
+            stderr: typeof e.stderr === "string" ? e.stderr : String(e.message ?? ""),
+        };
+    }
+}
+//# sourceMappingURL=subprocess.js.map

package/dist/swarm/verify-review-clean-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare function verifyReviewCleanMain(argv?: string[]): number;
+//# sourceMappingURL=verify-review-clean-cli.d.ts.map