@voybio/ace-swarm 2.4.3 → 2.4.6

package/dist/job-scheduler.js

@@ -538,6 +538,33 @@ function deriveOwner(input) {
 function defaultLeaseTtlSeconds() {
     return 1800;
 }
+/**
+ * Default window a running job may go without a worker heartbeat before the
+ * watchdog presumes the worker is dead and reaps the job into
+ * `unknown_recovery`. A live in-process worker is expected to call
+ * `heartbeatJob` well within this window (see job-worker.ts).
+ */
+export const DEFAULT_HEARTBEAT_STALE_MS = 120_000;
+function resolveStaleMs(heartbeatStaleSeconds) {
+    if (typeof heartbeatStaleSeconds !== "number" || !Number.isFinite(heartbeatStaleSeconds)) {
+        return DEFAULT_HEARTBEAT_STALE_MS;
+    }
+    if (heartbeatStaleSeconds <= 0)
+        return 0;
+    return Math.floor(heartbeatStaleSeconds * 1000);
+}
+function latestHeartbeatMs(job, activeLocks) {
+    let latest = 0;
+    for (const lock of activeLocks) {
+        const stamp = parseDate(lock.heartbeat_at ?? lock.acquired_at)?.getTime();
+        if (stamp && stamp > latest)
+            latest = stamp;
+    }
+    if (latest === 0) {
+        latest = parseDate(job.started_at)?.getTime() ?? 0;
+    }
+    return latest;
+}
 function hasActiveLockForJob(locks, jobId) {
     return locks.some((lock) => lock.job_id === jobId && isJobLockActive(lock));
 }
@@ -712,6 +739,66 @@ function reconcileRecoveryState(queue, table, now, recoveryMode, buf) {
     }
     return recovered;
 }
