@awebai/oats 0.69.1 → 0.69.2

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 (67) hide show
  1. package/bin/oats.mjs +79 -15
  2. package/docs/capabilities.md +24 -5
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/design/2026-09-23-workspace-module-contracts.md +6 -4
  5. package/docs/design/2026-10-22-module-upgrade.md +1 -1
  6. package/docs/desktop-cli-api.md +260 -28
  7. package/docs/desktop-instance-start.md +8 -37
  8. package/docs/desktop.md +76 -9
  9. package/docs/execution-targets.md +27 -5
  10. package/docs/implementation.md +6 -5
  11. package/docs/integrations.md +1 -1
  12. package/docs/knowledge.md +25 -16
  13. package/docs/official-catalog.md +3 -3
  14. package/docs/packages.md +12 -12
  15. package/docs/release-notes/v0.69.2.md +259 -0
  16. package/docs/servers.md +7 -2
  17. package/docs/soul.schema.json +1 -0
  18. package/docs/souls-and-instances.md +35 -2
  19. package/docs/tui.md +100 -9
  20. package/docs/upgrading.md +9 -5
  21. package/docs/workspaces.md +2 -2
  22. package/injects/instance-boundary.md +19 -33
  23. package/injects/work-attached.md +8 -13
  24. package/injects/work-checkout.md +16 -30
  25. package/injects/work-directory.md +9 -15
  26. package/injects/work-workspace.md +8 -19
  27. package/injects/work-worktree.md +18 -33
  28. package/lib/capability-contract.mjs +2 -2
  29. package/lib/core.mjs +162 -49
  30. package/lib/instance-background.mjs +54 -0
  31. package/lib/instance-inspect.mjs +3 -0
  32. package/lib/instance-lifecycle.mjs +35 -0
  33. package/lib/instance-resolution.mjs +3 -2
  34. package/lib/instance-same-work.mjs +67 -0
  35. package/lib/instance-upgrade.mjs +18 -0
  36. package/lib/materialize.mjs +23 -2
  37. package/lib/resolve.mjs +32 -5
  38. package/lib/servers.mjs +19 -4
  39. package/lib/session-resume-contract.mjs +1 -0
  40. package/lib/session-resume.mjs +36 -9
  41. package/lib/soul-composition.mjs +13 -10
  42. package/lib/workspace.mjs +3 -2
  43. package/package-catalog.json +2 -2
  44. package/package.json +1 -1
  45. package/packages/client/cli-adapter.mjs +30 -8
  46. package/packages/client/deployment-data.mjs +9 -0
  47. package/packages/client/deployment-panel.mjs +4 -0
  48. package/packages/client/instance-tree.mjs +64 -14
  49. package/packages/client/panel-views.mjs +11 -3
  50. package/packages/client/remote-roster.mjs +5 -1
  51. package/packages/client/roster-sections.mjs +50 -6
  52. package/packages/client/same-work.mjs +49 -0
  53. package/packages/client/session-resume.mjs +1 -1
  54. package/packages/client/soul-rows.mjs +2 -0
  55. package/packages/client/spawn-apply-contract.mjs +2 -1
  56. package/packages/client/spawn-decision.mjs +4 -1
  57. package/packages/client/spawn-preview-contract.mjs +12 -1
  58. package/packages/client/spawn-preview.mjs +2 -0
  59. package/packages/tui/README.md +2 -2
  60. package/packages/tui/lib/client.mjs +6 -2
  61. package/packages/tui/lib/main.mjs +44 -11
  62. package/packages/tui/lib/model.mjs +101 -43
  63. package/packages/tui/lib/store.mjs +76 -20
  64. package/packages/tui/lib/views/frame.mjs +2 -0
  65. package/packages/tui/lib/views/help.mjs +2 -0
  66. package/packages/tui/lib/views/instances.mjs +38 -1
  67. package/skills/oats-getting-started/SKILL.md +2 -2
package/bin/oats.mjs CHANGED
@@ -62,7 +62,7 @@ import { kernelNode, stableNode } from "../lib/stable-node.mjs";
62
62
  import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
63
63
 
64
64
  import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
65
- import { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance as resolveInstanceForCli, setInstanceColor, STOP_WARNINGS } from "../lib/instance-lifecycle.mjs";
65
+ import { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance as resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstanceSameWork, STOP_WARNINGS } from "../lib/instance-lifecycle.mjs";
66
66
  import { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } from "../lib/retire-output.mjs";
