@worca/app 1.0.0 → 1.2.0-rc.1

package/src/core/agent-store.mjs

@@ -8,6 +8,8 @@ import { mkdir, readFile, writeFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { loadAgentRegistry, normalizeMeta, userAgentsDir } from './agent-registry.mjs';
 import { listWorkflows } from './workflows.mjs';
+import { validateMetaV2 } from '../shared/graph/agent-meta.mjs';
+import { AWAIT_PORT } from '../shared/graph/constants.mjs';   // the synthesized gate port is wirable
 
 export { userAgentsDir }; // single source: the Phase 1 layer resolver
 
@@ -16,6 +18,15 @@ export const AGENT_KEY_RE = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
 
 function err(message, code) { return Object.assign(new Error(message), { code }); }
 
+/** The v2 capabilities whose ABSENCE is their off state in a sidecar. A complete
+ *  v2 PUT is a REPLACE of this surface — otherwise `{...existing, ...raw}` turns
+ *  every one of them into a one-way switch and `placeable:false` /
+ *  `scope:'workspace-only'` can never be undone from the editor. Everything else
+ *  (including the v1 wiring the registry still derives, which P8 owns) MERGES. */
+const V2_CLEARABLE = ['verdict', 'sideEffect', 'mockRole', 'wantsRequest', 'workspaceFanOut',
+  'workspaceStrategy', 'workspaceVariantOf', 'placeable', 'scope', 'domain', 'icon',
+  'promptHints', 'requiresSkills'];
+
 /** The writable user layer dir. userAgentsDir() returns null only when the home
  *  cannot be resolved (no WORCA_HOME under node:test) — surface that as a 400. */
 function requireUserDir() {
@@ -59,6 +70,12 @@ export async function createAgent({ meta: rawMeta, markdown } = {}) {
   raw.key = key;
   raw.agentFile = `${key}.md`;                              // store-owned sibling file
   if (!Number.isFinite(Number(raw.order))) raw.order = 99;  // sort after built-ins by default
+  // The v2 gate runs BEFORE normalizeMeta: normalizeMeta is lossy by design
+  // (fixed key set, silent coercions, and it returns null rather than a reason),
+  // so a broken sidecar would otherwise be "fixed" into something the user never
+  // wrote — or rejected with "invalid agent metadata". Every failed rule is named.
+  const issues = validateMetaV2(raw).errors;
+  if (issues.length) throw err(issues.join('; '), 'BAD_REQUEST');
   const meta = normalizeMeta(raw);
   if (!meta) throw err('invalid agent metadata', 'BAD_REQUEST');
   const existing = loadAgentRegistry()[key];
@@ -73,6 +90,126 @@ export async function createAgent({ meta: rawMeta, markdown } = {}) {
   return { meta: { ...meta, origin: 'user' }, markdown };
 }
 
+/** Per-port fields the workspace-variant signature deliberately EXCLUDES
+ *  (workflows.mjs portSignature): a variant may render and store differently, it
+ *  may not fire differently. These survive a propagation; everything else on the
+ *  port comes from the base. */
+const VARIANT_OWN_PORT_FIELDS = ['label', 'description', 'as', 'directive', 'filename', 'store', 'artifactKind'];
+
+/** One side of a variant's ports, rebuilt from the base's: the base decides the
+ *  set, the order and every scheduling field; the variant keeps its own rendering.
+ *  @param {object[]} basePorts @param {object[]} variantPorts */
+function mergeVariantPorts(basePorts, variantPorts) {
+  const mine = new Map((Array.isArray(variantPorts) ? variantPorts : []).map((p) => [p.id, p]));
+  return (Array.isArray(basePorts) ? basePorts : []).map((bp) => {
+    const own = mine.get(bp.id);
+    const out = { ...bp };
+    if (!own) return out;
+    // `as` is TYPE-COUPLED (agent-meta.mjs AS_REQUIRES_TYPE: worktree=>void,
+    // answers=>json, fix-review=>md; a bare 'file' demands a NON-void port and
+    // readInputs materializes it on every non-void input). The TYPE is the
+    // base's — the signature owns it — so the variant's stored `as` only
+    // survives a type it was written for; on a type change the base's own `as`
+    // stands. Without this, a base input that BECOMES void (the shipped
+    // reviewer/workspaceReviewer `done` worktree port) leaves the variant
+    // carrying `as:'file'` on a void port and the WHOLE merge is refused.
+    const keep = own.type === bp.type
+      ? VARIANT_OWN_PORT_FIELDS : VARIANT_OWN_PORT_FIELDS.filter((f) => f !== 'as');
+    for (const f of keep) if (own[f] !== undefined) out[f] = own[f];
+    // A void port carries none of these, whatever the variant used to say.
+    if (out.type === 'void') { delete out.filename; delete out.store; delete out.artifactKind; }
+    return out;
+  });
+}
+
+/**
+ * Re-point every USER workspace variant of `key` at the base's new port signature.
+ * A variant is BY DEFINITION the same ports with a different workspace strategy, so
+ * a base port edit that is not propagated makes resolveGraph refuse every workspace
+ * run ("workspace variant X does not match the port signature of Y") at a moment
+ * disconnected from the edit. Non-user variants (builtin/plugin) cannot be written
+ * — they are reported instead. Never throws: a variant that will not validate
+ * after the merge, or whose sidecar cannot be written, is left untouched and
+ * reported — the base's own save has already succeeded and must stand.
+ * @param {string} key the edited base key
+ * @param {object} baseMeta the base's NEW normalized meta
+ * @param {string} dir the writable user layer
+ * @returns {Promise<{updated:string[], warnings:string[]}>}
+ */
+async function propagateToVariants(key, baseMeta, dir) {
+  const updated = [];
+  const warnings = [];
+  for (const variant of Object.values(loadAgentRegistry())) {
+    if (!variant || variant.workspaceVariantOf !== key) continue;
+    if (variant.origin !== 'user') {
+      warnings.push(`workspace variant "${variant.key}" (${variant.origin}) still declares the old ports `
+        + '— workspace runs using it will be refused until it is updated');
+      continue;
+    }
+    const raw = {
+      ...variant,
+      inputs: mergeVariantPorts(baseMeta.inputs, variant.inputs),
+      outputs: mergeVariantPorts(baseMeta.outputs, variant.outputs),
+    };
+    // Boolean(verdict) IS part of the signature; its filename is not. Copying the
+    // base's verdict into a variant that had none also copies the base's filename
+    // TEMPLATE, so the variant writes its verdict there — correct for the
+    // `{base}`-tokenised names every shipped verifier uses; a hardcoded one would
+    // need re-pointing by hand.
+    if (baseMeta.verdict && !variant.verdict) raw.verdict = { ...baseMeta.verdict };
+    if (!baseMeta.verdict) delete raw.verdict;
+    if (variant.descriptionDerived) raw.description = '';   // never persist a derived blurb (agent-store.mjs:114)
+    delete raw.origin; delete raw.agentPath; delete raw.descriptionDerived;
+    const issues = validateMetaV2(raw).errors;
+    const merged = issues.length ? null : normalizeMeta(raw);
+    if (!merged) {
+      warnings.push(`workspace variant "${variant.key}" could not adopt the new ports `
+        + `(${issues.join('; ') || 'invalid agent metadata'}) — re-point it by hand`);
+      continue;
+    }
+    try {
+      await writeFile(join(dir, `${variant.key}.meta.json`), JSON.stringify(merged, null, 2) + '\n', 'utf8');
+    } catch (e) {
+      // Only the fs CODE: the message carries the absolute home path, which no
+      // banner may surface. `updatedVariants` lists what was actually written.
+      warnings.push(`workspace variant "${variant.key}" could not adopt the new ports `
+        + `(write failed: ${e?.code || 'unknown error'}) — re-point it by hand`);
+      continue;
+    }
+    updated.push(variant.key);
+  }
+  return { updated: updated.sort(), warnings };
+}
+
+/**
+ * Saved-template wires that the NEW port set of `key` no longer satisfies:
+ * `["<workflow name> (<nodeId>.<portId>)", …]`. A port rename/removal is NOT
+ * refused here — no saved template can reference the new port before it exists,
+ * so a 409 would make renaming impossible. The RUN refuses instead
+ * (assertRunnableWorkflow -> INVALID_GRAPH); this list is the editor's heads-up.
+ * `await` is the engine-synthesized gate input and is always wirable.
+ * @param {object[]} workflows every saved template (archived included)
+ * @param {string} key the edited agent key
+ * @param {object} meta the NEW normalized meta
+ * @returns {string[]}
+ */
+function stalePortRefs(workflows, key, meta) {
+  const outs = new Set((meta.outputs || []).map((p) => p.id));
+  const ins = new Set([...(meta.inputs || []).map((p) => p.id), AWAIT_PORT.id]);
+  const hits = [];
+  for (const wf of workflows) {
+    const mine = new Set((wf.nodes || [])
+      .filter((n) => n && n.kind === 'agent' && n.key === key).map((n) => n.id));
+    if (!mine.size) continue;
+    const label = wf.name || wf.id;
+    for (const w of wf.wires || []) {
+      if (mine.has(w?.from?.node) && !outs.has(w.from.port)) hits.push(`${label} (${w.from.node}.${w.from.port})`);
+      if (mine.has(w?.to?.node) && !ins.has(w.to.port)) hits.push(`${label} (${w.to.node}.${w.to.port})`);
+    }
+  }
+  return hits;
+}
+
 /** Update a USER agent (meta and/or markdown). Built-ins -> BUILTIN (409). */
 export async function updateAgent(key, { meta: rawMeta, markdown } = {}) {
   if (!AGENT_KEY_RE.test(String(key || ''))) throw err(`agent not found: ${key}`, 'NOT_FOUND');
@@ -96,10 +233,14 @@ export async function updateAgent(key, { meta: rawMeta, markdown } = {}) {
   // field) freezes the fallback into the sidecar and it stops tracking the .md.
   const base = { ...existing };
   if (base.descriptionDerived) base.description = '';
+  if (Number(rawMeta?.metaVersion) === 2) for (const k of V2_CLEARABLE) delete base[k];
   const raw = { ...base, ...(rawMeta && typeof rawMeta === 'object' ? rawMeta : {}) };
   raw.key = key;                                            // key immutable on update
   raw.agentFile = `${key}.md`;
   if (!Number.isFinite(Number(raw.order))) raw.order = existing.order;
+  // The same gate the create path applies: every failed rule named, nothing written.
+  const updIssues = validateMetaV2(raw).errors;
+  if (updIssues.length) throw err(updIssues.join('; '), 'BAD_REQUEST');
   const meta = normalizeMeta(raw);
   if (!meta) throw err('invalid agent metadata', 'BAD_REQUEST');
   const dir = requireUserDir();
@@ -111,7 +252,12 @@ export async function updateAgent(key, { meta: rawMeta, markdown } = {}) {
   const body = typeof markdown === 'string'
     ? markdown
     : await readFile(join(dir, `${key}.md`), 'utf8').catch(() => '');
-  return { meta: { ...meta, origin: 'user' }, markdown: body };
+  // Always present, possibly empty: the Agents view reads both unconditionally.
+  const stale = stalePortRefs(await listWorkflows({ includeArchived: true }), key, meta);
+  const warnings = stale.length ? [`saved pipelines reference a removed port: ${stale.join(', ')}`] : [];
+  const variants = await propagateToVariants(key, meta, dir);
+  warnings.push(...variants.warnings);
+  return { meta: { ...meta, origin: 'user' }, markdown: body, warnings, updatedVariants: variants.updated };
 }
 
 /** Delete a USER agent; REFERENCED (409) while a saved workflow uses the key. */
@@ -130,11 +276,25 @@ export async function deleteAgent(key) {
     );
   }
   if (!existing) throw err(`agent not found: ${key}`, 'NOT_FOUND');
-  const refs = (await listWorkflows())
-    .filter((wf) => (wf.steps || []).some((col) => (col || []).some((n) => n && n.key === key)))
+  const refs = (await listWorkflows({ includeArchived: true }))
+    // v1 rows are still live until the engine cut-over; v2 rows carry a key only
+    // on kind:'agent' nodes (a task/end/and/or/combine card never does).
+    .filter((wf) => (wf.steps || []).some((col) => (col || []).some((n) => n && n.key === key))
+      || (wf.nodes || []).some((n) => n && n.kind === 'agent' && n.key === key))
     .map((wf) => wf.name || wf.id);
   if (refs.length) {
-    throw err(`agent "${key}" is used by saved workflow(s): ${refs.join(', ')} — delete or edit those first`, 'REFERENCED');
+    throw err(`agent "${key}" is used by saved workflow(s): ${refs.join(', ')} `
+      + '— delete or edit those first (archived rows count)', 'REFERENCED');
+  }
+  // A workspace variant substitutes for its target agent by KEY: deleting the
+  // target would leave the variant pointing at nothing, and the substitution
+  // would silently stop happening on workspace runs.
+  const variants = Object.values(loadAgentRegistry())
+    .filter((m) => m && m.workspaceVariantOf === key)
+    .map((m) => m.key);
+  if (variants.length) {
+    throw err(`agent "${key}" is the workspace variant target of: ${variants.join(', ')} `
+      + '— delete or re-point those first', 'REFERENCED');
   }
   const dir = requireUserDir();
   await rm(join(dir, `${key}.meta.json`), { force: true });

package/src/core/artifacts.mjs

@@ -322,7 +322,8 @@ export function readPipelineExtras(pipelineId) {
  * @param {string} pipelineId
  * @param {{id:string, label?:string, nodeId?:string, stepIndex?:number, cycle?:number,
  *          stepKey?:string, status?:string, startedAt?:string, finishedAt?:string,
- *          durationMs?:number, tokens?:number, costUsd?:number, subagentType?:string}} rec
+ *          durationMs?:number, tokens?:number, costUsd?:number, subagentType?:string,
+ *          runModel?:string}} rec
  */
 export function upsertSubAgent(pipelineId, rec) {
   if (!pipelineId || !rec || !rec.id) return;
@@ -330,9 +331,11 @@ export function upsertSubAgent(pipelineId, rec) {
     tx(() => {
       getDb().prepare(`
         INSERT INTO sub_agents (pipeline_id, id, step_key, node_id, step_index, cycle,
-          label, status, started_at, finished_at, duration_ms, tokens, cost_usd, ui_phase, skills, subagent_type, graphify_count)
+          label, status, started_at, finished_at, duration_ms, tokens, cost_usd, ui_phase, skills, subagent_type, graphify_count,
+          run_model)
         VALUES (@pipeline_id,@id,@step_key,@node_id,@step_index,@cycle,@label,@status,
-          @started_at,@finished_at,@duration_ms,@tokens,@cost_usd,@ui_phase,@skills,@subagent_type,@graphify_count)
+          @started_at,@finished_at,@duration_ms,@tokens,@cost_usd,@ui_phase,@skills,@subagent_type,@graphify_count,
+          @run_model)
         ON CONFLICT(pipeline_id, id) DO UPDATE SET
           status      = excluded.status,
           step_key    = COALESCE(excluded.step_key, step_key),
@@ -348,7 +351,8 @@ export function upsertSubAgent(pipelineId, rec) {
           ui_phase    = COALESCE(excluded.ui_phase, ui_phase),
           skills      = COALESCE(excluded.skills, skills),
           subagent_type = COALESCE(excluded.subagent_type, subagent_type),
-          graphify_count = COALESCE(excluded.graphify_count, graphify_count)
+          graphify_count = COALESCE(excluded.graphify_count, graphify_count),
+          run_model      = COALESCE(excluded.run_model, run_model)
       `).run({
         pipeline_id: pipelineId,
         id: rec.id,
@@ -367,6 +371,10 @@ export function upsertSubAgent(pipelineId, rec) {
         skills: s(rec.skills),   // s() = JSON.stringify or null; growing supersets overwrite via COALESCE
         subagent_type: rec.subagentType ?? null,   // scalar TEXT: bound directly (no s() JSON wrap)
         graphify_count: Number.isFinite(rec.graphifyCount) ? rec.graphifyCount : null,  // scalar INTEGER
+        // The model this child actually ran on: the alias its Task call asked for,
+        // else the parent node's model (what it inherits). Written at spawn and
+        // COALESCE-guarded, so a later finish/telemetry update never nulls it.
+        run_model: rec.runModel ?? null,
       });
     });
   } catch { /* best-effort: live state.subAgents is the reconcile source of truth; a swallowed write is caught by tests, not a crashed run. */ }
@@ -382,13 +390,14 @@ export function upsertSubAgent(pipelineId, rec) {
  * @returns {Array<{id:string, label:string|null, nodeId:string|null, stepIndex:number|null,
  *   cycle:number|null, stepKey:string|null, status:string, startedAt:string|null,
  *   finishedAt:string|null, durationMs:number|null, tokens:number|null, costUsd:number|null,
- *   subagentType:string|null}>}
+ *   subagentType:string|null, runModel:string|null}>}
  */
 export function listSubAgents(pipelineId) {
   if (!pipelineId) return [];
   return getDb().prepare(`
     SELECT id, label, node_id, step_index, cycle, step_key, status,
-           started_at, finished_at, duration_ms, tokens, cost_usd, ui_phase, skills, subagent_type, graphify_count
+           started_at, finished_at, duration_ms, tokens, cost_usd, ui_phase, skills, subagent_type, graphify_count,
+           run_model
     FROM sub_agents WHERE pipeline_id = ? ORDER BY started_at, id
   `).all(pipelineId).map((r) => ({
     id: r.id,
@@ -407,6 +416,7 @@ export function listSubAgents(pipelineId) {
     skills: j(r.skills, []),     // NULL -> [] so the UI always has an array (no pills)
     subagentType: r.subagent_type ?? null,   // scalar TEXT: mapped directly (no j() parse)
     graphifyCount: r.graphify_count ?? null,   // scalar INTEGER: NULL -> null (no badge)
+    runModel: r.run_model ?? null,   // scalar TEXT: NULL -> null (no pill on pre-v25 rows)
   }));
 }
 
@@ -728,6 +738,42 @@ function resolveAgainst(base, p) {
   return isAbsolute(p) ? p : resolve(base, p);
 }
 
+/**
+ * The ONE typed error every prompt-file reader throws. Carried by `code` so the
+ * CLI can fail() on it and ui/server.mjs can answer 400 instead of letting it
+ * surface as an anonymous mid-run error event.
+ * @param {string} absPath  the resolved path the caller named
+ * @param {unknown} cause
+ */
+export function promptFileError(absPath, cause) {
+  const err = new Error(`cannot read prompt file ${absPath}: ${cause?.message || cause}`);
+  err.code = 'PROMPT_FILE_UNREADABLE';
+  err.promptFile = absPath;
+  err.cause = cause;
+  return err;
+}
+
+/**
+ * Read a NAMED prompt file, resolved against `projectDir` exactly as createPipeline
+ * does. Never degrades: a file the caller named but we cannot read is an ERROR, not
+ * an empty prompt. The old bare `catch { promptText = '' }` ran a whole pipeline on
+ * an empty task and exited 0 — in real mode spending tokens and cutting a worktree
+ * + feature branch for nothing. The empty-string fallback is only meaningful when
+ * NO file was named.
+ * @param {string} projectDir
+ * @param {string} promptFile  absolute, or relative to projectDir
+ * @returns {Promise<string>}
+ * @throws {Error & {code:'PROMPT_FILE_UNREADABLE'}}
+ */
+export async function readPromptFile(projectDir, promptFile) {
+  const abs = resolveAgainst(projectDir, promptFile);
+  try {
+    return await readFile(abs, 'utf8');
+  } catch (cause) {
+    throw promptFileError(abs, cause);
+  }
+}
+
 /**
  * Create a new pipeline directory and seed it with the prompt, extras and an audit
  * header (pipeline.md). The structured run state is INSERTed as a pipelines row
@@ -785,12 +831,14 @@ export async function createPipeline(projectDir, opts = {}) {
   // verbatim copy below is unchanged).
   let promptText = typeof prompt === 'string' ? prompt : '';
   if (!promptText && typeof precomputedPromptText === 'string') promptText = precomputedPromptText;
-  if (!promptText && promptFile) {
-    try {
-      promptText = await readFile(resolveAgainst(projectDir, promptFile), 'utf8');
-    } catch {
-      promptText = '';
-    }
+  // A NAMED prompt file must be readable, and it is checked BEFORE anything is
+  // created (no dir, no row). It is checked even when an inline prompt or a
+  // precomputed body already won the text, because the file is still copied
+  // verbatim into prompt.md below — the old bare catch there silently substituted
+  // the inline text for the file the caller named.
+  if (promptFile) {
+    const fileText = await readPromptFile(projectDir, promptFile);
+    if (!promptText) promptText = fileText;
   }
 
   const resolvedTitle =
@@ -810,8 +858,11 @@ export async function createPipeline(projectDir, opts = {}) {
   if (promptFile) {
     try {
       await copyFile(resolveAgainst(projectDir, promptFile), promptDest);
-    } catch {
-      await writeFile(promptDest, promptText, 'utf8');
+    } catch (cause) {
+      // The read above already proved this path readable, so a failure here is a
+      // TOCTOU (the file vanished) or a destination problem — either way the run
+      // must not proceed on a substituted prompt.
+      throw promptFileError(resolveAgainst(projectDir, promptFile), cause);
     }
   } else {
     await writeFile(promptDest, promptText, 'utf8');
@@ -992,11 +1043,11 @@ export async function writeState(pipelineDir, stateObj) {
       INSERT INTO pipelines (id, project_key, workspace_key, target, title, base_name,
         date_prefix, status, phase, cycle, started_at, updated_at, total_cost_usd,
         total_active_ms, prompt, branch, workspace_meta, stepper, tools, resume_point,
-        source_type, source_ref, guardrails_id)
+        source_type, source_ref, guardrails_id, outcome)
       VALUES (@id,@project_key,@workspace_key,@target,@title,@base_name,@date_prefix,
         @status,@phase,@cycle,@started_at,@updated_at,@total_cost_usd,@total_active_ms,
         @prompt,@branch,@workspace_meta,@stepper,@tools,@resume_point,
-        @source_type,@source_ref,@guardrails_id)
+        @source_type,@source_ref,@guardrails_id,@outcome)
       ON CONFLICT(id) DO UPDATE SET
         status=excluded.status, phase=excluded.phase, cycle=excluded.cycle,
         updated_at=excluded.updated_at, total_cost_usd=excluded.total_cost_usd,
@@ -1004,6 +1055,7 @@ export async function writeState(pipelineDir, stateObj) {
         workspace_meta=excluded.workspace_meta, stepper=excluded.stepper,
         tools=excluded.tools,
         resume_point=excluded.resume_point,
+        outcome=excluded.outcome,
         base_name=COALESCE(excluded.base_name, base_name),
         date_prefix=COALESCE(excluded.date_prefix, date_prefix)
     `).run(toPipelineRow(obj));
@@ -1011,10 +1063,19 @@ export async function writeState(pipelineDir, stateObj) {
     getDb().prepare('DELETE FROM pipeline_steps WHERE pipeline_id = ?').run(id);
     const ins = getDb().prepare(`
       INSERT INTO pipeline_steps (pipeline_id, key, node_id, phase, step_index, cycle,
-        status, started_at, updated_at, active_ms, running_since, cost_usd, session_id, skills, graphify_count)
-      VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+        status, started_at, updated_at, active_ms, running_since, cost_usd, session_id,
+        skills, graphify_count,
+        execution_id, exec_kind, agent_key, ended_at, exec_trigger, exec_result, exec_meta)
+      VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
     `);
     for (const st of Array.isArray(obj.steps) ? obj.steps : []) {
+      // v2 rows: execution_id === key. v1 rows leave every exec_* column NULL, so
+      // the readers below reproduce today's exact shape for a v1 pipeline.
+      const meta = (st.taskId != null || st.parentExecutionId != null || st.title != null || st.phaseOrdinal != null)
+        ? s({ taskId: st.taskId ?? null, parentExecutionId: st.parentExecutionId ?? null,
+              title: st.title ?? null, phaseOrdinal: st.phaseOrdinal ?? null,
+              taskIndex: st.taskIndex ?? null, taskTotal: st.taskTotal ?? null })
+        : null;
       ins.run(
         id, st.key, st.nodeId ?? null, st.phase ?? null,
         st.stepIndex ?? null, st.cycle ?? null, st.status ?? null,
@@ -1025,6 +1086,13 @@ export async function writeState(pipelineDir, stateObj) {
         st.sessionId ?? null,
         s(st.skills),
         Number.isFinite(st.graphifyCount) ? st.graphifyCount : null,
+        st.executionId ?? null,
+        st.kind ?? null,
+        st.agentKey ?? null,
+        st.endedAt ?? null,
+        st.trigger === undefined ? null : s(st.trigger),
+        st.result === undefined ? null : s(st.result),
+        meta,
       );
     }
   });
@@ -1334,11 +1402,23 @@ function toPipelineRow(o) {
     source_type: o.sourceType ?? 'prompt',
     source_ref: s(o.sourceMeta),
     guardrails_id: o.guardrailsId ?? null,
+    // §5.9 outcome: the derived run-level v2 facts, so a rehydrated state matches
+    // a live one. NULL for a v1 run (nothing to say), so v1 rows are unchanged.
+    outcome: (o.engine === 2 || o.endReached !== undefined)
+      ? s({
+          endReached: !!o.endReached,
+          result: o.result ?? null,
+          warnings: Array.isArray(o.warnings) ? o.warnings : [],
+          wireDeliveries: o.wireDeliveries ?? {},
+          tokens: o.tokens ?? {},
+        })
+      : null,
   };
 }
 
 /**
- * The pipeline's {cost, active} totals for the history list, read from the DB row.
+ * The pipeline's {cost, active} totals for the history list (and the Ask Worca
+ * `get_run` tool, ask-worca-design.md §6.4), read from the DB row.
  * Normal runs carry NOT-NULL 0-defaulted totals, so when a total is > 0 it is used
  * verbatim and NO extra query runs. Only when a total is 0 do we fall back to the
  * per-step SUM/COUNT (the DB-native equivalent of the old pipelineTotalCost/
@@ -1349,7 +1429,7 @@ function toPipelineRow(o) {
  * @param {object} row a pipelines DB row (total_cost_usd / total_active_ms)
  * @returns {{cost:number|null, active:number|null}}
  */
-function totalsFor(row) {
+export function totalsFor(row) {
   const agg = getDb().prepare(`
     SELECT COUNT(cost_usd) cc, SUM(cost_usd) sc, COUNT(active_ms) ca, SUM(active_ms) sa
     FROM pipeline_steps WHERE pipeline_id = ?
@@ -1439,6 +1519,7 @@ async function rowToHistoryEntry(row, repoDir = null, opts = {}) {
     sourceBranch: source,
     guardrailsId: row.guardrails_id ?? null,
     pauseReason: row.pause_reason ?? null,
+    pauseDetail: row.pause_detail ?? null,
     retainedWork: retainedWorkFor(row),
     survived,
     added,
@@ -1494,7 +1575,8 @@ export async function listPipelines(projectDir, opts = {}, workspaceKey) {
   const rows = getDb().prepare(`
     SELECT id, project_key, target, title, status, started_at, updated_at, total_cost_usd, total_active_ms,
            branch, workspace_meta, guardrails_id,
-           json_extract(CASE WHEN json_valid(resume_point) THEN resume_point END, '$.pauseReason') AS pause_reason
+           json_extract(CASE WHEN json_valid(resume_point) THEN resume_point END, '$.pauseReason') AS pause_reason,
+           json_extract(CASE WHEN json_valid(resume_point) THEN resume_point END, '$.pauseDetail') AS pause_detail
     FROM pipelines
     WHERE ${workspaceKey ? 'workspace_key = ?' : 'project_key = ?'} AND archived_at IS NULL
     ORDER BY started_at DESC
@@ -1522,7 +1604,8 @@ export async function listAllPipelines(opts = {}, { batchSize = 16 } = {}) {
   const rows = getDb().prepare(`
     SELECT id, project_key, workspace_key, target, title, status, started_at, updated_at,
            total_cost_usd, total_active_ms, branch, workspace_meta, guardrails_id,
-           json_extract(CASE WHEN json_valid(resume_point) THEN resume_point END, '$.pauseReason') AS pause_reason
+           json_extract(CASE WHEN json_valid(resume_point) THEN resume_point END, '$.pauseReason') AS pause_reason,
+           json_extract(CASE WHEN json_valid(resume_point) THEN resume_point END, '$.pauseDetail') AS pause_detail
     FROM pipelines
     WHERE archived_at IS NULL
     ORDER BY COALESCE(updated_at, started_at) DESC, project_key, id
@@ -1646,6 +1729,22 @@ function stepRowToStep(r) {
   };
   if (r.node_id != null) step.nodeId = r.node_id;
   if (r.step_index != null) step.stepIndex = r.step_index;
+  if (r.execution_id != null) step.executionId = r.execution_id;
+  if (r.exec_kind != null) step.kind = r.exec_kind;
+  if (r.agent_key != null) step.agentKey = r.agent_key;
+  if (r.ended_at != null) step.endedAt = r.ended_at;
+  if (r.execution_id != null && r.cycle != null) step.ordinal = r.cycle;  // `ordinal` is the v2 name; `cycle` is its alias
+  if (r.exec_trigger != null) step.trigger = j(r.exec_trigger, { wireIds: [], freshPorts: [] });
+  if (r.exec_result != null) step.result = j(r.exec_result, null);
+  const em = r.exec_meta != null ? j(r.exec_meta, null) : null;
+  if (em) {
+    if (em.taskId != null) step.taskId = em.taskId;
+    if (em.parentExecutionId != null) step.parentExecutionId = em.parentExecutionId;
+    if (em.title != null) step.title = em.title;
+    if (em.phaseOrdinal != null) step.phaseOrdinal = em.phaseOrdinal;
+    if (em.taskIndex != null) step.taskIndex = em.taskIndex;
+    if (em.taskTotal != null) step.taskTotal = em.taskTotal;
+  }
   return step;
 }
 
@@ -1678,13 +1777,33 @@ function rowToState(row) {
     stepper: j(row.stepper, null),
     tools: j(row.tools, null),
     guardrailsId: row.guardrails_id ?? null,
+    // A retired v1 resume point was NULLed by the v2 upgrade: the run stays in
+    // History with an honest status, but it can never be resumed again.
+    resumable: row.resume_point != null,
     steps: getDb().prepare(`
       SELECT key, node_id, phase, step_index, cycle, status, started_at, updated_at,
-             active_ms, running_since, cost_usd, session_id, skills, graphify_count
+             active_ms, running_since, cost_usd, session_id, skills, graphify_count,
+             execution_id, exec_kind, agent_key, ended_at, exec_trigger, exec_result, exec_meta
       FROM pipeline_steps WHERE pipeline_id = ? ORDER BY rowid
     `).all(row.id).map(stepRowToStep),
     subAgents: listSubAgents(row.id),
   };
+  // The pause cause rides resume_point (no column): expose it on the DETAIL payload
+  // too, so a deep-linked History detail no longer waits for the LIST row.
+  const rp = j(row.resume_point, null);
+  state.pauseReason = typeof rp?.pauseReason === 'string' ? rp.pauseReason : null;
+  state.pauseDetail = typeof rp?.pauseDetail === 'string' ? rp.pauseDetail : null;
+  const outcome = j(row.outcome, null);
+  if (outcome) {
+    state.engine = 2;
+    state.endReached = !!outcome.endReached;
+    state.result = outcome.result ?? null;
+    state.warnings = Array.isArray(outcome.warnings) ? outcome.warnings : [];
+    state.wireDeliveries = outcome.wireDeliveries ?? {};
+    state.tokens = outcome.tokens ?? {};
+    state.active = [];        // nothing is in flight in a rehydrated snapshot
+    state.gate = null;
+  }
   const meta = readStoreMeta(row.project_key);
   state.projectDir = meta?.path ?? null;
   // Workspace superset: spread workspace_meta back onto the top level + target.
@@ -1752,6 +1871,24 @@ export function lookupPipelineRow(key, id) {
   return row || null;
 }
 
+/**
+ * Ask Worca (ask-worca-design.md §6.4 get_run): one pipelines row by short id
+ * across EVERY store key, archived included. `pipelines.id` is the PRIMARY KEY, so
+ * there is at most one row; the dir-name form (`…-<8hex>`) is accepted like
+ * lookupPipelineRow does.
+ * @param {string} id
+ * @returns {object|null}
+ */
+export function findPipelineRowById(id) {
+  const raw = String(id ?? '').trim();
+  if (!raw) return null;
+  let row = getDb().prepare('SELECT * FROM pipelines WHERE id = ?').get(raw.toLowerCase());
+  if (row) return row;
+  const m = DIR_ID_RE.exec(raw);
+  if (m) row = getDb().prepare('SELECT * FROM pipelines WHERE id = ?').get(m[1].toLowerCase());
+  return row || null;
+}
+
 /**
  * The DB-backed lookups `sweepRunRoots` (worktree.mjs) needs, in ONE place shared by
  * both callers — `ui/server.mjs`'s boot sweep and the `worca doctor` subcommand.
@@ -1980,6 +2117,45 @@ export async function findRunDir(pipelinesDir, id) {
   return null;
 }
 
+/**
+ * Read one INDEXED artifact of a pipelines ROW. `rel` never reaches the
+ * filesystem: it only SELECTS among the rows the artifacts table already holds —
+ * the exact rel_path first, else the LONGEST rel_path that is a path SUFFIX of it
+ * (`…/<rel_path>`; the engine records absolute paths and the client sends
+ * `result.path` verbatim). Basenames CAN collide across dirs, so a bare basename
+ * never matches a nested row. The path that is read is ALWAYS the stored one,
+ * run dir first, store root second (plan/review markdown is store-root-relative);
+ * a stored path with a `..` segment is refused outright. Null when the row, the
+ * index row or the file is missing.
+ */
+export async function resolveIndexedArtifactForRow(row, rel) {
+  const norm = (p) => String(p || '').replace(/\\/g, '/');
+  const want = norm(rel);
+  if (!row || !want) return null;
+  const arts = (await listArtifacts(row.id))
+    .filter((a) => a && typeof a.relPath === 'string' && a.relPath && !a.relPath.split('/').includes('..'));
+  // Exact first, then the LONGEST suffix — with rows `plan.md` and `a/plan.md`
+  // a request for `/x/a/plan.md` ends with BOTH `/plan.md` and `/a/plan.md`, and a
+  // first-match `find` would serve whichever row the table happens to list first.
+  const hit = arts.find((a) => a.relPath === want)
+    || arts.filter((a) => want.endsWith(`/${a.relPath}`))
+      .sort((x, y) => y.relPath.length - x.relPath.length)[0];
+  if (!hit) return null;
+  const isWs = row.target === 'workspace' || !!row.workspace_key;
+  const storeRoot = isWs ? workspaceStorePath(row.workspace_key) : projectStorePath(row.project_key);
+  const runDir = await runDirForRow(row);
+  for (const base of [runDir, storeRoot]) {
+    try { return { rel: hit.relPath, text: await readFile(join(base, hit.relPath), 'utf8') }; } catch { /* try the next base */ }
+  }
+  return null;
+}
+
+/** The keyed form (`/api/history/:key/:id`, workspace twin) over lookupPipelineRow. */
+export async function resolveIndexedArtifact(key, id, rel) {
+  const row = lookupPipelineRow(key, id);
+  return row ? resolveIndexedArtifactForRow(row, rel) : null;
+}
+
 /** Read a pipeline-local artifact file as text, or null if absent. */
 export async function readRunArtifactText(key, id, relPath) {
   const row = lookupPipelineRow(key, id);