@awebai/oats 0.69.4 → 0.69.6

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 (74) hide show
  1. package/bin/oats.mjs +141 -364
  2. package/docs/configuration.md +12 -0
  3. package/docs/design/2026-09-26-okf-knowledge-operations.md +2 -0
  4. package/docs/design/2026-10-29-warm-reader.md +261 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +258 -13
  7. package/docs/execution-targets.md +36 -5
  8. package/docs/implementation.md +34 -9
  9. package/docs/integrations.md +2 -2
  10. package/docs/knowledge.md +18 -8
  11. package/docs/named-test-runs.md +4 -0
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +14 -14
  14. package/docs/release-notes/v0.69.5.md +146 -0
  15. package/docs/release-notes/v0.69.6.md +165 -0
  16. package/docs/schedules.md +8 -1
  17. package/docs/tui.md +23 -5
  18. package/docs/upgrading.md +20 -5
  19. package/docs/workspaces.md +2 -2
  20. package/lib/agents-root.mjs +51 -0
  21. package/lib/argv.mjs +41 -0
  22. package/lib/automation-api.mjs +7 -0
  23. package/lib/automation-scope.mjs +37 -0
  24. package/lib/automations.mjs +63 -12
  25. package/lib/captured-context.mjs +12 -0
  26. package/lib/compile-cache.mjs +36 -0
  27. package/lib/core.mjs +39 -1348
  28. package/lib/deployment-path.mjs +127 -0
  29. package/lib/deployments.mjs +2 -2
  30. package/lib/drift.mjs +95 -0
  31. package/lib/hot-reads.mjs +137 -0
  32. package/lib/install-stamp.mjs +61 -0
  33. package/lib/instance-address.mjs +21 -0
  34. package/lib/instance-events.mjs +8 -6
  35. package/lib/instance-lifecycle.mjs +4 -16
  36. package/lib/instance-listing.mjs +738 -0
  37. package/lib/instance-resolution.mjs +5 -166
  38. package/lib/kernel-features.mjs +10 -0
  39. package/lib/local-edit.mjs +1 -1
  40. package/lib/local-inputs.mjs +3 -0
  41. package/lib/materialize.mjs +2 -87
  42. package/lib/member-clone.mjs +192 -0
  43. package/lib/package-catalog.mjs +93 -0
  44. package/lib/packages.mjs +4 -24
  45. package/lib/read-call.mjs +143 -0
  46. package/lib/reader.mjs +203 -0
  47. package/lib/remote.mjs +47 -6
  48. package/lib/reserved-launch-env.mjs +20 -0
  49. package/lib/resolved-deployment.mjs +13 -5
  50. package/lib/roster-read.mjs +199 -0
  51. package/lib/schedule.mjs +5 -29
  52. package/lib/semver.mjs +12 -0
  53. package/lib/servers.mjs +10 -12
  54. package/lib/session-end.mjs +3 -2
  55. package/lib/session-input.mjs +35 -11
  56. package/lib/session-inspect.mjs +219 -0
  57. package/lib/soul-listing.mjs +216 -0
  58. package/lib/status-words.mjs +30 -0
  59. package/lib/version.mjs +9 -0
  60. package/lib/workspace-read.mjs +160 -0
  61. package/lib/write-file-atomic.mjs +28 -0
  62. package/package-catalog.json +4 -4
  63. package/package.json +1 -1
  64. package/packages/client/cli-locator.mjs +1 -0
  65. package/packages/client/cli-probe-contract.mjs +4 -2
  66. package/packages/client/deployment-observer.mjs +8 -3
  67. package/packages/client/deployment-panel.mjs +17 -1
  68. package/packages/client/deployment-read-cli.mjs +48 -27
  69. package/packages/client/own-codes.mjs +3 -0
  70. package/packages/client/warm-reader.mjs +241 -0
  71. package/packages/tui/lib/client.mjs +2 -1
  72. package/packages/tui/lib/read.mjs +59 -11
  73. package/packages/tui/lib/store.mjs +7 -3
  74. package/skills/oats-getting-started/SKILL.md +3 -3