67
67
  import { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } from "../lib/retained-after-retire.mjs";
68
68
  const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
@@ -74,7 +74,7 @@ import { SESSION_RESUME_FEATURE } from "../lib/session-resume-contract.mjs";
74
74
 
75
75
  const rawArgs = process.argv.slice(2);
76
76
  /** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
77
- const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "composed-skills", "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", "suggest-name", "verbose", "yes", "yolo"]);
77
+ const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "background", "check", "clear", "composed-skills", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-background", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "run-source", "same-work", "self", "skills", "suggest-name", "verbose", "yes", "yolo"]);
78
78
  /** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
79
79
  * routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
80
80
  * `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
@@ -110,7 +110,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
110
110
  * probe) and in `status --json`, which a remote roster relays as the host's (feature
111
111
  * server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
112
112
  * time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
113
- const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE];
113
+ const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-same-work"];
114
114
  /** Commands `--server <id>` runs on a registered server. */
115
115
  const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
116
116
  const flag = (name) => {
@@ -1411,8 +1411,8 @@ async function instanceCmd() {
1411
1411
  if (sub === "upgrade") return instanceUpgradeCmd(name, bail);
1412
1412
  if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
1413
1413
  if (sub === "suggest-name") return instanceSuggestNameCmd(bail);
1414
- 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]";
1415
- if (!["git", "diff", "stop", "events", "color"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
1414
+ 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]";
1415
+ if (!["git", "diff", "stop", "events", "color", "background", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
1416
1416
  dropAmbientRoot();
1417
1417
  if (sub === "events") {
1418
1418
  // K7: typed producer events, bounded window; nothing inferred.
@@ -1468,6 +1468,44 @@ async function instanceCmd() {
1468
1468
  return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
1469
1469
  }
1470
1470
  }
1471
+ if (sub === "background") {
1472
+ // Feature instance-background: presentation only, so no plan; addressed as `instance color` addresses an instance.
1473
+ const homeOpt = flag("home");
1474
+ if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
1475
+ const backgroundUsage = "usage: oats instance background <instance> on|off [--home <abs>] [--dir <d>] [--json]";
1476
+ // The words after the instance that are not a flag or the value of --home or --dir: exactly one, on or off.
1477
+ const words = [];
1478
+ 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]); }
1479
+ if (words.length !== 1 || !["on", "off"].includes(words[0])) return bail("E_BAD_ARGS", `give on or off; ${backgroundUsage}`);
1480
+ let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
1481
+ try {
1482
+ const r = setInstanceBackground(dirFlag(), root, name, { home: homeOpt, background: words[0] === "on" });
1483
+ if (JSON_MODE) { jsonOk(r); return; }
1484
+ console.log(`${r.instance}: ${r.background ? "background" : "not background"}${r.changed ? "" : " (unchanged)"}`);
1485
+ return;
1486
+ } catch (e) {
1487
+ return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
1488
+ }
1489
+ }
1490
+ if (sub === "same-work") {
1491
+ // Feature instance-same-work: presentation only, so no plan; addressed as color addresses an instance.
1492
+ const homeOpt = flag("home");
1493
+ if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
1494
+ const sameWorkUsage = "usage: oats instance same-work <instance> on|off [--home <abs>] [--dir <d>] [--json]";
1495
+ // The words after the instance that are not a flag or the value of --home or --dir: exactly one, on or off.
1496
+ const words = [];
1497
+ for (let i = 3; i < args.length; i++) { if (args[i] === "--home" || args[i] === "--dir") i++; else if (!args[i].startsWith("--")) words.push(args[i]); }
1498
+ if (words.length !== 1 || !["on", "off"].includes(words[0])) return bail("E_BAD_ARGS", `give on or off; ${sameWorkUsage}`);
1499
+ let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
1500
+ try {
1501
+ const r = setInstanceSameWork(dirFlag(), root, name, { home: homeOpt, on: words[0] === "on" });
1502
+ if (JSON_MODE) { jsonOk(r); return; }
1503
+ console.log(`${r.instance}: same work ${r.sameWork ? "on" : "off"}`);
1504
+ return;
1505
+ } catch (e) {
1506
+ return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
1507
+ }
1508
+ }
1471
1509
  if (sub === "stop") {
1472
1510
  // K3: plan → apply. The plan is what a confirmation shows; apply carries
1473
1511
  // its revision back and refuses if reality moved.
@@ -1770,7 +1808,8 @@ function workspaceItems(discovery, lock, local, deploymentDir) {
1770
1808
  try { launchConfigs = deploymentDir ? launchConfigsAt(deploymentDir) : {}; } catch { launchConfigs = {}; }
1771
1809
  // One description of this read for every soul's launch: which keys of souls.launch name no soul.
1772
1810
  const offered = soulsOffered(discovery);
1773
- const soulDefaults = (entry) => soulLaunchFacts(entry, local, { launchConfigs, contextDir: deploymentDir, offered });
1811
+ // Feature instance-background: `background: true` on a soul that declares it, absent otherwise.
1812
+ const soulDefaults = (entry) => ({ ...soulLaunchFacts(entry, local, { launchConfigs, contextDir: deploymentDir, offered }), ...(entry.definition?.background === true ? { background: true } : {}) });
1774
1813
  const capabilities = [];
1775
1814
  const model = teamModel(discovery.standalone === true ? null : discovery.workspace, local, { workspaceKey: discovery.key ?? null });
1776
1815
  const teamsHere = (entry) => {
@@ -2794,7 +2833,8 @@ async function status() {
2794
2833
  console.log(` ${a.name} [work: ${a.work || "checkout"}, repo: ${soulRepoLabel(a, ws)}]`);
2795
2834
  if (a.description) console.log(` ${a.description}`);
2796
2835
  for (const i of a.instances) {
2797
- console.log(` • ${i.instance} ${i.retirePending ? "RETIRING" : livenessWord(i)} (branch ${i.branch || "?"}, ${i.work || "?"})${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
2836
+ // Feature instance-background: the row is marked; it is listed like any other.
2837
+ console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${i.retirePending ? "RETIRING" : livenessWord(i)} (branch ${i.branch || "?"}, ${i.work || "?"})${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
2798
2838
  // Feature waiting-on-you: non-null only on a running row; the reader has
2799
2839
  // already validated the message (one line, no control characters).
2800
2840
  if (i.running === true && i.waitingOnYou) console.log(` ! needs input (${i.waitingOnYou.reason ?? "unknown"})${i.waitingOnYou.message ? `: ${i.waitingOnYou.message}` : ""}`);
@@ -2821,7 +2861,7 @@ const livenessWord = (i) => i.running === true ? "RUNNING" : i.running === false
2821
2861
  * host through `--server`, whose route reads it. `--max-age` reaches here only on a preview or an
2822
2862
  * apply bound by --expect-decision: the dispatch allow-list (maxAgeRefusal) refuses it otherwise. */
2823
2863
  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"]);
2824
- const SPAWN_SWITCHES = new Set(["allow-child-spawns", "json", "no-child-spawns", "no-launch", "no-yolo", "preview", "suggest-name", "yolo"]);
2864
+ 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"]);
2825
2865
  /** `--suggest-name` (features spawn-suggest-name, spawn-apply-suggest-name): a preview's or an apply's,
2826
2866
  * with no --name, --purpose or --expect-decision. The kernel refuses the same (core.mjs spawnBody); the
2827
2867
  * CLI says it before anything is read or sent. */
@@ -2832,6 +2872,8 @@ function suggestNameProblem(argv) {
2832
2872
  if (given("--name") || given("--purpose")) return "--suggest-name chooses the name: it takes no --name or --purpose";
2833
2873
  return undefined;
2834
2874
  }
2875
+ /** `--background` / `--no-background` (feature instance-background): one of them, or neither. */
2876
+ const backgroundProblem = (argv) => (argv.includes("--background") && argv.includes("--no-background") ? "choose --background or --no-background, not both" : undefined);
2835
2877
  /** Why `argv` (after `spawn`, the soul first) is not a spawn, or undefined: a positional after the
2836
2878
  * soul or a flag spawn does not read is never ignored. A value flag consumes its value exactly as
2837
2879
  * flag() reads it; a missing value is the flag's own check. */
@@ -2873,6 +2915,7 @@ function printSpawnPreview(r, { server, soulFetched = false } = {}) {
2873
2915
  console.log(`preview ${r.agent} → ${r.instance}${server ? ` on ${server}` : ""} (${r.work}${r.branch ? `, branch ${r.branch}${r.base ? ` from ${r.base.ref}@${r.base.oid.slice(0, 12)}` : ""}` : ""}) harness ${harness}${r.model ? ` model ${r.model}` : ` (${r.modelSource})`}${r.launchConfig ? ` via launch configuration ${r.launchConfig}${r.launchConfigDefault ? ` (${server ? "the server's" : "this machine's"} ${harness} default)` : ""}${r.launchConfigSource ? ` from ${server ? terminalText(r.launchConfigSource) : shortPath(launchConfigFile(r.launchConfigSource))}` : ""}` : ""}${r.yolo ? " YOLO" : ""}; nothing was created${soulFetched ? " (the soul source was fetched to a temporary copy, not kept)" : ""}`);
2874
2916
  // Feature spawn-suggest-name: how the name was chosen.
2875
2917
  { const line = namingLine(r.naming); if (line) console.log(`name: ${line}`); }
2918
+ if (r.background === true) console.log(`list: background (from the ${r.backgroundFrom === "flag" ? "--background flag" : "soul"})`);
2876
2919
  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");
2877
2920
  for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
2878
2921
  }
@@ -2891,7 +2934,7 @@ async function spawnCmd() {
2891
2934
  };
2892
2935
  checkDirectoryOptions(requestedWork); // before anything is resolved or written
2893
2936
  const name = args[1];
2894
- 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>] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux] [--yolo|--no-yolo] [--model <m>] [--branch <b>] [--no-launch] [--json]");
2937
+ 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]");
2895
2938
  // Retired boundary flags (maintainer transport ruling): fail LOUDLY before
2896
2939
  // ANY side effect, including root discovery.
2897
2940
  // Local souls (local-agents/) are gone with the workspace model: a soul is a member
@@ -2902,7 +2945,7 @@ async function spawnCmd() {
2902
2945
  const nameFlag = flag("name");
2903
2946
  if (nameFlag === true) bail("E_BAD_ARGS", "--name needs an instance name (a slug: lowercase letters and digits, single dashes between them)");
2904
2947
  if (nameFlag !== undefined && flag("purpose") !== undefined) bail("E_BAD_ARGS", "--name and --purpose are mutually exclusive: --name is the exact instance name, --purpose derives <agent>-<purpose>");
2905
- { const problem = suggestNameProblem(args); if (problem) bail("E_BAD_ARGS", problem); }
2948
+ { const problem = suggestNameProblem(args) ?? backgroundProblem(args); if (problem) bail("E_BAD_ARGS", problem); }
2906
2949
  // The slug rule is checked here too, before any side effect (soul fetch).
2907
2950
  if (nameFlag !== undefined) { try { explicitInstanceName(String(nameFlag)); } catch (e) { bail(e.code, e.message); throw e; } }
2908
2951
  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");
@@ -3085,6 +3128,8 @@ async function spawnCmd() {
3085
3128
  prepared,
3086
3129
  purpose: flag("purpose"), ...(nameFlag !== undefined ? { name: String(nameFlag) } : {}), task: taskText, taskFile: taskFileFlag, relation, relativeTo, relativeRoot,
3087
3130
  ...(args.includes("--allow-child-spawns") ? { allowChildSpawns: true } : args.includes("--no-child-spawns") ? { allowChildSpawns: false } : {}),
3131
+ // Feature instance-same-work: the kernel binds it to the parent the new home records, or refuses.
3132
+ ...(args.includes("--same-work") ? { sameWork: true } : {}),
3088
3133
  // Directory execution uses deployment configuration, not an ambient Git
3089
3134
  // checkout (especially when invoked via --dir from a source instance).
3090
3135
  // An attached instance's repository is the repository of the tree it is attached to (derived by the kernel).
@@ -3092,6 +3137,8 @@ async function spawnCmd() {
3092
3137
  ? repo : repo || defaultRepo(workspaceOf(root)) || defaultRepo(process.cwd()),
3093
3138
  work: requestedWork, workDir, harness: harnessFlag(), backend, yolo, model: flag("model"), branch,
3094
3139
  launchConfig: valueFlag("launch-config"),
3140
+ // Feature instance-background: the flag wins over the soul's `background:`.
3141
+ ...(args.includes("--background") ? { background: true } : args.includes("--no-background") ? { background: false } : {}),
3095
3142
  launch: !args.includes("--no-launch"),
3096
3143
  ...(triggerEvent ? { triggerEvent } : {}),
3097
3144
  // K6: --preview decides everything and touches nothing; --base <ref>
@@ -3147,6 +3194,8 @@ async function spawnCmd() {
3147
3194
  sibling: r.siblingInstance || null, relation: r.relation || null,
3148
3195
  spawnOrigin: r.spawnOrigin, attach: r.attach,
3149
3196
  ...(r.yolo !== undefined ? { yolo: r.yolo } : {}),
3197
+ // Feature instance-background: whether the home is background, and which layer declared it.
3198
+ background: r.background === true, ...(r.backgroundFrom ? { backgroundFrom: r.backgroundFrom } : {}),
3150
3199
  // K6b/K6c: what bound this spawn, and whether this receipt is a replay of an earlier one.
3151
3200
  ...(r.decision ? { decision: r.decision } : {}), ...(r.replayed !== undefined ? { replayed: r.replayed } : {}),
3152
3201
  ...(r.wake !== undefined ? { wake: r.wake } : {}), // {requested, saved|null, error}: saved:null = outcome not recorded
@@ -3160,6 +3209,7 @@ async function spawnCmd() {
3160
3209
  }
3161
3210
  console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux.window}"` : " — not launched"}`);
3162
3211
  console.log(` home: ${shortPath(r.home)}`);
3212
+ if (r.background === true) console.log(` list: background (from the ${r.backgroundFrom === "flag" ? "--background flag" : "soul"})`);
3163
3213
  { const line = namingLine(r.naming); if (line) console.log(` name: ${line}`); }
3164
3214
  if (r.base) console.log(` base: ${r.base.oid.slice(0, 12)} (${r.base.ref === r.workspace?.soul?.repoKey ? `observed head of ${r.base.ref}` : r.base.ref})`);
3165
3215
  for (const h of r.worktreeHooks || []) console.log(` setup: ${h.capability} worktree hook ${h.ok ? "ok" : "FAILED"} (log: ${shortPath(h.log)})`);
@@ -3664,8 +3714,10 @@ async function sessionCmd() {
3664
3714
  const chosen = ["--launch-config", "--harness", "--model", "--yolo", "--no-yolo", "--reselect-launch"].filter((f) => args.some((a) => a === f || a.startsWith(`${f}=`)));
3665
3715
  if (chosen.length) bad(`--resume runs the launch this home recorded; it cannot be combined with ${chosen.join(", ")}; nothing was read or started`);
3666
3716
  }
3667
- // Refuse before launch selection or live-team discovery can prepare this home.
3668
- assertNoPartialUpgrade(home);
3717
+ // Refuse before launch selection or live-team discovery can prepare this home. A resume is
3718
+ // refused under the home's lifecycle claim instead (lib/core.mjs startInstanceSession): beside
3719
+ // an upgrade that runs, it is busy, not a partial upgrade.
3720
+ if (!resume) assertNoPartialUpgrade(home);
3669
3721
  const opts = { model: model || undefined, launchConfig, harness, yolo: yoloFlag(), ...(reselectLaunch ? { reselectLaunch: true, launchOffered: await homeLaunchOffered(home, { named: harness !== undefined }) } : {}), ...(resume ? { resume: true } : {}), env: process.env, ...(await homeLiveTeams(home)) };
3670
3722
  if (args[1] === "restart") {
3671
3723
  const grace = flag("stop-grace");
@@ -4410,7 +4462,7 @@ async function serverCmd() {
4410
4462
  for (const g of out.groups) {
4411
4463
  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)"}`);
4412
4464
  console.log(g.probe?.ok ? ` reachable, ${g.souls.length} soul(s)` : ` UNREACHABLE: ${g.probe?.error?.message || "?"}`);
4413
- for (const i of g.instances) console.log(` • ${i.instance} ${i.missingRemotely ? "GONE on the host (saved route is stale: oats server forget)" : i.running === true ? "RUNNING" : i.running === false ? "idle" : "unknown"}${i.retirePending ? " RETIRING" : ""}${i.rollbackIncomplete ? " QUARANTINED" : ""}${i.savedRoute ? "" : " (observed only, no saved route)"}${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
4465
+ for (const i of g.instances) console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${i.missingRemotely ? "GONE on the host (saved route is stale: oats server forget)" : i.running === true ? "RUNNING" : i.running === false ? "idle" : "unknown"}${i.retirePending ? " RETIRING" : ""}${i.rollbackIncomplete ? " QUARANTINED" : ""}${i.savedRoute ? "" : " (observed only, no saved route)"}${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
4414
4466
  for (const f of g.retireFailures || []) console.log(` ! deferred retirement of ${f.instance} (${f.agent}) FAILED there${f.error?.message ? `: ${f.error.message}` : ""}${f.retry ? ` — retry on the host: ${f.retry}` : ""}`);
4415
4467
  }
4416
4468
  console.log(` bounds: ${out.bounds.perTargetTimeoutMs} ms per target within ${out.bounds.budgetMs} ms, ${out.bounds.elapsedMs} ms used`);
@@ -4716,7 +4768,7 @@ async function serverRouteCmd() {
4716
4768
  const herdr = herdrSpawnFlag();
4717
4769
  if (herdr) { const e = herdrSettingRemoved(`${herdr} was given`); bail(e.code, e.message); }
4718
4770
  const local = args.slice(1).filter((a, i, all) => a !== "--server" && all[i - 1] !== "--server");
4719
- const problem = spawnArgvProblem(local) ?? suggestNameProblem(local);
4771
+ const problem = spawnArgvProblem(local) ?? suggestNameProblem(local) ?? backgroundProblem(local);
4720
4772
  if (problem) bail("E_BAD_ARGS", problem);
4721
4773
  }
4722
4774
  // Everything after the command word travels, minus the routing flags; a
@@ -4807,7 +4859,7 @@ async function serverRouteCmd() {
4807
4859
  console.log(`oats status — server ${id} (ssh ${r.target.sshHost}, workspace ${r.target.workspace})\n`);
4808
4860
  for (const a of r.agents || []) {
4809
4861
  console.log(` ${a.name} [work: ${a.work || "checkout"}, repo: ${a.repo || "?"}]`);
4810
- for (const i of a.instances || []) console.log(` • ${i.instance} ${i.retirePending ? "RETIRING" : livenessWord(i)}${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
4862
+ for (const i of a.instances || []) console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${i.retirePending ? "RETIRING" : livenessWord(i)}${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
4811
4863
  }
4812
4864
  const snaps = r.snapshots || [];
4813
4865
  if (snaps.length) console.log(`\n spawned from this machine: ${snaps.map((s) => s.instance).join(", ")}`);
@@ -5143,6 +5195,9 @@ Usage:
5143
5195
  [--relation child|sibling|parent|unrelated] anchor with --relative-to (except unrelated);
5144
5196
  [--relative-to <instance>] default: unrelated, top-level
5145
5197
  [--relative-root <agents-root>] disambiguates same-named anchors
5198
+ [--same-work] record that the new instance does the same work as
5199
+ its parent; clients draw the parent line for it
5200
+ (needs a relation that records a parent)
5146
5201
  [--work worktree|checkout|attached|workspace|directory] override the soul's work mode
5147
5202
  [--work-dir <owner-work>] attached: the owner's work tree (always a child)
5148
5203
  [--branch <b>] [--base <ref>] worktree branch and starting ref;
@@ -5159,6 +5214,8 @@ Usage:
5159
5214
  [--model <id>|@native-default] override the selected model; @native-default
5160
5215
  selects the harness's own model default
5161
5216
  [--backend tmux] [--yolo|--no-yolo] session backend and launch permission option
5217
+ [--background|--no-background] list the instance under Background (presentation
5218
+ only); default: the soul's background:, else no
5162
5219
  [--no-launch] [--json] scaffold without launching; JSON result envelope
5163
5220
  [--allow-child-spawns|--no-child-spawns] this instance's child-spawn policy (default:
5164
5221
  allowed); enforced by OATS, not an OS sandbox
@@ -5323,6 +5380,13 @@ Usage:
5323
5380
  oats instance color <instance> (<color> | --clear) [--home <abs>] [--json]
5324
5381
  the instance's colour, presentation only: sand,
5325
5382
  sage, slate, mauve, clay or olive; --clear removes it
5383
+ oats instance background <instance> on|off [--home <abs>] [--json]
5384
+ whether clients list the instance under
5385
+ Background, presentation only
5386
+ oats instance same-work <instance> on|off [--home <abs>] [--json]
5387
+ record that this instance does the same work as
5388
+ its parent (on needs a recorded parent); clients
5389
+ draw the parent line for it; off removes it
5326
5390
  oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi]
5327
5391
  [--model <m>] [--launch-config <n>] [--dir <d>] [--json]
5328
5392
  a name for a spawn of <soul> (only a name: it gives
@@ -274,8 +274,9 @@ A self-contained package has an `oats.json`:
274
274
  `.a*`);
275
275
  - an exact name that is `.oats`, `.agents` or `.claude`, or that starts
276
276
  with `.oats-events`, `.oats-stop`, `.oats-restart`, `.oats-rollback`,
277
- `.oats-agents-md`, `.oats-start`, `.oats-attachments` or `.oats-color`: the top-level
278
- entries the kernel itself writes in an instance home;
277
+ `.oats-agents-md`, `.oats-start`, `.oats-attachments`, `.oats-color`,
278
+ `.oats-background` or `.oats-same-work`: the top-level entries the kernel
279
+ itself writes in an instance home;
279
280
  - a prefix that starts with `.oats-`.
280
281
 
281
282
  An exact name such as `.oats-aweb` is allowed: it is a provider's
@@ -473,8 +474,23 @@ Every spawned instance gets a **full copy** of each capability its soul
473
474
  resolved to, under `<home>/.oats/modules/<capability>/` (manifest, `bin/`,
474
475
  injects, skills), and those skills flat under `<home>/.agents/skills/<skill>/`
475
476
  beside the soul's own, one level deep where harnesses discover them. Its generated `AGENTS.md` is the
476
- soul's `AGENTS.md`, the kernel and work-mode blocks, then each module's inject
477
- in name order. Two composed skills with one name fail the spawn
477
+ soul's `AGENTS.md`, then each module's inject, then the kernel's instance-boundary
478
+ and work-mode blocks, last. The injects take the order the soul and the workspace
479
+ give them: first the capabilities the soul lists, in its `capabilities:` order (a
480
+ soul entry that re-lists a workspace default sits at the soul's place), then the
481
+ workspace defaults the soul does not list, in the order the workspace's
482
+ `defaults:` lists them (slot defaults and `defaults.capabilities` entries as they
483
+ appear in the file). A standalone soul has no workspace defaults; the kernel's
484
+ own `oats.core` default, which it gets unless it names `oats.core`, comes after
485
+ the capabilities it lists, as any default does. A capability name made only of
486
+ digits (`"123"`) is the one exception to the listing order: it comes first in its
487
+ list, ahead of the names written before it, because the parsed list puts
488
+ integer-like keys first. A capability
489
+ with no inject adds nothing, and one the soul turns `off` or a slot `none` drops
490
+ is not composed. Only the instructions take this order: modules, skills and hooks
491
+ stay in name order, and reordering a soul's list is not a composition change (no
492
+ drift). `oats instance upgrade` keeps the order a home recorded and puts the
493
+ kernel's blocks last. Two composed skills with one name fail the spawn
478
494
  (`E_SKILL_DUPLICATE`). The harness then starts normally, with its own skill
479
495
  discovery; the details are in [souls-and-instances.md](souls-and-instances.md).
480
496
  Change a capability's inject or skills in its repository, then spawn a new
@@ -1058,7 +1074,10 @@ question, a decision, an approval, a credential, any input it waits on), it runs
1058
1074
  `oats instance attention --message "<one line>"` from its home and ends its
1059
1075
  turn. Once it has the answer, it runs `oats instance attention --clear`. The
1060
1076
  claim belongs to producer `agent`. Only `--clear` or the next session start,
1061
- restart or stop clears it. The message is one line of at most 200
1077
+ restart or stop clears it. An instance whose human talks to its parent rather
1078
+ than to it sends the question to its parent instead; the parent sets its own
1079
+ claim naming the child and relays the answer. A claim is never set for
1080
+ another home. The message is one line of at most 200
1062
1081
  characters; control characters, the Unicode line and paragraph separators,
1063
1082
  bidi controls (U+202A–202E, U+2066–2069), U+200B, U+2060, U+FEFF and tag
1064
1083
  characters (U+E0000–E007F) are refused, and everything else (emoji ZWJ
@@ -366,7 +366,7 @@
366
366
  "description": "Home entries the kernel owns cannot be declared.",
367
367
  "anyOf": [
368
368
  {"pattern": "^\\.(?:oats|agents|claude)$"},
369
- {"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color)"},
369
+ {"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color|background|same-work)"},
370
370
  {"pattern": "^\\.oats-.*\\*$"}
371
371
  ]
372
372
  }
@@ -258,13 +258,15 @@ delivers; what a provider consumes is its own contract. Teams reach providers as
258
258
  from: { kind: "member", repoKey, commit }
259
259
  | { kind: "package", package, version, commit, integrity, repoKey } }],
260
260
  slots, skills, injects, payloads, payloadOrigins,
261
- teams, defaultTeam, slotsFrom, capabilitiesFrom, turnedOff, declRevision, payloadRevision, revision }
261
+ teams, defaultTeam, slotsFrom, capabilitiesFrom, instructionOrder, turnedOff, declRevision, payloadRevision, revision }
262
262
  ```
263
263
 
264
264
  `module.dir` is the listed capability directory (for a package, the `oats-package.json#capabilities[]`
