@awebai/oats 0.52.0 → 0.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/README.md +2 -1
  2. package/bin/oats.mjs +304 -92
  3. package/docs/capabilities.md +66 -4
  4. package/docs/configuration.md +66 -3
  5. package/docs/desktop-cli-api.md +673 -58
  6. package/docs/desktop-instance-start.md +25 -12
  7. package/docs/execution-targets.md +1 -0
  8. package/docs/implementation.md +175 -11
  9. package/docs/integrations.md +6 -3
  10. package/docs/knowledge.md +2 -2
  11. package/docs/macos-test-runs.md +246 -0
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +14 -14
  14. package/docs/release-lane.md +210 -6
  15. package/docs/release-notes/v0.53.0.md +1274 -0
  16. package/docs/schedules.md +7 -1
  17. package/docs/souls-and-instances.md +237 -15
  18. package/docs/tui.md +453 -21
  19. package/docs/upgrading.md +298 -0
  20. package/docs/workspaces.md +3 -3
  21. package/lib/automations.mjs +22 -22
  22. package/lib/claim.mjs +93 -4
  23. package/lib/config-data.mjs +4 -1
  24. package/lib/core.mjs +569 -121
  25. package/lib/instance-events.mjs +19 -1
  26. package/lib/instance-git.mjs +39 -3
  27. package/lib/instance-inspect.mjs +5 -6
  28. package/lib/instance-lifecycle.mjs +145 -18
  29. package/lib/instance-resolution.mjs +59 -6
  30. package/lib/launch-preference.mjs +226 -15
  31. package/lib/local-edit.mjs +118 -0
  32. package/lib/packages.mjs +13 -4
  33. package/lib/pi-bridge.mjs +308 -0
  34. package/lib/refused-text.mjs +11 -0
  35. package/lib/remote.mjs +190 -25
  36. package/lib/resolve.mjs +2 -1
  37. package/lib/retained-after-retire.mjs +2 -2
  38. package/lib/retire-output.mjs +12 -1
  39. package/lib/schedule-host.mjs +6 -35
  40. package/lib/shell-word.mjs +13 -0
  41. package/lib/soul-launch-verbs.mjs +153 -0
  42. package/lib/stable-node.mjs +62 -0
  43. package/lib/teams-verbs.mjs +18 -46
  44. package/lib/workspace.mjs +49 -19
  45. package/package-catalog.json +4 -4
  46. package/package.json +2 -1
  47. package/packages/client/attach-exit.mjs +25 -0
  48. package/packages/client/cli-adapter.mjs +16 -3
  49. package/packages/client/cli-locator.mjs +2 -2
  50. package/packages/client/deployment-contract.mjs +4 -0
  51. package/packages/client/deployment-facts.mjs +71 -10
  52. package/packages/client/deployment-panel.mjs +49 -11
  53. package/packages/client/deployment-read-cli.mjs +7 -3
  54. package/packages/client/display-text.mjs +8 -2
  55. package/packages/client/instance-acts.mjs +46 -10
  56. package/packages/client/instance-events-contract.mjs +4 -2
  57. package/packages/client/instance-presentation.mjs +66 -2
  58. package/packages/client/instance-tree.mjs +23 -14
  59. package/packages/client/kernel-lines.mjs +31 -0
  60. package/packages/client/kernel-made.mjs +23 -0
  61. package/packages/client/launch-prompt-outcome.mjs +51 -16
  62. package/packages/client/lifecycle-contract.mjs +45 -4
  63. package/packages/client/liveness.mjs +14 -1
  64. package/packages/client/own-codes.mjs +31 -0
  65. package/packages/client/panel-views.mjs +18 -11
  66. package/packages/client/readiness-contract.mjs +3 -1
  67. package/packages/client/remote-address.mjs +34 -9
  68. package/packages/client/remote-identity-memory.mjs +94 -0
  69. package/packages/client/remote-roster.mjs +92 -6
  70. package/packages/client/session-attach.mjs +175 -0
  71. package/packages/client/spawn-apply-contract.mjs +16 -4
  72. package/packages/client/spawn-messages.mjs +26 -3
  73. package/packages/client/spawn-preview-cli.mjs +8 -2
  74. package/packages/client/spawn-preview-contract.mjs +5 -1
  75. package/packages/client/terminal-exec.mjs +21 -0
  76. package/packages/client/workspace-choices.mjs +95 -0
  77. package/packages/client/workspace-views.mjs +39 -3
  78. package/packages/record/README.md +21 -0
  79. package/packages/record/bin/setup.mjs +108 -15
  80. package/packages/tui/README.md +30 -12
  81. package/packages/tui/lib/actions.mjs +16 -1
  82. package/packages/tui/lib/client.mjs +32 -1
  83. package/packages/tui/lib/config.mjs +151 -0
  84. package/packages/tui/lib/main.mjs +117 -46
  85. package/packages/tui/lib/model.mjs +392 -0
  86. package/packages/tui/lib/read.mjs +473 -0
  87. package/packages/tui/lib/store.mjs +364 -0
  88. package/packages/tui/lib/term/keys.mjs +44 -0
  89. package/packages/tui/lib/term/screen.mjs +16 -4
  90. package/packages/tui/lib/term/text.mjs +60 -0
  91. package/packages/tui/lib/term/tty.mjs +13 -3
  92. package/packages/tui/lib/views/detail.mjs +46 -0
  93. package/packages/tui/lib/views/frame.mjs +230 -36
  94. package/packages/tui/lib/views/help.mjs +125 -13
  95. package/packages/tui/lib/views/instances.mjs +137 -0
  96. package/packages/tui/lib/views/scroll.mjs +19 -0
  97. package/packages/tui/lib/views/switcher.mjs +97 -0
  98. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -46,7 +46,25 @@ export const EVENTS_API = 2;
46
46
  const HOME_LOG = ".oats-events.jsonl";
47
47
  const MAX_BYTES = 4 * 1024 * 1024;
48
48
 
