@awebai/oats 0.69.3 → 0.69.5

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.
Files changed (50) hide show
  1. package/bin/oats.mjs +68 -49
  2. package/docs/configuration.md +12 -0
  3. package/docs/desktop-cli-api.md +8 -1
  4. package/docs/execution-targets.md +25 -3
  5. package/docs/implementation.md +42 -3
  6. package/docs/integrations.md +2 -2
  7. package/docs/knowledge.md +9 -6
  8. package/docs/named-test-runs.md +4 -2
  9. package/docs/official-catalog.md +6 -6
  10. package/docs/packages.md +14 -14
  11. package/docs/release-lane.md +25 -18
  12. package/docs/release-notes/v0.69.4.md +73 -0
  13. package/docs/release-notes/v0.69.5.md +146 -0
  14. package/docs/souls-and-instances.md +2 -2
  15. package/docs/tui.md +2 -1
  16. package/docs/upgrading.md +16 -5
  17. package/docs/workspaces.md +2 -2
  18. package/lib/agents-root.mjs +51 -0
  19. package/lib/automation-api.mjs +7 -0
  20. package/lib/automation-scope.mjs +35 -0
  21. package/lib/automations.mjs +2 -1
  22. package/lib/compile-cache.mjs +36 -0
  23. package/lib/core.mjs +39 -1348
  24. package/lib/deployment-path.mjs +127 -0
  25. package/lib/deployments.mjs +2 -2
  26. package/lib/drift.mjs +95 -0
  27. package/lib/hot-reads.mjs +131 -0
  28. package/lib/instance-address.mjs +21 -0
  29. package/lib/instance-lifecycle.mjs +4 -16
  30. package/lib/instance-listing.mjs +730 -0
  31. package/lib/instance-resolution.mjs +5 -166
  32. package/lib/materialize.mjs +2 -87
  33. package/lib/member-clone.mjs +188 -0
  34. package/lib/package-catalog.mjs +93 -0
  35. package/lib/packages.mjs +4 -24
  36. package/lib/reserved-launch-env.mjs +20 -0
  37. package/lib/resolved-deployment.mjs +1 -1
  38. package/lib/schedule.mjs +5 -29
  39. package/lib/semver.mjs +12 -0
  40. package/lib/servers.mjs +10 -12
  41. package/lib/session-end.mjs +3 -2
  42. package/lib/session-inspect.mjs +219 -0
  43. package/lib/soul-listing.mjs +216 -0
  44. package/lib/status-words.mjs +30 -0
  45. package/lib/version.mjs +9 -0
  46. package/lib/write-file-atomic.mjs +28 -0
  47. package/package-catalog.json +5 -5
  48. package/package.json +1 -1
  49. package/packages/tui/lib/store.mjs +7 -3
  50. package/skills/oats-getting-started/SKILL.md +3 -3
package/bin/oats.mjs CHANGED
@@ -25,52 +25,66 @@ import { constants as osConstants, homedir, tmpdir } from "node:os";
25
25
  import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
26
26
  import { fileURLToPath } from "node:url";
27
27
  import { performance } from "node:perf_hooks";
