@awebai/oats 0.69.21 → 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 (36) hide show
  1. package/docs/container.md +311 -4
  2. package/docs/design/2026-11-18-kernel-test-ownership.md +82 -0
  3. package/docs/design/2026-11-19-aweb-suite-retirement.md +123 -0
  4. package/docs/desktop.md +316 -130
  5. package/docs/implementation.md +14 -1
  6. package/docs/integrations.md +2 -2
  7. package/docs/knowledge-capability-authoring.md +1 -1
  8. package/docs/official-catalog.md +44 -1
  9. package/docs/packages.md +2 -2
  10. package/docs/release-lane.md +8 -6
  11. package/docs/release-notes/v0.69.22.md +221 -0
  12. package/docs/tui.md +44 -4
  13. package/docs/upgrading.md +10 -5
  14. package/package-catalog.json +1 -1
  15. package/package.json +1 -1
  16. package/packages/client/above-tested.mjs +3 -2
  17. package/packages/client/capability-list.mjs +69 -0
  18. package/packages/client/capability-origin.mjs +54 -0
  19. package/packages/client/cli-adapter.mjs +9 -1
  20. package/packages/client/deployment-data.mjs +3 -0
  21. package/packages/client/deployment-panel.mjs +2 -0
  22. package/packages/client/home-board.mjs +50 -0
  23. package/packages/client/instance-pin.mjs +28 -0
  24. package/packages/client/instance-record-outcome.mjs +31 -0
  25. package/packages/client/instance-tree.mjs +62 -20
  26. package/packages/client/keymap.mjs +11 -3
  27. package/packages/client/remote-roster.mjs +8 -1
  28. package/packages/client/roster-sections.mjs +10 -7
  29. package/packages/client/soul-role.mjs +44 -0
  30. package/packages/client/waiting-on-you.mjs +10 -0
  31. package/packages/tui/lib/actions.mjs +11 -4
  32. package/packages/tui/lib/client.mjs +3 -1
  33. package/packages/tui/lib/main.mjs +16 -2
  34. package/packages/tui/lib/model.mjs +48 -5
  35. package/packages/tui/lib/store.mjs +28 -2
  36. package/skills/oats-getting-started/SKILL.md +88 -18
@@ -12,7 +12,7 @@
12
12
  import { homedir } from "node:os";
13
13
  import { resolve } from "node:path";
14
14
  import { bindings } from "./actions.mjs";
15
- import { TERMS, capabilityCatalogKey, cliDeploymentList, deploymentsListSupported, createCapabilityCatalog, createLifecycleBoundary, createLifecycleConfirmation, createRetiresInFlight, createSoulCatalog, createSpawnApplyBoundary, createSpawnPreview, createSpawnTransaction, createResumeTrigger, displayLine, heldHome, pendingEntry, prepareRemoteTerm, runResumeSweep, sessionAttachArgv, soulCatalogKey, startInstance } from "./client.mjs";
15
+ import { TERMS, capabilityCatalogKey, cliDeploymentList, deploymentsListSupported, createCapabilityCatalog, createLifecycleBoundary, createLifecycleConfirmation, createRetiresInFlight, createSoulCatalog, createSpawnApplyBoundary, createSpawnPreview, createSpawnTransaction, createResumeTrigger, displayLine, heldHome, pendingEntry, prepareRemoteTerm, runResumeSweep, sessionAttachArgv, soulCatalogKey, startInstance, pinInstance } from "./client.mjs";
16
16
  import { loadConfig, loadKeys } from "./config.mjs";
17
17
  import { ACT_WORDS, LIST_WORDS, actContext, actCwd, listRowsOf, localDeployments, model, outcomeOf, reachedMachines, resumeObservation, roster, spawnContext } from "./model.mjs";
18
18
  import { createPanel, sweep } from "./panel.mjs";
