@awebai/oats 0.69.4 → 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 (74) hide show
  1. package/bin/oats.mjs +141 -364
  2. package/docs/configuration.md +12 -0
  3. package/docs/design/2026-09-26-okf-knowledge-operations.md +2 -0
  4. package/docs/design/2026-10-29-warm-reader.md +261 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +258 -13
  7. package/docs/execution-targets.md +36 -5
  8. package/docs/implementation.md +34 -9
  9. package/docs/integrations.md +2 -2
  10. package/docs/knowledge.md +18 -8
  11. package/docs/named-test-runs.md +4 -0
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +14 -14
  14. package/docs/release-notes/v0.69.5.md +146 -0
  15. package/docs/release-notes/v0.69.6.md +165 -0
  16. package/docs/schedules.md +8 -1
  17. package/docs/tui.md +23 -5
  18. package/docs/upgrading.md +20 -5
  19. package/docs/workspaces.md +2 -2
  20. package/lib/agents-root.mjs +51 -0
  21. package/lib/argv.mjs +41 -0
  22. package/lib/automation-api.mjs +7 -0
  23. package/lib/automation-scope.mjs +37 -0
  24. package/lib/automations.mjs +63 -12
  25. package/lib/captured-context.mjs +12 -0
  26. package/lib/compile-cache.mjs +36 -0
  27. package/lib/core.mjs +39 -1348
  28. package/lib/deployment-path.mjs +127 -0
  29. package/lib/deployments.mjs +2 -2
  30. package/lib/drift.mjs +95 -0
  31. package/lib/hot-reads.mjs +137 -0
  32. package/lib/install-stamp.mjs +61 -0
  33. package/lib/instance-address.mjs +21 -0
  34. package/lib/instance-events.mjs +8 -6
  35. package/lib/instance-lifecycle.mjs +4 -16
  36. package/lib/instance-listing.mjs +738 -0
  37. package/lib/instance-resolution.mjs +5 -166
  38. package/lib/kernel-features.mjs +10 -0
  39. package/lib/local-edit.mjs +1 -1
  40. package/lib/local-inputs.mjs +3 -0
  41. package/lib/materialize.mjs +2 -87
  42. package/lib/member-clone.mjs +192 -0
  43. package/lib/package-catalog.mjs +93 -0
  44. package/lib/packages.mjs +4 -24
  45. package/lib/read-call.mjs +143 -0
  46. package/lib/reader.mjs +203 -0
  47. package/lib/remote.mjs +47 -6
  48. package/lib/reserved-launch-env.mjs +20 -0
  49. package/lib/resolved-deployment.mjs +13 -5
  50. package/lib/roster-read.mjs +199 -0
  51. package/lib/schedule.mjs +5 -29
  52. package/lib/semver.mjs +12 -0
  53. package/lib/servers.mjs +10 -12
  54. package/lib/session-end.mjs +3 -2
  55. package/lib/session-input.mjs +35 -11
  56. package/lib/session-inspect.mjs +219 -0
  57. package/lib/soul-listing.mjs +216 -0
  58. package/lib/status-words.mjs +30 -0
  59. package/lib/version.mjs +9 -0
  60. package/lib/workspace-read.mjs +160 -0
  61. package/lib/write-file-atomic.mjs +28 -0
  62. package/package-catalog.json +4 -4
  63. package/package.json +1 -1
  64. package/packages/client/cli-locator.mjs +1 -0
  65. package/packages/client/cli-probe-contract.mjs +4 -2
  66. package/packages/client/deployment-observer.mjs +8 -3
  67. package/packages/client/deployment-panel.mjs +17 -1
  68. package/packages/client/deployment-read-cli.mjs +48 -27
  69. package/packages/client/own-codes.mjs +3 -0
  70. package/packages/client/warm-reader.mjs +241 -0
  71. package/packages/tui/lib/client.mjs +2 -1
  72. package/packages/tui/lib/read.mjs +59 -11
  73. package/packages/tui/lib/store.mjs +7 -3
  74. package/skills/oats-getting-started/SKILL.md +3 -3
package/bin/oats.mjs CHANGED
@@ -25,99 +25,88 @@ import { constants as osConstants, homedir, tmpdir } from "node:os";
25
25
  import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
26
26
  import { fileURLToPath } from "node:url";
27
27
  import { performance } from "node:perf_hooks";
