@awebai/oats 0.50.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 (132) hide show
  1. package/README.md +1 -0
  2. package/bin/oats.mjs +153 -51
  3. package/docs/capabilities.md +11 -3
  4. package/docs/configuration.md +134 -88
  5. package/docs/desktop-cli-api.md +994 -71
  6. package/docs/desktop-instance-start.md +56 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +230 -59
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +73 -8
  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 +43 -7
  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.51.0.md +156 -0
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/schedules.md +91 -4
  27. package/docs/servers.md +21 -2
  28. package/docs/souls-and-instances.md +113 -21
  29. package/docs/tui.md +152 -0
  30. package/docs/workspaces.md +2 -2
  31. package/lib/claim.mjs +266 -0
  32. package/lib/core.mjs +845 -166
  33. package/lib/errors.mjs +170 -0
  34. package/lib/harness-trust-write.mjs +68 -27
  35. package/lib/harness-trust.mjs +34 -16
  36. package/lib/instance-inspect.mjs +40 -11
  37. package/lib/instance-lifecycle.mjs +169 -47
  38. package/lib/launch-preference.mjs +16 -0
  39. package/lib/launch-prompt-completion.mjs +7 -43
  40. package/lib/launch-prompt-evidence.mjs +14 -7
  41. package/lib/launch-prompt-fixtures/README.md +86 -152
  42. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  43. package/lib/launch-prompt-fixtures.mjs +122 -109
  44. package/lib/launch-prompt-transport.mjs +2 -56
  45. package/lib/launch-prompts.mjs +102 -100
  46. package/lib/schedule-host.mjs +154 -22
  47. package/lib/schedule.mjs +73 -24
  48. package/lib/servers.mjs +20 -4
  49. package/lib/session-viewer.mjs +87 -10
  50. package/lib/system-tools.mjs +39 -0
  51. package/lib/tmux-server-scope.mjs +62 -0
  52. package/lib/triggers.mjs +4 -4
  53. package/lib/workspace.mjs +5 -11
  54. package/lib/worktree-hooks.mjs +116 -23
  55. package/lib/worktree.mjs +89 -102
  56. package/package-catalog.json +3 -3
  57. package/package.json +7 -2
  58. package/packages/client/capability-show-contract.mjs +230 -0
  59. package/packages/client/capability-warnings-contract.mjs +57 -0
  60. package/packages/client/cli-adapter.mjs +548 -0
  61. package/packages/client/cli-environment.mjs +53 -0
  62. package/packages/client/cli-locator.mjs +253 -0
  63. package/packages/client/cli-probe-contract.mjs +47 -0
  64. package/packages/client/client-terms.mjs +60 -0
  65. package/packages/client/deployment-contract.mjs +68 -0
  66. package/packages/client/deployment-data.mjs +483 -0
  67. package/packages/client/deployment-facts.mjs +34 -0
  68. package/packages/client/deployment-label.mjs +76 -0
  69. package/packages/client/deployment-observer.mjs +89 -0
  70. package/packages/client/deployment-panel.mjs +142 -0
  71. package/packages/client/deployment-read-cli.mjs +53 -0
  72. package/packages/client/display-text.mjs +44 -0
  73. package/packages/client/harness-names.mjs +30 -0
  74. package/packages/client/inspect-contract.mjs +62 -0
  75. package/packages/client/instance-acts.mjs +54 -0
  76. package/packages/client/instance-admission.mjs +45 -0
  77. package/packages/client/instance-events-contract.mjs +74 -0
  78. package/packages/client/instance-git-contract.mjs +80 -0
  79. package/packages/client/instance-presentation.mjs +22 -0
  80. package/packages/client/instance-tree.mjs +453 -0
  81. package/packages/client/kernel-environment.mjs +11 -0
  82. package/packages/client/launch-contract.mjs +51 -0
  83. package/packages/client/launch-prompt-outcome.mjs +165 -0
  84. package/packages/client/lifecycle-cli.mjs +61 -0
  85. package/packages/client/lifecycle-contract.mjs +372 -0
  86. package/packages/client/liveness-main.mjs +10 -0
  87. package/packages/client/liveness.mjs +35 -0
  88. package/packages/client/machine-contract.mjs +123 -0
  89. package/packages/client/own-environment.mjs +22 -0
  90. package/packages/client/panel-views.mjs +286 -0
  91. package/packages/client/readiness-contract.mjs +172 -0
  92. package/packages/client/refresh-loop.mjs +52 -0
  93. package/packages/client/remote-address.mjs +126 -0
  94. package/packages/client/remote-roster.mjs +67 -0
  95. package/packages/client/roster-sections.mjs +80 -0
  96. package/packages/client/spawn-apply-cli.mjs +104 -0
  97. package/packages/client/spawn-apply-contract.mjs +183 -0
  98. package/packages/client/spawn-decision.mjs +46 -0
  99. package/packages/client/spawn-messages.mjs +119 -0
  100. package/packages/client/spawn-preview-cli.mjs +32 -0
  101. package/packages/client/spawn-preview-contract.mjs +314 -0
  102. package/packages/client/team-members.mjs +41 -0
  103. package/packages/client/team-rows.mjs +45 -0
  104. package/packages/client/terminal-contract.mjs +57 -0
  105. package/packages/client/tmux-status.mjs +66 -0
  106. package/packages/client/waiting-on-you.mjs +88 -0
  107. package/packages/client/workspace-admission.mjs +45 -0
  108. package/packages/client/workspace-cli.mjs +142 -0
  109. package/packages/client/workspace-views.mjs +147 -0
  110. package/packages/tui/README.md +46 -0
  111. package/packages/tui/bin/tui.mjs +7 -0
  112. package/packages/tui/lib/actions.mjs +29 -0
  113. package/packages/tui/lib/client.mjs +4 -0
  114. package/packages/tui/lib/main.mjs +105 -0
  115. package/packages/tui/lib/term/keys.mjs +323 -0
  116. package/packages/tui/lib/term/screen.mjs +122 -0
  117. package/packages/tui/lib/term/style.mjs +43 -0
  118. package/packages/tui/lib/term/text.mjs +49 -0
  119. package/packages/tui/lib/term/tty.mjs +168 -0
  120. package/packages/tui/lib/term/width.mjs +124 -0
  121. package/packages/tui/lib/views/frame.mjs +62 -0
  122. package/packages/tui/lib/views/help.mjs +28 -0
  123. package/packages/tui/package.json +8 -0
  124. package/skills/oats-getting-started/SKILL.md +29 -22
  125. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  126. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  127. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  128. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  129. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  130. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  131. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  132. 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, 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"];
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.
@@ -2874,36 +2908,55 @@ function retireCmd() {
2874
2908
  // resolved the home). A guarded apply acts on the children of the plan it
2875
2909
  // revalidated; a plain or --self retire computes them as the plan does, and
2876
2910
  // passes none when there are none.
2877
- let replayPath = null, plannedExtraWorktrees, fresh, children;
2911
+ let replayPath = null, fresh, revalidate, stalePlan, planFailure;
2878
2912
  if (planRev !== undefined) {
2879
2913
  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(idemKey)) die("--idempotency-key: 1-128 chars of [A-Za-z0-9._:-]");
2880
2914
  // Replay first: after a successful retire the home is gone, so the receipt
2881
2915
  // (beside the instances dir, keyed by the idempotency key) is the answer.
2882
2916
  const replay = (dir) => { const p = join(dir, `.oats-retire-receipt.${idemKey}.json`); if (!existsSync(p)) return false; try { const prior = JSON.parse(readFileSync(p, "utf8")); if (prior.retired !== name) return false; if (args.includes("--json")) jsonOk({ ...prior, replayed: true }); else console.log(`retire ${name}: replayed receipt for key ${idemKey}`); return true; } catch { return false; } };
2883
2917
  for (const a of listAgents(root)) if (replay(join(a._dir, "instances"))) return;
2884
- try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.details) : die(e.message); }
2885
- replayPath = join(dirname(fresh.home), `.oats-retire-receipt.${idemKey}.json`);
2886
- // The extra trees the confirmed plan names, as it names them: the retire refuses as stale rather than
2887
- // move or remove one that no longer reads that way when it gets to them.
2888
- plannedExtraWorktrees = fresh.facts.extraWorktrees;
2889
- if (fresh.planRevision !== planRev) return args.includes("--json") ? jsonFail("E_PLAN_STALE", `the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`, { plan: fresh }) : die(`the retire plan changed since it was shown; re-run oats retire ${name} --plan`);
2890
- children = fresh.facts.children;
2918
+ // Before the claim, only the home: where the receipt goes, and the answers of a name that
2919
+ // resolves to no home, to several or to another one.
2920
+ let target;
2921
+ try { target = resolveInstanceForCli(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.details); }
2922
+ replayPath = join(dirname(target.home), `.oats-retire-receipt.${idemKey}.json`);
2923
+ // The plan the revision is checked against is read once, by retireInstance, when it holds the
2924
+ // home's claim (RETIRE_UNDER_CLAIM): nobody else is retiring the home by then, so the plan is
2925
+ // the state the retire starts from. Against another retire of this home the answer is that one
2926
+ // is running (E_LIFECYCLE_BUSY), and no plan is read. A revision that no longer matches is
2927
+ // refused there, and nothing was done. What the retire takes from the plan: its children, and
2928
+ // its extra trees as it names them (the retire refuses as stale rather than move or remove one
2929
+ // that no longer reads that way when it gets to them).
2930
+ revalidate = () => {
2931
+ try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { planFailure = e; throw e; }
2932
+ if (fresh.planRevision !== planRev) throw (stalePlan = Object.assign(new Error(`the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`), { code: "E_PLAN_STALE", details: { plan: fresh } }));
2933
+ return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children };
2934
+ };
2891
2935
  } else {
2892
- const recorded = descendantsOf(root, name);
2893
- if (recorded.length) children = recorded;
2936
+ // A plain or --self retire reads its recorded children the same way: under the claim, as they
2937
+ // are when the retire starts (an earlier retire that kept the home has repaired lineage by
2938
+ // then), and none when there are none.
2939
+ revalidate = () => { const recorded = descendantsOf(root, name); return recorded.length ? { children: recorded } : {}; };
2894
2940
  }
