@awebai/oats 0.27.1 → 0.28.0

package/bin/oats.mjs

@@ -32,12 +32,13 @@ import {
 import {
   writeFileAtomic, LOCK_FILE, readLock, writeLock, resolvePackages,
   classifyPackageValue, parsePackageRequest } from "../lib/packages.mjs";
-import { loadLocal, validateWorkspace, validateLocal } from "../lib/workspace.mjs";
+import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, workspaceWarnings } from "../lib/workspace.mjs";
 import { parseConfigData } from "../lib/config-data.mjs";
 import * as remoteModule from "../lib/remote.mjs";
 import YAML from "yaml";
 import { attachArgv, checkRemote, forgetSnapshot, getServer, inspectRemote, startRemote, restartRemote, launchConfigRemote, scheduleRemote, listSnapshots, readServers, rosterGroups, routeCommand, targetOf, validateServer, writeServers, SERVERS_FILE } from "../lib/servers.mjs";
 import { spawnSync as spawnSyncProc } from "node:child_process";
+import { tickTriggers } from "../lib/triggers.mjs";
 import { parseEnvelopeText, scheduleScopeOf, listSchedules, describe as describeSchedule, addSchedule, updateSchedule, setEnabled as setScheduleEnabled, removeSchedule, runNow as runScheduleNow, reconcile as reconcileSchedule, tickHost, tickWorkspace, registerWorkspace, unregisterWorkspace, readRegistry, schedulerStatus, saveWakeForHome, removeWakeForHome, wakeFromFlags, withHostLock, scheduleError, SCHEDULE_API } from "../lib/schedule.mjs";
 import { hostUnitStatus, installHostUnit, uninstallHostUnit } from "../lib/schedule-host.mjs";
 import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
@@ -48,10 +49,32 @@ const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli }
 import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
 import { readEvents } from "../lib/instance-events.mjs";
 
-const args = process.argv.slice(2);
+const rawArgs = process.argv.slice(2);
+/** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
+const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "json", "keep-dir", "keep-env", "no-child-spawns", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "self", "verbose", "yes", "yolo"]);
+/** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
+ *  routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
+ *  `--flag=` or a switch given a value. */
+function expandInlineValues(argv) {
+  const out = [];
+  let problem;
+  for (const a of argv) {
+    const eq = a.indexOf("=");
+    if (!a.startsWith("--") || eq <= 2) { out.push(a); continue; }
+    const name = a.slice(2, eq), value = a.slice(eq + 1);
+    problem ??= KERNEL_SWITCHES.has(name) ? `--${name} takes no value (got ${a})` : value === "" ? `--${name}= needs a value` : undefined;
+    out.push(`--${name}`, value);
+  }
+  return { argv: out, problem };
+}
+const { argv: args, problem: argvProblem } = expandInlineValues(rawArgs);
 let cmd = args[0];
 const HELP_WORDS = new Set(["help", "--help", "-h"]);
 const KERNEL_COMMANDS = new Set(["capture", "capabilities", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "update", "version", "workspace"]);
