@awebai/oats 0.64.0 → 0.66.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 (51) hide show
  1. package/README.md +11 -5
  2. package/bin/oats.mjs +109 -11
  3. package/docs/desktop-cli-api.md +88 -5
  4. package/docs/desktop.md +14 -5
  5. package/docs/implementation.md +26 -3
  6. package/docs/integrations.md +1 -1
  7. package/docs/official-catalog.md +2 -2
  8. package/docs/packages.md +7 -7
  9. package/docs/release-notes/v0.65.0.md +187 -0
  10. package/docs/release-notes/v0.66.0.md +183 -0
  11. package/docs/servers.md +2 -2
  12. package/docs/tui.md +548 -249
  13. package/docs/upgrading.md +1 -1
  14. package/docs/workspaces.md +132 -1
  15. package/lib/core.mjs +14 -4
  16. package/lib/deployments.mjs +341 -0
  17. package/lib/resolved-deployment.mjs +37 -0
  18. package/lib/workspace.mjs +2 -0
  19. package/package-catalog.json +2 -2
  20. package/package.json +1 -1
  21. package/packages/client/cli-locator.mjs +2 -2
  22. package/packages/client/deployment-label.mjs +2 -2
  23. package/packages/client/deployment-list-cli.mjs +98 -0
  24. package/packages/client/deployment-list.mjs +91 -0
  25. package/packages/client/keymap.mjs +133 -0
  26. package/packages/client/machine-contract.mjs +1 -5
  27. package/packages/client/own-codes.mjs +2 -0
  28. package/packages/client/panel-views.mjs +1 -1
  29. package/packages/client/workspace-admission.mjs +2 -1
  30. package/packages/record/bin/setup.mjs +10 -2
  31. package/packages/record/docs/capture-service.md +45 -6
  32. package/packages/record/lib/capture-service-install.mjs +6 -95
  33. package/packages/record/lib/capture-setup-write.mjs +233 -0
  34. package/packages/tui/README.md +10 -9
  35. package/packages/tui/lib/actions.mjs +89 -64
  36. package/packages/tui/lib/client.mjs +4 -1
  37. package/packages/tui/lib/config.mjs +184 -36
  38. package/packages/tui/lib/main.mjs +161 -40
  39. package/packages/tui/lib/model.mjs +73 -41
  40. package/packages/tui/lib/read.mjs +15 -45
  41. package/packages/tui/lib/store.mjs +174 -40
  42. package/packages/tui/lib/term/keys.mjs +135 -33
  43. package/packages/tui/lib/term/kitty.mjs +198 -0
  44. package/packages/tui/lib/term/through.mjs +160 -24
  45. package/packages/tui/lib/term/tty.mjs +43 -12
  46. package/packages/tui/lib/views/act.mjs +17 -13
  47. package/packages/tui/lib/views/frame.mjs +418 -421
  48. package/packages/tui/lib/views/help.mjs +90 -29
  49. package/packages/tui/lib/views/instances.mjs +38 -9
  50. package/packages/tui/lib/views/switcher.mjs +65 -21
  51. package/skills/oats-getting-started/SKILL.md +102 -32
package/docs/upgrading.md CHANGED
@@ -93,7 +93,7 @@ Service A ships in [0.62.0](release-notes/v0.62.0.md) and every later
93
93
  release. Read 0.62.0's Upgrade section and keep this order: install the
94
94
  Desktop of the release you upgrade to first (the 0.62.0 Desktop accepts CLIs
95
95
  `>=0.26.0 <0.63.0`, the 0.63.0 Desktop `>=0.26.0 <0.64.0`, the 0.64.0
96
- Desktop `>=0.26.0 <0.65.0`), then that
96
+ Desktop `>=0.26.0 <0.65.0`, the 0.65.0 Desktop `>=0.26.0 <0.66.0`, the 0.66.0 Desktop `>=0.26.0 <0.67.0`), then that
97
97
  release's CLI and matching pi bridge. Only **after
98
98
  installing that CLI**, run its setup conversion once per user on each host,
99
99
  from that user's shell, then its health and doctor checks. That conversion is where an owned legacy
@@ -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.13.3 # bare version → resolves through the official catalog
57
+ oats.framework: v1.13.4 # bare version → resolves through the official catalog
58
58
  oats.okf: v5.2.1
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
@@ -657,6 +657,137 @@ is fetched into `<agents-root>/<soul>/souls/<commit12>/` at its discovered
657
657
  commit before its first spawn (idempotent per commit; `<agents-root>/<soul>/soul`
658
658
  points at the current one); its instances then materialize as above.
659
659
 