2895
2941
  let r;
2896
- try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), ...(plannedExtraWorktrees ? { plannedExtraWorktrees } : {}), ...(children ? { children } : {}) }); }
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 }); }
2897
2943
  catch (e) {
2898
- if (!e?.code) throw e;
2944
+ // The plan could not be read, or its revision is not the one shown: the answers they always had.
2945
+ if (e === planFailure) return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.details);
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`);
2899
2947
  // A child still running (or whose stop could not be established) refused the retirement: the
2900
2948
  // guarded apply returns the plan it acted on, and the text names each child's reason.
2901
- if (e.code === "E_CHILDREN_RUNNING") {
2949
+ if (e?.code === "E_CHILDREN_RUNNING") {
2902
2950
  const running = e.details.childrenStopped.filter((k) => !k.ok);
2903
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`);
2904
2952
  }
2905
- 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);
2906
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;
2907
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 */ } }
2908
2961
  // A retired home's wake jobs are forgotten (definitions only; nothing is
2909
2962
  // stopped by this); a deferred self-retire keeps them until the home is gone.
@@ -3018,14 +3071,26 @@ async function scheduleCmd() {
3018
3071
  case "reconcile": return out(reconcileSchedule(ws(), needId(), { io, clear: args.includes("--clear"), ctx: ctx() }));
3019
3072
  case "tick": {
3020
3073
  const dryRun = args.includes("--dry-run");
3021
- 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 }));
3022
3077
  const reg = readRegistry();
