@awebai/oats 0.69.21 → 0.69.23

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 (73) hide show
  1. package/bin/oats.mjs +131 -23
  2. package/docs/capabilities.md +12 -2
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/container.md +290 -5
  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/design/2026-11-19-sandboxes.md +878 -0
  8. package/docs/design/README.md +3 -0
  9. package/docs/desktop-cli-api.md +416 -72
  10. package/docs/desktop.md +377 -148
  11. package/docs/implementation.md +15 -2
  12. package/docs/integrations.md +3 -3
  13. package/docs/knowledge-capability-authoring.md +10 -7
  14. package/docs/knowledge-reference/acceptance.md +21 -19
  15. package/docs/knowledge-reference/adoption.md +18 -4
  16. package/docs/knowledge-reference/model.md +11 -9
  17. package/docs/knowledge-reference/package-craft.md +2 -2
  18. package/docs/knowledge-reference/proposal.md +117 -0
  19. package/docs/knowledge-reference/provider-mapping.md +10 -10
  20. package/docs/knowledge-reference/reader-capture.md +26 -22
  21. package/docs/knowledge-theory.md +1 -1
  22. package/docs/knowledge.md +5 -5
  23. package/docs/official-catalog.md +47 -4
  24. package/docs/packages.md +13 -13
  25. package/docs/release-lane.md +8 -6
  26. package/docs/release-notes/v0.69.22.md +221 -0
  27. package/docs/release-notes/v0.69.23.md +231 -0
  28. package/docs/servers.md +10 -6
  29. package/docs/souls-and-instances.md +51 -22
  30. package/docs/tui.md +48 -7
  31. package/docs/upgrading.md +17 -5
  32. package/docs/workspaces.md +2 -2
  33. package/lib/argv.mjs +6 -2
  34. package/lib/capability-contract.mjs +2 -2
  35. package/lib/command-flags.mjs +39 -2
  36. package/lib/core.mjs +25 -14
  37. package/lib/instance-board.mjs +337 -0
  38. package/lib/instance-events.mjs +48 -10
  39. package/lib/instance-lifecycle.mjs +19 -15
  40. package/lib/instance-listing.mjs +18 -10
  41. package/lib/instance-related-work.mjs +143 -0
  42. package/lib/kernel-features.mjs +4 -1
  43. package/lib/servers.mjs +123 -13
  44. package/package-catalog.json +3 -3
  45. package/package.json +1 -1
  46. package/packages/client/above-tested.mjs +3 -2
  47. package/packages/client/capability-list.mjs +69 -0
  48. package/packages/client/capability-origin.mjs +54 -0
  49. package/packages/client/cli-adapter.mjs +9 -1
  50. package/packages/client/deployment-data.mjs +7 -2
  51. package/packages/client/deployment-panel.mjs +4 -1
  52. package/packages/client/home-board.mjs +50 -0
  53. package/packages/client/instance-pin.mjs +28 -0
  54. package/packages/client/instance-record-outcome.mjs +31 -0
  55. package/packages/client/instance-tree.mjs +96 -24
  56. package/packages/client/keymap.mjs +16 -3
  57. package/packages/client/mail-contract.mjs +130 -0
  58. package/packages/client/panel-views.mjs +7 -7
  59. package/packages/client/related-work.mjs +84 -0
  60. package/packages/client/remote-roster.mjs +11 -3
  61. package/packages/client/roster-sections.mjs +10 -7
  62. package/packages/client/soul-role.mjs +44 -0
  63. package/packages/client/waiting-on-you.mjs +10 -0
  64. package/packages/client/workspace-cli.mjs +13 -2
  65. package/packages/tui/lib/actions.mjs +11 -4
  66. package/packages/tui/lib/client.mjs +3 -1
  67. package/packages/tui/lib/main.mjs +16 -2
  68. package/packages/tui/lib/model.mjs +48 -5
  69. package/packages/tui/lib/store.mjs +28 -2
  70. package/skills/oats-getting-started/SKILL.md +97 -24
  71. package/docs/knowledge-reference/harvester.md +0 -109
  72. package/lib/instance-same-work.mjs +0 -67
  73. package/packages/client/same-work.mjs +0 -49
