@yeaft/webchat-agent 1.0.130 → 1.0.132

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.130",
+  "version": "1.0.132",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/yeaft/config.js

@@ -454,11 +454,14 @@ export function loadConfig(overrides = {}) {
       const p = normalizeKnownProviderForRuntime(rawProvider);
       const normalized = normalizeProviderModels(p);
       for (const m of normalized) {
-        // Avoid duplicates (first provider wins)
-        if (!config.availableModels.some(am => am.id === m.id)) {
+        const ref = p.name ? `${p.name}/${m.id}` : m.id;
+        // A model id is only unique inside its provider. Keep provider-qualified
+        // duplicates so an explicit `provider/model` never disappears from the
+        // runtime catalog just because another provider exposes the same id.
+        if (!config.availableModels.some(am => am.ref === ref)) {
           const entry = {
             id: m.id,
-            ref: p.name ? `${p.name}/${m.id}` : m.id,
+            ref,
             provider: p.name,
             label: m.id,
           };

package/yeaft/tools/create-work-item.js

@@ -60,7 +60,9 @@ Use this when work must continue beyond the current turn, needs role handoffs, r
       goal,
       acceptanceCriteria: cleanCriteria(input.acceptanceCriteria),
       workDir: typeof input.workDir === 'string' ? input.workDir.trim() : (ctx.cwd || ''),
-      workflowTemplate: 'software-change',
+      // The Agent-local Work Center settings choose the default workflow and
+      // freeze its policy snapshot. Tool callers create the contract; they do
+      // not get to smuggle a different dispatch policy into it.
       origin: {
         sessionId,
         messageId: ctx.inboundEnvelope?.msgId || null,

package/yeaft/work-center/assignment.js

@@ -0,0 +1,135 @@
+import { parseModelRef } from '../models.js';
+import { normalizeAssignmentPolicy, normalizeModelPolicy } from './workflow.js';
+
+function policyError(message) {
+  const error = new Error(message);
+  error.retryable = false;
+  return error;
+}
+
+const CAPABILITY_TERMS = Object.freeze({
+  triage: ['triage', 'requirement', 'flow', 'product', 'strategy', 'cross-domain', 'analysis'],
+  implement: ['implement', 'engineer', 'developer', 'engineering', 'systems', 'code', 'execution'],
+  test: ['test', 'testing', 'quality', 'qa', 'verification', 'reliability'],
+  review: ['review', 'reviewer', 'refactor', 'architecture', 'code-smells', 'readability', 'maintainability'],
+  deliver: ['deliver', 'release', 'ship', 'git', 'engineering', 'systems', 'execution'],
+  research: ['research', 'science', 'analysis', 'evidence', 'investigation'],
+  write: ['write', 'writer', 'writing', 'documentation', 'editor', 'communication'],
+});
+
+function vpSearchText(vp) {
+  return [
+    vp.id,
+    vp.name,
+    vp.nameZh,
+    vp.role,
+    vp.roleZh,
+    vp.area,
+    ...(Array.isArray(vp.aliases) ? vp.aliases : []),
+    ...(Array.isArray(vp.traits) ? vp.traits : []),
+  ].filter(Boolean).join(' ').toLowerCase();
+}
+
+function capabilityScore(vp, capability) {
+  const needle = String(capability || '').trim().toLowerCase();
+  if (!needle) return 0;
+  const text = vpSearchText(vp);
+  const terms = CAPABILITY_TERMS[needle] || [needle];
+  let score = 0;
+  for (const term of terms) {
+    if (text.includes(term)) score += term === needle ? 6 : 2;
+  }
+  if (String(vp.area || '').toLowerCase() === needle) score += 4;
+  return score;
+}
+
+function priorVpIdsForSeparation(policy, priorRuns) {
+  const separatedTypes = new Set(policy.separateFromStageTypes || []);
+  if (separatedTypes.size === 0) return new Set();
+  return new Set((priorRuns || [])
+    .filter(run => separatedTypes.has(run.actionType) || separatedTypes.has(run.roleSnapshot?.actionType))
+    .map(run => run.vpSnapshot?.id)
+    .filter(Boolean));
+}
+
+export function selectWorkItemVp({ policy: rawPolicy, stageType, vps, priorRuns = [] }) {
+  const policy = normalizeAssignmentPolicy(rawPolicy, stageType);
+  const all = Array.isArray(vps) ? vps.filter(vp => vp?.id) : [];
+  if (all.length === 0) throw policyError('Work Center has no available VPs');
+  const byId = new Map(all.map(vp => [vp.id, vp]));
+  const excluded = priorVpIdsForSeparation(policy, priorRuns);
+
+  if (policy.mode === 'fixed') {
+    const fixed = byId.get(policy.fixedVpId);
+    if (!fixed) throw policyError(`Fixed Work Center VP is unavailable: ${policy.fixedVpId}`);
+    if (excluded.has(fixed.id)) throw policyError(`Work Center separation policy excludes VP: ${fixed.id}`);
+    return { vp: fixed, reason: `fixed:${fixed.id}`, policy };
+  }
+
+  const pool = policy.mode === 'pool'
+    ? policy.candidateVpIds.map(id => byId.get(id)).filter(Boolean)
+    : all;
+  if (pool.length === 0) throw policyError('No configured Work Center VP candidates are available');
+  const eligible = pool.filter(vp => !excluded.has(vp.id));
+  if (eligible.length === 0) throw policyError('No Work Center VP satisfies the stage separation policy');
+
+  const ranked = eligible
+    .map(vp => ({ vp, score: capabilityScore(vp, policy.capability || stageType) }))
+    .sort((left, right) => right.score - left.score || left.vp.id.localeCompare(right.vp.id));
+  if (ranked[0].score === 0 && policy.mode === 'auto') {
+    throw policyError(`No Work Center VP matches capability: ${policy.capability || stageType}`);
+  }
+  return {
+    vp: ranked[0].vp,
+    reason: `${policy.mode}:${policy.capability || stageType}:score=${ranked[0].score}`,
+    policy,
+  };
+}
+
+function availableModel(config, ref) {
+  const models = Array.isArray(config.availableModels) ? config.availableModels : [];
+  if (models.length === 0) return null;
+  const parsed = parseModelRef(ref);
+  return models.find(model => model.ref === ref)
+    || models.find(model => !parsed.providerName && model.id === parsed.modelId)
+    || null;
+}
+
+export function resolveWorkItemModel(config, vp, rawPolicy) {
+  const policy = normalizeModelPolicy(rawPolicy);
+  let model;
+  let source;
+  if (policy.mode === 'specific') {
+    model = policy.model;
+    source = 'stage-specific';
+  } else if (policy.mode === 'primary') {
+    model = config.primaryModel || config.model || null;
+    source = 'agent-primary';
+  } else if (policy.mode === 'fast') {
+    model = config.fastModel || null;
+    source = 'agent-fast';
+  } else if (vp.modelHint === 'fast') {
+    model = config.fastModel || config.primaryModel || config.model || null;
+    source = config.fastModel ? 'vp-fast' : 'vp-fast-primary-fallback';
+  } else {
+    model = config.primaryModel || config.model || null;
+    source = vp.modelHint === 'primary' ? 'vp-primary' : 'agent-default';
+  }
+  if (!model) throw policyError(`Work Center model policy "${policy.mode}" has no configured model`);
+  const available = availableModel(config, model);
+  if (Array.isArray(config.availableModels) && config.availableModels.length > 0 && !available) {
+    throw policyError(`Configured Work Center model is unavailable: ${model}`);
+  }
+  const effortOptions = Array.isArray(available?.effortOptions) ? available.effortOptions : [];
+  if (policy.effort && !effortOptions.includes(policy.effort)) {
+    throw policyError(`Configured Work Center effort is unsupported by ${model}: ${policy.effort}`);
+  }
+  const parsed = parseModelRef(model);
+  return {
+    model,
+    effort: policy.effort || null,
+    provider: available?.provider || parsed.providerName || null,
+    source,
+    policy,
+  };
+}

package/yeaft/work-center/bridge.js

@@ -1,11 +1,13 @@
 import ctx from '../../context.js';
 import { sendToServer } from '../../connection/buffer.js';
-import { ensureSessionLoaded } from '../web-bridge.js';
+import { ensureSessionLoaded, resetYeaftSession } from '../web-bridge.js';
 import { defaultRegistry } from '../vp/registry.js';
 import { scanVpLibrary } from '../vp/vp-store.js';
 import { WorkCenterService } from './service.js';
 import { WorkItemRunner } from './runner.js';
-import { projectWorkCenterEvent } from './projection.js';
+import { projectWorkCenterEvent, projectWorkItemDetail } from './projection.js';
+import { previewWorkCenterPlan } from './planner.js';
+import { readWorkCenterSettings } from './settings.js';
 import { join } from 'node:path';
 
 let service = null;
@@ -14,6 +16,8 @@ let shuttingDown = false;
 let shutdownPromise = null;
 let serviceFactory = null;
 
+const BROWSER_DETAIL_OPS = new Set(['get', 'create', 'update', 'start', 'cancel', 'guide', 'retry']);
+
 function send(msg) {
   sendToServer(msg);
 }
@@ -29,7 +33,7 @@ async function createDefaultService() {
     runtimeProvider: async () => {
       const runtime = await getRuntime();
       if (defaultRegistry.vpCount() === 0) {
-        for (const vp of scanVpLibrary({ dir: join(runtime.yeaftDir, 'virtual-persons') })) defaultRegistry.setVp(vp);
+        for (const vp of scanVpLibrary({ dir: join(yeaftDir, 'virtual-persons') })) defaultRegistry.setVp(vp);
       }
       return {
         ...runtime,
@@ -42,6 +46,27 @@ async function createDefaultService() {
   const created = new WorkCenterService({
     yeaftDir,
     runner,
+    runtimeInfoProvider: async () => {
+      const runtime = await getRuntime();
+      if (defaultRegistry.vpCount() === 0) {
+        for (const vp of scanVpLibrary({ dir: join(yeaftDir, 'virtual-persons') })) defaultRegistry.setVp(vp);
+      }
+      return {
+        vps: defaultRegistry.listVps().map(vp => ({
+          id: vp.id,
+          name: vp.name || vp.id,
+          nameZh: vp.nameZh || '',
+          role: vp.role || '',
+          roleZh: vp.roleZh || '',
+          area: vp.area || '',
+          traits: Array.isArray(vp.traits) ? vp.traits : [],
+          modelHint: vp.modelHint || null,
+        })),
+        models: Array.isArray(runtime.config.availableModels) ? runtime.config.availableModels : [],
+        primaryModel: runtime.config.primaryModel || runtime.config.model || null,
+        fastModel: runtime.config.fastModel || null,
+      };
+    },
     onEvent(event) {
       send({ type: 'work_center_event', event: projectWorkCenterEvent(event) });
     },
@@ -85,7 +110,28 @@ export async function handleWorkCenterRequest(msg) {
   const op = typeof msg.op === 'string' ? msg.op : '';
   try {
     const workCenter = await ensureWorkCenter();
-    const data = await workCenter.handle(op, msg.payload || {});
+    let data;
+    if (op === 'preview') {
+      const runtime = await getRuntime();
+      const yeaftDir = ctx.CONFIG?.yeaftDir;
+      if (!yeaftDir) throw new Error('Work Center requires a configured Yeaft directory');
+      if (defaultRegistry.vpCount() === 0) {
+        for (const vp of scanVpLibrary({ dir: join(yeaftDir, 'virtual-persons') })) defaultRegistry.setVp(vp);
+      }
+      data = previewWorkCenterPlan({
+        settings: readWorkCenterSettings(yeaftDir),
+        workflowId: msg.payload?.workflowTemplate,
+        stageOverrides: msg.payload?.stageOverrides,
+        registry: defaultRegistry,
+        config: runtime.config,
+      });
+    } else if (op === 'refresh_runtime') {
+      await resetYeaftSession();
+      data = await workCenter.handle('get_settings', {});
+    } else {
+      data = await workCenter.handle(op, msg.payload || {});
+    }
+    if (BROWSER_DETAIL_OPS.has(op)) data = projectWorkItemDetail(data);
     send({
       type: 'work_center_response',
       requestId,

package/yeaft/work-center/controller.js

@@ -1,4 +1,4 @@
-import { actionInstruction, getNextStep, initialActionFor, RUN_OUTCOMES } from './workflow.js';
+import { actionForStage, actionInstruction, getNextStep, initialActionFor, RUN_OUTCOMES } from './workflow.js';
 import { normalizeEvidence } from './evidence.js';
 
 function normalizeCriteria(value) {
@@ -48,10 +48,12 @@ function normalizeTerminalResult(result, action) {
   return normalized;
 }
 
-function contextEntry(action, result) {
+function contextEntry(action, result, run) {
   return {
     type: action.type,
-    role: action.requiredRole,
+    stageId: action.stageId || action.type,
+    vpId: run?.vpSnapshot?.id || action.requiredRole || null,
+    role: run?.roleSnapshot?.id || action.requiredRole || null,
     summary: result.summary || '',
     evidence: result.evidence || [],
     reviewDecision: result.reviewDecision || null,
@@ -125,7 +127,13 @@ export class WorkflowController {
         summary: guidance,
         evidence: [],
       }];
-      const step = { type: previous.type, requiredRole: previous.requiredRole };
+      const step = {
+        type: previous.type,
+        stageId: previous.stageId || previous.type,
+        assignmentPolicy: previous.assignmentPolicy,
+        modelPolicy: previous.modelPolicy,
+        requiredRole: previous.requiredRole,
+      };
       return {
         ...step,
         context,
@@ -144,13 +152,21 @@ export class WorkflowController {
         throw new Error('answer is required to resume a waiting WorkItem');
       }
       const step = previous
-        ? { type: previous.type, requiredRole: previous.requiredRole }
+        ? {
+            type: previous.type,
+            stageId: previous.stageId || previous.type,
+            assignmentPolicy: previous.assignmentPolicy,
+            modelPolicy: previous.modelPolicy,
+            requiredRole: previous.requiredRole,
+          }
         : initialActionFor(workItem);
       const context = Array.isArray(previous?.context) ? [...previous.context] : [];
       if (previousRun) {
         context.push({
           type: previous.type,
-          role: previous.requiredRole,
+          stageId: previous.stageId || previous.type,
+          vpId: previousRun.vpSnapshot?.id || previous.requiredRole || null,
+          role: previousRun.roleSnapshot?.id || previous.requiredRole || null,
           summary: previousRun.summary || '',
           evidence: normalizeEvidence(previousRun.evidence),
           waitingReason: previousRun.waitingReason || null,
@@ -223,7 +239,7 @@ export class WorkflowController {
               revision: workItem.revision + 1,
             }
           : workItem;
-        const nextStep = getNextStep(workItem.workflowTemplate, action.type, result);
+        const nextStep = getNextStep(workItem, action.stageId || action.type, result);
         if (!nextStep) {
           return {
             actionStatus: 'completed',
@@ -234,17 +250,12 @@ export class WorkflowController {
           };
         }
 
-        const context = [...(action.context || []), contextEntry(action, result)];
+        const context = [...(action.context || []), contextEntry(action, result, activeRun)];
         return {
           actionStatus: 'completed',
           workItemStatus: 'ready',
           contractPatch,
-          nextAction: {
-            ...nextStep,
-            context,
-            instruction: actionInstruction(nextStep, effectiveWorkItem, context),
-            maxAttempts: 2,
-          },
+          nextAction: actionForStage(nextStep, effectiveWorkItem, context),
           eventType: 'action.completed',
           eventData: {
             nextActionType: nextStep.type,

package/yeaft/work-center/planner.js

@@ -0,0 +1,66 @@
+import { resolveWorkItemModel, selectWorkItemVp } from './assignment.js';
+import { resolveWorkflowSnapshot } from './workflow.js';
+
+function publicVp(vp) {
+  return vp ? {
+    id: vp.id,
+    name: vp.name || vp.id,
+    nameZh: vp.nameZh || '',
+    role: vp.role || '',
+    roleZh: vp.roleZh || '',
+    area: vp.area || '',
+    traits: Array.isArray(vp.traits) ? vp.traits : [],
+    modelHint: vp.modelHint || null,
+  } : null;
+}
+
+export function previewWorkCenterPlan({ settings, workflowId, stageOverrides, registry, config }) {
+  const workflow = resolveWorkflowSnapshot(settings, workflowId, stageOverrides);
+  const vps = registry.listVps();
+  const syntheticRuns = [];
+  const stages = workflow.stages.map(stage => {
+    try {
+      const assignment = selectWorkItemVp({
+        policy: stage.assignmentPolicy,
+        stageType: stage.type,
+        vps,
+        priorRuns: syntheticRuns,
+      });
+      const model = resolveWorkItemModel(config, assignment.vp, stage.modelPolicy);
+      syntheticRuns.push({
+        actionType: stage.type,
+        roleSnapshot: { actionType: stage.type },
+        vpSnapshot: { id: assignment.vp.id },
+      });
+      return {
+        id: stage.id,
+        name: stage.name,
+        type: stage.type,
+        assignmentPolicy: stage.assignmentPolicy,
+        modelPolicy: stage.modelPolicy,
+        selectedVp: publicVp(assignment.vp),
+        selectionReason: assignment.reason,
+        model: {
+          id: model.model,
+          provider: model.provider,
+          effort: model.effort,
+          source: model.source,
+        },
+        error: null,
+      };
+    } catch (error) {
+      return {
+        id: stage.id,
+        name: stage.name,
+        type: stage.type,
+        assignmentPolicy: stage.assignmentPolicy,
+        modelPolicy: stage.modelPolicy,
+        selectedVp: null,
+        selectionReason: null,
+        model: null,
+        error: error?.message || String(error),
+      };
+    }
+  });
+  return { workflow, stages, valid: stages.every(stage => !stage.error) };
+}

package/yeaft/work-center/projection.js

@@ -3,10 +3,104 @@ function currentAction(detail) {
   return detail.actions.find(action => action.id === detail.currentActionId) || null;
 }
 
+function projectAction(action) {
+  if (!action) return null;
+  return {
+    id: action.id,
+    workItemId: action.workItemId,
+    sequence: action.sequence,
+    type: action.type,
+    stageId: action.stageId || action.type,
+    assignmentPolicy: action.assignmentPolicy || null,
+    modelPolicy: action.modelPolicy || null,
+    requiredRole: action.requiredRole || '',
+    status: action.status,
+    attempt: action.attempt,
+    maxAttempts: action.maxAttempts,
+    currentRunId: action.currentRunId || null,
+    createdAt: action.createdAt,
+    updatedAt: action.updatedAt,
+  };
+}
+
+function projectRun(run) {
+  if (!run) return null;
+  return {
+    id: run.id,
+    actionId: run.actionId,
+    workItemId: run.workItemId,
+    status: run.status,
+    startedAt: run.startedAt,
+    expiresAt: run.expiresAt,
+    endedAt: run.endedAt || null,
+    summary: run.summary || '',
+    evidence: Array.isArray(run.evidence) ? run.evidence : [],
+    waitingReason: run.waitingReason || '',
+    error: run.error || '',
+    reviewDecision: run.reviewDecision || null,
+    roleSnapshot: run.roleSnapshot ? {
+      id: run.roleSnapshot.id,
+      actionType: run.roleSnapshot.actionType,
+      selectionReason: run.roleSnapshot.selectionReason,
+    } : null,
+    vpSnapshot: run.vpSnapshot ? {
+      id: run.vpSnapshot.id,
+      name: run.vpSnapshot.name || run.vpSnapshot.id,
+      nameZh: run.vpSnapshot.nameZh || '',
+      role: run.vpSnapshot.role || '',
+      roleZh: run.vpSnapshot.roleZh || '',
+    } : null,
+    modelSnapshot: run.modelSnapshot ? {
+      id: run.modelSnapshot.id,
+      provider: run.modelSnapshot.provider || null,
+      effort: run.modelSnapshot.effort || null,
+      source: run.modelSnapshot.source || null,
+    } : null,
+  };
+}
+
+function projectEvent(event) {
+  if (!event) return null;
+  return {
+    id: event.id,
+    workItemId: event.workItemId,
+    actionId: event.actionId || null,
+    runId: event.runId || null,
+    type: event.type,
+    createdAt: event.createdAt,
+  };
+}
+
+/**
+ * Authenticated browser detail DTO. Execution-only snapshots, VP persona,
+ * tool policy, prompts, event data, and local filesystem paths never cross the wire.
+ */
+export function projectWorkItemDetail(detail) {
+  if (!detail) return null;
+  return {
+    id: detail.id,
+    revision: detail.revision,
+    title: detail.title,
+    goal: detail.goal,
+    acceptanceCriteria: Array.isArray(detail.acceptanceCriteria) ? detail.acceptanceCriteria : [],
+    workflowTemplate: detail.workflowTemplate,
+    status: detail.status,
+    currentActionId: detail.currentActionId || null,
+    currentRunId: detail.currentRunId || null,
+    reuseMemory: detail.reuseMemory !== false,
+    origin: detail.origin?.sessionId ? { sessionId: detail.origin.sessionId } : null,
+    linkedSessionIds: Array.isArray(detail.linkedSessionIds) ? detail.linkedSessionIds : [],
+    createdAt: detail.createdAt,
+    updatedAt: detail.updatedAt,
+    actions: Array.isArray(detail.actions) ? detail.actions.map(projectAction) : [],
+    runs: Array.isArray(detail.runs) ? detail.runs.map(projectRun) : [],
+    events: Array.isArray(detail.events) ? detail.events.map(projectEvent) : [],
+  };
+}
+
 /**
  * Browser event projection. This deliberately excludes local filesystem paths,
  * Run evidence/tool output, prompts, model snapshots, and execution errors.
- * Clients fetch the selected detail explicitly through the authenticated get op.
  */
 export function projectWorkItemSummary(detail) {
   if (!detail) return null;
@@ -36,7 +130,8 @@ export function projectWorkItemSummary(detail) {
     currentAction: action ? {
       id: action.id,
       type: action.type,
-      requiredRole: action.requiredRole,
+      stageId: action.stageId || action.type,
+      assignmentMode: action.assignmentPolicy?.mode || (action.requiredRole ? 'fixed' : null),
       status: action.status,
     } : null,
     origin: detail.origin?.sessionId ? { sessionId: detail.origin.sessionId } : null,

package/yeaft/work-center/runner.js

@@ -5,6 +5,7 @@ import { parsePatch } from '../tools/apply-patch.js';
 import { defaultRegistry } from '../vp/registry.js';
 import { NullTrace } from '../debug-trace.js';
 import { isPathInsideOrEqual } from '../tools/path-safety.js';
+import { resolveWorkItemModel, selectWorkItemVp } from './assignment.js';
 import { existsSync, lstatSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 
@@ -203,12 +204,6 @@ function completionContract(action) {
 }\nA model turn ending is not completion. Use waiting when user or external input is required. Use retryable only for a transient failure. Do not start background jobs or delegate this Action.`;
 }
 
-function resolveModel(config, vp) {
-  if (vp.modelHint === 'fast' && config.fastModel) return config.fastModel;
-  if (vp.modelHint === 'primary' && config.primaryModel) return config.primaryModel;
-  return config.model || config.primaryModel || null;
-}
-
 export class WorkItemRunner {
   constructor(options) {
     this.runtimeProvider = options.runtimeProvider;
@@ -219,20 +214,38 @@ export class WorkItemRunner {
   async run({ workItem, action, run, signal, ownerBootId }) {
     const runtime = await this.runtimeProvider();
     const workDir = resolveWorkItemWorkDir(workItem, runtime.defaultWorkDir);
-    const vp = copyVp(this.registry.getVp(action.requiredRole));
+    const priorRuns = this.store.listCompletedRuns(workItem.id);
+    const assignment = action.assignmentPolicy
+      ? selectWorkItemVp({
+          policy: action.assignmentPolicy,
+          stageType: action.type,
+          vps: this.registry.listVps(),
+          priorRuns,
+        })
+      : {
+          vp: this.registry.getVp(action.requiredRole),
+          reason: `legacy-fixed:${action.requiredRole}`,
+          policy: { mode: 'fixed', fixedVpId: action.requiredRole },
+        };
+    const vp = copyVp(assignment.vp);
     if (!vp) {
-      const error = new Error(`Required Work Center role is unavailable: ${action.requiredRole}`);
+      const error = new Error(`Required Work Center VP is unavailable: ${action.requiredRole || '(unassigned)'}`);
       error.retryable = false;
       throw error;
     }
+    const resolvedModel = resolveWorkItemModel(runtime.config, vp, action.modelPolicy);
     const isRunActive = () => !signal.aborted
       && this.store.isActiveRun(run.id, ownerBootId, run.leaseEpoch);
     const toolPolicySnapshot = workItemToolPolicySnapshot(workDir);
     const toolRegistry = createWorkItemToolRegistry({ workDir, isRunActive });
-    const model = resolveModel(runtime.config, vp);
     const config = {
       ...runtime.config,
-      model,
+      model: resolvedModel.model,
+      // WorkItem model policy is part of the frozen execution contract. The
+      // Agent-level fallback would silently execute a different model while
+      // leaving the Run snapshot unchanged, so WorkItems must fail explicitly.
+      fallbackModel: null,
+      ...(resolvedModel.effort ? { modelEffort: resolvedModel.effort } : {}),
       _readOnly: true,
       serverMode: true,
       // WorkItem messages live in the Work Center DB. Never archive their
@@ -247,9 +260,20 @@ export class WorkItemRunner {
       ownerBootId,
       run.leaseEpoch,
       {
-        roleSnapshot: { id: action.requiredRole, actionType: action.type },
+        roleSnapshot: {
+          id: action.stageId || action.type,
+          actionType: action.type,
+          assignmentPolicy: assignment.policy,
+          selectionReason: assignment.reason,
+        },
         vpSnapshot: vp,
-        modelSnapshot: { id: model, provider: runtime.config.provider || null },
+        modelSnapshot: {
+          id: resolvedModel.model,
+          provider: resolvedModel.provider,
+          effort: resolvedModel.effort,
+          source: resolvedModel.source,
+          policy: resolvedModel.policy,
+        },
         toolPolicySnapshot,
       },
     );

package/yeaft/work-center/service.js

@@ -3,7 +3,9 @@ import { randomUUID } from 'node:crypto';
 import { WorkItemStore } from './store.js';
 import { WorkflowController } from './controller.js';
 import { WorkItemWatcher } from './watcher.js';
-import { projectWorkItemSummary } from './projection.js';
+import { projectWorkItemDetail, projectWorkItemSummary } from './projection.js';
+import { readWorkCenterSettings, writeWorkCenterSettings } from './settings.js';
+import { resolveWorkflowSnapshot } from './workflow.js';
 
 function requiredString(value, name) {
   if (typeof value !== 'string' || !value.trim()) throw new Error(`${name} is required`);
@@ -13,6 +15,12 @@ function requiredString(value, name) {
 export class WorkCenterService {
   constructor(options) {
     const yeaftDir = requiredString(options?.yeaftDir, 'yeaftDir');
+    this.yeaftDir = yeaftDir;
+    this.settingsReader = options.settingsReader || readWorkCenterSettings;
+    this.settingsWriter = options.settingsWriter || writeWorkCenterSettings;
+    this.runtimeInfoProvider = typeof options.runtimeInfoProvider === 'function'
+      ? options.runtimeInfoProvider
+      : async () => ({ vps: [], models: [], primaryModel: null, fastModel: null });
     this.ownerBootId = options.ownerBootId || randomUUID();
     this.store = options.store || new WorkItemStore(join(yeaftDir, 'work-center', 'work-center.db'));
     this.controller = options.controller || new WorkflowController(this.store);
@@ -37,16 +45,32 @@ export class WorkCenterService {
           watcher: this.watcher.status(),
         };
       case 'get':
-        return this.#requiredItem(payload.id);
+        return projectWorkItemDetail(this.#requiredItem(payload.id));
+      case 'get_settings': {
+        const settings = this.settingsReader(this.yeaftDir);
+        return { settings, runtime: await this.runtimeInfoProvider() };
+      }
+      case 'update_settings': {
+        const settings = this.settingsWriter(this.yeaftDir, payload.settings);
+        return { settings, runtime: await this.runtimeInfoProvider() };
+      }
       case 'create': {
+        const settings = this.settingsReader(this.yeaftDir);
+        const workflowTemplate = typeof payload.workflowTemplate === 'string' && payload.workflowTemplate.trim()
+          ? payload.workflowTemplate.trim()
+          : settings.defaultWorkflowId;
+        const workflowSnapshot = resolveWorkflowSnapshot(settings, workflowTemplate, payload.stageOverrides);
         const item = this.controller.create({
           title: requiredString(payload.title, 'title'),
           goal: requiredString(payload.goal, 'goal'),
           acceptanceCriteria: Array.isArray(payload.acceptanceCriteria)
             ? payload.acceptanceCriteria.map(value => String(value).trim()).filter(Boolean)
             : [],
-          workflowTemplate: payload.workflowTemplate || 'software-change',
-          workDir: typeof payload.workDir === 'string' ? payload.workDir.trim() : '',
+          workflowTemplate,
+          workflowSnapshot,
+          workDir: typeof payload.workDir === 'string' && payload.workDir.trim()
+            ? payload.workDir.trim()
+            : settings.defaultWorkDir,
           reuseMemory: payload.reuseMemory !== false,
           origin: payload.origin && typeof payload.origin === 'object'
             ? {
@@ -58,7 +82,7 @@ export class WorkCenterService {
           linkedSessionIds: Array.isArray(payload.linkedSessionIds)
             ? [...new Set(payload.linkedSessionIds.map(value => String(value).trim()).filter(Boolean))]
             : [],
-          start: payload.start !== false,
+          start: payload.start === undefined ? settings.startImmediately : payload.start !== false,
         });
         const detail = this.#requiredItem(item.id);
         this.#emit({ type: 'work_item.created', workItem: detail });

package/yeaft/work-center/settings.js

@@ -0,0 +1,59 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { writeAtomic } from '../storage/atomic.js';
+import { defaultWorkCenterSettings, normalizeWorkCenterSettings } from './workflow.js';
+
+export const WORK_CENTER_SETTINGS_FILE = 'settings.json';
+const SETTINGS_LOCK_TIMEOUT_MS = 5_000;
+
+function settingsPath(yeaftDir) {
+  return join(yeaftDir, 'work-center', WORK_CENTER_SETTINGS_FILE);
+}
+
+function withSettingsTransaction(yeaftDir, fn) {
+  const dir = dirname(settingsPath(yeaftDir));
+  mkdirSync(dir, { recursive: true });
+  const db = new DatabaseSync(join(dir, 'work-center.db'), { timeout: SETTINGS_LOCK_TIMEOUT_MS });
+  let transactionOpen = false;
+  try {
+    db.exec(`PRAGMA busy_timeout = ${SETTINGS_LOCK_TIMEOUT_MS};`);
+    db.exec('BEGIN IMMEDIATE');
+    transactionOpen = true;
+    const result = fn();
+    db.exec('COMMIT');
+    transactionOpen = false;
+    return result;
+  } catch (error) {
+    if (transactionOpen) {
+      try { db.exec('ROLLBACK'); } catch {}
+    }
+    throw error;
+  } finally {
+    db.close();
+  }
+}
+
+export function readWorkCenterSettings(yeaftDir) {
+  const file = settingsPath(yeaftDir);
+  if (!existsSync(file)) return defaultWorkCenterSettings();
+  try {
+    return normalizeWorkCenterSettings(JSON.parse(readFileSync(file, 'utf8')));
+  } catch (error) {
+    throw new Error(`Failed to read Work Center settings: ${error.message}`);
+  }
+}
+
+export function writeWorkCenterSettings(yeaftDir, value) {
+  return withSettingsTransaction(yeaftDir, () => {
+    const current = readWorkCenterSettings(yeaftDir);
+    const expectedRevision = Number(value?.revision);
+    if (!Number.isInteger(expectedRevision) || expectedRevision !== current.revision) {
+      throw new Error('Work Center settings changed elsewhere; reload before saving');
+    }
+    const normalized = normalizeWorkCenterSettings({ ...value, revision: current.revision + 1 });
+    const file = settingsPath(yeaftDir);
+    writeAtomic(file, `${JSON.stringify(normalized, null, 2)}\n`);
+    return normalized;
+  });
+}

package/yeaft/work-center/store.js

@@ -31,6 +31,7 @@ function mapWorkItem(row) {
     goal: row.goal,
     acceptanceCriteria: parseJson(row.acceptance_criteria, []),
     workflowTemplate: row.workflow_template,
+    workflowSnapshot: parseJson(row.workflow_snapshot, null),
     status: row.status,
     currentActionId: row.current_action_id || null,
     currentRunId: row.current_run_id || null,
@@ -51,7 +52,10 @@ function mapAction(row) {
     workItemId: row.work_item_id,
     sequence: row.sequence,
     type: row.type,
-    requiredRole: row.required_role,
+    stageId: row.stage_id || row.type,
+    assignmentPolicy: parseJson(row.assignment_policy, null),
+    modelPolicy: parseJson(row.model_policy, null),
+    requiredRole: row.required_role || '',
     instruction: row.instruction,
     context: parseJson(row.context, []),
     contractRevision: row.contract_revision,
@@ -146,6 +150,7 @@ export class WorkItemStore {
         goal TEXT NOT NULL,
         acceptance_criteria TEXT NOT NULL,
         workflow_template TEXT NOT NULL,
+        workflow_snapshot TEXT,
         status TEXT NOT NULL,
         current_action_id TEXT,
         current_run_id TEXT,
@@ -163,6 +168,9 @@ export class WorkItemStore {
         sequence INTEGER NOT NULL,
         type TEXT NOT NULL,
         required_role TEXT NOT NULL,
+        stage_id TEXT,
+        assignment_policy TEXT,
+        model_policy TEXT,
         instruction TEXT NOT NULL,
         context TEXT NOT NULL DEFAULT '[]',
         contract_revision INTEGER NOT NULL DEFAULT 1,
@@ -241,6 +249,18 @@ export class WorkItemStore {
     if (!hasColumn(this.db, 'runs', 'contract_patch')) {
       this.db.exec('ALTER TABLE runs ADD COLUMN contract_patch TEXT');
     }
+    if (!hasColumn(this.db, 'work_items', 'workflow_snapshot')) {
+      this.db.exec('ALTER TABLE work_items ADD COLUMN workflow_snapshot TEXT');
+    }
+    if (!hasColumn(this.db, 'actions', 'stage_id')) {
+      this.db.exec('ALTER TABLE actions ADD COLUMN stage_id TEXT');
+    }
+    if (!hasColumn(this.db, 'actions', 'assignment_policy')) {
+      this.db.exec('ALTER TABLE actions ADD COLUMN assignment_policy TEXT');
+    }
+    if (!hasColumn(this.db, 'actions', 'model_policy')) {
+      this.db.exec('ALTER TABLE actions ADD COLUMN model_policy TEXT');
+    }
     this.db.prepare(`INSERT INTO schema_meta(key, value) VALUES('schema_version', ?)
       ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(String(SCHEMA_VERSION));
   }
@@ -269,15 +289,16 @@ export class WorkItemStore {
       const id = input.id || randomUUID();
       const workspaceKey = canonicalWorkspaceKey(input.workDir);
       this.db.prepare(`INSERT INTO work_items
-        (id, revision, title, goal, acceptance_criteria, workflow_template, status,
+        (id, revision, title, goal, acceptance_criteria, workflow_template, workflow_snapshot, status,
          current_action_id, current_run_id, work_dir, workspace_key, reuse_memory, origin, linked_session_ids,
          created_at, updated_at)
-        VALUES (?, 1, ?, ?, ?, ?, ?, NULL, NULL, ?, ?, ?, ?, ?, ?, ?)`).run(
+        VALUES (?, 1, ?, ?, ?, ?, ?, ?, NULL, NULL, ?, ?, ?, ?, ?, ?, ?)`).run(
         id,
         input.title,
         input.goal,
         stringify(input.acceptanceCriteria || []),
         input.workflowTemplate || 'software-change',
+        stringify(input.workflowSnapshot || null),
         firstAction ? 'ready' : 'draft',
         input.workDir || '',
         workspaceKey,
@@ -303,7 +324,10 @@ export class WorkItemStore {
       workItemId,
       sequence,
       type: input.type,
-      requiredRole: input.requiredRole,
+      stageId: input.stageId || input.type,
+      assignmentPolicy: input.assignmentPolicy || null,
+      modelPolicy: input.modelPolicy || null,
+      requiredRole: input.requiredRole || '',
       instruction: input.instruction || '',
       context: Array.isArray(input.context) ? input.context : [],
       contractRevision: Number.isInteger(input.contractRevision) ? input.contractRevision : 1,
@@ -316,15 +340,18 @@ export class WorkItemStore {
       updatedAt: now,
     };
     this.db.prepare(`INSERT INTO actions
-      (id, work_item_id, sequence, type, required_role, instruction, context,
-       contract_revision, status, attempt, max_attempts, current_run_id, lease_epoch,
-       created_at, updated_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, 0, ?, ?)`).run(
+      (id, work_item_id, sequence, type, required_role, stage_id, assignment_policy, model_policy,
+       instruction, context, contract_revision, status, attempt, max_attempts, current_run_id,
+       lease_epoch, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, 0, ?, ?)`).run(
       action.id,
       workItemId,
       action.sequence,
       action.type,
       action.requiredRole,
+      action.stageId,
+      stringify(action.assignmentPolicy),
+      stringify(action.modelPolicy),
       action.instruction,
       stringify(action.context),
       action.contractRevision,
@@ -358,6 +385,16 @@ export class WorkItemStore {
     return mapRun(this.db.prepare('SELECT * FROM runs WHERE id = ?').get(id));
   }
 
+  listCompletedRuns(workItemId) {
+    return this.db.prepare(`SELECT r.*, a.type AS action_type FROM runs r
+      JOIN actions a ON a.id = r.action_id
+      WHERE r.work_item_id = ? AND r.status != 'running'
+      ORDER BY r.started_at ASC`).all(workItemId).map(row => ({
+        ...mapRun(row),
+        actionType: row.action_type,
+      }));
+  }
+
   listWorkItems(filters = {}) {
     const where = [];
     const values = [];

package/yeaft/work-center/workflow.js

@@ -1,13 +1,35 @@
-const SOFTWARE_CHANGE_STEPS = Object.freeze([
-  { type: 'triage', requiredRole: 'omni' },
-  { type: 'implement', requiredRole: 'linus' },
-  { type: 'review', requiredRole: 'martin' },
-  { type: 'deliver', requiredRole: 'linus' },
-]);
+const STAGE_TYPES = new Set(['triage', 'implement', 'test', 'review', 'deliver', 'research', 'write', 'custom']);
+const ASSIGNMENT_MODES = new Set(['auto', 'pool', 'fixed']);
+const MODEL_MODES = new Set(['inherit', 'primary', 'fast', 'specific']);
+const MODEL_EFFORTS = new Set(['minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
 
-export const WORKFLOW_TEMPLATES = Object.freeze({
-  'software-change': SOFTWARE_CHANGE_STEPS,
-});
+const DEFAULT_SOFTWARE_CHANGE_STAGES = Object.freeze([
+  {
+    id: 'triage', name: 'Triage', type: 'triage',
+    assignmentPolicy: { mode: 'auto', capability: 'triage', candidateVpIds: [], fixedVpId: null, separateFromStageTypes: [] },
+    modelPolicy: { mode: 'inherit', model: null, effort: null },
+    maxAttempts: 2,
+  },
+  {
+    id: 'implement', name: 'Implement', type: 'implement',
+    assignmentPolicy: { mode: 'auto', capability: 'implement', candidateVpIds: [], fixedVpId: null, separateFromStageTypes: [] },
+    modelPolicy: { mode: 'inherit', model: null, effort: null },
+    maxAttempts: 2,
+  },
+  {
+    id: 'review', name: 'Review', type: 'review',
+    assignmentPolicy: { mode: 'auto', capability: 'review', candidateVpIds: [], fixedVpId: null, separateFromStageTypes: ['implement'] },
+    modelPolicy: { mode: 'inherit', model: null, effort: null },
+    maxAttempts: 2,
+    changesRequestedStageId: 'implement',
+  },
+  {
+    id: 'deliver', name: 'Deliver', type: 'deliver',
+    assignmentPolicy: { mode: 'auto', capability: 'deliver', candidateVpIds: [], fixedVpId: null, separateFromStageTypes: [] },
+    modelPolicy: { mode: 'inherit', model: null, effort: null },
+    maxAttempts: 2,
+  },
+]);
 
 export const RUN_OUTCOMES = Object.freeze([
   'completed',
@@ -16,23 +38,204 @@ export const RUN_OUTCOMES = Object.freeze([
   'failed',
 ]);
 
-export function getWorkflowSteps(template = 'software-change') {
-  const steps = WORKFLOW_TEMPLATES[template];
-  if (!steps) throw new Error(`Unsupported Work Center workflow: ${template}`);
-  return steps;
+function cleanId(value, fallback) {
+  const normalized = String(value || '').trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
+  return normalized || fallback;
+}
+
+function uniqueStrings(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.map(item => String(item || '').trim()).filter(Boolean))];
+}
+
+export function normalizeAssignmentPolicy(value, stageType = 'custom') {
+  const source = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  const mode = ASSIGNMENT_MODES.has(source.mode) ? source.mode : 'auto';
+  const fixedVpId = typeof source.fixedVpId === 'string' && source.fixedVpId.trim()
+    ? source.fixedVpId.trim()
+    : null;
+  const candidateVpIds = uniqueStrings(source.candidateVpIds);
+  if (mode === 'fixed' && !fixedVpId) throw new Error('Fixed Work Center assignment requires fixedVpId');
+  if (mode === 'pool' && candidateVpIds.length === 0) throw new Error('Work Center VP pool cannot be empty');
+  return {
+    mode,
+    capability: cleanId(source.capability, stageType),
+    candidateVpIds,
+    fixedVpId,
+    separateFromStageTypes: uniqueStrings(source.separateFromStageTypes),
+  };
+}
+
+export function normalizeModelPolicy(value) {
+  const source = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  const mode = MODEL_MODES.has(source.mode) ? source.mode : 'inherit';
+  const model = typeof source.model === 'string' && source.model.trim() ? source.model.trim() : null;
+  const effort = MODEL_EFFORTS.has(source.effort) ? source.effort : null;
+  if (mode === 'specific' && !model) throw new Error('Specific Work Center model policy requires a model');
+  return { mode, model, effort };
+}
+
+export function normalizeWorkflowDefinition(value, index = 0) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Work Center workflow must be an object');
+  }
+  const id = cleanId(value.id, `workflow-${index + 1}`);
+  const name = String(value.name || id).trim() || id;
+  if (!Array.isArray(value.stages) || value.stages.length === 0) {
+    throw new Error(`Work Center workflow "${id}" requires at least one stage`);
+  }
+  const seen = new Set();
+  const stages = value.stages.map((rawStage, stageIndex) => {
+    const source = rawStage && typeof rawStage === 'object' ? rawStage : {};
+    const type = STAGE_TYPES.has(source.type) ? source.type : 'custom';
+    const stageId = cleanId(source.id, `${type}-${stageIndex + 1}`);
+    if (seen.has(stageId)) throw new Error(`Duplicate Work Center stage id: ${stageId}`);
+    seen.add(stageId);
+    const stage = {
+      id: stageId,
+      name: String(source.name || stageId).trim() || stageId,
+      type,
+      instruction: typeof source.instruction === 'string' ? source.instruction.trim() : '',
+      assignmentPolicy: normalizeAssignmentPolicy(source.assignmentPolicy, type),
+      modelPolicy: normalizeModelPolicy(source.modelPolicy),
+      maxAttempts: Math.min(Math.max(Number(source.maxAttempts) || 2, 1), 5),
+    };
+    if (type === 'review') {
+      stage.changesRequestedStageId = cleanId(source.changesRequestedStageId, 'implement');
+    }
+    return stage;
+  });
+  for (const [stageIndex, stage] of stages.entries()) {
+    if (stage.type !== 'review') continue;
+    const targetIndex = stages.findIndex(candidate => candidate.id === stage.changesRequestedStageId);
+    if (targetIndex === -1) {
+      throw new Error(`Review stage "${stage.id}" points to missing stage "${stage.changesRequestedStageId}"`);
+    }
+    const target = stages[targetIndex];
+    if (targetIndex >= stageIndex || target.type === 'review' || target.type === 'deliver') {
+      throw new Error(`Review stage "${stage.id}" must return to an earlier editable stage`);
+    }
+  }
+  return { version: 1, id, name, stages };
+}
+
+export function defaultWorkCenterSettings() {
+  return {
+    version: 1,
+    revision: 1,
+    defaultWorkflowId: 'software-change',
+    startImmediately: true,
+    defaultWorkDir: '',
+    workflows: [normalizeWorkflowDefinition({
+      id: 'software-change',
+      name: 'Software change',
+      stages: DEFAULT_SOFTWARE_CHANGE_STAGES,
+    })],
+  };
 }
 
-export function getStep(template, type) {
-  return getWorkflowSteps(template).find(step => step.type === type) || null;
+export function normalizeWorkCenterSettings(value) {
+  const defaults = defaultWorkCenterSettings();
+  const source = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  const workflows = Array.isArray(source.workflows) && source.workflows.length > 0
+    ? source.workflows.map(normalizeWorkflowDefinition)
+    : defaults.workflows;
+  const workflowIds = new Set();
+  for (const workflow of workflows) {
+    if (workflowIds.has(workflow.id)) throw new Error(`Duplicate Work Center workflow id: ${workflow.id}`);
+    workflowIds.add(workflow.id);
+  }
+  const defaultWorkflowId = workflowIds.has(source.defaultWorkflowId)
+    ? source.defaultWorkflowId
+    : workflows[0].id;
+  const revision = Number.isInteger(source.revision) && source.revision > 0 ? source.revision : 1;
+  return {
+    version: 1,
+    revision,
+    defaultWorkflowId,
+    startImmediately: source.startImmediately !== false,
+    defaultWorkDir: typeof source.defaultWorkDir === 'string' ? source.defaultWorkDir.trim() : '',
+    workflows,
+  };
 }
 
-export function getNextStep(template, type, result = {}) {
-  const steps = getWorkflowSteps(template);
-  const index = steps.findIndex(step => step.type === type);
-  if (index === -1) throw new Error(`Action type ${type} is not in workflow ${template}`);
-  if (type === 'review') {
+export function resolveWorkflowSnapshot(settings, workflowId, stageOverrides = {}) {
+  const normalized = normalizeWorkCenterSettings(settings);
+  const id = workflowId || normalized.defaultWorkflowId;
+  const workflow = normalized.workflows.find(item => item.id === id);
+  if (!workflow) throw new Error(`Unsupported Work Center workflow: ${id}`);
+  const overrides = stageOverrides && typeof stageOverrides === 'object' && !Array.isArray(stageOverrides)
+    ? stageOverrides
+    : {};
+  return normalizeWorkflowDefinition({
+    ...workflow,
+    stages: workflow.stages.map(stage => {
+      const override = overrides[stage.id];
+      if (!override || typeof override !== 'object' || Array.isArray(override)) return stage;
+      return {
+        ...stage,
+        assignmentPolicy: override.assignmentPolicy
+          ? { ...stage.assignmentPolicy, ...override.assignmentPolicy }
+          : stage.assignmentPolicy,
+        modelPolicy: override.modelPolicy
+          ? { ...stage.modelPolicy, ...override.modelPolicy }
+          : stage.modelPolicy,
+      };
+    }),
+  });
+}
+
+const LEGACY_SOFTWARE_CHANGE_VPS = Object.freeze({
+  triage: 'omni',
+  implement: 'linus',
+  review: 'martin',
+  deliver: 'linus',
+});
+
+function workflowFrom(source = 'software-change') {
+  if (source && typeof source === 'object' && source.workflowSnapshot?.stages) {
+    return normalizeWorkflowDefinition(source.workflowSnapshot);
+  }
+  if (source && typeof source === 'object' && source.stages) return normalizeWorkflowDefinition(source);
+  const settings = defaultWorkCenterSettings();
+  const workflow = resolveWorkflowSnapshot(settings, typeof source === 'string' ? source : 'software-change');
+  // Existing WorkItems did not persist a workflow snapshot. Preserve their
+  // historical deterministic assignments; only newly created WorkItems use
+  // pool selection. This avoids silently changing in-flight durable work.
+  return {
+    ...workflow,
+    stages: workflow.stages.map(stage => ({
+      ...stage,
+      assignmentPolicy: {
+        ...stage.assignmentPolicy,
+        mode: 'fixed',
+        fixedVpId: LEGACY_SOFTWARE_CHANGE_VPS[stage.type],
+      },
+    })),
+  };
+}
+
+export function getWorkflowSteps(source = 'software-change') {
+  return workflowFrom(source).stages;
+}
+
+export function getStep(source, stageIdOrType) {
+  return getWorkflowSteps(source).find(stage => stage.id === stageIdOrType)
+    || getWorkflowSteps(source).find(stage => stage.type === stageIdOrType)
+    || null;
+}
+
+export function getNextStep(source, stageIdOrType, result = {}) {
+  const steps = getWorkflowSteps(source);
+  const index = steps.findIndex(stage => stage.id === stageIdOrType)
+    !== -1
+    ? steps.findIndex(stage => stage.id === stageIdOrType)
+    : steps.findIndex(stage => stage.type === stageIdOrType);
+  if (index === -1) throw new Error(`Work Center stage ${stageIdOrType} is not in the workflow snapshot`);
+  const current = steps[index];
+  if (current.type === 'review') {
     if (result.reviewDecision === 'changes_requested') {
-      return steps.find(step => step.type === 'implement') || null;
+      return steps.find(stage => stage.id === current.changesRequestedStageId) || null;
     }
     if (result.reviewDecision !== 'approved') {
       throw new Error('Completed review requires approved or changes_requested');
@@ -55,44 +258,61 @@ function renderContext(context = []) {
     const waitingReason = entry.waitingReason ? `\nWaiting reason: ${entry.waitingReason}` : '';
     const answer = entry.answer ? `\nUser answer: ${entry.answer}` : '';
     const source = entry.sourceTitle ? ` from ${entry.sourceTitle}` : '';
-    return `### ${entry.type}${source} (${entry.role || 'unknown role'})\n${entry.summary || '(no summary)'}${decision}${waitingReason}${answer}${evidence}`;
+    return `### ${entry.type}${source} (${entry.vpId || entry.role || 'unknown VP'})\n${entry.summary || '(no summary)'}${decision}${waitingReason}${answer}${evidence}`;
   });
   return `\n\nReusable Work Center context and prior Action results:\n${blocks.join('\n\n')}`;
 }
 
-export function actionInstruction(step, workItem, context = []) {
+export function actionInstruction(stage, workItem, context = []) {
   const criteria = (workItem.acceptanceCriteria || []).map(item => `- ${item}`).join('\n') || '- No explicit criteria';
   const common = `WorkItem: ${workItem.title}\nGoal: ${workItem.goal}\nAcceptance criteria:\n${criteria}${renderContext(context)}`;
-  switch (step.type) {
+  if (stage.instruction) return `${common}\n\n${stage.instruction}`;
+  switch (stage.type) {
     case 'triage':
       return `${common}\n\nAnalyze the request, verify scope and risks, and make the contract executable. Do not implement yet. If the goal or acceptance criteria need refinement, submit a contractPatch.`;
     case 'implement':
       return `${common}\n\nImplement the smallest correct change in the supplied work directory. Add and run relevant tests. Use the prior triage/review findings. Do not approve your own work.`;
+    case 'test':
+      return `${common}\n\nVerify the implementation against the acceptance criteria. Run focused tests and report reproducible evidence. Do not modify unrelated code.`;
     case 'review':
       return `${common}\n\nReview the implementation and evidence independently. Return approved or changes_requested with concrete findings.`;
     case 'deliver':
       return `${common}\n\nDeliver the approved change using the repository release policy. Verify the final remote state and provide evidence.`;
+    case 'research':
+      return `${common}\n\nResearch the question using verifiable sources. Separate evidence from inference and return a concise synthesis.`;
+    case 'write':
+      return `${common}\n\nProduce the requested written deliverable, then verify it against every acceptance criterion.`;
     default:
-      return common;
+      return `${common}\n\nComplete this stage and return verifiable evidence.`;
   }
 }
 
-export function initialActionFor(workItem) {
-  const step = getWorkflowSteps(workItem.workflowTemplate)[0];
+export function actionForStage(stage, workItem, context = []) {
   return {
-    ...step,
-    context: [],
-    instruction: actionInstruction(step, workItem, []),
-    maxAttempts: 2,
+    type: stage.type,
+    stageId: stage.id,
+    assignmentPolicy: stage.assignmentPolicy,
+    modelPolicy: stage.modelPolicy,
+    // Storage compatibility for databases created before assignment policies.
+    requiredRole: stage.assignmentPolicy.mode === 'fixed' ? stage.assignmentPolicy.fixedVpId : '',
+    context,
+    instruction: actionInstruction(stage, workItem, context),
+    maxAttempts: stage.maxAttempts,
   };
 }
 
+export function initialActionFor(workItem) {
+  const stage = getWorkflowSteps(workItem)[0];
+  return actionForStage(stage, workItem, []);
+}
+
 export function actionContextFromRuns(runs = []) {
   return runs
     .filter(run => run && run.summary)
     .map(run => ({
       type: run.actionType || 'action',
-      role: run.roleSnapshot?.id || run.vpSnapshot?.id || null,
+      vpId: run.vpSnapshot?.id || null,
+      role: run.roleSnapshot?.id || null,
       summary: run.summary,
       evidence: Array.isArray(run.evidence) ? run.evidence : [],
       reviewDecision: run.reviewDecision || null,