@volter/supercode-orchestrator 0.4.4

package/apply/hermes_door.py

@@ -0,0 +1,129 @@
+"""The applier's door into one Hermes home: Hermes's own functions, in the order
+Hermes's own callers run them (docs/plans/content-spec-status.md §7).
+
+Run under Hermes's interpreter with HERMES_HOME set to the home being applied.
+One request on stdin, one JSON answer on stdout (the line marked MARK): {"ok": true, "result": ...} or
+{"ok": false, "error": "..."}. Nothing here writes a Hermes file itself.
+
+  list                          cron.jobs.load_jobs()
+  create   {kwargs}             the prompt scan the agent's tool and the API
+                                server run, then create_job_with_scheduler_registration,
+                                then _notify_provider_jobs_changed
+  update   {id, updates}        update_job, then the notify
+  pause    {id, reason}         pause_job, then the notify
+  resume   {id}                 resume_job, then the notify
+  remove   {id}                 remove_job, then the notify
+  capture  {id}                 a job's durable data before it is deleted: its notepad
+                                (cron.notepad.list_notes) and its run outputs
+  config_read  {keys}           load_config(): the effective value of each dotted key, with the
+                                file's own ${VAR} template where the value is its expansion
+                                (_preserve_env_ref_templates against read_raw_config)
+  config_write {values}         save_config(<those keys only>, merge_existing=True)
+"""
+
+import json
+import sys
+
+
+def _notify():
+    try:
+        from cron.scheduler import _notify_provider_jobs_changed
+        _notify_provider_jobs_changed()
+    except Exception:
+        pass  # best-effort, as every Hermes caller treats it
+
+
+def _dig(tree, dotted):
+    node = tree
+    for part in dotted.split("."):
+        if not isinstance(node, dict) or part not in node:
+            return None
+        node = node[part]
+    return node
+
+
+def _nest(values):
+    tree = {}
+    for dotted, value in values.items():
+        node = tree
+        parts = dotted.split(".")
+        for part in parts[:-1]:
+            node = node.setdefault(part, {})
+        node[parts[-1]] = value
+    return tree
+
+
+def main():
+    request = json.loads(sys.stdin.read() or "{}")
+    op = request.get("op")
+    args = request.get("args") or {}
+    if op == "list":
+        from cron.jobs import load_jobs
+        return load_jobs()
+    if op == "create":
+        kwargs = dict(args.get("kwargs") or {})
+        prompt = kwargs.get("prompt")
+        if prompt:
+            from tools.cronjob_tools import _scan_cron_prompt
+            scan_error = _scan_cron_prompt(prompt)
+            if scan_error:
+                raise ValueError(scan_error)
+        from cron.scheduler import create_job_with_scheduler_registration
+        job = create_job_with_scheduler_registration(**kwargs)
+        _notify()
+        return job
+    if op in ("update", "pause", "resume", "remove"):
+        from cron import jobs as store
+        job_id = args["id"]
+        if op == "update":
+            prompt = (args.get("updates") or {}).get("prompt")
+            if prompt:
+                from tools.cronjob_tools import _scan_cron_prompt
+                scan_error = _scan_cron_prompt(prompt)
+                if scan_error:
+                    raise ValueError(scan_error)
+            result = store.update_job(job_id, args.get("updates") or {})
+        elif op == "pause":
+            result = store.pause_job(job_id, args.get("reason"))
+        elif op == "resume":
+            result = store.resume_job(job_id)
+        else:
+            result = store.remove_job(job_id)
+        if result is None or result is False:
+            raise LookupError(f"Hermes has no job {job_id}")
+        _notify()
+        return result
+    if op == "capture":
+        from cron.notepad import list_notes
+        from cron.jobs import _job_output_dir
+        job_id = args["id"]
+        outputs = {}
+        try:
+            folder = _job_output_dir(job_id)
+            for path in sorted(folder.glob("*.md")) if folder.is_dir() else []:
+                outputs[path.name] = path.read_text(encoding="utf-8", errors="replace")
+        except ValueError:
+            pass
+        return {"notes": list_notes(job_id), "outputs": outputs}
+    if op == "config_read":
+        from hermes_cli.config import _preserve_env_ref_templates, load_config, read_raw_config
+        effective = load_config() or {}
+        raw = read_raw_config() or {}
+        # load_config expands ${VAR}; a value declared as a template reads back as the template it is on disk
+        return {key: _preserve_env_ref_templates(_dig(effective, key), _dig(raw, key)) for key in args.get("keys") or []}
+    if op == "config_write":
+        from hermes_cli.config import save_config
+        save_config(_nest(args.get("values") or {}), merge_existing=True)
+        return True
+    raise ValueError(f"unknown op {op!r}")
+
+
+MARK = "@@supercode-apply@@"  # Hermes may print while importing; the answer is the marked line
+
+
+if __name__ == "__main__":
+    try:
+        answer = {"ok": True, "result": main()}
+    except Exception as exc:  # the applier reports it per record
+        answer = {"ok": False, "error": f"{type(exc).__name__}: {exc}"}
+    print(MARK + json.dumps(answer, default=str), flush=True)

