@awebai/oats 0.47.0 → 0.49.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 (44) hide show
  1. package/bin/oats.mjs +293 -41
  2. package/docs/capabilities.md +264 -8
  3. package/docs/capability-manifest.schema.json +18 -5
  4. package/docs/configuration.md +7 -1
  5. package/docs/desktop-cli-api.md +439 -40
  6. package/docs/desktop.md +72 -5
  7. package/docs/execution-targets.md +19 -1
  8. package/docs/implementation.md +81 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +6 -5
  12. package/docs/packages.md +14 -14
  13. package/docs/release-notes/v0.48.0.md +106 -0
  14. package/docs/release-notes/v0.49.0.md +770 -0
  15. package/docs/schedules.md +62 -39
  16. package/docs/servers.md +7 -0
  17. package/docs/souls-and-instances.md +395 -52
  18. package/docs/workspaces.md +18 -3
  19. package/injects/work-checkout.md +17 -11
  20. package/injects/work-worktree.md +19 -13
  21. package/lib/capability-contract.mjs +100 -11
  22. package/lib/capability-show.mjs +5 -2
  23. package/lib/core.mjs +1147 -319
  24. package/lib/instance-events.mjs +6 -3
  25. package/lib/instance-git.mjs +11 -5
  26. package/lib/instance-inspect.mjs +14 -3
  27. package/lib/instance-lifecycle.mjs +106 -16
  28. package/lib/instance-resolution.mjs +15 -3
  29. package/lib/launch-prompt-policy.mjs +17 -3
  30. package/lib/packages.mjs +1 -0
  31. package/lib/real-path.mjs +27 -0
  32. package/lib/resolve.mjs +4 -4
  33. package/lib/retire-output.mjs +6 -1
  34. package/lib/schedule.mjs +1 -0
  35. package/lib/servers.mjs +32 -6
  36. package/lib/teams-verbs.mjs +40 -9
  37. package/lib/tree-copy.mjs +18 -7
  38. package/lib/triggers.mjs +201 -65
  39. package/lib/workspace.mjs +20 -5
  40. package/lib/worktree-hooks.mjs +392 -0
  41. package/lib/worktree.mjs +655 -0
  42. package/package-catalog.json +12 -5
  43. package/package.json +1 -1
  44. package/skills/oats-getting-started/SKILL.md +1 -1
@@ -45,7 +45,7 @@ export const EVENTS_API = 2;
45
45
  const HOME_LOG = ".oats-events.jsonl";
46
46
  const MAX_BYTES = 4 * 1024 * 1024;
47
47
 
48
- export const EVENT_KINDS = ["spawned", "launched", "restarted", "stopped", "stop-refused", "retire-planned", "retired", "worktree-retained", "worktree-removed", "branch-deleted", "child-spawn-refused", "launch-warning", "launch-prompt", "recomposed", "waiting"];
48
+ export const EVENT_KINDS = ["spawned", "launched", "restarted", "stopped", "stop-refused", "retire-planned", "retired", "worktree-retained", "worktree-removed", "worktree-added", "branch-deleted", "child-spawn-refused", "launch-warning", "launch-prompt", "recomposed", "waiting"];
49
49
 
50
50
  /** Kernel rows that end or begin a session: a waiting claim older than the
51
51
  * incarnation's latest one is not live. */
