@worca/app 1.3.0-rc.2 → 1.4.0-rc.1

package/src/core/agent-registry.mjs

@@ -14,7 +14,8 @@ import { join, resolve, isAbsolute, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { worcaHome } from './projects.mjs'; // user agent layer root (read fresh per call)
 import { readPluginsLock, pluginCurrentDir } from './plugins-lock.mjs'; // plugin layer roots (Task 2)
-import { declaredApi, NOT_META_V2 } from './plugin-manifest.mjs'; // plugin API declared by a layer's manifest
+import { declaredApi, negotiatedApi, NOT_META_V2, ASK_NEEDS_API_4 } from './plugin-manifest.mjs'; // plugin API declared/negotiated by a layer's manifest
+import { WORCA_ASK_FORMS_API } from './plugin-api.mjs';
 import { normalizeAgentMeta, DEFAULT_ORDER } from '../shared/graph/agent-meta.mjs'; // meta v2 (one source: registry + store + UI)
 import { MOCK_WRITER_ROLES } from './claude-runner.mjs';             // mockRole vocabulary (no cycle: claude-runner imports no registry)
 import { readFrontmatterSync } from './frontmatter.mjs';
@@ -84,7 +85,7 @@ const AGENT_KEY_RE = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
  *  `warn` is INJECTABLE (defaults to console.warn) so scanLayer can capture the
  *  reason a sidecar was dropped and hand it to a diagnostics sink — the reason
  *  is authored here and must never be re-derived by a second reader. */
-export function normalizeMeta(raw, { warn = console.warn } = {}) {
+export function normalizeMeta(raw, { warn = console.warn, onDropForm = null } = {}) {
   if (!raw || typeof raw !== 'object') return null;
   const key = typeof raw.key === 'string' ? raw.key.trim() : '';
   if (!key) return null;
@@ -149,6 +150,7 @@ export function normalizeMeta(raw, { warn = console.warn } = {}) {
   const { meta, errors } = normalizeAgentMeta(raw, {
     mockWriterRoles: MOCK_WRITER_ROLES,
     warn: (msg) => warn(msg),
+    onDropForm,                  // §3: a dropped FORM must not look like a dropped SIDECAR
   });
   if (errors.length) {
     warn(`[agent-registry] sidecar "${key}" declares metaVersion 2 but is invalid; skipped: ${errors.join('; ')}`);
@@ -162,7 +164,7 @@ export function normalizeMeta(raw, { warn = console.warn } = {}) {
     portSummary: meta.portSummary,
   };
   for (const field of ['verdict', 'sideEffect', 'mockRole', 'wantsRequest', 'workspaceFanOut',
-    'workspaceStrategy', 'workspaceVariantOf', 'placeable']) {
+    'workspaceStrategy', 'workspaceVariantOf', 'placeable', 'ask', 'humanEffort']) {
     if (field in meta) merged[field] = meta[field];
   }
   return merged;
@@ -181,16 +183,18 @@ export function userAgentsDir() {
 
 /**
  * Third registry layer (spec §9.1): every ENABLED installed plugin's
- * current/agents dir, in lexicographic plugin-name order — the deterministic
- * collision winner among plugins. An entry is skipped when disabled
+ * current/<subdir> dir, in lexicographic plugin-name order — the deterministic
+ * collision winner among plugins. Shared by the agent registry (`agents`) and the
+ * script registry (`scripts`). An entry is skipped when disabled
  * (enabled === false in the lock) or broken (existsSync follows the current/
  * symlink, so a missing or dangling symlink — and a version dir without
- * agents/ — drops out). Wrapped in try/catch like userAgentsDir(): with no
+ * <subdir>/ — drops out). Wrapped in try/catch like userAgentsDir(): with no
  * resolvable worca-cc home (bare node:test runner) or an unreadable lock this
  * returns [] and registry loads never throw.
- * @returns {Array<{plugin: string, dir: string, builtFor: number|null}>}
+ * @param {'agents'|'scripts'} subdir
+ * @returns {Array<{plugin: string, dir: string, builtFor: number|null, api: number|null}>}
  */
-export function pluginAgentLayers() {
+export function pluginLayers(subdir) {
   try {
     const lock = readPluginsLock();
     return Object.keys(lock)
@@ -199,14 +203,22 @@ export function pluginAgentLayers() {
       .map((name) => {
         const dir = pluginCurrentDir(name);
         let builtFor = null;
+        let api = null;
         try {
           const raw = JSON.parse(readFileSync(join(dir, 'worca-cc-plugin.json'), 'utf8'));
+          const range = raw?.engines?.['worca-cc-api'] ?? '';
           // `|| null`: declaredApi('') is 0 (an unconstrained range accepts
           // everything), and "built for plugin API 0" is not English. apiMismatch
           // guards the same case the same way.
-          builtFor = declaredApi(raw?.engines?.['worca-cc-api'] ?? '') || null;
-        } catch { builtFor = null; } // unreadable manifest: the message degrades, the skip does not
-        return { plugin: name, dir: join(dir, 'agents'), builtFor };
+          builtFor = declaredApi(range) || null;
+          // builtFor is the LOWEST integer the range accepts (what the plugin was
+          // written against); `api` is the HIGHEST host API it admits — what the
+          // plugin actually NEGOTIATES, and therefore what decides which host
+          // features it gets. `null` when the manifest is missing or unreadable:
+          // every feature gate below must fail CLOSED on it.
+          api = negotiatedApi(range);
+        } catch { builtFor = null; api = null; } // unreadable manifest: the message degrades, the skip does not
+        return { plugin: name, dir: join(dir, subdir), builtFor, api };
       })
       .filter(({ dir }) => existsSync(dir));
   } catch {
@@ -214,14 +226,23 @@ export function pluginAgentLayers() {
   }
 }
 
-/** Scan one layer dir for *.meta.json; stamps the COMPUTED origin/agentPath/
- *  descriptionDerived fields (none of which normalizeMeta returns, so none can
- *  be persisted back into a sidecar). */
-function scanLayer(dir, origin, { requireMetaV2 = false, builtFor = null, onDrop = null } = {}) {
+export function pluginAgentLayers() { return pluginLayers('agents'); }
+
+/**
+ * Scan one layer dir for `*.meta.json` and normalize each through
+ * `normalize(parsed, { warn })` (null = skip). Stamps the COMPUTED `origin`.
+ * ONE reader for "a directory of sidecars", two normalizers (agents, scripts).
+ * `tag` prefixes the warnings (`[agent-registry]` / `[script-registry]`).
+ * @returns {Array<{meta: object, file: string}>}
+ */
+export function scanMetaLayer(dir, origin, { normalize, tag, requireMetaV2 = false, builtFor = null, onDrop = null }) {
   // Every skip below is a CONTRIBUTION THE USER CANNOT SEE unless someone
   // reports it: console.warn reaches a server log, not the Plugins card, the
   // install receipt or the doctor. onDrop is that reporting channel — optional,
-  // so the hot registry path pays nothing when nobody is listening.
+  // so the hot registry path pays nothing when nobody is listening. A drop means
+  // "this file, or a declared PART of it, was ignored": scanLayer's API-4 gate
+  // reports a stripped `ask` block through the same channel, and the reason
+  // string is what tells the two apart.
   const drop = (file, reason) => { if (onDrop) onDrop({ origin, file, reason }); };
   let files;
   try {
@@ -229,7 +250,7 @@ function scanLayer(dir, origin, { requireMetaV2 = false, builtFor = null, onDrop
   } catch {
     return []; // missing layer dir => empty layer (fails safe)
   }
-  const metas = [];
+  const out = [];
   for (const f of files) {
     if (!f.endsWith('.meta.json')) continue;
     let parsed;
@@ -246,18 +267,35 @@ function scanLayer(dir, origin, { requireMetaV2 = false, builtFor = null, onDrop
     // layers keep the v1 path until the engine cut-over.
     if (requireMetaV2 && Number(parsed?.metaVersion) !== 2) {
       const builtForText = builtFor == null ? 'an older plugin API' : `plugin API ${builtFor}`;
-      console.warn(`[agent-registry] ${origin}/${f}: built for ${builtForText} — ${NOT_META_V2} — ignored`);
+      console.warn(`[${tag}] ${origin}/${f}: built for ${builtForText} — ${NOT_META_V2} — ignored`);
       drop(f, `built for ${builtForText} — ${NOT_META_V2}`);
       continue;
     }
-    // Capture normalizeMeta's own reason rather than re-deriving one: the LAST
+    // Capture the normalizer's own reason rather than re-deriving one: the LAST
     // warning it emits is the fatal one (non-fatal coercion warnings precede it).
     let why = '';
-    const meta = normalizeMeta(parsed, {
-      warn: (m) => { why = String(m).replace(/^\[agent-registry\] /, ''); console.warn(m); },
+    const prefix = `[${tag}] `;
+    const meta = normalize(parsed, {
+      warn: (m) => { why = String(m).startsWith(prefix) ? String(m).slice(prefix.length) : String(m); console.warn(m); },
+      // A form that fails gate 1 drops the FORM, not the sidecar, so it reports
+      // straight to the diagnostics sink instead of through `why` (which names
+      // the reason an agent vanished). The script normalizer ignores the opt.
+      onDropForm: ({ message }) => drop(f, message),
     });
     if (!meta) { drop(f, why || 'invalid sidecar'); continue; }
     meta.origin = origin;                                              // computed, never stored
+    out.push({ meta, file: f });
+  }
+  return out;
+}
+
+/** Scan one agent layer dir for *.meta.json; stamps the COMPUTED origin/agentPath/
+ *  descriptionDerived fields (none of which normalizeMeta returns, so none can
+ *  be persisted back into a sidecar). */
+function scanLayer(dir, origin, { requireMetaV2 = false, builtFor = null, onDrop = null, askApi = null } = {}) {
+  const drop = (file, reason) => { if (onDrop) onDrop({ origin, file, reason }); };
+  const metas = [];
+  for (const { meta, file: f } of scanMetaLayer(dir, origin, { normalize: normalizeMeta, tag: 'agent-registry', requireMetaV2, builtFor, onDrop })) {
     // agentFile is a PATH read as the agent's system prompt AND for its
     // `tools:` frontmatter, so the loader refuses to stamp an agentPath outside
     // the layer it is scanning. Belt-and-braces behind validatePluginDir, which
@@ -268,6 +306,20 @@ function scanLayer(dir, origin, { requireMetaV2 = false, builtFor = null, onDrop
       drop(f, `agentFile "${meta.agentFile}" resolves outside the agents dir`);
       continue;
     }
+
+    // API 4 (plugin layers only — `requireMetaV2` is the same plugin-layer
+    // marker the meta v2 gate above rides): an agent's `ask` block is honoured
+    // only when the plugin NEGOTIATES plugin API 4. Below that it is stripped
+    // HERE, at the single choke point, so the prompt block, the ask-time gate,
+    // the Agents view and History all see an agent that simply has no forms and
+    // the agent falls back to generic questions on its own (ask-forms spec §10).
+    // Number(null) is 0, so an unknowable API fails CLOSED. The sidecar itself
+    // is NOT dropped: its ports are fine and its agent stays usable.
+    if (requireMetaV2 && meta.ask && !(Number(askApi) >= WORCA_ASK_FORMS_API)) {
+      console.warn(`[agent-registry] ${origin}/${f}: ${ASK_NEEDS_API_4}`);
+      drop(f, ASK_NEEDS_API_4);
+      delete meta.ask;
+    }
     meta.agentPath = meta.agentFile ? join(dir, meta.agentFile) : null; // layer-correct abs path
     // The agent .md's frontmatter (name/description/tools/model), read from the
     // file HEAD only (frontmatter.mjs) — COMPUTED like origin/agentPath, never
@@ -328,8 +380,8 @@ export function loadAgentRegistry(agentsDir = DEFAULT_AGENTS_DIR, opts = {}) {
   const plugins = [];
   if (opts.includePlugins !== false) {
     const taken = new Set([...builtinKeys, ...users.map((m) => m.key)]);
-    for (const { plugin, dir, builtFor } of pluginAgentLayers()) {
-      for (const m of scanLayer(dir, `plugin:${plugin}`, { requireMetaV2: true, builtFor, onDrop })) {
+    for (const { plugin, dir, builtFor, api } of pluginAgentLayers()) {
+      for (const m of scanLayer(dir, `plugin:${plugin}`, { requireMetaV2: true, builtFor, askApi: api, onDrop })) {
         if (taken.has(m.key)) {
           console.warn(
             `[agent-registry] plugin agent "${m.key}" (plugin "${plugin}") collides with an existing agent and was skipped`,

package/src/core/agent-store.mjs

@@ -11,6 +11,9 @@ 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
 
+import { normalizeAskBlock, validateFormDef } from '../shared/forms/form-def.mjs';
+import { ASK_LIMITS } from '../shared/forms/catalog.mjs';
+
 export { userAgentsDir }; // single source: the Phase 1 layer resolver
 
 /** A key is a bare alphanumeric stem — can never contain "/" or "..". */
@@ -24,8 +27,48 @@ function err(message, code) { return Object.assign(new Error(message), { code })
  *  `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'];
+  'workspaceStrategy', 'workspaceVariantOf', 'placeable', 'scope', 'domain', 'icon', 'ask',
+  'promptHints', 'requiresSkills', 'humanEffort'];
+
+/**
+ * GATE 1 for a sidecar's ask forms (ask-forms spec §5, §11). The SAME checks the
+ * registry runs at load and `worca plugin validate` runs on a plugin dir — one
+ * validator, three callers. Returns [] when the sidecar declares no forms.
+ * Every failed rule is named: the editor marks fields by `path`, so a single
+ * "invalid form" sentence would be unusable there.
+ * @param {object} raw a raw sidecar (pre-normalizeMeta)
+ * @returns {Array<{path: string, code: string, message: string}>}
+ */
+function askFormIssues(raw) {
+  if (!raw || raw.ask === undefined || raw.ask === null) return [];
+  // normalizeAskBlock is used ONLY for the whole-block refusals it alone knows
+  // (id '*': not `{ forms }`, or over the 64 KB cap). Its per-form `reason` is a
+  // collapsed one-liner of the first three errors — right for a registry log
+  // line, wrong for an editor that marks fields BY PATH — so each form goes
+  // through validateFormDef directly and keeps P1's paths verbatim
+  // (`layout#<n>`, a depth-first 1-based ordinal).
+  const blockDrops = normalizeAskBlock(raw.ask).dropped.filter((d) => d.id === '*');
+  if (blockDrops.length) return blockDrops.map((d) => ({ path: 'ask', code: 'dialect', message: d.reason }));
+  const issues = [];
+  const forms = raw.ask.forms && typeof raw.ask.forms === 'object' ? raw.ask.forms : {};
+  const ids = Object.keys(forms);
+  if (ids.length > ASK_LIMITS.formsPerAgent) {
+    issues.push({ path: 'ask.forms', code: 'too-many', message: `at most ${ASK_LIMITS.formsPerAgent} forms per agent` });
+  }
+  for (const id of ids) {
+    for (const e of validateFormDef(forms[id], { id }).errors) {
+      issues.push({ path: `ask.forms."${id}"${e.path ? ` ${e.path}` : ''}`, code: e.code, message: e.message });
+    }
+  }
+  return issues;
+}
+
+/** The ONE throw shape both write paths use for a failed gate 1: a joined message
+ *  for CLI/log surfaces, plus the structured list the route turns into a 422 body. */
+function askFormError(issues) {
+  return Object.assign(new Error(issues.map((i) => `${i.path}: ${i.message}`).join('; ')),
+    { code: 'ASK_FORM', errors: issues });
+}
 
 /** 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. */
@@ -76,6 +119,10 @@ export async function createAgent({ meta: rawMeta, markdown } = {}) {
   // 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');
+  // Gate 1 runs AFTER the meta gate and BEFORE normalizeMeta: normalizeMeta is
+  // lossy by design, so a form must be judged as the author wrote it.
+  const formIssues = askFormIssues(raw);
+  if (formIssues.length) throw askFormError(formIssues);
   const meta = normalizeMeta(raw);
   if (!meta) throw err('invalid agent metadata', 'BAD_REQUEST');
   const existing = loadAgentRegistry()[key];
@@ -241,6 +288,8 @@ export async function updateAgent(key, { meta: rawMeta, markdown } = {}) {
   // 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 updFormIssues = askFormIssues(raw);
+  if (updFormIssues.length) throw askFormError(updFormIssues);
   const meta = normalizeMeta(raw);
   if (!meta) throw err('invalid agent metadata', 'BAD_REQUEST');
   const dir = requireUserDir();

package/src/core/artifacts.mjs

@@ -19,6 +19,7 @@ import { branchExists, diffShortstat, hasGh, findPrForBranch } from './git-info.
 import { getDb, tx } from './db.mjs';
 import { RUN_LOG_FILE } from './run-log.mjs';
 import { readRunLedger } from './metrics/ledger.mjs';
+import { readPolicyState } from './policy/state.mjs';
 import { memoryTotals } from './memory-sync.mjs';
 
 // ── DB row <-> state object mapping (Phase 3) ──────────────────────────────────
@@ -249,6 +250,36 @@ export async function writeStepQuestions(pipelineId, stepKey, round, { agentKey,
   }
 }
 
+/**
+ * Spec §9: a form ask persists into the SAME schemaless JSON TEXT columns as the
+ * legacy Q&A — the `questions` half holds the full resolved ask, the `answers`
+ * half `{kind:'form', form, version, values}`. This merges the two into the one
+ * object History renders, or null for a legacy row. The legacy arrays are read
+ * separately and stay empty for a form row, so no existing reader changes.
+ * @param {object|null} qWrap parsed `questions` column
+ * @param {object|null} aWrap parsed `answers` column
+ */
+function formAskOf(qWrap, aWrap) {
+  if (!qWrap || qWrap.kind !== 'form') return null;
+  const values = aWrap && aWrap.kind === 'form' && aWrap.values && typeof aWrap.values === 'object'
+    ? aWrap.values
+    : null;
+  return { ...qWrap, values };
+}
+
+/** The two form fields a reader row carries — `{}` for a legacy row, so no legacy
+ *  payload gains a key (test/step-questions-db.test.mjs pins the exact row shape). */
+function formFieldsOf(qWrap, aWrap) {
+  const ask = formAskOf(qWrap, aWrap);
+  return ask ? { ask, formAnswer: formAnswerOf(aWrap) } : {};
+}
+
+/** The `{form, version, values}` payload the agent was resumed with, or null. */
+function formAnswerOf(aWrap) {
+  if (!aWrap || aWrap.kind !== 'form') return null;
+  return { form: aWrap.form, version: aWrap.version, values: aWrap.values && typeof aWrap.values === 'object' ? aWrap.values : {} };
+}
+
 /**
  * All ask-then-resume rounds of a pipeline, unwrapped to plain arrays, in
  * chronological insert order (rowid — lexicographic step_key would mis-order
@@ -270,6 +301,10 @@ export function readStepQuestions(pipelineId) {
       agentKey: r.agent_key || '',
       questions: Array.isArray(qWrap?.questions) ? qWrap.questions : [],
       answers: Array.isArray(aWrap?.answers) ? aWrap.answers : [],
+      // Ask forms (spec §9): `ask` + `formAnswer` on a FORM row only. A legacy row
+      // gains no key at all, so its wire shape (History, get_run_progress) stays
+      // byte-identical; consumers test `row.ask`, never `'ask' in row`.
+      ...formFieldsOf(qWrap, aWrap),
     };
   });
 }
@@ -348,6 +383,7 @@ export function readPipelineExtras(pipelineId) {
   const clarify = {
     questions: Array.isArray(qWrap?.questions) ? qWrap.questions : [],
     answers: Array.isArray(aWrap?.answers) ? aWrap.answers : [],
+    ...formFieldsOf(qWrap, aWrap),   // spec §9: `ask` + `formAnswer` on a form row only
   };
   const reviews = getDb().prepare(
     'SELECT kind, cycle, verdict FROM reviews WHERE pipeline_id = ? ORDER BY kind, cycle'
@@ -1128,15 +1164,16 @@ 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, outcome)
+        source_type, source_ref, guardrails_id, outcome, human_hours)
       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,@outcome)
+        @source_type,@source_ref,@guardrails_id,@outcome,@human_hours)
       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,
-        total_active_ms=excluded.total_active_ms, branch=excluded.branch,
+        total_active_ms=excluded.total_active_ms, human_hours=excluded.human_hours,
+        branch=excluded.branch,
         workspace_meta=excluded.workspace_meta, stepper=excluded.stepper,
         tools=excluded.tools,
         resume_point=excluded.resume_point,
@@ -1150,16 +1187,22 @@ export async function writeState(pipelineDir, stateObj) {
       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,
-        execution_id, exec_kind, agent_key, ended_at, exec_trigger, exec_result, exec_meta)
-      VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+        execution_id, exec_kind, agent_key, ended_at, exec_trigger, exec_result, exec_meta,
+        human_hours, human_signals)
+      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)
+      const hasMeta = st.taskId != null || st.parentExecutionId != null || st.title != null || st.phaseOrdinal != null
+        || st.nodeKey != null || st.runtime != null || st.exitCode != null || st.bridgeCalls != null;
+      const meta = hasMeta
         ? 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 })
+              taskIndex: st.taskIndex ?? null, taskTotal: st.taskTotal ?? null,
+              nodeKey: st.nodeKey ?? null, runtime: st.runtime ?? null, exitCode: st.exitCode ?? null,
+              // Model bridge (§8.6): requests the node initiated through the bridge.
+              ...(st.bridgeCalls != null ? { bridgeCalls: st.bridgeCalls, bridgeContinued: st.bridgeContinued ?? 0 } : {}) })
         : null;
       ins.run(
         id, st.key, st.nodeId ?? null, st.phase ?? null,
@@ -1178,6 +1221,8 @@ export async function writeState(pipelineDir, stateObj) {
         st.trigger === undefined ? null : s(st.trigger),
         st.result === undefined ? null : s(st.result),
         meta,
+        Number.isFinite(st.humanHours) ? st.humanHours : null,
+        st.humanSignals && typeof st.humanSignals === 'object' ? s(st.humanSignals) : null,
       );
     }
   });
@@ -1416,10 +1461,13 @@ export function reconcileStaleRunning({
     .map((r) => r.id);
   if (candidates.length === 0) return { reconciled: 0, ids: [] };
 
-  // Status-guarded UPDATE. Also NULLs owner columns so reclassified rows are clean.
+  // Status-guarded UPDATE. Also NULLs the owner columns so reclassified rows are clean.
+  // heartbeat_at STAYS: it is the last time the dead process was seen alive, and resume()
+  // measures the interrupted run's parked time (and closes its step clocks) from it. Nothing
+  // reads it on a non-running row otherwise; claimPipelineOwnership re-stamps it on resume.
   return tx(() => {
     const upd = getDb().prepare(
-      `UPDATE pipelines SET status = ?, owner_pid = NULL, owner_host = NULL, heartbeat_at = NULL
+      `UPDATE pipelines SET status = ?, owner_pid = NULL, owner_host = NULL
        WHERE id = ? AND status IN (${placeholders})`);
     const flipped = [];
     for (const id of candidates) {
@@ -1494,6 +1542,7 @@ function toPipelineRow(o) {
     updated_at: o.updatedAt ?? null,
     total_cost_usd: Number.isFinite(o.totalCostUsd) ? o.totalCostUsd : 0,
     total_active_ms: Number.isFinite(o.totalActiveMs) ? o.totalActiveMs : 0,
+    human_hours: Number.isFinite(o.humanHours) ? o.humanHours : 0,
     prompt: o.prompt ?? null,
     branch: s(o.branch),
     workspace_meta: workspaceMeta,
@@ -1841,6 +1890,8 @@ function stepRowToStep(r) {
   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);
+  if (r.human_hours != null) step.humanHours = r.human_hours;
+  if (r.human_signals != null) step.humanSignals = j(r.human_signals, null);
   const em = r.exec_meta != null ? j(r.exec_meta, null) : null;
   if (em) {
     if (em.taskId != null) step.taskId = em.taskId;
@@ -1849,6 +1900,10 @@ function stepRowToStep(r) {
     if (em.phaseOrdinal != null) step.phaseOrdinal = em.phaseOrdinal;
     if (em.taskIndex != null) step.taskIndex = em.taskIndex;
     if (em.taskTotal != null) step.taskTotal = em.taskTotal;
+    if (em.nodeKey != null) step.nodeKey = em.nodeKey;
+    if (em.runtime != null) step.runtime = em.runtime;
+    if (em.exitCode != null) step.exitCode = em.exitCode;
+    if (em.bridgeCalls != null) { step.bridgeCalls = em.bridgeCalls; step.bridgeContinued = em.bridgeContinued ?? 0; }
   }
   return step;
 }
@@ -1875,6 +1930,7 @@ function rowToState(row) {
     updatedAt: row.updated_at ?? null,
     totalCostUsd: row.total_cost_usd ?? 0,
     totalActiveMs: row.total_active_ms ?? 0,
+    humanHours: Number(row.human_hours || 0),
     prompt: row.prompt ?? null,
     baseName: row.base_name ?? null,
     datePrefix: row.date_prefix ?? null,
@@ -1882,13 +1938,17 @@ function rowToState(row) {
     stepper: j(row.stepper, null),
     tools: j(row.tools, null),
     guardrailsId: row.guardrails_id ?? null,
+    // v31 provenance: set when a schedule started this run (NULL = started by hand).
+    scheduledFor: row.scheduled_for ?? null,
+    scheduleId: row.schedule_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,
-             execution_id, exec_kind, agent_key, ended_at, exec_trigger, exec_result, exec_meta
+             execution_id, exec_kind, agent_key, ended_at, exec_trigger, exec_result, exec_meta,
+             human_hours, human_signals
       FROM pipeline_steps WHERE pipeline_id = ? ORDER BY rowid
     `).all(row.id).map(stepRowToStep),
     subAgents: listSubAgents(row.id),
@@ -2161,6 +2221,9 @@ export async function readPipelineByKey(key, id) {
     results,
     overview,
     teamMetrics: readRunLedger(row.id),
+    // Team policy (design §10 / board 10): the home the run's policy came from and what the
+    // developer did about it — the History meta line's "policy · 1 override" segment.
+    policy: readPolicyState(row.id),
     memory: await readMemoryLedger(dir),
     ...readPipelineExtras(row.id),
   };