@awebai/oats 0.69.12 → 0.69.15
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 +216 -178
- package/bin/oats.mjs +254 -201
- package/docs/capabilities.md +58 -13
- package/docs/configuration.md +63 -5
- package/docs/container.md +291 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +590 -55
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +84 -9
- package/docs/first-team.md +4 -3
- package/docs/implementation.md +99 -32
- package/docs/integrations.md +3 -2
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +39 -5
- package/docs/packages.md +93 -14
- package/docs/release-lane.md +2 -1
- package/docs/release-notes/v0.69.13.md +767 -0
- package/docs/release-notes/v0.69.14.md +83 -0
- package/docs/release-notes/v0.69.15.md +444 -0
- package/docs/schedules.md +159 -5
- package/docs/servers.md +241 -7
- package/docs/souls-and-instances.md +223 -14
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +36 -5
- package/docs/workspaces.md +31 -5
- package/lib/claim.mjs +20 -5
- package/lib/command-flags.mjs +240 -0
- package/lib/core.mjs +1004 -633
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +145 -33
- package/lib/errors.mjs +3 -2
- package/lib/harness-token.mjs +110 -0
- package/lib/host-run.mjs +218 -0
- package/lib/host-stop-child.mjs +21 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +165 -14
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-lifecycle.mjs +4 -3
- package/lib/instance-listing.mjs +114 -43
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- package/lib/kernel-features.mjs +4 -1
- package/lib/launch-env-exec.sh +7 -0
- package/lib/launch-env.mjs +74 -0
- package/lib/launch-preference.mjs +19 -12
- package/lib/member-clone.mjs +7 -1
- package/lib/packages.mjs +74 -2
- package/lib/read-call.mjs +4 -1
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +126 -31
- package/lib/retained-after-retire.mjs +2 -7
- package/lib/retire-git-forms.mjs +41 -0
- package/lib/retire-incomplete.mjs +96 -0
- package/lib/schedule.mjs +239 -21
- package/lib/servers.mjs +161 -28
- package/lib/session-end.mjs +28 -8
- package/lib/session-resume.mjs +63 -56
- package/lib/session-seen.mjs +3 -14
- package/lib/start-env.mjs +13 -7
- package/lib/status-words.mjs +11 -4
- package/lib/system-tools.mjs +1 -36
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree-hooks.mjs +6 -175
- package/lib/worktree.mjs +68 -10
- package/package-catalog.json +1 -1
- package/package.json +5 -1
- package/packages/client/instance-lifecycle.mjs +1 -1
- package/packages/client/lifecycle-contract.mjs +3 -1
- package/packages/client/session-resume-cli.mjs +2 -1
- package/packages/client/session-start.mjs +10 -7
- package/packages/client/workspace-cli.mjs +5 -1
- package/packages/record/README.md +56 -21
- package/packages/record/docs/capture-service.md +8 -5
- package/packages/record/docs/turn-record-sot.md +9 -0
- package/packages/record/lib/capture-health.mjs +6 -4
- package/packages/record/lib/capture-lock.mjs +31 -27
- package/packages/record/lib/capture-retained-scratch.mjs +4 -3
- package/packages/record/lib/capture-scratch.mjs +2 -1
- package/packages/record/lib/derived-state.mjs +4 -2
- package/packages/record/lib/index-db.mjs +4 -2
- package/packages/record/lib/lock-holder.mjs +21 -0
- package/packages/record/lib/private-files.mjs +18 -0
- package/packages/record/lib/process-identity.mjs +310 -0
- package/packages/record/lib/store.mjs +31 -25
- package/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +93 -26
- package/lib/tmux-config.mjs +0 -35
package/bin/oats.mjs
CHANGED
|
@@ -54,38 +54,40 @@ const {
|
|
|
54
54
|
capabilityManifests, capabilityTrust, capabilityExecutablePath,
|
|
55
55
|
officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
|
|
56
56
|
findInstanceHome, findInstanceHomes, homeLaunchLayers, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, suggestSpawnName, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, machineLaunchConfigs, machineLaunchConfigsFile, launchStartNotices, launchReportFor, explicitInstanceName, MAX_INSTANCE_NAME, retireInstance, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, upgradeHoldsClaim, writeHomeRecord, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
|
|
57
|
-
FAILED_SPAWN_BRANCH_LEFT,
|
|
57
|
+
FAILED_SPAWN_BRANCH_LEFT,
|
|
58
58
|
} = await kernelImport("core", () => import("../lib/core.mjs"));
|
|
59
59
|
const {
|
|
60
60
|
writeFileAtomic, LOCK_FILE, canonicalLock, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
|
|
61
61
|
classifyPackageValue, parsePackageRequest } = await kernelImport("packages", () => import("../lib/packages.mjs"));
|
|
62
|
+
const { harnessToken } = await kernelImport("harness-token", () => import("../lib/harness-token.mjs"));
|
|
62
63
|
const { harnessTrust } = await kernelImport("harness-trust-write", () => import("../lib/harness-trust-write.mjs"));
|
|
63
64
|
const { previewLaunchEnvironment, previewPaneEnvironment } = await kernelImport("core", () => import("../lib/core.mjs"));
|
|
64
65
|
const { PI_BRIDGE, piBridgeFolders, piBridgeSkewWarnings, planPiBridges, piBridgePlanLines, piBridgeStepProblem, piBridgeFailure, kernelLookup, kernelLookupResult, planCliUpdate, desktopFirstLine, bridgeLookup, bridgeLookupProblem } = await kernelImport("pi-bridge", () => import("../lib/pi-bridge.mjs"));
|
|
65
66
|
const { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, unlockedPackages, workspaceWarnings, memberRowByKey } = await kernelImport("workspace", () => import("../lib/workspace.mjs"));
|
|
66
67
|
const { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } = await kernelImport("teams", () => import("../lib/teams.mjs"));
|
|
67
|
-
const { LAUNCH_KEY_UNCHECKED, LAUNCH_PREFERENCE_UNMATCHED, launchKeyQuoted, launchKeysUnmatched, launchLayers, soulLaunchCommand, unmatchedKeyMessage } = await kernelImport("launch-preference", () => import("../lib/launch-preference.mjs"));
|
|
68
|
-
const { terminalText } = await kernelImport("refused-text", () => import("../lib/refused-text.mjs"));
|
|
69
|
-
const { qualifiedSoulName, soulCandidates, soulsOffered } = await kernelImport("instance-resolution", () => import("../lib/instance-resolution.mjs"));
|
|
68
|
+
const { LAUNCH_KEY_UNCHECKED, LAUNCH_PREFERENCE_UNMATCHED, LAUNCH_PROBLEM_TEXT_MAX, launchKeyQuoted, launchKeysUnmatched, launchLayers, soulLaunchCommand, uncheckedSentences, unmatchedKeyMessage } = await kernelImport("launch-preference", () => import("../lib/launch-preference.mjs"));
|
|
69
|
+
const { safeText, terminalText } = await kernelImport("refused-text", () => import("../lib/refused-text.mjs"));
|
|
70
|
+
const { disabledEntriesUnmatched, qualifiedSoulName, soulCandidates, soulsOffered } = await kernelImport("instance-resolution", () => import("../lib/instance-resolution.mjs"));
|
|
70
71
|
const { parseConfigData } = await kernelImport("config-data", () => import("../lib/config-data.mjs"));
|
|
71
72
|
const remoteModule = await kernelImport("remote", () => import("../lib/remote.mjs"));
|
|
72
73
|
const { sameRepo } = await kernelImport("repo-moves", () => import("../lib/repo-moves.mjs"));
|
|
73
74
|
const { OATS_PACKAGE_NAME } = await kernelImport("version", () => import("../lib/version.mjs"));
|
|
74
75
|
const { activateLocalInputs, localRevision } = await kernelImport("local-inputs", () => import("../lib/local-inputs.mjs"));
|
|
75
76
|
const { default: YAML } = await kernelImport("yaml", () => import("yaml"));
|
|
76
|
-
const { attachArgv, checkRemote, connectServer, forgetSnapshot, getServer, inspectRemote, startRemote, restartRemote, launchConfigRemote, scheduleRemote, listSnapshots, learnWorkspaceKey, readServers, redactArgv, reportedWorkspaceKey, rosterGroups, routeCapability, routeCommand, runRemote, serverFlagOf, targetOf, updateServers, validateServer, workspaceKeyOfStatus, workspaceMismatch, SERVERS_FILE } = await kernelImport("servers", () => import("../lib/servers.mjs"));
|
|
77
|
+
const { attachArgv, checkRemote, connectServer, forgetSnapshot, getServer, inspectRemote, startRemote, restartRemote, launchConfigRemote, scheduleRemote, listSnapshots, learnWorkspaceKey, readServers, readServerOperatorRoutes, redactArgv, reportedWorkspaceKey, rosterGroups, routeCapability, routeCommand, runRemote, serverFlagOf, targetOf, updateServers, validateServer, validateOperatorSshHost, workspaceKeyOfStatus, workspaceMismatch, SERVERS_FILE } = await kernelImport("servers", () => import("../lib/servers.mjs"));
|
|
77
78
|
const { readSessionViewer } = await kernelImport("session-viewer", () => import("../lib/session-viewer.mjs"));
|
|
78
79
|
const { tickTriggers } = await kernelImport("triggers", () => import("../lib/triggers.mjs"));
|
|
79
80
|
const A = await kernelImport("automations", () => import("../lib/automations.mjs"));
|
|
80
|
-
const { parseEnvelopeText, unresolvedScheduleAttempts, scheduleScopeOf, listSchedules, describe: describeSchedule, testSchedule, addSchedule, updateSchedule, updateScheduleDescription, setEnabled: setScheduleEnabled, removeSchedule, runNow: runScheduleNow, reconcile: reconcileSchedule, tickHost, tickWorkspace, scopeAutomations, scheduleKind, registerWorkspace, unregisterWorkspace, readRegistry, schedulerStatus, saveWakeForHome, removeWakeForHome, wakeFromFlags, withHostLock, scheduleError, SCHEDULE_API } = await kernelImport("schedule", () => import("../lib/schedule.mjs"));
|
|
81
|
+
const { parseEnvelopeText, SCHEDULE_SLOT_UNREADABLE, SCHEDULE_SLOT_ORPHANED, unresolvedScheduleAttempts, scheduleScopeOf, listSchedules, describe: describeSchedule, testSchedule, addSchedule, updateSchedule, updateScheduleDescription, setEnabled: setScheduleEnabled, removeSchedule, runNow: runScheduleNow, reconcile: reconcileSchedule, tickHost, tickWorkspace, scopeAutomations, scheduleKind, registerWorkspace, unregisterWorkspace, readRegistry, schedulerStatus, saveWakeForHome, removeWakeForHome, wakeFromFlags, withHostLock, scheduleError, SCHEDULE_API } = await kernelImport("schedule", () => import("../lib/schedule.mjs"));
|
|
81
82
|
const { hostUnitFiles, hostUnitStatus, installHostUnit, uninstallHostUnit } = await kernelImport("schedule-host", () => import("../lib/schedule-host.mjs"));
|
|
82
83
|
const { kernelNode, stableNode } = await kernelImport("stable-node", () => import("../lib/stable-node.mjs"));
|
|
83
84
|
const { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } = await kernelImport("attachments", () => import("../lib/attachments.mjs"));
|
|
84
|
-
const { observeInstanceGit, diffInstanceFile } = await kernelImport("instance-git", () => import("../lib/instance-git.mjs"));
|
|
85
|
+
const { observeInstanceGit, diffInstanceFile, NO_FILE_MONITOR } = await kernelImport("instance-git", () => import("../lib/instance-git.mjs"));
|
|
85
86
|
const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstanceSameWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
|
|
86
87
|
const { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } = await kernelImport("retire-output", () => import("../lib/retire-output.mjs"));
|
|
87
88
|
const { livenessWord, lostLine, statusWord, waitingLine } = await kernelImport("status-words", () => import("../lib/status-words.mjs"));
|
|
88
89
|
const { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } = await kernelImport("retained-after-retire", () => import("../lib/retained-after-retire.mjs"));
|
|
90
|
+
const { retireIncompleteProblems } = await kernelImport("retire-incomplete", () => import("../lib/retire-incomplete.mjs"));
|
|
89
91
|
const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
|
|
90
92
|
const { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposition, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } = await kernelImport("instance-inspect", () => import("../lib/instance-inspect.mjs"));
|
|
91
93
|
const { readEvents, setWaiting, incarnationOf } = await kernelImport("instance-events", () => import("../lib/instance-events.mjs"));
|
|
@@ -98,12 +100,13 @@ const { callSession, parseMaxAge, readBudget } = await kernelImport("read-call",
|
|
|
98
100
|
const { cachedWorkspace, legacyLayoutProblems, statusAnswer, statusView } = await kernelImport("roster-read", () => import("../lib/roster-read.mjs"));
|
|
99
101
|
const { memberLabel, memberRows, packageRows, standaloneCatalogVersion, standalonePackages, workspaceName, workspaceStatusAnswer, workspaceStatusView } = await kernelImport("workspace-read", () => import("../lib/workspace-read.mjs"));
|
|
100
102
|
const { expandInlineValues, flagValue } = await kernelImport("argv", () => import("../lib/argv.mjs"));
|
|
103
|
+
const { APPROVAL_REMOVED, NATIVE_RECORD_REFUSED, HOST_RUN_USAGE, RESUME_LOCAL_ONLY, RETIRE_USAGE, SOUL_LAUNCH_USAGE, SPAWN_USAGE, SYNC_USAGE, TEAMS_USAGE, WORKTREE_USAGE, commandArgvProblem, commandFlags } = await kernelImport("command-flags", () => import("../lib/command-flags.mjs"));
|
|
101
104
|
|
|
102
105
|
const rawArgs = process.argv.slice(2);
|
|
103
106
|
const { argv: args, problem: argvProblem, inline: inlineValues } = expandInlineValues(rawArgs);
|
|
104
107
|
let cmd = args[0];
|
|
105
108
|
const HELP_WORDS = new Set(["help", "--help", "-h"]);
|
|
106
|
-
const KERNEL_COMMANDS = new Set(["harness", "automations", "trigger", "capture", "capabilities", "deployments", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "onboard", "pane", "reader", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "tui", "update", "version", "workspace", "worktree"]);
|
|
109
|
+
const KERNEL_COMMANDS = new Set(["harness", "automations", "trigger", "capture", "capabilities", "deployments", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "host", "onboard", "pane", "reader", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "tui", "update", "version", "workspace", "worktree"]);
|
|
107
110
|
/** Commands whose argv another parser reads (packages/record, packages/experimental and packages/tui parse process.argv). */
|
|
108
111
|
const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental", "tui"]);
|
|
109
112
|
/** Commands `--server <id>` runs on a registered server. */
|
|
@@ -305,6 +308,24 @@ async function doctorOperator(ws) {
|
|
|
305
308
|
return { problems: found.map(({ code, label, message, remedy }) => ({ code, ...(label ? { label } : {}), message, remedy })), information: [] };
|
|
306
309
|
}
|
|
307
310
|
|
|
311
|
+
/** This machine's last read of the workspace, for doctor's checks of the soul names in oats-local.yaml:
|
|
312
|
+
* discovered OFFLINE like doctorOperator, from this machine's cache only (cacheOnlyRemote), once per
|
|
313
|
+
* doctor run however many checks ask, and only when one asks. A cache that cannot answer rejects, for
|
|
314
|
+
* each check to say as information (doctorCacheWhy). */
|
|
315
|
+
const doctorReads = new WeakMap();
|
|
316
|
+
function doctorDiscovery(ws) {
|
|
317
|
+
if (!doctorReads.has(ws)) doctorReads.set(ws, (async () => {
|
|
318
|
+
const { cacheOnlyRemote } = await import("../lib/operator-coverage.mjs");
|
|
319
|
+
const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs");
|
|
320
|
+
const deployment = dirname(ws.local.path);
|
|
321
|
+
return discoverOrStandalone(ws.local.value, { lock: readLockIfPresent(deployment), deployment, remoteOptions: remoteOptionsFromEnv(), remote: cacheOnlyRemote() });
|
|
322
|
+
})());
|
|
323
|
+
return doctorReads.get(ws);
|
|
324
|
+
}
|
|
325
|
+
/** Why doctorDiscovery could not answer, as a doctor line says it: a cache miss is the cache's; anything
|
|
326
|
+
* else is named as itself. */
|
|
327
|
+
const doctorCacheWhy = (e) => (e?.code === "E_REMOTE_UNREADABLE" ? `this machine's cache cannot answer (${e.message})` : `${e?.code ? `${e.code}: ` : ""}${e?.message ?? e}`);
|
|
328
|
+
|
|
308
329
|
/** The keys of oats-local.yaml souls.launch that name no soul (awebai/oats#989), in doctor, OFFLINE like
|
|
309
330
|
* doctorOperator: the souls are discovered from this machine's cache only, and the one function
|
|
310
331
|
* (launchKeysUnmatched) decides. A problem per unmatched key, which speaks about this machine's last
|
|
@@ -320,13 +341,9 @@ async function doctorLaunchPreferences(ws) {
|
|
|
320
341
|
const shown = (list) => (list.length > 3 ? `${list.slice(0, 3).map(launchKeyQuoted).join(", ")} and ${list.length - 3} more` : list.map(launchKeyQuoted).join(", "));
|
|
321
342
|
let found;
|
|
322
343
|
try {
|
|
323
|
-
|
|
324
|
-
const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs");
|
|
325
|
-
const deployment = dirname(ws.local.path);
|
|
326
|
-
const discovery = await discoverOrStandalone(local, { lock: readLockIfPresent(deployment), deployment, remoteOptions: remoteOptionsFromEnv(), remote: cacheOnlyRemote() });
|
|
327
|
-
found = launchKeysUnmatched({ local, offered: soulsOffered(discovery) });
|
|
344
|
+
found = launchKeysUnmatched({ local, offered: soulsOffered(await doctorDiscovery(ws)) });
|
|
328
345
|
} catch (e) {
|
|
329
|
-
const why =
|
|
346
|
+
const why = doctorCacheWhy(e);
|
|
330
347
|
return { problems: [], information: [`launch-preference-unchecked: the keys of oats-local.yaml souls.launch (${shown(keys)}) were not checked against the souls this workspace offers: ${why}; oats sync, then oats souls, then run doctor again (a spawn reads the workspace itself and refuses a key that names no soul)`] };
|
|
331
348
|
}
|
|
332
349
|
return {
|
|
@@ -337,6 +354,38 @@ async function doctorLaunchPreferences(ws) {
|
|
|
337
354
|
};
|
|
338
355
|
}
|
|
339
356
|
|
|
357
|
+
/** The entries of oats-local.yaml souls.disabled that name no soul (oats-project/oats#1772), in doctor,
|
|
358
|
+
* OFFLINE from the read doctorLaunchPreferences uses (doctorDiscovery), and the one function
|
|
359
|
+
* (disabledEntriesUnmatched) decides. Such an entry keeps no soul off this machine: it fails open. A
|
|
360
|
+
* problem per unmatched entry, which speaks about this machine's last read of the souls: a spawn reads
|
|
361
|
+
* the workspace itself and is the authority. An entry that could not be checked, or a cache that cannot
|
|
362
|
+
* answer, is an information line (`disabled-soul-unchecked`), never silence and never a failure of
|
|
363
|
+
* doctor. No command writes souls.disabled, so the remedy is the hand edit. The entry and the nearest
|
|
364
|
+
* souls are said through the launch texts' bound (launchKeyQuoted, safeText).
|
|
365
|
+
* → { problems: [{ code, entry, at, suggestions, message, remedy }], information: [string] } */
|
|
366
|
+
async function doctorDisabledSouls(ws) {
|
|
367
|
+
const local = ws.local.value;
|
|
368
|
+
const entries = Array.isArray(local?.souls?.disabled) ? local.souls.disabled.filter((e) => typeof e === "string") : [];
|
|
369
|
+
if (!entries.length) return { problems: [], information: [] };
|
|
370
|
+
let found;
|
|
371
|
+
try {
|
|
372
|
+
found = disabledEntriesUnmatched({ local, discovery: await doctorDiscovery(ws) });
|
|
373
|
+
} catch (e) {
|
|
374
|
+
const shown = entries.length > 3 ? `${entries.slice(0, 3).map(launchKeyQuoted).join(", ")} and ${entries.length - 3} more` : entries.map(launchKeyQuoted).join(", ");
|
|
375
|
+
return { problems: [], information: [`disabled-soul-unchecked: the entries of oats-local.yaml souls.disabled (${shown}) were not checked against the souls this workspace offers: ${doctorCacheWhy(e)}; oats sync, then oats souls, then run doctor again`] };
|
|
376
|
+
}
|
|
377
|
+
const reasons = uncheckedSentences("entry");
|
|
378
|
+
return {
|
|
379
|
+
problems: found.unmatched.map(({ entry, at, suggestions }) => {
|
|
380
|
+
const near = suggestions.map((name) => safeText(name, LAUNCH_PROBLEM_TEXT_MAX)).join(", ");
|
|
381
|
+
return { code: "disabled-soul-unmatched", entry, at, suggestions,
|
|
382
|
+
message: `oats-local.yaml souls.disabled names ${launchKeyQuoted(entry)}${near ? ` (nearest: ${near})` : ""}, which is no soul in this machine's last read of the souls this workspace offers, so it keeps no soul off this machine. A spawn reads the workspace itself and is the authority`,
|
|
383
|
+
remedy: `in oats-local.yaml souls.disabled, replace ${launchKeyQuoted(entry)} with the soul it was meant to keep off this machine (${near ? `nearest: ${near}; ` : ""}oats souls lists them), or remove it` };
|
|
384
|
+
}),
|
|
385
|
+
information: found.unchecked.map(({ entry, reason }) => `disabled-soul-unchecked: oats-local.yaml souls.disabled ${launchKeyQuoted(entry)} was not checked against the souls this workspace offers: ${reasons[reason] ?? reason}; this is this machine's last read, and a spawn reads the workspace itself`),
|
|
386
|
+
};
|
|
387
|
+
}
|
|
388
|
+
|
|
340
389
|
/** What the deployment's capabilities declare and this kernel ignores (an unknown hook event), for
|
|
341
390
|
* doctor without --soul, OFFLINE like doctorOperator, from this machine's parsed cache: each member's
|
|
342
391
|
* capabilities as `oats sync` enumerated them (the workspace's members confirmed by the cached
|
|
@@ -825,6 +874,14 @@ function doctorMachineLaunchConfigs() {
|
|
|
825
874
|
return { file, present: true, ok: false, configurations: [], error: e.message };
|
|
826
875
|
}
|
|
827
876
|
}
|
|
877
|
+
/** The machine's resume lock when it needs a person (lib/session-resume.mjs resumeLockProblem), as
|
|
878
|
+
* doctor's problems: read where a sweep would take it, nothing taken. It is this machine's, the
|
|
879
|
+
* same from every deployment. */
|
|
880
|
+
async function doctorResumeLock() {
|
|
881
|
+
const { resumeLockProblem } = await import("../lib/session-resume.mjs");
|
|
882
|
+
const problem = resumeLockProblem();
|
|
883
|
+
return problem ? [problem] : [];
|
|
884
|
+
}
|
|
828
885
|
async function doctorWorkspaceJson(ctx, soulName, ws) {
|
|
829
886
|
const composition = await doctorComposition(ctx, soulName, ws, (code, msg, details) => jsonFail(code, msg, details));
|
|
830
887
|
const agentsRoot = join(dirname(ws.local.path), "agents");
|
|
@@ -832,14 +889,15 @@ async function doctorWorkspaceJson(ctx, soulName, ws) {
|
|
|
832
889
|
const schedules = unresolvedScheduleAttempts(dirname(ws.local.path));
|
|
833
890
|
const operator = await doctorOperator(ws);
|
|
834
891
|
const launchPreferences = await doctorLaunchPreferences(ws);
|
|
892
|
+
const disabledSouls = await doctorDisabledSouls(ws);
|
|
835
893
|
// With --soul, the soul's composition; without, the deployment's capabilities (doctorHookWarnings).
|
|
836
894
|
const hookEvents = composition ? { warnings: composition.warnings, information: [] } : await doctorHookWarnings(ws);
|
|
837
|
-
const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot), ...localTeams.problems, ...schedules.problems, ...operator.problems, ...launchPreferences.problems].filter(Boolean);
|
|
895
|
+
const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot), ...localTeams.problems, ...schedules.problems, ...operator.problems, ...launchPreferences.problems, ...disabledSouls.problems, ...retireIncompleteProblems(agentsRoot), ...await doctorResumeLock()].filter(Boolean);
|
|
838
896
|
return {
|
|
839
897
|
schemaVersion: 1, workspaceApi: 2, context: ctx,
|
|
840
898
|
workspace: { file: ws.local.path, ref: ws.local.workspace },
|
|
841
899
|
workspaceError: ws.localError, lockFile: ws.lockFile, packages: ws.packages, lockError: ws.lockError,
|
|
842
|
-
information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
|
|
900
|
+
information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...disabledSouls.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
|
|
843
901
|
machineLaunchConfigs: doctorMachineLaunchConfigs(),
|
|
844
902
|
composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
|
|
845
903
|
...(problems.length ? { problems } : {}),
|
|
@@ -886,15 +944,20 @@ async function doctor(dir) {
|
|
|
886
944
|
for (const p of [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot)].filter(Boolean)) console.log(`\n! ${p.code}: ${p.message}`);
|
|
887
945
|
for (const p of localTeams.problems) console.log(`\n! ${p.code} (${p.condition}): ${p.message}`);
|
|
888
946
|
const schedules = unresolvedScheduleAttempts(dirname(ws.local.path));
|
|
889
|
-
for (const p of schedules.problems) console.log(`\n! ${p.code}: ${p.message}`);
|
|
947
|
+
for (const p of schedules.problems) console.log(`\n! ${p.code}: ${p.message}${[SCHEDULE_SLOT_UNREADABLE, SCHEDULE_SLOT_ORPHANED].includes(p.code) ? `\n ${p.remedy}` : ""}`);
|
|
890
948
|
const operator = await doctorOperator(ws);
|
|
891
949
|
for (const p of operator.problems) console.log(`\n! ${p.code}: ${p.message}\n ${p.remedy}`);
|
|
892
950
|
const launchPreferences = await doctorLaunchPreferences(ws);
|
|
893
951
|
for (const p of launchPreferences.problems) console.log(`\n! ${p.code}: ${p.message}\n ${p.remedy}`);
|
|
952
|
+
const disabledSouls = await doctorDisabledSouls(ws);
|
|
953
|
+
for (const p of disabledSouls.problems) console.log(`\n! ${p.code}: ${p.message}\n ${p.remedy}`);
|
|
954
|
+
// Retirements left open (#1747): the command that finishes each, and whose hook failed last.
|
|
955
|
+
for (const p of retireIncompleteProblems(agentsRoot)) console.log(`\n! ${p.code}: ${terminalText(p.message)}\n ${terminalText(p.remedy)}`);
|
|
956
|
+
for (const p of await doctorResumeLock()) console.log(`\n! ${p.code}: ${terminalText(p.message)}\n ${terminalText(p.remedy)}`);
|
|
894
957
|
const hookEvents = composition ? { warnings: composition.warnings, information: [] } : await doctorHookWarnings(ws);
|
|
895
958
|
for (const w of hookEvents.warnings) console.log(`\nwarning ${w.code} ${w.message}`);
|
|
896
959
|
if (!soulName) for (const w of doctorCaptureWarnings()) console.log(`\nwarning ${w.code} ${terminalText(w.message)}`);
|
|
897
|
-
for (const line of [...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...hookEvents.information, ...processScanInformation()]) console.log(`\nINFO: ${line}`);
|
|
960
|
+
for (const line of [...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...disabledSouls.information, ...hookEvents.information, ...processScanInformation()]) console.log(`\nINFO: ${line}`);
|
|
898
961
|
for (const block of doctorRetained(ws)) console.log(`\n${block.map((line) => `INFO: ${line}`).join("\n")}`);
|
|
899
962
|
if (soulName) {
|
|
900
963
|
const information = operationalKnowledgeNote(composition, soulName);
|
|
@@ -960,7 +1023,7 @@ function serializeLaunchConfigs(map) {
|
|
|
960
1023
|
const envNames = Object.keys(e.env || {}).sort();
|
|
961
1024
|
if (envNames.length) {
|
|
962
1025
|
lines.push(" env:");
|
|
963
|
-
for (const n of envNames) { const v = e.env[n]; if (typeof v === "string") lines.push(` ${n}: ${yamlQuoted(v)}`); else lines.push(` ${n}:`, ` fromEnv: ${v.fromEnv}`); }
|
|
1026
|
+
for (const n of envNames) { const v = e.env[n]; if (typeof v === "string") lines.push(` ${n}: ${yamlQuoted(v)}`); else lines.push(` ${n}:`, v.fromFile !== undefined ? ` fromFile: ${yamlQuoted(v.fromFile)}` : ` fromEnv: ${v.fromEnv}`); }
|
|
964
1027
|
}
|
|
965
1028
|
if (e.model !== undefined) lines.push(` model: ${yamlQuoted(e.model)}`);
|
|
966
1029
|
if (e.yolo !== undefined) lines.push(` yolo: ${e.yolo}`);
|
|
@@ -976,7 +1039,7 @@ function normalizeLaunchConfig(e) {
|
|
|
976
1039
|
harness: Object.hasOwn(e, "harness") ? e.harness : e.runtime,
|
|
977
1040
|
...(e.executable !== undefined ? { executable: e.executable } : {}),
|
|
978
1041
|
...(e.args?.length ? { args: [...e.args] } : {}),
|
|
979
|
-
...(e.env && Object.keys(e.env).length ? { env: Object.fromEntries(Object.keys(e.env).sort().map((n) => [n, typeof e.env[n] === "string" ? e.env[n] : {
|
|
1042
|
+
...(e.env && Object.keys(e.env).length ? { env: Object.fromEntries(Object.keys(e.env).sort().map((n) => [n, typeof e.env[n] === "string" ? e.env[n] : { ...e.env[n] }])) } : {}),
|
|
980
1043
|
...(e.model !== undefined ? { model: e.model } : {}),
|
|
981
1044
|
...(e.yolo !== undefined ? { yolo: e.yolo } : {}),
|
|
982
1045
|
...(e.default === true ? { default: true } : {}),
|
|
@@ -1001,10 +1064,10 @@ function machineDeclares(name) {
|
|
|
1001
1064
|
/** What a GUI or an operator sees of one configuration. Environment values
|
|
1002
1065
|
* never leave the file: a literal is answered as {redacted: true} (literals
|
|
1003
1066
|
* are non-secret by contract, but no value is shown anywhere) and a
|
|
1004
|
-
* reference as {fromEnv: NAME}. An editor keeps a literal it cannot see with
|
|
1067
|
+
* reference as {fromEnv: NAME} or {fromFile: /path}. An editor keeps a literal it cannot see with
|
|
1005
1068
|
* `set --keep-env`. */
|
|
1006
1069
|
function publicLaunchConfig(e, extra = {}) {
|
|
1007
|
-
const env = Object.fromEntries(Object.keys(e.env || {}).sort().map((n) => [n, typeof e.env[n] === "string" ? { redacted: true } : {
|
|
1070
|
+
const env = Object.fromEntries(Object.keys(e.env || {}).sort().map((n) => [n, typeof e.env[n] === "string" ? { redacted: true } : { ...e.env[n] }]));
|
|
1008
1071
|
return { harness: e.harness, executable: e.executable ?? null, args: [...(e.args || [])], env, model: e.model ?? null, yolo: e.yolo ?? null, default: e.default === true, ...extra };
|
|
1009
1072
|
}
|
|
1010
1073
|
/** The scope a launch-config command reads: --dir (or cwd), a running
|
|
@@ -1079,7 +1142,7 @@ function launchPreview(bail) {
|
|
|
1079
1142
|
const { recipe } = plan;
|
|
1080
1143
|
const command = renderLaunchRecipe(recipe, { home, instance, redact: true, trustHome: plan.trustHome });
|
|
1081
1144
|
const d = describeLaunchCommand(command);
|
|
1082
|
-
const environment = d.environment.map((e) => e.reference && recipe.env[e.name]
|
|
1145
|
+
const environment = d.environment.map((e) => e.reference && recipe.env[e.name] && typeof recipe.env[e.name] === "object" ? { name: e.name, ...recipe.env[e.name] } : e);
|
|
1083
1146
|
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 });
|
|
1084
1147
|
}
|
|
1085
1148
|
async function launchConfigCmd() {
|
|
@@ -1090,7 +1153,6 @@ async function launchConfigCmd() {
|
|
|
1090
1153
|
if (sub === "preview") { launchPreview(bail); return; }
|
|
1091
1154
|
if (!["list", "set", "remove"].includes(sub)) bail("E_USAGE", usage);
|
|
1092
1155
|
const { context: dir, selected } = sub === "list" ? launchConfigContext(bail) : { context: dirFlag(), selected: null };
|
|
1093
|
-
if (sub !== "list" && (flag("home") !== undefined || flag("soul") !== undefined)) bail("E_BAD_ARGS", `launch-config ${sub} writes the deployment's oats-local.yaml: address it with --dir, not --home or --soul`);
|
|
1094
1156
|
// Lead decision 2: launch configurations are a HOST choice, declared in the
|
|
1095
1157
|
// deployment's oats-local.yaml (found walking up; a home's own deployment).
|
|
1096
1158
|
const at = selected?.home ?? dir;
|
|
@@ -1108,7 +1170,7 @@ async function launchConfigCmd() {
|
|
|
1108
1170
|
if (JSON_MODE) { jsonOk({ context: dir, level, file, selected, configurations }); return; }
|
|
1109
1171
|
if (!configurations.length) { console.log(`No launch configurations are declared${file ? ` in ${shortPath(file)}` : ` (no oats-local.yaml in reach of ${dir})`} or in ${shortPath(machineLaunchConfigsFile())}`); return; }
|
|
1110
1172
|
for (const c of configurations) {
|
|
1111
|
-
const env = Object.entries(c.env).map(([n, v]) => v.fromEnv ? `${n}=$${v.fromEnv}` : `${n}=<redacted>`).join(" ");
|
|
1173
|
+
const env = Object.entries(c.env).map(([n, v]) => v.fromEnv ? `${n}=$${v.fromEnv}` : v.fromFile ? `${n}=<file:${v.fromFile}>` : `${n}=<redacted>`).join(" ");
|
|
1112
1174
|
console.log(`${c.name}: ${c.harness}${c.default ? ` (this machine's ${c.harness} default)` : ""}${c.executable ? ` ${c.executable}` : ""}${c.args.length ? ` ${c.args.map((a) => JSON.stringify(a)).join(" ")}` : ""}${env ? ` [${env}]` : ""}${c.model ? ` model ${c.model}` : ""}${c.yolo !== null ? ` yolo ${c.yolo}` : ""} (from ${shortPath(launchConfigFile(c.source))})${c.shadows.length ? ` (replaces ${c.shadows.map(shortPath).join(", ")}'s)` : ""}`);
|
|
1113
1175
|
}
|
|
1114
1176
|
return;
|
|
@@ -1210,15 +1272,13 @@ async function launchConfigCmd() {
|
|
|
1210
1272
|
function instanceWaitingCmd(sub, bail) {
|
|
1211
1273
|
dropAmbientRoot();
|
|
1212
1274
|
const usage = sub === "attention"
|
|
1213
|
-
? "usage: oats instance attention [--message
|
|
1214
|
-
: "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message
|
|
1275
|
+
? "usage: oats instance attention [--message=<text>] [--clear] [--json]"
|
|
1276
|
+
: "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json]";
|
|
1215
1277
|
const value = (name) => { const v = flag(name); if (v === true) throw Object.assign(new Error(`--${name} needs a value${name === "message" ? " (a message that starts with -- goes as --message=<text>)" : ""}`), { code: "E_BAD_ARGS" }); return v; };
|
|
1216
1278
|
let home, producer, waiting, reason, message;
|
|
1217
1279
|
try {
|
|
1218
1280
|
message = value("message");
|
|
1219
1281
|
if (sub === "attention") {
|
|
1220
|
-
if (args[2] && !args[2].startsWith("--")) return bail("E_BAD_ARGS", usage);
|
|
1221
|
-
for (const f of ["home", "dir", "producer", "reason"]) if (args.includes(`--${f}`)) return bail("E_BAD_ARGS", `oats instance attention has no --${f}: it records the agent's own claim on the instance it runs in ($OATS_INSTANCE_HOME); ${usage}`);
|
|
1222
1282
|
home = process.env.OATS_INSTANCE_HOME;
|
|
1223
1283
|
if (!home || !isAbsolute(home) || incarnationOf(home) === null) return bail("E_USAGE", `oats instance attention runs inside an instance session: $OATS_INSTANCE_HOME is ${home ? `${home}, which is not an instance home (no readable instance.json)` : "unset"}`);
|
|
1224
1284
|
producer = "agent"; waiting = !args.includes("--clear");
|
|
@@ -1230,7 +1290,7 @@ function instanceWaitingCmd(sub, bail) {
|
|
|
1230
1290
|
producer = value("producer"); reason = value("reason");
|
|
1231
1291
|
if (producer === undefined) return bail("E_BAD_ARGS", `--producer is required; ${usage}`);
|
|
1232
1292
|
// Producer `agent` is the agent's own claim: only `attention` writes it.
|
|
1233
|
-
if (producer === "agent") return bail("E_BAD_ARGS", "--producer agent is reserved for the agent's own claim: use `oats instance attention [--message
|
|
1293
|
+
if (producer === "agent") return bail("E_BAD_ARGS", "--producer agent is reserved for the agent's own claim: use `oats instance attention [--message=<text>]` or `oats instance attention --clear` from its session");
|
|
1234
1294
|
const homeOpt = flag("home");
|
|
1235
1295
|
if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
|
|
1236
1296
|
home = homeOpt ?? (process.env.OATS_INSTANCE_HOME || enclosingInstanceHome(logicalCwd()));
|
|
@@ -1252,6 +1312,19 @@ function instanceWaitingCmd(sub, bail) {
|
|
|
1252
1312
|
} catch (e) { return bail(e.code || "E_EVENTS_FAILED", e.message, e.candidates ? { candidates: e.candidates } : undefined); }
|
|
1253
1313
|
}
|
|
1254
1314
|
|
|
1315
|
+
/** A caller that closes its end of stdout or stderr (a tool shell killed, Desktop gone, an ssh
|
|
1316
|
+
* session that ended) has only stopped reading: the command goes on to its consistent end, what it
|
|
1317
|
+
* can no longer print is dropped, and its exit status is the one it would have had. Unhandled,
|
|
1318
|
+
* that EPIPE would end this process where it stands: a `worktree add` mid-hook, with no rollback; a
|
|
1319
|
+
* spawn, a retire, a start or a stop that has completed, as if it had failed. For the verbs that
|
|
1320
|
+
* change state: `worktree`, `spawn`, `retire`, `session start`, `session restart` and
|
|
1321
|
+
* `instance stop --apply`. */
|
|
1322
|
+
function outliveReader() {
|
|
1323
|
+
const readerGone = (e) => { if (e?.code !== "EPIPE" && e?.code !== "ERR_STREAM_DESTROYED") throw e; };
|
|
1324
|
+
process.stdout.on("error", readerGone);
|
|
1325
|
+
process.stderr.on("error", readerGone);
|
|
1326
|
+
}
|
|
1327
|
+
|
|
1255
1328
|
/** `oats worktree add|remove` (#796, feature worktree-event): an instance's extra trees,
|
|
1256
1329
|
* `<home>/.work-<purpose>`, made from its home (lib/worktree.mjs). The home is
|
|
1257
1330
|
* $OATS_INSTANCE_HOME (or $OATS_HOME), else the home enclosing the working directory.
|
|
@@ -1260,24 +1333,16 @@ function instanceWaitingCmd(sub, bail) {
|
|
|
1260
1333
|
async function worktreeCmd() {
|
|
1261
1334
|
const bail = (code, msg, details, exit) => (JSON_MODE ? jsonFail(code, msg, details, exit) : die(msg, exit));
|
|
1262
1335
|
const sub = args[1];
|
|
1263
|
-
const usage =
|
|
1336
|
+
const usage = WORKTREE_USAGE;
|
|
1264
1337
|
if (!["add", "remove"].includes(sub)) return bail("E_BAD_ARGS", usage);
|
|
1265
|
-
if (flag("server") !== undefined) return bail("E_BAD_ARGS", "oats worktree runs in an instance home on this machine; --server is not accepted");
|
|
1266
|
-
for (const f of ["dir", "home"]) if (args.includes(`--${f}`)) return bail("E_BAD_ARGS", `oats worktree has no --${f}: it acts on the instance home it runs in; ${usage}`);
|
|
1267
1338
|
const value = (name) => { const v = flag(name); if (v === true) throw Object.assign(new Error(`--${name} needs a value`), { code: "E_BAD_ARGS" }); return v === undefined ? undefined : String(v); };
|
|
1268
1339
|
const homeVariable = ["OATS_INSTANCE_HOME", "OATS_HOME"].find((name) => process.env[name]);
|
|
1269
1340
|
const home = homeVariable ? process.env[homeVariable] : enclosingInstanceHome(logicalCwd());
|
|
1270
1341
|
if (!home) return bail("E_BAD_ARGS", `oats worktree runs from an instance home: run it in the home (or below it), or with $OATS_INSTANCE_HOME set; ${usage}`);
|
|
1271
1342
|
const W = await import("../lib/worktree.mjs");
|
|
1272
|
-
|
|
1273
|
-
// stopped reading: the add or remove goes on to its consistent end, and what it can no longer
|
|
1274
|
-
// print is dropped. Unhandled, that EPIPE would end this process mid-hook, with no rollback.
|
|
1275
|
-
const readerGone = (e) => { if (e?.code !== "EPIPE" && e?.code !== "ERR_STREAM_DESTROYED") throw e; };
|
|
1276
|
-
process.stdout.on("error", readerGone);
|
|
1277
|
-
process.stderr.on("error", readerGone);
|
|
1343
|
+
outliveReader();
|
|
1278
1344
|
try {
|
|
1279
1345
|
if (sub === "remove") {
|
|
1280
|
-
for (const f of ["branch", "base", "repo", "preview"]) if (args.includes(`--${f}`)) return bail("E_BAD_ARGS", `oats worktree remove takes only --purpose; ${usage}`);
|
|
1281
1346
|
const r = await W.worktreeRemove(resolve(home), { purpose: value("purpose") });
|
|
1282
1347
|
if (JSON_MODE) { jsonOk(r); return; }
|
|
1283
1348
|
console.log(r.rolledBack
|
|
@@ -1338,7 +1403,6 @@ function retiredInstanceAddresses(root, name, home) {
|
|
|
1338
1403
|
async function instanceUpgradeCmd(name, bail) {
|
|
1339
1404
|
const usage = "usage: oats instance upgrade <instance> [--undo] (--plan | --plan-revision <rev> --idempotency-key <key>) [--home <abs>] [--dir <d>] [--json]";
|
|
1340
1405
|
if (!name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
|
|
1341
|
-
if (serverFlagOf(args)) return bail("E_BAD_ARGS", "instance upgrade supports local homes only; run it on the deployment host");
|
|
1342
1406
|
const home = flag("home"), revision = flag("plan-revision"), key = flag("idempotency-key");
|
|
1343
1407
|
if (home === true || (home !== undefined && !isAbsolute(home))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
|
|
1344
1408
|
const planOnly = args.includes("--plan"), undo = args.includes("--undo");
|
|
@@ -1359,8 +1423,6 @@ async function instanceUpgradeCmd(name, bail) {
|
|
|
1359
1423
|
} catch (e) { return lifecycleFail(e, "E_UPGRADE_FAILED", { ...e.details, ...(e.plan ? { plan: e.plan } : {}), ...(e.candidates ? { candidates: e.candidates } : {}) }); }
|
|
1360
1424
|
}
|
|
1361
1425
|
|
|
1362
|
-
/** The flags `oats instance suggest-name` reads, each taking a value (`--json` aside). */
|
|
1363
|
-
const SUGGEST_NAME_FLAGS = new Set(["soul", "task", "task-file", "harness", "model", "launch-config", "dir"]);
|
|
1364
1426
|
/** `oats instance suggest-name` (feature instance-suggest-name, awebai/oats#1490 §2): the name a spawn
|
|
1365
1427
|
* of a soul would get by --suggest-name, chosen here for a spawn that may land on another machine
|
|
1366
1428
|
* (lib/core.mjs suggestSpawnName). Never routed: --server is refused before the route dispatch. */
|
|
@@ -1374,12 +1436,6 @@ async function instanceSuggestNameCmd(bail) {
|
|
|
1374
1436
|
if (v === undefined || (!inlineValues.has(name) && v.startsWith("--"))) return bail("E_BAD_ARGS", `--${name} needs a value; ${usage}`);
|
|
1375
1437
|
return v;
|
|
1376
1438
|
};
|
|
1377
|
-
for (let i = 2; i < args.length; i++) {
|
|
1378
|
-
const a = args[i];
|
|
1379
|
-
if (a === "--json") continue;
|
|
1380
|
-
if (!a.startsWith("--") || !SUGGEST_NAME_FLAGS.has(a.slice(2))) return bail("E_BAD_ARGS", `oats instance suggest-name: unexpected ${a.startsWith("--") ? "flag" : "argument"} ${JSON.stringify(a)}; ${usage}`);
|
|
1381
|
-
if (!inlineValues.has(a.slice(2))) i++;
|
|
1382
|
-
}
|
|
1383
1439
|
const soul = value("soul"), task = value("task"), taskFile = value("task-file");
|
|
1384
1440
|
if (soul === undefined) return bail("E_BAD_ARGS", `--soul is required; ${usage}`);
|
|
1385
1441
|
if ((task === undefined) === (taskFile === undefined)) return bail("E_BAD_ARGS", `give the task with one of --task or --task-file; ${usage}`);
|
|
@@ -1397,7 +1453,7 @@ async function instanceCmd() {
|
|
|
1397
1453
|
if (sub === "upgrade") return instanceUpgradeCmd(name, bail);
|
|
1398
1454
|
if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
|
|
1399
1455
|
if (sub === "suggest-name") return instanceSuggestNameCmd(bail);
|
|
1400
|
-
const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message
|
|
1456
|
+
const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message=<text>] [--clear] [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json] | oats instance background <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance same-work <instance> on|off [--home <abs>] [--dir <d>] [--json]";
|
|
1401
1457
|
if (!["git", "diff", "stop", "events", "color", "background", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
|
|
1402
1458
|
dropAmbientRoot();
|
|
1403
1459
|
if (sub === "events") {
|
|
@@ -1440,7 +1496,6 @@ async function instanceCmd() {
|
|
|
1440
1496
|
const words = [];
|
|
1441
1497
|
for (let i = 3; i < args.length; i++) { if (args[i] === "--home" || args[i] === "--dir") i++; else if (!args[i].startsWith("--")) words.push(args[i]); }
|
|
1442
1498
|
const clear = args.includes("--clear");
|
|
1443
|
-
if (words.length > 1) return bail("E_BAD_ARGS", `oats instance color takes one colour; ${colorUsage}`);
|
|
1444
1499
|
const value = words[0];
|
|
1445
1500
|
if (value !== undefined && clear) return bail("E_BAD_ARGS", `give a colour or --clear, not both; ${colorUsage}`);
|
|
1446
1501
|
if (value === undefined && !clear) return bail("E_BAD_ARGS", `give a colour or --clear; ${colorUsage}`);
|
|
@@ -1513,6 +1568,7 @@ async function instanceCmd() {
|
|
|
1513
1568
|
}
|
|
1514
1569
|
const rev = flag("plan-revision"), key = flag("idempotency-key"), grace = flag("grace-ms");
|
|
1515
1570
|
if (rev === true || key === true || grace === true) return bail("E_BAD_ARGS", usage);
|
|
1571
|
+
outliveReader();
|
|
1516
1572
|
const receipt = applyStop(dirFlag(), root, name, { home: homeOpt, recursive, planRevision: rev, idempotencyKey: key, ...(grace !== undefined ? { graceMs: Number(grace) } : {}) });
|
|
1517
1573
|
// Not part of the receipt, whose shape is contract: on stderr in both modes.
|
|
1518
1574
|
for (const w of receipt[STOP_WARNINGS] || []) console.error(`oats: warning: ${w}`);
|
|
@@ -1620,7 +1676,8 @@ function commandSession() {
|
|
|
1620
1676
|
process.on("exit", () => { sayReadNotices(); readSession.closeNow(); });
|
|
1621
1677
|
for (const [signal, code] of [["SIGINT", 130], ["SIGTERM", 143], ["SIGHUP", 129]]) process.once(signal, () => {
|
|
1622
1678
|
readSession.closeNow();
|
|
1623
|
-
// Another handler (a
|
|
1679
|
+
// Another handler still listening (a naming call's and a lock's, lib/dir-lock.mjs, which raise
|
|
1680
|
+
// the signal again; a held `worktree` hook's, an attach's) ends the command itself after this one.
|
|
1624
1681
|
if (process.listenerCount(signal) === 0) process.exit(code);
|
|
1625
1682
|
});
|
|
1626
1683
|
}
|
|
@@ -1707,6 +1764,30 @@ function workspaceContext(bail) {
|
|
|
1707
1764
|
return { dir, localPath: found.path, local: found.local, deploymentDir: dirname(found.path), remoteOptions: remoteOptionsFromEnv() };
|
|
1708
1765
|
}
|
|
1709
1766
|
|
|
1767
|
+
/** Tokens are operator-local calls even with --server; the forced-command key is the receiver. */
|
|
1768
|
+
async function harnessTokenCmd() {
|
|
1769
|
+
const usage = "usage: oats harness token set|status|remove <harness> --server <id> [--name <team>] [--stdin] [--json] [--debug]";
|
|
1770
|
+
if (!["set", "status", "remove"].includes(args[2]) || !args[3] || args[3].startsWith("-")) return cmdFail("E_BAD_ARGS", usage);
|
|
1771
|
+
const seen = new Set();
|
|
1772
|
+
for (let i = 4; i < args.length; i++) {
|
|
1773
|
+
const word = args[i];
|
|
1774
|
+
if (seen.has(word)) return cmdFail("E_BAD_ARGS", "Give each token-command flag once.");
|
|
1775
|
+
seen.add(word);
|
|
1776
|
+
if (["--json", "--stdin", "--debug"].includes(word)) continue;
|
|
1777
|
+
if (["--server", "--name"].includes(word) && args[i + 1] && !args[i + 1].startsWith("-")) { i++; continue; }
|
|
1778
|
+
return cmdFail("E_BAD_ARGS", usage);
|
|
1779
|
+
}
|
|
1780
|
+
try {
|
|
1781
|
+
const result = await harnessToken({ action: args[2], harness: args[3], server: valueFlag("server"), name: valueFlag("name"), input: args.includes("--stdin") ? process.stdin : undefined }, { debug: args.includes("--debug") ? (line) => console.error(`oats: ${line}`) : undefined });
|
|
1782
|
+
if (JSON_MODE) jsonOk(result);
|
|
1783
|
+
else {
|
|
1784
|
+
console.log(result.action === "set" ? `Installed ${result.harness} credential for ${result.name} on ${result.server}: ${result.fingerprint}.` : result.action === "remove" ? `Removed ${result.harness} credential for ${result.name} on ${result.server}.` : `${result.harness} credential for ${result.name} on ${result.server}: ${result.fingerprint}, replaced ${result.replacedAt}.`);
|
|
1785
|
+
for (const row of result.staleInstances ?? []) console.log(terminalText(` ${row.instance} (${row.agent}): started ${row.startedAt}; picks up the token at its next start.`));
|
|
1786
|
+
for (const warning of result.warnings) console.error(`oats: warning: ${warning}`);
|
|
1787
|
+
}
|
|
1788
|
+
} catch (e) { cmdFail(e.code || "E_HARNESS_TOKEN_DELIVERY", JSON_MODE ? e.message : terminalText(e.message)); }
|
|
1789
|
+
}
|
|
1790
|
+
|
|
1710
1791
|
/** An explicit host-local operator action; never routed to a remote adapter. */
|
|
1711
1792
|
function harnessTrustCmd() {
|
|
1712
1793
|
if (args[1] !== "trust") return cmdFail("E_BAD_ARGS", "usage: oats harness trust [--dir <deployment>] [--harness claude|codex|all] [--plan] [--json]");
|
|
@@ -1825,7 +1906,6 @@ function printTable(header, rows) {
|
|
|
1825
1906
|
}
|
|
1826
1907
|
|
|
1827
1908
|
/** `--approve` left with package approval (human decision 2026-09-24). */
|
|
1828
|
-
const APPROVAL_REMOVED = "package approval was removed; declaring a package in packages: is the trust decision";
|
|
1829
1909
|
|
|
1830
1910
|
/** The body of `oats sync` — shared by `sync` and `onboard` (which onboards, then syncs the same
|
|
1831
1911
|
* way). Given a v2 deployment context: discover over the remotes, confirm membership, resolve
|
|
@@ -2015,31 +2095,11 @@ function setDisabledHereCli(ws, kind, qid, enabled) {
|
|
|
2015
2095
|
return A.setDisabledHere({ deployment: dirname(path), localPath: path }, kind, qid, !enabled);
|
|
2016
2096
|
}
|
|
2017
2097
|
|
|
2018
|
-
const SYNC_USAGE = "usage: oats sync [--dir <deployment>] [--plan] [--json]";
|
|
2019
|
-
/** Why `oats sync`'s argv is not a sync, or undefined (#731): an unknown flag or a positional is refused
|
|
2020
|
-
* before anything is read or written, never ignored. `--approve` keeps its own refusal (performSync). */
|
|
2021
|
-
function syncArgvProblem(argv) {
|
|
2022
|
-
let dirs = 0;
|
|
2023
|
-
for (let i = 1; i < argv.length; i++) {
|
|
2024
|
-
const a = argv[i];
|
|
2025
|
-
if (a === "--json" || a === "--plan") continue;
|
|
2026
|
-
if (a === "--dir") {
|
|
2027
|
-
if (dirs++) return { message: `oats sync: give --dir once\n${SYNC_USAGE}`, details: { flag: a } };
|
|
2028
|
-
if (argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) i++;
|
|
2029
|
-
continue;
|
|
2030
|
-
}
|
|
2031
|
-
if (a === "--approve") return { message: `--approve: ${APPROVAL_REMOVED}`, details: { flag: a } };
|
|
2032
|
-
if (a.startsWith("-")) return { message: `oats sync: unknown flag ${a}\n${SYNC_USAGE}`, details: { flag: a } };
|
|
2033
|
-
return { message: `oats sync: unexpected argument ${JSON.stringify(a)}: sync takes no positional (the deployment is --dir <deployment>)\n${SYNC_USAGE}`, details: { argument: a } };
|
|
2034
|
-
}
|
|
2035
|
-
return undefined;
|
|
2036
|
-
}
|
|
2037
|
-
|
|
2038
2098
|
/** `oats sync [--dir] [--plan] [--json]` — contract §6. `--plan` previews: the same report, nothing written. */
|
|
2039
2099
|
async function syncCmd() {
|
|
2040
2100
|
const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
|
|
2041
|
-
|
|
2042
|
-
if (
|
|
2101
|
+
// A second --dir: flag() would read the first and drop it.
|
|
2102
|
+
if (args.filter((a) => a === "--dir").length > 1) return bail("E_BAD_ARGS", `oats sync: give --dir once\n${SYNC_USAGE}`, { flag: "--dir" });
|
|
2043
2103
|
const ctx = workspaceContext(bail);
|
|
2044
2104
|
const synced = await performSync(ctx, bail, { plan: args.includes("--plan") });
|
|
2045
2105
|
// One envelope (or the §8 report); success is exit 0 (a failure bails with its code).
|
|
@@ -2057,7 +2117,8 @@ function workspaceCheckoutFrom(dir) {
|
|
|
2057
2117
|
let inCheckout = false;
|
|
2058
2118
|
for (let d = current; ; d = dirname(d)) { if (existsSync(join(d, ".git"))) { inCheckout = true; break; } if (dirname(d) === d) break; }
|
|
2059
2119
|
if (!inCheckout) return null;
|
|
2060
|
-
|
|
2120
|
+
// Git reads the checkout's index for this: it does not run the file monitor the checkout's configuration names.
|
|
2121
|
+
const tracked = spawnSync("git", [...NO_FILE_MONITOR, "-C", current, "ls-files", "--error-unmatch", "--", "oats-workspace.yaml"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 10000 });
|
|
2061
2122
|
return tracked.status === 0 ? { file: candidate, root: current } : null;
|
|
2062
2123
|
}
|
|
2063
2124
|
const parent = dirname(current);
|
|
@@ -2177,41 +2238,15 @@ async function teamsContext(bail) {
|
|
|
2177
2238
|
}
|
|
2178
2239
|
const positional = (i) => (args[i] !== undefined && !args[i].startsWith("--") ? args[i] : undefined);
|
|
2179
2240
|
|
|
2180
|
-
/** The flags each `oats teams` form takes (value flags → true), beyond the global `--dir` and `--json`.
|
|
2181
|
-
* Anything else is refused, never ignored: a kernel that ignored `--if-absent` would set unconditionally. */
|
|
2182
|
-
const TEAMS_FLAGS = {
|
|
2183
|
-
"": { "--max-age": true },
|
|
2184
|
-
add: { "--team": true, "--description": true, "--no-default": false },
|
|
2185
|
-
remove: {},
|
|
2186
|
-
default: { "--if-absent": false, "--expect": true },
|
|
2187
|
-
};
|
|
2188
|
-
/** The first flag `oats teams <sub>` does not take, or undefined. A value flag's value is skipped as flag()
|
|
2189
|
-
* reads it (the next word unless it starts with `--`). */
|
|
2190
|
-
function teamsUnknownFlag(sub) {
|
|
2191
|
-
const takes = { "--dir": true, "--json": false, ...TEAMS_FLAGS[sub ?? ""] };
|
|
2192
|
-
for (let i = 1; i < args.length; i++) {
|
|
2193
|
-
const a = args[i];
|
|
2194
|
-
if (!a.startsWith("-")) continue;
|
|
2195
|
-
if (!Object.hasOwn(takes, a)) return a;
|
|
2196
|
-
if (takes[a] && args[i + 1] !== undefined && !args[i + 1].startsWith("--")) i++;
|
|
2197
|
-
}
|
|
2198
|
-
return undefined;
|
|
2199
|
-
}
|
|
2200
|
-
|
|
2201
2241
|
/** `oats teams [--json] | add <label> --team <id> [--description <d>] [--no-default] | remove <label> |
|
|
2202
2242
|
* default <label> [--if-absent | --expect <label>]` — this deployment's teams (team model 3). Config only:
|
|
2203
2243
|
* never a provider call. */
|
|
2204
2244
|
async function teamsCmd() {
|
|
2205
2245
|
const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
|
|
2206
|
-
const usage =
|
|
2207
|
-
//
|
|
2208
|
-
|
|
2209
|
-
|
|
2210
|
-
const unknown = teamsUnknownFlag(sub);
|
|
2211
|
-
if (unknown !== undefined) {
|
|
2212
|
-
const form = sub ? `oats teams ${sub}` : "oats teams";
|
|
2213
|
-
bail("E_USAGE", `${form} does not take ${unknown} (an option this kernel does not know may need a newer kernel; nothing was changed) — ${usage}`, { flag: unknown });
|
|
2214
|
-
}
|
|
2246
|
+
const usage = TEAMS_USAGE;
|
|
2247
|
+
// The form and its flags were checked by the dispatch (lib/command-flags.mjs): a word where the form
|
|
2248
|
+
// belongs, and a flag the form does not take, are E_USAGE there.
|
|
2249
|
+
const sub = positional(1);
|
|
2215
2250
|
const label = sub ? positional(2) : undefined;
|
|
2216
2251
|
if (sub && label === undefined) bail("E_BAD_ARGS", `oats teams ${sub} needs a team label — ${usage}`);
|
|
2217
2252
|
const ctx = await teamsContext(bail);
|
|
@@ -2276,13 +2311,6 @@ async function soulCmd() {
|
|
|
2276
2311
|
if (doc.teams.length) printTable(["team", "id", "from", "why"], doc.teams.map((t) => [t.default ? `${t.label} (default)` : t.label, t.team ?? "(no id yet)", t.from, t.via.join(",")]));
|
|
2277
2312
|
}
|
|
2278
2313
|
|
|
2279
|
-
const SOUL_LAUNCH_USAGE = "oats soul launch set <soul>|'*' (--launch-config <name>|none | --harness pi|claude|codex [--model <id>]) [--plan] [--dir <deployment>] [--json] | oats soul launch remove <soul>|'*'|<exact key> [--plan] [--dir <deployment>] [--json]";
|
|
2280
|
-
/** The flags each `oats soul launch` form takes (value flags → true). Anything else is refused, never
|
|
2281
|
-
* ignored: `--home` and `--soul` among them, since the soul is the argument and the file the deployment's. */
|
|
2282
|
-
const SOUL_LAUNCH_FLAGS = {
|
|
2283
|
-
set: { "--launch-config": true, "--harness": true, "--model": true },
|
|
2284
|
-
remove: {},
|
|
2285
|
-
};
|
|
2286
2314
|
/** A souls.launch entry in words: a launch configuration's name, or the inline harness and model. */
|
|
2287
2315
|
const launchEntryText = (v) => (v === null ? "no entry" : typeof v === "string" ? (v === "none" ? "none (the bare harness)" : `launch configuration ${v}`) : `${v.harness}${v.model ? ` with model ${v.model}` : ""}`);
|
|
2288
2316
|
|
|
@@ -2292,23 +2320,22 @@ const launchEntryText = (v) => (v === null ? "no entry" : typeof v === "string"
|
|
|
2292
2320
|
async function soulLaunchCmd(bail, usage) {
|
|
2293
2321
|
const sub = positional(2);
|
|
2294
2322
|
if (!["set", "remove"].includes(sub)) bail("E_USAGE", usage);
|
|
2295
|
-
// Every argument is accounted for before anything is read or written
|
|
2296
|
-
//
|
|
2297
|
-
//
|
|
2298
|
-
|
|
2323
|
+
// Every argument is accounted for before anything is read or written. The dispatch refused a flag the
|
|
2324
|
+
// form does not take and a second name (lib/command-flags.mjs); here a value flag with no value at ANY
|
|
2325
|
+
// of its occurrences (`--harness codex --harness`) and a value flag given twice (flag() would read the
|
|
2326
|
+
// first and drop the second) are refused, never ignored. Its value flags are the declaration's.
|
|
2327
|
+
const { values } = commandFlags(args);
|
|
2299
2328
|
const names = [], given = new Set();
|
|
2300
2329
|
for (let i = 3; i < args.length; i++) {
|
|
2301
2330
|
const a = args[i];
|
|
2302
2331
|
if (!a.startsWith("-")) { names.push(a); continue; }
|
|
2303
|
-
if (!
|
|
2304
|
-
if (!takes[a]) continue;
|
|
2332
|
+
if (!values.includes(a)) continue;
|
|
2305
2333
|
if (args[i + 1] === undefined || args[i + 1].startsWith("--")) bail("E_BAD_ARGS", `${a} needs a value`);
|
|
2306
2334
|
if (given.has(a)) bail("E_BAD_ARGS", `oats soul launch ${sub} takes ${a} once (nothing was changed)`);
|
|
2307
2335
|
given.add(a);
|
|
2308
2336
|
i++;
|
|
2309
2337
|
}
|
|
2310
2338
|
if (names.length === 0) bail("E_BAD_ARGS", `oats soul launch ${sub} needs ${sub === "set" ? "a soul (or '*')" : "a soul, '*' or the exact text of a key in souls.launch"} — usage: ${SOUL_LAUNCH_USAGE}`);
|
|
2311
|
-
if (names.length > 1) bail("E_BAD_ARGS", `oats soul launch ${sub} takes one ${sub === "set" ? "soul" : "soul or key"}, and got ${names.length}: ${names.map((n) => JSON.stringify(n)).join(", ")} (nothing was changed) — usage: ${SOUL_LAUNCH_USAGE}`);
|
|
2312
2339
|
const name = names[0];
|
|
2313
2340
|
const V = await import("../lib/soul-launch-verbs.mjs");
|
|
2314
2341
|
let value = null;
|
|
@@ -2618,12 +2645,6 @@ function printStatus({ root, agents: data, ws, problems }, verbose) {
|
|
|
2618
2645
|
}
|
|
2619
2646
|
}
|
|
2620
2647
|
|
|
2621
|
-
/** The flags `oats spawn` reads: those taking a value, and switches. `--provider` takes two words.
|
|
2622
|
-
* `--instance` is refused by a local spawn (with its replacement) but still travels to an older
|
|
2623
|
-
* host through `--server`, whose route reads it. `--max-age` reaches here only on a preview or an
|
|
2624
|
-
* apply bound by --expect-decision: the dispatch allow-list (maxAgeRefusal) refuses it otherwise. */
|
|
2625
|
-
const SPAWN_VALUE_FLAGS = new Set(["agents-root", "backend", "base", "branch", "dir", "expect-decision", "harness", "idempotency-key", "instance", "launch-config", "max-age", "model", "name", "parent", "purpose", "relation", "relative-root", "relative-to", "repo", "runtime", "task", "task-file", "trigger-event", "wake-cron", "wake-every", "wake-file", "wake-json", "wake-message", "wake-message-file", "wake-tz", "work", "work-dir"]);
|
|
2626
|
-
const SPAWN_SWITCHES = new Set(["allow-child-spawns", "background", "json", "no-background", "no-child-spawns", "no-launch", "no-yolo", "preview", "same-work", "suggest-name", "yolo"]);
|
|
2627
2648
|
/** `--suggest-name` (features spawn-suggest-name, spawn-apply-suggest-name): a preview's or an apply's,
|
|
2628
2649
|
* with no --name, --purpose or --expect-decision. The kernel refuses the same (core.mjs spawnBody); the
|
|
2629
2650
|
* CLI says it before anything is read or sent. */
|
|
@@ -2636,26 +2657,6 @@ function suggestNameProblem(argv) {
|
|
|
2636
2657
|
}
|
|
2637
2658
|
/** `--background` / `--no-background` (feature instance-background): one of them, or neither. */
|
|
2638
2659
|
const backgroundProblem = (argv) => (argv.includes("--background") && argv.includes("--no-background") ? "choose --background or --no-background, not both" : undefined);
|
|
2639
|
-
/** Why `argv` (after `spawn`, the soul first) is not a spawn, or undefined: a positional after the
|
|
2640
|
-
* soul or a flag spawn does not read is never ignored. A value flag consumes its value exactly as
|
|
2641
|
-
* flag() reads it; a missing value is the flag's own check. */
|
|
2642
|
-
function spawnArgvProblem(argv) {
|
|
2643
|
-
const soul = argv[0];
|
|
2644
|
-
for (let i = 1; i < argv.length; i++) {
|
|
2645
|
-
const a = argv[i];
|
|
2646
|
-
if (a === "--provider") { i += 2; continue; }
|
|
2647
|
-
if (a.startsWith("--")) {
|
|
2648
|
-
const name = a.slice(2);
|
|
2649
|
-
if (SPAWN_SWITCHES.has(name)) continue;
|
|
2650
|
-
if (!SPAWN_VALUE_FLAGS.has(name)) return `oats spawn: unknown flag ${a}`;
|
|
2651
|
-
if (argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) i++;
|
|
2652
|
-
continue;
|
|
2653
|
-
}
|
|
2654
|
-
if (/^[A-Za-z0-9_.-]+=/.test(a)) return `oats spawn: unexpected argument ${JSON.stringify(a)} after the soul ${JSON.stringify(soul)}: a capability setting is given as --provider <capability> key=value (here: --provider <capability> ${a})`;
|
|
2655
|
-
return `oats spawn: unexpected argument ${JSON.stringify(a)} after the soul ${JSON.stringify(soul)}: spawn takes one soul`;
|
|
2656
|
-
}
|
|
2657
|
-
return undefined;
|
|
2658
|
-
}
|
|
2659
2660
|
/** The Herdr spawn flags (removed in 0.31.0), named for the refusal; undefined when none is given. */
|
|
2660
2661
|
function herdrSpawnFlag() {
|
|
2661
2662
|
if (flag("backend") === "herdr") return "--backend herdr";
|
|
@@ -2682,6 +2683,8 @@ function printSpawnPreview(r, { server, soulFetched = false } = {}) {
|
|
|
2682
2683
|
for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
|
|
2683
2684
|
}
|
|
2684
2685
|
async function spawnCmd() {
|
|
2686
|
+
// The spawn does not need its caller to finish: see outliveReader.
|
|
2687
|
+
outliveReader();
|
|
2685
2688
|
// JSON mode: contract envelope, stable error codes, stderr-only progress.
|
|
2686
2689
|
const bail = (code, msg, details, exit) => (JSON_MODE ? jsonFail(code, msg, details, exit) : die(msg, exit));
|
|
2687
2690
|
const note = (msg) => (JSON_MODE ? console.error(msg) : console.log(msg));
|
|
@@ -2696,12 +2699,9 @@ async function spawnCmd() {
|
|
|
2696
2699
|
};
|
|
2697
2700
|
checkDirectoryOptions(requestedWork); // before anything is resolved or written
|
|
2698
2701
|
const name = args[1];
|
|
2699
|
-
if (!name || name.startsWith("--")) bail("E_USAGE",
|
|
2702
|
+
if (!name || name.startsWith("--")) bail("E_USAGE", SPAWN_USAGE);
|
|
2700
2703
|
// Retired boundary flags (maintainer transport ruling): fail LOUDLY before
|
|
2701
2704
|
// ANY side effect, including root discovery.
|
|
2702
|
-
// Local souls (local-agents/) are gone with the workspace model: a soul is a member
|
|
2703
|
-
// repository's souls/<name>, so spawn never writes one.
|
|
2704
|
-
for (const removed of ["instructions-file", "def-file"]) if (flag(removed) !== undefined) bail("E_BAD_ARGS", `--${removed} created a local soul under local-agents/, which the workspace model removed — author souls/<name>/soul.yaml + AGENTS.md in a member repository, then \`oats sync\``);
|
|
2705
2705
|
if (args.includes("--instance")) bail("E_BAD_ARGS", "--instance was removed by the runtime-boundary ruling — use --purpose <slug> (deterministic <agent>-<purpose> naming) or --name <slug> (the exact instance name)");
|
|
2706
2706
|
// --name <slug>: the exact, unprefixed instance name (human decision 2026-09-24).
|
|
2707
2707
|
const nameFlag = flag("name");
|
|
@@ -2710,8 +2710,6 @@ async function spawnCmd() {
|
|
|
2710
2710
|
{ const problem = suggestNameProblem(args) ?? backgroundProblem(args); if (problem) bail("E_BAD_ARGS", problem); }
|
|
2711
2711
|
// The slug rule is checked here too, before any side effect (soul fetch).
|
|
2712
2712
|
if (nameFlag !== undefined) { try { explicitInstanceName(String(nameFlag)); } catch (e) { bail(e.code, e.message); throw e; } }
|
|
2713
|
-
if (args.includes("--ephemeral")) bail("E_BAD_ARGS", "--ephemeral was removed by the runtime-boundary ruling — declare the agent in a capability manifest (agents:) for automatic ephemeral semantics");
|
|
2714
|
-
{ const problem = spawnArgvProblem(args.slice(1)); if (problem) bail("E_BAD_ARGS", problem); }
|
|
2715
2713
|
let root;
|
|
2716
2714
|
// A spawn needs a workspace deployment (lead decision c3-1): no oats-local.yaml
|
|
2717
2715
|
// in reach is E_LOCAL_MISSING, before anything else is read. The agents root is
|
|
@@ -2743,11 +2741,14 @@ async function spawnCmd() {
|
|
|
2743
2741
|
{
|
|
2744
2742
|
let discovery = null;
|
|
2745
2743
|
try {
|
|
2746
|
-
const { prepareInstance, ensureWorkspaceSoul, previewWorkspaceSoul, parseProviderFlags, discoverOrStandalone, agentDirOf } = await import("../lib/instance-resolution.mjs");
|
|
2744
|
+
const { prepareInstance, verifyPreparedPackages, ensureWorkspaceSoul, previewWorkspaceSoul, parseProviderFlags, discoverOrStandalone, agentDirOf } = await import("../lib/instance-resolution.mjs");
|
|
2747
2745
|
const remoteOptions = remoteOptionsFromEnv();
|
|
2748
2746
|
const { local, path: localPath } = loadLocal(dirFlag());
|
|
2749
2747
|
discovery = wsDiscovery = await discoverOrStandalone(local, { deployment: dirname(localPath), remoteOptions });
|
|
2750
2748
|
wsPrepared = await prepareInstance(dirFlag(), name, { spawn: { providers: parseProviderFlags(providerPairs) }, remoteOptions, discovery });
|
|
2749
|
+
// Each package the soul composes is the content the lock records (E_PACKAGE_INTEGRITY), before the
|
|
2750
|
+
// first write of the spawn: the soul cache below is the first thing a spawn creates under the agents root.
|
|
2751
|
+
await verifyPreparedPackages(wsPrepared);
|
|
2751
2752
|
const soulName = agentDirOf(wsPrepared.soulEntry);
|
|
2752
2753
|
let soulDir;
|
|
2753
2754
|
if (isPreview) {
|
|
@@ -2813,7 +2814,13 @@ async function spawnCmd() {
|
|
|
2813
2814
|
if (taskText === true) bail("E_BAD_ARGS", "--task needs a value (use --task-file for long tasks)");
|
|
2814
2815
|
const taskFileFlag = flag("task-file");
|
|
2815
2816
|
if (taskFileFlag === true) bail("E_BAD_ARGS", "--task-file needs a path");
|
|
2816
|
-
|
|
2817
|
+
// `--task-file -` (feature spawn-task-stdin): the task's bytes arrive on stdin, which is how a
|
|
2818
|
+
// routed spawn sends them (lib/servers.mjs routeCommand), so that they are on no command line.
|
|
2819
|
+
let stdinTask;
|
|
2820
|
+
if (taskFileFlag === "-") {
|
|
2821
|
+
if (process.stdin.isTTY) bail("E_BAD_ARGS", "--task-file - reads the task from stdin");
|
|
2822
|
+
try { stdinTask = (await readStreamBounded(process.stdin, MAX_ATTACHMENT_BYTES)).toString("utf8"); } catch (e) { bail("E_BAD_ARGS", `--task-file -: the task could not be read from stdin (${e.message})`); }
|
|
2823
|
+
} else if (taskFileFlag && !existsSync(taskFileFlag)) bail("E_BAD_ARGS", `--task-file not found: ${taskFileFlag}`);
|
|
2817
2824
|
// --trigger-event <file>: the event a trigger spawns this instance for (lib/triggers.mjs). It is
|
|
2818
2825
|
// copied to <home>/.oats/trigger-event.json (OATS_TRIGGER_EVENT_FILE) and recorded as instance.json.trigger.
|
|
2819
2826
|
let triggerEvent;
|
|
@@ -2888,7 +2895,7 @@ async function spawnCmd() {
|
|
|
2888
2895
|
if (flag("base") === true) bail("E_BAD_ARGS", "--base needs a ref");
|
|
2889
2896
|
{ const spawnOpts = {
|
|
2890
2897
|
prepared,
|
|
2891
|
-
purpose: flag("purpose"), ...(nameFlag !== undefined ? { name: String(nameFlag) } : {}), task: taskText, taskFile: taskFileFlag, relation, relativeTo, relativeRoot,
|
|
2898
|
+
purpose: flag("purpose"), ...(nameFlag !== undefined ? { name: String(nameFlag) } : {}), task: taskText ?? stdinTask, taskFile: stdinTask === undefined ? taskFileFlag : undefined, relation, relativeTo, relativeRoot,
|
|
2892
2899
|
...(args.includes("--allow-child-spawns") ? { allowChildSpawns: true } : args.includes("--no-child-spawns") ? { allowChildSpawns: false } : {}),
|
|
2893
2900
|
// Feature instance-same-work: the kernel binds it to the parent the new home records, or refuses.
|
|
2894
2901
|
...(args.includes("--same-work") ? { sameWork: true } : {}),
|
|
@@ -2997,9 +3004,7 @@ function failedSpawnBranchLine(r, items, { local = false, host } = {}) {
|
|
|
2997
3004
|
let retireReturned = false;
|
|
2998
3005
|
function retireCmd() {
|
|
2999
3006
|
const name = args[1];
|
|
3000
|
-
|
|
3001
|
-
if (args.includes("--delete-branch")) return args.includes("--json") ? jsonFail("E_BAD_ARGS", RETIRE_DELETE_BRANCH_REFUSED) : die(RETIRE_DELETE_BRANCH_REFUSED);
|
|
3002
|
-
if (!name || name.startsWith("--")) die("usage: oats retire <instance> [--plan] [--plan-revision <rev> --idempotency-key <key>] [--home <path>] [--self] [--discard-worktree] [--keep-dir] [--force] [--json]");
|
|
3007
|
+
if (!name || name.startsWith("--")) return cmdFail("E_USAGE", RETIRE_USAGE);
|
|
3003
3008
|
let homeFlag = flag("home");
|
|
3004
3009
|
if (homeFlag === true) die("--home needs the instance home path");
|
|
3005
3010
|
if (args.includes("--plan")) {
|
|
@@ -3022,6 +3027,7 @@ function retireCmd() {
|
|
|
3022
3027
|
const isSelf = process.env.OATS_INSTANCE === name;
|
|
3023
3028
|
if (isSelf && !args.includes("--self")) die(`"${name}" is the calling instance — self-retire is irreversible; if your task is complete and you were told to retire, re-run with --self (finish your memory files FIRST; your session dies ~8s after)`);
|
|
3024
3029
|
if (!isSelf && args.includes("--self")) die(`--self given but "${name}" is not the calling instance`);
|
|
3030
|
+
outliveReader();
|
|
3025
3031
|
const root = ensureRoot(dirFlag());
|
|
3026
3032
|
// K3: a GUI-driven Remove carries the plan revision it showed and an
|
|
3027
3033
|
// idempotency key. The revision is revalidated against a fresh plan
|
|
@@ -3214,6 +3220,8 @@ async function scheduleCmd() {
|
|
|
3214
3220
|
const op = args[2];
|
|
3215
3221
|
const os = flag("os");
|
|
3216
3222
|
if (os !== undefined && !(op === "install" && args.includes("--print"))) throw scheduleError("E_BAD_ARGS", "--os is for oats schedule host install --print");
|
|
3223
|
+
const registerOnly = op === "install" && args.includes("--register-only");
|
|
3224
|
+
if (registerOnly && args.includes("--print")) throw scheduleError("E_BAD_ARGS", "--register-only records the scope and --print writes nothing: give one");
|
|
3217
3225
|
if (op === "install" && args.includes("--print")) {
|
|
3218
3226
|
// What install would write, rendered from this environment; nothing is written or loaded.
|
|
3219
3227
|
if (os !== undefined && os !== "darwin" && os !== "linux") throw scheduleError("E_BAD_ARGS", "--os darwin|linux");
|
|
@@ -3235,14 +3243,17 @@ async function scheduleCmd() {
|
|
|
3235
3243
|
};
|
|
3236
3244
|
const caps = { maxConcurrent: cap("max-concurrent", "default"), triggersMaxConcurrent: cap("triggers-max-concurrent", "none") };
|
|
3237
3245
|
registerWorkspace(ws(), caps);
|
|
3246
|
+
// --register-only: the scope is in the host registry and no unit is installed, for a host
|
|
3247
|
+
// whose ticker is `oats host run` (a container has neither launchd nor a systemd user manager).
|
|
3248
|
+
if (registerOnly) return out({ scheduler: schedulerStatus(ws(), io), warnings: [] });
|
|
3238
3249
|
const { warnings } = installHostUnit();
|
|
3239
3250
|
return out({ scheduler: schedulerStatus(ws(), io), warnings });
|
|
3240
3251
|
}
|
|
3241
3252
|
if (op === "uninstall") { unregisterWorkspace(ws()); if (!readRegistry().workspaces.length) uninstallHostUnit(); return out({ scheduler: schedulerStatus(ws(), io) }); }
|
|
3242
3253
|
if (op === "status") return out({ scheduler: schedulerStatus(ws(), io) });
|
|
3243
|
-
throw scheduleError("E_BAD_ARGS", "oats schedule host install [--print [--os darwin|linux]]|uninstall|status");
|
|
3254
|
+
throw scheduleError("E_BAD_ARGS", "oats schedule host install [--register-only | --print [--os darwin|linux]]|uninstall|status");
|
|
3244
3255
|
}
|
|
3245
|
-
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]");
|
|
3256
|
+
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 [--register-only] [--max-concurrent <N|default>] [--triggers-max-concurrent <N|none>] | host install --print [--os darwin|linux]|uninstall|status [--dir <workspace>|--server <id>] [--json]");
|
|
3246
3257
|
}
|
|
3247
3258
|
} catch (e) {
|
|
3248
3259
|
// K8b: typed refusal details travel (identity mismatch: key/declared; a refused file: its integrity source).
|
|
@@ -3251,6 +3262,31 @@ async function scheduleCmd() {
|
|
|
3251
3262
|
}
|
|
3252
3263
|
}
|
|
3253
3264
|
|
|
3265
|
+
/** `oats host run` (lib/host-run.mjs): the resume sweep once, the schedule tick each minute and an
|
|
3266
|
+
* ordered stop of the agents when the host stops, in the foreground. Progress goes to stderr; the
|
|
3267
|
+
* one answer is written when the run ends. */
|
|
3268
|
+
async function hostCmd() {
|
|
3269
|
+
try {
|
|
3270
|
+
const bad = (message) => Object.assign(new Error(message), { code: "E_BAD_ARGS" });
|
|
3271
|
+
if (args[1] !== "run") throw bad(HOST_RUN_USAGE);
|
|
3272
|
+
const grace = flag("stop-grace");
|
|
3273
|
+
if (grace !== undefined && (grace === true || !/^\d+$/.test(String(grace)) || Number(grace) < 1 || Number(grace) > 300)) throw bad("--stop-grace needs a number of seconds (1..300) to wait for each harness after SIGTERM");
|
|
3274
|
+
const { hostRun, hostRunPlan, NO_SCOPE_SAID } = await import("../lib/host-run.mjs");
|
|
3275
|
+
if (args.includes("--plan")) {
|
|
3276
|
+
const plan = await hostRunPlan();
|
|
3277
|
+
if (JSON_MODE) return jsonOk(plan);
|
|
3278
|
+
for (const r of plan.refusals) console.log(`would refuse (${r.code}): ${terminalText(r.message)}`);
|
|
3279
|
+
for (const w of plan.warnings) console.log(`warning: ${terminalText(w)}`);
|
|
3280
|
+
console.log(plan.scopes.length ? `would tick ${plan.scopes.length} scope${plan.scopes.length === 1 ? "" : "s"} each minute: ${plan.scopes.join(", ")}` : NO_SCOPE_SAID);
|
|
3281
|
+
for (const r of plan.sweep.rows) console.log(` ${r.instance} would be ${r.outcome}${r.reason ? ` (${r.reason}${r.code ? `, ${r.code}` : ""})` : ""}${r.message ? `: ${terminalText(r.message)}` : ""}`);
|
|
3282
|
+
if (!plan.sweep.rows.length) console.log("the sweep would find nothing to resume");
|
|
3283
|
+
return;
|
|
3284
|
+
}
|
|
3285
|
+
const answer = await hostRun({ kernel: { execPath: process.execPath, bin: CLI_BIN }, ...(grace !== undefined ? { stopGraceMs: Number(grace) * 1000 } : {}) });
|
|
3286
|
+
if (JSON_MODE) jsonOk(answer);
|
|
3287
|
+
} catch (e) { lifecycleFail(e, "E_HOST_RUN_FAILED", e?.details); }
|
|
3288
|
+
}
|
|
3289
|
+
|
|
3254
3290
|
/** `oats trigger …` (lib/triggers.mjs): event-driven spawns stored beside the schedules of the
|
|
3255
3291
|
* deployment scope and evaluated by the same host tick. Every subcommand answers the envelope. */
|
|
3256
3292
|
async function triggerCmd() {
|
|
@@ -3415,7 +3451,7 @@ async function triggerFromPackage(T, from, sets, idFlag) {
|
|
|
3415
3451
|
|
|
3416
3452
|
async function sessionCmd() {
|
|
3417
3453
|
try {
|
|
3418
|
-
if (flag("native-record") !== undefined) throw Object.assign(new Error(
|
|
3454
|
+
if (flag("native-record") !== undefined) throw Object.assign(new Error(NATIVE_RECORD_REFUSED), { code: "E_BAD_ARGS" });
|
|
3419
3455
|
const home = flag("home");
|
|
3420
3456
|
let result;
|
|
3421
3457
|
if (args[1] === "attach") {
|
|
@@ -3437,13 +3473,7 @@ async function sessionCmd() {
|
|
|
3437
3473
|
if (args[1] === "resume") {
|
|
3438
3474
|
// The machine sweep (feature session-resume, #1559): lib/session-resume.mjs. No --home: one home
|
|
3439
3475
|
// is `session start --resume`.
|
|
3440
|
-
const usage =
|
|
3441
|
-
for (let i = 2; i < args.length; i++) {
|
|
3442
|
-
const a = args[i];
|
|
3443
|
-
if (a === "--deployment") { i++; continue; }
|
|
3444
|
-
if (a.startsWith("--deployment=") || a === "--plan" || a === "--json") continue;
|
|
3445
|
-
throw Object.assign(new Error(a.startsWith("-") ? `oats session resume: unknown flag ${a}\n${usage}` : `oats session resume takes no argument ${JSON.stringify(a)}\n${usage}`), { code: "E_BAD_ARGS" });
|
|
3446
|
-
}
|
|
3476
|
+
const usage = commandFlags(args).usage;
|
|
3447
3477
|
const deployment = flag("deployment");
|
|
3448
3478
|
if (deployment === true || (typeof deployment === "string" && !deployment.trim())) throw Object.assign(new Error(`--deployment needs a deployment directory\n${usage}`), { code: "E_BAD_ARGS" });
|
|
3449
3479
|
const { resumeSessions } = await import("../lib/session-resume.mjs");
|
|
@@ -3457,6 +3487,7 @@ async function sessionCmd() {
|
|
|
3457
3487
|
if (args[1] === "inspect") result = inspectInstanceSession(home);
|
|
3458
3488
|
else if (args[1] === "recompose") throw Object.assign(new Error('unknown command "session recompose" — removed by the workspace model v2; use a re-spawn: an instance never changes under itself'), { code: "E_UNKNOWN_COMMAND" });
|
|
3459
3489
|
else if (args[1] === "start" || args[1] === "restart") {
|
|
3490
|
+
outliveReader();
|
|
3460
3491
|
const bad = (msg) => { throw Object.assign(new Error(msg), { code: "E_BAD_ARGS" }); };
|
|
3461
3492
|
const model = flag("model");
|
|
3462
3493
|
if (model === true) bad("--model needs a model id; omit it to keep the recorded model");
|
|
@@ -3472,7 +3503,6 @@ async function sessionCmd() {
|
|
|
3472
3503
|
// refused with a launch choice before anything of the home is read.
|
|
3473
3504
|
const resume = args.includes("--resume");
|
|
3474
3505
|
if (resume) {
|
|
3475
|
-
if (args[1] === "restart") bad("--resume exists on session start only: it brings back a session that was lost");
|
|
3476
3506
|
const chosen = ["--launch-config", "--harness", "--model", "--yolo", "--no-yolo", "--reselect-launch"].filter((f) => args.some((a) => a === f || a.startsWith(`${f}=`)));
|
|
3477
3507
|
if (chosen.length) bad(`--resume runs the launch this home recorded; it cannot be combined with ${chosen.join(", ")}; nothing was read or started`);
|
|
3478
3508
|
}
|
|
@@ -4224,7 +4254,7 @@ async function experimentalCmd() {
|
|
|
4224
4254
|
async function serverCmd() {
|
|
4225
4255
|
const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
|
|
4226
4256
|
const sub = args[1];
|
|
4227
|
-
const usage = "usage: oats server add <id> --ssh <host-alias> --workspace </abs/path> [--oats <path>] [--path <dir:dir>] [--label <text>] [--replace] | connect <id> --ssh <host-alias> [--workspace-ref <ref>] [--dir </abs/path or ~/path on the host>] [--oats <path>] [--path <dir:dir>] [--label <text>] [--install-oats] [--replace] | list [--workspace-ref <ref>] | remove <id> | check <id> | roster [--server <id>] [--workspace-key <key>]... | forget <id> --instance <name> [--json]";
|
|
4257
|
+
const usage = "usage: oats server add <id> --ssh <host-alias> [--operator-ssh <alias> | --no-operator-ssh] --workspace </abs/path> [--oats <path>] [--path <dir:dir>] [--label <text>] [--replace] | connect <id> --ssh <host-alias> [--operator-ssh <alias> | --no-operator-ssh] [--workspace-ref <ref>] [--dir </abs/path or ~/path on the host>] [--oats <path>] [--path <dir:dir>] [--label <text>] [--install-oats] [--replace] | list [--workspace-ref <ref>] | remove <id> | check <id> | roster [--server <id>] [--workspace-key <key>]... | forget <id> --instance <name> [--json]";
|
|
4228
4258
|
if (!["add", "connect", "list", "remove", "check", "roster", "forget"].includes(sub)) bail("E_USAGE", usage);
|
|
4229
4259
|
if (sub === "connect") return serverConnectCmd(bail);
|
|
4230
4260
|
if (sub === "forget") {
|
|
@@ -4274,7 +4304,9 @@ async function serverCmd() {
|
|
|
4274
4304
|
let servers;
|
|
4275
4305
|
try { servers = readServers(); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
|
|
4276
4306
|
if (sub === "list") {
|
|
4277
|
-
let
|
|
4307
|
+
let routes;
|
|
4308
|
+
try { routes = readServerOperatorRoutes(); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
|
|
4309
|
+
let rows = Object.entries(servers).map(([id, s]) => ({ id, ...s, ...(Object.hasOwn(routes, id) ? routes[id] : {}), workspaceKey: s.workspaceKey ?? null, target: targetOf({ id, ...s }), snapshots: listSnapshots(id).length }));
|
|
4278
4310
|
// --workspace-ref: the servers of one workspace, by canonical key, and the ids whose workspace is not known yet.
|
|
4279
4311
|
let unknownWorkspace;
|
|
4280
4312
|
if (flag("workspace-ref") !== undefined) {
|
|
@@ -4288,7 +4320,7 @@ async function serverCmd() {
|
|
|
4288
4320
|
if (JSON_MODE) { jsonOk({ file: SERVERS_FILE(), servers: rows, ...(unknownWorkspace ? { unknownWorkspace } : {}) }); return; }
|
|
4289
4321
|
if (unknownWorkspace?.length) console.log(` (workspace not known yet for ${unknownWorkspace.join(", ")}: oats server check <id> learns it)`);
|
|
4290
4322
|
if (!rows.length) { console.log(`no servers registered (${shortPath(SERVERS_FILE())}) — add one with \`oats server add <id> --ssh <alias> --workspace </path>\``); return; }
|
|
4291
|
-
for (const r of rows) console.log(` ${r.id}${r.label ? ` ${r.label}` : ""}${r.workspaceKey ? ` [${r.workspaceKey}]` : ""}\n ssh ${r.sshHost} workspace ${r.workspace} oats ${r.target.oatsPath}${r.snapshots ? ` (${r.snapshots} remote instance${r.snapshots === 1 ? "" : "s"} spawned from here)` : ""}`);
|
|
4323
|
+
for (const r of rows) console.log(` ${r.id}${r.label ? ` ${r.label}` : ""}${r.workspaceKey ? ` [${r.workspaceKey}]` : ""}\n ssh ${r.sshHost}${r.operatorSshHost ? ` operator ssh ${r.operatorSshHost}` : ""} workspace ${r.workspace} oats ${r.target.oatsPath}${r.snapshots ? ` (${r.snapshots} remote instance${r.snapshots === 1 ? "" : "s"} spawned from here)` : ""}`);
|
|
4292
4324
|
return;
|
|
4293
4325
|
}
|
|
4294
4326
|
const id = args[2];
|
|
@@ -4299,12 +4331,23 @@ async function serverCmd() {
|
|
|
4299
4331
|
const entry = { sshHost: val("ssh"), workspace: val("workspace") };
|
|
4300
4332
|
for (const [k, f] of [["oatsPath", "oats"], ["path", "path"], ["label", "label"]]) { const v = val(f); if (v !== undefined) entry[k] = v; }
|
|
4301
4333
|
if (!entry.sshHost || !entry.workspace) bail("E_USAGE", usage);
|
|
4302
|
-
|
|
4334
|
+
const operatorSshHost = val("operator-ssh"), noOperatorSsh = args.includes("--no-operator-ssh");
|
|
4335
|
+
if (operatorSshHost !== undefined && noOperatorSsh) bail("E_BAD_ARGS", "choose --operator-ssh or --no-operator-ssh, not both");
|
|
4336
|
+
try { validateServer(id, entry); if (operatorSshHost !== undefined) validateOperatorSshHost(operatorSshHost); } catch (e) { bail(e.code, e.message); }
|
|
4337
|
+
let operatorRoute;
|
|
4303
4338
|
try {
|
|
4304
|
-
updateServers((current) => {
|
|
4305
|
-
|
|
4339
|
+
updateServers((current, routes) => {
|
|
4340
|
+
const existing = Object.hasOwn(current, id) ? current[id] : undefined;
|
|
4341
|
+
if (existing && !args.includes("--replace")) throw Object.assign(new Error(`server ${id} is already registered (pass --replace to overwrite; existing remote instances keep the route they were spawned with)`), { code: "E_SERVER_EXISTS" });
|
|
4342
|
+
// An older kernel can remove a registration while leaving its sidecar route behind.
|
|
4343
|
+
if (!existing) delete routes[id];
|
|
4344
|
+
// An unchanged agent target keeps its learned identity when only the operator route changes.
|
|
4345
|
+
if (existing?.workspaceKey && JSON.stringify(targetOf(existing)) === JSON.stringify(targetOf(entry))) entry.workspaceKey = existing.workspaceKey;
|
|
4306
4346
|
current[id] = entry;
|
|
4307
|
-
|
|
4347
|
+
if (operatorSshHost !== undefined) routes[id] = { operatorSshHost };
|
|
4348
|
+
else if (noOperatorSsh) delete routes[id];
|
|
4349
|
+
operatorRoute = Object.hasOwn(routes, id) ? routes[id] : undefined;
|
|
4350
|
+
}, { operatorRoutes: true });
|
|
4308
4351
|
} catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
|
|
4309
4352
|
// The workspace key is learned from the host, never typed: recorded when the host answers one and
|
|
4310
4353
|
// the registration is still this one (it may change while the host is asked).
|
|
@@ -4312,20 +4355,24 @@ async function serverCmd() {
|
|
|
4312
4355
|
try {
|
|
4313
4356
|
const { key, why } = reportedWorkspaceKey(targetOf(entry), { serverId: id, timeoutMs: 60000 });
|
|
4314
4357
|
if (!key) warnings.push(`workspace key unknown: ${why}; oats server check ${id} learns it once the host answers one`);
|
|
4315
|
-
else if (learnWorkspaceKey(id, entry, key
|
|
4316
|
-
else
|
|
4358
|
+
else if (["recorded", "same"].includes(learnWorkspaceKey(id, entry, key, { replace: args.includes("--replace") }))) entry.workspaceKey = key;
|
|
4359
|
+
else {
|
|
4360
|
+
delete entry.workspaceKey;
|
|
4361
|
+
warnings.push(`workspace key not recorded: registration ${id} changed while the host was asked; oats server check ${id} learns it`);
|
|
4362
|
+
}
|
|
4317
4363
|
} catch (e) { warnings.push(`workspace key unknown: ${e.message}; oats server check ${id} learns it once the host answers`); }
|
|
4318
|
-
if (JSON_MODE) { jsonOk({ id, ...entry, workspaceKey: entry.workspaceKey ?? null, file: SERVERS_FILE(), ...(warnings.length ? { warnings } : {}) }); return; }
|
|
4364
|
+
if (JSON_MODE) { jsonOk({ id, ...entry, ...operatorRoute, workspaceKey: entry.workspaceKey ?? null, file: SERVERS_FILE(), ...(warnings.length ? { warnings } : {}) }); return; }
|
|
4319
4365
|
console.log(`Registered server ${id} → ssh ${entry.sshHost}, workspace ${entry.workspace}${entry.workspaceKey ? ` (workspace ${entry.workspaceKey})` : ""} (${shortPath(SERVERS_FILE())}). Verify it with \`oats server check ${id}\`.`);
|
|
4320
4366
|
for (const w of warnings) console.error(`oats: warning: ${w}`);
|
|
4321
4367
|
return;
|
|
4322
4368
|
}
|
|
4323
4369
|
if (sub === "remove") {
|
|
4324
4370
|
try {
|
|
4325
|
-
updateServers((current) => {
|
|
4371
|
+
updateServers((current, routes) => {
|
|
4326
4372
|
if (!current[id]) throw Object.assign(new Error(`no server registered as ${id}`), { code: "E_SERVER_UNKNOWN" });
|
|
4327
4373
|
delete current[id];
|
|
4328
|
-
|
|
4374
|
+
delete routes[id];
|
|
4375
|
+
}, { operatorRoutes: true });
|
|
4329
4376
|
} catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
|
|
4330
4377
|
const snaps = listSnapshots(id);
|
|
4331
4378
|
if (JSON_MODE) { jsonOk({ removed: id, remoteInstancesStillTracked: snaps.map((s) => s.instance) }); return; }
|
|
@@ -4368,7 +4415,7 @@ async function serverCmd() {
|
|
|
4368
4415
|
* step b): only the person knows where it goes. */
|
|
4369
4416
|
function serverConnectCmd(bail) {
|
|
4370
4417
|
const id = args[2];
|
|
4371
|
-
if (!id || id.startsWith("--")) bail("E_USAGE", "usage: oats server connect <id> --ssh <host-alias> --dir </abs/path or ~/path on the host> [--workspace-ref <ref>] [--oats <path>] [--path <dir:dir>] [--label <text>] [--install-oats] [--replace] [--json]");
|
|
4418
|
+
if (!id || id.startsWith("--")) bail("E_USAGE", "usage: oats server connect <id> --ssh <host-alias> [--operator-ssh <alias> | --no-operator-ssh] --dir </abs/path or ~/path on the host> [--workspace-ref <ref>] [--oats <path>] [--path <dir:dir>] [--label <text>] [--install-oats] [--replace] [--json]");
|
|
4372
4419
|
const val = (name) => { const v = flag(name); return v === true ? bail("E_BAD_ARGS", `--${name} needs a value`) : v; };
|
|
4373
4420
|
const sshHost = val("ssh");
|
|
4374
4421
|
if (!sshHost) bail("E_BAD_ARGS", "--ssh <host-alias> is required: the OpenSSH host alias of the machine to connect");
|
|
@@ -4381,7 +4428,7 @@ function serverConnectCmd(bail) {
|
|
|
4381
4428
|
if (!dir) bail("E_BAD_ARGS", `--dir <path on the host> is required: the folder on ${sshHost} for this deployment (absolute, or ~/… resolved there)`);
|
|
4382
4429
|
let res;
|
|
4383
4430
|
try {
|
|
4384
|
-
res = connectServer({ id, sshHost, workspaceRef, dir, oatsPath: val("oats"), path: val("path"), label: val("label"), installOats: args.includes("--install-oats"), replace: args.includes("--replace"), localVersion: OATS_VERSION });
|
|
4431
|
+
res = connectServer({ id, sshHost, operatorSshHost: val("operator-ssh"), noOperatorSsh: args.includes("--no-operator-ssh"), workspaceRef, dir, oatsPath: val("oats"), path: val("path"), label: val("label"), installOats: args.includes("--install-oats"), replace: args.includes("--replace"), localVersion: OATS_VERSION });
|
|
4385
4432
|
} catch (e) {
|
|
4386
4433
|
if (!JSON_MODE && e.details?.steps) printConnectSteps(id, sshHost, e.details.steps);
|
|
4387
4434
|
bail(e.code || "E_CONNECT", e.message, e.details);
|
|
@@ -4571,12 +4618,14 @@ async function serverRouteCmd() {
|
|
|
4571
4618
|
const herdr = herdrSpawnFlag();
|
|
4572
4619
|
if (herdr) { const e = herdrSettingRemoved(`${herdr} was given`); bail(e.code, e.message); }
|
|
4573
4620
|
const local = args.slice(1).filter((a, i, all) => a !== "--server" && all[i - 1] !== "--server");
|
|
4574
|
-
const problem =
|
|
4621
|
+
const problem = suggestNameProblem(local) ?? backgroundProblem(local);
|
|
4575
4622
|
if (problem) bail("E_BAD_ARGS", problem);
|
|
4623
|
+
if (flag("task") === true) bail("E_BAD_ARGS", "--task needs a value (use --task-file for long tasks)");
|
|
4576
4624
|
}
|
|
4577
4625
|
// Everything after the command word travels, minus the routing flags; a
|
|
4578
|
-
// local --task-file is read here and
|
|
4579
|
-
// remote cannot read this machine's files.
|
|
4626
|
+
// local --task-file is read here and handed on as --task text, since the
|
|
4627
|
+
// remote cannot read this machine's files. A spawn's task is then sent on
|
|
4628
|
+
// the remote command's stdin to a host that reads it there (routeCommand).
|
|
4580
4629
|
const rest = [];
|
|
4581
4630
|
for (let i = 1; i < args.length; i++) {
|
|
4582
4631
|
const a = args[i];
|
|
@@ -4609,8 +4658,6 @@ async function serverRouteCmd() {
|
|
|
4609
4658
|
}
|
|
4610
4659
|
rest.push(a);
|
|
4611
4660
|
}
|
|
4612
|
-
// Refused here too, before anything is sent: a host on an older OATS would still delete the branch.
|
|
4613
|
-
if (cmd === "retire" && rest.includes("--delete-branch")) bail("E_BAD_ARGS", RETIRE_DELETE_BRANCH_REFUSED);
|
|
4614
4661
|
let routed;
|
|
4615
4662
|
try { routed = routeCommand(id, cmd, rest); }
|
|
4616
4663
|
catch (e) { bail(e.code || "E_SSH", e.message, e.details); }
|
|
@@ -4747,11 +4794,11 @@ else {
|
|
|
4747
4794
|
// `okf harvest --help` spawned a harvester (BeadHub, 2026-09-05).
|
|
4748
4795
|
const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
|
|
4749
4796
|
if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); process.exit(0); } usageFor(cmd); process.exit(0); }
|
|
4750
|
-
|
|
4751
|
-
//
|
|
4752
|
-
|
|
4797
|
+
// A state-changing command's argv against the flags it defines (lib/command-flags.mjs), before it runs
|
|
4798
|
+
// and before a --server command is sent: a host on an older OATS would ignore a flag it does not read.
|
|
4799
|
+
{ const problem = commandArgvProblem(rawArgs); if (problem) cmdFail(problem.code, problem.message, problem.details); }
|
|
4753
4800
|
// Session resume is local only (#1559, D1): a server resumes its own instances.
|
|
4754
|
-
if (cmd === "session" && flag("server") !== undefined &&
|
|
4801
|
+
if (cmd === "session" && args[1] === "start" && flag("server") !== undefined && args.includes("--resume")) cmdFail("E_BAD_ARGS", RESUME_LOCAL_ONLY);
|
|
4755
4802
|
if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
|
|
4756
4803
|
else if (cmd === "server") await serverCmd();
|
|
4757
4804
|
else if (cmd === "deployments") deploymentsCmd();
|
|
@@ -4762,13 +4809,8 @@ else if (cmd === "doctor") {
|
|
|
4762
4809
|
const doctorDir = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
|
|
4763
4810
|
await (args.includes("--json") ? doctorJson(doctorDir) : doctor(doctorDir));
|
|
4764
4811
|
}
|
|
4765
|
-
else if (cmd === "update")
|
|
4766
|
-
|
|
4767
|
-
// the workspace file: `oats package add`); only the kernel self-update remains.
|
|
4768
|
-
const t = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
|
|
4769
|
-
if (t || flag("to") !== undefined) { cmdFail("E_BAD_ARGS", "oats update takes no package: pin package versions in oats-workspace.yaml (`oats package add <id> <version>`), then `oats sync`; bare `oats update [--check] [--yes]` updates the kernel"); process.exit(1); }
|
|
4770
|
-
updateCmd();
|
|
4771
|
-
}
|
|
4812
|
+
else if (cmd === "update") updateCmd();
|
|
4813
|
+
else if (cmd === "harness" && args[1] === "token") await harnessTokenCmd();
|
|
4772
4814
|
else if (cmd === "harness") harnessTrustCmd();
|
|
4773
4815
|
else if (cmd === "readiness") await readinessCmd();
|
|
4774
4816
|
else if (cmd === "instance") await instanceCmd();
|
|
@@ -4787,6 +4829,7 @@ else if (cmd === "version" || cmd === "--version" || cmd === "-v") versionCmd();
|
|
|
4787
4829
|
else if (cmd === "reader") await readerCmd();
|
|
4788
4830
|
else if (cmd === "session") await sessionCmd();
|
|
4789
4831
|
else if (cmd === "schedule") await scheduleCmd();
|
|
4832
|
+
else if (cmd === "host") await hostCmd();
|
|
4790
4833
|
else if (cmd === "trigger") await triggerCmd();
|
|
4791
4834
|
else if (cmd === "automations") await automationsCmd();
|
|
4792
4835
|
// What a spawn throws outside its kernel stage goes through the same door as the inner catch.
|
|
@@ -4947,6 +4990,8 @@ Usage:
|
|
|
4947
4990
|
host install|uninstall|status explicit IANA tz; see docs/schedules.md); --server
|
|
4948
4991
|
routes to that host's workspace
|
|
4949
4992
|
install [--max-concurrent N|default] [--triggers-max-concurrent N|none]
|
|
4993
|
+
install --register-only records the scope and installs no timer, for a
|
|
4994
|
+
host whose ticker is oats host run
|
|
4950
4995
|
oats schedule add|update <id> … --description=<text> a one-line summary (1-200 characters)
|
|
4951
4996
|
oats schedule update <id> --description=<text> change only it (--description= clears it)
|
|
4952
4997
|
oats trigger add (--file <json> | --from <package>:<template> [--set k=v]) | list | show | enable
|
|
@@ -4985,6 +5030,12 @@ Usage:
|
|
|
4985
5030
|
oats session resume [--deployment <dir>] resume every lost session of this computer's
|
|
4986
5031
|
[--plan] [--json] deployments (one sweep per machine; at most 3 resumes
|
|
4987
5032
|
of a home per boot); --plan starts nothing
|
|
5033
|
+
oats host run [--stop-grace <s>] run the kernel in the foreground where no host timer
|
|
5034
|
+
[--plan] [--json] can (a container): the resume sweep once, the schedule
|
|
5035
|
+
tick each minute; on SIGTERM it stops ticking, then
|
|
5036
|
+
stops every running instance (SIGTERM, bounded wait,
|
|
5037
|
+
never escalated) so that the next start resumes it
|
|
5038
|
+
(docs/container.md); --plan starts nothing
|
|
4988
5039
|
oats session restart --home <abs-home> stop the running harness (SIGTERM, bounded wait,
|
|
4989
5040
|
[same flags] [--stop-grace <s>] never escalated) and start it again in place under
|
|
4990
5041
|
the same lock; a stop that is not observed is
|
|
@@ -5086,6 +5137,8 @@ Usage:
|
|
|
5086
5137
|
modules or the deployment's soul, trust checked, the provider's
|
|
5087
5138
|
own command run in the home or scope, envelope
|
|
5088
5139
|
relayed; a view answers {documents: [...]}
|
|
5140
|
+
oats harness token set|status|remove <harness> --server <id> [--name <team>]
|
|
5141
|
+
[--stdin] [--json] [--debug] operator credential delivery, status and removal
|
|
5089
5142
|
oats harness trust [--dir <deployment>] explicitly trust one canonical deployment root
|
|
5090
5143
|
[--harness claude|codex|all] in every native configuration file a launch reads
|
|
5091
5144
|
[--plan] [--json] (the ambient one and each launch configuration's
|
|
@@ -5170,10 +5223,10 @@ Usage:
|
|
|
5170
5223
|
typed lifecycle events (spawned, launched, stopped,
|
|
5171
5224
|
restarted, retired, worktree-retained…) written by
|
|
5172
5225
|
the action that made them true; nothing inferred
|
|
5173
|
-
oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message
|
|
5226
|
+
oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json]
|
|
5174
5227
|
a producer's claim that the instance needs input
|
|
5175
5228
|
from a human; appended only on change; display only
|
|
5176
|
-
oats instance attention [--message
|
|
5229
|
+
oats instance attention [--message=<text>] [--clear] [--json]
|
|
5177
5230
|
run by the agent from its home: "I need a human's
|
|
5178
5231
|
answer" (waiting --producer agent --reason attention)
|
|
5179
5232
|
oats instance upgrade <instance> --plan [--undo] [--json]
|