3023
3078
  const tctx = scopeAutomations(ws(), { io, refresh: !dryRun });
3024
- 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()] })]);
3025
3080
  return out({ tickedAt: new Date().toISOString(), considered, scheduler: schedulerStatus(ws(), io) });
3026
3081
  }
3027
3082
  case "host": {
3028
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
+ }
3029
3094
  if (op === "install") {
3030
3095
  const cap = (name, reset) => {
3031
3096
  const occurrences = args.filter((arg) => arg === `--${name}`);
@@ -3039,14 +3104,14 @@ async function scheduleCmd() {
3039
3104
  };
3040
3105
  const caps = { maxConcurrent: cap("max-concurrent", "default"), triggersMaxConcurrent: cap("triggers-max-concurrent", "none") };
3041
3106
  registerWorkspace(ws(), caps);
3042
- installHostUnit();
3043
- return out({ scheduler: schedulerStatus(ws(), io) });
3107
+ const { warnings } = installHostUnit();
3108
+ return out({ scheduler: schedulerStatus(ws(), io), warnings });
3044
3109
  }
3045
3110
  if (op === "uninstall") { unregisterWorkspace(ws()); if (!readRegistry().workspaces.length) uninstallHostUnit(); return out({ scheduler: schedulerStatus(ws(), io) }); }
3046
3111
  if (op === "status") return out({ scheduler: schedulerStatus(ws(), io) });
3047
- 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");
3048
3113
  }
