@awebai/oats 0.68.0 → 0.69.1

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 (72) hide show
  1. package/bin/oats.mjs +102 -22
  2. package/docs/capabilities.md +49 -5
  3. package/docs/configuration.md +68 -2
  4. package/docs/desktop-cli-api.md +355 -12
  5. package/docs/desktop-instance-start.md +88 -3
  6. package/docs/desktop.md +147 -13
  7. package/docs/execution-targets.md +514 -62
  8. package/docs/harness-trust.md +3 -1
  9. package/docs/implementation.md +28 -11
  10. package/docs/integrations.md +1 -1
  11. package/docs/oats-local.schema.json +2 -2
  12. package/docs/official-catalog.md +4 -3
  13. package/docs/packages.md +7 -7
  14. package/docs/release-notes/v0.68.1.md +102 -0
  15. package/docs/release-notes/v0.69.0.md +658 -0
  16. package/docs/release-notes/v0.69.1.md +25 -0
  17. package/docs/servers.md +44 -5
  18. package/docs/souls-and-instances.md +11 -7
  19. package/docs/tui.md +114 -31
  20. package/docs/upgrading.md +14 -5
  21. package/docs/workspaces.md +1 -1
  22. package/lib/core.mjs +345 -89
  23. package/lib/file-pieces.mjs +49 -0
  24. package/lib/instance-events.mjs +25 -4
  25. package/lib/launch-prompt-fixtures/README.md +62 -0
  26. package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
  27. package/lib/launch-prompt-fixtures.mjs +49 -0
  28. package/lib/launch-prompt-resume.mjs +55 -0
  29. package/lib/login-environment.mjs +27 -9
  30. package/lib/schedule.mjs +3 -3
  31. package/lib/servers.mjs +117 -23
  32. package/lib/session-end.mjs +82 -0
  33. package/lib/session-input.mjs +43 -9
  34. package/lib/session-resume-contract.mjs +32 -0
  35. package/lib/session-resume.mjs +310 -0
  36. package/lib/session-seen.mjs +163 -0
  37. package/lib/session-viewer.mjs +147 -44
  38. package/lib/soul-composition.mjs +2 -1
  39. package/lib/start-env.mjs +110 -0
  40. package/lib/tmux-server-scope.mjs +139 -14
  41. package/lib/workspace.mjs +38 -4
  42. package/package-catalog.json +10 -4
  43. package/package.json +1 -1
  44. package/packages/client/cli-adapter.mjs +9 -0
  45. package/packages/client/cli-locator.mjs +3 -2
  46. package/packages/client/deployment-data.mjs +7 -0
  47. package/packages/client/deployment-panel.mjs +3 -0
  48. package/packages/client/file-output-exec.mjs +98 -0
  49. package/packages/client/instance-display-name.mjs +18 -0
  50. package/packages/client/launch-prompt-outcome.mjs +25 -13
  51. package/packages/client/own-codes.mjs +2 -0
  52. package/packages/client/session-attach.mjs +35 -5
  53. package/packages/client/session-resume-cli.mjs +64 -0
  54. package/packages/client/session-resume-trigger.mjs +167 -0
  55. package/packages/client/session-resume.mjs +332 -0
  56. package/packages/client/tmux-status.mjs +30 -7
  57. package/packages/client/waiting-on-you.mjs +11 -4
  58. package/packages/client/workspace-step.mjs +17 -5
  59. package/packages/record/lib/last-conversation.mjs +123 -0
  60. package/packages/record/lib/session-roots.mjs +10 -1
  61. package/packages/tui/README.md +1 -1
  62. package/packages/tui/lib/client.mjs +2 -1
  63. package/packages/tui/lib/main.mjs +5 -3
  64. package/packages/tui/lib/model.mjs +57 -15
  65. package/packages/tui/lib/store.mjs +8 -7
  66. package/packages/tui/lib/term/text.mjs +12 -9
  67. package/packages/tui/lib/views/capabilities.mjs +6 -6
  68. package/packages/tui/lib/views/frame.mjs +72 -7
  69. package/packages/tui/lib/views/help.mjs +9 -4
  70. package/packages/tui/lib/views/instances.mjs +46 -29
  71. package/packages/tui/lib/views/souls.mjs +9 -8
  72. package/skills/oats-getting-started/SKILL.md +117 -4
package/bin/oats.mjs CHANGED
@@ -33,7 +33,7 @@ import {
33
33
  LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
34
34
  capabilityManifests, capabilityTrust, capabilityExecutablePath,
35
35
  officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
36
- findInstanceHome, findInstanceHomes, homeLaunchLayers, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, suggestSpawnName, 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,
36
+ findInstanceHome, findInstanceHomes, homeLaunchLayers, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, suggestSpawnName, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, machineLaunchConfigs, machineLaunchConfigsFile, launchStartNotices, launchReportFor, explicitInstanceName, retireInstance, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
37
37
  FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
38
38
  } from "../lib/core.mjs";