@@ -0,0 +1,93 @@
1
+ /** The official package catalog (package-catalog.json, or the file OATS_PACKAGE_CATALOG names) and the slot names a
2
+ * soul's capabilities fill (LAYERS). A leaf (awebai/oats#1630): `oats workspace status` reads them
3
+ * without loading core.mjs, which imports what it still uses and re-exports what it exported. */
4
+ import { existsSync, readFileSync } from "node:fs";
5
+ import { join } from "node:path";
6
+ import { recordLocalInput } from "./local-inputs.mjs";
7
+ import { oatsError } from "./errors.mjs";
8
+ import { parseStrictJson, lineAt } from "./canonical-json.mjs";
9
+ import { PKG_ROOT } from "./version.mjs";
10
+
11
+ /** The package and capability id grammar (namespaced, lowercase): an id names a
12
+ * directory (a home's module copy), so no path spelling fits it. */
13
+ const PACKAGE_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
14
+
15
+ // ---------- capability slots ----------
16
+ export const LAYERS = ["knowledge", "messaging", "tasks"];
17
+
18
+ /** Official package catalog: identity + discovery ONLY — resolving through it
19
+ * never advances a lock and never grants executable trust (contract §1).
20
+ * Workstream 3 seeds the kernel-bundled catalog; OATS_PACKAGE_CATALOG points
21
+ * tests/deployments at an alternate catalog JSON ({ packages: { <id>: { url, ref? } } }). */
22
+ export function officialPackageCatalog() {
23
+ return readCatalogFile().packages;
24
+ }
25
+ /** Parse the catalog file once: { packages: { <id>: { url, ref?, path? } },
26
+ * capabilities?: { <legacy capability id>: <package id> } }. Both maps are
27
+ * returned with a null prototype so inherited Object.prototype names can never
28
+ * impersonate a catalog entry. */
29
+ function readCatalogFile() {
30
+ const file = officialCatalogFile();
31
+ const empty = { packages: Object.create(null), capabilities: Object.create(null), file };
32
+ // An OATS_PACKAGE_CATALOG override is local configuration (observation.localRevision); the bundled
33
+ // catalog belongs to the kernel install.
34
+ const override = !!process.env.OATS_PACKAGE_CATALOG;
35
+ if (!existsSync(file)) { if (override) recordLocalInput(file, null); return empty; }
36
+ const text = readFileSync(file, "utf8");
37
+ if (override) recordLocalInput(file, text);
38
+ return parsePackageCatalog(text, file);
39
+ }
40
+ /** A package catalog's text, parsed and checked as the kernel reads it (named `file` in errors):
41
+ * { packages, capabilities, file }, both maps null-prototype; invalid-source when it is broken. */
42
+ export function parsePackageCatalog(text, file) {
43
+ let doc;
44
+ try { doc = JSON.parse(text); }
45
+ catch (e) {
46
+ // JSON.parse does not say where; the kernel's strict reader (same grammar) locates the error.
47
+ let line;
48
+ try { parseStrictJson(text, { maxBytes: 64 * 1024 * 1024 }); } catch (s) { if (Number.isInteger(s.provenance?.offset)) line = lineAt(text, s.provenance.offset); }
49
+ throw oatsError("invalid-source", `broken package catalog ${file}${line ? ` (line ${line})` : ""}: ${e.message}`);
50
+ }
51
+ if (!doc || typeof doc !== "object" || Array.isArray(doc)) throw oatsError("invalid-source", `broken package catalog ${file}: root must be a JSON object`);
52
+ const out = { packages: Object.create(null), capabilities: Object.create(null), file };
53
+ const packages = doc.packages;
54
+ if (packages !== undefined) {
55
+ if (packages === null || typeof packages !== "object" || Array.isArray(packages)) throw oatsError("invalid-source", `broken package catalog ${file}: "packages" must be an object map`);
56
+ for (const [id, entry] of Object.entries(packages)) out.packages[id] = entry;
57
+ }
58
+ // Capability aliases (0.19.1 migration contract): legacy capability id →
59
+ // official package id. Identity mappings (package id == capability id) need
60
+ // no entry; an alias exists for capabilities a package exports under another
61
+ // package identity (oats.developer is exported by package oats.engineering).
62
+ //
63
+ // The object form may also carry "capability": the id the package exports
64
+ // TODAY in place of the legacy id (a RENAMING alias, the oas.* → oats.*
65
+ // migration contract). A plain alias promises the package exports the legacy
66
+ // id itself; a renaming alias promises it exports the successor instead.
67
+ const aliases = doc.capabilities;
68
+ if (aliases !== undefined) {
69
+ if (aliases === null || typeof aliases !== "object" || Array.isArray(aliases)) throw oatsError("invalid-source", `broken package catalog ${file}: "capabilities" must be a map of capability id → package id`);
70
+ for (const [capId, target] of Object.entries(aliases)) {
71
+ const obj = typeof target === "string" ? { package: target } : (target && typeof target === "object" && !Array.isArray(target) ? target : undefined);
72
+ const pkgId = obj?.package;
73
+ if (typeof pkgId !== "string" || !PACKAGE_ID_RE.test(pkgId)) throw oatsError("invalid-source", `broken package catalog ${file}: capability alias "${capId}" must name a package id (string, or { "package": "<id>" })`);
74
+ if (!PACKAGE_ID_RE.test(capId)) throw oatsError("invalid-source", `broken package catalog ${file}: capability alias key "${capId}" is not a valid capability id`);
75
+ const renamed = obj.capability;
76
+ if (renamed !== undefined && (typeof renamed !== "string" || !PACKAGE_ID_RE.test(renamed))) throw oatsError("invalid-source", `broken package catalog ${file}: capability alias "${capId}" has an invalid "capability" rename target`);
77
+ out.capabilities[capId] = renamed && renamed !== capId ? { package: pkgId, capability: renamed } : pkgId;
78
+ }
79
+ }
80
+ return out;
81
+ }
82
+
83
+ /** The effective official catalog file: `OATS_PACKAGE_CATALOG`, else the bundled one. */
84
+ export function officialCatalogFile() {
85
+ return process.env.OATS_PACKAGE_CATALOG || join(PKG_ROOT, "package-catalog.json");
86
+ }
87
+
88
+ /** The catalog's legacy-capability → official-package aliases (null-prototype). */
89
+ export function officialCapabilityAliases() {
90
+ return readCatalogFile().capabilities;
91
+ }
92
+
93
+ export { PACKAGE_ID_RE, readCatalogFile };
package/lib/packages.mjs CHANGED
@@ -41,13 +41,15 @@
41
41
  * is exported below as a thin function throwing E_REMOVED so nothing breaks at
42
42
  * import time; callers are deleted in the next phase.
43
43
  */
44
- import { closeSync, existsSync, fchmodSync, mkdirSync, mkdtempSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, lstatSync } from "node:fs";
44
+ import { existsSync, mkdtempSync, readFileSync, rmSync, lstatSync } from "node:fs";
45
45
  import { tmpdir } from "node:os";
46
- import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
46
+ import { isAbsolute, join, posix, relative, resolve, sep } from "node:path";
47
47
  import { recordLocalInput } from "./local-inputs.mjs";
48
48
  import { oatsError as baseOatsError } from "./errors.mjs";
49
49
  import * as defaultRemote from "./remote.mjs";
50
50
  import { manifestContractProblems } from "./capability-contract.mjs";
51
+ import { writeFileAtomic } from "./write-file-atomic.mjs";
52
+ export { writeFileAtomic } from "./write-file-atomic.mjs";
51
53
 
52
54
  export const LOCK_FILE = "oats-lock.json";
53
55
  export const LOCK_VERSION = 3;
@@ -98,28 +100,6 @@ export function assertNoSymlinkedParents(scopeDir, leafDir, what) {
98
100
  }
99
101
  }
100
102
 
