@awebai/oats 0.55.1 → 0.57.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 +96 -72
- package/docs/capabilities.md +67 -3
- package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
- package/docs/desktop-cli-api.md +375 -37
- package/docs/desktop-instance-start.md +105 -12
- package/docs/desktop.md +65 -11
- package/docs/execution-targets.md +184 -9
- package/docs/harness-trust.md +128 -11
- package/docs/implementation.md +153 -11
- package/docs/integrations.md +5 -3
- package/docs/knowledge.md +117 -43
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-lane.md +26 -1
- package/docs/release-notes/v0.56.0.md +699 -0
- package/docs/release-notes/v0.57.0.md +283 -0
- package/docs/schedules.md +8 -3
- package/docs/servers.md +21 -5
- package/docs/souls-and-instances.md +134 -19
- package/docs/tui.md +215 -31
- package/docs/upgrading.md +4 -1
- package/docs/workspaces.md +26 -6
- package/lib/automations.mjs +3 -4
- package/lib/bounded-read.mjs +18 -0
- package/lib/capability-show.mjs +13 -2
- package/lib/claim.mjs +3 -4
- package/lib/core.mjs +919 -278
- package/lib/errors.mjs +39 -0
- package/lib/harness-trust-write.mjs +119 -40
- package/lib/harness-trust.mjs +31 -18
- package/lib/instance-inspect.mjs +160 -11
- package/lib/instance-lifecycle.mjs +90 -37
- package/lib/packages.mjs +8 -5
- package/lib/pi-bridge.mjs +18 -19
- package/lib/remote.mjs +88 -51
- package/lib/retire-output.mjs +9 -4
- package/lib/schedule.mjs +3 -4
- package/lib/servers.mjs +39 -6
- package/lib/session-viewer.mjs +25 -1
- package/lib/triggers.mjs +3 -4
- package/lib/workspace.mjs +6 -6
- package/lib/worktree.mjs +33 -8
- package/lib/write-through-private-file.mjs +26 -0
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +108 -13
- package/packages/client/cli-locator.mjs +16 -14
- package/packages/client/deployment-panel.mjs +4 -3
- package/packages/client/display-text.mjs +2 -1
- package/packages/client/instance-events-contract.mjs +4 -3
- package/packages/client/instance-lifecycle.mjs +235 -0
- package/packages/client/instance-presentation.mjs +9 -0
- package/packages/client/instance-tree.mjs +10 -8
- package/packages/client/kernel-lines.mjs +3 -3
- package/packages/client/launch-contract.mjs +11 -0
- package/packages/client/launch-prompt-outcome.mjs +1 -1
- package/packages/client/lifecycle-cli.mjs +12 -6
- package/packages/client/lifecycle-confirmation.mjs +407 -0
- package/packages/client/lifecycle-contract.mjs +6 -2
- package/packages/client/own-codes.mjs +1 -0
- package/packages/client/panel-views.mjs +39 -2
- package/packages/client/readiness-contract.mjs +2 -2
- package/packages/client/remote-roster.mjs +50 -5
- package/packages/client/roster-sections.mjs +3 -3
- package/packages/client/session-start.mjs +98 -0
- package/packages/client/start-gate.mjs +46 -0
- package/packages/client/start-messages.mjs +17 -0
- package/packages/client/workspace-views.mjs +2 -2
- package/packages/tui/README.md +21 -8
- package/packages/tui/lib/actions.mjs +11 -2
- package/packages/tui/lib/client.mjs +9 -2
- package/packages/tui/lib/config.mjs +39 -9
- package/packages/tui/lib/main.mjs +168 -20
- package/packages/tui/lib/model.mjs +315 -13
- package/packages/tui/lib/open.mjs +45 -0
- package/packages/tui/lib/read.mjs +171 -16
- package/packages/tui/lib/store.mjs +171 -10
- package/packages/tui/lib/term/tty.mjs +71 -12
- package/packages/tui/lib/views/act.mjs +85 -0
- package/packages/tui/lib/views/frame.mjs +145 -33
- package/packages/tui/lib/views/help.mjs +46 -11
- package/skills/oats-getting-started/SKILL.md +6 -3
package/bin/oats.mjs
CHANGED
|
@@ -26,7 +26,7 @@ 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 { runtimeNameWarning, noteRuntimeName } from "../lib/deprecation.mjs";
|
|
29
|
-
import { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect } from "../lib/errors.mjs";
|
|
29
|
+
import { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect, spawnRefusalDetails } from "../lib/errors.mjs";
|
|
30
30
|
import {
|
|
31
31
|
LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
|
|
32
32
|
capabilityManifests, capabilityTrust, capabilityExecutablePath,
|
|
@@ -38,7 +38,8 @@ import {
|
|
|
38
38
|
writeFileAtomic, LOCK_FILE, canonicalLock, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
|
|
39
39
|
classifyPackageValue, parsePackageRequest } from "../lib/packages.mjs";
|
|
40
40
|
import { harnessTrust } from "../lib/harness-trust-write.mjs";
|
|
41
|
-
import {
|
|
41
|
+
import { previewLaunchEnvironment, previewPaneEnvironment } from "../lib/core.mjs";
|
|
42
|
+
import { PI_BRIDGE, piBridgeFolders, piBridgeSkewWarnings, planPiBridges, piBridgePlanLines, piBridgeStepProblem, piBridgeFailure, kernelLookup, kernelLookupResult, planCliUpdate, desktopFirstLine, bridgeLookup, bridgeLookupProblem } from "../lib/pi-bridge.mjs";
|
|
42
43
|
import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, unlockedPackages, workspaceWarnings, memberRowByKey } from "../lib/workspace.mjs";
|
|
43
44
|
import { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "../lib/teams.mjs";
|
|
44
45
|
import { LAUNCH_KEY_UNCHECKED, LAUNCH_PREFERENCE_UNMATCHED, launchKeyQuoted, launchKeysUnmatched, launchLayers, soulLaunchCommand, unmatchedKeyMessage } from "../lib/launch-preference.mjs";
|
|
@@ -62,12 +63,12 @@ import { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, d
|
|
|
62
63
|
import { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } from "../lib/retire-output.mjs";
|
|
63
64
|
import { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } from "../lib/retained-after-retire.mjs";
|
|
64
65
|
const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
|
|
65
|
-
import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposedInstructions, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
|
|
66
|
+
import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposedInstructions, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
|
|
66
67
|
import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mjs";
|
|
67
68
|
|
|
68
69
|
const rawArgs = process.argv.slice(2);
|
|
69
70
|
/** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
|
|
70
|
-
const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "run-source", "self", "verbose", "yes", "yolo"]);
|
|
71
|
+
const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "run-source", "self", "skills", "verbose", "yes", "yolo"]);
|
|
71
72
|
/** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
|
|
72
73
|
* routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
|
|
73
74
|
* `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
|
|
@@ -103,7 +104,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
|
|
|
103
104
|
* probe) and in `status --json`, which a remote roster relays as the host's (feature
|
|
104
105
|
* server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
|
|
105
106
|
* time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
|
|
106
|
-
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"];
|
|
107
|
+
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"];
|
|
107
108
|
/** Commands `--server <id>` runs on a registered server. */
|
|
108
109
|
const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
|
|
109
110
|
const flag = (name) => {
|
|
@@ -182,7 +183,7 @@ const withLocalWarnings = (envelope) => {
|
|
|
182
183
|
return { ...envelope, warnings: theirs.map((w) => (w === same ? { ...mine, sources, message: mine.message.replace(/\(.*\)/, `(${sources.join("; ")})`) } : w)) };
|
|
183
184
|
};
|
|
184
185
|
const jsonFail = (code, message, details, exit = 1) => { console.log(JSON.stringify({ schemaVersion: 1, ok: false, error: { code, message: String(message), ...(details !== undefined ? { details } : {}) }, ...envelopeWarnings() })); process.exit(exit); };
|
|
185
|
-
/** The door of the lifecycle verbs (retire, instance stop, session, worktree; awebai/oats#892): the
|
|
186
|
+
/** The door of the lifecycle verbs (retire, instance stop, session, worktree; awebai/oats#892), and of a spawn (spawnFail): the
|
|
186
187
|
* answer to an error `e` of one of them. Its code is the error's own only when that is a kernel
|
|
187
188
|
* code (lib/errors.mjs isKernelCode); any other error is answered as `fallback`. One that has a
|
|
188
189
|
* code (the system's, Node's) and a defect (isDefect: a TypeError and its kind) get
|
|
@@ -199,6 +200,11 @@ const lifecycleFail = (e, fallback, details, exit) => {
|
|
|
199
200
|
const all = cause ? { ...details, cause } : details;
|
|
200
201
|
return JSON_MODE ? jsonFail(kernelCode(e, fallback), message, all, exit) : die(message, exit);
|
|
201
202
|
};
|
|
203
|
+
/** The answer to an error of `oats spawn` (feature spawn-kernel-codes, awebai/oats#1047): the
|
|
204
|
+
* lifecycle verbs' door (lifecycleFail), whose general code for a spawn is E_SPAWN_FAILED. A
|
|
205
|
+
* kernel code is answered as raised, whatever stage of the spawn raised it; it says nothing about
|
|
206
|
+
* how far the spawn got (`details.unconfirmed` does). E_INTERRUPTED exits 128 + the signal. */
|
|
207
|
+
const spawnFail = (e) => lifecycleFail(e, "E_SPAWN_FAILED", spawnRefusalDetails(e), e?.code === "E_INTERRUPTED" ? e.exitStatus : undefined);
|
|
202
208
|
const jsonOk = (result) => { console.log(JSON.stringify({ schemaVersion: 1, ok: true, result, ...envelopeWarnings() })); };
|
|
203
209
|
// Text mode (or a JSON answer printed before the read): the warning goes to stderr, never stdout.
|
|
204
210
|
process.on("exit", () => { const w = runtimeNameWarning(); if (w && !warningDelivered) process.stderr.write(`oats: warning: ${w.message}\n`); });
|
|
@@ -560,10 +566,14 @@ async function inspectCmd() {
|
|
|
560
566
|
// Feature soul-composed-instructions: opt-in, soul subject only; without it nothing extra is composed.
|
|
561
567
|
const instructions = args.includes("--instructions");
|
|
562
568
|
if (instructions && flag("home") !== undefined) return bail("E_BAD_ARGS", "--instructions composes a soul's instructions before a spawn: it takes --soul, not --home (an instance's composed AGENTS.md is instance.instructions)");
|
|
569
|
+
// Feature soul-skills: opt-in, soul subject only; without it no skill file is read.
|
|
570
|
+
const skills = args.includes("--skills");
|
|
571
|
+
if (skills && flag("home") !== undefined) return bail("E_BAD_ARGS", "--skills lists a soul's own skills before a spawn: it takes --soul, not --home (an instance's skills are in its home's .agents/skills/)");
|
|
563
572
|
let t = await workspaceTarget(bail, { command: "inspect" });
|
|
564
573
|
if (t) {
|
|
565
574
|
if (t.resolutionError) return bail(t.resolutionError.code, t.resolutionError.message, t.resolutionError.details ?? undefined);
|
|
566
575
|
if (instructions) t = await withComposedInstructions(t);
|
|
576
|
+
if (skills) t = await withSkills(t);
|
|
567
577
|
const doc = inspectDocument(t, { kernel: OATS_VERSION });
|
|
568
578
|
if (JSON_MODE) { jsonOk(withObservation(doc)); return; }
|
|
569
579
|
printWorkspaceInspect(doc); return;
|
|
@@ -829,7 +839,7 @@ function doctorVersionSkew(deployment) {
|
|
|
829
839
|
try { launchConfigs = launchConfigsAt(deployment); } catch (e) { unread = e.message; }
|
|
830
840
|
const warnings = piBridgeSkewWarnings(piBridgeFolders({ launchConfigs }), OATS_VERSION);
|
|
831
841
|
if (unread) warnings.push(`pi bridge — the launch configurations could not be read, so only the default pi folder and this shell's were looked at: ${unread}`);
|
|
832
|
-
for (const warning of warnings) console.log(`WARNING: ${warning}`);
|
|
842
|
+
for (const warning of warnings) console.log(`WARNING: ${terminalText(warning)}`);
|
|
833
843
|
if (warnings.length) console.log("");
|
|
834
844
|
}
|
|
835
845
|
/** The "Workspace (v2, offline view)" + "Locked packages" sections, shared by both doctor shapes. */
|
|
@@ -1035,8 +1045,10 @@ function launchPreview(bail) {
|
|
|
1035
1045
|
let r;
|
|
1036
1046
|
try { r = meta ? resolvedFromHome(home, meta) : { capabilities: [], launchConfigs: launchConfigsAt(context) }; } catch (e) { bail(e.code || "E_CONFIG_BROKEN", e.message, e.details); }
|
|
1037
1047
|
// The same planner a start uses, in preview mode: failed checks are listed, nothing is touched.
|
|
1048
|
+
// Its checks read the pane a launch would run in, as a command that only reads can know it (a
|
|
1049
|
+
// home's recorded session, a soul's session default; with no server running, not established).
|
|
1038
1050
|
let plan;
|
|
1039
|
-
try { plan = planLaunch({ home, instance, meta, contextDir: context, agentLike, selection: sel, resolvedCfg: r, preview: true }); } catch (e) { bail(e.code || "E_BAD_ARGS", e.message); }
|
|
1051
|
+
try { plan = planLaunch({ home, instance, meta, contextDir: context, agentLike, selection: sel, resolvedCfg: r, preview: true, pane: () => previewPaneEnvironment(meta ? { home, meta } : { deployment: context }) }); } catch (e) { bail(e.code || "E_BAD_ARGS", e.message); }
|
|
1040
1052
|
const { recipe } = plan;
|
|
1041
1053
|
const command = renderLaunchRecipe(recipe, { home, instance, redact: true, trustHome: plan.trustHome });
|
|
1042
1054
|
const d = describeLaunchCommand(command);
|
|
@@ -1347,7 +1359,7 @@ function instanceCmd() {
|
|
|
1347
1359
|
if (JSON_MODE) { jsonOk(plan); return; }
|
|
1348
1360
|
console.log(`stop ${name}${recursive ? " (and recorded children)" : ""} — plan ${plan.planRevision}`);
|
|
1349
1361
|
for (const t of plan.targets) console.log(` ${" ".repeat(t.depth)}${t.instance}: session ${t.session.state}${t.work.observed ? `, ${t.work.changed} changed / ${t.work.untracked} untracked on ${t.work.branch ?? "detached"}` : ", work not observed"}${t.midTask === true ? " — mid-task" : t.midTask === "unknown" ? " — activity unknown" : ""}`);
|
|
1350
|
-
for (const n of plan.notes) console.log(` note: ${n}`);
|
|
1362
|
+
for (const n of plan.notes) console.log(` note: ${terminalText(n)}`);
|
|
1351
1363
|
console.log(`apply with: oats instance stop ${name} --apply --plan-revision ${plan.planRevision} --idempotency-key <key>`);
|
|
1352
1364
|
return;
|
|
1353
1365
|
}
|
|
@@ -1391,7 +1403,7 @@ function instanceCmd() {
|
|
|
1391
1403
|
console.log(` files: ${observed.files.length} (${Object.entries(observed.summary).filter(([, n]) => n).map(([k, n]) => `${n} ${k}`).join(", ") || "clean"})`);
|
|
1392
1404
|
const lines = (f) => (f.binary ? " binary" : Number.isInteger(f.additions) ? ` +${f.additions} -${f.deletions}` : "");
|
|
1393
1405
|
for (const f of observed.files) console.log(` ${f.xy} ${f.origPath ? `${f.origPath} -> ` : ""}${f.path}${lines(f)} [${f.id}]`);
|
|
1394
|
-
for (const n of observed.notes) console.log(` note: ${n}`);
|
|
1406
|
+
for (const n of observed.notes) console.log(` note: ${terminalText(n)}`);
|
|
1395
1407
|
return;
|
|
1396
1408
|
}
|
|
1397
1409
|
const fileId = flag("file"), revision = flag("revision"), indexRevision = flag("index-revision");
|
|
@@ -1432,7 +1444,7 @@ async function readinessCmd() {
|
|
|
1432
1444
|
}
|
|
1433
1445
|
if (doc.policy) console.log(` policy: child spawns ${doc.policy.childSpawns.allowed ? "allowed" : "disabled"} (${doc.policy.childSpawns.origin.kind}${doc.policy.childSpawns.enforced ? ", enforced" : ""}); worktrees ${doc.policy.worktrees.allowed === null ? "unknown" : doc.policy.worktrees.allowed ? "allowed" : "not in this work mode"}`);
|
|
1434
1446
|
for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
|
|
1435
|
-
for (const n of doc.notes) console.log(` note: ${n}`);
|
|
1447
|
+
for (const n of doc.notes) console.log(` note: ${terminalText(n)}`);
|
|
1436
1448
|
return;
|
|
1437
1449
|
}
|
|
1438
1450
|
}
|
|
@@ -1537,7 +1549,9 @@ function harnessTrustCmd() {
|
|
|
1537
1549
|
log(`${result.mode}: native harness trust for ${result.root}`);
|
|
1538
1550
|
const used = (entry) => [...(entry.ambient ? ["ambient"] : []), ...entry.launchConfigs.map((n) => `launch configuration ${n}`)].join(", ");
|
|
1539
1551
|
for (const entry of result.entries) {
|
|
1540
|
-
|
|
1552
|
+
// A refused file was not read through to its trust value: no current value or digests to show.
|
|
1553
|
+
if (entry.status === "refused") log(`${entry.harness}: refused ${entry.file ?? "unresolved file"} ${JSON.stringify(entry.key)} (${used(entry)})`);
|
|
1554
|
+
else log(`${entry.harness}: ${entry.status} ${entry.file ?? "unresolved file"} ${JSON.stringify(entry.key)} ${JSON.stringify(entry.current)} -> ${JSON.stringify(entry.desired)} (${entry.beforeDigest ?? "missing"} -> ${entry.afterDigest ?? "unknown/absent"}) (${used(entry)})`);
|
|
1541
1555
|
if (entry.problem) log(`problem: ${entry.problem}`);
|
|
1542
1556
|
if (entry.reason) log(`skipped: ${entry.reason}`);
|
|
1543
1557
|
}
|
|
@@ -1547,7 +1561,9 @@ function harnessTrustCmd() {
|
|
|
1547
1561
|
};
|
|
1548
1562
|
try {
|
|
1549
1563
|
// Every configuration file a launch of this deployment reads: its launch configurations' too.
|
|
1550
|
-
|
|
1564
|
+
// The ambient one is the file a launch with no launch configuration reads there (its session's
|
|
1565
|
+
// environment over the server's), by the answer every launch check reads; never this shell's own.
|
|
1566
|
+
const result = harnessTrust(context.deploymentDir, { harness: selected, plan: args.includes("--plan"), launchConfigs: launchConfigsAt(context.deploymentDir), launch: previewLaunchEnvironment({ deployment: context.deploymentDir }) });
|
|
1551
1567
|
if (JSON_MODE) jsonOk(result);
|
|
1552
1568
|
else show(result);
|
|
1553
1569
|
} catch (e) {
|
|
@@ -2285,7 +2301,7 @@ async function itemsCmd(kind) {
|
|
|
2285
2301
|
/** Owner fields decide context, never message text. A problem source is display data;
|
|
2286
2302
|
* render that projection without changing the operational external source. */
|
|
2287
2303
|
function catalogProblemLine(p) {
|
|
2288
|
-
const owner = p.repoKey || p.package || (p.source ? remoteModule.
|
|
2304
|
+
const owner = p.repoKey || p.package || (p.source ? remoteModule.displayRepoRef(p.source, { pinned: true }) : null);
|
|
2289
2305
|
const where = owner ? ` [${terminalText(`${owner}: ${p.path}`)}]` : "";
|
|
2290
2306
|
return `! ${p.code}: ${p.message}${where}`;
|
|
2291
2307
|
}
|
|
@@ -2700,6 +2716,15 @@ function herdrSpawnFlag() {
|
|
|
2700
2716
|
if (flag("herdr-socket") !== undefined) return "--herdr-socket";
|
|
2701
2717
|
return undefined;
|
|
2702
2718
|
}
|
|
2719
|
+
/** A spawn preview's text: the local one, or a host's answer to a routed
|
|
2720
|
+
* preview (`server`, its id), which this side printed the same way (#610). */
|
|
2721
|
+
function printSpawnPreview(r, { server, soulFetched = false } = {}) {
|
|
2722
|
+
// A host before 0.27 names the harness `runtime` (it still answers spawn-preview-2).
|
|
2723
|
+
const harness = r.harness ?? r.runtime;
|
|
2724
|
+
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)" : ""}`);
|
|
2725
|
+
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");
|
|
2726
|
+
for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
|
|
2727
|
+
}
|
|
2703
2728
|
async function spawnCmd() {
|
|
2704
2729
|
// JSON mode: contract envelope, stable error codes, stderr-only progress.
|
|
2705
2730
|
const bail = (code, msg, details, exit) => (JSON_MODE ? jsonFail(code, msg, details, exit) : die(msg, exit));
|
|
@@ -2911,7 +2936,7 @@ async function spawnCmd() {
|
|
|
2911
2936
|
...(args.includes("--allow-child-spawns") ? { allowChildSpawns: true } : args.includes("--no-child-spawns") ? { allowChildSpawns: false } : {}),
|
|
2912
2937
|
// Directory execution uses deployment configuration, not an ambient Git
|
|
2913
2938
|
// checkout (especially when invoked via --dir from a source instance).
|
|
2914
|
-
// An attached instance's repository is
|
|
2939
|
+
// An attached instance's repository is the repository of the tree it is attached to (derived by the kernel).
|
|
2915
2940
|
repo: preparedRepo !== undefined ? preparedRepo : ["directory", "attached"].includes(requestedWork || agent.work)
|
|
2916
2941
|
? repo : repo || defaultRepo(workspaceOf(root)) || defaultRepo(process.cwd()),
|
|
2917
2942
|
work: requestedWork, workDir, harness: harnessFlag(), backend, yolo, model: flag("model"), branch,
|
|
@@ -2934,42 +2959,14 @@ async function spawnCmd() {
|
|
|
2934
2959
|
// (the deployment's cache had no entry for its commit): the result says so.
|
|
2935
2960
|
if (prepared) r.soulFetched = soulFetched;
|
|
2936
2961
|
if (JSON_MODE) { jsonOk(withObservation(r)); return; }
|
|
2937
|
-
|
|
2938
|
-
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");
|
|
2939
|
-
for (const w of r.warnings || []) console.log(` WARNING: ${w}`);
|
|
2962
|
+
printSpawnPreview(r, { soulFetched });
|
|
2940
2963
|
return;
|
|
2941
2964
|
}
|
|
2942
2965
|
} catch (e) {
|
|
2943
|
-
//
|
|
2944
|
-
//
|
|
2945
|
-
//
|
|
2946
|
-
|
|
2947
|
-
if (TYPED_CLI_FAILURES.has(e?.code)) throw e;
|
|
2948
|
-
// A launch refusal (configuration, executable, environment reference,
|
|
2949
|
-
// model, harness) is a fact about the selection, not a spawn-mechanism
|
|
2950
|
-
// failure: it keeps its own code so a GUI can act on it.
|
|
2951
|
-
if (typeof e?.code === "string" && /^E_LAUNCH_|^E_MODEL_UNKNOWN$|^E_UNSUPPORTED_HARNESS$|^E_HARNESS_UNAVAILABLE$|^E_CLAUDE_CONFIG_REMOVED$/.test(e.code)) { bail(e.code, e.message, e.details); throw e; }
|
|
2952
|
-
// An unmet declared requirement is a fact about the soul's configuration
|
|
2953
|
-
// (with a remedy), not a spawn-mechanism failure: keep its code and details.
|
|
2954
|
-
if (e?.code === "E_REQUIREMENT_INACTIVE") { bail(e.code, e.message, { soul: e.soul, capabilities: e.capabilities, context: e.context, remedy: e.remedy }); throw e; }
|
|
2955
|
-
if (e?.code === "E_CHILD_SPAWNS_DISABLED") { bail(e.code, e.message, { parent: e.parent, policy: e.policy }); throw e; }
|
|
2956
|
-
if (["E_BRANCH_EXISTS", "E_BASE_UNKNOWN"].includes(e?.code)) { bail(e.code, e.message); throw e; }
|
|
2957
|
-
// #796: interrupted while its worktree hooks ran: rolled back (the message says how far), 128+signal.
|
|
2958
|
-
if (e?.code === "E_INTERRUPTED") { bail(e.code, e.message, e.details, e.exitStatus); throw e; }
|
|
2959
|
-
// A required spawn or worktree hook that failed, or answered outside its environment contract, keeps
|
|
2960
|
-
// its typed code: the hooks' receipt (`details.hooks`, paths only) and `unconfirmed` when the rollback
|
|
2961
|
-
// could not confirm its effects. Never `home`: a consumer reads that as retained effects.
|
|
2962
|
-
if (e?.code === "E_REQUIRED_HOOK_FAILED" || e?.code === "E_HOOK_ENVIRONMENT_CONTRACT") { bail(e.code, e.message, { hooks: e.details?.hooks ?? [], ...(e.details?.unconfirmed === true ? { unconfirmed: true } : {}) }); throw e; }
|
|
2963
|
-
// The observed base could not be fetched into the clone: the clone, the repository and the commit travel along.
|
|
2964
|
-
if (e?.code === "E_REMOTE_UNREADABLE" && e.details?.commit) { bail(e.code, e.message, e.details); throw e; }
|
|
2965
|
-
// K6b: the confirmed decision drifted — the fresh decision travels with the refusal so a GUI re-previews.
|
|
2966
|
-
if (e?.code === "E_DECISION_STALE") { bail(e.code, e.message, { decision: e.decision }); throw e; }
|
|
2967
|
-
if (e?.code === "E_IDEMPOTENCY_CONFLICT") { bail(e.code, e.message, { instance: e.instance, home: e.home }); throw e; }
|
|
2968
|
-
if (e?.code === "E_PLACEMENT_TAKEN") { bail(e.code, e.message, { instance: e.instance, home: e.home }); throw e; }
|
|
2969
|
-
if (e?.code === "E_INSTANCE_NAME_TAKEN") { bail(e.code, e.message, { instance: e.instance, home: e.home ?? null, ...(e.session ? { session: e.session } : {}) }); throw e; }
|
|
2970
|
-
if (e?.code === "E_INSTANCE_NAME_INVALID") { bail(e.code, e.message, e.details); throw e; }
|
|
2971
|
-
if (e?.code === "E_SPAWN_INCOMPLETE") { bail(e.code, e.message, { ...e.details, instance: e.instance, home: e.home, launched: e.launched }); throw e; }
|
|
2972
|
-
bail(["E_BAD_ARGS", "E_RELATIVE_AMBIGUOUS"].includes(e.code) ? e.code : "E_SPAWN_FAILED", e.message || e, e.details?.unconfirmed === true ? e.details : undefined); throw e;
|
|
2966
|
+
// The kernel's code, as raised, through the door every lifecycle verb has (spawnFail): a refusal
|
|
2967
|
+
// with a remedy is never answered as "the spawn mechanism failed". E_SPAWN_FAILED is for an
|
|
2968
|
+
// error with no kernel code; a typed CLI failure keeps its own name.
|
|
2969
|
+
spawnFail(e); throw e;
|
|
2973
2970
|
}
|
|
2974
2971
|
// The instance exists from here on: a failed wake save is reported beside
|
|
2975
2972
|
// the full receipt, never hidden, and never causes a second spawn.
|
|
@@ -3014,7 +3011,7 @@ async function spawnCmd() {
|
|
|
3014
3011
|
if (wakeSchedule) console.log(` wake: schedule ${wakeSchedule.id} (${wakeSchedule.cron} ${wakeSchedule.tz}), next ${wakeSchedule.nextRun || "disabled"}`);
|
|
3015
3012
|
if (wakeScheduleError) console.error(` wake: NOT saved — ${wakeScheduleError.message} (the instance is created and launched; add the wake by hand with oats schedule add)`);
|
|
3016
3013
|
if (!r.launched) console.log(` launch: oats session start --home ${shellQuote(r.home)}`);
|
|
3017
|
-
for (const w of r.warnings || []) console.log(` WARNING: ${w}`);
|
|
3014
|
+
for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
|
|
3018
3015
|
console.log(` attach: ${r.attach}`);
|
|
3019
3016
|
}
|
|
3020
3017
|
|
|
@@ -3048,7 +3045,7 @@ function retireCmd() {
|
|
|
3048
3045
|
console.log(`retire ${name} — plan ${plan.planRevision}`);
|
|
3049
3046
|
console.log(` session ${plan.facts.session.state}; work ${plan.facts.work.observed ? `${plan.facts.work.changed} changed / ${plan.facts.work.untracked} untracked on ${plan.facts.work.branch ?? (plan.facts.work.detached ? "detached" : "a ref OATS carries no branch name for")}` : `not observed (${plan.facts.work.reason})`}; children ${plan.facts.children.length}; pull request ${plan.facts.pullRequest}`);
|
|
3050
3047
|
console.log(` ${retireDefaultsLine(plan)}`);
|
|
3051
|
-
for (const n of plan.notes) console.log(` note: ${n}`);
|
|
3048
|
+
for (const n of plan.notes) console.log(` note: ${terminalText(n)}`);
|
|
3052
3049
|
return;
|
|
3053
3050
|
} catch (e) { return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { ...e.details, candidates: e.candidates } : e.details); }
|
|
3054
3051
|
}
|
|
@@ -3093,13 +3090,15 @@ function retireCmd() {
|
|
|
3093
3090
|
revalidate = () => {
|
|
3094
3091
|
try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { planFailure = e; throw e; }
|
|
3095
3092
|
if (fresh.planRevision !== planRev) throw (stalePlan = Object.assign(new Error(`the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`), { code: "E_PLAN_STALE", details: { plan: fresh } }));
|
|
3096
|
-
return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children };
|
|
3093
|
+
return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children, ambiguous: fresh.facts.ambiguous };
|
|
3097
3094
|
};
|
|
3098
3095
|
} else {
|
|
3099
3096
|
// A plain or --self retire reads its recorded children the same way: under the claim, as they
|
|
3100
3097
|
// are when the retire starts (an earlier retire that kept the home has repaired lineage by
|
|
3101
3098
|
// then), and none when there are none.
|
|
3102
|
-
|
|
3099
|
+
// The instances the plan lists under `ambiguous` go with them: the retire does not act on
|
|
3100
|
+
// them, and says what it left the ones attached to a tree it moved or removed with.
|
|
3101
|
+
revalidate = () => { const recorded = descendantsOf(root, name); return { ...(recorded.length ? { children: recorded } : {}), ...(recorded.ambiguous?.length ? { ambiguous: recorded.ambiguous } : {}) }; };
|
|
3103
3102
|
}
|
|
3104
3103
|
let r;
|
|
3105
3104
|
try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), [RETIRE_UNDER_CLAIM]: revalidate }); }
|
|
@@ -3158,9 +3157,11 @@ function retireCmd() {
|
|
|
3158
3157
|
process.exit(1);
|
|
3159
3158
|
}
|
|
3160
3159
|
console.log(`Retired ${r.retired} (agent ${r.agent})${r.worktreeRemoved ? ", worktree removed" : ""}`);
|
|
3161
|
-
// An attached child the retire repointed to
|
|
3162
|
-
|
|
3163
|
-
|
|
3160
|
+
// An attached child the retire repointed to a retained worktree, work/ (#718) or an extra tree
|
|
3161
|
+
// (#964), as its link now reads.
|
|
3162
|
+
const retainedAt = [...(r.retention?.worktree === "retained" ? [r.retention.movedTo] : []), ...(r.extraWorktrees || []).filter((t) => t.outcome === "retained").map((t) => t.movedTo)];
|
|
3163
|
+
const followsWorktree = (k) => { try { const to = readlinkSync(join(k.home, "work")); return retainedAt.includes(to) ? to : null; } catch { return null; } };
|
|
3164
|
+
for (const k of r.childrenStopped || []) { const to = followsWorktree(k); console.log(` child ${k.instance}: ${k.alreadyIdle ? "already idle" : "stopped"}${to ? `; its work now links to the retained worktree ${to}` : ""}`); }
|
|
3164
3165
|
// Preserving work and not saying so leaves the operator believing it is gone,
|
|
3165
3166
|
// which is most of the harm of deleting it. Name the classes and the path.
|
|
3166
3167
|
for (const line of workRecoveryLines(r)) console.log(line);
|
|
@@ -3499,7 +3500,7 @@ async function sessionCmd() {
|
|
|
3499
3500
|
else {
|
|
3500
3501
|
console.log(JSON.stringify(result, null, 2));
|
|
3501
3502
|
// A start's launch-hook warnings, as spawn prints its own (stderr keeps stdout one JSON document).
|
|
3502
|
-
for (const w of result?.warnings || []) console.error(` WARNING: ${w}`);
|
|
3503
|
+
for (const w of result?.warnings || []) console.error(` WARNING: ${terminalText(w)}`);
|
|
3503
3504
|
}
|
|
3504
3505
|
} catch (e) { lifecycleFail(e, "E_SESSION_FAILED", e.details); }
|
|
3505
3506
|
}
|
|
@@ -3966,6 +3967,9 @@ function updateCmd() {
|
|
|
3966
3967
|
if (!steps.length) return end(untouched || ahead ? `\nNothing for \`oats update\` to run.${untouchedNote}` : "\nUp to date.");
|
|
3967
3968
|
console.log("\nUpdate steps:");
|
|
3968
3969
|
for (const s of steps) console.log(` ${s.display}`);
|
|
3970
|
+
// A Desktop refuses a CLI of a newer minor (docs/upgrading.md, "Why the Desktop goes first").
|
|
3971
|
+
const desktopFirst = desktopFirstLine(cli);
|
|
3972
|
+
if (desktopFirst) console.log(`\n${desktopFirst}`);
|
|
3969
3973
|
if (checkOnly) return end("\n(--check: not executing)");
|
|
3970
3974
|
const interactive = process.stdin.isTTY && process.stdout.isTTY;
|
|
3971
3975
|
if (interactive) {
|
|
@@ -4064,7 +4068,7 @@ async function experimentalCmd() {
|
|
|
4064
4068
|
async function serverCmd() {
|
|
4065
4069
|
const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
|
|
4066
4070
|
const sub = args[1];
|
|
4067
|
-
const usage = "usage: oats server add <id> --ssh <host-alias> --workspace </abs/path> [--oats <path>] [--path <dir:dir>] [--label <text>] [--replace] | connect <id> --ssh <host-alias> [--workspace-ref <ref>] [--dir </abs/path or ~/path on the host>] [--oats <path>] [--path <dir:dir>] [--label <text>] [--install-oats] [--replace] | list [--workspace-ref <ref>] | remove <id> | check <id> | roster [--server <id>] | forget <id> --instance <name> [--json]";
|
|
4071
|
+
const usage = "usage: oats server add <id> --ssh <host-alias> --workspace </abs/path> [--oats <path>] [--path <dir:dir>] [--label <text>] [--replace] | connect <id> --ssh <host-alias> [--workspace-ref <ref>] [--dir </abs/path or ~/path on the host>] [--oats <path>] [--path <dir:dir>] [--label <text>] [--install-oats] [--replace] | list [--workspace-ref <ref>] | remove <id> | check <id> | roster [--server <id>] [--workspace-key <key>]... | forget <id> --instance <name> [--json]";
|
|
4068
4072
|
if (!["add", "connect", "list", "remove", "check", "roster", "forget"].includes(sub)) bail("E_USAGE", usage);
|
|
4069
4073
|
if (sub === "connect") return serverConnectCmd(bail);
|
|
4070
4074
|
if (sub === "forget") {
|
|
@@ -4084,13 +4088,21 @@ async function serverCmd() {
|
|
|
4084
4088
|
if (sub === "roster") {
|
|
4085
4089
|
// The remote roster for the Desktop and operators: grouped by saved route
|
|
4086
4090
|
// target, one bounded status pull per target, all at once, saved routes as the action
|
|
4087
|
-
// authority. --server narrows to one registry id
|
|
4091
|
+
// authority. --server narrows to one registry id; --workspace-key (repeatable, every occurrence
|
|
4092
|
+
// counts) to the groups that can belong to those workspaces (lib/servers.mjs rosterGroups).
|
|
4088
4093
|
const only = flag("server") === true ? bail("E_BAD_ARGS", "--server needs a registered server id") : flag("server");
|
|
4089
4094
|
const ms = (name) => { const v = flag(name); if (v === undefined) return undefined; const n = Number(v); if (!Number.isInteger(n) || n < 1000) bail("E_BAD_ARGS", `--${name} takes whole milliseconds, at least 1000`); return n; };
|
|
4095
|
+
let workspaceKeys;
|
|
4096
|
+
for (let i = 0; i < args.length; i++) if (args[i] === "--workspace-key") {
|
|
4097
|
+
const v = args[i + 1];
|
|
4098
|
+
if (!v || v.startsWith("--")) bail("E_BAD_ARGS", "--workspace-key needs a workspace key (as a host's oats status --json workspace.key reports it)");
|
|
4099
|
+
(workspaceKeys ||= []).push(v);
|
|
4100
|
+
i++;
|
|
4101
|
+
}
|
|
4090
4102
|
let out;
|
|
4091
|
-
try { out = await rosterGroups({ server: only, io: { budgetMs: ms("budget"), perTargetTimeoutMs: ms("per-target") } }); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
|
|
4103
|
+
try { out = await rosterGroups({ server: only, workspaceKeys, io: { budgetMs: ms("budget"), perTargetTimeoutMs: ms("per-target") } }); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
|
|
4092
4104
|
if (JSON_MODE) { jsonOk(out); return; }
|
|
4093
|
-
if (!out.groups.length) { console.log("no remote groups: no registrations and no saved routes"); return; }
|
|
4105
|
+
if (!out.groups.length) { console.log(workspaceKeys ? "no remote groups for the given workspace keys" : "no remote groups: no registrations and no saved routes"); return; }
|
|
4094
4106
|
for (const g of out.groups) {
|
|
4095
4107
|
console.log(` ${g.server}${g.label && g.label !== g.server ? ` ${g.label}` : ""} [${g.id}] ssh ${g.target.sshHost} workspace ${g.target.workspace}${g.registrationPresent ? "" : " (registration removed or changed; saved routes only)"}`);
|
|
4096
4108
|
console.log(g.probe?.ok ? ` reachable, ${g.souls.length} soul(s)` : ` UNREACHABLE: ${g.probe?.error?.message || "?"}`);
|
|
@@ -4455,11 +4467,14 @@ async function serverRouteCmd() {
|
|
|
4455
4467
|
if (!envelope.ok && !(cmd === "retire" && envelope.result)) die(`${id}: ${envelope.error?.message || "remote command failed"} (${envelope.error?.code || "E_REMOTE"})`);
|
|
4456
4468
|
const r = envelope.result;
|
|
4457
4469
|
const target = r.target || {};
|
|
4458
|
-
|
|
4470
|
+
// A routed preview created nothing, there or here: the local preview's lines, naming the server.
|
|
4471
|
+
// The host's answer decides, not the flag: one that spawned is reported as the spawn it was.
|
|
4472
|
+
if (cmd === "spawn" && rest.includes("--preview") && r.preview === true) printSpawnPreview(r, { server: id, soulFetched: r.soulFetched === true });
|
|
4473
|
+
else if (cmd === "spawn") {
|
|
4459
4474
|
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"}`);
|
|
4460
4475
|
console.log(` remote home: ${r.home}`);
|
|
4461
4476
|
console.log(` route snapshot: ${r.snapshot ? shortPath(r.snapshot) : "none (see the warning)"}`);
|
|
4462
|
-
for (const w of r.warnings || []) console.log(` WARNING: ${w}`);
|
|
4477
|
+
for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
|
|
4463
4478
|
console.log(` attach: oats session attach --server ${shellQuote(id)} --instance ${shellQuote(r.instance)}`);
|
|
4464
4479
|
} else if (cmd === "retire") {
|
|
4465
4480
|
// Everything the local retireCmd tells the operator, for a remote home
|
|
@@ -4474,6 +4489,7 @@ async function serverRouteCmd() {
|
|
|
4474
4489
|
console.log(`Retired ${r.retired} on ${id}${r.deferred ? " (deferred completion scheduled there)" : ""}${r.rollbackIncomplete ? " — cleanup INCOMPLETE on the server, home retained there" : ""}`);
|
|
4475
4490
|
for (const line of workRecoveryLines(r, { host: target.sshHost })) console.log(line);
|
|
4476
4491
|
for (const line of extraWorktreeLines(r, { host: target.sshHost })) console.log(line);
|
|
4492
|
+
for (const line of warningLines(r)) console.log(line);
|
|
4477
4493
|
if (r.rollbackIncomplete) {
|
|
4478
4494
|
for (const f of r.rollbackIncomplete) console.error(` ${f}`);
|
|
4479
4495
|
const branch = failedSpawnBranchLine(r, r.rollbackIncomplete, { host: target.sshHost });
|
|
@@ -4586,13 +4602,12 @@ else if (cmd === "status") await status();
|
|
|
4586
4602
|
else if (cmd === "pane") await paneCmd();
|
|
4587
4603
|
else if (cmd === "tui") await tuiCmd();
|
|
4588
4604
|
else if (cmd === "version" || cmd === "--version" || cmd === "-v") versionCmd();
|
|
4589
|
-
// Same rule as the inner catch: a typed CLI failure surfaces with its own code
|
|
4590
|
-
// through the shared boundary, never re-badged as a spawn-mechanism failure.
|
|
4591
4605
|
else if (cmd === "session") await sessionCmd();
|
|
4592
4606
|
else if (cmd === "schedule") await scheduleCmd();
|
|
4593
4607
|
else if (cmd === "trigger") await triggerCmd();
|
|
4594
4608
|
else if (cmd === "automations") await automationsCmd();
|
|
4595
|
-
|
|
4609
|
+
// What a spawn throws outside its kernel stage goes through the same door as the inner catch.
|
|
4610
|
+
else if (cmd === "spawn") { try { await spawnCmd(); } catch (e) { spawnFail(e); throw e; } }
|
|
4596
4611
|
// What a retire throws outside its own answers (the root, a replay's read) goes through the same door.
|
|
4597
4612
|
// An exception after the retire has returned (retireReturned) is rethrown, here and by the handler
|
|
4598
4613
|
// of typed failures below: a crash is read as "not confirmed", which is the truth, where an error
|
|
@@ -4654,9 +4669,11 @@ Usage:
|
|
|
4654
4669
|
oats tui [--dir <path>] [--ascii] PREVIEW: the full-screen terminal client (docs/tui.md):
|
|
4655
4670
|
the instances of the workspace of the deployment at or
|
|
4656
4671
|
above <path> (default: where you are), on this machine
|
|
4657
|
-
and on the machines registered here
|
|
4658
|
-
|
|
4659
|
-
|
|
4672
|
+
and on the machines registered here. Enter opens an agent's
|
|
4673
|
+
terminal; it stops, starts, restarts and retires them after a
|
|
4674
|
+
confirmation. ? help, w workspaces, q quit. Needs a terminal on
|
|
4675
|
+
stdin and stdout and has no --json form; --ascii = ASCII rules
|
|
4676
|
+
and marks
|
|
4660
4677
|
oats server add <id> --ssh <alias> register another machine's OATS (OpenSSH alias,
|
|
4661
4678
|
--workspace </abs/path> [--oats <p>] remote workspace, remote oats path; no keys stored;
|
|
4662
4679
|
[--path <dir:dir>] --path = dirs prepended to the remote PATH, e.g. ~/.local/bin)
|
|
@@ -4678,6 +4695,9 @@ Usage:
|
|
|
4678
4695
|
[--budget <ms>] [--per-target <ms>] target: one status pull per group within a total
|
|
4679
4696
|
[--json] budget (45 s, 20 s per target); every instance the
|
|
4680
4697
|
server reports is addressable by --home or name
|
|
4698
|
+
[--workspace-key <key>]... only groups that can belong to these workspaces:
|
|
4699
|
+
registered for one of them, workspace not known,
|
|
4700
|
+
or saved routes only (repeatable)
|
|
4681
4701
|
oats server forget <id> --instance <name> drop a saved route whose remote instance is gone
|
|
4682
4702
|
(the roster shows it as missingRemotely)
|
|
4683
4703
|
oats retire <instance> --home <path> retire exactly that home when two agents own an
|
|
@@ -4790,12 +4810,14 @@ Usage:
|
|
|
4790
4810
|
a detached external retirement runs
|
|
4791
4811
|
oats inspect [--dir <scope>] [--soul <name> one authoritative JSON answer for a GUI: souls
|
|
4792
4812
|
[--agents-root <abs>]] [--home <abs>] (harness defaults, editability, instructions),
|
|
4793
|
-
[--instructions] [--
|
|
4794
|
-
[--json]
|
|
4813
|
+
[--instructions] [--skills] installed capabilities with health, effective
|
|
4814
|
+
[--max-age <s>] [--json] layer bindings and activation, declared
|
|
4795
4815
|
operations with availability; --home answers the
|
|
4796
4816
|
running home's recorded modules and their drift
|
|
4797
4817
|
from the deployment; --instructions (--soul only)
|
|
4798
|
-
adds the AGENTS.md a spawn of the soul here would write
|
|
4818
|
+
adds the AGENTS.md a spawn of the soul here would write;
|
|
4819
|
+
--skills (--soul only) adds the soul's own skills, the
|
|
4820
|
+
ones a spawn copies, with each file's text
|
|
4799
4821
|
oats operation run <layer>:<name> run an operation the soul's core capability for that
|
|
4800
4822
|
(--home <abs> | --soul <name> [--dir <d>]) layer declares (knowledge:harvest, knowledge:
|
|
4801
4823
|
[--arg k=v ...] [--json] inspect ...): resolved from the home's recorded
|
|
@@ -4906,7 +4928,9 @@ Usage:
|
|
|
4906
4928
|
again with the same arguments: a no-op; --preview:
|
|
4907
4929
|
the clone, path, branch, base and hooks, nothing done
|
|
4908
4930
|
oats worktree remove --purpose <p> [--json] git worktree remove of a tree made by add (a dirty
|
|
4909
|
-
tree is refused: E_WORKTREE_DIRTY
|
|
4931
|
+
tree is refused: E_WORKTREE_DIRTY; so is the work of an
|
|
4932
|
+
attached instance whose session is running or cannot
|
|
4933
|
+
be read: E_CHILDREN_RUNNING); the branch is kept
|
|
4910
4934
|
oats readiness (--soul <n> | --home <abs>) [--policy] [--json]
|
|
4911
4935
|
readinessApi 2 for a soul or an instance home:
|
|
4912
4936
|
installed | configured | member | providers, each
|
package/docs/capabilities.md
CHANGED
|
@@ -319,8 +319,9 @@ A self-contained package has an `oats.json`:
|
|
|
319
319
|
Spawn alone can see two more cases, and refuses the spawn with
|
|
320
320
|
`E_CAPABILITY_BROKEN` and rolls it back: a declared root that is a
|
|
321
321
|
symlink in the work (also one whose target is missing), and roots of
|
|
322
|
-
different capabilities that overlap. `oats spawn --json`
|
|
323
|
-
|
|
322
|
+
different capabilities that overlap. `oats spawn --json` answers these
|
|
323
|
+
with `E_CAPABILITY_BROKEN` and the same message (`E_SPAWN_FAILED`
|
|
324
|
+
before 0.56.0).
|
|
324
325
|
|
|
325
326
|
A malformed `retirement` is refused wherever the manifest is read: member
|
|
326
327
|
discovery (`E_WORKSPACE_SCHEMA`), package manifests (`E_PACKAGE_MANIFEST`)
|
|
@@ -352,15 +353,29 @@ A self-contained package has an `oats.json`:
|
|
|
352
353
|
A harness package is **verified at spawn, never installed there**: installing
|
|
353
354
|
would mutate the operator's harness configuration without asking, in the
|
|
354
355
|
middle of a spawn. A missing, uninstalled or disabled package fails the spawn
|
|
355
|
-
with direct package-manager guidance for the operator
|
|
356
|
+
with direct package-manager guidance for the operator
|
|
357
|
+
(`E_HARNESS_RESOURCE_MISSING`; a start, a restart and a launch plan's
|
|
358
|
+
`harness-packages` check answer the same code, `E_HARNESS_PACKAGE` before
|
|
359
|
+
0.56.0). The command uses the
|
|
356
360
|
selected harness executable and resource directory, with Claude marketplace
|
|
357
361
|
registration before plugin installation. Run it in the indicated context
|
|
358
362
|
with the same launch environment; spawn and restart never install packages.
|
|
363
|
+
The probe runs the executable the launch's lookup selected, with the
|
|
364
|
+
`PATH`, `HOME` and harness folder the launch's
|
|
365
|
+
pane will have, never the calling process's in their place, and the command
|
|
366
|
+
starts with that folder's variable when the launch has one. Besides
|
|
367
|
+
`E_HARNESS_RESOURCE_MISSING` for a missing package, the check raises
|
|
368
|
+
`E_RUNTIME_ENDPOINT_UNKNOWN` when one of those names cannot be read from
|
|
369
|
+
the pane, and probes nothing
|
|
370
|
+
([the checks read the pane](execution-targets.md#the-checks-read-the-pane)).
|
|
359
371
|
- OATS never installs a host requirement silently. A missing host command is
|
|
360
372
|
the operator's to install; `oats doctor` reports it. Consent to install is
|
|
361
373
|
separate from declaring the package.
|
|
362
374
|
- `environment` lists the exact launch variables the capability may set;
|
|
363
375
|
spawn hook output must be a subset and use the capability vendor prefix.
|
|
376
|
+
A listed variable is the capability's to decide: a launch it is part of
|
|
377
|
+
never inherits one its hooks leave out
|
|
378
|
+
([a declared name is the provider's](#a-declared-name-is-the-providers)).
|
|
364
379
|
- `triggerSources` (optional) declares the capability's
|
|
365
380
|
[trigger sources](#trigger-sources-triggersources). It is checked only
|
|
366
381
|
where a source is used, never when the capability loads.
|
|
@@ -740,6 +755,55 @@ Spawn order is by capability name; retirement reverses successful
|
|
|
740
755
|
spawn order. Hooks run from the instance's own copy
|
|
741
756
|
(`<home>/.oats/modules/<cap>/`).
|
|
742
757
|
|
|
758
|
+
### A declared name is the provider's
|
|
759
|
+
|
|
760
|
+
A variable a capability declares in `environment` is the capability's to
|
|
761
|
+
decide, for every launch the capability is part of, from 0.56.0. A launch
|
|
762
|
+
starts with exactly what its capabilities' hooks return for those names:
|
|
763
|
+
|
|
764
|
+
- **Returned:** the launch has the hook's value, as before.
|
|
765
|
+
- **Left out** (the hook answered without it, the hook failed, or the
|
|
766
|
+
capability has no hook that ran for this launch): the launch has **no**
|
|
767
|
+
such variable. It is removed from the harness's environment, never
|
|
768
|
+
inherited from the pane's ambient environment: the tmux server's global
|
|
769
|
+
one, the session's, the login shell that started the server, or the
|
|
770
|
+
Desktop's. Before 0.56.0 such a name kept whatever value the pane held, so
|
|
771
|
+
one instance's value (`AWEB_DELIVERY=session`, say) could reach another
|
|
772
|
+
instance launched in the same session or on the same server.
|
|
773
|
+
- **Set by the launch configuration's `env`:** the configuration's value,
|
|
774
|
+
as before. It is the operator's explicit setting on the launch's own
|
|
775
|
+
command, not an ambient value. (A configuration still cannot override a
|
|
776
|
+
name a capability's hook returns: `E_LAUNCH_ENV_CONFLICT`.)
|
|
777
|
+
|
|
778
|
+
The capabilities a launch is checked against are the ones its hooks run
|
|
779
|
+
against: for a spawn, the soul's composed capabilities, with their spawn hooks'
|
|
780
|
+
answers; for a start or restart, the providers the spawn captured, with the
|
|
781
|
+
recorded contributions and the answers of the launch hooks that run again
|
|
782
|
+
then. A name two capabilities declare is removed unless one of them returns
|
|
783
|
+
it. Each window gets this on its own command: OATS unsets the removed names
|
|
784
|
+
in the window's command (as it does `COLORFGBG`), before the launch's own
|
|
785
|
+
assignments, for a spawn, a start, a start in place and a restart. The
|
|
786
|
+
persisted launch command (`instance.json` `command`) does not change. The
|
|
787
|
+
shell a pane falls back to when the harness exits is started by that command,
|
|
788
|
+
so it has none of them either.
|
|
789
|
+
|
|
790
|
+
A removed name that selects a harness's configuration folder (a capability
|
|
791
|
+
may declare `CLAUDE_CONFIG_DIR`, `CODEX_HOME` or `PI_CODING_AGENT_DIR` under a
|
|
792
|
+
namespace it names) reads as not set in the checks of that launch: the
|
|
793
|
+
package probe, folder trust and readiness then read the default folder under
|
|
794
|
+
`HOME`, as the harness will. A spawn's first package check runs before its
|
|
795
|
+
hooks and cannot know it yet; its check on the session it gets does
|
|
796
|
+
([one limit](execution-targets.md#the-checks-read-the-pane)).
|
|
797
|
+
|
|
798
|
+
A launch whose capabilities do not declare a name is unchanged: an ambient
|
|
799
|
+
value of that name still reaches it. The tmux server's and the session's
|
|
800
|
+
environment are not changed either (see
|
|
801
|
+
[the environment of the server and its panes](execution-targets.md#the-environment-of-the-server-and-its-panes)).
|
|
802
|
+
**A limit for Codex:** the removed names are not set for Codex's tool
|
|
803
|
+
commands (`shell_environment_policy.set`), but a Codex app-server that runs
|
|
804
|
+
outside the launch (a shared daemon another process started) has that
|
|
805
|
+
process's environment, which OATS does not reach.
|
|
806
|
+
|
|
743
807
|
### The node a hook writes down
|
|
744
808
|
|
|
745
809
|
A hook or a command that writes a `node` path into something that outlives it
|
|
@@ -60,11 +60,35 @@ symlink enters as `symlink:<target>`; empty directories and a top-level `.git/`
|
|
|
60
60
|
needs them; whole trees from a server without partial fetches; awebai/oats#384) into a bare cache `<cacheDir>/<sha256(key)>/` (default
|
|
61
61
|
`~/.cache/oats/remotes`; the CLI honours `OATS_REMOTE_CACHE`) and pinned as `refs/oats/commits/<oid>`.
|
|
62
62
|
The cache may be wiped at any time. Operations on one cache repo are serialized.
|
|
63
|
+
- Only a successfully parsed Git version below 2.45 authorizes a version-driven
|
|
64
|
+
rebuild of a partial cache into full mode. A failed or unparseable version
|
|
65
|
+
probe refuses the read as `E_REMOTE_UNREADABLE` under the existing failure
|
|
66
|
+
classification, preserving the cache, fetch mode and all commit pins. A
|
|
67
|
+
probe timeout stays `timeout` even before a session's deadline; unparseable
|
|
68
|
+
output is `unknown`. This holds with or without a session. Failures are not
|
|
69
|
+
memoized: a later call can probe again. Full caches remain full after a
|
|
70
|
+
successful modern-version probe. The private strict probe and the
|
|
71
|
+
version-or-`null` compatibility helper share one memo per executor. Each
|
|
72
|
+
waiter can leave on its own timeout/cancellation, evicting only the memo
|
|
73
|
+
entry it waited on. The launching caller's timeout and signal bound the
|
|
74
|
+
shared Git process; its rejection reaches all remaining waiters, including
|
|
75
|
+
those whose own deadlines have not expired. A later call can retry.
|
|
63
76
|
- Failures: `E_REMOTE_UNREADABLE { url, key, reason }`, `reason` ∈ `auth`, `not-found`, `network`,
|
|
64
77
|
`timeout`, `unknown`. Nothing half-succeeds.
|
|
65
|
-
- Reference-bearing diagnostics
|
|
66
|
-
|
|
67
|
-
|
|
78
|
+
- Reference-bearing diagnostics choose an explicit entry point:
|
|
79
|
+
`displayRepoRef(value, { pinned = false, rejectedValue = false } = {})` for
|
|
80
|
+
selected reference values, `displayDiagnosticText(value, source = null,
|
|
81
|
+
{ fragment = false, refusal = false, substitute = true, rejectedValue = false } = {})`
|
|
82
|
+
for kernel-authored prose, and `scrubGitLine(line, url = null)` for Git's
|
|
83
|
+
lines. One private renderer owns the [display rule](../workspaces.md#repository-references-in-diagnostics).
|
|
84
|
+
The entries extract only their named options and fix their own contexts;
|
|
85
|
+
reference or kernel-prose options cannot select Git-line handling.
|
|
86
|
+
`displayRepoRef` accepts `pinned: true` for a whole `<ref>@<commit>` source
|
|
87
|
+
or `pinned: { ref, commit }` for its original components; both strictly
|
|
88
|
+
validate reference and commit without a plain-value fallback. Display
|
|
89
|
+
changes no admission, transport, operational value or error shape. These
|
|
90
|
+
are internal/direct-module entry points, not package export-map entries;
|
|
91
|
+
there is no implicit `redactUrl` export or shim.
|
|
68
92
|
|
|
69
93
|
---
|
|
70
94
|
|