@awebai/oats 0.67.1 → 0.68.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 (60) hide show
  1. package/bin/oats.mjs +112 -16
  2. package/docs/capabilities.md +54 -5
  3. package/docs/capability-manifest.schema.json +4 -0
  4. package/docs/design/2026-10-22-module-upgrade.md +192 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +248 -9
  7. package/docs/desktop.md +278 -61
  8. package/docs/first-team.md +5 -3
  9. package/docs/implementation.md +42 -3
  10. package/docs/integrations.md +16 -4
  11. package/docs/knowledge.md +44 -27
  12. package/docs/layers.md +2 -2
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-notes/v0.68.0.md +504 -0
  16. package/docs/servers.md +6 -1
  17. package/docs/souls-and-instances.md +38 -3
  18. package/docs/tui.md +625 -223
  19. package/docs/upgrading.md +62 -6
  20. package/docs/workspaces.md +2 -2
  21. package/lib/capability-contract.mjs +6 -5
  22. package/lib/core.mjs +222 -38
  23. package/lib/instance-events.mjs +1 -1
  24. package/lib/instance-resolution.mjs +5 -5
  25. package/lib/instance-upgrade.mjs +1445 -0
  26. package/lib/materialize.mjs +225 -78
  27. package/lib/servers.mjs +11 -7
  28. package/lib/upgrade-state.mjs +101 -0
  29. package/lib/workspace.mjs +4 -1
  30. package/lib/worktree.mjs +103 -12
  31. package/package-catalog.json +5 -4
  32. package/package.json +1 -1
  33. package/packages/client/cli-adapter.mjs +15 -1
  34. package/packages/client/cli-locator.mjs +2 -2
  35. package/packages/client/deployment-panel.mjs +6 -2
  36. package/packages/client/keymap.mjs +89 -45
  37. package/packages/client/keys-file.mjs +9 -5
  38. package/packages/client/panel-views.mjs +16 -3
  39. package/packages/client/spawn-naming.mjs +7 -6
  40. package/packages/client/spawn-preview-cli.mjs +37 -1
  41. package/packages/client/spawn-preview-contract.mjs +35 -0
  42. package/packages/client/spawn-preview.mjs +35 -2
  43. package/packages/client/team-members.mjs +4 -1
  44. package/packages/client/workspace-step.mjs +25 -0
  45. package/packages/tui/README.md +5 -5
  46. package/packages/tui/lib/actions.mjs +51 -27
  47. package/packages/tui/lib/client.mjs +3 -2
  48. package/packages/tui/lib/config.mjs +4 -4
  49. package/packages/tui/lib/main.mjs +27 -13
  50. package/packages/tui/lib/model.mjs +132 -19
  51. package/packages/tui/lib/store.mjs +343 -68
  52. package/packages/tui/lib/term/keys.mjs +5 -3
  53. package/packages/tui/lib/term/kitty.mjs +28 -10
  54. package/packages/tui/lib/term/screen.mjs +15 -6
  55. package/packages/tui/lib/term/through.mjs +33 -28
  56. package/packages/tui/lib/views/frame.mjs +88 -109
  57. package/packages/tui/lib/views/help.mjs +56 -34
  58. package/packages/tui/lib/views/instances.mjs +4 -2
  59. package/packages/tui/lib/views/workspaces.mjs +55 -0
  60. package/skills/oats-getting-started/SKILL.md +92 -43
