@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,51 @@
1
+ /** The agents root a command works in: found by walking up from a directory (findRoot), or checked
2
+ * where one is named (ensureRoot), and its canonical spelling. A leaf (awebai/oats#1630): the hot reads
3
+ * resolve their scope without loading core.mjs, which re-exports these. */
4
+ import { existsSync, lstatSync } from "node:fs";
5
+ import { resolve, dirname, join, basename } from "node:path";
6
+ import { resolvedDeployment } from "./resolved-deployment.mjs";
7
+ import { oatsError } from "./errors.mjs";
8
+ import { canonicalDeploymentPath } from "./deployment-path.mjs";
9
+
10
+ // ---------- root discovery ----------
11
+ /** Closest agents/ walking up from `cwd`. A deployment whose agents/ was never
12
+ * created has no root here; ensureRoot names the remedy. */
13
+ export function findRoot(cwd = process.cwd()) {
14
+ if (process.env.PI_AGENTS_ROOT) return resolve(process.env.PI_AGENTS_ROOT);
15
+ let d = resolve(cwd);
16
+ while (true) {
17
+ if (basename(d) === "agents" && lstatSync(d).isDirectory()) return d;
18
+ const candidate = join(d, "agents");
19
+ if (existsSync(candidate) && lstatSync(candidate).isDirectory()) return candidate;
20
+ const parent = dirname(d);
21
+ if (parent === d) return undefined;
22
+ d = parent;
23
+ }
24
+ }
25
+
26
+ /** The canonical deployment root — where instance homes belong. */
27
+ export function canonicalAgentsRoot(root) { return canonicalDeploymentPath(root); }
28
+ export function ensureRoot(cwd) {
29
+ const root = findRoot(cwd);
30
+ if (!root) {
31
+ const from = resolve(cwd ?? process.cwd());
32
+ // Workspace model: an oats-local.yaml above `from` IS a deployment whose instance
33
+ // root (<deployment>/agents/) was never created — name that remedy, not a v1 verb.
34
+ let localDeployment = null;
35
+ for (let d = from; ; d = dirname(d)) { if (existsSync(join(d, "oats-local.yaml"))) { localDeployment = d; break; } if (dirname(d) === d) break; }
36
+ if (localDeployment) {
37
+ throw oatsError("E_NO_DEPLOYMENT",
38
+ `no instance root walking up from ${from}: ${join(localDeployment, "oats-local.yaml")} names this deployment but ${join(localDeployment, "agents")} does not exist — mkdir ${join(localDeployment, "agents")} (or run \`oats sync --dir ${localDeployment}\`, which creates it)`,
39
+ { from, looked: ["agents/"], deployment: localDeployment, local: join(localDeployment, "oats-local.yaml"), remedy: `mkdir ${join(localDeployment, "agents")} (or run oats sync)` });
40
+ }
41
+ throw oatsError("E_NO_DEPLOYMENT",
42
+ `no deployment found walking up from ${from}: no agents/ directory — run from the deployment (where oats-local.yaml lives; \`oats onboard\` creates one), or set PI_AGENTS_ROOT`,
43
+ { from, looked: ["agents/"] });
44
+ }
45
+ // Deployment root ≠ invocation CWD: homes always land in the primary checkout.
46
+ const canonical = canonicalAgentsRoot(root);
47
+ resolvedDeployment(dirname(canonical), { canonical: true });
48
+ return canonical;
49
+ }
50
+
51
+ export function workspaceOf(root) { return dirname(root); }
package/lib/argv.mjs ADDED
@@ -0,0 +1,41 @@
1
+ /** lib/argv.mjs — how the kernel reads `--flag=value` (docs/desktop-cli-api.md "Flag syntax"): the CLI's
2
+ * dispatch expands its argv here once, and a process answering reads (lib/reader.mjs) expands each request's
3
+ * argv here, so both give a malformed flag the same E_BAD_ARGS. Kernel-private, not exported from `./core`.
4
+ * Dependency-free. */
5
+
6
+ /** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
7
+ const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "background", "check", "clear", "composed-skills", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-background", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "run-source", "same-work", "self", "skills", "suggest-name", "verbose", "yes", "yolo"]);
8
+ /** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
9
+ * routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
10
+ * `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
11
+ * expanded, it would be a flag token every reader sees, which the spaced form can never carry. */
12
+ /** Free-text flags whose inline value may start with `--` (`--message=--deploy failed`). Such a
13
+ * value is kept out of argv, where it would read as a flag (`--message=--clear` must not
14
+ * clear), and flag() answers it from `inline`. */
15
+ const INLINE_TEXT_FLAGS = new Set(["message"]);
16
+ /** Free-text flags whose inline value is always kept whole, the empty one included:
17
+ * `--description=` clears a trigger's or schedule's description. */
18
+ const INLINE_WHOLE_FLAGS = new Set(["description"]);
19
+ export function expandInlineValues(argv) {
20
+ const out = [];
21
+ const inline = new Map();
22
+ let problem;
23
+ for (const a of argv) {
24
+ const eq = a.indexOf("=");
25
+ if (!a.startsWith("--") || eq <= 2) { out.push(a); continue; }
26
+ const name = a.slice(2, eq), value = a.slice(eq + 1);
27
+ if (INLINE_WHOLE_FLAGS.has(name) || (INLINE_TEXT_FLAGS.has(name) && value.startsWith("--"))) { inline.set(name, value); out.push(`--${name}`); continue; }
28
+ problem ??= KERNEL_SWITCHES.has(name) ? `--${name} takes no value (got ${a})` : value === "" ? `--${name}= needs a value` : value.startsWith("--") ? `--${name}= takes a value, not an option (got ${a})` : undefined;
29
+ out.push(`--${name}`, value);
30
+ }
31
+ return { argv: out, problem, inline };
32
+ }
33
+
34
+ /** A flag's value in an expanded argv (`args`, `inline`: expandInlineValues's): its free text from `inline`, the word
35
+ * after it, `true` when it has none (the next word is absent, empty or another flag), undefined when it is not given.
36
+ * The first `--name` wins. */
37
+ export function flagValue(args, inline, name) {
38
+ const i = args.indexOf(`--${name}`);
39
+ if (i >= 0 && inline.has(name)) return inline.get(name);
40
+ return i >= 0 ? (args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : true) : undefined;
41
+ }
@@ -0,0 +1,7 @@
1
+ /** The API versions of the automation answers (`scheduleApi` and `automationsApi` in `version --json`).
2
+ * A leaf (awebai/oats#1630): `oats version` reads them without loading schedule.mjs or automations.mjs,
3
+ * which re-export them. */
4
+
5
+ export const SCHEDULE_API = 2;
6
+
7
+ export const AUTOMATIONS_API = 1;
@@ -0,0 +1,37 @@
1
+ /** scopeAutomations: the triggers and schedules a deployment declares, read with the clone each one
2
+ * needs, and childEnv, the environment a scheduled job runs with. A leaf (awebai/oats#1630):
3
+ * `oats workspace status` reads the automation scope without loading schedule.mjs and core.mjs;
4
+ * schedule.mjs imports both and re-exports them. */
5
+ import { loadLocal } from "./workspace.mjs";
6
+ import { resolveMemberClone } from "./member-clone.mjs";
7
+ import { automationContext } from "./automations.mjs";
8
+ import { RESERVED_LAUNCH_ENV } from "./reserved-launch-env.mjs";
9
+
10
+ /** The environment a scheduler-launched oats child runs with: the caller's
11
+ * frozen instance identity and capability snapshot removed (a tick or run-now
12
+ * may be invoked from inside an unrelated instance; dispatch belongs to the
13
+ * job's cwd and explicit selectors, never to that caller), host configuration
14
+ * such as OATS_HOME_DIR and credentials kept. Shared by command and spawn jobs. */
15
+ export function childEnv() {
16
+ const env = { ...process.env };
17
+ for (const key of [...RESERVED_LAUNCH_ENV,
18
+ "OATS_DEPLOYMENT", "OATS_RESOLUTION", "OATS_CAPABILITY", "OATS_LAYER", "OATS_LEVEL", "OATS_META", "OATS_OPERATION",
19
+ "OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK",
20
+ "OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_LAUNCH_PREVIEW", "OATS_RETIRE_INTENT",
21
+ "OATS_TEAM_NAME", "OATS_TEAM_SCOPE", "OATS_TEAM_ID", "OATS_TEAM_LABEL", "OATS_TEAM_LABELS", "OATS_DEFAULT_TEAM", "OATS_DEFAULT_TEAM_ID", "OATS_DEFAULT_TEAM_FROM", "OATS_TEAMS", "OATS_TEAMS_SOURCE", "OATS_TRIGGER_EVENT_FILE",
22
+ "OATS_TREE", "OATS_TREE_CLONE", "OATS_TREE_REMOTE", "OATS_TREE_MEMBER", "OATS_TREE_BASE", "OATS_TREE_BASE_OID", "OATS_PURPOSE", "OATS_TREE_ORIGIN",
23
+ ]) delete env[key];
24
+ return env;
25
+ }
26
+
27
+ /** One scope's automations context (lib/automations.mjs automationContext) with its oats-local.yaml;
28
+ * an unreadable oats-local.yaml means no workspace automations (the local jobs still run). `remotes`:
29
+ * lib/member-clone.mjs verifyMemberClone's, for a read that verifies the same clones again. `lookup`: the
30
+ * status display's gh login lookup (lib/automations.mjs ghLogin), never an act's. */
31
+ export function scopeAutomations(ws, { io, now = new Date(), refresh = false, cache = new Map(), remotes, lookup } = {}) {
32
+ let local = null;
33
+ try { local = loadLocal(ws).local; } catch { local = null; }
34
+ const clonePathOf = (repoKey) => resolveMemberClone({ deployment: ws, soulEntry: { repoKey }, local }, { remotes });
35
+ const ctx = automationContext(ws, { local, io: { ...(io || {}), childEnv }, now, refresh, cache, clonePathOf, lookup });
36
+ return Object.assign(ctx, { ws, local });
37
+ }
@@ -33,15 +33,16 @@
33
33
  * `oats automations refresh`, which the tick runs as a child when the snapshot is ten minutes