3049
- 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]");
3050
3115
  }
3051
3116
  } catch (e) {
3052
3117
  // K8b: typed refusal details travel (identity mismatch: key/declared; a refused file: its integrity source).
@@ -3224,7 +3289,9 @@ async function sessionCmd() {
3224
3289
  let result;
3225
3290
  if (args[1] === "attach") {
3226
3291
  if (JSON_MODE) throw Object.assign(new Error("session attach is interactive; omit --json"), { code: "E_BAD_ARGS" });
3227
- process.exitCode = await attachInstanceSession(home);
3292
+ // --detach-key (feature session-attach-detach-key): the one key that leaves this viewer, with
3293
+ // status 20. Without it every key reaches the agent and there is no keyboard exit.
3294
+ process.exitCode = await attachInstanceSession(home, { detachKey: valueFlag("detach-key") });
3228
3295
  return;
3229
3296
  }
3230
3297
  if (args[1] === "inspect") result = inspectInstanceSession(home);
@@ -3264,18 +3331,29 @@ async function sessionCmd() {
3264
3331
  const file = flag("file");
3265
3332
  if (!file || file === true) throw Object.assign(new Error("session upload needs --file <local path>"), { code: "E_BAD_ARGS" });
3266
3333
  result = uploadAttachment({ file, home: home === true ? undefined : home });
3267
- } else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|restart|receive|upload --home /absolute/home [--text-file path] [--model id] [--launch-config name|none | --reselect-launch] [--harness pi|claude|codex] [--yolo|--no-yolo] [--stop-grace seconds] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
3334
+ } else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|restart|receive|upload --home /absolute/home [--text-file path] [--detach-key key] [--model id] [--launch-config name|none | --reselect-launch] [--harness pi|claude|codex] [--yolo|--no-yolo] [--stop-grace seconds] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
3268
3335
  if (JSON_MODE) jsonOk(result);
3269
3336
  else {
3270
3337
  console.log(JSON.stringify(result, null, 2));
3271
3338
  // A start's launch-hook warnings, as spawn prints its own (stderr keeps stdout one JSON document).
3272
3339
  for (const w of result?.warnings || []) console.error(` WARNING: ${w}`);
3273
3340
  }
3274
- } catch (e) { cmdFail(e.code || "E_SESSION_FAILED", e.message, e.details); }
3341
+ } catch (e) { lifecycleFail(e, "E_SESSION_FAILED", e.details); }
3275
3342
  }
3276
3343
 
3277
3344
  async function paneCmd() {
3278
- 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));
3279
3357
  }
3280
3358
 