660
+ ## This computer's deployments
661
+
662
+ Most people have several deployments, and one computer can hold two
663
+ deployments of the same workspace. The kernel keeps **one per-user list of the
664
+ deployments on this computer**, `~/.oats/config/deployments.json`
665
+ (`OATS_HOME_DIR` overrides `~/.oats`). The clients (the Desktop, the TUI) read
666
+ it to offer the deployments that are not open, and `oats deployments` shows it.
667
+ It lists local deployments only: other machines stay in the
668
+ [server registry](servers.md).
669
+
670
+ **The file** (mode 0600, in a `config/` directory with mode 0700) holds facts
671
+ only. Which deployments a client has open stays with that client.
672
+
673
+ ```json
674
+ {
675
+ "schemaVersion": 1,
676
+ "deployments": [ { "path": "/home/me/acme", "addedAt": "2026-10-19T10:00:00.000Z", "via": "onboard" } ],
677
+ "imports": { "agents-dir": "2026-10-19T10:00:00.000Z" }
678
+ }
679
+ ```
680
+
681
+ - **`path`** is absolute and canonical, and unique in the list: the directory
682
+ as it is on disk (a link, or another letter case on a case-insensitive
683
+ filesystem, is one row), then the primary checkout's path when the
684
+ deployment sits in a linked Git worktree.
685
+ - **`via`** says how the row joined, for information only: `onboard`, `tui`,
686
+ `desktop`, `cli`, `import:agents-dir` or `import:desktop`.
687
+ - **`removed: true`** and **`removedAt`** mark a row `oats deployments remove`
688
+ took out (below). Nothing shows it.
689
+ - **`imports`** holds the one-time migration markers; a missing key means that
690
+ import has not run.
691
+
692
+ **What lists a deployment:**
693
+
694
+ - `oats onboard`, on success, lists what it created (`via: onboard`). Its
695
+ result says so in `listed`: `true`, or `{ code, message }` when the list
696
+ could not be written. A failed add never fails the onboard; `--check` lists
697
+ nothing.
698
+ - `oats deployments add [<dir>]`, which the clients run when they open a
699
+ deployment, and people by hand. It lists the deployment at or above `<dir>`
700
+ (default: the current directory): the nearest directory whose
701
+ `oats-local.yaml` is a regular file, not a link. A directory or a link of
702
+ that name is not a deployment's file and is passed over.
703
+ - **Every kernel command that resolves a deployment that is not listed yet**
704
+ lists it (`via: cli`): `status`, `spawn`, `sync`, `session`, `doctor`,
705
+ `retire` and the others that read a local deployment, from inside an
706
+ instance home too. The deployment is the one the command itself resolved
707
+ (its canonical root, when it resolves one), checked once per process, as it
708
+ ends; a command that resolves none (`version`, help, a command
709
+ refused before it reads a deployment) checks nothing.
710
+ - A listed deployment costs one read of the list (at most 1 MiB, no lock),
711
+ compared with the path the command resolved: no lock, no write, no
712
+ process. Measured on `oats status --json`, that is about 0.5 ms the first
713
+ time in a process.
714
+ - Another spelling of a listed deployment (a link, or `/var` for
715
+ `/private/var` on macOS) costs a realpath too. Only an unlisted
716
+ deployment goes further: its canonical path, then one try of the lock. When the lock is free it re-reads and writes once; when
717
+ it is busy the add is skipped at once, and the next command tries again.
718
+ - It is best effort and silent: nothing is printed, and the command's
719
+ answer and exit status are the same whether or not it listed anything.
720
+ - A command routed with `--server` never lists anything: the host's path is
721
+ not this computer's.
722
+ - A deployment under a temporary directory (`os.tmpdir()`, `/tmp`,
723
+ `/private/tmp` or `/var/folders`, each compared after realpath) is never
724
+ listed this way, since test fixtures live there and would stay in the list
725
+ as `missing`; `oats deployments add`, `oats onboard` and a client opening it
726
+ still list one.
727
+ - A deployment inside a linked Git worktree or submodule is listed by the
728
+ first command that resolves its instance root (`status`, `spawn`,
729
+ `session` and the like), not by `sync`, `doctor` and the other
730
+ configuration commands.
731
+
732
+ **Removing.** `oats deployments remove <path>` takes the row whose stored path
733
+ is `<path>` (it does not walk up, so a row whose directory is gone can be
734
+ removed) and touches nothing on disk. The row stays in the file as a
735
+ tombstone, so nothing automatic lists that path again: not a plain command,
736
+ not an import. An explicit `oats deployments add`, an `oats onboard`, or a
737
+ client opening the deployment by its path brings it back.
738
+
739
+ **The first use imports `~/Agents`, once.** The first command that touches the
740
+ list (any of the above) reads `$HOME/Agents` under the list's lock: at most 200
741
+ entries, no link followed (`~/Agents` itself included). Every directory there
742
+ that holds a regular, non-link `oats-local.yaml` is listed
743
+ (`via: import:agents-dir`), and `imports["agents-dir"]` is set, even when
744
+ `~/Agents` is missing or empty. After that nothing reads `~/Agents` again. A
745
+ command whose import could not run (`~/Agents` cannot be read, the lock is
746
+ busy, the write fails) fails: it never answers a list that skipped it, and
747
+ nothing is marked. A single entry inside `~/Agents` that cannot be checked is
748
+ skipped.
749
+
750
+ **The Desktop's own lists** are imported once by
751
+ `oats deployments import --from desktop <path>...`: the first run lists every
752
+ absolute path given, whatever its state, and sets `imports.desktop` in the
753
+ same write; every later run changes nothing.
754
+
755
+ **Each row's state** comes from existence checks only; no deployment's content
756
+ is read:
757
+
758
+ | State | Meaning |
759
+ |---|---|
760
+ | `ok` | the directory holds a regular, non-link `oats-local.yaml` |
761
+ | `missing` | the path is gone, or on a volume that is not mounted |
762
+ | `not-a-deployment` | the path exists, without an `oats-local.yaml` |
763
+ | `unreadable` | the check failed (for example `EACCES`) |
764
+
765
+ ```
766
+ $ oats deployments
767
+ PATH STATE VIA
768
+ ~/acme ok onboard
769
+ ~/old-demo missing import:agents-dir
770
+ ```
771
+
772
+ **Concurrency.** Every change runs under `~/.oats/config/deployments.lock`
773
+ (waiting up to 3 s for it) and re-reads the file inside it, and each write
774
+ replaces the file atomically. Readers take no lock: they read a regular file
775
+ only, without following a link, up to 1 MiB. A missing file is an empty list.
776
+
777
+ **Errors:**
778
+
779
+ | Code | When |
780
+ |---|---|
781
+ | `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" |
782
+ | `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 |
783
+ | `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" |
784
+ | `E_DEPLOYMENTS_WRITE` | the write failed, or would make the file larger than 1 MiB: "cannot write `<file>` (`<system error>`); nothing was changed" |
785
+ | `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" |
786
+
787
+ `oats deployments add` outside every deployment is `E_LOCAL_MISSING`. The
788
+ JSON of each verb is in the
789
+ [Desktop CLI API](desktop-cli-api.md#this-computers-deployments-oats-deployments).
790
+
660
791
  ## The standalone case
661
792
 
662
793
  A repo you can read whose workspace you **cannot** read (a contractor with
package/lib/core.mjs CHANGED
@@ -40,6 +40,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "nod
40
40
  import { homedir } from "node:os";
41
41
  import { accessSync, constants as fsConstants, fstatSync } from "node:fs";
42
42
  import { recordLocalInput } from "./local-inputs.mjs";
43
+ import { resolvedDeployment } from "./resolved-deployment.mjs";
43
44
  import { createHash, randomUUID } from "node:crypto";
44
45
  import { fileURLToPath } from "node:url";
45
46
  import { initializeNativeHistory, prepareNativeStart } from "../packages/record/lib/native-history.mjs";
@@ -468,8 +469,15 @@ function hasGitMarker(dir) {
468
469
  * but the primary checkout cannot be established — including a failed probe,
469
470
  * which must never pass as "not a repo" (reviewer-2366d09): guessing recreates
470
471
  * the very misplacement this exists to prevent.
472
+ *
473
+ * `self`: the path is a deployment directory, owned by the repository it sits
474
+ * in, that repository's root included (this computer's deployments list,
475
+ * lib/deployments.mjs). The probe starts at the directory itself rather than
476
+ * its parent, and the root of a linked worktree maps to the primary checkout's
477
+ * root. Without it (the agents roots), a path that is a work tree's root is left
478
+ * where it is.
471
479
  */
472
- export function canonicalDeploymentPath(p) {
480
+ export function canonicalDeploymentPath(p, { self = false } = {}) {
473
481
  if (!p) return p;
474
482
  const abs = resolve(p);
475
483
  const probe = (argv) => {
@@ -479,7 +487,7 @@ export function canonicalDeploymentPath(p) {
479
487
  // The scope that owns the path. The directory itself may not exist yet
480
488
  // (local-only scopes, an agent dir created on first use), so probe from the
481
489
  // nearest existing ancestor.
482
- let scope = dirname(abs);
490
+ let scope = self ? abs : dirname(abs);
483
491
  while (!existsSync(scope) && dirname(scope) !== scope) scope = dirname(scope);
484
492
  const top = probe(["git", "-C", scope, "rev-parse", "--show-toplevel"]);
485
493
  if (!top.ok) {
@@ -537,7 +545,7 @@ export function canonicalDeploymentPath(p) {
537
545
  // A root OUTSIDE the work tree (sibling agents/ beside the repo) is not a
538
546
  // worktree artifact and is left exactly where it is.
539
547
  const rel = relative(realOf(toplevel), realOf(abs));
540
- if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return abs;
548
+ if ((rel === "" && !self) || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return abs;
541
549
  const canonical = join(realOf(mainWorktree), rel);
542
550
  const back = relative(realOf(mainWorktree), canonical);
543
551
  if (back === ".." || back.startsWith(`..${sep}`) || isAbsolute(back)) {
@@ -565,7 +573,9 @@ export function ensureRoot(cwd) {
565
573
  { from, looked: ["agents/"] });
566
574
  }
567
575
  // Deployment root ≠ invocation CWD: homes always land in the primary checkout.
568
- return canonicalAgentsRoot(root);
576
+ const canonical = canonicalAgentsRoot(root);
577
+ resolvedDeployment(dirname(canonical), { canonical: true });
578
+ return canonical;
569
579
  }
570
580
  export function workspaceOf(root) { return dirname(root); }
571
581
 
@@ -0,0 +1,341 @@
1
+ /**
2
+ * This computer's deployments (docs/workspaces.md "This computer's deployments"; awebai/oats#1390).
3
+ *
4
+ * One per-user list of the deployments on this machine, `~/.oats/config/deployments.json`
5
+ * (OATS_HOME_DIR overrides `~/.oats`, as for the server registry). It holds facts only: each row's
6
+ * canonical path, when it joined and how. Which deployments a client has open stays with that
7
+ * client, and remote machines stay in the server registry (lib/servers.mjs).
8
+ *
9
+ * Who writes it: `oats onboard` (what it created), `oats deployments add|remove|import`, and any
10
+ * kernel command that resolves a deployment that is not listed yet (listResolved, which the CLI
11
+ * sets to observe the command's own resolution: lib/resolved-deployment.mjs). A row `oats deployments remove` took out is kept as a tombstone (`removed`,
12
+ * `removedAt`): nothing automatic lists that path again, and only an explicit add (or an onboard)
13
+ * brings it back.
14
+ *
15
+ * The first command that touches the list imports `$HOME/Agents` once (the deployments directly
16
+ * inside it), under the same lock, and records `imports["agents-dir"]` even when there is nothing
17
+ * to import. A command whose import could not run fails: it never answers a list that skipped it.
18
+ *
19
+ * Concurrency: every read-modify-write holds `config/deployments.lock` (withDirLock), waits up to
20
+ * 3 s for it and re-reads inside it; each write replaces the file atomically. Readers take no lock:
21
+ * they read a regular file only, without following a link, up to 1 MiB. A row's `state` is an
22
+ * existence check: no deployment's content is read here.
23
+ */
24
+
25
+ import { closeSync, constants as fsConstants, fstatSync, lstatSync, mkdirSync, openSync, opendirSync, readSync, statSync } from "node:fs";
26
+ import { homedir, tmpdir } from "node:os";
27
+ import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
28
+ import { canonicalDeploymentPath } from "./core.mjs";
29
+ import { withDirLock } from "./dir-lock.mjs";
30
+ import { writeFileAtomic } from "./packages.mjs";
31
+ import { canonicalHomePath } from "./real-path.mjs";
32
+
33
+ export const DEPLOYMENTS_API = 1;
34
+ export const DEPLOYMENTS_SCHEMA = 1;
35
+ export const DEPLOYMENTS_FILE_BUDGET = 1024 * 1024;
36
+ /** The most entries the `~/Agents` import reads. */
37
+ export const AGENTS_DIR_IMPORT_LIMIT = 200;
38
+ const LOCK_WAIT_MS = 3000;
39
+ /** How a row joined the list (information only). */
40
+ export const DEPLOYMENT_VIA = Object.freeze(["onboard", "tui", "desktop", "cli", "import:agents-dir", "import:desktop"]);
41
+ /** The `--via` values `oats deployments add` takes from a client. */
42
+ export const CLIENT_VIA = Object.freeze(["tui", "desktop"]);
43
+
44
+ const oatsHomeDir = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
45
+ export const deploymentsConfigDir = () => join(oatsHomeDir(), "config");
46
+ export const deploymentsFile = () => join(deploymentsConfigDir(), "deployments.json");
47
+ export const deploymentsLock = () => join(deploymentsConfigDir(), "deployments.lock");
48
+ /** The real `$HOME`, never OATS_HOME_DIR: `~/Agents` is the person's directory. */
49
+ const agentsDir = () => join(homedir(), "Agents");
50
+
51
+ function deploymentsError(code, message, details) {
52
+ return Object.assign(new Error(message), { code, ...(details ? { details } : {}) });
53
+ }
54
+ const invalid = (file, reason) => deploymentsError("E_DEPLOYMENTS_INVALID",
55
+ `${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`, { file, reason });
56
+ const writeFailed = (file, e) => deploymentsError("E_DEPLOYMENTS_WRITE", `cannot write ${file} (${e?.message ?? e}); nothing was changed`, { file, ...(e?.code ? { cause: { code: e.code } } : {}) });
57
+
58
+ // ---------------------------------------------------------------- the file
59
+
60
+ /** The file's text: a regular file, never through a link, within the budget; null when absent. */
61
+ function readBounded(file) {
62
+ let st;
63
+ try { st = lstatSync(file); }
64
+ catch (e) { if (e.code === "ENOENT") return null; throw invalid(file, e.code || e.message); }
65
+ if (st.isSymbolicLink()) throw invalid(file, "it is a link");
66
+ if (!st.isFile()) throw invalid(file, "it is not a regular file");
67
+ if (st.size > DEPLOYMENTS_FILE_BUDGET) throw invalid(file, `it is ${st.size} bytes, over 1 MiB`);
68
+ let fd;
69
+ try {
70
+ // Writers replace the file by rename: the descriptor opened here is one whole old or new file.
71
+ fd = openSync(file, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0));
72
+ const fst = fstatSync(fd);
73
+ if (!fst.isFile()) throw invalid(file, "it is not a regular file");
74
+ if (fst.size > DEPLOYMENTS_FILE_BUDGET) throw invalid(file, `it is ${fst.size} bytes, over 1 MiB`);
75
+ const buf = Buffer.alloc(fst.size); let got = 0;
76
+ while (got < fst.size) { const n = readSync(fd, buf, got, fst.size - got, got); if (n <= 0) break; got += n; }
77
+ return buf.subarray(0, got).toString("utf8");
78
+ } catch (e) {
79
+ if (e?.code === "E_DEPLOYMENTS_INVALID") throw e;
80
+ throw invalid(file, e.code === "ELOOP" ? "it is a link" : e.code || e.message);
81
+ } finally { if (fd !== undefined) try { closeSync(fd); } catch { /* nothing to recover */ } }
82
+ }
83
+
84
+ const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
85
+
86
+ /** The list as stored: `{ schemaVersion, deployments, imports, ...unknown keys kept }`; an empty
87
+ * list when the file is absent. Lock-free. Throws E_DEPLOYMENTS_INVALID | E_DEPLOYMENTS_VERSION. */
88
+ export function readDeploymentsDocument() {
89
+ const file = deploymentsFile();
90
+ const text = readBounded(file);
91
+ if (text === null) return { schemaVersion: DEPLOYMENTS_SCHEMA, deployments: [], imports: {} };
92
+ let doc;
93
+ try { doc = JSON.parse(text); } catch (e) { throw invalid(file, `not JSON: ${e.message}`); }
94
+ if (!isPlainObject(doc)) throw invalid(file, "not a JSON object");
95
+ const v = doc.schemaVersion;
96
+ if (Number.isSafeInteger(v) && v > DEPLOYMENTS_SCHEMA) {
97
+ throw deploymentsError("E_DEPLOYMENTS_VERSION", `${file} was written by a newer oats (schema ${v}); upgrade oats`, { file, schemaVersion: v });
98
+ }
99
+ if (v !== DEPLOYMENTS_SCHEMA) throw invalid(file, `schemaVersion must be ${DEPLOYMENTS_SCHEMA}, got ${JSON.stringify(v)}`);
100
+ if (!Array.isArray(doc.deployments)) throw invalid(file, "deployments must be an array");
101
+ const seen = new Set();
102
+ for (const [i, row] of doc.deployments.entries()) {
103
+ if (!isPlainObject(row)) throw invalid(file, `deployments[${i}] must be an object`);
104
+ if (typeof row.path !== "string" || !isAbsolute(row.path)) throw invalid(file, `deployments[${i}].path must be an absolute path`);
105
+ if (seen.has(row.path)) throw invalid(file, `${row.path} is listed twice`);
106
+ if (typeof row.addedAt !== "string") throw invalid(file, `deployments[${i}].addedAt must be a string`);
107
+ if (!DEPLOYMENT_VIA.includes(row.via)) throw invalid(file, `deployments[${i}].via must be one of ${DEPLOYMENT_VIA.join(", ")}`);
108
+ seen.add(row.path);
109
+ }
110
+ if (doc.imports === undefined) doc.imports = {};
111
+ if (!isPlainObject(doc.imports)) throw invalid(file, "imports must be an object");
112
+ for (const [k, v] of Object.entries(doc.imports)) if (typeof v !== "string") throw invalid(file, `imports.${k} must be a string`);
113
+ return doc;
114
+ }
115
+
116
+ function writeDocument(doc) {
117
+ const file = deploymentsFile();
118
+ const text = JSON.stringify(doc, null, 2) + "\n";
119
+ // Never write what the readers would refuse: the list stays as it was.
120
+ const bytes = Buffer.byteLength(text);
121
+ if (bytes > DEPLOYMENTS_FILE_BUDGET) throw writeFailed(file, `it would be ${bytes} bytes, over 1 MiB`);
122
+ try {
123
+ mkdirSync(deploymentsConfigDir(), { recursive: true, mode: 0o700 });
124
+ writeFileAtomic(file, text, { mode: 0o600 });
125
+ } catch (e) { throw writeFailed(file, e); }
126
+ }
127
+
128
+ /** One read-modify-write: under the lock, over the file as it is now, with the first-use `~/Agents`
129
+ * import done first; written once, only when something changed. `change(doc, now)` mutates `doc`
130
+ * and returns what the caller answers. `wait`: how long the lock may be waited for. */
131
+ function updateDeployments(change, { wait = LOCK_WAIT_MS } = {}) {
132
+ const file = deploymentsFile(), lock = deploymentsLock();
133
+ // The directory is created private before withDirLock would create it with the default mode.
134
+ try { mkdirSync(deploymentsConfigDir(), { recursive: true, mode: 0o700 }); } catch (e) { throw writeFailed(file, e); }
135
+ try {
136
+ return withDirLock(lock, "this computer's deployments list", () => {
137
+ const doc = readDeploymentsDocument();
138
+ const before = JSON.stringify(doc);
139
+ const now = new Date().toISOString();
140
+ importAgentsDir(doc, now);
141
+ const out = change(doc, now);
142
+ if (JSON.stringify(doc) !== before) writeDocument(doc);
143
+ return out;
144
+ }, { retryMs: wait, busy: (why) => deploymentsError("E_DEPLOYMENTS_BUSY", `this computer's deployments list is locked (${why}); if no oats process is changing it, remove ${lock} and retry; nothing was changed`, { file, lock }) });
145
+ } catch (e) {
146
+ if (typeof e?.code === "string" && e.code.startsWith("E_")) throw e;
147
+ // The lock directory itself could not be made or written: the list was not touched.
148
+ if (typeof e?.code === "string") throw writeFailed(file, e);
149
+ throw e;
150
+ }
151
+ }
152
+
153
+ // ---------------------------------------------------------------- rows
154
+
155
+ /** A deployment's state, from existence checks only: `ok` (a regular, non-link oats-local.yaml, the
156
+ * rule of packages/client/workspace-admission.mjs), `missing` (the path is gone, or on a volume
157
+ * that is not mounted), `not-a-deployment` (it exists, with no such file), `unreadable` (the check
158
+ * failed, e.g. EACCES). */
159
+ export function deploymentState(path) {
160
+ try { statSync(path); }
161
+ catch (e) { return e.code === "ENOENT" ? "missing" : e.code === "ENOTDIR" ? "not-a-deployment" : "unreadable"; }
162
+ try {
163
+ const st = lstatSync(join(path, "oats-local.yaml"));
164
+ return st.isFile() ? "ok" : "not-a-deployment";
165
+ } catch (e) { return e.code === "ENOENT" || e.code === "ENOTDIR" ? "not-a-deployment" : "unreadable"; }
166
+ }
167
+
168
+ /** A path as the list stores it: absolute, its spelling on disk (realpath of what exists, so a link
169
+ * or another letter case on a case-insensitive filesystem is one row), then the deployment's
170
+ * primary checkout when it sits in a linked Git worktree, a worktree's root included
171
+ * (canonicalDeploymentPath `self`: probed from the directory itself, never through a child). */
172
+ export function canonicalListPath(p) {
173
+ return canonicalDeploymentPath(canonicalHomePath(resolve(p)), { self: true });
174
+ }
175
+ /** canonicalListPath, or the realpath'd form when Git cannot say (a saved path a migration keeps). */
176
+ function canonicalOrReal(p) {
177
+ try { return canonicalListPath(p); } catch { return canonicalHomePath(resolve(p)); }
178
+ }
179
+
180
+ const rowOf = (doc, path) => doc.deployments.find((r) => r.path === path);
181
+ const live = (row) => row && row.removed !== true;
182
+
183
+ /** Add `path` (canonical) to `doc`. An explicit add clears a tombstone; an automatic one (`revive`
184
+ * false: the imports, the auto-add) skips a tombstoned path. → whether a row joined. */
185
+ function addRow(doc, path, via, now, { revive }) {
186
+ const row = rowOf(doc, path);
187
+ if (live(row)) return false;
188
+ if (row) {
189
+ if (!revive) return false;
190
+ delete row.removed; delete row.removedAt;
191
+ Object.assign(row, { addedAt: now, via });
192
+ return true;
193
+ }
194
+ doc.deployments.push({ path, addedAt: now, via });
195
+ return true;
196
+ }
197
+
198
+ /** The first-use import of `$HOME/Agents`, inside the caller's lock: every directory directly inside
199
+ * it (at most AGENTS_DIR_IMPORT_LIMIT entries read, no link followed) that holds a regular
200
+ * `oats-local.yaml`. The marker is set even when the directory is missing, a link or empty. One
201
+ * that cannot be read is E_DEPLOYMENTS_IMPORT, and the caller writes nothing: an import that did
202
+ * not run is never marked. An entry that cannot be checked is not a deployment to import. */
203
+ function importAgentsDir(doc, now) {
204
+ if (Object.hasOwn(doc.imports, "agents-dir")) return;
205
+ const dir = agentsDir();
206
+ const unreadable = (e) => deploymentsError("E_DEPLOYMENTS_IMPORT",
207
+ `cannot read ${dir} to import its deployments (${e?.message ?? e}); make it readable, or move it aside, and retry; nothing was changed`, { dir, ...(e?.code ? { cause: { code: e.code } } : {}) });
208
+ let st = null;
209
+ try { st = lstatSync(dir); } catch (e) { if (e.code !== "ENOENT" && e.code !== "ENOTDIR") throw unreadable(e); }
210
+ if (st?.isDirectory()) {
211
+ let handle;
212
+ try {
213
+ handle = opendirSync(dir);
214
+ for (let read = 0; read < AGENTS_DIR_IMPORT_LIMIT; read++) {
215
+ const entry = handle.readSync();
216
+ if (!entry) break;
217
+ if (!entry.isDirectory()) continue; // a link is not followed
218
+ const path = join(dir, entry.name);
219
+ if (deploymentState(path) === "ok") addRow(doc, canonicalOrReal(path), "import:agents-dir", now, { revive: false });
220
+ }
221
+ } catch (e) { throw unreadable(e); }
222
+ finally { if (handle) try { handle.closeSync(); } catch { /* closed */ } }
223
+ }
224
+ doc.imports["agents-dir"] = now;
225
+ }
226
+
227
+ // ---------------------------------------------------------------- commands
228
+
229
+ /** The import has run once, and nothing is written when it has: → the stored document. */
230
+ function importedDocument() {
231
+ const doc = readDeploymentsDocument();
232
+ if (Object.hasOwn(doc.imports, "agents-dir")) return doc;
233
+ return updateDeployments((d) => d);
234
+ }
235
+
236
+ /** `oats deployments [list] --json`: the live rows, sorted by path, each with its state. */
237
+ export function listDeployments() {
238
+ const doc = importedDocument();
239
+ const deployments = doc.deployments.filter(live)
240
+ .map((r) => ({ path: r.path, name: basename(r.path) || r.path, state: deploymentState(r.path), addedAt: r.addedAt, via: r.via }))
241
+ .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
242
+ return { deploymentsApi: DEPLOYMENTS_API, file: deploymentsFile(), deployments, imports: doc.imports };
243
+ }
244
+
245
+ /** The deployment at or above `dir`: the first directory walking up whose oats-local.yaml is a
246
+ * regular file, not a link (the rule a client admits a deployment by, and the list's `ok`), or
247
+ * null. Anything else of that name (a directory, a link) is passed over (awebai/oats#1397). */
248
+ export function deploymentAtOrAbove(dir) {
249
+ for (let d = resolve(dir); ; d = dirname(d)) {
250
+ try { if (lstatSync(join(d, "oats-local.yaml")).isFile()) return d; } catch { /* not here */ }
251
+ if (dirname(d) === d) return null;
252
+ }
253
+ }
254
+
255
+ /** `oats deployments add`, and onboard's add: list the deployment directory `dir`; a tombstone is
256
+ * cleared. → `{ path, added }` (added false: it was listed already, and nothing changed). */
257
+ export function addDeployment(dir, { via = "cli" } = {}) {
258
+ if (!DEPLOYMENT_VIA.includes(via)) throw deploymentsError("E_BAD_ARGS", `via must be one of ${DEPLOYMENT_VIA.join(", ")}`);
259
+ const path = canonicalListPath(dir);
260
+ return updateDeployments((doc, now) => ({ path, added: addRow(doc, path, via, now, { revive: true }) }));
261
+ }
262
+
263
+ /** `oats deployments remove <path>`: the row whose stored path is `<path>` resolved (or its
264
+ * canonical spelling), not walked up, so a stale row can go. It becomes a tombstone; nothing on
265
+ * disk is touched. → `{ path, removed }`. */
266
+ export function removeDeployment(given) {
267
+ const resolved = resolve(given);
268
+ const candidates = [...new Set([resolved, canonicalOrReal(resolved)])];
269
+ return updateDeployments((doc, now) => {
270
+ const row = candidates.map((p) => rowOf(doc, p)).find(live);
271
+ if (!row) return { path: resolved, removed: false };
272
+ Object.assign(row, { removed: true, removedAt: now });
273
+ return { path: row.path, removed: true };
274
+ });
275
+ }
276
+
277
+ /** `oats deployments import --from desktop <path>...`: the Desktop's own lists, once. The first run
278
+ * adds every path given, whatever its state, and sets `imports.desktop`, in one write; every later
279
+ * run changes nothing. A tombstoned path is not listed again. → `{ imported, at, added? }`. */
280
+ export function importDesktopDeployments(paths) {
281
+ const relative = paths.find((p) => typeof p !== "string" || !isAbsolute(p));
282
+ if (relative !== undefined) throw deploymentsError("E_BAD_ARGS", `oats deployments import takes absolute paths only, got ${JSON.stringify(relative)}; nothing was changed`);
283
+ const canonical = [...new Set(paths.map(canonicalOrReal))];
284
+ return updateDeployments((doc, now) => {
285
+ if (Object.hasOwn(doc.imports, "desktop")) return { imported: false, at: doc.imports.desktop };
286
+ const added = canonical.filter((p) => addRow(doc, p, "import:desktop", now, { revive: false }));
287
+ doc.imports.desktop = now;
288
+ return { imported: true, at: now, added };
289
+ });
290
+ }
291
+
292
+ /** Whether `dir` sits in a Git work tree whose `.git` is a file (a linked worktree, or a
293
+ * submodule): the nearest `.git` at or above it, from lstat alone. */
294
+ function inGitFileWorkTree(dir) {
295
+ for (let d = dir; ; d = dirname(d)) {
296
+ try { return lstatSync(join(d, ".git")).isFile(); } catch { /* not here */ }
297
+ if (dirname(d) === d) return false;
298
+ }
299
+ }
300
+
301
+ /** The temporary directories, as the auto-add knows them (awebai/oats#1397): os.tmpdir(), /tmp,
302
+ * /private/tmp and /var/folders (macOS's per-user ones), each by its realpath. */
303
+ export const TEMPORARY_DIRECTORIES = Object.freeze(["/tmp", "/private/tmp", "/var/folders"]);
304
+ /** Whether the real path `real` is one of the temporary directories or under one. */
305
+ export function underTemporaryDirectory(real) {
306
+ return [tmpdir(), ...TEMPORARY_DIRECTORIES].some((dir) => {
307
+ const top = canonicalHomePath(dir);
308
+ return dirname(top) !== top && (real === top || real.startsWith(top + sep)); // a TMPDIR of / is not taken
309
+ });
310
+ }
311
+
312
+ /** The auto-add of awebai/oats#1390 (amendment and its performance budget): `root`, the deployment
313
+ * directory the command itself resolved (`canonical`: the root ensureRoot canonicalized), is
314
+ * listed when it is not. A listed deployment (live or tombstoned) costs one lock-free bounded read
315
+ * of the list, compared with `root`: no lock, no write, no process, no realpath. Past that:
316
+ * - a root that is only spelled (loadLocal's) and sits in a linked worktree or a submodule is left
317
+ * to the commands that resolve its canonical root, from lstat alone: its stored path is the
318
+ * primary checkout's, which only Git can tell;
319
+ * - another spelling of a listed deployment (a link, /var for /private/var) costs a realpath;
320
+ * - an unlisted root whose realpath is under a temporary directory is never listed by it
321
+ * (awebai/oats#1397): test fixtures live there, and would stay in the list as `missing`. An
322
+ * explicit add, onboard and the imports still list such a root;
323
+ * - only an unlisted deployment is canonicalized (a Git probe) and tries the lock once (no wait:
324
+ * busy skips, the next command tries again) to add it `via: cli`.
325
+ * Best effort and silent: it never throws or prints. → `"listed" | "added" | "skipped"`. */
326
+ export function listResolved(root, { canonical = false } = {}) {
327
+ try {
328
+ const doc = readDeploymentsDocument();
329
+ const known = (p) => doc.deployments.some((r) => r.path === p);
330
+ if (known(root)) return "listed";
331
+ try { if (!lstatSync(join(root, "oats-local.yaml")).isFile()) return "skipped"; } catch { return "skipped"; }
332
+ if (!canonical && inGitFileWorkTree(root)) return "skipped";
333
+ const real = canonicalHomePath(root);
334
+ if (known(real)) return "listed";
335
+ if (!canonical && real !== root && inGitFileWorkTree(real)) return "skipped";
336
+ if (underTemporaryDirectory(real)) return "skipped";
337
+ const path = canonicalListPath(root);
338
+ if (known(path)) return "listed";
339
+ return updateDeployments((d, now) => (addRow(d, path, "cli", now, { revive: false }) ? "added" : "listed"), { wait: 0 });
340
+ } catch { return "skipped"; }
341
+ }
@@ -0,0 +1,37 @@
1
+ /** lib/resolved-deployment.mjs — the deployment a command resolved, for this computer's deployments
2
+ * list (awebai/oats#1390; lib/deployments.mjs listResolved).
3
+ *
4
+ * The resolvers report the deployment directory they found: `loadLocal` (lib/workspace.mjs) the
5
+ * directory of the oats-local.yaml its walk up found, as spelled; `ensureRoot` (lib/core.mjs) the
6
+ * directory of the canonical agents root, `canonical`. The observer is called once, when the
7
+ * process exits, with the root the command settled on: the first canonical one reported, else the
8
+ * first one, and whether it is canonical. So a command that resolves its canonical root is compared
9
+ * with that root, never with an earlier spelling of the same deployment. Nothing happens until the
10
+ * CLI sets an observer for this process (the commands in its one table): library callers and tests
11
+ * are unaffected unless they opt in. The observer never throws into the command, nor changes its
12
+ * exit status. Dependency-free.
13
+ */
14
+ let observer = null;
15
+ const reported = { canonical: null, spelled: null };
16
+
17
+ /** Observe the deployment this process resolves; called once, at exit. */
18
+ export function observeResolvedDeployment(fn) {
19
+ if (!observer) process.once("exit", settleResolvedDeployment);
20
+ observer = fn;
21
+ }
22
+
23
+ /** A resolver found the deployment directory `dir` (`canonical`: its canonical spelling). */
24
+ export function resolvedDeployment(dir, { canonical = false } = {}) {
25
+ if (!observer) return;
26
+ if (canonical) reported.canonical ??= dir;
27
+ else reported.spelled ??= dir;
28
+ }
29
+
30
+ /** Call the observer with the settled root, once (the exit handler; exported for tests). */
31
+ export function settleResolvedDeployment() {
32
+ const fn = observer, dir = reported.canonical ?? reported.spelled, canonical = reported.canonical !== null;
33
+ observer = null;
34
+ reported.canonical = reported.spelled = null;
35
+ if (!fn || !dir) return;
36
+ try { fn(dir, { canonical }); } catch { /* the observer's failure is never the command's */ }
37
+ }
package/lib/workspace.mjs CHANGED
@@ -13,6 +13,7 @@
13
13
  import { readFileSync, existsSync } from "node:fs";
14
14
  import { dirname, join, resolve } from "node:path";
15
15
  import { recordLocalInput } from "./local-inputs.mjs";
16
+ import { resolvedDeployment } from "./resolved-deployment.mjs";
16
17
  import { parseConfigData } from "./config-data.mjs";
17
18
  import { oatsError } from "./errors.mjs";
18
19
  import * as defaultRemote from "./remote.mjs";
@@ -431,6 +432,7 @@ export function loadLocal(dir) {
431
432
  else {
432
433
  if (legacy.length) throw fail("E_CONFIG_BROKEN", `${legacy.join(", ")}: ${LEGACY_CONFIG_MIGRATION}`, { dir: resolve(dir), deployment: current, files: legacy, reason: "legacy-config" });
433
434
  const origin = { kind: "local", path: candidate };
435
+ resolvedDeployment(current);
434
436
  const bytes = readFileSync(candidate);
435
437
  recordLocalInput(candidate, bytes);
436
438
  const read = readDeclaration("local", bytes, origin);
@@ -8,7 +8,7 @@
8
8
  },
9
9
  "oats.aweb": {
10
10
  "url": "https://github.com/awebai/oats-aweb.git",
11
- "ref": "v1.29.0",
11
+ "ref": "v1.30.0",
12
12
  "path": "oats-package"
13
13
  },
14
14
  "oats.jira": {
@@ -43,7 +43,7 @@
43
43
  },
44
44
  "oats.framework": {
45
45
  "url": "https://github.com/awebai/oats.git",
46
- "ref": "oats-framework/v1.13.3",
46
+ "ref": "oats-framework/v1.13.4",
47
47
  "path": "oats-package"
48
48
  }
49
49
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.64.0",
3
+ "version": "0.66.0",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -13,7 +13,7 @@
13
13
  // Every candidate is canonicalized to an absolute executable and accepted
14
14
  // ONLY if executable and `<bin> version --json` returns the v1 probe:
15
15
  // {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
16
- // Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.65.0 (the band is
16
+ // Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.67.0 (the band is
17
17
  // spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
18
18
  // API version — not source adjacency — is authoritative.
19
19
  //
@@ -52,7 +52,7 @@ export const DESKTOP_API = 1;
52
52
  // carry a `description` for every kind and `<kind> update <id> --description`
53
53
  // sets one (feature `automation-descriptions`, which gates the Desktop's
54
54
  // summary writes). The Desktop v1 surface is otherwise unchanged.
55
- export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 65, 0] };
55
+ export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 67, 0] };
56
56
  /** The band as humans read it — derived, never hand-spelled, so the probe
57
57
  * rejection reason, the backend's /api status and the degradation card can
58
58
  * never disagree with the numbers actually enforced above. */