@worca/app 1.2.0 → 1.3.0-rc.2

package/src/core/settings.mjs

@@ -277,6 +277,67 @@ export function contextMaxBytesTotal() {
   return readByteCap('contextMaxBytesTotal', DEFAULT_CONTEXT_MAX_BYTES_TOTAL);
 }
 
+// ── Agent memory caps (agent-memory-design.md §2 / §12) ─────────────────────
+export const DEFAULT_MEMORY_SOFT_BYTES_PER_FILE = 8192;    // flagged in health above this
+export const DEFAULT_MEMORY_HARD_BYTES_PER_FILE = 32768;   // rejected at sync-back / write above this
+export const DEFAULT_MEMORY_MAX_FILES_PER_SCOPE = 50;
+export const DEFAULT_MEMORY_HOOK_MAX_CHARS = 160;
+
+export const DEFAULT_MEMORY_DEFRAG_WRITES = 10;     // writesSinceDefrag at which a scope is "due"
+export const DEFAULT_MEMORY_DEFRAG_FILES = 30;      // file count at which a scope is "due"
+export const DEFAULT_MEMORY_DEFRAG_BYTES_PCT = 60;  // % of (maxFilesPerScope × softBytesPerFile) at which a scope is "due"
+export const DEFAULT_MEMORY_DEFRAG_ALWAYS_ON_BYTES = 16384;  // bytes of path-less memory (loaded into EVERY agent's context) at which a scope is "due"
+
+/** settings.json → { memory: { maxBytesPerFile, softBytesPerFile, maxFilesPerScope, hookMaxChars,
+ *  defrag: { writes, files, bytesPct, alwaysOnBytes } } }. Every key optional; a bad value warns (naming the full key) and falls back. */
+function memoryBlock() {
+  const block = readSettings().memory;
+  return block && typeof block === 'object' && !Array.isArray(block) ? block : {};
+}
+function readMemoryCap(key, fallback) {
+  const v = memoryBlock()[key];
+  if (v === undefined) return fallback;
+  if (isByteCap(v)) return v;
+  console.warn(`[worca] invalid memory.${key} ${JSON.stringify(v)} — using ${fallback}`);
+  return fallback;
+}
+let warnedDefragBlock = false;   // module-level: the reader runs once per threshold key, the block is one mistake
+/** `memory.defrag.<key>`: a positive integer; `bytesPct` additionally ≤ 100 (it is a share).
+ *  A `defrag` that is not a plain object is one mistake, not three: warn ONCE and fall back. */
+function readDefragThreshold(key, fallback, { pct = false } = {}) {
+  const d = memoryBlock().defrag;
+  const isBlock = Boolean(d) && typeof d === 'object' && !Array.isArray(d);
+  if (d !== undefined && !isBlock) {
+    if (!warnedDefragBlock) {
+      warnedDefragBlock = true;
+      console.warn(`[worca] invalid memory.defrag ${JSON.stringify(d)} — using the defaults`);
+    }
+    return fallback;
+  }
+  const v = isBlock ? d[key] : undefined;
+  if (v === undefined) return fallback;
+  if (isByteCap(v) && (!pct || v <= 100)) return v;
+  console.warn(`[worca] invalid memory.defrag.${key} ${JSON.stringify(v)} — using ${fallback}`);
+  return fallback;
+}
+
+/** The caps every memory reader/writer takes (memory-store.mjs, memory-sync.mjs). Read fresh per call.
+ *  `defrag` is the health threshold block (agent-memory-design.md §8 / §12). */
+export function memoryCaps() {
+  return {
+    softBytesPerFile: readMemoryCap('softBytesPerFile', DEFAULT_MEMORY_SOFT_BYTES_PER_FILE),
+    hardBytesPerFile: readMemoryCap('maxBytesPerFile', DEFAULT_MEMORY_HARD_BYTES_PER_FILE),
+    maxFilesPerScope: readMemoryCap('maxFilesPerScope', DEFAULT_MEMORY_MAX_FILES_PER_SCOPE),
+    hookMaxChars: readMemoryCap('hookMaxChars', DEFAULT_MEMORY_HOOK_MAX_CHARS),
+    defrag: {
+      writes: readDefragThreshold('writes', DEFAULT_MEMORY_DEFRAG_WRITES),
+      files: readDefragThreshold('files', DEFAULT_MEMORY_DEFRAG_FILES),
+      bytesPct: readDefragThreshold('bytesPct', DEFAULT_MEMORY_DEFRAG_BYTES_PCT, { pct: true }),
+      alwaysOnBytes: readDefragThreshold('alwaysOnBytes', DEFAULT_MEMORY_DEFRAG_ALWAYS_ON_BYTES),
+    },
+  };
+}
+
 /** Skill delivery mechanism (§5.6): 'copy' (default, isolated) | 'symlink' (write-through). */
 export function skillMount() {
   const v = readSettings().skillMount;
@@ -544,6 +605,8 @@ export const SETTINGS_POST_KEYS = Object.freeze([
   'askMaxTurns', 'askMaxBudgetUsd',
   'debugSpawnEnabled',
   'titleModel', 'hideBuiltinModels',
+  'theme',
+  'autoWorkflowModel',                       // auto-workflow spec D14
 ]);
 
 // ── Title-generation model + hidden built-ins (#422) ─────────────────────────
@@ -606,6 +669,74 @@ export async function setHideBuiltinModels(input) {
   return { hideBuiltinModels: hideBuiltinModels() };
 }
 
+// ── Theme mode (2026-09-04 dark-mode design §6.1) ────────────────────────────
+// One machine-wide preference: `system` follows the OS, `light`/`dark` force a
+// scheme. The server writes it into the shell's <html data-theme> at serve time
+// (ui/server.mjs sendIndex) and the client keeps it live; the value is read at
+// use time like every other stored setting, so a save reaches the next request.
+export const THEME_MODES = Object.freeze(['system', 'light', 'dark']);
+export const DEFAULT_THEME = 'system';
+const isThemeMode = (v) => THEME_MODES.includes(v);
+
+/** STORED theme mode; an absent key is the default, an invalid value is the default (loudly). */
+export function theme() {
+  const v = readSettings().theme;
+  if (v === undefined) return DEFAULT_THEME;
+  if (isThemeMode(v)) return v;
+  console.warn(`[worca] invalid theme ${JSON.stringify(v)} — using the default (${DEFAULT_THEME})`);
+  return DEFAULT_THEME;
+}
+
+/** @throws {Error} unless `input` is system|light|dark, or empty/null (a clear). */
+export function assertThemeInput(input) {
+  if (isClearInput(input)) return;
+  if (!isThemeMode(input)) throw new Error('theme must be system, light or dark');
+}
+
+export async function setTheme(input) {
+  assertThemeInput(input);
+  const settings = readSettings();
+  if (isClearInput(input) || input === DEFAULT_THEME) delete settings.theme;
+  else settings.theme = input;
+  await persistSettings(settings);
+  return { theme: theme() };
+}
+
+// ── Auto workflow classifier model (auto-workflow spec D14) ─────────────────
+// '' = unset: the runtime resolves a default from the catalog
+// (src/core/auto/model.mjs). Read at use time like every other stored setting.
+
+/** The configured classifier model id, or '' when unset. */
+export function autoWorkflowModel() {
+  const v = readSettings().autoWorkflowModel;
+  return typeof v === 'string' ? v.trim() : '';
+}
+
+/**
+ * Validate a POST value. With `models` (the effective catalog) the id must name an
+ * entry and comes back in the catalog's casing; without it the id is returned as
+ * given (CLI, tests). Empty/null/undefined means "clear".
+ * @returns {string|null} the canonical id to store, null to clear
+ * @throws {Error} on a non-string or an id the catalog does not carry
+ */
+export function assertAutoWorkflowModelInput(input, models = null) {
+  if (input === '' || input === null || input === undefined) return null;
+  if (typeof input !== 'string' || !input.trim()) throw new Error('autoWorkflowModel must be a catalog model id');
+  const id = input.trim();
+  if (!Array.isArray(models)) return id;
+  const hit = models.find((m) => m && typeof m.id === 'string' && m.id.toLowerCase() === id.toLowerCase());
+  if (!hit) throw new Error(`unknown model "${id}" — add it to the catalog first`);
+  return hit.id;
+}
+
+export async function setAutoWorkflowModel(input, { models = null } = {}) {
+  const id = assertAutoWorkflowModelInput(input, models);
+  const settings = readSettings();
+  if (id === null) delete settings.autoWorkflowModel; else settings.autoWorkflowModel = id;
+  await persistSettings(settings);
+  return { autoWorkflowModel: autoWorkflowModel() };
+}
+
 // ── Spawn-debug diagnostics toggle (the stored side of WORCA_DEBUG_SPAWN) ────
 // Like every other stored setting (skillMount, the cost caps, the ask caps) this
 // is READ AT USE TIME: claude-runner.mjs#debugSpawnEnabled calls
@@ -912,3 +1043,34 @@ export async function removeGlobalModel(id) {
   if (!settings.models.length) delete settings.models;
   await persistSettings(settings);
 }
+
+// ── Getting started (onboarding) ─────────────────────────────────────────────
+// Two machine-wide flags, nothing more: which steps are DONE is derived from
+// product state by src/core/onboarding.mjs and never stored. `hidden` is the
+// checklist's Hide (Settings › General › Getting started shows it again);
+// `welcomeSeen` is the one-time welcome dialog. Both absent = both false.
+export function onboardingPrefs() {
+  const o = readSettings().onboarding;
+  const obj = o && typeof o === 'object' && !Array.isArray(o) ? o : {};
+  return { hidden: obj.hidden === true, welcomeSeen: obj.welcomeSeen === true };
+}
+
+/** @throws {Error} unless every present key is a boolean. Unknown keys are refused. */
+export function assertOnboardingPrefsInput(patch) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw new Error('onboarding prefs must be an object');
+  for (const [k, v] of Object.entries(patch)) {
+    if (k !== 'hidden' && k !== 'welcomeSeen') throw new Error(`unknown onboarding key ${JSON.stringify(k)}`);
+    if (typeof v !== 'boolean') throw new Error(`onboarding.${k} must be true or false`);
+  }
+}
+
+/** Merge `patch` over the stored flags; a store with both flags false drops the key. */
+export async function setOnboardingPrefs(patch = {}) {
+  assertOnboardingPrefsInput(patch);
+  const settings = readSettings();
+  const next = { ...onboardingPrefs(), ...patch };
+  if (!next.hidden && !next.welcomeSeen) delete settings.onboarding;
+  else settings.onboarding = next;
+  await persistSettings(settings);
+  return onboardingPrefs();
+}