34
34
  * old), one list per kind, and the tick reads it. The run state stays local. */
35
35
  import { spawnSync } from "node:child_process";
36
- import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
37
- import { dirname, join } from "node:path";
36
+ import { accessSync, constants as fsConstants, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
37
+ import { dirname, join, resolve } from "node:path";
38
38
  import { recordLocalInput } from "./local-inputs.mjs";
39
39
  import YAML from "yaml";
40
40
  import { parseConfigData } from "./config-data.mjs";
41
41
  import { editLocal } from "./local-edit.mjs";
42
42
  import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
43
+ import { AUTOMATIONS_API } from "./automation-api.mjs";
44
+ export { AUTOMATIONS_API } from "./automation-api.mjs";
43
45
 
44
- export const AUTOMATIONS_API = 1;
45
46
  export const SNAPSHOT_MAX_AGE_MS = 10 * 60_000;
46
47
  export const PLACEMENT_REASONS = Object.freeze(["host-unnamed", "assigned-elsewhere", "owner-mismatch", "untrusted"]);
47
48
  /** The kinds, in the order the snapshot keeps them (`triggers`, `schedules`). */
@@ -271,32 +272,82 @@ export function staleTrust(host, automations) {
271
272
  const known = new Set(automations.map((a) => a.id));
272
273
  return [...host.trust].filter((id) => !known.has(id));
273
274
  }
274
- /** The account the host's `gh` is logged in as on one GitHub host (`gh api user`), memoized in
275
- * `cache` (one per tick). `io.gh(args)` is the seam. → { ok, login } | { ok: false, error } */
276
- export function ghLogin(ghHost, { io, cache } = {}) {
275
+ /** The file a spawn of `name` runs: the first executable regular file on `path`, each entry (an empty one is the
276
+ * directory itself) resolved against `cwd` as the child's lookup resolves it. null when there is none. */
277
+ function onPath(name, path, cwd) {
278
+ for (const dir of String(path ?? "").split(":")) {
279
+ const candidate = resolve(cwd, dir || ".", name);
280
+ try { accessSync(candidate, fsConstants.X_OK); if (statSync(candidate).isFile()) return candidate; } catch { /* not here */ }
281
+ }
282
+ return null;
283
+ }
284
+ /** The token variables gh reads. Only which of them are set is part of a login's context, never a value. */
285
+ const GH_TOKEN_VARS = ["GH_TOKEN", "GITHUB_TOKEN", "GH_ENTERPRISE_TOKEN", "GITHUB_ENTERPRISE_TOKEN"];
286
+ /** What `gh api user`'s answer depends on, besides GitHub itself: the context a reused login is reused under
287
+ * (`--max-age`, display only: ghLogin's `lookup`). It is
288
+ * - the GitHub host;
289
+ * - the gh this read would run: `PATH` resolved against `cwd`, as the spawn resolves it, by its path, real path
290
+ * and file (so another deployment's relative PATH entry, or a binary replaced in place, is another context);
291
+ * - the NAMES of the token variables that are set, never their values, not even a digest of them;
292
+ * - `GH_HOST`, and gh's config directory as `GH_CONFIG_DIR`, `XDG_CONFIG_HOME` or `HOME` locate it;
293
+ * - the file of the hosts.yml there, as stat sees it: a `gh auth login`, `logout` or `switch` rewrites it.
294
+ * null when the gh to run cannot be found: such a read is never reused. What it does not see (a token variable
295
+ * given another value, a token revoked server-side) reuses the login until the record is older than --max-age,
296
+ * as a head moved on the remote reads unmoved. */
297
+ export function ghLoginParts(ghHost, env = process.env, cwd = process.cwd()) {
298
+ const stamp = (p) => { const st = statSync(p); return `${st.dev}:${st.ino}:${st.size}:${st.mtimeMs}:${st.ctimeMs}`; };
299
+ const gh = onPath("gh", env.PATH, cwd);
300
+ let binary;
301
+ try { binary = gh && `${gh}\0${realpathSync(gh)}\0${stamp(gh)}`; } catch { binary = null; }
302
+ if (!binary) return null;
303
+ const config = resolve(cwd, env.GH_CONFIG_DIR || (env.XDG_CONFIG_HOME ? join(env.XDG_CONFIG_HOME, "gh") : join(env.HOME ?? "", ".config", "gh")));
304
+ let hosts = "absent";
305
+ try { hosts = stamp(join(config, "hosts.yml")); } catch { /* absent or unreadable: as such */ }
306
+ const tokens = GH_TOKEN_VARS.filter((v) => typeof env[v] === "string" && env[v] !== "");
307
+ return [ghHost, binary, `tokens=${tokens.join(",")}`, `GH_HOST=${env.GH_HOST ?? ""}`, `config=${config}`, `hosts=${hosts}`];
308
+ }
309
+ /** How long the live lookup waits for gh before it is a failure: an act that places or fires an automation
310
+ * (a schedule tick, a trigger poll, a run) waits as long as it always has. */
311
+ export const GH_LOGIN_TIMEOUT_MS = 30_000;
312
+ /** How long the lookup behind a status display waits (`workspace status`): gh's answer takes well under a second
313
+ * (one GitHub API round trip, ~0.2 s of gh start), so 5 s is far above it; a hung gh then costs a read, which
314
+ * a client may run every few seconds, 5 s instead of 30. The placement shown says why (owner-mismatch). */
315
+ export const GH_LOGIN_DISPLAY_TIMEOUT_MS = 5_000;
316
+ /** The account the host's `gh` is logged in as on one GitHub host (`gh api user`), memoized in `cache` (one per
317
+ * tick). `io.gh(args, { timeout })` is the seam. `lookup` is the display's (`workspace status`), never an act's:
318
+ * `{ observe(ghHost), timeoutMs }`, `observe` answering a lib/remote.mjs factObservation (under --max-age a
319
+ * successful login is recorded and reused while recent; a failed one is never recorded and ends that reuse) or
320
+ * null, `timeoutMs` the wait (GH_LOGIN_TIMEOUT_MS without it). → { ok, login } | { ok: false, error } */
321
+ export function ghLogin(ghHost, { io, cache, lookup } = {}) {
277
322
  if (cache?.has(ghHost)) return cache.get(ghHost);
323
+ const fact = lookup?.observe?.(ghHost) ?? null;
324
+ const timeout = lookup?.timeoutMs ?? GH_LOGIN_TIMEOUT_MS;
325
+ const reused = fact?.reuse();
326
+ if (typeof reused === "string" && reused) { const out = { ok: true, login: reused }; cache?.set(ghHost, out); return out; }
278
327
  const argv = ["api", "user", "--jq", ".login", ...(ghHost === "github.com" ? [] : ["--hostname", ghHost])];
279
328
  let r;
280
- if (io?.gh) r = io.gh(argv);
329
+ if (io?.gh) r = io.gh(argv, { timeout });
281
330
  else {
282
- const p = spawnSync("gh", argv, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 30_000, env: { ...process.env, GH_PROMPT_DISABLED: "1" } });
331
+ const p = spawnSync("gh", argv, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout, env: { ...process.env, GH_PROMPT_DISABLED: "1" } });
283
332
  r = p.error ? { status: 127, stdout: "", stderr: p.error.code === "ENOENT" ? "gh is not installed on this host" : p.error.message } : p;
284
333
  }
285
334
  const login = String(r.stdout || "").trim();
286
335
  const out = r.status === 0 && login ? { ok: true, login } : { ok: false, error: String(r.stderr || r.stdout).split("\n").map((l) => l.trim()).find(Boolean) || `gh exited ${r.status}` };
336
+ // A failed answer is not recorded, and it ends the reuse of an earlier success: the next read asks again.
337
+ if (out.ok) fact?.record(login); else fact?.forget();
287
338
  cache?.set(ghHost, out);
288
339
  return out;
289
340
  }
