@awebai/oats 0.51.0 → 0.52.0

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 (128) hide show
  1. package/README.md +1 -0
  2. package/bin/oats.mjs +109 -37
  3. package/docs/capabilities.md +9 -2
  4. package/docs/configuration.md +134 -88
  5. package/docs/desktop-cli-api.md +927 -92
  6. package/docs/desktop-instance-start.md +56 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +144 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +66 -9
  12. package/docs/integrations.md +9 -8
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +25 -2
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/oats-local.schema.json +4 -3
  20. package/docs/official-catalog.md +4 -4
  21. package/docs/packages.md +14 -14
  22. package/docs/release-lane.md +15 -5
  23. package/docs/release-notes/v0.44.0.md +1 -1
  24. package/docs/release-notes/v0.52.0.md +933 -0
  25. package/docs/schedules.md +91 -4
  26. package/docs/souls-and-instances.md +95 -25
  27. package/docs/tui.md +152 -0
  28. package/docs/workspaces.md +2 -2
  29. package/lib/claim.mjs +186 -46
  30. package/lib/core.mjs +730 -185
  31. package/lib/errors.mjs +170 -0
  32. package/lib/harness-trust-write.mjs +68 -27
  33. package/lib/harness-trust.mjs +34 -16
  34. package/lib/instance-inspect.mjs +40 -11
  35. package/lib/instance-lifecycle.mjs +169 -47
  36. package/lib/launch-preference.mjs +16 -0
  37. package/lib/launch-prompt-completion.mjs +7 -43
  38. package/lib/launch-prompt-evidence.mjs +14 -7
  39. package/lib/launch-prompt-fixtures/README.md +86 -152
  40. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  41. package/lib/launch-prompt-fixtures.mjs +122 -109
  42. package/lib/launch-prompt-transport.mjs +2 -56
  43. package/lib/launch-prompts.mjs +102 -100
  44. package/lib/schedule-host.mjs +154 -22
  45. package/lib/schedule.mjs +73 -24
  46. package/lib/system-tools.mjs +39 -0
  47. package/lib/tmux-server-scope.mjs +62 -0
  48. package/lib/triggers.mjs +4 -4
  49. package/lib/workspace.mjs +5 -11
  50. package/lib/worktree-hooks.mjs +98 -20
  51. package/lib/worktree.mjs +83 -24
  52. package/package-catalog.json +3 -3
  53. package/package.json +7 -2
  54. package/packages/client/capability-show-contract.mjs +230 -0
  55. package/packages/client/capability-warnings-contract.mjs +57 -0
  56. package/packages/client/cli-adapter.mjs +548 -0
  57. package/packages/client/cli-environment.mjs +53 -0
  58. package/packages/client/cli-locator.mjs +253 -0
  59. package/packages/client/cli-probe-contract.mjs +47 -0
  60. package/packages/client/client-terms.mjs +60 -0
  61. package/packages/client/deployment-contract.mjs +68 -0
  62. package/packages/client/deployment-data.mjs +483 -0
  63. package/packages/client/deployment-facts.mjs +34 -0
  64. package/packages/client/deployment-label.mjs +76 -0
  65. package/packages/client/deployment-observer.mjs +89 -0
  66. package/packages/client/deployment-panel.mjs +142 -0
  67. package/packages/client/deployment-read-cli.mjs +53 -0
  68. package/packages/client/display-text.mjs +44 -0
  69. package/packages/client/harness-names.mjs +30 -0
  70. package/packages/client/inspect-contract.mjs +62 -0
  71. package/packages/client/instance-acts.mjs +54 -0
  72. package/packages/client/instance-admission.mjs +45 -0
  73. package/packages/client/instance-events-contract.mjs +74 -0
  74. package/packages/client/instance-git-contract.mjs +80 -0
  75. package/packages/client/instance-presentation.mjs +22 -0
  76. package/packages/client/instance-tree.mjs +453 -0
  77. package/packages/client/kernel-environment.mjs +11 -0
  78. package/packages/client/launch-contract.mjs +51 -0
  79. package/packages/client/launch-prompt-outcome.mjs +165 -0
  80. package/packages/client/lifecycle-cli.mjs +61 -0
  81. package/packages/client/lifecycle-contract.mjs +372 -0
  82. package/packages/client/liveness-main.mjs +10 -0
  83. package/packages/client/liveness.mjs +35 -0
  84. package/packages/client/machine-contract.mjs +123 -0
  85. package/packages/client/own-environment.mjs +22 -0
  86. package/packages/client/panel-views.mjs +286 -0
  87. package/packages/client/readiness-contract.mjs +172 -0
  88. package/packages/client/refresh-loop.mjs +52 -0
  89. package/packages/client/remote-address.mjs +126 -0
  90. package/packages/client/remote-roster.mjs +67 -0
  91. package/packages/client/roster-sections.mjs +80 -0
  92. package/packages/client/spawn-apply-cli.mjs +104 -0
  93. package/packages/client/spawn-apply-contract.mjs +183 -0
  94. package/packages/client/spawn-decision.mjs +46 -0
  95. package/packages/client/spawn-messages.mjs +119 -0
  96. package/packages/client/spawn-preview-cli.mjs +32 -0
  97. package/packages/client/spawn-preview-contract.mjs +314 -0
  98. package/packages/client/team-members.mjs +41 -0
  99. package/packages/client/team-rows.mjs +45 -0
  100. package/packages/client/terminal-contract.mjs +57 -0
  101. package/packages/client/tmux-status.mjs +66 -0
  102. package/packages/client/waiting-on-you.mjs +88 -0
  103. package/packages/client/workspace-admission.mjs +45 -0
  104. package/packages/client/workspace-cli.mjs +142 -0
  105. package/packages/client/workspace-views.mjs +147 -0
  106. package/packages/tui/README.md +46 -0
  107. package/packages/tui/bin/tui.mjs +7 -0
  108. package/packages/tui/lib/actions.mjs +29 -0
  109. package/packages/tui/lib/client.mjs +4 -0
  110. package/packages/tui/lib/main.mjs +105 -0
  111. package/packages/tui/lib/term/keys.mjs +323 -0
  112. package/packages/tui/lib/term/screen.mjs +122 -0
  113. package/packages/tui/lib/term/style.mjs +43 -0
  114. package/packages/tui/lib/term/text.mjs +49 -0
  115. package/packages/tui/lib/term/tty.mjs +168 -0
  116. package/packages/tui/lib/term/width.mjs +124 -0
  117. package/packages/tui/lib/views/frame.mjs +62 -0
  118. package/packages/tui/lib/views/help.mjs +28 -0
  119. package/packages/tui/package.json +8 -0
  120. package/skills/oats-getting-started/SKILL.md +29 -22
  121. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  122. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  123. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  124. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  125. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  126. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  127. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  128. package/lib/launch-prompt-policy.mjs +0 -87
