@worca/app 1.3.0 → 1.4.0

package/src/core/db.mjs

@@ -21,6 +21,7 @@ import { mkdirSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { worcaHome } from './projects.mjs';
 import { maybeMigrateFromFs } from './migrate-fs-to-db.mjs';
+import { backfillHumanHours } from './human-backfill.mjs';
 import { SEED_TEMPLATES, NODE_ID_MAP, FB_WIRE_MAP } from './graph/seed-templates.mjs';
 
 const _require = createRequire(import.meta.url);
@@ -54,7 +55,7 @@ const OPEN_BACKOFF_MS = 15;
 /** Latest schema version. Bump + append a new migration step when the DDL grows.
  *  Exported so migration tests assert "reached the module's current version"
  *  instead of hardcoding the number — a schema bump then touches no test file. */
-export const SCHEMA_VERSION = 30;
+export const SCHEMA_VERSION = 35;
 
 /** Absolute path to the database file: <worcaHome>/worca-cc.db. */
 export function dbPath() {
@@ -306,7 +307,9 @@ CREATE INDEX idx_pipeline_events_pipeline ON pipeline_events (pipeline_id, id);
 CREATE TABLE clarify (
   pipeline_id TEXT PRIMARY KEY,
   questions   TEXT,  -- JSON: { questions: [ {id,question,options[2..4],allowFreeText} ] }
+                     --    OR: the full resolved ask form { kind:'form', … } (spec §9)
   answers     TEXT,  -- JSON: { answers: [ {id,question,choice} ] }
+                     --    OR: { kind:'form', form, version, values } (spec §9)
   FOREIGN KEY (pipeline_id) REFERENCES pipelines (id) ON DELETE CASCADE
 );
 
@@ -521,7 +524,9 @@ CREATE TABLE IF NOT EXISTS step_questions (
   node_id     TEXT,
   agent_key   TEXT,
   questions   TEXT,  -- JSON: { questions: [ {id,question,options[2..4],allowFreeText} ] }
+                     --    OR: the full resolved ask form { kind:'form', … } (spec §9)
   answers     TEXT,  -- JSON: { answers: [ {id,question,choice} ] }
+                     --    OR: { kind:'form', form, version, values } (spec §9)
   PRIMARY KEY (pipeline_id, step_key, round),
   FOREIGN KEY (pipeline_id) REFERENCES pipelines (id) ON DELETE CASCADE
 );
@@ -726,6 +731,86 @@ CREATE TABLE IF NOT EXISTS ask_card_comments (
 );
 `;
 
+/** v31 (scheduled runs): launch tickets, recurring schedule parents, and the generic
+ *  notification log. A run that waits for its start time lives HERE, never in
+ *  `pipelines`: the pipeline row is still born inside run(), so no status-aware
+ *  reader (stats, stale sweep, delete guard, team metrics) ever meets a waiting row.
+ *  IF NOT EXISTS + INCREMENTAL_TABLES entries: reconcile-safe on a divergently
+ *  stamped DB. An older build simply ignores all three tables. */
+const SCHEDULED_RUNS_DDL = `
+CREATE TABLE IF NOT EXISTS schedules (
+  id             TEXT PRIMARY KEY,           -- 'sch_' + 8 hex
+  title          TEXT,
+  project_key    TEXT,
+  project_dir    TEXT,
+  workspace_id   TEXT,
+  request        TEXT NOT NULL,              -- JSON: POST /api/run body shape (+ internal)
+  rule           TEXT NOT NULL,              -- JSON: recurrence rule (local time + tz)
+  overlap        TEXT NOT NULL DEFAULT 'skip',   -- skip | start | queue
+  max_failures   INTEGER NOT NULL DEFAULT 3,     -- 0 = never pause
+  failure_streak INTEGER NOT NULL DEFAULT 0,
+  if_missed      TEXT NOT NULL DEFAULT 'run',    -- run | skip
+  grace_min      INTEGER NOT NULL DEFAULT 360,
+  status         TEXT NOT NULL DEFAULT 'active', -- active | paused | ended
+  pause_reason   TEXT,                       -- user | failure_streak
+  runs_count     INTEGER NOT NULL DEFAULT 0,
+  next_run_at    TEXT,
+  last_result    TEXT,                       -- last occurrence outcome (display)
+  ask_thread_id  TEXT,                       -- the Ask Worca card that made it (NULL = made by hand)
+  ask_card_id    TEXT,
+  created_at     TEXT NOT NULL,
+  updated_at     TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS scheduled_runs (
+  id           TEXT PRIMARY KEY,             -- the runId UUID the fired run will carry
+  schedule_id  TEXT REFERENCES schedules(id) ON DELETE CASCADE,
+  title        TEXT,
+  project_key  TEXT,
+  project_dir  TEXT,
+  workspace_id TEXT,
+  run_at       TEXT NOT NULL,                -- UTC ISO instant
+  request      TEXT NOT NULL,                -- JSON: POST /api/run body shape (+ internal)
+  status       TEXT NOT NULL DEFAULT 'scheduled', -- scheduled|firing|fired|canceled|skipped|missed|failed
+  if_missed    TEXT NOT NULL DEFAULT 'run',
+  grace_min    INTEGER NOT NULL DEFAULT 360,
+  attempts     INTEGER NOT NULL DEFAULT 0,
+  retry_at     TEXT,                         -- next attempt after a transient start error
+  queued       INTEGER NOT NULL DEFAULT 0,   -- overlap=queue: waiting for the previous run
+  forced       INTEGER NOT NULL DEFAULT 0,   -- Run now: start at once, bypass missed/overlap checks
+  owner_pid    INTEGER,                      -- a waiting --wait CLI (or the firing process)
+  owner_host   TEXT,
+  pipeline_id  TEXT,
+  fail_reason  TEXT,
+  ask_thread_id TEXT,
+  ask_card_id  TEXT,
+  after_kind   TEXT,                         -- v34: 'ticket' | 'pipeline' | NULL (a timed ticket)
+  after_id     TEXT,                         -- v34: scheduled_runs.id | pipelines.id
+  after_policy TEXT NOT NULL DEFAULT 'done', -- v34: done | any
+  source_from_previous INTEGER NOT NULL DEFAULT 0,  -- v34: start on the predecessor's feature branch
+  created_at   TEXT NOT NULL,
+  updated_at   TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_scheduled_runs_due ON scheduled_runs (status, run_at);
+CREATE INDEX IF NOT EXISTS idx_scheduled_runs_schedule ON scheduled_runs (schedule_id);
+CREATE INDEX IF NOT EXISTS idx_scheduled_runs_after ON scheduled_runs (after_id);
+CREATE TABLE IF NOT EXISTS notifications (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  scope       TEXT NOT NULL DEFAULT 'schedule',
+  kind        TEXT NOT NULL,                 -- missed|failed|skipped|late|paused|completed|run_error|run_paused|ended|retrying
+  severity    TEXT NOT NULL DEFAULT 'problem',   -- problem | info
+  schedule_id TEXT,
+  ticket_id   TEXT,
+  pipeline_id TEXT,
+  project_dir TEXT,
+  title       TEXT,
+  message     TEXT NOT NULL,
+  created_at  TEXT NOT NULL,
+  read_at     TEXT,
+  resolved_at TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_notifications_scope ON notifications (scope, created_at);
+`;
+
 const SCHEMA_V11 = `
 ALTER TABLE config_workflow_nodes ADD COLUMN ask_questions INTEGER;
 ${STEP_QUESTIONS_DDL}
@@ -746,10 +831,14 @@ const INCREMENTAL_COLUMNS = {
                             source_type: "TEXT DEFAULT 'prompt'", source_ref: 'TEXT', guardrails_id: 'TEXT',
                             archived_at: 'TEXT', cost_cap_override: 'INTEGER NOT NULL DEFAULT 0',
                             pr_url: 'TEXT', pr_number: 'INTEGER', pr_state: 'TEXT', pr_checked_at: 'TEXT',
-                            outcome: 'TEXT' },
+                            outcome: 'TEXT',
+                            scheduled_for: 'TEXT', schedule_id: 'TEXT',   // v31: scheduled-run provenance (NULL = started by hand)
+                            policy_state: 'TEXT',     // v32: team-policy run state (JSON: home, sha, overrides, exceeded, deviations, reason)
+                            human_hours: 'REAL NOT NULL DEFAULT 0' },   // v33: Σ pipeline_steps.human_hours (money-saved design §6)
   pipeline_steps:         { session_id: 'TEXT', skills: 'TEXT', graphify_count: 'INTEGER',
                             execution_id: 'TEXT', exec_kind: 'TEXT', agent_key: 'TEXT', ended_at: 'TEXT',
-                            exec_trigger: 'TEXT', exec_result: 'TEXT', exec_meta: 'TEXT' },
+                            exec_trigger: 'TEXT', exec_result: 'TEXT', exec_meta: 'TEXT',
+                            human_hours: 'REAL', human_signals: 'TEXT' },   // v33: per-execution human-hours credit + its signals JSON
   sub_agents:             { ui_phase: 'TEXT', skills: 'TEXT', subagent_type: 'TEXT', graphify_count: 'INTEGER',
                             run_model: 'TEXT' },   // v25: the model the child actually ran on
   workflows:              { domain: 'TEXT', origin: 'TEXT', graph: 'TEXT', archived_at: 'TEXT' },
@@ -760,7 +849,11 @@ const INCREMENTAL_COLUMNS = {
                             mime: 'TEXT' },               // v27: sniffed mime; NULL on pre-v27 rows (= text)
   project_config:         { human_in_loop: 'INTEGER NOT NULL DEFAULT 1' },   // v28: the Auto entry's human-in-the-loop switch
   diff_comments:          { parent_id: 'TEXT REFERENCES diff_comments(id) ON DELETE CASCADE' },  // v29: reply threads; NULL = thread root
-  workspaces:             { metrics_project: 'TEXT' },  // v30: team-metrics home (member absolute path); NULL = no home
+  workspaces:             { metrics_project: 'TEXT',    // v30: team-metrics home (member absolute path); NULL = no home
+                            policy_project: 'TEXT' },   // v32: team-policy home (member absolute path); NULL = no home
+  schedules:              { ask_thread_id: 'TEXT', ask_card_id: 'TEXT' },  // v31: the Ask Worca card a series came from
+  scheduled_runs:         { after_kind: 'TEXT', after_id: 'TEXT', after_policy: "TEXT NOT NULL DEFAULT 'done'",
+                            source_from_previous: 'INTEGER NOT NULL DEFAULT 0' },   // v34: run chains
 };
 
 /** v23: per-loop-wire cycle budgets, the graph-engine twin of
@@ -801,6 +894,9 @@ const INCREMENTAL_TABLES = {
   ask_worktrees:     ASK_WORKTREES_DDL,
   diff_comments:     DIFF_COMMENTS_DDL,
   ask_card_comments: DIFF_COMMENTS_DDL,
+  schedules:         SCHEDULED_RUNS_DDL,
+  scheduled_runs:    SCHEDULED_RUNS_DDL,
+  notifications:     SCHEDULED_RUNS_DDL,
 };
 
 /**
@@ -816,6 +912,10 @@ const INCREMENTAL_INDEXES = {
     table: 'ask_attachments',
     ddl: 'CREATE INDEX IF NOT EXISTS idx_ask_attachments_thread ON ask_attachments (thread_id)',
   },
+  idx_scheduled_runs_after: {
+    table: 'scheduled_runs',
+    ddl: 'CREATE INDEX IF NOT EXISTS idx_scheduled_runs_after ON scheduled_runs (after_id)',
+  },
 };
 
 /**
@@ -861,22 +961,29 @@ function schemaGaps(db) {
 
 /** Apply the gap repairs with NO transaction control of its own — the caller owns
  *  the transaction (the ladder tx in migrate(), or reconcileSchema's own lock).
- *  ORDER IS LOAD-BEARING: tables and indexes FIRST, then the columns RE-probed
- *  against the post-CREATE schema. `gaps.columns` was computed BEFORE this pass
- *  ran, so it cannot see an incremental column on a table this pass is about to
- *  create (ask_run_links.comment_ids on a >=20-stamped DB missing the ask
- *  tables) — the ALTER would be skipped and the DB stamped current with the
- *  column absent, and only a LATER migrate() would heal it. No gap DDL
- *  references an INCREMENTAL_COLUMNS column, so nothing here needs an ALTER to
- *  run first. */
+ *  ORDER IS LOAD-BEARING, three ways:
+ *  1. Columns on the tables that ALREADY exist go first. A table's DDL block may carry a
+ *     CREATE INDEX on an INCREMENTAL_COLUMNS column (v34: SCHEDULED_RUNS_DDL's
+ *     idx_scheduled_runs_after names scheduled_runs.after_id), and INCREMENTAL_TABLES
+ *     re-execs the WHOLE block when any sibling table (schedules / notifications) is
+ *     missing — CREATE TABLE IF NOT EXISTS skips the old-shape table and the index
+ *     would throw `no such column` inside getDb().
+ *  2. Then the tables; then the columns RE-probed against the post-CREATE schema.
+ *     `gaps.columns` was computed BEFORE this pass ran, so it cannot see an incremental
+ *     column on a table this pass is about to create (ask_run_links.comment_ids on a
+ *     >=20-stamped DB missing the ask tables) — the ALTER would be skipped and the DB
+ *     stamped current with the column absent, and only a LATER migrate() would heal it.
+ *  3. INCREMENTAL_INDEXES last, for the same reason as 1. */
 function repairSchemaGaps(db, gaps) {
+  const addColumns = () => {
+    for (const { table, col, type } of missingColumns(db)) db.exec(`ALTER TABLE ${table} ADD COLUMN ${col} ${type}`);
+  };
+  addColumns();
   // One DDL block can create several tables (ASK_DDL, DIFF_COMMENTS_DDL) — the
   // Set collapses the duplicate keys to a single idempotent exec.
   for (const ddl of new Set((gaps.tables || []).map((t) => INCREMENTAL_TABLES[t]))) db.exec(ddl);
+  addColumns();
   for (const name of gaps.indexes || []) db.exec(INCREMENTAL_INDEXES[name].ddl);
-  for (const { table, col, type } of missingColumns(db)) {
-    db.exec(`ALTER TABLE ${table} ADD COLUMN ${col} ${type}`);
-  }
 }
 
 /**
@@ -1157,6 +1264,48 @@ function applySchemaV30(db) {
   repairSchemaGaps(db, schemaGaps(db));
 }
 
+/** v31 (scheduled runs): schedules + scheduled_runs + notifications (INCREMENTAL_TABLES)
+ *  and pipelines.scheduled_for/schedule_id (INCREMENTAL_COLUMNS) — applySchemaV30's shape. */
+function applySchemaV31(db) {
+  repairSchemaGaps(db, schemaGaps(db));
+}
+
+/** v32 (team policy): pipelines.policy_state + workspaces.policy_project — two plain
+ *  additive columns declared in INCREMENTAL_COLUMNS, applySchemaV30's shape. NULL on
+ *  every existing row = no team policy touched this run / no policy home yet.
+ *  It is v32, not v31: scheduled runs claimed 31 on dev first, and a DB already
+ *  stamped 31 by that ladder would skip these columns forever (the v11 collision
+ *  this file's INCREMENTAL_COLUMNS comment describes). */
+function applySchemaV32(db) {
+  repairSchemaGaps(db, schemaGaps(db));
+}
+
+/** v33 (money saved): pipelines.human_hours + pipeline_steps.human_hours/human_signals —
+ *  additive columns declared in INCREMENTAL_COLUMNS, applySchemaV32's shape. Task 5 adds
+ *  the run-level backfill call for pre-v33 runs here. */
+function applySchemaV33(db) {
+  repairSchemaGaps(db, schemaGaps(db));
+  // Legacy credit for every terminal run recorded before v33. Best-effort by construction;
+  // a throw here would roll the ladder back, so it is fenced. Runs once (the fast path
+  // reconcileSchema never calls it). Cost: one read per indexed plan/review markdown.
+  try { backfillHumanHours(db); } catch { /* never fail the migration on the backfill */ }
+}
+
+/** v34 (run chains): scheduled_runs.after_kind/after_id/after_policy/source_from_previous + the
+ *  after_id index — INCREMENTAL_COLUMNS / INCREMENTAL_INDEXES, applySchemaV30's shape. */
+function applySchemaV34(db) {
+  repairSchemaGaps(db, schemaGaps(db));
+}
+
+/** v35 (Opus 5.5 replaces Opus 5 in PREDEFINED_MODELS): V26's catalog swap again —
+ *  same reasons, same stores, same rules (renameStoredModelPins). History keeps
+ *  recording `claude-opus-5` where that is what ran. */
+const V35_MODEL_RENAMES = [['claude-opus-5', 'claude-opus-5-5']];
+
+function applySchemaV35(db) {
+  for (const [from, to] of V35_MODEL_RENAMES) renameStoredModelPins(db, from, to);
+}
+
 /** Move every stored pin on model id `from` (lower-case) to `to`. Each table
  *  is guarded like V24's: hand-seeded upgrade fixtures (and a DB from before the
  *  fs->db import) reach this step without some of them. */
@@ -1543,6 +1692,11 @@ export function migrate(db) {
     if (current < 28) applySchemaV28(db);            // Auto workflow: human_in_loop + flip to wf_auto
     if (current < 29) applySchemaV29(db);            // diff-comment reply threads: parent_id
     if (current < 30) applySchemaV30(db);            // team metrics: workspaces.metrics_project
+    if (current < 31) applySchemaV31(db);            // scheduled runs: tickets + schedules + notifications
+    if (current < 32) applySchemaV32(db);            // team policy: pipelines.policy_state + workspaces.policy_project
+    if (current < 33) applySchemaV33(db);            // money saved: human_hours columns
+    if (current < 34) applySchemaV34(db);            // run chains: scheduled_runs.after_* + source_from_previous
+    if (current < 35) applySchemaV35(db);            // Opus 5 pins -> Opus 5.5 (catalog swap)
     db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
     db.exec('COMMIT');
   } catch (err) {

package/src/core/failure-policy.mjs

@@ -40,6 +40,10 @@ export const REASON = Object.freeze({
   ERROR: 'error',                 // a failure that would otherwise have ended the run
   COST_PIPELINE: 'cost_pipeline', // the per-pipeline cost cap
   COST_TOTAL: 'cost_total',       // the total (weekly/monthly) cost cap
+  // Team policy (soft caps set on the worca-policy branch): the same two gates, but the
+  // binding number came from the team, so the resume flow offers "continue past".
+  COST_PIPELINE_POLICY: 'cost_pipeline_policy',
+  COST_TOTAL_POLICY: 'cost_total_policy',
 });
 export const REASON_CODES = Object.freeze(Object.values(REASON));
 
@@ -92,6 +96,10 @@ export const FAILURE_POLICY = Object.freeze({
   budget: Object.freeze({
     cost_pipeline: both(pause(REASON.COST_PIPELINE)),
     cost_total:    both(pause(REASON.COST_TOTAL)),
+    // Team soft caps pause only when someone can click "continue past": the harness
+    // downgrades them to a warning under --yes before ever reaching this row.
+    cost_pipeline_policy: both(pause(REASON.COST_PIPELINE_POLICY)),
+    cost_total_policy:    both(pause(REASON.COST_TOTAL_POLICY)),
   }),
   // run()'s setup — checkout, graph build, skills gate — failed with the pipeline
   // row already created. A pause here stamps `setupIncomplete`; resume replays it.
@@ -177,6 +185,8 @@ const CONSEQUENCES = Object.freeze({
   [REASON.RECOVERABLE]:  { reportsToSource: true,  stagesResults: false, severity: 'warning', notifyPref: 'paused', exitInteractive: 0, label: 'recoverable error — resume to retry' },
   [REASON.COST_PIPELINE]:{ reportsToSource: true,  stagesResults: false, severity: 'warning', notifyPref: 'paused', exitInteractive: 0, label: 'pipeline cost limit reached' },
   [REASON.COST_TOTAL]:   { reportsToSource: true,  stagesResults: false, severity: 'warning', notifyPref: 'paused', exitInteractive: 0, label: 'total cost limit reached' },
+  [REASON.COST_PIPELINE_POLICY]: { reportsToSource: true, stagesResults: false, severity: 'warning', notifyPref: 'paused', exitInteractive: 0, label: 'team cost cap reached' },
+  [REASON.COST_TOTAL_POLICY]:    { reportsToSource: true, stagesResults: false, severity: 'warning', notifyPref: 'paused', exitInteractive: 0, label: 'team total cap reached' },
   [REASON.ERROR]:        { reportsToSource: true,  stagesResults: true,  severity: 'error',   notifyPref: 'error',  exitInteractive: 1, label: 'a step failed' },
 });
 

package/src/core/fs-browse.mjs

@@ -8,14 +8,26 @@
 import { readdir, stat } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { normalizeProjectPath } from './projects.mjs';
-import { defaultRoot } from './settings.mjs';
+import { defaultRoot, getProjectsRoot } from './settings.mjs';
 
 function err(message, code) { return Object.assign(new Error(message), { code }); }
 
+/** Where a blank listing opens: the projects root if it is a directory, else home. */
+async function startFolder(home) {
+  const root = getProjectsRoot();
+  try {
+    if (root !== home && (await stat(root)).isDirectory()) return root;
+  } catch { /* missing or unreadable root: fall back to home */ }
+  return home;
+}
+
 /**
  * List the sub-directories of `input` (tilde-expanded, resolved). Empty input
- * lists the OS home directory (normalizeProjectPath returns null for blank
- * input, so this can never fall through to process.cwd()).
+ * lists the effective projects root when it is an existing directory, else the
+ * OS home directory (normalizeProjectPath returns null for blank input, so this
+ * can never fall through to process.cwd()). With nothing configured the two are
+ * the same folder; in a container, WORCA_PROJECTS_ROOT names the mounted repos
+ * while home is an empty /home/worca. `home` stays the OS home (the Home button).
  * @param {string} input
  * @returns {Promise<{path:string, parent:string|null, home:string,
  *   dirs:Array<{name:string, path:string}>}>} parent is null at the fs root.
@@ -24,7 +36,7 @@ function err(message, code) { return Object.assign(new Error(message), { code })
  */
 export async function listFolders(input) {
   const home = resolve(defaultRoot());
-  const path = normalizeProjectPath(input) || home;
+  const path = normalizeProjectPath(input) || await startFolder(home);
   let entries;
   try {
     entries = await readdir(path, { withFileTypes: true });

package/src/core/git-info.mjs

@@ -438,6 +438,28 @@ export async function listRemotes(projectDir) {
   return { ok: true, remotes };
 }
 
+/**
+ * The branches each named remote has, from the LOCAL remote-tracking refs
+ * (`refs/remotes/<remote>/*` — no network, as fresh as the last fetch). A remote
+ * name may itself hold a slash, so the longest matching name owns a ref; the
+ * symbolic `HEAD` is dropped. Never throws:
+ * { ok:true, byRemote:{ [name]: string[] } } | { ok:false, byRemote:{}, error }.
+ */
+export async function listRemoteBranches(projectDir, remoteNames = []) {
+  if (!projectDir) return { ok: false, byRemote: {}, error: 'projectDir is required' };
+  const r = await _run('git', ['for-each-ref', '--format=%(refname)', 'refs/remotes/'], { cwd: projectDir });
+  if (!r.ok) return { ok: false, byRemote: {}, error: (r.stderr || '').trim() || `git exited ${r.code}` };
+  const names = [...remoteNames].sort((a, b) => b.length - a.length);
+  const byRemote = Object.fromEntries(remoteNames.map((n) => [n, []]));
+  for (const raw of (r.stdout || '').split(/\r?\n/)) {
+    const rest = raw.trim().startsWith('refs/remotes/') ? raw.trim().slice('refs/remotes/'.length) : '';
+    const name = rest && names.find((n) => rest.startsWith(`${n}/`));
+    const branch = name ? rest.slice(name.length + 1) : '';
+    if (branch && branch !== 'HEAD') byRemote[name].push(branch);
+  }
+  return { ok: true, byRemote };
+}
+
 // Test seam: swap the command runner + clear the gh memo. Mirrors server.mjs#_testing.
 export const _testing = {
   defaultRun,

package/src/core/graph/builtin-workflows.mjs

@@ -83,7 +83,9 @@ export const GRAPH_MEMORY_DEFRAG_WORKFLOW = deepFreeze({
   updatedAt: '1970-01-01T00:00:00.000Z',
   nodes: [
     { id: 'n_task', kind: 'task', x: 40, y: 200, config: {} },
-    { id: 'n_defrag', kind: 'agent', key: 'memoryDefragmenter', x: 320, y: 200, config: {} },
+    // Sonnet 5 by default: a bounded restructure of a few markdown files. The template layer
+    // is the lowest (workflows.mjs resolveGraph), so a per-role or per-node pick still wins.
+    { id: 'n_defrag', kind: 'agent', key: 'memoryDefragmenter', x: 320, y: 200, config: { model: 'claude-sonnet-5' } },
     { id: 'n_end', kind: 'end', x: 600, y: 200, config: {} },
   ],
   wires: [

package/src/core/graph/exec-io.mjs

@@ -0,0 +1,71 @@
+// src/core/graph/exec-io.mjs
+//
+// Execution I/O shared by every executor that publishes ports and reads a verdict:
+// the agent executor (executor.mjs) and the script runner (script-runner.mjs). Moved
+// out of executor.mjs so the script runner needs no executor import and no cycle;
+// executor.mjs re-exports `readVerdict` and `publishable` for its existing importers.
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { relative, basename } from 'node:path';
+
+import { normalizeReview, safeParseJson } from '../protocol.mjs';
+
+// ── verdicts ──────────────────────────────────────────────────────────────────
+
+/** The text every unparseable verdict file fails with. */
+const BAD_VERDICT_TAIL = 'expected { "issues": [ \u2026 ] }';
+
+/**
+ * Read a node's verdict JSON back through the protocol normalizer.
+ *
+ * Two degenerate cases, deliberately split (they are NOT the same failure):
+ *  - the file was NEVER WRITTEN -> `{issues: [], summary: '', missing: true}`: a clean
+ *    pass, v1 parity, because an agent that declares a verdict and writes none must not
+ *    fail a run. `missing` is the flag the caller turns into a warning (and the reason
+ *    the reviews table skips the row) instead of a phantom zero-issue review.
+ *  - the file EXISTS but does not parse, or carries no `issues` array -> THROW. The
+ *    verifier wrote garbage, and on every shipped seed the clean side is wired straight
+ *    to End, so "no issues" there is indistinguishable from an approval. Fail-fast owns
+ *    the rest.
+ *
+ * `readReview` is untouched for its other callers (it is v1 code with its own tolerant
+ * contract); the existsSync + parse-failure branch lives here.
+ */
+export async function readVerdict(verdictPath) {
+  if (!verdictPath) return { issues: [], summary: '' };
+  if (!existsSync(verdictPath)) return { issues: [], summary: '', missing: true };
+  let text;
+  try {
+    text = await readFile(verdictPath, 'utf8');
+  } catch (err) {
+    throw Object.assign(new Error(`verdict file unreadable: ${verdictPath} — ${err?.message || err}`),
+      { code: 'BAD_VERDICT' });
+  }
+  const data = safeParseJson(text);
+  if (!data || typeof data !== 'object' || !Array.isArray(data.issues)) {
+    throw Object.assign(new Error(`verdict file is not a review JSON: ${verdictPath} — ${BAD_VERDICT_TAIL}`),
+      { code: 'BAD_VERDICT' });
+  }
+  return normalizeReview(data);
+}
+
+/** The warning line a missing verdict raises, relative to the pipeline dir so the
+ *  run log stays readable. */
+export function missingVerdictWarning(ctx, verdictPath) {
+  const rel = ctx?.pipelineDir ? relative(ctx.pipelineDir, verdictPath) : basename(verdictPath);
+  return `verdict file missing: ${ctx?.nodeId || ctx?.node?.id || '?'} ${rel} — treated as clean`;
+}
+
+// ── publishing ────────────────────────────────────────────────────────────────
+
+/** The output map the scheduler publishes from: an entry per declared port, with a
+ *  path where one was allocated and an empty payload for void ports. Exported for
+ *  P4's composite `finish` arm. */
+export function publishable(ports, outputs) {
+  const out = {};
+  for (const port of ports?.outputs || []) {
+    if (!port) continue;
+    out[port.id] = outputs[port.id]?.path ? { path: outputs[port.id].path } : {};
+  }
+  return out;
+}