@awebai/oats 0.69.20 → 0.69.22

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 (53) hide show
  1. package/bin/oats.mjs +26 -3
  2. package/docs/capabilities.md +1 -1
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/container.md +311 -4
  5. package/docs/design/2026-11-18-kernel-test-ownership.md +82 -0
  6. package/docs/design/2026-11-19-aweb-suite-retirement.md +123 -0
  7. package/docs/desktop-cli-api.md +80 -0
  8. package/docs/desktop.md +404 -177
  9. package/docs/implementation.md +15 -2
  10. package/docs/integrations.md +2 -2
  11. package/docs/knowledge-capability-authoring.md +1 -1
  12. package/docs/official-catalog.md +44 -1
  13. package/docs/packages.md +2 -2
  14. package/docs/release-lane.md +8 -6
  15. package/docs/release-notes/v0.69.21.md +155 -0
  16. package/docs/release-notes/v0.69.22.md +221 -0
  17. package/docs/servers.md +5 -1
  18. package/docs/souls-and-instances.md +11 -0
  19. package/docs/tui.md +44 -4
  20. package/docs/upgrading.md +16 -5
  21. package/lib/capability-contract.mjs +2 -2
  22. package/lib/command-flags.mjs +1 -0
  23. package/lib/core.mjs +5 -3
  24. package/lib/instance-inspect.mjs +3 -0
  25. package/lib/instance-lifecycle.mjs +16 -0
  26. package/lib/instance-listing.mjs +8 -4
  27. package/lib/instance-pin.mjs +59 -0
  28. package/lib/kernel-features.mjs +1 -1
  29. package/lib/servers.mjs +8 -3
  30. package/package-catalog.json +1 -1
  31. package/package.json +1 -1
  32. package/packages/client/above-tested.mjs +3 -2
  33. package/packages/client/capability-list.mjs +69 -0
  34. package/packages/client/capability-origin.mjs +54 -0
  35. package/packages/client/cli-adapter.mjs +9 -1
  36. package/packages/client/deployment-data.mjs +3 -0
  37. package/packages/client/deployment-panel.mjs +2 -0
  38. package/packages/client/home-board.mjs +50 -0
  39. package/packages/client/instance-pin.mjs +28 -0
  40. package/packages/client/instance-record-outcome.mjs +31 -0
  41. package/packages/client/instance-tree.mjs +62 -20
  42. package/packages/client/keymap.mjs +11 -3
  43. package/packages/client/remote-roster.mjs +8 -1
  44. package/packages/client/roster-row-facts.mjs +50 -0
  45. package/packages/client/roster-sections.mjs +10 -7
  46. package/packages/client/soul-role.mjs +44 -0
  47. package/packages/client/waiting-on-you.mjs +10 -0
  48. package/packages/tui/lib/actions.mjs +11 -4
  49. package/packages/tui/lib/client.mjs +3 -1
  50. package/packages/tui/lib/main.mjs +16 -2
  51. package/packages/tui/lib/model.mjs +48 -5
  52. package/packages/tui/lib/store.mjs +28 -2
  53. package/skills/oats-getting-started/SKILL.md +283 -30
package/docs/tui.md CHANGED
@@ -182,7 +182,9 @@ while a terminal is open); under 80 columns it has the whole width.
182
182
  place when it gains or loses one. Under one parent, the instances that do