101
- /** Sibling temp + rename: replaces the directory entry itself, never writing
102
- * THROUGH a pre-planted symlink at `file`. The new file's permission bits are the process's default
103
- * (its umask) unless `mode` gives them: then they are exactly `mode`, and in force before a byte of
104
- * `contents` is written, so a file kept private is never readable by others on the way. */
105
- export function writeFileAtomic(file, contents, { mode } = {}) {
106
- mkdirSync(dirname(file), { recursive: true });
107
- const tmp = join(dirname(file), `.${basename(file)}.oats-tmp-${process.pid}`);
108
- try {
109
- if (mode === undefined) writeFileSync(tmp, contents);
110
- else {
111
- // A new file (one left by a killed process of this pid goes first; "wx" opens nothing that is
112
- // there), created with no more than `mode` (the umask only takes bits away), then set to it exactly.
113
- rmSync(tmp, { force: true });
114
- const fd = openSync(tmp, "wx", mode);
115
- try { fchmodSync(fd, mode); writeFileSync(fd, contents); } finally { closeSync(fd); }
116
- }
117
- renameSync(tmp, file);
118
- } finally {
119
- // A failed removal is not answered: when the write or the rename failed, that error is (#1076).
120
- try { rmSync(tmp, { force: true }); } catch { /* the first error is the one answered */ }
121
- }
122
- }
123
103
 
124
104
  /** Exact copy via `writeFileAtomic` (copyFileSync would follow a destination symlink). */
