@dotdrelle/wiki-manager 0.11.10 → 0.12.1

package/src/core/documentIntake.js

@@ -1,10 +1,10 @@
 import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { copyFile, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
-import { basename, extname, isAbsolute, join, resolve } from 'node:path';
+import { basename, extname, join, resolve } from 'node:path';
 import { callMcpTool, formatMcpToolResult } from './mcp.js';
 import { parseJsonText } from './activity.js';
-import { userManagerDir } from './env.js';
+import { resolveAgentsDataDir } from './env.js';
 
 const SUPPORTED_EXTENSIONS = new Set([
   '.txt', '.md', '.markdown', '.csv', '.json', '.xml', '.yaml', '.yml', '.html', '.htm', '.rtf',
@@ -13,17 +13,12 @@ const SUPPORTED_EXTENSIONS = new Set([
   '.pdf',
 ]);
 
-function agentsDataDir() {
-  const configured = process.env.AGENTS_DATA_DIR || '.agents-data';
-  return isAbsolute(configured) ? configured : resolve(userManagerDir(), configured);
+function documentInputRoot(session = null) {
+  return resolve(resolveAgentsDataDir(session), 'documents', 'input');
 }
 
-function documentInputRoot() {
-  return resolve(agentsDataDir(), 'documents', 'input');
-}
-
-function uploadsRoot() {
-  return resolve(agentsDataDir(), 'documents', 'uploads');
+function uploadsRoot(session = null) {
+  return resolve(resolveAgentsDataDir(session), 'documents', 'uploads');
 }
 
 function requireWorkspace(session) {
@@ -70,12 +65,12 @@ function assertSupportedFile(filename, size) {
   }
 }
 
-function manifestPath(workspace) {
-  return join(uploadsRoot(), `${workspace}.jsonl`);
+function manifestPath(workspace, session = null) {
+  return join(uploadsRoot(session), `${workspace}.jsonl`);
 }
 
-async function readManifest(workspace) {
-  const file = manifestPath(workspace);
+async function readManifest(workspace, session = null) {
+  const file = manifestPath(workspace, session);
   if (!existsSync(file)) return [];
   const raw = await readFile(file, 'utf8');
   return raw
@@ -90,26 +85,26 @@ async function readManifest(workspace) {
     });
 }
 
-async function writeManifest(workspace, records) {
-  const file = manifestPath(workspace);
-  await mkdir(uploadsRoot(), { recursive: true });
+async function writeManifest(workspace, records, session = null) {
+  const file = manifestPath(workspace, session);
+  await mkdir(uploadsRoot(session), { recursive: true });
   const body = records.map((record) => JSON.stringify(record)).join('\n');
   const tmp = `${file}.tmp.${process.pid}`;
   await writeFile(tmp, body ? `${body}\n` : '', 'utf8');
   await rename(tmp, file);
 }
 
-async function upsertUpload(record) {
-  const records = await readManifest(record.workspace);
+async function upsertUpload(record, session = null) {
+  const records = await readManifest(record.workspace, session);
   const index = records.findIndex((item) => item.id === record.id);
   if (index === -1) records.unshift(record);
   else records[index] = { ...records[index], ...record };
-  await writeManifest(record.workspace, records);
+  await writeManifest(record.workspace, records, session);
   return record;
 }
 
-async function removeExistingUploadsForFilename(workspace, filename) {
-  const records = await readManifest(workspace);
+async function removeExistingUploadsForFilename(workspace, filename, session = null) {
+  const records = await readManifest(workspace, session);
   const removed = records.filter((item) => item.filename === filename);
   if (removed.length === 0) return [];
 
@@ -119,7 +114,7 @@ async function removeExistingUploadsForFilename(workspace, filename) {
       if (file) await rm(file, { force: true }).catch(() => {});
     }
   }
-  await writeManifest(workspace, keep);
+  await writeManifest(workspace, keep, session);
   return removed;
 }
 
@@ -159,11 +154,11 @@ export async function storeDocumentUpload(session, sourcePath) {
   const filename = sanitizeFilename(absolutePath);
   assertSupportedFile(filename, info.size);
 
-  await removeExistingUploadsForFilename(workspace, filename);
+  await removeExistingUploadsForFilename(workspace, filename, session);
 
   const id = randomUUID().slice(0, 8);
   const storedFilename = `${id}-${filename}`;
-  const workspaceInput = join(documentInputRoot(), workspace);
+  const workspaceInput = join(documentInputRoot(session), workspace);
   await mkdir(workspaceInput, { recursive: true });
   const storedPath = join(workspaceInput, storedFilename);
   await copyFile(absolutePath, storedPath);
@@ -184,13 +179,13 @@ export async function storeDocumentUpload(session, sourcePath) {
     createdAt: now,
     updatedAt: now,
   };
-  await upsertUpload(record);
+  await upsertUpload(record, session);
   return record;
 }
 
 export async function convertStoredDocument(session, id, options = {}) {
   const workspace = requireWorkspace(session);
-  const records = await readManifest(workspace);
+  const records = await readManifest(workspace, session);
   const record = records.find((item) => item.id === id);
   if (!record) throw new Error(`Unknown upload id: ${id}`);
   if (!existsSync(record.storedPath)) throw new Error(`Stored file is missing: ${record.storedPath}`);
@@ -199,7 +194,7 @@ export async function convertStoredDocument(session, id, options = {}) {
     record.provider = null;
     record.error = 'documents MCP is not connected';
     record.updatedAt = new Date().toISOString();
-    await upsertUpload(record);
+    await upsertUpload(record, session);
     return { record, converted: false };
   }
 
@@ -207,7 +202,7 @@ export async function convertStoredDocument(session, id, options = {}) {
   record.provider = 'documents';
   record.error = null;
   record.updatedAt = new Date().toISOString();
-  await upsertUpload(record);
+  await upsertUpload(record, session);
 
   try {
     const toolArgs = {
@@ -223,7 +218,7 @@ export async function convertStoredDocument(session, id, options = {}) {
     if (activity && !activity.terminal) {
       record.jobId = payload.jobId ?? null;
       record.updatedAt = new Date().toISOString();
-      await upsertUpload(record);
+      await upsertUpload(record, session);
       return { record, converted: false, activity };
     }
 
@@ -232,13 +227,13 @@ export async function convertStoredDocument(session, id, options = {}) {
     record.method = payload.method ?? null;
     record.error = null;
     record.updatedAt = new Date().toISOString();
-    await upsertUpload(record);
+    await upsertUpload(record, session);
     return { record, converted: true, payload, activity };
   } catch (err) {
     record.status = 'failed';
     record.error = err instanceof Error ? err.message : String(err);
     record.updatedAt = new Date().toISOString();
-    await upsertUpload(record);
+    await upsertUpload(record, session);
     return { record, converted: false };
   }
 }
@@ -247,7 +242,7 @@ export async function storeAndMaybeConvertDocument(session, sourcePath, options
   const record = await storeDocumentUpload(session, sourcePath);
   if (!documentsConverter(session)) {
     record.error = 'documents MCP is not connected';
-    await upsertUpload(record);
+    await upsertUpload(record, session);
     return { record, converted: false };
   }
   return convertStoredDocument(session, record.id, options);
@@ -255,12 +250,12 @@ export async function storeAndMaybeConvertDocument(session, sourcePath, options
 
 export async function listDocumentUploads(session) {
   const workspace = requireWorkspace(session);
-  return (await readManifest(workspace)).map(publicRecord);
+  return (await readManifest(workspace, session)).map(publicRecord);
 }
 
 export async function convertPendingDocumentUploads(session, options = {}) {
   const workspace = requireWorkspace(session);
-  const records = await readManifest(workspace);
+  const records = await readManifest(workspace, session);
   const pending = records.filter((record) => ['stored', 'failed'].includes(record.status));
   const results = [];
   for (const record of pending) {
@@ -281,7 +276,7 @@ function parseAgeMs(value = '30d') {
 export async function cleanDocumentUploads(session, olderThan = '30d') {
   const workspace = requireWorkspace(session);
   const cutoff = Date.now() - parseAgeMs(olderThan);
-  const records = await readManifest(workspace);
+  const records = await readManifest(workspace, session);
   const keep = [];
   const removed = [];
   for (const record of records) {
@@ -295,7 +290,7 @@ export async function cleanDocumentUploads(session, olderThan = '30d') {
       keep.push(record);
     }
   }
-  if (removed.length > 0) await writeManifest(workspace, keep);
+  if (removed.length > 0) await writeManifest(workspace, keep, session);
   return { removed, kept: keep };
 }
 

package/src/core/documentIntake.test.js

@@ -38,6 +38,31 @@ test('document intake stores uploads without requiring documents MCP', async ()
   }
 });
 
+test('document intake falls back to workspace root agents data, not cwd', async () => {
+  const originalAgentsDataDir = process.env.AGENTS_DATA_DIR;
+  const root = await mkdtemp(path.join(os.tmpdir(), 'wiki-manager-doc-intake-root-'));
+  const workspacesRoot = path.join(root, 'workspaces');
+  const workspacePath = path.join(workspacesRoot, 'my-project');
+  await mkdir(workspacePath, { recursive: true });
+  const source = path.join(root, 'rapport.pdf');
+  await writeFile(source, 'fake pdf content');
+  const session = {
+    workspace: 'my-project',
+    workspacePath,
+    mcp: {},
+  };
+
+  try {
+    delete process.env.AGENTS_DATA_DIR;
+    const { record } = await storeAndMaybeConvertDocument(session, source);
+    assert.equal(record.storedPath.startsWith(path.join(workspacesRoot, '.agents-data')), true);
+    assert.equal(await readFile(record.storedPath, 'utf8'), 'fake pdf content');
+  } finally {
+    if (originalAgentsDataDir === undefined) delete process.env.AGENTS_DATA_DIR;
+    else process.env.AGENTS_DATA_DIR = originalAgentsDataDir;
+  }
+});
+
 test('document intake accepts quoted absolute paths with spaces', async () => {
   const originalAgentsDataDir = process.env.AGENTS_DATA_DIR;
   const root = await mkdtemp(path.join(os.tmpdir(), 'wiki-manager-doc-intake-'));

package/src/core/env.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 
 export function userManagerDir() {
   return process.cwd();
@@ -31,6 +31,16 @@ export function managerMcpEndpointsFile() {
   return join(managerStateDir(), 'mcp.endpoints.json');
 }
 
+// Single source of truth for where `.agents-data` lives, shared by the
+// manager's own document intake and by the host path it mounts into agent
+// containers — keeping them in sync avoids the two silently drifting apart.
+export function resolveAgentsDataDir(session = null) {
+  const configured = process.env.AGENTS_DATA_DIR;
+  if (configured) return isAbsolute(configured) ? configured : resolve(defaultRuntimeStateDir(), configured);
+  if (session?.workspacePath) return resolve(dirname(session.workspacePath), '.agents-data');
+  return resolve(defaultRuntimeStateDir(), 'agents-data');
+}
+
 function parseEnvValue(value) {
   if (value.startsWith('"') && value.endsWith('"')) {
     return value

package/src/core/jobQueue.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
 import { extractActivity, parseJsonText, sessionActivities } from './activity.js';
 import { createAgentEvent, dispatchAgentEvent } from './agentEvents.js';
 import { callMcpTool, formatMcpToolResult } from './mcp.js';
@@ -34,13 +35,18 @@ export function productionLockBusy(session) {
 
 export function enqueueProductionJob(session, args = {}, reason = 'waiting') {
   const workspace = session.workspace ?? null;
+  const workspacePath = session.workspacePath ? resolve(session.workspacePath) : null;
+  if (!workspace || !workspacePath) {
+    throw new Error('Cannot enqueue production job: no active workspace path. Use /use <workspace> first.');
+  }
+  const normalizedArgs = normalizeProductionJobArgsForWorkspace(args, workspacePath);
   const item = {
     id: shortId(),
     workspace,
     server: 'production',
     tool: 'production_start_job',
-    args: { ...args },
-    lockKey: workspace ? `production:${workspace}` : 'production',
+    args: normalizedArgs,
+    lockKey: `production:${workspace}`,
     status: 'waiting',
     reason,
     createdAt: now(),
@@ -50,6 +56,24 @@ export function enqueueProductionJob(session, args = {}, reason = 'waiting') {
   return item;
 }
 
+function normalizeProductionJobArgsForWorkspace(args, workspacePath) {
+  const normalized = { ...args };
+  if (!Array.isArray(normalized.inputs)) return normalized;
+  normalized.inputs = normalized.inputs.map((input) => normalizeWorkspaceInput(input, workspacePath));
+  return normalized;
+}
+
+function normalizeWorkspaceInput(input, workspacePath) {
+  const raw = String(input ?? '').trim();
+  if (!raw) return raw;
+  const absolute = isAbsolute(raw) ? resolve(raw) : resolve(workspacePath, raw);
+  const rel = relative(workspacePath, absolute);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`Cannot enqueue production job: input is outside the active workspace: ${raw}`);
+  }
+  return rel.split(sep).join('/');
+}
+
 export function queueSummary(args = {}) {
   const parts = [
     args.type,

package/src/core/mcp.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { managerEnvFile, managerMcpEndpointsFile, readEnvFile } from './env.js';
 
-const WIKI_MANAGER_VERSION = '0.11.10';
+const WIKI_MANAGER_VERSION = '0.12.1';
 
 function envValue(key) {
   const filePath = managerEnvFile();
@@ -174,7 +174,7 @@ function clarifyToolDescription(serverName, toolName, description) {
   if (serverName === 'production' && toolName === 'production_start_job') {
     return compactDescription([
       base,
-      'Production export means wiki deliverable/publication export only. Do not use type=export for Confluence/CME/source export; use cme_export_run instead.',
+      'Production export means wiki deliverable/publication export only. Do not use type=export for Confluence/CME/source export; use cme__cme_export_run instead.',
     ].filter(Boolean).join(' '));
   }
   return base;
@@ -469,7 +469,9 @@ export function formatMcpToolsForAgent(mcpStatus) {
       sections.push(`${name}: connected, tools not discovered yet`);
       continue;
     }
-    sections.push(`${name}: ${tools.map((tool) => tool.name).join(', ')}`);
+    // Always advertise the qualified call name (server__tool): showing bare
+    // tool names here is what teaches the model to emit unqualified calls.
+    sections.push(`${name}: ${tools.map((tool) => `${name}__${tool.name}`).join(', ')}`);
   }
   return sections.length > 0 ? sections.join('\n') : 'No connected MCP tools discovered yet.';
 }
@@ -498,6 +500,31 @@ export function parseToolCallName(name) {
   return { server: name.slice(0, sep), tool: name.slice(sep + 2) };
 }
 
+// Deterministic recovery for unqualified tool-call names emitted by the LLM
+// (e.g. "cme_status" instead of "cme__cme_status"). Exact-name match only:
+// if exactly one connected server (or extra pseudo-server) exposes the bare
+// tool name, route to it and report `normalized: true`; otherwise return
+// `server: null` with the list of candidate servers so the caller can raise
+// an explicit error. This is name normalization, never fuzzy matching — do
+// not extend it to description/similarity-based selection (plan directeur
+// §20 forbids that).
+export function resolveToolCallName(mcpStatus, name, extraServers = {}) {
+  const parsed = parseToolCallName(name);
+  if (parsed.server) return { ...parsed, normalized: false, candidates: [] };
+  const candidates = [];
+  for (const [serverName, toolNames] of Object.entries(extraServers)) {
+    if (toolNames.includes(parsed.tool)) candidates.push(serverName);
+  }
+  for (const [serverName, value] of Object.entries(mcpStatus ?? {})) {
+    if (value.status !== 'connected') continue;
+    if ((value.tools ?? []).some((tool) => tool.name === parsed.tool)) candidates.push(serverName);
+  }
+  if (candidates.length === 1) {
+    return { server: candidates[0], tool: parsed.tool, normalized: true, candidates };
+  }
+  return { server: null, tool: parsed.tool, normalized: false, candidates };
+}
+
 export function mcpStatusMarker(status) {
   if (status === 'connected') return '●';
   if (status === 'configured') return '◐';

package/src/core/mcp.test.js

@@ -3,7 +3,75 @@ import assert from 'node:assert/strict';
 import { mkdtemp, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { buildMcpStatus, callMcpTool, discoverMcpTools, resolveRetryPolicy } from './mcp.js';
+import {
+  buildMcpStatus,
+  callMcpTool,
+  discoverMcpTools,
+  formatMcpToolsForAgent,
+  resolveRetryPolicy,
+  resolveToolCallName,
+} from './mcp.js';
+
+const resolveFixtureStatus = {
+  production: {
+    status: 'connected',
+    tools: [{ name: 'production_start_job' }, { name: 'agent_status' }],
+  },
+  cme: {
+    status: 'connected',
+    tools: [{ name: 'cme_status' }, { name: 'agent_status' }],
+  },
+  documents: {
+    status: 'configured', // not connected: must never be a candidate
+    tools: [{ name: 'cme_status' }],
+  },
+};
+
+test('resolveToolCallName passes qualified names through untouched', () => {
+  const resolved = resolveToolCallName(resolveFixtureStatus, 'cme__cme_status');
+  assert.deepEqual(
+    { server: resolved.server, tool: resolved.tool, normalized: resolved.normalized },
+    { server: 'cme', tool: 'cme_status', normalized: false },
+  );
+});
+
+test('resolveToolCallName normalizes a bare name with exactly one connected match', () => {
+  const resolved = resolveToolCallName(resolveFixtureStatus, 'cme_status');
+  assert.deepEqual(
+    { server: resolved.server, tool: resolved.tool, normalized: resolved.normalized },
+    { server: 'cme', tool: 'cme_status', normalized: true },
+  );
+});
+
+test('resolveToolCallName refuses ambiguous bare names and reports candidates', () => {
+  const resolved = resolveToolCallName(resolveFixtureStatus, 'agent_status');
+  assert.equal(resolved.server, null);
+  assert.equal(resolved.normalized, false);
+  assert.deepEqual([...resolved.candidates].sort(), ['cme', 'production']);
+});
+
+test('resolveToolCallName returns no server for unknown bare names', () => {
+  const resolved = resolveToolCallName(resolveFixtureStatus, 'does_not_exist');
+  assert.equal(resolved.server, null);
+  assert.deepEqual(resolved.candidates, []);
+});
+
+test('resolveToolCallName resolves internal pseudo-server tools via extraServers', () => {
+  const resolved = resolveToolCallName(resolveFixtureStatus, 'plan_set', { wiki: ['plan_set', 'plan_done'] });
+  assert.deepEqual(
+    { server: resolved.server, tool: resolved.tool, normalized: resolved.normalized },
+    { server: 'wiki', tool: 'plan_set', normalized: true },
+  );
+});
+
+test('formatMcpToolsForAgent advertises qualified server__tool names only', () => {
+  const listing = formatMcpToolsForAgent(resolveFixtureStatus);
+  assert.match(listing, /cme__cme_status/);
+  assert.match(listing, /production__production_start_job/);
+  // No bare tool name outside a qualified form.
+  assert.doesNotMatch(listing, /(?<![\w])cme_status(?![\w])/);
+  assert.doesNotMatch(listing, /(?<![\w])production_start_job(?![\w])/);
+});
 
 test('buildMcpStatus reads external MCP endpoints from mcp.endpoints.json', async () => {
   const originalCwd = process.cwd();

package/src/core/plan.js

@@ -54,17 +54,24 @@ export function matchCompletedToPlan(plan, completed) {
 
 export function syncActivitiesToPlan(plan, activities) {
   if (!plan) return;
+  const contractTaskPlan = isContractTaskPlan(plan);
   for (const activity of activities ?? []) {
     const terminal = Boolean(activity.terminal);
     const failed = ['failed', 'error', 'cancelled', 'canceled'].includes(String(activity.status).toLowerCase());
     const actKey = activity.key ?? activity.id ?? activity.jobId ?? null;
-    const matched = findMatchingPlanStepByStructure(plan, activity) ?? findMatchingPlanStep(plan, activity);
+    const structuredMatch = findMatchingPlanStepByStructure(plan, activity);
+    const matched = structuredMatch ?? findMatchingPlanStep(plan, activity);
     if (!matched) continue;
 
     if (terminal && !failed) {
+      const ownedSteps = actKey ? plan.filter((s) => s._activityKey === actKey) : [];
+      if (contractTaskPlan && structuredMatch && ownedSteps.length === 0) {
+        matched.status = 'done';
+        matched.activityKey = actKey;
+        continue;
+      }
       // Structured plan: mark all steps owned by this activity as done.
       // Legacy plan (no _activityKey): mark all steps up to matched as done (sequential assumption).
-      const ownedSteps = actKey ? plan.filter((s) => s._activityKey === actKey) : [];
       if (ownedSteps.length > 0) {
         for (const step of ownedSteps) {
           if (step.status !== 'failed') {
@@ -85,6 +92,11 @@ export function syncActivitiesToPlan(plan, activities) {
       matched.status = 'failed';
       matched.activityKey = actKey;
     } else if (!failed) {
+      if (contractTaskPlan && structuredMatch) {
+        matched.status = 'running';
+        matched.activityKey = actKey;
+        continue;
+      }
       // Running: matched step is in progress; preceding pending steps are implicitly done.
       for (const step of plan) {
         if (step.status === 'failed') continue;
@@ -104,11 +116,30 @@ export function formatPlanStatus(plan) {
   return plan
     .map((s) => {
       const icon = s.status === 'done' ? '✓' : s.status === 'failed' ? '✗' : s.status === 'running' ? '…' : ' ';
-      return `${s.step}. [${icon}] ${s.description}`;
+      return `${s.step}. [${icon}] ${formatPlanStep(s)}`;
     })
     .join('\n');
 }
 
+export function formatPlanStep(step) {
+  if (step == null) return '';
+  if (typeof step === 'string') return step;
+  if (typeof step !== 'object') return String(step);
+  for (const key of ['description', 'label', 'id', 'name']) {
+    if (step[key] != null) return formatPlanStep(step[key]);
+  }
+  return '';
+}
+
+export function formatConfigValue(value) {
+  if (value == null) return '';
+  if (Array.isArray(value)) return value.map(formatConfigValue).join(', ');
+  if (typeof value !== 'object') return String(value);
+  return Object.entries(value)
+    .map(([key, item]) => `${key}: ${formatConfigValue(item)}`)
+    .join(', ');
+}
+
 export function formatCompletedActivities(activities) {
   return activities
     .filter((a) => a.terminal)
@@ -196,7 +227,10 @@ function statusRank(status) {
 export function attachActivityToExistingPlan(plan, activity) {
   const actKey = activity.key ?? activity.id ?? activity.jobId ?? null;
   if (!actKey) return;
-  const matched = plan.find((step) => step.activityKey === actKey)
+  const contractTaskPlan = isContractTaskPlan(plan);
+  const structuredMatch = findMatchingPlanStepByStructure(plan, activity);
+  const matched = structuredMatch
+    ?? plan.find((step) => step.activityKey === actKey)
     ?? plan.find((step) => step.ownerActivityKey === actKey)
     ?? plan.find((step) => step.status === 'pending')
     ?? plan.find((step) => step.status === 'running');
@@ -209,6 +243,10 @@ export function attachActivityToExistingPlan(plan, activity) {
     return;
   }
   if (!failed) {
+    if (contractTaskPlan && structuredMatch) {
+      matched.status = 'running';
+      return;
+    }
     for (const step of plan) {
       if (step.status === 'failed') continue;
       if (step.step < matched.step) step.status = 'done';
@@ -216,3 +254,7 @@ export function attachActivityToExistingPlan(plan, activity) {
     }
   }
 }
+
+function isContractTaskPlan(plan) {
+  return (plan ?? []).some((step) => step.requiredCapability || step.operation);
+}

package/src/core/plan.test.js

@@ -1,6 +1,6 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { ensurePlanFromActivity, syncActivitiesToPlan, extractHeadlessPlan } from './plan.js';
+import { ensurePlanFromActivity, syncActivitiesToPlan, extractHeadlessPlan, formatConfigValue, formatPlanStatus, formatPlanStep } from './plan.js';
 
 test('ensurePlanFromActivity: creates multi-step plan from activity.plan.steps', () => {
   const session = { headlessPlan: null };
@@ -166,3 +166,18 @@ test('extractHeadlessPlan: parses numbered list from text (legacy)', () => {
   assert.equal(plan[0].description, 'CME export');
   assert.equal(plan[1].step, 2);
 });
+
+test('formatPlanStep renders structured steps without object interpolation', () => {
+  assert.equal(formatPlanStep('Build'), 'Build');
+  assert.equal(formatPlanStep({ description: 'Build deliverable', label: 'Build' }), 'Build deliverable');
+  assert.equal(formatPlanStep({ label: 'Build' }), 'Build');
+  assert.equal(formatPlanStep({ id: 'build-doc' }), 'build-doc');
+  assert.equal(formatPlanStatus([{ step: 1, status: 'pending', description: { label: 'Build' } }]), '1. [ ] Build');
+  assert.doesNotMatch(formatPlanStatus([{ step: 1, status: 'pending', description: { label: 'Build' } }]), /\[object Object\]/);
+});
+
+test('formatConfigValue renders objects as key-value text', () => {
+  assert.equal(formatConfigValue({ requestsPerMinute: 60 }), 'requestsPerMinute: 60');
+  assert.equal(formatConfigValue({ limits: { requestsPerMinute: 60 } }), 'limits: requestsPerMinute: 60');
+  assert.doesNotMatch(formatConfigValue({ requestsPerMinute: 60 }), /\[object Object\]/);
+});

package/src/core/planPatch.js

@@ -112,17 +112,41 @@ export function formatReadyTaskPrompt(task) {
 
 export function normalizeTask(raw, index = 0) {
   const item = raw && typeof raw === 'object' ? raw : { description: String(raw ?? '') };
-  return {
+  const label = String(item.label ?? item.description ?? item.name ?? `Step ${index + 1}`);
+  const task = {
     ...item,
     step: Number(item.step ?? index + 1),
     id: item.id != null ? String(item.id) : null,
-    description: String(item.description ?? item.label ?? item.name ?? `Step ${index + 1}`),
+    label,
+    description: String(item.description ?? label),
     status: String(item.status ?? 'pending'),
     dependsOn: Array.isArray(item.dependsOn) ? item.dependsOn.map(String) : [],
+    requiredCapability: toNullableString(item.requiredCapability),
+    operation: toNullableString(item.operation),
+    arguments: item.arguments && typeof item.arguments === 'object' && !Array.isArray(item.arguments) ? { ...item.arguments } : {},
+    groupId: toNullableString(item.groupId),
+    dependsOnGroup: toNullableString(item.dependsOnGroup),
+    barrier: item.barrier === true,
+    parallelizable: item.parallelizable === true,
+    recommendedConcurrency: normalizeOptionalPositiveInteger(item.recommendedConcurrency),
+    inputRefs: normalizeReferenceArray(item.inputRefs),
+    expectedOutputRefs: normalizeReferenceArray(item.expectedOutputRefs),
+    locks: Array.isArray(item.locks) ? item.locks.map(String) : [],
+    requiresApproval: item.requiresApproval === true,
+    approvalClass: toNullableString(item.approvalClass),
+    approvalSummary: toNullableString(item.approvalSummary),
+    idempotencyKey: toNullableString(item.idempotencyKey),
+    progressWeight: normalizeProgressWeight(item.progressWeight),
+    priority: normalizeOptionalNumber(item.priority),
+    retryPolicy: item.retryPolicy == null ? undefined : normalizeRetryPolicy(item.retryPolicy),
     executor: item.executor ?? null,
     executorQuery: item.executorQuery ?? null,
-    outputRefs: Array.isArray(item.outputRefs) ? item.outputRefs.map(String) : [],
+    outputRefs: normalizeReferenceArray(item.outputRefs),
   };
+  for (const key of ['recommendedConcurrency', 'priority', 'retryPolicy']) {
+    if (task[key] === undefined) delete task[key];
+  }
+  return task;
 }
 
 export function sanitizePlanForExecution(plan) {
@@ -162,6 +186,43 @@ function normalizePatchOperation(raw) {
   return { ...raw, op };
 }
 
+function toNullableString(value) {
+  return value != null ? String(value) : null;
+}
+
+function normalizeReferenceArray(value) {
+  if (!Array.isArray(value)) return [];
+  return value.map((item) => {
+    if (item && typeof item === 'object' && !Array.isArray(item)) return { ...item };
+    return String(item);
+  });
+}
+
+function normalizeOptionalPositiveInteger(value) {
+  const number = Number(value);
+  return Number.isInteger(number) && number >= 1 ? number : undefined;
+}
+
+function normalizeOptionalNumber(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : undefined;
+}
+
+function normalizeProgressWeight(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : 1;
+}
+
+function normalizeRetryPolicy(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const maxAttempts = Number(value.maxAttempts);
+  return {
+    maxAttempts: Number.isInteger(maxAttempts) && maxAttempts >= 1 ? maxAttempts : 1,
+    retryableErrors: Array.isArray(value.retryableErrors) ? value.retryableErrors.map(String) : [],
+    allowAgentFallback: value.allowAgentFallback === true,
+  };
+}
+
 function normalizeAddedTask(raw, index) {
   const task = normalizeTask(raw, index);
   return {