@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
@@ -0,0 +1,67 @@
1
+ /** The "same work" flag (feature instance-same-work, awebai/oats#1577): a child instance's declared
2
+ * "same work as my parent", which clients draw as the parent→child line. A home file of its own,
3
+ * `<home>/.oats-same-work.json`, so that a start, restart, stop or resume, which rewrite instance.json,
4
+ * never lose it; only `oats instance same-work … off` or retirement removes it.
5
+ *
6
+ * The flag is BOUND to the parent it was set against: the record names that parent, and the flag is on
7
+ * only while it is still the home's recorded `parentInstance` (sameWorkOf, the one rule). A reparent (a
8
+ * retire's relink, a `--relation parent` spawn re-pointing its anchor) leaves the record bound to the
9
+ * old name, so the flag reads off and nothing errors.
10
+ *
11
+ * The record is `{ sameWorkApi: 1, parent, at }`, written atomically (writeThroughPrivateFile) at mode
12
+ * 0600; present means on. A reader takes a regular file only, without following a link, up to
13
+ * RECORD_MAX bytes: anything that is not a valid record reads as no binding (null), never an error.
14
+ * Dependency-free: the status rows, spawn and the command all go through here. */
15
+ import { lstatSync, rmSync } from "node:fs";
16
+ import { join } from "node:path";
17
+ import { readFileHead } from "./bounded-read.mjs";
18
+ import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
19
+
20
+ /** The record's own version. */
21
+ export const SAME_WORK_API = 1;
22
+ /** The home file, kernel-owned: in KERNEL_HOME_NAME_PREFIXES (lib/capability-contract.mjs), the retire
23
+ * fingerprint's receipts (lib/core.mjs KERNEL_HOME_RECEIPTS) and the manifest schema. */
24
+ export const SAME_WORK_FILE = ".oats-same-work.json";
25
+ /** A record larger than this is not one. */
26
+ export const RECORD_MAX = 4096;
27
+
28
+ /** The parent `home`'s record is bound to, or null: no file, not a regular file (a link is never
29
+ * followed), over RECORD_MAX bytes, unreadable, not JSON, another sameWorkApi or no non-empty string
30
+ * `parent`. Never throws. */
31
+ export function readSameWork(home) {
32
+ try {
33
+ const { bytes, size } = readFileHead(join(home, SAME_WORK_FILE), RECORD_MAX + 1);
34
+ if (size > RECORD_MAX) return null;
35
+ const record = JSON.parse(bytes.toString("utf8"));
36
+ if (!record || typeof record !== "object" || Array.isArray(record) || record.sameWorkApi !== SAME_WORK_API) return null;
37
+ return typeof record.parent === "string" && record.parent !== "" ? record.parent : null;
38
+ } catch { return null; }
39
+ }
40
+
41
+ /** Bind `home`'s flag to `parent` (an instance name), or remove the record when `parent` is null.
42
+ * → `{ changed }`. A record already bound to `parent` is no change: nothing is written. One bound to
43
+ * another (old) parent is rewritten to this one. A removal takes whatever stands at the name (an
44
+ * unreadable file, a link, a directory) and is a change only when a valid record was there. The caller
45
+ * decided `parent` (the home's recorded parentInstance) and holds the right to change the home. */
46
+ export function writeSameWork(home, parent, { now = () => new Date() } = {}) {
47
+ if (parent !== null && (typeof parent !== "string" || parent === "")) throw new TypeError("writeSameWork: parent is an instance name or null");
48
+ const path = join(home, SAME_WORK_FILE);
49
+ const before = readSameWork(home);
50
+ if (parent !== null && before === parent) return { changed: false };
51
+ let present;
52
+ try { present = lstatSync(path); } catch (e) { if (e?.code !== "ENOENT") throw e; }
53
+ // A directory at the name is no record, and a rename cannot replace it: it goes first. A link or a
54
+ // file is replaced by the rename itself, or removed here when the flag is cleared.
55
+ if (present && (parent === null || present.isDirectory())) rmSync(path, { recursive: true, force: true });
56
+ if (parent === null) return { changed: before !== null };
57
+ const bytes = JSON.stringify({ sameWorkApi: SAME_WORK_API, parent, at: now().toISOString() }) + "\n";
58
+ writeThroughPrivateFile(path, `${path}.tmp-${process.pid}`, bytes, 0o600);
59
+ return { changed: true };
60
+ }
61
+
62
+ /** THE rule: whether `home` does the same work as its parent, read against the row's current
63
+ * `parentInstance` (a non-empty string, else false): true only when the record is bound to exactly it. */
64
+ export function sameWorkOf(home, parentInstance) {
65
+ if (typeof parentInstance !== "string" || parentInstance === "") return false;
66
+ return readSameWork(home) === parentInstance;
67
+ }
@@ -38,6 +38,7 @@ import {
38
38
  retirementHomeChanged,
39
39
  rebaseUpgradeRetirementBaseline,
40
40
  planInstanceResources,
41
+ orderInstructionBlocks,
41
42
  findRetirementBaseline,
42
43
  officialPackageCatalog,
43
44
  } from "./core.mjs";
