@awebai/oats 0.50.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 +153 -51
- package/docs/capabilities.md +11 -3
- package/docs/configuration.md +134 -88
- package/docs/desktop-cli-api.md +994 -71
- package/docs/desktop-instance-start.md +56 -0
- package/docs/desktop.md +10 -7
- package/docs/execution-targets.md +230 -59
- package/docs/first-team.md +3 -1
- package/docs/harness-trust.md +50 -2
- package/docs/implementation.md +73 -8
- 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 +43 -7
- 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.51.0.md +156 -0
- package/docs/release-notes/v0.52.0.md +933 -0
- package/docs/schedules.md +91 -4
- package/docs/servers.md +21 -2
- package/docs/souls-and-instances.md +113 -21
- package/docs/tui.md +152 -0
- package/docs/workspaces.md +2 -2
- package/lib/claim.mjs +266 -0
- package/lib/core.mjs +845 -166
- 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/servers.mjs +20 -4
- package/lib/session-viewer.mjs +87 -10
- 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 +116 -23
- package/lib/worktree.mjs +89 -102
- 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"];
|
|
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.
|
|
@@ -2874,36 +2908,55 @@ function retireCmd() {
|
|
|
2874
2908
|
// resolved the home). A guarded apply acts on the children of the plan it
|
|
2875
2909
|
// revalidated; a plain or --self retire computes them as the plan does, and
|
|
2876
2910
|
// passes none when there are none.
|
|
2877
|
-
let replayPath = null,
|
|
2911
|
+
let replayPath = null, fresh, revalidate, stalePlan, planFailure;
|
|
2878
2912
|
if (planRev !== undefined) {
|
|
2879
2913
|
if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(idemKey)) die("--idempotency-key: 1-128 chars of [A-Za-z0-9._:-]");
|
|
2880
2914
|
// Replay first: after a successful retire the home is gone, so the receipt
|
|
2881
2915
|
// (beside the instances dir, keyed by the idempotency key) is the answer.
|
|
2882
2916
|
const replay = (dir) => { const p = join(dir, `.oats-retire-receipt.${idemKey}.json`); if (!existsSync(p)) return false; try { const prior = JSON.parse(readFileSync(p, "utf8")); if (prior.retired !== name) return false; if (args.includes("--json")) jsonOk({ ...prior, replayed: true }); else console.log(`retire ${name}: replayed receipt for key ${idemKey}`); return true; } catch { return false; } };
|
|
2883
2917
|
for (const a of listAgents(root)) if (replay(join(a._dir, "instances"))) return;
|
|
2884
|
-
|
|
2885
|
-
|
|
2886
|
-
|
|
2887
|
-
|
|
2888
|
-
|
|
2889
|
-
|
|
2890
|
-
|
|
2918
|
+
// Before the claim, only the home: where the receipt goes, and the answers of a name that
|
|
2919
|
+
// resolves to no home, to several or to another one.
|
|
2920
|
+
let target;
|
|
2921
|
+
try { target = resolveInstanceForCli(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.details); }
|
|
2922
|
+
replayPath = join(dirname(target.home), `.oats-retire-receipt.${idemKey}.json`);
|
|
2923
|
+
// The plan the revision is checked against is read once, by retireInstance, when it holds the
|
|
2924
|
+
// home's claim (RETIRE_UNDER_CLAIM): nobody else is retiring the home by then, so the plan is
|
|
2925
|
+
// the state the retire starts from. Against another retire of this home the answer is that one
|
|
2926
|
+
// is running (E_LIFECYCLE_BUSY), and no plan is read. A revision that no longer matches is
|
|
2927
|
+
// refused there, and nothing was done. What the retire takes from the plan: its children, and
|
|
2928
|
+
// its extra trees as it names them (the retire refuses as stale rather than move or remove one
|
|
2929
|
+
// that no longer reads that way when it gets to them).
|
|
2930
|
+
revalidate = () => {
|
|
2931
|
+
try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { planFailure = e; throw e; }
|
|
2932
|
+
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 } }));
|
|
2933
|
+
return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children };
|
|
2934
|
+
};
|
|
2891
2935
|
} else {
|
|
2892
|
-
|
|
2893
|
-
|
|
2936
|
+
// A plain or --self retire reads its recorded children the same way: under the claim, as they
|
|
2937
|
+
// are when the retire starts (an earlier retire that kept the home has repaired lineage by
|
|
2938
|
+
// then), and none when there are none.
|
|
2939
|
+
revalidate = () => { const recorded = descendantsOf(root, name); return recorded.length ? { children: recorded } : {}; };
|
|
2894
2940
|
}
|
|
2895
2941
|
let r;
|
|
2896
|
-
try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"),
|
|
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 }); }
|
|
2897
2943
|
catch (e) {
|
|
2898
|
-
|
|
2944
|
+
// The plan could not be read, or its revision is not the one shown: the answers they always had.
|
|
2945
|
+
if (e === planFailure) return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.details);
|
|
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`);
|
|
2899
2947
|
// A child still running (or whose stop could not be established) refused the retirement: the
|
|
2900
2948
|
// guarded apply returns the plan it acted on, and the text names each child's reason.
|
|
2901
|
-
if (e
|
|
2949
|
+
if (e?.code === "E_CHILDREN_RUNNING") {
|
|
2902
2950
|
const running = e.details.childrenStopped.filter((k) => !k.ok);
|
|
2903
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`);
|
|
2904
2952
|
}
|
|
2905
|
-
|
|
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);
|
|
2906
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;
|
|
2907
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 */ } }
|
|
2908
2961
|
// A retired home's wake jobs are forgotten (definitions only; nothing is
|
|
2909
2962
|
// stopped by this); a deferred self-retire keeps them until the home is gone.
|
|
@@ -3018,14 +3071,26 @@ async function scheduleCmd() {
|
|
|
3018
3071
|
case "reconcile": return out(reconcileSchedule(ws(), needId(), { io, clear: args.includes("--clear"), ctx: ctx() }));
|
|
3019
3072
|
case "tick": {
|
|
3020
3073
|
const dryRun = args.includes("--dry-run");
|
|
3021
|
-
|
|
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 }));
|
|
3022
3077
|
const reg = readRegistry();
|
|
3023
3078
|
const tctx = scopeAutomations(ws(), { io, refresh: !dryRun });
|
|
3024
|
-
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()] })]);
|
|
3025
3080
|
return out({ tickedAt: new Date().toISOString(), considered, scheduler: schedulerStatus(ws(), io) });
|
|
3026
3081
|
}
|
|
3027
3082
|
case "host": {
|
|
3028
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
|
+
}
|
|
3029
3094
|
if (op === "install") {
|
|
3030
3095
|
const cap = (name, reset) => {
|
|
3031
3096
|
const occurrences = args.filter((arg) => arg === `--${name}`);
|
|
@@ -3039,14 +3104,14 @@ async function scheduleCmd() {
|
|
|
3039
3104
|
};
|
|
3040
3105
|
const caps = { maxConcurrent: cap("max-concurrent", "default"), triggersMaxConcurrent: cap("triggers-max-concurrent", "none") };
|
|
3041
3106
|
registerWorkspace(ws(), caps);
|
|
3042
|
-
installHostUnit();
|
|
3043
|
-
return out({ scheduler: schedulerStatus(ws(), io) });
|
|
3107
|
+
const { warnings } = installHostUnit();
|
|
3108
|
+
return out({ scheduler: schedulerStatus(ws(), io), warnings });
|
|
3044
3109
|
}
|
|
3045
3110
|
if (op === "uninstall") { unregisterWorkspace(ws()); if (!readRegistry().workspaces.length) uninstallHostUnit(); return out({ scheduler: schedulerStatus(ws(), io) }); }
|
|
3046
3111
|
if (op === "status") return out({ scheduler: schedulerStatus(ws(), io) });
|
|
3047
|
-
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");
|
|
3048
3113
|
}
|
|
3049
|
-
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]");
|
|
3050
3115
|
}
|
|
3051
3116
|
} catch (e) {
|
|
3052
3117
|
// K8b: typed refusal details travel (identity mismatch: key/declared; a refused file: its integrity source).
|
|
@@ -3224,7 +3289,9 @@ async function sessionCmd() {
|
|
|
3224
3289
|
let result;
|
|
3225
3290
|
if (args[1] === "attach") {
|
|
3226
3291
|
if (JSON_MODE) throw Object.assign(new Error("session attach is interactive; omit --json"), { code: "E_BAD_ARGS" });
|
|
3227
|
-
|
|
3292
|
+
// --detach-key (feature session-attach-detach-key): the one key that leaves this viewer, with
|
|
3293
|
+
// status 20. Without it every key reaches the agent and there is no keyboard exit.
|
|
3294
|
+
process.exitCode = await attachInstanceSession(home, { detachKey: valueFlag("detach-key") });
|
|
3228
3295
|
return;
|
|
3229
3296
|
}
|
|
3230
3297
|
if (args[1] === "inspect") result = inspectInstanceSession(home);
|
|
@@ -3264,18 +3331,29 @@ async function sessionCmd() {
|
|
|
3264
3331
|
const file = flag("file");
|
|
3265
3332
|
if (!file || file === true) throw Object.assign(new Error("session upload needs --file <local path>"), { code: "E_BAD_ARGS" });
|
|
3266
3333
|
result = uploadAttachment({ file, home: home === true ? undefined : home });
|
|
3267
|
-
} else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|restart|receive|upload --home /absolute/home [--text-file path] [--model id] [--launch-config name|none | --reselect-launch] [--harness pi|claude|codex] [--yolo|--no-yolo] [--stop-grace seconds] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
|
|
3334
|
+
} else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|restart|receive|upload --home /absolute/home [--text-file path] [--detach-key key] [--model id] [--launch-config name|none | --reselect-launch] [--harness pi|claude|codex] [--yolo|--no-yolo] [--stop-grace seconds] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
|
|
3268
3335
|
if (JSON_MODE) jsonOk(result);
|
|
3269
3336
|
else {
|
|
3270
3337
|
console.log(JSON.stringify(result, null, 2));
|
|
3271
3338
|
// A start's launch-hook warnings, as spawn prints its own (stderr keeps stdout one JSON document).
|
|
3272
3339
|
for (const w of result?.warnings || []) console.error(` WARNING: ${w}`);
|
|
3273
3340
|
}
|
|
3274
|
-
} catch (e) {
|
|
3341
|
+
} catch (e) { lifecycleFail(e, "E_SESSION_FAILED", e.details); }
|
|
3275
3342
|
}
|
|
3276
3343
|
|
|
3277
3344
|
async function paneCmd() {
|
|
3278
|
-
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));
|
|
3279
3357
|
}
|
|
3280
3358
|
|
|
3281
3359
|
/** `oats onboard [<dir>] --workspace <repo ref> [--json]` — workspace model v2 (decision 9).
|
|
@@ -4091,8 +4169,14 @@ async function serverRouteCmd() {
|
|
|
4091
4169
|
return;
|
|
4092
4170
|
}
|
|
4093
4171
|
if (args[1] !== "attach") bail("E_USAGE", "--server routes `session inspect`, `session start`, `session restart`, `session upload` and `session attach`; input runs on the execution host (the wake broker calls it there)");
|
|
4172
|
+
// --detach-key travels only to a host that advertises session-attach-detach-key (attachArgv
|
|
4173
|
+
// probes for it, under --print too). The key may be C-\, the tty's QUIT character: pressed
|
|
4174
|
+
// once ssh has given the tty back, it reaches this process as SIGQUIT, whose default action
|
|
4175
|
+
// would replace the relayed status with 131. Held from here until this process exits.
|
|
4176
|
+
const detachKey = valueFlag("detach-key");
|
|
4177
|
+
if (detachKey !== undefined) process.on("SIGQUIT", () => {});
|
|
4094
4178
|
let route;
|
|
4095
|
-
try { route = attachArgv(id, addr, { skipVersionCheck: args.includes("--print") }); }
|
|
4179
|
+
try { route = attachArgv(id, { ...addr, detachKey }, { skipVersionCheck: args.includes("--print") }); }
|
|
4096
4180
|
// ssh failing before the viewer (the version probe, a name resolved through the host's roster)
|
|
4097
4181
|
// is the failure ssh has under it: exit 255, on which a caller reconnects. Every other refusal,
|
|
4098
4182
|
// and an ssh that never started (no link can come back), exits 1.
|
|
@@ -4102,7 +4186,7 @@ async function serverRouteCmd() {
|
|
|
4102
4186
|
// ssh exits 255 for its own failures: a link that died under the viewer
|
|
4103
4187
|
// (keepalives unanswered, the master or the host's sshd gone), or one
|
|
4104
4188
|
// never made. Say what is known rather than ending silently.
|
|
4105
|
-
if (r.status === 255) console.error(`\noats: ssh to ${route.target.sshHost} ended with an error (exit 255); if the link was lost, the instance keeps running on ${id}. Reattach with: oats session attach --server ${id} --home ${shellQuote(route.home)}`);
|
|
4189
|
+
if (r.status === 255) console.error(`\noats: ssh to ${route.target.sshHost} ended with an error (exit 255); if the link was lost, the instance keeps running on ${id}. Reattach with: oats session attach --server ${id} --home ${shellQuote(route.home)}${detachKey !== undefined ? ` --detach-key ${shellQuote(detachKey)}` : ""}`);
|
|
4106
4190
|
process.exit(r.status ?? 1);
|
|
4107
4191
|
}
|
|
4108
4192
|
// A spawn's argv is checked here, before the server is contacted.
|
|
@@ -4216,7 +4300,7 @@ async function serverRouteCmd() {
|
|
|
4216
4300
|
// keeping it at column 0 makes the whole command table one reviewable diff of
|
|
4217
4301
|
// added lines rather than ~150 lines of pure whitespace churn, and keeps `git
|
|
4218
4302
|
// blame` pointing at the commit that last changed each command.
|
|
4219
|
-
const TYPED_CLI_FAILURES =
|
|
4303
|
+
const TYPED_CLI_FAILURES = OWN_NAME_FAILURES; // one list: lib/errors.mjs
|
|
4220
4304
|
/** Removed 0.24 verbs → their v2 replacement (workspace model v2, decision 5). Checked before capability dispatch. */
|
|
4221
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" };
|
|
4222
4306
|
try {
|
|
@@ -4295,6 +4379,7 @@ else if (cmd === "teams") await teamsCmd();
|
|
|
4295
4379
|
else if (cmd === "soul") await soulCmd();
|
|
4296
4380
|
else if (cmd === "status") await status();
|
|
4297
4381
|
else if (cmd === "pane") await paneCmd();
|
|
4382
|
+
else if (cmd === "tui") await tuiCmd();
|
|
4298
4383
|
else if (cmd === "version" || cmd === "--version" || cmd === "-v") versionCmd();
|
|
4299
4384
|
// Same rule as the inner catch: a typed CLI failure surfaces with its own code
|
|
4300
4385
|
// through the shared boundary, never re-badged as a spawn-mechanism failure.
|
|
@@ -4303,7 +4388,11 @@ else if (cmd === "schedule") await scheduleCmd();
|
|
|
4303
4388
|
else if (cmd === "trigger") await triggerCmd();
|
|
4304
4389
|
else if (cmd === "automations") await automationsCmd();
|
|
4305
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; } }
|
|
4306
|
-
|
|
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); } }
|
|
4307
4396
|
else if (cmd === "capture" || cmd === "recall" || cmd === "setup") await recordCmd(cmd);
|
|
4308
4397
|
else if (cmd === "experimental") await experimentalCmd();
|
|
4309
4398
|
// `!HELP_WORDS.has(cmd)`: usage NEVER depends on deployment state. `help` is a
|
|
@@ -4357,6 +4446,9 @@ Usage:
|
|
|
4357
4446
|
Desktop CLI API v1 probe payload
|
|
4358
4447
|
oats status [--json] agents, souls, running instances
|
|
4359
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
|
|
4360
4452
|
oats server add <id> --ssh <alias> register another machine's OATS (OpenSSH alias,
|
|
4361
4453
|
--workspace </abs/path> [--oats <p>] remote workspace, remote oats path; no keys stored;
|
|
4362
4454
|
[--path <dir:dir>] --path = dirs prepended to the remote PATH, e.g. ~/.local/bin)
|
|
@@ -4386,7 +4478,9 @@ Usage:
|
|
|
4386
4478
|
--instance <name> [--json] saved home on its host
|
|
4387
4479
|
oats session inspect|attach --server <id> inspect (envelope) or attach a viewer (ssh PTY) for a
|
|
4388
4480
|
--instance <name> | --home <abs> remote instance, by its saved route or the server's
|
|
4389
|
-
|
|
4481
|
+
[--detach-key <key>] roster (--print shows attach); oats 0.22.2 or later.
|
|
4482
|
+
attach --detach-key: as below; the server must
|
|
4483
|
+
advertise session-attach-detach-key
|
|
4390
4484
|
oats session start --server <id> start a stopped remote instance in its existing home
|
|
4391
4485
|
--instance <name> | --home <abs> by its saved route or the server's roster; it must advertise
|
|
4392
4486
|
[--model <m>] [--json] session-start (oats 0.22.9 or later)
|
|
@@ -4409,6 +4503,11 @@ Usage:
|
|
|
4409
4503
|
[--check] --check: write nothing; report <dir> (~ = this home),
|
|
4410
4504
|
its state and whether Git reads the workspace remote
|
|
4411
4505
|
oats session inspect|input|attach --home <absolute-home> [--text-file <path>] [--json]
|
|
4506
|
+
oats session attach --home <absolute-home> [--detach-key <key>]
|
|
4507
|
+
a viewer of one instance. <key> (C-<letter>, M-<letter
|
|
4508
|
+
or digit>, F1 to F12; 'C-\\' is the suggested one)
|
|
4509
|
+
leaves it with exit status 20; without one no key
|
|
4510
|
+
leaves it: every key goes to the agent
|
|
4412
4511
|
oats schedule list|show <id>|test <id>|add <id> --file <spec.json>|update <id> --file <spec.json>
|
|
4413
4512
|
enable|disable|run|remove|reconcile <id> workspace-scoped, host-owned schedules (spawn,
|
|
4414
4513
|
tick [--dry-run] [--host] command or wake jobs on a five-field cron with an
|
|
@@ -4496,8 +4595,10 @@ Usage:
|
|
|
4496
4595
|
own command run in the home or scope, envelope
|
|
4497
4596
|
relayed; a view answers {documents: [...]}
|
|
4498
4597
|
oats harness trust [--dir <deployment>] explicitly trust one canonical deployment root
|
|
4499
|
-
[--harness claude|codex|all] in native
|
|
4500
|
-
[--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
|
|
4501
4602
|
oats launch-config list [--dir <scope> named launch configurations effective at a scope,
|
|
4502
4603
|
| --home <abs> | --soul <name>] a home's recorded context or a soul's own scope:
|
|
4503
4604
|
[--agents-root <abs>] [--json] harness, executable, args, env (values redacted,
|
|
@@ -4641,7 +4742,8 @@ Observation reuse (feature observe-max-age):
|
|
|
4641
4742
|
Layers: ${LAYERS.join(", ")}. Workspace model v2: docs/design/2026-09-23-workspace-module-contracts.md.`;
|
|
4642
4743
|
}
|
|
4643
4744
|
} catch (e) {
|
|
4644
|
-
|
|
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;
|
|
4645
4747
|
// Same two renderings as every other typed failure: one envelope on stdout in
|
|
4646
4748
|
// --json mode, one `oats: <message>` line on stderr otherwise. The message
|
|
4647
4749
|
// already names the offending file — the readers re-raise it with one.
|
package/docs/capabilities.md
CHANGED
|
@@ -205,8 +205,12 @@ A self-contained package has an `oats.json`:
|
|
|
205
205
|
Whether the process exists is the operating system's answer (`kill -0`:
|
|
206
206
|
"no such process" is gone, another user's process exists), the same on
|
|
207
207
|
every host. Only then is its start time read: from `/proc`, or with `ps`
|
|
208
|
-
|
|
209
|
-
|
|
208
|
+
where there is no `/proc`, as on macOS: the system `ps`, from
|
|
209
|
+
`/usr/bin:/bin` whatever the caller's `PATH` holds, in a fixed `LC_ALL=C`,
|
|
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
|
|
210
214
|
gone, nor shown as alive: `oats status` shows the quarantine
|
|
211
215
|
(`rollbackIncomplete`, whose `inProgress` names the pid), and `oats retire`
|
|
212
216
|
refuses with `E_LIFECYCLE_BUSY`, naming the recorded pid and start for a
|
|
@@ -243,7 +247,11 @@ A self-contained package has an `oats.json`:
|
|
|
243
247
|
and nothing is silently dropped. Without `--force` that state fails closed with
|
|
244
248
|
`E_UNIDENTIFIED_INSTANCE_HOME` rather than deleting whatever credentials the
|
|
245
249
|
directory still holds; `--force` removes it and leaves any external state for
|
|
246
|
-
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
|
|
247
255
|
`retirement.disposable.home` (below) go with the home: recovery holds no
|
|
248
256
|
copy of them.
|
|
249
257
|
- `retirement.disposable` declares what retirement treats as the provider's
|