package/README.md CHANGED
@@ -228,6 +228,7 @@ Further documentation:
228
228
  - [Packages](docs/packages.md)
229
229
  - [Sessions](docs/execution-targets.md)
230
230
  - [OATS Desktop](docs/desktop.md)
231
+ - [OATS TUI](docs/tui.md), the terminal client (`oats tui`, a preview)
231
232
 
232
233
  This README explains the framework and its direction. Advanced mechanisms such as automatic speciation and context cloning require their own implementation and verification; the model is not a claim that every feature or capability combination already works.
233
234
 
package/bin/oats.mjs CHANGED
@@ -24,13 +24,14 @@ import { execFileSync, spawnSync } from "node:child_process";
24
24
  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
+ import { performance } from "node:perf_hooks";
27
28
  import { runtimeNameWarning, noteRuntimeName } from "../lib/deprecation.mjs";
28
- import { herdrSettingRemoved } from "../lib/errors.mjs";
29
+ import { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect } from "../lib/errors.mjs";
29
30
  import {
30
31
  LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
31
32
  capabilityManifests, capabilityTrust, capabilityExecutablePath,
32
33
  officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
33
- findInstanceHome, findInstanceHomes, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchPromptPolicyAt, LAUNCH_PROMPT_UPDATE_WARNING, 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,
34
+ findInstanceHome, findInstanceHomes, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, 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,
34
35
  FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
35
36
  } from "../lib/core.mjs";