3281
3359
  /** `oats onboard [<dir>] --workspace <repo ref> [--json]` — workspace model v2 (decision 9).
@@ -4091,8 +4169,14 @@ async function serverRouteCmd() {
4091
4169
  return;
4092
4170
  }
4093
4171
  if (args[1] !== "attach") bail("E_USAGE", "--server routes `session inspect`, `session start`, `session restart`, `session upload` and `session attach`; input runs on the execution host (the wake broker calls it there)");
4172
+ // --detach-key travels only to a host that advertises session-attach-detach-key (attachArgv
4173
+ // probes for it, under --print too). The key may be C-\, the tty's QUIT character: pressed
4174
+ // once ssh has given the tty back, it reaches this process as SIGQUIT, whose default action
4175
+ // would replace the relayed status with 131. Held from here until this process exits.
4176
+ const detachKey = valueFlag("detach-key");
4177
+ if (detachKey !== undefined) process.on("SIGQUIT", () => {});
4094
4178
  let route;
4095
- try { route = attachArgv(id, addr, { skipVersionCheck: args.includes("--print") }); }
4179
+ try { route = attachArgv(id, { ...addr, detachKey }, { skipVersionCheck: args.includes("--print") }); }
4096
4180
  // ssh failing before the viewer (the version probe, a name resolved through the host's roster)
4097
4181
  // is the failure ssh has under it: exit 255, on which a caller reconnects. Every other refusal,
4098
4182
  // and an ssh that never started (no link can come back), exits 1.
@@ -4102,7 +4186,7 @@ async function serverRouteCmd() {
4102
4186
  // ssh exits 255 for its own failures: a link that died under the viewer
4103
4187
  // (keepalives unanswered, the master or the host's sshd gone), or one
4104
4188
  // never made. Say what is known rather than ending silently.
4105
- if (r.status === 255) console.error(`\noats: ssh to ${route.target.sshHost} ended with an error (exit 255); if the link was lost, the instance keeps running on ${id}. Reattach with: oats session attach --server ${id} --home ${shellQuote(route.home)}`);
4189
+ if (r.status === 255) console.error(`\noats: ssh to ${route.target.sshHost} ended with an error (exit 255); if the link was lost, the instance keeps running on ${id}. Reattach with: oats session attach --server ${id} --home ${shellQuote(route.home)}${detachKey !== undefined ? ` --detach-key ${shellQuote(detachKey)}` : ""}`);
4106
4190
  process.exit(r.status ?? 1);
4107
4191
  }
4108
4192
  // A spawn's argv is checked here, before the server is contacted.
@@ -4216,7 +4300,7 @@ async function serverRouteCmd() {
4216
4300
  // keeping it at column 0 makes the whole command table one reviewable diff of
4217
4301
  // added lines rather than ~150 lines of pure whitespace churn, and keeps `git
4218
4302
  // blame` pointing at the commit that last changed each command.
4219
- 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
4220
4304
  /** Removed 0.24 verbs → their v2 replacement (workspace model v2, decision 5). Checked before capability dispatch. */
4221
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" };
4222
4306
  try {
@@ -4295,6 +4379,7 @@ else if (cmd === "teams") await teamsCmd();
4295
4379
  else if (cmd === "soul") await soulCmd();
4296
4380
  else if (cmd === "status") await status();
4297
4381
  else if (cmd === "pane") await paneCmd();
4382
+ else if (cmd === "tui") await tuiCmd();
4298
4383
  else if (cmd === "version" || cmd === "--version" || cmd === "-v") versionCmd();
4299
4384
  // Same rule as the inner catch: a typed CLI failure surfaces with its own code
4300
4385
  // through the shared boundary, never re-badged as a spawn-mechanism failure.
@@ -4303,7 +4388,11 @@ else if (cmd === "schedule") await scheduleCmd();
4303
4388
  else if (cmd === "trigger") await triggerCmd();
4304
4389
  else if (cmd === "automations") await automationsCmd();
4305
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; } }
4306
- 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); } }
4307
4396
  else if (cmd === "capture" || cmd === "recall" || cmd === "setup") await recordCmd(cmd);
4308
4397
  else if (cmd === "experimental") await experimentalCmd();
4309
4398
  // `!HELP_WORDS.has(cmd)`: usage NEVER depends on deployment state. `help` is a
@@ -4357,6 +4446,9 @@ Usage:
4357
4446
  Desktop CLI API v1 probe payload
4358
4447
  oats status [--json] agents, souls, running instances
4359
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
4360
4452
  oats server add <id> --ssh <alias> register another machine's OATS (OpenSSH alias,
4361
4453
  --workspace </abs/path> [--oats <p>] remote workspace, remote oats path; no keys stored;
4362
4454
  [--path <dir:dir>] --path = dirs prepended to the remote PATH, e.g. ~/.local/bin)
@@ -4386,7 +4478,9 @@ Usage:
4386
4478
  --instance <name> [--json] saved home on its host
4387
4479
  oats session inspect|attach --server <id> inspect (envelope) or attach a viewer (ssh PTY) for a
4388
4480
  --instance <name> | --home <abs> remote instance, by its saved route or the server's