@@ -0,0 +1,44 @@
1
+ /** A soul's role, and the order souls are listed in, for every client (the Desktop's Souls grid and table, and
2
+ * the Terminal UI later): maintainers, experts, developers, operations, then the rest, each alphabetical. (Not the
3
+ * row's `soulKind`, which is where the soul comes from: member, package or external.)
4
+ *
5
+ * The kernel reports no role for a soul (oats-project/oats#1980 asks for one), so the role is read from the soul's
6
+ * name, one rule:
7
+ * 1. operations: any word of the name is setup, operator, operators, admin, ops or operations
8
+ * (`acme-oats-setup-expert`, `ops-admin`): a setup soul is operations even when it ends in -expert;
9
+ * 2. else the last word: maintainer → maintainer, expert → expert, developer → developer;
10
+ * 3. else other.
11
+ * A word is a run of the name between `-`, `_`, `.` and `/`, case aside, so a package soul's qualified name
12
+ * (`oats.engineering/code-reviewer`) reads the same as its bare one. The description is not read: a sentence
13
+ * that says a soul "operates" something would misfile it, and the name is what the soul's author chose.
14
+ *
15
+ * A kernel `role` fact on the soul row would replace this rule (#1980): then `soulRole` reads it, and every client
16
+ * keeps calling the same two functions.
17
+ *
18
+ * soulRole(row) -> 'maintainer' | 'expert' | 'developer' | 'operations' | 'other'
19
+ * SOUL_ROLES the roles, in list order
20
+ * SOUL_ROLE_WORDS a role in words, singular ("developer"); the Desktop's Souls call it the soul's kind
21
+ * compareSoulsByRole(a, b) list order: role, then name; for Array.prototype.sort
22
+ *
23
+ * No state, no DOM. */
24
+
25
+ export const SOUL_ROLES = Object.freeze(['maintainer', 'expert', 'developer', 'operations', 'other']);
26
+ export const SOUL_ROLE_WORDS = Object.freeze({ maintainer: 'maintainer', expert: 'expert', developer: 'developer', operations: 'operations', other: 'other' });
27
+ const OPERATIONS = new Set(['setup', 'operator', 'operators', 'admin', 'ops', 'operations']);
28
+ const LAST = Object.freeze({ maintainer: 'maintainer', expert: 'expert', developer: 'developer' });
29
+
30
+ const nameOf = row => typeof row === 'string' ? row : typeof row?.name === 'string' ? row.name : '';
31
+ const words = name => name.toLowerCase().split(/[-_./]+/).filter(Boolean);
32
+
33
+ /** The soul's role, from its name (a row with a `name`, or the name itself). */
34
+ export function soulRole(row) {
35
+ const parts = words(nameOf(row));
36
+ if (parts.some(part => OPERATIONS.has(part))) return 'operations';
37
+ const last = parts.at(-1);
38
+ return last !== undefined && Object.hasOwn(LAST, last) ? LAST[last] : 'other';
39
+ }
40
+
41
+ /** List order inside a group: the role's place in SOUL_ROLES, then the name. */
42
+ export function compareSoulsByRole(a, b) {
43
+ return SOUL_ROLES.indexOf(soulRole(a)) - SOUL_ROLES.indexOf(soulRole(b)) || nameOf(a).localeCompare(nameOf(b));
44
+ }
@@ -43,6 +43,16 @@ export function waitingClaim(row, { stale = false } = {}) {
43
43
  return waitingOnYouData(row.waitingOnYou);
44
44
  }
45
45
 
46
+ /** The rows that need you, newest claim first (the Desktop's palette and Home, the TUI's list later: one order for
47
+ * both clients, the Desktop UI rework, slice 4): each row's claim through the one gate (waitingClaim; `stale(row)`
48
+ * says a row is held stale), as `{ row, claim }`. Equal times keep the rows' own order. */
49
+ export function needsYouRows(rows, { stale = () => false } = {}) {
50
+ return (Array.isArray(rows) ? rows : []).map((row, at) => ({ row, at, claim: waitingClaim(row, { stale: stale(row) }) }))
51
+ .filter(({ claim }) => claim)
52
+ .sort((a, b) => Date.parse(b.claim.since) - Date.parse(a.claim.since) || a.at - b.at)
53
+ .map(({ row, claim }) => ({ row, claim }));
54
+ }
55
+
46
56
  const LABELS = Object.freeze({ permission: 'Waiting for a tool approval', question: 'Asked you a question', attention: 'Asked for your attention' });
47
57
  /** The reason in words. The raw reason is never rendered: an unknown one reads "Needs input". */