36
37
  import {
@@ -49,11 +50,11 @@ import { spawnSync as spawnSyncProc } from "node:child_process";
49
50
  import { tickTriggers } from "../lib/triggers.mjs";
50
51
  import * as A from "../lib/automations.mjs";
51
52
  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";
52
- import { hostUnitStatus, installHostUnit, uninstallHostUnit } from "../lib/schedule-host.mjs";
53
+ import { hostUnitFiles, hostUnitStatus, installHostUnit, uninstallHostUnit } from "../lib/schedule-host.mjs";
53
54
  import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
54
55
 
55
56
  import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
56
- import { planStop, applyStop, planRetire, descendantsOf, resolveInstance as resolveInstanceForCli } from "../lib/instance-lifecycle.mjs";
57
+ import { planStop, applyStop, planRetire, descendantsOf, resolveInstance as resolveInstanceForCli, STOP_WARNINGS } from "../lib/instance-lifecycle.mjs";
57
58
  import { extraWorktreeLines, formatBytes, workRecoveryLines } from "../lib/retire-output.mjs";
58
59
  import { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } from "../lib/retained-after-retire.mjs";
59
60
  const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
@@ -91,14 +92,14 @@ function expandInlineValues(argv) {
91
92
  const { argv: args, problem: argvProblem, inline: inlineValues } = expandInlineValues(rawArgs);
92
93
  let cmd = args[0];
93
94
  const HELP_WORDS = new Set(["help", "--help", "-h"]);
94
- const KERNEL_COMMANDS = new Set(["harness", "automations", "trigger", "capture", "capabilities", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "update", "version", "workspace", "worktree"]);
95
- /** Commands whose argv another parser reads (packages/record and packages/experimental parse process.argv). */
96
- const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental"]);
95
+ const KERNEL_COMMANDS = new Set(["harness", "automations", "trigger", "capture", "capabilities", "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"]);
96
+ /** Commands whose argv another parser reads (packages/record, packages/experimental and packages/tui parse process.argv). */
97
+ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental", "tui"]);
97
98
  /** The kernel features this binary implements: `features` in `version --json` (the Desktop API v1
98
99
  * probe) and in `status --json`, which a remote roster relays as the host's (feature
99
100
  * server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
100
101
  * time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
101
- 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"];
102
+ 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"];
102
103
  /** Commands `--server <id>` runs on a registered server. */
103
104
  const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
104
105
  const flag = (name) => {
@@ -177,6 +178,23 @@ const withLocalWarnings = (envelope) => {
177
178
  return { ...envelope, warnings: theirs.map((w) => (w === same ? { ...mine, sources, message: mine.message.replace(/\(.*\)/, `(${sources.join("; ")})`) } : w)) };
178
179
  };
179
180
  const jsonFail = (code, message, details, exit = 1) => { console.log(JSON.stringify({ schemaVersion: 1, ok: false, error: { code, message: String(message), ...(details !== undefined ? { details } : {}) }, ...envelopeWarnings() })); process.exit(exit); };
181
+ /** The door of the lifecycle verbs (retire, instance stop, session, worktree; awebai/oats#892): the
182
+ * answer to an error `e` of one of them. Its code is the error's own only when that is a kernel
183
+ * code (lib/errors.mjs isKernelCode); any other error is answered as `fallback`. One that has a
184
+ * code (the system's, Node's) and a defect (isDefect: a TypeError and its kind) get
185
+ * `details.cause` beside the command's `details`, and a defect's stack goes to stderr, in both
186
+ * modes: the answer must not swallow it. A plain Error without a code is a refusal the kernel
187
+ * wrote without one, or a child process that failed: the fallback and its message, nothing more.
188
+ * A typed failure that is not a code (TYPED_CLI_FAILURES) keeps its name, as before. Text mode
189
+ * prints the same message, with the same exit status. */
190
+ const lifecycleFail = (e, fallback, details, exit) => {
191
+ const message = String(e?.message ?? e);
192
+ if (TYPED_CLI_FAILURES.has(e?.code)) return JSON_MODE ? jsonFail(e.code, message, details, exit) : die(message, exit);
193
+ reportDefect(e);
194
+ const cause = isAnswerCode(e?.code) ? undefined : errorCause(e);
195
+ const all = cause ? { ...details, cause } : details;
196
+ return JSON_MODE ? jsonFail(kernelCode(e, fallback), message, all, exit) : die(message, exit);
197
+ };
180
198
  const jsonOk = (result) => { console.log(JSON.stringify({ schemaVersion: 1, ok: true, result, ...envelopeWarnings() })); };
181
199
  // Text mode (or a JSON answer printed before the read): the warning goes to stderr, never stdout.
182
200
  process.on("exit", () => { const w = runtimeNameWarning(); if (w && !warningDelivered) process.stderr.write(`oats: warning: ${w.message}\n`); });
@@ -945,8 +963,8 @@ function launchPreview(bail) {
945
963
  // selection the planner refuses it (E_LAUNCH_LEGACY: re-spawn it from the deployment).
946
964
  let d, frozen;
947
965
  try { frozen = withSafeTaskPrompt(meta.command, meta.harness); d = describeLaunchCommand(frozen); } catch (e) { bail(e.code || "E_LAUNCH_COMMAND_UNSUPPORTED", e.message); }
948
- const launchPromptAnswers = launchPromptPolicyAt(dirname(dirname(dirname(dirname(home)))), home);
949
- jsonOk({ context, selected, launchPromptAnswers, ...(launchPromptAnswers.awebDevelopmentChannel ? { warnings: [LAUNCH_PROMPT_UPDATE_WARNING] } : {}), selection: { source: "frozen-command", launchConfig: null, harness: null, model: null, yolo: null }, harness: meta.harness, model: meta.model || null, modelSource: meta.model ? "recorded" : "native default", yolo: meta.yolo ?? null, launchConfig: null, launchConfigSource: null, launchConfigDefault: false, executable: { path: d.executable, declared: null, resolvedFrom: "recorded" }, argv: d.argv, environment: d.environment, command: redactLaunchCommand(frozen), prompt: { kind: "task-file", file: "TASK.md" }, hooks: null, preflight: [{ check: "recipe", ok: true, detail: "frozen command; a selection is refused (E_LAUNCH_LEGACY): re-spawn it" }], ok: true });
966
+ const notices = launchStartNotices(dirname(dirname(dirname(dirname(home)))), meta.harness, frozen);
967
+ jsonOk({ context, selected, ...(notices.length ? { warnings: notices } : {}), selection: { source: "frozen-command", launchConfig: null, harness: null, model: null, yolo: null }, harness: meta.harness, model: meta.model || null, modelSource: meta.model ? "recorded" : "native default", yolo: meta.yolo ?? null, launchConfig: null, launchConfigSource: null, launchConfigDefault: false, executable: { path: d.executable, declared: null, resolvedFrom: "recorded" }, argv: d.argv, environment: d.environment, command: redactLaunchCommand(frozen), prompt: { kind: "task-file", file: "TASK.md" }, hooks: null, preflight: [{ check: "recipe", ok: true, detail: "frozen command; a selection is refused (E_LAUNCH_LEGACY): re-spawn it" }], ok: true });
950
968
  return;
951
969
  }
952
970
  const agentsRoot = agentsRootOfHome(home);
@@ -968,7 +986,7 @@ function launchPreview(bail) {
968
986
  const command = renderLaunchRecipe(recipe, { home, instance, redact: true, trustHome: plan.trustHome });
969
987
  const d = describeLaunchCommand(command);
970
988
  const environment = d.environment.map((e) => e.reference && recipe.env[e.name]?.fromEnv ? { name: e.name, fromEnv: recipe.env[e.name].fromEnv } : e);
971
- jsonOk({ context, selected, launchPromptAnswers: plan.launchPromptAnswers, ...(plan.warnings?.length ? { warnings: plan.warnings } : {}), selection: { source: plan.selectionSource, launchConfig: recipe.launchConfig, harness: sel.harness ?? null, model: sel.model ?? null, yolo: sel.yolo ?? null }, harness: plan.harness, model: recipe.model, modelSource: plan.modelSource, yolo: recipe.yolo ?? null, launchConfig: recipe.launchConfig, launchConfigSource: recipe.launchConfigSource, launchConfigDefault: recipe.launchConfigDefault === true, executable: { path: plan.executable.path, declared: plan.executable.declared ?? null, resolvedFrom: plan.executable.resolvedFrom }, argv: d.argv, environment, command, prompt: recipe.prompt, hooks: redactLaunchRecipe(recipe).hooks, preflight: plan.preflight, ok: plan.ok });
989
+ jsonOk({ context, selected, ...(plan.warnings?.length ? { warnings: plan.warnings } : {}), selection: { source: plan.selectionSource, launchConfig: recipe.launchConfig, harness: sel.harness ?? null, model: sel.model ?? null, yolo: sel.yolo ?? null }, harness: plan.harness, model: recipe.model, modelSource: plan.modelSource, yolo: recipe.yolo ?? null, launchConfig: recipe.launchConfig, launchConfigSource: recipe.launchConfigSource, launchConfigDefault: recipe.launchConfigDefault === true, executable: { path: plan.executable.path, declared: plan.executable.declared ?? null, resolvedFrom: plan.executable.resolvedFrom }, argv: d.argv, environment, command, prompt: recipe.prompt, hooks: redactLaunchRecipe(recipe).hooks, preflight: plan.preflight, ok: plan.ok });
972
990
  }
973
991
  async function launchConfigCmd() {
974
992
  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
@@ -1163,8 +1181,8 @@ async function worktreeCmd() {
1163
1181
  console.log(r.resumed ? `${r.path} is already made (branch ${r.branch} from ${r.base} @ ${String(r.baseOid).slice(0, 12)}); nothing was run` : `made ${r.path}: branch ${r.branch} from origin's ${r.base} @ ${String(r.baseOid).slice(0, 12)}${r.hooks.length ? `; worktree hooks: ${r.hooks.map((h) => `${h.capability} ${h.ok ? "ok" : "FAILED"}`).join(", ")}` : ""}`);
1164
1182
  for (const w of r.warnings || []) console.error(`oats: warning: ${w}`);
1165
1183
  } catch (e) {
1166
- if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details, e.exitStatus);
1167
- throw e;
1184
+ if (TYPED_CLI_FAILURES.has(e?.code)) throw e;
1185
+ return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.details, e.exitStatus);
1168
1186
  }
1169
1187
  }
1170
1188
 
@@ -1244,7 +1262,7 @@ function instanceCmd() {
1244
1262
  // its revision back and refuses if reality moved.
1245
1263
  const homeOpt = flag("home");
1246
1264
  if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
1247
- let root; try { root = ensureRoot(dirFlag()); } catch (e) { return bail(e.code || "E_NO_ROOT", e.message); }
1265
+ let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
1248
1266
  const recursive = !args.includes("--no-recursive");
1249
1267
  const wantPlan = args.includes("--plan"), wantApply = args.includes("--apply");
1250
1268
  if (wantPlan === wantApply) return bail("E_BAD_ARGS", "stop needs exactly one of --plan or --apply");
@@ -1261,12 +1279,18 @@ function instanceCmd() {
1261
1279
  const rev = flag("plan-revision"), key = flag("idempotency-key"), grace = flag("grace-ms");
1262
1280
  if (rev === true || key === true || grace === true) return bail("E_BAD_ARGS", usage);
1263
1281
  const receipt = applyStop(dirFlag(), root, name, { home: homeOpt, recursive, planRevision: rev, idempotencyKey: key, ...(grace !== undefined ? { graceMs: Number(grace) } : {}) });
1282
+ // Not part of the receipt, whose shape is contract: on stderr in both modes.
1283
+ for (const w of receipt[STOP_WARNINGS] || []) console.error(`oats: warning: ${w}`);
1264
1284
  if (JSON_MODE) { jsonOk(receipt); return; }
1265
1285
  for (const r of receipt.results) console.log(` ${r.instance}: ${r.ok ? (r.stopped ? "stopped" : `already ${r.state}`) : `${r.code} — ${r.message}`}`);
1266
1286
  console.log(receipt.ok ? `stopped${receipt.replayed ? " (replayed receipt)" : ""}; home, work, transcript and launch configuration retained — restart with \`oats session restart\`` : "some targets are still running; nothing was escalated");
1267
1287
  if (!receipt.ok) process.exit(1);
1268
1288
  return;
1269
- } catch (e) { return bail(e.code || "E_LIFECYCLE_FAILED", e.message, e.plan ? { plan: e.plan } : e.candidates ? { candidates: e.candidates } : undefined); }
1289
+ } catch (e) {
1290
+ // The error's own details (a claim's holder; a defect's cause) beside the plan it was refused with.
1291
+ const details = { ...e.details, ...(e.plan ? { plan: e.plan } : {}), ...(e.candidates ? { candidates: e.candidates } : {}) };
1292
+ return lifecycleFail(e, "E_LIFECYCLE_FAILED", Object.keys(details).length ? details : undefined);
1293
+ }
1270
1294
  }