28
- import { doctorCaptureWarnings } from "../lib/doctor-capture.mjs";
29
- import { assertNoPartialUpgrade } from "../lib/upgrade-state.mjs";
30
- import { runtimeNameWarning, noteRuntimeName } from "../lib/deprecation.mjs";
31
- import { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect, spawnRefusalDetails } from "../lib/errors.mjs";
32
- import {
28
+ import { spawnSync as spawnSyncProc } from "node:child_process";
29
+ import { enableCliCompileCache } from "../lib/compile-cache.mjs";
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;
36
+
37
+ // Node's compile cache is on before the kernel is parsed (lib/compile-cache.mjs): static imports are
38
+ // all parsed and linked before this module's body runs, so they are Node built-ins and the three small
39
+ // dependency-free modules above, and the kernel and `yaml` are imported here, in order, once it is on.
40
+ enableCliCompileCache();
41
+ // A hot read (lib/hot-reads.mjs) imports only the leaves it uses, never core.mjs: each line below takes
42
+ // the leaves its names come from, and every other command imports every module, in this order. A hot
43
+ // read takes its names from lib/hot-reads.mjs: a name newly used on a hot read's path must be listed
44
+ // there, under its line, or its first use throws (a tripwire); test/cli-hot-reads.test.mjs pins what
45
+ // each hot read must not load. Each line names its module and imports it by one string literal.
46
+ const HOT_READ = hotRead(process.argv.slice(2));
47
+ const kernelImport = (name, load) => (HOT_READ ? hotImport(HOT_READ, name) : load());
48
+ const { doctorCaptureWarnings } = await kernelImport("doctor-capture", () => import("../lib/doctor-capture.mjs"));
49
+ const { assertNoPartialUpgrade } = await kernelImport("upgrade-state", () => import("../lib/upgrade-state.mjs"));
50
+ const { runtimeNameWarning, noteRuntimeName } = await kernelImport("deprecation", () => import("../lib/deprecation.mjs"));
51
+ const { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect, spawnRefusalDetails } = await kernelImport("errors", () => import("../lib/errors.mjs"));
52
+ const {
33
53
  LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
34
54
  capabilityManifests, capabilityTrust, capabilityExecutablePath,
35
55
  officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
36
56
  findInstanceHome, findInstanceHomes, homeLaunchLayers, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, suggestSpawnName, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, machineLaunchConfigs, machineLaunchConfigsFile, launchStartNotices, launchReportFor, explicitInstanceName, retireInstance, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
37
57
  FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
38
- } from "../lib/core.mjs";
39
- import {
58
+ } = await kernelImport("core", () => import("../lib/core.mjs"));
59
+ const {
40
60
  writeFileAtomic, LOCK_FILE, canonicalLock, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
41
- classifyPackageValue, parsePackageRequest } from "../lib/packages.mjs";
42
- import { harnessTrust } from "../lib/harness-trust-write.mjs";
43
- import { previewLaunchEnvironment, previewPaneEnvironment } from "../lib/core.mjs";
44
- import { PI_BRIDGE, piBridgeFolders, piBridgeSkewWarnings, planPiBridges, piBridgePlanLines, piBridgeStepProblem, piBridgeFailure, kernelLookup, kernelLookupResult, planCliUpdate, desktopFirstLine, bridgeLookup, bridgeLookupProblem } from "../lib/pi-bridge.mjs";
45
- import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, unlockedPackages, workspaceWarnings, memberRowByKey } from "../lib/workspace.mjs";
46
- import { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "../lib/teams.mjs";
47
- import { LAUNCH_KEY_UNCHECKED, LAUNCH_PREFERENCE_UNMATCHED, launchKeyQuoted, launchKeysUnmatched, launchLayers, soulLaunchCommand, unmatchedKeyMessage } from "../lib/launch-preference.mjs";
48
- import { terminalText } from "../lib/refused-text.mjs";
49
- import { qualifiedSoulName, soulCandidates, soulsOffered } from "../lib/instance-resolution.mjs";
50
- import { parseConfigData } from "../lib/config-data.mjs";
51
- import * as remoteModule from "../lib/remote.mjs";
52
- import { activateLocalInputs, localRevision } from "../lib/local-inputs.mjs";
53
- import YAML from "yaml";
54
- import { attachArgv, checkRemote, connectServer, forgetSnapshot, getServer, inspectRemote, startRemote, restartRemote, launchConfigRemote, scheduleRemote, listSnapshots, learnWorkspaceKey, readServers, redactArgv, reportedWorkspaceKey, rosterGroups, routeCapability, routeCommand, runRemote, serverFlagOf, targetOf, updateServers, validateServer, workspaceKeyOfStatus, workspaceMismatch, SERVERS_FILE } from "../lib/servers.mjs";
55
- import { readSessionViewer } from "../lib/session-viewer.mjs";
56
- import { spawnSync as spawnSyncProc } from "node:child_process";
57
- import { tickTriggers } from "../lib/triggers.mjs";
58
- import * as A from "../lib/automations.mjs";
59
- import { parseEnvelopeText, unresolvedScheduleAttempts, scheduleScopeOf, listSchedules, describe as describeSchedule, testSchedule, addSchedule, updateSchedule, updateScheduleDescription, setEnabled as setScheduleEnabled, removeSchedule, runNow as runScheduleNow, reconcile as reconcileSchedule, tickHost, tickWorkspace, scopeAutomations, scheduleKind, registerWorkspace, unregisterWorkspace, readRegistry, schedulerStatus, saveWakeForHome, removeWakeForHome, wakeFromFlags, withHostLock, scheduleError, SCHEDULE_API } from "../lib/schedule.mjs";
60
- import { hostUnitFiles, hostUnitStatus, installHostUnit, uninstallHostUnit } from "../lib/schedule-host.mjs";
61
- import { kernelNode, stableNode } from "../lib/stable-node.mjs";
62
- import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
63
-
64
- import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
65
- import { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance as resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstanceSameWork, STOP_WARNINGS } from "../lib/instance-lifecycle.mjs";
66
- import { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } from "../lib/retire-output.mjs";
67
- import { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } from "../lib/retained-after-retire.mjs";
61
+ classifyPackageValue, parsePackageRequest } = await kernelImport("packages", () => import("../lib/packages.mjs"));
62
+ const { harnessTrust } = await kernelImport("harness-trust-write", () => import("../lib/harness-trust-write.mjs"));
63
+ const { previewLaunchEnvironment, previewPaneEnvironment } = await kernelImport("core", () => import("../lib/core.mjs"));
64
+ const { PI_BRIDGE, piBridgeFolders, piBridgeSkewWarnings, planPiBridges, piBridgePlanLines, piBridgeStepProblem, piBridgeFailure, kernelLookup, kernelLookupResult, planCliUpdate, desktopFirstLine, bridgeLookup, bridgeLookupProblem } = await kernelImport("pi-bridge", () => import("../lib/pi-bridge.mjs"));
65
+ const { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, unlockedPackages, workspaceWarnings, memberRowByKey } = await kernelImport("workspace", () => import("../lib/workspace.mjs"));
66
+ const { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } = await kernelImport("teams", () => import("../lib/teams.mjs"));
67
+ const { LAUNCH_KEY_UNCHECKED, LAUNCH_PREFERENCE_UNMATCHED, launchKeyQuoted, launchKeysUnmatched, launchLayers, soulLaunchCommand, unmatchedKeyMessage } = await kernelImport("launch-preference", () => import("../lib/launch-preference.mjs"));
68
+ const { terminalText } = await kernelImport("refused-text", () => import("../lib/refused-text.mjs"));
69
+ const { qualifiedSoulName, soulCandidates, soulsOffered } = await kernelImport("instance-resolution", () => import("../lib/instance-resolution.mjs"));
70
+ const { parseConfigData } = await kernelImport("config-data", () => import("../lib/config-data.mjs"));
71
+ const remoteModule = await kernelImport("remote", () => import("../lib/remote.mjs"));
72
+ const { activateLocalInputs, localRevision } = await kernelImport("local-inputs", () => import("../lib/local-inputs.mjs"));
73
+ const { default: YAML } = await kernelImport("yaml", () => import("yaml"));
74
+ const { attachArgv, checkRemote, connectServer, forgetSnapshot, getServer, inspectRemote, startRemote, restartRemote, launchConfigRemote, scheduleRemote, listSnapshots, learnWorkspaceKey, readServers, redactArgv, reportedWorkspaceKey, rosterGroups, routeCapability, routeCommand, runRemote, serverFlagOf, targetOf, updateServers, validateServer, workspaceKeyOfStatus, workspaceMismatch, SERVERS_FILE } = await kernelImport("servers", () => import("../lib/servers.mjs"));
75
+ const { readSessionViewer } = await kernelImport("session-viewer", () => import("../lib/session-viewer.mjs"));
76
+ const { tickTriggers } = await kernelImport("triggers", () => import("../lib/triggers.mjs"));
77
+ const A = await kernelImport("automations", () => import("../lib/automations.mjs"));
78
+ const { parseEnvelopeText, unresolvedScheduleAttempts, scheduleScopeOf, listSchedules, describe: describeSchedule, testSchedule, addSchedule, updateSchedule, updateScheduleDescription, setEnabled: setScheduleEnabled, removeSchedule, runNow: runScheduleNow, reconcile: reconcileSchedule, tickHost, tickWorkspace, scopeAutomations, scheduleKind, registerWorkspace, unregisterWorkspace, readRegistry, schedulerStatus, saveWakeForHome, removeWakeForHome, wakeFromFlags, withHostLock, scheduleError, SCHEDULE_API } = await kernelImport("schedule", () => import("../lib/schedule.mjs"));
79
+ const { hostUnitFiles, hostUnitStatus, installHostUnit, uninstallHostUnit } = await kernelImport("schedule-host", () => import("../lib/schedule-host.mjs"));
80
+ const { kernelNode, stableNode } = await kernelImport("stable-node", () => import("../lib/stable-node.mjs"));
81
+ const { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } = await kernelImport("attachments", () => import("../lib/attachments.mjs"));
82
+ const { observeInstanceGit, diffInstanceFile } = await kernelImport("instance-git", () => import("../lib/instance-git.mjs"));
83
+ const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstanceSameWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
84
+ const { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } = await kernelImport("retire-output", () => import("../lib/retire-output.mjs"));
85
+ const { livenessWord, lostLine, statusWord } = await kernelImport("status-words", () => import("../lib/status-words.mjs"));
86
+ const { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } = await kernelImport("retained-after-retire", () => import("../lib/retained-after-retire.mjs"));
68
87
  const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