49
- export const EVENT_KINDS = ["spawned", "launched", "restarted", "stopped", "stop-refused", "retire-planned", "retired", "worktree-retained", "worktree-removed", "worktree-added", "branch-deleted", "child-spawn-refused", "launch-warning", "launch-prompt", "recomposed", "waiting"];
49
+ export const EVENT_KINDS = ["spawned", "launched", "restarted", "stopped", "stop-refused", "retire-planned", "retired", "retire-refused", "worktree-retained", "worktree-removed", "worktree-added", "branch-deleted", "child-spawn-refused", "launch-warning", "launch-prompt", "recomposed", "waiting"];
50
+
51
+ /** The longest `reason` a `retire-refused` row carries, in UTF-16 code units. The bound is not the
52
+ * kernel's: the Desktop's events reader refuses a whole read that holds a longer detail
53
+ * (`eventsDetail`, packages/client/instance-events-contract.mjs), so the kernel writes none.
54
+ * test/retire-refused-reader.test.mjs pins the two together; nothing under lib/ reads that package. */
55
+ export const RETIRE_REFUSED_REASON_MAX = 2048;
56
+ /** The `reason` of a `retire-refused` row for the sentence a retire answered: on one line (each run
57
+ * of whitespace, newlines among them, is one space) and at most RETIRE_REFUSED_REASON_MAX code
58
+ * units. A longer one is cut and ends with `…`, the mark counted in the bound, and never through a
59
+ * surrogate pair. */
60
+ export function retireRefusedReason(sentence) {
61
+ const line = String(sentence).replace(/\s+/g, " ").trim();
62
+ if (line.length <= RETIRE_REFUSED_REASON_MAX) return line;
63
+ const cut = line.slice(0, RETIRE_REFUSED_REASON_MAX - 1);
64
+ const last = cut.charCodeAt(cut.length - 1);
65
+ // A high surrogate at the end was the first half of a pair the cut went through.
66
+ return `${last >= 0xd800 && last <= 0xdbff ? cut.slice(0, -1) : cut}…`;
67
+ }
50
68
 
51
69
  /** Kernel rows that end or begin a session: a waiting claim older than the
52
70
  * incarnation's latest one is not live. */
@@ -8,9 +8,10 @@
8
8
  * against a tree that has since moved is refused, never served. */
9
9
  import { execFileSync, spawnSync } from "node:child_process";
10
10
  import { createHash } from "node:crypto";
11
- import { existsSync, readFileSync } from "node:fs";
11
+ import { existsSync, lstatSync, readFileSync } from "node:fs";
12
12
  import { join } from "node:path";
13
13
  import { oatsError } from "./errors.mjs";
14
+ import { canonicalHomePath } from "./real-path.mjs";
14
15
 
15
16
  const GIT_MAX_BUFFER = 64 * 1024 * 1024;
16
17
  const DIFF_MAX_BYTES = 256 * 1024;
@@ -68,6 +69,26 @@ export function gitRepoRead(gitDir, argv, { input, encoding } = {}) { return git
68
69
  export function gitRepoRun(gitDir, argv) {
69
70
  return execFileSync("git", ["--git-dir", gitDir, ...READ_ONLY_GIT, ...argv], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 120_000, env: gitEnv() });
70
71
  }
72
+ /** What the result of a `git rev-parse -q --verify <ref>` (spawnSync's) says
73
+ * of the ref → "there" (status 0), "absent" (status 1 and nothing printed),
74
+ * else "unknown". An error or a signal is "unknown" whatever the status: a
75
+ * Git that could not be started has none, and one that is ended at the
76
+ * timeout can still exit 1 and print nothing, when it handles the signal. */
77
+ export function gitRefPresenceOf(r) {
78
+ if (r.error || r.signal) return "unknown";
79
+ if (r.status === 0) return "there";
80
+ return r.status === 1 && !r.stdout && !r.stderr ? "absent" : "unknown";
81
+ }
82
+ /** Whether the ref `name` is there in the tree at `cwd`, asked of Git
83
+ * (`rev-parse -q --verify`), which answers for every format a repository
84
+ * stores its refs in → "there", "absent" or "unknown" (gitRefPresenceOf);
85
+ * "unknown" too with no tree to ask in. Never throws: the caller decides
86
+ * what "unknown" means. Read-only and helper-free, like the module's other
87
+ * reads. */
88
+ export function gitRefPresence(cwd, name) {
89
+ if (typeof cwd !== "string" || !cwd) return "unknown";
90
+ return gitRefPresenceOf(spawnSync("git", ["-C", cwd, ...READ_ONLY_GIT, "rev-parse", "-q", "--verify", name], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 30_000, env: gitEnv() }));
91
+ }
71
92
  function gitProbe(where, argv, input, encoding = "utf8") {
72
93
  const r = spawnSync("git", [...where, ...READ_ONLY_GIT, ...argv], { encoding, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], input, maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 30_000, env: gitEnv() });
73
94
  return !r.error && r.status === 0 ? { ok: true, out: r.stdout } : { ok: false, out: "", err: String(r.error?.message ?? r.stderr ?? "").trim() || `git ${argv[0]} exited with ${r.status}` };