48
58
  export const waitingLabel = claim => Object.hasOwn(LABELS, claim?.reason ?? '') ? LABELS[claim.reason] : 'Needs input';
@@ -10,7 +10,8 @@
10
10
  * sync → `oats sync --dir D --json` (syncApi 1)
11
11
  * onboard → `oats onboard DIR --workspace REF --json` (onboardApi 2)
12
12
  * There is no package approval (packages-no-approval): declaring a package
13
- * is the trust decision, so every success exits 0. `--max-age` (feature
13
+ * is the trust decision, so every success exits 0, but one: a sync whose
14
+ * sandbox failed exits 1 with its report (sandboxFailureReport). `--max-age` (feature
14
15
  * observe-max-age) belongs to the three reads only and reaches argv only when
15
16
  * the probe declares the feature; cliWorkspace drops it otherwise. */
16
17
  import { execFile } from 'node:child_process';
@@ -97,6 +98,13 @@ export function workspaceArgv(options) {
97
98
  return { argv: ['sync', '--dir', options.context, '--json'], cwd: options.context, timeout: WORKSPACE_WRITE_TIMEOUT };
98
99
  }
99
100
 
101
+ /** Whether a sync's exit is its one non-zero success: exit 1 exactly, an `ok: true` answer, and a
102
+ * `result.sandboxes` entry whose `problems` is not empty (a failed sandbox; the lock is written). */
103
+ function sandboxFailureReport(options, error, document) {
104
+ if (options.action !== 'sync' || error?.code !== 1 || error.killed || error.signal) return false;
105
+ const sandboxes = document?.result?.sandboxes;
106
+ return Array.isArray(sandboxes) && sandboxes.some(entry => record(entry) && Array.isArray(entry.problems) && entry.problems.length > 0);
107
+ }
100
108
  /** `io.exec` is a client's own `execFile` (the rule is at cli-adapter.mjs `runJson`). */
101
109
  export function cliWorkspace(cli, options, terms, io = {}) {
102
110
  requireTerms(terms, 'cliWorkspace');
@@ -138,7 +146,10 @@ export function cliWorkspace(cli, options, terms, io = {}) {
138
146
  if (options.action === 'sync' && typeof reason.details?.why === 'string' && WHY_RE.test(reason.details.why)) out.why = reason.details.why;
139
147
  return done({ ok: false, reason: out });
140
148
  }
141
- if (error) return fail('E_CLI_FAILED'); // success is exit 0 only
149
+ // Success is exit 0, with one exception: a sync whose sandbox failed (feature sandboxes) wrote the lock
150
+ // and answers its report with `ok: true` and exit 1, the failure in a sandbox entry's `problems`
151
+ // (docs/desktop-cli-api.md, `oats sync`). That one answer is a report; any other exit is a failure.
152
+ if (error && !sandboxFailureReport(options, error, document)) return fail('E_CLI_FAILED');
142
153
  done({ ok: true, document });
143
154
  });
144
155
  } catch { fail('E_CLI_FAILED'); }
@@ -8,7 +8,7 @@
8
8
  // The keys the TUI shares with the Desktop are not written here: an action with no `keys` of its own
9
9
  // takes its default keys from the shared keymap (packages/client/keymap.mjs PLAIN_KEYS), and the
10
10
  // leader's table is the shared one (LEADER, below). What only the TUI has (q, Ctrl+C, Ctrl+Z, Ctrl+L,
11
- // Ctrl+K, Tab, Esc, Delete, C, i) keeps its keys here. packages/tui/test/keymap.test.mjs pins both.
11
+ // Ctrl+K, Tab, Esc, Delete, C, i, p) keeps its keys here. packages/tui/test/keymap.test.mjs pins both.
12
12
  import { CHORDS, DEFAULT_CHORD_FAMILY, LEADER_TABLE, PALETTE_KEYS, chordKeyOf, plainKeys } from "./client.mjs";
13
13
  // An action's words, for the help (views/help.mjs): a view takes the shared home's keymap through this module only.
14
14
  export { doesLabel } from "./client.mjs";
