@awebai/oats 0.69.12 → 0.69.15

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 (92) hide show
  1. package/README.md +216 -178
  2. package/bin/oats.mjs +254 -201
  3. package/docs/capabilities.md +58 -13
  4. package/docs/configuration.md +63 -5
  5. package/docs/container.md +291 -0
  6. package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
  7. package/docs/desktop-cli-api.md +590 -55
  8. package/docs/desktop-instance-start.md +4 -1
  9. package/docs/desktop.md +58 -12
  10. package/docs/execution-targets.md +84 -9
  11. package/docs/first-team.md +4 -3
  12. package/docs/implementation.md +99 -32
  13. package/docs/integrations.md +3 -2
  14. package/docs/knowledge-and-learning.md +72 -0
  15. package/docs/oats-local.schema.json +11 -2
  16. package/docs/official-catalog.md +39 -5
  17. package/docs/packages.md +93 -14
  18. package/docs/release-lane.md +2 -1
  19. package/docs/release-notes/v0.69.13.md +767 -0
  20. package/docs/release-notes/v0.69.14.md +83 -0
  21. package/docs/release-notes/v0.69.15.md +444 -0
  22. package/docs/schedules.md +159 -5
  23. package/docs/servers.md +241 -7
  24. package/docs/souls-and-instances.md +223 -14
  25. package/docs/tui.md +1 -1
  26. package/docs/upgrading.md +36 -5
  27. package/docs/workspaces.md +31 -5
  28. package/lib/claim.mjs +20 -5
  29. package/lib/command-flags.mjs +240 -0
  30. package/lib/core.mjs +1004 -633
  31. package/lib/deployments.mjs +4 -3
  32. package/lib/dir-lock.mjs +145 -33
  33. package/lib/errors.mjs +3 -2
  34. package/lib/harness-token.mjs +110 -0
  35. package/lib/host-run.mjs +218 -0
  36. package/lib/host-stop-child.mjs +21 -0
  37. package/lib/hot-reads.mjs +4 -3
  38. package/lib/instance-events.mjs +28 -6
  39. package/lib/instance-git.mjs +165 -14
  40. package/lib/instance-inspect.mjs +6 -1
  41. package/lib/instance-lifecycle.mjs +4 -3
  42. package/lib/instance-listing.mjs +114 -43
  43. package/lib/instance-resolution.mjs +56 -3
  44. package/lib/instance-upgrade.mjs +16 -20
  45. package/lib/kernel-features.mjs +4 -1
  46. package/lib/launch-env-exec.sh +7 -0
  47. package/lib/launch-env.mjs +74 -0
  48. package/lib/launch-preference.mjs +19 -12
  49. package/lib/member-clone.mjs +7 -1
  50. package/lib/packages.mjs +74 -2
  51. package/lib/read-call.mjs +4 -1
  52. package/lib/reader.mjs +3 -2
  53. package/lib/refused-text.mjs +3 -2
  54. package/lib/remote.mjs +126 -31
  55. package/lib/retained-after-retire.mjs +2 -7
  56. package/lib/retire-git-forms.mjs +41 -0
  57. package/lib/retire-incomplete.mjs +96 -0
  58. package/lib/schedule.mjs +239 -21
  59. package/lib/servers.mjs +161 -28
  60. package/lib/session-end.mjs +28 -8
  61. package/lib/session-resume.mjs +63 -56
  62. package/lib/session-seen.mjs +3 -14
  63. package/lib/start-env.mjs +13 -7
  64. package/lib/status-words.mjs +11 -4
  65. package/lib/system-tools.mjs +1 -36
  66. package/lib/teams.mjs +11 -4
  67. package/lib/upgrade-state.mjs +13 -2
  68. package/lib/worktree-hooks.mjs +6 -175
  69. package/lib/worktree.mjs +68 -10
  70. package/package-catalog.json +1 -1
  71. package/package.json +5 -1
  72. package/packages/client/instance-lifecycle.mjs +1 -1
  73. package/packages/client/lifecycle-contract.mjs +3 -1
  74. package/packages/client/session-resume-cli.mjs +2 -1
  75. package/packages/client/session-start.mjs +10 -7
  76. package/packages/client/workspace-cli.mjs +5 -1
  77. package/packages/record/README.md +56 -21
  78. package/packages/record/docs/capture-service.md +8 -5
  79. package/packages/record/docs/turn-record-sot.md +9 -0
  80. package/packages/record/lib/capture-health.mjs +6 -4
  81. package/packages/record/lib/capture-lock.mjs +31 -27
  82. package/packages/record/lib/capture-retained-scratch.mjs +4 -3
  83. package/packages/record/lib/capture-scratch.mjs +2 -1
  84. package/packages/record/lib/derived-state.mjs +4 -2
  85. package/packages/record/lib/index-db.mjs +4 -2
  86. package/packages/record/lib/lock-holder.mjs +21 -0
  87. package/packages/record/lib/private-files.mjs +18 -0
  88. package/packages/record/lib/process-identity.mjs +310 -0
  89. package/packages/record/lib/store.mjs +31 -25
  90. package/share/oats-login-receive +204 -0
  91. package/skills/oats-getting-started/SKILL.md +93 -26
  92. package/lib/tmux-config.mjs +0 -35
package/bin/oats.mjs CHANGED
@@ -54,38 +54,40 @@ const {
54
54
  capabilityManifests, capabilityTrust, capabilityExecutablePath,
55
55
  officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
56
56
  findInstanceHome, findInstanceHomes, homeLaunchLayers, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, suggestSpawnName, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, machineLaunchConfigs, machineLaunchConfigsFile, launchStartNotices, launchReportFor, explicitInstanceName, MAX_INSTANCE_NAME, retireInstance, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, upgradeHoldsClaim, writeHomeRecord, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
57
- FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
57
+ FAILED_SPAWN_BRANCH_LEFT,
58
58
  } = await kernelImport("core", () => import("../lib/core.mjs"));
59
59
  const {
60
60
  writeFileAtomic, LOCK_FILE, canonicalLock, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
61
61
  classifyPackageValue, parsePackageRequest } = await kernelImport("packages", () => import("../lib/packages.mjs"));
62
+ const { harnessToken } = await kernelImport("harness-token", () => import("../lib/harness-token.mjs"));
62
63
  const { harnessTrust } = await kernelImport("harness-trust-write", () => import("../lib/harness-trust-write.mjs"));
63
64
  const { previewLaunchEnvironment, previewPaneEnvironment } = await kernelImport("core", () => import("../lib/core.mjs"));
64
65
  const { PI_BRIDGE, piBridgeFolders, piBridgeSkewWarnings, planPiBridges, piBridgePlanLines, piBridgeStepProblem, piBridgeFailure, kernelLookup, kernelLookupResult, planCliUpdate, desktopFirstLine, bridgeLookup, bridgeLookupProblem } = await kernelImport("pi-bridge", () => import("../lib/pi-bridge.mjs"));
65
66
  const { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, unlockedPackages, workspaceWarnings, memberRowByKey } = await kernelImport("workspace", () => import("../lib/workspace.mjs"));
66
67
  const { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } = await kernelImport("teams", () => import("../lib/teams.mjs"));
67
- const { LAUNCH_KEY_UNCHECKED, LAUNCH_PREFERENCE_UNMATCHED, launchKeyQuoted, launchKeysUnmatched, launchLayers, soulLaunchCommand, unmatchedKeyMessage } = await kernelImport("launch-preference", () => import("../lib/launch-preference.mjs"));
68
- const { terminalText } = await kernelImport("refused-text", () => import("../lib/refused-text.mjs"));
69
- const { qualifiedSoulName, soulCandidates, soulsOffered } = await kernelImport("instance-resolution", () => import("../lib/instance-resolution.mjs"));
68
+ const { LAUNCH_KEY_UNCHECKED, LAUNCH_PREFERENCE_UNMATCHED, LAUNCH_PROBLEM_TEXT_MAX, launchKeyQuoted, launchKeysUnmatched, launchLayers, soulLaunchCommand, uncheckedSentences, unmatchedKeyMessage } = await kernelImport("launch-preference", () => import("../lib/launch-preference.mjs"));
69
+ const { safeText, terminalText } = await kernelImport("refused-text", () => import("../lib/refused-text.mjs"));
70
+ const { disabledEntriesUnmatched, qualifiedSoulName, soulCandidates, soulsOffered } = await kernelImport("instance-resolution", () => import("../lib/instance-resolution.mjs"));
70
71
  const { parseConfigData } = await kernelImport("config-data", () => import("../lib/config-data.mjs"));
71
72
  const remoteModule = await kernelImport("remote", () => import("../lib/remote.mjs"));
72
73
  const { sameRepo } = await kernelImport("repo-moves", () => import("../lib/repo-moves.mjs"));
73
74
  const { OATS_PACKAGE_NAME } = await kernelImport("version", () => import("../lib/version.mjs"));
74
75
  const { activateLocalInputs, localRevision } = await kernelImport("local-inputs", () => import("../lib/local-inputs.mjs"));
75
76
  const { default: YAML } = await kernelImport("yaml", () => import("yaml"));
76
- const { attachArgv, checkRemote, connectServer, forgetSnapshot, getServer, inspectRemote, startRemote, restartRemote, launchConfigRemote, scheduleRemote, listSnapshots, learnWorkspaceKey, readServers, redactArgv, reportedWorkspaceKey, rosterGroups, routeCapability, routeCommand, runRemote, serverFlagOf, targetOf, updateServers, validateServer, workspaceKeyOfStatus, workspaceMismatch, SERVERS_FILE } = await kernelImport("servers", () => import("../lib/servers.mjs"));
77
+ const { attachArgv, checkRemote, connectServer, forgetSnapshot, getServer, inspectRemote, startRemote, restartRemote, launchConfigRemote, scheduleRemote, listSnapshots, learnWorkspaceKey, readServers, readServerOperatorRoutes, redactArgv, reportedWorkspaceKey, rosterGroups, routeCapability, routeCommand, runRemote, serverFlagOf, targetOf, updateServers, validateServer, validateOperatorSshHost, workspaceKeyOfStatus, workspaceMismatch, SERVERS_FILE } = await kernelImport("servers", () => import("../lib/servers.mjs"));
77
78
  const { readSessionViewer } = await kernelImport("session-viewer", () => import("../lib/session-viewer.mjs"));
78
79
  const { tickTriggers } = await kernelImport("triggers", () => import("../lib/triggers.mjs"));
79
80
  const A = await kernelImport("automations", () => import("../lib/automations.mjs"));
80
- const { parseEnvelopeText, unresolvedScheduleAttempts, scheduleScopeOf, listSchedules, describe: describeSchedule, testSchedule, addSchedule, updateSchedule, updateScheduleDescription, setEnabled: setScheduleEnabled, removeSchedule, runNow: runScheduleNow, reconcile: reconcileSchedule, tickHost, tickWorkspace, scopeAutomations, scheduleKind, registerWorkspace, unregisterWorkspace, readRegistry, schedulerStatus, saveWakeForHome, removeWakeForHome, wakeFromFlags, withHostLock, scheduleError, SCHEDULE_API } = await kernelImport("schedule", () => import("../lib/schedule.mjs"));
81
+ const { parseEnvelopeText, SCHEDULE_SLOT_UNREADABLE, SCHEDULE_SLOT_ORPHANED, unresolvedScheduleAttempts, scheduleScopeOf, listSchedules, describe: describeSchedule, testSchedule, addSchedule, updateSchedule, updateScheduleDescription, setEnabled: setScheduleEnabled, removeSchedule, runNow: runScheduleNow, reconcile: reconcileSchedule, tickHost, tickWorkspace, scopeAutomations, scheduleKind, registerWorkspace, unregisterWorkspace, readRegistry, schedulerStatus, saveWakeForHome, removeWakeForHome, wakeFromFlags, withHostLock, scheduleError, SCHEDULE_API } = await kernelImport("schedule", () => import("../lib/schedule.mjs"));
81
82
  const { hostUnitFiles, hostUnitStatus, installHostUnit, uninstallHostUnit } = await kernelImport("schedule-host", () => import("../lib/schedule-host.mjs"));
82
83
  const { kernelNode, stableNode } = await kernelImport("stable-node", () => import("../lib/stable-node.mjs"));
83
84
  const { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } = await kernelImport("attachments", () => import("../lib/attachments.mjs"));
84
- const { observeInstanceGit, diffInstanceFile } = await kernelImport("instance-git", () => import("../lib/instance-git.mjs"));
85
+ const { observeInstanceGit, diffInstanceFile, NO_FILE_MONITOR } = await kernelImport("instance-git", () => import("../lib/instance-git.mjs"));
85
86
  const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstanceSameWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