69
- import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposition, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
70
- import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mjs";
71
- import { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } from "../lib/deployments.mjs";
72
- import { observeResolvedDeployment } from "../lib/resolved-deployment.mjs";
73
- import { SESSION_RESUME_FEATURE } from "../lib/session-resume-contract.mjs";
88
+ const { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposition, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } = await kernelImport("instance-inspect", () => import("../lib/instance-inspect.mjs"));
89
+ const { readEvents, setWaiting, incarnationOf } = await kernelImport("instance-events", () => import("../lib/instance-events.mjs"));
90
+ const { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } = await kernelImport("deployments", () => import("../lib/deployments.mjs"));
91
+ const { observeResolvedDeployment } = await kernelImport("resolved-deployment", () => import("../lib/resolved-deployment.mjs"));
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"));
74
99
 
75
100
  const rawArgs = process.argv.slice(2);
76
- /** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
77
- 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"]);
78
- /** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
79
- * routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
80
- * `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
81
- * expanded, it would be a flag token every reader sees, which the spaced form can never carry. */
82
- /** Free-text flags whose inline value may start with `--` (`--message=--deploy failed`). Such a
83
- * value is kept out of argv, where it would read as a flag (`--message=--clear` must not
84
- * clear), and flag() answers it from `inline`. */
85
- const INLINE_TEXT_FLAGS = new Set(["message"]);
86
- /** Free-text flags whose inline value is always kept whole, the empty one included:
87
- * `--description=` clears a trigger's or schedule's description. */
88
- const INLINE_WHOLE_FLAGS = new Set(["description"]);
89
- function expandInlineValues(argv) {
90
- const out = [];
91
- const inline = new Map();
92
- let problem;
93
- for (const a of argv) {
94
- const eq = a.indexOf("=");
95
- if (!a.startsWith("--") || eq <= 2) { out.push(a); continue; }
96
- const name = a.slice(2, eq), value = a.slice(eq + 1);
97
- if (INLINE_WHOLE_FLAGS.has(name) || (INLINE_TEXT_FLAGS.has(name) && value.startsWith("--"))) { inline.set(name, value); out.push(`--${name}`); continue; }
98
- 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;
99
- out.push(`--${name}`, value);
100
- }
101
- return { argv: out, problem, inline };
102
- }
103
101
  const { argv: args, problem: argvProblem, inline: inlineValues } = expandInlineValues(rawArgs);
104
102
  let cmd = args[0];
105
103
  const HELP_WORDS = new Set(["help", "--help", "-h"]);
106
- 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"]);
107
105
  /** Commands whose argv another parser reads (packages/record, packages/experimental and packages/tui parse process.argv). */
108
106
  const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental", "tui"]);
109
- /** The kernel features this binary implements: `features` in `version --json` (the Desktop API v1
110
- * probe) and in `status --json`, which a remote roster relays as the host's (feature
111
- * server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
112
- * time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
113
- 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"];
114
107
  /** Commands `--server <id>` runs on a registered server. */
115
108
  const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
