@awebai/oats 0.69.5 → 0.69.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/bin/oats.mjs +78 -320
  2. package/docs/design/2026-09-26-okf-knowledge-operations.md +2 -0
  3. package/docs/design/2026-10-29-warm-reader.md +261 -0
  4. package/docs/design/README.md +4 -0
  5. package/docs/desktop-cli-api.md +250 -12
  6. package/docs/execution-targets.md +11 -2
  7. package/docs/implementation.md +26 -8
  8. package/docs/integrations.md +1 -1
  9. package/docs/knowledge.md +14 -7
  10. package/docs/named-test-runs.md +4 -0
  11. package/docs/official-catalog.md +3 -3
  12. package/docs/packages.md +12 -12
  13. package/docs/release-notes/v0.69.6.md +165 -0
  14. package/docs/schedules.md +8 -1
  15. package/docs/tui.md +21 -4
  16. package/docs/upgrading.md +9 -5
  17. package/docs/workspaces.md +2 -2
  18. package/lib/argv.mjs +41 -0
  19. package/lib/automation-scope.mjs +6 -4
  20. package/lib/automations.mjs +61 -11
  21. package/lib/captured-context.mjs +12 -0
  22. package/lib/hot-reads.mjs +21 -15
  23. package/lib/install-stamp.mjs +61 -0
  24. package/lib/instance-events.mjs +8 -6
  25. package/lib/instance-listing.mjs +13 -5
  26. package/lib/kernel-features.mjs +10 -0
  27. package/lib/local-edit.mjs +1 -1
  28. package/lib/local-inputs.mjs +3 -0
  29. package/lib/member-clone.mjs +15 -11
  30. package/lib/read-call.mjs +143 -0
  31. package/lib/reader.mjs +203 -0
  32. package/lib/remote.mjs +47 -6
  33. package/lib/resolved-deployment.mjs +12 -4
  34. package/lib/roster-read.mjs +199 -0
  35. package/lib/session-input.mjs +35 -11
  36. package/lib/workspace-read.mjs +160 -0
  37. package/package-catalog.json +2 -2
  38. package/package.json +1 -1
  39. package/packages/client/cli-locator.mjs +1 -0
  40. package/packages/client/cli-probe-contract.mjs +4 -2
  41. package/packages/client/deployment-observer.mjs +8 -3
  42. package/packages/client/deployment-panel.mjs +17 -1
  43. package/packages/client/deployment-read-cli.mjs +48 -27
  44. package/packages/client/own-codes.mjs +3 -0
  45. package/packages/client/warm-reader.mjs +241 -0
  46. package/packages/tui/lib/client.mjs +2 -1
  47. package/packages/tui/lib/read.mjs +59 -11
  48. package/skills/oats-getting-started/SKILL.md +2 -2
package/bin/oats.mjs CHANGED
@@ -28,9 +28,14 @@ import { performance } from "node:perf_hooks";
28
28
  import { spawnSync as spawnSyncProc } from "node:child_process";
29
29
  import { enableCliCompileCache } from "../lib/compile-cache.mjs";
30
30
  import { hotImport, hotRead } from "../lib/hot-reads.mjs";
31
+ import { installStamp } from "../lib/install-stamp.mjs";
32
+
33
+ // The warm reader's baseline (lib/reader.mjs): its install's stamp before any kernel module loads, so that an
34
+ // install changed while the kernel loads is never the install the reader believes it answers from.
35
+ const READER_STAMP = process.argv[2] === "reader" ? installStamp() : null;
31
36
 
32
37
  // Node's compile cache is on before the kernel is parsed (lib/compile-cache.mjs): static imports are
33
- // all parsed and linked before this module's body runs, so they are Node built-ins and the two small
38
+ // all parsed and linked before this module's body runs, so they are Node built-ins and the three small
34
39
  // dependency-free modules above, and the kernel and `yaml` are imported here, in order, once it is on.
35
40
  enableCliCompileCache();
36
41
  // A hot read (lib/hot-reads.mjs) imports only the leaves it uses, never core.mjs: each line below takes
