@awebai/oats 0.69.11 → 0.69.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +216 -178
  2. package/bin/oats.mjs +176 -184
  3. package/docs/capabilities.md +4 -1
  4. package/docs/configuration.md +63 -5
  5. package/docs/container.md +246 -0
  6. package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
  7. package/docs/desktop-cli-api.md +376 -37
  8. package/docs/desktop-instance-start.md +4 -1
  9. package/docs/desktop.md +58 -12
  10. package/docs/execution-targets.md +69 -6
  11. package/docs/implementation.md +86 -29
  12. package/docs/integrations.md +9 -5
  13. package/docs/knowledge-and-learning.md +72 -0
  14. package/docs/knowledge.md +10 -3
  15. package/docs/oats-local.schema.json +11 -2
  16. package/docs/official-catalog.md +42 -8
  17. package/docs/packages.md +101 -22
  18. package/docs/release-lane.md +2 -1
  19. package/docs/release-notes/v0.69.12.md +97 -0
  20. package/docs/release-notes/v0.69.13.md +767 -0
  21. package/docs/release-notes/v0.69.14.md +83 -0
  22. package/docs/schedules.md +26 -3
  23. package/docs/servers.md +181 -5
  24. package/docs/souls-and-instances.md +140 -11
  25. package/docs/tui.md +1 -1
  26. package/docs/upgrading.md +30 -5
  27. package/docs/workspaces.md +32 -6
  28. package/lib/claim.mjs +21 -5
  29. package/lib/command-flags.mjs +238 -0
  30. package/lib/core.mjs +791 -563
  31. package/lib/deployments.mjs +4 -3
  32. package/lib/dir-lock.mjs +126 -31
  33. package/lib/errors.mjs +1 -1
  34. package/lib/harness-token.mjs +110 -0
  35. package/lib/hot-reads.mjs +4 -3
  36. package/lib/instance-events.mjs +28 -6
  37. package/lib/instance-git.mjs +138 -13
  38. package/lib/instance-inspect.mjs +6 -1
  39. package/lib/instance-listing.mjs +80 -38
  40. package/lib/instance-resolution.mjs +56 -3
  41. package/lib/instance-upgrade.mjs +16 -20
  42. package/lib/launch-env-exec.sh +7 -0
  43. package/lib/launch-env.mjs +74 -0
  44. package/lib/launch-preference.mjs +19 -12
  45. package/lib/member-clone.mjs +7 -1
  46. package/lib/packages.mjs +74 -2
  47. package/lib/read-call.mjs +3 -0
  48. package/lib/reader.mjs +3 -2
  49. package/lib/refused-text.mjs +3 -2
  50. package/lib/remote.mjs +119 -27
  51. package/lib/retained-after-retire.mjs +2 -7
  52. package/lib/retire-git-forms.mjs +41 -0
  53. package/lib/retire-incomplete.mjs +96 -0
  54. package/lib/schedule.mjs +2 -1
  55. package/lib/servers.mjs +78 -23
  56. package/lib/session-resume.mjs +68 -53
  57. package/lib/session-seen.mjs +54 -5
  58. package/lib/start-env.mjs +13 -7
  59. package/lib/system-tools.mjs +1 -1
  60. package/lib/teams.mjs +11 -4
  61. package/lib/upgrade-state.mjs +13 -2
  62. package/lib/worktree.mjs +56 -7
  63. package/package-catalog.json +3 -3
  64. package/package.json +2 -1
  65. package/packages/client/instance-lifecycle.mjs +1 -1
  66. package/packages/client/lifecycle-contract.mjs +3 -1
  67. package/packages/client/session-resume-cli.mjs +2 -1
  68. package/packages/client/session-start.mjs +10 -7
  69. package/packages/client/workspace-cli.mjs +5 -1
  70. package/share/oats-login-receive +204 -0
  71. package/skills/oats-getting-started/SKILL.md +180 -49
  72. package/lib/tmux-config.mjs +0 -35