28
- import { doctorCaptureWarnings } from "../lib/doctor-capture.mjs";
29
- import { assertNoPartialUpgrade } from "../lib/upgrade-state.mjs";
30
- import { runtimeNameWarning, noteRuntimeName } from "../lib/deprecation.mjs";
31
- import { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect, spawnRefusalDetails } from "../lib/errors.mjs";
32
- import {
28
+ import { spawnSync as spawnSyncProc } from "node:child_process";
29
+ import { enableCliCompileCache } from "../lib/compile-cache.mjs";
30
+ import { hotImport, hotRead } from "../lib/hot-reads.mjs";
31
+
32
+ // Node's compile cache is on before the kernel is parsed (lib/compile-cache.mjs): static imports are
33
+ // all parsed and linked before this module's body runs, so they are Node built-ins and the two small
34
+ // dependency-free modules above, and the kernel and `yaml` are imported here, in order, once it is on.
35
+ enableCliCompileCache();
36
+ // A hot read (lib/hot-reads.mjs) imports only the leaves it uses, never core.mjs: each line below takes
37
+ // the leaves its names come from, and every other command imports every module, in this order. A hot
38
+ // read takes its names from lib/hot-reads.mjs: a name newly used on a hot read's path must be listed
39
+ // there, under its line, or its first use throws (a tripwire); test/cli-hot-reads.test.mjs pins what
40
+ // each hot read must not load. Each line names its module and imports it by one string literal.
41
+ const HOT_READ = hotRead(process.argv.slice(2));
42
+ const kernelImport = (name, load) => (HOT_READ ? hotImport(HOT_READ, name) : load());
43
+ const { doctorCaptureWarnings } = await kernelImport("doctor-capture", () => import("../lib/doctor-capture.mjs"));
44
+ const { assertNoPartialUpgrade } = await kernelImport("upgrade-state", () => import("../lib/upgrade-state.mjs"));
45
+ const { runtimeNameWarning, noteRuntimeName } = await kernelImport("deprecation", () => import("../lib/deprecation.mjs"));
46
+ const { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect, spawnRefusalDetails } = await kernelImport("errors", () => import("../lib/errors.mjs"));
47
+ const {
33
48
  LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
34
49
  capabilityManifests, capabilityTrust, capabilityExecutablePath,
35
50
  officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
36
51
  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, retireInstance, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
37
52
  FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
38
- } from "../lib/core.mjs";
39
- import {
53
+ } = await kernelImport("core", () => import("../lib/core.mjs"));
54
+ const {
40
55
  writeFileAtomic, LOCK_FILE, canonicalLock, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
41
- classifyPackageValue, parsePackageRequest } from "../lib/packages.mjs";
42
- import { harnessTrust } from "../lib/harness-trust-write.mjs";
43
- import { previewLaunchEnvironment, previewPaneEnvironment } from "../lib/core.mjs";
44
- import { PI_BRIDGE, piBridgeFolders, piBridgeSkewWarnings, planPiBridges, piBridgePlanLines, piBridgeStepProblem, piBridgeFailure, kernelLookup, kernelLookupResult, planCliUpdate, desktopFirstLine, bridgeLookup, bridgeLookupProblem } from "../lib/pi-bridge.mjs";
45
- import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, unlockedPackages, workspaceWarnings, memberRowByKey } from "../lib/workspace.mjs";
46
- import { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "../lib/teams.mjs";
47
- import { LAUNCH_KEY_UNCHECKED, LAUNCH_PREFERENCE_UNMATCHED, launchKeyQuoted, launchKeysUnmatched, launchLayers, soulLaunchCommand, unmatchedKeyMessage } from "../lib/launch-preference.mjs";
48
- import { terminalText } from "../lib/refused-text.mjs";
49
- import { qualifiedSoulName, soulCandidates, soulsOffered } from "../lib/instance-resolution.mjs";
50
- import { parseConfigData } from "../lib/config-data.mjs";
51
- import * as remoteModule from "../lib/remote.mjs";
52
- import { activateLocalInputs, localRevision } from "../lib/local-inputs.mjs";
53
- import YAML from "yaml";
54
- import { 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 } from "../lib/servers.mjs";
55
- import { readSessionViewer } from "../lib/session-viewer.mjs";
56
- import { spawnSync as spawnSyncProc } from "node:child_process";
57
- import { tickTriggers } from "../lib/triggers.mjs";
58
- import * as A from "../lib/automations.mjs";
59
- import { parseEnvelopeText, unresolvedScheduleAttempts, scheduleScopeOf, listSchedules, describe as describeSchedule, testSchedule, addSchedule, updateSchedule, updateScheduleDescription, setEnabled as setScheduleEnabled, removeSchedule, runNow as runScheduleNow, reconcile as reconcileSchedule, tickHost, tickWorkspace, scopeAutomations, scheduleKind, registerWorkspace, unregisterWorkspace, readRegistry, schedulerStatus, saveWakeForHome, removeWakeForHome, wakeFromFlags, withHostLock, scheduleError, SCHEDULE_API } from "../lib/schedule.mjs";
60
- import { hostUnitFiles, hostUnitStatus, installHostUnit, uninstallHostUnit } from "../lib/schedule-host.mjs";
61
- import { kernelNode, stableNode } from "../lib/stable-node.mjs";
62
- import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
63
-
64
- import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
65
- import { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance as resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstanceSameWork, STOP_WARNINGS } from "../lib/instance-lifecycle.mjs";
66
- import { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } from "../lib/retire-output.mjs";
67
- import { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } from "../lib/retained-after-retire.mjs";
56
+ classifyPackageValue, parsePackageRequest } = await kernelImport("packages", () => import("../lib/packages.mjs"));
57
+ const { harnessTrust } = await kernelImport("harness-trust-write", () => import("../lib/harness-trust-write.mjs"));
58
+ const { previewLaunchEnvironment, previewPaneEnvironment } = await kernelImport("core", () => import("../lib/core.mjs"));
59
+ const { PI_BRIDGE, piBridgeFolders, piBridgeSkewWarnings, planPiBridges, piBridgePlanLines, piBridgeStepProblem, piBridgeFailure, kernelLookup, kernelLookupResult, planCliUpdate, desktopFirstLine, bridgeLookup, bridgeLookupProblem } = await kernelImport("pi-bridge", () => import("../lib/pi-bridge.mjs"));
60
+ const { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, unlockedPackages, workspaceWarnings, memberRowByKey } = await kernelImport("workspace", () => import("../lib/workspace.mjs"));
61
+ const { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } = await kernelImport("teams", () => import("../lib/teams.mjs"));
62
+ const { LAUNCH_KEY_UNCHECKED, LAUNCH_PREFERENCE_UNMATCHED, launchKeyQuoted, launchKeysUnmatched, launchLayers, soulLaunchCommand, unmatchedKeyMessage } = await kernelImport("launch-preference", () => import("../lib/launch-preference.mjs"));
63
+ const { terminalText } = await kernelImport("refused-text", () => import("../lib/refused-text.mjs"));
64
+ const { qualifiedSoulName, soulCandidates, soulsOffered } = await kernelImport("instance-resolution", () => import("../lib/instance-resolution.mjs"));
65
+ const { parseConfigData } = await kernelImport("config-data", () => import("../lib/config-data.mjs"));
66
+ const remoteModule = await kernelImport("remote", () => import("../lib/remote.mjs"));
67
+ const { activateLocalInputs, localRevision } = await kernelImport("local-inputs", () => import("../lib/local-inputs.mjs"));
68
+ const { default: YAML } = await kernelImport("yaml", () => import("yaml"));
69
+ 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"));
70
+ const { readSessionViewer } = await kernelImport("session-viewer", () => import("../lib/session-viewer.mjs"));
71
+ const { tickTriggers } = await kernelImport("triggers", () => import("../lib/triggers.mjs"));
72
+ const A = await kernelImport("automations", () => import("../lib/automations.mjs"));
73
+ 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"));
74
+ const { hostUnitFiles, hostUnitStatus, installHostUnit, uninstallHostUnit } = await kernelImport("schedule-host", () => import("../lib/schedule-host.mjs"));
75
+ const { kernelNode, stableNode } = await kernelImport("stable-node", () => import("../lib/stable-node.mjs"));
76
+ const { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } = await kernelImport("attachments", () => import("../lib/attachments.mjs"));
77
+ const { observeInstanceGit, diffInstanceFile } = await kernelImport("instance-git", () => import("../lib/instance-git.mjs"));
78
+ const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstanceSameWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
79
+ const { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } = await kernelImport("retire-output", () => import("../lib/retire-output.mjs"));
80
+ const { livenessWord, lostLine, statusWord } = await kernelImport("status-words", () => import("../lib/status-words.mjs"));
81
+ const { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } = await kernelImport("retained-after-retire", () => import("../lib/retained-after-retire.mjs"));
68
82
  const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
69
- import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposition, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
70
- import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mjs";
71
- import { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } from "../lib/deployments.mjs";
72
- import { observeResolvedDeployment } from "../lib/resolved-deployment.mjs";
73
- import { SESSION_RESUME_FEATURE } from "../lib/session-resume-contract.mjs";
83
+ const { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposition, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } = await kernelImport("instance-inspect", () => import("../lib/instance-inspect.mjs"));
84
+ const { readEvents, setWaiting, incarnationOf } = await kernelImport("instance-events", () => import("../lib/instance-events.mjs"));
85
+ const { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } = await kernelImport("deployments", () => import("../lib/deployments.mjs"));
86
+ const { observeResolvedDeployment } = await kernelImport("resolved-deployment", () => import("../lib/resolved-deployment.mjs"));
87
+ const { SESSION_RESUME_FEATURE } = await kernelImport("session-resume-contract", () => import("../lib/session-resume-contract.mjs"));
74
88
 
