@awebai/oats 0.55.1 → 0.56.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/bin/oats.mjs +78 -62
  2. package/docs/capabilities.md +67 -3
  3. package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
  4. package/docs/desktop-cli-api.md +317 -35
  5. package/docs/desktop-instance-start.md +105 -12
  6. package/docs/desktop.md +54 -7
  7. package/docs/execution-targets.md +184 -9
  8. package/docs/harness-trust.md +128 -11
  9. package/docs/implementation.md +54 -7
  10. package/docs/integrations.md +1 -1
  11. package/docs/knowledge.md +35 -16
  12. package/docs/official-catalog.md +3 -3
  13. package/docs/packages.md +12 -12
  14. package/docs/release-lane.md +26 -1
  15. package/docs/release-notes/v0.56.0.md +699 -0
  16. package/docs/servers.md +21 -5
  17. package/docs/souls-and-instances.md +8 -4
  18. package/docs/tui.md +99 -26
  19. package/docs/upgrading.md +4 -1
  20. package/docs/workspaces.md +26 -6
  21. package/lib/automations.mjs +3 -4
  22. package/lib/bounded-read.mjs +18 -0
  23. package/lib/capability-show.mjs +13 -2
  24. package/lib/claim.mjs +3 -4
  25. package/lib/core.mjs +480 -152
  26. package/lib/errors.mjs +39 -0
  27. package/lib/harness-trust-write.mjs +119 -40
  28. package/lib/harness-trust.mjs +31 -18
  29. package/lib/instance-inspect.mjs +160 -11
  30. package/lib/instance-lifecycle.mjs +47 -30
  31. package/lib/packages.mjs +8 -5
  32. package/lib/pi-bridge.mjs +18 -19
  33. package/lib/remote.mjs +88 -51
  34. package/lib/retire-output.mjs +9 -4
  35. package/lib/schedule.mjs +3 -4
  36. package/lib/servers.mjs +39 -6
  37. package/lib/session-viewer.mjs +25 -1
  38. package/lib/triggers.mjs +3 -4
  39. package/lib/workspace.mjs +6 -6
  40. package/lib/worktree.mjs +10 -6
  41. package/lib/write-through-private-file.mjs +26 -0
  42. package/package-catalog.json +2 -2
  43. package/package.json +1 -1
  44. package/packages/client/cli-adapter.mjs +108 -13
  45. package/packages/client/cli-locator.mjs +16 -14
  46. package/packages/client/deployment-panel.mjs +4 -3
  47. package/packages/client/display-text.mjs +2 -1
  48. package/packages/client/instance-events-contract.mjs +4 -3
  49. package/packages/client/instance-lifecycle.mjs +228 -0
  50. package/packages/client/instance-presentation.mjs +9 -0
  51. package/packages/client/instance-tree.mjs +10 -8
  52. package/packages/client/kernel-lines.mjs +3 -3
  53. package/packages/client/launch-contract.mjs +11 -0
  54. package/packages/client/lifecycle-cli.mjs +12 -6
  55. package/packages/client/lifecycle-confirmation.mjs +407 -0
  56. package/packages/client/lifecycle-contract.mjs +6 -2
  57. package/packages/client/own-codes.mjs +1 -0
  58. package/packages/client/panel-views.mjs +39 -2
  59. package/packages/client/readiness-contract.mjs +2 -2
  60. package/packages/client/remote-roster.mjs +50 -5
  61. package/packages/client/roster-sections.mjs +3 -3
  62. package/packages/client/session-start.mjs +98 -0
  63. package/packages/client/start-gate.mjs +46 -0
  64. package/packages/client/start-messages.mjs +17 -0
  65. package/packages/client/workspace-views.mjs +2 -2
  66. package/packages/tui/README.md +10 -6
  67. package/packages/tui/lib/actions.mjs +4 -2
  68. package/packages/tui/lib/client.mjs +5 -2
  69. package/packages/tui/lib/config.mjs +39 -9
  70. package/packages/tui/lib/main.mjs +83 -13
  71. package/packages/tui/lib/model.mjs +116 -11
  72. package/packages/tui/lib/open.mjs +45 -0
  73. package/packages/tui/lib/read.mjs +46 -10
  74. package/packages/tui/lib/store.mjs +64 -9
  75. package/packages/tui/lib/term/tty.mjs +71 -12
  76. package/packages/tui/lib/views/frame.mjs +115 -33
  77. package/packages/tui/lib/views/help.mjs +37 -8
  78. package/skills/oats-getting-started/SKILL.md +6 -3
package/bin/oats.mjs CHANGED
@@ -26,7 +26,7 @@ import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
26
26
  import { fileURLToPath } from "node:url";
27
27
  import { performance } from "node:perf_hooks";
28
28
  import { runtimeNameWarning, noteRuntimeName } from "../lib/deprecation.mjs";
29
- import { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect } from "../lib/errors.mjs";
29
+ import { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect, spawnRefusalDetails } from "../lib/errors.mjs";
30
30
  import {
31
31
  LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
32
32
  capabilityManifests, capabilityTrust, capabilityExecutablePath,
@@ -38,7 +38,8 @@ import {
38
38
  writeFileAtomic, LOCK_FILE, canonicalLock, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
39
39
  classifyPackageValue, parsePackageRequest } from "../lib/packages.mjs";
40
40
  import { harnessTrust } from "../lib/harness-trust-write.mjs";
41
- import { PI_BRIDGE, piBridgeFolders, piBridgeSkewWarnings, planPiBridges, piBridgePlanLines, piBridgeStepProblem, piBridgeFailure, kernelLookup, kernelLookupResult, planCliUpdate, bridgeLookup, bridgeLookupProblem } from "../lib/pi-bridge.mjs";
41
+ import { previewLaunchEnvironment, previewPaneEnvironment } from "../lib/core.mjs";
42
+ import { PI_BRIDGE, piBridgeFolders, piBridgeSkewWarnings, planPiBridges, piBridgePlanLines, piBridgeStepProblem, piBridgeFailure, kernelLookup, kernelLookupResult, planCliUpdate, desktopFirstLine, bridgeLookup, bridgeLookupProblem } from "../lib/pi-bridge.mjs";
42
43
  import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, unlockedPackages, workspaceWarnings, memberRowByKey } from "../lib/workspace.mjs";
