@yeaft/webchat-agent 1.0.129 → 1.0.131

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';
 
@@ -54,6 +55,21 @@ function canonicalWorkDir(workDir) {
   return realpathSync(workDir);
 }
 
+export function resolveWorkItemWorkDir(workItem, defaultWorkDir) {
+  if (typeof workItem?.workspaceKey === 'string' && workItem.workspaceKey) {
+    const expected = path.resolve(workItem.workspaceKey);
+    const actual = canonicalWorkDir(expected);
+    if (actual !== expected) {
+      throw new Error('WorkItem canonical workspace identity changed; update its workDir before retrying');
+    }
+    return expected;
+  }
+  if (typeof workItem?.workDir === 'string' && workItem.workDir.trim()) {
+    throw new Error('WorkItem has no canonical workspace identity; update its workDir before retrying');
+  }
+  return canonicalWorkDir(path.resolve(defaultWorkDir || process.cwd()));
+}
+
 function assertPathInside(toolName, workDir, value) {
   const resolved = path.resolve(workDir, value);
   if (!isPathInsideOrEqual(workDir, resolved)) {
@@ -188,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;
@@ -203,22 +213,39 @@ export class WorkItemRunner {
 
   async run({ workItem, action, run, signal, ownerBootId }) {
     const runtime = await this.runtimeProvider();
-    const rawWorkDir = workItem.workDir || runtime.defaultWorkDir || process.cwd();
-    const workDir = canonicalWorkDir(path.resolve(rawWorkDir));
-    const vp = copyVp(this.registry.getVp(action.requiredRole));
+    const workDir = resolveWorkItemWorkDir(workItem, runtime.defaultWorkDir);
+    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
@@ -233,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,
       },
     );
@@ -260,7 +298,6 @@ export class WorkItemRunner {
     });
 
     let text = '';
-    const toolEvidence = [];
     try {
       for await (const event of engine.query({
         prompt: `${action.instruction}${completionContract(action)}`,
@@ -275,18 +312,10 @@ export class WorkItemRunner {
         if (typeof event?.text === 'string') text += event.text;
         else if (typeof event?.delta === 'string') text += event.delta;
         else if (typeof event?.content === 'string' && event.type === 'assistant') text += event.content;
-        if (event?.type === 'tool_end') {
-          toolEvidence.push({
-            tool: event.name,
-            isError: !!event.isError,
-          });
-        }
       }
     } finally {
       try { engine.abort?.('work_item_run_finished'); } catch {}
     }
-    const result = parseStructuredResult(text, action.type);
-    result.evidence = [...result.evidence, ...toolEvidence].slice(-100);
-    return result;
+    return parseStructuredResult(text, action.type);
   }
 }

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,33 @@ 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'
             ? {
                 sessionId: typeof payload.origin.sessionId === 'string' ? payload.origin.sessionId : null,
@@ -57,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 });
@@ -82,6 +107,17 @@ export class WorkCenterService {
         this.#emit({ type: 'work_item.cancelled', workItem: detail });
         return detail;
       }
+      case 'guide': {
+        const id = requiredString(payload.id, 'id');
+        const detail = this.controller.guide(id, {
+          guidance: typeof payload.guidance === 'string' ? payload.guidance : '',
+          actionId: typeof payload.actionId === 'string' ? payload.actionId : '',
+          revision: payload.revision,
+        });
+        this.watcher.abortInvalidWorkItemRuns(id);
+        this.#emit({ type: 'action.guidance_added', workItem: detail });
+        return detail;
+      }
       case 'retry': {
         const detail = this.controller.retry(requiredString(payload.id, 'id'), {
           answer: typeof payload.answer === 'string' ? payload.answer : '',

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

@@ -1,11 +1,17 @@
 import { DatabaseSync } from 'node:sqlite';
-import { mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { mkdirSync, realpathSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { normalizeEvidence } from './evidence.js';
 
-const SCHEMA_VERSION = 2;
+const SCHEMA_VERSION = 3;
 const OPEN_ACTION_STATUSES = "'ready','running','waiting'";
+const MAX_REUSABLE_CONTEXT_ITEMS = 12;
+
+function canonicalWorkspaceKey(workDir) {
+  if (typeof workDir !== 'string' || !workDir.trim()) return '';
+  try { return realpathSync(resolve(workDir.trim())); } catch { return ''; }
+}
 
 function parseJson(value, fallback) {
   if (typeof value !== 'string' || !value) return fallback;
@@ -25,10 +31,13 @@ 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,
     workDir: row.work_dir || '',
+    workspaceKey: row.workspace_key || '',
+    reuseMemory: row.reuse_memory !== 0,
     origin: parseJson(row.origin, null),
     linkedSessionIds: parseJson(row.linked_session_ids, []),
     createdAt: row.created_at,
@@ -43,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,
@@ -138,10 +150,13 @@ 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,
         work_dir TEXT NOT NULL DEFAULT '',
+        workspace_key TEXT NOT NULL DEFAULT '',
+        reuse_memory INTEGER NOT NULL DEFAULT 1,
         origin TEXT,
         linked_session_ids TEXT NOT NULL DEFAULT '[]',
         created_at INTEGER NOT NULL,
@@ -153,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,
@@ -202,7 +220,20 @@ export class WorkItemStore {
     `);
 
     // The feature shipped first as an unmerged PR, but keep the store tolerant
-    // of a v1 database created by a review build.
+    // of databases created by review builds.
+    if (!hasColumn(this.db, 'work_items', 'workspace_key')) {
+      withTransaction(this.db, () => {
+        this.db.exec("ALTER TABLE work_items ADD COLUMN workspace_key TEXT NOT NULL DEFAULT ''");
+        const update = this.db.prepare('UPDATE work_items SET workspace_key = ? WHERE id = ?');
+        for (const row of this.db.prepare("SELECT id, work_dir FROM work_items WHERE work_dir != ''").all()) {
+          const workspaceKey = canonicalWorkspaceKey(row.work_dir);
+          if (workspaceKey) update.run(workspaceKey, row.id);
+        }
+      });
+    }
+    if (!hasColumn(this.db, 'work_items', 'reuse_memory')) {
+      this.db.exec('ALTER TABLE work_items ADD COLUMN reuse_memory INTEGER NOT NULL DEFAULT 1');
+    }
     if (!hasColumn(this.db, 'actions', 'context')) {
       this.db.exec("ALTER TABLE actions ADD COLUMN context TEXT NOT NULL DEFAULT '[]'");
     }
@@ -218,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));
   }
@@ -244,18 +287,22 @@ export class WorkItemStore {
     return withTransaction(this.db, () => {
       const now = this.now();
       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,
-         current_action_id, current_run_id, work_dir, origin, linked_session_ids,
+        (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,
+        input.reuseMemory === false ? 0 : 1,
         stringify(input.origin || null),
         stringify(input.linkedSessionIds || []),
         now,
@@ -277,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,
@@ -290,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,
@@ -332,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 = [];
@@ -366,6 +429,64 @@ export class WorkItemStore {
     };
   }
 
+  getReusableContext(workDir, excludeWorkItemId = null) {
+    const workspaceKey = canonicalWorkspaceKey(workDir);
+    if (!workspaceKey) return [];
+    const rows = this.db.prepare(`SELECT r.*, a.type AS action_type, a.required_role,
+        w.title AS source_title
+      FROM runs r
+      JOIN actions a ON a.id = r.action_id
+      JOIN work_items w ON w.id = r.work_item_id
+      WHERE w.workspace_key = ? AND w.reuse_memory = 1 AND w.id != ? AND w.status = 'done'
+        AND r.status = 'completed' AND length(trim(COALESCE(r.summary, ''))) > 0
+      ORDER BY r.ended_at DESC, r.started_at DESC
+      LIMIT ?`).all(workspaceKey, excludeWorkItemId || '', MAX_REUSABLE_CONTEXT_ITEMS);
+    return rows.reverse().map(row => {
+      const run = mapRun(row);
+      return {
+        type: row.action_type,
+        role: row.required_role,
+        summary: run.summary,
+        evidence: run.evidence,
+        reviewDecision: run.reviewDecision,
+        sourceTitle: row.source_title,
+      };
+    });
+  }
+
+  addActionGuidance(id, guidance, expected, makeAction) {
+    return withTransaction(this.db, () => {
+      const workItem = this.getWorkItem(id);
+      if (!workItem) return null;
+      if (workItem.currentActionId !== expected.actionId || workItem.revision !== expected.revision) {
+        throw new Error('Action changed before guidance was applied; refresh and try again');
+      }
+      if (!['ready', 'running'].includes(workItem.status)) {
+        throw new Error(`WorkItem in ${workItem.status} cannot accept Action guidance`);
+      }
+      const previous = workItem.currentActionId ? this.getAction(workItem.currentActionId) : null;
+      if (!previous || !['ready', 'running'].includes(previous.status)) {
+        throw new Error('WorkItem has no active Action for guidance');
+      }
+      const now = this.now();
+      this.#invalidateExecution(
+        workItem,
+        'superseded',
+        'superseded',
+        'Action restarted after user guidance',
+        now,
+      );
+      const action = this.#insertAction(id, {
+        ...makeAction(workItem, previous),
+        contractRevision: workItem.revision,
+      }, this.#nextSequence(id), now);
+      this.db.prepare(`UPDATE work_items SET status = 'ready', current_action_id = ?,
+        current_run_id = NULL, updated_at = ? WHERE id = ?`).run(action.id, now, id);
+      this.appendEvent(id, 'action.guidance_added', { guidance }, { actionId: action.id });
+      return this.getWorkItemDetail(id);
+    });
+  }
+
   #invalidateExecution(workItem, actionStatus, runStatus, reason, now) {
     if (workItem.currentRunId) {
       this.db.prepare(`UPDATE runs SET status = ?, ended_at = ?, error = ?
@@ -403,11 +524,12 @@ export class WorkItemStore {
         );
       }
       this.db.prepare(`UPDATE work_items SET title = ?, goal = ?, acceptance_criteria = ?,
-        work_dir = ?, revision = ?, updated_at = ? WHERE id = ?`).run(
+        work_dir = ?, workspace_key = ?, revision = ?, updated_at = ? WHERE id = ?`).run(
         next.title,
         next.goal,
         stringify(next.acceptanceCriteria),
         next.workDir,
+        canonicalWorkspaceKey(next.workDir),
         revision,
         now,
         id,