@awebai/oats 0.51.0 → 0.53.0

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 (166) hide show
  1. package/README.md +3 -1
  2. package/bin/oats.mjs +407 -123
  3. package/docs/capabilities.md +75 -6
  4. package/docs/configuration.md +200 -91
  5. package/docs/desktop-cli-api.md +1563 -113
  6. package/docs/desktop-instance-start.md +69 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +145 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +238 -17
  12. package/docs/integrations.md +13 -9
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +25 -2
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/macos-test-runs.md +246 -0
  20. package/docs/oats-local.schema.json +4 -3
  21. package/docs/official-catalog.md +5 -5
  22. package/docs/packages.md +14 -14
  23. package/docs/release-lane.md +225 -11
  24. package/docs/release-notes/v0.44.0.md +1 -1
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/release-notes/v0.53.0.md +1274 -0
  27. package/docs/schedules.md +97 -4
  28. package/docs/souls-and-instances.md +332 -40
  29. package/docs/tui.md +584 -0
  30. package/docs/upgrading.md +298 -0
  31. package/docs/workspaces.md +3 -3
  32. package/lib/automations.mjs +22 -22
  33. package/lib/claim.mjs +278 -49
  34. package/lib/config-data.mjs +4 -1
  35. package/lib/core.mjs +1282 -289
  36. package/lib/errors.mjs +170 -0
  37. package/lib/harness-trust-write.mjs +68 -27
  38. package/lib/harness-trust.mjs +34 -16
  39. package/lib/instance-events.mjs +19 -1
  40. package/lib/instance-git.mjs +39 -3
  41. package/lib/instance-inspect.mjs +45 -17
  42. package/lib/instance-lifecycle.mjs +306 -57
  43. package/lib/instance-resolution.mjs +59 -6
  44. package/lib/launch-preference.mjs +236 -9
  45. package/lib/launch-prompt-completion.mjs +7 -43
  46. package/lib/launch-prompt-evidence.mjs +14 -7
  47. package/lib/launch-prompt-fixtures/README.md +86 -152
  48. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  49. package/lib/launch-prompt-fixtures.mjs +122 -109
  50. package/lib/launch-prompt-transport.mjs +2 -56
  51. package/lib/launch-prompts.mjs +102 -100
  52. package/lib/local-edit.mjs +118 -0
  53. package/lib/packages.mjs +13 -4
  54. package/lib/pi-bridge.mjs +308 -0
  55. package/lib/refused-text.mjs +11 -0
  56. package/lib/remote.mjs +190 -25
  57. package/lib/resolve.mjs +2 -1
  58. package/lib/retained-after-retire.mjs +2 -2
  59. package/lib/retire-output.mjs +12 -1
  60. package/lib/schedule-host.mjs +125 -22
  61. package/lib/schedule.mjs +73 -24
  62. package/lib/shell-word.mjs +13 -0
  63. package/lib/soul-launch-verbs.mjs +153 -0
  64. package/lib/stable-node.mjs +62 -0
  65. package/lib/system-tools.mjs +39 -0
  66. package/lib/teams-verbs.mjs +18 -46
  67. package/lib/tmux-server-scope.mjs +62 -0
  68. package/lib/triggers.mjs +4 -4
  69. package/lib/workspace.mjs +54 -30
  70. package/lib/worktree-hooks.mjs +98 -20
  71. package/lib/worktree.mjs +83 -24
  72. package/package-catalog.json +4 -4
  73. package/package.json +8 -2
  74. package/packages/client/attach-exit.mjs +25 -0
  75. package/packages/client/capability-show-contract.mjs +230 -0
  76. package/packages/client/capability-warnings-contract.mjs +57 -0
  77. package/packages/client/cli-adapter.mjs +561 -0
  78. package/packages/client/cli-environment.mjs +53 -0
  79. package/packages/client/cli-locator.mjs +253 -0
  80. package/packages/client/cli-probe-contract.mjs +47 -0
  81. package/packages/client/client-terms.mjs +60 -0
  82. package/packages/client/deployment-contract.mjs +72 -0
  83. package/packages/client/deployment-data.mjs +483 -0
  84. package/packages/client/deployment-facts.mjs +95 -0
  85. package/packages/client/deployment-label.mjs +76 -0
  86. package/packages/client/deployment-observer.mjs +89 -0
  87. package/packages/client/deployment-panel.mjs +180 -0
  88. package/packages/client/deployment-read-cli.mjs +57 -0
  89. package/packages/client/display-text.mjs +50 -0
  90. package/packages/client/harness-names.mjs +30 -0
  91. package/packages/client/inspect-contract.mjs +62 -0
  92. package/packages/client/instance-acts.mjs +90 -0
  93. package/packages/client/instance-admission.mjs +45 -0
  94. package/packages/client/instance-events-contract.mjs +76 -0
  95. package/packages/client/instance-git-contract.mjs +80 -0
  96. package/packages/client/instance-presentation.mjs +86 -0
  97. package/packages/client/instance-tree.mjs +462 -0
  98. package/packages/client/kernel-environment.mjs +11 -0
  99. package/packages/client/kernel-lines.mjs +31 -0
  100. package/packages/client/kernel-made.mjs +23 -0
  101. package/packages/client/launch-contract.mjs +51 -0
  102. package/packages/client/launch-prompt-outcome.mjs +200 -0
  103. package/packages/client/lifecycle-cli.mjs +61 -0
  104. package/packages/client/lifecycle-contract.mjs +413 -0
  105. package/packages/client/liveness-main.mjs +10 -0
  106. package/packages/client/liveness.mjs +48 -0
  107. package/packages/client/machine-contract.mjs +123 -0
  108. package/packages/client/own-codes.mjs +31 -0
  109. package/packages/client/own-environment.mjs +22 -0
  110. package/packages/client/panel-views.mjs +293 -0
  111. package/packages/client/readiness-contract.mjs +174 -0
  112. package/packages/client/refresh-loop.mjs +52 -0
  113. package/packages/client/remote-address.mjs +151 -0
  114. package/packages/client/remote-identity-memory.mjs +94 -0
  115. package/packages/client/remote-roster.mjs +153 -0
  116. package/packages/client/roster-sections.mjs +80 -0
  117. package/packages/client/session-attach.mjs +175 -0
  118. package/packages/client/spawn-apply-cli.mjs +104 -0
  119. package/packages/client/spawn-apply-contract.mjs +195 -0
  120. package/packages/client/spawn-decision.mjs +46 -0
  121. package/packages/client/spawn-messages.mjs +142 -0
  122. package/packages/client/spawn-preview-cli.mjs +38 -0
  123. package/packages/client/spawn-preview-contract.mjs +318 -0
  124. package/packages/client/team-members.mjs +41 -0
  125. package/packages/client/team-rows.mjs +45 -0
  126. package/packages/client/terminal-contract.mjs +57 -0
  127. package/packages/client/terminal-exec.mjs +21 -0
  128. package/packages/client/tmux-status.mjs +66 -0
  129. package/packages/client/waiting-on-you.mjs +88 -0
  130. package/packages/client/workspace-admission.mjs +45 -0
  131. package/packages/client/workspace-choices.mjs +95 -0
  132. package/packages/client/workspace-cli.mjs +142 -0
  133. package/packages/client/workspace-views.mjs +183 -0
  134. package/packages/record/README.md +21 -0
  135. package/packages/record/bin/setup.mjs +108 -15
  136. package/packages/tui/README.md +64 -0
  137. package/packages/tui/bin/tui.mjs +7 -0
  138. package/packages/tui/lib/actions.mjs +44 -0
  139. package/packages/tui/lib/client.mjs +35 -0
  140. package/packages/tui/lib/config.mjs +151 -0
  141. package/packages/tui/lib/main.mjs +176 -0
  142. package/packages/tui/lib/model.mjs +392 -0
  143. package/packages/tui/lib/read.mjs +473 -0
  144. package/packages/tui/lib/store.mjs +364 -0
  145. package/packages/tui/lib/term/keys.mjs +367 -0
  146. package/packages/tui/lib/term/screen.mjs +134 -0
  147. package/packages/tui/lib/term/style.mjs +43 -0
  148. package/packages/tui/lib/term/text.mjs +109 -0
  149. package/packages/tui/lib/term/tty.mjs +178 -0
  150. package/packages/tui/lib/term/width.mjs +124 -0
  151. package/packages/tui/lib/views/detail.mjs +46 -0
  152. package/packages/tui/lib/views/frame.mjs +256 -0
  153. package/packages/tui/lib/views/help.mjs +140 -0
  154. package/packages/tui/lib/views/instances.mjs +137 -0
  155. package/packages/tui/lib/views/scroll.mjs +19 -0
  156. package/packages/tui/lib/views/switcher.mjs +97 -0
  157. package/packages/tui/package.json +8 -0
  158. package/skills/oats-getting-started/SKILL.md +30 -23
  159. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  160. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  161. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  162. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  163. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  164. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  165. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  166. package/lib/launch-prompt-policy.mjs +0 -87
