@awebai/oats 0.67.1 → 0.68.1
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 +316 -63
- 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/release-notes/v0.68.1.md +102 -0
- package/docs/servers.md +6 -1
- package/docs/souls-and-instances.md +38 -3
- package/docs/tui.md +663 -243
- package/docs/upgrading.md +66 -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/instance-display-name.mjs +18 -0
- 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 +4 -2
- package/packages/tui/lib/config.mjs +4 -4
- package/packages/tui/lib/main.mjs +27 -13
- package/packages/tui/lib/model.mjs +143 -21
- 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/capabilities.mjs +6 -6
- package/packages/tui/lib/views/frame.mjs +88 -109
- package/packages/tui/lib/views/help.mjs +57 -35
- package/packages/tui/lib/views/instances.mjs +48 -30
- package/packages/tui/lib/views/souls.mjs +9 -8
- package/packages/tui/lib/views/workspaces.mjs +55 -0
- package/skills/oats-getting-started/SKILL.md +92 -43
package/bin/oats.mjs
CHANGED
|
@@ -26,13 +26,14 @@ import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
|
|
|
26
26
|
import { fileURLToPath } from "node:url";
|
|
27
27
|
import { performance } from "node:perf_hooks";
|
|
28
28
|
import { doctorCaptureWarnings } from "../lib/doctor-capture.mjs";
|
|
29
|
+
import { assertNoPartialUpgrade } from "../lib/upgrade-state.mjs";
|
|
29
30
|
import { runtimeNameWarning, noteRuntimeName } from "../lib/deprecation.mjs";
|
|
30
31
|
import { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect, spawnRefusalDetails } from "../lib/errors.mjs";
|
|
31
32
|
import {
|
|
32
33
|
LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
|
|
33
34
|
capabilityManifests, capabilityTrust, capabilityExecutablePath,
|
|
34
35
|
officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
|
|
35
|
-
findInstanceHome, findInstanceHomes, homeLaunchLayers, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchStartNotices, launchReportFor, explicitInstanceName, retireInstance, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
|
|
36
|
+
findInstanceHome, findInstanceHomes, homeLaunchLayers, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, suggestSpawnName, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchStartNotices, launchReportFor, explicitInstanceName, retireInstance, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
|
|
36
37
|
FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
|
|
37
38
|
} from "../lib/core.mjs";
|
|
38
39
|
import {
|
|
@@ -107,7 +108,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
|
|
|
107
108
|
* probe) and in `status --json`, which a remote roster relays as the host's (feature
|
|
108
109
|
* server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
|
|
109
110
|
* time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
|
|
110
|
-
const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name"];
|
|
111
|
+
const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "instance-suggest-name", "spawn-apply-suggest-name"];
|
|
111
112
|
/** Commands `--server <id>` runs on a registered server. */
|
|
112
113
|
const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
|
|
113
114
|
const flag = (name) => {
|
|
@@ -1318,10 +1319,68 @@ function retiredInstanceAddresses(root, name, home) {
|
|
|
1318
1319
|
* instance's work tree. The instance is addressed qualified: an explicit
|
|
1319
1320
|
* --home, or a name under the --dir scope (team roots included) that resolves
|
|
1320
1321
|
* to exactly one home; several homes refuse with every candidate named. */
|
|
1321
|
-
function
|
|
1322
|
+
async function instanceUpgradeCmd(name, bail) {
|
|
1323
|
+
const usage = "usage: oats instance upgrade <instance> [--undo] (--plan | --plan-revision <rev> --idempotency-key <key>) [--home <abs>] [--dir <d>] [--json]";
|
|
1324
|
+
if (!name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
|
|
1325
|
+
if (serverFlagOf(args)) return bail("E_BAD_ARGS", "instance upgrade supports local homes only; run it on the deployment host");
|
|
1326
|
+
const home = flag("home"), revision = flag("plan-revision"), key = flag("idempotency-key");
|
|
1327
|
+
if (home === true || (home !== undefined && !isAbsolute(home))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
|
|
1328
|
+
const planOnly = args.includes("--plan"), undo = args.includes("--undo");
|
|
1329
|
+
if (revision === true || key === true || (planOnly && (revision !== undefined || key !== undefined))) return bail("E_BAD_ARGS", usage);
|
|
1330
|
+
dropAmbientRoot();
|
|
1331
|
+
try {
|
|
1332
|
+
const root = ensureRoot(dirFlag());
|
|
1333
|
+
const { planUpgrade, applyUpgrade } = await import("../lib/instance-upgrade.mjs");
|
|
1334
|
+
const result = planOnly ? await planUpgrade(dirFlag(), root, name, { home, undo })
|
|
1335
|
+
: await applyUpgrade(dirFlag(), root, name, { home, undo, planRevision: revision, idempotencyKey: key });
|
|
1336
|
+
if (JSON_MODE) { jsonOk(result); return; }
|
|
1337
|
+
console.log(`${undo ? "undo package upgrade" : "package upgrade"} ${name}: ${planOnly ? `plan ${result.planRevision}` : result.status}${result.replayed ? " (replayed receipt)" : ""}`);
|
|
1338
|
+
for (const row of result.modules) console.log(` ${row.capability}: ${row.from.version} @ ${row.from.commit.slice(0,12)} → ${row.to.version} @ ${row.to.commit.slice(0,12)}${row.provider?.decision === "refuse" ? `; refused: ${row.provider.reason}` : ""}`);
|
|
1339
|
+
for (const row of result.kept || []) console.log(` ${row.capability}: kept (${row.reason})`);
|
|
1340
|
+
for (const row of result.memberDrift || []) console.log(` ${row.module}: member drift (${row.reason || row.status}); respawn to move it`);
|
|
1341
|
+
if (planOnly) console.log(` home changed since spawn: ${result.homeChangedSinceSpawn ? "yes (retire preserves a recovery copy)" : "no"}`);
|
|
1342
|
+
if (planOnly) console.log(`apply with: oats instance upgrade ${name}${undo ? " --undo" : ""} --plan-revision ${result.planRevision} --idempotency-key <key>`);
|
|
1343
|
+
} catch (e) { return lifecycleFail(e, "E_UPGRADE_FAILED", { ...e.details, ...(e.plan ? { plan: e.plan } : {}), ...(e.candidates ? { candidates: e.candidates } : {}) }); }
|
|
1344
|
+
}
|
|
1345
|
+
|
|
1346
|
+
/** The flags `oats instance suggest-name` reads, each taking a value (`--json` aside). */
|
|
1347
|
+
const SUGGEST_NAME_FLAGS = new Set(["soul", "task", "task-file", "harness", "model", "launch-config", "dir"]);
|
|
1348
|
+
/** `oats instance suggest-name` (feature instance-suggest-name, awebai/oats#1490 §2): the name a spawn
|
|
1349
|
+
* of a soul would get by --suggest-name, chosen here for a spawn that may land on another machine
|
|
1350
|
+
* (lib/core.mjs suggestSpawnName). Never routed: --server is refused before the route dispatch. */
|
|
1351
|
+
async function instanceSuggestNameCmd(bail) {
|
|
1352
|
+
const usage = "usage: oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]";
|
|
1353
|
+
// A flag's value as given, the empty text included (`--task ""` is an empty task, not a missing one).
|
|
1354
|
+
const value = (name) => {
|
|
1355
|
+
const i = args.indexOf(`--${name}`);
|
|
1356
|
+
if (i < 0) return undefined;
|
|
1357
|
+
const v = inlineValues.has(name) ? inlineValues.get(name) : args[i + 1];
|
|
1358
|
+
if (v === undefined || (!inlineValues.has(name) && v.startsWith("--"))) return bail("E_BAD_ARGS", `--${name} needs a value; ${usage}`);
|
|
1359
|
+
return v;
|
|
1360
|
+
};
|
|
1361
|
+
for (let i = 2; i < args.length; i++) {
|
|
1362
|
+
const a = args[i];
|
|
1363
|
+
if (a === "--json") continue;
|
|
1364
|
+
if (!a.startsWith("--") || !SUGGEST_NAME_FLAGS.has(a.slice(2))) return bail("E_BAD_ARGS", `oats instance suggest-name: unexpected ${a.startsWith("--") ? "flag" : "argument"} ${JSON.stringify(a)}; ${usage}`);
|
|
1365
|
+
if (!inlineValues.has(a.slice(2))) i++;
|
|
1366
|
+
}
|
|
1367
|
+
const soul = value("soul"), task = value("task"), taskFile = value("task-file");
|
|
1368
|
+
if (soul === undefined) return bail("E_BAD_ARGS", `--soul is required; ${usage}`);
|
|
1369
|
+
if ((task === undefined) === (taskFile === undefined)) return bail("E_BAD_ARGS", `give the task with one of --task or --task-file; ${usage}`);
|
|
1370
|
+
let text = task;
|
|
1371
|
+
if (taskFile !== undefined) { try { text = readFileSync(taskFile, "utf8"); } catch (e) { return bail("E_BAD_ARGS", `--task-file ${taskFile} cannot be read (${e.code || "error"})`); } }
|
|
1372
|
+
let r;
|
|
1373
|
+
try { r = await suggestSpawnName({ dir: dirFlag(), soul, task: text, harness: value("harness"), model: value("model"), launchConfig: value("launch-config") }); }
|
|
1374
|
+
catch (e) { return bail(e.code || "E_BAD_ARGS", e.message, e.details); }
|
|
1375
|
+
if (JSON_MODE) { jsonOk(r); return; }
|
|
1376
|
+
console.log(r.name ?? namingLine(r.naming));
|
|
1377
|
+
}
|
|
1378
|
+
async function instanceCmd() {
|
|
1322
1379
|
const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
|
|
1323
1380
|
const sub = args[1], name = args[2];
|
|
1381
|
+
if (sub === "upgrade") return instanceUpgradeCmd(name, bail);
|
|
1324
1382
|
if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
|
|
1383
|
+
if (sub === "suggest-name") return instanceSuggestNameCmd(bail);
|
|
1325
1384
|
const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message <text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message <text>] [--clear] [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json]";
|
|
1326
1385
|
if (!["git", "diff", "stop", "events", "color"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
|
|
1327
1386
|
dropAmbientRoot();
|
|
@@ -2733,12 +2792,14 @@ const livenessWord = (i) => i.running === true ? "RUNNING" : i.running === false
|
|
|
2733
2792
|
* apply bound by --expect-decision: the dispatch allow-list (maxAgeRefusal) refuses it otherwise. */
|
|
2734
2793
|
const SPAWN_VALUE_FLAGS = new Set(["agents-root", "backend", "base", "branch", "dir", "expect-decision", "harness", "idempotency-key", "instance", "launch-config", "max-age", "model", "name", "parent", "purpose", "relation", "relative-root", "relative-to", "repo", "runtime", "task", "task-file", "trigger-event", "wake-cron", "wake-every", "wake-file", "wake-json", "wake-message", "wake-message-file", "wake-tz", "work", "work-dir"]);
|
|
2735
2794
|
const SPAWN_SWITCHES = new Set(["allow-child-spawns", "json", "no-child-spawns", "no-launch", "no-yolo", "preview", "suggest-name", "yolo"]);
|
|
2736
|
-
/** `--suggest-name` (
|
|
2737
|
-
* refuses the same (core.mjs spawnBody); the
|
|
2795
|
+
/** `--suggest-name` (features spawn-suggest-name, spawn-apply-suggest-name): a preview's or an apply's,
|
|
2796
|
+
* with no --name, --purpose or --expect-decision. The kernel refuses the same (core.mjs spawnBody); the
|
|
2797
|
+
* CLI says it before anything is read or sent. */
|
|
2738
2798
|
function suggestNameProblem(argv) {
|
|
2739
2799
|
if (!argv.includes("--suggest-name")) return undefined;
|
|
2740
|
-
|
|
2741
|
-
if (
|
|
2800
|
+
const given = (flag) => argv.some((a) => a.split("=")[0] === flag);
|
|
2801
|
+
if (given("--expect-decision")) return "--suggest-name chooses the name, and --expect-decision's decision already binds one: apply the previewed name with --name <instance> --expect-decision <revision>";
|
|
2802
|
+
if (given("--name") || given("--purpose")) return "--suggest-name chooses the name: it takes no --name or --purpose";
|
|
2742
2803
|
return undefined;
|
|
2743
2804
|
}
|
|
2744
2805
|
/** Why `argv` (after `spawn`, the soul first) is not a spawn, or undefined: a positional after the
|
|
@@ -2767,6 +2828,13 @@ function herdrSpawnFlag() {
|
|
|
2767
2828
|
if (flag("herdr-socket") !== undefined) return "--herdr-socket";
|
|
2768
2829
|
return undefined;
|
|
2769
2830
|
}
|
|
2831
|
+
/** How a name was chosen (`naming`: features spawn-suggest-name, spawn-apply-suggest-name,
|
|
2832
|
+
* instance-suggest-name), for a text line; null without one. */
|
|
2833
|
+
function namingLine(naming) {
|
|
2834
|
+
if (naming?.source === "suggested") return `suggested by ${terminalText(naming.harness)}${naming.model ? ` (${terminalText(naming.model)})` : ""} in ${naming.ms} ms`;
|
|
2835
|
+
if (naming?.source === "numbered") return `numbered (${terminalText(naming.reason)}: ${terminalText(naming.message)})`;
|
|
2836
|
+
return null;
|
|
2837
|
+
}
|
|
2770
2838
|
/** A spawn preview's text: the local one, or a host's answer to a routed
|
|
2771
2839
|
* preview (`server`, its id), which this side printed the same way (#610). */
|
|
2772
2840
|
function printSpawnPreview(r, { server, soulFetched = false } = {}) {
|
|
@@ -2774,8 +2842,7 @@ function printSpawnPreview(r, { server, soulFetched = false } = {}) {
|
|
|
2774
2842
|
const harness = r.harness ?? r.runtime;
|
|
2775
2843
|
console.log(`preview ${r.agent} → ${r.instance}${server ? ` on ${server}` : ""} (${r.work}${r.branch ? `, branch ${r.branch}${r.base ? ` from ${r.base.ref}@${r.base.oid.slice(0, 12)}` : ""}` : ""}) harness ${harness}${r.model ? ` model ${r.model}` : ` (${r.modelSource})`}${r.launchConfig ? ` via launch configuration ${r.launchConfig}${r.launchConfigDefault ? ` (${server ? "the server's" : "this machine's"} ${harness} default)` : ""}` : ""}${r.yolo ? " YOLO" : ""}; nothing was created${soulFetched ? " (the soul source was fetched to a temporary copy, not kept)" : ""}`);
|
|
2776
2844
|
// Feature spawn-suggest-name: how the name was chosen.
|
|
2777
|
-
|
|
2778
|
-
else if (r.naming?.source === "numbered") console.log(`name: numbered (${terminalText(r.naming.reason)}: ${terminalText(r.naming.message)})`);
|
|
2845
|
+
{ const line = namingLine(r.naming); if (line) console.log(`name: ${line}`); }
|
|
2779
2846
|
if (Array.isArray(r.worktreeHooks)) console.log(r.worktreeHooks.length ? `worktree hooks: ${r.worktreeHooks.map((h) => `${h.capability}${h.required ? " (required)" : ""}`).join(", ")}` : "worktree hooks: none");
|
|
2780
2847
|
for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
|
|
2781
2848
|
}
|
|
@@ -2794,7 +2861,7 @@ async function spawnCmd() {
|
|
|
2794
2861
|
};
|
|
2795
2862
|
checkDirectoryOptions(requestedWork); // before anything is resolved or written
|
|
2796
2863
|
const name = args[1];
|
|
2797
|
-
if (!name || name.startsWith("--")) bail("E_USAGE", "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug
|
|
2864
|
+
if (!name || name.startsWith("--")) bail("E_USAGE", "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>|--suggest-name] [--preview] [--base <ref>] [--model <id>|@native-default] [--allow-child-spawns|--no-child-spawns] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux] [--yolo|--no-yolo] [--model <m>] [--branch <b>] [--no-launch] [--json]");
|
|
2798
2865
|
// Retired boundary flags (maintainer transport ruling): fail LOUDLY before
|
|
2799
2866
|
// ANY side effect, including root discovery.
|
|
2800
2867
|
// Local souls (local-agents/) are gone with the workspace model: a soul is a member
|
|
@@ -3056,11 +3123,14 @@ async function spawnCmd() {
|
|
|
3056
3123
|
launchConfig: r.launch?.launchConfig ?? null, launch: r.launch || null, // already redacted by the kernel
|
|
3057
3124
|
// #796: the worktree hooks this spawn ran, with their logs; only when it ran any.
|
|
3058
3125
|
...(r.worktreeHooks ? { worktreeHooks: r.worktreeHooks } : {}),
|
|
3126
|
+
// Feature spawn-apply-suggest-name: how the name was chosen; only with --suggest-name.
|
|
3127
|
+
...(r.naming ? { naming: r.naming } : {}),
|
|
3059
3128
|
});
|
|
3060
3129
|
return;
|
|
3061
3130
|
}
|
|
3062
3131
|
console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux.window}"` : " — not launched"}`);
|
|
3063
3132
|
console.log(` home: ${shortPath(r.home)}`);
|
|
3133
|
+
{ const line = namingLine(r.naming); if (line) console.log(` name: ${line}`); }
|
|
3064
3134
|
if (r.base) console.log(` base: ${r.base.oid.slice(0, 12)} (${r.base.ref === r.workspace?.soul?.repoKey ? `observed head of ${r.base.ref}` : r.base.ref})`);
|
|
3065
3135
|
for (const h of r.worktreeHooks || []) console.log(` setup: ${h.capability} worktree hook ${h.ok ? "ok" : "FAILED"} (log: ${shortPath(h.log)})`);
|
|
3066
3136
|
if (wakeSchedule) console.log(` wake: schedule ${wakeSchedule.id} (${wakeSchedule.cron} ${wakeSchedule.tz}), next ${wakeSchedule.nextRun || "disabled"}`);
|
|
@@ -3533,6 +3603,8 @@ async function sessionCmd() {
|
|
|
3533
3603
|
// recorded launch stays frozen (a changed preference never reaches an existing home on its own).
|
|
3534
3604
|
const reselectLaunch = args.includes("--reselect-launch");
|
|
3535
3605
|
if (reselectLaunch && launchConfig !== undefined) bad("--reselect-launch applies the launch preferences; --launch-config names one explicitly — choose one");
|
|
3606
|
+
// Refuse before launch selection or live-team discovery can prepare this home.
|
|
3607
|
+
assertNoPartialUpgrade(home);
|
|
3536
3608
|
const opts = { model: model || undefined, launchConfig, harness, yolo: yoloFlag(), ...(reselectLaunch ? { reselectLaunch: true, launchOffered: await homeLaunchOffered(home, { named: harness !== undefined }) } : {}), env: process.env, ...(await homeLiveTeams(home)) };
|
|
3537
3609
|
if (args[1] === "restart") {
|
|
3538
3610
|
const grace = flag("stop-grace");
|
|
@@ -3562,6 +3634,11 @@ async function sessionCmd() {
|
|
|
3562
3634
|
console.log(JSON.stringify(result, null, 2));
|
|
3563
3635
|
// A start's launch-hook warnings, as spawn prints its own (stderr keeps stdout one JSON document).
|
|
3564
3636
|
for (const w of result?.warnings || []) console.error(` WARNING: ${terminalText(w)}`);
|
|
3637
|
+
if (result?.drift?.length) {
|
|
3638
|
+
const version = (v) => `${v.version ?? "?"} @ ${String(v.commit ?? "?").slice(0, 7)}`;
|
|
3639
|
+
const modules = result.drift.map((d) => `${d.capability} ${version(d.recorded)} → ${version(d.locked)}`).join(", ");
|
|
3640
|
+
console.error(terminalText(`${result.drift.length} package module(s) behind the lock (${modules}); to move them: oats instance stop ${shellQuote(result.instance)}; oats instance upgrade ${shellQuote(result.instance)} --plan`));
|
|
3641
|
+
}
|
|
3565
3642
|
}
|
|
3566
3643
|
} catch (e) { lifecycleFail(e, "E_SESSION_FAILED", e.details); }
|
|
3567
3644
|
}
|
|
@@ -4640,6 +4717,7 @@ async function serverRouteCmd() {
|
|
|
4640
4717
|
else if (cmd === "spawn") {
|
|
4641
4718
|
console.log(`Spawned ${r.instance} on ${id} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux?.window}" on ${r.target.sshHost}` : " — not launched"}`);
|
|
4642
4719
|
console.log(` remote home: ${r.home}`);
|
|
4720
|
+
{ const line = namingLine(r.naming); if (line) console.log(` name: ${line}`); }
|
|
4643
4721
|
console.log(` route snapshot: ${r.snapshot ? shortPath(r.snapshot) : "none (see the warning)"}`);
|
|
4644
4722
|
for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
|
|
4645
4723
|
console.log(` attach: oats session attach --server ${shellQuote(id)} --instance ${shellQuote(r.instance)}`);
|
|
@@ -4734,7 +4812,8 @@ try {
|
|
|
4734
4812
|
// listResolved): a listed deployment costs one bounded read of the list. Never on --server (the remote's path is not this computer's), never for
|
|
4735
4813
|
// help, and silent: no output, no change to the command's answer or exit status.
|
|
4736
4814
|
const LISTS_ITS_DEPLOYMENT = new Set(["automations", "capabilities", "doctor", "harness", "inspect", "instance", "launch-config", "operation", "package", "pane", "readiness", "retire", "schedule", "session", "soul", "souls", "spawn", "status", "sync", "teams", "trigger", "update", "workspace", "worktree"]);
|
|
4737
|
-
|
|
4815
|
+
// `instance suggest-name` records nothing (#1490 §2): the oats-local.yaml it reads is not listed.
|
|
4816
|
+
if (LISTS_ITS_DEPLOYMENT.has(cmd) && flag("server") === undefined && !(cmd === "instance" && args[1] === "suggest-name") && !args.slice(1).some((a) => a === "--help" || a === "-h")) observeResolvedDeployment(listResolved);
|
|
4738
4817
|
if (cmd === "onboard") {
|
|
4739
4818
|
if (args.includes("--help") || args.includes("-h")) { if (JSON_MODE) jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); else usageFor(cmd); process.exit(0); }
|
|
4740
4819
|
await onboardCmd();
|
|
@@ -4746,6 +4825,9 @@ else {
|
|
|
4746
4825
|
// `okf harvest --help` spawned a harvester (BeadHub, 2026-09-05).
|
|
4747
4826
|
const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
|
|
4748
4827
|
if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); process.exit(0); } usageFor(cmd); process.exit(0); }
|
|
4828
|
+
if (cmd === "instance" && args[1] === "upgrade" && flag("server") !== undefined) cmdFail("E_BAD_ARGS", "instance upgrade supports local homes only; run it on the deployment host");
|
|
4829
|
+
// #1490 §2: the name is decided on the machine that asks, for a spawn that lands elsewhere.
|
|
4830
|
+
if (cmd === "instance" && args[1] === "suggest-name" && flag("server") !== undefined) cmdFail("E_BAD_ARGS", "instance suggest-name takes no --server: it runs this machine's harness, for a spawn that may land on another; the host it lands on makes the name unique (or names an unnamed --suggest-name spawn itself)");
|
|
4749
4831
|
if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
|
|
4750
4832
|
else if (cmd === "server") await serverCmd();
|
|
4751
4833
|
else if (cmd === "deployments") deploymentsCmd();
|
|
@@ -4765,7 +4847,7 @@ else if (cmd === "update") {
|
|
|
4765
4847
|
}
|
|
4766
4848
|
else if (cmd === "harness") harnessTrustCmd();
|
|
4767
4849
|
else if (cmd === "readiness") await readinessCmd();
|
|
4768
|
-
else if (cmd === "instance") instanceCmd();
|
|
4850
|
+
else if (cmd === "instance") await instanceCmd();
|
|
4769
4851
|
else if (cmd === "worktree") await worktreeCmd();
|
|
4770
4852
|
else if (cmd === "root") console.log(resolve(new URL("..", import.meta.url).pathname));
|
|
4771
4853
|
else if (cmd === "sync") await syncCmd();
|
|
@@ -5005,10 +5087,12 @@ Usage:
|
|
|
5005
5087
|
instance.json providers.<capability>)
|
|
5006
5088
|
[--preview] decide everything, create no instance; --json
|
|
5007
5089
|
includes the decision revision for confirmation
|
|
5008
|
-
[--suggest-name]
|
|
5009
|
-
harness
|
|
5010
|
-
(<descriptive>-<role
|
|
5011
|
-
|
|
5090
|
+
[--suggest-name] no --name, --purpose or --expect-decision: the
|
|
5091
|
+
soul's harness, on the machine that spawns, names
|
|
5092
|
+
the instance for its task (<descriptive>-<role>,
|
|
5093
|
+
made unique); else it is numbered, and
|
|
5094
|
+
naming.reason says why (claude and pi); on a
|
|
5095
|
+
preview or an apply
|
|
5012
5096
|
[--expect-decision <rev>] bind apply to the previewed decision; drift refuses
|
|
5013
5097
|
[--idempotency-key <key>] with --expect-decision, replay the completed receipt
|
|
5014
5098
|
for the same key and confirmed decision; a different
|
|
@@ -5146,6 +5230,10 @@ Usage:
|
|
|
5146
5230
|
oats instance attention [--message <text>] [--clear] [--json]
|
|
5147
5231
|
run by the agent from its home: "I need a human's
|
|
5148
5232
|
answer" (waiting --producer agent --reason attention)
|
|
5233
|
+
oats instance upgrade <instance> --plan [--undo] [--json]
|
|
5234
|
+
Preview package module moves and provider adoption; session must be stopped.
|
|
5235
|
+
oats instance upgrade <instance> --plan-revision <rev> --idempotency-key <key> [--undo] [--json]
|
|
5236
|
+
Move whole package modules to the verified lock; --undo uses the latest previous copies.
|
|
5149
5237
|
oats instance stop <instance> --plan [--no-recursive] [--json]
|
|
5150
5238
|
what Stop would touch: session state, recorded
|
|
5151
5239
|
children, dirty work; a planRevision to apply
|
|
@@ -5155,6 +5243,14 @@ Usage:
|
|
|
5155
5243
|
oats instance color <instance> (<color> | --clear) [--home <abs>] [--json]
|
|
5156
5244
|
the instance's colour, presentation only: sand,
|
|
5157
5245
|
sage, slate, mauve, clay or olive; --clear removes it
|
|
5246
|
+
oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi]
|
|
5247
|
+
[--model <m>] [--launch-config <n>] [--dir <d>] [--json]
|
|
5248
|
+
a name for a spawn of <soul> (only a name: it gives
|
|
5249
|
+
the role) by this machine's harness, as a preview's
|
|
5250
|
+
--suggest-name chooses it, not made unique (where it
|
|
5251
|
+
lands decides that); else numbered, and naming.reason
|
|
5252
|
+
says why. Reads only this machine's launch
|
|
5253
|
+
configurations; writes and reserves nothing; no --server
|
|
5158
5254
|
oats worktree add --purpose <p> --branch <b> --base <remote-branch> from an instance home: make the
|
|
5159
5255
|
[--repo <member key|clone path>] extra tree <home>/.work-<p> on a new branch at origin's
|
|
5160
5256
|
[--preview] [--json] <base> (the clone's refs are not moved), then run the
|
package/docs/capabilities.md
CHANGED
|
@@ -94,17 +94,19 @@ A self-contained package has an `oats.json`:
|
|
|
94
94
|
slot.
|
|
95
95
|
- `skills` entries can be skill directories or roots containing skills.
|
|
96
96
|
- `inject` is optional instance instruction Markdown.
|
|
97
|
-
- The hooks are `spawn`, `launch`, `retire` and `
|
|
98
|
-
([The worktree event](#the-worktree-event)
|
|
97
|
+
- The hooks are `spawn`, `launch`, `retire`, `worktree` and `upgrade`
|
|
98
|
+
([The worktree event](#the-worktree-event),
|
|
99
|
+
[The upgrade event](#the-upgrade-event)). A hook is a
|
|
99
100
|
command string, or `{ command, required }`. `required: true` is valid **only
|
|
100
101
|
on `spawn` and `worktree`**: a required spawn hook's failure fails the spawn
|
|
101
102
|
and rolls it back,
|
|
102
103
|
instead of producing an instance whose capability never configured itself —
|
|
103
104
|
an aweb identity that could not be minted leaves an agent believing it can be
|
|
104
105
|
woken by mail. A required `worktree` hook's failure fails the spawn the same
|
|
105
|
-
way, or removes the tree `oats worktree add` made.
|
|
106
|
-
best-effort and only
|
|
107
|
-
|
|
106
|
+
way, or removes the tree `oats worktree add` made. `launch` and `retire` stay
|
|
107
|
+
best-effort and only warn, so advisory work never becomes a spawn blocker.
|
|
108
|
+
`upgrade` has its own adoption and failure protocol and cannot be required.
|
|
109
|
+
`launch` and `retire` cannot be
|
|
108
110
|
required: they run outside a spawn transaction, so there is no moment to
|
|
109
111
|
enforce them. A `soul-scaffold` hook is tolerated and ignored.
|
|
110
112
|
- An **event this kernel does not run** (a newer kernel's) is accepted from
|
|
@@ -845,6 +847,53 @@ turn record's setup script (`packages/record/bin/setup.mjs`), which writes it
|
|
|
845
847
|
into the capture hooks and the capture service's unit. In the third case
|
|
846
848
|
`oats setup` carries the warning, a dry run included.
|
|
847
849
|
|
|
850
|
+
### The upgrade event
|
|
851
|
+
|
|
852
|
+
`OATS_EVENT=upgrade` lets a staged destination package module adopt the state
|
|
853
|
+
of a stopped instance, for `oats instance upgrade` and `--undo`. It runs from
|
|
854
|
+
the staged new copy, with the usual lifecycle environment plus:
|
|
855
|
+
|
|
856
|
+
- `OATS_UPGRADE_PHASE`: `plan` or `apply`;
|
|
857
|
+
- `OATS_META`: the old recorded `capabilityMeta[capability]`;
|
|
858
|
+
- `OATS_UPGRADE_FROM`: JSON containing the recorded `from`, `commit` and
|
|
859
|
+
`digest`;
|
|
860
|
+
- `OATS_UPGRADE_TO`: JSON containing the locked destination entry;
|
|
861
|
+
- `OATS_UPGRADE_MODULE_DIR`: the module's final `<home>/.oats/modules/<cap>`
|
|
862
|
+
directory. Register host artifacts against this path, never the staging path,
|
|
863
|
+
which is removed after the move.
|
|
864
|
+
|
|
865
|
+
In `plan`, the hook is read-only. It prints `{"adopt":true}`, or
|
|
866
|
+
`{"adopt":false,"reason":"…","remedy":"…"}`. A module with recorded
|
|
867
|
+
capability metadata, or whose recorded old or destination manifest declares
|
|
868
|
+
`spawn` or `launch`, must declare this
|
|
869
|
+
hook; otherwise the plan refuses it and names respawn as the remedy. A module
|
|
870
|
+
with neither state nor those hooks can move without an upgrade hook.
|
|
871
|
+
|
|
872
|
+
In `apply`, the hook may change provider state inside the home and its own
|
|
873
|
+
host registrations. On success it prints `{meta, warning?}` and exits zero;
|
|
874
|
+
the kernel records `meta` as the module's new capability metadata. Apply must
|
|
875
|
+
be idempotent. A non-zero exit must leave no effects of its own, using
|
|
876
|
+
atomicity or compensation. The kernel treats that result as a hook reporting
|
|
877
|
+
failure; rollback restores composed home bytes only, and provider host effects
|
|
878
|
+
remain the provider's responsibility. The refusal error retains a bounded
|
|
879
|
+
provider `warning`, or stderr when no warning was reported.
|
|
880
|
+
|
|
881
|
+
Before commit, a failed upgrade rolls back only if no hook succeeded and no
|
|
882
|
+
hook outcome is uncertain. A hook's non-zero result must be observed and
|
|
883
|
+
recorded in that invocation to establish that it reported failure. A killed
|
|
884
|
+
or interrupted hook has an uncertain outcome, even if no success was recorded;
|
|
885
|
+
the receipt preserves that uncertainty before retrying it. Once a hook succeeds
|
|
886
|
+
or becomes uncertain, the act only finishes forward. Retry may run the same
|
|
887
|
+
idempotent hook again; a later refusal does not permit restoring old modules.
|
|
888
|
+
Its `partial` receipt names the same idempotency key to retry pending work,
|
|
889
|
+
or respawn if it cannot finish. Start refuses a partial upgrade. See
|
|
890
|
+
[the operator workflow](upgrading.md#moving-existing-homes-to-locked-package-versions).
|
|
891
|
+
After swap and baseline commit the receipt, the kernel publishes the success
|
|
892
|
+
event and cleans staging. A failure after commit is retried without hooks or
|
|
893
|
+
copies; start is allowed with a warning naming that retry.
|
|
894
|
+
Undo uses the hook of the version being restored, so it requires that version
|
|
895
|
+
to support adoption too. The event must never declare `required: true`.
|
|
896
|
+
|
|
848
897
|
### The worktree event
|
|
849
898
|
|
|
850
899
|
`OATS_EVENT=worktree` (OATS 0.49.0) lets a capability set up a Git tree the
|
|
@@ -302,6 +302,10 @@
|
|
|
302
302
|
},
|
|
303
303
|
"retire": {"$ref":"#/$defs/OptionalHook"},
|
|
304
304
|
"launch": {"$ref":"#/$defs/OptionalHook"},
|
|
305
|
+
"upgrade": {
|
|
306
|
+
"$ref":"#/$defs/OptionalHook",
|
|
307
|
+
"description":"Runs from the staged destination module for a stopped home's package upgrade or undo. OATS_UPGRADE_PHASE=plan is read-only and prints {adopt:true} or {adopt:false,reason,remedy}; apply prints {meta,warning?} on success. A non-zero apply must leave no provider effects through atomicity or compensation: kernel rollback covers composed home bytes only. Receives OATS_META (recorded state), OATS_UPGRADE_FROM (recorded from/commit/digest) and OATS_UPGRADE_TO (locked destination entry) as JSON. Never required."
|
|
308
|
+
},
|
|
305
309
|
"worktree": {
|
|
306
310
|
"description": "Runs once in each tree the kernel creates: ./work of a work: worktree spawn (after the spawn hooks) and each `oats worktree add`. Its cwd is the new tree; see docs/capabilities.md, The worktree event.",
|
|
307
311
|
"oneOf":[
|
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
# Upgrading an existing home's package modules (#1450)
|
|
2
|
+
|
|
3
|
+
Status: decided 2026-10-22 (Pepe, option (b) on #1450, with the five conditions of the lane:release view). This supersedes workspace model v2 items 10–11 **for package modules only**: "a package pin being bumped affects only new spawns" and "the refresh is a new spawn, never an in-place recompose". The soul body still stays at its spawn commit. Member modules still change only through a respawn.
|
|
4
|
+
|
|
5
|
+
## Why
|
|
6
|
+
|
|
7
|
+
A home keeps the modules it was spawned with, and `oats session restart` starts that copy again. So a provider fix never reaches a live seat short of a respawn.
|
|
8
|
+
|
|
9
|
+
On 2026-10-22 a seat spawned on oats.aweb 1.17.1 was restarted. Its renewal revoked the old grant without re-registering the wake broker, a bug fixed in 1.17.3. Mail stopped arriving, and readiness, which also ran from the frozen 1.17.1 copy, stayed green. Respawning a long-lived coordinator to pick up a fix is not an acceptable remedy.
|
|
10
|
+
|
|
11
|
+
## The act
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
oats instance upgrade <instance> --plan [--json]
|
|
15
|
+
oats instance upgrade <instance> --plan-revision <rev> --idempotency-key <key> [--json]
|
|
16
|
+
oats instance upgrade <instance> --undo --plan [--json]
|
|
17
|
+
oats instance upgrade <instance> --undo --plan-revision <rev> --idempotency-key <key> [--json]
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
It runs from the deployment, or from a parent's home, with the same instance resolution as `oats retire`.
|
|
21
|
+
|
|
22
|
+
**What moves.** Every recorded module whose `from.kind` is `package` and whose recorded commit differs from the deployment lock's commit for that package moves to the locked package version. That is exactly the set that `driftOf` reports as "package moved since".
|
|
23
|
+
- Modules move whole: copy, skills, inject and hooks together (condition 1).
|
|
24
|
+
- A module of a package the lock no longer holds is not moved. The plan lists it as `kept: package no longer locked`.
|
|
25
|
+
- Member modules and the soul body are never moved. The plan lists member drift as information.
|
|
26
|
+
|
|
27
|
+
**Preconditions (all checked at plan and again at apply, under the instance's lifecycle claim):**
|
|
28
|
+
- **The session is stopped.** If it is running, or its state can't be read, the act refuses with `E_SESSION_RUNNING` and the remedy `oats instance stop <instance>`, then upgrade, then `oats session start`. Nothing changes under a running harness.
|
|
29
|
+
- **No retire or other lifecycle act is in flight.** Use the existing claim.
|
|
30
|
+
- Upgrade also holds the existing `.oats-start.lock` mutex until its final
|
|
31
|
+
invocation receipt is persisted; start/restart do not take the lifecycle
|
|
32
|
+
claim. Start acquires this path with `mkdir`; upgrade creates an exclusive
|
|
33
|
+
regular file with `wx`, so either kind refuses an occupied path. Upgrade
|
|
34
|
+
takes the lifecycle claim first and may reclaim only a regular-file mutex,
|
|
35
|
+
including an empty file left by a killed opener. It never reclaims a
|
|
36
|
+
directory. Start never reclaims the mutex and its busy message names the
|
|
37
|
+
same-key upgrade retry. A partial receipt refuses starts until finalization
|
|
38
|
+
completes.
|
|
39
|
+
- **The previous-state directory has no stray entries.** Check it before any
|
|
40
|
+
provider plan or apply hook runs.
|
|
41
|
+
- **The lock's package commit and integrity verify,** just as at spawn (`moduleSource`).
|
|
42
|
+
|
|
43
|
+
## Plan (condition 3)
|
|
44
|
+
|
|
45
|
+
The plan is read-only. It returns:
|
|
46
|
+
- `homeChangedSinceSpawn`, whether retirement must preserve home changes;
|
|
47
|
+
- a revision, sha256 over the package-move facts (member drift and home-change reporting are informational), the same `planRevision` pattern as stop and retire;
|
|
48
|
+
- per moving module: `{capability, from:{version,commit,digest}, to:{version,commit,integrity}, skills:{added,removed,changed}, inject:changed?, hooks:changed?, provider:{decision, reason}}`;
|
|
49
|
+
- kept modules, with the reason;
|
|
50
|
+
- member drift, for information.
|
|
51
|
+
|
|
52
|
+
The plan writes nothing into the home, because the retire baseline compares home bytes. Like stop and retire plans, it touches nothing there. It stages the new copies in a temporary directory outside the home (`mkdtemp` under the OS temp dir) and removes that directory when it finishes.
|
|
53
|
+
|
|
54
|
+
**Provider adoption (condition 2).** For each moving module, the kernel needs to know whether the *new* version can take over the state the old version laid out. The kernel never guesses.
|
|
55
|
+
- **New lifecycle event `upgrade`.** It is approved in `lib/capability-contract.mjs` and `docs/capability-manifest.schema.json`. It must not be `required`. The kernel runs it from the **staged new copy**, with the usual `lifecycleHookEnv` plus:
|
|
56
|
+
- `OATS_UPGRADE_PHASE=plan|apply`;
|
|
57
|
+
- `OATS_META` (the recorded `capabilityMeta[cap]`, i.e. the old version's state);
|
|
58
|
+
- `OATS_UPGRADE_FROM` (JSON: the recorded `from`, commit, digest);
|
|
59
|
+
- `OATS_UPGRADE_TO` (JSON: the locked entry).
|
|
60
|
+
- **In `plan`** the hook is read-only and prints one of:
|
|
61
|
+
- `{"adopt": true}`;
|
|
62
|
+
- `{"adopt": false, "reason": "...", "remedy": "..."}`, for example naming the respawn.
|
|
63
|
+
- **In `apply`** it may change only provider state inside the home or provider-owned host registrations. One example is oats.aweb re-registering the wake broker against the recorded `grant.home`. It prints `{meta, warning?}` and exits 0, or exits non-zero to refuse.
|
|
64
|
+
A hook that exits non-zero must leave no effects of its own, by atomicity or
|
|
65
|
+
compensation. The kernel treats a failed hook as having made no changes;
|
|
66
|
+
its rollback covers composed home bytes, not provider-owned host effects.
|
|
67
|
+
Errors retain a bounded provider `warning` or stderr diagnosis, identify a
|
|
68
|
+
hook that reported failure, and state that host effects are the provider's responsibility.
|
|
69
|
+
- **Rules:**
|
|
70
|
+
- A moving module with recorded `capabilityMeta`, or one whose old or new manifest declares `spawn` or `launch` hooks, must declare `upgrade`. Otherwise its plan decision is `refuse: <cap> does not declare an upgrade hook; respawn the instance to change it`.
|
|
71
|
+
- A module with neither (skills/inject only) is adopted without a hook.
|
|
72
|
+
- One refusing module refuses the whole upgrade. There are no partial upgrades.
|
|
73
|
+
- **Older kernels.** An older kernel already treats an unknown non-required event as a warning (`capability-contract.mjs:52`), so a provider can declare `upgrade` before every host has the new kernel.
|
|
74
|
+
|
|
75
|
+
## Apply
|
|
76
|
+
|
|
77
|
+
Apply runs under the claim, with the plan revision re-checked. A stale plan refuses with `E_PLAN_STALE` and attaches a fresh plan. Apply is idempotent per `--idempotency-key`, with a receipt like retire's, and does the following in order:
|
|
78
|
+
|
|
79
|
+
1. **Stage.** Stage the new module copies in `<home>/.oats/.staging-upgrade-<receipt>`, on the same filesystem so the renames are atomic, and recompose the derived files there. Use the **same code as spawn**: refactor `materialize()` so that composing a home from a resolution can target an existing home. Do not write a second composer. The derived files are:
|
|
80
|
+
- `.agents/skills`;
|
|
81
|
+
- `AGENTS.md`: the soul body at the **recorded soul commit**, the kernel blocks, then each module's inject. If the soul body at that commit can't be read, refuse;
|
|
82
|
+
- in `instance.json`: `modules`, `capabilities[]`, `capabilityRuntime[]` (the absolute hook commands that retire runs), `skills[]`, `instructions[]`, `composition`, `launch.hooks.contributions`, `resolutionRevision`.
|
|
83
|
+
Read the soul body through discovery's path rule at that recorded commit:
|
|
84
|
+
a member soul uses `souls/<agent>/AGENTS.md`; a package soul uses its
|
|
85
|
+
manifest's explicit path. Upgrade never runs launch hooks. If a moved
|
|
86
|
+
module's new manifest has no launch hook, remove its recorded launch and
|
|
87
|
+
environment contribution inside the same journaled metadata swap. If it
|
|
88
|
+
still declares a launch hook, keep the contribution, with settings and trust
|
|
89
|
+
updated from the rebuilt capability, until the next start replaces it
|
|
90
|
+
wholesale through the standard launch refresh. Undo restores the recorded
|
|
91
|
+
contribution from the backed-up `instance.json`. No pending dropped-hook
|
|
92
|
+
state or `unsetEnv` JSON field is introduced; consecutive upgrades without
|
|
93
|
+
a start do not depend on an older previous manifest.
|
|
94
|
+
2. **Keep the previous state.** This happens before anything outside staging changes. Copy `.oats/modules/<cap>` for each moving module, and the current `instance.json` and `AGENTS.md`, to `<home>/.oats/previous/<receipt>/` with `copyTreeSafe`, then verify the copy. This is not the retirement recovery root, so it is not mistaken for a retained retire.
|
|
95
|
+
3. **Provider hooks.** Run each moving module's `upgrade` hook (`apply`) from the staged copy, in the plan's module order. `OATS_UPGRADE_MODULE_DIR` names its final `<home>/.oats/modules/<cap>` path: host registrations must use that path, never staging. Hooks must be idempotent in `apply`, because a retry runs them again.
|
|
96
|
+
Before spawning a hook, persist `step: "hook <capability>"` and
|
|
97
|
+
`hooks.inFlight: <capability>`. If execution is interrupted while that
|
|
98
|
+
outcome is unknown, resume must durably record `uncertain: [<capability>]`
|
|
99
|
+
before any retry work. The act then remains forward-only even when
|
|
100
|
+
`steps.hooks` contains no recorded success. A kill between that marker and
|
|
101
|
+
spawn also counts as uncertain unless not-started can be proved.
|
|
102
|
+
4. **Swap.** Swap in place using materialize's rollback journal. Each moved module gets `modules.<cap>.previous = {from, commit, digest, materializedAt, receipt}` (one level, the latest move). `capabilityMeta[cap]` becomes the hook's `meta`.
|
|
103
|
+
5. **Baseline.** Under the lifecycle claim, before staging, previous copies or
|
|
104
|
+
provider apply hooks change the home, compare it against the existing
|
|
105
|
+
retirement baseline with the same exclusions and comparison as retirement.
|
|
106
|
+
The plan shows `homeChangedSinceSpawn: true|false`. If the home is clean,
|
|
107
|
+
replace only `homeFingerprint` after the move, atomically. If it is dirty,
|
|
108
|
+
leave the entire baseline file byte-identical. Its old fingerprint keeps
|
|
109
|
+
classing the home as "changed instance-home bytes", including for older
|
|
110
|
+
kernels, which would ignore a new dirty-marker field. Later upgrades keep
|
|
111
|
+
that same dirty baseline; retirement writes its ordinary recovery copy.
|
|
112
|
+
An upgrade never re-takes `generatedWorkFingerprint` or changes the recorded
|
|
113
|
+
`digestVersion`: all work-tree changes remain compared against spawn.
|
|
114
|
+
Existing runtime authority and exclusions remain as recorded. No baseline
|
|
115
|
+
field, format migration or new recovery mechanism is introduced.
|
|
116
|
+
Upgrade receipts (the exact `upgrade-receipt.<key>.json` naming pattern)
|
|
117
|
+
and `.oats/.staging-upgrade-*` remain excluded. `.oats/previous/` is ordinary
|
|
118
|
+
home content. The comparison and clean replacement project out only the
|
|
119
|
+
upgrade's existing regular-file `.oats-start.lock`, using the exact-path
|
|
120
|
+
`transientHomePaths` validation. Future retire fingerprints still hash any
|
|
121
|
+
mutex left behind. A change made before the move is still a change at retire.
|
|
122
|
+
6. **Commit.** After swap and baseline, record receipt `status: complete`
|
|
123
|
+
with `steps.cleaned: false`. This is the commit boundary: no success event
|
|
124
|
+
may be written before it, so rollback cannot leave a `modules-upgraded` row.
|
|
125
|
+
7. **Event, then cleanup.** Append `modules-upgraded` with
|
|
126
|
+
`{receipt, modules:[{capability, from, to}]}`, deduplicated by receipt on
|
|
127
|
+
retry. The event kind is documented in the Desktop API and has a Desktop
|
|
128
|
+
label. Then clean staging and record `steps.cleaned: true`. A post-commit
|
|
129
|
+
failure leaves a committed upgrade: the same-key retry completes event
|
|
130
|
+
publication and cleanup without hooks or copies. Start remains allowed
|
|
131
|
+
with one warning naming that retry. A new upgrade or undo plan refuses
|
|
132
|
+
until finalization finishes, so staging cannot mix with another move.
|
|
133
|
+
Retirement keeps its existing behavior: staging is excluded and previous
|
|
134
|
+
copies remain ordinary home content.
|
|
135
|
+
|
|
136
|
+
**When a step fails before the commit boundary.** The rule is set by whether any provider hook's `apply` has succeeded or has an uncertain outcome. A hook can change host state (oats.aweb's wake re-register, for example), and restoring old modules under host state the new version adopted is the same mismatch #1450 is about.
|
|
137
|
+
- **No hook has succeeded or has an uncertain outcome:** roll back fully after a failure in steps 1–2. For a hook, only an explicit non-zero result observed and recorded in the same invocation, with no prior success or uncertainty, permits full rollback. Discard the staging and `<home>/.oats/previous/<receipt>`, change nothing in the home, and record a refusal event that names the step or module.
|
|
138
|
+
- **A hook has succeeded or has an uncertain outcome:** the act only finishes forward. The receipt records `partial` with the steps and modules already done. The error names what is pending, and says to retry with the same `--idempotency-key`. That retry re-runs pending work, including an uncertain idempotent hook, and finishes the swap, baseline and event. If the retried hook fails, the act stays `partial`; it never restores old modules. If the act can't be finished, the remedy named is a respawn. The home is never put back by hand under adopted or possibly adopted host state.
|
|
139
|
+
- **The session start** refuses while a `partial` receipt for the home exists (`E_UPGRADE_PARTIAL`, naming the retry).
|
|
140
|
+
|
|
141
|
+
**`--undo`** plans and applies the reverse move to `modules.<cap>.previous`, with the same steps and hooks; it is the `upgrade` hook of the version being restored. It works only for the latest move, and only while `<home>/.oats/previous/<receipt>` exists and verifies. The same adoption rule applies, so undo works only toward a version that declares `upgrade`. A move from a version without the hook, such as the motivating oats.aweb 1.17.1, cannot be undone through the act: its `.oats/previous/<receipt>` stays for inspection by hand, and the remedy for a bad move is a respawn.
|
|
142
|
+
|
|
143
|
+
**Lifetime of `.oats/previous/`.** Each home keeps one previous state, which the next move replaces. Retire carries it in its recovery copy like any other home content.
|
|
144
|
+
|
|
145
|
+
## Restart and start (condition 4)
|
|
146
|
+
|
|
147
|
+
- `oats session start` and `oats session restart` never move modules.
|
|
148
|
+
- When a home has package drift, both print one line after the start, and the JSON gets `drift:[{capability, recorded, locked}]`: `<n> package module(s) behind the lock (<cap> <recorded> → <locked>); to move them: oats instance stop <i>; oats instance upgrade <i> --plan`.
|
|
149
|
+
`recorded` and `locked` are each `{version, commit}`. The text renders each
|
|
150
|
+
as `<version> @ <shortcommit>`, so a moved commit is visible even when the
|
|
151
|
+
version string is unchanged. Homes without package drift omit this field and
|
|
152
|
+
preserve the existing start/restart answer shape. If the lock cannot be read
|
|
153
|
+
(including malformed JSON or an unsupported lock version), start/restart
|
|
154
|
+
proceed, omit `drift`, and print one warning naming the lock and the reason.
|
|
155
|
+
- No flag on restart runs the upgrade.
|
|
156
|
+
|
|
157
|
+
## Kernel stays runtime-neutral (condition 5)
|
|
158
|
+
|
|
159
|
+
The kernel knows modules, hooks, plans and receipts only. Anything aweb-specific lives in the provider's `upgrade` hook, such as grant-home adoption, the wake re-register, or refusing a 1.17.x meta shape it cannot adopt.
|
|
160
|
+
|
|
161
|
+
## Surfaces
|
|
162
|
+
|
|
163
|
+
- **CLI:** `oats instance upgrade` with help text, in `bin/oats.mjs`.
|
|
164
|
+
- **Docs:**
|
|
165
|
+
- `docs/souls-and-instances.md:200` and `docs/first-team.md:166`: the invariant now reads "a running instance never changes under itself; a stopped one can be moved to the locked package versions with `oats instance upgrade`".
|
|
166
|
+
- `docs/desktop-cli-api.md`: the command, the event, `modules.<cap>.previous`, the start/restart `drift`.
|
|
167
|
+
- `docs/upgrading.md`: the deploy step after a package bump.
|
|
168
|
+
- The oats-operate skill.
|
|
169
|
+
- A release note.
|
|
170
|
+
- **`oats status`:** no change. Drift clears by itself after a move.
|
|
171
|
+
- **Desktop:** `modules.<cap>.previous` is a new field in JSON the Desktop reads. The implementation PR names lane:lfx as that reader and includes a test that the Desktop tolerates the field.
|
|
172
|
+
|
|
173
|
+
## Out of scope
|
|
174
|
+
|
|
175
|
+
- Member modules and the soul body (still a respawn).
|
|
176
|
+
- Remote homes (`--server`).
|
|
177
|
+
- Moving several homes in one call (a deploy loops over instances).
|
|
178
|
+
- Desktop UI beyond the event label.
|
|
179
|
+
- Automatic upgrades.
|
|
180
|
+
- oats.aweb's `upgrade` hook, which is a separate provider spec and PR and ships after this kernel release with a kernel floor.
|
|
181
|
+
|
|
182
|
+
## Acceptance
|
|
183
|
+
|
|
184
|
+
- Real-fixture tests:
|
|
185
|
+
- a stopped home on an older package version moves to the locked one. Afterwards its skills, AGENTS.md inject, hook commands, `modules` and `previous` match a fresh spawn on the locked version, apart from identity and timestamps;
|
|
186
|
+
- a running home refuses;
|
|
187
|
+
- a provider refusal changes nothing;
|
|
188
|
+
- a stale plan refuses;
|
|
189
|
+
- an idempotency replay works;
|
|
190
|
+
- `--undo` restores the previous bytes;
|
|
191
|
+
- retire after a move sees no unexplained home change.
|
|
192
|
+
- A live check on a scratch seat, after the provider's hook ships: a global-grant session seat spawned on an old oats.aweb is upgraded and restarted, then a signed mail is presented in the resumed session.
|
package/docs/design/README.md
CHANGED
|
@@ -22,6 +22,10 @@ successor, with a link to its full text.
|
|
|
22
22
|
- [Team model 3](2026-10-02-team-model-3.md): the teams a soul may join, and
|
|
23
23
|
its default, are committed in the workspace; local teams only where the
|
|
24
24
|
workspace allows them.
|
|
25
|
+
- [Module upgrade](2026-10-22-module-upgrade.md): `oats instance upgrade` moves
|
|
26
|
+
a stopped home's package modules to the locked versions, with plan, apply,
|
|
27
|
+
provider adoption and undo (supersedes workspace model v2 items 10–11 for
|
|
28
|
+
package modules).
|
|
25
29
|
|
|
26
30
|
The Desktop's design brief for designers is in
|
|
27
31
|
[packages/desktop/docs](../../packages/desktop/docs/design-brief.md).
|