116
- const flag = (name) => {
117
- const i = args.indexOf(`--${name}`);
118
- if (i >= 0 && inlineValues.has(name)) return inlineValues.get(name);
119
- return i >= 0 ? (args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : true) : undefined;
120
- };
109
+ const flag = (name) => flagValue(args, inlineValues, name);
121
110
  function yoloFlag() {
122
111
  if (args.includes("--yolo") && args.includes("--no-yolo")) cmdFail("E_BAD_ARGS", "choose --yolo or --no-yolo, not both");
123
112
  return args.includes("--yolo") ? true : args.includes("--no-yolo") ? false : undefined;
@@ -273,7 +262,7 @@ async function doctorComposition(ctx, soulName, ws, bail) {
273
262
  * rules. → { problems, information } */
274
263
  function doctorLocalTeams(local) {
275
264
  const standalone = typeof local.standalone === "string" && local.standalone !== "";
276
- const file = standalone ? null : cachedWorkspace(local.workspace)?.file ?? null;
265
+ const file = standalone ? null : cachedWorkspace(local.workspace, remoteOptionsFromEnv)?.file ?? null;
277
266
  const model = teamModel(file, local);
278
267
  const declared = ["teams", "defaultTeam"].some((k) => Object.hasOwn(local, k));
279
268
  return { problems: model.closedKeys.length ? [localTeamsClosedProblem(model.closedKeys)] : [],
@@ -813,11 +802,6 @@ async function doctorJson(dir) {
813
802
 
814
803
  /** The v2 doctor payload: the deployment declaration + lock (offline) and, with
815
804
  * --soul, the composed instructions. No v1 keys (chain/layers/acquired/injects…). */
816
- /** The problems doctor and status share for a v2 deployment: what OATS 0.25 left
817
- * under local-agents/ (named, never read), and the captured homes under the agents root. */
818
- function legacyLayoutProblems(root) {
819
- return [legacyLocalAgents(root), legacyCapturedHomes(root)].filter(Boolean);
820
- }
821
805
  /** What retires left in the deployment (#703 part 2a), read-only: the
822
806
  * `retained-recovery:` and `retained-worktree:` information lines, as one
823
807
  * block per kind (a count line, then one line per item). */
@@ -1630,7 +1614,7 @@ let maxAgeGiven = null;
1630
1614
  let readBudgetMs = null;
1631
1615
  function commandSession() {
1632
1616
  if (!readSession) {
1633
- readSession = remoteModule.createReadSession({ maxAge: maxAgeGiven ?? 0, ...(readBudgetMs !== null ? { deadline: Date.now() + readBudgetMs } : {}) });
1617
+ readSession = callSession({ maxAge: maxAgeGiven, budgetMs: readBudgetMs });
1634
1618
  process.on("exit", () => { sayReadNotices(); readSession.closeNow(); });
1635
1619
  for (const [signal, code] of [["SIGINT", 130], ["SIGTERM", 143], ["SIGHUP", 129]]) process.once(signal, () => {
1636
1620
  readSession.closeNow();
@@ -1687,8 +1671,29 @@ const withObservation = (doc) => (maxAgeGiven === null ? doc : { ...doc, observa
1687
1671
  /** Remote options threaded into every remote call. OATS_REMOTE_CACHE relocates
1688
1672
  * the content-addressed fetch cache (tests never touch ~/.cache); `session` is the command's read session. */
1689
1673
  function remoteOptionsFromEnv() {
1674
+ const cacheDir = remoteCacheDir();
1675
+ return { ...(cacheDir ? { cacheDir } : {}), session: commandSession() };
1676
+ }
1677
+ /** OATS_REMOTE_CACHE, absolute, or undefined. */
1678
+ function remoteCacheDir() {
1690
1679
  const cacheDir = process.env.OATS_REMOTE_CACHE;
1691
- 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);
1692
1697
  }
1693
1698
 
1694
1699
  /** The v2 deployment context at --dir: { dir, localPath, local, deploymentDir, remoteOptions }. */
@@ -1748,35 +1753,11 @@ function catalogForSync(bail) {
1748
1753
  catch (e) { return bail(e.code || "E_PACKAGE_MISSING", e.message); }
1749
1754
  }
1750
1755
 
1751
- /** The package requests of a standalone view: the catalog's own pin of the package
1752
- * providing oats.core (decision 25) — nothing else, since the version list lives in
1753
- * the workspace file we cannot read. The request is written as resolvePackages
1754
- * expects a CATALOG entry: the bare version (`v1.1.3`), never the catalog's raw ref
1755
- * (`oats-framework/v1.1.3` is a tag PATH the one grammar refuses); parsePackageRequest
1756
- * recomposes the tag from the catalog's own convention.
1757
- * → { packages: { <id>: <version> }, problems: [ { code: "E_PACKAGE_MISSING", … } ] } */
1758
- function standalonePackages(catalog) {
1759
- let id = "oats.framework";
1760
- const file = officialCatalogFile();
1761
- try { const alias = officialCapabilityAliases()["oats.core"]; id = (typeof alias === "string" ? alias : alias?.package) ?? id; } catch { /* the catalog is diagnosed below */ }
1762
- const version = standaloneCatalogVersion(catalog?.[id]?.ref);
1763
- if (version) return { packages: { [id]: version }, problems: [] };
1764
- const why = catalog?.[id] ? `its ref ${JSON.stringify(catalog[id].ref)} carries no version` : `it has no entry ${JSON.stringify(id)}`;
1765
- 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` }] };
1766
- }
1767
- /** The bare version of a catalog ref: its LAST path segment when that is a version
1768
- * (`v1.1.3` → `v1.1.3`; `oats-framework/v1.1.3` → `v1.1.3`; `main` → null). */
1769
- function standaloneCatalogVersion(ref) {
1770
- if (typeof ref !== "string" || !ref.trim()) return null;
1771
- const tail = ref.trim().split("/").filter(Boolean).pop() ?? "";
1772
- return classifyPackageValue(tail).kind === "catalog" ? tail : null;
1773
- }
1774
-
1775
1756
  /** Discover the workspace named by oats-local.yaml over the real remote. */
1776
1757
  async function discoverForCli(ctx, bail) {
1777
1758
  // The standalone case (decisions 10/25) is a discovery too: the repo's own view
1778
1759
  // plus the kernel's oats.core default — discoverOrStandalone decides.
1779
- try { const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs"); return await discoverOrStandalone(ctx.local, { deployment: ctx.deploymentDir, remoteOptions: ctx.remoteOptions }); }
1760
+ try { const { discoverOrStandalone } = await import("../lib/member-clone.mjs"); return await discoverOrStandalone(ctx.local, { deployment: ctx.deploymentDir, remoteOptions: ctx.remoteOptions }); }
1780
1761
  catch (e) {
1781
1762
  if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details ?? e.provenance);
1782
1763
  throw e;
@@ -1784,9 +1765,6 @@ async function discoverForCli(ctx, bail) {
1784
1765
  }
1785
1766
 
1786
1767
  const short = (oid) => (typeof oid === "string" ? oid.slice(0, 8) : "?");
1787
- /** Display name of a discovery: the workspace's name, or the standalone label (decision 10). */
1788
- const workspaceName = (discovery) => discovery.workspace?.name ?? `standalone:${memberLabel(discovery.key)}`;
1789
- const memberLabel = (key) => String(key).split("/").filter(Boolean).pop()?.replace(/\.git$/, "") || String(key);
1790
1768
  const originOf = (item) => (item.package ? `package ${item.package} v${item.version}` : `member ${item.repoKey} @ ${short(item.commit)}`);
1791
1769
 
1792
1770
  /** A soul's launch here (feature launch-preference): the `Launch` report a spawn with no flags would decide
@@ -1837,19 +1815,6 @@ function workspaceItems(discovery, lock, local, deploymentDir) {
1837
1815
  return { souls, capabilities };
1838
1816
  }
1839
1817
 
1840
- /** Membership rows for `sync` / `workspace status`. */
1841
- function memberRows(discovery) {
1842
- return discovery.members.map((m) => ({
1843
- key: m.key, name: memberLabel(m.key), commit: m.commit ?? null, confirmed: m.confirmed, status: m.confirmed ? "confirmed" : m.reason, detail: m.detail ?? null,
1844
- souls: m.souls.map((s) => s.name), capabilities: m.capabilities.map((c) => c.name), publishes: m.publishes ?? null,
1845
- }));
1846
- }
1847
-
1848
- /** Package rows for `sync` / `workspace status` from the lock. */
1849
- function packageRows(lock) {
1850
- 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) }));
1851
- }
1852
-
1853
1818
  /** Print a padded table: rows are arrays of strings. */
1854
1819
  function printTable(header, rows) {
1855
1820
  const all = [header, ...rows];
@@ -2165,38 +2130,17 @@ async function packageCmd() {
2165
2130
  : `Removed packages.${id} (${had}) from ${shortPath(checkout.file)}. Commit it, then \`oats sync\`.`);
2166
2131
  }
2167
2132
 
2168
- /** `oats workspace status [--dir] [--json]` — contract §6. */
2133
+ /** `oats workspace status [--dir] [--json]` — contract §6. The read is lib/workspace-read.mjs's. */
2169
2134
  async function workspaceCmd() {
2170
2135
  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
2171
2136
  if (args[1] !== "status") return bail("E_USAGE", "usage: oats workspace status [--dir <d>] [--json]");
2172
- const ctx = workspaceContext(bail);
2173
- const discovery = await discoverForCli(ctx, bail);
2174
- let lock;
2175
- try { lock = readLock(ctx.deploymentDir); } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
2176
- const members = memberRows(discovery);
2177
- const packages = packageRows(lock);
2178
- // Standalone (decision 10): there is no workspace file — the declared packages are the
2179
- // kernel's own default (decision 25) and there are no teams.
2180
- const standalone = discovery.standalone === true;
2181
- const declared = Object.keys(standalone ? standalonePackages(catalogForSync(bail)).packages : (discovery.workspace?.packages || {})).sort();
2182
- const locked = new Set(packages.map((p) => p.id));
2183
- const unsynced = declared.filter((id) => !locked.has(id));
2184
- const stale = packages.filter((p) => !declared.includes(p.id)).map((p) => p.id);
2185
- 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 ?? [])] };
2186
- // Workspace automations (0.29.0), from the snapshot `oats sync` took, placed on this host.
2187
- const actx = scopeAutomations(ctx.deploymentDir, {});
2188
- 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 } : {}) })) };
2189
- // Automation trust (0.30): a workspace automation placed here but not trusted, and a trust entry
2190
- // that names none, are warnings the operator acts on in oats-local.yaml.
2191
- for (const a of [...actx.triggers, ...actx.schedules].filter((x) => x.placement.reason === "untrusted")) {
2192
- 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) });
2193
- }
2194
- for (const entry of A.staleTrust(actx.host, [...actx.triggers, ...actx.schedules])) {
2195
- 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` });
2196
- }
2197
- await workspaceStatusFacts(result, discovery, lock, ctx);
2198
- if (JSON_MODE) { jsonOk(withObservation(result)); return; }
2199
- 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`);
2200
2144
  if (standalone) console.log(` (${standaloneNote(discovery)})\n`);