1271
1295
  let home = flag("home");
1272
1296
  if (home === true) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
@@ -1435,13 +1459,19 @@ function harnessTrustCmd() {
1435
1459
  const context = workspaceContext(cmdFail);
1436
1460
  const show = (result, log = console.log) => {
1437
1461
  log(`${result.mode}: native harness trust for ${result.root}`);
1438
- for (const entry of result.entries) log(`${entry.harness}: ${entry.status} ${entry.file ?? "unresolved file"} ${JSON.stringify(entry.key)} ${JSON.stringify(entry.current)} -> ${JSON.stringify(entry.desired)} (${entry.beforeDigest ?? "missing"} -> ${entry.afterDigest ?? "unknown/absent"})`);
1462
+ const used = (entry) => [...(entry.ambient ? ["ambient"] : []), ...entry.launchConfigs.map((n) => `launch configuration ${n}`)].join(", ");
1463
+ for (const entry of result.entries) {
1464
+ log(`${entry.harness}: ${entry.status} ${entry.file ?? "unresolved file"} ${JSON.stringify(entry.key)} ${JSON.stringify(entry.current)} -> ${JSON.stringify(entry.desired)} (${entry.beforeDigest ?? "missing"} -> ${entry.afterDigest ?? "unknown/absent"}) (${used(entry)})`);
1465
+ if (entry.problem) log(`problem: ${entry.problem}`);
1466
+ if (entry.reason) log(`skipped: ${entry.reason}`);
1467
+ }
1439
1468
  if (result.audit) log(`audit: ${result.audit.status} ${result.audit.path} ${result.audit.operationId}`);
1440
1469
  for (const warning of result.warnings) log(`warning: ${warning}`);
1441
1470
  if (result.reason) log(`reason: ${result.reason}; native configuration may have changed: ${result.mayHaveChanged}`);
1442
1471
  };
1443
1472
  try {
1444
- const result = harnessTrust(context.deploymentDir, { harness: selected, plan: args.includes("--plan") });
1473
+ // Every configuration file a launch of this deployment reads: its launch configurations' too.
1474
+ const result = harnessTrust(context.deploymentDir, { harness: selected, plan: args.includes("--plan"), launchConfigs: launchConfigsAt(context.deploymentDir) });
1445
1475
  if (JSON_MODE) jsonOk(result);
1446
1476
  else show(result);
1447
1477
  } catch (e) {
@@ -2797,6 +2827,8 @@ async function spawnCmd() {
2797
2827
  jsonOk({
2798
2828
  instance: r.instance, agent: r.agent, home: r.home, work: r.work,
2799
2829
  branch: r.branch || null, base: r.base ?? null, launched: r.launched, warnings: r.warnings || [],
2830
+ // #917: what this spawn's start did with Claude's development-channel prompt, as a start answers it.
2831
+ ...(r.launchPrompts ? { launchPrompts: r.launchPrompts } : {}),
2800
2832
  ...(wakeSchedule ? { wakeSchedule } : {}), ...(wakeScheduleError ? { wakeScheduleError } : {}),
2801
2833
  tmux: r.tmux || null, backend: "tmux", repo: r.repo || null, harness: r.harness || null,
2802
2834
  model: r.model || null, parent: r.parentInstance || null,
@@ -2834,6 +2866,8 @@ function failedSpawnBranchLine(r, items, { local = false, host } = {}) {
2834
2866
  return r.retainedHome ? ` branch: the "branch" recorded in ${join(r.retainedHome, "instance.json")}${host ? ` on ${host}` : ""}` : null;
2835
2867
  }
2836
2868
 
2869
+ /** Whether this process's retire (retireCmd) has returned from the kernel: set once, read by the dispatch. */
2870
+ let retireReturned = false;
2837
2871
  function retireCmd() {
2838
2872
  const name = args[1];
2839
2873
  // Refused before anything else: before --plan, a replay, a plan revision or a recorded child is stopped.
@@ -2844,7 +2878,7 @@ function retireCmd() {
2844
2878
  if (args.includes("--plan")) {
2845
2879
  // K3: what retirement would touch, with the design's defaults — read-only.
2846
2880
  dropAmbientRoot();
2847
- let root; try { root = ensureRoot(dirFlag()); } catch (e) { return args.includes("--json") ? jsonFail(e.code || "E_NO_ROOT", e.message) : die(e.message); }
2881
+ let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
2848
2882
  try {
2849
2883
  const plan = planRetire(dirFlag(), root, name, { home: homeFlag });
2850
2884
  if (args.includes("--json")) { jsonOk(plan); return; }
@@ -2853,7 +2887,7 @@ function retireCmd() {
2853
2887
  console.log(` defaults: retain worktree ${plan.defaults.retainWorktree}, delete branch ${plan.defaults.deleteBranch}, stop children ${plan.defaults.stopChildren}`);
2854
2888
  for (const n of plan.notes) console.log(` note: ${n}`);
2855
2889
  return;
2856
- } catch (e) { return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.candidates ? { ...e.details, candidates: e.candidates } : e.details) : die(e.message); }
2890
+ } catch (e) { return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { ...e.details, candidates: e.candidates } : e.details); }
2857
2891
  }
2858
2892
  // The calling instance knows its own home: self-retire never needs to
2859
2893
  // disambiguate a same-named twin by hand.
@@ -2884,7 +2918,7 @@ function retireCmd() {
2884
2918
  // Before the claim, only the home: where the receipt goes, and the answers of a name that
2885
2919
  // resolves to no home, to several or to another one.
2886
2920
  let target;
2887
- try { target = resolveInstanceForCli(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.details) : die(e.message); }
2921
+ try { target = resolveInstanceForCli(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.details); }
2888
2922
  replayPath = join(dirname(target.home), `.oats-retire-receipt.${idemKey}.json`);
2889
2923
  // The plan the revision is checked against is read once, by retireInstance, when it holds the
2890
2924
  // home's claim (RETIRE_UNDER_CLAIM): nobody else is retiring the home by then, so the plan is
@@ -2908,17 +2942,21 @@ function retireCmd() {
2908
2942
  try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), [RETIRE_UNDER_CLAIM]: revalidate }); }
2909
2943
  catch (e) {
2910
2944
  // The plan could not be read, or its revision is not the one shown: the answers they always had.
2911
- if (e === planFailure) return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.details) : die(e.message);
2945
+ if (e === planFailure) return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.details);
2912
2946
  if (e === stalePlan) return args.includes("--json") ? jsonFail(e.code, e.message, e.details) : die(`the retire plan changed since it was shown; re-run oats retire ${name} --plan`);
2913
- if (!e?.code) throw e;
2914
2947
  // A child still running (or whose stop could not be established) refused the retirement: the
2915
2948
  // guarded apply returns the plan it acted on, and the text names each child's reason.
2916
- if (e.code === "E_CHILDREN_RUNNING") {
2949
+ if (e?.code === "E_CHILDREN_RUNNING") {
2917
2950
  const running = e.details.childrenStopped.filter((k) => !k.ok);
2918
2951
  return args.includes("--json") ? jsonFail(e.code, e.message, { ...e.details, ...(planRev !== undefined ? { plan: fresh } : {}) }) : die(`children still running: ${running.map((k) => `${k.instance} (${k.code})`).join(", ")}; nothing retired`);
2919
2952
  }
2920
- return args.includes("--json") ? jsonFail(e.code, e.message, e.candidates ? { ...e.details, candidates: e.candidates } : e.details) : die(e.message);
2953
+ // Whatever else the retire answers: retireInstance gives every error a kernel code, and what the
2954
+ // retire had done by then (`details.reached`).
2955
+ return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { ...e.details, candidates: e.candidates } : e.details);
2921
2956
  }
2957
+ // The retire has answered. Whatever throws from here on is not an answer of the retire and is
2958
+ // not given one (the dispatch): an error envelope without `reached` would say that nothing was done.
2959
+ retireReturned = true;
2922
2960
  if (replayPath) { r.planRevision = planRev; r.idempotencyKey = idemKey; r.replayed = false; try { writeFileAtomic(replayPath, JSON.stringify(r, null, 2)); } catch { /* receipt is evidence, not authority */ } }
2923
2961
  // A retired home's wake jobs are forgotten (definitions only; nothing is
2924
2962
  // stopped by this); a deferred self-retire keeps them until the home is gone.
@@ -3033,14 +3071,26 @@ async function scheduleCmd() {
3033
3071
  case "reconcile": return out(reconcileSchedule(ws(), needId(), { io, clear: args.includes("--clear"), ctx: ctx() }));
3034
3072
  case "tick": {
3035
3073
  const dryRun = args.includes("--dry-run");
3036
- if (args.includes("--host")) return out(tickHost({ io, dryRun }));
3074
+ // The minute the timer fired this tick for: this process's start, read before any work.
3075
+ const firedAt = new Date(Math.floor(performance.timeOrigin));
3076
+ if (args.includes("--host")) return out(tickHost({ firedAt, io, dryRun }));
3037
3077
  const reg = readRegistry();
3038
3078
  const tctx = scopeAutomations(ws(), { io, refresh: !dryRun });
3039
- const considered = withHostLock(() => [...(tctx.refresh && !tctx.refresh.ok ? [{ workspace: ws(), action: "error", error: `automations refresh: ${tctx.refresh.error}` }] : []), ...tickWorkspace(ws(), { io, reg, wsList: reg.workspaces.includes(ws()) ? reg.workspaces : [...reg.workspaces, ws()], dryRun, ctx: tctx }), ...tickTriggers(ws(), { io, dryRun, ctx: tctx, reg, wsList: reg.workspaces.includes(ws()) ? reg.workspaces : [...reg.workspaces, ws()] })]);
3079
+ const considered = withHostLock(() => [...(tctx.refresh && !tctx.refresh.ok ? [{ workspace: ws(), action: "error", error: `automations refresh: ${tctx.refresh.error}` }] : []), ...tickWorkspace(ws(), { firedAt, io, reg, wsList: reg.workspaces.includes(ws()) ? reg.workspaces : [...reg.workspaces, ws()], dryRun, ctx: tctx }), ...tickTriggers(ws(), { io, dryRun, ctx: tctx, reg, wsList: reg.workspaces.includes(ws()) ? reg.workspaces : [...reg.workspaces, ws()] })]);
3040
3080
  return out({ tickedAt: new Date().toISOString(), considered, scheduler: schedulerStatus(ws(), io) });
3041
3081
  }
3042
3082
  case "host": {
3043
3083
  const op = args[2];
3084
+ const os = flag("os");
3085
+ if (os !== undefined && !(op === "install" && args.includes("--print"))) throw scheduleError("E_BAD_ARGS", "--os is for oats schedule host install --print");
3086
+ if (op === "install" && args.includes("--print")) {
3087
+ // What install would write, rendered from this environment; nothing is written or loaded.
3088
+ if (os !== undefined && os !== "darwin" && os !== "linux") throw scheduleError("E_BAD_ARGS", "--os darwin|linux");
3089
+ if (flag("max-concurrent") !== undefined || flag("triggers-max-concurrent") !== undefined) throw scheduleError("E_BAD_ARGS", "--print writes nothing: run install without --print to set a cap");
3090
+ const r = hostUnitFiles(os ? { os } : {});
3091
+ if (!JSON_MODE) for (const w of r.warnings) console.error(`warning: ${w}`);
3092
+ return out(r, (x) => Object.entries(x.files).map(([path, content]) => `==> ${path} <==\n${content}`).join("\n").replace(/\n$/, ""));
3093
+ }
3044
3094
  if (op === "install") {
3045
3095
  const cap = (name, reset) => {
3046
3096
  const occurrences = args.filter((arg) => arg === `--${name}`);
@@ -3054,14 +3104,14 @@ async function scheduleCmd() {
3054
3104
  };
3055
3105
  const caps = { maxConcurrent: cap("max-concurrent", "default"), triggersMaxConcurrent: cap("triggers-max-concurrent", "none") };
3056
3106
  registerWorkspace(ws(), caps);
3057
- installHostUnit();
3058
- return out({ scheduler: schedulerStatus(ws(), io) });
3107
+ const { warnings } = installHostUnit();
3108
+ return out({ scheduler: schedulerStatus(ws(), io), warnings });
3059
3109
  }
3060
3110
  if (op === "uninstall") { unregisterWorkspace(ws()); if (!readRegistry().workspaces.length) uninstallHostUnit(); return out({ scheduler: schedulerStatus(ws(), io) }); }
3061
3111
  if (op === "status") return out({ scheduler: schedulerStatus(ws(), io) });
3062
- throw scheduleError("E_BAD_ARGS", "oats schedule host install|uninstall|status");
3112
+ throw scheduleError("E_BAD_ARGS", "oats schedule host install [--print [--os darwin|linux]]|uninstall|status");
3063
3113
  }
3064
- default: throw scheduleError("E_BAD_ARGS", "usage: oats schedule list|show <id>|test <id>|add <id> --file <spec.json> [--description=<text>] [--workspace <member> --runs-on <host> --owner <host>/<login>]|update <id> (--file <spec.json> [--description=<text>] | --description=<text>)|enable <id>|disable <id>|run <id> [--force]|remove <id> [--force]|reconcile <id> [--clear]|tick [--dry-run] [--host]|host install [--max-concurrent <N|default>] [--triggers-max-concurrent <N|none>]|uninstall|status [--dir <workspace>|--server <id>] [--json]");
3114
+ default: throw scheduleError("E_BAD_ARGS", "usage: oats schedule list|show <id>|test <id>|add <id> --file <spec.json> [--description=<text>] [--workspace <member> --runs-on <host> --owner <host>/<login>]|update <id> (--file <spec.json> [--description=<text>] | --description=<text>)|enable <id>|disable <id>|run <id> [--force]|remove <id> [--force]|reconcile <id> [--clear]|tick [--dry-run] [--host]|host install [--max-concurrent <N|default>] [--triggers-max-concurrent <N|none>] | host install --print [--os darwin|linux]|uninstall|status [--dir <workspace>|--server <id>] [--json]");
3065
3115
  }
3066
3116
  } catch (e) {
3067
3117
  // K8b: typed refusal details travel (identity mismatch: key/declared; a refused file: its integrity source).
@@ -3288,11 +3338,22 @@ async function sessionCmd() {
3288
3338
  // A start's launch-hook warnings, as spawn prints its own (stderr keeps stdout one JSON document).
3289
3339
  for (const w of result?.warnings || []) console.error(` WARNING: ${w}`);
3290
3340
  }
3291
- } catch (e) { cmdFail(e.code || "E_SESSION_FAILED", e.message, e.details); }
3341
+ } catch (e) { lifecycleFail(e, "E_SESSION_FAILED", e.details); }
3292
3342
  }