39
39
  import {
@@ -52,6 +52,7 @@ import * as remoteModule from "../lib/remote.mjs";
52
52
  import { activateLocalInputs, localRevision } from "../lib/local-inputs.mjs";
53
53
  import YAML from "yaml";
54
54
  import { attachArgv, checkRemote, connectServer, forgetSnapshot, getServer, inspectRemote, startRemote, restartRemote, launchConfigRemote, scheduleRemote, listSnapshots, learnWorkspaceKey, readServers, redactArgv, reportedWorkspaceKey, rosterGroups, routeCapability, routeCommand, runRemote, serverFlagOf, targetOf, updateServers, validateServer, workspaceKeyOfStatus, workspaceMismatch, SERVERS_FILE } from "../lib/servers.mjs";
55
+ import { readSessionViewer } from "../lib/session-viewer.mjs";
55
56
  import { spawnSync as spawnSyncProc } from "node:child_process";
56
57
  import { tickTriggers } from "../lib/triggers.mjs";
57
58
  import * as A from "../lib/automations.mjs";
@@ -69,6 +70,7 @@ import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withCompos
69
70
  import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mjs";
70
71
  import { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } from "../lib/deployments.mjs";
71
72
  import { observeResolvedDeployment } from "../lib/resolved-deployment.mjs";
73
+ import { SESSION_RESUME_FEATURE } from "../lib/session-resume-contract.mjs";
72
74
 
73
75
  const rawArgs = process.argv.slice(2);
74
76
  /** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
@@ -108,7 +110,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
108
110
  * probe) and in `status --json`, which a remote roster relays as the host's (feature
109
111
  * server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
110
112
  * time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
111
- const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "instance-suggest-name", "spawn-apply-suggest-name"];
113
+ const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE];
112
114
  /** Commands `--server <id>` runs on a registered server. */
113
115
  const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
114
116
  const flag = (name) => {
@@ -824,6 +826,19 @@ function doctorRetained(ws) {
824
826
  const kept = retainedWorktrees(deployment);
825
827
  return [retainedRecoveryLines(join(deployment, "agents"), kept), retainedWorktreeLines(kept)].filter((block) => block.length);
826
828
  }
829
+ /** The machine's launch configurations file (awebai/oats#1506) as doctor reports it: its path, whether
830
+ * it is there, its entries' names and whether it is valid. A broken file is reported, never a failure
831
+ * of doctor; the launches it would affect refuse it. */
832
+ function doctorMachineLaunchConfigs() {
833
+ const file = machineLaunchConfigsFile();
834
+ try {
835
+ const machine = machineLaunchConfigs();
836
+ return { file, present: machine !== null, ok: true, configurations: Object.keys(machine?.configs ?? {}).sort() };
837
+ } catch (e) {
838
+ if (e?.code !== "E_LAUNCH_CONFIG_INVALID") throw e;
839
+ return { file, present: true, ok: false, configurations: [], error: e.message };
840
+ }
841
+ }
827
842
  async function doctorWorkspaceJson(ctx, soulName, ws) {
828
843
  const composition = await doctorComposition(ctx, soulName, ws, (code, msg, details) => jsonFail(code, msg, details));
829
844
  const agentsRoot = join(dirname(ws.local.path), "agents");
@@ -839,6 +854,7 @@ async function doctorWorkspaceJson(ctx, soulName, ws) {
839
854
  workspace: { file: ws.local.path, ref: ws.local.workspace },
840
855
  workspaceError: ws.localError, lockFile: ws.lockFile, packages: ws.packages, lockError: ws.lockError,
841
856
  information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
857
+ machineLaunchConfigs: doctorMachineLaunchConfigs(),
842
858
  composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
843
859
  ...(problems.length ? { problems } : {}),
844
860
  warnings: [...hookEvents.warnings, ...(soulName ? [] : doctorCaptureWarnings())],
@@ -876,6 +892,9 @@ async function doctor(dir) {
876
892
  doctorVersionSkew(dirname(ws.local.path));
877
893
  const composition = await doctorComposition(ctx, soulName, ws, (code, msg) => die(`${msg} [${code}]`));
878
894
  printDoctorWorkspace(ws);
895
+ const machine = doctorMachineLaunchConfigs();
896
+ console.log("\nThis machine's launch configurations:");
897
+ console.log(` ${shortPath(machine.file)} ${!machine.present ? "(none: no file)" : machine.ok ? (machine.configurations.join(", ") || "(none declared)") : `ERROR: ${terminalText(machine.error)}`}`);
879
898
  const agentsRoot = join(dirname(ws.local.path), "agents");
880
899
  const localTeams = doctorLocalTeams(ws.local.value);
881
900
  for (const p of [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot)].filter(Boolean)) console.log(`\n! ${p.code}: ${p.message}`);
@@ -984,6 +1003,15 @@ function readLaunchConfigsModel(local) {
984
1003
  for (const [n, e] of Object.entries(map)) out[n] = normalizeLaunchConfig(e);
985
1004
  return out;
986
1005
  }
1006
+ /** Whether the machine's launch configurations file declares `name`; a broken file declares nothing here
1007
+ * (the launches it affects refuse it). */
1008
+ /** The file a launch configuration of this machine was declared in, from its `source` directory. */
1009
+ function launchConfigFile(source) {
1010
+ return source === dirname(machineLaunchConfigsFile()) ? machineLaunchConfigsFile() : join(source, "oats-local.yaml");
1011
+ }
1012
+ function machineDeclares(name) {
1013
+ try { return Object.hasOwn(machineLaunchConfigs()?.configs ?? {}, name); } catch (e) { if (e?.code === "E_LAUNCH_CONFIG_INVALID") return false; throw e; }
1014
+ }
987
1015
  /** What a GUI or an operator sees of one configuration. Environment values
988
1016
  * never leave the file: a literal is answered as {redacted: true} (literals
989
1017
  * are non-secret by contract, but no value is shown anywhere) and a
@@ -1092,10 +1120,10 @@ async function launchConfigCmd() {
1092
1120
  let configurations;
1093
1121
  try { configurations = effective(); } catch (e) { bail(e.code || "E_LAUNCH_CONFIG_INVALID", e.message); }
1094
1122
  if (JSON_MODE) { jsonOk({ context: dir, level, file, selected, configurations }); return; }
1095
- if (!configurations.length) { console.log(`No launch configurations are declared${file ? ` in ${shortPath(file)}` : ` (no oats-local.yaml in reach of ${dir})`}`); return; }
1123
+ if (!configurations.length) { console.log(`No launch configurations are declared${file ? ` in ${shortPath(file)}` : ` (no oats-local.yaml in reach of ${dir})`} or in ${shortPath(machineLaunchConfigsFile())}`); return; }
1096
1124
  for (const c of configurations) {
1097
1125
  const env = Object.entries(c.env).map(([n, v]) => v.fromEnv ? `${n}=$${v.fromEnv}` : `${n}=<redacted>`).join(" ");
1098
- console.log(`${c.name}: ${c.harness}${c.default ? ` (this machine's ${c.harness} default)` : ""}${c.executable ? ` ${c.executable}` : ""}${c.args.length ? ` ${c.args.map((a) => JSON.stringify(a)).join(" ")}` : ""}${env ? ` [${env}]` : ""}${c.model ? ` model ${c.model}` : ""}${c.yolo !== null ? ` yolo ${c.yolo}` : ""}`);
1126
+ console.log(`${c.name}: ${c.harness}${c.default ? ` (this machine's ${c.harness} default)` : ""}${c.executable ? ` ${c.executable}` : ""}${c.args.length ? ` ${c.args.map((a) => JSON.stringify(a)).join(" ")}` : ""}${env ? ` [${env}]` : ""}${c.model ? ` model ${c.model}` : ""}${c.yolo !== null ? ` yolo ${c.yolo}` : ""} (from ${shortPath(launchConfigFile(c.source))})${c.shadows.length ? ` (replaces ${c.shadows.map(shortPath).join(", ")}'s)` : ""}`);
1099
1127
  }
1100
1128
  return;
1101
1129
  }
@@ -1141,16 +1169,18 @@ async function launchConfigCmd() {
1141
1169
  const declaredHere = Object.hasOwn(model, name);
1142
1170
  before = declaredHere ? publicLaunchConfig(model[name]) : null;
1143
1171
  if (sub === "remove") {
1144
- if (!declaredHere) throw refusal("E_LAUNCH_CONFIG_UNKNOWN", `${name} is not declared in ${shortPath(file)}`);
1172
+ if (!declaredHere) throw refusal("E_LAUNCH_CONFIG_UNKNOWN", `${name} is not declared in ${shortPath(file)}${machineDeclares(name) ? `; it is this machine's, in ${shortPath(machineLaunchConfigsFile())}, which OATS never writes` : ""}`);
1145
1173
  delete model[name];
1146
1174
  } else {
1147
1175
  let written = entry;
1148
1176
  if (keepEnv) {
1149
1177
  // An editor that saw only redacted values keeps the environment of the
1150
1178
  // declared definition of that name: a one-time copy into the complete
1151
- // replacement entry.
1152
- const current = declaredHere ? model[name] : undefined;
1153
- if (!current) throw refusal("E_LAUNCH_CONFIG_UNKNOWN", `--keep-env: no launch configuration ${name} is declared in ${shortPath(file)}, so there is no environment to keep; declare it with env`);
1179
+ // replacement entry. A name only this machine declares keeps the machine
1180
+ // entry's, so the first save of a machine row writes the entry that shadows it.
1181
+ let current = declaredHere ? model[name] : undefined;
1182
+ if (!current) { try { const machine = machineLaunchConfigs()?.configs ?? {}; if (Object.hasOwn(machine, name)) current = machine[name]; } catch (e) { throw refusal(e.code || "E_LAUNCH_CONFIG_INVALID", e.message, e.details); } }
1183
+ if (!current) throw refusal("E_LAUNCH_CONFIG_UNKNOWN", `--keep-env: no launch configuration ${name} is declared in ${shortPath(file)} or in ${shortPath(machineLaunchConfigsFile())}, so there is no environment to keep; declare it with env`);
1154
1184
  if (Object.keys(current.env || {}).length) written = { ...entry, env: { ...current.env } };
1155
1185
  try { validateLaunchConfig(name, written, `--file ${f}`); } catch (e) { throw refusal(e.code || "E_LAUNCH_CONFIG_INVALID", e.message); }
1156
1186
  }
@@ -2754,7 +2784,7 @@ async function status() {
2754
2784
  const observation = maxAgeGiven === null ? {} : { observation: observationBlock() };
2755
2785
  // `features` (feature server-probe-features): this kernel's own list, as `version --json` answers
2756
2786
  // it, so a remote roster relays the host's without probing it. Never part of a reused observation.
2757
- console.log(JSON.stringify({ root, agents: data, ...observation, features: KERNEL_FEATURES, ...(ws ? { workspace: { ...(ws.unreachable ? { reachable: false, ...ws.unreachable } : { reachable: true }), ...workspaceIdentity(ws.local, ws.discovery) } } : {}), ...(problems.length ? { problems } : {}), ...envelopeWarnings() }, null, 2)); return;
2787
+ console.log(JSON.stringify({ root, agents: data, ...observation, features: KERNEL_FEATURES, sessionViewer: readSessionViewer(), ...(ws ? { workspace: { ...(ws.unreachable ? { reachable: false, ...ws.unreachable } : { reachable: true }), ...workspaceIdentity(ws.local, ws.discovery) } } : {}), ...(problems.length ? { problems } : {}), ...envelopeWarnings() }, null, 2)); return;
2758
2788
  }
2759
2789
  console.log(`oats status — agents root ${shortPath(root)}\n`);
2760
2790
  if (ws?.unreachable) console.log(` workspace: unreachable (${ws.unreachable.reason}) — drift unknown\n`);
@@ -2840,7 +2870,7 @@ function namingLine(naming) {
2840
2870
  function printSpawnPreview(r, { server, soulFetched = false } = {}) {
2841
2871
  // A host before 0.27 names the harness `runtime` (it still answers spawn-preview-2).
2842
2872
  const harness = r.harness ?? r.runtime;
2843
- console.log(`preview ${r.agent} → ${r.instance}${server ? ` on ${server}` : ""} (${r.work}${r.branch ? `, branch ${r.branch}${r.base ? ` from ${r.base.ref}@${r.base.oid.slice(0, 12)}` : ""}` : ""}) harness ${harness}${r.model ? ` model ${r.model}` : ` (${r.modelSource})`}${r.launchConfig ? ` via launch configuration ${r.launchConfig}${r.launchConfigDefault ? ` (${server ? "the server's" : "this machine's"} ${harness} default)` : ""}` : ""}${r.yolo ? " YOLO" : ""}; nothing was created${soulFetched ? " (the soul source was fetched to a temporary copy, not kept)" : ""}`);
2873
+ console.log(`preview ${r.agent} → ${r.instance}${server ? ` on ${server}` : ""} (${r.work}${r.branch ? `, branch ${r.branch}${r.base ? ` from ${r.base.ref}@${r.base.oid.slice(0, 12)}` : ""}` : ""}) harness ${harness}${r.model ? ` model ${r.model}` : ` (${r.modelSource})`}${r.launchConfig ? ` via launch configuration ${r.launchConfig}${r.launchConfigDefault ? ` (${server ? "the server's" : "this machine's"} ${harness} default)` : ""}${r.launchConfigSource ? ` from ${server ? terminalText(r.launchConfigSource) : shortPath(launchConfigFile(r.launchConfigSource))}` : ""}` : ""}${r.yolo ? " YOLO" : ""}; nothing was created${soulFetched ? " (the soul source was fetched to a temporary copy, not kept)" : ""}`);
2844
2874
  // Feature spawn-suggest-name: how the name was chosen.
2845
2875
  { const line = namingLine(r.naming); if (line) console.log(`name: ${line}`); }
2846
2876
  if (Array.isArray(r.worktreeHooks)) console.log(r.worktreeHooks.length ? `worktree hooks: ${r.worktreeHooks.map((h) => `${h.capability}${h.required ? " (required)" : ""}`).join(", ")}` : "worktree hooks: none");
@@ -3579,14 +3609,37 @@ async function sessionCmd() {
3579
3609
  if (args[1] === "attach") {
3580
3610
  if (JSON_MODE) throw Object.assign(new Error("session attach is interactive; omit --json"), { code: "E_BAD_ARGS" });
3581
3611
  // --detach-key (feature session-attach-detach-key): the one key that leaves this viewer, with
3582
- // status 20. Without it every key reaches the agent and there is no keyboard exit.
3612
+ // status 20. Without it every key but the viewer's scrollback key reaches the agent and there is
3613
+ // no keyboard exit.
3583
3614
  // What earlier attaches left (a viewer whose attach died without detaching): one line, on
3584
3615
  // stderr, before the client takes the terminal, and only when something was removed.
3585
3616
  const onSwept = ({ sessions, tables }) => {
3586
3617
  const n = (count, what) => `${count} ${what}${count === 1 ? "" : "s"}`;
3587
3618
  if (sessions + tables > 0) console.error(`oats: removed ${n(sessions, "leftover viewer session")} and ${n(tables, "key table")} of earlier attaches`);
3588
3619
  };
3589
- process.exitCode = await attachInstanceSession(home, { detachKey: valueFlag("detach-key"), onSwept });
3620
+ // --no-status-line (feature session-attach-no-status-line): a viewer without its status line,
3621
+ // the scroll keys, for a caller that shows them itself.
3622
+ process.exitCode = await attachInstanceSession(home, { detachKey: valueFlag("detach-key"), statusLine: !args.includes("--no-status-line"), onSwept });
3623
+ return;
3624
+ }
3625
+ if (args[1] === "resume") {
3626
+ // The machine sweep (feature session-resume, #1559): lib/session-resume.mjs. No --home: one home
3627
+ // is `session start --resume`.
3628
+ const usage = "usage: oats session resume [--deployment <dir>] [--plan] [--json]";
3629
+ for (let i = 2; i < args.length; i++) {
3630
+ const a = args[i];
3631
+ if (a === "--deployment") { i++; continue; }
3632
+ if (a.startsWith("--deployment=") || a === "--plan" || a === "--json") continue;
3633
+ throw Object.assign(new Error(a.startsWith("-") ? `oats session resume: unknown flag ${a}\n${usage}` : `oats session resume takes no argument ${JSON.stringify(a)}\n${usage}`), { code: "E_BAD_ARGS" });
3634
+ }
3635
+ const deployment = flag("deployment");
3636
+ if (deployment === true || (typeof deployment === "string" && !deployment.trim())) throw Object.assign(new Error(`--deployment needs a deployment directory\n${usage}`), { code: "E_BAD_ARGS" });
3637
+ const { resumeSessions } = await import("../lib/session-resume.mjs");
3638
+ const answer = await resumeSessions({ deployment, plan: args.includes("--plan"), kernel: { execPath: process.execPath, bin: CLI_BIN } });
3639
+ if (JSON_MODE) { jsonOk(answer); return; }
3640
+ for (const d of answer.deployments) console.log(`${d.deployment}: ${d.swept ? "swept" : `not swept (${d.reason}${d.code ? `, ${d.code}` : ""})`}`);
3641
+ for (const r of answer.rows) console.log(` ${r.instance} ${answer.plan ? "would be " : ""}${r.outcome}${r.reason ? ` (${r.reason}${r.code ? `, ${r.code}` : ""})` : ""}${r.message ? `: ${terminalText(r.message)}` : ""}`);
3642
+ if (!answer.rows.length) console.log("nothing to resume");
3590
3643
  return;
3591
3644
  }
3592
3645
  if (args[1] === "inspect") result = inspectInstanceSession(home);
@@ -3603,9 +3656,17 @@ async function sessionCmd() {
3603
3656
  // recorded launch stays frozen (a changed preference never reaches an existing home on its own).
3604
3657
  const reselectLaunch = args.includes("--reselect-launch");
3605
3658
  if (reselectLaunch && launchConfig !== undefined) bad("--reselect-launch applies the launch preferences; --launch-config names one explicitly — choose one");
3659
+ // --resume (feature session-resume): the recorded launch as it is, in the home's last conversation;
3660
+ // refused with a launch choice before anything of the home is read.
3661
+ const resume = args.includes("--resume");
3662
+ if (resume) {
3663
+ if (args[1] === "restart") bad("--resume exists on session start only: it brings back a session that was lost");
3664
+ const chosen = ["--launch-config", "--harness", "--model", "--yolo", "--no-yolo", "--reselect-launch"].filter((f) => args.some((a) => a === f || a.startsWith(`${f}=`)));
3665
+ if (chosen.length) bad(`--resume runs the launch this home recorded; it cannot be combined with ${chosen.join(", ")}; nothing was read or started`);
3666
+ }
3606
3667
  // Refuse before launch selection or live-team discovery can prepare this home.
3607
3668
  assertNoPartialUpgrade(home);
3608
- const opts = { model: model || undefined, launchConfig, harness, yolo: yoloFlag(), ...(reselectLaunch ? { reselectLaunch: true, launchOffered: await homeLaunchOffered(home, { named: harness !== undefined }) } : {}), env: process.env, ...(await homeLiveTeams(home)) };
3669
+ const opts = { model: model || undefined, launchConfig, harness, yolo: yoloFlag(), ...(reselectLaunch ? { reselectLaunch: true, launchOffered: await homeLaunchOffered(home, { named: harness !== undefined }) } : {}), ...(resume ? { resume: true } : {}), env: process.env, ...(await homeLiveTeams(home)) };
3609
3670
  if (args[1] === "restart") {
3610
3671
  const grace = flag("stop-grace");
3611
3672
  if (grace !== undefined) { if (grace === true || !/^\d+$/.test(String(grace)) || Number(grace) < 1 || Number(grace) > 300) bad("--stop-grace needs a number of seconds (1..300) to wait for the harness after SIGTERM"); opts.stopGraceMs = Number(grace) * 1000; }
@@ -3628,7 +3689,7 @@ async function sessionCmd() {
3628
3689
  const file = flag("file");
3629
3690
  if (!file || file === true) throw Object.assign(new Error("session upload needs --file <local path>"), { code: "E_BAD_ARGS" });
3630
3691
  result = uploadAttachment({ file, home: home === true ? undefined : home });
3631
- } 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" });
3692
+ } 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] [--no-status-line] [--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" });
3632
3693
  if (JSON_MODE) jsonOk(result);
3633
3694
  else {
3634
3695
  console.log(JSON.stringify(result, null, 2));
@@ -4255,7 +4316,7 @@ function versionCmd() {
4255
4316
  // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
4256
4317
  // runs on resolve/materialize (contract §6); a feature the binary does not implement is
4257
4318
  // never listed.
4258
- console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: KERNEL_FEATURES, automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1 }));
4319
+ console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: KERNEL_FEATURES, automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1, sessionViewer: readSessionViewer() }));
4259
4320
  return;
4260
4321
  }
4261
4322
  console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -4637,7 +4698,7 @@ async function serverRouteCmd() {
4637
4698
  const detachKey = valueFlag("detach-key");
4638
4699
  if (detachKey !== undefined) process.on("SIGQUIT", () => {});
4639
4700
  let route;
4640
- try { route = attachArgv(id, { ...addr, detachKey }, { skipVersionCheck: args.includes("--print") }); }
4701
+ try { route = attachArgv(id, { ...addr, detachKey, statusLine: !args.includes("--no-status-line") }, { skipVersionCheck: args.includes("--print") }); }
4641
4702
  // ssh failing before the viewer (the version probe, a name resolved through the host's roster)
4642
4703
  // is the failure ssh has under it: exit 255, on which a caller reconnects. Every other refusal,
4643
4704
  // and an ssh that never started (no link can come back), exits 1.
@@ -4779,7 +4840,10 @@ try {
4779
4840
  const kernelArgv = (KERNEL_COMMANDS.has(cmd) && !OWN_ARGV_COMMANDS.has(cmd)) || (ROUTED_COMMANDS.has(cmd) && flag("server") !== undefined);
4780
4841
  if (argvProblem && kernelArgv) cmdFail("E_BAD_ARGS", argvProblem);
4781
4842
  const end = args.indexOf("--"), head = end < 0 ? args : args.slice(0, end);
4782
- const selector = head.find((a) => /^--(deployment|resolution|artifact-set)$/.test(a));
4843
+ // `session resume --deployment <dir>` (feature session-resume) reuses the name for a deployment
4844
+ // the sweep is limited to, not a captured selector.
4845
+ const resumeSweep = cmd === "session" && args[1] === "resume";
4846
+ const selector = head.find((a) => /^--(deployment|resolution|artifact-set)$/.test(a) && !(resumeSweep && a === "--deployment"));
4783
4847
  const refuse = (message, details) => { if (JSON_MODE) jsonFail("E_UNSUPPORTED_MODE", message, details); die(message); };
4784
4848
  if (selector) refuse(`${selector}: a captured selector is refused (the captured/portable path was removed in 0.26); run the command in its workspace deployment or instance home instead`, { selector });
4785
4849
  // --max-age (feature observe-max-age): ONE allow-list for every kernel command, here — never a
@@ -4813,7 +4877,8 @@ try {
4813
4877
  // help, and silent: no output, no change to the command's answer or exit status.
4814
4878
  const LISTS_ITS_DEPLOYMENT = new Set(["automations", "capabilities", "doctor", "harness", "inspect", "instance", "launch-config", "operation", "package", "pane", "readiness", "retire", "schedule", "session", "soul", "souls", "spawn", "status", "sync", "teams", "trigger", "update", "workspace", "worktree"]);
4815
4879
  // `instance suggest-name` records nothing (#1490 §2): the oats-local.yaml it reads is not listed.
4816
- if (LISTS_ITS_DEPLOYMENT.has(cmd) && flag("server") === undefined && !(cmd === "instance" && args[1] === "suggest-name") && !args.slice(1).some((a) => a === "--help" || a === "-h")) observeResolvedDeployment(listResolved);
4880
+ // `session resume` reads the list and never writes it (#1559).
4881
+ if (LISTS_ITS_DEPLOYMENT.has(cmd) && flag("server") === undefined && !(cmd === "instance" && args[1] === "suggest-name") && !(cmd === "session" && args[1] === "resume") && !args.slice(1).some((a) => a === "--help" || a === "-h")) observeResolvedDeployment(listResolved);
4817
4882
  if (cmd === "onboard") {
4818
4883
  if (args.includes("--help") || args.includes("-h")) { if (JSON_MODE) jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); else usageFor(cmd); process.exit(0); }
4819
4884
  await onboardCmd();
@@ -4828,6 +4893,8 @@ if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ co
4828
4893
  if (cmd === "instance" && args[1] === "upgrade" && flag("server") !== undefined) cmdFail("E_BAD_ARGS", "instance upgrade supports local homes only; run it on the deployment host");
4829
4894
  // #1490 §2: the name is decided on the machine that asks, for a spawn that lands elsewhere.
4830
4895
  if (cmd === "instance" && args[1] === "suggest-name" && flag("server") !== undefined) cmdFail("E_BAD_ARGS", "instance suggest-name takes no --server: it runs this machine's harness, for a spawn that may land on another; the host it lands on makes the name unique (or names an unnamed --suggest-name spawn itself)");
4896
+ // Session resume is local only (#1559, D1): a server resumes its own instances.
4897
+ if (cmd === "session" && flag("server") !== undefined && (args[1] === "resume" || args.includes("--resume"))) cmdFail("E_BAD_ARGS", "session resume and session start --resume act on this machine's instances only; a server runs oats session resume itself");
4831
4898
  if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
4832
4899
  else if (cmd === "server") await serverCmd();
4833
4900
  else if (cmd === "deployments") deploymentsCmd();
@@ -4965,8 +5032,10 @@ Usage:
4965
5032
  oats session inspect|attach --server <id> inspect (envelope) or attach a viewer (ssh PTY) for a
4966
5033
  --instance <name> | --home <abs> remote instance, by its saved route or the server's
4967
5034
  [--detach-key <key>] roster (--print shows attach); oats 0.22.2 or later.
4968
- attach --detach-key: as below; the server must
4969
- advertise session-attach-detach-key
5035
+ [--no-status-line] attach --detach-key: as below; the server must
5036
+ advertise session-attach-detach-key.
5037
+ --no-status-line: as below; a server without
5038
+ session-attach-no-status-line shows the line
4970
5039
  oats session start --server <id> start a stopped remote instance in its existing home
4971
5040
  --instance <name> | --home <abs> by its saved route or the server's roster; it must advertise
4972
5041
  [--model <m>] [--json] session-start (oats 0.22.9 or later)
@@ -5002,11 +5071,15 @@ Usage:
5002
5071
  oats deployments import --from desktop <path>... [--json]
5003
5072
  the Desktop's one-time import of its own lists
5004
5073
  oats session inspect|input|attach --home <absolute-home> [--text-file <path>] [--json]
5005
- oats session attach --home <absolute-home> [--detach-key <key>]
5074
+ oats session attach --home <absolute-home> [--detach-key <key>] [--no-status-line]
5006
5075
  a viewer of one instance. <key> (C-<letter>, M-<letter
5007
5076
  or digit>, F1 to F12; 'C-\\' is the suggested one)
5008
5077
  leaves it with exit status 20; without one no key
5009
- leaves it: every key goes to the agent
5078
+ leaves it. Shift+PageUp scrolls back (tmux copy mode:
5079
+ PageUp, PageDown, q leaves), and so does C-b [ in a
5080
+ viewer without a key, whose status line says so
5081
+ (--no-status-line: none); every other key goes to
5082
+ the agent, C-b and the key after it included
5010
5083
  oats schedule list|show <id>|test <id>|add <id> --file <spec.json>|update <id> --file <spec.json>
5011
5084
  enable|disable|run|remove|reconcile <id> workspace-scoped, host-owned schedules (spawn,
5012
5085
  tick [--dry-run] [--host] command or wake jobs on a five-field cron with an
@@ -5044,6 +5117,13 @@ Usage:
5044
5117
  [--reselect-launch] applies the launch preferences now (oats-local.yaml
5045
5118
  souls.launch, the soul's launch); a changed preference
5046
5119
  never reaches an existing home without it or a respawn
5120
+ oats session start --resume --home <abs> start a home whose session was LOST (a reboot, a dead
5121
+ tmux server) in its own last conversation, the
5122
+ recorded launch as is; fresh on TASK.md when none is
5123
+ found (docs/execution-targets.md#resume-after-a-shutdown)
5124
+ oats session resume [--deployment <dir>] resume every lost session of this computer's
5125
+ [--plan] [--json] deployments (one sweep per machine; at most 3 resumes
5126
+ of a home per boot); --plan starts nothing
5047
5127
  oats session restart --home <abs-home> stop the running harness (SIGTERM, bounded wait,
5048
5128
  [same flags] [--stop-grace <s>] never escalated) and start it again in place under
5049
5129
  the same lock; a stop that is not observed is
@@ -1044,7 +1044,8 @@ latest-state capability.
1044
1044
 
1045
1045
  ### oats.core: needs input
1046
1046
 
1047
- oats.core (2.4.0 and later, kernel 0.40.0 and later) tells the deployment
1047
+ oats.core (since 2.4.0, which needs kernel 0.40.0; 2.8.0 needs 0.49.0, as
1048
+ "Across `oats instance upgrade`" below says) tells the deployment
1048
1049
  when an instance is waiting on a human, in two independent ways. Each shows
1049
1050
  on `oats status` and in `oats instance events`. The verbs' contract
1050
1051
  (`oats instance waiting`, `oats instance attention`, the `waiting` event) is
@@ -1091,10 +1092,31 @@ home. Before 2.4.1 it set and cleared the claim of the home its environment
1091
1092
  named, and its `Stop` and `SessionEnd` clears could erase that instance's
1092
1093
  real claim.
1093
1094
 
1095
+ **A set carries what the session waits on** (oats.core 2.8.0,
1096
+ [#1502](https://github.com/awebai/oats/issues/1502)). The script reads the
1097
+ hook's JSON input, at most 64 KiB and for at most 1 s, and its
1098
+ `bin/claude-waiting-message.mjs` makes the claim's `--message` from it. On
1099
+ Claude Code 2.1.300:
1100
+ - an `AskUserQuestion` gives its first question's own words
1101
+ (`tool_input.questions[0].question`), with `(+N more)` when it asks
1102
+ several;
1103
+ - a `Notification` gives its `message`: "Claude needs your permission to use
1104
+ Bash" for a permission prompt, "Claude Code needs your input" for an
1105
+ elicitation dialog.
1106
+
1107
+ The text is made one line, the kernel's refused characters are replaced with
1108
+ U+FFFD, and it is cut to 200 code points with `…`, so the kernel accepts it.
1109
+ An input with no text, or a reader that fails or takes over 1 s, sets the
1110
+ claim without one. A new text for the same reason is a change, so the claim
1111
+ is set again. A set records its intent before it reads the text, and only
1112
+ the latest event's text is ever applied. So a clear or a question that comes
1113
+ while an earlier set is still reading stands, and the earlier text never
1114
+ lands over it.
1115
+
1094
1116
  Claude Code shows an AskUserQuestion through its permission dialog, so that
1095
1117
  dialog's own `permission_prompt` follows the question's set: the script keeps
1096
- the current reason in its marker, and a permission prompt never relabels an
1097
- open question. A granted tool that fails fires `PostToolUseFailure`, not
1118
+ the current reason in its marker (and the text beside it), and a permission
1119
+ prompt never relabels an open question or replaces its text. A granted tool that fails fires `PostToolUseFailure`, not
1098
1120
  `PostToolUse`, so that clears too.
1099
1121
 
1100
1122
  **Subagents' tool calls do not clear.** Background and parallel subagents
@@ -1143,7 +1165,8 @@ clears it.
1143
1165
  in the home (`.oats/modules/oats.core`), which a start does not refresh. A
1144
1166
  home spawned with an oats.core that does not read the variable therefore
1145
1167
  writes its hook's own node path at every start: a restart repairs its
1146
- hooks after each Node upgrade, and a respawn gives it the lasting path. A
1168
+ hooks after each Node upgrade, and a respawn, or an upgrade of its
1169
+ oats.core (below), gives it the lasting path. A
1147
1170
  launch preview writes nothing. Every pass answers `{}`: no launch arguments and no env. Codex
1148
1171
  and pi homes get nothing.
1149
1172
  - **It never hurts the session.** Claude Code reads a hook's stdout and exit
@@ -1216,6 +1239,25 @@ clears it.
1216
1239
  exactly `.claude/settings.json`. oats.core writes it at spawn before the
1217
1240
  retirement baseline is taken, and again at every start.
1218
1241
 
1242
+ **Across `oats instance upgrade`.** oats.core 2.8.0 declares an `upgrade`
1243
+ hook ([the upgrade event](#the-upgrade-event)), not required, so a stopped
1244
+ home whose oats.core moves to it is upgraded rather than respawned. The
1245
+ hook that runs is the destination's, so this covers homes spawned on any
1246
+ earlier oats.core, with or without the emitter. oats.core records no
1247
+ capability metadata, and its settings entries name the module copy's path,
1248
+ `.oats/modules/oats.core`, which an upgrade keeps; the next start's launch
1249
+ hook rewrites them. So `plan` adopts a home whose recorded
1250
+ `capabilityMeta["oats.core"]` is absent or `{}`, or a falsy value (`null`,
1251
+ `false`, `0`, `""`), which the kernel passes in `OATS_META` as `{}`. It
1252
+ refuses any other value as state it cannot vouch for, with the remedy
1253
+ `respawn the instance: oats retire <instance>, then oats spawn`. `apply`
1254
+ returns `{"meta":{}}`, which the kernel records as
1255
+ `capabilityMeta["oats.core"]`, and exits 1 with a JSON `warning` on any other
1256
+ metadata. Neither phase reads the home or calls the host. oats.core 2.8.0
1257
+ requires OATS 0.49.0: an earlier kernel drops a capability that declares a
1258
+ hook event it does not know, so it would lose oats.core whole. Only OATS
1259
+ 0.68.0 and later run the hook.
1260
+
1219
1261
  **Why the project settings file, not `--settings`.** On Claude Code
1220
1262
  2.1.288, Claude honours only the last `--settings` flag on a command line:
1221
1263
  that file replaces earlier ones wholesale, even one with no hooks. The
@@ -1281,7 +1323,9 @@ again" permission rules there.
1281
1323
  so its `Stop` and `SessionEnd` clears can erase the home's own live
1282
1324
  `oats.core` claim ([#557](https://github.com/awebai/oats/issues/557)).
1283
1325
  - A Claude instance spawned before the upgrade gets the emitter only when
1284
- it is respawned. Its launch hook comes from its recorded module copy.
1326
+ it is respawned, or when `oats instance upgrade` moves its oats.core to
1327
+ 2.8.0 or later and it starts again. Its launch hook comes from its
1328
+ recorded module copy.
1285
1329
 
1286
1330
  ## Operations a capability declares
1287
1331
 
@@ -251,6 +251,15 @@ v<semver>` after the logo, which may be caught mid-animation), the error and the
251
251
 
252
252
  A restart where the notice shows records `flag-ignored`.
253
253
 
254
+ **Known limit: a split window.** The confirmation still requires the agent's
255
+ window to have one pane. A start or restart in place on a window that has
256
+ another pane (oats.setup's no-echo prompt, for example) relaunches Claude in
257
+ the agent's pane
258
+ ([which pane is the agent's](execution-targets.md#which-pane-is-the-agents))
259
+ but answers nothing: the home records `launchPrompts.status: "blocked"`, and
260
+ Claude waits at its development-channel prompt for a person, as after any
261
+ blocked start. Close the other pane before the restart.
262
+
254
263
  **The two settings that stop it.** OATS confirms the prompt only because the
255
264
  deployment launches Claude with the development-channel flag. To keep the prompt
256
265
  for a person, stop launching that way: `settings.oats.aweb.delivery: session`
@@ -279,8 +288,8 @@ instance's terminal and press Enter yourself.
279
288
  ## Launch configurations
280
289
 
281
290
  An entry has `harness` (`pi` \| `claude` \| `codex`, required), `executable`
282
- (a bare name looked up on `PATH`, or a path relative to this deployment
283
- directory), `args` (literal, no shell), `env` (a literal string, or
291
+ (a bare name looked up on `PATH`, or a path relative to the directory of the
292
+ file that declares it), `args` (literal, no shell), `env` (a literal string, or
284
293
  `{ fromEnv: NAME }` resolved on the host at start), `model`, `yolo` and
285
294
  `default` (0.32; see [the harness default](#the-harness-default)). A launch
286
295
  configuration is a host choice: a soul never names one.
@@ -315,6 +324,63 @@ configuration is a host choice: a soul never names one.
315
324
  `oats spawn` and reading `aw` mail and chat, and what stays gated.
316
325
  `yolo` is separate and is meant for isolated machines.
317
326
 
327
+ ### This machine's launch configurations
328
+
329
+ `~/.oats/config/launch-configs.yaml` (`$OATS_HOME_DIR/config/` when
330
+ `OATS_HOME_DIR` is set) declares launch configurations for every deployment
331
+ on this machine. The person writes it, or an installer running as the
332
+ person; nothing in OATS writes it.
333
+
334
+ ```yaml
335
+ launch-configs:
336
+ claude-auto:
337
+ harness: claude
338
+ args: ["--permission-mode", "auto"]
339
+ default: true
340
+ ```
341
+
342
+ - **One key.** The file holds `launch-configs:` and nothing else. Its entries
343
+ have exactly the schema of the deployment's block and the same checks.
344
+ - **Missing or broken.** A missing file declares nothing. A file that is there
345
+ but cannot be read, is not valid YAML, is empty, lacks `launch-configs:`,
346
+ has any other top-level key, or holds an invalid entry is refused
347
+ (`E_LAUNCH_CONFIG_INVALID`, naming the file). The refusal reaches every
348
+ listing, preview, spawn and start that reads launch configurations. It is
349
+ never skipped. `oats doctor` reports the file and does not fail on it.
350
+ - **Precedence, by name.** Each deployment reads the machine's entries under
351
+ its own. A deployment entry with the same name replaces the machine's
352
+ whole: no field of the machine's entry is kept. Its `shadows` names the
353
+ machine file. With no deployment in reach, the machine's entries alone
354
+ apply.
355
+ - **Precedence, for the default.** The [harness default](#the-harness-default)
356
+ is per harness. A deployment's `default: true` for a harness wins over the
357
+ machine's: the machine's entry for that harness stays listed, but not as
358
+ default. The machine's default applies when the deployment declares none
359
+ for that harness. Two defaults for one harness within one file are refused,
360
+ as in the deployment.
361
+ - **`source`** is the directory an entry was declared in: the deployment
362
+ directory, or `~/.oats/config`. A relative `executable` resolves against
363
+ it.
364
+ - **Where it shows.**
365
+ - `oats launch-config list` (and `--json`) gives each entry's `source` and
366
+ `shadows`.
367
+ - `oats spawn --preview` names the machine file when it supplied the
368
+ configuration; the JSON carries `launchConfigSource`.
369
+ - `oats doctor --json` reports the file under `machineLaunchConfigs`:
370
+ `file`, `present`, `ok`, `configurations` (the names) and, when broken,
371
+ `error`.
372
+ - **Writes.** `oats launch-config set|remove` writes only the deployment's
373
+ `oats-local.yaml`. Setting a name the machine also declares adds a
374
+ deployment entry that shadows it, and removing that entry uncovers the
375
+ machine's again. Desktop's launch-configuration editor writes the same
376
+ way: saving a row whose source is the machine file writes a deployment
377
+ entry of that name, which then shadows the machine's.
378
+ - **Homes.** A spawn records the configuration as it was, the machine's like
379
+ the deployment's (`launchConfigSource` is the directory it came from). A
380
+ start or restart runs the recorded recipe; a later edit of either file
381
+ reaches a home only through `--launch-config <name>`, `--reselect-launch`
382
+ or a respawn.
383
+
318
384
  ### The harness default
319
385
 
320
386
  `default: true` makes a configuration this host's baseline for its harness