@awebai/oats 0.69.12 → 0.69.14

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 (70) hide show
  1. package/README.md +216 -178
  2. package/bin/oats.mjs +176 -184
  3. package/docs/capabilities.md +4 -1
  4. package/docs/configuration.md +63 -5
  5. package/docs/container.md +246 -0
  6. package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
  7. package/docs/desktop-cli-api.md +376 -37
  8. package/docs/desktop-instance-start.md +4 -1
  9. package/docs/desktop.md +58 -12
  10. package/docs/execution-targets.md +69 -6
  11. package/docs/implementation.md +86 -29
  12. package/docs/integrations.md +3 -2
  13. package/docs/knowledge-and-learning.md +72 -0
  14. package/docs/oats-local.schema.json +11 -2
  15. package/docs/official-catalog.md +39 -5
  16. package/docs/packages.md +93 -14
  17. package/docs/release-lane.md +2 -1
  18. package/docs/release-notes/v0.69.13.md +767 -0
  19. package/docs/release-notes/v0.69.14.md +83 -0
  20. package/docs/schedules.md +26 -3
  21. package/docs/servers.md +181 -5
  22. package/docs/souls-and-instances.md +140 -11
  23. package/docs/tui.md +1 -1
  24. package/docs/upgrading.md +24 -5
  25. package/docs/workspaces.md +31 -5
  26. package/lib/claim.mjs +21 -5
  27. package/lib/command-flags.mjs +238 -0
  28. package/lib/core.mjs +791 -563
  29. package/lib/deployments.mjs +4 -3
  30. package/lib/dir-lock.mjs +126 -31
  31. package/lib/errors.mjs +1 -1
  32. package/lib/harness-token.mjs +110 -0
  33. package/lib/hot-reads.mjs +4 -3
  34. package/lib/instance-events.mjs +28 -6
  35. package/lib/instance-git.mjs +138 -13
  36. package/lib/instance-inspect.mjs +6 -1
  37. package/lib/instance-listing.mjs +80 -38
  38. package/lib/instance-resolution.mjs +56 -3
  39. package/lib/instance-upgrade.mjs +16 -20
  40. package/lib/launch-env-exec.sh +7 -0
  41. package/lib/launch-env.mjs +74 -0
  42. package/lib/launch-preference.mjs +19 -12
  43. package/lib/member-clone.mjs +7 -1
  44. package/lib/packages.mjs +74 -2
  45. package/lib/read-call.mjs +3 -0
  46. package/lib/reader.mjs +3 -2
  47. package/lib/refused-text.mjs +3 -2
  48. package/lib/remote.mjs +119 -27
  49. package/lib/retained-after-retire.mjs +2 -7
  50. package/lib/retire-git-forms.mjs +41 -0
  51. package/lib/retire-incomplete.mjs +96 -0
  52. package/lib/schedule.mjs +2 -1
  53. package/lib/servers.mjs +78 -23
  54. package/lib/session-resume.mjs +68 -53
  55. package/lib/session-seen.mjs +54 -5
  56. package/lib/start-env.mjs +13 -7
  57. package/lib/system-tools.mjs +1 -1
  58. package/lib/teams.mjs +11 -4
  59. package/lib/upgrade-state.mjs +13 -2
  60. package/lib/worktree.mjs +56 -7
  61. package/package-catalog.json +1 -1
  62. package/package.json +2 -1
  63. package/packages/client/instance-lifecycle.mjs +1 -1
  64. package/packages/client/lifecycle-contract.mjs +3 -1
  65. package/packages/client/session-resume-cli.mjs +2 -1
  66. package/packages/client/session-start.mjs +10 -7
  67. package/packages/client/workspace-cli.mjs +5 -1
  68. package/share/oats-login-receive +204 -0
  69. package/skills/oats-getting-started/SKILL.md +92 -25
  70. package/lib/tmux-config.mjs +0 -35
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.22.1 # bare version → resolves through the official catalog
57
+ oats.framework: v1.23.0 # bare version → resolves through the official catalog
58
58
  oats.okf: v5.8.0
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
@@ -336,6 +336,10 @@ output, `timeout` for a timeout). The partial cache, its fetch mode and its
336
336
  commit pins are preserved, and a later read can retry the version probe.
337
337
  This also applies to library reads without a session. A cache already using
338
338
  whole trees stays in that mode when a later probe finds a newer Git.
339
+ With an older Git, a command says so once, however many repositories it
340
+ fetches: one `oats: warning` line naming the Git version and the 2.45 floor,
341
+ and saying that OATS fetches whole trees instead. A Git of 2.45 or later
342
+ removes the line.
339
343
 
340
344
  **Repo-owned capabilities.** `private: true` in a capability's `oats.json`