@@ -639,6 +640,7 @@ async function prepare(ctx, root, name, opts, { own = false } = {}) {
639
640
  const resolution = {
640
641
  resolutionApi: 1,
641
642
  modules,
643
+ instructionOrder: recordedInstructionOrder(meta, modules),
642
644
  payloads: meta.providers || {},
643
645
  payloadOrigins: Object.fromEntries(
644
646
  (meta.capabilityRuntime || []).map((c) => [
@@ -855,6 +857,7 @@ function derivedMetadata(p, tx, receipt) {
855
857
  path: block.file,
856
858
  materialized: true,
857
859
  });
860
+ orderInstructionBlocks(expected, outcome.blocks);
858
861
  const composition = {
859
862
  ...meta.composition,
860
863
  expected: expected.map((r) => ({
@@ -945,6 +948,21 @@ function derivedMetadata(p, tx, receipt) {
945
948
  resolutionRevision: resolution.revision,
946
949
  };
947
950
  }
951
+ /** The home's capability-block order, from the `instructions` it recorded (its AGENTS.md as
952
+ * spawned or last upgraded); a module with no recorded block follows, by name. An upgrade
953
+ * keeps that order, and the kernel's blocks close the recomposed AGENTS.md. */
954
+ function recordedInstructionOrder(meta, modules) {
955
+ const names = modules.map((m) => m.name),
956
+ order = [];
957
+ for (const row of Array.isArray(meta.instructions) ? meta.instructions : []) {
958
+ const name =
959
+ typeof row?.source === "string" && row.source.startsWith("capability:")
960
+ ? row.source.slice("capability:".length)
961
+ : null;
962
+ if (name && names.includes(name) && !order.includes(name)) order.push(name);
963
+ }
964
+ return [...order, ...names.filter((n) => !order.includes(n)).sort()];
965
+ }
948
966
  function keepPrevious(home, receipt, meta) {
949
967
  const root = join(home, ".oats/previous");
950
968
  if (existsSync(root)) realDir(root);
@@ -107,6 +107,15 @@ function assertResolution(resolution) {
107
107
  if (resolution.skills !== undefined && !Array.isArray(resolution.skills)) throw bad("/skills", "must be an array when present");
108
108
  if (resolution.injects !== undefined && !Array.isArray(resolution.injects)) throw bad("/injects", "must be an array when present");
109
109
  if (resolution.payloads !== undefined && !plainObject(resolution.payloads)) throw bad("/payloads", "must be an object when present");
110
+ if (resolution.instructionOrder !== undefined) {
111
+ if (!Array.isArray(resolution.instructionOrder)) throw bad("/instructionOrder", "must be an array of module names when present");
112
+ const listed = new Set();
113
+ resolution.instructionOrder.forEach((name, i) => {
114
+ if (!seen.has(name)) throw bad(`/instructionOrder/${i}`, `names no module (found ${JSON.stringify(name)})`);
115
+ if (listed.has(name)) throw bad(`/instructionOrder/${i}`, `lists module ${JSON.stringify(name)} twice`);
116
+ listed.add(name);
117
+ });
118
+ }
110
119
  return resolution;
111
120
  }
112
121
 
@@ -317,6 +326,14 @@ function moduleInjects(resolution, module, moduleDir) {
317
326
  return rels;
318
327
  }
319
328
 
329
+ /** Capability blocks (`capability:<module>`, built in module order) in `resolution.instructionOrder`;
330
+ * a module the order does not list keeps its place after the listed ones. Stable within a module. */
331
+ function instructionOrdered(resolution, blocks) {
332
+ const order = Array.isArray(resolution.instructionOrder) ? resolution.instructionOrder : [];
333
+ const rank = (b) => { const i = order.indexOf(b.source.slice("capability:".length)); return i < 0 ? order.length : i; };
334
+ return blocks.map((b, i) => ({ b, i, r: rank(b) })).sort((x, y) => x.r - y.r || x.i - y.i).map(({ b }) => b);
335
+ }
336
+
320
337
  /* ───────────────────────────── home ─────────────────────────────── */
321
338
 
322
339
  function assertHome(home) {
@@ -371,10 +388,14 @@ function ensureOatsDir(home) {
371
388
  * lock oats-lock.json v3 object: package repo/path/commit for from.kind === "package"
372
389
  * catalog { <id>: { url, ref, path } } for lock entries whose source is "catalog:<id>"
373
390
  * soulAgentsMd the soul's canonical AGENTS.md text (else read from options.soulDir)
374
- * blocks pre-rendered blocks [{ source, file, content }] placed BEFORE the capability injects
391
+ * blocks pre-rendered blocks [{ source, file, content }] placed AFTER the capability injects
375
392
  * (the kernel's own kernel:… and work-mode:… blocks, composed by core.mjs)
376
393
  * now() ISO timestamp source (tests)
377
394
  *
395
+ * The AGENTS.md is the soul's body, then each module's inject in `resolution.instructionOrder`
396
+ * (the soul's listing, then the workspace defaults' order; a module the order omits follows, in
397
+ * module order), then `blocks`. `outcome.blocks` lists every block in that written order.
398
+ *
378
399
  * stageMaterialize adds `replace` (complete roots), `staging` (explicit scratch
379
400
  * directory), `existingModules` (name → frozen source path), and `instanceJson`
380
401
  * (derived metadata transform). Its commit({preserveOnFailure:true}) retains
@@ -544,7 +565,7 @@ export async function stageMaterialize(resolution, home, options = {}) {
544
565
  moduleRows.push({ name: module.name, from, commit: source.commit, digest, files: fetched.files ?? null, bytes: fetched.bytes ?? null, path: finalModule, materializedAt: at });
545
566
  }
546
567
 
547
- const blocks = [...(Array.isArray(options.blocks) ? options.blocks : []), ...capabilityBlocks];
568
+ const blocks = [...instructionOrdered(resolution, capabilityBlocks), ...(Array.isArray(options.blocks) ? options.blocks : [])];
548
569
  for (const b of blocks) {
549
570
  if (!plainObject(b) || typeof b.source !== "string" || typeof b.file !== "string" || typeof b.content !== "string") {
550
571
  throw fail("E_MATERIALIZE_RESOLUTION", "options.blocks entries must be { source, file, content } strings", { block: b });
package/lib/resolve.mjs CHANGED
@@ -367,6 +367,30 @@ export function composeCapabilities(workspace, soulDefinition, { offs = null } =
367
367
  return [...map.values()].sort((a, b) => byCodepoint(a.name, b.name));
368
368
  }
369
369
 
370
+ /**
371
+ * The order a soul's capability instructions take in its composed AGENTS.md: the capabilities the soul
372
+ * lists, in its `capabilities:` order, then the workspace defaults it does not list, in the order the
373
+ * workspace's `defaults:` lists them (slot defaults and `defaults.capabilities` entries as they appear in
374
+ * the file). Each capability sits where the entry that composed it (its `via`) lists it, so a soul entry
375
+ * that re-lists a default sits at the soul's position. A name made only of digits comes first in its map
376
+ * (JavaScript orders integer-like keys first): a documented quirk. `declared` is composeCapabilities' output,
377
+ * over the same workspace and soul definition. → [name], every declared name once.
378
+ */
379
+ export function instructionOrder(workspace, soulDefinition, declared) {
380
+ const viaOf = new Map(declared.map((d) => [d.name, d.via]));
381
+ const order = [];
382
+ const take = (entries, via) => {
383
+ for (const name of Object.keys(isObject(entries) ? entries : {})) if (viaOf.get(name) === via && !order.includes(name)) order.push(name);
384
+ };
385
+ take(soulDefinition?.capabilities, "soul");
386
+ const defaults = isObject(workspace?.defaults) ? workspace.defaults : {};
387
+ for (const key of Object.keys(defaults)) {
388
+ if (key === "capabilities") take(defaults.capabilities, "defaults.capabilities");
389
+ else if (SLOTS.includes(key)) take(defaults[key], `defaults.${key}`);
390
+ }
391
+ return order;
392
+ }
393
+
370
394
  /* ───────────────────────────── lookups ────────────────────────────────── */
371
395
 
372
396
  /** A discovery's member row by key (the first with that key; lib/workspace.mjs memberRowByKey). */
@@ -603,7 +627,7 @@ export function lockedCapability(name, id, entry, capabilities, details = { capa
603
627
  * options: { local, lock, spawn = { providers? }, catalog, remote, remoteOptions }
604
628
  * `catalog` (package-catalog.json shape) tells which repo a `catalog:<id>` lock entry is read from.
605
629
  *
606
- * → Resolution { resolutionApi: 1, soul, modules[], slots, payloads, payloadOrigins, skills[], injects[], revision } — deep-frozen.
630
+ * → Resolution { resolutionApi: 1, soul, modules[], slots, payloads, payloadOrigins, skills[], injects[], instructionOrder[], revision } — deep-frozen.
607
631
  * Extra fields beyond the contract (recorded for materialize): module.dir (capability dir, repo-relative)
608
632
  * and from.repoKey on package modules.
609
633
  */
@@ -627,9 +651,9 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
627
651
  // What the soul turned off (feature desktop-facts): its own `off` over a lower layer, and a `<slot>: none`
628
652
  // that dropped a workspace default below. Provenance, like slotsFrom.
629
653
  const offs = [];
630
- const declared = discovery?.standalone === true
631
- ? composeCapabilities(null, { ...definition, capabilities: soulEntry.capabilities ?? definition.capabilities }, { offs })
632
- : composeCapabilities(workspace, definition, { offs });
654
+ const composedWorkspace = discovery?.standalone === true ? null : workspace;
655
+ const composedSoul = discovery?.standalone === true ? { ...definition, capabilities: soulEntry.capabilities ?? definition.capabilities } : definition;
656
+ const declared = composeCapabilities(composedWorkspace, composedSoul, { offs });
633
657
  const turnedOff = offs;
634
658
 
635
659
  const modules = [];
@@ -816,8 +840,11 @@ export async function resolveSoul(discovery, soulEntry, { local = null, lock = n
816
840
  // `capabilitiesFrom` (the same per composed capability) and `turnedOff` (feature desktop-facts).
817
841
  const teams = reportRows(soulTeamsHere.teams), defaultTeam = soulTeamsHere.defaultTeam;
818
842
  const capabilitiesFrom = Object.fromEntries(modules.map((m) => [m.name, fromOfVia(viaOf.get(m.name))]));
843
+ // `instructionOrder` (the order the modules' injects take in the composed AGENTS.md: the soul's listing,
844
+ // then the workspace defaults' file order) is provenance too: reordering a soul's list is no composition change.
845
+ const order = instructionOrder(composedWorkspace, composedSoul, declared).filter((name) => moduleNames.has(name));
819
846
  turnedOff.sort((a, b) => byCodepoint(a.name, b.name));
820
- return deepFreeze({ ...decl, payloads, payloadOrigins: origins, teams, defaultTeam, slotsFrom, capabilitiesFrom, turnedOff, declRevision, payloadRevision, revision });
847
+ return deepFreeze({ ...decl, payloads, payloadOrigins: origins, teams, defaultTeam, slotsFrom, capabilitiesFrom, instructionOrder: order, turnedOff, declRevision, payloadRevision, revision });
821
848
  }
822
849
 
823
850
  /** Where a composed capability came from, as the Desktop names it (`layers.<layer>.from`): the soul's own
package/lib/servers.mjs CHANGED
@@ -675,6 +675,11 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
675
675
  if (oatsArgs.includes("--suggest-name")) requireRemoteFeature(remote, target, preview ? "spawn-suggest-name" : "spawn-apply-suggest-name");
676
676
  // An exact name is the host's to take: a host without spawn-name would refuse the flag, or worse.
677
677
  if (oatsArgs.includes("--name")) requireRemoteFeature(remote, target, "spawn-name");
678
+ // Feature instance-background: an older host would refuse the flag as unknown, or place the instance
679
+ // in the main list; either is said here, before anything is sent.
680
+ if (oatsArgs.includes("--background") || oatsArgs.includes("--no-background")) requireRemoteFeature(remote, target, "instance-background");
681
+ // A host without instance-same-work would refuse the flag as unknown: it is never sent there.
682
+ if (oatsArgs.includes("--same-work")) requireRemoteFeature(remote, target, "instance-same-work");
678
683
  const { envelope, stderr } = runRemote(target, json(withScope(["spawn", ...hostHarnessArgs(remote, oatsArgs)])), io);
679
684
  if (preview && envelope.ok && envelope.result?.preview === true && envelope.result.spawnPreviewApi === 2) {
680
685
  // The host's preview with the two fields a routed spawn adds; never a
@@ -819,6 +824,10 @@ const HOST_SURFACES = {
819
824
  "retire plan": { feature: "lifecycle-plans", api: "lifecycleApi", version: 1 },
820
825
  // Feature instance-color: the feature alone (its answer's instanceColorApi is not a probe key).
821
826
  "instance color": { feature: "instance-color" },
827
+ // Feature instance-background: the same (its answer's instanceBackgroundApi is not a probe key).
828
+ "instance background": { feature: "instance-background" },
829
+ // Feature instance-same-work: the feature alone, as instance color.
830
+ "instance same-work": { feature: "instance-same-work" },
822
831
  };
823
832
 
824
833
  function requireSurface(remote, target, surface) {
@@ -827,7 +836,7 @@ function requireSurface(remote, target, surface) {
827
836
  }
828
837
  }
829
838
 
830
- /** `readiness`, `instance events|git|diff|stop|color` and `retire --plan` on the
839
+ /** `readiness`, `instance events|git|diff|stop|color|background|same-work` and `retire --plan` on the
831
840
  * host: the instance is addressed as every routed session command addresses
832
841
  * it (its name through a saved route or the host's roster, or an exact
833
842
  * --home), the scope is an explicit --dir on the host or the registered
@@ -836,7 +845,7 @@ function requireSurface(remote, target, surface) {
836
845
  function routeHostSurface(serverId, cmd, oatsArgs, io) {
837
846
  const key = cmd === "instance" ? `instance ${oatsArgs[0]}` : cmd === "retire" ? "retire plan" : cmd;
838
847
  const surface = HOST_SURFACES[key];
839
- if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff, stop and color only (not ${key})`);
848
+ if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff, stop, color, background and same-work only (not ${key})`);
840
849
  const args = [...oatsArgs];
841
850
  const valueOf = (flag) => { const i = args.indexOf(flag); return i >= 0 && args[i + 1] !== undefined && !args[i + 1].startsWith("--") ? args[i + 1] : undefined; };
842
851
  const name = cmd === "readiness" ? undefined : args[cmd === "instance" ? 1 : 0];
@@ -891,13 +900,19 @@ const rowFacts = (i = {}) => Object.fromEntries(REMOTE_ROW_FACTS.map((k) => [k,
891
900
  * omits it, and absent ("not reported") must stay distinct from null ("no claim"). The
892
901
  * value passes the kernel's own read rule again; anything it refuses is null. */
893
902
  const rowWaiting = (i) => (Object.hasOwn(i, "waitingOnYou") ? { waitingOnYou: readWaitingClaim(i.waitingOnYou) } : {});
894
- /** `retire` (feature status-retire-state) the same way, relayed ONLY when the host's row has the
903
+ /** `background` (feature instance-background) only as `true`, relayed ONLY when the host's row says exactly
904
+ * that: absent is the only reading of "not background", so any other value is dropped, never false. */
905
+ const rowBackground = (i) => (i.background === true ? { background: true } : {});
906
+ /** `retire` (feature status-retire-state) as `waitingOnYou` is, relayed ONLY when the host's row has the
895
907
  * key: a host whose kernel predates the feature omits it, and its rows say nothing. Absent is the
896
908
  * only reading of "no retire", so a value the kernel's own read refuses is dropped, never null. */
897
909
  const rowRetire = (i) => {
898
910
  const retire = Object.hasOwn(i, "retire") ? readRetireState(i.retire) : undefined;
899
911
  return retire ? { retire } : {};
900
912
  };
913
+ /** `sameWork` (feature instance-same-work) as `background`: relayed ONLY when the host's row says
914
+ * `sameWork: true`, the one value a row carries; anything else, and a host that omits it, is absent. */
915
+ const rowSameWork = (i) => (i.sameWork === true ? { sameWork: true } : {});
901
916
 
902
917
  /** The bounds a host's `features` list must meet to be relayed (feature server-probe-features). */
903
918
  export const HOST_FEATURES_MAX = 256;
@@ -1000,7 +1015,7 @@ export async function rosterGroups({ server, workspaceKeys, io = {} } = {}) {
1000
1015
  harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null,
1001
1016
  ...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
1002
1017
  running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
1003
- ...rowFacts(i), ...rowWaiting(i), ...rowRetire(i),
1018
+ ...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowSameWork(i),
1004
1019
  // Every row the host reports is addressed by its home, saved
1005
1020
  // route or not; savedRoute says only that it was spawned from here.
1006
1021
  retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, addressable: true, missingRemotely: false,
@@ -26,6 +26,7 @@ export const ROW_REASON = Object.freeze({
26
26
  UNKNOWN: "unknown", START_BUSY: "start-busy", NOT_LOST: "not-lost", NOT_SEEN_RECENTLY: "not-seen-recently",
27
27
  RESUME_CONFIRMATION: RESUME_WAITING.RESUME_CONFIRMATION, LAUNCH_PROMPT: "launch-prompt",
28
28
  START_REFUSED: "start-refused", REFUSED_THIS_BOOT: "refused-this-boot", KEEPS_GETTING_LOST: "keeps-getting-lost",
29
+ LIFECYCLE_BUSY: "lifecycle-busy",
29
30
  });
30
31
 
31
32
  /** `deployments[].reason` of a deployment the sweep did not sweep. */
@@ -35,7 +35,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writ
35
35
  import { join, resolve } from "node:path";
36
36
  import { oatsError } from "./errors.mjs";
37
37
  import { deploymentState, readDeploymentsDocument } from "./deployments.mjs";
38
- import { listInstances, missingLaunchEnvRefs, resumeConversation } from "./core.mjs";
38
+ import { homeClaimHolder, listInstances, missingLaunchEnvRefs, owedRetireSaid, resumeConversation } from "./core.mjs";
39
39
  import { checkStartEnv, fromEnvNames, launchEnvChangedMessage, launchEnvMissingMessage, launchEnvUnverifiedWarning } from "./start-env.mjs";
40
40
  import { FRESH_REASON, NOT_SWEPT, OUTCOME, RESUME_WAITING, ROW_REASON, SESSION_END } from "./session-resume-contract.mjs";
41
41
  import { bootId, homeKey, judgeLosses, readSeen, resumeEligible, resumeStateDir } from "./session-seen.mjs";
@@ -158,11 +158,12 @@ function readDeployment(dir) {
158
158
  return { entry: { deployment: dir, state, swept: true }, rows };
159
159
  }
160
160
 
161
- /** The reasons of the rows a sweep answers without judging the loss, so that a later boot's sweep
162
- * may resume it: none. A loop guard's refusal (`keeps-getting-lost`) judges the loss like any
163
- * refusal, and nothing brings it back automatically, a reboot included (decided for #1567); naming
164
- * it here would let the next boot retry it. */
165
- const NOT_JUDGED = new Set([]);
161
+ /** The reasons of the rows a sweep answers without judging the loss, so that a later sweep may
162
+ * resume it: a home OATS was stopping, upgrading or retiring (`lifecycle-busy`), whose next state
163
+ * is that command's to decide. A loop guard's refusal (`keeps-getting-lost`) judges the loss like
164
+ * any refusal, and nothing brings it back automatically, a reboot included (decided for #1567);
165
+ * naming it here would let the next boot retry it. */
166
+ const NOT_JUDGED = new Set([ROW_REASON.LIFECYCLE_BUSY]);
166
167
  /** The outcomes of a start that launched something: the ones RESUME_LIMIT counts. */
167
168
  const LAUNCHED = new Set([OUTCOME.RESUMED, OUTCOME.FRESH, OUTCOME.BLOCKED]);
168
169
  const base = (row) => ({ deployment: row.deployment, instance: row.instance, home: row.home });
@@ -192,6 +193,9 @@ export function rowFromStart(row, answer) {
192
193
  const message = String(answer?.error?.message ?? "the start gave no answer");
193
194
  if (code === "E_SPAWN_INCOMPLETE") return { ...base(row), outcome: OUTCOME.BLOCKED, reason: ROW_REASON.LAUNCH_PROMPT, code, ...(answer.error.details?.launchPrompts ? { launchPrompts: answer.error.details.launchPrompts } : {}) };
194
195
  if (code === "E_SESSION_START_BUSY") return { ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.START_BUSY, code };
196
+ // The home's lifecycle claim was held, or its retire is owed: whatever OATS is doing decides the
197
+ // home's next state. Not a refusal: none is noted, judged or counted against the loop guard.
198
+ if (code === "E_INSTANCE_RETIRING" || code === "E_LIFECYCLE_BUSY") return { ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.LIFECYCLE_BUSY, code, message };
195
199
  if (code === "E_RESUME_NOT_LOST" || code === "E_SESSION_RUNNING") return { ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.NOT_LOST, code };
196
200
  if (code === "E_SESSION_UNKNOWN") return { ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.UNKNOWN, code, message };
197
201
  return { ...base(row), outcome: OUTCOME.REFUSED, reason: ROW_REASON.START_REFUSED, code, message };
@@ -242,7 +246,9 @@ export async function resumeSessions({ deployment, plan = false, kernel, env = p
242
246
  for (const row of found ?? []) {
243
247
  if (row.running === true) rows.push({ ...base(row), outcome: OUTCOME.ALREADY_RUNNING });
244
248
  else if (row.running === null) rows.push({ ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.UNKNOWN });
245
- else if (row.sessionEnd === SESSION_END.LOST) candidates.push(row);
249
+ // A launched home that is owed a self-retire reads no sessionEnd (its marker withholds it):
250
+ // it is listed as the lost ones are, so that the sweep says it is skipped (lifecycleBusy).
251
+ else if (row.sessionEnd === SESSION_END.LOST || (row.retirePending && row.launched === true && row.running === false)) candidates.push(row);
246
252
  }
247
253
  }
248
254
  const note = readBootNote(boot), now = Date.now();
@@ -250,11 +256,16 @@ export async function resumeSessions({ deployment, plan = false, kernel, env = p
250
256
  // Precedence, the first that applies: not seen recently, refused this boot, keeps getting lost,
251
257
  // started. The record and the note name a home by its real path (homeKey), whatever spelling the
252
258
  // sweep was given; a row shows the path it listed.
259
+ // A home OATS is stopping, upgrading or retiring, or whose retire is owed, comes first: nothing
260
+ // is started there. This read is only a filter (the sweep is not atomic with it): the start's
261
+ // own claim is what keeps a resume off such a home (lib/core.mjs startInstanceSession).
253
262
  for (const row of candidates) {
254
263
  const startId = row.startId ?? null, key = homeKey(row.home);
255
264
  const prior = note.refused.find((r) => r.home === key && (r.startId ?? null) === startId);
256
265
  const fit = resumeEligible(seen.get(key), row, { now });
257
- if (!fit.eligible) rows.push({ ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.NOT_SEEN_RECENTLY, message: `${row.instance} is not resumed automatically: ${fit.why}; start it by hand (oats session start --resume --home ${row.home}) if it should run` });
266
+ const busy = lifecycleBusy(row);
267
+ if (busy) rows.push({ ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.LIFECYCLE_BUSY, message: busy });
268
+ else if (!fit.eligible) rows.push({ ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.NOT_SEEN_RECENTLY, message: `${row.instance} is not resumed automatically: ${fit.why}; start it by hand (oats session start --resume --home ${row.home}) if it should run` });
258
269
  else if (prior) rows.push({ ...base(row), outcome: OUTCOME.REFUSED, reason: ROW_REASON.REFUSED_THIS_BOOT, code: prior.code, message: prior.message });
259
270
  else if ((note.resumes[key] ?? 0) >= RESUME_LIMIT) rows.push({ ...base(row), outcome: OUTCOME.REFUSED, reason: ROW_REASON.KEEPS_GETTING_LOST, message: `${row.instance} was resumed ${note.resumes[key]} times in this boot and was lost again each time; no sweep starts this loss again: start it by hand (oats session start --resume --home ${row.home})` });
260
271
  else if (plan) rows.push(predicted(row, env));
@@ -269,7 +280,11 @@ export async function resumeSessions({ deployment, plan = false, kernel, env = p
269
280
  const started = (await inBatches(toStart, RESUME_CONCURRENCY, async (row) => {
270
281
  const answer = await start(row);
271
282
  for (const w of hostWarnings(answer)) hostWide.add(w);
272
- const answered = rowFromStart(row, answer), key = homeKey(row.home);
283
+ // A home removed between the read and its start (a retire finished in between) is not lost:
284
+ // whatever its start answered.
285
+ const gone = answer?.ok !== true && !existsSync(row.home);
286
+ const answered = gone ? { ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.NOT_LOST, ...(typeof answer?.error?.code === "string" ? { code: answer.error.code } : {}) } : rowFromStart(row, answer);
287
+ const key = homeKey(row.home);
273
288
  try {
274
289
  noteSweep({
275
290
  refusals: answered.outcome === OUTCOME.REFUSED ? [{ home: key, startId: row.startId ?? null, code: answered.code, message: answered.message, at: new Date().toISOString() }] : [],
@@ -292,6 +307,18 @@ export async function resumeSessions({ deployment, plan = false, kernel, env = p
292
307
  } finally { release?.(); }
293
308
  }
294
309
 
310
+ /** Why a lost home's status row says OATS is stopping, upgrading or retiring it, or that its
311
+ * retire is owed, as one line; null when it says none of that. Read only: the row's `retire` (any
312
+ * value: running, unknown, failed, interrupted) or `retirePending`, then the holder of the home's lifecycle claim,
313
+ * alive or of a liveness that cannot be read (homeClaimHolder). A holder that is gone is not one:
314
+ * the start takes its claim over. */
315
+ function lifecycleBusy(row) {
316
+ if (row.retire || row.retirePending) return owedRetireSaid(row.instance, row.retire?.state ?? "unknown");
317
+ const held = homeClaimHolder(row.home);
318
+ if (!held || held.state === "gone") return null;
319
+ return `${row.instance} is held by ${held.state === "alive" ? "a" : "what may still be a"} ${held.action} (${held.lock}); that command decides what the home is next`;
320
+ }
321
+
295
322
  /** `--plan`'s prediction for a lost home, from what its start would check, read only: refused for a
296
323
  * home with no recipe, a reference not set in `env` (the environment each start gets) or one whose
297
324
  * value changed since the start it would bring back (lib/start-env.mjs, the start's own check), else
@@ -3,10 +3,11 @@
3
3
  *
4
4
  * It runs spawn's own two halves: the kernel half (composeInstanceAgentsMd: the soul's
5
5
  * AGENTS.md, the instance-boundary and work-mode blocks) and materialize (each capability's
6
- * inject), into a scratch home OUTSIDE the deployment that is removed before it returns (and
7
- * at exit). Nothing in the deployment is written. Capability blocks are reported
8
- * home-relative (`.oats/modules/<cap>/<inject>`, where an instance carries them); kernel
9
- * blocks keep the installed package's absolute path, as spawn writes them.
6
+ * inject, in the resolution's instruction order, before the kernel's blocks), into a scratch
7
+ * home OUTSIDE the deployment that is removed before it returns (and at exit). Nothing in the
8
+ * deployment is written. Capability blocks are reported home-relative
9
+ * (`.oats/modules/<cap>/<inject>`, where an instance carries them); kernel blocks keep the
10
+ * installed package's absolute path, as spawn writes them.
10
11
  *
11
12
  * Single-path guard: the reported text is re-rendered by renderInstructionParts (for the
12
13
  * ranges), so rendering the same parts with the scratch paths must give back, byte for byte,
@@ -66,10 +67,13 @@ export async function composeSoulInstructions({ deployment, prepared, soulDir, c
66
67
  const remove = () => { try { rmSync(scratch, { recursive: true, force: true }); } catch { /* best effort: a temporary copy only */ } };
67
68
  process.once("exit", remove);
68
69
  try {
69
- const outcome = await materialize({ ...prepared, soulAgentsMd: composition.text, soulDir }, scratch);
70
+ const kernelBlocks = composition.blocks.filter((b) => !b.source.startsWith("capability:"));
71
+ const outcome = await materialize({ ...prepared, soulAgentsMd: body, blocks: kernelBlocks, soulDir }, scratch);
70
72
  const written = readFileSync(join(scratch, "AGENTS.md"), "utf8");
71
- const materialized = Array.isArray(outcome?.blocks) ? outcome.blocks : [];
72
- if (renderInstructionParts(body, [...composition.blocks, ...materialized]).text !== written) {
73
+ // The capability blocks materialize reported, in its order; the kernel's blocks close the document.
74
+ const isKernel = (b) => kernelBlocks.some((k) => k.source === b.source && k.file === b.file);
75
+ const materialized = (Array.isArray(outcome?.blocks) ? outcome.blocks : []).filter((b) => !isKernel(b));
76
+ if (renderInstructionParts(body, [...materialized, ...kernelBlocks]).text !== written) {
73
77
  throw fail("E_COMPOSITION_INCOMPLETE", `soul "${soulName}": the instructions materialize wrote are not the kernel's composition plus the capability blocks it reported; nothing is reported in their place`);
74
78
  }
75
79
  const homeRelative = (file) => {
@@ -78,10 +82,9 @@ export async function composeSoulInstructions({ deployment, prepared, soulDir, c
78
82
  return rel.split(sep).join("/");
79
83
  };
80
84
  const capabilityBlocks = materialized.map((b) => ({ source: b.source, file: homeRelative(b.file), content: b.content, materialized: true }));
81
- const blocks = [...composition.blocks, ...capabilityBlocks];
85
+ const blocks = [...capabilityBlocks, ...kernelBlocks];
82
86
  const parts = renderInstructionParts(body, blocks);
83
87
  const length = Math.min(parts.text.length, cap);
84
- const kernelBlocks = composition.blocks.length;
85
88
  const scratchResult = inScratch ? await inScratch({ outcome, scratch }) : undefined;
86
89
  return {
87
90
  text: parts.text, blocks, resolved: composition.resolved, oatsCoreDeclared: composition.oatsCoreDeclared, scratchResult,
@@ -89,7 +92,7 @@ export async function composeSoulInstructions({ deployment, prepared, soulDir, c
89
92
  file: null, text: parts.text.slice(0, length), truncated: parts.text.length > length,
90
93
  resolution: prepared.resolution?.revision ?? null,
91
94
  body: clampSpan(parts.body, length),
92
- sources: parts.blocks.map((span, i) => ({ source: blocks[i].source, file: i < kernelBlocks ? null : blocks[i].file, ...clampSpan(span, length) })),
95
+ sources: parts.blocks.map((span, i) => ({ source: blocks[i].source, file: i < capabilityBlocks.length ? blocks[i].file : null, ...clampSpan(span, length) })),
93
96
  },
94
97
  };
95
98
  } catch (e) {
package/lib/workspace.mjs CHANGED
@@ -964,10 +964,10 @@ export function standaloneRepo(ref, commit, discovery, { remote: injected } = {}
964
964
  // even when the workspace (and its defaults) cannot be read. ANY mention of
965
965
  // oats.core in the soul — `{ from: package }`, `{ from: here }`, `{ from: <repo> }`
966
966
  // or `off` — suppresses the kernel default: the soul's own choice is then judged
967
- // by the loop below exactly like every other capability (S4).
967
+ // by the loop below exactly like every other capability (S4). The default is added
968
+ // after the soul's own entries, so its instructions follow theirs, as any default's do.
968
969
  const kept = {};
969
970
  const declaredCaps = soul.definition.capabilities || {};
970
- if (!Object.hasOwn(declaredCaps, STANDALONE_DEFAULT_CAPABILITY)) kept[STANDALONE_DEFAULT_CAPABILITY] = { from: "package" };
971
971
  for (const [name, choice] of Object.entries(declaredCaps)) {
972
972
  const from = isObject(choice) ? choice.from : null;
973
973
  if (choice === "off") continue;
@@ -983,6 +983,7 @@ export function standaloneRepo(ref, commit, discovery, { remote: injected } = {}
983
983
  problems.push({ code: "E_NOT_A_MEMBER", repoKey: key, path: `${soul.path}/soul.yaml#/capabilities/${pointerKey(name)}`, message: `${show(name)} comes from ${show(from)}, which cannot be confirmed as a member without the workspace` });
984
984
  }
985
985
  }
986
+ if (!Object.hasOwn(declaredCaps, STANDALONE_DEFAULT_CAPABILITY)) kept[STANDALONE_DEFAULT_CAPABILITY] = { from: "package" };
986
987
  return { ...soul, capabilities: kept };
987
988
  });
988
989
  return {
@@ -3,7 +3,7 @@
3
3
  "packages": {
4
4
  "oats.okf": {
5
5
  "url": "https://github.com/awebai/oats-okf.git",
6
- "ref": "v5.3.0",
6
+ "ref": "v5.5.0",
7
7
  "path": "oats-package"
8
8
  },
9
9
  "oats.aweb": {
@@ -48,7 +48,7 @@
48
48
  },
49
49
  "oats.framework": {
50
50
  "url": "https://github.com/awebai/oats.git",
51
- "ref": "oats-framework/v1.15.1",
51
+ "ref": "oats-framework/v1.16.1",
52
52
  "path": "oats-package"
53
53
  }
54
54
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.69.1",
3
+ "version": "0.69.2",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -124,6 +124,11 @@ export function spawnArgv(agent, workspaceDir, taskFile, opts = {}) {
124
124
  if (typeof opts.yolo !== "boolean") throw Object.assign(new Error("yolo must be a boolean"), { code: "E_BAD_ARGS" });
125
125
  argv.push(opts.yolo ? "--yolo" : "--no-yolo");
126
126
  }
127
+ // Run in background (feature instance-background, #1579): the instance's own flag, as the soul's default or not.
128
+ if (opts.background !== undefined) {
129
+ if (typeof opts.background !== "boolean") throw Object.assign(new Error("background must be a boolean"), { code: "E_BAD_ARGS" });
130
+ argv.push(opts.background ? "--background" : "--no-background");
131
+ }
127
132
  if (opts.suggestName) argv.push("--suggest-name");
128
133
  argv.push("--json");
129
134
  return argv;
@@ -648,22 +653,39 @@ export function operationArgs(args) {
648
653
  if (entries.length > 8 || entries.some(([k, v]) => !/^[a-z][a-z0-9-]{0,63}$/.test(k) || typeof v !== 'string' || !v || v.length > 1024 || /[\x00-\x1f\x7f]/.test(v))) return null;
649
654
  return entries.flatMap(([k, v]) => ['--arg', `${k}=${v}`]);
650
655
  }
651
- /** An instance's colour (feature instance-color, awebai/oats#1421 §2): `oats instance color <instance>
652
- * (<color> | --clear) --home <home> (--dir <context> | --server <server>) --json`, addressed as `oats
653
- * instance stop` is (lifecycle-cli.mjs: a routed command never carries --dir). `color` is a palette name
654
- * (soul-colors.mjs SOUL_COLORS) or null to clear; anything else is refused here and nothing runs. A read's
655
- * deadline: 30 s, 45 s routed. The envelope comes back as the kernel printed it; the caller decodes it. */
656
- export async function cliInstanceColor(bin, { instance, home, context, server, color }, io = {}) {
656
+ /** A verb that writes one field of an instance's own record: `oats instance <verb> <instance> <values…> --home <home>
657
+ * (--dir <context> | --server <server>) --json`, addressed as `oats instance stop` is (lifecycle-cli.mjs: a routed
658
+ * command never carries --dir). Shared by `instance color` and `instance background` (server/instance-record.mjs);
659
+ * each checks its own value first. Anything out of shape is refused here and nothing runs. A read's deadline:
660
+ * 30 s, 45 s routed. The envelope comes back as the kernel printed it; the caller decodes it. */
661
+ function runInstanceRecord(bin, { instance, home, context, server }, verb, values, io) {
657
662
  const fail = code => ({ schemaVersion: 1, ok: false, error: { code } });
658
663
  if (typeof bin !== "string" || !isAbsolute(bin) || typeof instance !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(instance)
659
- || typeof home !== "string" || !isAbsolute(home) || home.includes("\0") || !(color === null || SOUL_COLORS.includes(color))
664
+ || typeof home !== "string" || !isAbsolute(home) || home.includes("\0")
660
665
  || (server !== undefined ? !/^[a-z0-9][a-z0-9-]{0,63}$/.test(server ?? "") : typeof context !== "string" || !isAbsolute(context))) return fail("E_BAD_ARGS");
661
- const argv = ["instance", "color", instance, ...(color === null ? ["--clear"] : [color]), "--home", home,
666
+ const argv = ["instance", verb, instance, ...values, "--home", home,
662
667
  ...(server !== undefined ? ["--server", server] : ["--dir", context]), "--json"];
663
668
  const limit = server !== undefined ? 45_000 : 30_000;
664
669
  return runJson(bin, argv, { cwd: server !== undefined ? io.cwd : context, exec: io.exec, strictExit: true,
665
670
  timeout: Number.isFinite(io.timeout) && io.timeout > 0 ? Math.min(io.timeout, limit) : limit });
666
671
  }
672
+ const instanceRecordRefused = () => ({ schemaVersion: 1, ok: false, error: { code: "E_BAD_ARGS" } });
673
+ /** An instance's colour (feature instance-color, awebai/oats#1421 §2): `oats instance color <instance>
674
+ * (<color> | --clear) …` (runInstanceRecord). `color` is a palette name (soul-colors.mjs SOUL_COLORS) or null to
675
+ * clear; anything else is refused here and nothing runs. */
676
+ export async function cliInstanceColor(bin, args, io = {}) {
677
+ const { color } = args;
678
+ if (!(color === null || SOUL_COLORS.includes(color))) return instanceRecordRefused();
679
+ return runInstanceRecord(bin, args, "color", color === null ? ["--clear"] : [color], io);
680
+ }
681
+ /** Whether an instance runs in the background (feature instance-background, awebai/oats#1579): `oats instance
682
+ * background <instance> (on | off) …` (runInstanceRecord). `background` is a boolean; anything else is refused
683
+ * here and nothing runs. Over `--server`, a host without the feature refuses it (E_REMOTE_INCOMPATIBLE). */
684
+ export async function cliInstanceBackground(bin, args, io = {}) {
685
+ const { background } = args;
686
+ if (typeof background !== "boolean") return instanceRecordRefused();
687
+ return runInstanceRecord(bin, args, "background", [background ? "on" : "off"], io);
688
+ }
667
689
 
668
690
  /** `maxAge` (feature observe-max-age) is inspect's alone; `features` is the probe's list and
669
691
  * gates the flags (also `instructions`, `skills` and `composedSkills`), so an undeclared kernel gets the flagless argv even when a value is given. */
@@ -223,12 +223,18 @@ export function deploymentStatusData(document, deployment) {
223
223
  // instanceColor, the one rule of which colour a row shows). Validated, never check()ed: anything
224
224
  // else is dropped and the row reads as one with no colour.
225
225
  if (own(instance, 'color') && instanceColor(instance) !== null) row.color = instanceColor(instance);
226
+ // Feature instance-background (#1579): the row is placed in the Background section. Exactly true only; any
227
+ // other value is dropped, never checked: the row stays in the main tree.
228
+ if (own(instance, 'background') && instance.background === true) row.background = true;
226
229
  // #802 (feature worktree-event): a spawn running its worktree hooks, verifiably alive. Boolean true only;
227
230
  // any other value is dropped, never checked: the row stays an ordinary one.
228
231
  if (own(instance, 'spawnInProgress') && instance.spawnInProgress === true) row.spawnInProgress = true;
229
232
  // Session resume: how the instance's last session ended, one of SESSION_ENDS exactly. Any other value is
230
233
  // dropped, never checked: the row reads as one that did not say.
231
234
  if (own(instance, 'sessionEnd') && SESSION_END_VALUES.includes(instance.sessionEnd)) row.sessionEnd = instance.sessionEnd;
235
+ // #1577 (feature instance-same-work): the child does its parent's work, so its parent line is drawn
236
+ // (same-work.mjs). Boolean true only; any other value is dropped, never checked: the row reads unflagged.
237
+ if (own(instance, 'sameWork') && instance.sameWork === true) row.sameWork = true;
232
238
  if (own(instance, 'modules')) row.modules = modules(instance.modules);
233
239
  if (own(instance, 'soul')) row.soul = soulSource(instance.soul);
234
240
  if (own(instance, 'workspace')) row.workspace = recordedWorkspace(instance.workspace);
@@ -372,6 +378,9 @@ export function soulsData(document) {
372
378
  out.key = out.kind === 'package' ? out.qualifiedName : out.name;
373
379
  if (own(row, 'key')) check(soulKey(row.key) && row.key === out.key);
374
380
  flags(row, ['private', 'spawnable'], out);
381
+ // Feature instance-background (#1579): the soul declares `background: true`, the default of the spawn dialog's
382
+ // Run in background switch. Exactly true only; any other value is dropped, never checked (as an instance row's).
383
+ if (own(row, 'background') && row.background === true) out.background = true;
375
384
  // desktop-facts: whether a spawn here would refuse, and the file. The row's flat harness/model/harnessFrom
376
385
  // are not kept: with launch-preference (0.30) the soul and this machine choose them, and the row's `launch`
377
386
  // (below) carries the kernel's report of that choice; before 0.30 they were always the kernel's default.