@worca/app 1.3.0 → 1.4.0

package/src/core/graph/worca_script.py

@@ -0,0 +1,207 @@
+# src/core/graph/worca_script.py
+# The `python` runtime harness (scripts-workbench spec §7) — the twin of
+# script-child.mjs, one language over. Spawned as
+#   <python> -u worca_script.py <program.py>
+# with the envelope on stdin.
+#
+# Imports NOTHING from worca and nothing outside the standard library: it runs
+# with WORCA_HOME stripped, on whatever interpreter the probe found, and must
+# parse and run on python 3.8 (no match, no X | Y unions, no removeprefix).
+#
+# Protocol: read ONE JSON envelope from stdin, load the program, call its
+# main(api), write ONE JSON frame to the REAL stdout, exit 0. stdout is
+# protocol-reserved (base spec §5.1 rule 2) at TWO levels:
+#   - the file descriptor: a private duplicate of fd 1 is kept for the frame and
+#     fd 1 itself is pointed at stderr, so a child process the program starts
+#     (subprocess.run([...]) with no capture, os.system) writes into the run log.
+#     Rebinding sys.stdout alone does not cover that: a child inherits the OS
+#     descriptor, and one stray line before the frame is "stdout is not JSON".
+#   - the python object: sys.stdout points at sys.stderr from the moment user code
+#     can run and is NEVER pointed back, so every print() goes through the utf-8
+#     stream configured below — including one made after main() returned (an atexit
+#     hook, a worker thread that outlives main): the frame handle is private.
+# A non-zero exit means "crashed before the frame" and the parent reports
+# "no result frame (exit N)".
+import asyncio
+import importlib.machinery
+import importlib.util
+import inspect
+import json
+import os
+import sys
+import traceback
+
+# Never leave a __pycache__ beside a user's program — or inside the installed
+# package, which is where the built-in `py` card's program lives. Process-local on
+# purpose: PYTHONDONTWRITEBYTECODE in the environment would leak into every python
+# tool the program starts (pytest, a build script) and change how THEY behave.
+sys.dont_write_bytecode = True
+
+
+def _reserve_stdout():
+    """Keep a private handle on the REAL stdout for the frame, then point fd 1 at stderr.
+
+    os.dup() returns a NON-inheritable descriptor (PEP 446), so no child process can
+    ever write into the frame; os.dup2(2, 1) makes fd 1 the run log for this process
+    and for everything it starts. Falls back to the plain object when the descriptors
+    are not there to duplicate (an embedded interpreter) — print() is still covered.
+    """
+    try:
+        sys.stdout.flush()
+        keep = os.dup(1)
+        os.dup2(2, 1)
+        return os.fdopen(keep, 'w', encoding='utf-8', newline='')
+    except (OSError, ValueError, AttributeError):
+        return sys.stdout
+
+
+# The REAL stdout, reserved before anything can rebind or inherit it: the frame goes here.
+_FRAME_OUT = _reserve_stdout()
+# Appended by api.log(); carried on the frame even when main() then raises.
+_LOGS = []
+
+for _stream in (sys.stdin, sys.stderr):
+    # Windows consoles default to cp1252; the parent also exports PYTHONIOENCODING
+    # and PYTHONUTF8, this is the belt to that pair of braces. errors='replace' so
+    # an unprintable byte in a log line can never kill the execution.
+    if hasattr(_stream, 'reconfigure'):
+        try:
+            _stream.reconfigure(encoding='utf-8', errors='replace')
+        except (ValueError, OSError):
+            pass
+
+
+class Api(dict):
+    """The api bag: api.params and api['params'] are the same thing (spec §7)."""
+
+    def __getattr__(self, name):
+        try:
+            return self[name]
+        except KeyError:
+            # Only the MESSAGE reaches the run (`script "k": <message>`), so a bare name
+            # would read as `script "k": plan`. Say what is missing and what is there.
+            raise AttributeError('no "%s" here (has: %s)' % (name, ', '.join(sorted(str(k) for k in self)) or 'nothing')) from None
+
+    def __setattr__(self, name, value):
+        self[name] = value
+
+    def __delattr__(self, name):
+        try:
+            del self[name]
+        except KeyError:
+            raise AttributeError(name) from None
+
+
+def _wrap(value):
+    """Envelope JSON -> Api all the way down, so api.outputs.out.path reads naturally."""
+    if isinstance(value, dict):
+        return Api((key, _wrap(item)) for key, item in value.items())
+    if isinstance(value, list):
+        return [_wrap(item) for item in value]
+    return value
+
+
+def _log(level, msg):
+    _LOGS.append({'level': str(level), 'msg': str(msg)})
+
+
+def _load(path):
+    """Load the program as its own module, with its directory first on sys.path so
+    a script's sibling imports work (the node runtime gets that for free)."""
+    directory = os.path.dirname(os.path.abspath(path))
+    if directory not in sys.path:
+        sys.path.insert(0, directory)
+    # An EXPLICIT source loader: left to itself spec_from_file_location() picks the
+    # loader by suffix and answers None for anything that is not .py, and the sidecar
+    # only asks `file` to be a plain basename.
+    loader = importlib.machinery.SourceFileLoader('worca_user_script', path)
+    spec = importlib.util.spec_from_file_location('worca_user_script', path, loader=loader)
+    if spec is None or spec.loader is None:
+        raise ImportError('cannot load script module: ' + str(path))
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+async def _resolve(value):
+    return await value
+
+
+def _run(envelope, path):
+    api = Api(
+        inputs=_wrap(envelope.get('inputs') or {}),
+        outputs=_wrap(envelope.get('outputs') or {}),
+        params=_wrap(envelope.get('params') or {}),
+        ctx=_wrap(envelope.get('ctx') or {}),
+        verdictPath=envelope.get('verdictPath'),
+        node=_wrap(envelope.get('node') or {}),
+        execution=_wrap(envelope.get('execution') or {}),
+        log=_log,
+    )
+    module = _load(path)
+    entry = getattr(module, 'main', None)
+    if not callable(entry):
+        raise TypeError('script module has no callable main(api): ' + str(path))
+    result = entry(api)
+    if inspect.isawaitable(result):
+        result = asyncio.run(_resolve(result))
+    returned = result if isinstance(result, dict) else {}
+    frame = {'ok': True, 'logs': _LOGS}
+    if isinstance(returned.get('outputs'), dict):
+        frame['outputs'] = returned['outputs']
+    if 'verdict' in returned:
+        frame['verdict'] = returned['verdict']
+    if isinstance(returned.get('summary'), str):
+        frame['summary'] = returned['summary']
+    return frame
+
+
+def _message(err):
+    """str(err), except where python's own str() says nothing useful on its own."""
+    text = str(err)
+    if not text:
+        return err.__class__.__name__
+    if isinstance(err, KeyError):        # str(KeyError('plan')) is just "'plan'"
+        return 'KeyError: ' + text
+    return text
+
+
+def _encode(frame):
+    """ONE line of pure-ASCII JSON. ensure_ascii (the default) keeps the frame ASCII
+    whatever the console encoding is; the parent's JSON.parse restores every escape.
+    A returned set / bytes / datetime / Path, a NaN (which json would happily print
+    as the non-JSON token NaN) or a nesting json gives up on (RecursionError — not a
+    ValueError) is reported the way script-child.mjs reports it — as a frame —
+    instead of dying with no frame at all."""
+    try:
+        return json.dumps(frame, allow_nan=False)
+    except Exception as err:
+        return json.dumps({'ok': False, 'logs': _LOGS,
+                           'error': {'message': 'frame is not serializable: ' + (str(err) or err.__class__.__name__)}})
+
+
+def main():
+    try:
+        raw = sys.stdin.read()
+        envelope = json.loads(raw) if raw.strip() else {}
+        path = sys.argv[1] if len(sys.argv) > 1 else None
+        if not path:
+            raise ValueError('worca_script.py: no program file argument')
+        sys.stdout = sys.stderr          # stdout is protocol-reserved: prints go to the run log
+        frame = _run(envelope, path)
+    except Exception as err:             # a user's sys.exit() is SystemExit and is left to propagate:
+        frame = {'ok': False, 'logs': _LOGS,   # no frame, non-zero exit, "no result frame (exit N)" upstream
+                 'error': {'message': _message(err), 'stack': traceback.format_exc()}}
+    # sys.stdout is NOT pointed back at the frame handle — not here, not ever. User
+    # code is not over when main() returns: an atexit hook, a finalizer or a worker
+    # thread that outlives main (the exit below waits for a non-daemon one) can still
+    # print, and one byte after the frame is "stdout is not JSON" for a card that
+    # succeeded. Only this function ever writes to _FRAME_OUT.
+    _FRAME_OUT.write(_encode(frame))
+    _FRAME_OUT.flush()
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