package/lib/core.mjs CHANGED
@@ -50,12 +50,13 @@ import { attachSessionTarget, requireDetachKey } from "./session-viewer.mjs";
50
50
  import { createSessionPaneInspector, inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
51
51
  import { appendEvent, incarnationOf, liveWaiting, recordStartBoundary, retireRefusedReason } from "./instance-events.mjs";
52
52
  import { killGroup } from "./process-group.mjs";
53
- import { NAMING_TIMEOUT_MS, suggestInstanceName } from "./instance-naming.mjs";
53
+ import { NAMING_CALLS, NAMING_TIMEOUT_MS, suggestInstanceName } from "./instance-naming.mjs";
54
54
  import { interruptExitStatus, isStartToken, originRemoteOf, runWorktreeHooks, selfIdentity, processLiveness, processStartToken, signalGuard, terminateRecordedGroup, treeStillThere, unknownGroupNote, unverifiedGroupWarning, worktreeHooksOf } from "./worktree-hooks.mjs";
55
55
  import { CLAIM_WAIT_MS, acquireClaim, claimUnavailable, claimUnheld, claimWrite, readClaim, releaseClaim, removeGoneClaim, shownHolder, unwritableCode } from "./claim.mjs";
56
56
  import { isInstant as isInstantString, readRetireState } from "./retire-state.mjs";
57
57
  import { captureLoginEnvironment } from "./login-environment.mjs";
58
58
  import { kernelNode } from "./stable-node.mjs";
59
+ import { assertNoPartialUpgrade, packageUpgradeDrift, upgradeCleanupWarnings, upgradeMutexRetry, UPGRADE_RECEIPT_NAME_RE } from "./upgrade-state.mjs";
59
60
 
60
61
  import { oatsError, afterEndedSteps, afterFirstEffect, asKernelError, BEFORE_EFFECT_CODES, checkHolderByHand, errorCause, ifItDoesNotEnd, isAnswerCode, isKernelCode, kernelCode, lifecycleBusy, nothingAfter, reportDefect, OWN_NAME_FAILURES, OWN_START_REMEDY, herdrInstanceBusy, herdrInstanceRemoved, herdrSettingRemoved, HERDR_REMOVED } from "./errors.mjs";
61
62
  import { envRows, recordedTeams, teamsEnv } from "./teams.mjs";
@@ -70,7 +71,7 @@ async function plannedSkillsDefault(prepared) { const m = await import("./instan
70
71
  // (manifest, settings, origin, trust; no skills/inject since the copies are not
71
72
  // there yet) and REBUILT after materialize against what actually landed. Static
72
73
  // import: instance-resolution.mjs does not depend on core.mjs (no cycle).
73
- import { cloneRemoteFor, resolutionContractWarnings, toCapabilityRows, verifyMemberClone } from "./instance-resolution.mjs";
74
+ import { cloneRemoteFor, deploymentLock, resolutionContractWarnings, toCapabilityRows, verifyMemberClone } from "./instance-resolution.mjs";
74
75
  import { GIT_FETCH_TIMEOUT_MS, GIT_TIMEOUT_MS, gitEnv } from "./remote.mjs";
75
76
  import { loadLocal } from "./workspace.mjs";
76
77
  import { parseConfigData } from "./config-data.mjs";
@@ -1146,8 +1147,8 @@ function plannedCapabilityRows(resolution) {
1146
1147
  * `node <abs script> <args>`, exactly as `manifestHookCommands` renders a classic
1147
1148
  * capability. The script must exist inside the module's copy under
1148
1149
  * <home>/.oats/modules/<cap>/ — a path escaping it is a manifest defect. Only
1149
- * the events the kernel approves (soul-scaffold, spawn, retire, launch, worktree) are kept. */
1150
- function materializedHookCommands(row, home) {
1150
+ * the events the kernel approves (soul-scaffold, spawn, retire, launch, worktree, upgrade) are kept. */
1151
+ export function materializedHookCommands(row, home) {
1151
1152
  const out = {};
1152
1153
  const moduleDir = row.dir || join(home, ".oats", "modules", row.id);
1153
1154
  for (const [event, spec] of Object.entries(row.hooks || {})) {
@@ -3249,6 +3250,16 @@ export function kernelBin() { return realpathSync(join(PKG_ROOT, "bin", "oats.mj
3249
3250
  /** Where a home's `oats` lives: first on its harness's PATH, so plain `oats` inside an instance is
3250
3251
  * the kernel that launched it, whatever other `oats` the host's PATH finds first. */
3251
3252
  export const kernelShimDir = (home) => join(home, ".oats", "bin");
3253
+ /** Inspect existing shim parents without following them or creating anything.
3254
+ * Receipt fences must preserve this refusal for an unsafe module root. */
3255
+ function assertKernelShimParents(home) {
3256
+ for (const path of [join(home, ".oats"), kernelShimDir(home)]) {
3257
+ let stat;
3258
+ try { stat = lstatSync(path); }
3259
+ catch (error) { if (error.code === "ENOENT") return; throw error; }
3260
+ if (!stat.isDirectory()) throw oatsError("E_LAUNCH_SHIM", `cannot write the kernel shim ${join(kernelShimDir(home), "oats")}: ${path} is ${stat.isSymbolicLink() ? "a symbolic link" : "not a directory"}; nothing was started`);
3261
+ }
3262
+ }
3252
3263
  /** Write <home>/.oats/bin/oats, a symlink to this kernel's CLI, replacing any shim a previous
3253
3264
  * launch (perhaps by another kernel) left: built aside, then renamed over. `.oats` and `.oats/bin`
3254
3265
  * must be directories of the home itself: a link there would carry the write outside the home.
@@ -3259,6 +3270,7 @@ export function writeKernelShim(home) {
3259
3270
  let target, aside;
3260
3271
  try {
3261
3272
  target = kernelBin();
3273
+ assertKernelShimParents(home);
3262
3274
  for (const d of [join(home, ".oats"), dir]) {
3263
3275
  let st;
3264
3276
  try { st = lstatSync(d); }
@@ -3735,6 +3747,72 @@ function callerSpawnOrigin(root) {
3735
3747
  return matches.some((m) => realpathSync(m.home) === canonical) ? "instance" : "operator";
3736
3748
  } catch { return "operator"; }
3737
3749
  }
3750
+ /** A soul name as a spawn names it, by shape only: a slug, after an optional `<package or member>/`
3751
+ * and an optional `<package>--` (lib/instance-naming.mjs soulRole reads its role from the same). */
3752
+ const SOUL_NAME_SHAPE = /^(?:[A-Za-z0-9][A-Za-z0-9._-]*(?:\/[A-Za-z0-9][A-Za-z0-9._-]*)*\/)?(?:[a-z0-9]+(?:-[a-z0-9]+)*--)?[a-z0-9]+(?:-[a-z0-9]+)*$/;
3753
+ /** `oats instance suggest-name` (feature instance-suggest-name, awebai/oats#1490 §2): the name a spawn
3754
+ * of `soul` would get by `--suggest-name`, chosen on THIS machine for a spawn that may land on another.
3755
+ * `soul` is only a name (it gives the role) and needn't exist here: nothing resolves it. It resolves no
3756
+ * souls, members, lock or remote: it reads only this machine's launch configurations (the
3757
+ * oats-local.yaml in reach of `dir`) and the OATS tmux server's environment, writes nothing and
3758
+ * reserves no name. The name is not made unique: the host the spawn lands on owns uniqueness
3759
+ * (E_INSTANCE_NAME_TAKEN at its apply). The harness: `harness`, else the configuration's, else claude;
3760
+ * its executable and environment are what a spawn here would launch it with (`launchConfig`, else this
3761
+ * machine's default configuration for the harness), and the call is the preview's (lib/instance-
3762
+ * naming.mjs: its argv, isolation and bounds), the only process it starts. The model: `model`, else the
3763
+ * configuration's (`@native-default` for none; a list's first entry, with no catalogue probe). → Promise
3764
+ * of `{ name?, naming }`, `name` only when `naming.source` is "suggested". A naming failure is never an
3765
+ * error (an executable that is not there is `harness-failed`); bad arguments are. */
3766
+ export async function suggestSpawnName({ dir = process.cwd(), soul, task, harness: asked, model: askedModel, launchConfig: named } = {}) {
3767
+ if (typeof soul !== "string" || soul.length > 256 || !SOUL_NAME_SHAPE.test(soul)) throw oatsError("E_BAD_ARGS", `--soul ${JSON.stringify(soul)} is not a soul name (a slug, optionally qualified as <package>/<soul>)`);
3768
+ if (typeof task !== "string") throw oatsError("E_BAD_ARGS", "the task must be text");
3769
+ if (asked !== undefined && !LAUNCH_HARNESSES.includes(asked)) throw oatsError("E_BAD_ARGS", `--harness must be one of ${LAUNCH_HARNESSES.join("|")}`);
3770
+ if (askedModel !== undefined && (typeof askedModel !== "string" || !askedModel)) throw oatsError("E_BAD_ARGS", "--model needs a model id");
3771
+ let deployment = null;
3772
+ try { deployment = dirname(loadLocal(dir).path); } catch (e) { if (e?.code !== "E_LOCAL_MISSING") throw e; }
3773
+ const configs = deployment ? launchConfigsAt(deployment) : Object.create(null);
3774
+ let config = null;
3775
+ if (named !== undefined && named !== "none") {
3776
+ if (typeof named !== "string" || !Object.hasOwn(configs, named)) throw launchConfigUnknown({ name: named, from: "flag", at: "--launch-config" });
3777
+ config = configs[named];
3778
+ if (asked !== undefined && asked !== config.harness) throw oatsError("E_BAD_ARGS", `launch configuration ${named} runs ${config.harness}, not ${asked}: a named configuration is a unit; drop --harness or name another configuration`);
3779
+ }
3780
+ const harness = asked ?? config?.harness ?? "claude";
3781
+ if (named === undefined) config = harnessDefaultConfig(configs, harness);
3782
+ // Where a spawn here would look: the configuration's env, else the OATS tmux server's when one runs
3783
+ // (never started for this), else this process's; relative PATH entries from this process's directory.
3784
+ const launchEnv = launchEnvironment({ configEnv: config?.env, configName: config?.name, env: process.env, pane: () => previewPaneEnvironment({ deployment: deployment ?? dir }), cwd: process.cwd() });
3785
+ let bin = null, problem = null;
3786
+ const missing = missingLaunchEnvRefs(config?.env || {}, process.env);
3787
+ if (missing.length) problem = `launch configuration ${config.name} references ${missing.join(", ")}, not set in this environment`;
3788
+ else {
3789
+ try {
3790
+ const executable = resolveLaunchExecutable({ harness, declared: config?.executable, declaringDir: config?.source, contextDir: deployment ?? undefined, lookup: config?.executable?.includes("/") ? undefined : launchLookup(launchEnv) });
3791
+ if (!executable.path) problem = config?.executable ? `launch configuration ${config.name}: ${executable.missing}` : `${harness} is not installed on this machine (${executable.missing})`;
3792
+ else {
3793
+ const bad = checkLaunchExecutable(executable.path);
3794
+ if (bad) problem = config ? `launch configuration ${config.name}: ${bad}` : bad; else bin = executable.path;
3795
+ }
3796
+ } catch (e) { if (!isKernelCode(e?.code)) throw e; problem = e.message; }
3797
+ }
3798
+ // The model, read as a spawn reads it (resolveLaunchSelection) but with no catalogue probe: the naming
3799
+ // call is the only process this command starts. `@native-default` is none; a pi preference list names
3800
+ // its first entry (pi answers one it cannot use as harness-failed); another harness's list is
3801
+ // resolveModelPreference's, which starts nothing for it.
3802
+ const preference = askedModel ?? (typeof config?.model === "string" && config.model ? config.model : undefined);
3803
+ const firstEntry = (list) => list.split(",").map((m) => m.trim()).find(Boolean) ?? "";
3804
+ const namingModel = preference === undefined || preference === NATIVE_DEFAULT_MODEL ? null : (harness === "pi" ? firstEntry(preference) : resolveModelPreference(preference, harness)) || null;
3805
+ const seam = Number(process.env.OATS_TEST_NAMING_TIMEOUT_MS);
3806
+ const call = {
3807
+ soulName: soul, harness, bin, task, timeoutMs: seam > 0 ? seam : NAMING_TIMEOUT_MS,
3808
+ instanceModel: namingModel,
3809
+ env: () => launchEffectiveEnv({ base: process.env, configEnv: config?.env || {}, launch: launchEnv, harness }),
3810
+ taken: () => false,
3811
+ };
3812
+ // The call's own answers come first (no task, a harness with no naming call); then no executable.
3813
+ if (problem && task.trim() && Object.hasOwn(NAMING_CALLS, harness)) return { naming: { source: "numbered", reason: "harness-failed", message: `${harness} could not be run: ${problem}`, ms: 0 } };
3814
+ return suggestInstanceName(call);
3815
+ }
3738
3816
  export async function spawnInstanceAsync(root, agent, o = {}) {
3739
3817
  const it = spawnBody(root, agent, o);
3740
3818
  let step = it.next();
@@ -3827,19 +3905,19 @@ function* spawnBody(root, agent, o = {}) {
3827
3905
  }
3828
3906
  }
3829
3907
 
3830
- // --suggest-name (feature spawn-suggest-name, awebai/oats#1421 §3): a preview that also chooses the
3831
- // name, by a naming call through this launch's harness and executable, under its environment, after
3832
- // the preflight's probes and within its one budget (below, where the executable is known). Until
3833
- // then the preview proceeds with the numbered name, holding any refusal that is that name's own
3834
- // (`provisional`); a suggested name is then placed exactly as `--name <suggested>` is, so the
3908
+ // --suggest-name (features spawn-suggest-name, spawn-apply-suggest-name: awebai/oats#1421 §3,
3909
+ // #1490 §3): a spawn that also chooses the name, by a naming call through this launch's harness and
3910
+ // executable, under its environment, after the preflight's probes (below, where the executable is
3911
+ // known): a preview's within its one budget, an apply's within NAMING_TIMEOUT_MS. Until then the
3912
+ // spawn proceeds with the numbered name, holding any refusal that is that name's own
3913
+ // (`provisional`); a suggested name is then placed exactly as `--name <suggested>` is, so a
3835
3914
  // preview's instance, home, branch and decision are that preview's, and an apply with `--name
3836
3915
  // <instance> --expect-decision <revision>` matches it. Otherwise the numbered name stands, its held
3837
3916
  // refusal with it. `naming` says which, and why; a failed call is never an error.
3838
3917
  let naming, provisional;
3839
3918
  const suggesting = o.suggestName === true;
3840
- if (suggesting) {
3841
- if (o.preview !== true) throw oatsError("E_BAD_ARGS", "--suggest-name is a preview's: it chooses the name a spawn would get; pass --preview");
3842
- if (o.name !== undefined || o.purpose !== undefined || o.instance !== undefined) throw oatsError("E_BAD_ARGS", "--suggest-name chooses the name: it takes no --name or --purpose");
3919
+ if (suggesting && (o.name !== undefined || o.purpose !== undefined || o.instance !== undefined || o.expectDecision !== undefined)) {
3920
+ throw oatsError("E_BAD_ARGS", o.expectDecision !== undefined ? "--suggest-name chooses the name, and --expect-decision's decision already binds one: apply the previewed name with --name <instance> --expect-decision <revision>" : "--suggest-name chooses the name: it takes no --name or --purpose");
3843
3921
  }
3844
3922
  if (o.name !== undefined && (o.purpose !== undefined || o.instance !== undefined)) throw oatsError("E_BAD_ARGS", "name and purpose are mutually exclusive: --name is the exact instance name, --purpose derives <soul>-<purpose>");
3845
3923
  let instance;
@@ -4169,7 +4247,7 @@ function* spawnBody(root, agent, o = {}) {
4169
4247
  // no instance can be named stands in for the home: its `..` entries resolve as the home's do, and
4170
4248
  // nothing is inside either, so the executable and the probes are the ones the final home would get,
4171
4249
  // and the naming call runs that same executable.
4172
- const paneCwd = suggesting ? join(agent._dir, "instances", ".oats-suggest-name") : home;
4250
+ let paneCwd = suggesting ? join(agent._dir, "instances", ".oats-suggest-name") : home;
4173
4251
  const launchEnvOn = (pane, removed = []) => launchEnvironment({ configEnv: launchConfig?.env, configName: launchConfig?.name, removed, env: process.env, pane, cwd: paneCwd });
4174
4252
  const expectedEnv = launchEnvOn(launch ? () => expectedPaneEnvironment(tmuxSessionPlan, session, undefined, paneCwd) : NO_LAUNCH);
4175
4253
  // A launched harness is looked up where its pane will look it up (launchLookup): this is the
@@ -4213,14 +4291,15 @@ function* spawnBody(root, agent, o = {}) {
4213
4291
  return note ? `${checks.map(([what]) => what).join(", ")}: ${note}` : null;
4214
4292
  };
4215
4293
  const task = o.task ?? (o.taskFile ? readFileSync(o.taskFile, "utf8") : "");
4216
- // The naming call (#1421 §3): the probes have run, so it takes what is left of their budget (at most
4217
- // its own 20 s). Its time counts in the preflight's elapsedMs, but the preflight's status stays its
4218
- // checks': a call the budget ends is `naming.reason` "timeout", and the numbered preview it leaves is
4219
- // as confirmable as a plain one.
4294
+ // The naming call (#1421 §3): a preview's probes have run, so it takes what is left of their budget
4295
+ // (at most its own 20 s). Its time counts in the preflight's elapsedMs, but the preflight's status
4296
+ // stays its checks': a call the budget ends is `naming.reason` "timeout", and the numbered preview it
4297
+ // leaves is as confirmable as a plain one. An apply has no such budget: the call takes its own 20 s,
4298
+ // before anything is placed, and every later bound of the apply (hooks, the launch) starts after it.
4220
4299
  let suggested;
4221
4300
  if (suggesting) {
4222
4301
  const seam = Number(process.env.OATS_TEST_NAMING_TIMEOUT_MS), own = seam > 0 ? seam : NAMING_TIMEOUT_MS;
4223
- const left = preflightStarted + preflightBudgetMs - Date.now(), souls = deploymentSoulNames(root, o.prepared), homes = deploymentInstanceHomes(root);
4302
+ const left = o.preview === true ? preflightStarted + preflightBudgetMs - Date.now() : own, souls = deploymentSoulNames(root, o.prepared), homes = deploymentInstanceHomes(root);
4224
4303
  let windows;
4225
4304
  const suggestion = yield () => suggestInstanceName({
4226
4305
  soulName: agent.name, harness, bin, instanceModel: model || null, task, timeoutMs: Math.min(own, left),
@@ -4232,13 +4311,14 @@ function* spawnBody(root, agent, o = {}) {
4232
4311
  }
4233
4312
  if (o.preview === true) { preflight = { status: previewPreflightBudget?.exhausted ? "timeout" : "complete", budgetMs: preflightBudgetMs, elapsedMs: Date.now() - preflightStarted }; previewPreflightBudget = null; }
4234
4313
  // A suggested name is placed as `--name` places it (its shadow, its home); otherwise the numbered name
4235
- // keeps its own refusal.
4314
+ // keeps its own refusal. From here the home is known: an apply's launch reads its pane from there.
4236
4315
  if (suggested) {
4237
4316
  instance = suggested;
4238
4317
  const shadow = reverseShadow(instance);
4239
4318
  if (shadow) throw shadow;
4240
4319
  ({ home, homeReal, expectedHome } = place(instance));
4241
4320
  } else if (provisional) throw provisional;
4321
+ if (suggesting) paneCwd = home;
4242
4322
 
4243
4323
  if (existsSync(directoryRollbackPath(homeReal))) throw oatsError("E_WORK_INSPECTION_FAILED", `directory cleanup is still owed for ${home}; restore and retire the retained home before reusing its name`);
4244
4324
  // K6: everything a spawn decides is decided by here — and nothing has been
@@ -4367,7 +4447,8 @@ function* spawnBody(root, agent, o = {}) {
4367
4447
  if (holders.length > 1) {
4368
4448
  try { rmdirSync(home); } catch { /* empty by construction; leave it rather than recurse */ }
4369
4449
  const other = holders.find((h) => resolve(h) !== resolve(home)) ?? null;
4370
- if (o.name !== undefined) throw Object.assign(oatsError("E_INSTANCE_NAME_TAKEN", `instance name "${instance}" was taken by a concurrent spawn in this deployment (${other}); nothing was created by this call — pick another --name`), { instance, home: other });
4450
+ // A suggested name is refused as the same name given with --name would be.
4451
+ if (o.name !== undefined || suggested) throw Object.assign(oatsError("E_INSTANCE_NAME_TAKEN", `instance name "${instance}" was taken by a concurrent spawn in this deployment (${other}); nothing was created by this call — ${suggested ? "spawn again to have another name suggested" : "pick another --name"}`), { instance, home: other });
4371
4452
  throw Object.assign(oatsError("E_PLACEMENT_TAKEN", `${instance} was taken by a concurrent spawn of another soul (${other}); nothing was created by this call — preview again`), { instance, home: other });
4372
4453
  }
4373
4454
  }
@@ -5193,7 +5274,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
5193
5274
  meta.spawnCompleted = true;
5194
5275
  writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n"); // a kernel-owned field: the baseline fingerprint ignores it
5195
5276
  }
5196
- return deliver({ ...meta, ...(o.expectDecision !== undefined ? { replayed: false } : {}), ...(worktreeRun ? { worktreeHooks: worktreeRun.receipt } : {}), launch: redactLaunchRecipe(recipe), command: redactLaunchCommand(cmdline), attach: launch ? `tmux -S ${shellWord(meta.tmux.socket)} attach -t ${shellWord(session)}` : `oats session attach --home ${shellWord(home)}`, warnings: spawnWarnings.length ? spawnWarnings : undefined });
5277
+ return deliver({ ...meta, ...(o.expectDecision !== undefined ? { replayed: false } : {}), ...(worktreeRun ? { worktreeHooks: worktreeRun.receipt } : {}), launch: redactLaunchRecipe(recipe), command: redactLaunchCommand(cmdline), attach: launch ? `tmux -S ${shellWord(meta.tmux.socket)} attach -t ${shellWord(session)}` : `oats session attach --home ${shellWord(home)}`, warnings: spawnWarnings.length ? spawnWarnings : undefined, ...(naming ? { naming } : {}) });
5197
5278
  } catch (error) {
5198
5279
  if (promptDispatched) {
5199
5280
  // Once a launch that engages the confirmation was dispatched, uncertainty retains all effects.
@@ -5863,7 +5944,7 @@ function retirementBaselineFile(identity) {
5863
5944
  }
5864
5945
 
5865
5946
  /** Where a spawn writes a home's receipt: keyed by its canonical identity. */
5866
- function retirementBaselinePath(home) {
5947
+ export function retirementBaselinePath(home) {
5867
5948
  return retirementBaselineFile(receiptHomeIdentity(home));
5868
5949
  }
5869
5950
 
@@ -5890,7 +5971,7 @@ function legacyRetirementBaselinePath(home) {
5890
5971
  * directory-work disagreement is E_WORK_INSPECTION_FAILED; and a start's record rewrites the stale
5891
5972
  * file, as a kernel before 0.49.0 already does when a caller's spelling matches an earlier
5892
5973
  * incarnation's. */
5893
- function findRetirementBaseline(home) {
5974
+ export function findRetirementBaseline(home) {
5894
5975
  const canonical = retirementBaselinePath(home);
5895
5976
  if (existsSync(canonical)) return canonical;
5896
5977
  const legacy = legacyRetirementBaselinePath(home);
@@ -6113,7 +6194,7 @@ function treeDigests(root, { excludeRoot = new Set(), excludePaths = [], instanc
6113
6194
  const childRel = rel.length ? Buffer.concat([rel, PATH_SEPARATOR_BYTES, nameBytes]) : nameBytes;
6114
6195
  if ((!relText && excludeRoot.has(name)) || (excluded.size && excluded.has(childRel.toString("hex")))) continue;
6115
6196
  const childRelText = relText ? join(relText, name) : name;
6116
- const storedPassesOver = instanceHome && ((!relText && (KERNEL_HOME_RECEIPTS.has(name) || KERNEL_HOME_RECEIPT_PATTERNS.some((p) => p.test(name)))) || HARNESS_HOME_SETTINGS.has(childRelText) || KERNEL_HOME_STATE_DIRS.has(childRelText));
6197
+ const storedPassesOver = instanceHome && ((!relText && (KERNEL_HOME_RECEIPTS.has(name) || KERNEL_HOME_RECEIPT_PATTERNS.some((p) => p.test(name)))) || HARNESS_HOME_SETTINGS.has(childRelText) || KERNEL_HOME_STATE_DIRS.has(childRelText) || (relText === ".oats" && (UPGRADE_RECEIPT_NAME_RE.test(name) || /^\.staging-upgrade-[a-f0-9]+$/.test(name))));
6117
6198
  if (storedPassesOver && !x) continue;
6118
6199
  const on = storedOn && !storedPassesOver;
6119
6200
  const s = on ? outerS : null, v = on ? outerV : null;
@@ -6656,7 +6737,79 @@ export function retirementRecoveryFacts(home) {
6656
6737
  const baseline = readJsonOrUndefined(findRetirementBaseline(home));
6657
6738
  return { recoveryRoot: retirementRecoveryRoot(dirname(home)), disposableHome: retirementBaselineValid(baseline, home) ? baselineDisposableHome(baseline) : [] };
6658
6739
  }
6659
- function writeRetirementBaseline(home, work, mode, capabilities, runtime, { exclusive = false, incarnationId, executionBinding } = {}) {
6740
+ /** A projection is local to one fingerprint, never a persistent exclusion. */
6741
+ function retirementTransientFiles(home, transientHomePaths) {
6742
+ if (!Array.isArray(transientHomePaths) || transientHomePaths.some(path => typeof path !== "string" || !path || isAbsolute(path) || /[\x00*?\[\]{}]/.test(path) || path.split(/[\/\\]/).some(part => !part || part === "." || part === ".."))) throw oatsError("E_BAD_ARGS", "retirement baseline transientHomePaths must be exact relative paths without globs");
6743
+ return transientHomePaths.map(path => {
6744
+ let at = home;
6745
+ const parts = path.split(/[\/\\]/);
6746
+ try {
6747
+ for (const component of parts.slice(0, -1)) {
6748
+ at = join(at, component);
6749
+ if (!lstatSync(at).isDirectory()) throw new Error("not a real parent directory");
6750
+ }
6751
+ at = join(at, parts.at(-1));
6752
+ const stat = lstatSync(at);
6753
+ if (!stat.isFile()) throw new Error("not a regular file");
6754
+ return { relative: pathBytes(join(...parts)), path: at, stat };
6755
+ } catch { throw oatsError("E_WORK_INSPECTION_FAILED", `retirement baseline transient path ${path} must exist as a regular file inside ${home}`); }
6756
+ });
6757
+ }
6758
+
6759
+ function assertRetirementTransientsUnchanged(transientFiles) {
6760
+ for (const file of transientFiles) {
6761
+ let now;
6762
+ try { now = lstatSync(file.path); } catch { /* refused below */ }
6763
+ if (!now?.isFile() || now.dev !== file.stat.dev || now.ino !== file.stat.ino) throw oatsError("E_WORK_INSPECTION_FAILED", `retirement baseline transient file changed while projecting ${file.path}`);
6764
+ }
6765
+ }
6766
+
6767
+ /** Upgrade may adjust the fingerprint only while preserving a valid independent
6768
+ * baseline. Missing authority is never reconstructed from mutable home metadata. */
6769
+ function upgradeRetirementBaseline(home) {
6770
+ const path = findRetirementBaseline(home);
6771
+ const baseline = readJsonOrUndefined(path);
6772
+ const digestVersion = baselineDigestVersion(baseline);
6773
+ if (!retirementBaselineValid(baseline, home) || digestVersion === undefined || typeof baseline.homeFingerprint !== "string" || !/^sha256:[a-f0-9]{64}$/.test(baseline.homeFingerprint)) {
6774
+ throw oatsError("E_UPGRADE_INTEGRITY", `the independent retirement baseline at ${path} is missing or invalid; restore the original baseline or respawn the instance before upgrading; no retirement authority was replaced`);
6775
+ }
6776
+ return { path, baseline, digestVersion };
6777
+ }
6778
+
6779
+ function upgradeHomeFingerprint(home, baseline, digestVersion, transientHomePaths) {
6780
+ const transientFiles = retirementTransientFiles(home, transientHomePaths);
6781
+ // Retire resolves exclusions from the independent spawn record and verified
6782
+ // extra trees, never from the newly installed capability manifests.
6783
+ const extraTrees = extraWorktreesOf(home);
6784
+ const homeExclusions = resolveHomeExclusions(home, baselineDisposableHome(baseline), extraTrees);
6785
+ const digest = storedTreeDigest(home, digestVersion, { excludeRoot: homeExclusions.excludeRoot, excludePaths: transientFiles.map(file => file.relative), instanceHome: true });
6786
+ assertRetirementTransientsUnchanged(transientFiles);
6787
+ return digest;
6788
+ }
6789
+
6790
+ /** Read before upgrade creates previous copies or staging: the same stored
6791
+ * digest and exclusions retire compares with the original spawn baseline. */
6792
+ export function retirementHomeChanged(home, { transientHomePaths = [] } = {}) {
6793
+ const { baseline, digestVersion } = upgradeRetirementBaseline(home);
6794
+ return baseline.homeFingerprint !== upgradeHomeFingerprint(home, baseline, digestVersion, transientHomePaths);
6795
+ }
6796
+
6797
+ /** A dirty home retains its original baseline byte for byte, so old kernels
6798
+ * also preserve its pre-upgrade edits. A clean home's authorized module move
6799
+ * changes only homeFingerprint; work, exclusion and runtime authority stay as
6800
+ * recorded, including a legacy digest version or its absence. */
6801
+ export function rebaseUpgradeRetirementBaseline(home, { homeChangedSinceSpawn } = {}) {
6802
+ if (typeof homeChangedSinceSpawn !== "boolean") throw oatsError("E_BAD_ARGS", "upgrade baseline rebase needs the pre-upgrade homeChangedSinceSpawn boolean");
6803
+ const { path, baseline, digestVersion } = upgradeRetirementBaseline(home);
6804
+ if (homeChangedSinceSpawn) return;
6805
+ const homeFingerprint = upgradeHomeFingerprint(home, baseline, digestVersion, [".oats-start.lock"]);
6806
+ writeJsonAtomic(path, { ...baseline, homeFingerprint }, 0o600);
6807
+ }
6808
+
6809
+ /** Project transaction-owned temporary files out of this baseline only. Later
6810
+ * fingerprints still hold them: a stale mutex is work to preserve, not invisible state. */
6811
+ export function writeRetirementBaseline(home, work, mode, capabilities, runtime, { exclusive = false, incarnationId, executionBinding, transientHomePaths = [] } = {}) {
6812
+ const transientFiles = retirementTransientFiles(home, transientHomePaths);
6660
6813
  if (mode === "directory") assertDirectoryRoots(home);
6661
6814
  const isWorktree = mode === "worktree";
6662
6815
  const statusBytes = isWorktree && existsSync(work) ? worktreeStatusBytes(work) : Buffer.alloc(0);
@@ -6668,7 +6821,7 @@ function writeRetirementBaseline(home, work, mode, capabilities, runtime, { excl
6668
6821
  ...(incarnationId ? { incarnationId, executionBinding } : {}),
6669
6822
  ...(mode === "directory" ? { directoryWork: true, directoryRoots: { home: directoryRootIdentity(home), work: directoryRootIdentity(work) } } : {}),
6670
6823
  home: canonicalHomePath(home),
6671
- homeFingerprint: storedTreeDigest(home, BASELINE_DIGEST_VERSION, { excludeRoot: resolveHomeExclusions(home, disposableHome).excludeRoot, instanceHome: true }),
6824
+ homeFingerprint: storedTreeDigest(home, BASELINE_DIGEST_VERSION, { excludeRoot: resolveHomeExclusions(home, disposableHome).excludeRoot, excludePaths: transientFiles.map(file => file.relative), instanceHome: true }),
6672
6825
  disposableReceipts,
6673
6826
  disposableHome,
6674
6827
  generatedWorkFingerprint: isWorktree ? generatedWorkDigest(work, statusBytes, disposableReceipts.map((r) => r.root)) : undefined,
@@ -6677,9 +6830,14 @@ function writeRetirementBaseline(home, work, mode, capabilities, runtime, { excl
6677
6830
  ...(runtime?.tmux ? { tmux: { session: runtime.tmux.session, window: runtime.tmux.window, ...(runtime.tmux.socket ? { socket: resolve(runtime.tmux.socket) } : {}) } } : {}),
6678
6831
  },
6679
6832
  };
6833
+ assertRetirementTransientsUnchanged(transientFiles);
6680
6834
  const path = retirementBaselinePath(home);
6681
6835
  mkdirSync(dirname(path), { recursive: true });
6682
- writeFileSync(path, JSON.stringify(baseline, null, 2) + "\n", { mode: 0o600, ...(exclusive ? { flag: "wx" } : {}) });
6836
+ // Replacements must leave readable independent session authority even if a
6837
+ // short write or SIGKILL interrupts publication. Spawn's exclusive option
6838
+ // still creates directly with wx and never replaces an existing receipt.
6839
+ if (exclusive) writeFileSync(path, JSON.stringify(baseline, null, 2) + "\n", { mode: 0o600, flag: "wx" });
6840
+ else writeJsonAtomic(path, baseline, 0o600);
6683
6841
  }
6684
6842
 
6685
6843
  /** The repositories a recovery rebuilds from a clone, under a worktree at
@@ -6790,7 +6948,7 @@ const unreadableBecause = (e) => e?.code === "ENOENT" ? "it is missing" : String
6790
6948
 
6791
6949
  /** Session control uses the independent endpoint receipt. The receipt and the record are read
6792
6950
  * apart, so that a failure names the file that failed (#1092): one `catch` over both cannot know. */
6793
- function instanceSessionTarget(home) {
6951
+ function instanceSessionTarget(home, { absentMeta } = {}) {
6794
6952
  if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session needs an absolute instance home");
6795
6953
  home = realPathOrNearest(home);
6796
6954
  refuseHerdrHome(home);
@@ -6801,7 +6959,12 @@ function instanceSessionTarget(home) {
6801
6959
  throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read session receipt for ${home} at ${receiptPath}: ${unreadableBecause(e)}`);
6802
6960
  }
6803
6961
  try { meta = JSON.parse(readFileSync(recordPath, "utf8")); }
6804
- catch (e) { throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read ${recordPath}: ${unreadableBecause(e)}`); }
6962
+ catch (e) {
6963
+ // Upgrade may be between the two metadata renames. Its durable journal
6964
+ // supplies only the missing record; the independent endpoint still decides.
6965
+ if (e.code === "ENOENT" && isPlainObject(absentMeta)) meta = absentMeta;
6966
+ else throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read ${recordPath}: ${unreadableBecause(e)}`);
6967
+ }
6805
6968
  // A record that is JSON and no object gives no endpoint to compare the receipt with.
6806
6969
  if (!isPlainObject(meta)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read ${recordPath}: it holds no JSON object`);
6807
6970
  const authority = baseline.version === RETIRE_BASELINE_VERSION && receiptRecordsHome(baseline, canonicalHomePath(home)) && runtimeAuthorityOf(baseline);
@@ -6811,9 +6974,9 @@ function instanceSessionTarget(home) {
6811
6974
  }
6812
6975
 
6813
6976
  /** `io` (`{ exec }`) is the tmux and process-table seam inspectSessionTarget takes. */
6814
- export function inspectInstanceSession(home, { io } = {}) {
6977
+ export function inspectInstanceSession(home, { io, absentMeta } = {}) {
6815
6978
  if (typeof home === "string" && isAbsolute(home) && !existsSync(home)) return { home: realPathOrNearest(home), backend: null, present: false, state: "stopped", running: false, waitingOnYou: null };
6816
- const s = instanceSessionTarget(home);
6979
+ const s = instanceSessionTarget(home, { absentMeta });
6817
6980
  if (!s.target) return { home: s.home, backend: null, present: false, state: "not-launched", running: false, waitingOnYou: null };
6818
6981
  let observed;
6819
6982
  try { observed = inspectSessionTarget(s.target, io, { includeSize: true }); }
@@ -7389,6 +7552,7 @@ export function prepareLaunchHooks({ frozen, harness, resolvedCfg, home, meta, c
7389
7552
  if (!trust.trusted) throw oatsError("E_LAUNCH_PREPARATION", `${p.id} was part of this home's launch at spawn but is no longer trusted in the scope (${trust.reason || "not trusted"}); respawn the instance; nothing was stopped`);
7390
7553
  const hooks = manifestHookCommands(manifest);
7391
7554
  if (hooks.launch) withLaunchHook.push({ id: p.id, capability: p.id, manifest, layer: p.contribution?.layer ?? p.binding?.layer ?? manifest.layer ?? null, level: p.contribution?.level ?? p.binding?.level ?? null, settings: p.settings, settingsOrigins: p.settingsOrigins, hooks, trust, environment: [...(manifest.environment || [])], environmentNamespaces: [...(manifest.environmentNamespaces || [])], missingRequires: [] });
7555
+
7392
7556
  }
7393
7557
  const aware = withLaunchHook.filter((c) => c.manifest.launchPreview === true);
7394
7558
  const unaware = withLaunchHook.filter((c) => c.manifest.launchPreview !== true);
@@ -7499,6 +7663,8 @@ export function startInstanceSession(home, o = {}) {
7499
7663
  refuseHerdrHome(realPathOrNearest(home));
7500
7664
  if (readJsonOrUndefined(join(realPathOrNearest(home), ".oats-start-pending.json"))?.target?.backend === "herdr") throw herdrInstanceRemoved(basename(realPathOrNearest(home)));
7501
7665
  if (existsSync(directoryRollbackPath(home))) throw oatsError("E_INSTANCE_RETIRING", `${home} has retained directory cleanup; restore and retire it before starting anything there`);
7666
+ assertKernelShimParents(home);
7667
+ assertNoPartialUpgrade(realPathOrNearest(home));
7502
7668
  const directoryGuard = sessionDirectoryGuard(home);
7503
7669
  {
7504
7670
  let metadata; try { metadata = parseStrictJson(readPortableBytes(join(home, "instance.json"))); } catch { /* the receipt checks below report unreadable metadata */ }
@@ -7526,6 +7692,8 @@ export function startInstanceSession(home, o = {}) {
7526
7692
  // spawned records no modules, and there is no scope configuration left to
7527
7693
  // re-resolve it against. Retire still works on it.
7528
7694
  if (!isWorkspaceHome(readMeta())) throw preWorkspaceHome(realHome, "nothing was started");
7695
+ let drift; // Read under the start lock, so an upgrade cannot swap modules between reads.
7696
+ let cleanupWarnings = [];
7529
7697
  // A missing socket file is a stopped server only when no process works in this home (#624): its
7530
7698
  // check, for a recorded session and for the OATS server lookup. A failed read of a recorded session
7531
7699
  // is `{ stopped: true }` when its server is gone (or its socket file is missing and that check
@@ -7575,14 +7743,30 @@ export function startInstanceSession(home, o = {}) {
7575
7743
  next.tmux = { session: target.session, window: target.window, socket: resolve(target.socket) };
7576
7744
  writeJsonAtomic(metaPath, next);
7577
7745
  if (clearPending) { checkRoots(); rmSync(pendingPath, { force: true }); }
7578
- return { instance: meta.instance, agent: meta.agent, home: realHome, harness: next.harness, backend: "tmux", model: model ?? null, launchConfig: next.launch?.launchConfig ?? null, yolo: next.yolo ?? null, target, startedAt, restartCount: next.restartCount, reused, warnings: [], ...(launchPrompts ? { launchPrompts } : {}), ...(nativeRecordId ? { nativeRecordId } : {}), ...(stop ? { stop } : {}) };
7746
+ return { ...(drift.length ? { drift } : {}), instance: meta.instance, agent: meta.agent, home: realHome, harness: next.harness, backend: "tmux", model: model ?? null, launchConfig: next.launch?.launchConfig ?? null, yolo: next.yolo ?? null, target, startedAt, restartCount: next.restartCount, reused, warnings: cleanupWarnings, ...(launchPrompts ? { launchPrompts } : {}), ...(nativeRecordId ? { nativeRecordId } : {}), ...(stop ? { stop } : {}) };
7579
7747
  };
7580
7748
  try { mkdirSync(lock); }
7581
7749
  catch (e) {
7582
- if (e.code === "EEXIST") throw oatsError("E_SESSION_START_BUSY", `another start of ${basename(realHome)} is in progress (${lock}); if no start is running, remove that directory and retry`);
7750
+ if (e.code === "EEXIST") {
7751
+ const retry = upgradeMutexRetry(realHome);
7752
+ if (retry) throw oatsError("E_SESSION_START_BUSY", `a package upgrade of ${basename(realHome)} holds the start mutex (${lock}); nothing was stopped or started. Retry ${retry} to finish the upgrade before starting`);
7753
+ throw oatsError("E_SESSION_START_BUSY", `another start of ${basename(realHome)} is in progress (${lock}); if no start is running, remove that directory and retry`);
7754
+ }
7583
7755
  throw e;
7584
7756
  }
7585
7757
  try {
7758
+ // Upgrade holds this same start lock while applying; re-read after taking it.
7759
+ assertNoPartialUpgrade(realHome);
7760
+ cleanupWarnings = upgradeCleanupWarnings(realHome);
7761
+ // Compare the frozen package copies with the local deployment lock; starting never moves them.
7762
+ const driftDeployment = dirname(dirname(dirname(dirname(realHome))));
7763
+ let driftLock;
7764
+ try { driftLock = deploymentLock(driftDeployment); }
7765
+ catch (error) {
7766
+ // Drift is advisory; an unreadable deployment lock cannot invalidate a frozen home's launch.
7767
+ cleanupWarnings.push(`package module drift could not be read from ${join(driftDeployment, "oats-lock.json")}: ${error.message}`);
7768
+ }
7769
+ drift = driftLock === undefined ? [] : packageUpgradeDrift(readMeta(), { lock: driftLock });
7586
7770
  if (existsSync(join(realHome, ".oats-rollback-incomplete.json"))) throw oatsError("E_INSTANCE_RETIRING", `${realHome} is a quarantined home whose cleanup is incomplete; finish its retirement (oats retire) before starting anything there`);
7587
7771
  // A self-retirement leaves this marker while its detached teardown runs:
7588
7772
  // the home is about to disappear, so nothing is relaunched into it.
@@ -7962,7 +8146,7 @@ export function startInstanceSession(home, o = {}) {
7962
8146
  if (launchPrompts && !promptLaunched(launchPrompts.status)) throw retainedPromptError(realHome, meta.instance, launchPromptTarget ?? target, false, launchPrompts);
7963
8147
  // Said once the new socket is recorded: a start that could not record leaves it to the adoption.
7964
8148
  if (moved) { appendEvent(realHome, { kind: "launch-warning", data: { message: moved } }); movedWarnings.push(moved); }
7965
- return { ...done, warnings: [...warnings, ...movedWarnings] };
8149
+ return { ...done, warnings: [...done.warnings, ...warnings, ...movedWarnings] };
7966
8150
  } finally {
7967
8151
  // A hook may have replaced the home itself. Never follow that replacement
7968
8152
  // to remove a target's lock; keep the original retry state with its home.
@@ -9897,7 +10081,7 @@ export function retireClaimPath(home) {
9897
10081
 
9898
10082
  /** The verbs that take a home's lifecycle claim: what claimHomeFor accepts, and so every `action`
9899
10083
  * a claim of the kernel's names. */
9900
- const CLAIM_VERBS = Object.freeze(["retire", "stop"]);
10084
+ const CLAIM_VERBS = Object.freeze(["retire", "stop", "upgrade"]);
9901
10085
  /** The verb the holder of a home's claim recorded (`action`): one of CLAIM_VERBS, never the
9902
10086
  * record's text. A claim is read back as whatever is in its file, which other instances of the
9903
10087
  * deployment can write, and this goes into messages, remedies and `details` (lib/claim.mjs
@@ -9906,11 +10090,11 @@ const CLAIM_VERBS = Object.freeze(["retire", "stop"]);
9906
10090
  * retire took the claim. */
9907
10091
  const claimAction = (holder) => CLAIM_VERBS.includes(holder?.action) ? holder.action : "retire";
9908
10092
  /** The command that takes a home's claim for `action`, as a person types it. */
9909
- const claimCommand = (action) => action === "stop" ? "oats instance stop" : `oats ${action}`;
10093
+ const claimCommand = (action) => ["stop", "upgrade"].includes(action) ? `oats instance ${action}` : `oats ${action}`;
9910
10094
  /** What each verb that meets a held claim says it did not do: the words its refusals end with,
9911
10095
  * before any effect. After a takeover ended a dead holder's step, every verb says the same
9912
10096
  * (lib/errors.mjs nothingAfter). */
9913
- const CLAIM_NOTHING = { retire: "nothing was done", stop: "nothing was stopped", "worktree add": "no tree was made", "instance color": "the colour was not changed" };
10097
+ const CLAIM_NOTHING = { upgrade: "no modules were upgraded", retire: "nothing was done", stop: "nothing was stopped", "worktree add": "no tree was made", "instance color": "the colour was not changed" };
9914
10098
 
9915
10099
  /** The refusals of `arriving` ("retire", "stop", or "worktree add", which reads the claim and does
9916
10100
  * not take it) of `name` (home `home`) that meets the lifecycle claim `lock`, as lib/claim.mjs asks
@@ -9933,7 +10117,7 @@ const CLAIM_NOTHING = { retire: "nothing was done", stop: "nothing was stopped",
9933
10117
  export function lifecycleClaimRefusals(arriving, name, home, lock) {
9934
10118
  const nothing = (ended) => nothingAfter(ended, CLAIM_NOTHING[arriving]);
9935
10119
  const own = { instance: name, home };
9936
- const holders = "oats retire or oats instance stop";
10120
+ const holders = "oats retire, oats instance stop or oats instance upgrade";
9937
10121
  // The holder of `at`, as an answer names it: `shown` for the message, `details` beside it.
9938
10122
  const held = (holder, at) => {
9939
10123
  const shown = shownHolder(holder), action = claimAction(holder);
@@ -46,7 +46,7 @@ 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", "retire-refused", "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", "modules-upgraded", "upgrade-refused", "waiting"];
50
50
 
51
51
  /** The longest `reason` a `retire-refused` row carries, in UTF-16 code units. The bound is not the
52
52
  * kernel's: the Desktop's events reader refuses a whole read that holds a longer detail
@@ -664,13 +664,13 @@ export async function plannedPreparedSkills(prepared) {
664
664
  }
665
665
 
666
666
 
667
- /** Turn a Resolution's modules (already materialized under `home`) into the
668
- * capability rows the kernel's hooks/environment/requirements code consumes.
669
- * Paths point INTO the instance's own copy — never at a repo or a package dir. */
670
- export function toCapabilityRows(resolution, home) {
667
+ /** Turn a Resolution into the capability rows used by hooks and requirements.
668
+ * Published rows use the home's module copies. Upgrade may supply verified staged
669
+ * directories so new manifest paths are enumerated against the matching bytes. */
670
+ export function toCapabilityRows(resolution, home, { moduleDirs = {} } = {}) {
671
671
  const rows = [];
672
672
  for (const m of resolution.modules) {
673
- const dir = join(home, MODULES_DIR, m.name);
673
+ const dir = (Object.hasOwn(moduleDirs, m.name) ? moduleDirs[m.name] : undefined) ?? join(home, MODULES_DIR, m.name);
674
674
  const manifest = m.manifest;
675
675
  // Skills are flat under <home>/.agents/skills/<skill>/; which of them this module
676
676
  // contributed is read from its own copy, enumerated exactly as materialize placed them.