@@ -267,9 +267,12 @@ const waitingShape = (c) => (c ? { since: c.since, producer: c.producer, reason:
267
267
 
268
268
  /** Events for one instance ADDRESS, newest last, from both logs, with a bounded
269
269
  * window; integrity is reported independently of the selected rows. The answer's
270
- * `home`, and each returned row's, is the home as the caller spelled it. */
271
- export function readEvents(given, { limit = 200, since = null } = {}) {
270
+ * `home`, and each returned row's, is the home as the caller spelled it: `given`,
271
+ * or `asked` when the caller resolved its own spelling to `given` (a removed home
272
+ * named through an alias of the agents root, whose logs `given` locates). */
273
+ export function readEvents(given, { limit = 200, since = null, asked } = {}) {
272
274
  const address = addressOf(given);
275
+ if (asked !== undefined) address.asked = asked;
273
276
  const { home, instance, incarnation, homeLog, workspaceLog } = address;
274
277
  const a = readLog(homeLog, "home"), b = readLog(workspaceLog, "workspace");
275
278
  const { rows, foreign } = admit(home, [a, b]);
@@ -18,14 +18,18 @@ export const INSTANCE_GIT_API = 1;
18
18
 
19
19
  /** Every invocation is read-only and helper-free: the tree being observed may
20
20
  * carry a hostile repo config (an agent works there), so external diff /
21
- * textconv drivers, fsmonitor and hooks are disabled explicitly, the caller's
22
- * Git environment is not inherited, and optional locks are off so status/diff
23
- * never refresh (write) the index. */
21
+ * textconv drivers, fsmonitor, hooks and lazy fetch are disabled explicitly,
22
+ * the caller's Git environment is not inherited, and optional locks are off
23
+ * so status/diff never refresh (write) the index. Lazy fetch
24
+ * (GIT_NO_LAZY_FETCH=1): an object a promisor repository lacks is a failed
25
+ * read, never fetched through the remote, helper, ssh command or credential
26
+ * helper the repository's configuration names, and never written into it.
27
+ * Git before 2.44 ignores the variable. */
24
28
  const READ_ONLY_GIT = ["--no-optional-locks",
25
29
  "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "-c", "diff.external=", "-c", "core.pager=cat",
26
30
  "-c", "core.untrackedCache=false", "-c", "index.threads=1", "-c", "safe.bareRepository=explicit"];
27
31
  function gitEnv() {
28
- const env = { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", LANG: "C", LC_ALL: "C", GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0", GIT_CONFIG_NOSYSTEM: "1" };
32
+ const env = { PATH: process.env.PATH ?? "", HOME: process.env.HOME ?? "", LANG: "C", LC_ALL: "C", GIT_OPTIONAL_LOCKS: "0", GIT_NO_LAZY_FETCH: "1", GIT_TERMINAL_PROMPT: "0", GIT_CONFIG_NOSYSTEM: "1" };
29
33
  // The user's global config may name helpers too; observations do not need it.
30
34
  env.GIT_CONFIG_GLOBAL = "/dev/null";
31
35
  return env;
@@ -326,11 +330,13 @@ export function observeInstanceGit(home) {
326
330
  const files = entries.filter((e) => e.kind !== "ignored").map((e) => ({ id: fileId(revision, indexOid, e), ...e, ...countsOf(counts, e) }));
327
331
  const summary = { changed: 0, renamed: 0, copied: 0, unmerged: 0, untracked: 0 };
328
332
  for (const f of files) summary[f.kind]++;
333
+ // A home spawned before #641 may record the word "HEAD" for a detached HEAD; no branch is named that, so it reads as none.
334
+ const recordedBranch = meta.branch === "HEAD" ? null : meta.branch ?? null;
329
335
  return {
330
336
  instanceGitApi: INSTANCE_GIT_API,
331
337
  instance: meta.instance ?? null, agent: meta.agent ?? null, home, workMode: mode,
332
338
  observation: { revision, indexRevision: indexOid, at, worktree: work, branch: head.branch, detached: head.detached && headOid !== null, unborn: headOid === null },
333
- recorded: { branch: meta.branch ?? null, repo: meta.repo ?? null, drift: meta.branch !== undefined && meta.branch !== null && head.branch !== meta.branch },
339
+ recorded: { branch: recordedBranch, repo: meta.repo ?? null, drift: recordedBranch !== null && head.branch !== recordedBranch },
334
340
  upstream, base: baseComparison,
335
341
  remote: remoteOf(work, head.branch),
336
342
  summary, files,
@@ -15,8 +15,8 @@ import { accessSync, constants as fsConstants, existsSync, readFileSync, realpat
15
15
  import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
16
16
  import { fileURLToPath } from "node:url";
17
17
  import { capabilityManifests, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, preparedSoulIdOf, stableSoulId, launchFolderTrust, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
18
- import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance, soulCopyDigests } from "./instance-resolution.mjs";
19
- import { declaredSettings } from "./capability-contract.mjs";
18
+ import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance, resolutionContractWarnings, soulCopyDigests } from "./instance-resolution.mjs";
19
+ import { declaredSettings, locatedContractWarnings } from "./capability-contract.mjs";
20
20
  import { kernelCompatibility } from "./resolve.mjs";
21
21
  import { discoveredTeamKeys, isRemovedTeamKeys, isTeamRefusal, recordedTeams, reportRows, soulKeyOf, teamKeyOf, soulTeams, teamModel, teamProblems } from "./teams.mjs";
22
22
  import { launchLayers, launchReport } from "./launch-preference.mjs";
@@ -271,6 +271,15 @@ export async function withComposedInstructions(t, { compose = composeSoulInstruc
271
271
  }
272
272
 
273
273
  /** `oats inspect --json` on the workspace model. */
274
+ /** What the target's capabilities declare and this kernel ignores (an unknown hook event):
275
+ * [{ code, capability, path, message }]. A soul's from its resolution, where each manifest is read
276
+ * (`<repoKey>:<dir>/oats.json`, `package:<id>:<dir>/oats.json`); a home's from its module copies,
277
+ * at their path in the home (`.oats/modules/<name>/oats.json`: the source directory is not recorded). */
278
+ export function targetWarnings(t) {
279
+ if (!t.home) return resolutionContractWarnings(t.prepared?.resolution);
280
+ return t.modules.filter((x) => x.manifest).flatMap((x) => locatedContractWarnings(x.manifest, `.oats/modules/${x.name}/oats.json`));
281
+ }
282
+
274
283
  export function inspectDocument(t, { kernel }) {
275
284
  const capabilities = capabilityRows(t);
276
285
  // `from` (feature layers-from): where the slot's capability came from; null for an empty slot, and for a
@@ -302,6 +311,7 @@ export function inspectDocument(t, { kernel }) {
302
311
  problems: [...t.soul.problems, ...(t.soul.copyError ? [t.soul.copyError] : []), ...(t.composedInstructionsProblem ? [t.composedInstructionsProblem] : []), ...(t.discoveryError ? [t.discoveryError] : []),
303
312
  ...t.modules.filter((x) => !x.manifest).map((x) => ({ code: "module-missing", message: `${x.name} is recorded but its module copy has no readable oats.json`, capability: x.name })),
304
313
  ...capabilities.filter((c) => !c.compatibility.ok).map((c) => ({ code: "capability-incompatible", message: `${c.id} requires oats ${c.compatibility.range}; this kernel is ${c.compatibility.kernel} (re-spawn from the deployment with a release whose range admits it)`, capability: c.id, range: c.compatibility.range, kernel: c.compatibility.kernel }))],
314
+ warnings: targetWarnings(t),
305
315
  };
306
316
  }
307
317
 
@@ -573,7 +583,8 @@ export async function readinessDocument(t, { selector = null, remoteOptions, cat
573
583
  pass: requiredStatuses.filter((s) => s === "pass").length, fail: requiredStatuses.filter((s) => s === "fail").length, unknown: requiredStatuses.filter((s) => s === "unknown").length, byCapability, subjectBlockers },
574
584
  notes: ["ready means every REQUIRED check passes; it is never inferred from an empty set",
575
585
  "member is the soul's member repository confirmed in the workspace (oats-membership.yaml), never login or team registration",
576
- "providers relays each provider's own binding check verbatim; the spawn's fail-closed hooks are unchanged"] };
586
+ "providers relays each provider's own binding check verbatim; the spawn's fail-closed hooks are unchanged"],
587
+ warnings: targetWarnings(t) };
577
588
  }
578
589
 
579
590
  /** Enforced policy for an instance (from its recorded metadata) or a soul
@@ -10,7 +10,7 @@
10
10
  import { createHash } from "node:crypto";
11
11
  import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
12
12
  import { basename, join } from "node:path";
13
- import { extraWorktreePlan, findInstanceHomes, inspectInstanceSession, listAgents, listInstances, observeSessionWithoutReceipt, retirePendingMarkerPath, retirementRecoveryFacts, stopInstanceSession } from "./core.mjs";
13
+ import { attachedWorkLink, extraWorktreePlan, findInstanceHomes, inspectInstanceSession, listAgents, listInstances, observeSessionWithoutReceipt, retirePendingMarkerPath, retirementRecoveryFacts, stopInstanceSession } from "./core.mjs";
14
14
  import { groupedByOwner } from "./retire-output.mjs";
15
15
  import { observeInstanceGit } from "./instance-git.mjs";
16
16
  import { appendEvent } from "./instance-events.mjs";
@@ -165,12 +165,89 @@ function writeFileSyncAtomic(path, value) {
165
165
  writeFileSync(tmp, JSON.stringify(value, null, 2)); renameSync(tmp, path);
166
166
  }
167
167
 
168
- /** A retire plan's note for one extra tree (core extraWorktreePlan row). */
168
+ /** What the Desktop reads of a plan's notes (packages/desktop/renderer/lifecycle-contract.mjs): at
169
+ * most 64, each at most 4096 characters; it refuses a plan with more, so every note is built to fit
170
+ * (#658). A path is never cut: what does not fit is left to the plan JSON or the receipt. */
171
+ const PLAN_NOTES_MAX = 64;
172
+ const PLAN_NOTE_MAX = 4096;
173
+ /** The characters a note spends listing names (declared roots, attached children) before `, and N more`. */
174
+ const PLAN_LIST_BUDGET = 1024;
175
+ const SEE_EXTRA = "facts.extraWorktrees in the plan JSON";
176
+ /** The first `max` of `items` that fit `budget` characters as `render(shown)`, the rest counted as
177
+ * `, and N more`. → the text, or null when not even one fits. */
178
+ function listWithin(items, render, budget, max = items.length) {
179
+ for (let n = Math.min(items.length, max); n > 0; n--) {
180
+ const text = `${render(items.slice(0, n))}${n < items.length ? `, and ${items.length - n} more` : ""}`;
181
+ if (text.length <= budget) return text;
182
+ }
183
+ return null;
184
+ }
185
+
186
+ /** `render(parts)` within PLAN_NOTE_MAX: `parts` maps each name to [its full text, a pointer to where
187
+ * the plan JSON holds it]; while the note is too long, the longest part that a pointer shortens is
188
+ * replaced by it. → the note, or null when it still does not fit. */
189
+ function fitParts(render, parts) {
190
+ const shown = Object.fromEntries(Object.entries(parts).map(([key, [full]]) => [key, full]));
191
+ let note = render(shown);
192
+ for (const key of Object.keys(parts).sort((a, b) => String(parts[b][0]).length - String(parts[a][0]).length)) {
193
+ if (note.length <= PLAN_NOTE_MAX) return note;
194
+ if (String(parts[key][0]).length <= parts[key][1].length) continue; // the pointer would not shorten it
195
+ shown[key] = parts[key][1];
196
+ note = render(shown);
197
+ }
198
+ return note.length <= PLAN_NOTE_MAX ? note : null;
199
+ }
200
+
201
+ /** A retire plan's note for one extra tree (core extraWorktreePlan row). Too long for the Desktop, its
202
+ * longest parts go to the plan JSON, longest first; the tree's path stays whole, or the note says it
203
+ * is too long and where it is. */
169
204
  function extraWorktreeNote(t) {
170
- const at = t.branch ? `branch ${t.branch}` : t.detachedAt ? `detached at ${t.detachedAt.slice(0, 12)}` : "a HEAD that could not be read";
171
- if (t.disposition === "remove") return `extra worktree ${t.path} (${at}) is clean and would be removed; its branch and commits stay in ${t.repo}`;
172
- if (t.disposition === "retain") return `extra worktree ${t.path} (${at}) would be re-homed to ${t.movedTo}: ${t.reason}`;
173
- return `extra worktree ${t.path} (${at}): retire refuses, ${t.reason}`;
205
+ const parts = {
206
+ at: [t.branch ? `branch ${t.branch}` : t.detachedAt ? `detached at ${t.detachedAt.slice(0, 12)}` : "a HEAD that could not be read", `its HEAD: see ${SEE_EXTRA}`],
207
+ repo: [t.repo, `its repository (see ${SEE_EXTRA})`],
208
+ movedTo: [t.movedTo, `the path ${SEE_EXTRA} names`],
209
+ reason: [t.reason, `${SEE_EXTRA} says why`],
210
+ };
211
+ const render = (p) => t.disposition === "remove" ? `extra worktree ${t.path} (${p.at}) is clean and would be removed; its branch and commits stay in ${p.repo}`
212
+ : t.disposition === "retain" ? `extra worktree ${t.path} (${p.at}) would be re-homed to ${p.movedTo}: ${p.reason}`
213
+ : `extra worktree ${t.path} (${p.at}): retire refuses, ${p.reason}`;
214
+ const note = fitParts(render, parts);
215
+ if (note !== null) return note;
216
+ const outcome = t.disposition === "remove" ? "would be removed" : t.disposition === "retain" ? "would be re-homed" : "makes retire refuse";
217
+ return `an extra worktree whose path is too long for this note ${outcome}; ${SEE_EXTRA} lists it`;
218
+ }
219
+ /** The plan's note when the worktree is not on the recorded branch: both names, or, too long for the
220
+ * note, pointers to the plan JSON fields that hold them. */
221
+ function driftNote(work, recordedBranch) {
222
+ const on = work.branch ?? (work.detached ? "a detached HEAD" : "a ref OATS carries no branch name for");
223
+ return fitParts((p) => `the worktree is on ${p.on}, not the recorded ${p.recorded}`, {
224
+ on: [on, "the branch facts.work.branch in the plan JSON names"],
225
+ recorded: [recordedBranch, "branch, which facts.recordedBranch in the plan JSON names"],
226
+ }) ?? "the worktree is not on the recorded branch; facts.work.branch and facts.recordedBranch in the plan JSON name both";
227
+ }
228
+ /** The plan's note on a home without its session receipt: the observation's reason, or, too long
229
+ * for the note (a process's command line, a tmux error), a pointer to facts.session.note. */
230
+ function sessionNote(session) {
231
+ const [head, tail] = session.established ? ["session absent", "nothing needs quiescing"] : ["session not observably absent", "retire refuses until it is stopped"];
232
+ const note = `${head}: ${session.note}; ${tail}`;
233
+ return note.length <= PLAN_NOTE_MAX ? note : `${head}: the reason is too long for this note (facts.session.note in the plan JSON); ${tail}`;
234
+ }
235
+ /** The plan's recovery note: where a recovery would be written, and the declared roots it leaves
236
+ * out, listed within PLAN_LIST_BUDGET (at most 16). A recovery path too long for the note is named
237
+ * by where to find it instead. */
238
+ function recoveryNote(recovery) {
239
+ const roots = recovery.disposableHome;
240
+ const notCopied = (head) => {
241
+ if (!roots.length) return "";
242
+ const room = Math.min(PLAN_LIST_BUDGET, PLAN_NOTE_MAX - head.length - "; not copied: ".length);
243
+ const listed = room > 0 ? listWithin(roots, (shown) => groupedByOwner(shown, "root"), room, PLAN_NOT_COPIED_CAP) : null;
244
+ return `; not copied: ${listed ?? `${roots.length} declared root${roots.length === 1 ? "" : "s"}, too long to list here`}`;
245
+ };
246
+ const head = `recovery: the home is copied to ${recovery.recoveryRoot} before the home is removed, when it changed since spawn`;
247
+ const note = `${head}${notCopied(head)}`;
248
+ if (note.length <= PLAN_NOTE_MAX) return note;
249
+ const elsewhere = "recovery: the home is copied to the recovery directory beside the home before the home is removed, when it changed since spawn (its path is too long for this note: the retire receipt names it as workRecovery.path, and the retire summary prints it)";
250
+ return `${elsewhere}${notCopied(elsewhere)}`;
174
251
  }
175
252
  /** How many declared roots a retire plan's recovery note lists before `, and N more`. */
176
253
  const PLAN_NOT_COPIED_CAP = 16;
@@ -189,7 +266,8 @@ export function planRetire(ctx, root, name, { home } = {}) {
189
266
  // into the revision (below), so that an apply refuses as stale when a tree
190
267
  // was created, removed, dirtied or cleaned, or its target was taken.
191
268
  const extraWorktrees = extraWorktreePlan(me.home, me.root);
192
- const facts = { session: target.session, work: target.work, workMode: meta.work ?? null, repo: meta.repo ?? null, recordedBranch: meta.branch ?? null,
269
+ // A home spawned before #641 may record the word "HEAD" for a detached checkout: not a branch name.
270
+ const facts = { session: target.session, work: target.work, workMode: meta.work ?? null, repo: meta.repo ?? null, recordedBranch: meta.branch === "HEAD" ? null : meta.branch ?? null,
193
271
  extraWorktrees,
194
272
  children: kids.map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, session: sessionFacts(c.home) })),
195
273
  ambiguous: (kids.ambiguous || []).map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, reason: c.reason })),
@@ -200,21 +278,33 @@ export function planRetire(ctx, root, name, { home } = {}) {
200
278
  ...(extraWorktrees.length ? [extraWorktrees] : [])];
201
279
  // What retire would preserve and where, read from the spawn baseline and the
202
280
  // work mode: nothing is hashed, and the plan revision does not depend on it.
203
- // The declared roots are listed as written, capped so one note stays short.
281
+ // The declared roots are listed as written, bounded so one note stays short.
204
282
  const recovery = retirementRecoveryFacts(me.home);
205
- const declared = recovery.disposableHome.slice(0, PLAN_NOT_COPIED_CAP);
206
- const notCopied = declared.length ? `; not copied: ${groupedByOwner(declared, "root")}${recovery.disposableHome.length > declared.length ? `, and ${recovery.disposableHome.length - declared.length} more` : ""}` : "";
283
+ // Attached children whose work is this home's work/ (#718): a retire that keeps the worktree
284
+ // repoints them to it. One note holds whatever the dialog then picks.
285
+ const attached = meta.work === "worktree" ? kids.filter((c) => attachedWorkLink(c.home, me.home) !== null) : [];
207
286
  appendEvent(me.home, { kind: "retire-planned", data: { planRevision: planRevision(safety), children: kids.length, dirty: facts.work.observed ? facts.work.changed + facts.work.untracked : null } }, { workspaceOnly: true });
208
287
  return { lifecycleApi: LIFECYCLE_API, action: "retire", instance: name, home: me.home, at: new Date().toISOString(), facts, defaults, planRevision: planRevision(safety),
209
- notes: [
210
- ...(facts.work.observed && facts.work.drift ? [`the worktree is on ${facts.work.branch ?? (facts.work.detached ? "a detached HEAD" : "a ref OATS carries no branch name for")}, not the recorded ${facts.recordedBranch}`] : []),
288
+ notes: boundedNotes(extraWorktrees.map(extraWorktreeNote), [
289
+ ...(facts.work.observed && facts.work.drift ? [driftNote(facts.work, facts.recordedBranch)] : []),
211
290
  ...(facts.work.observed && facts.work.changed + facts.work.untracked > 0 ? [`${facts.work.changed} changed and ${facts.work.untracked} untracked file(s) would be retained with the worktree`] : []),
212
- ...extraWorktrees.map(extraWorktreeNote),
291
+ ], [
213
292
  ...(kids.length ? [`${kids.length} recorded child instance(s) are stopped first (bounded SIGTERM, never escalated) and retained (their homes are not removed); a child still running after the grace refuses the retirement`] : []),
293
+ ...(attached.length ? [`attached child instance(s) ${listWithin(attached.map((c) => c.instance), (shown) => shown.join(", "), PLAN_LIST_BUDGET) ?? attached.length} use this home's work/ as their work: a retire that keeps the worktree repoints their work link to it; with --discard-worktree the worktree is removed and their work link will dangle`] : []),
214
294
  ...((kids.ambiguous || []).length ? [`${kids.ambiguous.length} instance(s) record this name as parent but the name is not unique under this root; they are listed under ambiguous and NOT acted on`] : []),
215
- ...(target.session.note ? [target.session.established ? `session absent: ${target.session.note}; nothing needs quiescing` : `session not observably absent: ${target.session.note}; retire refuses until it is stopped`] : []),
295
+ ...(target.session.note ? [sessionNote(target.session)] : []),
216
296
  "pull request state is unknown to the kernel; the ADE reports it when a forge connection exists",
217
- `recovery: the home is copied to ${recovery.recoveryRoot} before the home is removed, when it changed since spawn${notCopied}`,
297
+ recoveryNote(recovery),
218
298
  ...(meta.work === "worktree" ? ["recovery: uncommitted worktree state is copied there too"] : meta.work === "directory" ? ["recovery: work/ is copied there when it is not empty"] : []),
219
- ] };
299
+ ]) };
300
+ }
301
+
302
+ /** A retire plan's notes in order: `before`, one per extra tree, `after`. The extra trees are the
303
+ * only notes without a fixed count: past PLAN_NOTES_MAX the last one kept counts the rest. Each note
304
+ * is built to fit PLAN_NOTE_MAX; one that still does not (a new note that forgot to) is replaced
305
+ * rather than let the Desktop refuse the whole plan. */
306
+ function boundedNotes(trees, before, after) {
307
+ const room = PLAN_NOTES_MAX - before.length - after.length;
308
+ const shown = trees.length <= room ? trees : [...trees.slice(0, room - 1), `and ${trees.length - room + 1} more extra worktrees (${SEE_EXTRA} lists every one)`];
309
+ return [...before, ...shown, ...after].map((note) => note.length <= PLAN_NOTE_MAX ? note : "a note too long for this plan was left out; the plan JSON's facts hold what it said");
220
310
  }