2201
2145
  console.log("Members:");
2202
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 ?? "?"}` : "—"]));
@@ -2213,44 +2157,7 @@ async function workspaceCmd() {
2213
2157
  }
2214
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}`); }
2215
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}` : ""}`); }
2216
- }
2217
-
2218
- /** The committed (shared) teams as `workspace status` reports them: rows in label order (team model v2). */
2219
- function sharedTeamRows(discovery) {
2220
- const teams = discovery.standalone === true ? {} : discovery.workspace?.teams || {};
2221
- 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 }));
2222
- }
2223
-
2224
- /** `oats workspace status` facts (feature desktop-facts): the workspace defaults as rows; this
2225
- * computer (member clones and the rule that found each, disabled souls, the lock); file locations with
2226
- * browsable urls; each catalog package's newer version, when the official catalog has one. */
2227
- async function workspaceStatusFacts(result, discovery, lock, ctx) {
2228
- const { memberCloneOf } = await import("../lib/instance-resolution.mjs");
2229
- const { browseUrl } = remoteModule;
2230
- const defaults = discovery.standalone === true ? {} : (discovery.workspace?.defaults ?? {});
2231
- 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));
2232
- const slot = (d) => (d && typeof d === "object" ? Object.entries(d).map(([name, v]) => ({ name, from: v?.from ?? null }))[0] ?? null : d ?? null);
2233
- result.defaults = {
2234
- slots: Object.fromEntries(LAYERS.map((l) => [l, slot(defaults[l])])),
2235
- capabilities: rows(defaults.capabilities),
2236
- };
2237
- result.workspace.file = discovery.standalone === true ? null : { path: "oats-workspace.yaml", url: browseUrl(discovery.key, discovery.commit, "oats-workspace.yaml") };
2238
- 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") } });
2239
- result.clones = result.members.map((m) => {
2240
- try { return { key: m.key, name: m.name, ...memberCloneOf(ctx.deploymentDir, ctx.local, m.key) }; }
2241
- 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; }
2242
- });
2243
- result.disabledSouls = [...(Array.isArray(ctx.local?.souls?.disabled) ? ctx.local.souls.disabled : [])];
2244
- result.lock = { path: join(ctx.deploymentDir, LOCK_FILE), lockfileVersion: lock.lockfileVersion ?? null };
2245
- const { compareSemver } = await import("../lib/servers.mjs");
2246
- let catalog = null; try { catalog = officialPackageCatalog(); } catch { catalog = null; }
2247
- const cat = catalog && typeof catalog === "object" ? (catalog.packages && typeof catalog.packages === "object" && !("url" in catalog.packages) ? catalog.packages : catalog) : {};
2248
- for (const p of result.packages) {
2249
- const ref = p.source === `catalog:${p.id}` ? cat[p.id]?.ref : undefined;
2250
- const tag = standaloneCatalogVersion(ref);
2251
- const version = tag ? tag.replace(/^v/, "") : null;
2252
- p.latest = version && typeof p.version === "string" && compareSemver(version, p.version) > 0 ? { version, ref } : null;
2253
- }
2160
+ process.stderr.write(read.stderr);
2254
2161
  }
2255
2162
 