package/bin/oats.mjs CHANGED
@@ -54,26 +54,27 @@ 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"));
@@ -86,6 +87,7 @@ const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, de
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,6 +100,7 @@ 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, 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);
@@ -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 } : {}),
@@ -891,10 +949,15 @@ async function doctor(dir) {
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()));
@@ -1260,10 +1320,8 @@ function instanceWaitingCmd(sub, bail) {
1260
1320
  async function worktreeCmd() {
1261
1321
  const bail = (code, msg, details, exit) => (JSON_MODE ? jsonFail(code, msg, details, exit) : die(msg, exit));
1262
1322
  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]";
1323
+ const usage = WORKTREE_USAGE;
1264
1324
  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
1325
  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
1326
  const homeVariable = ["OATS_INSTANCE_HOME", "OATS_HOME"].find((name) => process.env[name]);
1269
1327
  const home = homeVariable ? process.env[homeVariable] : enclosingInstanceHome(logicalCwd());
@@ -1277,7 +1335,6 @@ async function worktreeCmd() {
1277
1335
  process.stderr.on("error", readerGone);
1278
1336
  try {
1279
1337
  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
1338
  const r = await W.worktreeRemove(resolve(home), { purpose: value("purpose") });
1282
1339
  if (JSON_MODE) { jsonOk(r); return; }
1283
1340
  console.log(r.rolledBack
@@ -1338,7 +1395,6 @@ function retiredInstanceAddresses(root, name, home) {
1338
1395
  async function instanceUpgradeCmd(name, bail) {
1339
1396
  const usage = "usage: oats instance upgrade <instance> [--undo] (--plan | --plan-revision <rev> --idempotency-key <key>) [--home <abs>] [--dir <d>] [--json]";
1340
1397
  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
1398
  const home = flag("home"), revision = flag("plan-revision"), key = flag("idempotency-key");
1343
1399
  if (home === true || (home !== undefined && !isAbsolute(home))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
1344
1400
  const planOnly = args.includes("--plan"), undo = args.includes("--undo");
@@ -1359,8 +1415,6 @@ async function instanceUpgradeCmd(name, bail) {
1359
1415
  } catch (e) { return lifecycleFail(e, "E_UPGRADE_FAILED", { ...e.details, ...(e.plan ? { plan: e.plan } : {}), ...(e.candidates ? { candidates: e.candidates } : {}) }); }
1360
1416
  }
1361
1417
 
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
1418
  /** `oats instance suggest-name` (feature instance-suggest-name, awebai/oats#1490 §2): the name a spawn
1365
1419
  * of a soul would get by --suggest-name, chosen here for a spawn that may land on another machine
1366
1420
  * (lib/core.mjs suggestSpawnName). Never routed: --server is refused before the route dispatch. */
@@ -1374,12 +1428,6 @@ async function instanceSuggestNameCmd(bail) {
1374
1428
  if (v === undefined || (!inlineValues.has(name) && v.startsWith("--"))) return bail("E_BAD_ARGS", `--${name} needs a value; ${usage}`);
1375
1429
  return v;
1376
1430
  };
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
1431
  const soul = value("soul"), task = value("task"), taskFile = value("task-file");
1384
1432
  if (soul === undefined) return bail("E_BAD_ARGS", `--soul is required; ${usage}`);
1385
1433
  if ((task === undefined) === (taskFile === undefined)) return bail("E_BAD_ARGS", `give the task with one of --task or --task-file; ${usage}`);
@@ -1397,7 +1445,7 @@ async function instanceCmd() {
1397
1445
  if (sub === "upgrade") return instanceUpgradeCmd(name, bail);
1398
1446
  if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
1399
1447
  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]";
1448
+ 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
1449
  if (!["git", "diff", "stop", "events", "color", "background", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
1402
1450
  dropAmbientRoot();
1403
1451
  if (sub === "events") {
@@ -1440,7 +1488,6 @@ async function instanceCmd() {
1440
1488
  const words = [];
1441
1489
  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
1490
  const clear = args.includes("--clear");
1443
- if (words.length > 1) return bail("E_BAD_ARGS", `oats instance color takes one colour; ${colorUsage}`);
1444
1491
  const value = words[0];
1445
1492
  if (value !== undefined && clear) return bail("E_BAD_ARGS", `give a colour or --clear, not both; ${colorUsage}`);
1446
1493
  if (value === undefined && !clear) return bail("E_BAD_ARGS", `give a colour or --clear; ${colorUsage}`);
@@ -1620,7 +1667,8 @@ function commandSession() {
1620
1667
  process.on("exit", () => { sayReadNotices(); readSession.closeNow(); });
1621
1668
  for (const [signal, code] of [["SIGINT", 130], ["SIGTERM", 143], ["SIGHUP", 129]]) process.once(signal, () => {
1622
1669
  readSession.closeNow();
1623
- // Another handler (a scheduler lock's release) exits on its own after this one.
1670
+ // Another handler still listening (a naming call's and a lock's, lib/dir-lock.mjs, which raise
1671
+ // the signal again; a held `worktree` hook's, an attach's) ends the command itself after this one.
1624
1672
  if (process.listenerCount(signal) === 0) process.exit(code);
1625
1673
  });
1626
1674
  }
@@ -1707,6 +1755,30 @@ function workspaceContext(bail) {
1707
1755
  return { dir, localPath: found.path, local: found.local, deploymentDir: dirname(found.path), remoteOptions: remoteOptionsFromEnv() };
1708
1756
  }
1709
1757
 
1758
+ /** Tokens are operator-local calls even with --server; the forced-command key is the receiver. */
1759
+ async function harnessTokenCmd() {
1760
+ const usage = "usage: oats harness token set|status|remove <harness> --server <id> [--name <team>] [--stdin] [--json] [--debug]";
1761
+ if (!["set", "status", "remove"].includes(args[2]) || !args[3] || args[3].startsWith("-")) return cmdFail("E_BAD_ARGS", usage);
1762
+ const seen = new Set();
1763
+ for (let i = 4; i < args.length; i++) {
1764
+ const word = args[i];
1765
+ if (seen.has(word)) return cmdFail("E_BAD_ARGS", "Give each token-command flag once.");
1766
+ seen.add(word);
1767
+ if (["--json", "--stdin", "--debug"].includes(word)) continue;
1768
+ if (["--server", "--name"].includes(word) && args[i + 1] && !args[i + 1].startsWith("-")) { i++; continue; }
1769
+ return cmdFail("E_BAD_ARGS", usage);
1770
+ }
1771
+ try {
1772
+ 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 });
1773
+ if (JSON_MODE) jsonOk(result);
1774
+ else {
1775
+ 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}.`);
1776
+ for (const row of result.staleInstances ?? []) console.log(terminalText(` ${row.instance} (${row.agent}): started ${row.startedAt}; picks up the token at its next start.`));
1777
+ for (const warning of result.warnings) console.error(`oats: warning: ${warning}`);
1778
+ }
1779
+ } catch (e) { cmdFail(e.code || "E_HARNESS_TOKEN_DELIVERY", JSON_MODE ? e.message : terminalText(e.message)); }
1780
+ }
1781
+
1710
1782
  /** An explicit host-local operator action; never routed to a remote adapter. */
1711
1783
  function harnessTrustCmd() {
1712
1784
  if (args[1] !== "trust") return cmdFail("E_BAD_ARGS", "usage: oats harness trust [--dir <deployment>] [--harness claude|codex|all] [--plan] [--json]");
@@ -1825,7 +1897,6 @@ function printTable(header, rows) {
1825
1897
  }
1826
1898
 
1827
1899
  /** `--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
1900
 
1830
1901
  /** The body of `oats sync` — shared by `sync` and `onboard` (which onboards, then syncs the same
1831
1902
  * way). Given a v2 deployment context: discover over the remotes, confirm membership, resolve
@@ -2015,31 +2086,11 @@ function setDisabledHereCli(ws, kind, qid, enabled) {
2015
2086
  return A.setDisabledHere({ deployment: dirname(path), localPath: path }, kind, qid, !enabled);
2016
2087
  }
2017
2088
 
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
2089
  /** `oats sync [--dir] [--plan] [--json]` — contract §6. `--plan` previews: the same report, nothing written. */
2039
2090
  async function syncCmd() {
2040
2091
  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);
2092
+ // A second --dir: flag() would read the first and drop it.
2093
+ if (args.filter((a) => a === "--dir").length > 1) return bail("E_BAD_ARGS", `oats sync: give --dir once\n${SYNC_USAGE}`, { flag: "--dir" });
2043
2094
  const ctx = workspaceContext(bail);
2044
2095
  const synced = await performSync(ctx, bail, { plan: args.includes("--plan") });
2045
2096
  // One envelope (or the §8 report); success is exit 0 (a failure bails with its code).
@@ -2177,41 +2228,15 @@ async function teamsContext(bail) {
2177
2228
  }
2178
2229
  const positional = (i) => (args[i] !== undefined && !args[i].startsWith("--") ? args[i] : undefined);
2179
2230
 
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
2231
  /** `oats teams [--json] | add <label> --team <id> [--description <d>] [--no-default] | remove <label> |
2202
2232
  * default <label> [--if-absent | --expect <label>]` — this deployment's teams (team model 3). Config only:
2203
2233
  * never a provider call. */
2204
2234
  async function teamsCmd() {
2205
2235
  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
- }
2236
+ const usage = TEAMS_USAGE;
2237
+ // The form and its flags were checked by the dispatch (lib/command-flags.mjs): a word where the form
2238
+ // belongs, and a flag the form does not take, are E_USAGE there.
2239
+ const sub = positional(1);
2215
2240
  const label = sub ? positional(2) : undefined;
2216
2241
  if (sub && label === undefined) bail("E_BAD_ARGS", `oats teams ${sub} needs a team label — ${usage}`);
2217
2242
  const ctx = await teamsContext(bail);
@@ -2276,13 +2301,6 @@ async function soulCmd() {
2276
2301
  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
2302
  }
2278
2303
 
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
2304
  /** A souls.launch entry in words: a launch configuration's name, or the inline harness and model. */
2287
2305
  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
2306
 
@@ -2292,23 +2310,22 @@ const launchEntryText = (v) => (v === null ? "no entry" : typeof v === "string"
2292
2310
  async function soulLaunchCmd(bail, usage) {
2293
2311
  const sub = positional(2);
2294
2312
  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] };
2313
+ // Every argument is accounted for before anything is read or written. The dispatch refused a flag the
2314
+ // form does not take and a second name (lib/command-flags.mjs); here a value flag with no value at ANY
2315
+ // of its occurrences (`--harness codex --harness`) and a value flag given twice (flag() would read the
2316
+ // first and drop the second) are refused, never ignored. Its value flags are the declaration's.
2317
+ const { values } = commandFlags(args);
2299
2318
  const names = [], given = new Set();
2300
2319
  for (let i = 3; i < args.length; i++) {
2301
2320
  const a = args[i];
2302
2321
  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;
2322
+ if (!values.includes(a)) continue;
2305
2323
  if (args[i + 1] === undefined || args[i + 1].startsWith("--")) bail("E_BAD_ARGS", `${a} needs a value`);
2306
2324
  if (given.has(a)) bail("E_BAD_ARGS", `oats soul launch ${sub} takes ${a} once (nothing was changed)`);
2307
2325
  given.add(a);
2308
2326
  i++;
2309
2327
  }
2310
2328
  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
2329
  const name = names[0];
2313
2330
  const V = await import("../lib/soul-launch-verbs.mjs");
2314
2331
  let value = null;
@@ -2618,12 +2635,6 @@ function printStatus({ root, agents: data, ws, problems }, verbose) {
2618
2635
  }
2619
2636
  }
2620
2637
 
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
2638
  /** `--suggest-name` (features spawn-suggest-name, spawn-apply-suggest-name): a preview's or an apply's,
2628
2639
  * with no --name, --purpose or --expect-decision. The kernel refuses the same (core.mjs spawnBody); the
2629
2640
  * CLI says it before anything is read or sent. */
@@ -2636,26 +2647,6 @@ function suggestNameProblem(argv) {
2636
2647
  }
2637
2648
  /** `--background` / `--no-background` (feature instance-background): one of them, or neither. */
2638
2649
  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
2650
  /** The Herdr spawn flags (removed in 0.31.0), named for the refusal; undefined when none is given. */
2660
2651
  function herdrSpawnFlag() {
2661
2652
  if (flag("backend") === "herdr") return "--backend herdr";
@@ -2696,12 +2687,9 @@ async function spawnCmd() {
2696
2687
  };
2697
2688
  checkDirectoryOptions(requestedWork); // before anything is resolved or written
2698
2689
  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]");
2690
+ if (!name || name.startsWith("--")) bail("E_USAGE", SPAWN_USAGE);
2700
2691
  // Retired boundary flags (maintainer transport ruling): fail LOUDLY before
2701
2692
  // 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
2693
  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
2694
  // --name <slug>: the exact, unprefixed instance name (human decision 2026-09-24).
2707
2695
  const nameFlag = flag("name");
@@ -2710,8 +2698,6 @@ async function spawnCmd() {
2710
2698
  { const problem = suggestNameProblem(args) ?? backgroundProblem(args); if (problem) bail("E_BAD_ARGS", problem); }
2711
2699
  // The slug rule is checked here too, before any side effect (soul fetch).
2712
2700
  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
2701
  let root;
2716
2702
  // A spawn needs a workspace deployment (lead decision c3-1): no oats-local.yaml
2717
2703
  // in reach is E_LOCAL_MISSING, before anything else is read. The agents root is
@@ -2743,11 +2729,14 @@ async function spawnCmd() {
2743
2729
  {
2744
2730
  let discovery = null;
2745
2731
  try {
2746
- const { prepareInstance, ensureWorkspaceSoul, previewWorkspaceSoul, parseProviderFlags, discoverOrStandalone, agentDirOf } = await import("../lib/instance-resolution.mjs");
2732
+ const { prepareInstance, verifyPreparedPackages, ensureWorkspaceSoul, previewWorkspaceSoul, parseProviderFlags, discoverOrStandalone, agentDirOf } = await import("../lib/instance-resolution.mjs");
2747
2733
  const remoteOptions = remoteOptionsFromEnv();
2748
2734
  const { local, path: localPath } = loadLocal(dirFlag());
2749
2735
  discovery = wsDiscovery = await discoverOrStandalone(local, { deployment: dirname(localPath), remoteOptions });
2750
2736
  wsPrepared = await prepareInstance(dirFlag(), name, { spawn: { providers: parseProviderFlags(providerPairs) }, remoteOptions, discovery });
2737
+ // Each package the soul composes is the content the lock records (E_PACKAGE_INTEGRITY), before the
2738
+ // first write of the spawn: the soul cache below is the first thing a spawn creates under the agents root.
2739
+ await verifyPreparedPackages(wsPrepared);
2751
2740
  const soulName = agentDirOf(wsPrepared.soulEntry);
2752
2741
  let soulDir;
2753
2742
  if (isPreview) {
@@ -2997,9 +2986,7 @@ function failedSpawnBranchLine(r, items, { local = false, host } = {}) {
2997
2986
  let retireReturned = false;
2998
2987
  function retireCmd() {
2999
2988
  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]");
2989
+ if (!name || name.startsWith("--")) return cmdFail("E_USAGE", RETIRE_USAGE);
3003
2990
  let homeFlag = flag("home");
3004
2991
  if (homeFlag === true) die("--home needs the instance home path");
3005
2992
  if (args.includes("--plan")) {
@@ -3415,7 +3402,7 @@ async function triggerFromPackage(T, from, sets, idFlag) {
3415
3402
 
3416
3403
  async function sessionCmd() {
3417
3404
  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" });
3405
+ if (flag("native-record") !== undefined) throw Object.assign(new Error(NATIVE_RECORD_REFUSED), { code: "E_BAD_ARGS" });
3419
3406
  const home = flag("home");
3420
3407
  let result;
3421
3408
  if (args[1] === "attach") {
@@ -3437,13 +3424,7 @@ async function sessionCmd() {
3437
3424
  if (args[1] === "resume") {
3438
3425
  // The machine sweep (feature session-resume, #1559): lib/session-resume.mjs. No --home: one home
3439
3426
  // 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
- }
3427
+ const usage = commandFlags(args).usage;
3447
3428
  const deployment = flag("deployment");
3448
3429
  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
3430
  const { resumeSessions } = await import("../lib/session-resume.mjs");
@@ -3472,7 +3453,6 @@ async function sessionCmd() {
3472
3453
  // refused with a launch choice before anything of the home is read.
3473
3454
  const resume = args.includes("--resume");
3474
3455
  if (resume) {
3475
- if (args[1] === "restart") bad("--resume exists on session start only: it brings back a session that was lost");
3476
3456
  const chosen = ["--launch-config", "--harness", "--model", "--yolo", "--no-yolo", "--reselect-launch"].filter((f) => args.some((a) => a === f || a.startsWith(`${f}=`)));
3477
3457
  if (chosen.length) bad(`--resume runs the launch this home recorded; it cannot be combined with ${chosen.join(", ")}; nothing was read or started`);
3478
3458
  }
@@ -4224,7 +4204,7 @@ async function experimentalCmd() {
4224
4204
  async function serverCmd() {
4225
4205
  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
4226
4206
  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]";
4207
+ 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
4208
  if (!["add", "connect", "list", "remove", "check", "roster", "forget"].includes(sub)) bail("E_USAGE", usage);
4229
4209
  if (sub === "connect") return serverConnectCmd(bail);
4230
4210
  if (sub === "forget") {
@@ -4274,7 +4254,9 @@ async function serverCmd() {
4274
4254
  let servers;
4275
4255
  try { servers = readServers(); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
4276
4256
  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 }));
4257
+ let routes;
4258
+ try { routes = readServerOperatorRoutes(); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
4259
+ 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
4260
  // --workspace-ref: the servers of one workspace, by canonical key, and the ids whose workspace is not known yet.
4279
4261
  let unknownWorkspace;
4280
4262
  if (flag("workspace-ref") !== undefined) {
@@ -4288,7 +4270,7 @@ async function serverCmd() {
4288
4270
  if (JSON_MODE) { jsonOk({ file: SERVERS_FILE(), servers: rows, ...(unknownWorkspace ? { unknownWorkspace } : {}) }); return; }
4289
4271
  if (unknownWorkspace?.length) console.log(` (workspace not known yet for ${unknownWorkspace.join(", ")}: oats server check <id> learns it)`);
4290
4272
  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)` : ""}`);
4273
+ 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
4274
  return;
4293
4275
  }
4294
4276
  const id = args[2];
@@ -4299,12 +4281,23 @@ async function serverCmd() {
4299
4281
  const entry = { sshHost: val("ssh"), workspace: val("workspace") };
4300
4282
  for (const [k, f] of [["oatsPath", "oats"], ["path", "path"], ["label", "label"]]) { const v = val(f); if (v !== undefined) entry[k] = v; }
4301
4283
  if (!entry.sshHost || !entry.workspace) bail("E_USAGE", usage);
4302
- try { validateServer(id, entry); } catch (e) { bail(e.code, e.message); }
4284
+ const operatorSshHost = val("operator-ssh"), noOperatorSsh = args.includes("--no-operator-ssh");
4285
+ if (operatorSshHost !== undefined && noOperatorSsh) bail("E_BAD_ARGS", "choose --operator-ssh or --no-operator-ssh, not both");
4286
+ try { validateServer(id, entry); if (operatorSshHost !== undefined) validateOperatorSshHost(operatorSshHost); } catch (e) { bail(e.code, e.message); }
4287
+ let operatorRoute;
4303
4288
  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" });
4289
+ updateServers((current, routes) => {
4290
+ const existing = Object.hasOwn(current, id) ? current[id] : undefined;
4291
+ 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" });
4292
+ // An older kernel can remove a registration while leaving its sidecar route behind.
4293
+ if (!existing) delete routes[id];
4294
+ // An unchanged agent target keeps its learned identity when only the operator route changes.
4295
+ if (existing?.workspaceKey && JSON.stringify(targetOf(existing)) === JSON.stringify(targetOf(entry))) entry.workspaceKey = existing.workspaceKey;
4306
4296
  current[id] = entry;
4307
- });
4297
+ if (operatorSshHost !== undefined) routes[id] = { operatorSshHost };
4298
+ else if (noOperatorSsh) delete routes[id];
4299
+ operatorRoute = Object.hasOwn(routes, id) ? routes[id] : undefined;
4300
+ }, { operatorRoutes: true });
4308
4301
  } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
4309
4302
  // The workspace key is learned from the host, never typed: recorded when the host answers one and
4310
4303
  // the registration is still this one (it may change while the host is asked).
@@ -4312,20 +4305,24 @@ async function serverCmd() {
4312
4305
  try {
4313
4306
  const { key, why } = reportedWorkspaceKey(targetOf(entry), { serverId: id, timeoutMs: 60000 });
4314
4307
  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`);
4308
+ else if (["recorded", "same"].includes(learnWorkspaceKey(id, entry, key, { replace: args.includes("--replace") }))) entry.workspaceKey = key;
4309
+ else {
4310
+ delete entry.workspaceKey;
4311
+ warnings.push(`workspace key not recorded: registration ${id} changed while the host was asked; oats server check ${id} learns it`);
4312
+ }
4317
4313
  } 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; }
4314
+ if (JSON_MODE) { jsonOk({ id, ...entry, ...operatorRoute, workspaceKey: entry.workspaceKey ?? null, file: SERVERS_FILE(), ...(warnings.length ? { warnings } : {}) }); return; }
4319
4315
  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
4316
  for (const w of warnings) console.error(`oats: warning: ${w}`);
4321
4317
  return;
4322
4318
  }
4323
4319
  if (sub === "remove") {
4324
4320
  try {
4325
- updateServers((current) => {
4321
+ updateServers((current, routes) => {
4326
4322
  if (!current[id]) throw Object.assign(new Error(`no server registered as ${id}`), { code: "E_SERVER_UNKNOWN" });
4327
4323
  delete current[id];
4328
- });
4324
+ delete routes[id];
4325
+ }, { operatorRoutes: true });
4329
4326
  } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
4330
4327
  const snaps = listSnapshots(id);
4331
4328
  if (JSON_MODE) { jsonOk({ removed: id, remoteInstancesStillTracked: snaps.map((s) => s.instance) }); return; }
@@ -4368,7 +4365,7 @@ async function serverCmd() {
4368
4365
  * step b): only the person knows where it goes. */
4369
4366
  function serverConnectCmd(bail) {
4370
4367
  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]");
4368
+ 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
4369
  const val = (name) => { const v = flag(name); return v === true ? bail("E_BAD_ARGS", `--${name} needs a value`) : v; };
4373
4370
  const sshHost = val("ssh");
4374
4371
  if (!sshHost) bail("E_BAD_ARGS", "--ssh <host-alias> is required: the OpenSSH host alias of the machine to connect");
@@ -4381,7 +4378,7 @@ function serverConnectCmd(bail) {
4381
4378
  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
4379
  let res;
4383
4380
  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 });
4381
+ 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
4382
  } catch (e) {
4386
4383
  if (!JSON_MODE && e.details?.steps) printConnectSteps(id, sshHost, e.details.steps);
4387
4384
  bail(e.code || "E_CONNECT", e.message, e.details);
@@ -4571,7 +4568,7 @@ async function serverRouteCmd() {
4571
4568
  const herdr = herdrSpawnFlag();
4572
4569
  if (herdr) { const e = herdrSettingRemoved(`${herdr} was given`); bail(e.code, e.message); }
4573
4570
  const local = args.slice(1).filter((a, i, all) => a !== "--server" && all[i - 1] !== "--server");
4574
- const problem = spawnArgvProblem(local) ?? suggestNameProblem(local) ?? backgroundProblem(local);
4571
+ const problem = suggestNameProblem(local) ?? backgroundProblem(local);
4575
4572
  if (problem) bail("E_BAD_ARGS", problem);
4576
4573
  }
4577
4574
  // Everything after the command word travels, minus the routing flags; a
@@ -4609,8 +4606,6 @@ async function serverRouteCmd() {
4609
4606
  }
4610
4607
  rest.push(a);
4611
4608
  }
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
4609
  let routed;
4615
4610
  try { routed = routeCommand(id, cmd, rest); }
4616
4611
  catch (e) { bail(e.code || "E_SSH", e.message, e.details); }
@@ -4747,11 +4742,11 @@ else {
4747
4742
  // `okf harvest --help` spawned a harvester (BeadHub, 2026-09-05).
4748
4743
  const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
4749
4744
  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)");
4745
+ // A state-changing command's argv against the flags it defines (lib/command-flags.mjs), before it runs
4746
+ // and before a --server command is sent: a host on an older OATS would ignore a flag it does not read.
4747
+ { const problem = commandArgvProblem(rawArgs); if (problem) cmdFail(problem.code, problem.message, problem.details); }
4753
4748
  // 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");
4749
+ if (cmd === "session" && args[1] === "start" && flag("server") !== undefined && args.includes("--resume")) cmdFail("E_BAD_ARGS", RESUME_LOCAL_ONLY);
4755
4750
  if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
4756
4751
  else if (cmd === "server") await serverCmd();
4757
4752
  else if (cmd === "deployments") deploymentsCmd();
@@ -4762,13 +4757,8 @@ else if (cmd === "doctor") {
4762
4757
  const doctorDir = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
4763
4758
  await (args.includes("--json") ? doctorJson(doctorDir) : doctor(doctorDir));
4764
4759
  }
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
- }
4760
+ else if (cmd === "update") updateCmd();
4761
+ else if (cmd === "harness" && args[1] === "token") await harnessTokenCmd();
4772
4762
  else if (cmd === "harness") harnessTrustCmd();
4773
4763
  else if (cmd === "readiness") await readinessCmd();
4774
4764
  else if (cmd === "instance") await instanceCmd();
@@ -5086,6 +5076,8 @@ Usage:
5086
5076
  modules or the deployment's soul, trust checked, the provider's
5087
5077
  own command run in the home or scope, envelope
5088
5078
  relayed; a view answers {documents: [...]}
5079
+ oats harness token set|status|remove <harness> --server <id> [--name <team>]
5080
+ [--stdin] [--json] [--debug] operator credential delivery, status and removal
5089
5081
  oats harness trust [--dir <deployment>] explicitly trust one canonical deployment root
5090
5082
  [--harness claude|codex|all] in every native configuration file a launch reads
5091
5083
  [--plan] [--json] (the ambient one and each launch configuration's
@@ -5170,10 +5162,10 @@ Usage:
5170
5162
  typed lifecycle events (spawned, launched, stopped,
5171
5163
  restarted, retired, worktree-retained…) written by
5172
5164
  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]
5165
+ oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json]
5174
5166
  a producer's claim that the instance needs input
5175
5167
  from a human; appended only on change; display only
5176
- oats instance attention [--message <text>] [--clear] [--json]
5168
+ oats instance attention [--message=<text>] [--clear] [--json]
5177
5169
  run by the agent from its home: "I need a human's
5178
5170
  answer" (waiting --producer agent --reason attention)
5179
5171
  oats instance upgrade <instance> --plan [--undo] [--json]