package/src/core/guardrail-store.mjs

@@ -19,6 +19,7 @@ import { GUARDRAIL_PRESETS, GUARDRAIL_LEVELS, sanitizeGuardrails } from './guard
 // store stamps code:'REFERENCED' at the throw site, and the server ALSO matches
 // structurally (err.name === 'ReferencedError' || err.code === 'REFERENCED').
 import { ReferencedError } from './plugin-workflows.mjs';
+import { policyGuardrailSets } from './policy/cache.mjs';
 
 export { ReferencedError };
 
@@ -79,9 +80,24 @@ function readRaw(id) {
  */
 export async function readGuardrailSet(id) {
   if (isBuiltinGuardrailSetId(id)) return builtinSet(id);
+  // Team policy sets (team-policy design §8): virtual, read-only, `gp:<id>`, resolved from the
+  // discovery cache at read time — so a paused run that pinned one re-reads its latest
+  // definition on resume, and a vanished one takes the existing fail-open path.
+  if (isPolicyGuardrailSetId(id)) return policyGuardrailSet(id);
   return readRaw(id);
 }
 
+/** `gp:<id>` — a guardrail set shipped by a team policy (never a row; `:` is not a row-id character). */
+export function isPolicyGuardrailSetId(id) { return typeof id === 'string' && /^gp:[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(id); }
+function policyGuardrailSet(id) {
+  const hit = policyGuardrailSets().find((s) => s.id.toLowerCase() === id.toLowerCase());
+  return hit ? { ...hit, settings: sanitizeGuardrails(hit.settings) } : null;
+}
+/** Every policy set this machine has cached (Guardrails list rows with a policy badge). */
+export function listPolicyGuardrailSets() {
+  return policyGuardrailSets().map((s) => ({ ...s, settings: sanitizeGuardrails(s.settings) }));
+}
+
 /**
  * List USER sets (NOT the built-ins — callers prepend listBuiltinGuardrailSets()),
  * newest first by createdAt. Empty store => []. Never throws.

package/src/core/human-backfill.mjs

@@ -0,0 +1,108 @@
+// src/core/human-backfill.mjs
+// One-shot RUN-LEVEL human-hours backfill for runs recorded before schema v33 (money-saved
+// design §6.1). Synchronous (it runs inside the migration ladder), best-effort per run: a
+// missing file, an unreadable JSON or an unknown store root contributes 0 and never throws.
+// Steps stay NULL — only the run row is credited. Never re-runs on a credited run, and never
+// touches a run whose steps already carry an estimate (the step path owns those).
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { projectStorePath, workspaceStorePath } from './store.mjs';
+import { estimateStepHours, proseWords, jsonItems, roundHours } from '../shared/human-estimate.mjs';
+
+const TERMINAL = "('done','error','stopped')";   // `interrupted` and `paused` are resumable (stats.mjs buckets them together): the step path owns them
+const SKIP_JSON = new Set(['results.json', 'run.json', 'memory.json']);
+const MD_DIR_RE = /^(plans|reviews)\//;
+const VERSION_RE = /-v(\d+)\.md$/i;
+
+function readTextSafe(path) { try { return readFileSync(path, 'utf8'); } catch { return null; } }
+
+/** The pipeline dir under <root>/pipelines whose name ends with `-<id>` (the run-dir naming). */
+function pipelineDirFor(root, id, cache) {
+  if (!cache.has(root)) {
+    let names = [];
+    try { names = readdirSync(join(root, 'pipelines')); } catch { /* no store yet */ }
+    cache.set(root, names);
+  }
+  const name = cache.get(root).find((n) => n.endsWith(`-${id}`));
+  return name ? join(root, 'pipelines', name) : null;
+}
+
+const producer = (over) => ({ nodeKind: 'agent', agent: { runnerType: 'producer' }, cycle: 1, code: null, outputs: [], reads: null, ...over });
+
+/** db.mjs's hasSqliteTable is not exported; a hand-seeded upgrade fixture may lack a table. */
+function hasTable(db, name) {
+  return !!db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(name);
+}
+
+function defaultRootFor(row) {
+  try {
+    return row.target === 'workspace' && row.workspace_key ? workspaceStorePath(row.workspace_key) : projectStorePath(row.project_key);
+  } catch { return null; }   // no resolvable home (node:test without WORCA_HOME): credit nothing
+}
+
+/**
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {{rootFor?:(row:object)=>string|null}} [opts]
+ * @returns {{runs:number, credited:number}}
+ */
+export function backfillHumanHours(db, { rootFor = defaultRootFor } = {}) {
+  if (!hasTable(db, 'artifacts') || !hasTable(db, 'reviews')) return { runs: 0, credited: 0 };
+  const rows = db.prepare(`SELECT id, project_key, workspace_key, target FROM pipelines
+    WHERE status IN ${TERMINAL} AND human_hours = 0`).all();
+  const hasStepEstimate = db.prepare('SELECT 1 AS n FROM pipeline_steps WHERE pipeline_id = ? AND human_hours IS NOT NULL LIMIT 1');
+  const reviews = db.prepare('SELECT verdict FROM reviews WHERE pipeline_id = ? ORDER BY rowid');   // every persisted verdict (writeReview)
+  const artifacts = db.prepare('SELECT kind, rel_path FROM artifacts WHERE pipeline_id = ? ORDER BY rowid');   // insertion order: a plan, its versions, then the reviews
+  const update = db.prepare('UPDATE pipelines SET human_hours = ? WHERE id = ?');
+  const dirCache = new Map();
+  let credited = 0;
+  for (const row of rows) {
+    try {
+      if (hasStepEstimate.get(row.id)) continue;
+      const root = rootFor(row);
+      if (!root) continue;
+      const pdir = pipelineDirFor(root, row.id, dirCache);
+      const pseudo = [];
+      let diffLines = 0;
+      // code
+      const results = pdir ? readTextSafe(join(pdir, 'results.json')) : null;
+      if (results) {
+        try {
+          const s = JSON.parse(results)?.summary || {};
+          const ins = s.linesAdded | 0; const del = s.linesRemoved | 0;
+          diffLines = ins + del;
+          pseudo.push(producer({ code: { files: (s.filesNew | 0) + (s.filesChanged | 0), insertions: ins, deletions: del } }));
+        } catch { /* unreadable summary → no code credit */ }
+      }
+      // prose + json artifacts
+      for (const a of artifacts.all(row.id)) {
+        const rel = String(a.rel_path || '');
+        if (rel.endsWith('.md') && MD_DIR_RE.test(rel)) {
+          const text = readTextSafe(join(root, ...rel.split('/')));
+          if (text == null) continue;
+          const m = VERSION_RE.exec(rel);
+          // -vN is the (N−1)-th revision: the refiner's k-th execution mints -v(k+1) and the step
+          // path credits it at cycle k (spec §6.1), so the decay here is 0.5^(N−2), never 0.5^(N−1).
+          pseudo.push(producer({ cycle: m ? Math.max(1, Number(m[1]) - 1) : 1, outputs: [{ type: 'md', words: proseWords(text), revision: !!m }] }));
+        } else if (rel.endsWith('.json') && pdir && !SKIP_JSON.has(rel) && !rel.includes('/')) {   // dir-relative JSON the run indexed (decomposition.json)
+          const text = readTextSafe(join(pdir, rel));
+          if (text == null) continue;
+          let items = 0; try { items = jsonItems(JSON.parse(text)); } catch { /* 0 */ }
+          pseudo.push(producer({ outputs: [{ type: 'json', items }] }));
+        }
+      }
+      // verdict JSON: the product persists every per-cycle verdict in reviews.verdict (writeReview);
+      // the *-review-cycleN.json file the agent wrote is transient scratch and never an artifacts row.
+      let verdicts = 0;
+      for (const r of reviews.all(row.id)) {
+        verdicts += 1;
+        let items = 0; try { items = jsonItems(JSON.parse(r.verdict)); } catch { /* 0 */ }
+        pseudo.push(producer({ outputs: [{ type: 'json', items }] }));
+      }
+      // one verifier read of the full diff when a verdict was written — no agent key involved (rule 6, cycle 1 only)
+      if (diffLines > 0 && verdicts > 0) pseudo.push(producer({ agent: { runnerType: 'verifier' }, reads: { diffLines, words: 0 } }));
+      const hours = roundHours(pseudo.reduce((sum, e) => sum + estimateStepHours(e).hours, 0));
+      if (hours > 0) { update.run(hours, row.id); credited += 1; }
+    } catch { /* best-effort per run */ }
+  }
+  return { runs: rows.length, credited };
+}

package/src/core/human-rate.mjs

@@ -0,0 +1,17 @@
+// src/core/human-rate.mjs
+// The rate that prices human hours (money-saved design §8): the developer's stored setting wins
+// when set, then the team policy's `cost.humanRateUsd` default, then 35. Read fresh per call.
+import { humanRateUsdPerHour, DEFAULT_HUMAN_RATE_USD } from './settings.mjs';
+import { teamDefault } from './policy/cache.mjs';
+
+/** @param {string|null} [projectDir] the project whose policy home applies (null: no policy lookup) */
+export function effectiveHumanRateUsd(projectDir = null) {
+  const local = humanRateUsdPerHour();
+  if (local != null) return local;
+  if (projectDir) {
+    let team;
+    try { team = teamDefault(projectDir, 'cost.humanRateUsd'); } catch { team = undefined; }   // a policy read must never break a metrics page
+    if (typeof team === 'number' && Number.isFinite(team) && team > 0) return team;
+  }
+  return DEFAULT_HUMAN_RATE_USD;
+}

package/src/core/index-html.mjs

@@ -8,10 +8,14 @@ export const INDEX_THEME_ANCHOR = '<html lang="en" data-theme="system">';
 /**
  * @param {string} html  the on-disk ui/public/index.html
  * @param {'system'|'light'|'dark'} theme
+ * @param {'simple'|'advanced'|'expert'} [level]  always one of UI_LEVELS (the server resolves it)
  * @returns {string}
  * @throws {Error} when the anchor is not present (index.html drifted)
  */
-export function renderIndexHtml(html, theme) {
+export function renderIndexHtml(html, theme, level) {
   if (!html.includes(INDEX_THEME_ANCHOR)) throw new Error('index.html theme anchor missing');
-  return html.replace(INDEX_THEME_ANCHOR, `<html lang="en" data-theme="${theme}">`);
+  // `level` (docs/ui-levels.md) rides the same anchor so the first paint already hides what the
+  // interface mode hides. Omitted ⇒ no attribute, and the stylesheet then gates nothing.
+  const lvl = level ? ` data-level="${level}"` : '';
+  return html.replace(INDEX_THEME_ANCHOR, `<html lang="en" data-theme="${theme}"${lvl}>`);
 }

package/src/core/memory-defrag-model.mjs

@@ -0,0 +1,112 @@
+// src/core/memory-defrag-model.mjs
+// Settings › Memory: which model (and effort) a Memory defragment run's agent uses. Pure
+// functions — the callers read the setting (settings.mjs#memoryDefragModel) and the catalog
+// (config.mjs#listModels) and hand them in, so this module imports nothing but the built-in
+// workflow constant.
+//
+// Precedence, resolved ONCE at run start (orchestrator.mjs _defragAgentPair):
+//   1. a pair named explicitly at start — the run's `claude.model` (+ `claude.effort`): the CLI's
+//      --model (verbatim, like --model everywhere), a CLI-made schedule's stored model, or the
+//      `model`/`effort` of a POST /api/run body starting a defragment run (checkStartPair).
+//   2. the stored setting, validated against the run's project catalog.
+//   3. nothing: the node layers resolve exactly as before (a project's own node pick, a team
+//      default, then the built-in template's model).
+// The pair rule holds throughout: an effort travels with its model, so an effort without a model
+// is ignored and no lower layer's effort ever rides under a model it was not chosen for.
+
+import { GRAPH_MEMORY_DEFRAG_WORKFLOW } from './graph/builtin-workflows.mjs';
+
+const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+
+/**
+ * @param {{explicit?:{model?:string, effort?:string}, stored?:{model?:string|null, effort?:string|null},
+ *   models?:Array<{id:string, efforts?:string[]}>}} o `models` = the catalog the run resolves against
+ * @returns {{model:string|null, effort:string|null, source:'explicit'|'setting'|'default', warning:string|null}}
+ *   `model: null` = no pair (today's resolution). `warning` = a stored setting that did not survive
+ *   the catalog check — the run degrades, it is never refused. It names the problem only: the
+ *   caller appends what the run uses instead (agentPairText, once the graph is resolved).
+ */
+export function resolveDefragModel({ explicit = {}, stored = {}, models = [] } = {}) {
+  const exModel = str(explicit && explicit.model);
+  if (exModel) return { model: exModel, effort: str(explicit.effort), source: 'explicit', warning: null };
+  const model = str(stored && stored.model);
+  if (!model) return { model: null, effort: null, source: 'default', warning: null };
+  const hit = (Array.isArray(models) ? models : [])
+    .find((m) => m && typeof m.id === 'string' && m.id.toLowerCase() === model.toLowerCase());
+  if (!hit) {
+    return {
+      model: null, effort: null, source: 'default',
+      warning: `Memory defragment model "${model}" (Settings › Memory) is not in this project's model catalog`,
+    };
+  }
+  const effort = str(stored.effort);
+  if (effort && !(Array.isArray(hit.efforts) && hit.efforts.includes(effort))) {
+    return {
+      model: hit.id, effort: null, source: 'setting',
+      warning: `Memory defragment effort "${effort}" (Settings › Memory) is not offered by ${hit.id}`,
+    };
+  }
+  return { model: hit.id, effort, source: 'setting', warning: null };
+}
+
+/**
+ * The tail of a degrade warning — what the run's agent nodes resolved to INSTEAD (a project's own
+ * pick, a team default or the template's model), so the log never claims a fallback the run did
+ * not take: `claude-fable-5-1 · max`, `claude-sonnet-5 at its default effort`.
+ * @param {Record<string, {kind?:string, model?:string, effort?:string}>} nodes resolveGraph's per-node table
+ */
+export function agentPairText(nodes) {
+  const seen = [];
+  for (const nc of Object.values(nodes && typeof nodes === 'object' ? nodes : {})) {
+    if (!nc || nc.kind !== 'agent') continue;
+    const text = nc.model ? `${nc.model}${nc.effort ? ` · ${nc.effort}` : ' at its default effort'}` : 'the CLI default model';
+    if (!seen.includes(text)) seen.push(text);
+  }
+  return seen.join(', ') || 'the CLI default model';
+}
+
+/**
+ * POST /api/run: the pair a defragment run names AT START (`body.model` / `body.effort`) — tier 1,
+ * above the setting. Checked against the run's project catalog like any model a user picks: the id
+ * comes back in the catalog's casing and the effort must be one the entry offers; an effort without
+ * a model is refused (it would mean nothing). `models: null` skips the catalog check — a scheduled
+ * ticket firing, whose request was checked when it was scheduled (then taken verbatim, like --model).
+ * @param {{model?:unknown, effort?:unknown}} body
+ * @param {Array<{id:string, efforts?:string[]}>|null} models
+ * @returns {{pair: ({model:string, effort:(string|null)}|null)} | {error: string}}
+ */
+export function checkStartPair({ model, effort } = {}, models = null) {
+  const blank = (v) => v === undefined || v === null || (typeof v === 'string' && !v.trim());
+  if (blank(model)) return blank(effort) ? { pair: null } : { error: 'effort needs a model — an effort without a model means nothing' };
+  if (typeof model !== 'string' || model.length > 200) return { error: 'model must be a catalog model id' };
+  if (!blank(effort) && typeof effort !== 'string') return { error: 'effort must be a string' };
+  let id = model.trim();
+  const eff = blank(effort) ? null : effort.trim();
+  if (Array.isArray(models)) {
+    const hit = models.find((m) => m && typeof m.id === 'string' && m.id.toLowerCase() === id.toLowerCase());
+    if (!hit) return { error: `unknown model "${id}"` };
+    id = hit.id;
+    if (eff && !(Array.isArray(hit.efforts) && hit.efforts.includes(eff))) return { error: `${id} does not offer effort "${eff}"` };
+  }
+  return { pair: { model: id, effort: eff } };
+}
+
+/** What "(default)" means in Settings › Memory: the built-in template's own agent model. */
+export function defragDefaultModel() {
+  const agent = GRAPH_MEMORY_DEFRAG_WORKFLOW.nodes.find((n) => n.kind === 'agent');
+  return (agent && agent.config && typeof agent.config.model === 'string' && agent.config.model) || null;
+}
+
+/**
+ * GET /api/workflows/wf_memory_defrag, as every start surface should show it: with a resolved
+ * pair the template carries `pinnedAgentModel`, which node-tunables.mjs turns into LOCKED
+ * model/effort rows (New pipeline's agent rows, an Ask card's lane) — the run uses the pair
+ * whatever the project picked, so an editable model there would be a control that lies. The
+ * deep-frozen constant is never mutated: a shallow copy gains one key.
+ * @param {object} wf the workflow as assertRunnableWorkflow returned it
+ * @param {{model:string|null, effort?:string|null}|null} pair resolveDefragModel's answer
+ */
+export function defragWorkflowView(wf, pair) {
+  if (!wf || !pair || !str(pair.model)) return wf;
+  return { ...wf, pinnedAgentModel: { model: str(pair.model), effort: str(pair.effort), source: 'settings' } };
+}

package/src/core/memory-store.mjs

@@ -210,7 +210,7 @@ export async function readMemory(root, scope, name) {
 
 // ── .state counters ──────────────────────────────────────────────────────────
 const stateFile = (root, scope) => join(root, '.state', `${scopeKey(scope)}.json`);
-const EMPTY_STATE = Object.freeze({ writesSinceDefrag: 0, lastWriteAt: null, lastDefragAt: null, lastDefragRunId: null });
+const EMPTY_STATE = Object.freeze({ writesSinceDefrag: 0, lastWriteAt: null, lastDefragAt: null, lastDefragRunId: null, failedWrites: 0, lastFailedAt: null, lastFailedRunId: null });
 export async function readScopeState(root, scope) {
   const text = await readTextMaybe(stateFile(root, scope));
   if (text === null) return { ...EMPTY_STATE };
@@ -339,8 +339,9 @@ export async function removeMemory(root, scope, name, { source, now, snapshot =
 }
 
 // ── the agent-facing pointer block (§4.2, native-rules revision) ─────
-// The bodies reach the agent through Claude Code's own `.claude/rules` loader (the
-// mount lives inside every spawn's cwd — memory-sync.mjs MEMORY_RULES_REL); this block
+// The bodies reach the agent through Claude Code's own `.claude/rules` loader (the rules copy
+// lives inside every spawn's cwd (memory-sync.mjs MEMORY_RULES_REL) and is READ-ONLY there; the
+// dir lines name the WRITABLE copy (memoryWorkPath)); this block
 // only says WHERE memory lives and WHAT belongs there — the WRITE TRIGGER, the worth-a-file
 // categories and the anti-list are what decide whether a run records anything at all, so they
 // live in the intro rather than in each agent body. One `Label — /abs/dir:` line per
@@ -348,10 +349,12 @@ export async function removeMemory(root, scope, name, { source, now, snapshot =
 // intro must stay ONE line and nothing may follow the dir lines inside the block.
 export const MEMORY_BLOCK_HEADING = '## Worca memory';
 export const MEMORY_BLOCK_INTRO =
-  'Durable rules, preferences and traps kept across runs and chats. Claude Code loads them into your context ' +
-  'from the memory directories below (a file with `paths` loads when you read a matching file), so never search ' +
-  'for them (the built-in Explore and Plan sub-agents do not load them — read the files there if you are one). ' +
-  'WRITE TRIGGER: write a file there only when what you learned (a) cost you a cycle, or would have cost the next agent one, ' +
+  'Durable rules, preferences and traps kept across runs and chats. Claude Code has already loaded them into your context as rules ' +
+  '(a file with `paths` loads when you read a matching file), so never search for them (the built-in Explore and Plan sub-agents ' +
+  'do not load them — read the files in the directories below if you are one). The directories below hold the WRITABLE copy of ' +
+  'those files — worca syncs them back to its store after your turn; the read-only copy under the cwd\'s `.claude/rules/worca` is ' +
+  'Claude Code\'s own and a write there is refused as a sensitive path, so never write there. ' +
+  'WRITE TRIGGER: write a file into the directories below only when what you learned (a) cost you a cycle, or would have cost the next agent one, ' +
   'or (b) contradicted what you assumed when you started — AND will still be true next month. Worth a file: ' +
   'a trap (behaves differently from how it reads); a verification recipe (the exact command / env var / ' +
   'fixture-regeneration step that proves work here is correct); an invariant or contract the code depends ' +
@@ -375,7 +378,7 @@ export function renderMemoryBlock(sections) {
 }
 
 // ── health (§8) ──────────────────────────────────────────────────────────────
-export const MEMORY_LEVELS = Object.freeze(['fresh', 'ok', 'due', 'overdue']);
+export const MEMORY_LEVELS = Object.freeze(['fresh', 'ok', 'due', 'overdue', 'failing']);
 const DEFAULT_DEFRAG = Object.freeze({ writes: 10, files: 30, bytesPct: 60, alwaysOnBytes: 16384 });
 const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
 const names = (list) => `${list.slice(0, 3).map((e) => `${e.name}.md`).join(', ')}${list.length > 3 ? ', …' : ''}`;
@@ -390,6 +393,9 @@ const names = (list) => `${list.slice(0, 3).map((e) => `${e.name}.md`).join(', '
  * Native rules: every file WITHOUT `paths` is loaded into every agent's context at launch —
  * `alwaysOnBytes` is that cost (the figure the old 4 KB index cap used to bound). A path-scoped
  * file costs nothing until a matching file is read, so it is excluded from it.
+ * failing = the scope's last recorded write ATTEMPT by a run failed (failedWrites > 0 and no store
+ * write newer than lastFailedAt); it outranks every other level, fresh included, and a defragment
+ * resets the counters.
  */
 export function memoryHealth(entries, state, caps) {
   const list = Array.isArray(entries) ? entries : [];
@@ -412,27 +418,73 @@ export function memoryHealth(entries, state, caps) {
   const overBudget = budget > 0 && bytes * 100 >= T.bytesPct * budget;
   const pct = budget > 0 ? Math.floor((bytes * 100) / budget) : 0;
   const writes = Number(st.writesSinceDefrag) || 0;
-  const reasons = [];
+  const failedWrites = Number(st.failedWrites) || 0;
+  // A store write (any writer) newer than the last failure means the path works again; the COUNT
+  // stays as a reason until a defragment resets it. A count with no timestamp is still loud.
+  const failing = failedWrites > 0 && !(st.lastWriteAt && st.lastFailedAt && st.lastWriteAt > st.lastFailedAt);
+  const fileReasons = [];
   if (files > 0) {
-    if (writes >= T.writes) reasons.push(`${plural(writes, 'memory write')} since the last defragment (due at ${T.writes})`);
-    if (files >= T.files) reasons.push(`${plural(files, 'file')} in this scope (due at ${T.files})`);
-    if (overBudget) reasons.push(`${pct}% of the scope's byte budget in use (due at ${T.bytesPct}%)`);
-    if (oversized.length) reasons.push(`${plural(oversized.length, 'file')} over the ${soft}-byte soft cap: ${names(oversized)}`);
-    if (overHard.length) reasons.push(`${plural(overHard.length, 'file')} over the ${hard}-byte hard cap — runs cannot update them: ${names(overHard)}`);
-    if (invalid.length) reasons.push(`${plural(invalid.length, 'file')} without frontmatter — added by hand? worca still serves them; a defragment rewrites them: ${names(invalid)}`);
-    if (alwaysOnBytes >= T.alwaysOnBytes) reasons.push(`${alwaysOnBytes} bytes of memory load into the context of every agent that mounts this scope (${plural(alwaysOn.length, 'file')} without paths; due at ${T.alwaysOnBytes})`);
+    if (writes >= T.writes) fileReasons.push(`${plural(writes, 'memory write')} since the last defragment (due at ${T.writes})`);
+    if (files >= T.files) fileReasons.push(`${plural(files, 'file')} in this scope (due at ${T.files})`);
+    if (overBudget) fileReasons.push(`${pct}% of the scope's byte budget in use (due at ${T.bytesPct}%)`);
+    if (oversized.length) fileReasons.push(`${plural(oversized.length, 'file')} over the ${soft}-byte soft cap: ${names(oversized)}`);
+    if (overHard.length) fileReasons.push(`${plural(overHard.length, 'file')} over the ${hard}-byte hard cap — runs cannot update them: ${names(overHard)}`);
+    if (invalid.length) fileReasons.push(`${plural(invalid.length, 'file')} without frontmatter — added by hand? worca still serves them; a defragment rewrites them: ${names(invalid)}`);
+    if (alwaysOnBytes >= T.alwaysOnBytes) fileReasons.push(`${alwaysOnBytes} bytes of memory load into the context of every agent that mounts this scope (${plural(alwaysOn.length, 'file')} without paths; due at ${T.alwaysOnBytes})`);
   }
-  const level = files === 0 ? 'fresh'
+  const reasons = [...fileReasons];
+  if (failedWrites > 0) {
+    reasons.push(`${plural(failedWrites, 'memory write')} by runs failed since the last defragment` +
+      `${st.lastFailedRunId ? ` — last in run ${st.lastFailedRunId}` : ''}; that run's History detail carries the reason`);
+  }
+  const level = failing ? 'failing'
+    : files === 0 ? 'fresh'
     : (writes >= 2 * T.writes || overHard.length || alwaysOnBytes >= 2 * T.alwaysOnBytes) ? 'overdue'
-    : reasons.length ? 'due' : 'ok';
+    : fileReasons.length ? 'due' : 'ok';
   return {
     files, bytes, oversized: oversized.length, overHard: overHard.length, invalidFrontmatter: invalid.length,
     alwaysOnBytes, alwaysOnFiles: alwaysOn.length,
     writesSinceDefrag: writes, lastWriteAt: st.lastWriteAt, lastDefragAt: st.lastDefragAt, lastDefragRunId: st.lastDefragRunId,
+    failedWrites, lastFailedAt: st.lastFailedAt, lastFailedRunId: st.lastFailedRunId,
     level, reasons,
   };
 }
 
+// ── the defragmenter's brief (§7) ────────────────────────────────────────────
+export const DEFRAG_BRIEF_HEADING = '## Memory health';
+
+/**
+ * Pure. The section a Memory defragment run appends to its task document: WHY the scope is
+ * flagged (memoryHealth's own reasons, verbatim — the same lines Settings → Memory shows) and the
+ * budgets a finished defragment has to meet. Without it the agent tidies topics and leaves the
+ * scope exactly as `due` as it found it: the always-on budget is a property of the whole scope,
+ * which no single file shows. A healthy scope still gets the budgets, so a defragment never
+ * breaks one. Thresholds resolve exactly as memoryHealth resolves them; byte-stable.
+ * @param {ReturnType<typeof memoryHealth>} health
+ * @param {object} [caps] memoryCaps()
+ */
+export function renderDefragBrief(health, caps) {
+  const h = health && typeof health === 'object' ? health : memoryHealth([], null, caps);
+  const T = { ...DEFAULT_DEFRAG, ...(caps?.defrag && typeof caps.defrag === 'object' ? caps.defrag : {}) };
+  const soft = caps?.softBytesPerFile ?? 8192;
+  const hard = caps?.hardBytesPerFile ?? 32768;
+  const maxFiles = caps?.maxFilesPerScope ?? 50;
+  const reasons = Array.isArray(h.reasons) ? h.reasons : [];
+  const lines = ['', DEFRAG_BRIEF_HEADING, ''];
+  if (reasons.length) {
+    lines.push(`Level: ${h.level}. worca flags this scope for the reasons below — the defragment is finished only when none of them still holds ` +
+      '(a write-count or failed-write reason clears by itself when this run ends; every other one needs your edits):', '');
+    for (const r of reasons) lines.push(`- ${flattenLine(r)}`);
+  } else {
+    lines.push(`Level: ${h.level}. No threshold is crossed — keep it that way.`);
+  }
+  lines.push('',
+    `Budgets for this scope: always-on memory (files WITHOUT \`paths\` — loaded into every agent's context) under ${T.alwaysOnBytes} bytes — ` +
+    `now ${h.alwaysOnBytes} in ${plural(h.alwaysOnFiles, 'file')}; fewer than ${T.files} files — now ${h.files}; ` +
+    `each file under ${soft} bytes (hard cap ${hard}); all files together under ${T.bytesPct}% of ${maxFiles} × ${soft} bytes — now ${h.bytes}.`);
+  return `${lines.join('\n')}\n`;
+}
+
 /** Everything a scope view or route needs in one read: the listing, the counters and the health. */
 export async function memoryScopeReport(root, scope, caps, { onError } = {}) {
   const entries = await listMemory(root, scope, { onError });