@@ -85,53 +90,23 @@ const { readEvents, setWaiting, incarnationOf } = await kernelImport("instance-e
85
90
  const { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } = await kernelImport("deployments", () => import("../lib/deployments.mjs"));
86
91
  const { observeResolvedDeployment } = await kernelImport("resolved-deployment", () => import("../lib/resolved-deployment.mjs"));
87
92
  const { SESSION_RESUME_FEATURE } = await kernelImport("session-resume-contract", () => import("../lib/session-resume-contract.mjs"));
93
+ const { KERNEL_FEATURES, READER_API } = await kernelImport("kernel-features", () => import("../lib/kernel-features.mjs"));
94
+ const { inheritedContextRefusal } = await kernelImport("captured-context", () => import("../lib/captured-context.mjs"));
95
+ const { callSession, parseMaxAge, readBudget } = await kernelImport("read-call", () => import("../lib/read-call.mjs"));
96
+ const { cachedWorkspace, legacyLayoutProblems, statusAnswer, statusView } = await kernelImport("roster-read", () => import("../lib/roster-read.mjs"));
97
+ const { memberLabel, memberRows, packageRows, standaloneCatalogVersion, standalonePackages, workspaceName, workspaceStatusAnswer, workspaceStatusView } = await kernelImport("workspace-read", () => import("../lib/workspace-read.mjs"));
98
+ const { expandInlineValues, flagValue } = await kernelImport("argv", () => import("../lib/argv.mjs"));
88
99
 
89
100
  const rawArgs = process.argv.slice(2);
90
- /** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
91
- const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "background", "check", "clear", "composed-skills", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-background", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "run-source", "same-work", "self", "skills", "suggest-name", "verbose", "yes", "yolo"]);
92
- /** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
93
- * routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
94
- * `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
95
- * expanded, it would be a flag token every reader sees, which the spaced form can never carry. */
96
- /** Free-text flags whose inline value may start with `--` (`--message=--deploy failed`). Such a
97
- * value is kept out of argv, where it would read as a flag (`--message=--clear` must not
98
- * clear), and flag() answers it from `inline`. */
99
- const INLINE_TEXT_FLAGS = new Set(["message"]);
100
- /** Free-text flags whose inline value is always kept whole, the empty one included:
101
- * `--description=` clears a trigger's or schedule's description. */
102
- const INLINE_WHOLE_FLAGS = new Set(["description"]);
103
- function expandInlineValues(argv) {
104
- const out = [];
105
- const inline = new Map();
106
- let problem;
107
- for (const a of argv) {
108
- const eq = a.indexOf("=");
109
- if (!a.startsWith("--") || eq <= 2) { out.push(a); continue; }
110
- const name = a.slice(2, eq), value = a.slice(eq + 1);
111
- if (INLINE_WHOLE_FLAGS.has(name) || (INLINE_TEXT_FLAGS.has(name) && value.startsWith("--"))) { inline.set(name, value); out.push(`--${name}`); continue; }
112
- problem ??= KERNEL_SWITCHES.has(name) ? `--${name} takes no value (got ${a})` : value === "" ? `--${name}= needs a value` : value.startsWith("--") ? `--${name}= takes a value, not an option (got ${a})` : undefined;
113
- out.push(`--${name}`, value);
114
- }
115
- return { argv: out, problem, inline };
116
- }
117
101
  const { argv: args, problem: argvProblem, inline: inlineValues } = expandInlineValues(rawArgs);
118
102
  let cmd = args[0];
119
103
  const HELP_WORDS = new Set(["help", "--help", "-h"]);
120
- const KERNEL_COMMANDS = new Set(["harness", "automations", "trigger", "capture", "capabilities", "deployments", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "tui", "update", "version", "workspace", "worktree"]);
104
+ const KERNEL_COMMANDS = new Set(["harness", "automations", "trigger", "capture", "capabilities", "deployments", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "onboard", "pane", "reader", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "tui", "update", "version", "workspace", "worktree"]);
121
105
  /** Commands whose argv another parser reads (packages/record, packages/experimental and packages/tui parse process.argv). */
122
106
  const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental", "tui"]);
123
- /** The kernel features this binary implements: `features` in `version --json` (the Desktop API v1
124
- * probe) and in `status --json`, which a remote roster relays as the host's (feature
125
- * server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
126
- * time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
127
- const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "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", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-same-work"];
128
107
  /** Commands `--server <id>` runs on a registered server. */
129
108
  const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
130
- const flag = (name) => {
131
- const i = args.indexOf(`--${name}`);
132
- if (i >= 0 && inlineValues.has(name)) return inlineValues.get(name);
133
- return i >= 0 ? (args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : true) : undefined;
134
- };
109
+ const flag = (name) => flagValue(args, inlineValues, name);
135
110
  function yoloFlag() {
136
111
  if (args.includes("--yolo") && args.includes("--no-yolo")) cmdFail("E_BAD_ARGS", "choose --yolo or --no-yolo, not both");
137
112
  return args.includes("--yolo") ? true : args.includes("--no-yolo") ? false : undefined;
@@ -287,7 +262,7 @@ async function doctorComposition(ctx, soulName, ws, bail) {
287
262
  * rules. → { problems, information } */
288
263
  function doctorLocalTeams(local) {
289
264
  const standalone = typeof local.standalone === "string" && local.standalone !== "";
290
- const file = standalone ? null : cachedWorkspace(local.workspace)?.file ?? null;
265
+ const file = standalone ? null : cachedWorkspace(local.workspace, remoteOptionsFromEnv)?.file ?? null;
291
266
  const model = teamModel(file, local);
292
267
  const declared = ["teams", "defaultTeam"].some((k) => Object.hasOwn(local, k));
293
268
  return { problems: model.closedKeys.length ? [localTeamsClosedProblem(model.closedKeys)] : [],
@@ -827,11 +802,6 @@ async function doctorJson(dir) {
827
802
 
828
803
  /** The v2 doctor payload: the deployment declaration + lock (offline) and, with
829
804
  * --soul, the composed instructions. No v1 keys (chain/layers/acquired/injects…). */
830
- /** The problems doctor and status share for a v2 deployment: what OATS 0.25 left
831
- * under local-agents/ (named, never read), and the captured homes under the agents root. */
832
- function legacyLayoutProblems(root) {
833
- return [legacyLocalAgents(root), legacyCapturedHomes(root)].filter(Boolean);
834
- }
835
805
  /** What retires left in the deployment (#703 part 2a), read-only: the
836
806
  * `retained-recovery:` and `retained-worktree:` information lines, as one
837
807
  * block per kind (a count line, then one line per item). */
@@ -1644,7 +1614,7 @@ let maxAgeGiven = null;
1644
1614
  let readBudgetMs = null;
1645
1615
  function commandSession() {
1646
1616
  if (!readSession) {
1647
- readSession = remoteModule.createReadSession({ maxAge: maxAgeGiven ?? 0, ...(readBudgetMs !== null ? { deadline: Date.now() + readBudgetMs } : {}) });
1617
+ readSession = callSession({ maxAge: maxAgeGiven, budgetMs: readBudgetMs });
1648
1618
  process.on("exit", () => { sayReadNotices(); readSession.closeNow(); });
1649
1619
  for (const [signal, code] of [["SIGINT", 130], ["SIGTERM", 143], ["SIGHUP", 129]]) process.once(signal, () => {
1650
1620
  readSession.closeNow();
@@ -1701,8 +1671,29 @@ const withObservation = (doc) => (maxAgeGiven === null ? doc : { ...doc, observa
1701
1671
  /** Remote options threaded into every remote call. OATS_REMOTE_CACHE relocates
1702
1672
  * the content-addressed fetch cache (tests never touch ~/.cache); `session` is the command's read session. */
1703
1673
  function remoteOptionsFromEnv() {
1674
+ const cacheDir = remoteCacheDir();
1675
+ return { ...(cacheDir ? { cacheDir } : {}), session: commandSession() };
1676
+ }
1677
+ /** OATS_REMOTE_CACHE, absolute, or undefined. */
1678
+ function remoteCacheDir() {
1704
1679
  const cacheDir = process.env.OATS_REMOTE_CACHE;
1705
- return { ...(cacheDir ? { cacheDir: resolve(cacheDir) } : {}), session: commandSession() };
1680
+ return cacheDir ? resolve(cacheDir) : undefined;
1681
+ }
1682
+ /** Say a lifted read's answer (lib/read-call.mjs: `{ exit, answer, stderr }`) as the command always did. JSON
1683
+ * mode prints the answer (`indent`: status's document is printed indented; a failure envelope never is),
1684
+ * text mode a failure as `oats: <message>`; then the read session's notices, and a failure exits. On a
1685
+ * text failure the deprecated-name warning comes before the notices, as the exit hooks said them. */
1686
+ function sayRead(read, { indent } = {}) {
1687
+ if (JSON_MODE) {
1688
+ if (read.answer && Object.hasOwn(read.answer, "warnings")) warningDelivered = true;
1689
+ console.log(read.exit === 0 && indent ? JSON.stringify(read.answer, null, indent) : JSON.stringify(read.answer));
1690
+ } else {
1691
+ console.error(`oats: ${read.answer.error.message}`);
1692
+ const w = runtimeNameWarning();
1693
+ if (w && !warningDelivered) { process.stderr.write(`oats: warning: ${w.message}\n`); warningDelivered = true; }
1694
+ }
1695
+ process.stderr.write(read.stderr);
1696
+ if (read.exit) process.exit(read.exit);
1706
1697
  }
1707
1698
 
1708
1699
  /** The v2 deployment context at --dir: { dir, localPath, local, deploymentDir, remoteOptions }. */
@@ -1762,30 +1753,6 @@ function catalogForSync(bail) {
1762
1753
  catch (e) { return bail(e.code || "E_PACKAGE_MISSING", e.message); }
1763
1754
  }
1764
1755
 
1765
- /** The package requests of a standalone view: the catalog's own pin of the package
1766
- * providing oats.core (decision 25) — nothing else, since the version list lives in
1767
- * the workspace file we cannot read. The request is written as resolvePackages
1768
- * expects a CATALOG entry: the bare version (`v1.1.3`), never the catalog's raw ref
1769
- * (`oats-framework/v1.1.3` is a tag PATH the one grammar refuses); parsePackageRequest
1770
- * recomposes the tag from the catalog's own convention.
1771
- * → { packages: { <id>: <version> }, problems: [ { code: "E_PACKAGE_MISSING", … } ] } */
1772
- function standalonePackages(catalog) {
1773
- let id = "oats.framework";
1774
- const file = officialCatalogFile();
1775
- try { const alias = officialCapabilityAliases()["oats.core"]; id = (typeof alias === "string" ? alias : alias?.package) ?? id; } catch { /* the catalog is diagnosed below */ }
1776
- const version = standaloneCatalogVersion(catalog?.[id]?.ref);
1777
- if (version) return { packages: { [id]: version }, problems: [] };
1778
- const why = catalog?.[id] ? `its ref ${JSON.stringify(catalog[id].ref)} carries no version` : `it has no entry ${JSON.stringify(id)}`;
1779
- return { packages: {}, problems: [{ code: "E_PACKAGE_MISSING", id, reason: "no-catalog", catalog: file, path: `/packages/${id}`, message: `the catalog has no package providing oats.core (OATS_PACKAGE_CATALOG=${file}): ${why}; standalone spawns will be refused until it does` }] };
1780
- }
1781
- /** The bare version of a catalog ref: its LAST path segment when that is a version
1782
- * (`v1.1.3` → `v1.1.3`; `oats-framework/v1.1.3` → `v1.1.3`; `main` → null). */
1783
- function standaloneCatalogVersion(ref) {
1784
- if (typeof ref !== "string" || !ref.trim()) return null;
1785
- const tail = ref.trim().split("/").filter(Boolean).pop() ?? "";
1786
- return classifyPackageValue(tail).kind === "catalog" ? tail : null;
1787
- }
1788
-
1789
1756
  /** Discover the workspace named by oats-local.yaml over the real remote. */
1790
1757
  async function discoverForCli(ctx, bail) {
1791
1758
  // The standalone case (decisions 10/25) is a discovery too: the repo's own view
@@ -1798,9 +1765,6 @@ async function discoverForCli(ctx, bail) {
1798
1765
  }
1799
1766
 
1800
1767
  const short = (oid) => (typeof oid === "string" ? oid.slice(0, 8) : "?");
1801
- /** Display name of a discovery: the workspace's name, or the standalone label (decision 10). */
1802
- const workspaceName = (discovery) => discovery.workspace?.name ?? `standalone:${memberLabel(discovery.key)}`;
1803
- const memberLabel = (key) => String(key).split("/").filter(Boolean).pop()?.replace(/\.git$/, "") || String(key);
1804
1768
  const originOf = (item) => (item.package ? `package ${item.package} v${item.version}` : `member ${item.repoKey} @ ${short(item.commit)}`);
1805
1769
 
1806
1770
  /** A soul's launch here (feature launch-preference): the `Launch` report a spawn with no flags would decide
@@ -1851,19 +1815,6 @@ function workspaceItems(discovery, lock, local, deploymentDir) {
1851
1815
  return { souls, capabilities };
1852
1816
  }
1853
1817
 
1854
- /** Membership rows for `sync` / `workspace status`. */
1855
- function memberRows(discovery) {
1856
- return discovery.members.map((m) => ({
1857
- key: m.key, name: memberLabel(m.key), commit: m.commit ?? null, confirmed: m.confirmed, status: m.confirmed ? "confirmed" : m.reason, detail: m.detail ?? null,
1858
- souls: m.souls.map((s) => s.name), capabilities: m.capabilities.map((c) => c.name), publishes: m.publishes ?? null,
1859
- }));
1860
- }
1861
-
1862
- /** Package rows for `sync` / `workspace status` from the lock. */
1863
- function packageRows(lock) {
1864
- 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) }));
1865
- }
1866
-
1867
1818
  /** Print a padded table: rows are arrays of strings. */
1868
1819
  function printTable(header, rows) {
1869
1820
  const all = [header, ...rows];
@@ -2179,38 +2130,17 @@ async function packageCmd() {
2179
2130
  : `Removed packages.${id} (${had}) from ${shortPath(checkout.file)}. Commit it, then \`oats sync\`.`);
2180
2131
  }
2181
2132
 
2182
- /** `oats workspace status [--dir] [--json]` — contract §6. */
2133
+ /** `oats workspace status [--dir] [--json]` — contract §6. The read is lib/workspace-read.mjs's. */
2183
2134
  async function workspaceCmd() {
2184
2135
  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
2185
2136
  if (args[1] !== "status") return bail("E_USAGE", "usage: oats workspace status [--dir <d>] [--json]");
2186
- const ctx = workspaceContext(bail);
2187
- const discovery = await discoverForCli(ctx, bail);
2188
- let lock;
2189
- try { lock = readLock(ctx.deploymentDir); } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
2190
- const members = memberRows(discovery);
2191
- const packages = packageRows(lock);
2192
- // Standalone (decision 10): there is no workspace file — the declared packages are the
2193
- // kernel's own default (decision 25) and there are no teams.
2194
- const standalone = discovery.standalone === true;
2195
- const declared = Object.keys(standalone ? standalonePackages(catalogForSync(bail)).packages : (discovery.workspace?.packages || {})).sort();
2196
- const locked = new Set(packages.map((p) => p.id));
2197
- const unsynced = declared.filter((id) => !locked.has(id));
2198
- const stale = packages.filter((p) => !declared.includes(p.id)).map((p) => p.id);
2199
- const result = { workspaceStatusApi: 1, standalone: standalone || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, url: discovery.url, commit: discovery.commit, observedAt: discovery.observedAt, local: ctx.localPath, teams: sharedTeamRows(discovery) }, members, packages, declaredPackages: declared, unsynced, stale, external: (discovery.external || []).map((e) => ({ source: e.source, soul: e.soul.name })), problems: discovery.problems, warnings: [...(discovery.warnings ?? [])] };
2200
- // Workspace automations (0.29.0), from the snapshot `oats sync` took, placed on this host.
2201
- const actx = scopeAutomations(ctx.deploymentDir, {});
2202
- result.automations = { host: actx.host.name, snapshot: actx.snapshot ? { takenAt: actx.snapshot.takenAt, problems: actx.snapshot.problems.length } : null, rows: [...actx.triggers, ...actx.schedules].map((a) => ({ kind: a.kind, id: a.id, runsOn: a.runsOn, owner: a.owner, runsHere: a.placement.runsHere, reason: a.placement.reason, enabledHere: a.placement.enabledHere, origin: a.origin, ...(a.invalid ? { invalid: a.invalid } : {}) })) };
2203
- // Automation trust (0.30): a workspace automation placed here but not trusted, and a trust entry
2204
- // that names none, are warnings the operator acts on in oats-local.yaml.
2205
- for (const a of [...actx.triggers, ...actx.schedules].filter((x) => x.placement.reason === "untrusted")) {
2206
- result.warnings.push({ code: "automation-untrusted", kind: a.kind, id: a.id, message: `${a.kind} ${a.id} is declared for this host (${a.runsOn}, as ${a.owner}) but not trusted here, so it does not run`, remedy: A.trustRemedy(a.id) });
2207
- }
2208
- for (const entry of A.staleTrust(actx.host, [...actx.triggers, ...actx.schedules])) {
2209
- result.warnings.push({ code: "automation-trust-stale", entry, message: `oats-local.yaml automations.trust names ${entry}, which is no workspace trigger or schedule${actx.snapshot ? "" : " (no automations snapshot yet: run oats sync)"}; its member may not have synced yet` });
2210
- }
2211
- await workspaceStatusFacts(result, discovery, lock, ctx);
2212
- if (JSON_MODE) { jsonOk(withObservation(result)); return; }
2213
- console.log(`workspace ${workspaceName(discovery)} (${discovery.key} @ ${short(discovery.commit)}) local ${shortPath(ctx.localPath)}\n`);
2137
+ const ctx = { dir: dirFlag(), maxAge: maxAgeGiven, session: commandSession, cacheDir: remoteCacheDir() };
2138
+ if (JSON_MODE) return sayRead(await workspaceStatusAnswer(ctx));
2139
+ const read = await workspaceStatusView(ctx);
2140
+ if (read.exit) return sayRead(read);
2141
+ const { result, discovery, localPath } = read.view;
2142
+ const { members, packages, unsynced, stale } = result, standalone = result.standalone === true;
2143
+ console.log(`workspace ${workspaceName(discovery)} (${discovery.key} @ ${short(discovery.commit)}) local ${shortPath(localPath)}\n`);
2214
2144
  if (standalone) console.log(` (${standaloneNote(discovery)})\n`);
2215
2145
  console.log("Members:");
2216
2146
  printTable(["member", "status", "commit", "souls", "capabilities", "publishes"], members.map((m) => [m.name, m.status, short(m.commit), m.souls.join(",") || "—", m.capabilities.join(",") || "—", m.publishes ? `${m.publishes.package} v${m.publishes.version ?? "?"}` : "—"]));
@@ -2227,44 +2157,7 @@ async function workspaceCmd() {
2227
2157
  }
2228
2158
  if (discovery.problems.length) { console.log("\nProblems:"); for (const p of discovery.problems) console.log(` ${p.code} ${p.repoKey ? `${memberLabel(p.repoKey)}:` : ""}${p.path} ${p.message}`); }
2229
2159
  if (result.warnings.length) { console.log("\nWarnings:"); for (const w of result.warnings) console.log(` ${w.code} ${w.message}${w.remedy ? `\n ${w.remedy}` : ""}`); }
2230
- }
2231
-
2232
- /** The committed (shared) teams as `workspace status` reports them: rows in label order (team model v2). */
2233
- function sharedTeamRows(discovery) {
2234
- const teams = discovery.standalone === true ? {} : discovery.workspace?.teams || {};
2235
- return Object.keys(teams).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)).map((label) => ({ label, team: typeof teams[label]?.team === "string" ? teams[label].team : null, description: typeof teams[label]?.description === "string" ? teams[label].description : null }));
2236
- }
2237
-
2238
- /** `oats workspace status` facts (feature desktop-facts): the workspace defaults as rows; this
2239
- * computer (member clones and the rule that found each, disabled souls, the lock); file locations with
2240
- * browsable urls; each catalog package's newer version, when the official catalog has one. */
2241
- async function workspaceStatusFacts(result, discovery, lock, ctx) {
2242
- const { memberCloneOf } = await import("../lib/member-clone.mjs");
2243
- const { browseUrl } = remoteModule;
2244
- const defaults = discovery.standalone === true ? {} : (discovery.workspace?.defaults ?? {});
2245
- const rows = (entries) => Object.entries(entries && typeof entries === "object" ? entries : {}).map(([name, v]) => ({ name, from: v === "off" ? null : v?.from ?? null, off: v === "off" })).sort((a, b) => (a.name < b.name ? -1 : 1));
2246
- const slot = (d) => (d && typeof d === "object" ? Object.entries(d).map(([name, v]) => ({ name, from: v?.from ?? null }))[0] ?? null : d ?? null);
2247
- result.defaults = {
2248
- slots: Object.fromEntries(LAYERS.map((l) => [l, slot(defaults[l])])),
2249
- capabilities: rows(defaults.capabilities),
2250
- };
2251
- result.workspace.file = discovery.standalone === true ? null : { path: "oats-workspace.yaml", url: browseUrl(discovery.key, discovery.commit, "oats-workspace.yaml") };
2252
- for (const m of result.members) Object.assign(m, { url: browseUrl(m.key, m.commit), membershipFile: { path: "oats-membership.yaml", url: browseUrl(m.key, m.commit, "oats-membership.yaml") } });
2253
- result.clones = result.members.map((m) => {
2254
- try { return { key: m.key, name: m.name, ...memberCloneOf(ctx.deploymentDir, ctx.local, m.key) }; }
2255
- catch (e) { if (e?.code === "E_CLONE_MISMATCH") return { key: m.key, name: m.name, path: null, rule: null, problem: { code: e.code, message: e.message } }; throw e; }
2256
- });
2257
- result.disabledSouls = [...(Array.isArray(ctx.local?.souls?.disabled) ? ctx.local.souls.disabled : [])];
2258
- result.lock = { path: join(ctx.deploymentDir, LOCK_FILE), lockfileVersion: lock.lockfileVersion ?? null };
2259
- const { compareSemver } = await import("../lib/semver.mjs");
2260
- let catalog = null; try { catalog = officialPackageCatalog(); } catch { catalog = null; }
2261
- const cat = catalog && typeof catalog === "object" ? (catalog.packages && typeof catalog.packages === "object" && !("url" in catalog.packages) ? catalog.packages : catalog) : {};
2262
- for (const p of result.packages) {
2263
- const ref = p.source === `catalog:${p.id}` ? cat[p.id]?.ref : undefined;
2264
- const tag = standaloneCatalogVersion(ref);
2265
- const version = tag ? tag.replace(/^v/, "") : null;
2266
- p.latest = version && typeof p.version === "string" && compareSemver(version, p.version) > 0 ? { version, ref } : null;
2267
- }
2160
+ process.stderr.write(read.stderr);
2268
2161
  }
2269
2162
 
2270
2163
  /** The deployment's team facts for the team verbs: oats-local.yaml, the committed workspace file and the
@@ -2649,125 +2542,6 @@ async function soulFacts(rows, discovery, lock, ctx, remote = remoteModule) {
2649
2542
  }
2650
2543
 
2651
2544
  // ---------- roster: status / spawn / retire / create ----------
2652
- /** Workspace drift for `oats status` (decision 17: shown, not prevented). ONE discovery over
2653
- * the remotes serves every instance; `driftOf` compares each instance's recorded modules to
2654
- * the members' current state (and package modules to the lock), `soulDriftOf` the instance's
2655
- * recorded SOUL SOURCE (instance.json.workspace.soul) to its member's current commit. Offline →
2656
- * { unreachable }. Returns null when the deployment is not a workspace deployment (no
2657
- * oats-local.yaml). `souls` maps each workspace soul NAME (agents/<name>/.oats-soul-source.json
2658
- * present) to its stamp — the roster's `repo:` column for a workspace soul. */
2659
- async function statusDrift(data) {
2660
- let ctx;
2661
- try { ctx = loadLocal(dirFlag()); }
2662
- catch (e) {
2663
- if (e?.code === "E_LOCAL_MISSING") return null;
2664
- // A 0.25 oats-config.yaml inside the deployment: the typed migration error, never a stack.
2665
- if (e?.code === "E_CONFIG_BROKEN") { if (JSON_MODE) jsonFail(e.code, e.message, e.details); die(e.message); }
2666
- throw e;
2667
- }
2668
- const hasModules = (i) => i.modules && typeof i.modules === "object" && Object.keys(i.modules).length > 0;
2669
- const hasSoul = (i) => i.workspace && typeof i.workspace === "object" && i.workspace.soul && typeof i.workspace.soul === "object" && typeof i.workspace.soul.repoKey === "string";
2670
- // Workspace souls of this roster: the stamp ensureWorkspaceSoul leaves beside the soul pointer.
2671
- const souls = new Map();
2672
- for (const a of data) {
2673
- if (!a.dir) continue;
2674
- 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 } : {}) }); }
2675
- catch { /* not a workspace soul (classic, or an unreadable stamp) */ }
2676
- }
2677
- const anything = data.some((a) => (a.instances || []).some((i) => hasModules(i) || hasSoul(i)));
2678
- if (!anything) return { drift: new Map(), soul: new Map(), souls, unreachable: null, local: ctx.local, discovery: null };
2679
- const deploymentDir = dirname(ctx.path);
2680
- let lock = null;
2681
- try { lock = readLockIfPresent(deploymentDir); } catch { lock = null; }
2682
- let discovery;
2683
- // The standalone view (decisions 10/25) is a discovery too: drift of a standalone
2684
- // instance is computed against its member's current state, not reported "unreachable".
2685
- try { const { discoverOrStandalone } = await import("../lib/member-clone.mjs"); discovery = await discoverOrStandalone(ctx.local, { lock, remoteOptions: remoteOptionsFromEnv() }); }
2686
- catch (e) {
2687
- const reason = e?.details?.reason ? `${e.code}: ${e.details.reason}` : (e?.code || e?.message || "unknown");
2688
- return { drift: new Map(), soul: new Map(), souls, unreachable: { code: e?.code ?? null, reason, message: e?.message ?? String(e) }, local: ctx.local, discovery: null };
2689
- }
2690
- const { driftOf, soulDriftOf } = await import("../lib/drift.mjs");
2691
- const drift = new Map();
2692
- const soul = new Map();
2693
- for (const a of data) for (const i of a.instances || []) {
2694
- const key = i.home ?? `${a.name}/${i.instance}`;
2695
- if (hasModules(i)) { try { drift.set(key, driftOf(i, discovery, { lock })); } catch { /* an unreadable module record shows as no drift rows */ } }
2696
- if (hasSoul(i)) { try { const row = soulDriftOf(i, discovery); if (row) soul.set(key, row); } catch { /* an unreadable soul record shows as no soul row */ } }
2697
- }
2698
- // The roster's soul row reflects the CURRENT member commit too (the pointer may lag a moved member).
2699
- // First match per key, as `find` gave, from indexes built once (not a scan per agent).
2700
- const packageSoulAt = new Map();
2701
- for (const p of discovery.packageSouls || []) { const k = `${p.package}\0${p.path}`; if (!packageSoulAt.has(k)) packageSoulAt.set(k, p); }
2702
- for (const [, stamp] of souls) {
2703
- if (typeof stamp.package === "string") { const now = packageSoulAt.get(`${stamp.package}\0${stamp.path}`); if (now) stamp.current = now.commit; continue; }
2704
- const member = memberRowByKey(discovery.members, stamp.repoKey);
2705
- if (member && typeof member.commit === "string" && (member.confirmed || (discovery.standalone === true && member.key === discovery.key))) stamp.current = member.commit;
2706
- }
2707
- return { drift, soul, souls, unreachable: null, local: ctx.local, discovery };
2708
- }
2709
- /** The deployment's workspace identity in `oats status --json` (feature workspace-identity), read
2710
- * OFFLINE. `key` is the workspace HOST's canonical repo key (parseRepoRef(...).key) and `ref` the
2711
- * reference as oats-local.yaml writes it. The host is the one this run observed, else the one this
2712
- * machine's parsed cache knows: `ref` itself when the cache holds its workspace file, or the host its
2713
- * cached oats-membership.yaml names when `ref` is a member ("workspace"). A member whose host is not
2714
- * known keys as itself ("member"); a ref nothing is known of is taken as the host, as the schema
2715
- * defines `workspace:` ("workspace"). The team model resolves as teamModel resolves it (the default is
2716
- * the local one the workspace allows, else the workspace's; a committed team wins a collision) over the shared teams of, in order, the workspace
2717
- * file this run observed (`teamsFrom: "observed"`), the cached file ("cache": no git process), or none
2718
- * ("local"). `standalone` is the CONFIGURED standalone view only (oats-local.yaml `standalone:`): it
2719
- * reads no workspace file, so its local teams are the whole team model. A run that fell back to the
2720
- * standalone view (the host unreadable) is not: its team model is the workspace's, and its
2721
- * discovery is the member's, never the host's key. */
2722
- function workspaceIdentity(local, discovery) {
2723
- const ref = local.workspace;
2724
- const standalone = typeof local.standalone === "string" && local.standalone !== "";
2725
- const observed = discovery && discovery.standalone !== true && discovery.workspace ? discovery : null;
2726
- const cached = observed ? null : cachedWorkspace(ref);
2727
- const keyOf = (r) => { try { return remoteModule.parseRepoRef(r).key; } catch { return null; } };
2728
- let key, keyFrom;
2729
- if (observed) [key, keyFrom] = [observed.key, "workspace"];
2730
- else if (cached && cached.host === null) [key, keyFrom] = [keyOf(ref), "member"];
2731
- else [key, keyFrom] = [keyOf(cached?.host ?? ref), "workspace"];
2732
- if (key === null) keyFrom = null; // a reference parseRepoRef refuses: unusable, never matched
2733
- let shared = null, teamsFrom = "local";
2734
- if (!standalone) {
2735
- if (observed) [shared, teamsFrom] = [observed.workspace, "observed"];
2736
- else if (cached?.file) [shared, teamsFrom] = [cached.file, "cache"];
2737
- }
2738
- const model = teamModel(shared, local);
2739
- // A soul with no souls: default of its own lives here (team model 3: the local default the workspace allows, else the workspace's).
2740
- const deploymentDefault = model.localDefault ?? model.workspaceDefault;
2741
- const labels = [...model.labels.keys()].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
2742
- return {
2743
- key, ref, keyFrom, standalone,
2744
- defaultTeam: deploymentDefault === null ? null : { label: deploymentDefault, team: model.labels.get(deploymentDefault)?.team ?? null },
2745
- teams: Object.fromEntries(labels.map((l) => [l, model.labels.get(l).team])),
2746
- teamsFrom,
2747
- };
2748
- }
2749
- /** What this machine's parsed cache knows of the workspace `ref` names (the values observeWorkspace and
2750
- * confirmMembership stored, each at its repo's last observed commit): { host, file } — `host` the ref
2751
- * of the workspace host, `file` its workspace file or null — when `ref` is the host (its workspace file
2752
- * is cached) or a member whose cached oats-membership.yaml names it (discoverOrStandalone follows the
2753
- * same backlink). A member's backlink is cached whether its own workspace slot was observed (missing)
2754
- * or never was (the host's discovery confirmed it). { host: null, file: null } for a ref cached as
2755
- * having no workspace file and no backlink; null when nothing is known. */
2756
- function cachedWorkspace(ref) {
2757
- const options = remoteOptionsFromEnv();
2758
- const cached = (r, item) => {
2759
- const commit = remoteModule.lastObservedCommit(r, options);
2760
- const value = commit ? remoteModule.peekAtCommit(r, commit, item, options) : undefined;
2761
- return value && typeof value === "object" ? value : null;
2762
- };
2763
- const fileOf = (read) => (read && !read.missing && !read.problems && read.value && typeof read.value === "object" ? read.value : null);
2764
- const read = cached(ref, "workspace");
2765
- if (read && !read.missing) return { host: ref, file: fileOf(read) };
2766
- const membership = cached(ref, "membership");
2767
- const host = membership?.kind === "ok" && typeof membership.value?.workspace === "string" ? membership.value.workspace : null;
2768
- if (host !== null) return { host, file: fileOf(cached(host, "workspace")) };
2769
- return read ? { host: null, file: null } : null;
2770
- }
2771
2545
  /** One `modules:` line per module. */
2772
2546
  function driftLine(row) {
2773
2547
  const from = row.from || {};
@@ -2798,47 +2572,20 @@ function soulRepoLabel(a, ws) {
2798
2572
  const moved = stamp.current && stamp.commit && stamp.current !== stamp.commit ? ` (member now @ ${short7(stamp.current)})` : "";
2799
2573
  return `${memberLabel(stamp.repoKey)} @ ${short7(stamp.commit)}${moved}`;
2800
2574
  }
2801
- /** A roster agent's soul key: the qualified name of a package soul, else the recorded agent (soul) name;
2802
- * null when no instance records a workspace soul. Exactly soulKeyOf for the soul it was spawned from. */
2803
- function agentSoulKey(a) {
2804
- for (const i of a.instances || []) {
2805
- const soul = i?.workspace?.soul;
2806
- if (!soul || typeof soul !== "object") continue;
2807
- return soul.package && typeof soul.qualifiedName === "string" ? soul.qualifiedName : (typeof i.agent === "string" ? i.agent : a.name);
2808
- }
2809
- return null;
2810
- }
2811
2575
  const short7 = (oid) => (typeof oid === "string" ? oid.slice(0, 7) : "?");
2812
2576
 
2577
+ /** `oats status [--dir] [--verbose] [--json]`. The read is lib/roster-read.mjs's; `--team` is refused
2578
+ * before --dir is read. */
2813
2579
  async function status() {
2814
- if (args.includes("--team")) { const msg = "status --team was removed with the classic team scope: `oats status` in the deployment lists every instance, and `oats workspace status` shows the members"; if (JSON_MODE) jsonFail("E_BAD_ARGS", msg); die(msg); }
2815
- let root;
2816
- try { root = ensureRoot(dirFlag()); }
2817
- catch (e) { if (e?.code === "E_NO_DEPLOYMENT") { if (JSON_MODE) jsonFail("E_NO_DEPLOYMENT", e.message, e.details ?? e.provenance); die(e.message); } throw e; }
2818
- const data = listInstances(root);
2819
- const ws = await statusDrift(data);
2820
- const verbose = args.includes("--verbose");
2821
- const problems = legacyLayoutProblems(root);
2822
- if (args.includes("--json")) {
2823
- // The soul key (feature launch-preference): what souls.launch and `oats soul teams <key>` use —
2824
- // from the instances' records, so it needs no remote.
2825
- for (const a of data) a.key = agentSoulKey(a);
2826
- if (ws) for (const a of data) {
2827
- const stamp = ws.souls.get(a.name);
2828
- if (stamp) a.soulSource = { repoKey: stamp.repoKey, commit: stamp.commit, path: stamp.path, ...(stamp.current ? { current: stamp.current, status: stamp.current === stamp.commit ? "current" : "moved" } : {}) };
2829
- for (const i of a.instances || []) {
2830
- const key = i.home ?? `${a.name}/${i.instance}`;
2831
- const rows = ws.drift.get(key);
2832
- 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 } : {}) }));
2833
- const s = ws.soul.get(key);
2834
- 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 } : {}) };
2835
- }
2836
- }
2837
- const observation = maxAgeGiven === null ? {} : { observation: observationBlock() };
2838
- // `features` (feature server-probe-features): this kernel's own list, as `version --json` answers
2839
- // it, so a remote roster relays the host's without probing it. Never part of a reused observation.
2840
- console.log(JSON.stringify({ root, agents: data, ...observation, features: KERNEL_FEATURES, sessionViewer: readSessionViewer(), ...(ws ? { workspace: { ...(ws.unreachable ? { reachable: false, ...ws.unreachable } : { reachable: true }), ...workspaceIdentity(ws.local, ws.discovery) } } : {}), ...(problems.length ? { problems } : {}), ...envelopeWarnings() }, null, 2)); return;
2841
- }
2580
+ const team = args.includes("--team");
2581
+ const ctx = { dir: team ? null : dirFlag(), team, maxAge: maxAgeGiven, session: commandSession, cacheDir: remoteCacheDir() };
2582
+ if (JSON_MODE) return sayRead(await statusAnswer(ctx), { indent: 2 });
2583
+ const read = await statusView(ctx);
2584
+ if (read.exit) return sayRead(read);
2585
+ printStatus(read.view, args.includes("--verbose"));
2586
+ process.stderr.write(read.stderr);
2587
+ }
2588
+ function printStatus({ root, agents: data, ws, problems }, verbose) {
2842
2589
  console.log(`oats status — agents root ${shortPath(root)}\n`);
2843
2590
  if (ws?.unreachable) console.log(` workspace: unreachable (${ws.unreachable.reason}) — drift unknown\n`);
2844
2591
  for (const p of problems) console.log(` ! ${p.code}: ${p.message}\n`);
@@ -4368,6 +4115,14 @@ function updateCmd() {
4368
4115
  }
4369
4116
 
4370
4117
  // ---------- version (Desktop CLI API v1 probe) ----------
4118
+ /** `oats reader --stdio`: the warm reader (lib/reader.mjs), a client's child that answers status and workspace
4119
+ * status on its stdin and stdout until the client ends it. */
4120
+ async function readerCmd() {
4121
+ if (args.length !== 2 || args[1] !== "--stdio") return cmdFail("E_USAGE", "usage: oats reader --stdio (the warm reader: a client's child process that answers status and workspace status reads on stdin and stdout; docs/desktop-cli-api.md \"The warm reader\")");
4122
+ const { runReader } = await import("../lib/reader.mjs");
4123
+ await runReader({ stamp: READER_STAMP });
4124
+ }
4125
+
4371
4126
  function versionCmd() {
4372
4127
  if (JSON_MODE) {
4373
4128
  // EXACT Desktop API v1 probe payload — one JSON object, nothing else on
@@ -4381,7 +4136,7 @@ function versionCmd() {
4381
4136
  // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
4382
4137
  // runs on resolve/materialize (contract §6); a feature the binary does not implement is
4383
4138
  // never listed.
4384
- console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: KERNEL_FEATURES, automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1, sessionViewer: readSessionViewer() }));
4139
+ console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: KERNEL_FEATURES, automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1, readerApi: READER_API, sessionViewer: readSessionViewer() }));
4385
4140
  return;