@@ -147,7 +168,17 @@ export function worktreeHead(work) {
147
168
 
148
169
  /** The instance's work tree, from its home. The home's instance.json names
149
170
  * the work mode; the tree is `<home>/work` (a directory or a symlink to the
150
- * shared checkout). Missing/retired → attributed refusal, never a crash. */
171
+ * shared checkout). Missing/retired → attributed refusal, never a crash.
172
+ *
173
+ * A real directory at `work/` is the instance's work tree only when it is
174
+ * the top level Git names for it (awebai/oats#962). Git answers for any
175
+ * directory inside a work tree, so a plain directory in a home whose
176
+ * deployment is a checkout, or whose home was made a repository, would be
177
+ * read as that repository's: its branch and its files, none of them the
178
+ * instance's. That is E_NO_WORKTREE, in every work mode: the rule is the
179
+ * path. A `work/` that is a link is read as what it leads to, wherever
180
+ * that is (a workspace instance's leads to the deployment directory, which
181
+ * is above its home). */
151
182
  export function instanceWorkTree(home) {
152
183
  const metaFile = join(home, "instance.json");
153
184
  if (!existsSync(metaFile)) throw oatsError("E_SESSION_UNKNOWN", `${home} is not an OATS instance home (no instance.json)`);
@@ -155,8 +186,13 @@ export function instanceWorkTree(home) {
155
186
  try { meta = JSON.parse(readFileSync(metaFile, "utf8")); } catch (e) { throw oatsError("E_SESSION_UNKNOWN", `${metaFile}: ${e.message}`); }
156
187
  const work = join(home, "work");
157
188
  if (!existsSync(work)) throw oatsError("E_NO_WORKTREE", `${meta.instance ?? home} has no work tree at ${work} (retired, recovered, or never materialized)`);
158
- const inside = trim(git(work, ["rev-parse", "--is-inside-work-tree"], { allowFail: true }));
189
+ // One read: whether Git answers for `work` at all, and the top level it names for it.
190
+ const [inside, ...rest] = (trim(git(work, ["rev-parse", "--is-inside-work-tree", "--show-toplevel"], { allowFail: true })) ?? "").split("\n");
159
191
  if (inside !== "true") throw oatsError("E_NO_WORKTREE", `${work} is not inside a git work tree`);
192
+ const top = rest.join("\n");
193
+ if (!lstatSync(work).isSymbolicLink() && (!top || canonicalHomePath(top) !== canonicalHomePath(work))) {
194
+ throw oatsError("E_NO_WORKTREE", `${work} is not a git work tree of its own: Git reads it as a directory inside another work tree`);
195
+ }
160
196
  return { meta, work, mode: meta.work ?? null };
161
197
  }
162
198
 
@@ -13,9 +13,8 @@
13
13
  import { spawnSync } from "node:child_process";
14
14
  import { accessSync, constants as fsConstants, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
15
15
  import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
16
- import { fileURLToPath } from "node:url";
17
- import { capabilityManifests, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, preparedSoulIdOf, stableSoulId, launchFolderTrust, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
18
- import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance, resolutionContractWarnings, soulCopyDigests } from "./instance-resolution.mjs";
16
+ import { capabilityManifests, kernelBin, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, preparedSoulIdOf, stableSoulId, launchFolderTrust, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
17
+ import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance, resolutionContractWarnings, soulCopyDigests, soulsOffered } from "./instance-resolution.mjs";
19
18
  import { declaredSettings, locatedContractWarnings } from "./capability-contract.mjs";
20
19
  import { kernelCompatibility } from "./resolve.mjs";
21
20
  import { discoveredTeamKeys, isRemovedTeamKeys, isTeamRefusal, recordedTeams, reportRows, soulKeyOf, teamKeyOf, soulTeams, teamModel, teamProblems } from "./teams.mjs";
@@ -30,12 +29,12 @@ import { composeSoulInstructions } from "./soul-composition.mjs";
30
29
  /** Bounds of a provider check's answer (bytes, nesting, entries), as the released binding wire set them. */
31
30
  const BINDING_LIMITS = Object.freeze({ maxBytes: 1024 * 1024, maxDepth: 32, maxEntries: 16384 });
32
31
  import { parseStrictJson } from "./canonical-json.mjs";
32
+ import { kernelNode } from "./stable-node.mjs";
33
33
 
34
34
  export const INSPECT_OPERATIONS_API = 2;
35
35
  export const SOULS_API = 2;
36
36
  export const READINESS_API = 2;
37
37
  const LAYERS = ["knowledge", "messaging", "tasks"];
38
- const CLI_BIN = fileURLToPath(new URL("../bin/oats.mjs", import.meta.url));
39
38
  const obj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
40
39
  const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
41
40
 
@@ -195,7 +194,7 @@ export async function soulTarget(contextDir, soul, { remoteOptions, materialize
195
194
  // Feature launch-preference: what a spawn with no flags would launch here.
196
195
  let launchConfigs = {};
197
196
  try { launchConfigs = launchConfigsAt(deployment); } catch { launchConfigs = {}; }
198
- const launch = launchReportFor({ layers: prepared?.launch ?? launchLayers({ definition: soulEntry.definition, entry: soulEntry, key: soulKeyOf(soulEntry), local: found.local }), launchConfigs, contextDir: deployment });
197
+ const launch = launchReportFor({ layers: prepared?.launch ?? launchLayers({ definition: soulEntry.definition, entry: soulEntry, key: soulKeyOf(soulEntry), local: found.local, offered: soulsOffered(discovery) }), launchConfigs, contextDir: deployment });
199
198
  return {
200
199
  kind: "soul", home: null, meta: null, deployment, agentsRoot: join(deployment, "agents"), teams, defaultTeam, teamsSource: "live", teamModel: model, teamKey, launch, session: newSessionDefaults(deployment),
201
200
  subject: { kind: "soul", soul: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null },
@@ -440,7 +439,7 @@ const item = (subject, status, { required = true, reason = null, producer = "ker
440
439
  function providerEnv(t, capability, settings) {
441
440
  const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^(OATS_|OAS_|PI_)/.test(k)));
442
441
  Object.assign(env, teamEnv({ workspace: { key: t.workspace.key, name: t.workspace.name, deployment: t.deployment }, teams: t.teams, defaultTeam: t.defaultTeam, teamsSource: t.teamsSource }));
443
- return Object.assign(env, { OATS_CAPABILITY: capability, OATS_SETTINGS: JSON.stringify(settings), OATS_SETTINGS_ORIGINS: JSON.stringify(t.payloadOrigins?.[capability] ?? {}), OATS_CLI_BIN: CLI_BIN, OATS_WORKSPACE: t.deployment,
442
+ return Object.assign(env, { OATS_CAPABILITY: capability, OATS_SETTINGS: JSON.stringify(settings), OATS_SETTINGS_ORIGINS: JSON.stringify(t.payloadOrigins?.[capability] ?? {}), OATS_CLI_BIN: kernelBin(), OATS_NODE_BIN: kernelNode().node, OATS_WORKSPACE: t.deployment,
444
443
  ...(t.home ? { OATS_INSTANCE: t.meta.instance, OATS_INSTANCE_HOME: t.home } : {}), OATS_AGENT: t.soulIdentity?.agent || t.soul.name, ...(t.soulIdentity?.id ? { OATS_SOUL_ID: t.soulIdentity.id } : {}),
445
444
  ...(t.soul.soulDir ? { OATS_SOUL: t.soul.soulDir } : {}) });
446
445
  }
@@ -10,7 +10,7 @@
10
10
  import { createHash } from "node:crypto";
11
11
  import { existsSync, lstatSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
12
12
  import { basename, join } from "node:path";
13
- import { attachedWorkLink, claimHomeFor, extraWorktreePlan, findInstanceHomes, homeClaimHolder, identifiedHomeRecord, inspectInstanceSession, listAgents, listInstances, observeSessionWithoutReceipt, readHomeRecord, releaseHomeClaim, requireStopGrace, retireClaimPath, retirePendingMarkerPath, retirementRecoveryFacts, stillRunningOf, stopInstanceSession, STOP_UNDER_CLAIM } from "./core.mjs";
13
+ import { attachedWorkLink, claimHomeFor, extraWorktreePlan, findInstanceHomes, homeClaimHolder, identifiedHomeRecord, inspectInstanceSession, instanceWork, listAgents, listInstances, observeSessionWithoutReceipt, readHomeRecord, READ_CLAIM_WHEN_UNWRITABLE, releaseHomeClaim, requireStopGrace, retireClaimPath, retirePendingMarkerPath, retirementRecoveryFacts, shq, stillRunningOf, stopInstanceSession, STOP_UNDER_CLAIM } from "./core.mjs";
14
14
  import { groupedByOwner } from "./retire-output.mjs";
15
15
  import { observeInstanceGit } from "./instance-git.mjs";
16
16
  import { appendEvent } from "./instance-events.mjs";
@@ -192,7 +192,11 @@ const STOP_CLAIM_PASSES = 3;
192
192
 
193
193
  /** Apply a Stop plan. A stop holds the lifecycle claim of EVERY target (core claimHomeFor, the
194
194
  * retire's file) before it stops the first one, and until it has written its receipt
195
- * (awebai/oats#866, #890). In this order:
195
+ * (awebai/oats#866, #890). The one exception (awebai/oats#946): a target whose claim cannot be
196
+ * WRITTEN, for a reason of the system's that stops every other writer of this user as well
197
+ * (lib/claim.mjs CLAIM_UNWRITABLE_CODES: a full disk, a directory that is not writable), is
198
+ * read where it would have been taken, and the stop goes on when nobody holds it, holding
199
+ * nothing for that target and saying so (STOP_WARNINGS). In this order:
196
200
  * 1. the plan, read for its targets and for the home of the receipt;
197
201
  * 2. a receipt recorded under the same key is replayed (STORED_UNDER_KERNEL_CODES,
198
202
  * replayedResults): read-only, before any claim;
@@ -200,12 +204,14 @@ const STOP_CLAIM_PASSES = 3;
200
204
  * stops cannot each hold half: one wins the first file both want, the other is refused at
201
205
  * once and releases what it took. A holder is answered here, before a stale plan:
202
206
  * E_INSTANCE_RETIRING beside a retire, E_LIFECYCLE_BUSY beside a stop, with the plan read
203
- * before the claims;
207
+ * before the claims. A claim that is only read answers the same for whoever holds it;
204
208
  * 4. the plan again, under the claims: the plan that is acted on. Every target IT names is held
205
209
  * by this apply before anything is done: one it does not hold (a child recorded, or readable
206
210
  * again, since the read of 1) sends the apply back to 3 with this plan's targets, every claim
207
- * released first, so that the order of 3 holds (STOP_CLAIM_PASSES bounds it). Then the one
208
- * comparison with the revision the caller sent: a child retired or re-made, a session started
211
+ * released first, so that the order of 3 holds (STOP_CLAIM_PASSES bounds it). A target whose
212
+ * claim was only read counts as covered, and is read once more here, with the same read: the
213
+ * last look before the first signal, answered before a stale plan as a holder is in 3. Then
214
+ * the one comparison with the revision the caller sent: a child retired or re-made, a session started
209
215
  * or ended, a self-retire scheduled since the plan was shown is E_PLAN_STALE with the fresh
210
216
  * plan (the guarded retire's pattern, core RETIRE_UNDER_CLAIM). The plan's own refusals come
211
217
  * from this read too: the instance itself retired since (E_SESSION_UNKNOWN), its record no
@@ -238,9 +244,10 @@ export function applyStop(ctx, root, name, { home, recursive = true, planRevisio
238
244
  const order = before.targets.map((t) => ({ t, lock: retireClaimPath(t.home) })).sort((a, b) => (a.lock < b.lock ? -1 : a.lock > b.lock ? 1 : 0));
239
245
  for (const { t } of order) {
240
246
  // The refusal's details are of the target whose claim refused, which may be a child.
241
- try { held.push(claimHomeFor("stop", t.instance, t.home)); } catch (e) { throw Object.assign(e, { plan: before }); }
247
+ // A claim that cannot be written is read in its place (#946): held, or held by nobody.
248
+ try { held.push({ ...claimHomeFor("stop", t.instance, t.home, { [READ_CLAIM_WHEN_UNWRITABLE]: true }), instance: t.instance }); } catch (e) { throw Object.assign(e, { plan: before }); }
242
249
  }
243
- const fresh = planStop(ctx, root, name, { home, recursive, [OWN_HOLDINGS]: new Set(held.map((h) => h.me.nonce)) });
250
+ const fresh = planStop(ctx, root, name, { home, recursive, [OWN_HOLDINGS]: new Set(held.filter((h) => h.me).map((h) => h.me.nonce)) });
244
251
  const mine = new Set(held.map((h) => h.lock));
245
252
  // A claim it holds for a home the fresh plan no longer names is released with the rest.
246
253
  if (fresh.targets.every((t) => mine.has(retireClaimPath(t.home)))) { plan = fresh; break; }
@@ -248,10 +255,18 @@ export function applyStop(ctx, root, name, { home, recursive = true, planRevisio
248
255
  if (pass === STOP_CLAIM_PASSES) throw Object.assign(lifecycleBusy("none", `the instances a stop of ${name} would stop changed each of the ${pass} times their claims were taken; nothing was stopped`, "run the command again", { instance: name, home: fresh.home }), { plan: fresh });
249
256
  before = fresh;
250
257
  }
258
+ // The targets whose claim was only read, of this plan: nothing is held for them, so the same
259
+ // read is made again here, the last look before the first signal. A holder that came since
260
+ // is answered as a held claim's is, before a stale plan.
261
+ const targets = new Set(plan.targets.map((t) => retireClaimPath(t.home)));
262
+ const unheld = held.filter((h) => !h.me && targets.has(h.lock));
263
+ for (const h of unheld) { try { h.look(); } catch (e) { throw Object.assign(e, { plan }); } }
251
264
  if (plan.planRevision !== expected) throw Object.assign(oatsError("E_PLAN_STALE", `the stop plan changed since it was shown (${expected} → ${plan.planRevision}); review the fresh plan`), { plan });
252
265
  const retiring = plan.targets.filter((t) => t.retiring);
253
266
  if (retiring.length) throw Object.assign(oatsError("E_INSTANCE_RETIRING", `${retiring.map((t) => t.instance).join(", ")} ${retiring.length === 1 ? "is" : "are"} being retired; nothing was stopped`), { plan });
254
- const warnings = [];
267
+ // The system's code, never its message. The claim's own path, also when the write that
268
+ // failed was a takeover's.
269
+ const warnings = unheld.map((h) => `${h.instance}: stopping without its claim: ${h.lock} could not be written (${h.unwritable}), and nobody holds it. A retire or a stop of ${h.instance} that starts while this one runs will not see it.`);
255
270
  for (const t of plan.targets) {
256
271
  const left = leftoverStopMarkerPath(t.home);
257
272
  try { rmSync(left, { force: true }); } catch (e) { warnings.push(`${left}, a stop marker an older OATS left, could not be removed (${e?.message ?? e}); it refuses nothing, and the stop went on`); }
@@ -280,9 +295,32 @@ export function applyStop(ctx, root, name, { home, recursive = true, planRevisio
280
295
  }
281
296
  }
282
297
 
283
- function writeFileSyncAtomic(path, value) {
298
+ /** Write `value` as JSON at `path` through a private file beside it, renamed over it. When the
299
+ * write or the rename fails the private file is removed and the error thrown is that failure's
300
+ * (awebai/oats#963, as core.mjs writeJsonAtomic). The removal's own failure is not answered.
301
+ * Exported for its test alone (test/stop-private-files.test.mjs): its one caller keeps the error
302
+ * to itself, so nothing but a call of it shows what it throws. */
303
+ export function writeFileSyncAtomic(path, value) {
284
304
  const tmp = `${path}.${process.pid}.tmp`;
285
- writeFileSync(tmp, JSON.stringify(value, null, 2)); renameSync(tmp, path);
305
+ try {
306
+ writeFileSync(tmp, JSON.stringify(value, null, 2)); renameSync(tmp, path);
307
+ } catch (e) {
308
+ try { rmSync(tmp, { force: true }); } catch { /* the first error is the one answered */ }
309
+ throw e;
310
+ }
311
+ }
312
+
313
+ /** The sentence a stop's text closes with, chosen from the receipt's rows as a client reads them
314
+ * (docs/desktop-cli-api.md, `stillRunning`): a failed row whose `stillRunning` names a process,
315
+ * or is `null` or absent (nothing established), may still run; `[]` says stopped. A receipt that
316
+ * is not `ok` while no failed row has anything still running is a stop that stopped its targets
317
+ * and could not complete its record (a write into the home refused: a full disk), and the text
318
+ * must not say that something still runs (awebai/oats#963). Fixed sentences; the JSON receipt
319
+ * is not made from this. */
320
+ export function stopClosingLine(receipt) {
321
+ if (receipt.ok) return `stopped${receipt.replayed ? " (replayed receipt)" : ""}; home, work, transcript and launch configuration retained — restart with \`oats session restart\``;
322
+ const mayRun = receipt.results.some((r) => !r.ok && !(Array.isArray(r.stillRunning) && r.stillRunning.length === 0));
323
+ return mayRun ? "some targets are still running; nothing was escalated" : "the stop did not complete its record; nothing is still running";
286
324
  }
287
325
 
288
326
  /** What the Desktop reads of a plan's notes (packages/client/lifecycle-contract.mjs): at
@@ -388,28 +426,62 @@ export function planRetire(ctx, root, name, { home } = {}) {
388
426
  // into the revision (below), so that an apply refuses as stale when a tree
389
427
  // was created, removed, dirtied or cleaned, or its target was taken.
390
428
  const extraWorktrees = extraWorktreePlan(me.home, me.root);
429
+ // What work/ is, by the one function the retire reads too (core instanceWork, #962): the plan says
430
+ // what the retire will do with it.
431
+ const workIs = instanceWork(me.home, meta);
432
+ const ownTree = workIs.is === "own-tree", homeDirectory = workIs.is === "home-directory";
391
433
  // A home spawned before #641 may record the word "HEAD" for a detached checkout: not a branch name.
392
- const facts = { session: target.session, work: target.work, workMode: meta.work ?? null, repo: meta.repo ?? null, recordedBranch: meta.branch === "HEAD" ? null : meta.branch ?? null,
434
+ // `ownWorktree` (#988, feature retire-plan-own-worktree) is that reading as a fact: whether work/
435
+ // is the instance's own work tree, the one this retire retains or removes. `workMode` is the
436
+ // record's value, which the instance can write, and `work` observes through any link: neither
437
+ // says whose tree it is. A stop plan does not carry it.
438
+ const facts = { session: target.session, work: target.work, workMode: meta.work ?? null, ownWorktree: ownTree, repo: meta.repo ?? null, recordedBranch: meta.branch === "HEAD" ? null : meta.branch ?? null,
393
439
  extraWorktrees,
394
440
  children: kids.map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, session: sessionFacts(c.home) })),
395
441
  ambiguous: (kids.ambiguous || []).map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, reason: c.reason })),
396
442
  pullRequest: "unknown" /* forge facts are the ADE's (P1); the kernel never claims 'no PR' */ };
397
- const defaults = { retainWorktree: meta.work === "worktree", deleteBranch: false, stopChildren: true, retainChildren: true };
443
+ // `retainWorktree` is the default of one option, whether the instance's own tree is retained. It
444
+ // follows the reading of work/ today, as the fact above does: a default is what the retire would
445
+ // do if nobody chose, a fact is what is there, and a client reads neither as the other.
446
+ // A link under a record that says `worktree` (#973): the link decides, and the plan says so.
447
+ const linkNotOwn = workIs.is === "link" && meta.work === "worktree";
448
+ const defaults = { retainWorktree: ownTree, deleteBranch: false, stopChildren: true, retainChildren: true };
449
+ // The repository the retire would read from Git for an own tree whose record names none.
450
+ const repoFromGit = ownTree && !meta.repo ? workIs.tree?.repo ?? null : null;
451
+ const byModeAlone = meta.work === "worktree" ? "own-tree" : meta.work === "directory" ? "directory-mode" : workIs.at;
452
+ const workBinding = workIs.is !== byModeAlone || repoFromGit ? { work: workIs.is, repo: repoFromGit } : null;
398
453
  const safety = [me.home, target.session.state, target.launched, facts.work.observed ? [facts.work.revision, facts.work.branch, facts.work.changed, facts.work.untracked] : null, kids.map((c) => c.home),
399
454
  // Only when there are any: a home without extra trees keeps the revision it had.
400
- ...(extraWorktrees.length ? [extraWorktrees] : [])];
455
+ ...(extraWorktrees.length ? [extraWorktrees] : []),
456
+ // What work/ is decides what the retire does with it (#962), so it is part of the revision: a
457
+ // guarded apply refuses as stale when an own tree became a directory of the home, or the other
458
+ // way round, since the plan was shown, and when the repository read from Git changed. A link
459
+ // under a record that says `worktree` is bound the same way (#973): a plan read while work/ was
460
+ // a link is stale once work/ is the instance's own tree, and the other way round. Only where
461
+ // the answer is not the one the record's mode alone gives: every other home keeps the revision
462
+ // it had.
463
+ ...(workBinding ? [workBinding] : [])];
401
464
  // What retire would preserve and where, read from the spawn baseline and the
402
465
  // work mode: nothing is hashed, and the plan revision does not depend on it.
403
466
  // The declared roots are listed as written, bounded so one note stays short.
404
467
  const recovery = retirementRecoveryFacts(me.home);
405
468
  // Attached children whose work is this home's work/ (#718): a retire that keeps the worktree
406
469
  // repoints them to it. One note holds whatever the dialog then picks.
407
- const attached = meta.work === "worktree" ? kids.filter((c) => attachedWorkLink(c.home, me.home) !== null) : [];
470
+ const attached = ownTree ? kids.filter((c) => attachedWorkLink(c.home, me.home) !== null) : [];
408
471
  appendEvent(me.home, { kind: "retire-planned", data: { planRevision: planRevision(safety), children: kids.length, dirty: facts.work.observed ? facts.work.changed + facts.work.untracked : null } }, { workspaceOnly: true });
409
- return { lifecycleApi: LIFECYCLE_API, action: "retire", instance: name, home: me.home, at: new Date().toISOString(), facts, defaults, planRevision: planRevision(safety),
472
+ const plan = { lifecycleApi: LIFECYCLE_API, action: "retire", instance: name, home: me.home, at: new Date().toISOString(), facts, defaults, planRevision: planRevision(safety),
410
473
  notes: boundedNotes(extraWorktrees.map(extraWorktreeNote), [
411
- ...(facts.work.observed && facts.work.drift ? [driftNote(facts.work, facts.recordedBranch)] : []),
412
- ...(facts.work.observed && facts.work.changed + facts.work.untracked > 0 ? [`${facts.work.changed} changed and ${facts.work.untracked} untracked file(s) would be retained with the worktree`] : []),
474
+ // The two notes about a worktree that is retained are for the instance's own tree alone (#973).
475
+ // Not for a directory of the home (what it holds is copied and removed), not for a directory
476
+ // instance whose work/ is a repository of its own (the recovery note below says what is done),
477
+ // and not for a link: facts.work observes what the link leads to, which is another's tree
478
+ // (its owner's, the shared checkout, the deployment) that the retire neither keeps nor moves.
479
+ ...(ownTree && facts.work.observed && facts.work.drift ? [driftNote(facts.work, facts.recordedBranch)] : []),
480
+ ...(ownTree && facts.work.observed && facts.work.changed + facts.work.untracked > 0 ? [`${facts.work.changed} changed and ${facts.work.untracked} untracked file(s) would be retained with the worktree`] : []),
481
+ ...(homeDirectory ? [HOME_DIRECTORY_NOTE] : []),
482
+ ...(linkNotOwn ? [LINK_NOTE] : []),
483
+ ...(homeDirectory && workIs.tree ? [`work/ is registered as a worktree of ${workIs.tree.repo}: the retire leaves its entry there until a prune (git -C ${shq(workIs.tree.repo)} worktree prune), and does not touch its branch or its commits`] : []),
484
+ ...(repoFromGit ? [`the record names no repository for the work tree: the retire uses the one Git names for it, ${repoFromGit}, and does not write it into the record`] : []),
413
485
  ], [
414
486
  ...(kids.length ? [`${kids.length} recorded child instance(s) are stopped first (bounded SIGTERM, never escalated) and retained (their homes are not removed); a child still running after the grace refuses the retirement`] : []),
415
487
  ...(attached.length ? [`attached child instance(s) ${listWithin(attached.map((c) => c.instance), (shown) => shown.join(", "), PLAN_LIST_BUDGET) ?? attached.length} use this home's work/ as their work: a retire that keeps the worktree repoints their work link to it; with --discard-worktree the worktree is removed and their work link will dangle`] : []),
@@ -417,8 +489,63 @@ export function planRetire(ctx, root, name, { home } = {}) {
417
489
  ...(target.session.note ? [sessionNote(target.session)] : []),
418
490
  "pull request state is unknown to the kernel; the ADE reports it when a forge connection exists",
419
491
  recoveryNote(recovery),
420
- ...(meta.work === "worktree" ? ["recovery: uncommitted worktree state is copied there too"] : meta.work === "directory" ? ["recovery: work/ is copied there when it is not empty"] : []),
492
+ ...(ownTree ? ["recovery: uncommitted worktree state is copied there too"] : homeDirectory || meta.work === "directory" ? ["recovery: work/ is copied there when it is not empty"] : []),
421
493
  ]) };
494
+ // For the plan's text alone (retireDefaultsLine): not part of the plan's JSON.
495
+ Object.defineProperty(plan, PLAN_WORK, { value: workIs.is });
496
+ return plan;
497
+ }
498
+
499
+ /** A retire plan's own answer to what work/ is (core instanceWork), kept on the plan object for its
500
+ * text line and never serialised: the plan's JSON has no field for it. */
501
+ const PLAN_WORK = Symbol("oats.retire-plan.work");
502
+ /** The plan's note for a real directory at work/ that is not the instance's own tree (#962). */
503
+ const HOME_DIRECTORY_NOTE = "work/ is a real directory of the home and not a work tree of the instance's own: the retire copies it to recovery when it is not empty (a .git in it included), checks the copy, and removes it with the home";
504
+ /** The same, as the plan's text says it where a `worktree` instance's says "retain worktree". */
505
+ const HOME_DIRECTORY_SENTENCE = "no work tree of its own (work/ is a real directory of the home: copied to recovery when not empty and then removed with the home)";
506
+
507
+ /** The plan's note for a link at work/ under a record that says `worktree` (#973). It names no
508
+ * target: the plan's revision does not bind where the link leads. It names the flag: a plan takes
509
+ * no option (`--plan --discard-worktree` answers this same plan), and no worktree step runs for a
510
+ * link with the flag either, which the plan says before the receipt does. */
511
+ const LINK_NOTE = "the record says work mode worktree, but work/ is a link and not a work tree of the instance's own: the retire removes the link with the home and does not touch what it leads to, with --discard-worktree as well";
512
+ /** The same, as the plan's text says it where a `worktree` instance's says "retain worktree". */
513
+ const LINK_SENTENCE = "no work tree of its own (work/ is a link, though the record says worktree: what it leads to is not touched)";
514
+
515
+ /** What a retire does with `work/` in each work mode that has no work tree of its own, as the plan's
516
+ * text says it where a `worktree` instance's says "retain worktree" (awebai/oats#959). Each is what
517
+ * retireInstance does (lib/core.mjs): `work/` of an attached, checkout or workspace instance is a
518
+ * link the spawn made, which goes with the home and whose target no step of the retire reads as a
519
+ * tree to move or remove; `work/` of a directory instance is the home's own directory, copied to
520
+ * recovery when it holds anything and then removed with the home. */
521
+ const RETIRE_WORK_SENTENCES = {
522
+ attached: "no work tree of its own (work/ links to its owner's tree and that tree is not touched)",
523
+ checkout: "no work tree of its own (work/ links to the shared checkout and that checkout is not touched)",
524
+ workspace: "no work tree of its own (work/ links to the deployment directory and that directory is not touched)",
525
+ directory: "no work tree (work/ is the home's own directory: copied to recovery when not empty and then removed with the home)",
526
+ };
527
+ /** The `defaults:` line of a retire plan's text. `defaults.retainWorktree` is the default of one
528
+ * option, whether the instance's OWN work tree is retained, and is `true` only when `work/` is
529
+ * that tree (below): printed as `false` for a home without one it reads as if a tree were
530
+ * removed, so the line says what is true of that mode's work instead. A record with no work mode, or one this kernel does not know
531
+ * (a value that is not a string included: it is never read as a mode's name), says so, in the
532
+ * kernel's words alone: the value is the record's, which the instance can write, and is never
533
+ * printed (`facts.workMode` of the JSON holds it). The plan's JSON is not changed by any of this.
534
+ *
535
+ * What is at `work/` comes first (#962, the plan's own answer, PLAN_WORK): a real directory that is
536
+ * not the instance's own tree is said as that, whatever the mode, and the instance's own tree is
537
+ * "retain worktree", whatever the mode (a record with no work mode whose `work/` Git confirms is a
538
+ * registered worktree). A link under a record that says `worktree` is said as a link, never as
539
+ * "retain worktree false" (#973). A plan object without that answer is read by its mode alone. */
540
+ export function retireDefaultsLine(plan) {
541
+ const mode = plan.facts.workMode;
542
+ const work = plan[PLAN_WORK] === "home-directory" ? HOME_DIRECTORY_SENTENCE
543
+ : plan[PLAN_WORK] === "link" && mode === "worktree" ? LINK_SENTENCE
544
+ : mode === "worktree" || plan[PLAN_WORK] === "own-tree" ? `retain worktree ${plan.defaults.retainWorktree}`
545
+ : typeof mode === "string" && Object.hasOwn(RETIRE_WORK_SENTENCES, mode) ? RETIRE_WORK_SENTENCES[mode]
546
+ : mode === null || mode === undefined ? "work mode not recorded"
547
+ : "work mode not known to this kernel";
548
+ return `defaults: ${work}, delete branch ${plan.defaults.deleteBranch}, stop children ${plan.defaults.stopChildren}`;
422
549
  }
423
550
 
424
551
  /** A retire plan's notes in order: `before`, one per extra tree, `after`. The extra trees are the
@@ -108,10 +108,6 @@ export function homeSoulMatches(name, meta) {
108
108
  return soulNameMatches(name, soul.package && typeof soul.package === "object" ? { name: soul.name, package: soul.package.id } : { name: meta?.agent, repoKey: soul.repoKey });
109
109
  }
110
110
 
111
- /** Find the soul named `name` in a discovery: confirmed members, external souls and package
112
- * souls. A bare name must be unique across all three (else E_SOUL_AMBIGUOUS naming each
113
- * qualified form); `<repo>/<soul>` names a member (its key, a key suffix or its member name)
114
- * or an external source, `<package>/<soul>` a package soul. */
115
111
  /** Every soul a discovery offers, each with the rule a typed name matches it by: the confirmed
116
112
  * members' souls (a standalone view's one row is the repo's own, unconfirmed by definition — the
117
113
  * workspace could not be read; resolveSoul admits exactly that case), the external souls, and the
@@ -134,6 +130,48 @@ export function soulCandidates(discovery) {
134
130
  return out;
135
131
  }
136
132
 
133
+ /**
134
+ * What a read of the workspace offered, for the keys of oats-local.yaml souls.launch: the description
135
+ * lib/launch-preference.mjs launchKeysUnmatched decides from. Built here, once, from the discovery:
136
+ * `keys`: the soul key (soulKeyOf) of every offered soul (soulCandidates), sorted. souls.disabled is
137
+ * not consulted: a soul not run on this machine is still a soul the workspace offers.
138
+ * `unread`: what this read could not see (discovery.soulsUnread, the members' rows):
139
+ * `all`: "standalone" in the standalone view of a workspace whose host cannot be read: the souls
140
+ * there are one member's, and the workspace's are not known. An explicit `standalone:` is
141
+ * the configured view: what it offers is all it offers.
142
+ * `bare`: why a soul keyed by its bare name may be missing: "member-unconfirmed" (a member the
143
+ * workspace lists and could not confirm), else "soul-unread" (a member's or an external
144
+ * soul skipped with a problem); null when every such soul was read.
145
+ * `packages`: { <id>: "package-unlocked" | "package-soul-unread" } for a package the workspace
146
+ * declares and the lock does not hold, or a locked one with a soul skipped.
147
+ * What a read did not record, it did not establish: a discovery with no `soulsUnread` record (whatever
148
+ * built it; discoverWorkspace and standaloneRepo always write one) says nothing about what it skipped,
149
+ * so `all` is "unrecorded" and every key is left unchecked.
150
+ */
151
+ export function soulsOffered(discovery) {
152
+ const keys = [...new Set(soulCandidates(discovery).map((c) => soulKeyOf(c.entry)))].sort();
153
+ const record = discovery?.soulsUnread;
154
+ const recorded = record !== null && typeof record === "object" && ["members", "external", "packages", "unlocked"].every((k) => Array.isArray(record[k]));
155
+ const skipped = recorded ? record : {};
156
+ const standalone = discovery?.standalone === true;
157
+ const unconfirmed = !standalone && (discovery?.members || []).some((m) => !m.confirmed);
158
+ const packages = {};
159
+ for (const id of skipped.unlocked || []) packages[id] = "package-unlocked";
160
+ for (const id of skipped.packages || []) packages[id] = "package-soul-unread";
161
+ return {
162
+ keys,
163
+ unread: {
164
+ all: standalone && discovery.standaloneReason !== "explicit" ? "standalone" : recorded ? null : "unrecorded",
165
+ bare: unconfirmed ? "member-unconfirmed" : (skipped.members?.length || skipped.external?.length) ? "soul-unread" : null,
166
+ packages,
167
+ },
168
+ };
169
+ }
170
+
171
+ /** Find the soul named `name` in a discovery: confirmed members, external souls and package
172
+ * souls. A bare name must be unique across all three (else E_SOUL_AMBIGUOUS naming each
173
+ * qualified form); `<repo>/<soul>` names a member (its key, a key suffix or its member name)
174
+ * or an external source, `<package>/<soul>` a package soul. */
137
175
  export function findSoulEntry(discovery, name) {
138
176
  const hits = soulCandidates(discovery).filter((c) => c.matches(name)).map((c) => c.entry);
139
177
  if (hits.length === 0) throw err("E_SOUL_UNKNOWN", `no soul ${JSON.stringify(name)} among the confirmed members, external souls or package souls of this workspace`, { name, members: (discovery.members || []).filter((m) => m.confirmed).map((m) => m.key), packages: [...new Set((discovery.packageSouls || []).map((s) => s.package))].sort() });
@@ -188,6 +226,20 @@ export async function liveTeams(home, meta, { remoteOptions, remote } = {}) {
188
226
  }
189
227
  }
190
228
 
229
+ /**
230
+ * For `session start|restart --reselect-launch`: what the home's launch layers need of the workspace
231
+ * (lib/core.mjs homeLaunchLayers `offered`) to say which keys of souls.launch name no soul. The workspace
232
+ * is read only when `needed` (the home's soul has no entry of its own and souls.launch holds a key
233
+ * besides "*"); otherwise → null and nothing is read. A read that fails throws its own error: a
234
+ * selection that could not check those keys does not go on.
235
+ */
236
+ export async function homeSoulsOffered(home, { needed, remoteOptions, remote } = {}) {
237
+ if (!needed) return null;
238
+ const deployment = dirname(dirname(dirname(dirname(resolvePath(home)))));
239
+ const found = loadLocal(deployment);
240
+ return soulsOffered(await discoverOrStandalone(found.local, { lock: readLockIfPresent(deployment), deployment, remoteOptions, remote }));
241
+ }
242
+
191
243
  /** The per-commit soul cache under an agent directory: `<agentDir>/souls/<commit12>/`.
192
244
  * Each entry is IMMUTABLE once written (fetched to staging, renamed in) and is never
193
245
  * removed by the kernel — a running instance records its own commit's directory
@@ -515,8 +567,9 @@ export async function prepareInstance(contextDir, soulName, { spawn = {}, remote
515
567
  const disabled = disabledEntry(local, soulEntry);
516
568
  if (disabled !== null) throw err("E_SOUL_DISABLED", `soul ${qualifiedSoulName(soulEntry)} is disabled on this machine (oats-local.yaml souls.disabled: ${disabled}) — remove it from that list to spawn it here`, { name: soulEntry.name, qualifiedName: qualifiedSoulName(soulEntry), entry: disabled });
517
569
  const resolution = await resolveSoul(discovery, soulEntry, { local, lock, spawn, remoteOptions, remote });
518
- // The launch layers a new selection reads (feature launch-preference): souls.launch, the soul's own launch.
519
- const launch = launchLayers({ definition: soulEntry.definition, entry: soulEntry, key: soulKeyOf(soulEntry), local });
570
+ // The launch layers a new selection reads (feature launch-preference): souls.launch, the soul's own launch,
571
+ // and, from this read of the workspace, the keys of souls.launch that name no soul it offers.
572
+ const launch = launchLayers({ definition: soulEntry.definition, entry: soulEntry, key: soulKeyOf(soulEntry), local, offered: soulsOffered(discovery) });
520
573
  return { local, deployment, lock, discovery, soulEntry, resolution, remoteOptions, spawn, launch };
521
574
  }
522
575