265
265
  entry). `declRevision` covers `{ resolutionApi, soul, modules, slots, skills, injects }`,
266
266
  `payloadRevision` the payloads, `revision` both (24 hex of SHA-256 over canonical JSON). A spawn decision
267
- binds `revision`. Provenance fields enter neither revision.
267
+ binds `revision`. Provenance fields enter neither revision. `instructionOrder` is one: the module names
268
+ in the order their injects take in the composed `AGENTS.md` (the soul's `capabilities:` order, then the
269
+ workspace defaults it does not list, in `defaults:` file order).
268
270
 
269
271
  ---
270
272
 
@@ -316,8 +318,8 @@ shims that throw `E_REMOVED { name, contract }`, pointing at this record.
316
318
  2. The copy's digest must equal the fetch's and any `module.digest` (`E_MATERIALIZE_INTEGRITY`).
317
319
  3. Copy skills whole to `<home>/.agents/skills/<skill>/`, flat (0.30.2; the grouped
318
320
  `<name>/<skill>/` layout this section first specified hid every skill from the harnesses).
319
- 4. Compose `<home>/AGENTS.md` = soul body (`options.soulAgentsMd` or `soulDir`) + kernel blocks + module
320
- injects; operating guidance comes from a module such as `oats.core`. Keep `CLAUDE.md → AGENTS.md`
321
+ 4. Compose `<home>/AGENTS.md` = soul body (`options.soulAgentsMd` or `soulDir`) + module injects in
322
+ `instructionOrder` + kernel blocks (`options.blocks`); operating guidance comes from a module such as `oats.core`. Keep `CLAUDE.md → AGENTS.md`
321
323
  and `.claude/skills → ../.agents/skills`.