3293
3343
 
3294
3344
  async function paneCmd() {
3295
- die("`oats pane` has been retired — the OATS Desktop app (packages/desktop) is the control panel now.");
3345
+ die("`oats pane` has been retired — the OATS Desktop app (packages/desktop) is the control panel now; in a terminal, `oats tui` (preview).");
3346
+ }
3347
+
3348
+ /** `oats tui` (preview, docs/tui.md): the terminal client, shipped inside this package as
3349
+ * packages/tui. It is interactive, so `--json` is refused here, before anything is loaded.
3350
+ * This is the ONLY import of packages/tui in the kernel and the CLI, and it is dynamic: a broken
3351
+ * TUI cannot break another word, and no other word pays for loading it (test/tui-boundary.test.mjs).
3352
+ * packages/tui parses process.argv itself, so the word is spliced out first, as for the record. */
3353
+ async function tuiCmd() {
3354
+ if (args.includes("--json")) return cmdFail("E_BAD_ARGS", "oats tui is interactive and has no --json form; `oats status --json` is the machine view");
3355
+ process.argv.splice(2, 1);
3356
+ await import(new URL("../packages/tui/bin/tui.mjs", import.meta.url));
3296
3357
  }
3297
3358
 
3298
3359
  /** `oats onboard [<dir>] --workspace <repo ref> [--json]` — workspace model v2 (decision 9).
@@ -4239,7 +4300,7 @@ async function serverRouteCmd() {
4239
4300
  // keeping it at column 0 makes the whole command table one reviewable diff of
4240
4301
  // added lines rather than ~150 lines of pure whitespace churn, and keeps `git
4241
4302
  // blame` pointing at the commit that last changed each command.
4242
- const TYPED_CLI_FAILURES = new Set(["unsafe-config-key", "unsafe-config-value"]);
4303
+ const TYPED_CLI_FAILURES = OWN_NAME_FAILURES; // one list: lib/errors.mjs
4243
4304
  /** Removed 0.24 verbs → their v2 replacement (workspace model v2, decision 5). Checked before capability dispatch. */
