@dotdrelle/wiki-manager 0.11.9 → 0.12.0

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.9';
+const WIKI_MANAGER_VERSION = '0.12.0';
 
 function envValue(key) {
   const filePath = managerEnvFile();

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 {

package/src/core/planPatch.test.js

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { applyPlanPatch, nextReadyPlanTask, readyPlanTasks, rebasePlanPatch, sanitizePlanForExecution } from './planPatch.js';
+import { applyPlanPatch, nextReadyPlanTask, normalizeTask, readyPlanTasks, rebasePlanPatch, sanitizePlanForExecution } from './planPatch.js';
 
 test('applyPlanPatch adds a task and increments the plan revision', () => {
   const result = applyPlanPatch([
@@ -83,3 +83,112 @@ test('sanitizePlanForExecution breaks cycles with declaration-order fallback', (
   assert.match(result.warnings.join('\n'), /cycle/);
   assert.deepEqual(readyPlanTasks(result.plan).map((task) => task.id), ['a']);
 });
+
+test('normalizeTask carries task contract fields with safe defaults', () => {
+  const task = normalizeTask({
+    id: 'ingest-a',
+    label: 'Ingest A',
+    requiredCapability: 'knowledge.update',
+    operation: 'ingest',
+    arguments: { files: ['raw/untracked/a.md'] },
+    groupId: 'ingest',
+    dependsOn: ['scan'],
+    dependsOnGroup: 'sources',
+    barrier: true,
+    parallelizable: true,
+    recommendedConcurrency: 3,
+    inputRefs: [{ type: 'file', ref: 'raw/untracked/a.md' }],
+    expectedOutputRefs: ['wiki/a.md'],
+    locks: ['workspace:wiki'],
+    requiresApproval: true,
+    approvalClass: 'mutation',
+    approvalSummary: 'Update wiki',
+    idempotencyKey: 'idem-1',
+    progressWeight: 2,
+    priority: 5,
+    retryPolicy: {
+      maxAttempts: 2,
+      retryableErrors: ['timeout'],
+      allowAgentFallback: true,
+    },
+  }, 0);
+
+  assert.equal(task.description, 'Ingest A');
+  assert.equal(task.parallelizable, true);
+  assert.deepEqual(task.inputRefs, [{ type: 'file', ref: 'raw/untracked/a.md' }]);
+  assert.deepEqual(task.expectedOutputRefs, ['wiki/a.md']);
+  assert.deepEqual(task.locks, ['workspace:wiki']);
+  assert.equal(task.requiresApproval, true);
+  assert.equal(task.progressWeight, 2);
+  assert.deepEqual(task.retryPolicy, {
+    maxAttempts: 2,
+    retryableErrors: ['timeout'],
+    allowAgentFallback: true,
+  });
+});
+
+test('normalizeTask supplies safe defaults for new execution fields', () => {
+  const task = normalizeTask({ id: 'legacy', description: 'Legacy task' }, 0);
+
+  assert.equal(task.label, 'Legacy task');
+  assert.equal(task.requiredCapability, null);
+  assert.equal(task.operation, null);
+  assert.deepEqual(task.arguments, {});
+  assert.equal(task.parallelizable, false);
+  assert.deepEqual(task.inputRefs, []);
+  assert.deepEqual(task.locks, []);
+  assert.equal(task.requiresApproval, false);
+  assert.equal(task.idempotencyKey, null);
+  assert.equal(task.progressWeight, 1);
+});
+
+test('sanitizePlanForExecution preserves task contract fields through cleanup', () => {
+  const result = sanitizePlanForExecution([
+    {
+      id: 'scan',
+      label: 'Scan inputs',
+      requiredCapability: 'knowledge.update',
+      operation: 'scan',
+      dependsOn: [],
+      parallelizable: false,
+      inputRefs: [{ type: 'directory', ref: 'raw/untracked' }],
+      locks: [],
+      requiresApproval: false,
+      idempotencyKey: null,
+      progressWeight: 1,
+    },
+    {
+      id: 'ingest',
+      label: 'Ingest inputs',
+      requiredCapability: 'knowledge.update',
+      operation: 'ingest',
+      dependsOn: ['scan', 'missing'],
+      parallelizable: true,
+      inputRefs: ['raw/untracked/a.md'],
+      locks: ['workspace:wiki'],
+      requiresApproval: false,
+      idempotencyKey: null,
+      progressWeight: 3,
+    },
+  ]);
+
+  assert.deepEqual(result.plan[1].dependsOn, ['scan']);
+  assert.equal(result.plan[1].requiredCapability, 'knowledge.update');
+  assert.equal(result.plan[1].operation, 'ingest');
+  assert.equal(result.plan[1].parallelizable, true);
+  assert.deepEqual(result.plan[1].inputRefs, ['raw/untracked/a.md']);
+  assert.deepEqual(result.plan[1].locks, ['workspace:wiki']);
+  assert.equal(result.plan[1].progressWeight, 3);
+});
+
+test('legacy event plan replay remains readable after task contract extension', () => {
+  const result = sanitizePlanForExecution([
+    { step: 1, id: 'a', description: 'Old A', status: 'done' },
+    { step: 2, id: 'b', description: 'Old B', status: 'pending', dependsOn: ['a'] },
+  ]);
+
+  assert.deepEqual(result.warnings, []);
+  assert.deepEqual(result.plan.map((task) => task.id), ['a', 'b']);
+  assert.deepEqual(result.plan.map((task) => task.label), ['Old A', 'Old B']);
+  assert.deepEqual(readyPlanTasks(result.plan).map((task) => task.id), ['b']);
+});