package/src/core/sources.mjs

@@ -283,7 +283,10 @@ export async function retryWriteback(pipelineId) {
       try {
         const meta = readStoreMeta(row.project_key);
         if (meta?.path && (await hasGh())) {
-          prUrl = (await findPrForBranch({ projectDir: meta.path, head: branch }))?.url || null;
+          // The persisted pr_url (SELECT * above) resolves a cross-repo PR by URL; the
+          // branch search stays the fallback for rows that never recorded one.
+          const persisted = row.pr_url || null;
+          prUrl = (await findPrForBranch({ projectDir: meta.path, head: branch, prUrl: persisted }))?.url || null;
         }
       } catch { prUrl = null; }
     }

package/src/core/store.mjs

@@ -32,6 +32,11 @@ export function canonicalProjectRoot(projectDir) {
   try { return realpathSync(dir); } catch { return dir; }
 }
 
+/** The SHAPE projectKey() produces — `<slug>-<sha1[:8]>`, lowercase. One source of truth for the
+ *  readers that validate a key before a lookup or a path join (ui/server.mjs' /api/memory routes),
+ *  next to WORKSPACE_KEY_RE's role in workspaces.mjs. */
+export const PROJECT_KEY_RE = /^[a-z0-9][a-z0-9-]*-[0-9a-f]{8}$/;
+
 /** Stable key for a project. Memoized by resolved input path. */
 export function projectKey(projectDir) {
   const cacheKey = resolve(projectDir);

package/src/core/workflow-export.mjs

@@ -41,6 +41,7 @@ import { portsOf, findPort } from '../shared/graph/ports.mjs';
 /** Canonical leading-`---` YAML frontmatter matcher (was workflows.mjs FRONTMATTER_RE).
  *  Group 1 is the inner YAML; the whole match (m[0]) is the fence block incl. its
  *  trailing newline when present. */
+// Readers use src/core/frontmatter.mjs; this stays a WRITER's fence matcher (m[0] bounds the stamp insertion — byte-pinned by the export tests).
 const FRONTMATTER_RE = /^---\s*\n([\s\S]*?)\n---\n?/;
 
 /**
@@ -379,6 +380,7 @@ function deriveNodeIo(graph, tnode, nodeKey, { cycle = 1, channelDefs } = {}) {
 async function buildExportSet({ workflowId, destination, projectDir, slug, includeAgents = true, repoRoot }) {
   const tpl = await readWorkflow(workflowId);
   if (!tpl) throw err(`workflow not found: ${workflowId}`, 'NOT_FOUND');
+  if (tpl.auto) throw err('the Auto entry has no graph to export — it is decided per run', 'UNSUPPORTED');
 
   const dest = resolveDest({ destination, projectDir });
   const finalSlug = assertName(slug || slugify(tpl.name).slice(0, 48) || 'workflow', 'slug');

package/src/core/workflow-share.mjs

@@ -61,6 +61,7 @@ export function nodeDefaultsError(raw, models, where) {
 export async function exportGraphJson(id) {
   const tpl = await readWorkflow(id);
   if (!tpl) throw err(`workflow not found: ${id}`, 'NOT_FOUND');
+  if (tpl.auto) throw err('the Auto entry has no graph to export — it is decided per run', 'UNSUPPORTED');
   if (tpl.version !== 2) {
     throw err(`workflow ${id} is a v1 template — open and save it in the composer first`, 'UNSUPPORTED');
   }

package/src/core/workflows.mjs

@@ -25,9 +25,13 @@ import { DEFAULT_AGENTS_DIR, loadAgentRegistry } from './agent-registry.mjs'; //
 import { readPluginsLock } from './plugins-lock.mjs';                 // a DISABLED plugin's rows are hidden
 import { validateGraph, formatIssue, AGENT_TUNABLES } from '../shared/graph/validate.mjs';
 import { classifyLoops } from '../shared/graph/loops.mjs';
-import { GRAPH_DEFAULT_WORKFLOW } from './graph/builtin-workflows.mjs';
-export { GRAPH_DEFAULT_WORKFLOW };
+import {
+  GRAPH_DEFAULT_WORKFLOW, AUTO_WORKFLOW_ID, AUTO_WORKFLOW_NAME, AUTO_WORKFLOW_STUB,
+  GRAPH_MEMORY_DEFRAG_WORKFLOW, MEMORY_DEFRAG_WORKFLOW_ID, MEMORY_DEFRAG_WORKFLOW_NAME, isReservedWorkflowId,
+} from './graph/builtin-workflows.mjs';
+export { GRAPH_DEFAULT_WORKFLOW, AUTO_WORKFLOW_ID, GRAPH_MEMORY_DEFRAG_WORKFLOW, MEMORY_DEFRAG_WORKFLOW_ID, isReservedWorkflowId };
 import { registryPortsFn } from './graph/registry-ports.mjs';
+import { parseFrontmatter } from './frontmatter.mjs';
 
 /**
  * Default feedback cycle count when run-config does not override it. Matches the
@@ -70,20 +74,7 @@ export async function loadAgentFile(agentsDir, agentFile, agentPath = null) {
   } catch {
     return { prompt: '', tools: [] };
   }
-  return { prompt: text, tools: parseFrontmatterTools(text) };
-}
-
-/** Extract a comma-separated `tools:` list from leading --- YAML frontmatter. */
-function parseFrontmatterTools(text) {
-  const m = /^---\s*\n([\s\S]*?)\n---/.exec(text);
-  if (!m) return [];
-  const line = m[1].split(/\r?\n/).find((l) => /^tools\s*:/.test(l));
-  if (!line) return [];
-  return line
-    .replace(/^tools\s*:/, '')
-    .split(',')
-    .map((s) => s.trim())
-    .filter(Boolean);
+  return { prompt: text, tools: parseFrontmatter(text)?.tools ?? [] };
 }
 
 /**
@@ -310,16 +301,18 @@ export async function writeGraphWorkflow(tpl, opts = {}) {
   // The ONE reserved id is the built-in default's; a save may never claim it,
   // so it falls back to the slug.
   const asked = tpl && typeof tpl.id === 'string' ? tpl.id.trim() : '';
-  const minted = !(asked && isSafeWorkflowId(asked) && asked !== GRAPH_DEFAULT_WORKFLOW.id);
+  const reserved = (id) => isReservedWorkflowId(id);
+  const minted = !(asked && isSafeWorkflowId(asked) && !reserved(asked));
   const id = minted ? `wf_${slugify(name)}` : asked;
   // C-3: the fallback re-mints the reserved id for ANY name slugging to
   // "default" ('Default', ' dEfAuLt ', 'default!!', 'Défault'…). That row is
   // filtered out of listWorkflows(), short-circuited past by readWorkflow() and
   // refused by DELETE — the user's pipeline would vanish behind a 201. Refuse
   // the WRITE instead; only the name is wrong, so the caller can rename.
-  if (id === GRAPH_DEFAULT_WORKFLOW.id) {
+  if (reserved(id)) {
+    const which = id === AUTO_WORKFLOW_ID ? AUTO_WORKFLOW_NAME : id === MEMORY_DEFRAG_WORKFLOW_ID ? MEMORY_DEFRAG_WORKFLOW_NAME : GRAPH_DEFAULT_WORKFLOW.name;
     throw Object.assign(
-      new Error(`the name "${GRAPH_DEFAULT_WORKFLOW.name}" is reserved — choose another name`),
+      new Error(`the name "${which}" is reserved — choose another name`),
       { code: 'RESERVED_NAME' });
   }
   const domain = normDomain(tpl && tpl.domain);
@@ -370,6 +363,8 @@ export async function writeGraphWorkflow(tpl, opts = {}) {
 export async function readWorkflow(id, opts = {}) {
   // `wf_default` IS the graph: the v1 default died with the v1 engine.
   if (id === GRAPH_DEFAULT_WORKFLOW.id) return GRAPH_DEFAULT_WORKFLOW;
+  if (id === AUTO_WORKFLOW_ID) return AUTO_WORKFLOW_STUB;
+  if (id === MEMORY_DEFRAG_WORKFLOW_ID) return GRAPH_MEMORY_DEFRAG_WORKFLOW;
   return readRaw(id, opts);
 }
 
@@ -400,7 +395,7 @@ export async function listWorkflows({ includeArchived = false, includeDisabled =
   const rows = prepare(`SELECT ${ROW_COLS} FROM workflows ${where} ORDER BY created_at DESC, id`).all();
   const lock = includeDisabled ? null : readPluginsLock();
   return rows
-    .filter((r) => r.id !== GRAPH_DEFAULT_WORKFLOW.id)
+    .filter((r) => !isReservedWorkflowId(r.id))
     .filter((r) => includeDisabled || !pluginDisabled(r.origin, lock))
     .map(rowToTpl);
 }
@@ -437,6 +432,8 @@ function assertValidGraph(tpl, registry) {
  */
 export async function assertRunnableWorkflow(id, { registry, checkGraph = true } = {}) {
   const wanted = typeof id === 'string' && id.trim() ? id.trim() : GRAPH_DEFAULT_WORKFLOW.id;
+  // The Auto entry has no graph to check: the run decides one (spec §5.1).
+  if (wanted === AUTO_WORKFLOW_ID) return AUTO_WORKFLOW_STUB;
   const live = await readWorkflow(wanted);
   if (live) {
     // A disabled plugin's template is neither runnable nor openable: its agents
@@ -479,6 +476,9 @@ export async function setWorkflowNodeDefaults(id, map) {
   if (id === GRAPH_DEFAULT_WORKFLOW.id) {
     throw new Error('the built-in Default workflow cannot store defaults — save a copy in Composer first');
   }
+  if (id === MEMORY_DEFRAG_WORKFLOW_ID) {
+    throw new Error('the built-in Memory defragment workflow cannot store defaults — save a copy in Composer first');
+  }
   const tpl = readRaw(id);
   if (!tpl) throw new Error(`workflow not found: ${id}`);
   const patch = map && typeof map === 'object' ? map : {};
@@ -523,6 +523,8 @@ export async function setWorkflowNodeDefaults(id, map) {
  */
 export async function deleteWorkflow(id) {
   if (id === GRAPH_DEFAULT_WORKFLOW.id) return false; // built-in default is undeletable
+  if (id === AUTO_WORKFLOW_ID) return false;    // never a row
+  if (id === MEMORY_DEFRAG_WORKFLOW_ID) return false; // a constant, never a row
   if (!isSafeWorkflowId(id)) return false;      // SECURITY: reject unsafe ids
   getDb();
   let changed = 0;
@@ -548,7 +550,7 @@ export async function deleteWorkflow(id) {
  * @param {string} workflowId
  * @param {Record<string,object>} registry  loadAgentRegistry() output
  * @param {string} [agentsDir]  override for tests; defaults to ../../agents
- * @param {{ isWorkspace?: boolean }} [opts]  workspace-mode resolve options
+ * @param {{ isWorkspace?: boolean, overlay?: {nodes?: object, wires?: object}, ignoreProjectOverrides?: boolean }} [opts]  workspace-mode resolve options
  * @returns {Promise<object>} ExecutablePlan
  * @throws {Error} when the workflow id is unknown, or a node resolves the off-pipeline scanner
  */
@@ -591,6 +593,9 @@ export function workspaceVariants(registry) {
  * @throws {Error} unknown workflow, a v1 row, an unknown/un-ported/unplaceable agent
  */
 export async function resolveGraph(projectDir, workflowId, registry, agentsDir = DEFAULT_AGENTS_DIR, opts = {}) {
+  if (workflowId === AUTO_WORKFLOW_ID) {
+    throw new Error('the Auto workflow is decided per run — resolveGraph needs the adopted workflow id');
+  }
   const stored = await readWorkflow(workflowId);
   if (!stored) throw new Error(`unknown workflowId "${workflowId}"`);
   if (stored.version !== 2) throw new Error('template is not a graph — runs on the v1 engine');
@@ -600,12 +605,27 @@ export async function resolveGraph(projectDir, workflowId, registry, agentsDir =
   const reg = registry && typeof registry === 'object' ? registry : {};
   const isWorkspace = !!opts.isWorkspace;
   const variants = isWorkspace ? workspaceVariants(reg) : {};
-  const { nodes: nodeCfg, wires: wireCfg } = await resolveRunConfig(projectDir, workflowId);
+  // Per-project overlays. An Auto run owns its tuning (spec D7/D9): with
+  // `ignoreProjectOverrides` every per-project layer is skipped and `overlay`
+  // (the proposal the user accepted) is the ONLY overlay. Otherwise `overlay`
+  // merges PER NODE / PER WIRE over the project layer.
+  const ignore = !!opts.ignoreProjectOverrides;
+  const runCfg = ignore ? { nodes: {}, wires: {} } : await resolveRunConfig(projectDir, workflowId);
+  const over = opts.overlay && typeof opts.overlay === 'object' ? opts.overlay : {};
+  const mergeMaps = (base, extra) => {
+    const out = { ...base };
+    for (const [id, sel] of Object.entries(extra && typeof extra === 'object' ? extra : {})) {
+      if (sel && typeof sel === 'object') out[id] = { ...(out[id] || {}), ...sel };
+    }
+    return out;
+  };
+  const nodeCfg = mergeMaps(runCfg.nodes, over.nodes);
+  const wireCfg = mergeMaps(runCfg.wires, over.wires);
   // The legacy per-role layer is the Default workflow's storage only (saved rows
   // use nodeCfg); it is addressed by agent KEY, never by node id.
   // A defaults-only global export passes projectDir=null and must not touch the config
   // store (projectKey(null) throws); its legacy per-role layer is empty by definition.
-  const stepsCfg = (workflowId === GRAPH_DEFAULT_WORKFLOW.id && projectDir) ? (await readConfig(projectDir)).steps : {};
+  const stepsCfg = (!ignore && workflowId === GRAPH_DEFAULT_WORKFLOW.id && projectDir) ? (await readConfig(projectDir)).steps : {};
   const firstDefined = (...vals) => vals.find((v) => v !== undefined);
 
   const nodes = {};

package/src/core/workspaces.mjs

@@ -32,6 +32,27 @@ import { getDb, prepare, tx } from './db.mjs';
 /** Object-shaped error carrying a machine code (mirrors pipeline-delete.mjs). */
 function err(message, code) { return Object.assign(new Error(message), { code }); }
 
+/**
+ * Validate a metricsProject candidate against a workspace's member paths.
+ * null/'' means "no home" and returns null. Anything else must resolve (by exact
+ * match or by canonical git root) to one of `paths`; the member's OWN stored path
+ * is returned (workspace_projects convention), not the normalized candidate.
+ * @param {string[]} paths
+ * @param {string|null|undefined} candidate
+ * @returns {string|null}
+ * @throws err(code: BAD_REQUEST)
+ */
+function memberPathFor(paths, candidate) {
+  if (candidate == null || candidate === '') return null;
+  if (typeof candidate !== 'string') throw err('metricsProject must be a project path or null', 'BAD_REQUEST');
+  const want = normalizeProjectPath(candidate);
+  // normalizeProjectPath('   ') -> null; canonicalProjectRoot(null) would throw ERR_INVALID_ARG_TYPE -> 500.
+  if (!want) throw err('metricsProject must be a project path or null', 'BAD_REQUEST');
+  const hit = paths.find((p) => p === want || canonicalProjectRoot(p) === canonicalProjectRoot(want));
+  if (!hit) throw err('metricsProject must be one of the workspace projects', 'BAD_REQUEST');
+  return hit;
+}
+
 /**
  * The workspace-key shape: "wks-<slug>-<sha1[:8]>". The server imports this as
  * its single source of truth (M2 route validation), so core + route agree on one
@@ -108,6 +129,7 @@ function annotate(entry) {
     projectPaths: pairs.map((x) => x.path),
     projectKeys: pairs.map((x) => x.key),
     exists: pairs.map((x) => isDir(x.path)),
+    metricsProject: entry.metricsProject ?? null,
     createdAt: entry.createdAt,
     updatedAt: entry.updatedAt,
   };
@@ -127,6 +149,7 @@ function rowToEntry(r) {
     name: r.name,
     description: typeof r.description === 'string' ? r.description : '',
     projectPaths: memberPaths(r.id),
+    metricsProject: r.metrics_project ?? null,
     createdAt: typeof r.created_at === 'string' ? r.created_at : '',
     updatedAt: typeof r.updated_at === 'string' ? r.updated_at : '',
   };
@@ -136,7 +159,7 @@ function rowToEntry(r) {
 function readEntry(id) {
   getDb();
   const r = prepare(
-    'SELECT id, name, description, created_at, updated_at FROM workspaces WHERE id = ?'
+    'SELECT id, name, description, metrics_project, created_at, updated_at FROM workspaces WHERE id = ?'
   ).get(id);
   return r ? rowToEntry(r) : null;
 }
@@ -148,7 +171,7 @@ function readEntry(id) {
 export async function listWorkspaces() {
   getDb();
   const rows = prepare(
-    'SELECT id, name, description, created_at, updated_at FROM workspaces ORDER BY created_at, name'
+    'SELECT id, name, description, metrics_project, created_at, updated_at FROM workspaces ORDER BY created_at, name'
   ).all();
   return rows.map(rowToEntry).map(annotate);
 }
@@ -218,6 +241,7 @@ export async function createWorkspace(input = {}) {
     if (!isGitRepo(p)) throw err(`member path is not a git repository: ${p}`, 'BAD_REQUEST');
   }
 
+  const metricsProject = memberPathFor(members, input.metricsProject ?? null);
   const id = workspaceKey({ name, projectPaths: members });
   const hash = rootsHash(members);
   const now = new Date().toISOString();
@@ -235,8 +259,8 @@ export async function createWorkspace(input = {}) {
       }
     }
     prepare(
-      'INSERT INTO workspaces (id, name, description, created_at, updated_at) VALUES (?, ?, ?, ?, ?)'
-    ).run(id, name, description, now, now);
+      'INSERT INTO workspaces (id, name, description, metrics_project, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)'
+    ).run(id, name, description, metricsProject, now, now);
     const insMember = prepare(
       'INSERT INTO workspace_projects (workspace_id, project_key, ordinal) VALUES (?, ?, ?)'
     );
@@ -245,7 +269,9 @@ export async function createWorkspace(input = {}) {
   });
 
   // Return the annotated entry (derived fields recomputed from the persisted paths).
-  return annotate({ id, name, description, projectPaths: members, createdAt: now, updatedAt: now });
+  return annotate({
+    id, name, description, projectPaths: members, metricsProject, createdAt: now, updatedAt: now,
+  });
 }
 
 /**
@@ -270,6 +296,9 @@ export async function updateWorkspace(id, patch = {}) {
   if (patch && typeof patch.description === 'string') {
     description = patch.description; // cap-on-freeze, not cap-on-store: persisted whole
   }
+  const metricsProject = Object.prototype.hasOwnProperty.call(patch || {}, 'metricsProject')
+    ? memberPathFor(entry.projectPaths, patch.metricsProject)
+    : entry.metricsProject ?? null;
   const now = new Date().toISOString();
 
   tx(() => {
@@ -279,11 +308,11 @@ export async function updateWorkspace(id, patch = {}) {
     ).get(name, id);
     if (clash) throw err(`a workspace named "${name}" already exists`, 'DUPLICATE_NAME');
     prepare(
-      'UPDATE workspaces SET name = ?, description = ?, updated_at = ? WHERE id = ?'
-    ).run(name, description, now, id);
+      'UPDATE workspaces SET name = ?, description = ?, metrics_project = ?, updated_at = ? WHERE id = ?'
+    ).run(name, description, metricsProject, now, id);
   });
 
-  return annotate({ ...entry, name, description, updatedAt: now });
+  return annotate({ ...entry, name, description, metricsProject, updatedAt: now });
 }
 
 /** Thin setter: edit only the description. */

package/src/shared/graph/agent-meta.mjs

@@ -16,6 +16,9 @@ const RESERVED_PORT_ID = 'await';
 const DOMAIN_RE = /^[a-z][a-z0-9-]{0,31}$/;
 const COLORS = new Set(['green', 'peach', 'red', 'blue', 'violet', 'amber']);
 const RUNNER_TYPES = new Set(['producer', 'verifier', 'clarifier']);
+/** What an agent may write outside its output ports: 'code' (the worktree — implementer tool
+ *  set) or 'memory' (worca's memory mount only — Read/Write/Edit/Glob/Grep, no Bash). */
+const SIDE_EFFECTS = new Set(['code', 'memory']);
 const INPUT_AS = new Set(['file', 'answers', 'fix-review', 'worktree']);
 /** The port type each non-default `as` renderer requires. `file` is the default
  *  and is materialized on NON-VOID inputs only, which makes `worktree` the only
@@ -112,7 +115,7 @@ export function normalizeAgentMeta(raw, opts = {}) {
   // Scope coercion mirrors color: anything but the explicit 'workspace-only'
   // marker is a normal project agent, so a typo fails safe to a VISIBLE agent.
   const scope = raw.scope === 'workspace-only' ? 'workspace-only' : 'project';
-  if (raw.sideEffect !== undefined && raw.sideEffect !== 'code') err('sideEffect must be "code" when present');
+  if (raw.sideEffect !== undefined && !SIDE_EFFECTS.has(raw.sideEffect)) err(`sideEffect must be one of ${[...SIDE_EFFECTS].join(', ')}`);
   if (raw.workspaceStrategy !== undefined && !WORKSPACE_STRATEGIES.has(raw.workspaceStrategy)) {
     err(`workspaceStrategy must be one of ${[...WORKSPACE_STRATEGIES].join(', ')}`);
   }
@@ -164,7 +167,7 @@ export function normalizeAgentMeta(raw, opts = {}) {
   // an absent field means "the default", so a v2 entry stays diffable against
   // the sidecar that produced it.
   if (verdict) meta.verdict = verdict;
-  if (raw.sideEffect === 'code') meta.sideEffect = 'code';
+  if (SIDE_EFFECTS.has(raw.sideEffect)) meta.sideEffect = raw.sideEffect;
   if (mockRole) meta.mockRole = mockRole;
   if (raw.wantsRequest) meta.wantsRequest = true;
   if (raw.workspaceFanOut) meta.workspaceFanOut = true;