4244
4305
  const REMOVED_VERBS = { prepare: "`oats onboard` / `oats sync` to set up a workspace, and `oats spawn <soul> --preview` to see what a spawn would resolve (the captured/portable path was removed in 0.26)", create: "author souls/<name>/soul.yaml + AGENTS.md in a member repository, then `oats sync`", type: "the soul's own soul.yaml in its member repository (agent types were a classic config block)", install: "oats sync", restore: "oats sync", init: "oats-local.yaml + oats sync", use: "soul.yaml capabilities: { <cap>: { from } } + workspace defaults", trust: "declaring the package in packages: (package approval was removed; oats sync locks commit + integrity)", list: "oats workspace status | oats capabilities", catalog: "oats package add <id> <version> (bare versions resolve through package-catalog.json)", remove: "oats package remove <id>", migrate: "a rebuild (no migration: docs/design/2026-09-23-workspace-module-contracts.md)", config: "oats-local.yaml (host settings) and oats-workspace.yaml (shared)", inject: "injection overrides are not part of the workspace model yet; edit the capability inject in its member repo" };
4245
4306
  try {
@@ -4318,6 +4379,7 @@ else if (cmd === "teams") await teamsCmd();
4318
4379
  else if (cmd === "soul") await soulCmd();
4319
4380
  else if (cmd === "status") await status();
4320
4381
  else if (cmd === "pane") await paneCmd();
4382
+ else if (cmd === "tui") await tuiCmd();
4321
4383
  else if (cmd === "version" || cmd === "--version" || cmd === "-v") versionCmd();
4322
4384
  // Same rule as the inner catch: a typed CLI failure surfaces with its own code
4323
4385
  // through the shared boundary, never re-badged as a spawn-mechanism failure.
@@ -4326,7 +4388,11 @@ else if (cmd === "schedule") await scheduleCmd();
4326
4388
  else if (cmd === "trigger") await triggerCmd();
4327
4389
  else if (cmd === "automations") await automationsCmd();
4328
4390
  else if (cmd === "spawn") { try { await spawnCmd(); } catch (e) { if (TYPED_CLI_FAILURES.has(e?.code)) throw e; if (JSON_MODE) jsonFail("E_SPAWN_FAILED", e.message || e, e.details?.unconfirmed === true ? e.details : undefined); throw e; } }
4329
- else if (cmd === "retire") retireCmd();
4391
+ // What a retire throws outside its own answers (the root, a replay's read) goes through the same door.
4392
+ // An exception after the retire has returned (retireReturned) is rethrown, here and by the handler
4393
+ // of typed failures below: a crash is read as "not confirmed", which is the truth, where an error
4394
+ // answer without `reached` would read as "nothing was done".
4395
+ else if (cmd === "retire") { try { retireCmd(); } catch (e) { if (retireReturned || TYPED_CLI_FAILURES.has(e?.code)) throw e; lifecycleFail(e, "E_LIFECYCLE_FAILED", e.details); } }
4330
4396
  else if (cmd === "capture" || cmd === "recall" || cmd === "setup") await recordCmd(cmd);
4331
4397
  else if (cmd === "experimental") await experimentalCmd();
4332
4398
  // `!HELP_WORDS.has(cmd)`: usage NEVER depends on deployment state. `help` is a
@@ -4380,6 +4446,9 @@ Usage:
4380
4446
  Desktop CLI API v1 probe payload
4381
4447
  oats status [--json] agents, souls, running instances
4382
4448
  [--max-age <s>] reuse head observations up to <s> s old (below)
4449
+ oats tui [--ascii] PREVIEW: the full-screen terminal client (docs/tui.md);
4450
+ ? help, q quit. Needs a terminal on stdin and stdout
4451
+ and has no --json form; --ascii = ASCII rules and marks
4383
4452
  oats server add <id> --ssh <alias> register another machine's OATS (OpenSSH alias,
4384
4453
  --workspace </abs/path> [--oats <p>] remote workspace, remote oats path; no keys stored;
4385
4454
  [--path <dir:dir>] --path = dirs prepended to the remote PATH, e.g. ~/.local/bin)
