@awebai/oats 0.51.0 → 0.52.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/README.md +1 -0
- package/bin/oats.mjs +109 -37
- package/docs/capabilities.md +9 -2
- package/docs/configuration.md +134 -88
- package/docs/desktop-cli-api.md +927 -92
- package/docs/desktop-instance-start.md +56 -0
- package/docs/desktop.md +10 -7
- package/docs/execution-targets.md +144 -58
- package/docs/first-team.md +3 -1
- package/docs/harness-trust.md +50 -2
- package/docs/implementation.md +66 -9
- package/docs/integrations.md +9 -8
- package/docs/knowledge-reference/acceptance.md +1 -0
- package/docs/knowledge-reference/harvester.md +5 -3
- package/docs/knowledge-reference/model.md +5 -3
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -2
- package/docs/launch-prompt-completion.md +50 -48
- package/docs/oats-local.schema.json +4 -3
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +15 -5
- package/docs/release-notes/v0.44.0.md +1 -1
- package/docs/release-notes/v0.52.0.md +933 -0
- package/docs/schedules.md +91 -4
- package/docs/souls-and-instances.md +95 -25
- package/docs/tui.md +152 -0
- package/docs/workspaces.md +2 -2
- package/lib/claim.mjs +186 -46
- package/lib/core.mjs +730 -185
- package/lib/errors.mjs +170 -0
- package/lib/harness-trust-write.mjs +68 -27
- package/lib/harness-trust.mjs +34 -16
- package/lib/instance-inspect.mjs +40 -11
- package/lib/instance-lifecycle.mjs +169 -47
- package/lib/launch-preference.mjs +16 -0
- package/lib/launch-prompt-completion.mjs +7 -43
- package/lib/launch-prompt-evidence.mjs +14 -7
- package/lib/launch-prompt-fixtures/README.md +86 -152
- package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
- package/lib/launch-prompt-fixtures.mjs +122 -109
- package/lib/launch-prompt-transport.mjs +2 -56
- package/lib/launch-prompts.mjs +102 -100
- package/lib/schedule-host.mjs +154 -22
- package/lib/schedule.mjs +73 -24
- package/lib/system-tools.mjs +39 -0
- package/lib/tmux-server-scope.mjs +62 -0
- package/lib/triggers.mjs +4 -4
- package/lib/workspace.mjs +5 -11
- package/lib/worktree-hooks.mjs +98 -20
- package/lib/worktree.mjs +83 -24
- package/package-catalog.json +3 -3
- package/package.json +7 -2
- package/packages/client/capability-show-contract.mjs +230 -0
- package/packages/client/capability-warnings-contract.mjs +57 -0
- package/packages/client/cli-adapter.mjs +548 -0
- package/packages/client/cli-environment.mjs +53 -0
- package/packages/client/cli-locator.mjs +253 -0
- package/packages/client/cli-probe-contract.mjs +47 -0
- package/packages/client/client-terms.mjs +60 -0
- package/packages/client/deployment-contract.mjs +68 -0
- package/packages/client/deployment-data.mjs +483 -0
- package/packages/client/deployment-facts.mjs +34 -0
- package/packages/client/deployment-label.mjs +76 -0
- package/packages/client/deployment-observer.mjs +89 -0
- package/packages/client/deployment-panel.mjs +142 -0
- package/packages/client/deployment-read-cli.mjs +53 -0
- package/packages/client/display-text.mjs +44 -0
- package/packages/client/harness-names.mjs +30 -0
- package/packages/client/inspect-contract.mjs +62 -0
- package/packages/client/instance-acts.mjs +54 -0
- package/packages/client/instance-admission.mjs +45 -0
- package/packages/client/instance-events-contract.mjs +74 -0
- package/packages/client/instance-git-contract.mjs +80 -0
- package/packages/client/instance-presentation.mjs +22 -0
- package/packages/client/instance-tree.mjs +453 -0
- package/packages/client/kernel-environment.mjs +11 -0
- package/packages/client/launch-contract.mjs +51 -0
- package/packages/client/launch-prompt-outcome.mjs +165 -0
- package/packages/client/lifecycle-cli.mjs +61 -0
- package/packages/client/lifecycle-contract.mjs +372 -0
- package/packages/client/liveness-main.mjs +10 -0
- package/packages/client/liveness.mjs +35 -0
- package/packages/client/machine-contract.mjs +123 -0
- package/packages/client/own-environment.mjs +22 -0
- package/packages/client/panel-views.mjs +286 -0
- package/packages/client/readiness-contract.mjs +172 -0
- package/packages/client/refresh-loop.mjs +52 -0
- package/packages/client/remote-address.mjs +126 -0
- package/packages/client/remote-roster.mjs +67 -0
- package/packages/client/roster-sections.mjs +80 -0
- package/packages/client/spawn-apply-cli.mjs +104 -0
- package/packages/client/spawn-apply-contract.mjs +183 -0
- package/packages/client/spawn-decision.mjs +46 -0
- package/packages/client/spawn-messages.mjs +119 -0
- package/packages/client/spawn-preview-cli.mjs +32 -0
- package/packages/client/spawn-preview-contract.mjs +314 -0
- package/packages/client/team-members.mjs +41 -0
- package/packages/client/team-rows.mjs +45 -0
- package/packages/client/terminal-contract.mjs +57 -0
- package/packages/client/tmux-status.mjs +66 -0
- package/packages/client/waiting-on-you.mjs +88 -0
- package/packages/client/workspace-admission.mjs +45 -0
- package/packages/client/workspace-cli.mjs +142 -0
- package/packages/client/workspace-views.mjs +147 -0
- package/packages/tui/README.md +46 -0
- package/packages/tui/bin/tui.mjs +7 -0
- package/packages/tui/lib/actions.mjs +29 -0
- package/packages/tui/lib/client.mjs +4 -0
- package/packages/tui/lib/main.mjs +105 -0
- package/packages/tui/lib/term/keys.mjs +323 -0
- package/packages/tui/lib/term/screen.mjs +122 -0
- package/packages/tui/lib/term/style.mjs +43 -0
- package/packages/tui/lib/term/text.mjs +49 -0
- package/packages/tui/lib/term/tty.mjs +168 -0
- package/packages/tui/lib/term/width.mjs +124 -0
- package/packages/tui/lib/views/frame.mjs +62 -0
- package/packages/tui/lib/views/help.mjs +28 -0
- package/packages/tui/package.json +8 -0
- package/skills/oats-getting-started/SKILL.md +29 -22
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
- package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
- package/lib/launch-prompt-policy.mjs +0 -87
package/README.md
CHANGED
|
@@ -228,6 +228,7 @@ Further documentation:
|
|
|
228
228
|
- [Packages](docs/packages.md)
|
|
229
229
|
- [Sessions](docs/execution-targets.md)
|
|
230
230
|
- [OATS Desktop](docs/desktop.md)
|
|
231
|
+
- [OATS TUI](docs/tui.md), the terminal client (`oats tui`, a preview)
|
|
231
232
|
|
|
232
233
|
This README explains the framework and its direction. Advanced mechanisms such as automatic speciation and context cloning require their own implementation and verification; the model is not a claim that every feature or capability combination already works.
|
|
233
234
|
|
package/bin/oats.mjs
CHANGED
|
@@ -24,13 +24,14 @@ import { execFileSync, spawnSync } from "node:child_process";
|
|
|
24
24
|
import { constants as osConstants, homedir, tmpdir } from "node:os";
|
|
25
25
|
import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
|
|
26
26
|
import { fileURLToPath } from "node:url";
|
|
27
|
+
import { performance } from "node:perf_hooks";
|
|
27
28
|
import { runtimeNameWarning, noteRuntimeName } from "../lib/deprecation.mjs";
|
|
28
|
-
import { herdrSettingRemoved } from "../lib/errors.mjs";
|
|
29
|
+
import { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect } from "../lib/errors.mjs";
|
|
29
30
|
import {
|
|
30
31
|
LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
|
|
31
32
|
capabilityManifests, capabilityTrust, capabilityExecutablePath,
|
|
32
33
|
officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
|
|
33
|
-
findInstanceHome, findInstanceHomes, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt,
|
|
34
|
+
findInstanceHome, findInstanceHomes, 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,
|
|
34
35
|
FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
|
|
35
36
|
} from "../lib/core.mjs";
|
|
36
37
|
import {
|
|
@@ -49,11 +50,11 @@ import { spawnSync as spawnSyncProc } from "node:child_process";
|
|
|
49
50
|
import { tickTriggers } from "../lib/triggers.mjs";
|
|
50
51
|
import * as A from "../lib/automations.mjs";
|
|
51
52
|
import { parseEnvelopeText, unresolvedScheduleAttempts, scheduleScopeOf, listSchedules, describe as describeSchedule, testSchedule, addSchedule, updateSchedule, updateScheduleDescription, setEnabled as setScheduleEnabled, removeSchedule, runNow as runScheduleNow, reconcile as reconcileSchedule, tickHost, tickWorkspace, scopeAutomations, scheduleKind, registerWorkspace, unregisterWorkspace, readRegistry, schedulerStatus, saveWakeForHome, removeWakeForHome, wakeFromFlags, withHostLock, scheduleError, SCHEDULE_API } from "../lib/schedule.mjs";
|
|
52
|
-
import { hostUnitStatus, installHostUnit, uninstallHostUnit } from "../lib/schedule-host.mjs";
|
|
53
|
+
import { hostUnitFiles, hostUnitStatus, installHostUnit, uninstallHostUnit } from "../lib/schedule-host.mjs";
|
|
53
54
|
import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
|
|
54
55
|
|
|
55
56
|
import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
|
|
56
|
-
import { planStop, applyStop, planRetire, descendantsOf, resolveInstance as resolveInstanceForCli } from "../lib/instance-lifecycle.mjs";
|
|
57
|
+
import { planStop, applyStop, planRetire, descendantsOf, resolveInstance as resolveInstanceForCli, STOP_WARNINGS } from "../lib/instance-lifecycle.mjs";
|
|
57
58
|
import { extraWorktreeLines, formatBytes, workRecoveryLines } from "../lib/retire-output.mjs";
|
|
58
59
|
import { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } from "../lib/retained-after-retire.mjs";
|
|
59
60
|
const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
|
|
@@ -91,14 +92,14 @@ function expandInlineValues(argv) {
|
|
|
91
92
|
const { argv: args, problem: argvProblem, inline: inlineValues } = expandInlineValues(rawArgs);
|
|
92
93
|
let cmd = args[0];
|
|
93
94
|
const HELP_WORDS = new Set(["help", "--help", "-h"]);
|
|
94
|
-
const KERNEL_COMMANDS = new Set(["harness", "automations", "trigger", "capture", "capabilities", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "update", "version", "workspace", "worktree"]);
|
|
95
|
-
/** Commands whose argv another parser reads (packages/record and packages/
|
|
96
|
-
const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental"]);
|
|
95
|
+
const KERNEL_COMMANDS = new Set(["harness", "automations", "trigger", "capture", "capabilities", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "tui", "update", "version", "workspace", "worktree"]);
|
|
96
|
+
/** Commands whose argv another parser reads (packages/record, packages/experimental and packages/tui parse process.argv). */
|
|
97
|
+
const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental", "tui"]);
|
|
97
98
|
/** The kernel features this binary implements: `features` in `version --json` (the Desktop API v1
|
|
98
99
|
* probe) and in `status --json`, which a remote roster relays as the host's (feature
|
|
99
100
|
* server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
|
|
100
101
|
* time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
|
|
101
|
-
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"];
|
|
102
|
+
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"];
|
|
102
103
|
/** Commands `--server <id>` runs on a registered server. */
|
|
103
104
|
const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
|
|
104
105
|
const flag = (name) => {
|
|
@@ -177,6 +178,23 @@ const withLocalWarnings = (envelope) => {
|
|
|
177
178
|
return { ...envelope, warnings: theirs.map((w) => (w === same ? { ...mine, sources, message: mine.message.replace(/\(.*\)/, `(${sources.join("; ")})`) } : w)) };
|
|
178
179
|
};
|
|
179
180
|
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); };
|
|
181
|
+
/** The door of the lifecycle verbs (retire, instance stop, session, worktree; awebai/oats#892): the
|
|
182
|
+
* answer to an error `e` of one of them. Its code is the error's own only when that is a kernel
|
|
183
|
+
* code (lib/errors.mjs isKernelCode); any other error is answered as `fallback`. One that has a
|
|
184
|
+
* code (the system's, Node's) and a defect (isDefect: a TypeError and its kind) get
|
|
185
|
+
* `details.cause` beside the command's `details`, and a defect's stack goes to stderr, in both
|
|
186
|
+
* modes: the answer must not swallow it. A plain Error without a code is a refusal the kernel
|
|
187
|
+
* wrote without one, or a child process that failed: the fallback and its message, nothing more.
|
|
188
|
+
* A typed failure that is not a code (TYPED_CLI_FAILURES) keeps its name, as before. Text mode
|
|
189
|
+
* prints the same message, with the same exit status. */
|
|
190
|
+
const lifecycleFail = (e, fallback, details, exit) => {
|
|
191
|
+
const message = String(e?.message ?? e);
|
|
192
|
+
if (TYPED_CLI_FAILURES.has(e?.code)) return JSON_MODE ? jsonFail(e.code, message, details, exit) : die(message, exit);
|
|
193
|
+
reportDefect(e);
|
|
194
|
+
const cause = isAnswerCode(e?.code) ? undefined : errorCause(e);
|
|
195
|
+
const all = cause ? { ...details, cause } : details;
|
|
196
|
+
return JSON_MODE ? jsonFail(kernelCode(e, fallback), message, all, exit) : die(message, exit);
|
|
197
|
+
};
|
|
180
198
|
const jsonOk = (result) => { console.log(JSON.stringify({ schemaVersion: 1, ok: true, result, ...envelopeWarnings() })); };
|
|
181
199
|
// Text mode (or a JSON answer printed before the read): the warning goes to stderr, never stdout.
|
|
182
200
|
process.on("exit", () => { const w = runtimeNameWarning(); if (w && !warningDelivered) process.stderr.write(`oats: warning: ${w.message}\n`); });
|
|
@@ -945,8 +963,8 @@ function launchPreview(bail) {
|
|
|
945
963
|
// selection the planner refuses it (E_LAUNCH_LEGACY: re-spawn it from the deployment).
|
|
946
964
|
let d, frozen;
|
|
947
965
|
try { frozen = withSafeTaskPrompt(meta.command, meta.harness); d = describeLaunchCommand(frozen); } catch (e) { bail(e.code || "E_LAUNCH_COMMAND_UNSUPPORTED", e.message); }
|
|
948
|
-
const
|
|
949
|
-
jsonOk({ context, selected,
|
|
966
|
+
const notices = launchStartNotices(dirname(dirname(dirname(dirname(home)))), meta.harness, frozen);
|
|
967
|
+
jsonOk({ context, selected, ...(notices.length ? { warnings: notices } : {}), selection: { source: "frozen-command", launchConfig: null, harness: null, model: null, yolo: null }, harness: meta.harness, model: meta.model || null, modelSource: meta.model ? "recorded" : "native default", yolo: meta.yolo ?? null, launchConfig: null, launchConfigSource: null, launchConfigDefault: false, executable: { path: d.executable, declared: null, resolvedFrom: "recorded" }, argv: d.argv, environment: d.environment, command: redactLaunchCommand(frozen), prompt: { kind: "task-file", file: "TASK.md" }, hooks: null, preflight: [{ check: "recipe", ok: true, detail: "frozen command; a selection is refused (E_LAUNCH_LEGACY): re-spawn it" }], ok: true });
|
|
950
968
|
return;
|
|
951
969
|
}
|
|
952
970
|
const agentsRoot = agentsRootOfHome(home);
|
|
@@ -968,7 +986,7 @@ function launchPreview(bail) {
|
|
|
968
986
|
const command = renderLaunchRecipe(recipe, { home, instance, redact: true, trustHome: plan.trustHome });
|
|
969
987
|
const d = describeLaunchCommand(command);
|
|
970
988
|
const environment = d.environment.map((e) => e.reference && recipe.env[e.name]?.fromEnv ? { name: e.name, fromEnv: recipe.env[e.name].fromEnv } : e);
|
|
971
|
-
jsonOk({ context, selected,
|
|
989
|
+
jsonOk({ context, selected, ...(plan.warnings?.length ? { warnings: plan.warnings } : {}), selection: { source: plan.selectionSource, launchConfig: recipe.launchConfig, harness: sel.harness ?? null, model: sel.model ?? null, yolo: sel.yolo ?? null }, harness: plan.harness, model: recipe.model, modelSource: plan.modelSource, yolo: recipe.yolo ?? null, launchConfig: recipe.launchConfig, launchConfigSource: recipe.launchConfigSource, launchConfigDefault: recipe.launchConfigDefault === true, executable: { path: plan.executable.path, declared: plan.executable.declared ?? null, resolvedFrom: plan.executable.resolvedFrom }, argv: d.argv, environment, command, prompt: recipe.prompt, hooks: redactLaunchRecipe(recipe).hooks, preflight: plan.preflight, ok: plan.ok });
|
|
972
990
|
}
|
|
973
991
|
async function launchConfigCmd() {
|
|
974
992
|
const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
|
|
@@ -1163,8 +1181,8 @@ async function worktreeCmd() {
|
|
|
1163
1181
|
console.log(r.resumed ? `${r.path} is already made (branch ${r.branch} from ${r.base} @ ${String(r.baseOid).slice(0, 12)}); nothing was run` : `made ${r.path}: branch ${r.branch} from origin's ${r.base} @ ${String(r.baseOid).slice(0, 12)}${r.hooks.length ? `; worktree hooks: ${r.hooks.map((h) => `${h.capability} ${h.ok ? "ok" : "FAILED"}`).join(", ")}` : ""}`);
|
|
1164
1182
|
for (const w of r.warnings || []) console.error(`oats: warning: ${w}`);
|
|
1165
1183
|
} catch (e) {
|
|
1166
|
-
if (
|
|
1167
|
-
|
|
1184
|
+
if (TYPED_CLI_FAILURES.has(e?.code)) throw e;
|
|
1185
|
+
return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.details, e.exitStatus);
|
|
1168
1186
|
}
|
|
1169
1187
|
}
|
|
1170
1188
|
|
|
@@ -1244,7 +1262,7 @@ function instanceCmd() {
|
|
|
1244
1262
|
// its revision back and refuses if reality moved.
|
|
1245
1263
|
const homeOpt = flag("home");
|
|
1246
1264
|
if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
|
|
1247
|
-
let root; try { root = ensureRoot(dirFlag()); } catch (e) { return
|
|
1265
|
+
let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
|
|
1248
1266
|
const recursive = !args.includes("--no-recursive");
|
|
1249
1267
|
const wantPlan = args.includes("--plan"), wantApply = args.includes("--apply");
|
|
1250
1268
|
if (wantPlan === wantApply) return bail("E_BAD_ARGS", "stop needs exactly one of --plan or --apply");
|
|
@@ -1261,12 +1279,18 @@ function instanceCmd() {
|
|
|
1261
1279
|
const rev = flag("plan-revision"), key = flag("idempotency-key"), grace = flag("grace-ms");
|
|
1262
1280
|
if (rev === true || key === true || grace === true) return bail("E_BAD_ARGS", usage);
|
|
1263
1281
|
const receipt = applyStop(dirFlag(), root, name, { home: homeOpt, recursive, planRevision: rev, idempotencyKey: key, ...(grace !== undefined ? { graceMs: Number(grace) } : {}) });
|
|
1282
|
+
// Not part of the receipt, whose shape is contract: on stderr in both modes.
|
|
1283
|
+
for (const w of receipt[STOP_WARNINGS] || []) console.error(`oats: warning: ${w}`);
|
|
1264
1284
|
if (JSON_MODE) { jsonOk(receipt); return; }
|
|
1265
1285
|
for (const r of receipt.results) console.log(` ${r.instance}: ${r.ok ? (r.stopped ? "stopped" : `already ${r.state}`) : `${r.code} — ${r.message}`}`);
|
|
1266
1286
|
console.log(receipt.ok ? `stopped${receipt.replayed ? " (replayed receipt)" : ""}; home, work, transcript and launch configuration retained — restart with \`oats session restart\`` : "some targets are still running; nothing was escalated");
|
|
1267
1287
|
if (!receipt.ok) process.exit(1);
|
|
1268
1288
|
return;
|
|
1269
|
-
} catch (e) {
|
|
1289
|
+
} catch (e) {
|
|
1290
|
+
// The error's own details (a claim's holder; a defect's cause) beside the plan it was refused with.
|
|
1291
|
+
const details = { ...e.details, ...(e.plan ? { plan: e.plan } : {}), ...(e.candidates ? { candidates: e.candidates } : {}) };
|
|
1292
|
+
return lifecycleFail(e, "E_LIFECYCLE_FAILED", Object.keys(details).length ? details : undefined);
|
|
1293
|
+
}
|
|
1270
1294
|
}
|
|
1271
1295
|
let home = flag("home");
|
|
1272
1296
|
if (home === true) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
|
|
@@ -1435,13 +1459,19 @@ function harnessTrustCmd() {
|
|
|
1435
1459
|
const context = workspaceContext(cmdFail);
|
|
1436
1460
|
const show = (result, log = console.log) => {
|
|
1437
1461
|
log(`${result.mode}: native harness trust for ${result.root}`);
|
|
1438
|
-
|
|
1462
|
+
const used = (entry) => [...(entry.ambient ? ["ambient"] : []), ...entry.launchConfigs.map((n) => `launch configuration ${n}`)].join(", ");
|
|
1463
|
+
for (const entry of result.entries) {
|
|
1464
|
+
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)})`);
|
|
1465
|
+
if (entry.problem) log(`problem: ${entry.problem}`);
|
|
1466
|
+
if (entry.reason) log(`skipped: ${entry.reason}`);
|
|
1467
|
+
}
|
|
1439
1468
|
if (result.audit) log(`audit: ${result.audit.status} ${result.audit.path} ${result.audit.operationId}`);
|
|
1440
1469
|
for (const warning of result.warnings) log(`warning: ${warning}`);
|
|
1441
1470
|
if (result.reason) log(`reason: ${result.reason}; native configuration may have changed: ${result.mayHaveChanged}`);
|
|
1442
1471
|
};
|
|
1443
1472
|
try {
|
|
1444
|
-
|
|
1473
|
+
// Every configuration file a launch of this deployment reads: its launch configurations' too.
|
|
1474
|
+
const result = harnessTrust(context.deploymentDir, { harness: selected, plan: args.includes("--plan"), launchConfigs: launchConfigsAt(context.deploymentDir) });
|
|
1445
1475
|
if (JSON_MODE) jsonOk(result);
|
|
1446
1476
|
else show(result);
|
|
1447
1477
|
} catch (e) {
|
|
@@ -2797,6 +2827,8 @@ async function spawnCmd() {
|
|
|
2797
2827
|
jsonOk({
|
|
2798
2828
|
instance: r.instance, agent: r.agent, home: r.home, work: r.work,
|
|
2799
2829
|
branch: r.branch || null, base: r.base ?? null, launched: r.launched, warnings: r.warnings || [],
|
|
2830
|
+
// #917: what this spawn's start did with Claude's development-channel prompt, as a start answers it.
|
|
2831
|
+
...(r.launchPrompts ? { launchPrompts: r.launchPrompts } : {}),
|
|
2800
2832
|
...(wakeSchedule ? { wakeSchedule } : {}), ...(wakeScheduleError ? { wakeScheduleError } : {}),
|
|
2801
2833
|
tmux: r.tmux || null, backend: "tmux", repo: r.repo || null, harness: r.harness || null,
|
|
2802
2834
|
model: r.model || null, parent: r.parentInstance || null,
|
|
@@ -2834,6 +2866,8 @@ function failedSpawnBranchLine(r, items, { local = false, host } = {}) {
|
|
|
2834
2866
|
return r.retainedHome ? ` branch: the "branch" recorded in ${join(r.retainedHome, "instance.json")}${host ? ` on ${host}` : ""}` : null;
|
|
2835
2867
|
}
|
|
2836
2868
|
|
|
2869
|
+
/** Whether this process's retire (retireCmd) has returned from the kernel: set once, read by the dispatch. */
|
|
2870
|
+
let retireReturned = false;
|
|
2837
2871
|
function retireCmd() {
|
|
2838
2872
|
const name = args[1];
|
|
2839
2873
|
// Refused before anything else: before --plan, a replay, a plan revision or a recorded child is stopped.
|
|
@@ -2844,7 +2878,7 @@ function retireCmd() {
|
|
|
2844
2878
|
if (args.includes("--plan")) {
|
|
2845
2879
|
// K3: what retirement would touch, with the design's defaults — read-only.
|
|
2846
2880
|
dropAmbientRoot();
|
|
2847
|
-
let root; try { root = ensureRoot(dirFlag()); } catch (e) { return
|
|
2881
|
+
let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
|
|
2848
2882
|
try {
|
|
2849
2883
|
const plan = planRetire(dirFlag(), root, name, { home: homeFlag });
|
|
2850
2884
|
if (args.includes("--json")) { jsonOk(plan); return; }
|
|
@@ -2853,7 +2887,7 @@ function retireCmd() {
|
|
|
2853
2887
|
console.log(` defaults: retain worktree ${plan.defaults.retainWorktree}, delete branch ${plan.defaults.deleteBranch}, stop children ${plan.defaults.stopChildren}`);
|
|
2854
2888
|
for (const n of plan.notes) console.log(` note: ${n}`);
|
|
2855
2889
|
return;
|
|
2856
|
-
} catch (e) { return
|
|
2890
|
+
} catch (e) { return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { ...e.details, candidates: e.candidates } : e.details); }
|
|
2857
2891
|
}
|
|
2858
2892
|
// The calling instance knows its own home: self-retire never needs to
|
|
2859
2893
|
// disambiguate a same-named twin by hand.
|
|
@@ -2884,7 +2918,7 @@ function retireCmd() {
|
|
|
2884
2918
|
// Before the claim, only the home: where the receipt goes, and the answers of a name that
|
|
2885
2919
|
// resolves to no home, to several or to another one.
|
|
2886
2920
|
let target;
|
|
2887
|
-
try { target = resolveInstanceForCli(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return
|
|
2921
|
+
try { target = resolveInstanceForCli(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.details); }
|
|
2888
2922
|
replayPath = join(dirname(target.home), `.oats-retire-receipt.${idemKey}.json`);
|
|
2889
2923
|
// The plan the revision is checked against is read once, by retireInstance, when it holds the
|
|
2890
2924
|
// home's claim (RETIRE_UNDER_CLAIM): nobody else is retiring the home by then, so the plan is
|
|
@@ -2908,17 +2942,21 @@ function retireCmd() {
|
|
|
2908
2942
|
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 }); }
|
|
2909
2943
|
catch (e) {
|
|
2910
2944
|
// The plan could not be read, or its revision is not the one shown: the answers they always had.
|
|
2911
|
-
if (e === planFailure) return
|
|
2945
|
+
if (e === planFailure) return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.details);
|
|
2912
2946
|
if (e === stalePlan) return args.includes("--json") ? jsonFail(e.code, e.message, e.details) : die(`the retire plan changed since it was shown; re-run oats retire ${name} --plan`);
|
|
2913
|
-
if (!e?.code) throw e;
|
|
2914
2947
|
// A child still running (or whose stop could not be established) refused the retirement: the
|
|
2915
2948
|
// guarded apply returns the plan it acted on, and the text names each child's reason.
|
|
2916
|
-
if (e
|
|
2949
|
+
if (e?.code === "E_CHILDREN_RUNNING") {
|
|
2917
2950
|
const running = e.details.childrenStopped.filter((k) => !k.ok);
|
|
2918
2951
|
return args.includes("--json") ? jsonFail(e.code, e.message, { ...e.details, ...(planRev !== undefined ? { plan: fresh } : {}) }) : die(`children still running: ${running.map((k) => `${k.instance} (${k.code})`).join(", ")}; nothing retired`);
|
|
2919
2952
|
}
|
|
2920
|
-
|
|
2953
|
+
// Whatever else the retire answers: retireInstance gives every error a kernel code, and what the
|
|
2954
|
+
// retire had done by then (`details.reached`).
|
|
2955
|
+
return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { ...e.details, candidates: e.candidates } : e.details);
|
|
2921
2956
|
}
|
|
2957
|
+
// The retire has answered. Whatever throws from here on is not an answer of the retire and is
|
|
2958
|
+
// not given one (the dispatch): an error envelope without `reached` would say that nothing was done.
|
|
2959
|
+
retireReturned = true;
|
|
2922
2960
|
if (replayPath) { r.planRevision = planRev; r.idempotencyKey = idemKey; r.replayed = false; try { writeFileAtomic(replayPath, JSON.stringify(r, null, 2)); } catch { /* receipt is evidence, not authority */ } }
|
|
2923
2961
|
// A retired home's wake jobs are forgotten (definitions only; nothing is
|
|
2924
2962
|
// stopped by this); a deferred self-retire keeps them until the home is gone.
|
|
@@ -3033,14 +3071,26 @@ async function scheduleCmd() {
|
|
|
3033
3071
|
case "reconcile": return out(reconcileSchedule(ws(), needId(), { io, clear: args.includes("--clear"), ctx: ctx() }));
|
|
3034
3072
|
case "tick": {
|
|
3035
3073
|
const dryRun = args.includes("--dry-run");
|
|
3036
|
-
|
|
3074
|
+
// The minute the timer fired this tick for: this process's start, read before any work.
|
|
3075
|
+
const firedAt = new Date(Math.floor(performance.timeOrigin));
|
|
3076
|
+
if (args.includes("--host")) return out(tickHost({ firedAt, io, dryRun }));
|
|
3037
3077
|
const reg = readRegistry();
|
|
3038
3078
|
const tctx = scopeAutomations(ws(), { io, refresh: !dryRun });
|
|
3039
|
-
const considered = withHostLock(() => [...(tctx.refresh && !tctx.refresh.ok ? [{ workspace: ws(), action: "error", error: `automations refresh: ${tctx.refresh.error}` }] : []), ...tickWorkspace(ws(), { io, reg, wsList: reg.workspaces.includes(ws()) ? reg.workspaces : [...reg.workspaces, ws()], dryRun, ctx: tctx }), ...tickTriggers(ws(), { io, dryRun, ctx: tctx, reg, wsList: reg.workspaces.includes(ws()) ? reg.workspaces : [...reg.workspaces, ws()] })]);
|
|
3079
|
+
const considered = withHostLock(() => [...(tctx.refresh && !tctx.refresh.ok ? [{ workspace: ws(), action: "error", error: `automations refresh: ${tctx.refresh.error}` }] : []), ...tickWorkspace(ws(), { firedAt, io, reg, wsList: reg.workspaces.includes(ws()) ? reg.workspaces : [...reg.workspaces, ws()], dryRun, ctx: tctx }), ...tickTriggers(ws(), { io, dryRun, ctx: tctx, reg, wsList: reg.workspaces.includes(ws()) ? reg.workspaces : [...reg.workspaces, ws()] })]);
|
|
3040
3080
|
return out({ tickedAt: new Date().toISOString(), considered, scheduler: schedulerStatus(ws(), io) });
|
|
3041
3081
|
}
|
|
3042
3082
|
case "host": {
|
|
3043
3083
|
const op = args[2];
|
|
3084
|
+
const os = flag("os");
|
|
3085
|
+
if (os !== undefined && !(op === "install" && args.includes("--print"))) throw scheduleError("E_BAD_ARGS", "--os is for oats schedule host install --print");
|
|
3086
|
+
if (op === "install" && args.includes("--print")) {
|
|
3087
|
+
// What install would write, rendered from this environment; nothing is written or loaded.
|
|
3088
|
+
if (os !== undefined && os !== "darwin" && os !== "linux") throw scheduleError("E_BAD_ARGS", "--os darwin|linux");
|
|
3089
|
+
if (flag("max-concurrent") !== undefined || flag("triggers-max-concurrent") !== undefined) throw scheduleError("E_BAD_ARGS", "--print writes nothing: run install without --print to set a cap");
|
|
3090
|
+
const r = hostUnitFiles(os ? { os } : {});
|
|
3091
|
+
if (!JSON_MODE) for (const w of r.warnings) console.error(`warning: ${w}`);
|
|
3092
|
+
return out(r, (x) => Object.entries(x.files).map(([path, content]) => `==> ${path} <==\n${content}`).join("\n").replace(/\n$/, ""));
|
|
3093
|
+
}
|
|
3044
3094
|
if (op === "install") {
|
|
3045
3095
|
const cap = (name, reset) => {
|
|
3046
3096
|
const occurrences = args.filter((arg) => arg === `--${name}`);
|
|
@@ -3054,14 +3104,14 @@ async function scheduleCmd() {
|
|
|
3054
3104
|
};
|
|
3055
3105
|
const caps = { maxConcurrent: cap("max-concurrent", "default"), triggersMaxConcurrent: cap("triggers-max-concurrent", "none") };
|
|
3056
3106
|
registerWorkspace(ws(), caps);
|
|
3057
|
-
installHostUnit();
|
|
3058
|
-
return out({ scheduler: schedulerStatus(ws(), io) });
|
|
3107
|
+
const { warnings } = installHostUnit();
|
|
3108
|
+
return out({ scheduler: schedulerStatus(ws(), io), warnings });
|
|
3059
3109
|
}
|
|
3060
3110
|
if (op === "uninstall") { unregisterWorkspace(ws()); if (!readRegistry().workspaces.length) uninstallHostUnit(); return out({ scheduler: schedulerStatus(ws(), io) }); }
|
|
3061
3111
|
if (op === "status") return out({ scheduler: schedulerStatus(ws(), io) });
|
|
3062
|
-
throw scheduleError("E_BAD_ARGS", "oats schedule host install|uninstall|status");
|
|
3112
|
+
throw scheduleError("E_BAD_ARGS", "oats schedule host install [--print [--os darwin|linux]]|uninstall|status");
|
|
3063
3113
|
}
|
|
3064
|
-
default: throw scheduleError("E_BAD_ARGS", "usage: oats schedule list|show <id>|test <id>|add <id> --file <spec.json> [--description=<text>] [--workspace <member> --runs-on <host> --owner <host>/<login>]|update <id> (--file <spec.json> [--description=<text>] | --description=<text>)|enable <id>|disable <id>|run <id> [--force]|remove <id> [--force]|reconcile <id> [--clear]|tick [--dry-run] [--host]|host install [--max-concurrent <N|default>] [--triggers-max-concurrent <N|none>]|uninstall|status [--dir <workspace>|--server <id>] [--json]");
|
|
3114
|
+
default: throw scheduleError("E_BAD_ARGS", "usage: oats schedule list|show <id>|test <id>|add <id> --file <spec.json> [--description=<text>] [--workspace <member> --runs-on <host> --owner <host>/<login>]|update <id> (--file <spec.json> [--description=<text>] | --description=<text>)|enable <id>|disable <id>|run <id> [--force]|remove <id> [--force]|reconcile <id> [--clear]|tick [--dry-run] [--host]|host install [--max-concurrent <N|default>] [--triggers-max-concurrent <N|none>] | host install --print [--os darwin|linux]|uninstall|status [--dir <workspace>|--server <id>] [--json]");
|
|
3065
3115
|
}
|
|
3066
3116
|
} catch (e) {
|
|
3067
3117
|
// K8b: typed refusal details travel (identity mismatch: key/declared; a refused file: its integrity source).
|
|
@@ -3288,11 +3338,22 @@ async function sessionCmd() {
|
|
|
3288
3338
|
// A start's launch-hook warnings, as spawn prints its own (stderr keeps stdout one JSON document).
|
|
3289
3339
|
for (const w of result?.warnings || []) console.error(` WARNING: ${w}`);
|
|
3290
3340
|
}
|
|
3291
|
-
} catch (e) {
|
|
3341
|
+
} catch (e) { lifecycleFail(e, "E_SESSION_FAILED", e.details); }
|
|
3292
3342
|
}
|
|
3293
3343
|
|
|
3294
3344
|
async function paneCmd() {
|
|
3295
|
-
die("`oats pane` has been retired — the OATS Desktop app (packages/desktop) is the control panel now.");
|
|
3345
|
+
die("`oats pane` has been retired — the OATS Desktop app (packages/desktop) is the control panel now; in a terminal, `oats tui` (preview).");
|
|
3346
|
+
}
|
|
3347
|
+
|
|
3348
|
+
/** `oats tui` (preview, docs/tui.md): the terminal client, shipped inside this package as
|
|
3349
|
+
* packages/tui. It is interactive, so `--json` is refused here, before anything is loaded.
|
|
3350
|
+
* This is the ONLY import of packages/tui in the kernel and the CLI, and it is dynamic: a broken
|
|
3351
|
+
* TUI cannot break another word, and no other word pays for loading it (test/tui-boundary.test.mjs).
|
|
3352
|
+
* packages/tui parses process.argv itself, so the word is spliced out first, as for the record. */
|
|
3353
|
+
async function tuiCmd() {
|
|
3354
|
+
if (args.includes("--json")) return cmdFail("E_BAD_ARGS", "oats tui is interactive and has no --json form; `oats status --json` is the machine view");
|
|
3355
|
+
process.argv.splice(2, 1);
|
|
3356
|
+
await import(new URL("../packages/tui/bin/tui.mjs", import.meta.url));
|
|
3296
3357
|
}
|
|
3297
3358
|
|
|
3298
3359
|
/** `oats onboard [<dir>] --workspace <repo ref> [--json]` — workspace model v2 (decision 9).
|
|
@@ -4239,7 +4300,7 @@ async function serverRouteCmd() {
|
|
|
4239
4300
|
// keeping it at column 0 makes the whole command table one reviewable diff of
|
|
4240
4301
|
// added lines rather than ~150 lines of pure whitespace churn, and keeps `git
|
|
4241
4302
|
// blame` pointing at the commit that last changed each command.
|
|
4242
|
-
const TYPED_CLI_FAILURES =
|
|
4303
|
+
const TYPED_CLI_FAILURES = OWN_NAME_FAILURES; // one list: lib/errors.mjs
|
|
4243
4304
|
/** Removed 0.24 verbs → their v2 replacement (workspace model v2, decision 5). Checked before capability dispatch. */
|
|
4244
4305
|
const REMOVED_VERBS = { prepare: "`oats onboard` / `oats sync` to set up a workspace, and `oats spawn <soul> --preview` to see what a spawn would resolve (the captured/portable path was removed in 0.26)", create: "author souls/<name>/soul.yaml + AGENTS.md in a member repository, then `oats sync`", type: "the soul's own soul.yaml in its member repository (agent types were a classic config block)", install: "oats sync", restore: "oats sync", init: "oats-local.yaml + oats sync", use: "soul.yaml capabilities: { <cap>: { from } } + workspace defaults", trust: "declaring the package in packages: (package approval was removed; oats sync locks commit + integrity)", list: "oats workspace status | oats capabilities", catalog: "oats package add <id> <version> (bare versions resolve through package-catalog.json)", remove: "oats package remove <id>", migrate: "a rebuild (no migration: docs/design/2026-09-23-workspace-module-contracts.md)", config: "oats-local.yaml (host settings) and oats-workspace.yaml (shared)", inject: "injection overrides are not part of the workspace model yet; edit the capability inject in its member repo" };
|
|
4245
4306
|
try {
|
|
@@ -4318,6 +4379,7 @@ else if (cmd === "teams") await teamsCmd();
|
|
|
4318
4379
|
else if (cmd === "soul") await soulCmd();
|
|
4319
4380
|
else if (cmd === "status") await status();
|
|
4320
4381
|
else if (cmd === "pane") await paneCmd();
|
|
4382
|
+
else if (cmd === "tui") await tuiCmd();
|
|
4321
4383
|
else if (cmd === "version" || cmd === "--version" || cmd === "-v") versionCmd();
|
|
4322
4384
|
// Same rule as the inner catch: a typed CLI failure surfaces with its own code
|
|
4323
4385
|
// through the shared boundary, never re-badged as a spawn-mechanism failure.
|
|
@@ -4326,7 +4388,11 @@ else if (cmd === "schedule") await scheduleCmd();
|
|
|
4326
4388
|
else if (cmd === "trigger") await triggerCmd();
|
|
4327
4389
|
else if (cmd === "automations") await automationsCmd();
|
|
4328
4390
|
else if (cmd === "spawn") { try { await spawnCmd(); } catch (e) { if (TYPED_CLI_FAILURES.has(e?.code)) throw e; if (JSON_MODE) jsonFail("E_SPAWN_FAILED", e.message || e, e.details?.unconfirmed === true ? e.details : undefined); throw e; } }
|
|
4329
|
-
|
|
4391
|
+
// What a retire throws outside its own answers (the root, a replay's read) goes through the same door.
|
|
4392
|
+
// An exception after the retire has returned (retireReturned) is rethrown, here and by the handler
|
|
4393
|
+
// of typed failures below: a crash is read as "not confirmed", which is the truth, where an error
|
|
4394
|
+
// answer without `reached` would read as "nothing was done".
|
|
4395
|
+
else if (cmd === "retire") { try { retireCmd(); } catch (e) { if (retireReturned || TYPED_CLI_FAILURES.has(e?.code)) throw e; lifecycleFail(e, "E_LIFECYCLE_FAILED", e.details); } }
|
|
4330
4396
|
else if (cmd === "capture" || cmd === "recall" || cmd === "setup") await recordCmd(cmd);
|
|
4331
4397
|
else if (cmd === "experimental") await experimentalCmd();
|
|
4332
4398
|
// `!HELP_WORDS.has(cmd)`: usage NEVER depends on deployment state. `help` is a
|
|
@@ -4380,6 +4446,9 @@ Usage:
|
|
|
4380
4446
|
Desktop CLI API v1 probe payload
|
|
4381
4447
|
oats status [--json] agents, souls, running instances
|
|
4382
4448
|
[--max-age <s>] reuse head observations up to <s> s old (below)
|
|
4449
|
+
oats tui [--ascii] PREVIEW: the full-screen terminal client (docs/tui.md);
|
|
4450
|
+
? help, q quit. Needs a terminal on stdin and stdout
|
|
4451
|
+
and has no --json form; --ascii = ASCII rules and marks
|
|
4383
4452
|
oats server add <id> --ssh <alias> register another machine's OATS (OpenSSH alias,
|
|
4384
4453
|
--workspace </abs/path> [--oats <p>] remote workspace, remote oats path; no keys stored;
|
|
4385
4454
|
[--path <dir:dir>] --path = dirs prepended to the remote PATH, e.g. ~/.local/bin)
|
|
@@ -4526,8 +4595,10 @@ Usage:
|
|
|
4526
4595
|
own command run in the home or scope, envelope
|
|
4527
4596
|
relayed; a view answers {documents: [...]}
|
|
4528
4597
|
oats harness trust [--dir <deployment>] explicitly trust one canonical deployment root
|
|
4529
|
-
[--harness claude|codex|all] in native
|
|
4530
|
-
[--plan] [--json]
|
|
4598
|
+
[--harness claude|codex|all] in every native configuration file a launch reads
|
|
4599
|
+
[--plan] [--json] (the ambient one and each launch configuration's
|
|
4600
|
+
CLAUDE_CONFIG_DIR / CODEX_HOME); --plan reads only,
|
|
4601
|
+
bare command applies with a durable audit
|
|
4531
4602
|
oats launch-config list [--dir <scope> named launch configurations effective at a scope,
|
|
4532
4603
|
| --home <abs> | --soul <name>] a home's recorded context or a soul's own scope:
|
|
4533
4604
|
[--agents-root <abs>] [--json] harness, executable, args, env (values redacted,
|
|
@@ -4671,7 +4742,8 @@ Observation reuse (feature observe-max-age):
|
|
|
4671
4742
|
Layers: ${LAYERS.join(", ")}. Workspace model v2: docs/design/2026-09-23-workspace-module-contracts.md.`;
|
|
4672
4743
|
}
|
|
4673
4744
|
} catch (e) {
|
|
4674
|
-
|
|
4745
|
+
// After a retire has returned, nothing is answered as an error, a typed failure included (the dispatch).
|
|
4746
|
+
if (retireReturned || !TYPED_CLI_FAILURES.has(e?.code)) throw e;
|
|
4675
4747
|
// Same two renderings as every other typed failure: one envelope on stdout in
|
|
4676
4748
|
// --json mode, one `oats: <message>` line on stderr otherwise. The message
|
|
4677
4749
|
// already names the offending file — the readers re-raise it with one.
|
package/docs/capabilities.md
CHANGED
|
@@ -207,7 +207,10 @@ A self-contained package has an `oats.json`:
|
|
|
207
207
|
every host. Only then is its start time read: from `/proc`, or with `ps`
|
|
208
208
|
where there is no `/proc`, as on macOS: the system `ps`, from
|
|
209
209
|
`/usr/bin:/bin` whatever the caller's `PATH` holds, in a fixed `LC_ALL=C`,
|
|
210
|
-
`TZ=UTC` environment. A
|
|
210
|
+
`TZ=UTC` environment. A spawning process that has exited or was killed and
|
|
211
|
+
that its parent has not reaped (a zombie) is gone, although it still has
|
|
212
|
+
its pid and its start: the row shows the quarantine and `oats retire`
|
|
213
|
+
completes it. A start that cannot be read is never taken to mean the process is
|
|
211
214
|
gone, nor shown as alive: `oats status` shows the quarantine
|
|
212
215
|
(`rollbackIncomplete`, whose `inProgress` names the pid), and `oats retire`
|
|
213
216
|
refuses with `E_LIFECYCLE_BUSY`, naming the recorded pid and start for a
|
|
@@ -244,7 +247,11 @@ A self-contained package has an `oats.json`:
|
|
|
244
247
|
and nothing is silently dropped. Without `--force` that state fails closed with
|
|
245
248
|
`E_UNIDENTIFIED_INSTANCE_HOME` rather than deleting whatever credentials the
|
|
246
249
|
directory still holds; `--force` removes it and leaves any external state for
|
|
247
|
-
the operator to clean up by hand.
|
|
250
|
+
the operator to clean up by hand. One home is the exception for now: a home
|
|
251
|
+
whose `instance.json` is there and cannot be read is refused by every
|
|
252
|
+
retire, `--force` included, until the file is restored from a copy
|
|
253
|
+
([souls-and-instances.md](souls-and-instances.md#retire); awebai/oats#896).
|
|
254
|
+
Home entries declared in
|
|
248
255
|
`retirement.disposable.home` (below) go with the home: recovery holds no
|
|
249
256
|
copy of them.
|
|
250
257
|
- `retirement.disposable` declares what retirement treats as the provider's
|