+/** Commands whose argv another parser reads (packages/record and packages/experimental parse process.argv). */
+const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental"]);
+/** Commands `--server <id>` runs on a registered server. */
+const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config"]);
 const flag = (name) => {
   const i = args.indexOf(`--${name}`);
   return i >= 0 ? (args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : true) : undefined;
@@ -154,7 +177,7 @@ function operationalKnowledgeNote(composition, soulName) {
  *  home-relative (`.oats/modules/<cap>/<inject>`), where an instance carries them. */
 async function doctorComposition(ctx, soulName, ws, bail) {
   if (!soulName) return undefined;
-  const { prepareInstance, previewWorkspaceSoul, materializePrepared, discoverOrStandalone } = await import("../lib/instance-resolution.mjs");
+  const { prepareInstance, previewWorkspaceSoul, materializePrepared, discoverOrStandalone, agentDirOf } = await import("../lib/instance-resolution.mjs");
   const deployment = dirname(ws.local.path);
   const root = join(deployment, "agents");
   const remoteOptions = remoteOptionsFromEnv();
@@ -162,11 +185,11 @@ async function doctorComposition(ctx, soulName, ws, bail) {
   // A bail exits the process without unwinding: the temporary copies are removed at exit too.
   process.once("exit", () => { for (const c of cleanups) { try { c(); } catch { /* best effort */ } } });
   try {
-    const discovery = await discoverOrStandalone(loadLocal(deployment).local, { remoteOptions });
+    const discovery = await discoverOrStandalone(loadLocal(deployment).local, { deployment, remoteOptions });
     const prepared = await prepareInstance(deployment, soulName, { remoteOptions, discovery });
     const pv = await previewWorkspaceSoul(prepared, root);
     cleanups.push(pv.cleanup);
-    const agent = findAgentAt(root, prepared.soulEntry.name, pv.soulDir);
+    const agent = findAgentAt(root, agentDirOf(prepared.soulEntry), pv.soulDir);
     if (!agent) bail("E_SOUL_UNKNOWN", `soul "${soulName}" was fetched but is not readable as a soul`);
     const composition = composeInstanceAgentsMd(pv.soulDir, deployment, agent.name, agent.work || "checkout", agent.kind, prepared);
     const scratch = realpathSync(mkdtempSync(join(tmpdir(), "oats-doctor-home-")));
@@ -1035,7 +1058,7 @@ function standaloneCatalogVersion(ref) {
 async function discoverForCli(ctx, bail) {
   // The standalone case (decisions 10/25) is a discovery too: the repo's own view
   // plus the kernel's oats.core default — discoverOrStandalone decides.
-  try { const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs"); return await discoverOrStandalone(ctx.local, { remoteOptions: ctx.remoteOptions }); }
+  try { const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs"); return await discoverOrStandalone(ctx.local, { deployment: ctx.deploymentDir, remoteOptions: ctx.remoteOptions }); }
   catch (e) {
     if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details ?? e.provenance);
     throw e;
@@ -1064,6 +1087,9 @@ function workspaceItems(discovery, lock) {
     const s = ext.soul;
     souls.push({ name: s.name, origin: `external ${s.repoKey} @ ${short(s.commit)}`, kind: "external", repoKey: s.repoKey, commit: s.commit, team: teamLabel(s.team), labels: [...(s.labels ?? (s.team ? [s.team] : []))], private: s.private, path: s.path, work: s.definition.work ?? null, description: s.definition.description ?? null });
   }
+  for (const s of discovery.packageSouls || []) {
+    souls.push({ name: s.name, qualifiedName: s.qualifiedName, origin: originOf(s), kind: "package", package: s.package, version: s.version, repoKey: s.repoKey, commit: s.commit, team: teamLabel(s.team), labels: [...(s.labels ?? [])], private: false, path: s.path, work: s.definition.work ?? null, description: s.definition.description ?? null });
+  }
   for (const [id, entry] of Object.entries(lock?.packages || {})) {
     for (const name of entry.capabilities) capabilities.push({ name, origin: originOf({ package: id, version: entry.version }), kind: "package", package: id, version: entry.version, commit: entry.commit, team: teamLabel(null), private: false });
   }
@@ -1083,7 +1109,7 @@ function memberRows(discovery) {
 
 /** Package rows for `sync` / `workspace status` from the lock. */
 function packageRows(lock) {
-  return Object.entries(lock.packages).map(([id, p]) => ({ id, version: p.version, source: p.source, commit: p.commit, integrity: p.integrity, capabilities: p.capabilities }));
+  return Object.entries(lock.packages).map(([id, p]) => ({ id, version: p.version, source: p.source, commit: p.commit, integrity: p.integrity, capabilities: p.capabilities, souls: (p.souls ?? []).map((x) => x.name) }));
 }
 
 /** Print a padded table: rows are arrays of strings. */
@@ -1124,6 +1150,17 @@ async function performSync(ctx, bail, { onDiscovered } = {}) {
   const lock = resolved.lock;
   let lockFile;
   try { lockFile = writeLock(ctx.deploymentDir, lock); } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
+  // Package souls come from the lock: list what THIS sync locked, not what the previous lock held.
+  if (discovery.standalone !== true) {
+    let pkg;
+    try { pkg = await discoverPackageSouls(discovery.workspace, lock, { remoteOptions: ctx.remoteOptions }); }
+    catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details ?? e.provenance); throw e; }
+    const kept = (list) => list.filter((p) => typeof p.package !== "string");
+    discovery.packageSouls = pkg.souls;
+    discovery.problems = [...kept(discovery.problems), ...pkg.problems];
+    discovery.warnings = workspaceWarnings(discovery.workspace, discovery.members, discovery.external || [], pkg.souls);
+    problems.splice(0, problems.length, ...kept(problems), ...pkg.problems);
+  }
   // The deployment's instance root: <deployment>/agents/ (findRoot's marker). A hand-written
   // oats-local.yaml + sync is a complete deployment; spawn must not answer E_NO_DEPLOYMENT after it.
   try { mkdirSync(join(ctx.deploymentDir, "agents"), { recursive: true }); } catch { /* reported by spawn's E_NO_DEPLOYMENT remedy if it matters */ }
@@ -1152,6 +1189,7 @@ function printSyncReport(ctx, synced) {
   const { report, discovery, items, lockFile } = synced;
   const { members, packages, changes } = report;
   const disabled = new Set(ctx.local.souls?.disabled || []);
+  const isDisabled = (s) => disabled.has(s.name) || disabled.has(s.qualifiedName ?? `${memberLabel(s.repoKey)}/${s.name}`);
   console.log(`workspace  ${discovery.workspace?.name ?? `(${standaloneNote(discovery)})`}  (${discovery.key} @ ${short(discovery.commit)})`);
   console.log(`members    ${members.map((m) => m.confirmed ? `${m.name} ✓↔ (@ ${short(m.commit)})` : `${m.name} ✗ (${m.status})`).join("   ") || "(none)"}`);
   console.log(`packages   ${packages.map((p) => `${p.id} ${p.version} ✓ (@ ${short(p.commit)})`).join("   ") || "(none)"}`);
@@ -1162,8 +1200,9 @@ function printSyncReport(ctx, synced) {
   const externalSouls = items.souls.filter((s) => s.kind === "external");
   // Souls have no private mode (0.26.0); the private count is of repo-owned member capabilities.
   const repoOwned = items.capabilities.filter((c) => c.kind === "member" && c.private);
-  const disabledHere = items.souls.filter((s) => disabled.has(s.name));
-  console.log(`souls      ${items.souls.length} discovered (${memberSouls.length} members, ${externalSouls.length} external, ${disabledHere.length} disabled here) · ${repoOwned.length} private capabilit${repoOwned.length === 1 ? "y" : "ies"}${repoOwned.length ? ` (${repoOwned.map((c) => `${c.name}, ${memberLabel(c.repoKey)} only`).join("; ")})` : ""}`);
+  const packageSouls = items.souls.filter((s) => s.kind === "package");
+  const disabledHere = items.souls.filter(isDisabled);
+  console.log(`souls      ${items.souls.length} discovered (${memberSouls.length} members, ${externalSouls.length} external, ${packageSouls.length ? `${packageSouls.length} package, ` : ""}${disabledHere.length} disabled here) · ${repoOwned.length} private capabilit${repoOwned.length === 1 ? "y" : "ies"}${repoOwned.length ? ` (${repoOwned.map((c) => `${c.name}, ${memberLabel(c.repoKey)} only`).join("; ")})` : ""}`);
   const teams = new Map();
   for (const s of items.souls) { const t = teams.get(s.team) || { souls: 0, capabilities: 0 }; t.souls++; teams.set(s.team, t); }
   for (const c of items.capabilities.filter((c) => c.kind === "member")) { const t = teams.get(c.team) || { souls: 0, capabilities: 0 }; t.capabilities++; teams.set(c.team, t); }
@@ -1294,7 +1333,7 @@ async function workspaceCmd() {
   for (const m of members.filter((m) => !m.confirmed)) console.log(`    ${m.name}: ${m.detail}`);
   console.log("\nPackages:");
   if (!packages.length) console.log(unsynced.length ? `  (none locked yet — \`oats sync\` resolves ${unsynced.join(", ")})` : "  (none)");
-  else printTable(["package", "version", "source", "commit", "capabilities"], packages.map((p) => [p.id, p.version, p.source, short(p.commit), p.capabilities.join(",")]));
+  else printTable(["package", "version", "source", "commit", "capabilities", "souls"], packages.map((p) => [p.id, p.version, p.source, short(p.commit), p.capabilities.join(","), p.souls.join(",") || "—"]));
   if (packages.length && unsynced.length) console.log(`  declared but not locked (run \`oats sync\`): ${unsynced.join(", ")}`);
   if (stale.length) console.log(`  locked but no longer declared (run \`oats sync\`): ${stale.join(", ")}`);
   if (result.external.length) console.log(`\nExternal: ${result.external.map((e) => `${e.soul} (${e.source.replace(/@([0-9a-f]{40})$/, (_, o) => `@${short(o)}`)}, ${e.team})`).join("   ")}`);
@@ -1343,7 +1382,7 @@ async function statusDrift(data) {
   const souls = new Map();
   for (const a of data) {
     if (!a.dir) continue;
-    try { const stamp = JSON.parse(readFileSync(join(a.dir, ".oats-soul-source.json"), "utf8")); if (stamp && typeof stamp.repoKey === "string") souls.set(a.name, { repoKey: stamp.repoKey, commit: typeof stamp.commit === "string" ? stamp.commit : null, path: stamp.path ?? null }); }
+    try { const stamp = JSON.parse(readFileSync(join(a.dir, ".oats-soul-source.json"), "utf8")); if (stamp && typeof stamp.repoKey === "string") souls.set(a.name, { repoKey: stamp.repoKey, commit: typeof stamp.commit === "string" ? stamp.commit : null, path: stamp.path ?? null, ...(typeof stamp.package === "string" ? { package: stamp.package, version: stamp.version ?? null } : {}) }); }
     catch { /* not a workspace soul (classic, capability agent, or unreadable stamp) */ }
   }
   const anything = data.some((a) => (a.instances || []).some((i) => hasModules(i) || hasSoul(i)));
@@ -1354,7 +1393,7 @@ async function statusDrift(data) {
   let discovery;
   // The standalone view (decisions 10/25) is a discovery too: drift of a standalone
   // instance is computed against its member's current state, not reported "unreachable".
-  try { const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs"); discovery = await discoverOrStandalone(ctx.local, { remoteOptions: remoteOptionsFromEnv() }); }
+  try { const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs"); discovery = await discoverOrStandalone(ctx.local, { lock, remoteOptions: remoteOptionsFromEnv() }); }
   catch (e) {
     const reason = e?.details?.reason ? `${e.code}: ${e.details.reason}` : (e?.code || e?.message || "unknown");
     return { drift: new Map(), soul: new Map(), souls, unreachable: { code: e?.code ?? null, reason, message: e?.message ?? String(e) } };
@@ -1369,6 +1408,7 @@ async function statusDrift(data) {
   }
   // The roster's soul row reflects the CURRENT member commit too (the pointer may lag a moved member).
   for (const [, stamp] of souls) {
+    if (typeof stamp.package === "string") { const now = (discovery.packageSouls || []).find((p) => p.package === stamp.package && p.path === stamp.path); if (now) stamp.current = now.commit; continue; }
     const member = discovery.members.find((m) => m && m.key === stamp.repoKey);
     if (member && typeof member.commit === "string" && (member.confirmed || (discovery.standalone === true && member.key === discovery.key))) stamp.current = member.commit;
   }
@@ -1385,6 +1425,12 @@ function driftLine(row) {
 }
 /** The `soul:` line of an instance — decision 17 for the soul source. */
 function soulDriftLine(row, agentName) {
+  if (row.package) {
+    const base = `soul: ${row.name ?? agentName} from package ${row.package} v${row.version} @ ${short7(row.commit)}`;
+    if (row.status === "moved") return `${base}  [package moved since (now v${row.current?.version} @ ${short7(row.current?.commit)})]`;
+    if (row.status === "missing") return `${base}  [${row.reason === "soul-absent" ? "soul no longer shipped by the package" : "package no longer locked"}]`;
+    return base;
+  }
   const base = `soul: ${row.name ?? agentName} from ${memberLabel(row.repoKey)} @ ${short7(row.commit)}`;
   if (row.status === "moved") return `${base}  [member moved since (now @ ${short7(row.current?.commit)})]`;
   if (row.status === "missing") return `${base}  [${row.reason === "soul-absent" ? "soul no longer present" : `member ${row.reason || "unconfirmed"}`}]`;
@@ -1394,6 +1440,7 @@ function soulDriftLine(row, agentName) {
 function soulRepoLabel(a, ws) {
   const stamp = ws?.souls?.get(a.name);
   if (!stamp) return a.repo || "?";
+  if (typeof stamp.package === "string") return `package ${stamp.package} v${stamp.version} @ ${short7(stamp.commit)}`;
   const moved = stamp.current && stamp.commit && stamp.current !== stamp.commit ? ` (member now @ ${short7(stamp.current)})` : "";
   return `${memberLabel(stamp.repoKey)} @ ${short7(stamp.commit)}${moved}`;
 }
@@ -1417,7 +1464,7 @@ async function status() {
         const rows = ws.drift.get(key);
         if (rows) i.modules = rows.map((r) => ({ name: r.module, from: r.from, commit: r.recorded?.commit ?? null, current: r.current, status: r.status, ...(r.reason ? { reason: r.reason } : {}) }));
         const s = ws.soul.get(key);
-        if (s) i.soul = { repoKey: s.repoKey, commit: s.commit, current: s.current?.commit ?? null, status: s.status, ...(s.reason ? { reason: s.reason } : {}) };
+        if (s) i.soul = { repoKey: s.repoKey, commit: s.commit, current: s.current?.commit ?? null, status: s.status, ...(s.reason ? { reason: s.reason } : {}), ...(s.package ? { package: s.package, version: s.version, currentVersion: s.current?.version ?? null } : {}) };
       }
     }
     console.log(JSON.stringify({ root, agents: data, ...(ws ? { workspace: ws.unreachable ? { reachable: false, ...ws.unreachable } : { reachable: true } } : {}), ...(problems.length ? { problems } : {}), ...envelopeWarnings() }, null, 2)); return;
@@ -1503,12 +1550,12 @@ async function spawnCmd() {
   {
     let discovery = null;
     try {
-      const { prepareInstance, ensureWorkspaceSoul, previewWorkspaceSoul, parseProviderFlags, discoverOrStandalone } = await import("../lib/instance-resolution.mjs");
+      const { prepareInstance, ensureWorkspaceSoul, previewWorkspaceSoul, parseProviderFlags, discoverOrStandalone, agentDirOf } = await import("../lib/instance-resolution.mjs");
       const remoteOptions = remoteOptionsFromEnv();
-      const { local } = loadLocal(dirFlag());
-      discovery = wsDiscovery = await discoverOrStandalone(local, { remoteOptions });
+      const { local, path: localPath } = loadLocal(dirFlag());
+      discovery = wsDiscovery = await discoverOrStandalone(local, { deployment: dirname(localPath), remoteOptions });
       wsPrepared = await prepareInstance(dirFlag(), name, { spawn: { providers: parseProviderFlags(providerPairs) }, remoteOptions, discovery });
-      const soulName = wsPrepared.soulEntry.name;
+      const soulName = agentDirOf(wsPrepared.soulEntry);
       let soulDir;
       if (isPreview) {
         // A preview writes nothing in the deployment: the soul comes from the
@@ -1616,6 +1663,17 @@ async function spawnCmd() {
   const taskFileFlag = flag("task-file");
   if (taskFileFlag === true) bail("E_BAD_ARGS", "--task-file needs a path");
   if (taskFileFlag && !existsSync(taskFileFlag)) bail("E_BAD_ARGS", `--task-file not found: ${taskFileFlag}`);
+  // --trigger-event <file>: the event a trigger spawns this instance for (lib/triggers.mjs). It is
+  // copied to <home>/.oats/trigger-event.json (OATS_TRIGGER_EVENT_FILE) and recorded as instance.json.trigger.
+  let triggerEvent;
+  { const f = flag("trigger-event");
+    if (f === true) bail("E_BAD_ARGS", "--trigger-event needs a path");
+    if (f !== undefined) {
+      if (!existsSync(f)) bail("E_BAD_ARGS", `--trigger-event not found: ${f}`);
+      try { triggerEvent = JSON.parse(readFileSync(f, "utf8")); } catch (e) { bail("E_BAD_ARGS", `--trigger-event is not valid JSON: ${e.message}`); }
+      const ok = triggerEvent && typeof triggerEvent === "object" && !Array.isArray(triggerEvent) && typeof triggerEvent.trigger === "string" && typeof triggerEvent.source === "string" && typeof triggerEvent.repo === "string" && Number.isInteger(triggerEvent.number) && typeof triggerEvent.event === "string";
+      if (!ok) bail("E_BAD_ARGS", "--trigger-event must hold { trigger, source, repo, number, url, event, headSha, labels, observedAt }");
+    } }
   const relativeRoot = flag("relative-root");
   if (relativeRoot !== undefined && (relativeRoot === true || !String(relativeRoot).trim())) bail("E_BAD_ARGS", "--relative-root needs an agents-root path");
   if (relativeRoot && !relativeTo) bail("E_BAD_ARGS", "--relative-root only qualifies --relative-to/--parent");
@@ -1684,6 +1742,7 @@ async function spawnCmd() {
       work: requestedWork, workDir, harness: harnessFlag(), backend, herdrSocket, yolo, model: flag("model"), branch,
       launchConfig: valueFlag("launch-config"),
       launch: !args.includes("--no-launch"),
+      ...(triggerEvent ? { triggerEvent } : {}),
       // K6: --preview decides everything and touches nothing; --base <ref>
       // selects a worktree's start point; --model @native-default is the
       // explicit "harness's own default" (distinct from omitting --model).
@@ -1897,7 +1956,7 @@ function scheduleCmd() {
   const needId = () => { if (!id) throw scheduleError("E_BAD_ARGS", `oats schedule ${sub} <id>`); return id; };
   try {
     switch (sub) {
-      case "list": return out(listSchedules(ws(), io));
+      case "list": { const r = listSchedules(ws(), io); out(r); if (!JSON_MODE && r.triggers.count) console.log(`${r.triggers.count} trigger${r.triggers.count === 1 ? " is" : "s are"} not listed here: ${r.triggers.command}`); return; }
       case "show": return out({ schedule: describeSchedule(ws(), needId(), io) });
       case "add": { const spec = readSpec(); if (id && spec.id === undefined) spec.id = id; if (id && spec.id !== id) throw scheduleError("E_SCHEDULE_INVALID", `id ${JSON.stringify(spec.id)} in the file does not match ${JSON.stringify(id)}`, { field: "id" }); return out({ schedule: addSchedule(ws(), spec, io) }); }
       case "update": return out({ schedule: updateSchedule(ws(), needId(), readSpec(), io) });
@@ -1910,7 +1969,7 @@ function scheduleCmd() {
         const dryRun = args.includes("--dry-run");
         if (args.includes("--host")) return out(tickHost({ io, dryRun }));
         const reg = readRegistry();
-        const considered = withHostLock(() => tickWorkspace(ws(), { io, reg, wsList: reg.workspaces.includes(ws()) ? reg.workspaces : [...reg.workspaces, ws()], dryRun }));
+        const considered = withHostLock(() => [...tickWorkspace(ws(), { io, reg, wsList: reg.workspaces.includes(ws()) ? reg.workspaces : [...reg.workspaces, ws()], dryRun }), ...tickTriggers(ws(), { io, dryRun })]);
         return out({ tickedAt: new Date().toISOString(), considered, scheduler: schedulerStatus(ws(), io) });
       }
       case "host": {
@@ -1929,6 +1988,98 @@ function scheduleCmd() {
   }
 }
 
+/** `oats trigger …` (lib/triggers.mjs): event-driven spawns stored beside the schedules of the
+ *  deployment scope and evaluated by the same host tick. Every subcommand answers the envelope. */
+async function triggerCmd() {
+  const sub = args[1];
+  const id = args[2] && !args[2].startsWith("--") ? args[2] : undefined;
+  const T = await import("../lib/triggers.mjs");
+  let scope;
+  const ws = () => (scope ??= scheduleScopeOf(dirFlag()));
+  const out = (result, text) => { if (JSON_MODE) jsonOk(result); else console.log(text ? text(result) : JSON.stringify(result, null, 2)); };
+  const needId = () => { if (!id) throw T.triggerError("E_BAD_ARGS", `oats trigger ${sub} <id>`); return id; };
+  const usage = "usage: oats trigger add (--file <trigger.json> | --from <package>:<template> [--set <name>=<value>]… [--id <id>]) | list | show <id> | enable <id> | disable <id> | remove <id> | test <id> | status [<id>]  [--dir <deployment>] [--json]";
+  const line = (t) => `${t.id}  ${t.enabled ? "enabled " : "disabled"}  ${t.on?.source ?? "?"} ${t.on?.repo ?? "?"} [${(t.on?.events || []).join(",")}]${t.on?.labels?.length ? ` labels ${t.on.labels.join(",")}` : ""} every ${t.on?.poll ?? "?"} → spawn ${t.spawn?.soul ?? "?"}${t.spawn?.teams?.length ? ` in ${t.spawn.teams.join(",")}` : ""}${t.invalid ? `  INVALID: ${t.invalid.message}` : ""}`;
+  try {
+    switch (sub) {
+      case "list": return out(T.listTriggers(ws()), (r) => r.triggers.length ? r.triggers.map(line).join("\n") : "(no triggers — oats trigger add --file <trigger.json> | --from <package>:<template>)");
+      case "show": return out({ trigger: T.describeTrigger(ws(), needId()) });
+      case "enable": return out({ trigger: T.setTriggerEnabled(ws(), needId(), true) }, (r) => line(r.trigger));
+      case "disable": return out({ trigger: T.setTriggerEnabled(ws(), needId(), false) }, (r) => line(r.trigger));
+      case "remove": return out(T.removeTrigger(ws(), needId()), (r) => `removed trigger ${r.removed}${r.live.length ? ` (its live instances keep running: ${r.live.join(", ")})` : ""}`);
+      case "status": return out(T.triggerStatus(ws(), id), (r) => r.triggers.map((t) => `${t.id}  last poll ${t.lastPoll ? `${t.lastPoll.at} ${t.lastPoll.ok ? `ok (${t.lastPoll.matching}/${t.lastPoll.prs} PRs match)` : `FAILED: ${t.lastPoll.error}`}` : "never"}  pending ${t.pending.length}  fired ${t.firedTotal}  live ${t.live.map((l) => l.instance).join(",") || "none"}${t.lastError ? `\n    last error ${t.lastError.at}: ${t.lastError.message}` : ""}`).join("\n") || "(no triggers)");
+      case "test": {
+        let workspaceTeams = null;
+        try {
+          const { observeWorkspace } = await import("../lib/workspace.mjs");
+          const { local } = loadLocal(ws());
+          if (typeof local.workspace === "string") workspaceTeams = Object.keys((await observeWorkspace(local.workspace, { remoteOptions: remoteOptionsFromEnv() })).workspace.teams || {});
+        } catch { /* reported as unknown (null) */ }
+        return out(T.testTrigger(ws(), needId(), { workspaceTeams }), (r) => [
+          `trigger ${r.id}: ${r.ok ? "ready" : "NOT ready"} (nothing was spawned)`,
+          `  gh auth    ${r.gh.ok ? `ok — ${r.gh.account ?? "?"} via ${r.gh.credentialSource}` : `FAILED${r.gh.detail ? ` — ${r.gh.detail}` : ""}`}`,
+          `  repo       ${r.repo.key} ${r.repo.readable ? `readable; push ${r.repo.permissions.push} maintain ${r.repo.permissions.maintain} admin ${r.repo.permissions.admin}` : `NOT readable: ${r.repo.error}`}`,
+          `  soul       ${r.soul.name} ${r.soul.resolves ? `resolves${r.soul.messaging ? ` (messaging ${r.soul.messaging})` : ""}` : `does NOT resolve: ${r.soul.error.code} ${r.soul.error.message}`}`,
+          `  teams      ${r.teams.requested.join(", ") || "(none)"}${r.teams.undeclared?.length ? `  undeclared: ${r.teams.undeclared.join(", ")}` : ""}`,
+          `  would fire ${r.wouldFire.length ? r.wouldFire.map((w) => `${w.event} #${w.number}${w.held ? ` (held: ${w.held})` : ""}`).join(", ") : "nothing now"}`,
+          ...r.problems.map((p) => `  problem    ${p}`),
+          ...(r.warnings ?? []).map((w) => `  warning    ${w}`),
+        ].join("\n"));
+      }
+      case "add": {
+        const file = flag("file"), from = flag("from");
+        if ((file === undefined) === (from === undefined)) throw T.triggerError("E_BAD_ARGS", `oats trigger add needs exactly one of --file <trigger.json> or --from <package>:<template>\n${usage}`);
+        const sets = {};
+        for (let i = 0; i < args.length; i++) if (args[i] === "--set") {
+          const kv = args[i + 1];
+          if (typeof kv !== "string" || !kv.includes("=")) throw T.triggerError("E_BAD_ARGS", "--set needs <name>=<value>");
+          sets[kv.slice(0, kv.indexOf("="))] = kv.slice(kv.indexOf("=") + 1); i++;
+        }
+        const idFlag = flag("id");
+        if (idFlag === true) throw T.triggerError("E_BAD_ARGS", "--id needs a trigger id");
+        let spec;
+        if (file !== undefined) {
+          if (file === true || !existsSync(file)) throw T.triggerError("E_BAD_ARGS", `--file ${file === true ? "needs a path" : `not found: ${file}`}`);
+          if (Object.keys(sets).length) throw T.triggerError("E_BAD_ARGS", "--set fills a package template's parameters; with --file, edit the file");
+          try { spec = JSON.parse(readFileSync(file, "utf8")); } catch (e) { throw T.triggerError("E_TRIGGER_INVALID", `${file} is not valid JSON: ${e.message}`, { details: { field: "file" } }); }
+          if (idFlag !== undefined) spec.id = idFlag;
+        } else spec = await triggerFromPackage(T, String(from), sets, idFlag);
+        return out({ trigger: T.addTrigger(ws(), spec) }, (r) => `added ${line(r.trigger)}\n(\`oats trigger test ${r.trigger.id}\` checks gh, the repository, the soul and the teams on this host)`);
+      }
+      default: throw T.triggerError("E_BAD_ARGS", usage);
+    }
+  } catch (e) {
+    const details = { ...(e.details && typeof e.details === "object" ? e.details : {}), ...(e.field !== undefined ? { field: e.field } : {}) };
+    if (JSON_MODE) jsonFail(e.code || "E_TRIGGER_FAILED", e.message, Object.keys(details).length ? details : undefined); else die(e.message);
+  }
+}
+/** A package trigger template (`triggers: [{ id, file }]` in the locked package's oats-package.json),
+ *  read at the lock's commit and instantiated with the --set parameters. */
+async function triggerFromPackage(T, from, sets, idFlag) {
+  const m = /^([a-z0-9][a-z0-9._-]*):([a-z0-9][a-z0-9._-]*)$/.exec(from);
+  if (!m) throw T.triggerError("E_BAD_ARGS", `--from ${JSON.stringify(from)}: write <package>:<template>, e.g. oats.okf:harvest-review`);
+  const [, pkg, template] = m;
+  const deployment = scheduleScopeOf(dirFlag());
+  const lock = readLock(deployment);
+  const entry = lock.packages[pkg];
+  if (!entry) throw T.triggerError("E_PACKAGE_MISSING", `package ${pkg} is not in ${LOCK_FILE} — declare it in packages: and run \`oats sync\``, { details: { package: pkg } });
+  const { lockedPackageRef, bindRemote } = await import("../lib/packages.mjs");
+  const ref = lockedPackageRef(entry);
+  const remote = bindRemote(remoteModule, remoteOptionsFromEnv());
+  const read = async (rel, what) => {
+    let bytes;
+    try { ({ bytes } = await remote.readRemoteFile(ref, entry.commit, `${entry.path}/${rel}`)); }
+    catch (e) { throw T.triggerError(e?.code === "E_REMOTE_PATH_MISSING" ? "E_PACKAGE_MANIFEST" : (e?.code || "E_REMOTE_UNREADABLE"), `${pkg} v${entry.version}: ${what} ${entry.path}/${rel} cannot be read: ${e.message}`, { details: { package: pkg, path: rel } }); }
+    try { return JSON.parse(Buffer.from(bytes).toString("utf8")); } catch (e) { throw T.triggerError("E_PACKAGE_MANIFEST", `${pkg} v${entry.version}: ${what} ${entry.path}/${rel} is not valid JSON: ${e.message}`, { details: { package: pkg, path: rel } }); }
+  };
+  const manifest = await read("oats-package.json", "the package manifest");
+  const listed = Array.isArray(manifest.triggers) ? manifest.triggers : [];
+  const row = listed.find((t) => t && t.id === template);
+  if (!row || typeof row.file !== "string" || !row.file || row.file.split("/").includes("..") || row.file.startsWith("/")) throw T.triggerError("E_TRIGGER_UNKNOWN", `package ${pkg} v${entry.version} has no trigger template ${JSON.stringify(template)} (templates: ${listed.map((t) => t?.id).filter(Boolean).join(", ") || "none"})`, { details: { package: pkg, template, templates: listed.map((t) => t?.id).filter(Boolean) } });
+  const doc = await read(row.file, `trigger template ${template}`);
+  return T.instantiateTemplate(doc, sets, { id: idFlag, provenance: { package: pkg, version: entry.version, commit: entry.commit, template } });
+}
+
 async function sessionCmd() {
   try {
     if (flag("native-record") !== undefined) throw Object.assign(new Error("--native-record outcome inspection is gone (the captured/portable path was removed in 0.26)"), { code: "E_BAD_ARGS" });
@@ -2279,7 +2430,7 @@ async function capabilityCommand() {
     // OATS_SOUL is the recorded soul or nothing: an ambient value inherited from the
     // invoking process names some other soul (a coordinator's own), never this one.
     const { OATS_SOUL: _ambientSoul, ...inherited } = process.env;
-    const r = spawnSync("node", [abs, ...rest, ...args.slice(2)], { stdio: "inherit", env: {
+    const r = spawnSync("node", [abs, ...rest, ...rawArgs.slice(2)], { stdio: "inherit", env: {
       ...inherited, OATS_CAPABILITY: m.capability,
       // Package-runtime boundary: dispatched commands receive the active
       // capability's EFFECTIVE settings (instance snapshot, resolved context, or
@@ -2356,7 +2507,7 @@ function versionCmd() {
     // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
     // runs on resolve/materialize (contract §6); a feature the binary does not implement is
     // never listed.
-    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "teams", "settings-declared", "capabilities-private", "layers-from", "harness"], workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2 }));
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "teams", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers"], workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2 }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -2495,7 +2646,7 @@ async function serverRouteCmd() {
   // so its explicit --dir travels; every other routed command takes its
   // scope from the registration.
   const explicitScopeOk = ["inspect", "operation", "launch-config"].includes(cmd);
-  if (!explicitScopeOk && (flag("dir") !== undefined || args.some((a) => a.startsWith("--dir=")))) bail("E_BAD_ARGS", "--dir cannot be combined with --server: the remote workspace comes from the server registration");
+  if (!explicitScopeOk && flag("dir") !== undefined) bail("E_BAD_ARGS", "--dir cannot be combined with --server: the remote workspace comes from the server registration");
   if (cmd === "launch-config") {
     const action = args[1];
     const value = (name) => { const v = flag(name); if (v === true) bail("E_BAD_ARGS", `--${name} needs a value`); return v; };
@@ -2715,13 +2866,16 @@ try {
 // resolved against the current context instead. `version` answers regardless:
 // host protocol negotiation describes this executable.
 {
+  // The kernel's own argv only: a capability command's flags are its provider's to parse.
+  const kernelArgv = (KERNEL_COMMANDS.has(cmd) && !OWN_ARGV_COMMANDS.has(cmd)) || (ROUTED_COMMANDS.has(cmd) && flag("server") !== undefined);
+  if (argvProblem && kernelArgv) cmdFail("E_BAD_ARGS", argvProblem);
   const end = args.indexOf("--"), head = end < 0 ? args : args.slice(0, end);
-  const selector = head.find((a) => /^--(deployment|resolution|artifact-set)(=|$)/.test(a));
+  const selector = head.find((a) => /^--(deployment|resolution|artifact-set)$/.test(a));
   const refuse = (message, details) => { if (JSON_MODE) jsonFail("E_UNSUPPORTED_MODE", message, details); die(message); };
-  if (selector) refuse(`${selector.split("=")[0]}: a captured selector is refused (the captured/portable path was removed in 0.26); run the command in its workspace deployment or instance home instead`, { selector: selector.split("=")[0] });
+  if (selector) refuse(`${selector}: a captured selector is refused (the captured/portable path was removed in 0.26); run the command in its workspace deployment or instance home instead`, { selector });
   const inherited = ["OATS_RESOLUTION", "OATS_DEPLOYMENT"].filter((k) => process.env[k]);
   if (inherited.length && cmd !== "version") refuse(`this environment carries a captured context (${inherited.join(", ")}): the captured/portable path was removed in 0.26, and nothing is run against the current context in its place — retire the captured home and re-spawn it from the deployment`, { inherited });
-  if (cmd === "inspect" && head.some((a) => a === "--request" || a.startsWith("--request="))) {
+  if (cmd === "inspect" && head.includes("--request")) {
     const message = "oats inspect --request (portable onboarding inspection) is gone (the captured/portable path was removed in 0.26); use `oats onboard` / `oats sync` to set up a workspace and `oats spawn <soul> --preview` to see what a spawn would resolve";
     if (JSON_MODE) jsonFail("E_UNKNOWN_COMMAND", message, { removed: "inspect --request", replacement: "oats onboard / oats sync; oats spawn --preview" });
     die(message);
@@ -2738,7 +2892,7 @@ else {
 // `okf harvest --help` spawned a harvester (BeadHub, 2026-09-05).
 const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
 if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); process.exit(0); } usageFor(cmd); process.exit(0); }
-if (flag("server") !== undefined && ["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config"].includes(cmd)) await serverRouteCmd();
+if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
 else if (cmd === "server") serverCmd();
 else if (cmd === "inspect") await inspectCmd();
 else if (cmd === "operation") await operationCmd();
@@ -2768,6 +2922,7 @@ else if (cmd === "version" || cmd === "--version" || cmd === "-v") versionCmd();
 // through the shared boundary, never re-badged as a spawn-mechanism failure.
 else if (cmd === "session") await sessionCmd();
 else if (cmd === "schedule") scheduleCmd();
+else if (cmd === "trigger") await triggerCmd();
 else if (cmd === "spawn") { try { await spawnCmd(); } catch (e) { if (TYPED_CLI_FAILURES.has(e?.code)) throw e; if (JSON_MODE) jsonFail("E_SPAWN_FAILED", e.message || e); throw e; } }
 else if (cmd === "retire") retireCmd();
 else if (cmd === "capture" || cmd === "recall" || cmd === "setup") await recordCmd(cmd);
@@ -2861,6 +3016,10 @@ Usage:
       tick [--dry-run] [--host]                  command or wake jobs on a five-field cron with an
       host install|uninstall|status              explicit IANA tz; see docs/schedules.md); --server
                                                 routes to that host's workspace
+  oats trigger add (--file <json> | --from <package>:<template> [--set k=v]) | list | show | enable
+      | disable | remove <id> | test <id> | status [<id>]   event-driven spawns (github.pull_request
+                                                polled with the host's gh by the schedule tick;
+                                                see docs/schedules.md#triggers)
   oats spawn ... --wake-file <json> | --wake-every <N> --wake-message <text>  save a wake schedule
                                                 bound to the new instance's home (docs/schedules.md)
   oats session upload --file <path>          store a copy of a local file as a private attachment

package/capabilities/oats-okf/agents/memory-harvest/AGENTS.md

@@ -10,9 +10,14 @@ worktree, or write accepted bases directly. Only the listed owned nodes and
 base navigation are editable. Read other nodes as context.
 
 You are a service: no STATE.md/log.md/notes upkeep and no recursive capture.
-The working-agent read-only injection below applies to ordinary sources, not
-to the explicitly listed STAGED roots in your task. Accepted bases remain
-read-only even for you: the completion command performs provider publication.
+No okf injection is composed for you (capability agents get none), so the
+working-agent consultation protocol does not apply to you. Judge and edit the
+owned nodes from your STAGED roots in ./work (listed in staging.json). Do NOT
+use `oats okf index`, `cat` or `search` for those nodes: they serve the
+accepted state, not your staging, and would hide the changes you are judging.
+Use them, if at all, only for read-only context from nodes you do not edit.
+Accepted bases remain read-only even for you: the completion command performs
+provider publication.
 
 Write the explicit judgment receipt, call the task's safely quoted completion
 command, and inspect its result. A failed/uncertain command is NOT success:

package/capabilities/oats-okf/bin/oats-okf.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { randomUUID } from 'node:crypto';
-import { fs, join, dirname, resolve, readJSON, save, safePath, cliPath, oats, fail, unlock } from '../lib/io.mjs';
-import { loadBindings, declaration, splitRef } from '../lib/config.mjs';
-import { register, registerCaptured, loadInvocationSourceReceipt, homeSource, loadSource, loadStatus, saveStatus, updateStatus, capture, scheduleSource, settleRetiredSchedule, service, markerPath, views } from '../lib/sources.mjs';
+import { fs, join, resolve, readJSON, safePath, oats, fail, unlock } from '../lib/io.mjs';
+import { loadBindings } from '../lib/config.mjs';
+import { register, registerCaptured, loadInvocationSourceReceipt, homeSource, loadSource, loadStatus, saveStatus, updateStatus, capture, scheduleSource, settleRetiredSchedule, service, markerPath } from '../lib/sources.mjs';
+import { CONSULT } from '../lib/consult.mjs';
 import { runSource, complete, retry, readRun, requireQualifiedHelper } from '../lib/worker.mjs';
 import { initBase, migrate, deliverMigration, cutoverMigration, migrateSource, forgetMigration } from '../lib/migration.mjs';
 import { inspect } from '../lib/inspection.mjs';
@@ -13,8 +13,16 @@ oats okf harvest [--home PATH] [--no-launch] [--json]
 oats okf run-source --source FILE [--manual] [--no-launch] [--json]
 oats okf complete --source FILE --run ID --judgment FILE [--json]
 oats okf retry --source FILE [--run ID --rejudge | --rejudge | --launch | --adopt-home PATH] [--json]
-oats okf read [--home PATH | --source FILE] --base ALIAS [--path node/index.md] [--json]
-oats okf refresh [--home PATH | --source FILE] [--json]
+oats okf bases [--fresh] [--json]
+oats okf index [--base ALIAS] [NODE | ALIAS/NODE] [--fresh] [--json]
+oats okf cat --base ALIAS PATH [--from PATH] [--fresh] [--json]
+oats okf ls --base ALIAS [DIR] [--fresh] [--json]
+oats okf links --base ALIAS PATH [--fresh] [--json]
+oats okf search [--base ALIAS | --all] [--node NODE] [--regex] [--case-sensitive] TEXT [--fresh] [--json]
+oats okf read --base ALIAS [--path node/index.md] [--json]   (2.x alias of cat)
+Consult commands read the accepted state remotely (host cache, no local copy);
+also accept --home PATH | --source FILE. PATH is /node/x.md from the base root,
+relative to --from's directory, or bare node/x.md from the root.
 oats okf setup --source FILE [--enable | --disable] [--install-host] [--json]
 oats okf init --base ALIAS --nodes FILE [--output PATH | --confirm] [--json]
 oats okf migrate --legacy PATH --base ALIAS --node NODE --output PATH [--json]
@@ -36,11 +44,13 @@ if(args.includes('--help') || args.includes('-h')) {process.stdout.write(HELP);}
 else {
   const event=process.env.OATS_EVENT || args[0];
   const hook=['spawn','retire','soul-scaffold'].includes(event);
-  let exit=0,answer;
+  const consult=Object.hasOwn(CONSULT,event);
+  let exit=0,answer,text,textMode=consult && !args.includes('--json');
   try {
-    const flags={}; const boolean=new Set(['json','no-launch','manual','rejudge','launch','enable','disable','install-host','confirm']);
+    const flags={},positionals=[]; const boolean=new Set(['json','no-launch','manual','rejudge','launch','enable','disable','install-host','confirm','fresh','all','regex','case-sensitive']);
     for(let i=1;i<args.length;i++) {
-      if(!args[i].startsWith('--')) fail('E_USAGE',`unexpected argument ${args[i]}`);
+      if(consult && args[i]==='--') {positionals.push(...args.slice(i+1));break;}
+      if(!args[i].startsWith('--')) {if(!consult || event==='read') fail('E_USAGE',`unexpected argument ${args[i]}`);positionals.push(args[i]);continue;}
       const k=args[i].slice(2);if(k in flags) fail('E_USAGE',`duplicate --${k}`);
       if(boolean.has(k)) flags[k]=true;
       else {if(!args[i+1] || args[i+1].startsWith('--')) fail('E_USAGE',`--${k} needs a value`);flags[k]=args[++i];}
@@ -49,7 +59,9 @@ else {
       spawn:[],retire:['home'], 'soul-scaffold':[],
       harvest:['home','no-launch','native-request','worker-mode'],inspect:['home','source'],
       'run-source':['source','manual','no-launch'],complete:['source','run','judgment'],
-      retry:['source','run','rejudge','launch','adopt-home'],read:['home','source','base','path'],refresh:['home','source'],
+      retry:['source','run','rejudge','launch','adopt-home'],read:['home','source','base','path','fresh'],refresh:['home','source'],
+      bases:['home','source','fresh'],index:['home','source','base','fresh'],cat:['home','source','base','from','fresh'],ls:['home','source','base','fresh'],
+      links:['home','source','base','fresh'],search:['home','source','base','all','node','regex','case-sensitive','fresh'],
       setup:['source','enable','disable','install-host'],init:['base','nodes','output','confirm'],
       migrate:['source-home','legacy','base','node','output','deliver','cutover','soul-dir'],unlock:['lock','token']
     };
@@ -107,7 +119,9 @@ else {
       readRun(s,id);return s;
     };
     let result;
-    if(event==='soul-scaffold') {
+    if(consult) {const answer=CONSULT[event](src(),flags,positionals);result=answer.result;text=answer.text;}
+    else if(event==='refresh') fail('E_REMOVED','okf 3.0.0 has no per-instance views; index/cat always read the accepted state: run `oats okf index`, then `oats okf cat --base ALIAS PATH`');
+    else if(event==='soul-scaffold') {
       // Souls are portable declarations, never an implicit knowledge store.
       result={meta:{scaffolded:false},brief:'OKF requires explicit external bindings and soul/okf.json before a working instance can spawn. Use init or migrate; no knowledge was created in this soul.'};
     } else if(event==='spawn') {
@@ -115,7 +129,8 @@ else {
       if(s.skipped) result={meta:{memory:'none'},brief:'Service agent: follow your own task; no working-memory upkeep.'};
       else {
         const schedule=loadStatus(s).schedule.result;
-        result={meta:{memory:'okf-v2',source:s.file,schedule},brief:`Knowledge is an immutable accepted snapshot at ./knowledge/. Read knowledge/view.json for base paths under knowledge/bases/<alias>/, then the indexes for ${[...new Set([...s.decl.owns,...s.decl.reads])].join(', ')}. Follow only relevant links. All configured bases are available. Use oats okf read for current accepted text; old views stay stable. Keep STATE.md/log.md/notes/ current; never edit knowledge.`};
+        const nodes=(list)=>list.join(', ') || 'none';
+        result={meta:{memory:'okf-v2',source:s.file,schedule},brief:`Your knowledge is read remotely at its accepted state; there is no local copy. Start every task with \`oats okf index\` (owns: ${nodes(s.decl.owns)}; reads: ${nodes(s.decl.reads.filter(r=>!s.decl.owns.includes(r)))}), then \`oats okf cat --base ALIAS PATH\` for the concepts the task needs; \`oats okf search\` before re-deriving a decision. Load the okf-consultation skill for the procedure. Keep STATE.md/log.md/notes/ current; never edit knowledge.`};
       }
     } else if(event==='retire') {
       if(captured) {
@@ -151,20 +166,6 @@ else {
       if(flags.enable || flags.disable) {oats(['schedule',flags.enable?'enable':'disable',`okf-${s.id}`,'--dir',s.context,'--json'],s.context);updateStatus(s,current=>{current.auto=!!flags.enable;});}
       if(flags['install-host']) oats(['schedule','host','install','--dir',s.context,'--json'],s.context);
       result={source:s.file,scheduler:oats(['schedule','list','--dir',s.context,'--json'],s.context).scheduler};
-    } else if(event==='read' || event==='refresh') {
-      const s=src();
-      // A descriptor-selected read is independent of any invoking/source home.
-      // In particular, retired sources must not leave caches in context/repo.
-      const target=join(flags.source?join(dirname(s.file),'views'):home,`knowledge-view-${randomUUID()}`);
-      const receipts=views(s.bindings,s.decl,target);
-      if(event==='refresh') result={path:target,receipts};
-      else {
-        if(!Object.hasOwn(s.bindings.bases,flags.base || '')) fail('E_CONFIG','unknown --base');
-        const basePath=join(target,receipts[flags.base].path);
-        const p=safePath(join(basePath,flags.path || 'index.md'));
-        if(!p.startsWith(basePath+'/') || !p.endsWith('.md')) fail('E_PATH','read only contained Markdown');
-        result={path:p,text:fs.readFileSync(p,'utf8'),receipt:receipts[flags.base]};
-      }
     } else if(event==='init') result=initBase(loadBindings(),flags.base,flags.nodes,flags.output,{confirm:!!flags.confirm});
     else if(event==='migrate') {
       if(flags['source-home']) result=migrateSource(loadBindings(),flags['source-home']);
@@ -176,6 +177,10 @@ else {
     else fail('E_USAGE',`unknown command ${event}; see --help`);
     answer=hook?result:{schemaVersion:1,ok:true,result};
   } catch(e) {const code=e.code || 'E_OKF';exit=1;answer=hook?{meta:{...(event==='retire'?{retired:false,reason:e.message}:{})},warning:`oats-okf ${code}: ${e.message}`}:{schemaVersion:1,ok:false,error:{code,message:e.message}};}
-  // Let Node drain the pipe; no process.exit after a possibly large view.
-  process.stdout.write(JSON.stringify(answer)+'\n');process.exitCode=exit;
+  // Consult commands print text unless --json; every other answer is JSON.
+  // Let Node drain the pipe; no process.exit after a possibly large answer.
+  if(textMode && exit) process.stderr.write(`oats okf ${event}: ${answer.error.code}: ${answer.error.message}\n`);
+  else if(textMode) process.stdout.write(text+'\n');
+  else process.stdout.write(JSON.stringify(answer)+'\n');
+  process.exitCode=exit;
 }