@@ -75,6 +75,12 @@ export const ACTIONS = Object.freeze([
75
75
  { id: "spawn-another", label: "spawn another", views: [["instances", "spawn another agent of the selected agent's soul: the preview, and Enter spawns it"], ["souls", "the same as n"]] },
76
76
  // Offered only while a spawn's outcome is not known: it asks the kernel once, never spawns again.
77
77
  { id: "spawn-check", keys: ["C"], label: "check spawn", views: [["instances", "check the result of a spawn whose outcome is not known, while one is"]] },
78
+ // Pinned instances (feature instance-pin; docs/tui.md, "Pinning"): at once, no confirmation (a pin only orders the
79
+ // list, and the same key undoes it). `p` is a new default key: a tui.json that gives it to another action is
80
+ // refused at the start with the line that says so (config.mjs), until that action moves or pin gets another key.
81
+ // Lower-case, unlike the four acts above: it opens no confirmation and changes nothing but the order. Its help
82
+ // line fits one row of the help: the shared pin and the feature's line are in docs/tui.md and on the status line.
83
+ { id: "pin", keys: ["p"], label: "pin", views: [["instances", "pin the selected agent at the top of its list or unpin it, as oats instance pin <name> on|off; needs instance-pin"]] },
78
84
  { id: "help", label: "help" },
79
85
  { id: "close", keys: ["escape"], label: "close" },
80
86
  { id: "quit", keys: ["q", "ctrl+c"], label: "quit" },
@@ -93,9 +99,10 @@ export const ACTIONS = Object.freeze([
93
99
  * and from any other focus it only cancels the leader (lib/store.mjs `twice`). */
94
100
  export const LEADER = LEADER_TABLE;
95
101
  /** What the leader does that no action of ACTIONS does (lib/store.mjs `led`): `workspace-previous`
96
- * and `workspace-next` (the workspace before or after the open one in the list of workspaces) and
97
- * `list` (the list's focus, which Esc gives). */
98
- export const LEADER_OWN = Object.freeze(["workspace-previous", "workspace-next", "list"]);
102
+ * and `workspace-next` (the workspace before or after the open one in the list of workspaces),
103
+ * `list` (the list's focus, which Esc gives), and `sidebar` (the shared table's `b`, the Desktop's
104
+ * sidebar: here the list, hidden by the shown terminal taking the whole screen, or given back). */
105
+ export const LEADER_OWN = Object.freeze(["workspace-previous", "workspace-next", "list", "sidebar"]);
99
106
  /** What a chord does that neither the leader's table nor an action does (lib/store.mjs `led`):
100
107
  * `tab-1` to `tab-8`, the focused group's Nth tab shown, and `tab-9`, its last (as the Desktop and
101
108
  * the browsers do). No key after the leader does them: LEADER has no row for them. */
@@ -12,6 +12,8 @@ export { cliDeploymentRead } from "../../client/deployment-read-cli.mjs";
12
12
  export { cliDeploymentList } from "../../client/deployment-list-cli.mjs";
13
13
  export { deploymentsListSupported } from "../../client/deployment-list.mjs";
14
14
  export { cliRemoteRoster } from "../../client/cli-adapter.mjs";
15
+ // Pinned instances (feature instance-pin): the pin key runs the kernel's verb, read by the shared home.
16
+ export { pinInstance } from "../../client/instance-pin.mjs";
15
17
  export { createDeploymentObserver, mapBounded, MAX_DEPLOYMENT_OBSERVATIONS } from "../../client/deployment-observer.mjs";
16
18
  export { createWarmReader } from "../../client/warm-reader.mjs";
17
19
  export { createRefreshLoop } from "../../client/refresh-loop.mjs";
@@ -23,7 +25,7 @@ export { remoteRosterState } from "../../client/remote-roster.mjs";
23
25
  export { observeIdentities, identityMemory } from "../../client/remote-identity-memory.mjs";
24
26
  export { workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION } from "../../client/workspace-choices.mjs";
25
27
  export { shortPath, deploymentLabel, machineLabels } from "../../client/deployment-label.mjs";
26
- export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree, hasInstanceChildren, heldHome, instanceSiblings, backgroundPlacement, BACKGROUND_FEATURE } from "../../client/instance-tree.mjs";
28
+ export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree, hasInstanceChildren, heldHome, instanceSiblings, backgroundPlacement, BACKGROUND_FEATURE, PIN_FEATURE } from "../../client/instance-tree.mjs";
27
29
  export { rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment, rosterSectionKey, sidebarSections } from "../../client/roster-sections.mjs";
28
30
  export { runtimeState, runtimeCounts, originLead, siblingText, instanceColor } from "../../client/instance-presentation.mjs";
29
31
  export { instanceDisplayName } from "../../client/instance-display-name.mjs";
@@ -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 };
@@ -209,10 +209,10 @@ the final values in one short message before you go on. The rules:
209
209
  - New: the **workspace name**: lowercase letters and digits, words joined
210
210
  by single `-` (`^[a-z0-9]+(?:-[a-z0-9]+)*$`), for example `acme`. Refuse
211
211
  `agents`: OATS keeps instance homes in a folder of that name. Default:
212
- their project's name (its repository's, or its folder's), normalised as
213
- in the machine's round, with repeated `-` collapsed and a leading or
214
- trailing `-` dropped (`My_App_` gives `my-app`); with no project, ask
215
- for a name.
212
+ their project's name: its repository's name when it has one, else its
213
+ folder's (the repository's wins when they differ), normalised as in the
214
+ machine's round, with repeated `-` collapsed and a leading or trailing
215
+ `-` dropped (`My_App_` gives `my-app`); with no project, ask for a name.
216
216
  - **New workspace: the host,** the one repository that holds the
