@voybio/ace-swarm 2.4.9 → 2.4.10

package/dist/tools-goal.js

@@ -1,15 +1,24 @@
 /**
  * ACE Goal Engine tool registrations (WS-F).
  *
- * These let a premium host delegate a long-running objective to ACE and poll
- * it. `start_goal`/`resume_goal` never block the MCP server for the life of the
- * goal: they compile/prepare, then hand execution to a detached `ace goal run`
- * child and return immediately. The host polls `get_goal_status`.
+ * Engine goals delegate to the existing detached runner. Host goals return
+ * assignments to the connected participant and never invoke that executor.
  */
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
-import { getGoalStatus, listGoals, startGoal, stopGoal, } from "./goal-engine.js";
+import { getGoalStatus, listGoals, startGoal, stopGoal, resumeGoal, beginStep, completeStep, } from "./goal-engine.js";
+import { hostRefusal } from './host-goal-engine.js';
+import { resolveCurrentWork } from './ace-autonomy.js';
+import { resolveWorkspaceRoot } from './helpers.js';
+import { bindHostWork, hostAgent } from './host-work-context.js';
+import { getCompactGoalStatus } from './host-goal-status.js';
+import { commandPolicySchema, withMcpCommandProgress } from './mcp-command-progress.js';
+function hostResult(result) {
+    return { isError: !!result.isError, structuredContent: { ...result }, content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+}
+const artifactSchema = z.object({ path: z.string().min(1), required: z.boolean().optional(), transient: z.boolean().optional() });
+const hostStepSchema = z.object({ id: z.string().optional(), task: z.string().min(1), role: z.string().optional(), depends_on: z.array(z.string()).optional(), expected_artifacts: z.array(z.union([z.string().min(1), artifactSchema])).optional(), required_evidence_refs: z.array(z.string()).optional(), required_observation: z.enum(['action', 'command_pass']).optional() });
 function asJsonBlock(value) {
     return `\`\`\`json\n${JSON.stringify(value, null, 2)}\n\`\`\``;
 }
@@ -29,14 +38,34 @@ function spawnDetachedRunner(goalId, verb) {
     }
 }
 export function registerGoalTools(server) {
-    server.tool("start_goal", "Compile and launch a long-running autonomous goal (ACE plans it, executes step-by-step under evidence-gated completion, and can never declare success by prose). Returns immediately; poll with get_goal_status.", {
+    server.tool("start_goal", "Start a goal with an explicit executor choice: host accepts your steps and returns the first assignment; engine plans and runs through ACE's autonomous executor. Productive work has no default duration, tick, or total replan limit.", {
+        executor: z.enum(['engine', 'host']),
+        agent: z.string().min(1).optional(),
+        steps: z.array(hostStepSchema).min(1).optional(),
+        verify: z.array(z.union([z.string().min(1), commandPolicySchema.extend({ cmd: z.string().min(1) })])).optional(),
+        todo_ids: z.record(z.string(), z.string()).optional(),
         objective: z.string().min(1).describe("What the goal should accomplish"),
-        budget_hours: z.number().positive().max(24).optional().describe("Wall-clock budget (default 4h)"),
-        max_replans: z.number().int().min(0).max(20).optional().describe("Max plan-level replans (default 3)"),
+        budget_hours: z.number().positive().optional().describe("Explicit operator deadline measured from the original start; omit for unlimited work."),
+        max_replans: z.number().int().min(0).optional().describe("Explicit operator cap on corrections; omitted by default. Repeated unchanged failures are detected separately."),
         plan_only: z.boolean().optional().describe("Compile + validate the plan but do not execute"),
         detach: z.boolean().optional().describe("Run in a detached background child (default true when not plan_only)"),
-    }, async ({ objective, budget_hours, max_replans, plan_only, detach }) => {
-        const started = await startGoal(objective, { budget_hours, max_replans, plan_only });
+    }, async ({ objective, budget_hours, max_replans, plan_only, detach, executor, agent, steps, verify, todo_ids }, extra) => {
+        const participant = hostAgent(agent, extra.sessionId);
+        let started;
+        try {
+            if (budget_hours !== undefined && !Number.isFinite(budget_hours * 3600000))
+                throw new Error('budget_hours must be a finite positive allowance.');
+            started = await startGoal(objective, { budget_hours, max_replans, plan_only, executor, agent: participant, session_id: extra.sessionId, steps, verify_commands: verify, todo_ids });
+        }
+        catch (error) {
+            if (executor !== 'host')
+                throw error;
+            return hostResult(hostRefusal(resolveWorkspaceRoot(), 'host_plan_invalid', error instanceof Error ? error.message : String(error)));
+        }
+        if (executor === 'host') {
+            bindHostWork({ agent: participant, goal_id: started.goal.goal_id, step_id: started.assignment?.step_id, attempt: started.assignment?.attempt }, extra.sessionId);
+            return { isError: !started.ok, structuredContent: { ...started }, content: [{ type: 'text', text: JSON.stringify(started, null, 2) }] };
+        }
         let runnerPid;
         if (started.ok && !plan_only && detach !== false) {
             runnerPid = spawnDetachedRunner(started.goal.goal_id, "run");
@@ -59,25 +88,75 @@ export function registerGoalTools(server) {
             ],
         };
     });
-    server.tool("get_goal_status", "Get a goal's status (tick count, current step, last heartbeat, escalations, plan status), or list all goals when no goal_id is given.", {
+    server.tool('next_step', 'Receive or resume your current assignment from a host goal. Never executes work itself.', {
+        goal_id: z.string().optional(), step_id: z.string().optional(), agent: z.string().min(1).optional(),
+    }, async ({ goal_id, step_id, agent }, extra) => {
+        const participant = hostAgent(agent, extra.sessionId);
+        const work = resolveCurrentWork({ goal_id, agent: participant });
+        const id = goal_id ?? work.objective?.goal_id ?? (work.idle_learning?.includes('learning step available') ? 'G-learning' : undefined);
+        if (!id)
+            return hostResult({ ...hostRefusal(resolveWorkspaceRoot(), work.state === 'ambiguous' ? 'ambiguous_goal' : 'no_active_goal', 'Select a host goal_id, or create one with start_goal executor:host.'), candidates: work.other_goals });
+        try {
+            const result = await beginStep(id, { step_id, agent: participant, session_id: extra.sessionId });
+            if (result.assignment)
+                bindHostWork({ agent: participant, goal_id: id, step_id: result.assignment.step_id, attempt: result.assignment.attempt }, extra.sessionId);
+            return hostResult(result);
+        }
+        catch (error) {
+            return hostResult(hostRefusal(resolveWorkspaceRoot(), 'next_step_failed', error instanceof Error ? error.message : String(error), id));
+        }
+    });
+    server.tool('complete_step', 'Record this attempt once, update linked state and optionally receive the next assignment. Identical retries return the original response.', {
+        goal_id: z.string(), step_id: z.string(), attempt: z.number().int().positive(), agent: z.string().min(1).optional(), continue: z.boolean().optional(),
+        outcome: z.object({ status: z.enum(['done', 'blocked', 'failed']), summary: z.string().min(1).max(2000), waiting_on: z.string().optional(), artifacts: z.array(z.string()).optional(),
+            feedback: z.array(z.object({ id: z.string(), helpful: z.boolean() })).optional(),
+            learned: z.object({
+                lessons: z.array(z.object({ op: z.enum(['add', 'edit', 'retire']), bullet_id: z.string().optional(), section: z.enum(['strategies', 'tool_usage', 'failure_modes', 'verification', 'env_facts']), content: z.string().max(400), scope: z.object({ role: z.string().optional(), paths: z.array(z.string()).optional(), task_tags: z.array(z.string()).optional(), failure_signature: z.string().optional() }), episodes: z.array(z.string()).min(1), retired_episodes: z.array(z.string()).optional() })).max(3).optional(),
+                skill: z.object({ op: z.enum(['add', 'edit']), slug: z.string(), skill_md: z.string(), references: z.record(z.string(), z.string()).optional(), episodes: z.array(z.string()).min(3), retired_episodes: z.array(z.string()).optional() }).optional(),
+                instruction: z.object({ role: z.string(), text: z.string().max(1200), episodes: z.array(z.string()).min(1) }).optional()
+            }).optional(),
+            requirement_updates: z.array(z.object({ step_id: z.string(), reason: z.string().min(1), task: z.string().min(1).optional(), expected_artifacts: z.array(artifactSchema).optional(), required_evidence_refs: z.array(z.string()).optional() })).optional(),
+            evidence: z.array(z.object({ ref: z.string(), kind: z.enum(['command', 'artifact', 'diff', 'note']), detail: z.string().optional() })).optional(),
+            follow_ups: z.array(z.object({ task: z.string().min(1), role: z.string().optional(), depends_on: z.array(z.string()).optional() })).optional() }),
+    }, async ({ goal_id, step_id, attempt, agent, outcome, continue: proceed }, extra) => {
+        const participant = hostAgent(agent, extra.sessionId);
+        try {
+            const result = await withMcpCommandProgress(extra, 'complete_step acceptance', () => completeStep(goal_id, step_id, outcome, { agent: participant, attempt, continue: proceed }));
+            if (result.ok)
+                bindHostWork({ agent: participant, goal_id, step_id: result.assignment?.step_id, attempt: result.assignment?.attempt }, extra.sessionId);
+            return hostResult(result);
+        }
+        catch (error) {
+            return hostResult(hostRefusal(resolveWorkspaceRoot(), 'completion_failed', error instanceof Error ? error.message : String(error), goal_id));
+        }
+    });
+    server.tool("get_goal_status", "Get goal status. view:compact gives bounded verification, blockers and executable next actions; view:full (default) retains the complete plan and evidence. Omit goal_id to list goals.", {
         goal_id: z.string().optional().describe("Goal id; omit to list all goals"),
-    }, async ({ goal_id }) => {
+        view: z.enum(['compact', 'full']).optional(),
+        agent: z.string().min(1).optional(),
+    }, async ({ goal_id, view: mode, agent }, extra) => {
         if (!goal_id) {
             return {
                 content: [{ type: "text", text: asJsonBlock({ goals: listGoals() }) }],
             };
         }
+        if (mode === 'compact') {
+            const compact = getCompactGoalStatus(goal_id, hostAgent(agent, extra.sessionId));
+            if (!compact)
+                return hostResult(hostRefusal(resolveWorkspaceRoot(), 'goal_not_found', `Unknown goal: ${goal_id}`, goal_id));
+            return { structuredContent: { ...compact }, content: [{ type: 'text', text: JSON.stringify(compact) }] };
+        }
         const view = getGoalStatus(goal_id);
         if (!view) {
             return { content: [{ type: "text", text: `❌ Unknown goal: ${goal_id}` }] };
         }
-        return { content: [{ type: "text", text: asJsonBlock(view) }] };
+        return { structuredContent: { ...view }, content: [{ type: "text", text: asJsonBlock(view) }] };
     });
     server.tool("stop_goal", "Request that a running goal stop at its next tick boundary.", { goal_id: z.string().describe("Goal id to stop") }, async ({ goal_id }) => {
         try {
-            const goal = stopGoal(goal_id);
+            const goal = await stopGoal(goal_id);
             return {
-                content: [{ type: "text", text: `🛑 Stop requested for ${goal.goal_id} (status ${goal.status}).` }],
+                content: [{ type: "text", text: `🛑 Stop requested for ${goal.goal_id} (status ${goal.status}).\n` }],
             };
         }
         catch (err) {
@@ -86,11 +165,35 @@ export function registerGoalTools(server) {
             };
         }
     });
-    server.tool("resume_goal", "Resume a blocked/stopped goal: reset any step left running mid-crash and continue execution in a detached runner.", { goal_id: z.string().describe("Goal id to resume") }, async ({ goal_id }) => {
+    server.tool("resume_goal", "Resume a goal. budget_hours/max_replans increase explicit total allowances only with operator approval; never execute a status proposal automatically. Accepted work and original start time are preserved. Engine goals resume in the detached runner.", { goal_id: z.string().describe("Goal id to resume"),
+        budget_hours: z.number().positive().optional().describe('Operator-approved increase to an explicit total deadline from the original start.'),
+        max_replans: z.number().int().nonnegative().optional().describe('Operator-approved increase admitting retained pending follow-ups.') }, async ({ goal_id, budget_hours, max_replans }, extra) => {
         const view = getGoalStatus(goal_id);
         if (!view) {
             return { content: [{ type: "text", text: `❌ Unknown goal: ${goal_id}` }] };
         }
+        if (view.goal.executor === 'host') {
+            try {
+                const resumed = await resumeGoal(goal_id, {}, { budget_hours, max_replans });
+                const status = getCompactGoalStatus(goal_id, hostAgent(undefined, extra.sessionId));
+                const result = { ...resumed, options: status?.options, operator_proposal: status?.operator_proposal, waiting_on: status?.waiting_on, now: status?.now };
+                return { structuredContent: result, content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            catch (error) {
+                return hostResult(hostRefusal(resolveWorkspaceRoot(), 'budget_recovery_rejected', error instanceof Error ? error.message : String(error), goal_id));
+            }
+        }
+        if (budget_hours !== undefined || max_replans !== undefined) {
+            try {
+                const { recoverEngineGoalBudgets } = await import('./goal-engine.js');
+                await recoverEngineGoalBudgets(goal_id, { budget_hours, max_replans });
+            }
+            catch (error) {
+                const refusal = hostRefusal(resolveWorkspaceRoot(), 'budget_recovery_rejected', error instanceof Error ? error.message : String(error), goal_id);
+                refusal.options = [{ tool: 'get_goal_status', args: { goal_id, view: 'compact' }, why: 'Inspect the retained engine allowance and obtain operator approval for any sufficient increase.' }];
+                return hostResult(refusal);
+            }
+        }
         const runnerPid = spawnDetachedRunner(goal_id, "resume");
         return {
             content: [

package/dist/tools-handoff.js

@@ -9,9 +9,12 @@ import { ROLE_ENUM, HANDOFF_VALIDATION_MODE, HANDOFF_LIFECYCLE_STATUS_ENUM, } fr
 import { validateHandoffPayload, validateSwarmHandoffPayload, lintHandoffPayload, } from "./schemas.js";
 import { acknowledgeHandoffSafe, getHandoffRegistryPath, readHandoffRegistry, registerHandoffSafe, } from "./handoff-registry.js";
 import { appendRunLedgerEntrySafe } from "./run-ledger.js";
-import { refreshKanbanArtifacts } from "./kanban.js";
+import { formatKanbanRefresh, refreshKanbanArtifacts } from "./kanban.js";
 import { readJobQueue, syncHandoffLifecycleJob } from "./job-scheduler.js";
 import { appendStatusEventSafe } from "./status-events.js";
+import { hostAgent, bindHostWork } from './host-work-context.js';
+import { GoalRepository } from './store/repositories/goal-repository.js';
+import { resolveWorkspaceRoot } from './helpers.js';
 function toSchedulerPriority(input) {
     if (input === "P0" || input === "P1" || input === "P2" || input === "P3") {
         return input;
@@ -61,6 +64,8 @@ async function recordHandoffSchedulerSyncEffects(record, sync) {
     }
 }
 export async function syncHandoffIntoScheduler(record, options = {}) {
+    if (record.step_ref)
+        return { ok: true, job_id: '', enqueued: false, enqueue_reason: 'Host step ownership follows the handoff; no engine dispatch.', dispatch_performed: false, reconciliation_required: false };
     const jobId = handoffSchedulerJobId(record.handoff_id);
     const enqueue = await syncHandoffLifecycleJob({
         now_iso: options.now_iso,
@@ -107,6 +112,7 @@ export async function backfillHandoffsIntoScheduler(options = {}) {
     const existing = new Set(readJobQueue().jobs.filter((job) => job.kind === "handoff.lifecycle")
         .map((job) => job.payload.handoff_id));
     const active = Object.values(registry.handoffs)
+        .filter(record => !record.step_ref)
         .filter((record) => record.status !== "completed" || existing.has(record.handoff_id))
         .sort((a, b) => Date.parse(a.created_at) - Date.parse(b.created_at));
     const result = {
@@ -161,11 +167,15 @@ export function registerHandoffTools(server) {
         })
             .optional()
             .describe("File:line pointers for context"),
-    }, async ({ from, to, title, task_type, priority, directive, acceptance_criteria, context_pointers, }) => {
+        step_ref: z.object({ goal_id: z.string(), step_id: z.string() }).optional(),
+        agent: z.string().optional().describe('Submitting host label for a linked step'),
+        recipient_agent: z.string().optional().describe('Host label receiving a linked step; defaults to the target role label'),
+    }, async ({ from, to, title, task_type, priority, directive, acceptance_criteria, context_pointers, step_ref, agent, recipient_agent, }, extra) => {
         const now = new Date();
         const dateStr = now.toISOString().slice(0, 10).replace(/-/g, "");
         const shortId = randomUUID().replace(/-/g, "").slice(0, 8);
         const handoff = {
+            ...(step_ref ? { step_ref, recipient_agent: recipient_agent ?? `ACE-${to.charAt(0).toUpperCase() + to.slice(1)}` } : {}),
             handoff_id: `HND-${dateStr}-${shortId}`,
             timestamp_utc: now.toISOString(),
             router: {
@@ -252,6 +262,9 @@ export function registerHandoffTools(server) {
             task_type: handoff.task.type,
             priority: handoff.task.priority,
             source_file: payloadPath,
+            step_ref,
+            actor: step_ref ? hostAgent(agent, extra.sessionId) : undefined,
+            ...(step_ref && recipient_agent ? { to: recipient_agent } : {}),
         });
         const runLedger = await appendRunLedgerEntrySafe({
             tool: "create_handoff",
@@ -271,6 +284,7 @@ export function registerHandoffTools(server) {
         const schedulerSync = await syncHandoffIntoScheduler(registry.record);
         const kanban = refreshKanbanArtifacts("tool:create_handoff");
         return {
+            structuredContent: { handoff_id: handoff.handoff_id, record: registry.record },
             content: [
                 {
                     type: "text",
@@ -290,7 +304,7 @@ export function registerHandoffTools(server) {
                             ? `Scheduler enqueue detail: ${schedulerSync.enqueue_reason}`
                             : "",
                         "",
-                        `Kanban updated: ${kanban.html_path}`,
+                        formatKanbanRefresh(kanban),
                         `Kanban counts: backlog=${kanban.counts.backlog}, blocked=${kanban.counts.blocked}, in_progress=${kanban.counts.in_progress}, gated=${kanban.counts.gated}, done=${kanban.counts.done}`,
                         "",
                         "```json",
@@ -411,14 +425,19 @@ export function registerHandoffTools(server) {
         handoff_id: z.string().describe("Handoff identifier"),
         status: HANDOFF_LIFECYCLE_STATUS_ENUM.describe("Lifecycle status"),
         note: z.string().optional().describe("Optional status note"),
-    }, async ({ handoff_id, status, note }) => {
+        agent: z.string().optional().describe('Recipient host label for a linked step'),
+    }, async ({ handoff_id, status, note, agent }, extra) => {
+        const linked = readHandoffRegistry().handoffs[handoff_id]?.step_ref;
         const ack = await acknowledgeHandoffSafe({
             handoff_id,
             status,
             note,
+            actor: linked ? hostAgent(agent, extra.sessionId) : undefined,
         });
         if (!ack.ok) {
             return {
+                ...(linked ? { isError: true } : {}),
+                structuredContent: { ...ack },
                 content: [
                     {
                         type: "text",
@@ -438,6 +457,10 @@ export function registerHandoffTools(server) {
                 ],
             };
         }
+        if (linked && ack.record) {
+            const step = new GoalRepository(resolveWorkspaceRoot()).getPlan(linked.goal_id)?.steps.find(s => s.step_id === linked.step_id);
+            bindHostWork({ agent: ack.record.to, goal_id: linked.goal_id, ...(status === 'accepted' ? { step_id: linked.step_id, attempt: step?.attempt } : {}) }, extra.sessionId);
+        }
         const runLedger = await appendRunLedgerEntrySafe({
             tool: "ack_handoff",
             category: status === "blocked" ? "regression" : "major_update",
@@ -455,6 +478,7 @@ export function registerHandoffTools(server) {
             : undefined;
         const kanban = refreshKanbanArtifacts("tool:ack_handoff");
         return {
+            structuredContent: { ...ack },
             content: [
                 {
                     type: "text",

package/dist/tools-lifecycle.js

@@ -190,7 +190,7 @@ export function registerLifecycleTools(server) {
                 {
                     type: "text",
                     text: [
-                        "# Kanban Updated",
+                        snapshot.refresh_scheduled ? "# Kanban refresh scheduled" : "# Kanban Updated",
                         "",
                         `JSON: ${snapshot.json_path}`,
                         `HTML: ${snapshot.html_path}`,

package/dist/tools-memory.d.ts

@@ -1,6 +1,3 @@
-/**
- * Memory tool registrations – context snapshots and recall.
- */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare function registerMemoryTools(server: McpServer): void;
 //# sourceMappingURL=tools-memory.d.ts.map

package/dist/tools-memory.js

@@ -1,3 +1,5 @@
+import { renderLearningTask } from './learning-input-context.js';
+import { readLearningPolicy } from './learning-policy.js';
 /**
  * Memory tool registrations – context snapshots and recall.
  */
@@ -8,7 +10,10 @@ import { isReadError } from "./shared.js";
 import { appendRunLedgerEntrySafe } from "./run-ledger.js";
 import { appendStatusEventSafe } from "./status-events.js";
 import { readRuntimeProfile } from "./runtime-profile.js";
-import { buildAceContinuityPacket, formatAceContinuityPacketMarkdown, normalizeContinuityPolicy, } from "./ace-autonomy.js";
+import { buildAceContinuityPacket, formatAceContinuityPacketMarkdown, normalizeContinuityPolicy, formatCurrentWork, readCurrentWorkContext, } from "./ace-autonomy.js";
+import { GoalRepository } from "./store/repositories/goal-repository.js";
+import { bindHostWork } from './host-work-context.js';
+import { formatStepTaskForBridge, collectUpstreamOutputs } from "./task-plan-context.js";
 import { openStore } from "./store/ace-packed-store.js";
 import { ProjectionManager } from "./store/materializers/projection-manager.js";
 import { ContextSnapshotRepository } from "./store/repositories/context-snapshot-repository.js";
@@ -89,6 +94,8 @@ export function registerMemoryTools(server) {
             if (!isReadError(indexRaw)) {
                 try {
                     index = JSON.parse(indexRaw);
+                    if (!Array.isArray(index.snapshots) || index.snapshots.some((s) => !s || typeof s.name !== "string" || typeof s.file !== "string" || typeof s.timestamp !== "string"))
+                        throw new Error("Invalid snapshot index");
                 }
                 catch {
                     /* keep default */
@@ -207,16 +214,43 @@ export function registerMemoryTools(server) {
             ],
         };
     });
-    server.tool("recall_context", "Retrieve a previously saved context snapshot by name, or list all snapshots", {
+    server.tool("recall_context", "Return current work and linked context; retrieve a named snapshot or explicitly list snapshots", {
         name: z
             .string()
             .optional()
-            .describe("Snapshot name to retrieve (omit for list)"),
-    }, async ({ name }) => {
-        const indexPath = wsPath(CONTEXT_STORE_REL, "index.json");
+            .describe("Named snapshot to retrieve; omit for current work"),
+        list: z.boolean().optional().describe("List saved snapshots instead of current work"),
+        goal_id: z.string().optional(),
+        agent: z.string().optional(),
+    }, async ({ name, list, goal_id, agent }, extra) => {
+        if (!name && !list) {
+            const context = readCurrentWorkContext({ goal_id, agent });
+            const lines = [formatCurrentWork(context.work, "block")];
+            const goalId = goal_id ?? context.work.objective?.goal_id;
+            if (goalId) {
+                const plan = new GoalRepository(resolveWorkspaceRoot()).getPlan(goalId);
+                if (plan)
+                    for (const step of plan.steps.filter((s) => s.status === "running")) {
+                        if (agent && step.assignee === agent)
+                            bindHostWork({ agent, goal_id: goalId, step_id: step.step_id, attempt: step.attempt }, extra.sessionId);
+                        lines.push(`Assignment ${step.step_id} (attempt ${step.attempt ?? 'engine'}, assignee ${step.assignee ?? step.role}):\n${formatStepTaskForBridge({ ...step, task: renderLearningTask(resolveWorkspaceRoot(), goalId, step), upstream_outputs: collectUpstreamOutputs(plan, step) })}${readLearningPolicy(resolveWorkspaceRoot()).enabled && step.served_learning?.text ? '\n' + step.served_learning.text : ''}`);
+                    }
+            }
+            const failures = context.events.filter((e) => ["fail", "blocked"].includes(e.status));
+            const selected = [...new Map([...context.events.slice(-5), ...failures].map((e) => [e.event_id, e])).values()];
+            for (const event of selected.reverse())
+                lines.push(`[${event.event_id}] ${event.event_type}: ${event.payload.summary ?? ""}`);
+            for (const entry of context.entries.slice(-4).reverse())
+                lines.push(`[${entry.id}] ${entry.message}`);
+            if (context.events.length > selected.length || context.entries.length > 4)
+                lines.push("Additional linked detail: list_status_events / get_run_ledger.");
+            return { isError: false, content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        const indexPath = `${CONTEXT_STORE_REL}/index.json`;
         const indexRaw = safeRead(indexPath);
         if (isReadError(indexRaw)) {
             return {
+                isError: !!name,
                 content: [
                     {
                         type: "text",
@@ -228,9 +262,12 @@ export function registerMemoryTools(server) {
         let index;
         try {
             index = JSON.parse(indexRaw);
+            if (!Array.isArray(index.snapshots) || index.snapshots.some((s) => !s || typeof s.name !== "string" || typeof s.file !== "string" || typeof s.timestamp !== "string"))
+                throw new Error("Invalid snapshot index");
         }
         catch {
             return {
+                isError: true,
                 content: [
                     {
                         type: "text",
@@ -257,6 +294,7 @@ export function registerMemoryTools(server) {
         const match = index.snapshots.find((s) => s.name.toLowerCase() === name.toLowerCase());
         if (!match) {
             return {
+                isError: true,
                 content: [
                     {
                         type: "text",
@@ -265,9 +303,10 @@ export function registerMemoryTools(server) {
                 ],
             };
         }
-        const content = safeRead(wsPath(CONTEXT_STORE_REL, match.file));
+        const content = safeRead(`${CONTEXT_STORE_REL}/${match.file}`);
         if (isReadError(content)) {
             return {
+                isError: true,
                 content: [
                     {
                         type: "text",
@@ -276,6 +315,12 @@ export function registerMemoryTools(server) {
                 ],
             };
         }
+        try {
+            JSON.parse(content);
+        }
+        catch {
+            return { isError: true, content: [{ type: "text", text: `Snapshot ${match.name} is corrupt. Recover its source or select another named snapshot.` }] };
+        }
         return {
             content: [
                 {

package/dist/tools-scheduler.js

@@ -2,6 +2,7 @@
  * Job scheduler tool registrations.
  */
 import { z } from "zod";
+import { resolveWorkspaceRoot } from "./helpers.js";
 import { acknowledgeJob, completeJob, dispatchJobNow, dispatchJobs, enqueueJob, getJobLockTablePath, getJobQueuePath, getSchedulerLeasePath, heartbeatJob, reapStaleRunningJobsTick, readJobQueue, readJobLockTable, readSchedulerLease, } from "./job-scheduler.js";
 // Event emission handled in core job-scheduler.ts — no wrapper duplication.
 const PRIORITY_BAND_ENUM = z.enum(["P0", "P1", "P2", "P3"]);
@@ -22,6 +23,7 @@ function asJsonBlock(value) {
     return `\`\`\`json\n${JSON.stringify(value, null, 2)}\n\`\`\``;
 }
 export function registerSchedulerTools(server) {
+    const workspaceRoot = resolveWorkspaceRoot();
     server.tool("enqueue_job", "Add a handoff job to the scheduler queue with priority/dependency/resource metadata", {
         kind: z.string().describe("Job kind/type identifier"),
         payload: z
@@ -46,7 +48,7 @@ export function registerSchedulerTools(server) {
         backoff_ms: z.number().int().min(1000).max(86_400_000).optional(),
         job_id: z.string().optional().describe("Optional caller-provided job id"),
     }, async (input) => {
-        const result = await enqueueJob(input);
+        const result = await enqueueJob(input, workspaceRoot);
         return {
             content: [
                 {
@@ -78,15 +80,15 @@ export function registerSchedulerTools(server) {
             .describe("Include lock table payload (default true)"),
         limit: z.number().int().min(1).max(1000).optional().describe("Max jobs returned"),
     }, async ({ status, include_locks, limit }) => {
-        const queue = readJobQueue();
+        const queue = readJobQueue(workspaceRoot);
         const filtered = queue.jobs.filter((job) => (status ? job.status === status : true));
         const clipped = typeof limit === "number" ? filtered.slice(0, limit) : filtered;
-        const lockTable = readJobLockTable();
-        const lease = readSchedulerLease();
+        const lockTable = readJobLockTable(workspaceRoot);
+        const lease = readSchedulerLease(workspaceRoot);
         const payload = {
-            queue_path: getJobQueuePath(),
-            lock_path: getJobLockTablePath(),
-            lease_path: getSchedulerLeasePath(),
+            queue_path: getJobQueuePath(workspaceRoot),
+            lock_path: getJobLockTablePath(workspaceRoot),
+            lease_path: getSchedulerLeasePath(workspaceRoot),
             total_jobs: queue.jobs.length,
             returned_jobs: clipped.length,
             jobs: clipped,
@@ -109,7 +111,7 @@ export function registerSchedulerTools(server) {
         action: z.enum(["accept", "reject", "cancel", "resume"]),
         reason: z.string().optional(),
     }, async ({ job_id, action, reason }) => {
-        const result = await acknowledgeJob({ job_id, action, reason });
+        const result = await acknowledgeJob({ job_id, action, reason }, workspaceRoot);
         return {
             content: [
                 {
@@ -135,7 +137,7 @@ export function registerSchedulerTools(server) {
         lease_ttl_seconds: z.number().int().min(5).max(3600).optional(),
         now_iso: z.string().optional().describe("Optional deterministic clock override"),
     }, async (input) => {
-        const result = await dispatchJobs(input);
+        const result = await dispatchJobs(input, workspaceRoot);
         return {
             content: [
                 {
@@ -158,7 +160,7 @@ export function registerSchedulerTools(server) {
         owner: z.string().optional(),
         now_iso: z.string().optional(),
     }, async ({ job_id, owner, now_iso }) => {
-        const result = await dispatchJobNow({ job_id, owner, now_iso });
+        const result = await dispatchJobNow({ job_id, owner, now_iso }, workspaceRoot);
         return {
             content: [
                 {
@@ -185,7 +187,7 @@ export function registerSchedulerTools(server) {
             evidence_ref,
             error,
             now_iso,
-        });
+        }, workspaceRoot);
         return {
             content: [
                 {
@@ -203,7 +205,7 @@ export function registerSchedulerTools(server) {
         lease_ttl_seconds: z.number().int().min(5).max(3600).optional(),
         now_iso: z.string().optional().describe("Optional deterministic clock override"),
     }, async ({ job_id, owner, lease_ttl_seconds, now_iso }) => {
-        const result = await heartbeatJob({ job_id, owner, lease_ttl_seconds, now_iso });
+        const result = await heartbeatJob({ job_id, owner, lease_ttl_seconds, now_iso }, workspaceRoot);
         return {
             content: [
                 {
@@ -225,7 +227,7 @@ export function registerSchedulerTools(server) {
             .describe("Staleness window in seconds (default 120)"),
         now_iso: z.string().optional().describe("Optional deterministic clock override"),
     }, async ({ heartbeat_stale_seconds, now_iso }) => {
-        const result = await reapStaleRunningJobsTick({ heartbeat_stale_seconds, now_iso });
+        const result = await reapStaleRunningJobsTick({ heartbeat_stale_seconds, now_iso }, workspaceRoot);
         return {
             content: [
                 {
@@ -247,9 +249,9 @@ export function registerSchedulerTools(server) {
                 text: [
                     "# Lock Table",
                     "",
-                    `Path: ${getJobLockTablePath()}`,
+                    `Path: ${getJobLockTablePath(workspaceRoot)}`,
                     "",
-                    asJsonBlock(readJobLockTable()),
+                    asJsonBlock(readJobLockTable(workspaceRoot)),
                 ].join("\n"),
             },
         ],
@@ -261,9 +263,9 @@ export function registerSchedulerTools(server) {
                 text: [
                     "# Scheduler Lease",
                     "",
-                    `Path: ${getSchedulerLeasePath()}`,
+                    `Path: ${getSchedulerLeasePath(workspaceRoot)}`,
                     "",
-                    asJsonBlock(readSchedulerLease() ?? null),
+                    asJsonBlock(readSchedulerLease(workspaceRoot) ?? null),
                 ].join("\n"),
             },
         ],