@@ -100,7 +100,7 @@ function errorLines(error) {
100
100
  * chord family (lib/config.mjs), replaceable so no test reads a user's file. `createResumeTrigger`
101
101
  * is the shared trigger of the kernel's machine sweep (packages/client session-resume-trigger.mjs). */
102
102
  const EFFECTS = Object.freeze({ loadConfig, loadKeys, findDeployment, probeKernel, createReader, createIdentityReads, deploymentList: cliDeploymentList, startExec, admitDeployment, prepareRemoteTerm, createPanel, sweep,
103
- runDir: CHANGE_FILES.dir, removeDir: CHANGE_FILES.remove, realpath, tellable, startInstance, createLifecycleConfirmation, createLifecycleBoundary, createSoulCatalog,
103
+ runDir: CHANGE_FILES.dir, removeDir: CHANGE_FILES.remove, realpath, tellable, startInstance, pinInstance, createLifecycleConfirmation, createLifecycleBoundary, createSoulCatalog,
104
104
  createCapabilityCatalog, createSpawnPreview, createSpawnApplyBoundary, createSpawnTransaction, createResumeTrigger });
105
105
 
106
106
  /** The timers a run lends the shared spawn: the apply's deadline and its grace (the boundary's
@@ -487,6 +487,7 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
487
487
  if (effect.act) openConfirmation(effect.act);
488
488
  if (effect.call) callConfirmation(effect.call);
489
489
  if (effect.start) startAct(effect.start);
490
+ if (effect.pin) pinAct(effect.pin);
490
491
  if (effect.refresh) refresh(effect.refresh);
491
492
  if (effect.souls === "settle" && state.open !== null) settleSouls(state.open);
492
493
  if (effect.souls === "reread" && state.open !== null) rereadSouls(state.open);
@@ -601,6 +602,19 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
601
602
  .then(() => effects.startInstance(probe.cli, row, {}, { restart: verb === "restart", deployments: localDeployments(state, clock()), realpath: effects.realpath, localCwd: actCwd(state), exec, terms: TERMS, group: contextOf(row?.deployment?.id).workspace?.group }))
602
603
  .then((answer) => heard({ acted: { n, answer } }), () => heard({ acted: { n, answer: null } }));
603
604
  }
605
+ /** Pin or unpin the row the store decided on (feature instance-pin; lib/model.mjs pinDecision): the kernel's verb,
606
+ * through the shared pinInstance, on this machine with `--dir` its deployment, on another routed with `--server`,
607
+ * as a stop is. It is a change (reader.changeExec): never ended by the TUI, and named on the way out while it
608
+ * runs. Its answer goes to the store as `{ pinned }`, which reads the rows again. */
609
+ function pinAct({ id, row, pinned }) {
610
+ const name = row.instance, workspace = contextOf(row.deployment?.id).workspace;
611
+ const remote = !!(workspace?.remote || workspace?.server);
612
+ const args = { instance: name, home: row.home, pinned, ...(remote ? { server: workspace?.server } : { context: workspace?.scope }) };
613
+ const exec = (bin, argv, options, callback) => reader.changeExec(bin, argv, { ...options, label: { verb: "pin", name } }, callback);
614
+ Promise.resolve()
615
+ .then(() => effects.pinInstance(probe.cli.bin, args, { exec, ...(remote ? { cwd: actCwd(state) } : {}) }))
616
+ .then((answer) => heard({ pinned: { id, name, pinned, answer } }), () => heard({ pinned: { id, name, pinned, answer: null } }));
617
+ }
604
618
 
605
619
  /** Open the agent the store decided on (lib/model.mjs openDecision). On this machine the viewer
606
620
  * starts in the panel at once. On another, the shared preflight runs first over the reader's
@@ -7,7 +7,7 @@
7
7
  // in. What it adds is the TUI's: the window, the clock times, and which fact stands on which line.
8
8
  import {
9
9
  TERMS, panelData, localDeploymentIds, displayLine, DETAIL_WITHHELD, originLead, instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree,
10
- hasInstanceChildren, heldHome, instanceSiblings, siblingText, rosterSections, rosterSectionKey, sidebarSections, backgroundPlacement, BACKGROUND_FEATURE, deploymentState, rowStale, primaryDeployment, isMultiDeployment, runtimeState, runtimeCounts, instanceColor, instanceDisplayName,
10
+ hasInstanceChildren, heldHome, instanceSiblings, siblingText, rosterSections, rosterSectionKey, sidebarSections, backgroundPlacement, BACKGROUND_FEATURE, PIN_FEATURE, deploymentState, rowStale, primaryDeployment, isMultiDeployment, runtimeState, runtimeCounts, instanceColor, instanceDisplayName,
11
11
  waitingClaim, waitingLabel, waitedText, waitingClock, waitingBelowText, instanceActs, rowReason,
12
12
  identityMemory, viewModel, listedViews, workspaceChoices, workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION, shortPath, machineLabels,
13
13
  openAct, deployments as heldDeployments, localScrollKeys, hostScrollKeys, attachExit, preflightFailure, kernelLines,
@@ -149,6 +149,8 @@ export const BACKGROUND_ID = "\u0000background";
149
149
  * and kept for the run per workspace as `collapsed` is (by `state.open`): `state.background` holds the
150
150
  * ones open. */
151
151
  export const backgroundOpen = (state) => state.background.has(state.open);
152
+ /** Whether this run's kernel lists the pin's feature (instance-pin): a row's `pinned` orders the list only then. */
153
+ export const pinsListed = (state) => Array.isArray(state.cli?.features) && state.cli.features.includes(PIN_FEATURE);
152
154
 
153
155
  /** The key prefix of each run of instances related to no other, as the shared grouping names it
154
156
  * (`independent:<id>`). Read by key, not by label: a cluster whose root is named `independent` has that
@@ -172,7 +174,10 @@ function build(state, at) {
172
174
  // `ordered`: every row in the shared order of the whole roster, whatever is filtered, folded or in the
173
175
  // Background section (the lists of a soul's instances read it).
174
176
  const ordered = [];
175
- for (const part of rosterSections(instances, instances, deployments, TERMS)) for (const group of part.groups) for (const cluster of group.clusters) ordered.push(...cluster.instances);
177
+ // Pinned first (feature instance-pin), as in the Desktop: only when this run's kernel lists the feature; without
178
+ // it a row's `pinned` is ignored and the order is the roster's own.
179
+ const pins = pinsListed(state);
180
+ for (const part of rosterSections(instances, instances, deployments, TERMS, { pins })) for (const group of part.groups) for (const cluster of group.clusters) ordered.push(...cluster.instances);
176
181
  // The rows the Background section holds (#1579), the shared placement's: only when this run's kernel
177
182
  // lists the feature; without it a row's `background` is ignored and nothing below changes.
178
183
  const placement = backgroundPlacement(instances, Array.isArray(state.cli?.features) && state.cli.features.includes(BACKGROUND_FEATURE));
@@ -186,14 +191,14 @@ function build(state, at) {
186
191
  // left out makes an ambiguous name unique. The key without a placement is the deployment's alone.
187
192
  const deploymentOf = rosterSectionKey(deployments), bySection = new Map();
188
193
  for (const row of instances) { const key = deploymentOf(row); if (!bySection.has(key)) bySection.set(key, []); bySection.get(key).push(row); }
189
- const siblings = new Map([...bySection.values()].flatMap((own) => [...instanceSiblings(own)]));
194
+ const siblings = new Map([...bySection.values()].flatMap((own) => [...instanceSiblings(own, { pins })]));
190
195
  const matched = soul !== null ? filterInstanceTree(instances, soul.name, (row) => soul.names.includes(row.agent)) : filterInstanceTree(instances, query);
191
196
  const visible = matched.filter((i) => instanceVisibleInTree(i, instances, state.collapsed, state.open, filtering, { section }));
192
197
  const stale = (row) => rowStale(row, deployments);
193
198
  // The main tree's sections, and the Background section after them, each a tree of its own (the shared
194
199
  // sidebarSections). A filter draws the section open, so its matches show, and changes nothing stored;
195
200
  // the heading counts the rows the filter leaves in it.
196
- const { main: sections, background } = sidebarSections(instances, visible, deployments, TERMS, { placement, open: backgroundOpen(state) || filtering, listed: matched, stale });
201
+ const { main: sections, background } = sidebarSections(instances, visible, deployments, TERMS, { placement, open: backgroundOpen(state) || filtering, listed: matched, stale, pins });
197
202
  // How many instances each collapse folds away under its row: every descendant of the row in its
198
203
  // own section, as the shared walk finds them when it is asked with that collapse alone (so a
199
204
  // fold further down hides none of them from the count). A filter folds nothing away.
@@ -878,7 +883,7 @@ export function paletteItems(state, at = new Date(0).toISOString()) {
878
883
  sibling: siblingText(r.siblings.get(instanceId(row))), text: `${row.instance} ${machine ?? ""}`,
879
884
  };
880
885
  };
881
- for (const section of rosterSections(r.instances, openable, r.deployments, TERMS, { lastFocus })) for (const group of section.groups) {
886
+ for (const section of rosterSections(r.instances, openable, r.deployments, TERMS, { lastFocus, pins: pinsListed(state) })) for (const group of section.groups) {
882
887
  const rows = group.clusters.flatMap((cluster) => cluster.instances).map(item).filter(matched);
883
888
  if (!rows.length) continue;
884
889
  // A group is named, and kept apart, by its deployment where there are several (the Desktop's palette.mjs).
@@ -1140,6 +1145,44 @@ export function actDecision(state, row, acts, verb) {
1140
1145
  return { open: true, verb, id, name, kind: lifecycle ? "lifecycle" : "start", machine, label: machine, home: row.home ?? null };
1141
1146
  }
1142
1147
 
1148
+ /** The TUI's own words around the pin key (feature instance-pin; docs/tui.md, "Pinning"), as parts the way
1149
+ * ACT_WORDS are. `unavailable` says why the key does nothing on a kernel that does not list the feature, and the
1150
+ * command that pins. */
1151
+ export const PIN_WORDS = Object.freeze({
1152
+ unavailable: [{ own: "This OATS can't pin instances: it doesn't list instance-pin. With a newer one, p or `oats instance pin <name> on|off` pins." }],
1153
+ pinning: (name, pinned) => [{ own: pinned ? "Pinning " : "Unpinning " }, { shown: name }, { own: "…" }],
1154
+ still: (name) => [{ own: "The pin of " }, { shown: name }, { own: " is still changing." }],
1155
+ done: (name, pinned) => [{ shown: name }, { own: pinned ? " is pinned to the top of its machine's list." : " is unpinned." }],
1156
+ notChanged: (name) => [{ own: "The pin of " }, { shown: name }, { own: " was not changed." }],
1157
+ unconfirmed: (name) => [{ own: "OATS didn't confirm the pin of " }, { shown: name }, { own: ". The list shows it once it is read again." }],
1158
+ });
1159
+
1160
+ /** What the pin key does on `row` (`acts`: its instanceActs answer): `{ open: true, id, name, pinned }`, `pinned`
1161
+ * the value it sets (Unpin on a pinned row, else Pin), or `{ open: false, said }`, the line that says why not:
1162
+ * without the feature, while this run's pin of the row is still changing, or on a row that offers no act of a
1163
+ * client's own (a held, retiring or unaddressable home: the shared reason). A remote row's host without the
1164
+ * feature is the kernel's to refuse (E_REMOTE_INCOMPATIBLE: nothing is sent), said as its refusal. */
1165
+ export function pinDecision(state, row, acts) {
1166
+ const name = row.instance, id = instanceId(row);
1167
+ const no = (said, under = []) => ({ open: false, said: Object.freeze({ said, under }) });
1168
+ if (!pinsListed(state)) return no(PIN_WORDS.unavailable);
1169
+ if (state.pinning?.has(id)) return no(PIN_WORDS.still(name));
1170
+ const held = acts.blocked ?? acts.limited;
1171
+ if (held) return no([], outside(reasonSpoken(held)));
1172
+ return { open: true, id, name, pinned: row.pinned !== true };
1173
+ }
1174
+
1175
+ /** The line after a pin's answer (packages/client instance-pin.mjs pinOutcome): the change, the kernel's refusal
1176
+ * under the TUI's sentence, or that OATS did not confirm it (the list read after it says what is true). */
1177
+ export function pinLine(name, pinned, answer) {
1178
+ if (answer?.status === "ok" && answer.pinned === pinned) return Object.freeze({ said: PIN_WORDS.done(name, pinned), under: Object.freeze([]) });
1179
+ if (answer?.status === "refused") {
1180
+ const said = kernelLines(answer.reason?.message, undefined, TERMS);
1181
+ return Object.freeze({ said: PIN_WORDS.notChanged(name), under: Object.freeze(said.length ? said : outside(displayLine(answer.reason?.code))) });
1182
+ }
1183
+ return Object.freeze({ said: PIN_WORDS.unconfirmed(name), under: Object.freeze([]) });
1184
+ }
1185
+
1143
1186
  /** What a start's or a restart's answer (the shared startInstance's) shows, as the act view's
1144
1187
  * lines: `{ said }` the TUI's own sentence in parts, `{ text }` a shared sentence or the kernel's
1145
1188
  * line (each already as the shared home words it). Chosen by the answer's fields and codes, never
@@ -12,7 +12,7 @@
12
12
  import { ACTIONS, LEADER_KEYS, backKeyLabel, bindings, chordKeys, chordsRead, paletteKeys } from "./actions.mjs";
13
13
  import { CHORDS, chordFamilyFrom, collapseKey, workspaceStep, displayLine, instanceActs, instanceId, outcomeWords, pendingEntry, spawnProblem } from "./client.mjs";
14
14
  import { defaultDetachKey } from "./config.mjs";
15
- import { BACKGROUND_ID, backgroundOpen, BUTTON_ORDER, SPAWN_WORDS, LEADER_WORDS, SPLIT_WORDS, TAB_WORDS, actDecision, capabilitiesHeight, capabilitiesOf, capabilityUsersOf, disclosure, openDecision, paletteItems, paletteStep, preflightLine, returnedLine, roster, soulNames, soulOfAgent, soulsOf, spawnChoices, spawnChoicesKey, spawnLine, spawnPickerItems, spawnReady, spawnRing, spawnSelector, spawnedRow, switcher, switcherHeight, switcherWindow, memoryKey, memoryKeys, LIST_WORDS, WORKSPACE_WORDS, listChoice, listChoices, workspaceList } from "./model.mjs";
15
+ import { BACKGROUND_ID, backgroundOpen, BUTTON_ORDER, PIN_WORDS, pinDecision, pinLine, SPAWN_WORDS, LEADER_WORDS, SPLIT_WORDS, TAB_WORDS, actDecision, capabilitiesHeight, capabilitiesOf, capabilityUsersOf, disclosure, openDecision, paletteItems, paletteStep, preflightLine, returnedLine, roster, soulNames, soulOfAgent, soulsOf, spawnChoices, spawnChoicesKey, spawnLine, spawnPickerItems, spawnReady, spawnRing, spawnSelector, spawnedRow, switcher, switcherHeight, switcherWindow, memoryKey, memoryKeys, LIST_WORDS, WORKSPACE_WORDS, listChoice, listChoices, workspaceList } from "./model.mjs";
16
16
  import { backKeyId, backKeySequences, isBackKey } from "./term/through.mjs";
17
17
  import { windowOf } from "./views/scroll.mjs";
18
18
  import { SPLIT_MIN, splitFits } from "./views/split.mjs";
@@ -133,7 +133,7 @@ export function initialState({ deployment = null, cli, home, entry = null, actio
133
133
  selected: null, collapsed: new Set(), background: new Set(), filter: NO_FILTER, focus: "list", top: 0, loose: false, detailTop: 0, places: new Map(), unread: new Map(), unreadKeys: new Map(), workspaceCursor: null, colour,
134
134
  switcher: NO_SWITCHER,
135
135
  listed: NO_LIST, identities: new Map(),
136
- helpTop: 0, actions, ascii, detachKey, opening: null, terminal: null, outcome: null, act: null, acted: 0, starting: new Map(), retiring: new Set(),
136
+ helpTop: 0, actions, ascii, detachKey, opening: null, terminal: null, outcome: null, act: null, acted: 0, starting: new Map(), retiring: new Set(), pinning: new Set(),
137
137
  leaderKey: backKeyId(detachKey), leader: null, keyboard: null, keysRead, mac: platform === "darwin", chords: chordKeys(platform === "darwin", actions, CHORDS, keysRead.family, backKeyId(detachKey)), palette: null, paletteKeys: paletteKeys(platform === "darwin"), recent: new Map(), layouts: new Map(), restoring: null, leftFocus: null, souls: NO_SOULS, capabilities: NO_CAPABILITIES,
138
138
  spawn: null, spawning: null, spawnCheck: null, arriving: null, previews: 0, tabs: Object.freeze([]), split: null, group: 0, aside: null,
139
139
  notice: null,
@@ -737,6 +737,23 @@ function resumedHeard(state, reading) {
737
737
  return { state, effect: null };
738
738
  }
739
739
 
740
+ /** The pin key on `row` (feature instance-pin; lib/model.mjs pinDecision): at once, no confirmation. The line under
741
+ * the sidebar's title says it is changing, the row is held from a second press until the answer, and the loop runs
742
+ * the kernel's verb (`{ pin }`); a key it does nothing for says why on that line. */
743
+ function pinOn(state, row) {
744
+ const decision = pinDecision(state, row, instanceActs(row));
745
+ if (!decision.open) return { state: next(state, { outcome: decision.said }), effect: null };
746
+ const pinning = new Set(state.pinning); pinning.add(decision.id);
747
+ const outcome = Object.freeze({ said: PIN_WORDS.pinning(decision.name, decision.pinned), under: Object.freeze([]) });
748
+ return { state: next(state, { pinning, outcome }), effect: { pin: Object.freeze({ id: decision.id, row, pinned: decision.pinned }) } };
749
+ }
750
+ /** A pin answered (lib/main.mjs): the line says how, the row is free again, and the rows are read again, so the
751
+ * list moves (a refusal changes nothing, and the read says so too). */
752
+ function pinHeard(state, { id, name, pinned, answer }) {
753
+ const pinning = new Set(state.pinning); pinning.delete(id);
754
+ return { state: next(state, { pinning, outcome: pinLine(name, pinned, answer) }), effect: { refresh: { live: true } } };
755
+ }
756
+
740
757
  /** A Remove answered (lib/main.mjs): the switcher says how, and the list is read again. */
741
758
  function removedHeard(state, { name, ok, reason = null }) {
742
759
  const line = Object.freeze(ok ? { removed: name } : { notRemoved: name, message: reason?.message ?? "" });
@@ -1477,6 +1494,13 @@ function led(state, does, event, keymap) {
1477
1494
  const stay = { state, effect: null }, t = state.terminal;
1478
1495
  const inTerminal = t?.focus === "terminal" && state.view === "instances";
1479
1496
  if (does === "list") return toList(state);
1497
+ // The shared table's `b` (the Desktop's sidebar; the Desktop UI rework, slice 4): the list is the TUI's sidebar. With
1498
+ // a terminal shown, it takes the whole screen with the focus (as zoom does), and zoomed, the list comes back with the
1499
+ // focus (as Esc does). With none shown the list is all there is: nothing.
1500
+ if (does === "sidebar") {
1501
+ if (t === null || state.view !== "instances") return stay;
1502
+ return t.zoom ? toList(state) : { state: terminalWith(state, { focus: "terminal", zoom: true }), effect: null };
1503
+ }
1480
1504
  if (does === "palette") return { state: paletteOpened(state, event, inTerminal ? "terminal" : "list"), effect: null };
1481
1505
  if (does === "zoom" || does === "close-terminal") {
1482
1506
  if (t === null) return stay;
@@ -1661,6 +1685,7 @@ function reduced(state, event, keymap) {
1661
1685
  if (event.retiring !== undefined) return { state: next(state, { retiring: new Set(event.retiring) }), effect: null };
1662
1686
  if (event.listed !== undefined) return listedHeard(state, event.listed);
1663
1687
  if (event.removed !== undefined) return removedHeard(state, event.removed);
1688
+ if (event.pinned !== undefined) return pinHeard(state, event.pinned);
1664
1689
  // The machine sweep's reading: no line, at most a live read.
1665
1690
  if (event.resumed !== undefined) return resumedHeard(state, event.resumed);
1666
1691
  // Shown once, in the line under the sidebar's title, as the line after an open is.
@@ -1762,6 +1787,7 @@ function reduced(state, event, keymap) {
1762
1787
  return refused === true ? { state, effect: null } : refused !== null ? { state: next(state, { outcome: refused }), effect: null } : splitKey(state, action, false);
1763
1788
  }
1764
1789
  case "stop": case "retire": case "start": case "restart": return at < 0 ? stay : actOn(state, r.items[at].row, action);
1790
+ case "pin": return at < 0 || !r.items[at].row ? stay : pinOn(state, r.items[at].row);
1765
1791
  case "detail": return at < 0 ? stay : { state: next(state, { focus: state.focus === "detail" ? "list" : "detail" }), effect: null };
1766
1792
  case "up": case "down": case "top": case "bottom": case "page-up": case "page-down": {
1767
1793
  if (state.focus === "detail") return { state: next(state, { detailTop: scrolled(state.detailTop) }), effect: null };
@@ -249,15 +249,16 @@ the final values in one short message before you go on. The rules:
249
249
  `U` (`https://…`, the API URL their server gives its users), and whether
250
250
  their server uses the public AWID registry. Answers given in the prompt
251
251
  that started you are used without asking. When it uses a private
252
- registry, the own-server branch stops here, before anything is written:
253
- tell the person in one sentence that a private registry needs oats.aweb
254
- with `oats aweb setup --registry`, and that this skill stops here. Offer
255
- hosted aweb now (the hosted defaults above, `N` among them, shown in one
256
- short message) or waiting for that release. Otherwise, tell them, in
252
+ registry, ask its address too, the registry origin `RG` (`https://…`,
253
+ the scheme and host only, with no path), also not a secret. Step 9
254
+ records it for this deployment. Then tell them, in
257
255
  plain words, what must already be in place on their side, since you
258
256
  make none of it: the namespace's controller key on this computer, for
259
257
  this computer account; the `_awid.ND` DNS record published for that
260
- key; and their server reachable at `U`. Step 9
258
+ key; and their server reachable at `U`. On a private registry, that
259
+ record must name their registry: a key prepared without
260
+ `--registry RG` gives a record for the public registry, so tell them
261
+ to check that its value carries `registry=RG`. Step 9
261
262
  checks them, read-only. On their own server there is no account `N` and
262
263
  no step 5: the team is `<workspace>:ND`, created in step 9 in their
263
264
  namespace, and `A` is `<workspace>-root` as on hosted. Never offer it on
@@ -561,7 +562,7 @@ installed CLI's catalog:
561
562
  node -e 'const c=require(process.argv[1]);console.log(c.packages["oats.framework"].ref,c.packages["oats.aweb"].ref)' "$(oats root)/package-catalog.json"
562
563
  ```
563
564
 
564
- It prints the two refs, for example `oats-framework/v1.26.0 v1.43.0`. If the
565
+ It prints the two refs, for example `oats-framework/v1.26.0 v1.45.0`. If the
565
566
  framework's version (after the `/`) is below `1.19.0`, or with aweb
566
567
  `oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
567
568
  skill: stop, and tell the person to wait for the next OATS
@@ -601,14 +602,18 @@ release's `oats.aweb` was tested with, which `oats.aweb` publishes in its
601
602
  `aw-compat.json`: hosted aweb upgrades its server before a new `aw` comes
602
603
  out, but their own server has no such order. Read that version at the exact
603
604
  `oats.aweb` release the installed CLI's catalog names, never at `main`.
604
- This prints `TESTED <version>`, or why it can't:
605
+ On a private registry (step 1), add ` private` at the end of the line,
606
+ after the catalog's path: that branch needs a later `oats.aweb`. This
607
+ prints `TESTED <version>`, or why it can't:
605
608
 
606
609
  ```bash
607
- node -e 'const c=require(process.argv[1]).packages["oats.aweb"],m=/^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(c.url),v=/^v(\d+)\.(\d+)\.(\d+)$/.exec(c.ref);if(!m){console.log("NOT_GITHUB "+c.url);process.exit(1)}if(!v||v.slice(1).reduce((d,x,i)=>d||x-[1,42,1][i],0)<0){console.log("TOO_OLD "+c.ref);process.exit(1)}const u="https://raw.githubusercontent.com/"+m[1]+"/"+m[2]+"/"+c.ref+"/"+c.path+"/capabilities/oats-aweb/aw-compat.json";fetch(u).then(r=>{if(!r.ok)throw new Error("HTTP "+r.status+" "+u);return r.json()}).then(j=>{if(Object.keys(j).sort().join()!=="min,tested"||typeof j.tested!=="string"||!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-(0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(\.(0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$/.test(j.tested))throw new Error("unexpected "+JSON.stringify(j));console.log("TESTED "+j.tested)}).catch(e=>{console.log("FAILED "+e.message);process.exit(1)})' "$(oats root)/package-catalog.json"
610
+ node -e 'const c=require(process.argv[1]).packages["oats.aweb"],m=/^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(c.url),v=/^v(\d+)\.(\d+)\.(\d+)$/.exec(c.ref);if(!m){console.log("NOT_GITHUB "+c.url);process.exit(1)}if(process.argv.length>3||![undefined,"private"].includes(process.argv[2])){console.log("FAILED usage");process.exit(1)}const f=process.argv[2]?[1,43,0]:[1,42,1];if(!v||v.slice(1).reduce((d,x,i)=>d||x-f[i],0)<0){console.log("TOO_OLD "+c.ref);process.exit(1)}const u="https://raw.githubusercontent.com/"+m[1]+"/"+m[2]+"/"+c.ref+"/"+c.path+"/capabilities/oats-aweb/aw-compat.json";fetch(u).then(r=>{if(!r.ok)throw new Error("HTTP "+r.status+" "+u);return r.json()}).then(j=>{if(Object.keys(j).sort().join()!=="min,tested"||typeof j.tested!=="string"||!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-(0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(\.(0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$/.test(j.tested))throw new Error("unexpected "+JSON.stringify(j));console.log("TESTED "+j.tested)}).catch(e=>{console.log("FAILED "+e.message);process.exit(1)})' "$(oats root)/package-catalog.json"
608
611
  ```
609
612
 
610
613
  - **`TOO_OLD`:** this OATS release's `oats.aweb` is older than `v1.42.1`,
611
- the first that sets up a team on a person's own server.
614
+ the first that sets up a team on a person's own server, or, on a private
615
+ registry, older than `v1.43.0`, the first that records the registry
616
+ (`oats aweb setup --registry`).
612
617
  **`NOT_GITHUB` or `FAILED`:** the tested version can't be read. Either
613
618
  way, the own-server branch stops here. Tell the person in one sentence,
614
619
  and offer hosted aweb now (step 1's hosted defaults, `N` among them,
@@ -852,7 +857,7 @@ members:
852
857
  - git:github.com/acme/acme-oats # the host; the setup expert adds the others
853
858
  packages:
854
859
  oats.framework: v1.26.0 # the installed CLI's catalog versions (below)
855
- oats.aweb: v1.43.0 # messaging: agent identities, mail and chat
860
+ oats.aweb: v1.45.0 # messaging: agent identities, mail and chat
856
861
  oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
857
862
  defaults:
858
863
  capabilities:
@@ -1019,6 +1024,30 @@ below; for another capability, follow its own setup skill, and stop if its
1019
1024
  readiness still reports a problem.
1020
1025
 
1021
1026
  **With aweb (`oats.aweb`):**
1027
+
1028
+ **Their own aweb server on a private registry (step 1): record it first,**
1029
+ before item 1, with `RG` written in. Skip this on the public registry and
1030
+ on hosted aweb.
1031
+
1032
+ ```bash
1033
+ cd "D" && oats aweb setup --soul S --registry RG
1034
+ ```
1035
+
1036
+ It writes only `settings.oats.aweb.registry` in `D/oats-local.yaml`, the
1037
+ one setting that admits a private registry here: every later `oats aweb`
1038
+ command and every agent of `D` reads its registry from it. Never set
1039
+ `AWID_REGISTRY_URL` instead: oats.aweb refuses a private registry given
1040
+ that way (`registry-setting-required`), item 1's check included, until
1041
+ this setting is recorded. Success prints one line of JSON whose
1042
+ `registry` is `RG` as an origin (the host in lowercase, no trailing `/`).
1043
+ Its `next` lists "Restart resident serve" and "Restart wake": both are
1044
+ expected and need nothing from you, since this new deployment has no
1045
+ resident yet and item 6 installs the broker after this. An
1046
+ `E_SETUP_REGISTRY` refusal that starts `settings.oats.aweb.registry:`
1047
+ says what is wrong with the address (a path, `/api`, a query): ask the
1048
+ person for the registry's origin again and run this again. Anything
1049
+ else: stop, spawn nothing, and tell the person what it shows.
1050
+
1022
1051
  1. **Check:**
1023
1052
 
1024
1053
  ```bash
@@ -1230,8 +1259,45 @@ readiness still reports a problem.
1230
1259
  `delivery: session`: its own channel wakes it (step 4). Any other setup
1231
1260
  expert is woken only by the host wake broker, and oats.aweb refuses to
1232
1261
  spawn or start it while no broker runs (`wake-daemon-not-running`). The
1233
- broker is the person's own user service, so it is theirs to start. Open
1234
- their own terminal ("How to work") running this, with `D` filled in:
1262
+ broker is the person's own user service, so it is theirs to start.
1263
+
1264
+ **On a private registry (step 1), first check the install yourself,**
1265
+ read-only: the broker must carry `RG`, and the status check below can't
1266
+ see which registry a running broker serves.
1267
+
1268
+ ```bash
1269
+ cd "D" && oats aweb wake install --plan --json
1270
+ ```
1271
+
1272
+ It changes nothing, and it refuses whatever the install would refuse.
1273
+ Only `"ok": true` lets you go on to their install below: then no other
1274
+ broker runs on this computer account, or the one that runs is the
1275
+ install's own and already carries `RG`, so the status check below
1276
+ proves the right broker. Otherwise its `error.code` decides:
1277
+ - **`E_WAKE_REGISTRY_CONFLICT`:** this computer account already runs a
1278
+ wake broker for another registry, or for none, most likely for
1279
+ another deployment, and one account's broker serves one registry.
1280
+ Stop, spawn nothing, and tell the person in plain words; the choice is
1281
+ theirs: run this deployment under another computer account, or move
1282
+ the other one, as the message says. Never uninstall the broker or
1283
+ deregister another deployment's homes yourself.
1284
+ - **`E_WAKE_UNSUPPORTED`** (a container, or a machine with neither
1285
+ launchd nor systemd): there is no service to install, and the plain
1286
+ `aw wake run` below would not carry `RG`. Stop and spawn nothing.
1287
+ Tell the person in one sentence, and offer a Claude or pi setup
1288
+ expert instead, which its own channel wakes: with that harness, this
1289
+ item is skipped.
1290
+ - **Any other refusal** (for example a broker started by hand or by
1291
+ another supervisor, `E_WAKE_RUNNING_UNSUPERVISED`, or a service the
1292
+ install didn't write, `E_WAKE_UNIT_CONFLICT`): stop and spawn nothing.
1293
+ A broker that is running now would pass the status check without
1294
+ carrying `RG`. Tell the person in plain words what its message says;
1295
+ the fix is theirs, and the message names it. Once they say it's done,
1296
+ run this check again. Never stop, uninstall or deregister a broker
1297
+ yourself.
1298
+
1299
+ Open their own terminal ("How to work") running this, with `D` filled
1300
+ in:
1235
1301
 
1236
1302
  ```text
1237
1303
  cd "D" && oats aweb wake install
@@ -1239,7 +1305,8 @@ readiness still reports a problem.
1239
1305
 
1240
1306
  In a container, or on a machine with neither launchd nor systemd (the
1241
1307
  command answers `E_WAKE_UNSUPPORTED`), there is no service to install:
1242
- the line is `aw wake run`, kept running as a supervised process.
1308
+ on the public registry, the line is `aw wake run`, kept running as a
1309
+ supervised process.
1243
1310
 
1244
1311
  Then check it yourself:
1245
1312
 
@@ -1323,8 +1390,10 @@ are cloned, knowledge tools, messaging wanted or not>
1323
1390
  the person (new workspace), or T owned by aweb account <handle>
1324
1391
  (signed in at step 5), or new account N signed up (machine found-list),
1325
1392
  or joined L by invite (existing), or team T on their own aweb server U,
1326
- namespace ND, aw <tested> (oats.aweb's tested version) or "aw <version>
1327
- is newer than the tested <tested>; kept", its key at
1393
+ namespace ND, registry public | RG (recorded in
1394
+ `settings.oats.aweb.registry`), aw <tested> (oats.aweb's tested
1395
+ version) or "aw <version> is newer than the tested <tested>; kept", its
1396
+ key at
1328
1397
  <team key path> | not set up (the setup expert has no messaging)
1329
1398
  - Harness channel mode: development, confirmed by OATS at each start
1330
1399
  (Claude with aweb) | none (Codex, pi or no messaging)
@@ -1493,8 +1562,9 @@ the setup expert, not in this message. You are done.
1493
1562
  aweb server, checked against step 9's create.
1494
1563
  - **On their own aweb server:** make or touch the namespace's controller key
1495
1564
  (`aw id namespace prepare-controller`, `~/.awid`), set or ask for
1496
- `AWEB_API_KEY`, or write a hosted `default:…aweb.ai` team or
1497
- `localTeams` into the workspace.
1565
+ `AWEB_API_KEY`, set `AWID_REGISTRY_URL` (a private registry is
1566
+ recorded by `oats aweb setup --registry` only), or write a hosted
1567
+ `default:…aweb.ai` team or `localTeams` into the workspace.
1498
1568
  - **Write a setup soul into the workspace:** the setup expert is
1499
1569
  `oats.framework`'s.
1500
1570
  - **The Desktop:** never download it through a browser, skip a verification