217
217
  workspace's files:
218
218
  - **One repository (a monorepo):** that repository, the files at its root;
@@ -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.27.0 v1.46.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,
@@ -851,8 +856,8 @@ name: acme
851
856
  members:
852
857
  - git:github.com/acme/acme-oats # the host; the setup expert adds the others
853
858
  packages:
854
- oats.framework: v1.26.0 # the installed CLI's catalog versions (below)
855
- oats.aweb: v1.43.0 # messaging: agent identities, mail and chat
859
+ oats.framework: v1.27.0 # the installed CLI's catalog versions (below)
860
+ oats.aweb: v1.46.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:
@@ -902,7 +907,10 @@ workspace: git:github.com/acme/acme-oats
902
907
  repos/<owner>/<repo>/branches/<branch> --jq .protected` prints `true`,
903
908
  `gh api repos/<owner>/<repo>/rules/branches/<branch> --jq length` prints
904
909
  more than 0, or either fails), or the push is refused: push a branch
905
- instead, open a pull request, tell them, and stop until it is merged.
910
+ instead, open a pull request, tell them, and stop until it is merged. A
911
+ 403 from the rules read saying the feature needs an upgrade ("Upgrade to
912
+ GitHub Pro or make this repository public") is not a failure: the
913
+ repository's plan has no rulesets, so it counts as 0.
906
914
  - If `git config user.name` or `git config user.email` prints nothing in
907
915
  `D/<repo>`, commit with the name step 1's yes covered:
908
916
  `-c user.name="<their name>" -c user.email="<their noreply address>"`,
@@ -1019,6 +1027,30 @@ below; for another capability, follow its own setup skill, and stop if its
1019
1027
  readiness still reports a problem.
1020
1028
 
1021
1029
  **With aweb (`oats.aweb`):**
1030
+
1031
+ **Their own aweb server on a private registry (step 1): record it first,**
1032
+ before item 1, with `RG` written in. Skip this on the public registry and
1033
+ on hosted aweb.
1034
+
1035
+ ```bash
1036
+ cd "D" && oats aweb setup --soul S --registry RG
1037
+ ```
1038
+
1039
+ It writes only `settings.oats.aweb.registry` in `D/oats-local.yaml`, the
1040
+ one setting that admits a private registry here: every later `oats aweb`
1041
+ command and every agent of `D` reads its registry from it. Never set
1042
+ `AWID_REGISTRY_URL` instead: oats.aweb refuses a private registry given
1043
+ that way (`registry-setting-required`), item 1's check included, until
1044
+ this setting is recorded. Success prints one line of JSON whose
1045
+ `registry` is `RG` as an origin (the host in lowercase, no trailing `/`).
1046
+ Its `next` lists "Restart resident serve" and "Restart wake": both are
1047
+ expected and need nothing from you, since this new deployment has no
1048
+ resident yet and item 6 installs the broker after this. An
1049
+ `E_SETUP_REGISTRY` refusal that starts `settings.oats.aweb.registry:`
1050
+ says what is wrong with the address (a path, `/api`, a query): ask the
1051
+ person for the registry's origin again and run this again. Anything
1052
+ else: stop, spawn nothing, and tell the person what it shows.
1053
+
1022
1054
  1. **Check:**
1023
1055
 
1024
1056
  ```bash
@@ -1230,8 +1262,45 @@ readiness still reports a problem.
1230
1262
  `delivery: session`: its own channel wakes it (step 4). Any other setup