2256
2163
  /** The deployment's team facts for the team verbs: oats-local.yaml, the committed workspace file and the
@@ -2635,125 +2542,6 @@ async function soulFacts(rows, discovery, lock, ctx, remote = remoteModule) {
2635
2542
  }
2636
2543
 
2637
2544
  // ---------- roster: status / spawn / retire / create ----------
2638
- /** Workspace drift for `oats status` (decision 17: shown, not prevented). ONE discovery over
2639
- * the remotes serves every instance; `driftOf` compares each instance's recorded modules to
2640
- * the members' current state (and package modules to the lock), `soulDriftOf` the instance's
2641
- * recorded SOUL SOURCE (instance.json.workspace.soul) to its member's current commit. Offline →
2642
- * { unreachable }. Returns null when the deployment is not a workspace deployment (no
2643
- * oats-local.yaml). `souls` maps each workspace soul NAME (agents/<name>/.oats-soul-source.json
2644
- * present) to its stamp — the roster's `repo:` column for a workspace soul. */
2645
- async function statusDrift(data) {
2646
- let ctx;
2647
- try { ctx = loadLocal(dirFlag()); }
2648
- catch (e) {
2649
- if (e?.code === "E_LOCAL_MISSING") return null;
2650
- // A 0.25 oats-config.yaml inside the deployment: the typed migration error, never a stack.
2651
- if (e?.code === "E_CONFIG_BROKEN") { if (JSON_MODE) jsonFail(e.code, e.message, e.details); die(e.message); }
2652
- throw e;
2653
- }
2654
- const hasModules = (i) => i.modules && typeof i.modules === "object" && Object.keys(i.modules).length > 0;
2655
- const hasSoul = (i) => i.workspace && typeof i.workspace === "object" && i.workspace.soul && typeof i.workspace.soul === "object" && typeof i.workspace.soul.repoKey === "string";
2656
- // Workspace souls of this roster: the stamp ensureWorkspaceSoul leaves beside the soul pointer.
2657
- const souls = new Map();
2658
- for (const a of data) {
2659
- if (!a.dir) continue;
2660
- 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 } : {}) }); }
2661
- catch { /* not a workspace soul (classic, or an unreadable stamp) */ }
2662
- }
2663
- const anything = data.some((a) => (a.instances || []).some((i) => hasModules(i) || hasSoul(i)));
2664
- if (!anything) return { drift: new Map(), soul: new Map(), souls, unreachable: null, local: ctx.local, discovery: null };
2665
- const deploymentDir = dirname(ctx.path);
2666
- let lock = null;
2667
- try { lock = readLockIfPresent(deploymentDir); } catch { lock = null; }
2668
- let discovery;
2669
- // The standalone view (decisions 10/25) is a discovery too: drift of a standalone
2670
- // instance is computed against its member's current state, not reported "unreachable".
2671
- try { const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs"); discovery = await discoverOrStandalone(ctx.local, { lock, remoteOptions: remoteOptionsFromEnv() }); }
2672
- catch (e) {
2673
- const reason = e?.details?.reason ? `${e.code}: ${e.details.reason}` : (e?.code || e?.message || "unknown");
2674
- return { drift: new Map(), soul: new Map(), souls, unreachable: { code: e?.code ?? null, reason, message: e?.message ?? String(e) }, local: ctx.local, discovery: null };
2675
- }
2676
- const { driftOf, soulDriftOf } = await import("../lib/materialize.mjs");
2677
- const drift = new Map();
2678
- const soul = new Map();
2679
- for (const a of data) for (const i of a.instances || []) {
2680
- const key = i.home ?? `${a.name}/${i.instance}`;
2681
- if (hasModules(i)) { try { drift.set(key, driftOf(i, discovery, { lock })); } catch { /* an unreadable module record shows as no drift rows */ } }
2682
- 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 */ } }
2683
- }
2684
- // The roster's soul row reflects the CURRENT member commit too (the pointer may lag a moved member).
2685
- // First match per key, as `find` gave, from indexes built once (not a scan per agent).
2686
- const packageSoulAt = new Map();
2687
- for (const p of discovery.packageSouls || []) { const k = `${p.package}\0${p.path}`; if (!packageSoulAt.has(k)) packageSoulAt.set(k, p); }
2688
- for (const [, stamp] of souls) {
2689
- if (typeof stamp.package === "string") { const now = packageSoulAt.get(`${stamp.package}\0${stamp.path}`); if (now) stamp.current = now.commit; continue; }
2690
- const member = memberRowByKey(discovery.members, stamp.repoKey);
2691
- if (member && typeof member.commit === "string" && (member.confirmed || (discovery.standalone === true && member.key === discovery.key))) stamp.current = member.commit;
2692
- }
2693
- return { drift, soul, souls, unreachable: null, local: ctx.local, discovery };
2694
- }
2695
- /** The deployment's workspace identity in `oats status --json` (feature workspace-identity), read
2696
- * OFFLINE. `key` is the workspace HOST's canonical repo key (parseRepoRef(...).key) and `ref` the
2697
- * reference as oats-local.yaml writes it. The host is the one this run observed, else the one this
2698
- * machine's parsed cache knows: `ref` itself when the cache holds its workspace file, or the host its
2699
- * cached oats-membership.yaml names when `ref` is a member ("workspace"). A member whose host is not
2700
- * known keys as itself ("member"); a ref nothing is known of is taken as the host, as the schema
2701
- * defines `workspace:` ("workspace"). The team model resolves as teamModel resolves it (the default is
2702
- * 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
2703
- * file this run observed (`teamsFrom: "observed"`), the cached file ("cache": no git process), or none
2704
- * ("local"). `standalone` is the CONFIGURED standalone view only (oats-local.yaml `standalone:`): it
2705
- * reads no workspace file, so its local teams are the whole team model. A run that fell back to the
2706
- * standalone view (the host unreadable) is not: its team model is the workspace's, and its
2707
- * discovery is the member's, never the host's key. */
2708
- function workspaceIdentity(local, discovery) {
2709
- const ref = local.workspace;
2710
- const standalone = typeof local.standalone === "string" && local.standalone !== "";
2711
- const observed = discovery && discovery.standalone !== true && discovery.workspace ? discovery : null;
2712
- const cached = observed ? null : cachedWorkspace(ref);
2713
- const keyOf = (r) => { try { return remoteModule.parseRepoRef(r).key; } catch { return null; } };
2714
- let key, keyFrom;
2715
- if (observed) [key, keyFrom] = [observed.key, "workspace"];
2716
- else if (cached && cached.host === null) [key, keyFrom] = [keyOf(ref), "member"];
2717
- else [key, keyFrom] = [keyOf(cached?.host ?? ref), "workspace"];
2718
- if (key === null) keyFrom = null; // a reference parseRepoRef refuses: unusable, never matched
2719
- let shared = null, teamsFrom = "local";
2720
- if (!standalone) {
2721
- if (observed) [shared, teamsFrom] = [observed.workspace, "observed"];
2722
- else if (cached?.file) [shared, teamsFrom] = [cached.file, "cache"];
2723
- }
2724
- const model = teamModel(shared, local);
2725
- // A soul with no souls: default of its own lives here (team model 3: the local default the workspace allows, else the workspace's).
2726
- const deploymentDefault = model.localDefault ?? model.workspaceDefault;
2727
- const labels = [...model.labels.keys()].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
2728
- return {
2729
- key, ref, keyFrom, standalone,
2730
- defaultTeam: deploymentDefault === null ? null : { label: deploymentDefault, team: model.labels.get(deploymentDefault)?.team ?? null },
2731
- teams: Object.fromEntries(labels.map((l) => [l, model.labels.get(l).team])),
2732
- teamsFrom,
2733
- };
2734
- }
2735
- /** What this machine's parsed cache knows of the workspace `ref` names (the values observeWorkspace and
2736
- * confirmMembership stored, each at its repo's last observed commit): { host, file } — `host` the ref
2737
- * of the workspace host, `file` its workspace file or null — when `ref` is the host (its workspace file
2738
- * is cached) or a member whose cached oats-membership.yaml names it (discoverOrStandalone follows the
2739
- * same backlink). A member's backlink is cached whether its own workspace slot was observed (missing)
2740
- * or never was (the host's discovery confirmed it). { host: null, file: null } for a ref cached as
2741
- * having no workspace file and no backlink; null when nothing is known. */
2742
- function cachedWorkspace(ref) {
2743
- const options = remoteOptionsFromEnv();
2744
- const cached = (r, item) => {
2745
- const commit = remoteModule.lastObservedCommit(r, options);
2746
- const value = commit ? remoteModule.peekAtCommit(r, commit, item, options) : undefined;
2747
- return value && typeof value === "object" ? value : null;
2748
- };
2749
- const fileOf = (read) => (read && !read.missing && !read.problems && read.value && typeof read.value === "object" ? read.value : null);
2750
- const read = cached(ref, "workspace");
2751
- if (read && !read.missing) return { host: ref, file: fileOf(read) };
2752
- const membership = cached(ref, "membership");
2753
- const host = membership?.kind === "ok" && typeof membership.value?.workspace === "string" ? membership.value.workspace : null;
2754
- if (host !== null) return { host, file: fileOf(cached(host, "workspace")) };
2755
- return read ? { host: null, file: null } : null;
2756
- }
2757
2545
  /** One `modules:` line per module. */