@@ -7,15 +7,11 @@
7
7
  * schema, and no label reference the write would leave unknown. A soul's teams are the workspace's
8
8
  * `souls:`, edited by a PR to that file: `oats soul teams` only reads them.
9
9
  */
10
- import { readFileSync } from "node:fs";
11
- import { join } from "node:path";
12
10
  import YAML from "yaml";
13
- import { parseConfigData } from "./config-data.mjs";
14
11
  import { oatsError } from "./errors.mjs";
15
- import { teamLabelProblem, validateLocal } from "./workspace.mjs";
12
+ import { teamLabelProblem } from "./workspace.mjs";
16
13
  import { TEAM_ID_RE, localTeamsClosed, soulTeams, teamModel, teamProblems, teamReferences } from "./teams.mjs";
17
- import { writeFileAtomic } from "./packages.mjs";
18
- import { withDirLock } from "./dir-lock.mjs";
14
+ import { editLocal } from "./local-edit.mjs";
19
15
 
20
16
  export const TEAMS_API = 2, SOUL_TEAMS_API = 2;
21
17
  const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
@@ -66,13 +62,6 @@ const modelOf = (ctx, local) => teamModel(ctx.workspace, local, { workspaceKey:
66
62
  const refusals = (ctx, local) => new Map(teamProblems(modelOf(ctx, local))
67
63
  .filter((p) => p.code === "E_TEAM_UNKNOWN").map((p) => [`${p.code} ${p.at}`, p]));
68
64
  const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
69
- const readLocal = (ctx) => {
70
- const text = readFileSync(ctx.localPath, "utf8");
71
- const doc = YAML.parseDocument(text, { keepSourceTokens: true });
72
- if (doc.errors?.length) throw fail("E_WORKSPACE_SCHEMA", `${ctx.localPath}: ${doc.errors[0].message}`, { path: ctx.localPath });
73
- return { text, doc, local: parseConfigData(text, { origin: { kind: "local", path: ctx.localPath } }).value };
74
- };
75
-
76
65
  /**
77
66
  * Edit `doc` from `before` to `next` SURGICALLY: only the entries that change are touched, so comments and
78
67
  * styles on everything else (inline comments on sibling entries) are kept. A map left empty is removed.
@@ -94,46 +83,29 @@ function applyState(doc, before, next) {
94
83
  }
95
84
 
96
85
  /**
97
- * Rewrite oats-local.yaml. `mutate(state, model)` edits the plain `state` (teamState) and may throw a
98
- * refusal; both come from the file AS IT IS NOW (re-read here, never the command's startup snapshot), so
99
- * two verbs running together cannot drop each other's change: the write is compare-and-swap — when the
100
- * file changed after this read, the edit is redone on the new content (a few times, then E_LOCAL_CHANGED).
86
+ * Rewrite oats-local.yaml through the shared edit path (lib/local-edit.mjs editLocal: the file as it is
87
+ * NOW, the deployment's local lock, compare-and-swap, the local schema). `mutate(state, model)` edits the
88
+ * plain `state` (teamState) and may throw a refusal; both come from the file as that path read it, so two
89
+ * verbs running together cannot drop each other's change, and a conditional write sees every earlier one.
101
90
  * `verb` names the command and `writes` the keys it adds, for the refusal where the workspace does not
102
91
  * allow local teams (local-teams-closed); a verb that only takes local teams away (`writes: null`) runs
103
92
  * there too, since it moves the file toward what the workspace allows. → { changed, local } (the value now).
104
- * The whole read-compare-write runs under the deployment's local lock (localLock), so among `oats teams`
105
- * writers the compare and the rename are one step: a conditional write sees every earlier one.
93
+ * A write is also refused when it would leave a label reference unknown that the file did not have.
106
94
  */
107
- function editLocal(ctx, { verb, writes }, mutate) {
108
- const lock = localLock(ctx);
109
- return withDirLock(lock, `${verb} on ${ctx.localPath}`, () => editLocalLocked(ctx, { verb, writes }, mutate), {
110
- retryMs: 5000,
111
- busy: (why) => fail("E_LOCAL_BUSY", `${ctx.localPath} is being edited by another oats process (the lock ${lock}: ${why}); if no oats teams command is running, remove ${lock} and retry; nothing was written`, { path: ctx.localPath, lock }),
112
- });
113
- }
114
- /** The lock every `oats teams` mutation holds: in the deployment's kernel state tree, never beside the files. */
115
- const localLock = (ctx) => join(ctx.deployment, ".agents", "locks", "local.lock");
116
- function editLocalLocked(ctx, { verb, writes }, mutate) {
117
- for (let attempt = 0; attempt < 5; attempt++) {
118
- const { text, doc, local: current } = readLocal(ctx);
95
+ function editTeams(ctx, { verb, writes }, mutate) {
96
+ return editLocal(ctx, { verb }, ({ doc, local: current }) => {
119
97
  const model = modelOf(ctx, current);
120
98
  if (model.localTeams === false && writes !== null) throw localTeamsClosed(writes, { verb });
121
99
  const before = teamState(current);
122
100
  const next = teamState(current);
123
101
  mutate(next, model);
124
- if (same(next, before)) return { changed: false, local: current };
102
+ if (same(next, before)) return null;
125
103
  applyState(doc, before, next);
126
- const out = doc.toString();
127
- const local = parseConfigData(out, { origin: { kind: "local", path: ctx.localPath } }).value;
128
- const problems = validateLocal(local);
129
- if (problems.length) throw fail("E_WORKSPACE_SCHEMA", `the rewritten oats-local.yaml would be invalid (${problems.map((p) => `${p.path || "/"}: ${p.message}`).join("; ")}); nothing was written`, { problems });
130
- const had = refusals(ctx, current);
131
- for (const [k, p] of refusals(ctx, local)) if (!had.has(k)) throw fail(p.code, `${p.message}; nothing was written`, Object.fromEntries(Object.entries(p).filter(([key]) => !["code", "severity", "message", "fix"].includes(key))));
132
- if (readFileSync(ctx.localPath, "utf8") !== text) continue; // changed under us: redo on the new content
133
- writeFileAtomic(ctx.localPath, out);
134
- return { changed: true, local };
135
- }
136
- throw fail("E_LOCAL_CHANGED", `${ctx.localPath} kept changing while this edit ran; nothing was written — run it again`, { path: ctx.localPath });
104
+ return { check: (local) => {
105
+ const had = refusals(ctx, current);
106
+ for (const [k, p] of refusals(ctx, local)) if (!had.has(k)) throw fail(p.code, `${p.message}; nothing was written`, Object.fromEntries(Object.entries(p).filter(([key]) => !["code", "severity", "message", "fix"].includes(key))));
107
+ } };
108
+ });
137
109
  }
138
110
 
139
111
  const assertLabel = (label) => {
@@ -149,7 +121,7 @@ export function teamsAdd(ctx, label, { team, description, noDefault = false } =
149
121
  if (typeof team !== "string" || !team.trim()) throw fail("E_BAD_ARGS", "oats teams add needs --team <provider team id>", { label });
150
122
  if (!TEAM_ID_RE.test(team.trim())) throw fail("E_BAD_ARGS", `${JSON.stringify(team)} is not a team id: it must match ${TEAM_ID_RE.source} (a letter or digit first; no whitespace or control characters; at most 256 characters)`, { label, team });
151
123
  let reused = false;
152
- const result = editLocal(ctx, { verb: "oats teams add", writes: ["teams"] }, (s, model) => {
124
+ const result = editTeams(ctx, { verb: "oats teams add", writes: ["teams"] }, (s, model) => {
153
125
  if (model.labels.has(label)) {
154
126
  const { from, team: existing } = model.labels.get(label);
155
127
  if (noDefault && existing === team.trim()) { reused = true; return; }
@@ -165,7 +137,7 @@ export function teamsAdd(ctx, label, { team, description, noDefault = false } =
165
137
  /** `oats teams remove <label>`: a LOCAL team nothing references (no cascade). Allowed where the workspace
166
138
  * does not allow local teams: removing them is the last step of committing them there. */
167
139
  export function teamsRemove(ctx, label) {
168
- return editLocal(ctx, { verb: "oats teams remove", writes: null }, (s, model) => {
140
+ return editTeams(ctx, { verb: "oats teams remove", writes: null }, (s, model) => {
169
141
  if (!model.local.has(label)) {
170
142
  if (model.shared.has(label)) throw fail("E_TEAM_SHARED", `team ${label} is shared (declared in oats-workspace.yaml): it is edited by a PR to that file, never removed here`, { label, at: model.shared.get(label).at });
171
143
  throw fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared`, { label });
@@ -192,7 +164,7 @@ function assertDefaultPrecondition(model, { ifAbsent, expect }) {
192
164
  * judged inside the edit, on the file as it is now (and again on every retry), after today's refusals. */
193
165
  export function teamsDefault(ctx, label, { ifAbsent = false, expect } = {}) {
194
166
  if (ifAbsent && expect !== undefined) throw fail("E_BAD_ARGS", "oats teams default takes --if-absent or --expect <label>, not both", { label });
195
- return editLocal(ctx, { verb: "oats teams default", writes: ["defaultTeam"] }, (s, model) => {
167
+ return editTeams(ctx, { verb: "oats teams default", writes: ["defaultTeam"] }, (s, model) => {
196
168
  if (!model.labels.has(label)) throw fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared: \`oats teams add\` it first`, { label });
197
169
  if (ifAbsent || expect !== undefined) assertDefaultPrecondition(model, { ifAbsent, expect });
198
170
  s.defaultTeam = label;
@@ -0,0 +1,62 @@
1
+ /** Whether the OATS tmux server starts in a systemd scope of its own (awebai/oats#915).
2
+ * A server started by a process inside a systemd service lives in that service's cgroup and dies
3
+ * when the unit stops: the schedule tick's oneshot, or a Desktop run as a user service. On Linux,
4
+ * from inside a service, on the unified cgroup hierarchy, the server's start runs under
5
+ * `systemd-run --user --scope`: the server is then a sibling of the service, not part of it.
6
+ * Everything else starts the server as before. */
7
+ import { createHash, randomBytes } from "node:crypto";
8
+ import { readFileSync } from "node:fs";
9
+
10
+ const HIERARCHY = "the cgroup hierarchy is not the unified one, so there is no unified cgroup path to judge";
11
+ /** The last component of an absolute cgroup path, when it names a systemd service. */
12
+ function serviceOf(path) {
13
+ if (typeof path !== "string" || !path.startsWith("/")) return null;
14
+ const last = path.split("/").pop();
15
+ return last.endsWith(".service") ? last : null;
16
+ }
17
+
18
+ /** → { wrap: true, unit } (inside `unit`, start the server in its own scope), { wrap: false }, or
19
+ * { wrap: false, warn: { unit, reason } } (inside a service, known only from INVOCATION_ID, on a
20
+ * hierarchy this cannot judge). `cgroup` is the text of /proc/self/cgroup, null when unreadable. */
21
+ export function serverScopePlan({ platform, cgroup, invocationId }) {
22
+ if (platform !== "linux" || typeof cgroup !== "string") return { wrap: false };
23
+ const lines = cgroup.split("\n").filter(Boolean);
24
+ if (lines.length === 1 && lines[0].startsWith("0::") && lines[0].slice(3).startsWith("/")) {
25
+ const unit = serviceOf(lines[0].slice(3));
26
+ return unit ? { wrap: true, unit } : { wrap: false };
27
+ }
28
+ if (!invocationId) return { wrap: false };
29
+ // The service the systemd hierarchy names, when one does: a hybrid host's 0:: line, or v1's name=systemd.
30
+ const named = lines.map((line) => /^(?:0::|\d+:name=systemd:)(\/.*)$/.exec(line)?.[1]).map(serviceOf).find(Boolean);
31
+ return { wrap: false, warn: { unit: named || "a systemd service", reason: HIERARCHY } };
32
+ }
33
+
34
+ /** Where the creator runs → { platform, cgroup, invocationId }: `io`'s when it says, else for a test only
35
+ * OATS_TEST_CGROUP (the text of a /proc/self/cgroup, judged as Linux), else this process's own (null
36
+ * cgroup when it cannot be read, or off Linux). */
37
+ export function creatorPlacement(io) {
38
+ const seam = process.env.OATS_TEST_CGROUP;
39
+ const platform = io?.platform ?? (seam !== undefined ? "linux" : process.platform);
40
+ let cgroup = io?.cgroup;
41
+ if (cgroup === undefined) {
42
+ if (seam !== undefined) cgroup = seam;
43
+ else if (platform === "linux") { try { cgroup = readFileSync("/proc/self/cgroup", "utf8"); } catch { cgroup = null; } }
44
+ else cgroup = null;
45
+ }
46
+ const invocationId = io && "invocationId" in io ? io.invocationId : process.env.INVOCATION_ID;
47
+ return { platform, cgroup, invocationId };
48
+ }
49
+
50
+ /** The scope's name, one per start that starts the server: a prefix per server address (the socket
51
+ * when it is known, else `-L oats` under the TMUX_TMPDIR the tmux client resolves it in, tmux's
52
+ * default /tmp when unset) and a random part. A scope ends with its last process, which is not
53
+ * always the server (a pane's process can outlive it), so a later start never reuses its name. */
54
+ export function serverScopeUnit({ socket, env }) {
55
+ const address = socket ? socket : `-L oats\0${env?.TMUX_TMPDIR || "/tmp"}`;
56
+ return `oats-tmux-${createHash("sha256").update(address).digest("hex").slice(0, 12)}-${randomBytes(4).toString("hex")}`;
57
+ }
58
+
59
+ /** The answer's warning when the server was started inside a service after all. */
60
+ export function serverScopeWarning({ unit, reason }) {
61
+ return `the OATS tmux server was started inside ${unit}: it ends when that unit stops; start the OATS tmux server from your own shell, or enable the user systemd bus (${reason})`;
62
+ }
package/lib/triggers.mjs CHANGED
@@ -39,7 +39,7 @@ import { createHash } from "node:crypto";
39
39
  import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
40
40
  import { dirname, join } from "node:path";
41
41
  import { fileURLToPath } from "node:url";
42
- import { readDefinitions, writeDefinitions, stateDir, withScopeLock, childEnv, parseEnvelopeText, schedulerStatus, readRegistry, definitionsPath } from "./schedule.mjs";
42
+ import { readDefinitions, writeDefinitions, stateDir, withScopeLock, childEnv, parseEnvelopeText, schedulerStatus, readRegistry, definitionsPath, runWarnings } from "./schedule.mjs";
43
43
  import { herdrSettingRemoved } from "./errors.mjs";
44
44
  import { MODEL_RE, SNAPSHOT_MAX_AGE_MS, automationError, baseRow, localEntry, localId, parseOwner, qualifiedId, soulOriginOf, validateDescription } from "./automations.mjs";
45
45
  import { judgeAnswer, pollFailure, triggerSourcesOf } from "./trigger-sources.mjs";
@@ -774,7 +774,7 @@ const isNewEvent = (ts, key) => !ts.fired[key] && !ts.pending[key];
774
774
  const pendingQueue = (ts) => Object.values(ts.pending).map(withSubject).sort((a, b) => a.observedAt.localeCompare(b.observedAt) || a.key.localeCompare(b.key));
775
775
  /** Record a spawned event as fired (only after its spawn succeeded: at least once). */
776
776
  function recordFired(ts, ev, run, now) {
777
- ts.fired[ev.key] = { at: now.toISOString(), instance: run.instance ?? null, home: run.home ?? null, event: ev.event, number: ev.number ?? null, subject: ev.subject };
777
+ ts.fired[ev.key] = { at: now.toISOString(), instance: run.instance ?? null, home: run.home ?? null, event: ev.event, number: ev.number ?? null, subject: ev.subject, ...runWarnings(run) };
778
778
  delete ts.pending[ev.key];
779
779
  ts.lastFiredAt = now.toISOString();
780
780
  }
@@ -882,7 +882,7 @@ export function spawnForEvent(ws, def, ev, io, pv = previewSoul(ws, def, io)) {
882
882
  if (r.timedOut) throw triggerError("E_SPAWN_UNCONFIRMED", "the trigger's spawn timed out; a home may exist (it counts toward concurrency) — the event is retried on the next poll");
883
883
  if (!r.envelope || typeof r.envelope.ok !== "boolean") throw triggerError("E_SPAWN_UNCONFIRMED", `the trigger's spawn answered no envelope (exit ${r.status})${r.stderr ? `: ${r.stderr.trim().split("\n").pop()}` : ""}`);
884
884
  if (!r.envelope.ok) throw triggerError(r.envelope.error?.code || "E_SPAWN_FAILED", String(r.envelope.error?.message || "spawn failed"), { details: r.envelope.error?.details });
885
- return { instance: r.envelope.result?.instance, home: r.envelope.result?.home };
885
+ return { instance: r.envelope.result?.instance, home: r.envelope.result?.home, ...runWarnings(r.envelope.result) };
886
886
  }
887
887
 
888
888
  /** Admission of one pending event against the trigger's concurrency. → null | reason */
@@ -1053,7 +1053,7 @@ function triggerRow(ws, e, st, ctx) {
1053
1053
  const ts = stateFor(st.triggers[e.id], e.definition?.on?.source);
1054
1054
  const fired = Object.entries(ts?.fired || {}).map(([key, f]) => ({ key, ...f })).sort((a, b) => b.at.localeCompare(a.at));
1055
1055
  const pollMs = parsePoll(e.definition?.on?.poll ?? DEFAULT_POLL);
1056
- const lastRun = fired[0] ? { at: fired[0].at, instance: fired[0].instance ?? null, home: fired[0].home ?? null, event: fired[0].event, number: fired[0].number, subject: subjectOf(fired[0]), key: fired[0].key } : null;
1056
+ const lastRun = fired[0] ? { at: fired[0].at, instance: fired[0].instance ?? null, home: fired[0].home ?? null, event: fired[0].event, number: fired[0].number, subject: subjectOf(fired[0]), key: fired[0].key, ...runWarnings(fired[0]) } : null;
1057
1057
  const nextDue = e.placement.runsHere && ts?.lastPollAt && pollMs ? new Date(Date.parse(ts.lastPollAt) + pollMs).toISOString() : null;
1058
1058
  const local = e.member === "local";
1059
1059
  const def = e.definition || {};
package/lib/workspace.mjs CHANGED
@@ -12,7 +12,6 @@
12
12
  */
13
13
  import { readFileSync, existsSync } from "node:fs";
14
14
  import { dirname, join, resolve } from "node:path";
15
- import { launchPromptPolicyProblems } from "./launch-prompt-policy.mjs";
16
15
  import { recordLocalInput } from "./local-inputs.mjs";
17
16
  import { parseConfigData } from "./config-data.mjs";
18
17
  import { oatsError } from "./errors.mjs";
@@ -42,6 +41,12 @@ function remoteOf(options) {
42
41
  /** The parsed cache (lib/remote.mjs memoAtCommit, optional on the remote contract): `compute()` is a pure
43
42
  * function of the bytes at (ref's key, commit) and this kernel. A remote without it — every in-memory fake —
44
43
  * just computes. */
44
+ /** Whether a member's enumeration may be missing a soul: it says so (`soulsSkipped`, enumerateRepo), or it
45
+ * carries no such record. What a read did not record, it did not establish: an enumeration that was not
46
+ * written by this build (whatever built it) says nothing about the souls it skipped, so it counts as one
47
+ * that skipped some. The parsed cache is not how that arises: its entries are kept per kernel fingerprint,
48
+ * and another build's are never read (lib/remote.mjs, test/parsed-cache.test.mjs). */
49
+ const skippedSome = (soulsSkipped) => !Array.isArray(soulsSkipped) || soulsSkipped.length > 0;
45
50
  function atCommit(remote, ref, commit, item, compute) {
46
51
  return typeof remote.memoAtCommit === "function" ? remote.memoAtCommit(ref, commit, item, compute) : compute();
47
52
  }
@@ -282,6 +287,11 @@ const REMOVED_KEYS = {
282
287
  local: [
283
288
  { at: (v) => (isObject(v?.souls) && Object.hasOwn(v.souls, "teams") ? ["/souls/teams"] : []), message: "souls.teams was removed in 0.38.0 (team model 3): which teams a soul may join is souls: in oats-workspace.yaml" },
284
289
  { at: (v) => (isObject(v?.souls) && Object.hasOwn(v.souls, "default") ? ["/souls/default"] : []), message: "souls.default was removed in 0.38.0 (team model 3): a soul's default team is souls: in oats-workspace.yaml (default:)" },
290
+ // 0.52.0: launchPromptAnswers is ignored (core.mjs launchPromptAnswersNotice), except an
291
+ // operator's explicit refusal, which this kernel cannot honour and so must not drop silently.
292
+ { at: (v) => (isObject(v?.launchPromptAnswers?.homes) ? Object.entries(v.launchPromptAnswers.homes)
293
+ .filter(([, e]) => isObject(e) && e.awebDevelopmentChannel === false).map(([home]) => `/launchPromptAnswers/homes/${pointerKey(home)}`) : []),
294
+ message: "launchPromptAnswers awebDevelopmentChannel: false cannot be honoured: OATS confirms Claude's development-channel prompt whenever it launches Claude with --dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace. To keep the prompt unanswered, set settings.oats.aweb.delivery: session or settings.oats.aweb.claudeChannelMode: approved in oats-local.yaml, then remove launchPromptAnswers" },
285
295
  ],
286
296
  };
287
297
  function withRemovedKeys(problems, value, removed) {
@@ -339,16 +349,6 @@ export function validateLocal(value) {
339
349
  problems.push({ path: `/launch-configs/${pointerKey(name)}/runtime`, reason: "harness-conflict", message: `harness ${show(entry.harness)} and runtime ${show(entry.runtime)} disagree: \`runtime\` is the pre-0.27 name of \`harness\` — keep one` });
340
350
  }
341
351
  }
342
- if (isObject(value) && Object.hasOwn(value, "launchPromptAnswers")) {
343
- // Shape is checked by the schema; add filesystem-dependent canonical-home checks.
344
- for (const problem of launchPromptPolicyProblems(value.launchPromptAnswers)) {
345
- if (problem.reason === "unsupported-launch-prompt") {
346
- const index = problems.findIndex((p) => p.path === problem.path);
347
- if (index !== -1) problems.splice(index, 1);
348
- problems.push(problem);
349
- } else if (problem.reason === "noncanonical-home") problems.push(problem);
350
- }
351
- }
352
352
  return problems;
353
353
  }
354
354
 
@@ -538,18 +538,21 @@ const CAP_FILE = /^([^/]+)\/oats\.json$/;
538
538
  /**
539
539
  * Enumerate souls/*\/soul.yaml and capabilities/*\/oats.json of one repo at one commit.
540
540
  * Validates each item; collects problems instead of aborting.
541
- * → { souls: [SoulEntry], capabilities: [CapEntry], problems: [{ code, path, message, repoKey }] }
541
+ * → { souls: [SoulEntry], capabilities: [CapEntry], problems: [{ code, path, message, repoKey }],
542
+ * soulsSkipped: [path] }: where a soul may exist and is not in `souls` (the souls/ listing failed, or
543
+ * a soul.yaml could not be read or is invalid). `problems` says why; this says that a soul is missing.
542
544
  */
543
545
  async function enumerateRepo(remote, ref, key, commit) {
544
546
  const souls = [];
545
547
  const capabilities = [];
546
548
  const problems = [];
549
+ const soulsSkipped = [];
547
550
  const problem = (code, path, message) => problems.push({ code, repoKey: key, path, message });
548
551
  // A listing failure on one directory is a problem of THIS repo, never an abort of the whole picture.
549
552
  const list = async (dir) => {
550
553
  try { return await remote.listRemoteTree(ref, commit, dir, { depth: 2 }); }
551
554
  catch (e) {
552
- if (typeof e?.code === "string" && e.code.startsWith("E_REMOTE_")) { problem(e.code, dir, e.message); return []; }
555
+ if (typeof e?.code === "string" && e.code.startsWith("E_REMOTE_")) { problem(e.code, dir, e.message); if (dir === "souls") soulsSkipped.push(dir); return []; }
553
556
  throw e;
554
557
  }
555
558
  };
@@ -561,11 +564,12 @@ async function enumerateRepo(remote, ref, key, commit) {
561
564
  const file = `${path}/soul.yaml`;
562
565
  let bytes;
563
566
  try { ({ bytes } = await remote.readRemoteFile(ref, commit, file)); }
564
- catch (e) { problem(e?.code || "E_REMOTE_UNREADABLE", file, e.message); continue; }
567
+ catch (e) { problem(e?.code || "E_REMOTE_UNREADABLE", file, e.message); soulsSkipped.push(file); continue; }
565
568
  const read = readDeclaration("soul", bytes, { kind: "soul", repoKey: key, commit, path: file });
566
- if (read.problems) { for (const p of read.problems) problem("E_WORKSPACE_SCHEMA", `${file}#${p.path}`, `${p.message}${schemaHint("soul", read.value)}`); continue; }
569
+ if (read.problems) { for (const p of read.problems) problem("E_WORKSPACE_SCHEMA", `${file}#${p.path}`, `${p.message}${schemaHint("soul", read.value)}`); soulsSkipped.push(file); continue; }
567
570
  const definition = read.value;
568
571
  if (definition.name !== m[1]) problem("E_WORKSPACE_SCHEMA", `${file}#/name`, `soul name ${show(definition.name)} does not match its directory ${show(m[1])}`);
572
+ // (A second declaration of a name is not a missing soul: the first one is listed under that name.)
569
573
  if (soulNames.has(definition.name)) { problem("E_WORKSPACE_SCHEMA", `${file}#/name`, `soul name ${show(definition.name)} is already declared by ${soulNames.get(definition.name)}; the second declaration is not listed`); continue; }
570
574
  soulNames.set(definition.name, file);
571
575
  // Souls have no private mode since 0.26.0: `private` is accepted, warned (soul-private-ignored) and never hides a soul.
@@ -618,7 +622,7 @@ async function enumerateRepo(remote, ref, key, commit) {
618
622
  else throw e;
619
623
  }
620
624
  }
621
- return { souls, capabilities, publishes, problems };
625
+ return { souls, capabilities, publishes, problems, soulsSkipped };
622
626
  }
623
627
 
624
628
  /**
@@ -655,11 +659,12 @@ export function packageSoulAgentName(id, soul) { return `${String(id).replace(/[
655
659
  * (`package`, `version`) and its qualified name `<package>/<soul>`. A package soul.yaml still carrying
656
660
  * `team:` (removed in 0.30: team membership is local) is invalid and not listed.
657
661
  * Nothing here trusts the lock's digests — a spawn verifies the fetched soul against them.
658
- * `lock` null (or no workspace) → nothing. → { souls: [SoulEntry], problems }
662
+ * `lock` null (or no workspace) → nothing. → { souls: [SoulEntry], problems, skipped: [package id] }:
663
+ * `skipped` names each package with a soul the lock records and this read does not list.
659
664
  */
660
665
  export async function discoverPackageSouls(workspace, lock, { remote: injected, remoteOptions } = {}) {
661
- const souls = [], problems = [];
662
- if (!isObject(lock?.packages) || !isObject(workspace)) return { souls, problems };
666
+ const souls = [], problems = [], skipped = new Set();
667
+ if (!isObject(lock?.packages) || !isObject(workspace)) return { souls, problems, skipped: [] };
663
668
  const remote = remoteOf({ remote: injected, remoteOptions });
664
669
  const declared = isObject(workspace.packages) ? workspace.packages : {};
665
670
  for (const id of Object.keys(lock.packages).sort()) {
@@ -668,10 +673,10 @@ export async function discoverPackageSouls(workspace, lock, { remote: injected,
668
673
  const at = (rel) => `package:${id}:${rel}`;
669
674
  const problem = (code, path, message) => problems.push({ code, repoKey: null, package: id, path: at(path), message });
670
675
  const ref = lockedPackageRef(entry);
671
- if (!ref) { problem("E_PACKAGE_MISSING", entry.path, `the lock records no url for ${id} — run \`oats sync\``); continue; }
676
+ if (!ref) { problem("E_PACKAGE_MISSING", entry.path, `the lock records no url for ${id} — run \`oats sync\``); skipped.add(id); continue; }
672
677
  let key;
673
678
  try { key = remote.parseRepoRef(ref).key; }
674
- catch (e) { if (e?.code === "E_REPO_REF") { problem("E_REPO_REF", entry.path, e.message); continue; } throw e; }
679
+ catch (e) { if (e?.code === "E_REPO_REF") { problem("E_REPO_REF", entry.path, e.message); skipped.add(id); continue; } throw e; }
675
680
  for (const locked of entry.souls) {
676
681
  const path = `${entry.path}/${locked.path}`;
677
682
  const file = `${path}/soul.yaml`;
@@ -681,10 +686,10 @@ export async function discoverPackageSouls(workspace, lock, { remote: injected,
681
686
  try { return readDeclaration("soul", (await remote.readRemoteFile(ref, entry.commit, file)).bytes, { kind: "soul", repoKey: key, commit: entry.commit, path: file }); }
682
687
  catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_REMOTE_")) return { remoteError: { code: e.code, message: e.message } }; throw e; }
683
688
  });
684
- if (read.remoteError) { problem(read.remoteError.code, file, read.remoteError.message); continue; }
685
- if (read.problems) { for (const p of read.problems) problem("E_WORKSPACE_SCHEMA", `${file}#${p.path}`, `${p.message}${schemaHint("soul", read.value)}`); continue; }
689
+ if (read.remoteError) { problem(read.remoteError.code, file, read.remoteError.message); skipped.add(id); continue; }
690
+ if (read.problems) { for (const p of read.problems) problem("E_WORKSPACE_SCHEMA", `${file}#${p.path}`, `${p.message}${schemaHint("soul", read.value)}`); skipped.add(id); continue; }
686
691
  const definition = read.value;
687
- if (definition.name !== locked.name) { problem("E_WORKSPACE_SCHEMA", `${file}#/name`, `soul name ${show(definition.name)} does not match its directory ${show(locked.name)}`); continue; }
692
+ if (definition.name !== locked.name) { problem("E_WORKSPACE_SCHEMA", `${file}#/name`, `soul name ${show(definition.name)} does not match its directory ${show(locked.name)}`); skipped.add(id); continue; }
688
693
  souls.push({
689
694
  name: locked.name, path, repoKey: key, ref, commit: entry.commit, private: false, definition,
690
695
  package: id, version: entry.version, qualifiedName: `${id}/${locked.name}`, agentName: packageSoulAgentName(id, locked.name), digest: locked.digest,
@@ -703,7 +708,13 @@ export async function discoverPackageSouls(workspace, lock, { remote: injected,
703
708
  problems.push({ code: "E_SOUL_AMBIGUOUS", repoKey: null, package: s.package, path: `package:${s.package}:${s.path}/soul.yaml`, message: `package souls ${qualified.join(" and ")} would share the agent directory agents/${dir}/ — keep one of the packages in packages:` });
704
709
  }
705
710
  }
706
- return { souls, problems };
711
+ return { souls, problems, skipped: [...skipped] };
712
+ }
713
+
714
+ /** The packages the workspace declares and `lock` does not hold (declared, and `oats sync` not run since), by id. */
715
+ export function unlockedPackages(workspace, lock) {
716
+ const locked = isObject(lock?.packages) ? lock.packages : {};
717
+ return Object.keys(isObject(workspace?.packages) ? workspace.packages : {}).filter((id) => !Object.hasOwn(locked, id)).sort();
707
718
  }
708
719
 
709
720
  /** Members discovered at once (a fixed bound: the laptop's git and network, not the workspace's size). */
@@ -730,7 +741,13 @@ async function boundedMap(items, limit, task) {
730
741
  /**
731
742
  * The whole picture in one access context.
732
743
  * → { workspace, members: [{ key, commit, confirmed, reason?, souls, capabilities, publishes }], external: [...],
733
- * problems: [{ code, path, message, repoKey? }] }
744
+ * problems: [{ code, path, message, repoKey? }], soulsUnread }
745
+ * `soulsUnread` is where this read may be missing a soul, for the readers of oats-local.yaml souls.launch
746
+ * (lib/instance-resolution.mjs soulsOffered): { members: [repo key] (a confirmed member with a soul skipped,
747
+ * or whose enumeration carries no record of what it skipped: skippedSome),
748
+ * external: [source] (an external soul skipped), packages: [id] (a locked package with a soul skipped),
749
+ * unlocked: [id] (a package the workspace declares and `lock` does not hold) }. It is no part of any
750
+ * JSON answer: `problems` rows keep their fields.
734
751
  * `publishes` = { package, version } when the member carries oats-package/oats-package.json (informational:
735
752
  * the package's capabilities are NOT member capabilities — non-collapse rule), else null.
736
753
  * Members are read DISCOVERY_CONCURRENCY at a time; rows and problems are assembled in declaration order.
@@ -760,21 +777,23 @@ export async function discoverWorkspace(ref, { at, local, lock = null, remote: i
760
777
  row.souls = items.souls;
761
778
  row.capabilities = items.capabilities;
762
779
  row.publishes = items.publishes;
763
- return { row, problems: items.problems };
780
+ return { row, problems: items.problems, skipped: skippedSome(items.soulsSkipped) };
764
781
  });
765
782
  } finally {
766
783
  // Every member listed now has adopted its prefetch (or the discovery failed): the rest, members dropped
767
784
  // since the host's last observed commit, are given up.
768
785
  remote.abandonPrefetches?.();
769
786
  }
770
- for (const d of discovered) { members.push(d.row); problems.push(...d.problems); }
787
+ const soulsUnread = { members: [], external: [], packages: [], unlocked: [] };
788
+ // An unconfirmed member carries no enumeration at all: its row says so, and it is not "skipped" here.
789
+ for (const d of discovered) { members.push(d.row); problems.push(...d.problems); if (d.skipped) soulsUnread.members.push(d.row.key); }
771
790
  const externalRows = [];
772
791
  for (const [index, entry] of (workspace.external || []).entries()) {
773
792
  const pin = entry.source.lastIndexOf("@");
774
793
  const sourceRef = entry.source.slice(0, pin);
775
794
  const commit = entry.source.slice(pin + 1);
776
795
  const file = `${entry.soul.replace(/\/+$/, "")}/soul.yaml`;
777
- const pushProblem = (code, path, message) => problems.push({ code, repoKey: null, path: `external/${index}:${path}`, message, source: entry.source });
796
+ const pushProblem = (code, path, message) => { problems.push({ code, repoKey: null, path: `external/${index}:${path}`, message, source: entry.source }); if (!soulsUnread.external.includes(entry.source)) soulsUnread.external.push(entry.source); };
778
797
  let key;
779
798
  try { key = refKey(remote, sourceRef); }
780
799
  catch (e) { if (e?.code === "E_REPO_REF") { pushProblem("E_REPO_REF", "source", e.message); continue; } throw e; }
@@ -790,7 +809,9 @@ export async function discoverWorkspace(ref, { at, local, lock = null, remote: i
790
809
  }
791
810
  const pkg = await discoverPackageSouls(workspace, lock, { remote });
792
811
  problems.push(...pkg.problems);
793
- return { workspace, key: wsObs.key, url: wsObs.url, commit: wsObs.commit, observedAt: wsObs.observedAt, local: local ?? null, members, external: externalRows, packageSouls: pkg.souls, problems, warnings: workspaceWarnings(workspace, members, externalRows, pkg.souls) };
812
+ soulsUnread.packages = pkg.skipped;
813
+ soulsUnread.unlocked = unlockedPackages(workspace, lock);
814
+ return { workspace, key: wsObs.key, url: wsObs.url, commit: wsObs.commit, observedAt: wsObs.observedAt, local: local ?? null, members, external: externalRows, packageSouls: pkg.souls, problems, soulsUnread, warnings: workspaceWarnings(workspace, members, externalRows, pkg.souls) };
794
815
  }
795
816
 
796
817
  /**
@@ -911,5 +932,8 @@ export function standaloneRepo(ref, commit, discovery, { remote: injected } = {}
911
932
  standalone: true, key, commit: source.commit ?? commit ?? null, workspace: null,
912
933
  members: [{ key, commit: source.commit ?? commit ?? null, confirmed: false, reason: "cannot-read", detail: `workspace of ${key} cannot be read; standalone view`, souls, capabilities, publishes: source.publishes ?? null }],
913
934
  external: [], problems, warnings: [...privateSoulWarnings(souls), ...capabilityContractWarnings(capabilities)],
935
+ // As discoverWorkspace's: the repo's own souls are all this view offers, so only they can be missing.
936
+ // A discovery or an enumeration with no record of it counts as one with a soul skipped (skippedSome).
937
+ soulsUnread: { members: (Array.isArray(discovery.members) ? (!Array.isArray(discovery.soulsUnread?.members) || discovery.soulsUnread.members.includes(key)) : skippedSome(source.soulsSkipped)) ? [key] : [], external: [], packages: [], unlocked: [] },
914
938
  };
915
939
  }