290
341
  /** Where a workspace trigger or schedule runs, from this host's point of view.
291
342
  * → { runsHere, reason: null | host-unnamed | assigned-elsewhere | owner-mismatch | untrusted, detail?, enabledHere } */
292
- export function placementOf(a, { host, io, cache }) {
343
+ export function placementOf(a, { host, io, cache, lookup }) {
293
344
  const enabledHere = a.enabled !== false && !host.disabled[a.kind]?.has(a.id);
294
345
  let reason = null, detail;
295
346
  if (!host.name) { reason = "host-unnamed"; detail = "this host has no host.name in oats-local.yaml"; }
296
347
  else if (a.runsOn !== host.name) { reason = "assigned-elsewhere"; detail = `runs on ${a.runsOn}; this host is ${host.name}`; }
297
348
  else {
298
349
  const owner = parseOwner(a.owner);
299
- const who = owner ? ghLogin(owner.host, { io, cache }) : { ok: false, error: "owner is not <host>/<login>" };
350
+ const who = owner ? ghLogin(owner.host, { io, cache, lookup }) : { ok: false, error: "owner is not <host>/<login>" };
300
351
  if (!who.ok) { reason = "owner-mismatch"; detail = `acts as ${a.owner}, but this host's gh is not logged in on ${owner?.host ?? "?"}: ${who.error}`; }
301
352
  else if (who.login.toLowerCase() !== owner.login.toLowerCase()) { reason = "owner-mismatch"; detail = `acts as ${a.owner}; this host's gh is logged in as ${owner.host}/${who.login}`; }
302
353
  else if (!trusted(host, a.id)) { reason = "untrusted"; detail = `declared for this host, not trusted here; to run it, ${trustRemedy(a.id)}`; }
@@ -313,7 +364,7 @@ export function localEntry(kind, def, { invalid = null, dep = null } = {}) {
313
364
  * and it is ten minutes old — at most one attempt per interval) and each workspace trigger and
314
365
  * schedule placed on this host, kept per kind.
315
366
  * → { snapshot, host, triggers: [entry + placement], schedules: [...], refresh: null | { ok, error? } } */
316
- export function automationContext(dep, { local, io, now = new Date(), refresh = false, cache = new Map(), clonePathOf = null } = {}) {
367
+ export function automationContext(dep, { local, io, now = new Date(), refresh = false, cache = new Map(), clonePathOf = null, lookup } = {}) {
317
368
  let snapshot = readSnapshot(dep);
318
369
  let refreshed = null;
319
370
  const realizesWorkspace = typeof local?.workspace === "string" && local?.standalone === undefined;
@@ -325,7 +376,7 @@ export function automationContext(dep, { local, io, now = new Date(), refresh =
325
376
  if (refreshed.ok) snapshot = readSnapshot(dep);
326
377
  }
327
378
  const host = hostOf(local);
328
- const place = (list) => (list || []).map((a) => ({ ...a, origin: { ...a.origin, ...originLinks(a.origin, clonePathOf) }, placement: placementOf(a, { host, io, cache }) }));
379
+ const place = (list) => (list || []).map((a) => ({ ...a, origin: { ...a.origin, ...originLinks(a.origin, clonePathOf) }, placement: placementOf(a, { host, io, cache, lookup }) }));
329
380
  const ctx = { snapshot, host, ...Object.fromEntries(KIND_NAMES.map((k) => [`${k}s`, place(snapshot?.[`${k}s`])])), refresh: refreshed };
330
381
  /** The login this host's gh is authenticated as on each GitHub host the listed items (and
331
382
  * `extraHosts`) name: { <host>: <login> | null }. Asked once per host (the tick's cache). */
@@ -0,0 +1,12 @@
1
+ /** lib/captured-context.mjs — the refusal of an inherited captured context (the captured/portable path was
2
+ * removed in 0.26): an environment that carries OATS_RESOLUTION or OATS_DEPLOYMENT runs no kernel command
3
+ * but `version`, never against the current context in its place. The CLI's dispatch asks it for every
4
+ * command; a process answering reads asks it for each request. Kernel-private, not exported from
5
+ * `./core`. Dependency-free. */
6
+
7
+ /** → null, or the refusal `{ code: "E_UNSUPPORTED_MODE", message, details: { inherited } }` of `env`. */
8
+ export function inheritedContextRefusal(env) {
9
+ const inherited = ["OATS_RESOLUTION", "OATS_DEPLOYMENT"].filter((k) => env[k]);
10
+ if (!inherited.length) return null;
11
+ return { code: "E_UNSUPPORTED_MODE", message: `this environment carries a captured context (${inherited.join(", ")}): the captured/portable path was removed in 0.26, and nothing is run against the current context in its place — retire the captured home and re-spawn it from the deployment`, details: { inherited } };
12
+ }
@@ -0,0 +1,36 @@
1
+ /** Node's compile cache for the CLI (awebai/oats#1630): V8 keeps the code it compiled for the
2
+ * kernel's modules, so a command does not recompile them all on every run. Kernel-private, not
3
+ * exported from `./core` and not a contract: `bin/oats.mjs` calls enableCliCompileCache before it
4
+ * imports the kernel (only the dependency-free lib/hot-reads.mjs is parsed before), and in-process
5
+ * consumers never call it (they run in their own processes).
6
+ *
7
+ * - The cache is `$OATS_HOME_DIR/compile-cache` (`~/.oats/compile-cache`), made 0700 here: Node's
8
+ * default, `os.tmpdir()/node-compile-cache`, is shared by every user of the computer, and Node
9
+ * would make the directory 0755. Node keeps one subdirectory per Node version under it; the whole
10
+ * directory is safe to delete at any time.
11
+ * - The caller's choice wins, and Node applies it before any of this runs: with NODE_COMPILE_CACHE
12
+ * (another place) or NODE_DISABLE_COMPILE_CACHE (none) set, nothing is made or written under
13
+ * OATS_HOME_DIR. There is no OATS variable for it.
14
+ * - Never in the way: a Node without enableCompileCache (22.0), a directory that cannot be made or
15
+ * written, any throw, is simply no cache, with nothing printed. NODE_COMPILE_CACHE is never set in
16
+ * the environment, so hooks and other children inherit only what the caller gave.
17
+ * Node built-ins only, so that it parses nothing of the kernel. */
18
+ import { mkdirSync } from "node:fs";
19
+ import module from "node:module";
20
+ import { homedir } from "node:os";
21
+ import { join } from "node:path";
22
+
23
+ export function enableCliCompileCache() {
24
+ // A named import would be a link-time SyntaxError on a Node that lacks it.
25
+ if (typeof module.enableCompileCache !== "function") return;
26
+ // As Node reads them: any NODE_DISABLE_COMPILE_CACHE disables, even "" or "0"; an empty
27
+ // NODE_COMPILE_CACHE is none.
28
+ if (process.env.NODE_COMPILE_CACHE || process.env.NODE_DISABLE_COMPILE_CACHE !== undefined) return;
29
+ try {
30
+ const dir = join(process.env.OATS_HOME_DIR || join(homedir(), ".oats"), "compile-cache");
31
+ // Made here first, also because Node 22 never returns from a directory it cannot make.
32
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
33
+ // The string form: Node 22 takes no options object.
34
+ module.enableCompileCache(dir);
35
+ } catch { /* no cache */ }
36
+ }