2758
2546
  function driftLine(row) {
2759
2547
  const from = row.from || {};
@@ -2784,47 +2572,20 @@ function soulRepoLabel(a, ws) {
2784
2572
  const moved = stamp.current && stamp.commit && stamp.current !== stamp.commit ? ` (member now @ ${short7(stamp.current)})` : "";
2785
2573
  return `${memberLabel(stamp.repoKey)} @ ${short7(stamp.commit)}${moved}`;
2786
2574
  }
2787
- /** A roster agent's soul key: the qualified name of a package soul, else the recorded agent (soul) name;
2788
- * null when no instance records a workspace soul. Exactly soulKeyOf for the soul it was spawned from. */
2789
- function agentSoulKey(a) {
2790
- for (const i of a.instances || []) {
2791
- const soul = i?.workspace?.soul;
2792
- if (!soul || typeof soul !== "object") continue;
2793
- return soul.package && typeof soul.qualifiedName === "string" ? soul.qualifiedName : (typeof i.agent === "string" ? i.agent : a.name);
2794
- }
2795
- return null;
2796
- }
2797
2575
  const short7 = (oid) => (typeof oid === "string" ? oid.slice(0, 7) : "?");
2798
2576
 
2577
+ /** `oats status [--dir] [--verbose] [--json]`. The read is lib/roster-read.mjs's; `--team` is refused
2578
+ * before --dir is read. */
2799
2579
  async function status() {
2800
- 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); }
2801
- let root;
2802
- try { root = ensureRoot(dirFlag()); }
2803
- 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; }
2804
- const data = listInstances(root);
2805
- const ws = await statusDrift(data);
2806
- const verbose = args.includes("--verbose");
2807
- const problems = legacyLayoutProblems(root);
2808
- if (args.includes("--json")) {
2809
- // The soul key (feature launch-preference): what souls.launch and `oats soul teams <key>` use —
2810
- // from the instances' records, so it needs no remote.
2811
- for (const a of data) a.key = agentSoulKey(a);
2812
- if (ws) for (const a of data) {
2813
- const stamp = ws.souls.get(a.name);
2814
- 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" } : {}) };
2815
- for (const i of a.instances || []) {
2816
- const key = i.home ?? `${a.name}/${i.instance}`;
2817
- const rows = ws.drift.get(key);
2818
- 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 } : {}) }));
2819
- const s = ws.soul.get(key);
2820
- 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 } : {}) };
2821
- }
2822
- }
2823
- const observation = maxAgeGiven === null ? {} : { observation: observationBlock() };
2824
- // `features` (feature server-probe-features): this kernel's own list, as `version --json` answers
2825
- // it, so a remote roster relays the host's without probing it. Never part of a reused observation.
2826
- 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;
2827
- }
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) {
2828
2589
  console.log(`oats status — agents root ${shortPath(root)}\n`);
2829
2590
  if (ws?.unreachable) console.log(` workspace: unreachable (${ws.unreachable.reason}) — drift unknown\n`);
2830
2591
  for (const p of problems) console.log(` ! ${p.code}: ${p.message}\n`);
@@ -2834,7 +2595,8 @@ async function status() {
2834
2595
  if (a.description) console.log(` ${a.description}`);
2835
2596
  for (const i of a.instances) {
2836
2597
  // Feature instance-background: the row is marked; it is listed like any other.
2837
- console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${i.retirePending ? "RETIRING" : livenessWord(i)} (branch ${i.branch || "?"}, ${i.work || "?"})${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
2598
+ console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${statusWord(i)} (branch ${i.branch || "?"}, ${i.work || "?"})${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
2599
+ { const lost = lostLine(i); if (lost) console.log(` ${lost}`); }
2838
2600
  // Feature waiting-on-you: non-null only on a running row; the reader has
2839
2601
  // already validated the message (one line, no control characters).
2840
2602
  if (i.running === true && i.waitingOnYou) console.log(` ! needs input (${i.waitingOnYou.reason ?? "unknown"})${i.waitingOnYou.message ? `: ${i.waitingOnYou.message}` : ""}`);
@@ -2854,8 +2616,6 @@ async function status() {
2854
2616
  }
2855
2617
  }
2856
2618
 
2857
- /** A status row's liveness in text: `running` null (a server that cannot be read, a Herdr home) is unknown, never idle. */
2858
- const livenessWord = (i) => i.running === true ? "RUNNING" : i.running === false ? "idle" : "unknown";
2859
2619
  /** The flags `oats spawn` reads: those taking a value, and switches. `--provider` takes two words.
2860
2620
  * `--instance` is refused by a local spawn (with its replacement) but still travels to an older
2861
2621
  * host through `--server`, whose route reads it. `--max-age` reaches here only on a preview or an
@@ -4355,6 +4115,14 @@ function updateCmd() {
4355
4115
  }
4356
4116
 
4357
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
+
4358
4126
  function versionCmd() {
4359
4127
  if (JSON_MODE) {
4360
4128
  // EXACT Desktop API v1 probe payload — one JSON object, nothing else on
@@ -4368,7 +4136,7 @@ function versionCmd() {
4368
4136
  // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
4369
4137
  // runs on resolve/materialize (contract §6); a feature the binary does not implement is
4370
4138
  // never listed.
4371
- 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() }));
4372
4140
  return;
4373
4141
  }
4374
4142
  console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -4462,7 +4230,10 @@ async function serverCmd() {
4462
4230
  for (const g of out.groups) {
4463
4231
  console.log(` ${g.server}${g.label && g.label !== g.server ? ` ${g.label}` : ""} [${g.id}] ssh ${g.target.sshHost} workspace ${g.target.workspace}${g.registrationPresent ? "" : " (registration removed or changed; saved routes only)"}`);
4464
4232
  console.log(g.probe?.ok ? ` reachable, ${g.souls.length} soul(s)` : ` UNREACHABLE: ${g.probe?.error?.message || "?"}`);
4465
- for (const i of g.instances) console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${i.missingRemotely ? "GONE on the host (saved route is stale: oats server forget)" : i.running === true ? "RUNNING" : i.running === false ? "idle" : "unknown"}${i.retirePending ? " RETIRING" : ""}${i.rollbackIncomplete ? " QUARANTINED" : ""}${i.savedRoute ? "" : " (observed only, no saved route)"}${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
4233
+ for (const i of g.instances) {
4234
+ console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${i.missingRemotely ? "GONE on the host (saved route is stale: oats server forget)" : livenessWord(i)}${i.retirePending ? " RETIRING" : ""}${i.rollbackIncomplete ? " QUARANTINED" : ""}${i.savedRoute ? "" : " (observed only, no saved route)"}${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
4235
+ const lost = lostLine(i, { host: g.target.sshHost || g.server }); if (lost) console.log(` ${lost}`);
4236
+ }
4466
4237
  for (const f of g.retireFailures || []) console.log(` ! deferred retirement of ${f.instance} (${f.agent}) FAILED there${f.error?.message ? `: ${f.error.message}` : ""}${f.retry ? ` — retry on the host: ${f.retry}` : ""}`);
4467
4238
  }
4468
4239
  console.log(` bounds: ${out.bounds.perTargetTimeoutMs} ms per target within ${out.bounds.budgetMs} ms, ${out.bounds.elapsedMs} ms used`);
@@ -4859,7 +4630,10 @@ async function serverRouteCmd() {
4859
4630
  console.log(`oats status — server ${id} (ssh ${r.target.sshHost}, workspace ${r.target.workspace})\n`);
4860
4631
  for (const a of r.agents || []) {
4861
4632
  console.log(` ${a.name} [work: ${a.work || "checkout"}, repo: ${a.repo || "?"}]`);
4862
- for (const i of a.instances || []) console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${i.retirePending ? "RETIRING" : livenessWord(i)}${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
4633
+ for (const i of a.instances || []) {
4634
+ console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${statusWord(i)}${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
4635
+ const lost = lostLine(i, { host: r.target.sshHost || id }); if (lost) console.log(` ${lost}`);
4636
+ }
4863
4637
  }
4864
4638
  const snaps = r.snapshots || [];
4865
4639
  if (snaps.length) console.log(`\n spawned from this machine: ${snaps.map((s) => s.instance).join(", ")}`);
@@ -4903,18 +4677,17 @@ try {
4903
4677
  if (kernelArgv && head.includes("--max-age")) {
4904
4678
  const refusal = maxAgeRefusal(cmd, head);
4905
4679
  if (refusal) cmdFail("E_BAD_ARGS", refusal);
4906
- const raw = flag("max-age");
4907
- if (raw === true) cmdFail("E_BAD_ARGS", `--max-age needs a value: whole seconds from 0 to ${remoteModule.MAX_AGE_LIMIT}`);
4908
- 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)}`);
4909
- maxAgeGiven = Number(raw);
4680
+ const { maxAge, refusal: badAge } = parseMaxAge(flag("max-age"));
4681
+ if (badAge) cmdFail(badAge.code, badAge.message);
4682
+ maxAgeGiven = maxAge;
4910
4683
  activateLocalInputs(); // observation.localRevision: every local config read from here on is recorded
4911
4684
  }
4912
4685
  if (kernelArgv && !head.includes("--server") && (cmd === "status" || (cmd === "workspace" && head[1] === "status"))) {
4913
- const override = Number(process.env.OATS_READ_REMOTE_BUDGET_MS);
4914
- readBudgetMs = Number.isSafeInteger(override) && override > 0 ? override : remoteModule.READ_REMOTE_BUDGET_MS;
4686
+ readBudgetMs = readBudget(process.env);
4915
4687
  }
4916
- const inherited = ["OATS_RESOLUTION", "OATS_DEPLOYMENT"].filter((k) => process.env[k]);
4917
- 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);
4918
4691
  if (cmd === "inspect" && head.includes("--request")) {
4919
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";
4920
4693
  if (JSON_MODE) jsonFail("E_UNKNOWN_COMMAND", message, { removed: "inspect --request", replacement: "oats onboard / oats sync; oats spawn --preview" });
@@ -4979,6 +4752,7 @@ else if (cmd === "status") await status();
4979
4752
  else if (cmd === "pane") await paneCmd();
4980
4753
  else if (cmd === "tui") await tuiCmd();
4981
4754
  else if (cmd === "version" || cmd === "--version" || cmd === "-v") versionCmd();
4755
+ else if (cmd === "reader") await readerCmd();
4982
4756
  else if (cmd === "session") await sessionCmd();
4983
4757
  else if (cmd === "schedule") await scheduleCmd();
4984
4758
  else if (cmd === "trigger") await triggerCmd();
@@ -5043,6 +4817,9 @@ Usage:
5043
4817
  Desktop CLI API v1 probe payload
5044
4818
  oats status [--json] agents, souls, running instances
5045
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")
5046
4823
  oats tui [--dir <path>] [--ascii] PREVIEW: the full-screen terminal client (docs/tui.md):
5047
4824
  the instances of the workspace of the deployment at or
5048
4825
  above <path> (default: where you are), on this machine