4386
4141
  }
4387
4142
  console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -4922,18 +4677,17 @@ try {
4922
4677
  if (kernelArgv && head.includes("--max-age")) {
4923
4678
  const refusal = maxAgeRefusal(cmd, head);
4924
4679
  if (refusal) cmdFail("E_BAD_ARGS", refusal);
4925
- const raw = flag("max-age");
4926
- if (raw === true) cmdFail("E_BAD_ARGS", `--max-age needs a value: whole seconds from 0 to ${remoteModule.MAX_AGE_LIMIT}`);
4927
- if (!/^\d{1,5}$/.test(raw) || Number(raw) > remoteModule.MAX_AGE_LIMIT) cmdFail("E_BAD_ARGS", `--max-age takes whole seconds from 0 to ${remoteModule.MAX_AGE_LIMIT}, got ${JSON.stringify(raw)}`);
4928
- maxAgeGiven = Number(raw);
4680
+ const { maxAge, refusal: badAge } = parseMaxAge(flag("max-age"));
4681
+ if (badAge) cmdFail(badAge.code, badAge.message);
4682
+ maxAgeGiven = maxAge;
4929
4683
  activateLocalInputs(); // observation.localRevision: every local config read from here on is recorded
4930
4684
  }
4931
4685
  if (kernelArgv && !head.includes("--server") && (cmd === "status" || (cmd === "workspace" && head[1] === "status"))) {
4932
- const override = Number(process.env.OATS_READ_REMOTE_BUDGET_MS);
4933
- readBudgetMs = Number.isSafeInteger(override) && override > 0 ? override : remoteModule.READ_REMOTE_BUDGET_MS;
4686
+ readBudgetMs = readBudget(process.env);
4934
4687
  }
4935
- const inherited = ["OATS_RESOLUTION", "OATS_DEPLOYMENT"].filter((k) => process.env[k]);
4936
- 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 });
4688
+ // The warm reader answers each request as the CLI would, this refusal included (lib/reader.mjs).
4689
+ const captured = cmd === "version" || cmd === "reader" ? null : inheritedContextRefusal(process.env);
4690
+ if (captured) refuse(captured.message, captured.details);
4937
4691
  if (cmd === "inspect" && head.includes("--request")) {
4938
4692
  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";
4939
4693
  if (JSON_MODE) jsonFail("E_UNKNOWN_COMMAND", message, { removed: "inspect --request", replacement: "oats onboard / oats sync; oats spawn --preview" });
@@ -4998,6 +4752,7 @@ else if (cmd === "status") await status();
4998
4752
  else if (cmd === "pane") await paneCmd();
4999
4753
  else if (cmd === "tui") await tuiCmd();
5000
4754
  else if (cmd === "version" || cmd === "--version" || cmd === "-v") versionCmd();
4755
+ else if (cmd === "reader") await readerCmd();
5001
4756
  else if (cmd === "session") await sessionCmd();
5002
4757
  else if (cmd === "schedule") await scheduleCmd();
5003
4758
  else if (cmd === "trigger") await triggerCmd();
@@ -5062,6 +4817,9 @@ Usage:
5062
4817
  Desktop CLI API v1 probe payload
5063
4818
  oats status [--json] agents, souls, running instances
5064
4819
  [--max-age <s>] reuse head observations up to <s> s old (below)
4820
+ oats reader --stdio the warm reader: a client starts it as its child and
4821
+ asks it status and workspace status reads, one JSON
4822
+ line each way (docs/desktop-cli-api.md "The warm reader")
5065
4823
  oats tui [--dir <path>] [--ascii] PREVIEW: the full-screen terminal client (docs/tui.md):
5066
4824
  the instances of the workspace of the deployment at or
5067
4825
  above <path> (default: where you are), on this machine
@@ -125,6 +125,7 @@ Otherwise it is listed with the reason `assigned-elsewhere`, `owner-mismatch` (n
125
125
  3. **Tasks:** if the provenance names a tasks provider and refs, and its own tasks capability matches, it reads those tickets. Otherwise the verdict records `tasks: "unavailable"`. This is never a blocker.
126
126
  4. **Verdict**, recorded as a structured `okf-review` PR comment: `merge`; `amend+merge` (it pushes fixes, supersession edits in other concepts of the same base, index and log to the PR branch); `request-changes` (it messages the harvester and waits, bounded); `close` (with the reason); `needs-human`. It checks the doctrine's two-part test, one canonical home, explicit supersession and provenance.
127
127
  5. **Human-accepted decisions are never superseded silently.** A PR that would supersede a concept with human acceptance evidence is not merged: the maintainer labels it `okf-needs-human` and asks a human. That label is a hard stop that only a human removes.
128
+ *Superseded by oats.okf 5.7.0 ([awebai/oats-okf#118](https://github.com/awebai/oats-okf/issues/118)): the maintainer never parks a PR; it merges such a supersession only with the human's acceptance cited (checked when the record is on GitHub, otherwise recorded as source-reported) and closes it otherwise.*
128
129
  6. It merges with the host's `gh` (squash, pinned to the reviewed head), notifies the harvester (`merged` or `closed`) and retires.
129
130
 
130
131
  **Messaging:** the harvester and the maintainer talk through the soul's messaging capability, in the deployment's default team like every instance. There is no dedicated team to declare; a deployment that wants them in another team opts them in locally, as for any soul (see [the team model](2026-09-27-team-model-v2.md)).
@@ -160,5 +161,6 @@ The oats.okf inject teaches a work mode over both kinds of knowledge:
160
161
  3. **Workspace automations are placed by declaration:** `runsOn` names the one host, `owner` the account it acts as, and a host runs one only when both match.
161
162
  4. **The harvester is a package soul** (it needs messaging and a lifetime past its PR); capability agents are removed.
162
163
  5. **The maintainer merges autonomously** when the doctrine passes, except where it would supersede a human-accepted decision (`okf-needs-human`).
164
+ *Superseded by oats.okf 5.7.0 ([awebai/oats-okf#118](https://github.com/awebai/oats-okf/issues/118)): no exception remains, and the maintainer settles every PR itself: a supersession of a human-accepted decision merges when it cites the human's acceptance and is closed otherwise.*
163
165
  6. **The harvester and the maintainer hold no knowledge slot** (no recursive harvest).
164
166
  7. **Harvest is opt-in per host and opt-out per soul**, and the soul's opt-out is absolute.