75
89
  const rawArgs = process.argv.slice(2);
76
90
  /** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
@@ -1776,7 +1790,7 @@ function standaloneCatalogVersion(ref) {
1776
1790
  async function discoverForCli(ctx, bail) {
1777
1791
  // The standalone case (decisions 10/25) is a discovery too: the repo's own view
1778
1792
  // plus the kernel's oats.core default — discoverOrStandalone decides.
1779
- try { const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs"); return await discoverOrStandalone(ctx.local, { deployment: ctx.deploymentDir, remoteOptions: ctx.remoteOptions }); }
1793
+ try { const { discoverOrStandalone } = await import("../lib/member-clone.mjs"); return await discoverOrStandalone(ctx.local, { deployment: ctx.deploymentDir, remoteOptions: ctx.remoteOptions }); }
1780
1794
  catch (e) {
1781
1795
  if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details ?? e.provenance);
1782
1796
  throw e;
@@ -2225,7 +2239,7 @@ function sharedTeamRows(discovery) {
2225
2239
  * computer (member clones and the rule that found each, disabled souls, the lock); file locations with
2226
2240
  * browsable urls; each catalog package's newer version, when the official catalog has one. */
2227
2241
  async function workspaceStatusFacts(result, discovery, lock, ctx) {
2228
- const { memberCloneOf } = await import("../lib/instance-resolution.mjs");
2242
+ const { memberCloneOf } = await import("../lib/member-clone.mjs");
2229
2243
  const { browseUrl } = remoteModule;
2230
2244
  const defaults = discovery.standalone === true ? {} : (discovery.workspace?.defaults ?? {});
2231
2245
  const rows = (entries) => Object.entries(entries && typeof entries === "object" ? entries : {}).map(([name, v]) => ({ name, from: v === "off" ? null : v?.from ?? null, off: v === "off" })).sort((a, b) => (a.name < b.name ? -1 : 1));
@@ -2242,7 +2256,7 @@ async function workspaceStatusFacts(result, discovery, lock, ctx) {
2242
2256
  });
2243
2257
  result.disabledSouls = [...(Array.isArray(ctx.local?.souls?.disabled) ? ctx.local.souls.disabled : [])];
2244
2258
  result.lock = { path: join(ctx.deploymentDir, LOCK_FILE), lockfileVersion: lock.lockfileVersion ?? null };
2245
- const { compareSemver } = await import("../lib/servers.mjs");
2259
+ const { compareSemver } = await import("../lib/semver.mjs");
2246
2260
  let catalog = null; try { catalog = officialPackageCatalog(); } catch { catalog = null; }
2247
2261
  const cat = catalog && typeof catalog === "object" ? (catalog.packages && typeof catalog.packages === "object" && !("url" in catalog.packages) ? catalog.packages : catalog) : {};