@@ -23,7 +23,7 @@ import { loadLocal, discoverWorkspace, discoverRepo, standaloneRepo, observeWork
23
23
  import { resolveSoul, kernelCompatibility } from "./resolve.mjs";
24
24
  import { BY_TEAM_REMOVED, isRemovedTeamKeys, isTeamRefusal, memberNameOf, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "./teams.mjs";
25
25
  import { launchLayers } from "./launch-preference.mjs";
26
- import { declaredSettings } from "./capability-contract.mjs";
26
+ import { APPROVED_HOOKS, declaredSettings, locatedContractWarnings } from "./capability-contract.mjs";
27
27
  import { materialize, moduleSkills, MODULES_DIR, SKILLS_DIR } from "./materialize.mjs";
28
28
  import { contentDigest, fetchRemoteTree } from "./remote.mjs";
29
29
  import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync, symlinkSync, statSync } from "node:fs";
@@ -351,7 +351,7 @@ export function conventionCloneDir(deployment, key) {
351
351
  * (`github.com/org/repo`), or any ref form parseRepoRef understands (`git:…`,
352
352
  * `https://…`, `git@host:…`, `/abs/bare.git`) — to the canonical key. A key that
353
353
  * parses no way is returned as written (it can then only match literally). */
354
- function canonicalCloneKey(written) {
354
+ export function canonicalCloneKey(written) {
355
355
  const s = String(written).trim();
356
356
  if (s.startsWith("local/")) return s; // a local key is already canonical
357
357
  for (const candidate of [s, `git:${s}`]) {
@@ -643,10 +643,22 @@ export function toCapabilityRows(resolution, home) {
643
643
  return rows;
644
644
  }
645
645
 
646
+ /** A resolution's contract warnings (an unknown, non-required hook event): its modules'
647
+ * [{ code, capability, path, message }] by module name (as a replayed spawn reads them from the home),
648
+ * each module's manifest where it was read (`<repoKey>:<dir>/oats.json`, a package's
649
+ * `package:<id>:<dir>/oats.json`). */
650
+ export function resolutionContractWarnings(resolution) {
651
+ return [...(resolution?.modules || [])].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)).flatMap((m) => locatedContractWarnings(m.manifest,
652
+ m.from?.kind === "package" ? `package:${m.from.package}:${m.dir}/oats.json` : `${m.from?.repoKey}:${m.dir}/oats.json`));
653
+ }
654
+
655
+ /** The hooks a row carries: the events this kernel runs. An unknown event (a newer
656
+ * kernel's, accepted with a warning by the manifest contract) never reaches a row. */
646
657
  function hookCommandsOf(manifest, dir) {
647
658
  const out = {};
648
659
  const hooks = manifest.hooks && typeof manifest.hooks === "object" ? manifest.hooks : {};
649
660
  for (const [event, spec] of Object.entries(hooks)) {
661
+ if (!APPROVED_HOOKS.has(event)) continue;
650
662
  const cmd = typeof spec === "string" ? spec : spec?.command;
651
663
  if (typeof cmd === "string" && cmd) out[event] = { command: cmd, cwd: dir, required: spec?.required === true };
652
664
  }
@@ -654,7 +666,7 @@ function hookCommandsOf(manifest, dir) {
654
666
  }
655
667
  function requiredHooksOf(manifest) {
656
668
  const hooks = manifest.hooks && typeof manifest.hooks === "object" ? manifest.hooks : {};
657
- return Object.entries(hooks).filter(([, s]) => s && typeof s === "object" && s.required === true).map(([e]) => e);
669
+ return Object.entries(hooks).filter(([e, s]) => APPROVED_HOOKS.has(e) && s && typeof s === "object" && s.required === true).map(([e]) => e);
658
670
  }
659
671
 
660
672
  /** What a preview shows about modules: from/commit/digest per module, whether
@@ -2,6 +2,7 @@
2
2
  import { lstatSync, realpathSync, statSync } from "node:fs";
3
3
  import { basename, dirname, isAbsolute, join, resolve } from "node:path";
4
4
  import { oatsError } from "./errors.mjs";
5
+ import { canonicalHomePath } from "./real-path.mjs";
5
6
 
6
7
  const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
7
8
  const pointer = (value) => value.replace(/~/g, "~0").replace(/\//g, "~1");
@@ -54,6 +55,18 @@ export function launchPromptPolicyProblems(policy) {
54
55
  return problems;
55
56
  }
56
57
 
58
+ /** The configured key that names `home`: the key spelled exactly as `home`, else the one key that
59
+ * names the same directory in its on-disk spelling (on a case-insensitive filesystem a key may be
60
+ * written in another letter case and still be valid). Several such keys and no exact one decide
61
+ * nothing: no consent. */
62
+ function consentKey(homes, home) {
63
+ if (!homes) return undefined;
64
+ if (Object.hasOwn(homes, home)) return home;
65
+ const onDisk = canonicalHomePath(home);
66
+ const same = Object.keys(homes).filter((key) => canonicalHomePath(key) === onDisk);
67
+ return same.length === 1 ? same[0] : undefined;
68
+ }
69
+
57
70
  /** Exact-home consent + config JSON-pointer provenance for previews/controllers.
58
71
  * Call again after home creation; the controller must separately retain and
59
72
  * recheck directory identity before each input. No captured policy is authority. */
@@ -64,10 +77,11 @@ export function effectiveLaunchPromptPolicy(local, home, source) {
64
77
  if (problems.length) throw oatsError("E_WORKSPACE_SCHEMA", `invalid launchPromptAnswers: ${problems.map((p) => `${p.path}: ${p.message}`).join("; ")}`, { problems });
65
78
  try { canonicalLaunchPromptHome(home); } catch { return disabled; }
66
79
  const homes = local.launchPromptAnswers.homes;
67
- if (!homes || !Object.hasOwn(homes, home)) return disabled;
68
- const consent = homes[home];
80
+ const key = consentKey(homes, home);
81
+ if (key === undefined) return disabled;
82
+ const consent = homes[key];
69
83
  return {
70
84
  awebDevelopmentChannel: consent.awebDevelopmentChannel === true,
71
- consentSource: typeof source === "string" && source.length ? `${source}#${root}/homes/${pointer(home)}` : null,
85
+ consentSource: typeof source === "string" && source.length ? `${source}#${root}/homes/${pointer(key)}` : null,
72
86
  };
73
87
  }
package/lib/packages.mjs CHANGED
@@ -344,6 +344,7 @@ async function readPackageManifestsAt(remote, remoteRef, commit, path, details)
344
344
  if (seen.has(capManifest.capability)) {
345
345
  throw oatsError("E_PACKAGE_MANIFEST", `package ${manifest.package} declares capability ${JSON.stringify(capManifest.capability)} twice (${seen.get(capManifest.capability)} and ${dir})`, { ...details, path: dir, duplicate: capManifest.capability, other: seen.get(capManifest.capability) });
346
346
  }
347
+ // What it declares and this kernel ignores (an unknown hook event) is its readers' warning, not a refusal.
347
348
  const [problem] = manifestContractProblems(capManifest);
348
349
  if (problem) throw oatsError("E_PACKAGE_MANIFEST", `${pjoin(dir, CAPABILITY_MANIFEST)}#${problem.pointer}: ${problem.message}`, { ...details, path: dir, capability: capManifest.capability, pointer: problem.pointer });
349
350
  seen.set(capManifest.capability, dir);
@@ -0,0 +1,27 @@
1
+ // The real path of a location that may not exist yet, in the caller's spelling or the one on disk.
2
+ import { existsSync, realpathSync } from "node:fs";
3
+ import { basename, dirname, join, resolve } from "node:path";
4
+
5
+ /** realpath of `p`, or — when `p` does not exist yet — the realpath of its
6
+ * nearest existing ancestor with the remaining segments re-appended. Any path
7
+ * decision about WHERE something will be created has to go through this: a
8
+ * lexical path says nothing about the destination once a symlink sits anywhere
9
+ * along it. */
10
+ export function realPathOrNearest(p) {
11
+ return nearestRealPath(p, realpathSync);
12
+ }
13
+ /** realPathOrNearest with the operating system's realpath: the one spelling of a path. On a
14
+ * case-insensitive filesystem (APFS, the macOS default) JS realpathSync keeps the caller's
15
+ * letter case, so `.../agents/x` and `.../Agents/x` (one directory) come back as two strings;
16
+ * realpathSync.native returns each existing component as it is on disk. On a case-sensitive
17
+ * filesystem the two agree: two spellings are two directories, and this changes nothing. (On
18
+ * APFS it can also return a name's on-disk Unicode normalization.) */
19
+ export function canonicalHomePath(p) {
20
+ return nearestRealPath(p, realpathSync.native);
21
+ }
22
+ function nearestRealPath(p, realpath) {
23
+ try { return realpath(p); } catch { /* not created yet — resolve what exists */ }
24
+ let d = resolve(p); const tail = [];
25
+ while (!existsSync(d) && dirname(d) !== d) { tail.unshift(basename(d)); d = dirname(d); }
26
+ try { return join(realpath(d), ...tail); } catch { return resolve(p); }
27
+ }
package/lib/resolve.mjs CHANGED
@@ -59,7 +59,7 @@ import { oatsError as baseOatsError } from "./errors.mjs";
59
59
  import * as defaultRemote from "./remote.mjs";
60
60
  import { BY_TEAM_REMOVED, reportRows, soulTeams, teamKeyOf, teamModel } from "./teams.mjs";
61
61
  import { bindRemote, packageProviding, readPackageManifests, validateLock } from "./packages.mjs";
62
- import { settingValueProblems } from "./capability-contract.mjs";
62
+ import { APPROVED_HOOKS, settingValueProblems } from "./capability-contract.mjs";
63
63
  import { memberRowByKey } from "./workspace.mjs";
64
64
 
65
65
  export const RESOLUTION_API = 1;
@@ -539,12 +539,12 @@ async function enumerateSkills({ remote, ref, commit, dir, manifest, listing, mo
539
539
  }
540
540
 
541
541
  /** What a capability provides, by name (feature desktop-facts): its skills (enumerated exactly as a spawn
542
- * would), commands and hooks. `skills` is null when its declared skills cannot be listed (a spawn of it
543
- * would refuse; the listing does not). */
542
+ * would), commands and hooks (the events this kernel runs: an unknown one never runs here). `skills` is
543
+ * null when its declared skills cannot be listed (a spawn of it would refuse; the listing does not). */
544
544
  export async function capabilityProvides({ ref, commit, dir, manifest, remote: injected, remoteOptions }) {
545
545
  const keys = (o) => (isObject(o) ? Object.keys(o).sort(byCodepoint) : []);
546
546
  const { skills } = await capabilitySkills({ ref, commit, dir, manifest, remote: injected, remoteOptions });
547
- return { skills: skills && skills.map((s) => s.name), commands: keys(manifest.commands), hooks: keys(manifest.hooks) };
547
+ return { skills: skills && skills.map((s) => s.name), commands: keys(manifest.commands), hooks: keys(manifest.hooks).filter((event) => APPROVED_HOOKS.has(event)) };
548
548
  }
549
549
 
550
550
  /** A capability's skills as a spawn enumerates them (enumerateSkills), sorted by name in codepoint order:
@@ -30,11 +30,15 @@ export function receiptRecoveries(receipt) {
30
30
  return receipt?.workRecovery ? [receipt.workRecovery] : [];
31
31
  }
32
32
 
33
+ /** Where the summary sends an operator to inspect, restore or dispose of a recovery (#703). */
34
+ const RECOVERY_POINTER = " to inspect, restore or dispose of a recovery: see docs/souls-and-instances.md#after-a-retire-inspect-restore-dispose";
35
+
33
36
  /** The lines `oats retire` prints for what a receipt preserved; `host` (the
34
37
  * remote path) names where. Per recovery: the classes, the path with its
35
38
  * size, then, when they apply, what was copied from the home, the copied
36
39
  * outputs, the home entries left out by a capability's declaration (names and
37
- * owners only) and which parts were copied again under after-hooks/. */
40
+ * owners only) and which parts were copied again under after-hooks/; and,
41
+ * after them all, where the docs say what to do with a recovery. */
38
42
  export function workRecoveryLines(receipt, { host } = {}) {
39
43
  const lines = [];
40
44
  for (const recovery of receiptRecoveries(receipt)) {
@@ -47,6 +51,7 @@ export function workRecoveryLines(receipt, { host } = {}) {
47
51
  const again = [recovery.afterHooks?.home === true && "home", recovery.afterHooks?.work === true && "work"].filter(Boolean);
48
52
  if (again.length) lines.push(` after the retire hooks: ${again.join(" and ")} copied again under after-hooks/`);
49
53
  }
54
+ if (lines.length) lines.push(RECOVERY_POINTER);
50
55
  return lines;
51
56
  }
52
57
 
package/lib/schedule.mjs CHANGED
@@ -552,6 +552,7 @@ export function childEnv() {
552
552
  "OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK",
553
553
  "OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_LAUNCH_PREVIEW", "OATS_RETIRE_INTENT",
554
554
  "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",
555
+ "OATS_TREE", "OATS_TREE_CLONE", "OATS_TREE_REMOTE", "OATS_TREE_MEMBER", "OATS_TREE_BASE", "OATS_TREE_BASE_OID", "OATS_PURPOSE", "OATS_TREE_ORIGIN",
555
556
  ]) delete env[key];
556
557
  return env;
557
558
  }
package/lib/servers.mjs CHANGED
@@ -798,6 +798,27 @@ const rowFacts = (i = {}) => Object.fromEntries(REMOTE_ROW_FACTS.map((k) => [k,
798
798
  * value passes the kernel's own read rule again; anything it refuses is null. */
799
799
  const rowWaiting = (i) => (Object.hasOwn(i, "waitingOnYou") ? { waitingOnYou: readWaitingClaim(i.waitingOnYou) } : {});
800
800
 
801
+ /** The bounds a host's `features` list must meet to be relayed (feature server-probe-features). */
802
+ export const HOST_FEATURES_MAX = 256;
803
+ export const HOST_FEATURE_NAME_MAX = 64;
804
+ const FEATURE_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
805
+ /** The host's kernel features from its `status --json` result (feature server-probe-features), or
806
+ * null when unknown. The answer is untrusted: it is relayed as given (order, duplicates and all)
807
+ * only when it is an array of at most HOST_FEATURES_MAX names, each a string of lowercase
808
+ * hyphen-separated words of at most HOST_FEATURE_NAME_MAX characters. Anything else, a host
809
+ * before 0.49.0 that omits the key, or a single bad entry, is null: never filtered, coerced,
810
+ * sorted or deduped. `[]` is a valid answer, distinct from null. */
811
+ export function hostFeatures(result) {
812
+ if (!result || typeof result !== "object" || !Object.hasOwn(result, "features")) return null;
813
+ const list = result.features;
814
+ if (!Array.isArray(list) || list.length > HOST_FEATURES_MAX) return null;
815
+ for (let i = 0; i < list.length; i++) {
816
+ const name = list[i];
817
+ if (typeof name !== "string" || name.length > HOST_FEATURE_NAME_MAX || !FEATURE_NAME_RE.test(name)) return null;
818
+ }
819
+ return [...list];
820
+ }
821
+
801
822
  export function rosterGroups({ server, io = {} } = {}) {
802
823
  const started = Date.now();
803
824
  if (server && !ID_RE.test(server)) throw serverError("E_BAD_ARGS", `server id ${JSON.stringify(server)} is not a valid id`);
@@ -837,20 +858,25 @@ export function rosterGroups({ server, io = {} } = {}) {
837
858
  const bySnapshot = new Map(g._snapshots.map((s) => [s.instance, s]));
838
859
  const routeOf = (i) => { const s = bySnapshot.get(i.instance); return s && s.home && i.home && resolve(s.home) === resolve(i.home) ? s : undefined; };
839
860
  if (status?.ok) {
840
- g.probe = { ok: true };
841
- g.agentsRoot = status.result.root;
861
+ // A success envelope whose result is null or missing reads as an empty answer, never a crash
862
+ // that would sink every other group.
863
+ const result = status.result ?? {};
864
+ // The host's own kernel features (feature server-probe-features), relayed from the same status
865
+ // answer, never probed: null when the host does not report a valid list.
866
+ g.probe = { ok: true, features: hostFeatures(result) };
867
+ g.agentsRoot = result.root;
842
868
  // The host's own workspace identity (feature workspace-identity), relayed as it answered it: never
843
869
  // derived here, null when the host reports none.
844
- g.workspace = status.result.workspace ?? null;
845
- for (const a of status.result.agents || []) {
846
- g.souls.push({ name: a.name, harness: a.harness ?? a.runtime, work: a.work, backend: a.backend, description: a.description, agentsRoot: status.result.root });
870
+ g.workspace = result.workspace ?? null;
871
+ for (const a of result.agents || []) {
872
+ g.souls.push({ name: a.name, harness: a.harness ?? a.runtime, work: a.work, backend: a.backend, description: a.description, agentsRoot: result.root });
847
873
  // A failed deferred self-retirement needs an operator: it rides with
848
874
  // the group, named by agent and instance, as `oats status` prints it.
849
875
  for (const f of a.retireFailures || []) g.retireFailures.push({ agent: a.name, ...f });
850
876
  for (const i of a.instances || []) {
851
877
  const snap = routeOf(i);
852
878
  g.instances.push({
853
- server: g.server, instance: i.instance, agent: a.name, home: i.home || snap?.home, agentsRoot: status.result.root,
879
+ server: g.server, instance: i.instance, agent: a.name, home: i.home || snap?.home, agentsRoot: result.root,
854
880
  harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null,
855
881
  ...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
856
882
  running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),