341
345
  makes it **repo-owned**: it is listed like any other capability (with
@@ -418,6 +422,23 @@ So the framework's own souls say `oats.okf: { from: package }` even though
418
422
  member soul that is the expert in that capability (`oats-okf-expert`,
419
423
  `oats-aweb-expert`, …), discoverable at latest state like any member soul.
420
424
 
425
+ **OATS's coordination is a member copy of the engineering template.** The
426
+ `oats` repository keeps its own copy of
427
+ [oats-project/oats-engineering-coordination](https://github.com/oats-project/oats-engineering-coordination)
428
+ at template-v3.0.1, adapted to OATS: `oats.engineering-expert`,
429
+ `oats.developer`, `oats.build`, `oats.code-review`, `oats.maintainer`,
430
+ `oats.landing-rules` and `oats.dispatcher`, in `capabilities/oats-<name>/`.
431
+ `capabilities/TEMPLATE-RELEASE` records the release, its commit and what was copied, and
432
+ `capabilities/THIRD-PARTY-NOTICES.md` the sources four of the build skills and the
433
+ developer's quality floor adapt. `oats.build` holds the build skills, and every soul that
434
+ builds composes it: the developers, and the engineering experts that build their own
435
+ specs. The framework's own souls compose them `from: here`, never the `oats.engineering` package's copies; the
436
+ landing rules point at the lane map, which stays the one home of OATS's lanes.
437
+ The reviewer is the template's `code-reviewer` soul, in `souls/`. The workspace
438
+ doesn't pin the `oats.engineering` package, frozen at v1.18.0
439
+ ([official catalog](official-catalog.md#coordination-templates)), so each of
440
+ those ids has one source here: the member copy.
441
+
421
442
  ## Packages, lock, catalog
422
443
 
423
444
  `packages:` values have two forms, a **bare version** resolved through the
@@ -438,6 +459,7 @@ the workspace's slot default):
438
459
  ```
439
460
  from: package → some locked package provides `name` else E_PACKAGE_MISSING (run `oats sync`)
440
461
  → read its manifests at the locked commit; the lock's capability list must match else E_PACKAGE_INTEGRITY
462
+ → at spawn, the package tree at the locked commit must digest to the lock's integrity else E_PACKAGE_INTEGRITY
441
463
  → copy; record package/version/commit/digest
442
464
  from: <repo> → <repo> is a CONFIRMED member else E_NOT_A_MEMBER / E_MEMBERSHIP_UNCONFIRMED
443
465
  (or `here`) → it has capabilities/<name>/oats.json else E_CAPABILITY_MISSING
@@ -527,7 +549,9 @@ souls: # per soul pattern: its default team an
527
549
  `<member>/*` or `<package>/*`, and `"*"`, with the member and package names
528
550
  `souls.disabled` uses (a member's name is its repository's). A bare soul name
529
551
  is refused. A key that is neither a pattern nor a soul the workspace offers
530
- is the warning `team-soul-unknown` (a typo guard).
552
+ is the warning `team-soul-unknown` (a typo guard). So is a `<prefix>/*`
553
+ pattern whose prefix matches no soul the workspace offers: a typo, or a
554
+ member or package that was renamed or dropped. `"*"` never warns.
531
555
  - **The most specific key wins outright** for a soul's teams, and lists never
532
556
  merge: the soul's own key, then `<member|package>/*`, then `"*"`. The
533
557
  default comes from the most specific key that sets one. So
@@ -820,8 +844,10 @@ PATH STATE VIA
820
844
  ```
821
845
 
822
846
  **Concurrency.** Every change runs under `~/.oats/config/deployments.lock`
823
- (waiting up to 3 s for it) and re-reads the file inside it, and each write
824
- replaces the file atomically. Readers take no lock: they read a regular file
847
+ (waiting up to 3 s for a holder that is running) and re-reads the file inside
848
+ it, and each write replaces the file atomically. The lock is a file that names
849
+ the process holding it: one left by a command that was killed is taken over by
850
+ the next command. Readers take no lock: they read a regular file
825
851
  only, without following a link, up to 1 MiB. A missing file is an empty list.
826
852
 
827
853
  **Errors:**
@@ -830,7 +856,7 @@ only, without following a link, up to 1 MiB. A missing file is an empty list.
830
856
  |---|---|
831
857
  | `E_DEPLOYMENTS_INVALID` | the file is not JSON, not an object, a link, over 1 MiB, or a row breaks the schema: "`<file>` cannot be read as this computer's deployments list (`<reason>`). Fix it, or move it aside and run `oats deployments add <dir>` for each deployment; nothing was changed" |
832
858
  | `E_DEPLOYMENTS_VERSION` | `schemaVersion` is newer than this oats reads: "`<file>` was written by a newer oats (schema `<n>`); upgrade oats". The file is never rewritten down |
833
- | `E_DEPLOYMENTS_BUSY` | the lock is still held after 3 s: "this computer's deployments list is locked (`<why>`); if no oats process is changing it, remove `<lock>` and retry; nothing was changed" |
859
+ | `E_DEPLOYMENTS_BUSY` | the lock is still held by a running process after 3 s, or cannot be judged: "this computer's deployments list is locked (`<why>`); if no oats process is changing it, remove `<lock>` and retry; nothing was changed". `<why>` says what was found: `pid <n> holds it`; `the record at <lock> is unreadable` (remove that file); that it cannot be established whether pid `<n>` still runs (check that pid by hand, then remove the file); or `<lock> is a lock directory written by an earlier kernel` (remove the directory once no older oats is running) |
834
860
  | `E_DEPLOYMENTS_WRITE` | the write failed, or would make the file larger than 1 MiB: "cannot write `<file>` (`<system error>`); nothing was changed" |
835
861
  | `E_DEPLOYMENTS_IMPORT` | `~/Agents` cannot be read for the first-use import: "cannot read `<dir>` to import its deployments (`<system error>`); make it readable, or move it aside, and retry; nothing was changed" |
836
862
 
package/lib/claim.mjs CHANGED
@@ -1,10 +1,11 @@
1
1
  /** The claim: one file that says which process is doing a thing that must happen once at a time.
2
2
  * One protocol, used by `oats worktree add|remove` (the purpose's claim, lib/worktree.mjs
3
3
  * `withClaim`) and by `oats retire` and `oats instance stop` (the home's claim, lib/core.mjs
4
- * `claimHomeFor`).
4
+ * `claimHomeFor`), and by the lock of the kernel's shared files and of the machine's resume sweep
5
+ * (lib/dir-lock.mjs `withDirLock`, `acquireDirLock`).
5
6
  *
6
- * Unlike lib/dir-lock.mjs, a claim left by a process that died is taken over, so a killed command
7
- * can always be run again: the owner is named by pid AND start time (processLiveness), never by a
7
+ * A claim left by a process that died is taken over, so a killed command can always be run
8
+ * again: the owner is named by pid AND start time (processLiveness), never by a
8
9
  * pid alone, and a holder whose start cannot be read is never taken for gone.
9
10
  *
10
11
  * - Taking it: the owner's facts `{ pid, processStart, nonce, at }`, with what the caller adds to
@@ -87,6 +88,13 @@
87
88
  * caller's answer for a step that could not be ended
88
89
  * (`at` is kept); `ended` is a clause naming what it
89
90
  * ended, when it ended something
91
+ * holderGone(holder) optional: whether a fact of the caller's own in the record
92
+ * says that `holder` is gone, whatever its pid reads as (the
93
+ * resume sweep's lock: taken in another boot, which no process
94
+ * outlives, while a pid and a start counted from the boot can
95
+ * both come again in the next). Asked in place of reading the
96
+ * process, by acquireClaim and by claimUnheld; such a holder
97
+ * is taken over as any gone one
90
98
  * waitMs how long a live holder is waited for (default CLAIM_WAIT_MS)
91
99
  * warnings optional array a takeover's warnings are pushed to
92
100
  * facts optional object, what the caller's claim says besides its
@@ -223,7 +231,7 @@ export function claimUnheld(path, opts, otherwise) {
223
231
  try { holder = JSON.parse(text); } catch { holder = null; }
224
232
  // readClaim's own reading of bytes that are no claim, `unreadable` in a record included.
225
233
  if (!holder || typeof holder !== "object" || holder.unreadable) throw opts.unreadableClaim(path, []);
226
- const live = processLiveness(holder);
234
+ const live = holderLiveness(holder, opts);
227
235
  if (live.state !== "gone") throw opts.busy(holder, live.state === "unknown" ? live.reason : null, path, []);
228
236
  const stuck = cannotBeTakenOver(holder, 0);
229
237
  if (stuck) throw opts.cannotTakeOver(holder, path, stuck, []);
@@ -231,6 +239,14 @@ export function claimUnheld(path, opts, otherwise) {
231
239
  }
232
240
  }
233
241
 
242
+ /** Whether the holder a claim record names can still act, as processLiveness answers it, for the
243
+ * caller whose refusals are `opts`: gone when its `holderGone` says so, whatever the process reads
244
+ * as. The one reading of a holder for taking a claim (takeClaim) and for reading one (claimUnheld),
245
+ * and of a cache write lock's holder that names its boot and start (lib/remote.mjs isStaleLock). */
246
+ export function holderLiveness(holder, opts) {
247
+ return opts.holderGone?.(holder) ? { state: "gone" } : processLiveness(holder);
248
+ }
249
+
234
250
  /** Take the claim `path` → this holding (`{ pid, processStart, nonce, at }`, with `opts.facts`), to
235
251
  * pass to releaseClaim. Throws the caller's refusal when it cannot be taken, and claimUnavailable for
236
252
  * any error that is not the kernel's. The directory exists. */
@@ -258,7 +274,7 @@ function takeClaim(path, opts, depth, endedSteps) {
258
274
  catch (e) { if (e?.code !== "EEXIST") throw e; }
259
275
  const holder = readClaim(path);
260
276
  if (holder?.unreadable) throw opts.unreadableClaim(path, endedSteps);
261
- const live = holder ? processLiveness(holder) : null;
277
+ const live = holder ? holderLiveness(holder, opts) : null;
262
278
  // Unreadable is never taken for gone: the claim is kept, and the refusal names the way out.
263
279
  if (live?.state === "unknown") throw busy(holder, live.reason, path, endedSteps);
264
280
  const gone = live?.state === "gone";
@@ -0,0 +1,238 @@
1
+ /** lib/command-flags.mjs — the flags each state-changing kernel command defines (oats-project/oats#1791),
2
+ * and the one check of a command's argv against them, which the CLI's dispatch runs before the command
3
+ * runs and before a `--server` command is sent to its host: a flag the command does not define, a value
4
+ * on one of its switches, or an argument after its last one is refused with E_BAD_ARGS, never ignored, so
5
+ * a mistyped protective flag (`--keep-dirs` for `--keep-dir`) never does the unprotected thing. A command
6
+ * missing here is not checked. Kernel-private, not exported from `./core`. Dependency-free. */
7
+
8
+ export const RETIRE_DELETE_BRANCH_REFUSED = "oats retire no longer deletes branches: --delete-branch is not accepted. Retire without it; the branch is left in the repository. Inspect it there and delete it with Git if it is no longer wanted.";
9
+ export const RETIRE_USAGE = "usage: oats retire <instance> [--plan] [--plan-revision <rev> --idempotency-key <key>] [--home <path>] [--dir <d>] [--server <id>] [--self] [--discard-worktree] [--keep-dir] [--force] [--json]";
10
+ export const SPAWN_USAGE = "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>|--suggest-name] [--preview] [--base <ref>] [--model <id>|@native-default] [--allow-child-spawns|--no-child-spawns] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--same-work] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux] [--yolo|--no-yolo] [--background|--no-background] [--model <m>] [--branch <b>] [--no-launch] [--json]";
11
+ export const SYNC_USAGE = "usage: oats sync [--dir <deployment>] [--plan] [--json]";
12
+ export const APPROVAL_REMOVED = "package approval was removed; declaring a package in packages: is the trust decision";
13
+ export const TEAMS_USAGE = "usage: oats teams [--json] | oats teams add <label> --team <id> [--description <d>] [--no-default] | oats teams remove <label> | oats teams default <label> [--if-absent | --expect <label>] [--dir <deployment>] [--json]";
14
+ export const SOUL_LAUNCH_USAGE = "oats soul launch set <soul>|'*' (--launch-config <name>|none | --harness pi|claude|codex [--model <id>]) [--plan] [--dir <deployment>] [--json] | oats soul launch remove <soul>|'*'|<exact key> [--plan] [--dir <deployment>] [--json]";
15
+ export const WORKTREE_USAGE = "usage: oats worktree add --purpose <p> --branch <b> --base <remote-branch> [--repo <member key|clone path>] [--preview] [--json] | oats worktree remove --purpose <p> [--json]";
16
+
17
+ const WORKTREE_REFUSED = Object.freeze({
18
+ "--server": "oats worktree runs in an instance home on this machine; --server is not accepted",
19
+ "--dir": `oats worktree has no --dir: it acts on the instance home it runs in; ${WORKTREE_USAGE}`,
20
+ "--home": `oats worktree has no --home: it acts on the instance home it runs in; ${WORKTREE_USAGE}`,
21
+ });
22
+ const launchConfigWrite = (sub) => {
23
+ const refused = `launch-config ${sub} writes the deployment's oats-local.yaml: address it with --dir, not --home or --soul`;
24
+ return { "--home": refused, "--soul": refused };
25
+ };
26
+ const SESSION_VALUES = Object.freeze(["--home", "--instance", "--launch-config", "--harness", "--runtime", "--model", "--server"]);
27
+ const SESSION_SWITCHES = Object.freeze(["--reselect-launch", "--yolo", "--no-yolo", "--json"]);
28
+ const SCHEDULE_VALUES = Object.freeze(["--dir", "--server"]);
29
+ const schedule = (verb, switches = []) => ({ command: `schedule ${verb}`, operands: ["id"], values: SCHEDULE_VALUES, switches: [...switches, "--json"],
30
+ usage: `usage: oats schedule ${verb} <id>${switches.map((s) => ` [${s}]`).join("")} [--dir <workspace> | --server <id>] [--json]` });
31
+ const trigger = (verb) => ({ command: `trigger ${verb}`, operands: ["id"], values: ["--dir"], switches: ["--json"], usage: `usage: oats trigger ${verb} <id> [--dir <deployment>] [--json]` });
32
+ const INSTANCE_RECORD_VALUES = Object.freeze(["--home", "--dir", "--server"]);
33
+ const onOff = (verb) => ({ command: `instance ${verb}`, operands: ["instance", "state"], values: INSTANCE_RECORD_VALUES, switches: ["--json"],
34
+ usage: `usage: oats instance ${verb} <instance> on|off [--home <abs>] [--dir <d> | --server <id>] [--json]` });
35
+ const WAITING_VALUES = Object.freeze(["--producer", "--reason", "--message", "--home", "--dir"]);
36
+ const waiting = (verb) => ({ command: `instance waiting ${verb}`, operands: [], values: WAITING_VALUES, switches: ["--json"],
37
+ usage: `usage: oats instance waiting ${verb} --producer <id>${verb === "set" ? " --reason permission|question|attention" : ""} [--message=<text>] [--home <abs>] [--dir <d>] [--json]` });
38
+ const ATTENTION_USAGE = "usage: oats instance attention [--message=<text>] [--clear] [--json]";
39
+ const attentionHasNo = (flag) => `oats instance attention has no ${flag}: it records the agent's own claim on the instance it runs in ($OATS_INSTANCE_HOME); ${ATTENTION_USAGE}`;
40
+ const TRIGGER_RUN_SOURCE = Object.freeze(["--run-source", "--json"]);
41
+ const SESSION_ADDRESS = Object.freeze(["--home", "--instance", "--server"]);
42
+ /** Every `oats session` form refuses the captured path's selector in these words (bin's sessionCmd says them
43
+ * for the forms not declared here). */
44
+ export const NATIVE_RECORD_REFUSED = "--native-record outcome inspection is gone (the captured/portable path was removed in 0.26)";
45
+ const NATIVE_RECORD_GONE = Object.freeze({ "--native-record": NATIVE_RECORD_REFUSED });
46
+ /** A resume is this machine's (#1559, D1): a server resumes its own instances. */
47
+ export const RESUME_LOCAL_ONLY = "session resume and session start --resume act on this machine's instances only; a server runs oats session resume itself";
48
+ const UPDATE_TAKES_NO_PACKAGE = "oats update takes no package: pin package versions in oats-workspace.yaml (`oats package add <id> <version>`), then `oats sync`; bare `oats update [--check] [--yes]` updates the kernel";
49
+ const SPAWN_REMOVED_SOUL = (flag) => `${flag} created a local soul under local-agents/, which the workspace model removed — author souls/<name>/soul.yaml + AGENTS.md in a member repository, then \`oats sync\``;
50
+ /** `oats teams` and `oats soul launch` answer a flag they do not take with E_USAGE in their own words
51
+ * (docs/desktop-cli-api.md "oats teams", "oats soul launch"). */
52
+ const teamsUnknown = (form) => (flag) => ({ code: "E_USAGE", message: `${form} does not take ${flag} (an option this kernel does not know may need a newer kernel; nothing was changed) — ${TEAMS_USAGE}`, details: { flag } });
53
+ /** An `oats teams` form takes these, beyond `--dir` and `--json`; anything else is refused, never ignored:
54
+ * a kernel that ignored `--if-absent` would set unconditionally. */
55
+ const teams = (verb, values, switches) => ({ command: `teams ${verb}`, operands: ["label"], values: ["--dir", ...values], switches: [...switches, "--json"], unknown: teamsUnknown(`oats teams ${verb}`),
56
+ usage: `usage: oats teams ${verb} <label>${[...values.map((v) => ` [${v} <${v.slice(2)}>]`), ...switches.map((s) => ` [${s}]`)].join("")} [--dir <deployment>] [--json]` });
57
+ /** An `oats soul launch` form takes these; anything else is refused, never ignored: `--home` and `--soul`
58
+ * among them, since the soul is the argument and the file the deployment's. */
59
+ const soulLaunch = (verb, values) => ({ command: `soul launch ${verb}`, operands: [verb === "set" ? "soul" : "soul or key"], values: ["--dir", ...values], switches: ["--plan", "--json"],
60
+ unknown: (flag) => ({ code: "E_USAGE", message: `oats soul launch ${verb} does not take ${flag} (nothing was changed) — usage: ${SOUL_LAUNCH_USAGE}`, details: { flag } }),
61
+ // Every name it was given, in its own words: `remove dev writer` would remove dev alone.
62
+ extra: (args) => ({ code: "E_BAD_ARGS", message: `oats soul launch ${verb} takes one ${verb === "set" ? "soul" : "soul or key"}, and got ${args.length}: ${args.map((n) => JSON.stringify(n)).join(", ")} (nothing was changed) — usage: ${SOUL_LAUNCH_USAGE}` }),
63
+ usage: verb === "set" ? "usage: oats soul launch set <soul>|'*' (--launch-config <name>|none | --harness pi|claude|codex [--model <id>]) [--plan] [--dir <deployment>] [--json]" : "usage: oats soul launch remove <soul>|'*'|<exact key> [--plan] [--dir <deployment>] [--json]" });
64
+
65
+ /** Each command's argv, frozen to its arrays: `command` its words; `operands` the names of the arguments
66
+ * it takes after them, in order (one more is refused); `required` how many of them it needs (all, unless
67
+ * it says: a missing one is the command's own refusal, and E_USAGE here when `--server` is given);
68
+ * `values` the flags that take a value, `arity` those that take more than one word (`{ flag: words }`);
69
+ * `switches` the flags that take none; `refused` the flags it refuses with their own message; `usage`
70
+ * the line every shared refusal ends with. A row answers in its own words with `unknown(flag)` for a flag
71
+ * it does not define and `extra(args)` for an argument after its last (`args`: every argument it was
72
+ * given), each → { code, message, details? }. `--json` is a switch of every one. A value flag given no
73
+ * value is that flag's own refusal, by the command. */
74
+ export const COMMAND_FLAGS = Object.freeze([
75
+ { command: "retire", operands: ["instance"], values: ["--plan-revision", "--idempotency-key", "--home", "--dir", "--server"], switches: ["--plan", "--self", "--discard-worktree", "--keep-dir", "--force", "--json"],
76
+ refused: { "--delete-branch": RETIRE_DELETE_BRANCH_REFUSED }, usage: RETIRE_USAGE },
77
+ // `--instance` is refused by a local spawn (with its replacement) but still travels to an older host
78
+ // through `--server`, whose route reads it. `--max-age` reaches here only on a preview or an apply bound
79
+ // by --expect-decision: the dispatch allow-list (maxAgeRefusal) refuses it otherwise. `--herdr-socket`
80
+ // and `--backend herdr` are read to be refused (E_HERDR_REMOVED), here and on the route.
81
+ { command: "spawn", operands: ["soul"],
82
+ values: ["--agents-root", "--backend", "--base", "--branch", "--dir", "--expect-decision", "--harness", "--herdr-socket", "--idempotency-key", "--instance", "--launch-config", "--max-age", "--model", "--name", "--parent", "--provider", "--purpose", "--relation", "--relative-root", "--relative-to", "--repo", "--runtime", "--server", "--task", "--task-file", "--trigger-event", "--wake-cron", "--wake-every", "--wake-file", "--wake-json", "--wake-message", "--wake-message-file", "--wake-tz", "--work", "--work-dir"],
83
+ arity: { "--provider": 2 },
84
+ switches: ["--allow-child-spawns", "--background", "--json", "--no-background", "--no-child-spawns", "--no-launch", "--no-yolo", "--preview", "--same-work", "--suggest-name", "--yolo"],
85
+ // Local souls (local-agents/) are gone with the workspace model: a soul is a member
86
+ // repository's souls/<name>, so spawn never writes one.
87
+ refused: { "--instructions-file": SPAWN_REMOVED_SOUL("--instructions-file"), "--def-file": SPAWN_REMOVED_SOUL("--def-file"),
88
+ "--ephemeral": "--ephemeral was removed by the runtime-boundary ruling — declare the agent in a capability manifest (agents:) for automatic ephemeral semantics" },
89
+ unknown: (flag) => ({ code: "E_BAD_ARGS", message: `oats spawn: unknown flag ${flag}` }),
90
+ extra: ([soul, a]) => ({ code: "E_BAD_ARGS", message: /^[A-Za-z0-9_.-]+=/.test(a)
91
+ ? `oats spawn: unexpected argument ${JSON.stringify(a)} after the soul ${JSON.stringify(soul)}: a capability setting is given as --provider <capability> key=value (here: --provider <capability> ${a})`
92
+ : `oats spawn: unexpected argument ${JSON.stringify(a)} after the soul ${JSON.stringify(soul)}: spawn takes one soul` }),
93
+ usage: SPAWN_USAGE },
94
+ // An unknown flag or an argument of sync is refused before anything is read or written (#731).
95
+ { command: "sync", operands: [], values: ["--dir"], switches: ["--plan", "--json"], refused: { "--approve": `--approve: ${APPROVAL_REMOVED}` }, usage: SYNC_USAGE },
96
+ { command: "instance stop", operands: ["instance"], values: ["--plan-revision", "--idempotency-key", "--grace-ms", "--home", "--dir", "--server"], switches: ["--plan", "--apply", "--no-recursive", "--json"],
97
+ usage: "usage: oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d> | --server <id>] [--json]" },
98
+ { command: "instance upgrade", operands: ["instance"], values: ["--plan-revision", "--idempotency-key", "--home", "--dir"], switches: ["--undo", "--plan", "--json"],
99
+ refused: { "--server": "instance upgrade supports local homes only; run it on the deployment host" },
100
+ usage: "usage: oats instance upgrade <instance> [--undo] (--plan | --plan-revision <rev> --idempotency-key <key>) [--home <abs>] [--dir <d>] [--json]" },
101
+ { command: "instance color", operands: ["instance", "color"], required: 1, values: INSTANCE_RECORD_VALUES, switches: ["--clear", "--json"],
102
+ usage: "usage: oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d> | --server <id>] [--json]" },
103
+ onOff("background"),
104
+ onOff("same-work"),
105
+ waiting("set"),
106
+ waiting("clear"),
107
+ { command: "instance attention", operands: [], values: ["--message"], switches: ["--clear", "--json"],
108
+ refused: Object.fromEntries(["--home", "--dir", "--producer", "--reason"].map((f) => [f, attentionHasNo(f)])), usage: ATTENTION_USAGE },
109
+ { command: "instance suggest-name", operands: [], values: ["--soul", "--task", "--task-file", "--harness", "--model", "--launch-config", "--dir"], switches: ["--json"],
110
+ refused: { "--server": "instance suggest-name takes no --server: it runs this machine's harness, for a spawn that may land on another; the host it lands on makes the name unique (or names an unnamed --suggest-name spawn itself)" },
111
+ usage: "usage: oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]" },
112
+ { command: "worktree add", operands: [], values: ["--purpose", "--branch", "--base", "--repo"], switches: ["--preview", "--json"], refused: WORKTREE_REFUSED,
113
+ usage: "usage: oats worktree add --purpose <p> --branch <b> --base <remote-branch> [--repo <member key|clone path>] [--preview] [--json]" },
114
+ { command: "worktree remove", operands: [], values: ["--purpose"], switches: ["--json"], refused: WORKTREE_REFUSED,
115
+ usage: "usage: oats worktree remove --purpose <p> [--json]" },
116
+ { command: "session start", operands: [], refused: NATIVE_RECORD_GONE, values: SESSION_VALUES, switches: [...SESSION_SWITCHES, "--resume"],
117
+ usage: "usage: oats session start (--home <abs> | --server <id> (--instance <name> | --home <abs>)) [--launch-config <name>|none | --reselect-launch] [--harness pi|claude|codex] [--model <id>] [--yolo|--no-yolo] [--resume] [--json]" },
118
+ { command: "session restart", operands: [], values: [...SESSION_VALUES, "--stop-grace"], switches: SESSION_SWITCHES,
119
+ refused: { ...NATIVE_RECORD_GONE, "--resume": "--resume exists on session start only: it brings back a session that was lost" },
120
+ usage: "usage: oats session restart (--home <abs> | --server <id> (--instance <name> | --home <abs>)) [--launch-config <name>|none | --reselect-launch] [--harness pi|claude|codex] [--model <id>] [--yolo|--no-yolo] [--stop-grace <seconds>] [--json]" },
121
+ { command: "session resume", operands: [], values: ["--deployment"],
122
+ refused: { ...NATIVE_RECORD_GONE, "--server": RESUME_LOCAL_ONLY }, switches: ["--plan", "--json"], usage: "usage: oats session resume [--deployment <dir>] [--plan] [--json]" },
123
+ { command: "session input", operands: [], refused: NATIVE_RECORD_GONE, values: ["--home", "--text-file"], switches: ["--json"], usage: "usage: oats session input --home <abs> [--text-file <path>] [--json]" },
124
+ { command: "session receive", operands: [], refused: NATIVE_RECORD_GONE, values: ["--home", "--name"], switches: ["--json"], usage: "usage: oats session receive --home <abs> --name <file name> [--json]" },
125
+ { command: "session upload", operands: [], refused: NATIVE_RECORD_GONE, values: ["--file", ...SESSION_ADDRESS], switches: ["--json"],
126
+ usage: "usage: oats session upload --file <path> (--home <abs> | --server <id> (--instance <name> | --home <abs>)) [--json]" },
127
+ { command: "session attach", operands: [], refused: NATIVE_RECORD_GONE, values: ["--detach-key", ...SESSION_ADDRESS], switches: ["--no-status-line", "--print", "--json"],
128
+ usage: "usage: oats session attach (--home <abs> | --server <id> (--instance <name> | --home <abs>) [--print]) [--detach-key <key>] [--no-status-line]" },
129
+ { command: "schedule add", operands: ["id"], required: 0, values: ["--file", "--spec-json", "--description", "--workspace", "--runs-on", "--owner", ...SCHEDULE_VALUES], switches: ["--json"],
130
+ usage: "usage: oats schedule add [<id>] (--file <spec.json> | --spec-json <json>) [--description=<text>] [--workspace <member> --runs-on <host> --owner <host>/<login>] [--dir <workspace> | --server <id>] [--json]" },
131
+ { command: "schedule update", operands: ["id"], values: ["--file", "--spec-json", "--description", ...SCHEDULE_VALUES], switches: ["--json"],
132
+ usage: "usage: oats schedule update <id> (--file <spec.json> | --spec-json <json> [--description=<text>] | --description=<text>) [--dir <workspace> | --server <id>] [--json]" },
133
+ schedule("remove", ["--force"]),
134
+ schedule("run", ["--force"]),
135
+ schedule("enable"),
136
+ schedule("disable"),
137
+ schedule("reconcile", ["--clear"]),
138
+ { command: "schedule tick", operands: [], values: SCHEDULE_VALUES, switches: ["--dry-run", "--host", "--json"], usage: "usage: oats schedule tick [--dry-run] [--host] [--dir <workspace> | --server <id>] [--json]" },
139
+ { command: "schedule host install", operands: [], values: ["--max-concurrent", "--triggers-max-concurrent", "--os", ...SCHEDULE_VALUES], switches: ["--print", "--json"],
140
+ usage: "usage: oats schedule host install [--max-concurrent <N|default>] [--triggers-max-concurrent <N|none>] | --print [--os darwin|linux] [--dir <workspace> | --server <id>] [--json]" },
141
+ { command: "schedule host uninstall", operands: [], values: SCHEDULE_VALUES, switches: ["--json"], usage: "usage: oats schedule host uninstall [--dir <workspace> | --server <id>] [--json]" },
142
+ { command: "trigger add", operands: [], values: ["--file", "--from", "--set", "--id", "--description", "--workspace", "--runs-on", "--owner", "--dir"], switches: ["--json"],
143
+ usage: "usage: oats trigger add (--file <trigger.json> | --from <package>:<template> [--set <name>=<value>]… [--id <id>]) [--description=<text>] [--workspace <member> --runs-on <host> --owner <host>/<login>] [--dir <deployment>] [--json]" },
144
+ { command: "trigger poll", operands: ["id"], values: ["--dir", "--max-age"], switches: TRIGGER_RUN_SOURCE, usage: "usage: oats trigger poll <id> --run-source [--max-age <s>] [--dir <deployment>] [--json]" },
145
+ { command: "trigger test", operands: ["id"], values: ["--dir"], switches: TRIGGER_RUN_SOURCE, usage: "usage: oats trigger test <id> [--run-source] [--dir <deployment>] [--json]" },
146
+ trigger("remove"),
147
+ trigger("enable"),
148
+ trigger("disable"),
149
+ { command: "teams", operands: [], values: ["--dir", "--max-age"], switches: ["--json"], unknown: teamsUnknown("oats teams"),
150
+ // A word where a form belongs: the forms' usage, as before.
151
+ extra: () => ({ code: "E_USAGE", message: TEAMS_USAGE }), usage: "usage: oats teams [--max-age <s>] [--dir <deployment>] [--json]" },
152
+ teams("add", ["--team", "--description"], ["--no-default"]),
153
+ teams("remove", [], []),
154
+ teams("default", ["--expect"], ["--if-absent"]),
155
+ soulLaunch("set", ["--launch-config", "--harness", "--model"]),
156
+ soulLaunch("remove", []),
157
+ { command: "server check", operands: ["id"], values: [], switches: ["--json"], usage: "usage: oats server check <id> [--json]" },
158
+ { command: "server remove", operands: ["id"], values: [], switches: ["--json"], usage: "usage: oats server remove <id> [--json]" },
159
+ { command: "server forget", operands: ["id"], values: ["--instance"], switches: ["--json"], usage: "usage: oats server forget <id> --instance <name> [--json]" },
160
+ { command: "package add", operands: ["id", "version"], values: ["--dir"], switches: ["--json"], usage: "usage: oats package add <id> <version|git:<repo>@<ref>> [--dir <d>] [--json]" },
161
+ { command: "package remove", operands: ["id"], values: ["--dir"], switches: ["--json"], usage: "usage: oats package remove <id> [--dir <d>] [--json]" },
162
+ { command: "launch-config set", operands: ["name"], values: ["--file", "--dir", "--server"], switches: ["--keep-env", "--json"], refused: launchConfigWrite("set"),
163
+ usage: "usage: oats launch-config set <name> --file <json> [--keep-env] [--dir <scope> | --server <id>] [--json]" },
164
+ { command: "launch-config remove", operands: ["name"], values: ["--dir", "--server"], switches: ["--json"], refused: launchConfigWrite("remove"),
165
+ usage: "usage: oats launch-config remove <name> [--dir <scope> | --server <id>] [--json]" },
166
+ { command: "automations refresh", operands: [], values: ["--dir"], switches: ["--json"], usage: "usage: oats automations refresh [--dir <deployment>] [--json]" },
167
+ // `oats update <package>` left with the installed tier (packages are pinned in the workspace file:
168
+ // `oats package add`); only the kernel self-update remains, and a package word is answered with that.
169
+ { command: "update", operands: [], values: ["--dir"], switches: ["--check", "--yes", "--json"], refused: { "--to": UPDATE_TAKES_NO_PACKAGE },
170
+ extra: ([a]) => ({ code: "E_BAD_ARGS", message: UPDATE_TAKES_NO_PACKAGE, details: { argument: a } }), usage: "usage: oats update [--check] [--yes] [--dir <deployment>]" },
171
+ ].map((c) => Object.freeze({ ...c, operands: Object.freeze([...c.operands]), required: c.required ?? c.operands.length, values: Object.freeze([...c.values]), switches: Object.freeze([...c.switches]),
172
+ arity: Object.freeze({ ...c.arity }), ...(c.refused ? { refused: Object.freeze({ ...c.refused }) } : {}) })));
173
+
174
+ /** The declaration of the command `argv` (the CLI's argv, after `oats`) runs: the one whose words its
175
+ * first words are, the longest of them; undefined for a command not declared here. */
176
+ export function commandFlags(argv) {
177
+ let found;
178
+ for (const c of COMMAND_FLAGS) {
179
+ const words = c.command.split(" ");
180
+ if (words.every((w, i) => argv[i] === w) && (!found || words.length > found.command.split(" ").length)) found = c;
181
+ }
182
+ return found;
183
+ }
184
+
185
+ /** Why `argv` (the CLI's argv, after `oats`, as typed: `--flag=value` unexpanded) is not a command its
186
+ * declaration allows, as { code, message, details? }, or undefined (allowed, or not declared). The first
187
+ * problem from the left, E_BAD_ARGS unless the row answers in its own words: a refused flag (its own
188
+ * message), a flag the command does not define (`oats <command>: unknown flag <flag>`, or the row's
189
+ * `unknown`), a switch given a value with `=`, or an argument after its last (or the row's `extra`, given
190
+ * every argument); each shared one ends with the command's usage. A value flag with no value (none, or a word that starts with `--`) ends the
191
+ * check there with undefined: the command refuses it in its own words. Then, for a command given `--server`,
192
+ * a missing argument it requires: E_USAGE with the usage line, so that it is never sent (on this machine
193
+ * each command answers a missing argument itself). A value flag takes the next word (its `arity` words)
194
+ * as its value unless it starts with `--`, as the CLI's flag reader does (lib/argv.mjs flagValue); a value
195
+ * after `=` is its first. `--` is a flag like any other. */
196
+ export function commandArgvProblem(argv) {
197
+ const c = commandFlags(argv);
198
+ if (!c) return undefined;
199
+ const given = [];
200
+ let extra = null, routed = false;
201
+ for (let i = c.command.split(" ").length; i < argv.length; i++) {
202
+ const a = argv[i];
203
+ if (!a.startsWith("-")) {
204
+ if (given.length === c.operands.length && extra === null) extra = a;
205
+ given.push(a);
206
+ continue;
207
+ }
208
+ const eq = a.startsWith("--") ? a.indexOf("=") : -1;
209
+ const flag = eq > 2 ? a.slice(0, eq) : a;
210
+ // After an argument too many, the rest is read only for the arguments it holds.
211
+ if (extra === null) {
212
+ if (c.refused && Object.hasOwn(c.refused, flag)) return { code: "E_BAD_ARGS", message: c.refused[flag], details: { flag } };
213
+ if (c.switches.includes(flag)) {
214
+ if (flag !== a) return { code: "E_BAD_ARGS", message: `oats ${c.command}: ${flag} takes no value (got ${a})\n${c.usage}`, details: { flag } };
215
+ continue;
216
+ }
217
+ if (!c.values.includes(flag)) return c.unknown ? c.unknown(flag) : { code: "E_BAD_ARGS", message: `oats ${c.command}: unknown flag ${flag}\n${c.usage}`, details: { flag } };
218
+ if (flag === "--server") routed = true;
219
+ } else if (!c.values.includes(flag)) continue;
220
+ for (let words = (c.arity[flag] ?? 1) - (flag === a ? 0 : 1); words > 0; words--) {
221
+ // A value missing is a problem at this flag, the command's own: the check ends here, and the
222
+ // command answers it ("--dir needs a value"), never a flag further on.
223
+ // Its limit: a command that reads such a flag as absent on some path (instance stop --plan and
224
+ // --grace-ms) lets a later unknown flag pass on that path unrefused.
225
+ if (argv[i + 1] === undefined || argv[i + 1].startsWith("--")) { if (extra === null) return undefined; break; }
226
+ i++;
227
+ }
228
+ }
229
+ if (extra !== null) return c.extra ? c.extra(given) : { code: "E_BAD_ARGS", message: extraArgument(c, extra, given), details: { argument: extra } };
230
+ if (routed && given.length < c.required) return { code: "E_USAGE", message: c.usage };
231
+ return undefined;
232
+ }
233
+
234
+ function extraArgument(c, a, given) {
235
+ if (!c.operands.length) return `oats ${c.command}: unexpected argument ${JSON.stringify(a)}: ${c.command} takes no argument\n${c.usage}`;
236
+ const last = c.operands.length - 1;
237
+ return `oats ${c.command}: unexpected argument ${JSON.stringify(a)} after the ${c.operands[last]} ${JSON.stringify(given[last])}: ${c.command} takes ${c.operands.map((n) => `one ${n}`).join(" and ")}\n${c.usage}`;
238
+ }