2248
2262
  for (const p of result.packages) {
@@ -2668,12 +2682,12 @@ async function statusDrift(data) {
2668
2682
  let discovery;
2669
2683
  // The standalone view (decisions 10/25) is a discovery too: drift of a standalone
2670
2684
  // instance is computed against its member's current state, not reported "unreachable".
2671
- try { const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs"); discovery = await discoverOrStandalone(ctx.local, { lock, remoteOptions: remoteOptionsFromEnv() }); }
2685
+ try { const { discoverOrStandalone } = await import("../lib/member-clone.mjs"); discovery = await discoverOrStandalone(ctx.local, { lock, remoteOptions: remoteOptionsFromEnv() }); }
2672
2686
  catch (e) {
2673
2687
  const reason = e?.details?.reason ? `${e.code}: ${e.details.reason}` : (e?.code || e?.message || "unknown");
2674
2688
  return { drift: new Map(), soul: new Map(), souls, unreachable: { code: e?.code ?? null, reason, message: e?.message ?? String(e) }, local: ctx.local, discovery: null };
2675
2689
  }
2676
- const { driftOf, soulDriftOf } = await import("../lib/materialize.mjs");
2690
+ const { driftOf, soulDriftOf } = await import("../lib/drift.mjs");
2677
2691
  const drift = new Map();
2678
2692
  const soul = new Map();
2679
2693
  for (const a of data) for (const i of a.instances || []) {
@@ -2834,7 +2848,8 @@ async function status() {
2834
2848
  if (a.description) console.log(` ${a.description}`);
2835
2849
  for (const i of a.instances) {
2836
2850
  // Feature instance-background: the row is marked; it is listed like any other.
2837
- console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${i.retirePending ? "RETIRING" : livenessWord(i)} (branch ${i.branch || "?"}, ${i.work || "?"})${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
2851
+ console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${statusWord(i)} (branch ${i.branch || "?"}, ${i.work || "?"})${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
2852
+ { const lost = lostLine(i); if (lost) console.log(` ${lost}`); }
2838
2853
  // Feature waiting-on-you: non-null only on a running row; the reader has
2839
2854
  // already validated the message (one line, no control characters).
2840
2855
  if (i.running === true && i.waitingOnYou) console.log(` ! needs input (${i.waitingOnYou.reason ?? "unknown"})${i.waitingOnYou.message ? `: ${i.waitingOnYou.message}` : ""}`);
@@ -2854,8 +2869,6 @@ async function status() {
2854
2869
  }
2855
2870
  }
2856
2871
 
2857
- /** A status row's liveness in text: `running` null (a server that cannot be read, a Herdr home) is unknown, never idle. */
2858
- const livenessWord = (i) => i.running === true ? "RUNNING" : i.running === false ? "idle" : "unknown";
2859
2872
  /** The flags `oats spawn` reads: those taking a value, and switches. `--provider` takes two words.
2860
2873
  * `--instance` is refused by a local spawn (with its replacement) but still travels to an older
2861
2874
  * host through `--server`, whose route reads it. `--max-age` reaches here only on a preview or an
@@ -4462,7 +4475,10 @@ async function serverCmd() {
4462
4475
  for (const g of out.groups) {
4463
4476
  console.log(` ${g.server}${g.label && g.label !== g.server ? ` ${g.label}` : ""} [${g.id}] ssh ${g.target.sshHost} workspace ${g.target.workspace}${g.registrationPresent ? "" : " (registration removed or changed; saved routes only)"}`);
4464
4477
  console.log(g.probe?.ok ? ` reachable, ${g.souls.length} soul(s)` : ` UNREACHABLE: ${g.probe?.error?.message || "?"}`);
4465
- for (const i of g.instances) console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${i.missingRemotely ? "GONE on the host (saved route is stale: oats server forget)" : i.running === true ? "RUNNING" : i.running === false ? "idle" : "unknown"}${i.retirePending ? " RETIRING" : ""}${i.rollbackIncomplete ? " QUARANTINED" : ""}${i.savedRoute ? "" : " (observed only, no saved route)"}${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
4478
+ for (const i of g.instances) {
4479
+ console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${i.missingRemotely ? "GONE on the host (saved route is stale: oats server forget)" : livenessWord(i)}${i.retirePending ? " RETIRING" : ""}${i.rollbackIncomplete ? " QUARANTINED" : ""}${i.savedRoute ? "" : " (observed only, no saved route)"}${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
4480
+ const lost = lostLine(i, { host: g.target.sshHost || g.server }); if (lost) console.log(` ${lost}`);
4481
+ }
4466
4482
  for (const f of g.retireFailures || []) console.log(` ! deferred retirement of ${f.instance} (${f.agent}) FAILED there${f.error?.message ? `: ${f.error.message}` : ""}${f.retry ? ` — retry on the host: ${f.retry}` : ""}`);
4467
4483
  }
4468
4484
  console.log(` bounds: ${out.bounds.perTargetTimeoutMs} ms per target within ${out.bounds.budgetMs} ms, ${out.bounds.elapsedMs} ms used`);
@@ -4859,7 +4875,10 @@ async function serverRouteCmd() {
4859
4875
  console.log(`oats status — server ${id} (ssh ${r.target.sshHost}, workspace ${r.target.workspace})\n`);
4860
4876
  for (const a of r.agents || []) {
4861
4877
  console.log(` ${a.name} [work: ${a.work || "checkout"}, repo: ${a.repo || "?"}]`);
4862
- for (const i of a.instances || []) console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${i.retirePending ? "RETIRING" : livenessWord(i)}${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
4878
+ for (const i of a.instances || []) {
4879
+ console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${statusWord(i)}${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
4880
+ const lost = lostLine(i, { host: r.target.sshHost || id }); if (lost) console.log(` ${lost}`);
4881
+ }
4863
4882
  }
4864
4883
  const snaps = r.snapshots || [];
4865
4884
  if (snaps.length) console.log(`\n spawned from this machine: ${snaps.map((s) => s.instance).join(", ")}`);
@@ -655,6 +655,18 @@ home has its own copy under `<home>/.oats/modules/<capability>/`
655
655
  ([souls-and-instances.md](souls-and-instances.md)). The store is a cache; it
656
656
  is safe to delete.
657
657
 
658
+ ## The compile cache
659
+
660
+ Every `oats` command keeps Node's compile cache in `~/.oats/compile-cache`
661
+ (`$OATS_HOME_DIR/compile-cache` when `OATS_HOME_DIR` is set), so a command
662
+ does not recompile the kernel each time it starts. The CLI creates the
663
+ directory mode 0700. It is a cache: delete it at any time; it holds one
664
+ subdirectory per Node version, so it grows a little with each Node upgrade.
665
+ Node's own variables override it: `NODE_COMPILE_CACHE=<dir>` moves it there,
666
+ and `NODE_DISABLE_COMPILE_CACHE=1` turns it off. A cache that cannot be
667
+ written means no cache, never a different answer. Hooks and other processes the
668
+ CLI starts do not inherit it.
669
+
658
670
  ## What is not in it
659
671
 
660
672
  - **Which capabilities a soul gets:** the soul's `capabilities:` plus the
@@ -3332,7 +3332,8 @@ its absence.
3332
3332
  `lost` (the host went down, its tmux server died, or the harness was killed
3333
3333
  by a signal: the sweep brings it back when it can vouch for the loss,
3334
3334
  [Which losses come back](execution-targets.md#which-losses-come-back)), `stopped` (stopped with OATS:
3335
- `oats instance stop`, Desktop's Stop) or `exited` (the harness ended by
3335
+ `oats instance stop`, Desktop's Stop, or an `oats session restart` whose
3336
+ relaunch did not happen) or `exited` (the harness ended by
3336
3337
  itself: `/exit`, its own error). Present only on a row that reads
3337
3338
  `running: false` and records `launched: true`, a row at its fallback shell
3338
3339
  (`runtimeState: "shell"`) included; absent while it runs or reads unknown
@@ -3621,6 +3622,12 @@ route target:
3621
3622
  whose kernel predates the feature, and a saved route the host did not list
3622
3623
  carry no key ([`sameWork`](#row-same-work)). `oats status --server <id>
3623
3624
  --json` relays the host's answer verbatim, `sameWork` included.
3625
+ - **`sessionEnd`** (feature `session-resume`; relayed from 0.69.5) is on a row only
3626
+ when the host's row has the key, with the host's value: a host whose kernel
3627
+ predates the feature, a row the host reports without it (one that runs,
3628
+ for example), and a saved route the host did not list carry none. Its
3629
+ meaning and when the host sends it are the [local row's](#row-session-end).
3630
+ A value that is not `lost`, `stopped` or `exited` drops the key.
3624
3631
  - **`addressable`** (0.31): `true` for every row the host reports. Routed
3625
3632
  session and lifecycle commands reach it by `--home`, or by name when the
3626
3633
  name is unique on the host ([addressing](servers.md#run-there); a shared
@@ -1185,6 +1185,16 @@ it ends, before it ends it, so a home it was retiring reads `stopped`, never
1185
1185
  stop record itself cannot be written (a full disk) and the retire then fails
1186
1186
  as well: that home reads `lost`, as it did before 0.69.2.
1187
1187
 
1188
+ `oats session restart` records the stop of the session it replaces the same
1189
+ way, before it asks the harness to end (#1601): a restart whose relaunch
1190
+ fails, or that dies between the stop and the relaunch, leaves a home that
1191
+ reads `stopped`, so no resume starts again the launch it was replacing. The
1192
+ relaunch records a new start, which that record does not name. A restart
1193
+ whose stop is refused (`E_SESSION_STOP_FAILED`, the harness still there after
1194
+ the grace) keeps its record: should that harness die later, the home reads
1195
+ `stopped`, not `lost`. A restart of a home that does not run stops nothing and
1196
+ records nothing, so it keeps its reading.
1197
+
1188
1198
  #### How a session's end is read
1189
1199
 
1190
1200
  A launched home that does not run reads one of three ends, `sessionEnd` on
@@ -1198,10 +1208,18 @@ for its current start (`startId` in `instance.json`):
1198
1208
  | an exit marker that names it with a signal's status (128 and up: the harness alone was killed, an out-of-memory kill for example) | `lost` | when the sweep can vouch for the loss ([below](#which-losses-come-back)) |
1199
1209
  | neither (the host went down, or the tmux server died under the live harness) | `lost` | when the sweep can vouch for the loss |
1200
1210
 
1211
+ In text, `oats status`, `oats status --server <id>` and `oats server roster`
1212
+ print a `lost` row as `LOST`, where a `stopped` or `exited` row, or one
1213
+ without `sessionEnd`, prints `idle`, with one line under it naming the way
1214
+ back: `oats session start --resume --home <home>`, or the next sweep (`oats
1215
+ session resume`, which OATS Desktop and `oats tui` run when they open) when
1216
+ it can vouch for the loss. Both act on this machine's homes only, so a row
1217
+ of another host names the host to run them on.
1218
+
1201
1219
  The window a spawn or a start makes writes the exit marker,
1202
1220
  `.oats-start-exited`, when the harness exits; `oats instance stop` writes its
1203
- record, `.oats-stop.json`, and so does a retire, before it ends the window
1204
- (0.69.2). Both are kernel-private files of the home, not a
1221
+ record, `.oats-stop.json`, and so do a retire, before it ends the window
1222
+ (0.69.2), and `oats session restart`, before it stops the harness (#1601). Both are kernel-private files of the home, not a
1205
1223
  contract: read `sessionEnd`. A shutdown kills the window's shell with the
1206
1224
  harness, so a lost session leaves no marker. A home spawned before 0.69 and
1207
1225
  never restarted since names no start: it reads `stopped` only after a stop,
@@ -1325,13 +1343,17 @@ resumes it. So:
1325
1343
  - a loss first seen a day ago or more, or a session that died before any read
1326
1344
  of OATS saw it run, stays down.
1327
1345
 
1328
- Two limits follow from reading only what OATS saw:
1346
+ Three limits follow from reading only what OATS saw:
1329
1347
 
1330
1348
  - **After upgrading to 0.69**, open OATS Desktop or `oats tui`, or run `oats
1331
1349
  status`, once before you restart the computer, or nothing from before the
1332
1350
  upgrade comes back.
1333
1351
  - A whole boot with no OATS read leaves that boot unknown: what ran in it and
1334
1352
  was lost there is not resumed.
1353
+ - Clause 4 does not reach across a reboot. On a computer where nothing read
1354
+ OATS for more than a day before a restart (every agent already down, no
1355
+ client open), the first sweep after the restart can bring back a session
1356
+ that was lost during that quiet spell.
1335
1357
 
1336
1358
  Without a boot id (neither Linux nor macOS: both have one), clause 4 applies
1337
1359
  to every loss and the 3-resumes-per-boot guard (below) is off.
@@ -23,7 +23,10 @@ reference pages ([workspaces](workspaces.md), [souls and instances](souls-and-in
23
23
  and may never add one: with a dependency it could no longer ship in this
24
24
  tarball.
25
25
  - **`@awebai/oats-pi`** (`packages/pi/`): a thin pi adapter that exposes an
26
- instance's own resources. It registers no agent tools.
26
+ instance's own resources. It registers no agent tools. It ships no kernel:
27
+ `extension/core-loader.mjs` imports the kernel that launched the instance,
28
+ through the home's `oats` link, before any PATH or global lookup (the
29
+ order is in [its README](../packages/pi/README.md)).
27
30
  - **`oats.framework`** (`oats-package/`): the `oats.core`, `oats.setup`,
28
31
  `oats.support` and `oats.knowledge-theory` capabilities and the
29
32
  `knowledge-theory-expert` soul,
@@ -71,7 +74,7 @@ and the rules its tests pin.
71
74
 
72
75
  | path | contents |
73
76
  |---|---|
74
- | `bin/oats.mjs` | the CLI: argument parsing, JSON envelopes, the verbs |
77
+ | `bin/oats.mjs` | the CLI: argument parsing, JSON envelopes, the verbs. Its only static imports are Node built-ins and two dependency-free modules, `lib/compile-cache.mjs` and `lib/hot-reads.mjs`: it turns Node's compile cache on first, then imports the kernel and `yaml` with top-level `await import()`, in their order, because static imports are all parsed and linked before a module's body runs. A hot read (`version`, `session inspect`, `status`, `workspace status`, `instance events`, `instance waiting clear`, given only their own flags) imports only the leaves it uses, never `core.mjs` ([`hot-reads.mjs`](#kernel-modules)); every other command imports every module. A hot read takes its names from `lib/hot-reads.mjs`: a name newly used on a hot read's path must be listed there, under its import line, or its first use throws (a tripwire), and `test/cli-hot-reads.test.mjs` pins what each hot read must not load |
75
78
  | `lib/` | the kernel (below) |
76
79
  | `injects/` | the kernel and work-mode instruction blocks composed into every instance |
77
80
  | `skills/` | bootstrap skills shipped with the kernel |
@@ -96,6 +99,9 @@ and the rules its tests pin.
96
99
  | `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit. Its text rules (`decodeText`, `skillDocDescription`, the limits) are also the rules of `inspect --soul --skills` (`instance-inspect.mjs` `soulSkills`), which reads a soul copy's own skills locally, and of `--composed-skills` (`composedSkillsIn`), which adds the capability skills of the scratch composition |
97
100
  | `materialize.mjs` | the shared home composer for spawn and module upgrade: `stageMaterialize` stages module copies and derived files, then a durable rename journal commits or rolls back a replacement in an existing home; `moduleSkills` is the one rule for which skills a module gives, read over the fetched tree, or over a remote listing for the spawn preview (`plannedModuleSkills`) |
98
101
  | `instance-upgrade.mjs` | `planUpgrade` and `applyUpgrade`: verified package-module staging, provider adoption, idempotent forward completion, undo and retirement baseline refresh for a stopped local home, using the shared composer for derived home files |
102
+ | `compile-cache.mjs` | the CLI's Node compile cache (awebai/oats#1630): `$OATS_HOME_DIR/compile-cache`, made 0700, unless the caller's `NODE_COMPILE_CACHE` or `NODE_DISABLE_COMPILE_CACHE` decides; any failure is no cache and prints nothing, and `NODE_COMPILE_CACHE` is never put in the environment children inherit ([configuration](configuration.md#the-compile-cache)). Node built-ins only; kernel-private, not in `./core` |
103
+ | `hot-reads.mjs` | the CLI's hot reads (awebai/oats#1630): each one's form (its words and the flags it takes) and, for each import line of `bin/oats.mjs`, the leaves it loads in that line's place; a line it does not list loads nothing, and any other argv loads everything. A name a read does not list is a tripwire: destructuring it is free, and any use throws a `HotReadUnlisted` defect naming the read, the line and the name. `test/cli-hot-reads.test.mjs` runs each read with a load hook and pins what it must not load. Kernel-private, not in `./core` |
104
+ | `version.mjs`, `deployment-path.mjs`, `write-file-atomic.mjs`, `agents-root.mjs`, `soul-listing.mjs`, `instance-address.mjs`, `session-inspect.mjs`, `instance-listing.mjs`, `drift.mjs`, `package-catalog.mjs`, `member-clone.mjs`, `reserved-launch-env.mjs`, `automation-scope.mjs`, `automation-api.mjs`, `semver.mjs` | the leaves the hot reads load instead of the modules that re-export them (awebai/oats#1630): the version; the canonical deployment path; the atomic file write; the agents root; souls and instance homes; `resolveInstance`; `inspectInstanceSession`; `listInstances` and the status rows; soul and module drift; the official package catalog; discovery and member clones; the reserved launch environment; the automation scope; the automation API versions; `compareSemver`. Each name is still exported, under the same name, from the module it left (`core.mjs`, `packages.mjs`, `instance-lifecycle.mjs`, `materialize.mjs`, `instance-resolution.mjs`, `schedule.mjs`, `automations.mjs`, `servers.mjs`), so `./core` is unchanged (`test/core-exports.test.mjs`), and no leaf imports `core.mjs` or the module it left. Code a hot read reaches goes in a leaf, never in `core.mjs` |
99
105
  | `upgrade-state.mjs` | upgrade receipt state and the partial-upgrade guard used before session start; receipts remain lifecycle state, and provider adoption stays in the module's upgrade hook |
100
106
  | `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata. A home's record (`instance.json`) is read with `readHomeRecord`, which never throws: a record, an absent one, or one that is there and cannot be read, with the reason. Code that walks other homes (the listing, a retire's lineage repair) uses it, so that one home's record decides only for that home; `identifiedHomeRecord` is the one refusal (`E_UNIDENTIFIED_INSTANCE_HOME`) a lifecycle verb makes when it has resolved its home: `resolveRetireHome`, `startInstanceSession`, and `resolveTarget` in `instance-lifecycle.mjs` for the stop and retire plans. A plan reads its own home's record with `targetRecord` (the same refusal) and any other home's with `otherRecord` (absent or unreadable: nobody's parent or child) |
101
107
  | `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
@@ -127,6 +133,7 @@ and the rules its tests pin.
127
133
  | `login-environment.mjs` | the user's login environment a server OATS starts gets: the login shell's answer as one nonce-framed block on its stdout, bounded and accepted only whole ([execution targets](execution-targets.md#the-servers-start-environment)) |
128
134
  | `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`) as problems and warnings (`manifestContract`: an unknown, non-required hook event is a warning every reader reports), the hook environment rules, the readiness wire |
129
135
  | `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
136
+ | `status-words.mjs` | the word `oats status`, `oats status --server` and `oats server roster` print for an instance row (RUNNING, LOST, idle, unknown, RETIRING; the roster keeps its own suffixes) and the line under a LOST row that names the way back; rows in, strings out, the JSON untouched |
130
137
  | `retire-state.mjs` | a status row's `retire` (feature `status-retire-state`): `readRetireState`, the one read of the value, which the local row (`core.mjs` `retireStateOf`, from the marker, its result and the home's claim) and the remote roster's relay (`servers.mjs` `rowRetire`) both go through. Pure; status only reads, so nothing here takes a claim, removes a file or signals a process |
131
138
  | `retained-after-retire.mjs` | what retires left behind (recovery copies, retained worktrees) as `oats doctor` information lines: read-only, Git through `instance-git.mjs`'s helper-free reads |
132
139
  | `read-ahead.mjs`, `read-ahead-worker.mjs` | read-ahead for the tree digests (`fingerprintTrees`): while a digest reads a tree on the calling thread, a planner thread walks it in the digest's order and a few reader threads read the next files into the page cache, within a window of bytes and files ahead of the digest. The digest still reads and hashes every byte itself, so no value or error depends on it; one that cannot start or falls behind costs speed only |
@@ -134,7 +141,7 @@ and the rules its tests pin.
134
141
  | `session-input.mjs` | session inspection and input transport. `resolveAgentPane` is the one rule for which of a window's panes is the agent's (the `@oats-agent` mark, `AGENT_PANE_OPTION`, that the launches in `core.mjs` set); `harnessProcesses` (Stop) and the viewer use it too. `createSessionPaneInspector` resolves the agent's pane, then interprets it for both lifecycle inspection and status, sharing a lazy process scan across a status read; `core.mjs` batches pane reads per socket/session and applies its shared `harnessRunning` predicate |
135
142
  | `servers.mjs` | routing commands to a registered server |
136
143
  | `deployments.mjs` | this computer's deployments ([workspaces.md](workspaces.md#this-computers-deployments)): the per-user files `<OATS_HOME_DIR>/config/deployments.json` (the list, 0600 in a 0700 `config/`) and `config/deployments.lock` (`withDirLock`, waited for up to 3 s), the bounded no-follow read, the atomic write, the first-use `~/Agents` import (the real `$HOME`) and the five `E_DEPLOYMENTS_*` codes. `oats deployments`, onboard's `listed` and the auto-add write through it. `listResolved` is the auto-add: `bin/oats.mjs` sets it as the observer of `resolved-deployment.mjs` for the commands in its one table (`LISTS_ITS_DEPLOYMENT`), so it runs once per process on the deployment the command itself resolved. A listed deployment costs one bounded read (no lock, write, process or realpath), another spelling of it a realpath; a spelled root in a linked worktree or submodule (a `.git` file above it) is left to the commands that resolve its canonical root; a root under a temporary directory (`underTemporaryDirectory`, awebai/oats#1397) is never auto-added; only a path not listed is canonicalized and takes the lock, without waiting for it. It never throws or prints |
137
- | `resolved-deployment.mjs` | the deployment a command resolved: `loadLocal` (`workspace.mjs`) reports the directory it found as spelled, `ensureRoot` (`core.mjs`) the canonical one, and the observer the CLI set is called once, at exit, with the first canonical root (else the first spelled one), so an earlier spelling never stands for a root the command canonicalized. A no-op until the CLI sets one, so library callers and tests are unaffected. Dependency-free |
144
+ | `resolved-deployment.mjs` | the deployment a command resolved: `loadLocal` (`workspace.mjs`) reports the directory it found as spelled, `ensureRoot` (`agents-root.mjs`) the canonical one, and the observer the CLI set is called once, at exit, with the first canonical root (else the first spelled one), so an earlier spelling never stands for a root the command canonicalized. A no-op until the CLI sets one, so library callers and tests are unaffected. Dependency-free |
138
145
  | `launch-prompt-evidence.mjs` | private bounded storage of exact unmatched, stable-screen completed or flag-ignored notice frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
139
146
  | `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
140
147
  | `launch-prompt-fixtures.mjs` | the development-channel tolerance list (`launch-prompt-fixtures/dev-channel-confirmation.json`): engagement from the argv, the enumerated normalization, equality matching, the `flag-ignored` notice block, the running-session banner hint, what differed, and the Claude version read from the executable's path |
@@ -509,6 +516,38 @@ dependencies installed, `check`, `validate`, `pack:check` and the smoke test,
509
516
  and is the gate. Tests use local bare repositories and fakes; none contacts
510
517
  GitHub, aweb, Jira or Linear.
511
518
 
519
+ ### The TUI's tests on macOS
520
+
521
+ A pull request that touches `packages/tui/`, `packages/client/`, a
522
+ `test/tui-*.test.mjs` file or the workflow itself also runs
523
+ [`tui-macos.yml`](../.github/workflows/tui-macos.yml): every TUI test file,
524
+ `packages/tui/test/*.test.mjs` and `test/tui-*.test.mjs`, one file at a time
525
+ and each test within five minutes, on `macos-14` with tmux installed, in about
526
+ five minutes. Its last step fails the run if a test left a tmux server on the
527
+ default `oats` socket, as a hand-started run checks after each file; it does
528
+ not give each file a process group of its own, as a hand-started run does. The
529
+ TUI reads tables keyed by platform (the shared keymap's macOS chords) and
530
+ drives macOS's own tmux, whose output differs from Linux's, and Linux CI sees
531
+ neither ([#1608](https://github.com/awebai/oats/issues/1608),
532
+ [#1613](https://github.com/awebai/oats/issues/1613)). It runs at pull-request
533
+ time, not on the tag's macOS legs: a failure found on the tag costs a version,
534
+ and `release.yml` holds the publishing rights, so a TUI flake there would hold
535
+ a publication (the release lane's call, 2026-10-27).
536
+
537
+ The paths are the TUI's own. A change the TUI depends on outside them (`lib/`,
538
+ `bin/`, `test/helpers/`, `package.json`, `package-lock.json`) starts no run,
539
+ and nothing runs on a push to `main`: such a change wants hand-started macOS
540
+ runs of the TUI's files, at most ten files a run
541
+ ([Named test runs](named-test-runs.md)).
542
+
543
+ The job is not part of the gate above. A path filter that skips the workflow
544
+ reports no check, so a required check would hold every pull request that does
545
+ not touch the TUI. Its run on the pull request is that pull request's macOS
546
+ evidence. `test/tui-macos-workflow.test.mjs` pins its terms: the one trigger
547
+ and its paths, the read-only token, no secret, no artifact or cache, tmux, a
548
+ command that runs every TUI test file, and the leak check. Like the release's
549
+ workflows, it names its actions by commit (`test/workflow-no-cache.test.mjs`).
550
+
512
551
  **Test output is pristine.** A warning that a test expects is captured and
513
552
  asserted by the test, or by its fixture, and never left in the output: a line
514
553
  nobody asserted is then one nobody expected. The root run holds the rule
@@ -40,8 +40,8 @@ arrives from.
40
40
  ```yaml
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
- oats.okf: v5.5.0
44
- oats.aweb: v1.32.0
43
+ oats.okf: v5.6.0
44
+ oats.aweb: v1.32.1
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
package/docs/knowledge.md CHANGED
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
6
6
  owns its knowledge format, instructions and promotion procedure. The model is
7
7
  in [Knowledge, instances and evolving expertise](knowledge-theory.md).
8
8
 
9
- This is the operator guide for **oats.okf 5.5.0** (OATS **>=0.49.0**). Provider implementation and
9
+ This is the operator guide for **oats.okf 5.6.0** (OATS **>=0.69.2**). Provider implementation and
10
10
  recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
11
11
 
12
12
  | Surface | What it holds |
@@ -25,7 +25,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
25
25
  ```yaml
26
26
  # oats-workspace.yaml (excerpt)
27
27
  packages:
28
- oats.okf: v5.5.0
28
+ oats.okf: v5.6.0
29
29
  defaults:
30
30
  knowledge: { oats.okf: { from: package } }
31
31
  stores:
@@ -50,10 +50,11 @@ settings:
50
50
 
51
51
  Upgrading from 4.x requires the ordered
52
52
  [5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
53
- just editing a version line. For 5.5.0, OATS >=0.49.0 remains required:
54
- that kernel first supports the public source-event lookup after retirement.
53
+ just editing a version line. 5.6.0 requires OATS >=0.69.2: its
54
+ `knowledge-harvester` and `knowledge-maintainer` souls say `background: true`,
55
+ which an older kernel refuses. Upgrade OATS first, then the package.
55
56
 
56
- **Upgrade:** pin `oats.okf: v5.5.0` and run `oats sync`. Only new spawns get
57
+ **Upgrade:** pin `oats.okf: v5.6.0` and run `oats sync`. Only new spawns get
57
58
  the capability-owned harvest duty, skill and spawn-recorded policy. Existing
58
59
  homes keep their copied provider even after a session restart; from 5.4.0, a
59
60
  stopped 5.x home can move with `oats instance upgrade` (OATS 0.68.0 and
@@ -65,7 +66,9 @@ remain. From 5.2.x, 5.3.0 adds the long-lived-role checkpoints and the
65
66
  checkpoint line in `log.md`, drops the available-memory gate, and has the
66
67
  proposer name each harvester (`--name`, below). 5.5.0 adds the incarnation to
67
68
  the proposal's `Source:` line (below): a harvester on 5.4.0 or older refuses
68
- that line, so run `oats sync` to 5.5.0 before instances on 5.5.0 propose.
69
+ that line, so run `oats sync` to 5.5.0 or later before instances on 5.5.0
70
+ propose. 5.6.0 lists new harvesters and knowledge maintainers under the
71
+ clients' Background section; existing ones do not move.
69
72
 
70
73
  ### Bindings document
71
74
 
@@ -1,8 +1,10 @@
1
1
  # Named test runs on macOS and Linux
2
2
 
3
3
  Pull-request CI runs the tests on Linux, in its own way: sharded, and with no
4
- working `systemctl --user`. Some tests need something CI does not give them,
5
- and two workflows run them by hand:
4
+ working `systemctl --user`. Beside it, a pull request that touches the TUI
5
+ also runs the TUI's tests on macOS ([The TUI's tests on
6
+ macOS](implementation.md#the-tuis-tests-on-macos)). Some tests need something
7
+ CI does not give them, and two workflows run them by hand:
6
8
 
7
9
  - **macOS.** Some tests rest on what only macOS does: a file system that
8
10
  ignores case, `/var` and `/tmp` as links, long temporary paths, the BSD
@@ -9,12 +9,12 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.16.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
- | `oats.okf` | `v5.5.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.32.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
- | `oats.engineering` | `v1.16.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
12
+ | `oats.framework` | `oats-framework/v1.16.3` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
+ | `oats.okf` | `v5.6.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
+ | `oats.aweb` | `v1.32.1` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
+ | `oats.engineering` | `v1.17.2` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
- | `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
17
+ | `oats.cloning` | `v1.1.0` | `oats.cloning` | `cloner` |
18
18
  | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
19
19
  | `oats.linear` | `v1.0.1` | `oats.linear` (tasks) | |
20
20
  | `oats.apps` | `v1.0.0` | `oats.folio`, `oats.library` | |
@@ -30,7 +30,7 @@ no lock and adds nothing to an existing workspace.
30
30
  ## Find and use packages
31
31
 
32
32
  - A workspace pins an official package by **bare version** in its
33
- `packages:` map (`oats.okf: v5.5.0`); `oats sync` resolves it through the
33
+ `packages:` map (`oats.okf: v5.6.0`); `oats sync` resolves it through the
34
34
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
35
35
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
36
36
  not join a team or adopt the publisher's workspace. See
package/docs/packages.md CHANGED
@@ -44,14 +44,14 @@ whole organisation:
44
44
 
45
45
  ```yaml
46
46
  packages:
47
- oats.okf: v5.5.0 # bare version → the official catalog
47
+ oats.okf: v5.6.0 # bare version → the official catalog
48
48
  acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
49
49
  ```
50
50
 
51
- - **Bare version** (`v5.5.0`, `5.5.0`, `1.0.0-rc.1`): the id is looked up in
51
+ - **Bare version** (`v5.6.0`, `5.6.0`, `1.0.0-rc.1`): the id is looked up in
52
52
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
53
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v5.5.0` or `oats-framework/v1.16.1`) and the payload path. An id
54
+ convention (`v5.6.0` or `oats-framework/v1.16.3`) and the payload path. An id
55
55
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
56
  a package outside the catalog"). The catalog is the reviewed official list
57
57
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,9 +74,9 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.16.1
78
- oats.okf: v5.5.0
79
- oats.aweb: v1.32.0
77
+ oats.framework: v1.16.3
78
+ oats.okf: v5.6.0
79
+ oats.aweb: v1.32.1
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
82
82
  defaults:
@@ -105,7 +105,7 @@ decision recorded in the lock.
105
105
  $ oats sync
106
106
  workspace acme (github.com/acme/agents @ 3f2a9c1e)
107
107
  members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
108
- packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.5.0 ✓ (@ 4817c74e)
108
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.6.0 ✓ (@ ec169fd6)
109
109
  changed acme.tools — → 0.4.0 (@ 47f4b816)
110
110
  souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
111
111
  teams platform (shared) · this deployment's: oats teams
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
134
134
  ## `oats package add | remove`
135
135
 
136
136
  ```bash
137
- oats package add oats.aweb v1.32.0 # a catalog version
137
+ oats package add oats.aweb v1.32.1 # a catalog version
138
138
  oats package add acme.tools git:github.com/acme/tools@v0.4.0
139
139
  oats package remove acme.tools
140
140
  ```
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
160
160
  "source": "catalog:oats.okf",
161
161
  "url": "https://github.com/awebai/oats-okf.git",
162
162
  "path": "oats-package",
163
- "version": "5.5.0",
164
- "commit": "4817c74ede1e1b578e5a78759862964ea077ded1",
163
+ "version": "5.6.0",
164
+ "commit": "ec169fd6ab20abea1eea26fe8eff3a9b547e7210",
165
165
  "integrity": "sha256-…",
166
166
  "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
167
167
  },
@@ -352,12 +352,12 @@ A soul that names one of the package's capabilities with
352
352
  {
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
- "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.5.0", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.16.1", "path": "oats-package" }
355
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.6.0", "path": "oats-package" },
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.16.3", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.16.1`
362
- resolves to tag `oats-framework/v1.16.1`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.16.3`
362
+ resolves to tag `oats-framework/v1.16.3`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.