package/apply/index.d.ts

@@ -0,0 +1,4 @@
+// The applier's entry point: the same declarations as the root's "agent-setup applier" (index.d.ts), under the names
+// this module exports them by (index.mjs re-exports them renamed). A consumer that loads only the applier imports this
+// path and keeps its types.
+export { planSetup as plan, applySetup as apply, adoptSetup as adopt, resolveSetup as resolve, provisionHome as provision, validateSetup as validate, resolveParameters, hermesConfig, SETUP_SCHEMA_VERSION as SCHEMA_VERSION } from '@volter/supercode-orchestrator';

package/apply/index.mjs

@@ -0,0 +1,441 @@
+// The agent-setup applier (docs/plans/content-spec-status.md §7): a package's declared jobs, its
+// Inference and its harness settings reach one home through the gateway's own door (doors.mjs), against
+// a base the applier keeps in its own state (state.mjs). Ownership is by harness id, never by name.
+// Every record gets one row of §7's table:
+//
+//   owned, spec equals base and live equals read-back      stamp
+//   spec changed, live equals read-back                     act (only the fields that differ from live)
+//   live changed, spec unchanged                            conflict, reported to the manager
+//   both changed                                            conflict, reported
+//   declared, no base, no unowned live record with the key  create (home provisioned; else plan-only)
+//   declared, no base, an unowned live record has the key   unowned, reported (adopt is an act)
+//   owned, live in error                                    the harness's error, reported
+//   owned, live missing, last lifecycle completed           forgotten (lifecycle), no report
+//   owned, live missing otherwise                           deleted, reported, never re-created
+//   owned, `removed` in the declaration                     forget | pause | delete (delete only through a
+//                                                           reviewed plan, after its durable data is captured)
+//   owned, bare removal from the declaration                still live, reported
+//   a record the target cannot express                      refused: that record only
+//
+// `act` and `create` need no judgment and run whenever apply runs; every report goes to the manager.
+// Inference and harness settings are planned and applied before triggers. A plan is bound by its hash
+// to the base, the spec and the live records it read; applying a stale plan is refused.
+
+import { canonical, hash, lock, provision as provisionState, readIntents, readState, stateRoot, writeCapture, writeIntents, writeState } from './state.mjs';
+import { MANAGED_JOB_FIELDS, namedModel } from './doors.mjs';
+
+export const SCHEMA_VERSION = 1;
+/** How long after an intent a live record may be taken as the applier's own create. */
+const INTENT_WINDOW_MS = 10 * 60_000;
+
+const managedOf = (row) => canonical(Object.fromEntries(MANAGED_JOB_FIELDS.map((f) => [f, row.managed[f] ?? null])));
+
+/**
+ * Parameters (plan §6): scalars the manifest names, resolved at render time
+ * from the values the runtime passes (the workspace is the checkout's path).
+ * `{{name}}` in any string is replaced; a name the manifest does not list, or a
+ * listed one with no value and no default, is refused.
+ */
+export function resolveParameters(spec, values = {}) {
+  const declared = spec?.parameters ?? {};
+  const value = (name) => {
+    if (!(name in declared)) throw new Error(`{{${name}}} is not a parameter the setup declares`);
+    const v = values[name] ?? declared[name]?.default;
+    if (v === undefined || v === null) throw new Error(`parameter ${name} has no value`);
+    if (typeof v !== 'string' && typeof v !== 'number' && typeof v !== 'boolean') throw new Error(`parameter ${name} must be a scalar`);
+    return String(v);
+  };
+  const walk = (node) => {
+    if (typeof node === 'string') return node.replace(/\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g, (_, name) => value(name));
+    if (Array.isArray(node)) return node.map(walk);
+    if (node && typeof node === 'object') return Object.fromEntries(Object.entries(node).map(([k, v]) => [k, k === 'parameters' ? v : walk(v)]));
+    return node;
+  };
+  return walk(spec);
+}
+
+/** Refuse what the package as a whole cannot mean; a single record's problem is that record's refusal. */
+export function validate(spec) {
+  if (spec?.schema_version !== SCHEMA_VERSION) throw new Error(`schema_version ${JSON.stringify(spec?.schema_version)} is not ${SCHEMA_VERSION}`);
+  for (const key of Object.keys(spec.jobs ?? {})) if (!/^[A-Za-z0-9._ -]{1,128}$/.test(key)) throw new Error(`job key ${JSON.stringify(key)} is not a name`);
+  for (const m of spec.moved ?? []) if (!m?.from || !m?.to) throw new Error('every moved entry needs from and to');
+  for (const r of spec.removed ?? []) if (!r?.key || !['forget', 'pause', 'delete'].includes(r.then)) throw new Error('every removed entry needs a key and then: forget | pause | delete');
+  return spec;
+}
+
+/** A custody name (plan §3.4): an environment variable's name, written as Hermes's `${NAME}` reference, never its value. */
+function custodyRef(name, what) {
+  if (!/^[A-Z][A-Z0-9_]*$/.test(String(name ?? ''))) throw new Error(`${what} must be a custody name (an environment variable's name), got ${JSON.stringify(name)}`);
+  return `\${${name}}`;
+}
+
+/**
+ * The Hermes config keys a package manages (plan §5, §6), grouped into the
+ * units apply writes whole:
+ * - Inference: the default pointer's `model.*` (its endpoint and key as custody
+ *   references, or a literal URL and a placeholder key); the unattended
+ *   pointer's `cron.model` with `cron.model_provider`, one unit that is never
+ *   written half; delegation's `delegation.*`; the fallback chain;
+ * - `extensions.hermes.config`: Hermes-only settings in its own dotted names.
+ */
+export function hermesConfig(spec) {
+  const inf = spec.inference ?? {};
+  const pick = (name) => {
+    const m = name ? inf.models?.[name] : null;
+    if (name && !m) throw new Error(`inference pointer names ${JSON.stringify(name)}, which is not in inference.models`);
+    return m;
+  };
+  const units = [];
+  // each unit is built on its own: one bad entry refuses that unit, never the others
+  const unit = (name, build) => { try { units.push({ unit: name, values: build() }); } catch (error) { units.push({ unit: name, error: error.message }); } };
+  const d = (() => { try { return pick(inf.default); } catch (error) { units.push({ unit: 'inference.default', error: error.message }); return null; } })();
+  if (d) unit('inference.default', () => {
+    const v = { 'model.default': d.model, 'model.provider': d.provider ?? '' };
+    if (d.endpoint && d.base_url) throw new Error('a named model takes endpoint (a custody name) or base_url (a literal URL), not both');
+    if (d.endpoint) v['model.base_url'] = custodyRef(d.endpoint, 'an endpoint');
+    if (d.base_url) {
+      if (!/^https?:\/\/[^\s@?#]+$/.test(d.base_url)) throw new Error(`base_url ${JSON.stringify(d.base_url)} must be a plain http(s) URL with no credentials or query`);
+      v['model.base_url'] = d.base_url;
+    }
+    if (d.credential && d.placeholder_key) throw new Error('a named model takes credential or placeholder_key, not both');
+    if (d.credential && d.credential !== 'harness-login') v['model.api_key'] = custodyRef(d.credential, 'a credential');
+    if (d.placeholder_key) {
+      if (!/^[a-z][a-z-]{0,15}$/.test(d.placeholder_key)) throw new Error('placeholder_key is a short lowercase word, never a secret');
+      v['model.api_key'] = d.placeholder_key;
+    }
+    if (d.api_mode) v['model.api_mode'] = d.api_mode;
+    return v;
+  });
+  if (inf.unattended) unit('inference.unattended', () => {
+    const u = pick(inf.unattended);
+    // with cron.model alone, Hermes's drift guard trips (plan §5, measured): the provider is required
+    if (!u.provider) throw new Error('the unattended model needs its provider: cron.model is written with cron.model_provider, never alone');
+    return { 'cron.model': u.model, 'cron.model_provider': u.provider };
+  });
+  if (inf.delegation) unit('inference.delegation', () => { const g = pick(inf.delegation); return { 'delegation.model': g.model, 'delegation.provider': g.provider ?? '' }; });
+  if (Array.isArray(inf.fallbacks)) unit('inference.fallbacks', () => ({ fallback_providers: inf.fallbacks.map((name) => { const m = pick(name); return { provider: m.provider, model: m.model }; }) }));
+  for (const [key, value] of Object.entries(spec.extensions?.hermes?.config ?? {})) {
+    unit(`setting.${key}`, () => {
+      if (/^model(\.|$)|^cron\.model|^delegation\.(model|provider)$|^fallback_providers$/.test(key)) throw new Error(`extensions.hermes.config.${key} is Inference's to manage`);
+      return { [key]: value };
+    });
+  }
+  return units;
+}
+
+/** Each config unit's row: its values against the base and the live config. */
+function diffConfig({ state, spec, live }) {
+  const rows = [];
+  const units = hermesConfig(spec);
+  const base = state?.config ?? {};
+  for (const { unit, values, error } of units) {
+    if (error) { rows.push({ key: unit, action: 'refused', detail: error }); continue; }
+    const want = canonical(values);
+    const has = canonical(Object.fromEntries(Object.keys(values).map((k) => [k, live[k] ?? null])));
+    const b = base[unit];
+    if (!b) rows.push(has === want ? { key: unit, action: 'stamp', values } : { key: unit, action: state === null ? 'plan-only' : 'act', values });
+    else {
+      const specChanged = b.declared !== want;
+      const liveChanged = b.readback !== has;
+      // Both moved to the same value (the owner set by hand what the declaration now says): agreed, not a conflict.
+      if ((!specChanged && !liveChanged) || has === want) rows.push({ key: unit, action: 'stamp', values });
+      else if (specChanged && !liveChanged) rows.push({ key: unit, action: 'act', values });
+      else rows.push({ key: unit, action: 'conflict', values, detail: specChanged ? 'both the declaration and the live value changed' : 'the live value changed (hermes config set, /model); the manager decides whether to capture it back' });
+    }
+  }
+  // a unit applied once and no longer declared: Hermes has no function that unsets a key, so the home keeps
+  // the value; said, like a job still live, until the manager sets it or `resolve`s the unit
+  const declared = new Set(units.map((u) => u.unit));
+  for (const unit of Object.keys(base)) {
+    if (!declared.has(unit)) rows.push({ key: unit, action: 'still-live', detail: 'applied before, no longer declared; the home keeps its value until it is set there or resolved' });
+  }
+  return rows;
+}
+
+function diffJobs({ state, live, spec, door }) {
+  const records = { ...(state?.records ?? {}) };
+  const rows = [];
+  // `moved` renames the base's key before anything is compared; a move that cannot happen is said
+  for (const { from, to } of spec.moved ?? []) {
+    if (records[from] && !records[to]) { records[to] = records[from]; delete records[from]; rows.push({ key: to, action: 'moved', from, detail: `was ${from}` }); }
+    else if (records[from] && records[to]) rows.push({ key: to, action: 'refused', detail: `moved from ${from}: ${to} is already owned` });
+  }
+  const byId = new Map(live.map((r) => [r.id, r]));
+  const owned = new Set(Object.values(records).map((r) => r.id));
+  const removed = new Map((spec.removed ?? []).map((r) => [r.key, r.then]));
+  const declared = spec.jobs ?? {};
+  for (const [key, job] of Object.entries(declared)) {
+    let want;
+    try {
+      // context_from names jobs by their declared keys; the harness wants its own ids
+      const refs = job.context_from === undefined ? undefined : (Array.isArray(job.context_from) ? job.context_from : [job.context_from]).map((ref) => {
+        if (ref === 'self') return ref;
+        const owner = records[ref];
+        if (!owner) throw new Error(`context_from names ${JSON.stringify(ref)}, which this home does not own yet; it applies once ${ref} exists`);
+        return owner.id;
+      });
+      want = door.fields(refs === undefined ? job : { ...job, context_from: refs }, spec.inference);
+    } catch (error) { rows.push({ key, action: 'refused', detail: error.message }); continue; }
+    const base = records[key];
+    if (!base) {
+      const carrier = live.find((r) => r.name === key && !owned.has(r.id));
+      if (carrier) rows.push({ key, action: 'unowned', id: carrier.id, detail: 'a live record carries this key; adopt it to own it' });
+      else if (state === null) rows.push({ key, action: 'plan-only', detail: 'this home has no apply state: provision or adopt it first' });
+      else rows.push({ key, action: 'create', want, enabled: job.enabled !== false });
+      continue;
+    }
+    const row = byId.get(base.id);
+    if (!row) {
+      rows.push(base.lifecycle === 'completed'
+        ? { key, action: 'forget', id: base.id, detail: 'completed and gone (its lifecycle)' }
+        : { key, action: 'deleted', id: base.id, detail: 'owned, but the harness no longer has it; never re-created' });
+      continue;
+    }
+    if (row.lifecycle === 'error') { rows.push({ key, action: 'harness-error', id: row.id, detail: 'the harness reports this job in error' }); continue; }
+    const specChanged = base.declared !== canonical(want);
+    const liveChanged = base.readback !== managedOf(row);
+    if (liveChanged) { rows.push({ key, action: 'conflict', id: row.id, detail: specChanged ? 'both the declaration and the live record changed' : 'the live record changed; the manager decides whether to capture it back' }); continue; }
+    if (!specChanged) { rows.push({ key, action: 'stamp', id: row.id, lifecycle: row.lifecycle, detail: row.lifecycle === 'paused' ? 'converged; the pause stands (an overlay)' : 'converged' }); continue; }
+    // act: only what differs from live, so an unchanged schedule is never re-armed
+    let patch = door.differs(want, row.managed);
+    // a field the declaration held and no longer does is cleared, never left as it was
+    const before = base.declared ? JSON.parse(base.declared) : {};
+    const dropped = Object.keys(before).filter((f) => f !== 'schedule' && !(f in want) && !(before[f] === null || before[f] === undefined));
+    const clear = Object.fromEntries(dropped.map((f) => [f, f === 'no_agent' ? false : null]));
+    let pinKept = base.pinKept ?? null;
+    // An adopted record's live model pin is kept, reported, until the declared model itself changes (plan §5)
+    const declaredModel = canonical({ model: want.model ?? null, provider: want.provider ?? null });
+    if (base.declared === null && !base.resolved && (row.managed.model || row.managed.provider) && patch.some((f) => f === 'model' || f === 'provider')) pinKept = declaredModel;
+    if (pinKept && pinKept === declaredModel) patch = patch.filter((f) => f !== 'model' && f !== 'provider');
+    else pinKept = null;
+    const changes = { ...clear, ...Object.fromEntries(patch.map((f) => [f, want[f]])) };
+    const notes = [pinKept ? `the live model pin (${row.managed.provider ?? ''}/${row.managed.model ?? ''}) is kept until the declared model changes` : null, dropped.length ? `no longer declared, cleared: ${dropped.join(', ')}` : null].filter(Boolean);
+    rows.push({ key, action: Object.keys(changes).length ? 'act' : 'stamp', id: row.id, want, patch: changes, pinKept, lifecycle: row.lifecycle, detail: notes.length ? notes.join('; ') : undefined });
+  }
+  for (const [key, base] of Object.entries(records)) {
+    if (declared[key]) continue;
+    const then = removed.get(key);
+    const row = byId.get(base.id);
+    // gone or finished already: whatever the removal asked, there is only a record to forget
+    if (then && (!row || row.lifecycle === 'completed')) rows.push({ key, action: 'forget', id: base.id, detail: `removed (${then}); the harness no longer runs it` });
+    else if (then) rows.push({ key, action: `remove:${then}`, id: base.id });
+    else if (row) rows.push({ key, action: 'still-live', id: base.id, detail: 'owned but no longer declared; declare `removed` to forget, pause or delete it' });
+    else rows.push({ key, action: 'forget', id: base.id, detail: 'owned, undeclared and gone' });
+  }
+  return rows;
+}
+
+/**
+ * The plan for one home: a row per record, and the hash that binds it to the
+ * base, the spec and the live records it read (the owned ones and any carrying
+ * a declared key; a record the agent makes meanwhile does not stale it).
+ */
+export async function plan({ door, homeId, spec: raw, root = stateRoot(), params = {} }) {
+  const spec = validate(resolveParameters(raw, params));
+  const state = readState(root, homeId);
+  const live = await door.list();
+  let configLive = {};
+  let configRows = [];
+  if (door.readInference && (spec.inference || spec.extensions?.hermes || Object.keys(state?.config ?? {}).length)) {
+    const units = hermesConfig(spec).filter((u) => u.values);
+    const keys = units.flatMap((u) => Object.keys(u.values));
+    configLive = keys.length ? await door.readInference(keys) : {};
+    configRows = diffConfig({ state, spec, live: configLive });
+  } else if (spec.inference && !door.readInference) {
+    configRows = [{ key: 'inference', action: 'refused', detail: `${door.target} has no door for Inference here; its worker model is the profile's` }];
+  }
+  const jobRows = diffJobs({ state, live, spec, door });
+  const owned = new Set(Object.values(state?.records ?? {}).map((r) => r.id));
+  const keys = new Set(Object.keys(spec.jobs ?? {}));
+  const seen = live.filter((r) => owned.has(r.id) || keys.has(r.name)).map((r) => ({ id: r.id, name: r.name, m: managedOf(r), l: r.lifecycle }));
+  return {
+    homeId, planOnly: state === null, rows: [...configRows, ...jobRows],
+    hash: hash({ base: state ?? null, spec, live: seen, config: configLive }),
+  };
+}
+
+/**
+ * Apply: under the home's lock, recompute the plan; refuse when a stored plan's
+ * hash no longer matches; apply config units, then creates (each behind an
+ * intent) and acts; write the new base with every verb's read-back as one
+ * generation. Reports come back as rows.
+ */
+export async function apply({ door, homeId, spec: raw, root = stateRoot(), planHash = null, reviewedPlan = false, params = {} }) {
+  const spec = validate(resolveParameters(raw, params));
+  const release = lock(root, homeId);
+  try {
+    const fresh = await plan({ door, homeId, spec, root });
+    if (planHash && planHash !== fresh.hash) throw new Error('the stored plan is stale: the base, the spec or the live records changed since it was made');
+    if (fresh.planOnly) return { ...fresh, applied: [] };
+    // this apply's one generation (none when it changes nothing); every verb after it is written in place,
+    // so a crash loses no record
+    const changes = readIntents(root, homeId).length || fresh.rows.some((r) => ['create', 'act', 'moved', 'forget', 'remove:forget', 'remove:pause', 'remove:delete'].includes(r.action));  // config units' acts included
+    const state = changes ? writeState(root, homeId, readState(root, homeId)) : readState(root, homeId);
+    state.records ??= {};
+    state.config ??= {};
+    const applied = await recoverIntents({ state, door, spec, root, homeId });
+    const save = () => writeState(root, homeId, state, { generation: false });
+    for (const row of fresh.rows) {
+      try {
+        if (row.key.startsWith('inference.') || row.key.startsWith('setting.')) {
+          if (row.action === 'act') {
+            await door.writeInference(row.values);
+            const back = await door.readInference(Object.keys(row.values));
+            const has = canonical(Object.fromEntries(Object.keys(row.values).map((k) => [k, back[k] ?? null])));
+            state.config[row.key] = { declared: canonical(row.values), readback: has };
+            // a managed scope, or Hermes stripping a default, can leave the value other than declared: said, not assumed
+            applied.push(has === canonical(row.values) ? { key: row.key, action: 'updated' } : { key: row.key, action: 'not-applied', detail: 'the harness reads back a different value (a managed scope, or a default it strips)' });
+          } else if (row.action === 'stamp') {
+            state.config[row.key] = { declared: canonical(row.values), readback: canonical(row.values) };
+          }
+          continue;
+        }
+        if (row.action === 'moved') {
+          if (state.records[row.from] && !state.records[row.key]) { state.records[row.key] = state.records[row.from]; delete state.records[row.from]; }
+        } else if (row.action === 'create') {
+          const intents = readIntents(root, homeId);
+          writeIntents(root, homeId, [...intents, { key: row.key, at: new Date().toISOString(), declared: canonical(row.want), want: row.want, enabled: row.enabled }]);
+          let made = await door.create(row.key, row.want);
+          // create then pause is one intent: the intent stays until the pause is done
+          if (!row.enabled) made = await door.pause(made.id);
+          state.records[row.key] = { id: made.id, declared: canonical(row.want), readback: managedOf(made), lifecycle: made.lifecycle };
+          save();
+          writeIntents(root, homeId, readIntents(root, homeId).filter((i) => i.key !== row.key));
+          applied.push({ key: row.key, action: 'created', id: made.id });
+        } else if (row.action === 'act') {
+          const after = await door.update(row.id, row.patch);
+          state.records[row.key] = { id: after.id, declared: canonical(row.want), readback: managedOf(after), lifecycle: after.lifecycle, ...(row.pinKept ? { pinKept: row.pinKept } : {}) };
+          // what was sent is checked against what the harness now holds: a field it rewrote is said, not assumed
+          const left = door.differs(row.patch, after.managed);
+          applied.push(left.length
+            ? { key: row.key, action: 'not-applied', id: after.id, detail: `the harness holds other values for ${left.join(', ')} than were sent` }
+            : { key: row.key, action: 'updated', id: after.id, detail: Object.keys(row.patch).join(', ') });
+        } else if (row.action === 'stamp' && row.id && state.records[row.key]) {
+          state.records[row.key].lifecycle = row.lifecycle ?? state.records[row.key].lifecycle;
+          if (row.want) { state.records[row.key].declared = canonical(row.want); if (row.pinKept) state.records[row.key].pinKept = row.pinKept; }
+        } else if (row.action === 'forget' || row.action === 'remove:forget') {
+          delete state.records[row.key];
+          applied.push({ key: row.key, action: 'forgotten', id: row.id });
+        } else if (row.action === 'remove:pause') {
+          await door.pause(row.id);
+          delete state.records[row.key];
+          applied.push({ key: row.key, action: 'paused and forgotten', id: row.id });
+        } else if (row.action === 'remove:delete') {
+          // only through the plan the manager reviewed (never at start), and only after the record's
+          // durable data is captured beside the applier's state
+          if (!reviewedPlan || !planHash) { applied.push({ key: row.key, action: 'refused', detail: 'delete runs only through a reviewed, stored plan (--plan-hash with --reviewed)' }); continue; }
+          const captured = writeCapture(root, homeId, row.key, row.id, await door.capture(row.id));
+          await door.remove(row.id);
+          delete state.records[row.key];
+          applied.push({ key: row.key, action: 'deleted', id: row.id, detail: `durable data captured in ${captured}` });
+        }
+      } catch (error) {
+        // refusal is per record: one record's failure never stops the others
+        applied.push({ key: row.key, action: 'refused', detail: error.message });
+      }
+      save();
+    }
+    return { ...fresh, applied };
+  } finally {
+    release();
+  }
+}
+
+/**
+ * A crash between a create's verb and the base's write leaves an intent. It is
+ * the applier's own act only when exactly one unowned live record carries the
+ * key, the declared values and a creation time inside the intent's window;
+ * then an intended pause is finished. Anything else stays an intent, reported.
+ */
+async function recoverIntents({ state, door, spec, root, homeId }) {
+  const intents = readIntents(root, homeId);
+  if (!intents.length) return [];
+  const live = await door.list();
+  const owned = new Set(Object.values(state.records).map((r) => r.id));
+  const left = [];
+  const report = [];
+  for (const intent of intents) {
+    const at = Date.parse(intent.at);
+    const job = spec.jobs?.[intent.key];
+    // the values the create was sent (references already resolved to ids), as the intent recorded them
+    const want = job ? intent.want ?? null : null;
+    // compared on what Hermes stores as given (paths and references it normalizes are left out)
+    const core = want ? Object.fromEntries(Object.entries(want).filter(([f]) => ['schedule', 'prompt', 'skills', 'script', 'no_agent'].includes(f))) : null;
+    const matches = live.filter((r) => !owned.has(r.id) && r.name === intent.key && r.created_at
+      && Math.abs(Date.parse(r.created_at) - at) <= INTENT_WINDOW_MS && core && door.differs(core, r.managed).length === 0);
+    if (matches.length === 1 && want && canonical(want) === intent.declared) {
+      let row = matches[0];
+      if (intent.enabled === false && row.lifecycle !== 'paused') row = await door.pause(row.id);
+      state.records[intent.key] = { id: row.id, declared: intent.declared, readback: managedOf(row), lifecycle: row.lifecycle };
+      owned.add(row.id);
+      report.push({ key: intent.key, action: 'recovered', id: row.id, detail: 'a create interrupted before its record was written' });
+    } else if (!matches.length && (!job || Date.now() - at > INTENT_WINDOW_MS)) {
+      // nothing was made (the harness refused it) or the key is no longer declared: nothing to recover
+      report.push({ key: intent.key, action: 'intent-dropped', detail: 'an interrupted create left no record to recover' });
+    } else {
+      left.push(intent);
+      report.push({ key: intent.key, action: 'intent-unresolved', detail: `${matches.length} live record(s) match an interrupted create; reported, not assumed` });
+    }
+  }
+  writeIntents(root, homeId, left);
+  return report;
+}
+
+/**
+ * Resolve a conflict (a per-home act, the manager's): the live record becomes
+ * the base. The next apply then either restores the declaration over it (the
+ * manager chose the package) or finds nothing to change (the manager captured
+ * the live value back into the package first). Config units likewise.
+ */
+export async function resolve({ door, homeId, keys, root = stateRoot() }) {
+  const release = lock(root, homeId);
+  try {
+    const state = readState(root, homeId);
+    if (!state) throw new Error(`home ${homeId} has no apply state; there is nothing to resolve`);
+    const live = await door.list();
+    const out = [];
+    for (const key of keys) {
+      if (state.config?.[key]) { delete state.config[key]; out.push({ key, action: 'resolved' }); continue; }
+      const base = state.records?.[key];
+      const row = base && live.find((r) => r.id === base.id);
+      if (!row) { out.push({ key, action: 'refused', detail: 'not an owned record with a live counterpart' }); continue; }
+      state.records[key] = { id: base.id, declared: null, readback: managedOf(row), lifecycle: row.lifecycle, resolved: true };
+      out.push({ key, action: 'resolved', id: row.id });
+    }
+    writeState(root, homeId, state);
+    return out;
+  } finally {
+    release();
+  }
+}
+
+/** Adopt (a per-home act): the named live records become owned, their base the live read-back. */
+export async function adopt({ door, homeId, keys, root = stateRoot() }) {
+  const release = lock(root, homeId);
+  try {
+    const state = readState(root, homeId) ?? { records: {}, generation: 0 };
+    state.records ??= {};
+    const live = await door.list();
+    const owned = new Set(Object.values(state.records).map((r) => r.id));
+    const adopted = [];
+    for (const key of keys) {
+      const candidates = live.filter((r) => r.name === key && !owned.has(r.id));
+      if (candidates.length !== 1) { adopted.push({ key, action: 'refused', detail: `${candidates.length} unowned live record(s) carry this key` }); continue; }
+      const row = candidates[0];
+      // declared is left unset, so the next apply acts: only the fields that differ, a live pin kept
+      state.records[key] = { id: row.id, declared: null, readback: managedOf(row), lifecycle: row.lifecycle };
+      owned.add(row.id);
+      adopted.push({ key, action: 'adopted', id: row.id });
+    }
+    writeState(root, homeId, state);
+    return adopted;
+  } finally {
+    release();
+  }
+}
+
+/** Provisioning: the runtime's own new home gets an empty state, so its first apply creates. */
+export function provision({ homeId, root = stateRoot() }) {
+  const release = lock(root, homeId);
+  try { return provisionState(root, homeId); } finally { release(); }
+}