4389
- roster (--print shows attach); oats 0.22.2 or later
4481
+ [--detach-key <key>] roster (--print shows attach); oats 0.22.2 or later.
4482
+ attach --detach-key: as below; the server must
4483
+ advertise session-attach-detach-key
4390
4484
  oats session start --server <id> start a stopped remote instance in its existing home
4391
4485
  --instance <name> | --home <abs> by its saved route or the server's roster; it must advertise
4392
4486
  [--model <m>] [--json] session-start (oats 0.22.9 or later)
@@ -4409,6 +4503,11 @@ Usage:
4409
4503
  [--check] --check: write nothing; report <dir> (~ = this home),
4410
4504
  its state and whether Git reads the workspace remote
4411
4505
  oats session inspect|input|attach --home <absolute-home> [--text-file <path>] [--json]
4506
+ oats session attach --home <absolute-home> [--detach-key <key>]
4507
+ a viewer of one instance. <key> (C-<letter>, M-<letter
4508
+ or digit>, F1 to F12; 'C-\\' is the suggested one)
4509
+ leaves it with exit status 20; without one no key
4510
+ leaves it: every key goes to the agent
4412
4511
  oats schedule list|show <id>|test <id>|add <id> --file <spec.json>|update <id> --file <spec.json>
4413
4512
  enable|disable|run|remove|reconcile <id> workspace-scoped, host-owned schedules (spawn,
4414
4513
  tick [--dry-run] [--host] command or wake jobs on a five-field cron with an
@@ -4496,8 +4595,10 @@ Usage:
4496
4595
  own command run in the home or scope, envelope
4497
4596
  relayed; a view answers {documents: [...]}
4498
4597
  oats harness trust [--dir <deployment>] explicitly trust one canonical deployment root
4499
- [--harness claude|codex|all] in native host configuration; --plan reads only,
4500
- [--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
4501
4602
  oats launch-config list [--dir <scope> named launch configurations effective at a scope,
4502
4603
  | --home <abs> | --soul <name>] a home's recorded context or a soul's own scope:
4503
4604
  [--agents-root <abs>] [--json] harness, executable, args, env (values redacted,
@@ -4641,7 +4742,8 @@ Observation reuse (feature observe-max-age):
4641
4742
  Layers: ${LAYERS.join(", ")}. Workspace model v2: docs/design/2026-09-23-workspace-module-contracts.md.`;
4642
4743
  }
4643
4744
  } catch (e) {
4644
- 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;
4645
4747
  // Same two renderings as every other typed failure: one envelope on stdout in
4646
4748
  // --json mode, one `oats: <message>` line on stderr otherwise. The message
4647
4749
  // already names the offending file — the readers re-raise it with one.
@@ -205,8 +205,12 @@ A self-contained package has an `oats.json`:
205
205
  Whether the process exists is the operating system's answer (`kill -0`:
206
206
  "no such process" is gone, another user's process exists), the same on
207
207
  every host. Only then is its start time read: from `/proc`, or with `ps`
208
- (in a fixed `LC_ALL=C`, `TZ=UTC` environment) where there is no `/proc`,
209
- as on macOS. A start that cannot be read is never taken to mean the process is
208
+ where there is no `/proc`, as on macOS: the system `ps`, from
209
+ `/usr/bin:/bin` whatever the caller's `PATH` holds, in a fixed `LC_ALL=C`,
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
210
214
  gone, nor shown as alive: `oats status` shows the quarantine
211
215
  (`rollbackIncomplete`, whose `inProgress` names the pid), and `oats retire`
212
216
  refuses with `E_LIFECYCLE_BUSY`, naming the recorded pid and start for a
@@ -243,7 +247,11 @@ A self-contained package has an `oats.json`:
243
247
  and nothing is silently dropped. Without `--force` that state fails closed with
244
248
  `E_UNIDENTIFIED_INSTANCE_HOME` rather than deleting whatever credentials the
245
249
  directory still holds; `--force` removes it and leaves any external state for
246
- 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
247
255
  `retirement.disposable.home` (below) go with the home: recovery holds no
248
256
  copy of them.
249
257
  - `retirement.disposable` declares what retirement treats as the provider's