1231
1263
  expert is woken only by the host wake broker, and oats.aweb refuses to
1232
1264
  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:
1265
+ broker is the person's own user service, so it is theirs to start.
1266
+
1267
+ **On a private registry (step 1), first check the install yourself,**
1268
+ read-only: the broker must carry `RG`, and the status check below can't
1269
+ see which registry a running broker serves.
1270
+
1271
+ ```bash
1272
+ cd "D" && oats aweb wake install --plan --json
1273
+ ```
1274
+
1275
+ It changes nothing, and it refuses whatever the install would refuse.
1276
+ Only `"ok": true` lets you go on to their install below: then no other
1277
+ broker runs on this computer account, or the one that runs is the
1278
+ install's own and already carries `RG`, so the status check below
1279
+ proves the right broker. Otherwise its `error.code` decides:
1280
+ - **`E_WAKE_REGISTRY_CONFLICT`:** this computer account already runs a
1281
+ wake broker for another registry, or for none, most likely for
1282
+ another deployment, and one account's broker serves one registry.
1283
+ Stop, spawn nothing, and tell the person in plain words; the choice is
1284
+ theirs: run this deployment under another computer account, or move
1285
+ the other one, as the message says. Never uninstall the broker or
1286
+ deregister another deployment's homes yourself.
1287
+ - **`E_WAKE_UNSUPPORTED`** (a container, or a machine with neither
1288
+ launchd nor systemd): there is no service to install, and the plain
1289
+ `aw wake run` below would not carry `RG`. Stop and spawn nothing.
1290
+ Tell the person in one sentence, and offer a Claude or pi setup
1291
+ expert instead, which its own channel wakes: with that harness, this
1292
+ item is skipped.
1293
+ - **Any other refusal** (for example a broker started by hand or by
1294
+ another supervisor, `E_WAKE_RUNNING_UNSUPERVISED`, or a service the
1295
+ install didn't write, `E_WAKE_UNIT_CONFLICT`): stop and spawn nothing.
1296
+ A broker that is running now would pass the status check without
1297
+ carrying `RG`. Tell the person in plain words what its message says;
1298
+ the fix is theirs, and the message names it. Once they say it's done,
1299
+ run this check again. Never stop, uninstall or deregister a broker
1300
+ yourself.
1301
+
1302
+ Open their own terminal ("How to work") running this, with `D` filled
1303
+ in:
1235
1304
 
1236
1305
  ```text
1237
1306
  cd "D" && oats aweb wake install
@@ -1239,7 +1308,8 @@ readiness still reports a problem.
1239
1308
 
1240
1309
  In a container, or on a machine with neither launchd nor systemd (the
1241
1310
  command answers `E_WAKE_UNSUPPORTED`), there is no service to install:
1242
- the line is `aw wake run`, kept running as a supervised process.
1311
+ on the public registry, the line is `aw wake run`, kept running as a
1312
+ supervised process.
1243
1313
 
1244
1314
  Then check it yourself:
1245
1315
 
@@ -1323,8 +1393,10 @@ are cloned, knowledge tools, messaging wanted or not>
1323
1393
  the person (new workspace), or T owned by aweb account <handle>
1324
1394
  (signed in at step 5), or new account N signed up (machine found-list),
1325
1395
  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
1396
+ namespace ND, registry public | RG (recorded in
1397
+ `settings.oats.aweb.registry`), aw <tested> (oats.aweb's tested
1398
+ version) or "aw <version> is newer than the tested <tested>; kept", its
1399
+ key at
1328
1400
  <team key path> | not set up (the setup expert has no messaging)
1329
1401
  - Harness channel mode: development, confirmed by OATS at each start
1330
1402
  (Claude with aweb) | none (Codex, pi or no messaging)
@@ -1493,8 +1565,9 @@ the setup expert, not in this message. You are done.
1493
1565
  aweb server, checked against step 9's create.
1494
1566
  - **On their own aweb server:** make or touch the namespace's controller key
1495
1567
  (`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.
1568
+ `AWEB_API_KEY`, set `AWID_REGISTRY_URL` (a private registry is
1569
+ recorded by `oats aweb setup --registry` only), or write a hosted
1570
+ `default:…aweb.ai` team or `localTeams` into the workspace.
1498
1571
  - **Write a setup soul into the workspace:** the setup expert is
1499
1572
  `oats.framework`'s.
1500
1573
  - **The Desktop:** never download it through a browser, skip a verification