86
87
  const { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } = await kernelImport("retire-output", () => import("../lib/retire-output.mjs"));
87
88
  const { livenessWord, lostLine, statusWord, waitingLine } = await kernelImport("status-words", () => import("../lib/status-words.mjs"));
88
89
  const { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } = await kernelImport("retained-after-retire", () => import("../lib/retained-after-retire.mjs"));
90
+ const { retireIncompleteProblems } = await kernelImport("retire-incomplete", () => import("../lib/retire-incomplete.mjs"));
89
91
  const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
90
92
  const { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposition, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } = await kernelImport("instance-inspect", () => import("../lib/instance-inspect.mjs"));
91
93
  const { readEvents, setWaiting, incarnationOf } = await kernelImport("instance-events", () => import("../lib/instance-events.mjs"));
@@ -98,12 +100,13 @@ const { callSession, parseMaxAge, readBudget } = await kernelImport("read-call",
98
100
  const { cachedWorkspace, legacyLayoutProblems, statusAnswer, statusView } = await kernelImport("roster-read", () => import("../lib/roster-read.mjs"));
99
101
  const { memberLabel, memberRows, packageRows, standaloneCatalogVersion, standalonePackages, workspaceName, workspaceStatusAnswer, workspaceStatusView } = await kernelImport("workspace-read", () => import("../lib/workspace-read.mjs"));
100
102
  const { expandInlineValues, flagValue } = await kernelImport("argv", () => import("../lib/argv.mjs"));
103
+ const { APPROVAL_REMOVED, NATIVE_RECORD_REFUSED, HOST_RUN_USAGE, RESUME_LOCAL_ONLY, RETIRE_USAGE, SOUL_LAUNCH_USAGE, SPAWN_USAGE, SYNC_USAGE, TEAMS_USAGE, WORKTREE_USAGE, commandArgvProblem, commandFlags } = await kernelImport("command-flags", () => import("../lib/command-flags.mjs"));
101
104
 
102
105
  const rawArgs = process.argv.slice(2);
103
106
  const { argv: args, problem: argvProblem, inline: inlineValues } = expandInlineValues(rawArgs);
104
107
  let cmd = args[0];
105
108
  const HELP_WORDS = new Set(["help", "--help", "-h"]);
106
- const KERNEL_COMMANDS = new Set(["harness", "automations", "trigger", "capture", "capabilities", "deployments", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "onboard", "pane", "reader", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "tui", "update", "version", "workspace", "worktree"]);
109
+ const KERNEL_COMMANDS = new Set(["harness", "automations", "trigger", "capture", "capabilities", "deployments", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "host", "onboard", "pane", "reader", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "tui", "update", "version", "workspace", "worktree"]);
107
110
  /** Commands whose argv another parser reads (packages/record, packages/experimental and packages/tui parse process.argv). */
108
111
  const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental", "tui"]);
109
112
  /** Commands `--server <id>` runs on a registered server. */
@@ -305,6 +308,24 @@ async function doctorOperator(ws) {
305
308
  return { problems: found.map(({ code, label, message, remedy }) => ({ code, ...(label ? { label } : {}), message, remedy })), information: [] };
306
309
  }
307
310
 
311
+ /** This machine's last read of the workspace, for doctor's checks of the soul names in oats-local.yaml:
312
+ * discovered OFFLINE like doctorOperator, from this machine's cache only (cacheOnlyRemote), once per
313
+ * doctor run however many checks ask, and only when one asks. A cache that cannot answer rejects, for
314
+ * each check to say as information (doctorCacheWhy). */
315
+ const doctorReads = new WeakMap();
316
+ function doctorDiscovery(ws) {
317
+ if (!doctorReads.has(ws)) doctorReads.set(ws, (async () => {
318
+ const { cacheOnlyRemote } = await import("../lib/operator-coverage.mjs");
319
+ const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs");
320
+ const deployment = dirname(ws.local.path);
321
+ return discoverOrStandalone(ws.local.value, { lock: readLockIfPresent(deployment), deployment, remoteOptions: remoteOptionsFromEnv(), remote: cacheOnlyRemote() });
322
+ })());
323
+ return doctorReads.get(ws);
324
+ }
325
+ /** Why doctorDiscovery could not answer, as a doctor line says it: a cache miss is the cache's; anything
326
+ * else is named as itself. */
327
+ const doctorCacheWhy = (e) => (e?.code === "E_REMOTE_UNREADABLE" ? `this machine's cache cannot answer (${e.message})` : `${e?.code ? `${e.code}: ` : ""}${e?.message ?? e}`);
328
+
308
329
  /** The keys of oats-local.yaml souls.launch that name no soul (awebai/oats#989), in doctor, OFFLINE like
309
330
  * doctorOperator: the souls are discovered from this machine's cache only, and the one function
310
331
  * (launchKeysUnmatched) decides. A problem per unmatched key, which speaks about this machine's last
@@ -320,13 +341,9 @@ async function doctorLaunchPreferences(ws) {
320
341
  const shown = (list) => (list.length > 3 ? `${list.slice(0, 3).map(launchKeyQuoted).join(", ")} and ${list.length - 3} more` : list.map(launchKeyQuoted).join(", "));
321
342
  let found;
322
343
  try {
323
- const { cacheOnlyRemote } = await import("../lib/operator-coverage.mjs");
324
- const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs");
325
- const deployment = dirname(ws.local.path);
326
- const discovery = await discoverOrStandalone(local, { lock: readLockIfPresent(deployment), deployment, remoteOptions: remoteOptionsFromEnv(), remote: cacheOnlyRemote() });
327
- found = launchKeysUnmatched({ local, offered: soulsOffered(discovery) });
344
+ found = launchKeysUnmatched({ local, offered: soulsOffered(await doctorDiscovery(ws)) });
328
345
  } catch (e) {
329
- const why = e?.code === "E_REMOTE_UNREADABLE" ? `this machine's cache cannot answer (${e.message})` : `${e?.code ? `${e.code}: ` : ""}${e?.message ?? e}`;
346
+ const why = doctorCacheWhy(e);
330
347
  return { problems: [], information: [`launch-preference-unchecked: the keys of oats-local.yaml souls.launch (${shown(keys)}) were not checked against the souls this workspace offers: ${why}; oats sync, then oats souls, then run doctor again (a spawn reads the workspace itself and refuses a key that names no soul)`] };
331
348
  }
332
349
  return {
@@ -337,6 +354,38 @@ async function doctorLaunchPreferences(ws) {
337
354
  };
338
355
  }
339
356
 
357
+ /** The entries of oats-local.yaml souls.disabled that name no soul (oats-project/oats#1772), in doctor,
358
+ * OFFLINE from the read doctorLaunchPreferences uses (doctorDiscovery), and the one function
359
+ * (disabledEntriesUnmatched) decides. Such an entry keeps no soul off this machine: it fails open. A
360
+ * problem per unmatched entry, which speaks about this machine's last read of the souls: a spawn reads
361
+ * the workspace itself and is the authority. An entry that could not be checked, or a cache that cannot
362
+ * answer, is an information line (`disabled-soul-unchecked`), never silence and never a failure of
363
+ * doctor. No command writes souls.disabled, so the remedy is the hand edit. The entry and the nearest
364
+ * souls are said through the launch texts' bound (launchKeyQuoted, safeText).
365
+ * → { problems: [{ code, entry, at, suggestions, message, remedy }], information: [string] } */
366
+ async function doctorDisabledSouls(ws) {
367
+ const local = ws.local.value;
368
+ const entries = Array.isArray(local?.souls?.disabled) ? local.souls.disabled.filter((e) => typeof e === "string") : [];
369
+ if (!entries.length) return { problems: [], information: [] };
370
+ let found;
371
+ try {
372
+ found = disabledEntriesUnmatched({ local, discovery: await doctorDiscovery(ws) });
373
+ } catch (e) {
374
+ const shown = entries.length > 3 ? `${entries.slice(0, 3).map(launchKeyQuoted).join(", ")} and ${entries.length - 3} more` : entries.map(launchKeyQuoted).join(", ");
375
+ return { problems: [], information: [`disabled-soul-unchecked: the entries of oats-local.yaml souls.disabled (${shown}) were not checked against the souls this workspace offers: ${doctorCacheWhy(e)}; oats sync, then oats souls, then run doctor again`] };
376
+ }
377
+ const reasons = uncheckedSentences("entry");
378
+ return {
379
+ problems: found.unmatched.map(({ entry, at, suggestions }) => {
380
+ const near = suggestions.map((name) => safeText(name, LAUNCH_PROBLEM_TEXT_MAX)).join(", ");
381
+ return { code: "disabled-soul-unmatched", entry, at, suggestions,
382
+ message: `oats-local.yaml souls.disabled names ${launchKeyQuoted(entry)}${near ? ` (nearest: ${near})` : ""}, which is no soul in this machine's last read of the souls this workspace offers, so it keeps no soul off this machine. A spawn reads the workspace itself and is the authority`,
383
+ remedy: `in oats-local.yaml souls.disabled, replace ${launchKeyQuoted(entry)} with the soul it was meant to keep off this machine (${near ? `nearest: ${near}; ` : ""}oats souls lists them), or remove it` };
384
+ }),
385
+ information: found.unchecked.map(({ entry, reason }) => `disabled-soul-unchecked: oats-local.yaml souls.disabled ${launchKeyQuoted(entry)} was not checked against the souls this workspace offers: ${reasons[reason] ?? reason}; this is this machine's last read, and a spawn reads the workspace itself`),
386
+ };
387
+ }
388
+
340
389
  /** What the deployment's capabilities declare and this kernel ignores (an unknown hook event), for
341
390
  * doctor without --soul, OFFLINE like doctorOperator, from this machine's parsed cache: each member's
342
391
  * capabilities as `oats sync` enumerated them (the workspace's members confirmed by the cached
@@ -825,6 +874,14 @@ function doctorMachineLaunchConfigs() {
825
874
  return { file, present: true, ok: false, configurations: [], error: e.message };
826
875
  }
827
876
  }
877
+ /** The machine's resume lock when it needs a person (lib/session-resume.mjs resumeLockProblem), as
878
+ * doctor's problems: read where a sweep would take it, nothing taken. It is this machine's, the
879
+ * same from every deployment. */
880
+ async function doctorResumeLock() {
881
+ const { resumeLockProblem } = await import("../lib/session-resume.mjs");
882
+ const problem = resumeLockProblem();
883
+ return problem ? [problem] : [];
884
+ }
828
885
  async function doctorWorkspaceJson(ctx, soulName, ws) {
829
886
  const composition = await doctorComposition(ctx, soulName, ws, (code, msg, details) => jsonFail(code, msg, details));
830
887
  const agentsRoot = join(dirname(ws.local.path), "agents");
@@ -832,14 +889,15 @@ async function doctorWorkspaceJson(ctx, soulName, ws) {
832
889
  const schedules = unresolvedScheduleAttempts(dirname(ws.local.path));
833
890
  const operator = await doctorOperator(ws);
834
891
  const launchPreferences = await doctorLaunchPreferences(ws);
892
+ const disabledSouls = await doctorDisabledSouls(ws);
835
893
  // With --soul, the soul's composition; without, the deployment's capabilities (doctorHookWarnings).
836
894
  const hookEvents = composition ? { warnings: composition.warnings, information: [] } : await doctorHookWarnings(ws);
837
- const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot), ...localTeams.problems, ...schedules.problems, ...operator.problems, ...launchPreferences.problems].filter(Boolean);
895
+ const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot), ...localTeams.problems, ...schedules.problems, ...operator.problems, ...launchPreferences.problems, ...disabledSouls.problems, ...retireIncompleteProblems(agentsRoot), ...await doctorResumeLock()].filter(Boolean);
838
896
  return {
839
897
  schemaVersion: 1, workspaceApi: 2, context: ctx,
840
898
  workspace: { file: ws.local.path, ref: ws.local.workspace },
841
899
  workspaceError: ws.localError, lockFile: ws.lockFile, packages: ws.packages, lockError: ws.lockError,
842
- information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
900
+ information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...disabledSouls.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
843
901
  machineLaunchConfigs: doctorMachineLaunchConfigs(),
844
902
  composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
845
903
  ...(problems.length ? { problems } : {}),
@@ -886,15 +944,20 @@ async function doctor(dir) {
886
944
  for (const p of [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot)].filter(Boolean)) console.log(`\n! ${p.code}: ${p.message}`);
887
945
  for (const p of localTeams.problems) console.log(`\n! ${p.code} (${p.condition}): ${p.message}`);
888
946
  const schedules = unresolvedScheduleAttempts(dirname(ws.local.path));
889
- for (const p of schedules.problems) console.log(`\n! ${p.code}: ${p.message}`);
947
+ for (const p of schedules.problems) console.log(`\n! ${p.code}: ${p.message}${[SCHEDULE_SLOT_UNREADABLE, SCHEDULE_SLOT_ORPHANED].includes(p.code) ? `\n ${p.remedy}` : ""}`);
890
948
  const operator = await doctorOperator(ws);
891
949
  for (const p of operator.problems) console.log(`\n! ${p.code}: ${p.message}\n ${p.remedy}`);
892
950
  const launchPreferences = await doctorLaunchPreferences(ws);
893
951
  for (const p of launchPreferences.problems) console.log(`\n! ${p.code}: ${p.message}\n ${p.remedy}`);
952
+ const disabledSouls = await doctorDisabledSouls(ws);
953
+ for (const p of disabledSouls.problems) console.log(`\n! ${p.code}: ${p.message}\n ${p.remedy}`);
954
+ // Retirements left open (#1747): the command that finishes each, and whose hook failed last.
955
+ for (const p of retireIncompleteProblems(agentsRoot)) console.log(`\n! ${p.code}: ${terminalText(p.message)}\n ${terminalText(p.remedy)}`);
956
+ for (const p of await doctorResumeLock()) console.log(`\n! ${p.code}: ${terminalText(p.message)}\n ${terminalText(p.remedy)}`);
894
957
  const hookEvents = composition ? { warnings: composition.warnings, information: [] } : await doctorHookWarnings(ws);
895
958
  for (const w of hookEvents.warnings) console.log(`\nwarning ${w.code} ${w.message}`);
896
959
  if (!soulName) for (const w of doctorCaptureWarnings()) console.log(`\nwarning ${w.code} ${terminalText(w.message)}`);
897
- for (const line of [...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...hookEvents.information, ...processScanInformation()]) console.log(`\nINFO: ${line}`);
960
+ for (const line of [...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...disabledSouls.information, ...hookEvents.information, ...processScanInformation()]) console.log(`\nINFO: ${line}`);
898
961
  for (const block of doctorRetained(ws)) console.log(`\n${block.map((line) => `INFO: ${line}`).join("\n")}`);
899
962
  if (soulName) {
900
963
  const information = operationalKnowledgeNote(composition, soulName);
@@ -960,7 +1023,7 @@ function serializeLaunchConfigs(map) {
960
1023
  const envNames = Object.keys(e.env || {}).sort();
961
1024
  if (envNames.length) {
962
1025
  lines.push(" env:");
963
- for (const n of envNames) { const v = e.env[n]; if (typeof v === "string") lines.push(` ${n}: ${yamlQuoted(v)}`); else lines.push(` ${n}:`, ` fromEnv: ${v.fromEnv}`); }
1026
+ for (const n of envNames) { const v = e.env[n]; if (typeof v === "string") lines.push(` ${n}: ${yamlQuoted(v)}`); else lines.push(` ${n}:`, v.fromFile !== undefined ? ` fromFile: ${yamlQuoted(v.fromFile)}` : ` fromEnv: ${v.fromEnv}`); }
964
1027
  }
965
1028
  if (e.model !== undefined) lines.push(` model: ${yamlQuoted(e.model)}`);
966
1029
  if (e.yolo !== undefined) lines.push(` yolo: ${e.yolo}`);
@@ -976,7 +1039,7 @@ function normalizeLaunchConfig(e) {
976
1039
  harness: Object.hasOwn(e, "harness") ? e.harness : e.runtime,
977
1040
  ...(e.executable !== undefined ? { executable: e.executable } : {}),
978
1041
  ...(e.args?.length ? { args: [...e.args] } : {}),
979
- ...(e.env && Object.keys(e.env).length ? { env: Object.fromEntries(Object.keys(e.env).sort().map((n) => [n, typeof e.env[n] === "string" ? e.env[n] : { fromEnv: e.env[n].fromEnv }])) } : {}),
1042
+ ...(e.env && Object.keys(e.env).length ? { env: Object.fromEntries(Object.keys(e.env).sort().map((n) => [n, typeof e.env[n] === "string" ? e.env[n] : { ...e.env[n] }])) } : {}),
980
1043
  ...(e.model !== undefined ? { model: e.model } : {}),
981
1044
  ...(e.yolo !== undefined ? { yolo: e.yolo } : {}),
982
1045
  ...(e.default === true ? { default: true } : {}),
@@ -1001,10 +1064,10 @@ function machineDeclares(name) {
1001
1064
  /** What a GUI or an operator sees of one configuration. Environment values
1002
1065
  * never leave the file: a literal is answered as {redacted: true} (literals
1003
1066
  * are non-secret by contract, but no value is shown anywhere) and a
1004
- * reference as {fromEnv: NAME}. An editor keeps a literal it cannot see with
1067
+ * reference as {fromEnv: NAME} or {fromFile: /path}. An editor keeps a literal it cannot see with
1005
1068
  * `set --keep-env`. */
1006
1069
  function publicLaunchConfig(e, extra = {}) {
1007
- const env = Object.fromEntries(Object.keys(e.env || {}).sort().map((n) => [n, typeof e.env[n] === "string" ? { redacted: true } : { fromEnv: e.env[n].fromEnv }]));
1070
+ const env = Object.fromEntries(Object.keys(e.env || {}).sort().map((n) => [n, typeof e.env[n] === "string" ? { redacted: true } : { ...e.env[n] }]));
1008
1071
  return { harness: e.harness, executable: e.executable ?? null, args: [...(e.args || [])], env, model: e.model ?? null, yolo: e.yolo ?? null, default: e.default === true, ...extra };
1009
1072
  }
1010
1073
  /** The scope a launch-config command reads: --dir (or cwd), a running
@@ -1079,7 +1142,7 @@ function launchPreview(bail) {
1079
1142
  const { recipe } = plan;
1080
1143
  const command = renderLaunchRecipe(recipe, { home, instance, redact: true, trustHome: plan.trustHome });
1081
1144
  const d = describeLaunchCommand(command);
1082
- const environment = d.environment.map((e) => e.reference && recipe.env[e.name]?.fromEnv ? { name: e.name, fromEnv: recipe.env[e.name].fromEnv } : e);
1145
+ const environment = d.environment.map((e) => e.reference && recipe.env[e.name] && typeof recipe.env[e.name] === "object" ? { name: e.name, ...recipe.env[e.name] } : e);
1083
1146
  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 });
1084
1147
  }
1085
1148
  async function launchConfigCmd() {
@@ -1090,7 +1153,6 @@ async function launchConfigCmd() {
1090
1153
  if (sub === "preview") { launchPreview(bail); return; }
1091
1154
  if (!["list", "set", "remove"].includes(sub)) bail("E_USAGE", usage);
1092
1155
  const { context: dir, selected } = sub === "list" ? launchConfigContext(bail) : { context: dirFlag(), selected: null };
1093
- if (sub !== "list" && (flag("home") !== undefined || flag("soul") !== undefined)) bail("E_BAD_ARGS", `launch-config ${sub} writes the deployment's oats-local.yaml: address it with --dir, not --home or --soul`);
1094
1156
  // Lead decision 2: launch configurations are a HOST choice, declared in the
1095
1157
  // deployment's oats-local.yaml (found walking up; a home's own deployment).
1096
1158
  const at = selected?.home ?? dir;
@@ -1108,7 +1170,7 @@ async function launchConfigCmd() {
1108
1170
  if (JSON_MODE) { jsonOk({ context: dir, level, file, selected, configurations }); return; }
1109
1171
  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; }
1110
1172
  for (const c of configurations) {
1111
- const env = Object.entries(c.env).map(([n, v]) => v.fromEnv ? `${n}=$${v.fromEnv}` : `${n}=<redacted>`).join(" ");
1173
+ const env = Object.entries(c.env).map(([n, v]) => v.fromEnv ? `${n}=$${v.fromEnv}` : v.fromFile ? `${n}=<file:${v.fromFile}>` : `${n}=<redacted>`).join(" ");
1112
1174
  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)` : ""}`);
1113
1175
  }
1114
1176
  return;
@@ -1210,15 +1272,13 @@ async function launchConfigCmd() {
1210
1272
  function instanceWaitingCmd(sub, bail) {
1211
1273
  dropAmbientRoot();
1212
1274
  const usage = sub === "attention"
1213
- ? "usage: oats instance attention [--message <text>] [--clear] [--json]"
1214
- : "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message <text>] [--home <abs>] [--dir <d>] [--json]";
1275
+ ? "usage: oats instance attention [--message=<text>] [--clear] [--json]"
1276
+ : "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json]";
1215
1277
  const value = (name) => { const v = flag(name); if (v === true) throw Object.assign(new Error(`--${name} needs a value${name === "message" ? " (a message that starts with -- goes as --message=<text>)" : ""}`), { code: "E_BAD_ARGS" }); return v; };
1216
1278
  let home, producer, waiting, reason, message;
1217
1279
  try {
1218
1280
  message = value("message");
1219
1281
  if (sub === "attention") {
1220
- if (args[2] && !args[2].startsWith("--")) return bail("E_BAD_ARGS", usage);
1221
- for (const f of ["home", "dir", "producer", "reason"]) if (args.includes(`--${f}`)) return bail("E_BAD_ARGS", `oats instance attention has no --${f}: it records the agent's own claim on the instance it runs in ($OATS_INSTANCE_HOME); ${usage}`);
1222
1282
  home = process.env.OATS_INSTANCE_HOME;
1223
1283
  if (!home || !isAbsolute(home) || incarnationOf(home) === null) return bail("E_USAGE", `oats instance attention runs inside an instance session: $OATS_INSTANCE_HOME is ${home ? `${home}, which is not an instance home (no readable instance.json)` : "unset"}`);
1224
1284
  producer = "agent"; waiting = !args.includes("--clear");
@@ -1230,7 +1290,7 @@ function instanceWaitingCmd(sub, bail) {
1230
1290
  producer = value("producer"); reason = value("reason");
1231
1291
  if (producer === undefined) return bail("E_BAD_ARGS", `--producer is required; ${usage}`);
1232
1292
  // Producer `agent` is the agent's own claim: only `attention` writes it.
1233
- if (producer === "agent") return bail("E_BAD_ARGS", "--producer agent is reserved for the agent's own claim: use `oats instance attention [--message <text>]` or `oats instance attention --clear` from its session");
1293
+ if (producer === "agent") return bail("E_BAD_ARGS", "--producer agent is reserved for the agent's own claim: use `oats instance attention [--message=<text>]` or `oats instance attention --clear` from its session");
1234
1294
  const homeOpt = flag("home");
1235
1295
  if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
1236
1296
  home = homeOpt ?? (process.env.OATS_INSTANCE_HOME || enclosingInstanceHome(logicalCwd()));
@@ -1252,6 +1312,19 @@ function instanceWaitingCmd(sub, bail) {
1252
1312
  } catch (e) { return bail(e.code || "E_EVENTS_FAILED", e.message, e.candidates ? { candidates: e.candidates } : undefined); }
1253
1313
  }
1254
1314
 
1315
+ /** A caller that closes its end of stdout or stderr (a tool shell killed, Desktop gone, an ssh
1316
+ * session that ended) has only stopped reading: the command goes on to its consistent end, what it
1317
+ * can no longer print is dropped, and its exit status is the one it would have had. Unhandled,
1318
+ * that EPIPE would end this process where it stands: a `worktree add` mid-hook, with no rollback; a
1319
+ * spawn, a retire, a start or a stop that has completed, as if it had failed. For the verbs that
1320
+ * change state: `worktree`, `spawn`, `retire`, `session start`, `session restart` and
1321
+ * `instance stop --apply`. */
1322
+ function outliveReader() {
1323
+ const readerGone = (e) => { if (e?.code !== "EPIPE" && e?.code !== "ERR_STREAM_DESTROYED") throw e; };
1324
+ process.stdout.on("error", readerGone);
1325
+ process.stderr.on("error", readerGone);
1326
+ }
1327
+
1255
1328
  /** `oats worktree add|remove` (#796, feature worktree-event): an instance's extra trees,
1256
1329
  * `<home>/.work-<purpose>`, made from its home (lib/worktree.mjs). The home is
1257
1330
  * $OATS_INSTANCE_HOME (or $OATS_HOME), else the home enclosing the working directory.
@@ -1260,24 +1333,16 @@ function instanceWaitingCmd(sub, bail) {
1260
1333
  async function worktreeCmd() {
1261
1334
  const bail = (code, msg, details, exit) => (JSON_MODE ? jsonFail(code, msg, details, exit) : die(msg, exit));
1262
1335
  const sub = args[1];
1263
- const usage = "usage: oats worktree add --purpose <p> --branch <b> --base <remote-branch> [--repo <member key|clone path>] [--preview] [--json] | oats worktree remove --purpose <p> [--json]";
1336
+ const usage = WORKTREE_USAGE;
1264
1337
  if (!["add", "remove"].includes(sub)) return bail("E_BAD_ARGS", usage);
1265
- if (flag("server") !== undefined) return bail("E_BAD_ARGS", "oats worktree runs in an instance home on this machine; --server is not accepted");
1266
- for (const f of ["dir", "home"]) if (args.includes(`--${f}`)) return bail("E_BAD_ARGS", `oats worktree has no --${f}: it acts on the instance home it runs in; ${usage}`);
1267
1338
  const value = (name) => { const v = flag(name); if (v === true) throw Object.assign(new Error(`--${name} needs a value`), { code: "E_BAD_ARGS" }); return v === undefined ? undefined : String(v); };
1268
1339
  const homeVariable = ["OATS_INSTANCE_HOME", "OATS_HOME"].find((name) => process.env[name]);
1269
1340
  const home = homeVariable ? process.env[homeVariable] : enclosingInstanceHome(logicalCwd());
1270
1341
  if (!home) return bail("E_BAD_ARGS", `oats worktree runs from an instance home: run it in the home (or below it), or with $OATS_INSTANCE_HOME set; ${usage}`);
1271
1342
  const W = await import("../lib/worktree.mjs");
1272
- // A caller that closes its end of stdout or stderr (a tool shell killed, Desktop gone) has only
1273
- // stopped reading: the add or remove goes on to its consistent end, and what it can no longer
1274
- // print is dropped. Unhandled, that EPIPE would end this process mid-hook, with no rollback.
1275
- const readerGone = (e) => { if (e?.code !== "EPIPE" && e?.code !== "ERR_STREAM_DESTROYED") throw e; };
1276
- process.stdout.on("error", readerGone);
1277
- process.stderr.on("error", readerGone);
1343
+ outliveReader();
1278
1344
  try {
1279
1345
  if (sub === "remove") {
1280
- for (const f of ["branch", "base", "repo", "preview"]) if (args.includes(`--${f}`)) return bail("E_BAD_ARGS", `oats worktree remove takes only --purpose; ${usage}`);
1281
1346
  const r = await W.worktreeRemove(resolve(home), { purpose: value("purpose") });
1282
1347
  if (JSON_MODE) { jsonOk(r); return; }
1283
1348
  console.log(r.rolledBack
@@ -1338,7 +1403,6 @@ function retiredInstanceAddresses(root, name, home) {
1338
1403
  async function instanceUpgradeCmd(name, bail) {
1339
1404
  const usage = "usage: oats instance upgrade <instance> [--undo] (--plan | --plan-revision <rev> --idempotency-key <key>) [--home <abs>] [--dir <d>] [--json]";
1340
1405
  if (!name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
1341
- if (serverFlagOf(args)) return bail("E_BAD_ARGS", "instance upgrade supports local homes only; run it on the deployment host");
1342
1406
  const home = flag("home"), revision = flag("plan-revision"), key = flag("idempotency-key");
1343
1407
  if (home === true || (home !== undefined && !isAbsolute(home))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
1344
1408
  const planOnly = args.includes("--plan"), undo = args.includes("--undo");
@@ -1359,8 +1423,6 @@ async function instanceUpgradeCmd(name, bail) {
1359
1423
  } catch (e) { return lifecycleFail(e, "E_UPGRADE_FAILED", { ...e.details, ...(e.plan ? { plan: e.plan } : {}), ...(e.candidates ? { candidates: e.candidates } : {}) }); }
1360
1424
  }
1361
1425
 
1362
- /** The flags `oats instance suggest-name` reads, each taking a value (`--json` aside). */
1363
- const SUGGEST_NAME_FLAGS = new Set(["soul", "task", "task-file", "harness", "model", "launch-config", "dir"]);
1364
1426
  /** `oats instance suggest-name` (feature instance-suggest-name, awebai/oats#1490 §2): the name a spawn
1365
1427
  * of a soul would get by --suggest-name, chosen here for a spawn that may land on another machine
1366
1428
  * (lib/core.mjs suggestSpawnName). Never routed: --server is refused before the route dispatch. */
@@ -1374,12 +1436,6 @@ async function instanceSuggestNameCmd(bail) {
1374
1436
  if (v === undefined || (!inlineValues.has(name) && v.startsWith("--"))) return bail("E_BAD_ARGS", `--${name} needs a value; ${usage}`);
1375
1437
  return v;
1376
1438
  };
1377
- for (let i = 2; i < args.length; i++) {
1378
- const a = args[i];
1379
- if (a === "--json") continue;
1380
- if (!a.startsWith("--") || !SUGGEST_NAME_FLAGS.has(a.slice(2))) return bail("E_BAD_ARGS", `oats instance suggest-name: unexpected ${a.startsWith("--") ? "flag" : "argument"} ${JSON.stringify(a)}; ${usage}`);
1381
- if (!inlineValues.has(a.slice(2))) i++;
1382
- }
1383
1439
  const soul = value("soul"), task = value("task"), taskFile = value("task-file");
1384
1440
  if (soul === undefined) return bail("E_BAD_ARGS", `--soul is required; ${usage}`);
1385
1441
  if ((task === undefined) === (taskFile === undefined)) return bail("E_BAD_ARGS", `give the task with one of --task or --task-file; ${usage}`);
@@ -1397,7 +1453,7 @@ async function instanceCmd() {
1397
1453
  if (sub === "upgrade") return instanceUpgradeCmd(name, bail);
1398
1454
  if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
1399
1455
  if (sub === "suggest-name") return instanceSuggestNameCmd(bail);
1400
- const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message <text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message <text>] [--clear] [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json] | oats instance background <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance same-work <instance> on|off [--home <abs>] [--dir <d>] [--json]";
1456
+ const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message=<text>] [--clear] [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json] | oats instance background <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance same-work <instance> on|off [--home <abs>] [--dir <d>] [--json]";
1401
1457
  if (!["git", "diff", "stop", "events", "color", "background", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
1402
1458
  dropAmbientRoot();
1403
1459
  if (sub === "events") {
@@ -1440,7 +1496,6 @@ async function instanceCmd() {
1440
1496
  const words = [];
1441
1497
  for (let i = 3; i < args.length; i++) { if (args[i] === "--home" || args[i] === "--dir") i++; else if (!args[i].startsWith("--")) words.push(args[i]); }
1442
1498
  const clear = args.includes("--clear");
1443
- if (words.length > 1) return bail("E_BAD_ARGS", `oats instance color takes one colour; ${colorUsage}`);
1444
1499
  const value = words[0];
1445
1500
  if (value !== undefined && clear) return bail("E_BAD_ARGS", `give a colour or --clear, not both; ${colorUsage}`);
1446
1501
  if (value === undefined && !clear) return bail("E_BAD_ARGS", `give a colour or --clear; ${colorUsage}`);
@@ -1513,6 +1568,7 @@ async function instanceCmd() {
1513
1568
  }
1514
1569
  const rev = flag("plan-revision"), key = flag("idempotency-key"), grace = flag("grace-ms");
1515
1570
  if (rev === true || key === true || grace === true) return bail("E_BAD_ARGS", usage);
1571
+ outliveReader();
1516
1572
  const receipt = applyStop(dirFlag(), root, name, { home: homeOpt, recursive, planRevision: rev, idempotencyKey: key, ...(grace !== undefined ? { graceMs: Number(grace) } : {}) });
1517
1573
  // Not part of the receipt, whose shape is contract: on stderr in both modes.
1518
1574
  for (const w of receipt[STOP_WARNINGS] || []) console.error(`oats: warning: ${w}`);
@@ -1620,7 +1676,8 @@ function commandSession() {
1620
1676
  process.on("exit", () => { sayReadNotices(); readSession.closeNow(); });
1621
1677
  for (const [signal, code] of [["SIGINT", 130], ["SIGTERM", 143], ["SIGHUP", 129]]) process.once(signal, () => {
1622
1678
  readSession.closeNow();
1623
- // Another handler (a scheduler lock's release) exits on its own after this one.
1679
+ // Another handler still listening (a naming call's and a lock's, lib/dir-lock.mjs, which raise
1680
+ // the signal again; a held `worktree` hook's, an attach's) ends the command itself after this one.
1624
1681
  if (process.listenerCount(signal) === 0) process.exit(code);
1625
1682
  });
1626
1683
  }
@@ -1707,6 +1764,30 @@ function workspaceContext(bail) {
1707
1764
  return { dir, localPath: found.path, local: found.local, deploymentDir: dirname(found.path), remoteOptions: remoteOptionsFromEnv() };
1708
1765
  }
1709
1766
 
1767
+ /** Tokens are operator-local calls even with --server; the forced-command key is the receiver. */
1768
+ async function harnessTokenCmd() {
1769
+ const usage = "usage: oats harness token set|status|remove <harness> --server <id> [--name <team>] [--stdin] [--json] [--debug]";
1770
+ if (!["set", "status", "remove"].includes(args[2]) || !args[3] || args[3].startsWith("-")) return cmdFail("E_BAD_ARGS", usage);
1771
+ const seen = new Set();
1772
+ for (let i = 4; i < args.length; i++) {
1773
+ const word = args[i];
1774
+ if (seen.has(word)) return cmdFail("E_BAD_ARGS", "Give each token-command flag once.");
1775
+ seen.add(word);
1776
+ if (["--json", "--stdin", "--debug"].includes(word)) continue;
1777
+ if (["--server", "--name"].includes(word) && args[i + 1] && !args[i + 1].startsWith("-")) { i++; continue; }
1778
+ return cmdFail("E_BAD_ARGS", usage);
1779
+ }
1780
+ try {
1781
+ const result = await harnessToken({ action: args[2], harness: args[3], server: valueFlag("server"), name: valueFlag("name"), input: args.includes("--stdin") ? process.stdin : undefined }, { debug: args.includes("--debug") ? (line) => console.error(`oats: ${line}`) : undefined });
1782
+ if (JSON_MODE) jsonOk(result);
1783
+ else {
1784
+ console.log(result.action === "set" ? `Installed ${result.harness} credential for ${result.name} on ${result.server}: ${result.fingerprint}.` : result.action === "remove" ? `Removed ${result.harness} credential for ${result.name} on ${result.server}.` : `${result.harness} credential for ${result.name} on ${result.server}: ${result.fingerprint}, replaced ${result.replacedAt}.`);
1785
+ for (const row of result.staleInstances ?? []) console.log(terminalText(` ${row.instance} (${row.agent}): started ${row.startedAt}; picks up the token at its next start.`));
1786
+ for (const warning of result.warnings) console.error(`oats: warning: ${warning}`);
1787
+ }
1788
+ } catch (e) { cmdFail(e.code || "E_HARNESS_TOKEN_DELIVERY", JSON_MODE ? e.message : terminalText(e.message)); }
1789
+ }
1790
+
1710
1791
  /** An explicit host-local operator action; never routed to a remote adapter. */
1711
1792
  function harnessTrustCmd() {
1712
1793
  if (args[1] !== "trust") return cmdFail("E_BAD_ARGS", "usage: oats harness trust [--dir <deployment>] [--harness claude|codex|all] [--plan] [--json]");
@@ -1825,7 +1906,6 @@ function printTable(header, rows) {
1825
1906
  }
1826
1907
 
1827
1908
  /** `--approve` left with package approval (human decision 2026-09-24). */
1828
- const APPROVAL_REMOVED = "package approval was removed; declaring a package in packages: is the trust decision";
1829
1909
 
1830
1910
  /** The body of `oats sync` — shared by `sync` and `onboard` (which onboards, then syncs the same
1831
1911
  * way). Given a v2 deployment context: discover over the remotes, confirm membership, resolve
@@ -2015,31 +2095,11 @@ function setDisabledHereCli(ws, kind, qid, enabled) {
2015
2095
  return A.setDisabledHere({ deployment: dirname(path), localPath: path }, kind, qid, !enabled);
2016
2096
  }
2017
2097
 
2018
- const SYNC_USAGE = "usage: oats sync [--dir <deployment>] [--plan] [--json]";
2019
- /** Why `oats sync`'s argv is not a sync, or undefined (#731): an unknown flag or a positional is refused
2020
- * before anything is read or written, never ignored. `--approve` keeps its own refusal (performSync). */
2021
- function syncArgvProblem(argv) {
2022
- let dirs = 0;
2023
- for (let i = 1; i < argv.length; i++) {
2024
- const a = argv[i];
2025
- if (a === "--json" || a === "--plan") continue;
2026
- if (a === "--dir") {
2027
- if (dirs++) return { message: `oats sync: give --dir once\n${SYNC_USAGE}`, details: { flag: a } };
2028
- if (argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) i++;
2029
- continue;
2030
- }
2031
- if (a === "--approve") return { message: `--approve: ${APPROVAL_REMOVED}`, details: { flag: a } };
2032
- if (a.startsWith("-")) return { message: `oats sync: unknown flag ${a}\n${SYNC_USAGE}`, details: { flag: a } };
2033
- return { message: `oats sync: unexpected argument ${JSON.stringify(a)}: sync takes no positional (the deployment is --dir <deployment>)\n${SYNC_USAGE}`, details: { argument: a } };
2034
- }
2035
- return undefined;
2036
- }
2037
-
2038
2098
  /** `oats sync [--dir] [--plan] [--json]` — contract §6. `--plan` previews: the same report, nothing written. */
2039
2099
  async function syncCmd() {
2040
2100
  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
2041
- const problem = syncArgvProblem(args);
2042
- if (problem) return bail("E_BAD_ARGS", problem.message, problem.details);
2101
+ // A second --dir: flag() would read the first and drop it.
2102
+ if (args.filter((a) => a === "--dir").length > 1) return bail("E_BAD_ARGS", `oats sync: give --dir once\n${SYNC_USAGE}`, { flag: "--dir" });
2043
2103
  const ctx = workspaceContext(bail);
2044
2104
  const synced = await performSync(ctx, bail, { plan: args.includes("--plan") });
2045
2105
  // One envelope (or the §8 report); success is exit 0 (a failure bails with its code).
@@ -2057,7 +2117,8 @@ function workspaceCheckoutFrom(dir) {
2057
2117
  let inCheckout = false;
2058
2118
  for (let d = current; ; d = dirname(d)) { if (existsSync(join(d, ".git"))) { inCheckout = true; break; } if (dirname(d) === d) break; }
2059
2119
  if (!inCheckout) return null;
2060
- const tracked = spawnSync("git", ["-C", current, "ls-files", "--error-unmatch", "--", "oats-workspace.yaml"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 10000 });
2120
+ // Git reads the checkout's index for this: it does not run the file monitor the checkout's configuration names.
2121
+ const tracked = spawnSync("git", [...NO_FILE_MONITOR, "-C", current, "ls-files", "--error-unmatch", "--", "oats-workspace.yaml"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 10000 });
2061
2122
  return tracked.status === 0 ? { file: candidate, root: current } : null;
2062
2123
  }
2063
2124
  const parent = dirname(current);
@@ -2177,41 +2238,15 @@ async function teamsContext(bail) {
2177
2238
  }
2178
2239
  const positional = (i) => (args[i] !== undefined && !args[i].startsWith("--") ? args[i] : undefined);
2179
2240
 
2180
- /** The flags each `oats teams` form takes (value flags → true), beyond the global `--dir` and `--json`.
2181
- * Anything else is refused, never ignored: a kernel that ignored `--if-absent` would set unconditionally. */
2182
- const TEAMS_FLAGS = {
2183
- "": { "--max-age": true },
2184
- add: { "--team": true, "--description": true, "--no-default": false },
2185
- remove: {},
2186
- default: { "--if-absent": false, "--expect": true },
2187
- };
2188
- /** The first flag `oats teams <sub>` does not take, or undefined. A value flag's value is skipped as flag()
2189
- * reads it (the next word unless it starts with `--`). */
2190
- function teamsUnknownFlag(sub) {
2191
- const takes = { "--dir": true, "--json": false, ...TEAMS_FLAGS[sub ?? ""] };
2192
- for (let i = 1; i < args.length; i++) {
2193
- const a = args[i];
2194
- if (!a.startsWith("-")) continue;
2195
- if (!Object.hasOwn(takes, a)) return a;
2196
- if (takes[a] && args[i + 1] !== undefined && !args[i + 1].startsWith("--")) i++;
2197
- }
2198
- return undefined;
2199
- }
2200
-
2201
2241
  /** `oats teams [--json] | add <label> --team <id> [--description <d>] [--no-default] | remove <label> |
2202
2242
  * default <label> [--if-absent | --expect <label>]` — this deployment's teams (team model 3). Config only:
2203
2243
  * never a provider call. */
2204
2244
  async function teamsCmd() {
2205
2245
  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
2206
- const usage = "usage: oats teams [--json] | oats teams add <label> --team <id> [--description <d>] [--no-default] | oats teams remove <label> | oats teams default <label> [--if-absent | --expect <label>] [--dir <deployment>] [--json]";
2207
- // A single-dash word (`-x`) is a flag, never the subcommand: teamsUnknownFlag names it.
2208
- const sub = positional(1)?.startsWith("-") ? undefined : positional(1);
2209
- if (sub !== undefined && !["add", "remove", "default"].includes(sub)) bail("E_USAGE", usage);
2210
- const unknown = teamsUnknownFlag(sub);
2211
- if (unknown !== undefined) {
2212
- const form = sub ? `oats teams ${sub}` : "oats teams";
2213
- bail("E_USAGE", `${form} does not take ${unknown} (an option this kernel does not know may need a newer kernel; nothing was changed) — ${usage}`, { flag: unknown });
2214
- }
2246
+ const usage = TEAMS_USAGE;
2247
+ // The form and its flags were checked by the dispatch (lib/command-flags.mjs): a word where the form
2248
+ // belongs, and a flag the form does not take, are E_USAGE there.
2249
+ const sub = positional(1);
2215
2250
  const label = sub ? positional(2) : undefined;
2216
2251
  if (sub && label === undefined) bail("E_BAD_ARGS", `oats teams ${sub} needs a team label — ${usage}`);
2217
2252
  const ctx = await teamsContext(bail);
@@ -2276,13 +2311,6 @@ async function soulCmd() {
2276
2311
  if (doc.teams.length) printTable(["team", "id", "from", "why"], doc.teams.map((t) => [t.default ? `${t.label} (default)` : t.label, t.team ?? "(no id yet)", t.from, t.via.join(",")]));
2277
2312
  }
2278
2313
 
2279
- const SOUL_LAUNCH_USAGE = "oats soul launch set <soul>|'*' (--launch-config <name>|none | --harness pi|claude|codex [--model <id>]) [--plan] [--dir <deployment>] [--json] | oats soul launch remove <soul>|'*'|<exact key> [--plan] [--dir <deployment>] [--json]";
2280
- /** The flags each `oats soul launch` form takes (value flags → true). Anything else is refused, never
2281
- * ignored: `--home` and `--soul` among them, since the soul is the argument and the file the deployment's. */
2282
- const SOUL_LAUNCH_FLAGS = {
2283
- set: { "--launch-config": true, "--harness": true, "--model": true },
2284
- remove: {},
2285
- };
2286
2314
  /** A souls.launch entry in words: a launch configuration's name, or the inline harness and model. */
2287
2315
  const launchEntryText = (v) => (v === null ? "no entry" : typeof v === "string" ? (v === "none" ? "none (the bare harness)" : `launch configuration ${v}`) : `${v.harness}${v.model ? ` with model ${v.model}` : ""}`);
2288
2316
 
@@ -2292,23 +2320,22 @@ const launchEntryText = (v) => (v === null ? "no entry" : typeof v === "string"
2292
2320
  async function soulLaunchCmd(bail, usage) {
2293
2321
  const sub = positional(2);
2294
2322
  if (!["set", "remove"].includes(sub)) bail("E_USAGE", usage);
2295
- // Every argument is accounted for before anything is read or written: a flag the form does not take, a
2296
- // value flag with no value at ANY of its occurrences (`--harness codex --harness`), a value flag given
2297
- // twice (flag() would read the first and drop the second) and a second name are refused, never ignored.
2298
- const takes = { "--dir": true, "--json": false, "--plan": false, ...SOUL_LAUNCH_FLAGS[sub] };
2323
+ // Every argument is accounted for before anything is read or written. The dispatch refused a flag the
2324
+ // form does not take and a second name (lib/command-flags.mjs); here a value flag with no value at ANY
2325
+ // of its occurrences (`--harness codex --harness`) and a value flag given twice (flag() would read the
2326
+ // first and drop the second) are refused, never ignored. Its value flags are the declaration's.
2327
+ const { values } = commandFlags(args);
2299
2328
  const names = [], given = new Set();
2300
2329
  for (let i = 3; i < args.length; i++) {
2301
2330
  const a = args[i];
2302
2331
  if (!a.startsWith("-")) { names.push(a); continue; }
2303
- if (!Object.hasOwn(takes, a)) bail("E_USAGE", `oats soul launch ${sub} does not take ${a} (nothing was changed) — usage: ${SOUL_LAUNCH_USAGE}`, { flag: a });
2304
- if (!takes[a]) continue;
2332
+ if (!values.includes(a)) continue;
2305
2333
  if (args[i + 1] === undefined || args[i + 1].startsWith("--")) bail("E_BAD_ARGS", `${a} needs a value`);
2306
2334
  if (given.has(a)) bail("E_BAD_ARGS", `oats soul launch ${sub} takes ${a} once (nothing was changed)`);
2307
2335
  given.add(a);
2308
2336
  i++;
2309
2337
  }
2310
2338
  if (names.length === 0) bail("E_BAD_ARGS", `oats soul launch ${sub} needs ${sub === "set" ? "a soul (or '*')" : "a soul, '*' or the exact text of a key in souls.launch"} — usage: ${SOUL_LAUNCH_USAGE}`);
2311
- if (names.length > 1) bail("E_BAD_ARGS", `oats soul launch ${sub} takes one ${sub === "set" ? "soul" : "soul or key"}, and got ${names.length}: ${names.map((n) => JSON.stringify(n)).join(", ")} (nothing was changed) — usage: ${SOUL_LAUNCH_USAGE}`);
2312
2339
  const name = names[0];
2313
2340
  const V = await import("../lib/soul-launch-verbs.mjs");
2314
2341
  let value = null;
@@ -2618,12 +2645,6 @@ function printStatus({ root, agents: data, ws, problems }, verbose) {
2618
2645
  }
2619
2646
  }
2620
2647
 
2621
- /** The flags `oats spawn` reads: those taking a value, and switches. `--provider` takes two words.
2622
- * `--instance` is refused by a local spawn (with its replacement) but still travels to an older
2623
- * host through `--server`, whose route reads it. `--max-age` reaches here only on a preview or an
2624
- * apply bound by --expect-decision: the dispatch allow-list (maxAgeRefusal) refuses it otherwise. */
2625
- const SPAWN_VALUE_FLAGS = new Set(["agents-root", "backend", "base", "branch", "dir", "expect-decision", "harness", "idempotency-key", "instance", "launch-config", "max-age", "model", "name", "parent", "purpose", "relation", "relative-root", "relative-to", "repo", "runtime", "task", "task-file", "trigger-event", "wake-cron", "wake-every", "wake-file", "wake-json", "wake-message", "wake-message-file", "wake-tz", "work", "work-dir"]);
2626
- const SPAWN_SWITCHES = new Set(["allow-child-spawns", "background", "json", "no-background", "no-child-spawns", "no-launch", "no-yolo", "preview", "same-work", "suggest-name", "yolo"]);
2627
2648
  /** `--suggest-name` (features spawn-suggest-name, spawn-apply-suggest-name): a preview's or an apply's,
2628
2649
  * with no --name, --purpose or --expect-decision. The kernel refuses the same (core.mjs spawnBody); the
2629
2650
  * CLI says it before anything is read or sent. */
@@ -2636,26 +2657,6 @@ function suggestNameProblem(argv) {
2636
2657
  }
2637
2658
  /** `--background` / `--no-background` (feature instance-background): one of them, or neither. */
2638
2659
  const backgroundProblem = (argv) => (argv.includes("--background") && argv.includes("--no-background") ? "choose --background or --no-background, not both" : undefined);
2639
- /** Why `argv` (after `spawn`, the soul first) is not a spawn, or undefined: a positional after the
2640
- * soul or a flag spawn does not read is never ignored. A value flag consumes its value exactly as
2641
- * flag() reads it; a missing value is the flag's own check. */
2642
- function spawnArgvProblem(argv) {
2643
- const soul = argv[0];
2644
- for (let i = 1; i < argv.length; i++) {
2645
- const a = argv[i];
2646
- if (a === "--provider") { i += 2; continue; }
2647
- if (a.startsWith("--")) {
2648
- const name = a.slice(2);
2649
- if (SPAWN_SWITCHES.has(name)) continue;
2650
- if (!SPAWN_VALUE_FLAGS.has(name)) return `oats spawn: unknown flag ${a}`;
2651
- if (argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) i++;
2652
- continue;
2653
- }
2654
- if (/^[A-Za-z0-9_.-]+=/.test(a)) return `oats spawn: unexpected argument ${JSON.stringify(a)} after the soul ${JSON.stringify(soul)}: a capability setting is given as --provider <capability> key=value (here: --provider <capability> ${a})`;
2655
- return `oats spawn: unexpected argument ${JSON.stringify(a)} after the soul ${JSON.stringify(soul)}: spawn takes one soul`;
2656
- }
2657
- return undefined;
2658
- }
2659
2660
  /** The Herdr spawn flags (removed in 0.31.0), named for the refusal; undefined when none is given. */
2660
2661
  function herdrSpawnFlag() {
2661
2662
  if (flag("backend") === "herdr") return "--backend herdr";
@@ -2682,6 +2683,8 @@ function printSpawnPreview(r, { server, soulFetched = false } = {}) {
2682
2683
  for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
2683
2684
  }
2684
2685
  async function spawnCmd() {
2686
+ // The spawn does not need its caller to finish: see outliveReader.
2687
+ outliveReader();
2685
2688
  // JSON mode: contract envelope, stable error codes, stderr-only progress.
2686
2689
  const bail = (code, msg, details, exit) => (JSON_MODE ? jsonFail(code, msg, details, exit) : die(msg, exit));
2687
2690
  const note = (msg) => (JSON_MODE ? console.error(msg) : console.log(msg));
@@ -2696,12 +2699,9 @@ async function spawnCmd() {
2696
2699
  };
2697
2700
  checkDirectoryOptions(requestedWork); // before anything is resolved or written
2698
2701
  const name = args[1];
2699
- if (!name || name.startsWith("--")) bail("E_USAGE", "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>|--suggest-name] [--preview] [--base <ref>] [--model <id>|@native-default] [--allow-child-spawns|--no-child-spawns] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--same-work] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux] [--yolo|--no-yolo] [--background|--no-background] [--model <m>] [--branch <b>] [--no-launch] [--json]");
2702
+ if (!name || name.startsWith("--")) bail("E_USAGE", SPAWN_USAGE);
2700
2703
  // Retired boundary flags (maintainer transport ruling): fail LOUDLY before
2701
2704
  // ANY side effect, including root discovery.
2702
- // Local souls (local-agents/) are gone with the workspace model: a soul is a member
2703
- // repository's souls/<name>, so spawn never writes one.
2704
- for (const removed of ["instructions-file", "def-file"]) if (flag(removed) !== undefined) bail("E_BAD_ARGS", `--${removed} created a local soul under local-agents/, which the workspace model removed — author souls/<name>/soul.yaml + AGENTS.md in a member repository, then \`oats sync\``);
2705
2705
  if (args.includes("--instance")) bail("E_BAD_ARGS", "--instance was removed by the runtime-boundary ruling — use --purpose <slug> (deterministic <agent>-<purpose> naming) or --name <slug> (the exact instance name)");
2706
2706
  // --name <slug>: the exact, unprefixed instance name (human decision 2026-09-24).
2707
2707
  const nameFlag = flag("name");
@@ -2710,8 +2710,6 @@ async function spawnCmd() {
2710
2710
  { const problem = suggestNameProblem(args) ?? backgroundProblem(args); if (problem) bail("E_BAD_ARGS", problem); }
2711
2711
  // The slug rule is checked here too, before any side effect (soul fetch).
2712
2712
  if (nameFlag !== undefined) { try { explicitInstanceName(String(nameFlag)); } catch (e) { bail(e.code, e.message); throw e; } }
2713
- if (args.includes("--ephemeral")) bail("E_BAD_ARGS", "--ephemeral was removed by the runtime-boundary ruling — declare the agent in a capability manifest (agents:) for automatic ephemeral semantics");
2714
- { const problem = spawnArgvProblem(args.slice(1)); if (problem) bail("E_BAD_ARGS", problem); }
2715
2713
  let root;
2716
2714
  // A spawn needs a workspace deployment (lead decision c3-1): no oats-local.yaml
2717
2715
  // in reach is E_LOCAL_MISSING, before anything else is read. The agents root is
@@ -2743,11 +2741,14 @@ async function spawnCmd() {
2743
2741
  {
2744
2742
  let discovery = null;
2745
2743
  try {
2746
- const { prepareInstance, ensureWorkspaceSoul, previewWorkspaceSoul, parseProviderFlags, discoverOrStandalone, agentDirOf } = await import("../lib/instance-resolution.mjs");
2744
+ const { prepareInstance, verifyPreparedPackages, ensureWorkspaceSoul, previewWorkspaceSoul, parseProviderFlags, discoverOrStandalone, agentDirOf } = await import("../lib/instance-resolution.mjs");
2747
2745
  const remoteOptions = remoteOptionsFromEnv();
2748
2746
  const { local, path: localPath } = loadLocal(dirFlag());
2749
2747
  discovery = wsDiscovery = await discoverOrStandalone(local, { deployment: dirname(localPath), remoteOptions });
2750
2748
  wsPrepared = await prepareInstance(dirFlag(), name, { spawn: { providers: parseProviderFlags(providerPairs) }, remoteOptions, discovery });
2749
+ // Each package the soul composes is the content the lock records (E_PACKAGE_INTEGRITY), before the
2750
+ // first write of the spawn: the soul cache below is the first thing a spawn creates under the agents root.
2751
+ await verifyPreparedPackages(wsPrepared);
2751
2752
  const soulName = agentDirOf(wsPrepared.soulEntry);
2752
2753
  let soulDir;
2753
2754
  if (isPreview) {
@@ -2813,7 +2814,13 @@ async function spawnCmd() {
2813
2814
  if (taskText === true) bail("E_BAD_ARGS", "--task needs a value (use --task-file for long tasks)");
2814
2815
  const taskFileFlag = flag("task-file");
2815
2816
  if (taskFileFlag === true) bail("E_BAD_ARGS", "--task-file needs a path");
2816
- if (taskFileFlag && !existsSync(taskFileFlag)) bail("E_BAD_ARGS", `--task-file not found: ${taskFileFlag}`);
2817
+ // `--task-file -` (feature spawn-task-stdin): the task's bytes arrive on stdin, which is how a
2818
+ // routed spawn sends them (lib/servers.mjs routeCommand), so that they are on no command line.
2819
+ let stdinTask;
2820
+ if (taskFileFlag === "-") {
2821
+ if (process.stdin.isTTY) bail("E_BAD_ARGS", "--task-file - reads the task from stdin");
2822
+ try { stdinTask = (await readStreamBounded(process.stdin, MAX_ATTACHMENT_BYTES)).toString("utf8"); } catch (e) { bail("E_BAD_ARGS", `--task-file -: the task could not be read from stdin (${e.message})`); }
2823
+ } else if (taskFileFlag && !existsSync(taskFileFlag)) bail("E_BAD_ARGS", `--task-file not found: ${taskFileFlag}`);
2817
2824
  // --trigger-event <file>: the event a trigger spawns this instance for (lib/triggers.mjs). It is
2818
2825
  // copied to <home>/.oats/trigger-event.json (OATS_TRIGGER_EVENT_FILE) and recorded as instance.json.trigger.
2819
2826
  let triggerEvent;
@@ -2888,7 +2895,7 @@ async function spawnCmd() {
2888
2895
  if (flag("base") === true) bail("E_BAD_ARGS", "--base needs a ref");
2889
2896
  { const spawnOpts = {
2890
2897
  prepared,
2891
- purpose: flag("purpose"), ...(nameFlag !== undefined ? { name: String(nameFlag) } : {}), task: taskText, taskFile: taskFileFlag, relation, relativeTo, relativeRoot,
2898
+ purpose: flag("purpose"), ...(nameFlag !== undefined ? { name: String(nameFlag) } : {}), task: taskText ?? stdinTask, taskFile: stdinTask === undefined ? taskFileFlag : undefined, relation, relativeTo, relativeRoot,
2892
2899
  ...(args.includes("--allow-child-spawns") ? { allowChildSpawns: true } : args.includes("--no-child-spawns") ? { allowChildSpawns: false } : {}),
2893
2900
  // Feature instance-same-work: the kernel binds it to the parent the new home records, or refuses.
2894
2901
  ...(args.includes("--same-work") ? { sameWork: true } : {}),
@@ -2997,9 +3004,7 @@ function failedSpawnBranchLine(r, items, { local = false, host } = {}) {
2997
3004
  let retireReturned = false;
2998
3005
  function retireCmd() {
2999
3006
  const name = args[1];
3000
- // Refused before anything else: before --plan, a replay, a plan revision or a recorded child is stopped.
3001
- if (args.includes("--delete-branch")) return args.includes("--json") ? jsonFail("E_BAD_ARGS", RETIRE_DELETE_BRANCH_REFUSED) : die(RETIRE_DELETE_BRANCH_REFUSED);
3002
- if (!name || name.startsWith("--")) die("usage: oats retire <instance> [--plan] [--plan-revision <rev> --idempotency-key <key>] [--home <path>] [--self] [--discard-worktree] [--keep-dir] [--force] [--json]");
3007
+ if (!name || name.startsWith("--")) return cmdFail("E_USAGE", RETIRE_USAGE);
3003
3008
  let homeFlag = flag("home");
3004
3009
  if (homeFlag === true) die("--home needs the instance home path");
3005
3010
  if (args.includes("--plan")) {
@@ -3022,6 +3027,7 @@ function retireCmd() {
3022
3027
  const isSelf = process.env.OATS_INSTANCE === name;
3023
3028
  if (isSelf && !args.includes("--self")) die(`"${name}" is the calling instance — self-retire is irreversible; if your task is complete and you were told to retire, re-run with --self (finish your memory files FIRST; your session dies ~8s after)`);
3024
3029
  if (!isSelf && args.includes("--self")) die(`--self given but "${name}" is not the calling instance`);
3030
+ outliveReader();
3025
3031
  const root = ensureRoot(dirFlag());
3026
3032
  // K3: a GUI-driven Remove carries the plan revision it showed and an
3027
3033
  // idempotency key. The revision is revalidated against a fresh plan
@@ -3214,6 +3220,8 @@ async function scheduleCmd() {
3214
3220
  const op = args[2];
3215
3221
  const os = flag("os");
3216
3222
  if (os !== undefined && !(op === "install" && args.includes("--print"))) throw scheduleError("E_BAD_ARGS", "--os is for oats schedule host install --print");
3223
+ const registerOnly = op === "install" && args.includes("--register-only");
3224
+ if (registerOnly && args.includes("--print")) throw scheduleError("E_BAD_ARGS", "--register-only records the scope and --print writes nothing: give one");
3217
3225
  if (op === "install" && args.includes("--print")) {
3218
3226
  // What install would write, rendered from this environment; nothing is written or loaded.
3219
3227
  if (os !== undefined && os !== "darwin" && os !== "linux") throw scheduleError("E_BAD_ARGS", "--os darwin|linux");
@@ -3235,14 +3243,17 @@ async function scheduleCmd() {
3235
3243
  };
3236
3244
  const caps = { maxConcurrent: cap("max-concurrent", "default"), triggersMaxConcurrent: cap("triggers-max-concurrent", "none") };
3237
3245
  registerWorkspace(ws(), caps);
3246
+ // --register-only: the scope is in the host registry and no unit is installed, for a host
3247
+ // whose ticker is `oats host run` (a container has neither launchd nor a systemd user manager).
3248
+ if (registerOnly) return out({ scheduler: schedulerStatus(ws(), io), warnings: [] });
3238
3249
  const { warnings } = installHostUnit();
3239
3250
  return out({ scheduler: schedulerStatus(ws(), io), warnings });
3240
3251
  }
3241
3252
  if (op === "uninstall") { unregisterWorkspace(ws()); if (!readRegistry().workspaces.length) uninstallHostUnit(); return out({ scheduler: schedulerStatus(ws(), io) }); }
3242
3253
  if (op === "status") return out({ scheduler: schedulerStatus(ws(), io) });
3243
- throw scheduleError("E_BAD_ARGS", "oats schedule host install [--print [--os darwin|linux]]|uninstall|status");
3254
+ throw scheduleError("E_BAD_ARGS", "oats schedule host install [--register-only | --print [--os darwin|linux]]|uninstall|status");
3244
3255
  }
3245
- 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]");
3256
+ 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 [--register-only] [--max-concurrent <N|default>] [--triggers-max-concurrent <N|none>] | host install --print [--os darwin|linux]|uninstall|status [--dir <workspace>|--server <id>] [--json]");
3246
3257
  }
3247
3258
  } catch (e) {
3248
3259
  // K8b: typed refusal details travel (identity mismatch: key/declared; a refused file: its integrity source).
@@ -3251,6 +3262,31 @@ async function scheduleCmd() {
3251
3262
  }
3252
3263
  }
3253
3264
 
3265
+ /** `oats host run` (lib/host-run.mjs): the resume sweep once, the schedule tick each minute and an
3266
+ * ordered stop of the agents when the host stops, in the foreground. Progress goes to stderr; the
3267
+ * one answer is written when the run ends. */
3268
+ async function hostCmd() {
3269
+ try {
3270
+ const bad = (message) => Object.assign(new Error(message), { code: "E_BAD_ARGS" });
3271
+ if (args[1] !== "run") throw bad(HOST_RUN_USAGE);
3272
+ const grace = flag("stop-grace");
3273
+ if (grace !== undefined && (grace === true || !/^\d+$/.test(String(grace)) || Number(grace) < 1 || Number(grace) > 300)) throw bad("--stop-grace needs a number of seconds (1..300) to wait for each harness after SIGTERM");
3274
+ const { hostRun, hostRunPlan, NO_SCOPE_SAID } = await import("../lib/host-run.mjs");
3275
+ if (args.includes("--plan")) {
3276
+ const plan = await hostRunPlan();
3277
+ if (JSON_MODE) return jsonOk(plan);
3278
+ for (const r of plan.refusals) console.log(`would refuse (${r.code}): ${terminalText(r.message)}`);
3279
+ for (const w of plan.warnings) console.log(`warning: ${terminalText(w)}`);
3280
+ console.log(plan.scopes.length ? `would tick ${plan.scopes.length} scope${plan.scopes.length === 1 ? "" : "s"} each minute: ${plan.scopes.join(", ")}` : NO_SCOPE_SAID);
3281
+ for (const r of plan.sweep.rows) console.log(` ${r.instance} would be ${r.outcome}${r.reason ? ` (${r.reason}${r.code ? `, ${r.code}` : ""})` : ""}${r.message ? `: ${terminalText(r.message)}` : ""}`);
3282
+ if (!plan.sweep.rows.length) console.log("the sweep would find nothing to resume");
3283
+ return;
3284
+ }
3285
+ const answer = await hostRun({ kernel: { execPath: process.execPath, bin: CLI_BIN }, ...(grace !== undefined ? { stopGraceMs: Number(grace) * 1000 } : {}) });
3286
+ if (JSON_MODE) jsonOk(answer);
3287
+ } catch (e) { lifecycleFail(e, "E_HOST_RUN_FAILED", e?.details); }
3288
+ }
3289
+
3254
3290
  /** `oats trigger …` (lib/triggers.mjs): event-driven spawns stored beside the schedules of the
3255
3291
  * deployment scope and evaluated by the same host tick. Every subcommand answers the envelope. */
3256
3292
  async function triggerCmd() {
@@ -3415,7 +3451,7 @@ async function triggerFromPackage(T, from, sets, idFlag) {
3415
3451
 
3416
3452
  async function sessionCmd() {
3417
3453
  try {
3418
- if (flag("native-record") !== undefined) throw Object.assign(new Error("--native-record outcome inspection is gone (the captured/portable path was removed in 0.26)"), { code: "E_BAD_ARGS" });
3454
+ if (flag("native-record") !== undefined) throw Object.assign(new Error(NATIVE_RECORD_REFUSED), { code: "E_BAD_ARGS" });
3419
3455
  const home = flag("home");
3420
3456
  let result;
3421
3457
  if (args[1] === "attach") {
@@ -3437,13 +3473,7 @@ async function sessionCmd() {
3437
3473
  if (args[1] === "resume") {
3438
3474
  // The machine sweep (feature session-resume, #1559): lib/session-resume.mjs. No --home: one home
3439
3475
  // is `session start --resume`.
3440
- const usage = "usage: oats session resume [--deployment <dir>] [--plan] [--json]";
3441
- for (let i = 2; i < args.length; i++) {
3442
- const a = args[i];
3443
- if (a === "--deployment") { i++; continue; }
3444
- if (a.startsWith("--deployment=") || a === "--plan" || a === "--json") continue;
3445
- 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" });
3446
- }
3476
+ const usage = commandFlags(args).usage;
3447
3477
  const deployment = flag("deployment");
3448
3478
  if (deployment === true || (typeof deployment === "string" && !deployment.trim())) throw Object.assign(new Error(`--deployment needs a deployment directory\n${usage}`), { code: "E_BAD_ARGS" });
3449
3479
  const { resumeSessions } = await import("../lib/session-resume.mjs");
@@ -3457,6 +3487,7 @@ async function sessionCmd() {
3457
3487
  if (args[1] === "inspect") result = inspectInstanceSession(home);
3458
3488
  else if (args[1] === "recompose") throw Object.assign(new Error('unknown command "session recompose" — removed by the workspace model v2; use a re-spawn: an instance never changes under itself'), { code: "E_UNKNOWN_COMMAND" });
3459
3489
  else if (args[1] === "start" || args[1] === "restart") {
3490
+ outliveReader();
3460
3491
  const bad = (msg) => { throw Object.assign(new Error(msg), { code: "E_BAD_ARGS" }); };
3461
3492
  const model = flag("model");
3462
3493
  if (model === true) bad("--model needs a model id; omit it to keep the recorded model");
@@ -3472,7 +3503,6 @@ async function sessionCmd() {
3472
3503
  // refused with a launch choice before anything of the home is read.
3473
3504
  const resume = args.includes("--resume");
3474
3505
  if (resume) {
3475
- if (args[1] === "restart") bad("--resume exists on session start only: it brings back a session that was lost");
3476
3506
  const chosen = ["--launch-config", "--harness", "--model", "--yolo", "--no-yolo", "--reselect-launch"].filter((f) => args.some((a) => a === f || a.startsWith(`${f}=`)));
3477
3507
  if (chosen.length) bad(`--resume runs the launch this home recorded; it cannot be combined with ${chosen.join(", ")}; nothing was read or started`);
3478
3508
  }
@@ -4224,7 +4254,7 @@ async function experimentalCmd() {
4224
4254
  async function serverCmd() {
4225
4255
  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
4226
4256
  const sub = args[1];
4227
- const usage = "usage: oats server add <id> --ssh <host-alias> --workspace </abs/path> [--oats <path>] [--path <dir:dir>] [--label <text>] [--replace] | connect <id> --ssh <host-alias> [--workspace-ref <ref>] [--dir </abs/path or ~/path on the host>] [--oats <path>] [--path <dir:dir>] [--label <text>] [--install-oats] [--replace] | list [--workspace-ref <ref>] | remove <id> | check <id> | roster [--server <id>] [--workspace-key <key>]... | forget <id> --instance <name> [--json]";
4257
+ const usage = "usage: oats server add <id> --ssh <host-alias> [--operator-ssh <alias> | --no-operator-ssh] --workspace </abs/path> [--oats <path>] [--path <dir:dir>] [--label <text>] [--replace] | connect <id> --ssh <host-alias> [--operator-ssh <alias> | --no-operator-ssh] [--workspace-ref <ref>] [--dir </abs/path or ~/path on the host>] [--oats <path>] [--path <dir:dir>] [--label <text>] [--install-oats] [--replace] | list [--workspace-ref <ref>] | remove <id> | check <id> | roster [--server <id>] [--workspace-key <key>]... | forget <id> --instance <name> [--json]";
4228
4258
  if (!["add", "connect", "list", "remove", "check", "roster", "forget"].includes(sub)) bail("E_USAGE", usage);
4229
4259
  if (sub === "connect") return serverConnectCmd(bail);
4230
4260
  if (sub === "forget") {
@@ -4274,7 +4304,9 @@ async function serverCmd() {
4274
4304
  let servers;
4275
4305
  try { servers = readServers(); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
4276
4306
  if (sub === "list") {
4277
- let rows = Object.entries(servers).map(([id, s]) => ({ id, ...s, workspaceKey: s.workspaceKey ?? null, target: targetOf({ id, ...s }), snapshots: listSnapshots(id).length }));
4307
+ let routes;
4308
+ try { routes = readServerOperatorRoutes(); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
4309
+ let rows = Object.entries(servers).map(([id, s]) => ({ id, ...s, ...(Object.hasOwn(routes, id) ? routes[id] : {}), workspaceKey: s.workspaceKey ?? null, target: targetOf({ id, ...s }), snapshots: listSnapshots(id).length }));
4278
4310
  // --workspace-ref: the servers of one workspace, by canonical key, and the ids whose workspace is not known yet.
4279
4311
  let unknownWorkspace;
4280
4312
  if (flag("workspace-ref") !== undefined) {
@@ -4288,7 +4320,7 @@ async function serverCmd() {
4288
4320
  if (JSON_MODE) { jsonOk({ file: SERVERS_FILE(), servers: rows, ...(unknownWorkspace ? { unknownWorkspace } : {}) }); return; }
4289
4321
  if (unknownWorkspace?.length) console.log(` (workspace not known yet for ${unknownWorkspace.join(", ")}: oats server check <id> learns it)`);
4290
4322
  if (!rows.length) { console.log(`no servers registered (${shortPath(SERVERS_FILE())}) — add one with \`oats server add <id> --ssh <alias> --workspace </path>\``); return; }
4291
- for (const r of rows) console.log(` ${r.id}${r.label ? ` ${r.label}` : ""}${r.workspaceKey ? ` [${r.workspaceKey}]` : ""}\n ssh ${r.sshHost} workspace ${r.workspace} oats ${r.target.oatsPath}${r.snapshots ? ` (${r.snapshots} remote instance${r.snapshots === 1 ? "" : "s"} spawned from here)` : ""}`);
4323
+ for (const r of rows) console.log(` ${r.id}${r.label ? ` ${r.label}` : ""}${r.workspaceKey ? ` [${r.workspaceKey}]` : ""}\n ssh ${r.sshHost}${r.operatorSshHost ? ` operator ssh ${r.operatorSshHost}` : ""} workspace ${r.workspace} oats ${r.target.oatsPath}${r.snapshots ? ` (${r.snapshots} remote instance${r.snapshots === 1 ? "" : "s"} spawned from here)` : ""}`);
4292
4324
  return;
4293
4325
  }
4294
4326
  const id = args[2];
@@ -4299,12 +4331,23 @@ async function serverCmd() {
4299
4331
  const entry = { sshHost: val("ssh"), workspace: val("workspace") };
4300
4332
  for (const [k, f] of [["oatsPath", "oats"], ["path", "path"], ["label", "label"]]) { const v = val(f); if (v !== undefined) entry[k] = v; }
4301
4333
  if (!entry.sshHost || !entry.workspace) bail("E_USAGE", usage);
4302
- try { validateServer(id, entry); } catch (e) { bail(e.code, e.message); }
4334
+ const operatorSshHost = val("operator-ssh"), noOperatorSsh = args.includes("--no-operator-ssh");
4335
+ if (operatorSshHost !== undefined && noOperatorSsh) bail("E_BAD_ARGS", "choose --operator-ssh or --no-operator-ssh, not both");
4336
+ try { validateServer(id, entry); if (operatorSshHost !== undefined) validateOperatorSshHost(operatorSshHost); } catch (e) { bail(e.code, e.message); }
4337
+ let operatorRoute;
4303
4338
  try {
4304
- updateServers((current) => {
4305
- if (current[id] && !args.includes("--replace")) throw Object.assign(new Error(`server ${id} is already registered (pass --replace to overwrite; existing remote instances keep the route they were spawned with)`), { code: "E_SERVER_EXISTS" });
4339
+ updateServers((current, routes) => {
4340
+ const existing = Object.hasOwn(current, id) ? current[id] : undefined;
4341
+ if (existing && !args.includes("--replace")) throw Object.assign(new Error(`server ${id} is already registered (pass --replace to overwrite; existing remote instances keep the route they were spawned with)`), { code: "E_SERVER_EXISTS" });
4342
+ // An older kernel can remove a registration while leaving its sidecar route behind.
4343
+ if (!existing) delete routes[id];
4344
+ // An unchanged agent target keeps its learned identity when only the operator route changes.
4345
+ if (existing?.workspaceKey && JSON.stringify(targetOf(existing)) === JSON.stringify(targetOf(entry))) entry.workspaceKey = existing.workspaceKey;
4306
4346
  current[id] = entry;
4307
- });
4347
+ if (operatorSshHost !== undefined) routes[id] = { operatorSshHost };
4348
+ else if (noOperatorSsh) delete routes[id];
4349
+ operatorRoute = Object.hasOwn(routes, id) ? routes[id] : undefined;
4350
+ }, { operatorRoutes: true });
4308
4351
  } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
4309
4352
  // The workspace key is learned from the host, never typed: recorded when the host answers one and
4310
4353
  // the registration is still this one (it may change while the host is asked).
@@ -4312,20 +4355,24 @@ async function serverCmd() {
4312
4355
  try {
4313
4356
  const { key, why } = reportedWorkspaceKey(targetOf(entry), { serverId: id, timeoutMs: 60000 });
4314
4357
  if (!key) warnings.push(`workspace key unknown: ${why}; oats server check ${id} learns it once the host answers one`);
4315
- else if (learnWorkspaceKey(id, entry, key) === "recorded") entry.workspaceKey = key;
4316
- else warnings.push(`workspace key not recorded: registration ${id} changed while the host was asked; oats server check ${id} learns it`);
4358
+ else if (["recorded", "same"].includes(learnWorkspaceKey(id, entry, key, { replace: args.includes("--replace") }))) entry.workspaceKey = key;
4359
+ else {
4360
+ delete entry.workspaceKey;
4361
+ warnings.push(`workspace key not recorded: registration ${id} changed while the host was asked; oats server check ${id} learns it`);
4362
+ }
4317
4363
  } catch (e) { warnings.push(`workspace key unknown: ${e.message}; oats server check ${id} learns it once the host answers`); }
4318
- if (JSON_MODE) { jsonOk({ id, ...entry, workspaceKey: entry.workspaceKey ?? null, file: SERVERS_FILE(), ...(warnings.length ? { warnings } : {}) }); return; }
4364
+ if (JSON_MODE) { jsonOk({ id, ...entry, ...operatorRoute, workspaceKey: entry.workspaceKey ?? null, file: SERVERS_FILE(), ...(warnings.length ? { warnings } : {}) }); return; }
4319
4365
  console.log(`Registered server ${id} → ssh ${entry.sshHost}, workspace ${entry.workspace}${entry.workspaceKey ? ` (workspace ${entry.workspaceKey})` : ""} (${shortPath(SERVERS_FILE())}). Verify it with \`oats server check ${id}\`.`);
4320
4366
  for (const w of warnings) console.error(`oats: warning: ${w}`);
4321
4367
  return;
4322
4368
  }
4323
4369
  if (sub === "remove") {
4324
4370
  try {
4325
- updateServers((current) => {
4371
+ updateServers((current, routes) => {
4326
4372
  if (!current[id]) throw Object.assign(new Error(`no server registered as ${id}`), { code: "E_SERVER_UNKNOWN" });
4327
4373
  delete current[id];
4328
- });
4374
+ delete routes[id];
4375
+ }, { operatorRoutes: true });
4329
4376
  } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
4330
4377
  const snaps = listSnapshots(id);
4331
4378
  if (JSON_MODE) { jsonOk({ removed: id, remoteInstancesStillTracked: snaps.map((s) => s.instance) }); return; }
@@ -4368,7 +4415,7 @@ async function serverCmd() {
4368
4415
  * step b): only the person knows where it goes. */
4369
4416
  function serverConnectCmd(bail) {
4370
4417
  const id = args[2];
4371
- if (!id || id.startsWith("--")) bail("E_USAGE", "usage: oats server connect <id> --ssh <host-alias> --dir </abs/path or ~/path on the host> [--workspace-ref <ref>] [--oats <path>] [--path <dir:dir>] [--label <text>] [--install-oats] [--replace] [--json]");
4418
+ if (!id || id.startsWith("--")) bail("E_USAGE", "usage: oats server connect <id> --ssh <host-alias> [--operator-ssh <alias> | --no-operator-ssh] --dir </abs/path or ~/path on the host> [--workspace-ref <ref>] [--oats <path>] [--path <dir:dir>] [--label <text>] [--install-oats] [--replace] [--json]");
4372
4419
  const val = (name) => { const v = flag(name); return v === true ? bail("E_BAD_ARGS", `--${name} needs a value`) : v; };
4373
4420
  const sshHost = val("ssh");
4374
4421
  if (!sshHost) bail("E_BAD_ARGS", "--ssh <host-alias> is required: the OpenSSH host alias of the machine to connect");
@@ -4381,7 +4428,7 @@ function serverConnectCmd(bail) {
4381
4428
  if (!dir) bail("E_BAD_ARGS", `--dir <path on the host> is required: the folder on ${sshHost} for this deployment (absolute, or ~/… resolved there)`);
4382
4429
  let res;
4383
4430
  try {
4384
- res = connectServer({ id, sshHost, workspaceRef, dir, oatsPath: val("oats"), path: val("path"), label: val("label"), installOats: args.includes("--install-oats"), replace: args.includes("--replace"), localVersion: OATS_VERSION });
4431
+ res = connectServer({ id, sshHost, operatorSshHost: val("operator-ssh"), noOperatorSsh: args.includes("--no-operator-ssh"), workspaceRef, dir, oatsPath: val("oats"), path: val("path"), label: val("label"), installOats: args.includes("--install-oats"), replace: args.includes("--replace"), localVersion: OATS_VERSION });
4385
4432
  } catch (e) {
4386
4433
  if (!JSON_MODE && e.details?.steps) printConnectSteps(id, sshHost, e.details.steps);
4387
4434
  bail(e.code || "E_CONNECT", e.message, e.details);
@@ -4571,12 +4618,14 @@ async function serverRouteCmd() {
4571
4618
  const herdr = herdrSpawnFlag();
4572
4619
  if (herdr) { const e = herdrSettingRemoved(`${herdr} was given`); bail(e.code, e.message); }
4573
4620
  const local = args.slice(1).filter((a, i, all) => a !== "--server" && all[i - 1] !== "--server");
4574
- const problem = spawnArgvProblem(local) ?? suggestNameProblem(local) ?? backgroundProblem(local);
4621
+ const problem = suggestNameProblem(local) ?? backgroundProblem(local);
4575
4622
  if (problem) bail("E_BAD_ARGS", problem);
4623
+ if (flag("task") === true) bail("E_BAD_ARGS", "--task needs a value (use --task-file for long tasks)");
4576
4624
  }
4577
4625
  // Everything after the command word travels, minus the routing flags; a
4578
- // local --task-file is read here and travels as --task text, since the
4579
- // remote cannot read this machine's files.
4626
+ // local --task-file is read here and handed on as --task text, since the
4627
+ // remote cannot read this machine's files. A spawn's task is then sent on
4628
+ // the remote command's stdin to a host that reads it there (routeCommand).
4580
4629
  const rest = [];
4581
4630
  for (let i = 1; i < args.length; i++) {
4582
4631
  const a = args[i];
@@ -4609,8 +4658,6 @@ async function serverRouteCmd() {
4609
4658
  }
4610
4659
  rest.push(a);
4611
4660
  }
4612
- // Refused here too, before anything is sent: a host on an older OATS would still delete the branch.
4613
- if (cmd === "retire" && rest.includes("--delete-branch")) bail("E_BAD_ARGS", RETIRE_DELETE_BRANCH_REFUSED);
4614
4661
  let routed;
4615
4662
  try { routed = routeCommand(id, cmd, rest); }
4616
4663
  catch (e) { bail(e.code || "E_SSH", e.message, e.details); }
@@ -4747,11 +4794,11 @@ else {
4747
4794
  // `okf harvest --help` spawned a harvester (BeadHub, 2026-09-05).
4748
4795
  const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
4749
4796
  if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); process.exit(0); } usageFor(cmd); process.exit(0); }
4750
- 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");
4751
- // #1490 §2: the name is decided on the machine that asks, for a spawn that lands elsewhere.
4752
- 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)");
4797
+ // A state-changing command's argv against the flags it defines (lib/command-flags.mjs), before it runs
4798
+ // and before a --server command is sent: a host on an older OATS would ignore a flag it does not read.
4799
+ { const problem = commandArgvProblem(rawArgs); if (problem) cmdFail(problem.code, problem.message, problem.details); }
4753
4800
  // Session resume is local only (#1559, D1): a server resumes its own instances.
4754
- 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");
4801
+ if (cmd === "session" && args[1] === "start" && flag("server") !== undefined && args.includes("--resume")) cmdFail("E_BAD_ARGS", RESUME_LOCAL_ONLY);
4755
4802
  if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
4756
4803
  else if (cmd === "server") await serverCmd();
4757
4804
  else if (cmd === "deployments") deploymentsCmd();
@@ -4762,13 +4809,8 @@ else if (cmd === "doctor") {
4762
4809
  const doctorDir = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
4763
4810
  await (args.includes("--json") ? doctorJson(doctorDir) : doctor(doctorDir));
4764
4811
  }
4765
- else if (cmd === "update") {
4766
- // `oats update <package>` left with the installed tier (packages are pinned in
4767
- // the workspace file: `oats package add`); only the kernel self-update remains.
4768
- const t = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
4769
- if (t || flag("to") !== undefined) { cmdFail("E_BAD_ARGS", "oats update takes no package: pin package versions in oats-workspace.yaml (`oats package add <id> <version>`), then `oats sync`; bare `oats update [--check] [--yes]` updates the kernel"); process.exit(1); }
4770
- updateCmd();
4771
- }
4812
+ else if (cmd === "update") updateCmd();
4813
+ else if (cmd === "harness" && args[1] === "token") await harnessTokenCmd();
4772
4814
  else if (cmd === "harness") harnessTrustCmd();
4773
4815
  else if (cmd === "readiness") await readinessCmd();
4774
4816
  else if (cmd === "instance") await instanceCmd();
@@ -4787,6 +4829,7 @@ else if (cmd === "version" || cmd === "--version" || cmd === "-v") versionCmd();
4787
4829
  else if (cmd === "reader") await readerCmd();
4788
4830
  else if (cmd === "session") await sessionCmd();
4789
4831
  else if (cmd === "schedule") await scheduleCmd();
4832
+ else if (cmd === "host") await hostCmd();
4790
4833
  else if (cmd === "trigger") await triggerCmd();
4791
4834
  else if (cmd === "automations") await automationsCmd();
4792
4835
  // What a spawn throws outside its kernel stage goes through the same door as the inner catch.
@@ -4947,6 +4990,8 @@ Usage:
4947
4990
  host install|uninstall|status explicit IANA tz; see docs/schedules.md); --server
4948
4991
  routes to that host's workspace
4949
4992
  install [--max-concurrent N|default] [--triggers-max-concurrent N|none]
4993
+ install --register-only records the scope and installs no timer, for a
4994
+ host whose ticker is oats host run
4950
4995
  oats schedule add|update <id> … --description=<text> a one-line summary (1-200 characters)
4951
4996
  oats schedule update <id> --description=<text> change only it (--description= clears it)
4952
4997
  oats trigger add (--file <json> | --from <package>:<template> [--set k=v]) | list | show | enable
@@ -4985,6 +5030,12 @@ Usage:
4985
5030
  oats session resume [--deployment <dir>] resume every lost session of this computer's
4986
5031
  [--plan] [--json] deployments (one sweep per machine; at most 3 resumes
4987
5032
  of a home per boot); --plan starts nothing
5033
+ oats host run [--stop-grace <s>] run the kernel in the foreground where no host timer
5034
+ [--plan] [--json] can (a container): the resume sweep once, the schedule
5035
+ tick each minute; on SIGTERM it stops ticking, then
5036
+ stops every running instance (SIGTERM, bounded wait,
5037
+ never escalated) so that the next start resumes it
5038
+ (docs/container.md); --plan starts nothing
4988
5039
  oats session restart --home <abs-home> stop the running harness (SIGTERM, bounded wait,
4989
5040
  [same flags] [--stop-grace <s>] never escalated) and start it again in place under
4990
5041
  the same lock; a stop that is not observed is
@@ -5086,6 +5137,8 @@ Usage:
5086
5137
  modules or the deployment's soul, trust checked, the provider's
5087
5138
  own command run in the home or scope, envelope
5088
5139
  relayed; a view answers {documents: [...]}
5140
+ oats harness token set|status|remove <harness> --server <id> [--name <team>]
5141
+ [--stdin] [--json] [--debug] operator credential delivery, status and removal
5089
5142
  oats harness trust [--dir <deployment>] explicitly trust one canonical deployment root
5090
5143
  [--harness claude|codex|all] in every native configuration file a launch reads
5091
5144
  [--plan] [--json] (the ambient one and each launch configuration's
@@ -5170,10 +5223,10 @@ Usage:
5170
5223
  typed lifecycle events (spawned, launched, stopped,
5171
5224
  restarted, retired, worktree-retained…) written by
5172
5225
  the action that made them true; nothing inferred
5173
- oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message <text>] [--home <abs>] [--dir <d>] [--json]
5226
+ oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json]
5174
5227
  a producer's claim that the instance needs input
5175
5228
  from a human; appended only on change; display only
5176
- oats instance attention [--message <text>] [--clear] [--json]
5229
+ oats instance attention [--message=<text>] [--clear] [--json]
5177
5230
  run by the agent from its home: "I need a human's
5178
5231
  answer" (waiting --producer agent --reason attention)
5179
5232
  oats instance upgrade <instance> --plan [--undo] [--json]