125
105
  export function copyFileAtomic(from, to) {
@@ -0,0 +1,143 @@
1
+ /** lib/read-call.mjs — one call of a deployment read (awebai/oats#1630): the scope `oats status` and
2
+ * `oats workspace status` run in (lib/roster-read.mjs, lib/workspace-read.mjs), so that the CLI runs
3
+ * each once and a long-lived process answers them many times with the same code.
4
+ *
5
+ * In a one-shot CLI, process exit is what forgets a read's state. A call does that itself: it starts
6
+ * by resetting every piece of module-level state its reads can reach (READ_STATE, which
7
+ * test/read-call-state.test.mjs pins against a scan of the reads' import closure), and ends by draining
8
+ * what its read session found worth telling the operator. A read answers `{ exit, answer, stderr }`:
9
+ * `answer` the JSON value the CLI prints, every refusal an answer too (refuse); `stderr` the read
10
+ * session's notices, as the CLI says them. Each read has a data layer beside it (`…View`): `view`, what
11
+ * bin's text renderer reads, in place of `answer`, without the JSON-only work.
12
+ *
13
+ * The context: `dir` (absolute), `maxAge` (null, or the --max-age seconds: parseMaxAge), `session` (a
14
+ * function answering the caller's read session, created by callSession: the CLI's is created at its
15
+ * first remote read and carries the CLI's exit and signal listeners; a reader's is created at the start
16
+ * of the request), `cacheDir` (the remote cache, absolute, or none), and `deployments` (an observer of
17
+ * the deployment the call resolves, settled when the call ends; the CLI passes none and settles its own
18
+ * at exit, lib/resolved-deployment.mjs). A call registers no process listener and closes no session:
19
+ * the caller closes it. Nor does it read argv or the working directory: the caller owns the process's
20
+ * cwd, which still reaches the children the reads run by name (tmux, git: a relative or empty PATH entry
21
+ * is resolved against it), so a caller answering for a deployment runs the call with that deployment
22
+ * as its cwd, as the CLI does when run there. Kernel-private, not exported from `./core`. Dependency-free.
23
+ */
24
+ import { resetRuntimeNames, runtimeNameWarning } from "./deprecation.mjs";
25
+ import { OWN_NAME_FAILURES } from "./errors.mjs";
26
+ import { activateLocalInputs, localRevision, resetLocalInputs } from "./local-inputs.mjs";
27
+ import { createReadSession, MAX_AGE_LIMIT, READ_REMOTE_BUDGET_MS, resetGitProbes, resetSshCommand } from "./remote.mjs";
28
+ import { observeResolvedDeployment, resetResolvedDeployment, settleResolvedDeployment } from "./resolved-deployment.mjs";
29
+
30
+ /** Every module-level binding the reads' import closure writes, and what a call does with it: `reset`
31
+ * (forgotten at the start of each call), `scoped` (set and ended by the call itself) or `safe` (kept
32
+ * across calls, and why that cannot change an answer). A binding the scan finds that is not here fails
33
+ * test/read-call-state.test.mjs, by module and name. */
34
+ export const READ_STATE = [
35
+ { module: "lib/deprecation.mjs", binding: "sources", how: "reset", reset: resetRuntimeNames },
36
+ { module: "lib/local-inputs.mjs", binding: "inputs", how: "reset", reset: resetLocalInputs },
37
+ { module: "lib/remote.mjs", binding: "sshCommandCache", how: "reset", reset: resetSshCommand },
38
+ { module: "lib/remote.mjs", binding: "gitVersions", how: "reset", reset: resetGitProbes },
39
+ { module: "lib/remote.mjs", binding: "protocolPins", how: "reset", reset: resetGitProbes },
40
+ { module: "lib/resolved-deployment.mjs", binding: "reported", how: "reset", reset: resetResolvedDeployment },
41
+ { module: "lib/resolved-deployment.mjs", binding: "observer", how: "scoped", why: "set and settled by the call when it is given `deployments`; else the CLI's own, settled at exit" },
42
+ { module: "lib/remote.mjs", binding: "liveChildren", how: "safe", why: "a registry of live git process groups, each leaving on 'close': empty once a call's session is closed, never cleared (that would lose exit reaping)" },
43
+ { module: "lib/remote.mjs", binding: "cacheLocks", how: "safe", why: "an in-process mutex per cache repo; an entry is removed when its holder releases it" },
44
+ { module: "lib/remote.mjs", binding: "fingerprintMemo", how: "safe", why: "the kernel code's fingerprint, install data: a process that runs a changed install exits first (the warm reader's install stamp)" },
45
+ { module: "lib/session-seen.mjs", binding: "processBoot", how: "safe", why: "the boot id: a process never outlives its boot" },
46
+ { module: "lib/session-viewer.mjs", binding: "probed", how: "safe", why: "only an attach's preparation reads it; readSessionViewer asks tmux -V at every call" },
47
+ { module: "lib/session-viewer.mjs", binding: "onQuit", how: "safe", why: "only an attach (attachSessionTarget) sets it" },
48
+ { module: "lib/session-viewer.mjs", binding: "quitHeld", how: "safe", why: "only an attach (attachSessionTarget) sets it" },
49
+ { module: "lib/workspace.mjs", binding: "schemaCache", how: "safe", why: "compiled validators of the kernel's own schema files, install data: the warm reader's install stamp covers them" },
50
+ { module: "lib/workspace.mjs", binding: "regexCache", how: "safe", why: "compiled patterns: a pure function of the pattern text" },
51
+ { module: "lib/workspace.mjs", binding: "workspaceChecks", how: "safe", why: "a WeakMap keyed by a workspace value one call parsed: never reached by another call" },
52
+ { module: "lib/workspace.mjs", binding: "memberRowIndex", how: "safe", why: "a WeakMap keyed by a discovery's members array one call built: never reached by another call" },
53
+ { module: "lib/errors.mjs", binding: "answeredAfterEndedSteps", how: "safe", why: "a WeakSet of refusals one call made: never reached by another call" },
54
+ { module: "lib/process-group.mjs", binding: "closedGroups", how: "safe", why: "a WeakSet of child processes: each one call's own" },
55
+ ];
56
+
57
+ /** Forget the state of the last read: every `reset` row of READ_STATE, each reset once. */
58
+ export function resetReadState() {
59
+ for (const reset of new Set(READ_STATE.map((row) => row.reset).filter(Boolean))) reset();
60
+ }
61
+
62
+ /** `--max-age <raw>` as the read verbs take it: `raw` the flag's value (true when it has none). → `{ maxAge }`,
63
+ * or `{ refusal: { code, message } }`. Which commands take the flag is the CLI's allow-list. */
64
+ export function parseMaxAge(raw) {
65
+ if (raw === true) return { refusal: { code: "E_BAD_ARGS", message: `--max-age needs a value: whole seconds from 0 to ${MAX_AGE_LIMIT}` } };
66
+ if (!/^\d{1,5}$/.test(raw) || Number(raw) > MAX_AGE_LIMIT) return { refusal: { code: "E_BAD_ARGS", message: `--max-age takes whole seconds from 0 to ${MAX_AGE_LIMIT}, got ${JSON.stringify(raw)}` } };
67
+ return { maxAge: Number(raw) };
68
+ }
69
+
70
+ /** The remote budget of these reads (ms): READ_REMOTE_BUDGET_MS, or `OATS_READ_REMOTE_BUDGET_MS` from `env`
71
+ * when it is a positive integer (a test and ops override, not a contract). */
72
+ export function readBudget(env) {
73
+ const override = Number(env.OATS_READ_REMOTE_BUDGET_MS);
74
+ return Number.isSafeInteger(override) && override > 0 ? override : READ_REMOTE_BUDGET_MS;
75
+ }
76
+
77
+ /** The read session of one call: --max-age's reuse window (`maxAge`, null for none) and, with `budgetMs`, a
78
+ * deadline that far from now. */
79
+ export function callSession({ maxAge = null, budgetMs = null } = {}) {
80
+ return createReadSession({ maxAge: maxAge ?? 0, ...(budgetMs !== null ? { deadline: Date.now() + budgetMs } : {}) });
81
+ }
82
+
83
+ /** A refusal of a read: the call answers it as the CLI's JSON failure, `{ schemaVersion: 1, ok: false,
84
+ * error: { code, message, details? } }` with the deprecated-name warning, and exit 1. */
85
+ class ReadRefusal extends Error {}
86
+ export function refuse(code, message, details) {
87
+ throw Object.assign(new ReadRefusal(String(message)), { code, details });
88
+ }
89
+
90
+ /** The deprecated-name warning a JSON answer carries (lib/deprecation.mjs), as the envelope spreads it. */
91
+ export function answerWarnings() {
92
+ const w = runtimeNameWarning();
93
+ return w ? { warnings: [w] } : {};
94
+ }
95
+
96
+ /** Run one read: `body(call)` answers `{ answer }` or `{ view }`, or refuses (refuse). → `{ exit, answer,
97
+ * view?, stderr }`. A typed config-shape failure (lib/errors.mjs OWN_NAME_FAILURES) is answered as the
98
+ * CLI's dispatch answers it. Anything else is thrown, and the session's notices are left in it for the
99
+ * caller to say. */
100
+ export async function runRead(ctx, body) {
101
+ const call = openCall(ctx);
102
+ let result;
103
+ try {
104
+ result = { exit: 0, answer: null, ...(await body(call)) };
105
+ } catch (e) {
106
+ if (e instanceof ReadRefusal) result = { exit: 1, answer: failure(e.code, e.message, e.details) };
107
+ else if (OWN_NAME_FAILURES.has(e?.code)) result = { exit: 1, answer: failure(e.code, e.message, e.details?.unconfirmed === true ? e.details : undefined) };
108
+ else throw e;
109
+ } finally {
110
+ if (ctx.deployments) settleResolvedDeployment();
111
+ }
112
+ return { ...result, stderr: call.notices() };
113
+ }
114
+
115
+ /** A refusal answered before any read runs (a caller's own preamble: lib/reader.mjs), as runRead answers one. */
116
+ export function refusalAnswer(code, message, details) {
117
+ return { exit: 1, answer: failure(code, message, details), stderr: "" };
118
+ }
119
+
120
+ function failure(code, message, details) {
121
+ return { schemaVersion: 1, ok: false, error: { code, message: String(message), ...(details !== undefined ? { details } : {}) }, ...answerWarnings() };
122
+ }
123
+
124
+ function openCall({ maxAge = null, session, cacheDir, deployments }) {
125
+ resetReadState();
126
+ if (maxAge !== null) activateLocalInputs(); // observation.localRevision: every local config read from here on
127
+ if (deployments) observeResolvedDeployment(deployments, { atExit: false });
128
+ let used = null;
129
+ const call = {
130
+ maxAge,
131
+ /** The caller's read session, asked for where the read first needs it. */
132
+ session: () => (used ??= session()),
133
+ /** The options every remote read of the call takes. */
134
+ remoteOptions: () => ({ ...(cacheDir ? { cacheDir } : {}), session: call.session() }),
135
+ /** The observation block: the heads' oldest observedAt and reuse, and the local configuration's revision. */
136
+ observation: () => ({ ...call.session().observation(), localRevision: localRevision() }),
137
+ /** A read verb's JSON with the observation block, only when --max-age was given (0 included). */
138
+ withObservation: (doc) => (maxAge === null ? doc : { ...doc, observation: call.observation() }),
139
+ /** What the session found worth telling the operator, taken out of it, as the CLI says it on stderr. */
140
+ notices: () => (used?.notices.splice(0) ?? []).map((notice) => `oats: warning: ${notice}\n`).join(""),
141
+ };
142
+ return call;
143
+ }
package/lib/reader.mjs ADDED
@@ -0,0 +1,203 @@
1
+ /** lib/reader.mjs — `oats reader --stdio`, the warm reader (awebai/oats#1630): a process a client starts as its own
2
+ * child, which answers `oats status --json` and `oats workspace status --json` over its stdin and stdout, many
3
+ * times, with the kernel's own read code (lib/roster-read.mjs and lib/workspace-read.mjs, through
4
+ * lib/read-call.mjs). The contract is docs/desktop-cli-api.md "The warm reader"; the decisions,
5
+ * docs/design/2026-10-29-warm-reader.md.
6
+ *
7
+ * - Warm code, not warm data. Each request reads the deployment afresh: its answer is what `oats <argv>`, run by
8
+ * this install with the same environment and with cwd = `--dir`, prints and exits with. What the reader cannot
9
+ * answer that way it refuses, and the client runs the CLI.
10
+ * - One request at a time, in arrival order. The reads' module state is process-wide (lib/read-call.mjs
11
+ * READ_STATE), and so is the cwd: the children the reads run by name (tmux, git) resolve a relative PATH
12
+ * entry against it, so the reader chdirs to the request's `--dir` for the read and back to its install root
13
+ * when the request ends, never keeping a deployment directory that may go away. A second lane must first give
14
+ * each child its own cwd.
15
+ * - The install stamp (lib/install-stamp.mjs), taken before the kernel loads and again for each request: an install
16
+ * that changed under the reader (an upgrade, a Node upgrade) is never answered from the old code. That request and every queued one are refused E_READER_STALE, and the
17
+ * reader exits 0.
18
+ * - Its lifetime is the client's: stdin EOF or error, EPIPE on stdout, SIGTERM/SIGINT/SIGHUP end it. A request in
19
+ * flight is not answered, and its read session is closed from the `exit` handler, which kills its git
20
+ * children (a deployments-list lock, lib/dir-lock.mjs, exits from its own signal handler).
21
+ * - Its stdout carries protocol lines only: anything else written there (console.log) goes to stderr, and every
22
+ * child on the read path pipes or ignores its stdout.
23
+ * Kernel-private, not exported from `./core`. Dependency-free. */
24
+ import { isAbsolute, resolve } from "node:path";
25
+ import { expandInlineValues, flagValue } from "./argv.mjs";
26
+ import { inheritedContextRefusal } from "./captured-context.mjs";
27
+ import { listResolved } from "./deployments.mjs";
28
+ import { hotRead } from "./hot-reads.mjs";
29
+ import { installStamp } from "./install-stamp.mjs";
30
+ import { READER_API } from "./kernel-features.mjs";
31
+ import { callSession, parseMaxAge, readBudget, refusalAnswer, resetReadState } from "./read-call.mjs";
32
+ import { statusAnswer } from "./roster-read.mjs";
33
+ import { OATS_VERSION, PKG_ROOT } from "./version.mjs";
34
+ import { workspaceStatusAnswer } from "./workspace-read.mjs";
35
+
36
+ /** The reads a reader answers, by their hot-read names (lib/hot-reads.mjs hotRead): the hello's `reads`. */
37
+ export const READS = Object.freeze(["status", "workspace status"]);
38
+ /** The longest request line, in bytes, its newline not counted. */
39
+ export const LINE_LIMIT = 64 * 1024;
40
+ /** The longest `stderr` of an answer frame, in UTF-8 bytes. It is diagnostics only (the read session's notices), cut
41
+ * here so that a client's bound on an answer line, the CLI read's own output limit, is never passed for its sake. */
42
+ export const STDERR_LIMIT = 8 * 1024;
43
+ /** The modules the reads import lazily (by a literal `import()`), loaded before the hello so that the hello means
44
+ * ready: no request waits on a module load. test/reader-protocol.test.mjs pins it against the reads' closure. */
45
+ export const PRELOAD = Object.freeze({
46
+ "member-clone": () => import("./member-clone.mjs"),
47
+ drift: () => import("./drift.mjs"),
48
+ semver: () => import("./semver.mjs"),
49
+ });
50
+
51
+ const BAD_REQUEST = "E_READER_BAD_REQUEST", UNSUPPORTED = "E_READER_UNSUPPORTED", STALE = "E_READER_STALE", DEFECT = "E_READER_DEFECT";
52
+ const validId = (id) => (typeof id === "string" && [...id].length <= 64) || Number.isSafeInteger(id);
53
+ const refused = (id, code, message) => ({ id, refused: { code, message } });
54
+
55
+ /** Run the reader on this process's stdin and stdout until its client ends it. Returns once it is listening. `stamp`
56
+ * is the install's stamp taken before any kernel module loaded (bin/oats.mjs; lib/install-stamp.mjs), the baseline
57
+ * every request is checked against. */
58
+ export async function runReader({ stamp }) {
59
+ const stale = () => installStamp() !== stamp;
60
+ process.chdir(PKG_ROOT);
61
+
62
+ // stdout is the protocol's: every other write meant for it goes to stderr.
63
+ const protocol = process.stdout.write.bind(process.stdout);
64
+ process.stdout.write = process.stderr.write.bind(process.stderr);
65
+ const send = (frame) => new Promise((done) => { protocol(`${JSON.stringify(frame)}\n`, () => done()); });
66
+ const end = (code) => process.exit(code);
67
+
68
+ // The request in flight's read session: closed on any exit, which kills its git children.
69
+ let inFlight = null;
70
+ process.on("exit", () => inFlight?.closeNow());
71
+ for (const [signal, code] of [["SIGINT", 130], ["SIGTERM", 143], ["SIGHUP", 129]]) process.on(signal, () => {
72
+ // A deployments-list lock (lib/dir-lock.mjs) holds its own handler, which releases the lock and exits.
73
+ if (process.listenerCount(signal) === 1) end(code);
74
+ });
75
+ process.stdout.on("error", () => end(0)); // EPIPE: the client is gone
76
+ process.stdin.on("end", () => end(0));
77
+ process.stdin.on("error", () => end(0));
78
+
79
+ for (const load of Object.values(PRELOAD)) await load();
80
+
81
+ const queue = [];
82
+ let pending = [], pendingBytes = 0, oversize = false, working = false, stopped = false;
83
+ const take = (part, complete) => {
84
+ if (!oversize) {
85
+ pendingBytes += part.length;
86
+ if (pendingBytes > LINE_LIMIT) { oversize = true; pending = []; } else if (part.length) pending.push(part);
87
+ }
88
+ if (!complete) return;
89
+ queue.push(oversize ? { oversize: true } : { line: Buffer.concat(pending).toString("utf8") });
90
+ pending = []; pendingBytes = 0; oversize = false;
91
+ };
92
+
93
+ /** Refuse `id` and every queued request as stale, then exit 0. */
94
+ const refuseStale = async (id) => {
95
+ stopped = true;
96
+ process.stdin.pause();
97
+ const message = "the kernel install changed since this reader started: run the read with the CLI, and start a new reader";
98
+ await send(refused(id, STALE, message));
99
+ for (const item of queue.splice(0)) await send(refused(requestOf(item).id ?? null, STALE, message));
100
+ end(0);
101
+ };
102
+
103
+ const handle = async (item) => {
104
+ const request = requestOf(item);
105
+ if (request.refusal) return send(refused(request.id ?? null, BAD_REQUEST, request.refusal));
106
+ const { id, argv } = request;
107
+ if (stale()) return refuseStale(id);
108
+ let frame;
109
+ try {
110
+ frame = await answer(argv, (session) => { inFlight = session; });
111
+ } catch (e) {
112
+ stopped = true;
113
+ process.stderr.write(`${e?.stack ?? e}\n`);
114
+ await send(refused(id, DEFECT, `the reader failed: ${e?.message ?? e}; run the read with the CLI`));
115
+ return end(1); // per-request state may be half reset
116
+ }
117
+ if (stale()) return refuseStale(id);
118
+ return send({ id, ...frame });
119
+ };
120
+
121
+ const pump = async () => {
122
+ if (working) return;
123
+ working = true;
124
+ try { while (queue.length && !stopped) await handle(queue.shift()); } finally { working = false; }
125
+ };
126
+
127
+ process.stdin.on("data", (chunk) => {
128
+ if (stopped) return;
129
+ let start = 0;
130
+ for (let nl = chunk.indexOf(10); nl !== -1; nl = chunk.indexOf(10, start)) { take(chunk.subarray(start, nl), true); start = nl + 1; }
131
+ take(chunk.subarray(start), false);
132
+ pump();
133
+ });
134
+
135
+ await send({ readerApi: READER_API, version: OATS_VERSION, reads: READS });
136
+ }
137
+
138
+ /** `text` cut to at most STDERR_LIMIT bytes of UTF-8, at a character boundary. */
139
+ export function boundedStderr(text) {
140
+ if (Buffer.byteLength(text) <= STDERR_LIMIT) return text;
141
+ let out = "", bytes = 0;
142
+ for (const ch of text) {
143
+ const n = Buffer.byteLength(ch);
144
+ if (bytes + n > STDERR_LIMIT) break;
145
+ out += ch;
146
+ bytes += n;
147
+ }
148
+ return out;
149
+ }
150
+
151
+ /** A queued line as a request: `{ id, argv }`, or `{ id?, refusal }` for a line that is none. */
152
+ function requestOf(item) {
153
+ if (item.oversize) return { refusal: `a request line is at most ${LINE_LIMIT} bytes` };
154
+ let request;
155
+ try { request = JSON.parse(item.line); } catch { return { refusal: "a request is one JSON object on one line" }; }
156
+ if (!request || typeof request !== "object" || Array.isArray(request)) return { refusal: "a request is one JSON object on one line" };
157
+ if (!validId(request.id)) return { refusal: "a request's id is a string of at most 64 characters or a safe integer" };
158
+ if (!Array.isArray(request.argv) || !request.argv.every((a) => typeof a === "string")) return { id: request.id, refusal: "a request's argv is an array of strings" };
159
+ return { id: request.id, argv: request.argv };
160
+ }
161
+
162
+ /** One request's answer frame (without its id): `{ exit, answer, stderr? }`, or `{ refused }`. `track` is told the
163
+ * read session while it is open. Accepted: what hotRead classifies as one of READS, read with --json, with an
164
+ * absolute --dir. Then the CLI's own dispatch, in its order: the flag syntax, --max-age, the inherited context,
165
+ * then the read itself with its deployments-list observer. */
166
+ async function answer(argv, track) {
167
+ const unsupported = (message) => ({ refused: { code: UNSUPPORTED, message: `${message}: run the read with the CLI` } });
168
+ const read = hotRead(argv);
169
+ if (!read || !READS.includes(read.form)) return unsupported(`this reader answers ${READS.map((r) => `oats ${r}`).join(" and ")} only`);
170
+ const { argv: args, problem, inline } = expandInlineValues(argv);
171
+ if (!args.includes("--json")) return unsupported("a request reads with --json");
172
+ const given = flagValue(args, inline, "dir");
173
+ if (typeof given !== "string" || !isAbsolute(given)) return unsupported("a request names its deployment with an absolute --dir");
174
+ const dir = resolve(given);
175
+ resetReadState(); // a refusal below carries no warning a previous request noted
176
+ try { process.chdir(dir); } catch (e) { return unsupported(`--dir ${dir} cannot be the working directory (${e.code ?? e.message})`); }
177
+ try {
178
+ const said = ({ exit, answer: doc, stderr }) => ({ exit, answer: doc, ...(stderr ? { stderr: boundedStderr(stderr) } : {}) });
179
+ if (problem) return said(refusalAnswer("E_BAD_ARGS", problem));
180
+ let maxAge = null;
181
+ if (args.includes("--max-age")) {
182
+ const parsed = parseMaxAge(flagValue(args, inline, "max-age"));
183
+ if (parsed.refusal) return said(refusalAnswer(parsed.refusal.code, parsed.refusal.message));
184
+ maxAge = parsed.maxAge;
185
+ }
186
+ const captured = inheritedContextRefusal(process.env);
187
+ if (captured) return said(refusalAnswer(captured.code, captured.message, captured.details));
188
+ const session = callSession({ maxAge, budgetMs: readBudget(process.env) });
189
+ track(session);
190
+ try {
191
+ const cacheDir = process.env.OATS_REMOTE_CACHE ? resolve(process.env.OATS_REMOTE_CACHE) : undefined;
192
+ const ctx = { dir, maxAge, session: () => session, cacheDir, deployments: listResolved };
193
+ if (read.form === "workspace status") return said(await workspaceStatusAnswer(ctx));
194
+ const team = args.includes("--team");
195
+ return said(await statusAnswer({ ...ctx, dir: team ? null : dir, team }));
196
+ } finally {
197
+ await session.close();
198
+ track(null);
199
+ }
200
+ } finally {
201
+ try { process.chdir(PKG_ROOT); } catch { /* the install is gone: the stamp says so */ }
202
+ }
203
+ }
package/lib/remote.mjs CHANGED
@@ -181,7 +181,7 @@ export const TREE_BUDGET = 64 * 1024 * 1024; // fetchRemoteTree: 64 MiB pe
181
181
  export const SMALL_BLOB_LIMIT = 64 * 1024;
182
182
  /** The oldest git that keeps a partial cache honest: GIT_NO_LAZY_FETCH arrived in 2.45; an older git fetches a
183
183
  * missing blob on its own, or dies trying. With an older git every cache fetches whole trees. */
184
- export const PARTIAL_FETCH_GIT = [2, 45];
184
+ export const PARTIAL_FETCH_GIT = Object.freeze([2, 45]);
185
185
  export const GIT_TIMEOUT_MS = 30_000;
186
186
  /** The fetch of a commit into the cache: the first one transfers the commit's whole tree, which for a
187
187
  * large workspace host takes far longer than GIT_TIMEOUT_MS (awebai/oats#362). */
@@ -319,7 +319,7 @@ export function parseRepoRef(text, options = undefined) {
319
319
 
320
320
  /** The operator's own ssh command (GIT_SSH_COMMAND, else core.sshCommand, else `ssh`),
321
321
  * ALWAYS with `-o BatchMode=yes` appended so ssh can never prompt for a passphrase or
322
- * host key. Resolved once per process; `-o` after the operator's flags is valid for ssh
322
+ * host key. Resolved once per process (per read in a process answering many: resetSshCommand); `-o` after the operator's flags is valid for ssh
323
323
  * and for every ssh-compatible wrapper that forwards its argv. */
324
324
  let sshCommandCache;
325
325
  export function sshCommand() {
@@ -332,6 +332,9 @@ export function sshCommand() {
332
332
  sshCommandCache = /(?:^|\s)-o\s*BatchMode=yes(?:\s|$)/i.test(base) ? base : `${base} -o BatchMode=yes`;
333
333
  return sshCommandCache;
334
334
  }
335
+ /** Resolve the ssh command again at its next use: a process that answers many reads (lib/read-call.mjs)
336
+ * reads core.sshCommand afresh for each, as a fresh CLI does. */
337
+ export function resetSshCommand() { sshCommandCache = undefined; }
335
338
 
336
339
  /** The environment every git child of the kernel that may reach a remote runs under: it never prompts (no
337
340
  * terminal prompt, askpass refused, ssh in BatchMode) and never fetches a missing object on its own. */
@@ -351,6 +354,9 @@ export function gitEnv() {
351
354
  /** Every git child this module started that has not exited yet (runGit's and the batch readers'): what
352
355
  * reapOnExit still has to end when the process exits. */
353
356
  const liveChildren = new Set();
357
+ /** How many git children of this module are still live: none once every read session that started them
358
+ * is closed (a process answering many reads holds that after each one; test/read-call-equivalence.test.mjs). */
359
+ export function liveGitChildren() { return liveChildren.size; }
354
360
  /** The exit path (`process.on("exit")`, ReadSession.closeNow) cannot wait for a timer, so the graceful kill
355
361
  * is done synchronously and bounded: every live git group gets SIGTERM, the process blocks for at most
356
362
  * EXIT_GRACE_MS (git removes its lock files on SIGTERM in far less), then SIGKILL ends what is left. A
@@ -1400,8 +1406,7 @@ export function pruneStores(root, { fingerprint = kernelFingerprint(), limits =
1400
1406
  if (st && now - st.mtimeMs > L.staleFingerprintMs && remove(dir, { recursive: true })) removed++;
1401
1407
  }
1402
1408
  }
1403
- const observed = join(root, ".observed");
1404
- for (const f of list(observed)) {
1409
+ for (const observed of [join(root, ".observed"), join(root, ".observed-facts")]) for (const f of list(observed)) {
1405
1410
  const p = join(observed, f), st = stat(p);
1406
1411
  if (st && now - st.mtimeMs > (f.endsWith(".tmp") ? L.staleTempMs : L.staleObservationMs) && remove(p)) removed++;
1407
1412
  }
@@ -1430,6 +1435,39 @@ function writeObservation(root, ref, atArgs, obs) {
1430
1435
  writeAtomicQuiet(observationFile(root, ref, atArgs), JSON.stringify({ v: 1, key: ref.key, args: atArgs, urlDigest: sha256(ref.url), commit: obs.commit, ref: obs.ref, observedAt: obs.observedAt }));
1431
1436
  }
1432
1437
 
1438
+ /** --max-age over a remote fact that is not a head (awebai/oats#1630: the gh login a status display places
1439
+ * automations with; lib/automations.mjs ghLogin's `lookup`), reused as a head is. `kind` names the fact; `parts`
1440
+ * everything its answer depends on: a record is reused only under the same parts, and the digest of `kind` and
1441
+ * `parts` names the record, which holds no part. A record is reusable while it is at most the session's maxAge
1442
+ * old (and dated at most 5 s ahead); a successful live answer is recorded, and a failed one removes the record
1443
+ * (forget), so the next read asks again. A reused fact counts in the session's observation block as a reused
1444
+ * head does (`reused: true`, `observedAt` the oldest); a live one does not. Records live beside the head
1445
+ * observations (`<cache>/.observed-facts`), private and written atomically.
1446
+ * → { reuse() → value | undefined, record(value), forget() }, or null without a session. */
1447
+ export function factObservation(options, kind, parts) {
1448
+ const session = sessionOf(options);
1449
+ if (!session) return null;
1450
+ const digest = sha256([kind, ...parts].join("\0"));
1451
+ const file = join(cacheRootOf(options), ".observed-facts", `${digest}.json`);
1452
+ return {
1453
+ reuse() {
1454
+ if (session.maxAge <= 0) return undefined;
1455
+ const rec = readStoreFile(file);
1456
+ if (!rec || typeof rec !== "object" || rec.v !== 1 || rec.kind !== kind || rec.digest !== digest || !("value" in rec)) return undefined;
1457
+ const at = typeof rec.observedAt === "string" ? Date.parse(rec.observedAt) : NaN, now = session.now();
1458
+ if (!Number.isFinite(at) || at > now + 5000 || now - at > session.maxAge * 1000) return undefined;
1459
+ session.used.set(`fact\0${digest}`, { observedAt: rec.observedAt, reused: true });
1460
+ return rec.value;
1461
+ },
1462
+ record(value) {
1463
+ writeAtomicQuiet(file, JSON.stringify({ v: 1, kind, digest, value, observedAt: new Date(session.now()).toISOString() }));
1464
+ },
1465
+ forget() {
1466
+ try { rmSync(file, { force: true }); } catch { /* a record that cannot be removed is still read only within --max-age */ }
1467
+ },
1468
+ };
1469
+ }
1470
+
1433
1471
  /** The COMMIT <oid> peels to, when <oid> is present in the cache and is a commit or an
1434
1472
  * annotated tag chain ending in one; null on a missing object, a pruned store, or a
1435
1473
  * tag/tree/blob that does not peel to a commit. (`rev-parse <oid>^{commit}` peels.)
@@ -1581,7 +1619,7 @@ const olderGitNotice = (version, ref) =>
1581
1619
 
1582
1620
  /** One strict probe per exec: share in-flight work and retain only parsed success. A failed or abandoned
1583
1621
  * probe cannot authorize rebuilding a cache, nor erase a newer probe installed by a retry. */
1584
- const gitVersions = new WeakMap();
1622
+ let gitVersions = new WeakMap();
1585
1623
  async function probeGitVersion(exec, opts = undefined) {
1586
1624
  if (opts?.signal?.aborted) throw abortError(opts.signal);
1587
1625
  let version = gitVersions.get(exec);
@@ -1968,7 +2006,10 @@ const isHeadAt = (at) => at === undefined || at === null || at === "" || at ===
1968
2006
  * `git config --get`, in the observation's own environment): asked once per command (its session) and exec, or
1969
2007
  * once per exec without a session. Unset (exit 1) → false; any value, or a read that fails otherwise (an abort
1970
2008
  * included) → true: today's argv, never an error. */
1971
- const protocolPins = new WeakMap();
2009
+ let protocolPins = new WeakMap();
2010
+ /** Ask git's version and the protocol pin again at their next use: a process that answers many reads
2011
+ * (lib/read-call.mjs) probes them afresh for each, as a fresh CLI does (a git upgraded meanwhile). */
2012
+ export function resetGitProbes() { gitVersions = new WeakMap(); protocolPins = new WeakMap(); }
1972
2013
  function protocolPinned(exec, session) {
1973
2014
  const memo = session?.protocolPins ?? protocolPins;
1974
2015
  let pinned = memo.get(exec);
@@ -0,0 +1,20 @@
1
+ /** The environment names the kernel sets for every launch: a launch configuration may not name them,
2
+ * and a scheduled job's environment drops them (automation-scope.mjs childEnv). A leaf
3
+ * (awebai/oats#1630): the automation scope reads it without loading core.mjs, which imports it and
4
+ * re-exports it. One instance, here. */
5
+
6
+ /** Environment the kernel sets for every launch (identity, home, roots) and
7
+ * its reference aliases: a configuration may not name them. */
8
+ export const RESERVED_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME", "OATS_HOME", "OATS_AGENT", "OATS_SOUL", "OATS_SOUL_ID", "OATS_ROOT", "OATS_CONTEXT", "OATS_WORKSPACE", "OATS_EVENT", "OATS_SETTINGS", "OATS_SETTINGS_ORIGINS", "OATS_CLI_BIN", "OATS_NODE_BIN", "PI_AGENT_INSTANCE", "PI_AGENT_HOME", "PI_AGENTS_ROOT",
9
+ // The test seam that replaces the login shell (lib/login-environment.mjs): never a launch's to set.
10
+ "OATS_TEST_LOGIN_SHELL",
11
+ // The test seams of #796, the same: a worktree hook's fixed timeout, the fetch timeout of
12
+ // `oats worktree add` (lib/worktree-hooks.mjs, lib/worktree.mjs), and the `ps` path of a
13
+ // process's start time on a host with procfs, and the `ps` it runs (lib/worktree-hooks.mjs processStart).
14
+ "OATS_TEST_WORKTREE_HOOK_TIMEOUT_MS", "OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS", "OATS_TEST_PROCESS_START_PS",
15
+ // The test seams of #915 and #1559: the cgroup the kernel judges itself in, whether the host was
16
+ // booted with systemd, and the directories its systemd-run comes from (lib/tmux-server-scope.mjs,
17
+ // lib/system-tools.mjs).
18
+ "OATS_TEST_CGROUP", "OATS_TEST_SYSTEMD_BOOTED", "OATS_TEST_SYSTEM_TOOL_DIRS",
19
+ // The test seam of #1421 §3: the naming call's time limit (lib/instance-naming.mjs NAMING_TIMEOUT_MS).
20
+ "OATS_TEST_NAMING_TIMEOUT_MS"]);