@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.
- package/bin/oats.mjs +112 -16
- package/docs/capabilities.md +54 -5
- package/docs/capability-manifest.schema.json +4 -0
- package/docs/design/2026-10-22-module-upgrade.md +192 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +248 -9
- package/docs/desktop.md +278 -61
- package/docs/first-team.md +5 -3
- package/docs/implementation.md +42 -3
- package/docs/integrations.md +16 -4
- package/docs/knowledge.md +44 -27
- package/docs/layers.md +2 -2
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.68.0.md +504 -0
- package/docs/servers.md +6 -1
- package/docs/souls-and-instances.md +38 -3
- package/docs/tui.md +625 -223
- package/docs/upgrading.md +62 -6
- package/docs/workspaces.md +2 -2
- package/lib/capability-contract.mjs +6 -5
- package/lib/core.mjs +222 -38
- package/lib/instance-events.mjs +1 -1
- package/lib/instance-resolution.mjs +5 -5
- package/lib/instance-upgrade.mjs +1445 -0
- package/lib/materialize.mjs +225 -78
- package/lib/servers.mjs +11 -7
- package/lib/upgrade-state.mjs +101 -0
- package/lib/workspace.mjs +4 -1
- package/lib/worktree.mjs +103 -12
- package/package-catalog.json +5 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +15 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-panel.mjs +6 -2
- package/packages/client/keymap.mjs +89 -45
- package/packages/client/keys-file.mjs +9 -5
- package/packages/client/panel-views.mjs +16 -3
- package/packages/client/spawn-naming.mjs +7 -6
- package/packages/client/spawn-preview-cli.mjs +37 -1
- package/packages/client/spawn-preview-contract.mjs +35 -0
- package/packages/client/spawn-preview.mjs +35 -2
- package/packages/client/team-members.mjs +4 -1
- package/packages/client/workspace-step.mjs +25 -0
- package/packages/tui/README.md +5 -5
- package/packages/tui/lib/actions.mjs +51 -27
- package/packages/tui/lib/client.mjs +3 -2
- package/packages/tui/lib/config.mjs +4 -4
- package/packages/tui/lib/main.mjs +27 -13
- package/packages/tui/lib/model.mjs +132 -19
- package/packages/tui/lib/store.mjs +343 -68
- package/packages/tui/lib/term/keys.mjs +5 -3
- package/packages/tui/lib/term/kitty.mjs +28 -10
- package/packages/tui/lib/term/screen.mjs +15 -6
- package/packages/tui/lib/term/through.mjs +33 -28
- package/packages/tui/lib/views/frame.mjs +88 -109
- package/packages/tui/lib/views/help.mjs +56 -34
- package/packages/tui/lib/views/instances.mjs +4 -2
- package/packages/tui/lib/views/workspaces.mjs +55 -0
- 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 (
|
|
3831
|
-
// name, by a naming call through this launch's harness and
|
|
3832
|
-
// the preflight's probes
|
|
3833
|
-
//
|
|
3834
|
-
//
|
|
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
|
-
|
|
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
|
-
|
|
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):
|
|
4217
|
-
// its own 20 s). Its time counts in the preflight's elapsedMs, but the preflight's status
|
|
4218
|
-
// checks': a call the budget ends is `naming.reason` "timeout", and the numbered preview it
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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) {
|
|
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:
|
|
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")
|
|
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) =>
|
|
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
|
|
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);
|
package/lib/instance-events.mjs
CHANGED
|
@@ -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
|
|
668
|
-
*
|
|
669
|
-
*
|
|
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.
|