43
44
  import { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "../lib/teams.mjs";
44
45
  import { LAUNCH_KEY_UNCHECKED, LAUNCH_PREFERENCE_UNMATCHED, launchKeyQuoted, launchKeysUnmatched, launchLayers, soulLaunchCommand, unmatchedKeyMessage } from "../lib/launch-preference.mjs";
@@ -62,12 +63,12 @@ import { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, d
62
63
  import { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } from "../lib/retire-output.mjs";
63
64
  import { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } from "../lib/retained-after-retire.mjs";
64
65
  const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
65
- import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposedInstructions, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
66
+ import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposedInstructions, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
66
67
  import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mjs";
67
68
 
68
69
  const rawArgs = process.argv.slice(2);
69
70
  /** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
70
- const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "run-source", "self", "verbose", "yes", "yolo"]);
71
+ const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "run-source", "self", "skills", "verbose", "yes", "yolo"]);
71
72
  /** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
72
73
  * routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
73
74
  * `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
@@ -103,7 +104,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
103
104
  * probe) and in `status --json`, which a remote roster relays as the host's (feature
104
105
  * server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
105
106
  * time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
106
- const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree"];
107
+ const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key"];
107
108
  /** Commands `--server <id>` runs on a registered server. */
108
109
  const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
109
110
  const flag = (name) => {
@@ -182,7 +183,7 @@ const withLocalWarnings = (envelope) => {
182
183
  return { ...envelope, warnings: theirs.map((w) => (w === same ? { ...mine, sources, message: mine.message.replace(/\(.*\)/, `(${sources.join("; ")})`) } : w)) };
183
184
  };
184
185
  const jsonFail = (code, message, details, exit = 1) => { console.log(JSON.stringify({ schemaVersion: 1, ok: false, error: { code, message: String(message), ...(details !== undefined ? { details } : {}) }, ...envelopeWarnings() })); process.exit(exit); };
185
- /** The door of the lifecycle verbs (retire, instance stop, session, worktree; awebai/oats#892): the
186
+ /** The door of the lifecycle verbs (retire, instance stop, session, worktree; awebai/oats#892), and of a spawn (spawnFail): the
186
187
  * answer to an error `e` of one of them. Its code is the error's own only when that is a kernel
187
188
  * code (lib/errors.mjs isKernelCode); any other error is answered as `fallback`. One that has a
188
189
  * code (the system's, Node's) and a defect (isDefect: a TypeError and its kind) get
@@ -199,6 +200,11 @@ const lifecycleFail = (e, fallback, details, exit) => {
199
200
  const all = cause ? { ...details, cause } : details;
200
201
  return JSON_MODE ? jsonFail(kernelCode(e, fallback), message, all, exit) : die(message, exit);
201
202
  };
203
+ /** The answer to an error of `oats spawn` (feature spawn-kernel-codes, awebai/oats#1047): the
204
+ * lifecycle verbs' door (lifecycleFail), whose general code for a spawn is E_SPAWN_FAILED. A
205
+ * kernel code is answered as raised, whatever stage of the spawn raised it; it says nothing about
206
+ * how far the spawn got (`details.unconfirmed` does). E_INTERRUPTED exits 128 + the signal. */
207
+ const spawnFail = (e) => lifecycleFail(e, "E_SPAWN_FAILED", spawnRefusalDetails(e), e?.code === "E_INTERRUPTED" ? e.exitStatus : undefined);
202
208
  const jsonOk = (result) => { console.log(JSON.stringify({ schemaVersion: 1, ok: true, result, ...envelopeWarnings() })); };
203
209
  // Text mode (or a JSON answer printed before the read): the warning goes to stderr, never stdout.
204
210
  process.on("exit", () => { const w = runtimeNameWarning(); if (w && !warningDelivered) process.stderr.write(`oats: warning: ${w.message}\n`); });
@@ -560,10 +566,14 @@ async function inspectCmd() {
560
566
  // Feature soul-composed-instructions: opt-in, soul subject only; without it nothing extra is composed.
561
567
  const instructions = args.includes("--instructions");
562
568
  if (instructions && flag("home") !== undefined) return bail("E_BAD_ARGS", "--instructions composes a soul's instructions before a spawn: it takes --soul, not --home (an instance's composed AGENTS.md is instance.instructions)");
569
+ // Feature soul-skills: opt-in, soul subject only; without it no skill file is read.
570
+ const skills = args.includes("--skills");
571
+ if (skills && flag("home") !== undefined) return bail("E_BAD_ARGS", "--skills lists a soul's own skills before a spawn: it takes --soul, not --home (an instance's skills are in its home's .agents/skills/)");
563
572
  let t = await workspaceTarget(bail, { command: "inspect" });
564
573
  if (t) {
565
574
  if (t.resolutionError) return bail(t.resolutionError.code, t.resolutionError.message, t.resolutionError.details ?? undefined);
566
575
  if (instructions) t = await withComposedInstructions(t);
576
+ if (skills) t = await withSkills(t);
567
577
  const doc = inspectDocument(t, { kernel: OATS_VERSION });
568
578
  if (JSON_MODE) { jsonOk(withObservation(doc)); return; }
569
579
  printWorkspaceInspect(doc); return;
@@ -829,7 +839,7 @@ function doctorVersionSkew(deployment) {
829
839
  try { launchConfigs = launchConfigsAt(deployment); } catch (e) { unread = e.message; }
830
840
  const warnings = piBridgeSkewWarnings(piBridgeFolders({ launchConfigs }), OATS_VERSION);
831
841
  if (unread) warnings.push(`pi bridge — the launch configurations could not be read, so only the default pi folder and this shell's were looked at: ${unread}`);
832
- for (const warning of warnings) console.log(`WARNING: ${warning}`);
842
+ for (const warning of warnings) console.log(`WARNING: ${terminalText(warning)}`);
833
843
  if (warnings.length) console.log("");
834
844
  }
835
845
  /** The "Workspace (v2, offline view)" + "Locked packages" sections, shared by both doctor shapes. */
@@ -1035,8 +1045,10 @@ function launchPreview(bail) {
1035
1045
  let r;
1036
1046
  try { r = meta ? resolvedFromHome(home, meta) : { capabilities: [], launchConfigs: launchConfigsAt(context) }; } catch (e) { bail(e.code || "E_CONFIG_BROKEN", e.message, e.details); }
1037
1047
  // The same planner a start uses, in preview mode: failed checks are listed, nothing is touched.
1048
+ // Its checks read the pane a launch would run in, as a command that only reads can know it (a
1049
+ // home's recorded session, a soul's session default; with no server running, not established).
1038
1050
  let plan;
1039
- try { plan = planLaunch({ home, instance, meta, contextDir: context, agentLike, selection: sel, resolvedCfg: r, preview: true }); } catch (e) { bail(e.code || "E_BAD_ARGS", e.message); }
1051
+ try { plan = planLaunch({ home, instance, meta, contextDir: context, agentLike, selection: sel, resolvedCfg: r, preview: true, pane: () => previewPaneEnvironment(meta ? { home, meta } : { deployment: context }) }); } catch (e) { bail(e.code || "E_BAD_ARGS", e.message); }
1040
1052
  const { recipe } = plan;
1041
1053
  const command = renderLaunchRecipe(recipe, { home, instance, redact: true, trustHome: plan.trustHome });
1042
1054
  const d = describeLaunchCommand(command);
@@ -1347,7 +1359,7 @@ function instanceCmd() {
1347
1359
  if (JSON_MODE) { jsonOk(plan); return; }
1348
1360
  console.log(`stop ${name}${recursive ? " (and recorded children)" : ""} — plan ${plan.planRevision}`);
1349
1361
  for (const t of plan.targets) console.log(` ${" ".repeat(t.depth)}${t.instance}: session ${t.session.state}${t.work.observed ? `, ${t.work.changed} changed / ${t.work.untracked} untracked on ${t.work.branch ?? "detached"}` : ", work not observed"}${t.midTask === true ? " — mid-task" : t.midTask === "unknown" ? " — activity unknown" : ""}`);
1350
- for (const n of plan.notes) console.log(` note: ${n}`);
1362
+ for (const n of plan.notes) console.log(` note: ${terminalText(n)}`);
1351
1363
  console.log(`apply with: oats instance stop ${name} --apply --plan-revision ${plan.planRevision} --idempotency-key <key>`);
1352
1364
  return;
1353
1365
  }
@@ -1391,7 +1403,7 @@ function instanceCmd() {
1391
1403
  console.log(` files: ${observed.files.length} (${Object.entries(observed.summary).filter(([, n]) => n).map(([k, n]) => `${n} ${k}`).join(", ") || "clean"})`);
1392
1404
  const lines = (f) => (f.binary ? " binary" : Number.isInteger(f.additions) ? ` +${f.additions} -${f.deletions}` : "");
1393
1405
  for (const f of observed.files) console.log(` ${f.xy} ${f.origPath ? `${f.origPath} -> ` : ""}${f.path}${lines(f)} [${f.id}]`);
1394
- for (const n of observed.notes) console.log(` note: ${n}`);
1406
+ for (const n of observed.notes) console.log(` note: ${terminalText(n)}`);
1395
1407
  return;
1396
1408
  }
1397
1409
  const fileId = flag("file"), revision = flag("revision"), indexRevision = flag("index-revision");
@@ -1432,7 +1444,7 @@ async function readinessCmd() {
1432
1444
  }
1433
1445
  if (doc.policy) console.log(` policy: child spawns ${doc.policy.childSpawns.allowed ? "allowed" : "disabled"} (${doc.policy.childSpawns.origin.kind}${doc.policy.childSpawns.enforced ? ", enforced" : ""}); worktrees ${doc.policy.worktrees.allowed === null ? "unknown" : doc.policy.worktrees.allowed ? "allowed" : "not in this work mode"}`);
1434
1446
  for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
1435
- for (const n of doc.notes) console.log(` note: ${n}`);
1447
+ for (const n of doc.notes) console.log(` note: ${terminalText(n)}`);
1436
1448
  return;
1437
1449
  }
1438
1450
  }
@@ -1537,7 +1549,9 @@ function harnessTrustCmd() {
1537
1549
  log(`${result.mode}: native harness trust for ${result.root}`);
1538
1550
  const used = (entry) => [...(entry.ambient ? ["ambient"] : []), ...entry.launchConfigs.map((n) => `launch configuration ${n}`)].join(", ");
1539
1551
  for (const entry of result.entries) {
1540
- log(`${entry.harness}: ${entry.status} ${entry.file ?? "unresolved file"} ${JSON.stringify(entry.key)} ${JSON.stringify(entry.current)} -> ${JSON.stringify(entry.desired)} (${entry.beforeDigest ?? "missing"} -> ${entry.afterDigest ?? "unknown/absent"}) (${used(entry)})`);
1552
+ // A refused file was not read through to its trust value: no current value or digests to show.
1553
+ if (entry.status === "refused") log(`${entry.harness}: refused ${entry.file ?? "unresolved file"} ${JSON.stringify(entry.key)} (${used(entry)})`);
1554
+ else log(`${entry.harness}: ${entry.status} ${entry.file ?? "unresolved file"} ${JSON.stringify(entry.key)} ${JSON.stringify(entry.current)} -> ${JSON.stringify(entry.desired)} (${entry.beforeDigest ?? "missing"} -> ${entry.afterDigest ?? "unknown/absent"}) (${used(entry)})`);
1541
1555
  if (entry.problem) log(`problem: ${entry.problem}`);
1542
1556
  if (entry.reason) log(`skipped: ${entry.reason}`);
1543
1557
  }
@@ -1547,7 +1561,9 @@ function harnessTrustCmd() {
1547
1561
  };
1548
1562
  try {
1549
1563
  // Every configuration file a launch of this deployment reads: its launch configurations' too.
1550
- const result = harnessTrust(context.deploymentDir, { harness: selected, plan: args.includes("--plan"), launchConfigs: launchConfigsAt(context.deploymentDir) });
1564
+ // The ambient one is the file a launch with no launch configuration reads there (its session's
1565
+ // environment over the server's), by the answer every launch check reads; never this shell's own.
1566
+ const result = harnessTrust(context.deploymentDir, { harness: selected, plan: args.includes("--plan"), launchConfigs: launchConfigsAt(context.deploymentDir), launch: previewLaunchEnvironment({ deployment: context.deploymentDir }) });
1551
1567
  if (JSON_MODE) jsonOk(result);
1552
1568
  else show(result);
1553
1569
  } catch (e) {
@@ -2285,7 +2301,7 @@ async function itemsCmd(kind) {
2285
2301
  /** Owner fields decide context, never message text. A problem source is display data;
2286
2302
  * render that projection without changing the operational external source. */
2287
2303
  function catalogProblemLine(p) {
2288
- const owner = p.repoKey || p.package || (p.source ? remoteModule.redactUrl(p.source, null, { pinned: true }) : null);
2304
+ const owner = p.repoKey || p.package || (p.source ? remoteModule.displayRepoRef(p.source, { pinned: true }) : null);
2289
2305
  const where = owner ? ` [${terminalText(`${owner}: ${p.path}`)}]` : "";
2290
2306
  return `! ${p.code}: ${p.message}${where}`;
2291
2307
  }
@@ -2700,6 +2716,15 @@ function herdrSpawnFlag() {
2700
2716
  if (flag("herdr-socket") !== undefined) return "--herdr-socket";
2701
2717
  return undefined;
2702
2718
  }
2719
+ /** A spawn preview's text: the local one, or a host's answer to a routed
2720
+ * preview (`server`, its id), which this side printed the same way (#610). */
2721
+ function printSpawnPreview(r, { server, soulFetched = false } = {}) {
2722
+ // A host before 0.27 names the harness `runtime` (it still answers spawn-preview-2).
2723
+ const harness = r.harness ?? r.runtime;
2724
+ console.log(`preview ${r.agent} → ${r.instance}${server ? ` on ${server}` : ""} (${r.work}${r.branch ? `, branch ${r.branch}${r.base ? ` from ${r.base.ref}@${r.base.oid.slice(0, 12)}` : ""}` : ""}) harness ${harness}${r.model ? ` model ${r.model}` : ` (${r.modelSource})`}${r.launchConfig ? ` via launch configuration ${r.launchConfig}${r.launchConfigDefault ? ` (${server ? "the server's" : "this machine's"} ${harness} default)` : ""}` : ""}${r.yolo ? " YOLO" : ""}; nothing was created${soulFetched ? " (the soul source was fetched to a temporary copy, not kept)" : ""}`);
2725
+ if (Array.isArray(r.worktreeHooks)) console.log(r.worktreeHooks.length ? `worktree hooks: ${r.worktreeHooks.map((h) => `${h.capability}${h.required ? " (required)" : ""}`).join(", ")}` : "worktree hooks: none");
2726
+ for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
2727
+ }
2703
2728
  async function spawnCmd() {
2704
2729
  // JSON mode: contract envelope, stable error codes, stderr-only progress.
2705
2730
  const bail = (code, msg, details, exit) => (JSON_MODE ? jsonFail(code, msg, details, exit) : die(msg, exit));
@@ -2934,42 +2959,14 @@ async function spawnCmd() {
2934
2959
  // (the deployment's cache had no entry for its commit): the result says so.
2935
2960
  if (prepared) r.soulFetched = soulFetched;
2936
2961
  if (JSON_MODE) { jsonOk(withObservation(r)); return; }
2937
- console.log(`preview ${r.agent} → ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch} from ${r.base.ref}@${r.base.oid.slice(0, 12)}` : ""}) harness ${r.harness}${r.model ? ` model ${r.model}` : ` (${r.modelSource})`}${r.launchConfig ? ` via launch configuration ${r.launchConfig}${r.launchConfigDefault ? ` (this machine's ${r.harness} default)` : ""}` : ""}${r.yolo ? " YOLO" : ""}; nothing was created${soulFetched ? " (the soul source was fetched to a temporary copy, not kept)" : ""}`);
2938
- if (Array.isArray(r.worktreeHooks)) console.log(r.worktreeHooks.length ? `worktree hooks: ${r.worktreeHooks.map((h) => `${h.capability}${h.required ? " (required)" : ""}`).join(", ")}` : "worktree hooks: none");
2939
- for (const w of r.warnings || []) console.log(` WARNING: ${w}`);
2962
+ printSpawnPreview(r, { soulFetched });
2940
2963
  return;
2941
2964
  }
2942
2965
  } catch (e) {
2943
- // A typed CLI failure keeps ITS OWN code: re-badging an unsafe-config-key
2944
- // (raised by the readers spawn walks) as E_SPAWN_FAILED tells an agent
2945
- // consumer the spawn mechanism broke, when the fixable fact is a poisoned
2946
- // document the message already names. The shared boundary renders it.
2947
- if (TYPED_CLI_FAILURES.has(e?.code)) throw e;
2948
- // A launch refusal (configuration, executable, environment reference,
2949
- // model, harness) is a fact about the selection, not a spawn-mechanism
2950
- // failure: it keeps its own code so a GUI can act on it.
2951
- if (typeof e?.code === "string" && /^E_LAUNCH_|^E_MODEL_UNKNOWN$|^E_UNSUPPORTED_HARNESS$|^E_HARNESS_UNAVAILABLE$|^E_CLAUDE_CONFIG_REMOVED$/.test(e.code)) { bail(e.code, e.message, e.details); throw e; }
2952
- // An unmet declared requirement is a fact about the soul's configuration
2953
- // (with a remedy), not a spawn-mechanism failure: keep its code and details.
2954
- if (e?.code === "E_REQUIREMENT_INACTIVE") { bail(e.code, e.message, { soul: e.soul, capabilities: e.capabilities, context: e.context, remedy: e.remedy }); throw e; }
2955
- if (e?.code === "E_CHILD_SPAWNS_DISABLED") { bail(e.code, e.message, { parent: e.parent, policy: e.policy }); throw e; }
2956
- if (["E_BRANCH_EXISTS", "E_BASE_UNKNOWN"].includes(e?.code)) { bail(e.code, e.message); throw e; }
2957
- // #796: interrupted while its worktree hooks ran: rolled back (the message says how far), 128+signal.
2958
- if (e?.code === "E_INTERRUPTED") { bail(e.code, e.message, e.details, e.exitStatus); throw e; }
2959
- // A required spawn or worktree hook that failed, or answered outside its environment contract, keeps
2960
- // its typed code: the hooks' receipt (`details.hooks`, paths only) and `unconfirmed` when the rollback
2961
- // could not confirm its effects. Never `home`: a consumer reads that as retained effects.
2962
- if (e?.code === "E_REQUIRED_HOOK_FAILED" || e?.code === "E_HOOK_ENVIRONMENT_CONTRACT") { bail(e.code, e.message, { hooks: e.details?.hooks ?? [], ...(e.details?.unconfirmed === true ? { unconfirmed: true } : {}) }); throw e; }
2963
- // The observed base could not be fetched into the clone: the clone, the repository and the commit travel along.
2964
- if (e?.code === "E_REMOTE_UNREADABLE" && e.details?.commit) { bail(e.code, e.message, e.details); throw e; }
2965
- // K6b: the confirmed decision drifted — the fresh decision travels with the refusal so a GUI re-previews.
2966
- if (e?.code === "E_DECISION_STALE") { bail(e.code, e.message, { decision: e.decision }); throw e; }
2967
- if (e?.code === "E_IDEMPOTENCY_CONFLICT") { bail(e.code, e.message, { instance: e.instance, home: e.home }); throw e; }
2968
- if (e?.code === "E_PLACEMENT_TAKEN") { bail(e.code, e.message, { instance: e.instance, home: e.home }); throw e; }
2969
- if (e?.code === "E_INSTANCE_NAME_TAKEN") { bail(e.code, e.message, { instance: e.instance, home: e.home ?? null, ...(e.session ? { session: e.session } : {}) }); throw e; }
2970
- if (e?.code === "E_INSTANCE_NAME_INVALID") { bail(e.code, e.message, e.details); throw e; }
2971
- if (e?.code === "E_SPAWN_INCOMPLETE") { bail(e.code, e.message, { ...e.details, instance: e.instance, home: e.home, launched: e.launched }); throw e; }
2972
- bail(["E_BAD_ARGS", "E_RELATIVE_AMBIGUOUS"].includes(e.code) ? e.code : "E_SPAWN_FAILED", e.message || e, e.details?.unconfirmed === true ? e.details : undefined); throw e;
2966
+ // The kernel's code, as raised, through the door every lifecycle verb has (spawnFail): a refusal
2967
+ // with a remedy is never answered as "the spawn mechanism failed". E_SPAWN_FAILED is for an
2968
+ // error with no kernel code; a typed CLI failure keeps its own name.
2969
+ spawnFail(e); throw e;
2973
2970
  }
2974
2971
  // The instance exists from here on: a failed wake save is reported beside
2975
2972
  // the full receipt, never hidden, and never causes a second spawn.
@@ -3014,7 +3011,7 @@ async function spawnCmd() {
3014
3011
  if (wakeSchedule) console.log(` wake: schedule ${wakeSchedule.id} (${wakeSchedule.cron} ${wakeSchedule.tz}), next ${wakeSchedule.nextRun || "disabled"}`);
3015
3012
  if (wakeScheduleError) console.error(` wake: NOT saved — ${wakeScheduleError.message} (the instance is created and launched; add the wake by hand with oats schedule add)`);
3016
3013
  if (!r.launched) console.log(` launch: oats session start --home ${shellQuote(r.home)}`);
3017
- for (const w of r.warnings || []) console.log(` WARNING: ${w}`);
3014
+ for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
3018
3015
  console.log(` attach: ${r.attach}`);
3019
3016
  }
3020
3017
 
@@ -3048,7 +3045,7 @@ function retireCmd() {
3048
3045
  console.log(`retire ${name} — plan ${plan.planRevision}`);
3049
3046
  console.log(` session ${plan.facts.session.state}; work ${plan.facts.work.observed ? `${plan.facts.work.changed} changed / ${plan.facts.work.untracked} untracked on ${plan.facts.work.branch ?? (plan.facts.work.detached ? "detached" : "a ref OATS carries no branch name for")}` : `not observed (${plan.facts.work.reason})`}; children ${plan.facts.children.length}; pull request ${plan.facts.pullRequest}`);
3050
3047
  console.log(` ${retireDefaultsLine(plan)}`);
3051
- for (const n of plan.notes) console.log(` note: ${n}`);
3048
+ for (const n of plan.notes) console.log(` note: ${terminalText(n)}`);
3052
3049
  return;
3053
3050
  } catch (e) { return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { ...e.details, candidates: e.candidates } : e.details); }
3054
3051
  }
@@ -3499,7 +3496,7 @@ async function sessionCmd() {
3499
3496
  else {
3500
3497
  console.log(JSON.stringify(result, null, 2));
3501
3498
  // A start's launch-hook warnings, as spawn prints its own (stderr keeps stdout one JSON document).
3502
- for (const w of result?.warnings || []) console.error(` WARNING: ${w}`);
3499
+ for (const w of result?.warnings || []) console.error(` WARNING: ${terminalText(w)}`);
3503
3500
  }
3504
3501
  } catch (e) { lifecycleFail(e, "E_SESSION_FAILED", e.details); }
3505
3502
  }
@@ -3966,6 +3963,9 @@ function updateCmd() {
3966
3963
  if (!steps.length) return end(untouched || ahead ? `\nNothing for \`oats update\` to run.${untouchedNote}` : "\nUp to date.");
3967
3964
  console.log("\nUpdate steps:");
3968
3965
  for (const s of steps) console.log(` ${s.display}`);
3966
+ // A Desktop refuses a CLI of a newer minor (docs/upgrading.md, "Why the Desktop goes first").
3967
+ const desktopFirst = desktopFirstLine(cli);
3968
+ if (desktopFirst) console.log(`\n${desktopFirst}`);
3969
3969
  if (checkOnly) return end("\n(--check: not executing)");
3970
3970
  const interactive = process.stdin.isTTY && process.stdout.isTTY;
3971
3971
  if (interactive) {
@@ -4064,7 +4064,7 @@ async function experimentalCmd() {
4064
4064
  async function serverCmd() {
4065
4065
  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
4066
4066
  const sub = args[1];
4067
- 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>] | forget <id> --instance <name> [--json]";
4067
+ 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]";
4068
4068
  if (!["add", "connect", "list", "remove", "check", "roster", "forget"].includes(sub)) bail("E_USAGE", usage);
4069
4069
  if (sub === "connect") return serverConnectCmd(bail);
4070
4070
  if (sub === "forget") {
@@ -4084,13 +4084,21 @@ async function serverCmd() {
4084
4084
  if (sub === "roster") {
4085
4085
  // The remote roster for the Desktop and operators: grouped by saved route
4086
4086
  // target, one bounded status pull per target, all at once, saved routes as the action
4087
- // authority. --server narrows to one registry id.
4087
+ // authority. --server narrows to one registry id; --workspace-key (repeatable, every occurrence
4088
+ // counts) to the groups that can belong to those workspaces (lib/servers.mjs rosterGroups).
4088
4089
  const only = flag("server") === true ? bail("E_BAD_ARGS", "--server needs a registered server id") : flag("server");
4089
4090
  const ms = (name) => { const v = flag(name); if (v === undefined) return undefined; const n = Number(v); if (!Number.isInteger(n) || n < 1000) bail("E_BAD_ARGS", `--${name} takes whole milliseconds, at least 1000`); return n; };
4091
+ let workspaceKeys;
4092
+ for (let i = 0; i < args.length; i++) if (args[i] === "--workspace-key") {
4093
+ const v = args[i + 1];
4094
+ if (!v || v.startsWith("--")) bail("E_BAD_ARGS", "--workspace-key needs a workspace key (as a host's oats status --json workspace.key reports it)");
4095
+ (workspaceKeys ||= []).push(v);
4096
+ i++;
4097
+ }
4090
4098
  let out;
4091
- try { out = await rosterGroups({ server: only, io: { budgetMs: ms("budget"), perTargetTimeoutMs: ms("per-target") } }); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
4099
+ try { out = await rosterGroups({ server: only, workspaceKeys, io: { budgetMs: ms("budget"), perTargetTimeoutMs: ms("per-target") } }); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
4092
4100
  if (JSON_MODE) { jsonOk(out); return; }
4093
- if (!out.groups.length) { console.log("no remote groups: no registrations and no saved routes"); return; }
4101
+ if (!out.groups.length) { console.log(workspaceKeys ? "no remote groups for the given workspace keys" : "no remote groups: no registrations and no saved routes"); return; }
4094
4102
  for (const g of out.groups) {
4095
4103
  console.log(` ${g.server}${g.label && g.label !== g.server ? ` ${g.label}` : ""} [${g.id}] ssh ${g.target.sshHost} workspace ${g.target.workspace}${g.registrationPresent ? "" : " (registration removed or changed; saved routes only)"}`);
4096
4104
  console.log(g.probe?.ok ? ` reachable, ${g.souls.length} soul(s)` : ` UNREACHABLE: ${g.probe?.error?.message || "?"}`);
@@ -4455,11 +4463,14 @@ async function serverRouteCmd() {
4455
4463
  if (!envelope.ok && !(cmd === "retire" && envelope.result)) die(`${id}: ${envelope.error?.message || "remote command failed"} (${envelope.error?.code || "E_REMOTE"})`);
4456
4464
  const r = envelope.result;
4457
4465
  const target = r.target || {};
4458
- if (cmd === "spawn") {
4466
+ // A routed preview created nothing, there or here: the local preview's lines, naming the server.
4467
+ // The host's answer decides, not the flag: one that spawned is reported as the spawn it was.
4468
+ if (cmd === "spawn" && rest.includes("--preview") && r.preview === true) printSpawnPreview(r, { server: id, soulFetched: r.soulFetched === true });
4469
+ else if (cmd === "spawn") {
4459
4470
  console.log(`Spawned ${r.instance} on ${id} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux?.window}" on ${r.target.sshHost}` : " — not launched"}`);
4460
4471
  console.log(` remote home: ${r.home}`);
4461
4472
  console.log(` route snapshot: ${r.snapshot ? shortPath(r.snapshot) : "none (see the warning)"}`);
4462
- for (const w of r.warnings || []) console.log(` WARNING: ${w}`);
4473
+ for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
4463
4474
  console.log(` attach: oats session attach --server ${shellQuote(id)} --instance ${shellQuote(r.instance)}`);
4464
4475
  } else if (cmd === "retire") {
4465
4476
  // Everything the local retireCmd tells the operator, for a remote home
@@ -4474,6 +4485,7 @@ async function serverRouteCmd() {
4474
4485
  console.log(`Retired ${r.retired} on ${id}${r.deferred ? " (deferred completion scheduled there)" : ""}${r.rollbackIncomplete ? " — cleanup INCOMPLETE on the server, home retained there" : ""}`);
4475
4486
  for (const line of workRecoveryLines(r, { host: target.sshHost })) console.log(line);
4476
4487
  for (const line of extraWorktreeLines(r, { host: target.sshHost })) console.log(line);
4488
+ for (const line of warningLines(r)) console.log(line);
4477
4489
  if (r.rollbackIncomplete) {
4478
4490
  for (const f of r.rollbackIncomplete) console.error(` ${f}`);
4479
4491
  const branch = failedSpawnBranchLine(r, r.rollbackIncomplete, { host: target.sshHost });
@@ -4586,13 +4598,12 @@ else if (cmd === "status") await status();
4586
4598
  else if (cmd === "pane") await paneCmd();
4587
4599
  else if (cmd === "tui") await tuiCmd();
4588
4600
  else if (cmd === "version" || cmd === "--version" || cmd === "-v") versionCmd();
4589
- // Same rule as the inner catch: a typed CLI failure surfaces with its own code
4590
- // through the shared boundary, never re-badged as a spawn-mechanism failure.
4591
4601
  else if (cmd === "session") await sessionCmd();
4592
4602
  else if (cmd === "schedule") await scheduleCmd();
4593
4603
  else if (cmd === "trigger") await triggerCmd();
4594
4604
  else if (cmd === "automations") await automationsCmd();
4595
- else if (cmd === "spawn") { try { await spawnCmd(); } catch (e) { if (TYPED_CLI_FAILURES.has(e?.code)) throw e; if (JSON_MODE) jsonFail("E_SPAWN_FAILED", e.message || e, e.details?.unconfirmed === true ? e.details : undefined); throw e; } }
4605
+ // What a spawn throws outside its kernel stage goes through the same door as the inner catch.
4606
+ else if (cmd === "spawn") { try { await spawnCmd(); } catch (e) { spawnFail(e); throw e; } }
4596
4607
  // What a retire throws outside its own answers (the root, a replay's read) goes through the same door.
4597
4608
  // An exception after the retire has returned (retireReturned) is rethrown, here and by the handler
4598
4609
  // of typed failures below: a crash is read as "not confirmed", which is the truth, where an error
@@ -4678,6 +4689,9 @@ Usage:
4678
4689
  [--budget <ms>] [--per-target <ms>] target: one status pull per group within a total
4679
4690
  [--json] budget (45 s, 20 s per target); every instance the
4680
4691
  server reports is addressable by --home or name
4692
+ [--workspace-key <key>]... only groups that can belong to these workspaces:
4693
+ registered for one of them, workspace not known,
4694
+ or saved routes only (repeatable)
4681
4695
  oats server forget <id> --instance <name> drop a saved route whose remote instance is gone
4682
4696
  (the roster shows it as missingRemotely)
4683
4697
  oats retire <instance> --home <path> retire exactly that home when two agents own an
@@ -4790,12 +4804,14 @@ Usage:
4790
4804
  a detached external retirement runs
4791
4805
  oats inspect [--dir <scope>] [--soul <name> one authoritative JSON answer for a GUI: souls
4792
4806
  [--agents-root <abs>]] [--home <abs>] (harness defaults, editability, instructions),
4793
- [--instructions] [--max-age <s>] installed capabilities with health, effective
4794
- [--json] layer bindings and activation, declared
4807
+ [--instructions] [--skills] installed capabilities with health, effective
4808
+ [--max-age <s>] [--json] layer bindings and activation, declared
4795
4809
  operations with availability; --home answers the
4796
4810
  running home's recorded modules and their drift
4797
4811
  from the deployment; --instructions (--soul only)
4798
- adds the AGENTS.md a spawn of the soul here would write
4812
+ adds the AGENTS.md a spawn of the soul here would write;
4813
+ --skills (--soul only) adds the soul's own skills, the
4814
+ ones a spawn copies, with each file's text
4799
4815
  oats operation run <layer>:<name> run an operation the soul's core capability for that
4800
4816
  (--home <abs> | --soul <name> [--dir <d>]) layer declares (knowledge:harvest, knowledge:
4801
4817
  [--arg k=v ...] [--json] inspect ...): resolved from the home's recorded
@@ -319,8 +319,9 @@ A self-contained package has an `oats.json`:
319
319
  Spawn alone can see two more cases, and refuses the spawn with
320
320
  `E_CAPABILITY_BROKEN` and rolls it back: a declared root that is a
321
321
  symlink in the work (also one whose target is missing), and roots of
322
- different capabilities that overlap. `oats spawn --json` reports these,
323
- as other spawn failures, as `E_SPAWN_FAILED` with the same message.
322
+ different capabilities that overlap. `oats spawn --json` answers these
323
+ with `E_CAPABILITY_BROKEN` and the same message (`E_SPAWN_FAILED`
324
+ before 0.56.0).
324
325
 
325
326
  A malformed `retirement` is refused wherever the manifest is read: member
326
327
  discovery (`E_WORKSPACE_SCHEMA`), package manifests (`E_PACKAGE_MANIFEST`)
@@ -352,15 +353,29 @@ A self-contained package has an `oats.json`:
352
353
  A harness package is **verified at spawn, never installed there**: installing
353
354
  would mutate the operator's harness configuration without asking, in the
354
355
  middle of a spawn. A missing, uninstalled or disabled package fails the spawn
355
- with direct package-manager guidance for the operator. The command uses the
356
+ with direct package-manager guidance for the operator
357
+ (`E_HARNESS_RESOURCE_MISSING`; a start, a restart and a launch plan's
358
+ `harness-packages` check answer the same code, `E_HARNESS_PACKAGE` before
359
+ 0.56.0). The command uses the
356
360
  selected harness executable and resource directory, with Claude marketplace
357
361
  registration before plugin installation. Run it in the indicated context
358
362
  with the same launch environment; spawn and restart never install packages.
363
+ The probe runs the executable the launch's lookup selected, with the
364
+ `PATH`, `HOME` and harness folder the launch's
365
+ pane will have, never the calling process's in their place, and the command
366
+ starts with that folder's variable when the launch has one. Besides
367
+ `E_HARNESS_RESOURCE_MISSING` for a missing package, the check raises
368
+ `E_RUNTIME_ENDPOINT_UNKNOWN` when one of those names cannot be read from
369
+ the pane, and probes nothing
370
+ ([the checks read the pane](execution-targets.md#the-checks-read-the-pane)).
359
371
  - OATS never installs a host requirement silently. A missing host command is
360
372
  the operator's to install; `oats doctor` reports it. Consent to install is
361
373
  separate from declaring the package.
362
374
  - `environment` lists the exact launch variables the capability may set;
363
375
  spawn hook output must be a subset and use the capability vendor prefix.
376
+ A listed variable is the capability's to decide: a launch it is part of
377
+ never inherits one its hooks leave out
378
+ ([a declared name is the provider's](#a-declared-name-is-the-providers)).
364
379
  - `triggerSources` (optional) declares the capability's
365
380
  [trigger sources](#trigger-sources-triggersources). It is checked only
366
381
  where a source is used, never when the capability loads.
@@ -740,6 +755,55 @@ Spawn order is by capability name; retirement reverses successful
740
755
  spawn order. Hooks run from the instance's own copy
741
756
  (`<home>/.oats/modules/<cap>/`).
742
757
 
758
+ ### A declared name is the provider's
759
+
760
+ A variable a capability declares in `environment` is the capability's to
761
+ decide, for every launch the capability is part of, from 0.56.0. A launch
762
+ starts with exactly what its capabilities' hooks return for those names:
763
+
764
+ - **Returned:** the launch has the hook's value, as before.
765
+ - **Left out** (the hook answered without it, the hook failed, or the
766
+ capability has no hook that ran for this launch): the launch has **no**
767
+ such variable. It is removed from the harness's environment, never
768
+ inherited from the pane's ambient environment: the tmux server's global
769
+ one, the session's, the login shell that started the server, or the
770
+ Desktop's. Before 0.56.0 such a name kept whatever value the pane held, so
771
+ one instance's value (`AWEB_DELIVERY=session`, say) could reach another
772
+ instance launched in the same session or on the same server.
773
+ - **Set by the launch configuration's `env`:** the configuration's value,
774
+ as before. It is the operator's explicit setting on the launch's own
775
+ command, not an ambient value. (A configuration still cannot override a
776
+ name a capability's hook returns: `E_LAUNCH_ENV_CONFLICT`.)
777
+
778
+ The capabilities a launch is checked against are the ones its hooks run
779
+ against: for a spawn, the soul's composed capabilities, with their spawn hooks'
780
+ answers; for a start or restart, the providers the spawn captured, with the
781
+ recorded contributions and the answers of the launch hooks that run again
782
+ then. A name two capabilities declare is removed unless one of them returns
783
+ it. Each window gets this on its own command: OATS unsets the removed names
784
+ in the window's command (as it does `COLORFGBG`), before the launch's own
785
+ assignments, for a spawn, a start, a start in place and a restart. The
786
+ persisted launch command (`instance.json` `command`) does not change. The
787
+ shell a pane falls back to when the harness exits is started by that command,
788
+ so it has none of them either.
789
+
790
+ A removed name that selects a harness's configuration folder (a capability
791
+ may declare `CLAUDE_CONFIG_DIR`, `CODEX_HOME` or `PI_CODING_AGENT_DIR` under a
792
+ namespace it names) reads as not set in the checks of that launch: the
793
+ package probe, folder trust and readiness then read the default folder under
794
+ `HOME`, as the harness will. A spawn's first package check runs before its
795
+ hooks and cannot know it yet; its check on the session it gets does
796
+ ([one limit](execution-targets.md#the-checks-read-the-pane)).
797
+
798
+ A launch whose capabilities do not declare a name is unchanged: an ambient
799
+ value of that name still reaches it. The tmux server's and the session's
800
+ environment are not changed either (see
801
+ [the environment of the server and its panes](execution-targets.md#the-environment-of-the-server-and-its-panes)).
802
+ **A limit for Codex:** the removed names are not set for Codex's tool
803
+ commands (`shell_environment_policy.set`), but a Codex app-server that runs
804
+ outside the launch (a shared daemon another process started) has that
805
+ process's environment, which OATS does not reach.
806
+
743
807
  ### The node a hook writes down
744
808
 
745
809
  A hook or a command that writes a `node` path into something that outlives it
@@ -60,11 +60,35 @@ symlink enters as `symlink:<target>`; empty directories and a top-level `.git/`
60
60
  needs them; whole trees from a server without partial fetches; awebai/oats#384) into a bare cache `<cacheDir>/<sha256(key)>/` (default
61
61
  `~/.cache/oats/remotes`; the CLI honours `OATS_REMOTE_CACHE`) and pinned as `refs/oats/commits/<oid>`.
62
62
  The cache may be wiped at any time. Operations on one cache repo are serialized.
63
+ - Only a successfully parsed Git version below 2.45 authorizes a version-driven
64
+ rebuild of a partial cache into full mode. A failed or unparseable version
65
+ probe refuses the read as `E_REMOTE_UNREADABLE` under the existing failure
66
+ classification, preserving the cache, fetch mode and all commit pins. A
67
+ probe timeout stays `timeout` even before a session's deadline; unparseable
68
+ output is `unknown`. This holds with or without a session. Failures are not
69
+ memoized: a later call can probe again. Full caches remain full after a
70
+ successful modern-version probe. The private strict probe and the
71
+ version-or-`null` compatibility helper share one memo per executor. Each
72
+ waiter can leave on its own timeout/cancellation, evicting only the memo
73
+ entry it waited on. The launching caller's timeout and signal bound the
74
+ shared Git process; its rejection reaches all remaining waiters, including
75
+ those whose own deadlines have not expired. A later call can retry.
63
76
  - Failures: `E_REMOTE_UNREADABLE { url, key, reason }`, `reason` ∈ `auth`, `not-found`, `network`,
64
77
  `timeout`, `unknown`. Nothing half-succeeds.
65
- - Reference-bearing diagnostics use `redactUrl`, including parser refusals, package and
66
- workspace validation errors, and quoted Git text; the [display rule](../workspaces.md#repository-references-in-diagnostics)
67
- removes user information without changing the reference used for transport.
78
+ - Reference-bearing diagnostics choose an explicit entry point:
79
+ `displayRepoRef(value, { pinned = false, rejectedValue = false } = {})` for
80
+ selected reference values, `displayDiagnosticText(value, source = null,
81
+ { fragment = false, refusal = false, substitute = true, rejectedValue = false } = {})`
82
+ for kernel-authored prose, and `scrubGitLine(line, url = null)` for Git's
83
+ lines. One private renderer owns the [display rule](../workspaces.md#repository-references-in-diagnostics).
84
+ The entries extract only their named options and fix their own contexts;
85
+ reference or kernel-prose options cannot select Git-line handling.
86
+ `displayRepoRef` accepts `pinned: true` for a whole `<ref>@<commit>` source
87
+ or `pinned: { ref, commit }` for its original components; both strictly
88
+ validate reference and commit without a plain-value fallback. Display
89
+ changes no admission, transport, operational value or error shape. These
90
+ are internal/direct-module entry points, not package export-map entries;
91
+ there is no implicit `redactUrl` export or shim.
68
92
 
69
93
  ---
70
94