+/**
+ * Heartbeat watchdog: move any `running` job whose worker heartbeat has gone
+ * stale into `unknown_recovery` and release its resource locks. Unlike lease
+ * recovery (which only fires on owner change / lease expiry), this catches the
+ * common D3 failure where a worker dies — or never existed — while the job's
+ * owner keeps holding a valid lease, leaving the job stuck `running` forever.
+ *
+ * Missing-lock jobs are intentionally left to `reconcileRecoveryState`, which
+ * runs first; this pass only inspects jobs that still hold active locks.
+ */
+function reapStaleRunningJobs(queue, table, now, staleMs, buf) {
+    if (staleMs <= 0)
+        return [];
+    const reaped = [];
+    for (const job of queue.jobs) {
+        if (job.status !== "running")
+            continue;
+        const activeLocks = table.locks.filter((lock) => lock.job_id === job.job_id && lock.status === "active");
+        if (activeLocks.length === 0)
+            continue;
+        const lastBeat = latestHeartbeatMs(job, activeLocks);
+        if (lastBeat === 0)
+            continue;
+        const ageMs = now.getTime() - lastBeat;
+        if (ageMs <= staleMs)
+            continue;
+        const previousStatus = job.status;
+        job.status = "unknown_recovery";
+        job.reason_code = "heartbeat_stale";
+        job.error = `Running job heartbeat is stale (${Math.round(ageMs / 1000)}s since last heartbeat, threshold ${Math.round(staleMs / 1000)}s); worker presumed dead.`;
+        job.next_attempt_at = undefined;
+        releaseLocksForRecoveredJob(table, job.job_id, "heartbeat_stale", now);
+        reaped.push(job.job_id);
+        buf.status.push({
+            event_type: "SCHEDULER_WATCHDOG",
+            status: "blocked",
+            summary: `Job ${job.job_id} reaped by watchdog (heartbeat_stale, ${Math.round(ageMs / 1000)}s)`,
+            payload: {
+                job_id: job.job_id,
+                from_status: previousStatus,
+                reason_code: "heartbeat_stale",
+                stale_ms: ageMs,
+                threshold_ms: staleMs,
+            },
+        });
+        buf.ledger.push({
+            tool: "scheduler_watchdog",
+            category: "regression",
+            message: `Watchdog reaped stale running job ${job.job_id} (heartbeat_stale)`,
+            artifacts: ["agent-state/job-queue.json", "agent-state/job-locks.json"],
+            metadata: {
+                job_id: job.job_id,
+                reason_code: "heartbeat_stale",
+                stale_ms: ageMs,
+                threshold_ms: staleMs,
+            },
+        });
+    }
+    return reaped;
+}
 export async function enqueueJob(input) {
     const buf = newEventBuffer();
     const result = await withFileLock(SCHEDULER_LOCK_REL, async () => {
@@ -923,6 +1010,7 @@ export async function dispatchJobs(input = {}) {
                     running_jobs: queue.jobs.filter((job) => job.status === "running").length,
                     started_jobs: 0,
                     recovered_jobs: 0,
+                    reaped_jobs: 0,
                 },
             };
         }
@@ -933,7 +1021,13 @@ export async function dispatchJobs(input = {}) {
             statusEvents: readStatusEvents(500),
         };
         const recoveredJobs = reconcileRecoveryState(queue, table, now, leaseResult.recovery_mode, buf);
-        heartbeatRunningLocks(table, leaseResult.lease.lease_id, now);
+        // Heartbeat watchdog: reap running jobs whose worker heartbeat is stale.
+        // NOTE: dispatch deliberately does NOT re-stamp running-job heartbeats here.
+        // Only a live worker (heartbeatJob) or a fresh start proves liveness; if the
+        // dispatcher renewed heartbeats it would mask worker death (root cause of D3).
+        const staleMs = resolveStaleMs(input.heartbeat_stale_seconds);
+        const reapedJobIds = reapStaleRunningJobs(queue, table, now, staleMs, buf);
+        const reapedJobs = reapedJobIds.length;
         for (const job of queue.jobs) {
             if (TERMINAL_STATUSES.has(job.status))
                 continue;
@@ -990,11 +1084,12 @@ export async function dispatchJobs(input = {}) {
             running_jobs: queue.jobs.filter((job) => job.status === "running").length,
             started_jobs: startedJobs,
             recovered_jobs: recoveredJobs,
+            reaped_jobs: reapedJobs,
         };
         buf.status.push({
             event_type: "SCHEDULER_TICK",
             status: "pass",
-            summary: `Dispatch started=${summary.started_jobs} ready=${summary.ready_jobs} running=${summary.running_jobs} recovered=${recoveredJobs}`,
+            summary: `Dispatch started=${summary.started_jobs} ready=${summary.ready_jobs} running=${summary.running_jobs} recovered=${recoveredJobs} reaped=${reapedJobs}`,
             payload: {
                 owner,
                 lease_acquired: true,
@@ -1290,4 +1385,109 @@ export async function completeJob(input) {
     await flushTransitionEvents(buf);
     return result;
 }
+/**
+ * Prove liveness for a running job. A live in-process worker calls this
+ * periodically while executing a job body so the heartbeat watchdog does not
+ * reap it. Advances the job's active-lock heartbeats and renews the owner
+ * lease. This is the ONLY path (besides a fresh start) that advances a running
+ * job's heartbeat — the dispatcher deliberately does not, so a missing
+ * heartbeat reliably signals a dead worker.
+ */
+export async function heartbeatJob(input) {
+    return withFileLock(SCHEDULER_LOCK_REL, async () => {
+        const owner = deriveOwner(input.owner);
+        const now = parseDate(input.now_iso) ?? new Date();
+        const leaseTtl = typeof input.lease_ttl_seconds === "number" && input.lease_ttl_seconds > 0
+            ? Math.floor(input.lease_ttl_seconds)
+            : defaultLeaseTtlSeconds();
+        const leaseResult = ensureLeaseForOwner(owner, now, leaseTtl);
+        if (!leaseResult.acquired) {
+            return {
+                ok: false,
+                queue_path: getJobQueuePath(),
+                lock_path: getJobLockTablePath(),
+                error: `Owner ${owner} does not hold an active scheduler lease.`,
+            };
+        }
+        const queue = readJobQueue();
+        const table = readJobLockTable();
+        const job = queue.jobs.find((row) => row.job_id === input.job_id);
+        if (!job) {
+            return {
+                ok: false,
+                queue_path: getJobQueuePath(),
+                lock_path: getJobLockTablePath(),
+                error: `Unknown job_id: ${input.job_id}`,
+            };
+        }
+        if (job.status !== "running") {
+            return {
+                ok: false,
+                queue_path: getJobQueuePath(),
+                lock_path: getJobLockTablePath(),
+                error: `Job ${input.job_id} is ${job.status}; only running jobs can be heartbeated.`,
+            };
+        }
+        const activeLocks = table.locks.filter((lock) => lock.job_id === input.job_id && lock.status === "active");
+        if (activeLocks.length === 0) {
+            return {
+                ok: false,
+                queue_path: getJobQueuePath(),
+                lock_path: getJobLockTablePath(),
+                error: `Job ${input.job_id} has no active resource locks to heartbeat.`,
+            };
+        }
+        const beatAt = nowIso(now);
+        for (const lock of activeLocks) {
+            lock.heartbeat_at = beatAt;
+            lock.lease_id = leaseResult.lease.lease_id;
+        }
+        await persistSchedulerState({
+            queue,
+            locks: table,
+            lease: leaseResult.lease,
+        });
+        return {
+            ok: true,
+            queue_path: getJobQueuePath(),
+            lock_path: getJobLockTablePath(),
+            heartbeat_at: beatAt,
+            resources: activeLocks.map((lock) => lock.resource),
+        };
+    });
+}
+/**
+ * Standalone heartbeat-watchdog tick: reap stale running jobs without planning
+ * or starting anything. Takes its own scheduler lock. Useful for a dedicated
+ * watchdog cadence separate from dispatch. Does not require lease ownership —
+ * reaping a dead worker's job must not depend on holding the lease.
+ */
+export async function reapStaleRunningJobsTick(input = {}) {
+    const buf = newEventBuffer();
+    const result = await withFileLock(SCHEDULER_LOCK_REL, async () => {
+        const now = parseDate(input.now_iso) ?? new Date();
+        const staleMs = resolveStaleMs(input.heartbeat_stale_seconds);
+        const queue = readJobQueue();
+        const table = readJobLockTable();
+        const reapedJobIds = reapStaleRunningJobs(queue, table, now, staleMs, buf);
+        if (reapedJobIds.length > 0) {
+            await persistSchedulerState({
+                queue,
+                locks: table,
+                lease: readSchedulerLease(),
+            });
+        }
+        return {
+            ok: true,
+            queue_path: getJobQueuePath(),
+            lock_path: getJobLockTablePath(),
+            queue,
+            locks: table,
+            reaped_jobs: reapedJobIds.length,
+            reaped_job_ids: reapedJobIds,
+        };
+    });
+    await flushTransitionEvents(buf);
+    return result;
+}
 //# sourceMappingURL=job-scheduler.js.map

package/dist/job-worker.d.ts

@@ -0,0 +1,87 @@
+/**
+ * In-process job worker (WS-D).
+ *
+ * The scheduler (`job-scheduler.ts`) is a pure planner: it moves jobs to
+ * `running` and grabs collision-free resource locks, but it never executes a
+ * job body nor calls `completeJob`. Before this worker existed, that left every
+ * dispatched job stuck at `running` forever (defect D3).
+ *
+ * This module closes the loop:
+ *   1. dispatch runnable jobs (which also runs the heartbeat watchdog),
+ *   2. execute the handler registered for each newly-running job's `kind`,
+ *      heartbeating throughout so the watchdog does not reap a live job,
+ *   3. finalize each job via `completeJob` (success → done, throw/fail → retry
+ *      or terminal failure).
+ *
+ * Every scheduler call takes its own file lock; the worker never holds a lock
+ * across a handler invocation, so a slow or hung handler cannot wedge the
+ * scheduler for other owners.
+ */
+import { readSchedulerLease, type JobRecord } from "./job-scheduler.js";
+export interface JobHandlerContext {
+    job: JobRecord;
+    owner: string;
+}
+export interface JobHandlerResult {
+    success: boolean;
+    evidence_ref?: string;
+    error?: string;
+}
+export type JobHandler = (context: JobHandlerContext) => Promise<JobHandlerResult> | JobHandlerResult;
+export declare function registerJobHandler(kind: string, handler: JobHandler): void;
+export declare function unregisterJobHandler(kind: string): boolean;
+export declare function clearJobHandlers(): void;
+export declare function listJobHandlerKinds(): string[];
+export declare function hasJobHandler(kind: string): boolean;
+export interface RunJobWorkerInput {
+    owner?: string;
+    /** Deterministic clock override; threaded through every scheduler call. */
+    now_iso?: string;
+    lease_ttl_seconds?: number;
+    /** Max jobs to execute this tick (default: unlimited). */
+    max_jobs?: number;
+    /**
+     * Heartbeat cadence while a handler runs. Set to 0 to disable the interval
+     * timer (handlers still get a heartbeat when picked up). Default 15s.
+     */
+    heartbeat_ms?: number;
+    /** Watchdog staleness window forwarded to the dispatch tick. */
+    heartbeat_stale_seconds?: number;
+}
+export type WorkerJobStatus = "done" | "blocked" | "failed_terminal" | "failed" | "errored" | "unknown";
+export interface WorkerJobOutcome {
+    job_id: string;
+    kind: string;
+    handler_success: boolean;
+    final_status: WorkerJobStatus;
+    evidence_ref?: string;
+    error?: string;
+}
+export interface WorkerSkippedJob {
+    job_id: string;
+    kind: string;
+    reason: "no_handler" | "max_jobs";
+}
+export interface RunJobWorkerResult {
+    owner: string;
+    lease_acquired: boolean;
+    dispatch: {
+        started_jobs: number;
+        running_jobs: number;
+        reaped_jobs: number;
+    };
+    executed: WorkerJobOutcome[];
+    skipped: WorkerSkippedJob[];
+}
+/**
+ * Run one worker tick: dispatch, then execute handlers for running jobs.
+ * Idempotent and safe to call on a timer or on demand.
+ */
+export declare function runJobWorkerOnce(input?: RunJobWorkerInput): Promise<RunJobWorkerResult>;
+/**
+ * Convenience: report whether any running job currently lacks a handler.
+ * Useful for diagnostics ("why is running=1 not draining?").
+ */
+export declare function findUnhandledRunningKinds(): string[];
+export { readSchedulerLease };
+//# sourceMappingURL=job-worker.d.ts.map

package/dist/job-worker.js

@@ -0,0 +1,182 @@
+/**
+ * In-process job worker (WS-D).
+ *
+ * The scheduler (`job-scheduler.ts`) is a pure planner: it moves jobs to
+ * `running` and grabs collision-free resource locks, but it never executes a
+ * job body nor calls `completeJob`. Before this worker existed, that left every
+ * dispatched job stuck at `running` forever (defect D3).
+ *
+ * This module closes the loop:
+ *   1. dispatch runnable jobs (which also runs the heartbeat watchdog),
+ *   2. execute the handler registered for each newly-running job's `kind`,
+ *      heartbeating throughout so the watchdog does not reap a live job,
+ *   3. finalize each job via `completeJob` (success → done, throw/fail → retry
+ *      or terminal failure).
+ *
+ * Every scheduler call takes its own file lock; the worker never holds a lock
+ * across a handler invocation, so a slow or hung handler cannot wedge the
+ * scheduler for other owners.
+ */
+import { completeJob, dispatchJobs, heartbeatJob, readJobQueue, readSchedulerLease, } from "./job-scheduler.js";
+import { resolveWorkspaceRoot } from "./helpers.js";
+const handlers = new Map();
+export function registerJobHandler(kind, handler) {
+    const key = kind.trim();
+    if (key.length === 0) {
+        throw new Error("registerJobHandler: kind must be a non-empty string");
+    }
+    handlers.set(key, handler);
+}
+export function unregisterJobHandler(kind) {
+    return handlers.delete(kind.trim());
+}
+export function clearJobHandlers() {
+    handlers.clear();
+    builtInHandlersRegistered = false;
+}
+export function listJobHandlerKinds() {
+    return Array.from(handlers.keys()).sort();
+}
+export function hasJobHandler(kind) {
+    return handlers.has(kind.trim());
+}
+const DEFAULT_HEARTBEAT_MS = 15_000;
+let builtInHandlersRegistered = false;
+function deriveOwner(owner) {
+    const trimmed = owner?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : "capability-ops";
+}
+function errorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+/**
+ * Run one worker tick: dispatch, then execute handlers for running jobs.
+ * Idempotent and safe to call on a timer or on demand.
+ */
+export async function runJobWorkerOnce(input = {}) {
+    await ensureBuiltInHandlers();
+    const owner = deriveOwner(input.owner);
+    const heartbeatMs = typeof input.heartbeat_ms === "number" && input.heartbeat_ms >= 0
+        ? Math.floor(input.heartbeat_ms)
+        : DEFAULT_HEARTBEAT_MS;
+    const dispatch = await dispatchJobs({
+        owner,
+        now_iso: input.now_iso,
+        lease_ttl_seconds: input.lease_ttl_seconds,
+        heartbeat_stale_seconds: input.heartbeat_stale_seconds,
+    });
+    const executed = [];
+    const skipped = [];
+    if (!dispatch.lease_acquired) {
+        return {
+            owner,
+            lease_acquired: false,
+            dispatch: {
+                started_jobs: dispatch.summary.started_jobs,
+                running_jobs: dispatch.summary.running_jobs,
+                reaped_jobs: dispatch.summary.reaped_jobs,
+            },
+            executed,
+            skipped,
+        };
+    }
+    const queue = readJobQueue();
+    const runningJobs = queue.jobs.filter((job) => job.status === "running");
+    const maxJobs = typeof input.max_jobs === "number" && input.max_jobs > 0
+        ? Math.floor(input.max_jobs)
+        : Number.POSITIVE_INFINITY;
+    let executedCount = 0;
+    for (const job of runningJobs) {
+        const handler = handlers.get(job.kind);
+        if (!handler) {
+            skipped.push({ job_id: job.job_id, kind: job.kind, reason: "no_handler" });
+            continue;
+        }
+        if (executedCount >= maxJobs) {
+            skipped.push({ job_id: job.job_id, kind: job.kind, reason: "max_jobs" });
+            continue;
+        }
+        executedCount += 1;
+        // Prove liveness immediately, then keep beating while the handler runs.
+        await heartbeatJob({ job_id: job.job_id, owner, now_iso: input.now_iso });
+        let heartbeatTimer;
+        if (heartbeatMs > 0 && input.now_iso === undefined) {
+            heartbeatTimer = setInterval(() => {
+                void heartbeatJob({ job_id: job.job_id, owner }).catch(() => {
+                    // Best-effort liveness signal; the watchdog is the backstop.
+                });
+            }, heartbeatMs);
+            // Never keep the event loop alive purely for a heartbeat.
+            heartbeatTimer.unref?.();
+        }
+        let handlerResult;
+        try {
+            handlerResult = await handler({ job, owner });
+        }
+        catch (err) {
+            handlerResult = { success: false, error: errorMessage(err) };
+        }
+        finally {
+            if (heartbeatTimer)
+                clearInterval(heartbeatTimer);
+        }
+        const completion = await completeJob({
+            job_id: job.job_id,
+            owner,
+            success: handlerResult.success,
+            evidence_ref: handlerResult.evidence_ref,
+            error: handlerResult.error,
+            now_iso: input.now_iso,
+        });
+        const finalStatus = completion.ok
+            ? completion.status ?? "unknown"
+            : "errored";
+        executed.push({
+            job_id: job.job_id,
+            kind: job.kind,
+            handler_success: handlerResult.success,
+            final_status: finalStatus,
+            evidence_ref: handlerResult.evidence_ref,
+            error: completion.ok ? handlerResult.error : completion.error ?? handlerResult.error,
+        });
+    }
+    return {
+        owner,
+        lease_acquired: true,
+        dispatch: {
+            started_jobs: dispatch.summary.started_jobs,
+            running_jobs: dispatch.summary.running_jobs,
+            reaped_jobs: dispatch.summary.reaped_jobs,
+        },
+        executed,
+        skipped,
+    };
+}
+async function ensureBuiltInHandlers() {
+    if (builtInHandlersRegistered)
+        return;
+    builtInHandlersRegistered = true;
+    if (!handlers.has("playbook.reflect")) {
+        const { createPlaybookReflectJobHandler } = await import("./playbook-llm-reflector.js");
+        handlers.set("playbook.reflect", createPlaybookReflectJobHandler({ workspaceRoot: resolveWorkspaceRoot() }));
+    }
+}
+/**
+ * Convenience: report whether any running job currently lacks a handler.
+ * Useful for diagnostics ("why is running=1 not draining?").
+ */
+export function findUnhandledRunningKinds() {
+    const queue = readJobQueue();
+    const kinds = new Set();
+    for (const job of queue.jobs) {
+        if (job.status === "running" && !handlers.has(job.kind)) {
+            kinds.add(job.kind);
+        }
+    }
+    return Array.from(kinds).sort();
+}
+// Re-export so callers can inspect lease state without importing the scheduler.
+export { readSchedulerLease };
+//# sourceMappingURL=job-worker.js.map

package/dist/local-model-policy.d.ts

@@ -1,4 +1,4 @@
-import type { AceContextTier } from "./ace-context.js";
+import { type AceContextTier } from "./ace-context.js";
 import { type RuntimeModelClass } from "./runtime-profile.js";
 export interface LocalModelPolicyInput {
     provider: string;
@@ -19,9 +19,15 @@ export declare function resolveLocalModelClass(input: {
     provider: string;
     model: string;
     requested_model_class?: RuntimeModelClass;
+    /**
+     * Class derived from a connect-time capability measurement (E10). Consulted
+     * ahead of the name regex so classing rests on observed behavior/metadata,
+     * not brittle string patterns. See measured-classing.ts.
+     */
+    measured_model_class?: RuntimeModelClass;
 }): RuntimeModelClass;
 export declare function tierForModelClass(role: string, modelClass: RuntimeModelClass, requestedTier?: "auto" | AceContextTier): AceContextTier;
 export declare function defaultTurnsForPolicy(role: string, policy: LocalModelExecutionPolicy): number;
-export declare function defaultToolScopeForPolicy(role: string, policy: LocalModelExecutionPolicy): string[] | undefined;
+export declare function defaultToolScopeForPolicy(role: string, policy: LocalModelExecutionPolicy): string[];
 export declare function resolveLocalModelExecutionPolicy(input: LocalModelPolicyInput): LocalModelExecutionPolicy;
 //# sourceMappingURL=local-model-policy.d.ts.map

package/dist/local-model-policy.js

@@ -1,3 +1,4 @@
+import { ROLE_TOOL_DEFAULTS } from "./ace-context.js";
 import { DEFAULT_SURGICAL_READ_BUDGETS, } from "./runtime-profile.js";
 const FRONTIER_MODEL_PATTERN = /\b(70b|72b|90b|405b|claude|gpt-|codex|gemini|o[1345])\b/i;
 const SMALL_LOCAL_MODEL_PATTERN = /\b(1\.5b|2b|3b|4b|5b|6b|7b|8b|mini|small|phi|tiny|qwen2\.5-coder|llama-3\.2-3b)\b/i;
@@ -14,6 +15,8 @@ function isMutationTask(task, role) {
 export function resolveLocalModelClass(input) {
     if (input.requested_model_class)
         return input.requested_model_class;
+    if (input.measured_model_class)
+        return input.measured_model_class;
     const provider = normalize(input.provider);
     const model = normalize(input.model);
     const joined = `${provider} ${model}`;
@@ -44,25 +47,36 @@ export function defaultTurnsForPolicy(role, policy) {
         return 6;
     return policy.model_class === "small_local" ? 4 : 4;
 }
+const STRUCTURAL_TOOL_SCOPE = [
+    "outline_file",
+    "astgrep_query",
+    "astgrep_locate",
+    "read_file_lines",
+    "compile_structural_edit",
+    "preview_structural_edit",
+    "astgrep_rewrite",
+    "safe_edit_file",
+    "write_workspace_file",
+    "run_tests",
+    "git_diff",
+    "git_status",
+    "execute_gates",
+];
+// Returns the default tool scope for a Hermes-bound run; never returns undefined or [].
+// For small_local mutation coders/builder: structural-edit scope.
+// For all other (role, policy) combinations: the role's default scope from ROLE_TOOL_DEFAULTS.
+// For roles absent from the map: orchestrator defaults minus mutation tools.
 export function defaultToolScopeForPolicy(role, policy) {
-    if (!policy.structural_tools_required || !(role === "coders" || role === "builder")) {
-        return undefined;
+    if (policy.structural_tools_required && (role === "coders" || role === "builder")) {
+        return STRUCTURAL_TOOL_SCOPE;
     }
-    return [
-        "outline_file",
-        "astgrep_query",
-        "astgrep_locate",
-        "read_file_lines",
-        "compile_structural_edit",
-        "preview_structural_edit",
-        "astgrep_rewrite",
-        "safe_edit_file",
-        "write_workspace_file",
-        "run_tests",
-        "git_diff",
-        "git_status",
-        "execute_gates",
-    ];
+    const normalized = role.trim().toLowerCase();
+    const roleDefaults = ROLE_TOOL_DEFAULTS[normalized];
+    if (roleDefaults && roleDefaults.length > 0) {
+        return roleDefaults;
+    }
+    // Unknown role: orchestrator defaults minus mutation tools
+    return (ROLE_TOOL_DEFAULTS["orchestrator"] ?? []).filter((t) => !["run_orchestrator", "enqueue_job", "dispatch_jobs"].includes(t));
 }
 export function resolveLocalModelExecutionPolicy(input) {
     const role = normalize(input.role);

package/dist/local-model-runtime.d.ts

@@ -31,6 +31,12 @@ export interface RunLocalModelTaskOptions {
     clients?: ModelBridgeClients;
     hermesExecutor?: HermesLocalExecutor;
     hermesLaunchProfile?: HermesLaunchProfile;
+    expectedArtifacts?: {
+        path: string;
+        required?: boolean;
+    }[];
+    requiredEvidenceRefs?: string[];
+    timeoutMs?: number;
 }
 export interface RunLocalModelTaskResult {
     runtime: LocalModelRuntimeConfig;