@@ -4526,8 +4595,10 @@ Usage:
4526
4595
  own command run in the home or scope, envelope
4527
4596
  relayed; a view answers {documents: [...]}
4528
4597
  oats harness trust [--dir <deployment>] explicitly trust one canonical deployment root
4529
- [--harness claude|codex|all] in native host configuration; --plan reads only,
4530
- [--plan] [--json] bare command applies with a durable audit
4598
+ [--harness claude|codex|all] in every native configuration file a launch reads
4599
+ [--plan] [--json] (the ambient one and each launch configuration's
4600
+ CLAUDE_CONFIG_DIR / CODEX_HOME); --plan reads only,
4601
+ bare command applies with a durable audit
4531
4602
  oats launch-config list [--dir <scope> named launch configurations effective at a scope,
4532
4603
  | --home <abs> | --soul <name>] a home's recorded context or a soul's own scope:
4533
4604
  [--agents-root <abs>] [--json] harness, executable, args, env (values redacted,
@@ -4671,7 +4742,8 @@ Observation reuse (feature observe-max-age):
4671
4742
  Layers: ${LAYERS.join(", ")}. Workspace model v2: docs/design/2026-09-23-workspace-module-contracts.md.`;
4672
4743
  }
4673
4744
  } catch (e) {
4674
- if (!TYPED_CLI_FAILURES.has(e?.code)) throw e;
4745
+ // After a retire has returned, nothing is answered as an error, a typed failure included (the dispatch).
4746
+ if (retireReturned || !TYPED_CLI_FAILURES.has(e?.code)) throw e;
4675
4747
  // Same two renderings as every other typed failure: one envelope on stdout in
4676
4748
  // --json mode, one `oats: <message>` line on stderr otherwise. The message
4677
4749
  // already names the offending file — the readers re-raise it with one.
@@ -207,7 +207,10 @@ A self-contained package has an `oats.json`:
207
207
  every host. Only then is its start time read: from `/proc`, or with `ps`
208
208
  where there is no `/proc`, as on macOS: the system `ps`, from
209
209
  `/usr/bin:/bin` whatever the caller's `PATH` holds, in a fixed `LC_ALL=C`,
210
- `TZ=UTC` environment. A start that cannot be read is never taken to mean the process is
210
+ `TZ=UTC` environment. A spawning process that has exited or was killed and
211
+ that its parent has not reaped (a zombie) is gone, although it still has
212
+ its pid and its start: the row shows the quarantine and `oats retire`
213
+ completes it. A start that cannot be read is never taken to mean the process is
211
214
  gone, nor shown as alive: `oats status` shows the quarantine
212
215
  (`rollbackIncomplete`, whose `inProgress` names the pid), and `oats retire`
213
216
  refuses with `E_LIFECYCLE_BUSY`, naming the recorded pid and start for a
@@ -244,7 +247,11 @@ A self-contained package has an `oats.json`:
244
247
  and nothing is silently dropped. Without `--force` that state fails closed with
245
248
  `E_UNIDENTIFIED_INSTANCE_HOME` rather than deleting whatever credentials the
246
249
  directory still holds; `--force` removes it and leaves any external state for
247
- the operator to clean up by hand. Home entries declared in
250
+ the operator to clean up by hand. One home is the exception for now: a home
251
+ whose `instance.json` is there and cannot be read is refused by every
252
+ retire, `--force` included, until the file is restored from a copy
253
+ ([souls-and-instances.md](souls-and-instances.md#retire); awebai/oats#896).
254
+ Home entries declared in
248
255
  `retirement.disposable.home` (below) go with the home: recovery holds no
249
256
  copy of them.
250
257
  - `retirement.disposable` declares what retirement treats as the provider's