@awebai/oats 0.69.12 → 0.69.14
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 +176 -184
- package/docs/capabilities.md +4 -1
- package/docs/configuration.md +63 -5
- package/docs/container.md +246 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +376 -37
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +69 -6
- package/docs/implementation.md +86 -29
- 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/schedules.md +26 -3
- package/docs/servers.md +181 -5
- package/docs/souls-and-instances.md +140 -11
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +24 -5
- package/docs/workspaces.md +31 -5
- package/lib/claim.mjs +21 -5
- package/lib/command-flags.mjs +238 -0
- package/lib/core.mjs +791 -563
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +126 -31
- package/lib/errors.mjs +1 -1
- package/lib/harness-token.mjs +110 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +138 -13
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-listing.mjs +80 -38
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- 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 +3 -0
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +119 -27
- 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 +2 -1
- package/lib/servers.mjs +78 -23
- package/lib/session-resume.mjs +68 -53
- package/lib/session-seen.mjs +54 -5
- package/lib/start-env.mjs +13 -7
- package/lib/system-tools.mjs +1 -1
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree.mjs +56 -7
- package/package-catalog.json +1 -1
- package/package.json +2 -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/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +92 -25
- package/lib/tmux-config.mjs +0 -35
package/bin/oats.mjs
CHANGED
|
@@ -54,26 +54,27 @@ 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"));
|
|
@@ -86,6 +87,7 @@ const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, de
|
|
|
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,6 +100,7 @@ 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, 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);
|
|
@@ -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 } : {}),
|
|
@@ -891,10 +949,15 @@ async function doctor(dir) {
|
|
|
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()));
|
|
@@ -1260,10 +1320,8 @@ function instanceWaitingCmd(sub, bail) {
|
|
|
1260
1320
|
async function worktreeCmd() {
|
|
1261
1321
|
const bail = (code, msg, details, exit) => (JSON_MODE ? jsonFail(code, msg, details, exit) : die(msg, exit));
|
|
1262
1322
|
const sub = args[1];
|
|
1263
|
-
const usage =
|
|
1323
|
+
const usage = WORKTREE_USAGE;
|
|
1264
1324
|
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
1325
|
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
1326
|
const homeVariable = ["OATS_INSTANCE_HOME", "OATS_HOME"].find((name) => process.env[name]);
|
|
1269
1327
|
const home = homeVariable ? process.env[homeVariable] : enclosingInstanceHome(logicalCwd());
|
|
@@ -1277,7 +1335,6 @@ async function worktreeCmd() {
|
|
|
1277
1335
|
process.stderr.on("error", readerGone);
|
|
1278
1336
|
try {
|
|
1279
1337
|
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
1338
|
const r = await W.worktreeRemove(resolve(home), { purpose: value("purpose") });
|
|
1282
1339
|
if (JSON_MODE) { jsonOk(r); return; }
|
|
1283
1340
|
console.log(r.rolledBack
|
|
@@ -1338,7 +1395,6 @@ function retiredInstanceAddresses(root, name, home) {
|
|
|
1338
1395
|
async function instanceUpgradeCmd(name, bail) {
|
|
1339
1396
|
const usage = "usage: oats instance upgrade <instance> [--undo] (--plan | --plan-revision <rev> --idempotency-key <key>) [--home <abs>] [--dir <d>] [--json]";
|
|
1340
1397
|
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
1398
|
const home = flag("home"), revision = flag("plan-revision"), key = flag("idempotency-key");
|
|
1343
1399
|
if (home === true || (home !== undefined && !isAbsolute(home))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
|
|
1344
1400
|
const planOnly = args.includes("--plan"), undo = args.includes("--undo");
|
|
@@ -1359,8 +1415,6 @@ async function instanceUpgradeCmd(name, bail) {
|
|
|
1359
1415
|
} catch (e) { return lifecycleFail(e, "E_UPGRADE_FAILED", { ...e.details, ...(e.plan ? { plan: e.plan } : {}), ...(e.candidates ? { candidates: e.candidates } : {}) }); }
|
|
1360
1416
|
}
|
|
1361
1417
|
|
|
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
1418
|
/** `oats instance suggest-name` (feature instance-suggest-name, awebai/oats#1490 §2): the name a spawn
|
|
1365
1419
|
* of a soul would get by --suggest-name, chosen here for a spawn that may land on another machine
|
|
1366
1420
|
* (lib/core.mjs suggestSpawnName). Never routed: --server is refused before the route dispatch. */
|
|
@@ -1374,12 +1428,6 @@ async function instanceSuggestNameCmd(bail) {
|
|
|
1374
1428
|
if (v === undefined || (!inlineValues.has(name) && v.startsWith("--"))) return bail("E_BAD_ARGS", `--${name} needs a value; ${usage}`);
|
|
1375
1429
|
return v;
|
|
1376
1430
|
};
|
|
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
1431
|
const soul = value("soul"), task = value("task"), taskFile = value("task-file");
|
|
1384
1432
|
if (soul === undefined) return bail("E_BAD_ARGS", `--soul is required; ${usage}`);
|
|
1385
1433
|
if ((task === undefined) === (taskFile === undefined)) return bail("E_BAD_ARGS", `give the task with one of --task or --task-file; ${usage}`);
|
|
@@ -1397,7 +1445,7 @@ async function instanceCmd() {
|
|
|
1397
1445
|
if (sub === "upgrade") return instanceUpgradeCmd(name, bail);
|
|
1398
1446
|
if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
|
|
1399
1447
|
if (sub === "suggest-name") return instanceSuggestNameCmd(bail);
|
|
1400
|
-
const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message
|
|
1448
|
+
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
1449
|
if (!["git", "diff", "stop", "events", "color", "background", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
|
|
1402
1450
|
dropAmbientRoot();
|
|
1403
1451
|
if (sub === "events") {
|
|
@@ -1440,7 +1488,6 @@ async function instanceCmd() {
|
|
|
1440
1488
|
const words = [];
|
|
1441
1489
|
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
1490
|
const clear = args.includes("--clear");
|
|
1443
|
-
if (words.length > 1) return bail("E_BAD_ARGS", `oats instance color takes one colour; ${colorUsage}`);
|
|
1444
1491
|
const value = words[0];
|
|
1445
1492
|
if (value !== undefined && clear) return bail("E_BAD_ARGS", `give a colour or --clear, not both; ${colorUsage}`);
|
|
1446
1493
|
if (value === undefined && !clear) return bail("E_BAD_ARGS", `give a colour or --clear; ${colorUsage}`);
|
|
@@ -1620,7 +1667,8 @@ function commandSession() {
|
|
|
1620
1667
|
process.on("exit", () => { sayReadNotices(); readSession.closeNow(); });
|
|
1621
1668
|
for (const [signal, code] of [["SIGINT", 130], ["SIGTERM", 143], ["SIGHUP", 129]]) process.once(signal, () => {
|
|
1622
1669
|
readSession.closeNow();
|
|
1623
|
-
// Another handler (a
|
|
1670
|
+
// Another handler still listening (a naming call's and a lock's, lib/dir-lock.mjs, which raise
|
|
1671
|
+
// the signal again; a held `worktree` hook's, an attach's) ends the command itself after this one.
|
|
1624
1672
|
if (process.listenerCount(signal) === 0) process.exit(code);
|
|
1625
1673
|
});
|
|
1626
1674
|
}
|
|
@@ -1707,6 +1755,30 @@ function workspaceContext(bail) {
|
|
|
1707
1755
|
return { dir, localPath: found.path, local: found.local, deploymentDir: dirname(found.path), remoteOptions: remoteOptionsFromEnv() };
|
|
1708
1756
|
}
|
|
1709
1757
|
|
|
1758
|
+
/** Tokens are operator-local calls even with --server; the forced-command key is the receiver. */
|
|
1759
|
+
async function harnessTokenCmd() {
|
|
1760
|
+
const usage = "usage: oats harness token set|status|remove <harness> --server <id> [--name <team>] [--stdin] [--json] [--debug]";
|
|
1761
|
+
if (!["set", "status", "remove"].includes(args[2]) || !args[3] || args[3].startsWith("-")) return cmdFail("E_BAD_ARGS", usage);
|
|
1762
|
+
const seen = new Set();
|
|
1763
|
+
for (let i = 4; i < args.length; i++) {
|
|
1764
|
+
const word = args[i];
|
|
1765
|
+
if (seen.has(word)) return cmdFail("E_BAD_ARGS", "Give each token-command flag once.");
|
|
1766
|
+
seen.add(word);
|
|
1767
|
+
if (["--json", "--stdin", "--debug"].includes(word)) continue;
|
|
1768
|
+
if (["--server", "--name"].includes(word) && args[i + 1] && !args[i + 1].startsWith("-")) { i++; continue; }
|
|
1769
|
+
return cmdFail("E_BAD_ARGS", usage);
|
|
1770
|
+
}
|
|
1771
|
+
try {
|
|
1772
|
+
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 });
|
|
1773
|
+
if (JSON_MODE) jsonOk(result);
|
|
1774
|
+
else {
|
|
1775
|
+
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}.`);
|
|
1776
|
+
for (const row of result.staleInstances ?? []) console.log(terminalText(` ${row.instance} (${row.agent}): started ${row.startedAt}; picks up the token at its next start.`));
|
|
1777
|
+
for (const warning of result.warnings) console.error(`oats: warning: ${warning}`);
|
|
1778
|
+
}
|
|
1779
|
+
} catch (e) { cmdFail(e.code || "E_HARNESS_TOKEN_DELIVERY", JSON_MODE ? e.message : terminalText(e.message)); }
|
|
1780
|
+
}
|
|
1781
|
+
|
|
1710
1782
|
/** An explicit host-local operator action; never routed to a remote adapter. */
|
|
1711
1783
|
function harnessTrustCmd() {
|
|
1712
1784
|
if (args[1] !== "trust") return cmdFail("E_BAD_ARGS", "usage: oats harness trust [--dir <deployment>] [--harness claude|codex|all] [--plan] [--json]");
|
|
@@ -1825,7 +1897,6 @@ function printTable(header, rows) {
|
|
|
1825
1897
|
}
|
|
1826
1898
|
|
|
1827
1899
|
/** `--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
1900
|
|
|
1830
1901
|
/** The body of `oats sync` — shared by `sync` and `onboard` (which onboards, then syncs the same
|
|
1831
1902
|
* way). Given a v2 deployment context: discover over the remotes, confirm membership, resolve
|
|
@@ -2015,31 +2086,11 @@ function setDisabledHereCli(ws, kind, qid, enabled) {
|
|
|
2015
2086
|
return A.setDisabledHere({ deployment: dirname(path), localPath: path }, kind, qid, !enabled);
|
|
2016
2087
|
}
|
|
2017
2088
|
|
|
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
2089
|
/** `oats sync [--dir] [--plan] [--json]` — contract §6. `--plan` previews: the same report, nothing written. */
|
|
2039
2090
|
async function syncCmd() {
|
|
2040
2091
|
const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
|
|
2041
|
-
|
|
2042
|
-
if (
|
|
2092
|
+
// A second --dir: flag() would read the first and drop it.
|
|
2093
|
+
if (args.filter((a) => a === "--dir").length > 1) return bail("E_BAD_ARGS", `oats sync: give --dir once\n${SYNC_USAGE}`, { flag: "--dir" });
|
|
2043
2094
|
const ctx = workspaceContext(bail);
|
|
2044
2095
|
const synced = await performSync(ctx, bail, { plan: args.includes("--plan") });
|
|
2045
2096
|
// One envelope (or the §8 report); success is exit 0 (a failure bails with its code).
|
|
@@ -2177,41 +2228,15 @@ async function teamsContext(bail) {
|
|
|
2177
2228
|
}
|
|
2178
2229
|
const positional = (i) => (args[i] !== undefined && !args[i].startsWith("--") ? args[i] : undefined);
|
|
2179
2230
|
|
|
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
2231
|
/** `oats teams [--json] | add <label> --team <id> [--description <d>] [--no-default] | remove <label> |
|
|
2202
2232
|
* default <label> [--if-absent | --expect <label>]` — this deployment's teams (team model 3). Config only:
|
|
2203
2233
|
* never a provider call. */
|
|
2204
2234
|
async function teamsCmd() {
|
|
2205
2235
|
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
|
-
}
|
|
2236
|
+
const usage = TEAMS_USAGE;
|
|
2237
|
+
// The form and its flags were checked by the dispatch (lib/command-flags.mjs): a word where the form
|
|
2238
|
+
// belongs, and a flag the form does not take, are E_USAGE there.
|
|
2239
|
+
const sub = positional(1);
|
|
2215
2240
|
const label = sub ? positional(2) : undefined;
|
|
2216
2241
|
if (sub && label === undefined) bail("E_BAD_ARGS", `oats teams ${sub} needs a team label — ${usage}`);
|
|
2217
2242
|
const ctx = await teamsContext(bail);
|
|
@@ -2276,13 +2301,6 @@ async function soulCmd() {
|
|
|
2276
2301
|
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
2302
|
}
|
|
2278
2303
|
|
|
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
2304
|
/** A souls.launch entry in words: a launch configuration's name, or the inline harness and model. */
|
|
2287
2305
|
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
2306
|
|
|
@@ -2292,23 +2310,22 @@ const launchEntryText = (v) => (v === null ? "no entry" : typeof v === "string"
|
|
|
2292
2310
|
async function soulLaunchCmd(bail, usage) {
|
|
2293
2311
|
const sub = positional(2);
|
|
2294
2312
|
if (!["set", "remove"].includes(sub)) bail("E_USAGE", usage);
|
|
2295
|
-
// Every argument is accounted for before anything is read or written
|
|
2296
|
-
//
|
|
2297
|
-
//
|
|
2298
|
-
|
|
2313
|
+
// Every argument is accounted for before anything is read or written. The dispatch refused a flag the
|
|
2314
|
+
// form does not take and a second name (lib/command-flags.mjs); here a value flag with no value at ANY
|
|
2315
|
+
// of its occurrences (`--harness codex --harness`) and a value flag given twice (flag() would read the
|
|
2316
|
+
// first and drop the second) are refused, never ignored. Its value flags are the declaration's.
|
|
2317
|
+
const { values } = commandFlags(args);
|
|
2299
2318
|
const names = [], given = new Set();
|
|
2300
2319
|
for (let i = 3; i < args.length; i++) {
|
|
2301
2320
|
const a = args[i];
|
|
2302
2321
|
if (!a.startsWith("-")) { names.push(a); continue; }
|
|
2303
|
-
if (!
|
|
2304
|
-
if (!takes[a]) continue;
|
|
2322
|
+
if (!values.includes(a)) continue;
|
|
2305
2323
|
if (args[i + 1] === undefined || args[i + 1].startsWith("--")) bail("E_BAD_ARGS", `${a} needs a value`);
|
|
2306
2324
|
if (given.has(a)) bail("E_BAD_ARGS", `oats soul launch ${sub} takes ${a} once (nothing was changed)`);
|
|
2307
2325
|
given.add(a);
|
|
2308
2326
|
i++;
|
|
2309
2327
|
}
|
|
2310
2328
|
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
2329
|
const name = names[0];
|
|
2313
2330
|
const V = await import("../lib/soul-launch-verbs.mjs");
|
|
2314
2331
|
let value = null;
|
|
@@ -2618,12 +2635,6 @@ function printStatus({ root, agents: data, ws, problems }, verbose) {
|
|
|
2618
2635
|
}
|
|
2619
2636
|
}
|
|
2620
2637
|
|
|
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
2638
|
/** `--suggest-name` (features spawn-suggest-name, spawn-apply-suggest-name): a preview's or an apply's,
|
|
2628
2639
|
* with no --name, --purpose or --expect-decision. The kernel refuses the same (core.mjs spawnBody); the
|
|
2629
2640
|
* CLI says it before anything is read or sent. */
|
|
@@ -2636,26 +2647,6 @@ function suggestNameProblem(argv) {
|
|
|
2636
2647
|
}
|
|
2637
2648
|
/** `--background` / `--no-background` (feature instance-background): one of them, or neither. */
|
|
2638
2649
|
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
2650
|
/** The Herdr spawn flags (removed in 0.31.0), named for the refusal; undefined when none is given. */
|
|
2660
2651
|
function herdrSpawnFlag() {
|
|
2661
2652
|
if (flag("backend") === "herdr") return "--backend herdr";
|
|
@@ -2696,12 +2687,9 @@ async function spawnCmd() {
|
|
|
2696
2687
|
};
|
|
2697
2688
|
checkDirectoryOptions(requestedWork); // before anything is resolved or written
|
|
2698
2689
|
const name = args[1];
|
|
2699
|
-
if (!name || name.startsWith("--")) bail("E_USAGE",
|
|
2690
|
+
if (!name || name.startsWith("--")) bail("E_USAGE", SPAWN_USAGE);
|
|
2700
2691
|
// Retired boundary flags (maintainer transport ruling): fail LOUDLY before
|
|
2701
2692
|
// 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
2693
|
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
2694
|
// --name <slug>: the exact, unprefixed instance name (human decision 2026-09-24).
|
|
2707
2695
|
const nameFlag = flag("name");
|
|
@@ -2710,8 +2698,6 @@ async function spawnCmd() {
|
|
|
2710
2698
|
{ const problem = suggestNameProblem(args) ?? backgroundProblem(args); if (problem) bail("E_BAD_ARGS", problem); }
|
|
2711
2699
|
// The slug rule is checked here too, before any side effect (soul fetch).
|
|
2712
2700
|
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
2701
|
let root;
|
|
2716
2702
|
// A spawn needs a workspace deployment (lead decision c3-1): no oats-local.yaml
|
|
2717
2703
|
// in reach is E_LOCAL_MISSING, before anything else is read. The agents root is
|
|
@@ -2743,11 +2729,14 @@ async function spawnCmd() {
|
|
|
2743
2729
|
{
|
|
2744
2730
|
let discovery = null;
|
|
2745
2731
|
try {
|
|
2746
|
-
const { prepareInstance, ensureWorkspaceSoul, previewWorkspaceSoul, parseProviderFlags, discoverOrStandalone, agentDirOf } = await import("../lib/instance-resolution.mjs");
|
|
2732
|
+
const { prepareInstance, verifyPreparedPackages, ensureWorkspaceSoul, previewWorkspaceSoul, parseProviderFlags, discoverOrStandalone, agentDirOf } = await import("../lib/instance-resolution.mjs");
|
|
2747
2733
|
const remoteOptions = remoteOptionsFromEnv();
|
|
2748
2734
|
const { local, path: localPath } = loadLocal(dirFlag());
|
|
2749
2735
|
discovery = wsDiscovery = await discoverOrStandalone(local, { deployment: dirname(localPath), remoteOptions });
|
|
2750
2736
|
wsPrepared = await prepareInstance(dirFlag(), name, { spawn: { providers: parseProviderFlags(providerPairs) }, remoteOptions, discovery });
|
|
2737
|
+
// Each package the soul composes is the content the lock records (E_PACKAGE_INTEGRITY), before the
|
|
2738
|
+
// first write of the spawn: the soul cache below is the first thing a spawn creates under the agents root.
|
|
2739
|
+
await verifyPreparedPackages(wsPrepared);
|
|
2751
2740
|
const soulName = agentDirOf(wsPrepared.soulEntry);
|
|
2752
2741
|
let soulDir;
|
|
2753
2742
|
if (isPreview) {
|
|
@@ -2997,9 +2986,7 @@ function failedSpawnBranchLine(r, items, { local = false, host } = {}) {
|
|
|
2997
2986
|
let retireReturned = false;
|
|
2998
2987
|
function retireCmd() {
|
|
2999
2988
|
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]");
|
|
2989
|
+
if (!name || name.startsWith("--")) return cmdFail("E_USAGE", RETIRE_USAGE);
|
|
3003
2990
|
let homeFlag = flag("home");
|
|
3004
2991
|
if (homeFlag === true) die("--home needs the instance home path");
|
|
3005
2992
|
if (args.includes("--plan")) {
|
|
@@ -3415,7 +3402,7 @@ async function triggerFromPackage(T, from, sets, idFlag) {
|
|
|
3415
3402
|
|
|
3416
3403
|
async function sessionCmd() {
|
|
3417
3404
|
try {
|
|
3418
|
-
if (flag("native-record") !== undefined) throw Object.assign(new Error(
|
|
3405
|
+
if (flag("native-record") !== undefined) throw Object.assign(new Error(NATIVE_RECORD_REFUSED), { code: "E_BAD_ARGS" });
|
|
3419
3406
|
const home = flag("home");
|
|
3420
3407
|
let result;
|
|
3421
3408
|
if (args[1] === "attach") {
|
|
@@ -3437,13 +3424,7 @@ async function sessionCmd() {
|
|
|
3437
3424
|
if (args[1] === "resume") {
|
|
3438
3425
|
// The machine sweep (feature session-resume, #1559): lib/session-resume.mjs. No --home: one home
|
|
3439
3426
|
// 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
|
-
}
|
|
3427
|
+
const usage = commandFlags(args).usage;
|
|
3447
3428
|
const deployment = flag("deployment");
|
|
3448
3429
|
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
3430
|
const { resumeSessions } = await import("../lib/session-resume.mjs");
|
|
@@ -3472,7 +3453,6 @@ async function sessionCmd() {
|
|
|
3472
3453
|
// refused with a launch choice before anything of the home is read.
|
|
3473
3454
|
const resume = args.includes("--resume");
|
|
3474
3455
|
if (resume) {
|
|
3475
|
-
if (args[1] === "restart") bad("--resume exists on session start only: it brings back a session that was lost");
|
|
3476
3456
|
const chosen = ["--launch-config", "--harness", "--model", "--yolo", "--no-yolo", "--reselect-launch"].filter((f) => args.some((a) => a === f || a.startsWith(`${f}=`)));
|
|
3477
3457
|
if (chosen.length) bad(`--resume runs the launch this home recorded; it cannot be combined with ${chosen.join(", ")}; nothing was read or started`);
|
|
3478
3458
|
}
|
|
@@ -4224,7 +4204,7 @@ async function experimentalCmd() {
|
|
|
4224
4204
|
async function serverCmd() {
|
|
4225
4205
|
const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
|
|
4226
4206
|
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]";
|
|
4207
|
+
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
4208
|
if (!["add", "connect", "list", "remove", "check", "roster", "forget"].includes(sub)) bail("E_USAGE", usage);
|
|
4229
4209
|
if (sub === "connect") return serverConnectCmd(bail);
|
|
4230
4210
|
if (sub === "forget") {
|
|
@@ -4274,7 +4254,9 @@ async function serverCmd() {
|
|
|
4274
4254
|
let servers;
|
|
4275
4255
|
try { servers = readServers(); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
|
|
4276
4256
|
if (sub === "list") {
|
|
4277
|
-
let
|
|
4257
|
+
let routes;
|
|
4258
|
+
try { routes = readServerOperatorRoutes(); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
|
|
4259
|
+
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
4260
|
// --workspace-ref: the servers of one workspace, by canonical key, and the ids whose workspace is not known yet.
|
|
4279
4261
|
let unknownWorkspace;
|
|
4280
4262
|
if (flag("workspace-ref") !== undefined) {
|
|
@@ -4288,7 +4270,7 @@ async function serverCmd() {
|
|
|
4288
4270
|
if (JSON_MODE) { jsonOk({ file: SERVERS_FILE(), servers: rows, ...(unknownWorkspace ? { unknownWorkspace } : {}) }); return; }
|
|
4289
4271
|
if (unknownWorkspace?.length) console.log(` (workspace not known yet for ${unknownWorkspace.join(", ")}: oats server check <id> learns it)`);
|
|
4290
4272
|
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)` : ""}`);
|
|
4273
|
+
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
4274
|
return;
|
|
4293
4275
|
}
|
|
4294
4276
|
const id = args[2];
|
|
@@ -4299,12 +4281,23 @@ async function serverCmd() {
|
|
|
4299
4281
|
const entry = { sshHost: val("ssh"), workspace: val("workspace") };
|
|
4300
4282
|
for (const [k, f] of [["oatsPath", "oats"], ["path", "path"], ["label", "label"]]) { const v = val(f); if (v !== undefined) entry[k] = v; }
|
|
4301
4283
|
if (!entry.sshHost || !entry.workspace) bail("E_USAGE", usage);
|
|
4302
|
-
|
|
4284
|
+
const operatorSshHost = val("operator-ssh"), noOperatorSsh = args.includes("--no-operator-ssh");
|
|
4285
|
+
if (operatorSshHost !== undefined && noOperatorSsh) bail("E_BAD_ARGS", "choose --operator-ssh or --no-operator-ssh, not both");
|
|
4286
|
+
try { validateServer(id, entry); if (operatorSshHost !== undefined) validateOperatorSshHost(operatorSshHost); } catch (e) { bail(e.code, e.message); }
|
|
4287
|
+
let operatorRoute;
|
|
4303
4288
|
try {
|
|
4304
|
-
updateServers((current) => {
|
|
4305
|
-
|
|
4289
|
+
updateServers((current, routes) => {
|
|
4290
|
+
const existing = Object.hasOwn(current, id) ? current[id] : undefined;
|
|
4291
|
+
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" });
|
|
4292
|
+
// An older kernel can remove a registration while leaving its sidecar route behind.
|
|
4293
|
+
if (!existing) delete routes[id];
|
|
4294
|
+
// An unchanged agent target keeps its learned identity when only the operator route changes.
|
|
4295
|
+
if (existing?.workspaceKey && JSON.stringify(targetOf(existing)) === JSON.stringify(targetOf(entry))) entry.workspaceKey = existing.workspaceKey;
|
|
4306
4296
|
current[id] = entry;
|
|
4307
|
-
|
|
4297
|
+
if (operatorSshHost !== undefined) routes[id] = { operatorSshHost };
|
|
4298
|
+
else if (noOperatorSsh) delete routes[id];
|
|
4299
|
+
operatorRoute = Object.hasOwn(routes, id) ? routes[id] : undefined;
|
|
4300
|
+
}, { operatorRoutes: true });
|
|
4308
4301
|
} catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
|
|
4309
4302
|
// The workspace key is learned from the host, never typed: recorded when the host answers one and
|
|
4310
4303
|
// the registration is still this one (it may change while the host is asked).
|
|
@@ -4312,20 +4305,24 @@ async function serverCmd() {
|
|
|
4312
4305
|
try {
|
|
4313
4306
|
const { key, why } = reportedWorkspaceKey(targetOf(entry), { serverId: id, timeoutMs: 60000 });
|
|
4314
4307
|
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
|
|
4308
|
+
else if (["recorded", "same"].includes(learnWorkspaceKey(id, entry, key, { replace: args.includes("--replace") }))) entry.workspaceKey = key;
|
|
4309
|
+
else {
|
|
4310
|
+
delete entry.workspaceKey;
|
|
4311
|
+
warnings.push(`workspace key not recorded: registration ${id} changed while the host was asked; oats server check ${id} learns it`);
|
|
4312
|
+
}
|
|
4317
4313
|
} 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; }
|
|
4314
|
+
if (JSON_MODE) { jsonOk({ id, ...entry, ...operatorRoute, workspaceKey: entry.workspaceKey ?? null, file: SERVERS_FILE(), ...(warnings.length ? { warnings } : {}) }); return; }
|
|
4319
4315
|
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
4316
|
for (const w of warnings) console.error(`oats: warning: ${w}`);
|
|
4321
4317
|
return;
|
|
4322
4318
|
}
|
|
4323
4319
|
if (sub === "remove") {
|
|
4324
4320
|
try {
|
|
4325
|
-
updateServers((current) => {
|
|
4321
|
+
updateServers((current, routes) => {
|
|
4326
4322
|
if (!current[id]) throw Object.assign(new Error(`no server registered as ${id}`), { code: "E_SERVER_UNKNOWN" });
|
|
4327
4323
|
delete current[id];
|
|
4328
|
-
|
|
4324
|
+
delete routes[id];
|
|
4325
|
+
}, { operatorRoutes: true });
|
|
4329
4326
|
} catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
|
|
4330
4327
|
const snaps = listSnapshots(id);
|
|
4331
4328
|
if (JSON_MODE) { jsonOk({ removed: id, remoteInstancesStillTracked: snaps.map((s) => s.instance) }); return; }
|
|
@@ -4368,7 +4365,7 @@ async function serverCmd() {
|
|
|
4368
4365
|
* step b): only the person knows where it goes. */
|
|
4369
4366
|
function serverConnectCmd(bail) {
|
|
4370
4367
|
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]");
|
|
4368
|
+
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
4369
|
const val = (name) => { const v = flag(name); return v === true ? bail("E_BAD_ARGS", `--${name} needs a value`) : v; };
|
|
4373
4370
|
const sshHost = val("ssh");
|
|
4374
4371
|
if (!sshHost) bail("E_BAD_ARGS", "--ssh <host-alias> is required: the OpenSSH host alias of the machine to connect");
|
|
@@ -4381,7 +4378,7 @@ function serverConnectCmd(bail) {
|
|
|
4381
4378
|
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
4379
|
let res;
|
|
4383
4380
|
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 });
|
|
4381
|
+
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
4382
|
} catch (e) {
|
|
4386
4383
|
if (!JSON_MODE && e.details?.steps) printConnectSteps(id, sshHost, e.details.steps);
|
|
4387
4384
|
bail(e.code || "E_CONNECT", e.message, e.details);
|
|
@@ -4571,7 +4568,7 @@ async function serverRouteCmd() {
|
|
|
4571
4568
|
const herdr = herdrSpawnFlag();
|
|
4572
4569
|
if (herdr) { const e = herdrSettingRemoved(`${herdr} was given`); bail(e.code, e.message); }
|
|
4573
4570
|
const local = args.slice(1).filter((a, i, all) => a !== "--server" && all[i - 1] !== "--server");
|
|
4574
|
-
const problem =
|
|
4571
|
+
const problem = suggestNameProblem(local) ?? backgroundProblem(local);
|
|
4575
4572
|
if (problem) bail("E_BAD_ARGS", problem);
|
|
4576
4573
|
}
|
|
4577
4574
|
// Everything after the command word travels, minus the routing flags; a
|
|
@@ -4609,8 +4606,6 @@ async function serverRouteCmd() {
|
|
|
4609
4606
|
}
|
|
4610
4607
|
rest.push(a);
|
|
4611
4608
|
}
|
|
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
4609
|
let routed;
|
|
4615
4610
|
try { routed = routeCommand(id, cmd, rest); }
|
|
4616
4611
|
catch (e) { bail(e.code || "E_SSH", e.message, e.details); }
|
|
@@ -4747,11 +4742,11 @@ else {
|
|
|
4747
4742
|
// `okf harvest --help` spawned a harvester (BeadHub, 2026-09-05).
|
|
4748
4743
|
const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
|
|
4749
4744
|
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
|
-
|
|
4745
|
+
// A state-changing command's argv against the flags it defines (lib/command-flags.mjs), before it runs
|
|
4746
|
+
// and before a --server command is sent: a host on an older OATS would ignore a flag it does not read.
|
|
4747
|
+
{ const problem = commandArgvProblem(rawArgs); if (problem) cmdFail(problem.code, problem.message, problem.details); }
|
|
4753
4748
|
// Session resume is local only (#1559, D1): a server resumes its own instances.
|
|
4754
|
-
if (cmd === "session" && flag("server") !== undefined &&
|
|
4749
|
+
if (cmd === "session" && args[1] === "start" && flag("server") !== undefined && args.includes("--resume")) cmdFail("E_BAD_ARGS", RESUME_LOCAL_ONLY);
|
|
4755
4750
|
if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
|
|
4756
4751
|
else if (cmd === "server") await serverCmd();
|
|
4757
4752
|
else if (cmd === "deployments") deploymentsCmd();
|
|
@@ -4762,13 +4757,8 @@ else if (cmd === "doctor") {
|
|
|
4762
4757
|
const doctorDir = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
|
|
4763
4758
|
await (args.includes("--json") ? doctorJson(doctorDir) : doctor(doctorDir));
|
|
4764
4759
|
}
|
|
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
|
-
}
|
|
4760
|
+
else if (cmd === "update") updateCmd();
|
|
4761
|
+
else if (cmd === "harness" && args[1] === "token") await harnessTokenCmd();
|
|
4772
4762
|
else if (cmd === "harness") harnessTrustCmd();
|
|
4773
4763
|
else if (cmd === "readiness") await readinessCmd();
|
|
4774
4764
|
else if (cmd === "instance") await instanceCmd();
|
|
@@ -5086,6 +5076,8 @@ Usage:
|
|
|
5086
5076
|
modules or the deployment's soul, trust checked, the provider's
|
|
5087
5077
|
own command run in the home or scope, envelope
|
|
5088
5078
|
relayed; a view answers {documents: [...]}
|
|
5079
|
+
oats harness token set|status|remove <harness> --server <id> [--name <team>]
|
|
5080
|
+
[--stdin] [--json] [--debug] operator credential delivery, status and removal
|
|
5089
5081
|
oats harness trust [--dir <deployment>] explicitly trust one canonical deployment root
|
|
5090
5082
|
[--harness claude|codex|all] in every native configuration file a launch reads
|
|
5091
5083
|
[--plan] [--json] (the ambient one and each launch configuration's
|
|
@@ -5170,10 +5162,10 @@ Usage:
|
|
|
5170
5162
|
typed lifecycle events (spawned, launched, stopped,
|
|
5171
5163
|
restarted, retired, worktree-retained…) written by
|
|
5172
5164
|
the action that made them true; nothing inferred
|
|
5173
|
-
oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message
|
|
5165
|
+
oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json]
|
|
5174
5166
|
a producer's claim that the instance needs input
|
|
5175
5167
|
from a human; appended only on change; display only
|
|
5176
|
-
oats instance attention [--message
|
|
5168
|
+
oats instance attention [--message=<text>] [--clear] [--json]
|
|
5177
5169
|
run by the agent from its home: "I need a human's
|
|
5178
5170
|
answer" (waiting --producer agent --reason attention)
|
|
5179
5171
|
oats instance upgrade <instance> --plan [--undo] [--json]
|