183
183
  its work (the kernel's `sameWork`, from an OATS with `instance-same-work`)
184
184
  come first, then the others, each part newest first, as the Desktop lists
185
- them. An empty row stands between each run
185
+ them. Pinned instances come before all of these, at every level, and an
186
+ instance with a pinned one below it counts as pinned
187
+ ([Pinning](#pinning)). An empty row stands between each run
186
188
  of instances related to no other and the group before or after it. The
187
189
  indent alone says which instance is under which: no mark is drawn for
188
190
  it. A row whose instances are folded away (`h`) says how many after its
@@ -744,9 +746,14 @@ The panel can be split in two **groups**, side by side or one above the
744
746
  other. Each group is a panel of [tabs](#tabs) of its own: a tab bar, a shown
745
747
  tab and the marks of its hidden ones.
746
748
 
747
- - **Splitting.** The leader then `|` splits the panel side by side, and the
748
- leader then `-` one above the other; in the Instances view `|` and `-`
749
- do the same without the leader. The tabs open stay in the first group
749
+ - **The list out of the way.** The leader then `b` gives the shown terminal the
750
+ whole screen with the focus, and again gives the list back with the focus (the
751
+ Desktop's `b` hides its sidebar; the list is the TUI's). With no terminal shown
752
+ it does nothing.
753
+ - **Splitting.** The leader then `|` (or `h`) splits the panel side by side, and the
754
+ leader then `-` (or `v`) one above the other; in the Instances view `|` and `-`
755
+ do the same without the leader. (`h` and `v` are Herdr's letters, shared with the
756
+ Desktop since its UI rework.) The tabs open stay in the first group
750
757
  (left, or top). The second group starts empty and is the focused group.
751
758
  - A split needs a tab open, and none starting.
752
759
  - **There are at most two groups.** With two, the split keys do nothing,
@@ -1301,6 +1308,38 @@ The exit status never depends on it.
1301
1308
  there can leave `.oats-stop-pending.json` in the agent's home, and then
1302
1309
  the agent can be started but not stopped while that file exists.
1303
1310
 
1311
+ ## Pinning
1312
+
1313
+ `p` pins the selected instance to the top of its machine's list, or unpins a
1314
+ pinned one. It runs `oats instance pin <name> on|off` at once, with no
1315
+ confirmation: a pin changes only the order, and `p` again undoes it. The line
1316
+ under the sidebar's title says `Pinning <name>…`, then the result, and the
1317
+ list is read again, so the row moves.
1318
+
1319
+ - **The order** is the Desktop's, from the same code. Pinned instances come
1320
+ first at every level: the groups of a machine's list, the instances of a
1321
+ group, and the children of one parent. An instance counts as pinned when
1322
+ it or any instance below it is, so pinning a child lifts its whole group,
1323
+ and the path down to it rises among its siblings. Among pinned instances,
1324
+ and among the others, the order is spawn time, newest first. Under one
1325
+ parent, the instances that do its work still come first. A pinned
1326
+ background instance leads the Background section. A filter never
1327
+ reorders the list. The palette lists the instances you opened most
1328
+ recently first, as before, and the others in this order.
1329
+ - **Shared.** The pin is kept in the instance's home, so everyone who views
1330
+ that machine sees it, in the TUI, the Desktop and another machine's view.
1331
+ There is no pin of your own.
1332
+ - **When `p` does nothing**, the line says why: this OATS doesn't list the
1333
+ `instance-pin` feature (then `oats instance pin <name> on|off` needs a
1334
+ newer OATS too), the instance is held by a spawn or a retire, or its pin
1335
+ is still changing. For an instance on another machine whose OATS doesn't
1336
+ list the feature, the kernel refuses before it sends anything, and the
1337
+ line gives its words.
1338
+ - **The key.** `p` is a default key from this version on. A `tui.json` that
1339
+ gives `p` to another action is refused at the start, with a line that
1340
+ names the key and both actions: move that action to another key, or give
1341
+ `pin` another key (or none) in `tui.json`.
1342
+
1304
1343
  ## Resuming lost sessions
1305
1344
 
1306
1345
  After a shutdown, a reboot or a crash, the instances that were running have
@@ -1472,6 +1511,7 @@ that kind.
1472
1511
  | close the empty group | – | – | – | – | – | `x` |
1473
1512
  | stop, restart, start, retire | `X`, `R`, `S`, `D` | – | – | – | – | `X`, `R`, `S`, `D` |
1474
1513
  | spawn another of the soul | `N` | – | – | – | – | `N` |
1514
+ | pin or unpin (`oats tui` only; the Desktop's is in the row's menu) | `p` | – | – | – | – | – |
1475
1515
  | the Instances, Souls, Capabilities views | `1`, `2`, `3` | – | – | – | – | `1`, `2`, `3` |
1476
1516
  | the help | `?` | – | – | – | – | `?` |
1477
1517
  | the list | `Esc` | – | – | – | – | `Esc` |
package/docs/upgrading.md CHANGED
@@ -6,12 +6,12 @@ host that comes from it.
6
6
 
7
7
  ## Upgrading to the latest version
8
8
 
9
- The latest version is **OATS 0.69.20** ([release notes](release-notes/v0.69.20.md)).
10
- The 0.69.20 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: the
9
+ The latest version is **OATS 0.69.22** ([release notes](release-notes/v0.69.22.md)).
10
+ The 0.69.22 Desktop accepts OATS CLIs `>=0.26.0`, tested through 0.69: the
11
11
  Desktop and the CLI can be upgraded [in either order](#either-order-works).
12
12
 
13
13
  **First, read the `## Upgrade` section of every release after yours, up to
14
- 0.69.20,** in the [release notes](release-notes/): it says what to do before
14
+ 0.69.22,** in the [release notes](release-notes/): it says what to do before
15
15
  the CLI changes, and what else must change with it (the Desktop, another
16
16
  tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
17
17
  names the releases that ask for more than the steps below. `oats version`
@@ -20,8 +20,8 @@ prints the version you have.
20
20
  Then, on each host:
21
21
 
22
22
  ```sh
23
- # 0. where the Desktop is installed: Desktop 0.69.20, in either order
24
- npm install -g @awebai/oats@0.69.20 # 1. the CLI
23
+ # 0. where the Desktop is installed: Desktop 0.69.22, in either order
24
+ npm install -g @awebai/oats@0.69.22 # 1. the CLI
25
25
  oats update # 2. in each deployment: the plan, then it asks before it runs
26
26
  oats doctor # 3. in the same deployment
27
27
  ```
@@ -217,6 +217,17 @@ of the Desktop and the CLI, and an optional package pin. A change a script
217
217
  must follow is in its release's Upgrade section whether or not it is listed
218
218
  here.
219
219
 
220
+ - **[0.69.22](release-notes/v0.69.22.md#upgrade):** the catalog pins
221
+ oats.aweb 1.45.0; `setup --install-aw` installs the tested aw by default.
222
+ The Desktop's leader is Ctrl+Space (Ctrl+X a click away; a leader you set is
223
+ kept). A `tui.json` that binds `p` to another action moves it. Respawn
224
+ instances to take the new module.
225
+ - **[0.69.21](release-notes/v0.69.21.md#upgrade):** the catalog pins
226
+ oats.aweb 1.43.0. A deployment on a non-public aw registry runs
227
+ `oats aweb setup --registry <origin>`, reruns `oats aweb resident create`,
228
+ reinstalls the wake service and restarts its homes; exported aw selectors no
229
+ longer reach aw. Respawn grant seats whose resident or default team changed.
230
+ Respawn instances to take the new module.
220
231
  - **[0.69.20](release-notes/v0.69.20.md#upgrade):** the catalog pins
221
232
  oats.okf 6.2.0 and oats.framework 1.26.0. Retiring an old home whose
222
233
  recorded cleanup hooks cannot run is refused; clean up its external state,
@@ -181,13 +181,13 @@ const DISPOSABLE_HOME_PREFIX_RE = /^\.[A-Za-z0-9_][A-Za-z0-9._-]*-\*$/;
181
181
  * declaration may not cover them: these exact names, and every exact name
182
182
  * starting with one of these prefixes (the events log; the stop, restart and
183
183
  * start receipts and locks; the rollback marker; AGENTS.md backups; the
184
- * attachments directory; the instance colour, `.oats-color.json`; the background record, `.oats-background.json`; the same-work flag, `.oats-same-work.json`). This is the one list: a new kernel-written top-level
184
+ * attachments directory; the instance colour, `.oats-color.json`; the background record, `.oats-background.json`; the pin, `.oats-pinned.json`; the same-work flag, `.oats-same-work.json`). This is the one list: a new kernel-written top-level
185
185
  * home entry MUST be added here and to the `not` patterns of
186
186
  * `retirement.disposable.home` in docs/capability-manifest.schema.json. A
187
187
  * prefix declaration can reach none of them except through `.oats-`, which is
188
188
  * refused whole; `.oats-<provider>` as an exact name stays declarable. */
189
189
  const KERNEL_HOME_NAMES = new Set([".oats", ".agents", ".claude"]);
190
- const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments", ".oats-color", ".oats-background", ".oats-same-work"];
190
+ const KERNEL_HOME_NAME_PREFIXES = [".oats-events", ".oats-stop", ".oats-restart", ".oats-rollback", ".oats-agents-md", ".oats-start", ".oats-attachments", ".oats-color", ".oats-background", ".oats-pinned", ".oats-same-work"];
191
191
 
192
192
  /** Why `root` is not a declarable home entry: "shape" (not one hidden top-level
193
193
  * name or prefix), "kernel-owned", or undefined when it is sound. */
@@ -102,6 +102,7 @@ export const COMMAND_FLAGS = Object.freeze([
102
102
  { command: "instance color", operands: ["instance", "color"], required: 1, values: INSTANCE_RECORD_VALUES, switches: ["--clear", "--json"],
103
103
  usage: "usage: oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d> | --server <id>] [--json]" },
104
104
  onOff("background"),
105
+ onOff("pin"),
105
106
  onOff("same-work"),
106
107
  waiting("set"),
107
108
  waiting("clear"),
package/lib/core.mjs CHANGED
@@ -98,6 +98,7 @@ import { systemTool } from "./system-tools.mjs";
98
98
  import { SCOPE_ENV_NAMES, agentScope, agentScopeArgv, agentScopeUnit, creatorPlacement, serverScopePlan, serverScopeUnit, serverScopeWarning } from "./tmux-server-scope.mjs";
99
99
  import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
100
100
  import { readInstanceBackground, writeInstanceBackground } from "./instance-background.mjs";
101
+ import { PIN_FILE } from "./instance-pin.mjs";
101
102
  import { SAME_WORK_FILE, writeSameWork } from "./instance-same-work.mjs";
102
103
  import { HOST_STOP_REASON, readStartExited, sessionEndOf, START_EXITED_FILE, STOP_RECEIPT_FILE } from "./session-end.mjs";
103
104
  import { thisBoot } from "./session-seen.mjs";
@@ -5474,13 +5475,14 @@ function retireGitProbe(repo, args, { encoding } = {}) {
5474
5475
  * as its own (`retirement.disposable.home`: KERNEL_HOME_NAMES and
5475
5476
  * KERNEL_HOME_NAME_PREFIXES in lib/capability-contract.mjs, and the schema). */
5476
5477
  // `.oats-color.json` (feature instance-color) and `.oats-background.json` (feature instance-background) are
5477
- // presentation anyone may change at any time: never work.
5478
+ // presentation anyone may change at any time: never work. `.oats-pinned.json` (feature instance-pin) is
5479
+ // presentation of the same kind.
5478
5480
  // `.oats-same-work.json` (feature instance-same-work) is kernel presentation of the same kind.
5479
5481
  // `.oats-start-exited` (lib/session-end.mjs) is the window's record of how the harness ended: every
5480
5482
  // launched home whose harness ever ended holds it.
5481
5483
  // `.oats-start-env.json` and its key (lib/start-env.mjs) are written at every start that renders a
5482
5484
  // recipe, after the spawn's baseline: every launched home holds them.
5483
- const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json", ".oats-color.json", ".oats-background.json", SAME_WORK_FILE, START_EXITED_FILE, START_ENV_FILE, START_ENV_KEY_FILE]);
5485
+ const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json", ".oats-color.json", ".oats-background.json", PIN_FILE, SAME_WORK_FILE, START_EXITED_FILE, START_ENV_FILE, START_ENV_KEY_FILE]);
5484
5486
  // `instance.json.tmp-<pid>` is what a process killed between the two steps of writeJsonAtomic leaves
5485
5487
  // of the record: not a hidden name, so a capability cannot declare it (disposableHomeRootProblem).
5486
5488
  const KERNEL_HOME_RECEIPT_PATTERNS = [/^\.oats-stop-receipt\..+\.json$/, /^\.oats-agents-md\..+\.previous$/, /^instance\.json\.tmp-\d+$/, START_ENV_TMP, LAUNCH_ENV_HANDOFF];
@@ -9557,7 +9559,7 @@ const claimCommand = (action) => action === "resume" ? "oats session start --res
9557
9559
  /** What each verb that meets a held claim says it did not do: the words its refusals end with,
9558
9560
  * before any effect. After a takeover ended a dead holder's step, every verb says the same
9559
9561
  * (lib/errors.mjs nothingAfter). */
9560
- const CLAIM_NOTHING = { upgrade: "no modules were upgraded", retire: "nothing was done", stop: "nothing was stopped", resume: "nothing was started", start: "nothing was started", "worktree add": "no tree was made", "instance color": "the colour was not changed", "instance same-work": "the flag was not changed", "instance background": "the background was not changed" };
9562
+ const CLAIM_NOTHING = { upgrade: "no modules were upgraded", retire: "nothing was done", stop: "nothing was stopped", resume: "nothing was started", start: "nothing was started", "worktree add": "no tree was made", "instance color": "the colour was not changed", "instance same-work": "the flag was not changed", "instance background": "the background was not changed", "instance pin": "the pin was not changed" };
9561
9563
 
9562
9564
  /** The refusals of `arriving` ("retire", "stop", "upgrade", "resume", "start", or "worktree add", which
9563
9565
  * reads the claim and does not take it) of `name` (home `home`) that meets the lifecycle claim `lock`, as lib/claim.mjs asks
@@ -30,6 +30,7 @@ import { readLockIfPresent } from "./packages.mjs";
30
30
  import { composeSoulInstructions } from "./soul-composition.mjs";
31
31
  import { readInstanceColor } from "./instance-color.mjs";
32
32
  import { readInstanceBackground } from "./instance-background.mjs";
33
+ import { readInstancePin } from "./instance-pin.mjs";
33
34
  /** Bounds of a provider check's answer (bytes, nesting, entries), as the released binding wire set them. */
34
35
  const BINDING_LIMITS = Object.freeze({ maxBytes: 1024 * 1024, maxDepth: 32, maxEntries: 16384 });
35
36
  import { parseStrictJson } from "./canonical-json.mjs";
@@ -543,6 +544,8 @@ export function inspectDocument(t, { kernel }) {
543
544
  color: readInstanceColor(t.home),
544
545
  // Feature instance-background: `true` while the home holds a valid record, absent otherwise (as on a row).
545
546
  ...(readInstanceBackground(t.home) ? { background: true } : {}),
547
+ // Feature instance-pin: `true` while the home holds a valid pin, absent otherwise (as on a row).
548
+ ...(readInstancePin(t.home) ? { pinned: true } : {}),
546
549
  resolution: m.workspace?.resolution ?? null, soulDir: t.soul.soulDir, instructions: { ...readTextCapped(join(t.home, "AGENTS.md")), sources: m.instructions || [] } } : null,
547
550
  ...(m ? { identity: servedIdentityOf(m) } : {}),
548
551
  problems: [...t.soul.problems, ...(t.soul.copyError ? [t.soul.copyError] : []), ...(t.composedInstructionsProblem ? [t.composedInstructionsProblem] : []), ...(t.skillsProblems || []), ...(t.composedSkillsProblems || []), ...(t.discoveryError ? [t.discoveryError] : []),
@@ -20,6 +20,7 @@ import { afterFirstEffect, isAnswerCode, kernelCode, lifecycleBusy, oatsError, r
20
20
  import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
21
21
  import { INSTANCE_COLOR_API, INSTANCE_COLORS, writeInstanceColor } from "./instance-color.mjs";
22
22
  import { INSTANCE_BACKGROUND_API, writeInstanceBackground } from "./instance-background.mjs";
23
+ import { INSTANCE_PIN_API, writeInstancePin } from "./instance-pin.mjs";
23
24
  import { sameWorkOf, writeSameWork } from "./instance-same-work.mjs";
24
25
  import { resolveInstance } from "./instance-address.mjs";
25
26
  export { resolveInstance } from "./instance-address.mjs";
@@ -94,6 +95,21 @@ export function setInstanceBackground(ctx, root, name, { home, background }) {
94
95
  return { instanceBackgroundApi: INSTANCE_BACKGROUND_API, instance: name, home: me.home, background, changed };
95
96
  }
96
97
 
98
+ /** `oats instance pin <instance> on|off` (feature instance-pin): pin the home `name` resolves to at the top of
99
+ * its machine's list, or remove its pin, with the authority and the refusals of `instance background` above
100
+ * (setInstanceBackground), a stopped home included. The pin is the home's, so every viewer of the machine
101
+ * sees it. `pinned` is a boolean; the caller refused anything else.
102
+ * → `{ instancePinApi, instance, home, pinned, changed }`. */
103
+ export function setInstancePin(ctx, root, name, { home, pinned }) {
104
+ if (typeof pinned !== "boolean") throw oatsError("E_BAD_ARGS", "pinned must be on or off");
105
+ const me = resolveTarget(ctx, root, name, { home });
106
+ if (existsSync(join(me.home, ".oats-rollback-incomplete.json"))) throw oatsError("E_INSTANCE_RETIRING", `${me.home} is a quarantined home (or a spawn still in progress); finish its retirement (oats retire); the pin was not changed`);
107
+ if (existsSync(retirePendingMarkerPath(me.home))) throw oatsError("E_INSTANCE_RETIRING", `${name} is being retired; the pin was not changed`);
108
+ refuseBesideRetire("instance pin", me.home);
109
+ const { changed } = writeInstancePin(me.home, pinned);
110
+ return { instancePinApi: INSTANCE_PIN_API, instance: name, home: me.home, pinned, changed };
111
+ }
112
+
97
113
  /** `oats instance same-work <instance> on|off` (feature instance-same-work, awebai/oats#1577): bind the flag
98
114
  * of the home `name` resolves to to its recorded parent (`on`), or remove it (`off`). Addressed, and refused
99
115
  * beside a retire or in a quarantined home, exactly as setInstanceColor is. `on` needs a recorded
@@ -15,6 +15,7 @@ import { isInstant as isInstantString, readRetireState } from "./retire-state.mj
15
15
  import { herdrInstanceRemoved, oatsError } from "./errors.mjs";
16
16
  import { readInstanceColor } from "./instance-color.mjs";
17
17
  import { readInstanceBackground } from "./instance-background.mjs";
18
+ import { readInstancePin } from "./instance-pin.mjs";
18
19
  import { sameWorkOf } from "./instance-same-work.mjs";
19
20
  import { readSpawnedBy } from "./spawned-by.mjs";
20
21
  import { sessionEndOf } from "./session-end.mjs";
@@ -349,9 +350,10 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
349
350
  try { const s = instanceSessionTarget(home); if (!s.target) waitingOnYou = null; }
350
351
  catch { waitingOnYou = null; }
351
352
  }
352
- // `retire` is only ever the value read above, and `background` and `sameWork` the home's own records
353
- // (below): a record that carries any of them (hand-edited, or copied from a row) never stands in for it.
354
- const { retire: _recordedRetire, background: _recordedBackground, sameWork: _recordedSameWork, ...recorded } = meta;
353
+ // `retire` is only ever the value read above, and `background`, `pinned` and `sameWork` the home's own
354
+ // records (below): a record that carries any of them (hand-edited, or copied from a row) never stands in
355
+ // for it.
356
+ const { retire: _recordedRetire, background: _recordedBackground, pinned: _recordedPinned, sameWork: _recordedSameWork, ...recorded } = meta;
355
357
  // `spawnedBy` (feature spawn-attribution) is the record's own, read in place by its rule (lib/spawned-by.mjs):
356
358
  // a malformed one is null, and a home spawned before the feature has no key.
357
359
  if (Object.hasOwn(recorded, "spawnedBy")) recorded.spawnedBy = readSpawnedBy(recorded.spawnedBy);
@@ -361,10 +363,12 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
361
363
  const sessionEnd = record.state === "record" && liveness.running === false && meta.launched === true && !rollbackIncomplete && !spawnInProgress && !retirePending ? sessionEndOf(home, meta) : null;
362
364
  // Feature instance-color: the home's own colour record (lib/instance-color.mjs), a palette name or
363
365
  // null, after the record so that nothing in instance.json stands in for it.
366
+ // Feature instance-pin: `pinned: true` while the home holds a valid pin (lib/instance-pin.mjs), absent
367
+ // otherwise, never false.
364
368
  // Feature instance-same-work: `sameWork: true` only while the home's flag is bound to the parent
365
369
  // its readable record names (lib/instance-same-work.mjs sameWorkOf); absent otherwise, never false.
366
370
  const sameWork = record.state === "record" && sameWorkOf(home, meta.parentInstance);
367
- return { ...recorded, ...claims, home, instance: e.name, ...facts, color: readInstanceColor(home), ...(readInstanceBackground(home) ? { background: true } : {}), ...(sameWork ? { sameWork: true } : {}), ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(sessionEnd ? { sessionEnd } : {}), waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
371
+ return { ...recorded, ...claims, home, instance: e.name, ...facts, color: readInstanceColor(home), ...(readInstanceBackground(home) ? { background: true } : {}), ...(readInstancePin(home) ? { pinned: true } : {}), ...(sameWork ? { sameWork: true } : {}), ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(sessionEnd ? { sessionEnd } : {}), waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
368
372
 
369
373
  });
370
374
  };
@@ -0,0 +1,59 @@
1
+ /** Whether an instance is pinned (feature instance-pin): presentation like the colour
2
+ * (lib/instance-color.mjs) and background (lib/instance-background.mjs), never identity or policy. A client
3
+ * of the machine lists a pinned instance at the top of its list; nothing else about the instance changes.
4
+ * The pin is the home's, so it is shared: everyone who views that machine sees it. It is a home file of
5
+ * its own, `<home>/.oats-pinned.json`, so that a start or restart, which rewrites instance.json, can never
6
+ * lose it, and retire removes it with the home.
7
+ *
8
+ * The record is `{ pinnedApi: 1, at }` (present means pinned), written atomically (writeThroughPrivateFile)
9
+ * at mode 0600; absent means not pinned, and `off` removes the file. A reader takes a regular file only,
10
+ * without following a link, up to RECORD_MAX bytes: anything that is not a valid record reads as not
11
+ * pinned (false), never an error. Dependency-free: the status rows, inspect and the command all read and
12
+ * write it through here. */
13
+ import { lstatSync, rmSync } from "node:fs";
14
+ import { join } from "node:path";
15
+ import { readFileHead } from "./bounded-read.mjs";
16
+ import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
17
+
18
+ /** The record's own version, and the command answer's. */
19
+ export const PIN_API = 1;
20
+ export const INSTANCE_PIN_API = 1;
21
+ /** The home file, kernel-owned: in KERNEL_HOME_NAME_PREFIXES (lib/capability-contract.mjs), the retire
22
+ * fingerprint's receipts (lib/core.mjs KERNEL_HOME_RECEIPTS) and the manifest schema. */
23
+ export const PIN_FILE = ".oats-pinned.json";
24
+ /** A record larger than this is not one. */
25
+ export const RECORD_MAX = 4096;
26
+
27
+ /** Whether `home` records itself pinned: false for no file, not a regular file (a link is never followed),
28
+ * over RECORD_MAX bytes, unreadable, not a JSON object or another pinnedApi. Never throws. */
29
+ export function readInstancePin(home) {
30
+ try {
31
+ const { bytes, size } = readFileHead(join(home, PIN_FILE), RECORD_MAX + 1);
32
+ if (size > RECORD_MAX) return false;
33
+ const record = JSON.parse(bytes.toString("utf8"));
34
+ return !!record && typeof record === "object" && !Array.isArray(record) && record.pinnedApi === PIN_API;
35
+ } catch { return false; }
36
+ }
37
+
38
+ /** Pin `home` (`on` true), or remove its pin (`on` false). → `{ pinned, changed }`. A home already pinned is
39
+ * no change: nothing is written. `off` removes whatever stands at the name (a link or an invalid record
40
+ * included) and is a change only when the home read as pinned. The caller holds the right to change the
41
+ * home. */
42
+ export function writeInstancePin(home, on, { now = () => new Date() } = {}) {
43
+ const path = join(home, PIN_FILE);
44
+ const before = readInstancePin(home);
45
+ // What stands at the name, never followed: null for nothing. The name is kernel-owned, so a directory
46
+ // there is no one's work: `off` removes it, and `on` removes it before the record is renamed into place
47
+ // (a rename cannot replace a directory).
48
+ let standing = null;
49
+ try { standing = lstatSync(path); } catch (e) { if (e?.code !== "ENOENT") throw e; }
50
+ if (!on) {
51
+ if (standing) rmSync(path, { force: true, recursive: standing.isDirectory() });
52
+ return { pinned: false, changed: before };
53
+ }
54
+ if (before) return { pinned: true, changed: false };
55
+ if (standing?.isDirectory()) rmSync(path, { force: true, recursive: true });
56
+ const bytes = JSON.stringify({ pinnedApi: PIN_API, at: now().toISOString() }) + "\n";
57
+ writeThroughPrivateFile(path, `${path}.tmp-${process.pid}`, bytes, 0o600);
58
+ return { pinned: true, changed: true };
59
+ }
@@ -8,6 +8,6 @@ import { SESSION_RESUME_FEATURE } from "./session-resume-contract.mjs";
8
8
  /** `oats spawn --task-file -` reads the task from standard input: how a routed spawn's task reaches
9
9
  * its host (lib/servers.mjs routeCommand); a host that does not list this gets it as an argument. */
10
10
  export const SPAWN_TASK_STDIN_FEATURE = "spawn-task-stdin";
11
- export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-same-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution", "workspace-tasks-payload", "settings-committed-only", "schedule-host-register-only", SPAWN_TASK_STDIN_FEATURE]);
11
+ export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-pin", "instance-same-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution", "workspace-tasks-payload", "settings-committed-only", "schedule-host-register-only", SPAWN_TASK_STDIN_FEATURE]);
12
12
  /** The warm reader's protocol (`oats reader --stdio`, lib/reader.mjs): `readerApi` in the probe and in the reader's hello. */
13
13
  export const READER_API = 1;
package/lib/servers.mjs CHANGED
@@ -936,6 +936,8 @@ const HOST_SURFACES = {
936
936
  "instance color": { feature: "instance-color" },
937
937
  // Feature instance-background: the same (its answer's instanceBackgroundApi is not a probe key).
938
938
  "instance background": { feature: "instance-background" },
939
+ // Feature instance-pin: the feature alone, as instance background.
940
+ "instance pin": { feature: "instance-pin" },
939
941
  // Feature instance-same-work: the feature alone, as instance color.
940
942
  "instance same-work": { feature: "instance-same-work" },
941
943
  };
@@ -946,7 +948,7 @@ function requireSurface(remote, target, surface) {
946
948
  }
947
949
  }
948
950
 
949
- /** `readiness`, `instance events|git|diff|stop|color|background|same-work` and `retire --plan` on the
951
+ /** `readiness`, `instance events|git|diff|stop|color|background|pin|same-work` and `retire --plan` on the
950
952
  * host: the instance is addressed as every routed session command addresses
951
953
  * it (its name through a saved route or the host's roster, or an exact
952
954
  * --home), the scope is an explicit --dir on the host or the registered
@@ -955,7 +957,7 @@ function requireSurface(remote, target, surface) {
955
957
  function routeHostSurface(serverId, cmd, oatsArgs, io) {
956
958
  const key = cmd === "instance" ? `instance ${oatsArgs[0]}` : cmd === "retire" ? "retire plan" : cmd;
957
959
  const surface = HOST_SURFACES[key];
958
- if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff, stop, color, background and same-work only (not ${key})`);
960
+ if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff, stop, color, background, pin and same-work only (not ${key})`);
959
961
  const args = [...oatsArgs];
960
962
  const valueOf = (flag) => { const i = args.indexOf(flag); return i >= 0 && args[i + 1] !== undefined && !args[i + 1].startsWith("--") ? args[i + 1] : undefined; };
961
963
  const name = cmd === "readiness" ? undefined : args[cmd === "instance" ? 1 : 0];
@@ -1016,6 +1018,9 @@ const rowWaiting = (i) => (Object.hasOwn(i, "waitingOnYou") ? { waitingOnYou: re
1016
1018
  /** `background` (feature instance-background) only as `true`, relayed ONLY when the host's row says exactly
1017
1019
  * that: absent is the only reading of "not background", so any other value is dropped, never false. */
1018
1020
  const rowBackground = (i) => (i.background === true ? { background: true } : {});
1021
+ /** `pinned` (feature instance-pin) as `background`: relayed ONLY when the host's row says exactly `true`;
1022
+ * absent is the only reading of "not pinned", so any other value (`"true"`, `1`) is dropped, never false. */
1023
+ const rowPinned = (i) => (i.pinned === true ? { pinned: true } : {});
1019
1024
  /** `retire` (feature status-retire-state) as `waitingOnYou` is, relayed ONLY when the host's row has the
1020
1025
  * key: a host whose kernel predates the feature omits it, and its rows say nothing. Absent is the
1021
1026
  * only reading of "no retire", so a value the kernel's own read refuses is dropped, never null. */
@@ -1134,7 +1139,7 @@ export async function rosterGroups({ server, workspaceKeys, io = {} } = {}) {
1134
1139
  harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null,
1135
1140
  ...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
1136
1141
  running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
1137
- ...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowSameWork(i), ...rowSessionEnd(i),
1142
+ ...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowPinned(i), ...rowSameWork(i), ...rowSessionEnd(i),
1138
1143
  // Every row the host reports is addressed by its home, saved
1139
1144
  // route or not; savedRoute says only that it was spawned from here.
1140
1145
  retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, addressable: true, missingRemotely: false,
@@ -8,7 +8,7 @@
8
8
  },
9
9
  "oats.aweb": {
10
10
  "url": "https://github.com/awebai/oats-aweb.git",
11
- "ref": "v1.42.1",
11
+ "ref": "v1.45.0",
12
12
  "path": "oats-package"
13
13
  },
14
14
  "oats.jira": {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.69.20",
3
+ "version": "0.69.22",
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",
@@ -9,8 +9,8 @@
9
9
  Why these and not others: the four traced cases on #1879 (schedule edit at 0.40, Remove at 0.49 and
10
10
  0.53, the Stop outcome at 0.52) all sit where the Desktop words a consequence itself or writes a whole
11
11
  definition. What stays on is a read, a terminal, or a change fenced by the kernel's own answer: Spawn
12
- applies only the decision its preview showed (`--expect-decision`), and Start, Restart, colour and
13
- background report only an answer the Desktop reads in full (each fails closed on a shape it does not
12
+ applies only the decision its preview showed (`--expect-decision`), and Start, Restart, colour,
13
+ background and pin report only an answer the Desktop reads in full (each fails closed on a shape it does not
14
14
  know).
15
15
 
16
16
  Enforcement is not the renderer's. Every place an operation enters the backend asks
@@ -65,6 +65,7 @@ export const OPERATIONS = Object.freeze({
65
65
  // ── An instance's own record.
66
66
  'POST /api/instance-color': allowed("colour: one field of the instance's own record, the answer read in full"),
67
67
  'POST /api/instance-background': allowed("background: one field of the instance's own record, the answer read in full"),
68
+ 'POST /api/instance-pin': allowed("pin: one field of the instance's own record, the answer read in full"),
68
69
  // ── Reads.
69
70
  'POST /api/instance-git git': read('git'),
70
71
  'POST /api/instance-git diff': read('git'),
@@ -0,0 +1,69 @@
1
+ /** The workspace's capabilities as one flat list, as both clients draw it (the Desktop UI rework, slice 3b: "show
2
+ * core and other ones as really the same"). Core capabilities (a knowledge, messaging or tasks `layer`) come first
3
+ * in that order, then every other one by name. Each entry carries what its row says: its core slot, whether it
4
+ * is one of the workspace's defaults (`oats workspace status` `defaults`), and who made it (capability-origin.mjs).
5
+ * Nothing is inferred: a default is matched to a row only by the name and the source the kernel reports, and
6
+ * with no reported `defaults` no row is called a default. Pure and DOM-free. */
7
+ import { sameRepo } from './repo-moves.mjs';
8
+ import { memberNames, hostKeyOf, matchCapabilities } from './capability-rows.mjs';
9
+ import { capabilityOrigin } from './capability-origin.mjs';
10
+
11
+ /** The core slots, in the one order every surface shows them. */
12
+ export const CORE_LAYERS = Object.freeze(['knowledge', 'messaging', 'tasks']);
13
+
14
+ const record = v => !!v && typeof v === 'object' && !Array.isArray(v);
15
+ const text = v => typeof v === 'string' && v ? v : null;
16
+ const list = v => Array.isArray(v) ? v : [];
17
+
18
+ /** Whether a declared default (`{ name, from }`: `from` is "package", "here" or a member key) names this row. */
19
+ export function defaultNames(entry, row, hostKey = null) {
20
+ if (!record(entry) || entry.name !== row?.name) return false;
21
+ if (entry.from === 'package') return row.kind === 'package';
22
+ if (entry.from === 'here') return row.kind === 'member' && !!text(hostKey) && sameRepo(row.repoKey, hostKey);
23
+ if (text(entry.from)) return row.kind === 'member' && sameRepo(row.repoKey, entry.from);
24
+ return false;
25
+ }
26
+ /** The row's place in the workspace's defaults: 'on' (every soul starts with it), 'off' (the workspace turns it
27
+ * off), or null (not a default, or no defaults reported). A turned-off entry reports no source: it is matched by
28
+ * name. A slot default fills its core slot (`defaults.slots.<layer>`). */
29
+ export function defaultState(status, row) {
30
+ const defaults = status?.defaults;
31
+ if (!record(defaults) || !row) return null;
32
+ const hostKey = hostKeyOf(status);
33
+ for (const cap of list(defaults.capabilities)) {
34
+ if (!record(cap) || cap.name !== row.name) continue;
35
+ if (cap.off === true) return 'off';
36
+ if (defaultNames(cap, row, hostKey)) return 'on';
37
+ }
38
+ const slot = text(row.layer) && record(defaults.slots) ? defaults.slots[row.layer] : null;
39
+ return record(slot) && defaultNames(slot, row, hostKey) ? 'on' : null;
40
+ }
41
+ /** The rank of a row in the list: a core slot's index, else after every core one. */
42
+ const rank = row => { const at = CORE_LAYERS.indexOf(row?.layer); return at < 0 ? CORE_LAYERS.length : at; };
43
+
44
+ /** The list's entries, in drawn order: `{ row, core, default, origin }`. `core`: the row's core slot or null;
45
+ * `default`: defaultState; `origin`: capabilityOrigin. `query` narrows by name (matchCapabilities). */
46
+ export function capabilityList(rows, status, { query = '' } = {}) {
47
+ const names = memberNames(status);
48
+ return matchCapabilities(list(rows), query)
49
+ .map(row => ({ row, core: CORE_LAYERS.includes(row.layer) ? row.layer : null, default: defaultState(status, row), origin: capabilityOrigin(row, status, names) }))
50
+ .sort((a, b) => rank(a.row) - rank(b.row) || String(a.row.name).localeCompare(String(b.row.name)) || a.origin.by.localeCompare(b.origin.by));
51
+ }
52
+
53
+ /** What the list's lead sentence needs, from the reported defaults: null when the kernel reports none (no claim).
54
+ * `empty`: the workspace sets no default at all. `emptySlots`: the core slots no default fills (by a slot or a
55
+ * named capability of that layer), in CORE_LAYERS order. `unlisted`: the declared defaults no catalog row
56
+ * matches (`{ name, off }`), so the list cannot show them as rows; a turned-off one is unlisted when no row has
57
+ * its name. */
58
+ export function defaultsSummary(status, rows) {
59
+ const defaults = status?.defaults;
60
+ if (!record(defaults)) return null;
61
+ const hostKey = hostKeyOf(status), all = list(rows);
62
+ const slots = CORE_LAYERS.map(layer => [layer, record(defaults.slots) && record(defaults.slots[layer]) && text(defaults.slots[layer].name) ? defaults.slots[layer] : null]);
63
+ const caps = list(defaults.capabilities).filter(cap => record(cap) && text(cap.name));
64
+ const listed = entry => entry.off === true ? all.some(row => row?.name === entry.name) : all.some(row => defaultNames(entry, row, hostKey));
65
+ const filled = new Set(slots.filter(([, value]) => value).map(([layer]) => layer));
66
+ for (const cap of caps) if (cap.off !== true) for (const row of all) if (defaultNames(cap, row, hostKey) && CORE_LAYERS.includes(row.layer)) filled.add(row.layer);
67
+ const unlisted = [...slots.filter(([, value]) => value).map(([, value]) => value), ...caps].filter(entry => !listed(entry)).map(entry => ({ name: entry.name, off: entry.off === true }));
68
+ return { empty: !filled.size && !caps.length, emptySlots: CORE_LAYERS.filter(layer => !filled.has(layer)), unlisted };
69
+ }
@@ -0,0 +1,54 @@
1
+ /** Who made a capability, as both clients say it on a capability row (the Desktop UI rework, D24): "official"
2
+ * (a small ✓ whose words say which fact made it official: "Official: in the OATS catalog" or "Official: from the
3
+ * OATS repository") or "by <source>". The words say only what the rule shows: "verified" or "published by OATS" is a
4
+ * trust claim a client rule can't make (dec-feb06c322c75, "listed is not trusted"); a kernel fact for "official" is
5
+ * oats-project/oats#1981. Decided from facts the kernel
6
+ * already reports, never from a name (an `oats.` prefix proves nothing) and never from a new field:
7
+ *
8
+ * - a **package** capability is official when `oats workspace status` reports its package pinned from the
9
+ * catalog (`packages[].source` is `catalog:<id>`): only the reviewed official catalog makes a package
10
+ * pinnable by id (docs/packages.md, docs/official-catalog.md). Caveat: `OATS_PACKAGE_CATALOG` can point a kernel
11
+ * at another catalog file, and status does not say which one was read. An operator who points it elsewhere gets the
12
+ * ✓ for that catalog's packages: their choice (the effort's lead, 2026-11-19).
13
+ * A package pinned by `git:<repo>@<ref>` is "by <repo>", whatever its id;
14
+ * - a **member** capability is official when its repository is the OATS repository itself
15
+ * (github.com/oats-project/oats, or its old key github.com/awebai/oats: repo-moves.mjs);
16
+ * - anything else (another member, an external source, a package status does not list) is "by <source>".
17
+ *
18
+ * Pure and DOM-free; the words are ORIGIN_COPY so no client writes its own. */
19
+ import { sameRepo } from './repo-moves.mjs';
20
+ import { capabilitySource, memberNames } from './capability-rows.mjs';
21
+
22
+ /** The OATS repository's key (its moved spelling is the same repository: sameRepo). */
23
+ export const OATS_REPO_KEY = 'github.com/oats-project/oats';
24
+
25
+ export const ORIGIN_COPY = Object.freeze({
26
+ official: 'OATS',
27
+ // The mark's words per the fact that made it official (`reason`): its tooltip and its accessible name.
28
+ officialTitle: Object.freeze({ catalog: 'Official: in the OATS catalog', 'oats-repo': 'Official: from the OATS repository' }),
29
+ by: source => `by ${source}`,
30
+ });
31
+
32
+ const text = v => typeof v === 'string' && v ? v : null;
33
+ const list = v => Array.isArray(v) ? v : [];
34
+ /** `git:<repo>@<ref>` → the repository's last path segment, without `.git`; null for anything else. */
35
+ function gitRepoName(source) {
36
+ const m = /^git:(.+)@[^@]*$/.exec(source || '');
37
+ if (!m) return null;
38
+ return m[1].replace(/\.git$/, '').split(/[/:]/).filter(Boolean).pop() || null;
39
+ }
40
+
41
+ /** `{ official, by, reason }` for a catalog row (`oats capabilities`, or a soul's resolved capability in the same
42
+ * shape). `by` is the source as words ("OATS" when official); `reason` is the fact that decided it: 'catalog'
43
+ * (a package pinned from the catalog), 'oats-repo' (a member capability of the OATS repository), else null.
44
+ * `status`: workspace status (packages[] and members[]); `names`: memberNames(status) when the caller holds it. */
45
+ export function capabilityOrigin(row, status, names = memberNames(status)) {
46
+ if (row?.kind === 'package') {
47
+ const pkg = list(status?.packages).find(p => p?.id === row.package);
48
+ const source = text(pkg?.source);
49
+ if (source && source.startsWith('catalog:')) return { official: true, by: ORIGIN_COPY.official, reason: 'catalog' };
50
+ return { official: false, by: gitRepoName(source) || text(row.package) || text(row.name) || 'a package', reason: null };
51
+ }
52
+ if (row?.kind === 'member' && text(row.repoKey) && sameRepo(row.repoKey, OATS_REPO_KEY)) return { official: true, by: ORIGIN_COPY.official, reason: 'oats-repo' };
53
+ return { official: false, by: capabilitySource(row || {}, names).label, reason: null };
54
+ }
@@ -655,7 +655,7 @@ export function operationArgs(args) {
655
655
  }
656
656
  /** A verb that writes one field of an instance's own record: `oats instance <verb> <instance> <values…> --home <home>
657
657
  * (--dir <context> | --server <server>) --json`, addressed as `oats instance stop` is (lifecycle-cli.mjs: a routed
658
- * command never carries --dir). Shared by `instance color` and `instance background` (server/instance-record.mjs);
658
+ * command never carries --dir). Shared by `instance color`, `instance background` and `instance pin` (server/instance-record.mjs);
659
659
  * each checks its own value first. Anything out of shape is refused here and nothing runs. A read's deadline:
660
660
  * 30 s, 45 s routed. The envelope comes back as the kernel printed it; the caller decodes it. */
661
661
  function runInstanceRecord(bin, { instance, home, context, server }, verb, values, io) {
@@ -686,6 +686,14 @@ export async function cliInstanceBackground(bin, args, io = {}) {
686
686
  if (typeof background !== "boolean") return instanceRecordRefused();
687
687
  return runInstanceRecord(bin, args, "background", [background ? "on" : "off"], io);
688
688
  }
689
+ /** Whether an instance is pinned (feature instance-pin): `oats instance pin <instance> (on | off) …`
690
+ * (runInstanceRecord). `pinned` is a boolean; anything else is refused here and nothing runs. Over `--server`, a
691
+ * host without the feature refuses it (E_REMOTE_INCOMPATIBLE). */
692
+ export async function cliInstancePin(bin, args, io = {}) {
693
+ const { pinned } = args;
694
+ if (typeof pinned !== "boolean") return instanceRecordRefused();
695
+ return runInstanceRecord(bin, args, "pin", [pinned ? "on" : "off"], io);
696
+ }
689
697
 
690
698
  /** `maxAge` (feature observe-max-age) is inspect's alone; `features` is the probe's list and
691
699
  * gates the flags (also `instructions`, `skills` and `composedSkills`), so an undeclared kernel gets the flagless argv even when a value is given. */
@@ -227,6 +227,9 @@ export function deploymentStatusData(document, deployment) {
227
227
  // Feature instance-background (#1579): the row is placed in the Background section. Exactly true only; any
228
228
  // other value is dropped, never checked: the row stays in the main tree.
229
229
  if (own(instance, 'background') && instance.background === true) row.background = true;
230
+ // Feature instance-pin: the row is listed first in its machine's list (instance-tree.mjs rowPinned). Exactly
231
+ // true only; any other value is dropped, never checked: the row keeps the roster's order.
232
+ if (own(instance, 'pinned') && instance.pinned === true) row.pinned = true;
230
233
  // #802 (feature worktree-event): a spawn running its worktree hooks, verifiably alive. Boolean true only;
231
234
  // any other value is dropped, never checked: the row stays an ordinary one.
232
235
  if (own(instance, 'spawnInProgress') && instance.spawnInProgress === true) row.spawnInProgress = true;
@@ -139,6 +139,8 @@ export function panelInstance(i) {
139
139
  ...(instanceColor(i) !== null ? { color: instanceColor(i) } : {}),
140
140
  // Feature instance-background (#1579): exactly true, else absent (instance-tree.mjs backgroundPlacement).
141
141
  ...(i.background === true ? { background: true } : {}),
142
+ // Feature instance-pin: exactly true, else absent (instance-tree.mjs rowPinned).
143
+ ...(i.pinned === true ? { pinned: true } : {}),
142
144
  team: i.team || null,
143
145
  };
144
146
  }