322
324
  5. Record `modules: { <name>: { from, commit, digest, materializedAt } }`, `providers` (the payloads) and
323
325
  `resolutionRevision` in `instance.json`.
@@ -78,7 +78,7 @@ Apply runs under the claim, with the plan revision re-checked. A stale plan refu
78
78
 
79
79
  1. **Stage.** Stage the new module copies in `<home>/.oats/.staging-upgrade-<receipt>`, on the same filesystem so the renames are atomic, and recompose the derived files there. Use the **same code as spawn**: refactor `materialize()` so that composing a home from a resolution can target an existing home. Do not write a second composer. The derived files are:
80
80
  - `.agents/skills`;
81
- - `AGENTS.md`: the soul body at the **recorded soul commit**, the kernel blocks, then each module's inject. If the soul body at that commit can't be read, refuse;
81
+ - `AGENTS.md`: the soul body at the **recorded soul commit**, each module's inject in the order the home's `instructions` recorded (a module with no recorded block after them, by name), then the kernel blocks. If the soul body at that commit can't be read, refuse;
82
82
  - in `instance.json`: `modules`, `capabilities[]`, `capabilityRuntime[]` (the absolute hook commands that retire runs), `skills[]`, `instructions[]`, `composition`, `launch.hooks.contributions`, `resolutionRevision`.
83
83
  Read the soul body through discovery's path rule at that recorded commit:
84
84
  a member soul uses `souls/<agent>/AGENTS.md`; a package soul uses its