@awebai/oats 0.55.1 → 0.56.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/bin/oats.mjs +78 -62
  2. package/docs/capabilities.md +67 -3
  3. package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
  4. package/docs/desktop-cli-api.md +317 -35
  5. package/docs/desktop-instance-start.md +105 -12
  6. package/docs/desktop.md +54 -7
  7. package/docs/execution-targets.md +184 -9
  8. package/docs/harness-trust.md +128 -11
  9. package/docs/implementation.md +54 -7
  10. package/docs/integrations.md +1 -1
  11. package/docs/knowledge.md +35 -16
  12. package/docs/official-catalog.md +3 -3
  13. package/docs/packages.md +12 -12
  14. package/docs/release-lane.md +26 -1
  15. package/docs/release-notes/v0.56.0.md +699 -0
  16. package/docs/servers.md +21 -5
  17. package/docs/souls-and-instances.md +8 -4
  18. package/docs/tui.md +99 -26
  19. package/docs/upgrading.md +4 -1
  20. package/docs/workspaces.md +26 -6
  21. package/lib/automations.mjs +3 -4
  22. package/lib/bounded-read.mjs +18 -0
  23. package/lib/capability-show.mjs +13 -2
  24. package/lib/claim.mjs +3 -4
  25. package/lib/core.mjs +480 -152
  26. package/lib/errors.mjs +39 -0
  27. package/lib/harness-trust-write.mjs +119 -40
  28. package/lib/harness-trust.mjs +31 -18
  29. package/lib/instance-inspect.mjs +160 -11
  30. package/lib/instance-lifecycle.mjs +47 -30
  31. package/lib/packages.mjs +8 -5
  32. package/lib/pi-bridge.mjs +18 -19
  33. package/lib/remote.mjs +88 -51
  34. package/lib/retire-output.mjs +9 -4
  35. package/lib/schedule.mjs +3 -4
  36. package/lib/servers.mjs +39 -6
  37. package/lib/session-viewer.mjs +25 -1
  38. package/lib/triggers.mjs +3 -4
  39. package/lib/workspace.mjs +6 -6
  40. package/lib/worktree.mjs +10 -6
  41. package/lib/write-through-private-file.mjs +26 -0
  42. package/package-catalog.json +2 -2
  43. package/package.json +1 -1
  44. package/packages/client/cli-adapter.mjs +108 -13
  45. package/packages/client/cli-locator.mjs +16 -14
  46. package/packages/client/deployment-panel.mjs +4 -3
  47. package/packages/client/display-text.mjs +2 -1
  48. package/packages/client/instance-events-contract.mjs +4 -3
  49. package/packages/client/instance-lifecycle.mjs +228 -0
  50. package/packages/client/instance-presentation.mjs +9 -0
  51. package/packages/client/instance-tree.mjs +10 -8
  52. package/packages/client/kernel-lines.mjs +3 -3
  53. package/packages/client/launch-contract.mjs +11 -0
  54. package/packages/client/lifecycle-cli.mjs +12 -6
  55. package/packages/client/lifecycle-confirmation.mjs +407 -0
  56. package/packages/client/lifecycle-contract.mjs +6 -2
  57. package/packages/client/own-codes.mjs +1 -0
  58. package/packages/client/panel-views.mjs +39 -2
  59. package/packages/client/readiness-contract.mjs +2 -2
  60. package/packages/client/remote-roster.mjs +50 -5
  61. package/packages/client/roster-sections.mjs +3 -3
  62. package/packages/client/session-start.mjs +98 -0
  63. package/packages/client/start-gate.mjs +46 -0
  64. package/packages/client/start-messages.mjs +17 -0
  65. package/packages/client/workspace-views.mjs +2 -2
  66. package/packages/tui/README.md +10 -6
  67. package/packages/tui/lib/actions.mjs +4 -2
  68. package/packages/tui/lib/client.mjs +5 -2
  69. package/packages/tui/lib/config.mjs +39 -9
  70. package/packages/tui/lib/main.mjs +83 -13
  71. package/packages/tui/lib/model.mjs +116 -11
  72. package/packages/tui/lib/open.mjs +45 -0
  73. package/packages/tui/lib/read.mjs +46 -10
  74. package/packages/tui/lib/store.mjs +64 -9
  75. package/packages/tui/lib/term/tty.mjs +71 -12
  76. package/packages/tui/lib/views/frame.mjs +115 -33
  77. package/packages/tui/lib/views/help.mjs +37 -8
  78. package/skills/oats-getting-started/SKILL.md +6 -3
package/lib/servers.mjs CHANGED
@@ -609,7 +609,8 @@ export function listSnapshots(serverId) {
609
609
 
610
610
  /** Route one lifecycle command to a server. Returns the remote envelope,
611
611
  * having kept the local snapshot store in step with it:
612
- * - spawn: compatibility checked first, a snapshot written on success;
612
+ * - spawn: compatibility checked first, a snapshot written on success; a
613
+ * --preview runs the same checks, needs spawn-preview-2 and writes nothing;
613
614
  * - retire: the target comes from the instance's snapshot when one exists
614
615
  * (the registry may have changed since), the snapshot is removed only
615
616
  * when the remote kernel reports the home gone;
@@ -654,8 +655,24 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
654
655
  const status = runRemote(target, json(withScope(["status"])), io).envelope;
655
656
  if (!status.ok) return { envelope: status, stderr: "" };
656
657
  checkRemoteSupport(remote, target, oatsArgs, status.result);
658
+ // A preview answers what the apply would, refusals included (every check
659
+ // above), and writes nothing here (#610). Only a host that advertises
660
+ // spawn-preview-2 is proven to answer --preview without spawning.
661
+ const preview = oatsArgs.includes("--preview");
662
+ if (preview) requireRemoteFeature(remote, target, "spawn-preview-2");
657
663
  const { envelope, stderr } = runRemote(target, json(withScope(["spawn", ...hostHarnessArgs(remote, oatsArgs)])), io);
658
- if (envelope.ok && envelope.result?.instance) {
664
+ if (preview && envelope.ok && envelope.result?.preview === true && envelope.result.spawnPreviewApi === 2) {
665
+ // The host's preview with the two fields a routed spawn adds; never a
666
+ // `snapshot` key, which on the apply path says what was (or was not) saved.
667
+ const prior = envelope.result.instance ? readSnapshot(serverId, envelope.result.instance) : undefined;
668
+ const sameAsPrior = prior && prior.home && envelope.result.home && resolve(prior.home) === resolve(envelope.result.home);
669
+ const warnings = prior && !sameAsPrior
670
+ ? { warnings: [...(envelope.result.warnings || []), `a spawn would save no route: ${envelope.result.instance} already names ${prior.home} through ${serverId}; that instance (${envelope.result.home}) would not be managed from here, and would be retired on the host with oats retire ${envelope.result.instance} --home ${envelope.result.home}`] }
671
+ : {};
672
+ return { envelope: { ...envelope, result: { ...envelope.result, server: serverId, target, ...warnings } }, stderr };
673
+ }
674
+ // An answer that says it is a preview created nothing: it is never recorded as a route.
675
+ if (envelope.ok && envelope.result?.instance && envelope.result.preview !== true) {
659
676
  // A generated name can still collide with a saved route of another
660
677
  // soul on the same host (dev --purpose foo-1 vs dev-foo --purpose 1).
661
678
  // The existing route is never overwritten: the new instance is
@@ -765,6 +782,8 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
765
782
  // `inspect --instructions` (feature soul-composed-instructions): an older host would ignore the
766
783
  // flag and answer without the field — refused here instead, nothing sent.
767
784
  if (cmd === "inspect" && args.includes("--instructions")) requireRemoteFeature(remote, target, "soul-composed-instructions");
785
+ // `inspect --skills` (feature soul-skills): the same, for the soul's own skills.
786
+ if (cmd === "inspect" && args.includes("--skills")) requireRemoteFeature(remote, target, "soul-skills");
768
787
  const scoped = args.includes("--dir") || args.includes("--home") ? args : [...args, "--dir", target.workspace];
769
788
  const { envelope, stderr } = runRemote(target, json([cmd, ...scoped]), io);
770
789
  return { envelope: envelope.result && typeof envelope.result === "object" ? { ...envelope, result: { ...envelope.result, server: serverId, ...(route ? { route: { home: route.home, instance: route.snapshot?.instance || null, frozen: !!route.snapshot } } : {}) } } : envelope, stderr };
@@ -873,27 +892,41 @@ export function hostFeatures(result) {
873
892
  return [...list];
874
893
  }
875
894
 
876
- export async function rosterGroups({ server, io = {} } = {}) {
895
+ /** `workspaceKeys` (feature roster-workspace-key): when given, only the groups that can belong to
896
+ * one of those workspaces are probed and returned. A group is judged by its registration: kept
897
+ * when the registration's `workspaceKey` is one of the keys or is not known, dropped when it names
898
+ * another workspace (its saved routes under that target with it). A group with no registration
899
+ * (saved routes only) is always kept: its workspace is unknown, and it is the row an operator may
900
+ * need to forget. Keys compare by exact string equality, never parsed as a repo reference. */
901
+ export async function rosterGroups({ server, workspaceKeys, io = {} } = {}) {
877
902
  const started = Date.now();
878
903
  if (server && !ID_RE.test(server)) throw serverError("E_BAD_ARGS", `server id ${JSON.stringify(server)} is not a valid id`);
904
+ if (workspaceKeys !== undefined) {
905
+ if (!Array.isArray(workspaceKeys)) throw serverError("E_BAD_ARGS", "workspaceKeys must be a list of workspace keys");
906
+ for (const k of workspaceKeys) if (typeof k !== "string" || !WORKSPACE_KEY_RE.test(k)) throw serverError("E_BAD_ARGS", `--workspace-key ${JSON.stringify(k)} is not a canonical workspace key (as a host's oats status --json reports it: no whitespace or control characters)`);
907
+ }
879
908
  if (server && !readServers()[server] && !existsSync(join(REMOTE_SNAPSHOT_DIR(), server))) throw serverError("E_SERVER_UNKNOWN", `no server registered as ${JSON.stringify(server)} and no saved routes for it (oats server list)`);
880
909
  const perTargetTimeoutMs = io.perTargetTimeoutMs || ROSTER_PER_TARGET_TIMEOUT_MS;
881
910
  const budgetMs = io.budgetMs || ROSTER_BUDGET_MS;
882
911
  const timeoutMs = Math.min(perTargetTimeoutMs, budgetMs);
883
912
  const servers = readServers();
884
913
  const groups = new Map();
885
- const add = (serverId, target, registrationPresent, label) => {
914
+ const add = (serverId, target, registrationPresent, label, workspaceKey) => {
886
915
  const key = `${serverId}:${targetKey(target)}`;
887
916
  if (!groups.has(key)) groups.set(key, { id: key, server: serverId, label: label || serverId, registrationPresent, target, probe: null, agentsRoot: undefined, workspace: null, souls: [], instances: [], retireFailures: [], _snapshots: [] });
888
917
  const g = groups.get(key);
889
- if (registrationPresent) g.registrationPresent = true;
918
+ if (registrationPresent) { g.registrationPresent = true; g._workspaceKey = workspaceKey ?? null; }
890
919
  return g;
891
920
  };
892
- for (const [id, s] of Object.entries(servers)) { if (server && id !== server) continue; add(id, targetOf({ id, ...s }), true, s.label); }
921
+ for (const [id, s] of Object.entries(servers)) { if (server && id !== server) continue; add(id, targetOf({ id, ...s }), true, s.label, s.workspaceKey); }
893
922
  for (const serverId of listSnapshotServers()) {
894
923
  if (server && serverId !== server) continue;
895
924
  for (const snap of listSnapshots(serverId)) { if (!snap.target) continue; add(serverId, snap.target, false, servers[serverId]?.label)._snapshots.push(snap); }
896
925
  }
926
+ // The workspace filter applies to whole groups, before any probe: a group whose registration
927
+ // names another workspace is never asked.
928
+ if (workspaceKeys) for (const [key, g] of groups) if (g.registrationPresent && g._workspaceKey !== null && !workspaceKeys.includes(g._workspaceKey)) groups.delete(key);
929
+ for (const g of groups.values()) delete g._workspaceKey;
897
930
  // Groups keep their registration order in the answer, whatever order their probes finish in.
898
931
  await Promise.all([...groups.values()].map(async (g) => {
899
932
  let status;
@@ -36,6 +36,19 @@ const MOUSE_BINDINGS = [
36
36
  * A constant: no caller text is ever part of a tmux command string. */
37
37
  const DETACH_BINDING = "set-option @oats-detached 1 ; detach-client";
38
38
 
39
+ /** Whether a `tmux -V` answer names a release with the client's `-T <features>` flag (tmux 3.2):
40
+ * `tmux X.Y` with an optional letter suffix only. A development build (`tmux next-3.6`,
41
+ * `tmux master`), another vendor's spelling or no answer is not one. */
42
+ export function tmuxHasClientFeatures(versionText) {
43
+ const m = /^tmux (\d+)\.(\d+)[a-z]*$/.exec(String(versionText ?? "").trim());
44
+ if (!m) return false;
45
+ const [major, minor] = [Number(m[1]), Number(m[2])];
46
+ return major > 3 || (major === 3 && minor >= 2);
47
+ }
48
+ /** The probe's answer per `exec`: one `tmux -V` per process for the real one, and a fresh probe
49
+ * for each fake a test injects. */
50
+ const clientFeatures = new WeakMap();
51
+
39
52
  export function prepareSessionViewer(target, { exec = execFileSync, detachKey } = {}) {
40
53
  if (detachKey !== undefined) requireDetachKey(detachKey);
41
54
  if (!inspectSessionTarget(target, { exec }).present) throw new Error("session no longer exists");
@@ -81,7 +94,18 @@ export function prepareSessionViewer(target, { exec = execFileSync, detachKey }
81
94
  if (detachKey === undefined) return false;
82
95
  try { return run(["show-options", "-t", `=${viewer}:`, "-qv", "@oats-detached"]) === "1"; } catch { return false; }
83
96
  };
84
- return { binary: "tmux", args: ["-u", "-S", target.socket, "attach-session", "-t", `=${viewer}`], env, cleanup, detached };
97
+ // Synchronized output (DEC 2026) for this client alone, the tmux client's own option, before the
98
+ // command and after the socket (every viewer call starts `-u -S <socket>`): tmux then wraps each redraw in ESC[?2026h … ESC[?2026l, and a terminal that gets
99
+ // one in two reads does not paint the half-drawn state (#1193). A terminal without the mode
100
+ // ignores it. tmux before 3.2 has no -T, and a probe that fails leaves it out: never the
101
+ // attach's failure.
102
+ if (!clientFeatures.has(exec)) {
103
+ let sync = false;
104
+ try { sync = tmuxHasClientFeatures(run(["-V"])); } catch { /* no answer: today's client */ }
105
+ clientFeatures.set(exec, sync);
106
+ }
107
+ const features = clientFeatures.get(exec) ? ["-T", "sync"] : [];
108
+ return { binary: "tmux", args: ["-u", "-S", target.socket, ...features, "attach-session", "-t", `=${viewer}`], env, cleanup, detached };
85
109
  } catch (e) { cleanup(); throw e; }
86
110
  }
87
111
 
package/lib/triggers.mjs CHANGED
@@ -36,7 +36,7 @@
36
36
  * State: <scope>/.agents/schedules/triggers.json (gitignored with the schedule state). */
37
37
  import { spawnSync } from "node:child_process";
38
38
  import { createHash } from "node:crypto";
39
- import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
39
+ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
40
40
  import { dirname, join } from "node:path";
41
41
  import { fileURLToPath } from "node:url";
42
42
  import { readDefinitions, writeDefinitions, stateDir, withScopeLock, childEnv, parseEnvelopeText, schedulerStatus, readRegistry, definitionsPath, runWarnings } from "./schedule.mjs";
@@ -47,6 +47,7 @@ import { REFUSED_TEXT, safeText } from "./refused-text.mjs";
47
47
  import { lockedPackageRef } from "./packages.mjs";
48
48
  import { teamLabelProblem } from "./workspace.mjs";
49
49
  import { MAX_INSTANCE_NAME, slug } from "./core.mjs";
50
+ import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
50
51
 
51
52
  export const TRIGGER_API = 1;
52
53
  export const TRIGGER_SOURCES = Object.freeze(["github.pull_request"]);
@@ -377,9 +378,7 @@ const sameTrigger = (recorded, id) => recorded === id || (typeof recorded === "s
377
378
  function writeTriggerState(ws, st) {
378
379
  const file = statePath(ws);
379
380
  mkdirSync(dirname(file), { recursive: true });
380
- const tmp = `${file}.tmp-${process.pid}`;
381
- writeFileSync(tmp, JSON.stringify(st, null, 2) + "\n");
382
- renameSync(tmp, file);
381
+ writeThroughPrivateFile(file, `${file}.tmp-${process.pid}`, JSON.stringify(st, null, 2) + "\n");
383
382
  }
384
383
  /** What only a source's own polls write. A state written for another source has none of it, so a
385
384
  * trigger's row never shows one source's lists, counts or words (`skipped[].why`, a refusal's
package/lib/workspace.mjs CHANGED
@@ -202,7 +202,7 @@ function* refFields(value) {
202
202
  function referenceProblems(problems, refs) {
203
203
  const sources = new Map(refs);
204
204
  return problems.map((problem) => sources.has(problem.path)
205
- ? { ...problem, message: defaultRemote.redactUrl(problem.message, sources.get(problem.path), { known: false }) }
205
+ ? { ...problem, message: defaultRemote.displayDiagnosticText(problem.message, sources.get(problem.path)) }
206
206
  : problem);
207
207
  }
208
208
 
@@ -509,13 +509,13 @@ export async function confirmMembership(workspaceObs, memberRef, { remote: injec
509
509
  let key;
510
510
  try { key = refKey(remote, memberRef); }
511
511
  catch (e) {
512
- if (e?.code === "E_REPO_REF") return unconfirmed(defaultRemote.redactUrl(typeof memberRef === "string" ? memberRef : String(memberRef), null, { reference: true }), "not-listed", `${show(defaultRemote.redactUrl(memberRef, null, { reference: true }))} is not a repo ref: ${e.message}`);
512
+ if (e?.code === "E_REPO_REF") return unconfirmed(defaultRemote.displayRepoRef(typeof memberRef === "string" ? memberRef : String(memberRef)), "not-listed", `${show(defaultRemote.displayRepoRef(memberRef))} is not a repo ref: ${e.message}`);
513
513
  throw e;
514
514
  }
515
515
  if (!checked.keys.has(key)) return unconfirmed(key, "not-listed", `${key} is not in members of workspace ${workspaceObs.key}`);
516
516
  const cannotRead = (e) => {
517
- const url = defaultRemote.redactUrl(e.details?.url ?? e.provenance?.url ?? null, null, { reference: true });
518
- return unconfirmed(key, "cannot-read", `cannot read ${url ?? defaultRemote.redactUrl(memberRef, null, { reference: true })}${e.details?.reason ? ` (${e.details.reason})` : ""}`, { url });
517
+ const url = defaultRemote.displayRepoRef(e.details?.url ?? e.provenance?.url ?? null);
518
+ return unconfirmed(key, "cannot-read", `cannot read ${url ?? defaultRemote.displayRepoRef(memberRef)}${e.details?.reason ? ` (${e.details.reason})` : ""}`, { url });
519
519
  };
520
520
  let obs;
521
521
  try { obs = await remote.observeRemote(memberRef); }
@@ -538,7 +538,7 @@ export async function confirmMembership(workspaceObs, memberRef, { remote: injec
538
538
  let backlinkKey;
539
539
  try { backlinkKey = refKey(remote, read.value.workspace); }
540
540
  catch (e) {
541
- if (e?.code === "E_REPO_REF") return unconfirmed(key, "no-backlink", `${key}@${obs.commit.slice(0, 12)} oats-membership.yaml names an unparseable workspace ${show(defaultRemote.redactUrl(read.value.workspace, null, { reference: true }))}`, { commit: obs.commit });
541
+ if (e?.code === "E_REPO_REF") return unconfirmed(key, "no-backlink", `${key}@${obs.commit.slice(0, 12)} oats-membership.yaml names an unparseable workspace ${show(defaultRemote.displayRepoRef(read.value.workspace))}`, { commit: obs.commit });
542
542
  throw e;
543
543
  }
544
544
  if (backlinkKey !== workspaceObs.key) {
@@ -811,7 +811,7 @@ export async function discoverWorkspace(ref, { at, local, lock = null, remote: i
811
811
  const sourceRef = entry.source.slice(0, pin);
812
812
  const commit = entry.source.slice(pin + 1);
813
813
  const file = `${entry.soul.replace(/\/+$/, "")}/soul.yaml`;
814
- const pushProblem = (code, path, message) => { problems.push({ code, repoKey: null, path: `external/${index}:${path}`, message, source: defaultRemote.redactUrl(entry.source, null, { pinned: { ref: sourceRef, commit } }) }); if (!soulsUnread.external.includes(entry.source)) soulsUnread.external.push(entry.source); };
814
+ const pushProblem = (code, path, message) => { problems.push({ code, repoKey: null, path: `external/${index}:${path}`, message, source: defaultRemote.displayRepoRef(entry.source, { pinned: { ref: sourceRef, commit } }) }); if (!soulsUnread.external.includes(entry.source)) soulsUnread.external.push(entry.source); };
815
815
  let key;
816
816
  try { key = refKey(remote, sourceRef); }
817
817
  catch (e) { if (e?.code === "E_REPO_REF") { pushProblem("E_REPO_REF", "source", e.message); continue; } throw e; }
package/lib/worktree.mjs CHANGED
@@ -19,7 +19,7 @@
19
19
  * is passed after `--end-of-options` where the git subcommand honours it. The
20
20
  * remote URL is recorded, printed and handed to hooks without userinfo (A2). */
21
21
  import { execFileSync, spawn as spawnChild, spawnSync } from "node:child_process";
22
- import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
22
+ import { existsSync, linkSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
23
23
  import { basename, dirname, isAbsolute, join, resolve } from "node:path";
24
24
  import { checkHolderByHand, ifItDoesNotEnd, lifecycleBusy, nothingAfter, oatsError, OWN_START_REMEDY } from "./errors.mjs";
25
25
  import { appendEvent } from "./instance-events.mjs";
@@ -29,6 +29,7 @@ import { loadLocal } from "./workspace.mjs";
29
29
  import { GIT_FETCH_TIMEOUT_MS } from "./remote.mjs";
30
30
  import { terminateGroup, watchGroup } from "./process-group.mjs";
31
31
  import { CLAIM_WAIT_MS, acquireClaim, claimUnavailable, recordInClaim, releaseClaim, shownHolder } from "./claim.mjs";
32
+ import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
32
33
  import {
33
34
  cloneOfMember, instanceSoulDir, isCapturedHome, isWorkspaceHome, capturedHomeRefusal, preWorkspaceHome, lifecycleHookEnv,
34
35
  refuseBesideRetire, retirePendingMarkerPath, stableSoulId, workspaceOf,
@@ -227,16 +228,19 @@ function readRecord(path) {
227
228
  return { state: "unreadable" };
228
229
  }
229
230
  function writeRecord(path, rec) {
230
- const tmp = `${path}.tmp-${process.pid}`;
231
- writeFileSync(tmp, JSON.stringify(rec, null, 2) + "\n", { mode: 0o600 });
232
- renameSync(tmp, path);
231
+ writeThroughPrivateFile(path, `${path}.tmp-${process.pid}`, JSON.stringify(rec, null, 2) + "\n", 0o600);
233
232
  }
234
233
  /** Create the record only if none exists (two concurrent adds: one wins, the other sees it). */
235
234
  function createRecord(path, rec) {
236
235
  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
237
236
  const tmp = `${path}.tmp-${process.pid}`;
238
- writeFileSync(tmp, JSON.stringify(rec, null, 2) + "\n", { mode: 0o600 });
239
- try { linkSync(tmp, path); }
237
+ // Its own code, not the one writer (#1076): it puts the record in place with an exclusive link,
238
+ // which no rename does. The write is in the block whose finally removes the private file, so a
239
+ // write that fails once the file is made leaves nothing behind either.
240
+ try {
241
+ writeFileSync(tmp, JSON.stringify(rec, null, 2) + "\n", { mode: 0o600 });
242
+ linkSync(tmp, path);
243
+ }
240
244
  // Reached only when a record appeared after this add, which holds the purpose's claim, read that
241
245
  // there was none: whoever wrote it did not hold the claim, and whether it still runs was not read.
242
246
  catch (e) { if (e.code === "EEXIST") throw lifecycleBusy("unknown", `another oats worktree add of purpose ${rec.purpose} wrote ${path} at the same moment; nothing was done`, `check whether the process that record names still runs (its \`pid\`), then run the command again`, { purpose: rec.purpose, record: path }); throw e; }
@@ -0,0 +1,26 @@
1
+ /** The one writer of a file the kernel writes through a private file beside it (awebai/oats#1076).
2
+ * The rule, decided on awebai/oats#963: a private file is removed when its write or its rename
3
+ * fails, and the error answered is that failure's. A file system with no space makes the file and
4
+ * has no block for its bytes; nothing else would remove it, and each later attempt would leave one
5
+ * more. Dependency-free and synchronous, as every caller is.
6
+ *
7
+ * What differs between callers stays theirs to give: the private file's name (`<path>.tmp-<pid>`
8
+ * for most, a nonce or a leading dot for some: two processes writing one path never share it),
9
+ * the bytes (each makes its own JSON), and the mode the private file is created with. No caller
10
+ * syncs today, and this adds none. A caller that needs more than this (an exclusive create through
11
+ * a link, an exact mode, a failed removal reported) keeps its own code. */
12
+ import { renameSync, rmSync, writeFileSync } from "node:fs";
13
+
14
+ /** Write `bytes` to `privatePath`, created with `mode` when one is given (as writeFileSync applies
15
+ * it: on creation, less the umask), and rename it over `path`. When the write or the rename fails,
16
+ * the private file is removed and that failure's error is thrown; a failure of the removal itself
17
+ * is not answered. */
18
+ export function writeThroughPrivateFile(path, privatePath, bytes, mode) {
19
+ try {
20
+ writeFileSync(privatePath, bytes, mode !== undefined ? { mode } : undefined);
21
+ renameSync(privatePath, path);
22
+ } catch (e) {
23
+ try { rmSync(privatePath, { force: true }); } catch { /* the first error is the one answered */ }
24
+ throw e;
25
+ }
26
+ }
@@ -3,7 +3,7 @@
3
3
  "packages": {
4
4
  "oats.okf": {
5
5
  "url": "https://github.com/awebai/oats-okf.git",
6
- "ref": "v5.0.5",
6
+ "ref": "v5.1.0",
7
7
  "path": "oats-package"
8
8
  },
9
9
  "oats.aweb": {
@@ -43,7 +43,7 @@
43
43
  },
44
44
  "oats.framework": {
45
45
  "url": "https://github.com/awebai/oats.git",
46
- "ref": "oats-framework/v1.10.0",
46
+ "ref": "oats-framework/v1.10.1",
47
47
  "path": "oats-package"
48
48
  }
49
49
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.55.1",
3
+ "version": "0.56.0",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -23,7 +23,7 @@
23
23
  // * A provider operation names its instance by --home: the home of
24
24
  // exactly one row the server reports (packages/desktop/server/capabilities.mjs), never
25
25
  // a caller path.
26
- import { execFile } from "node:child_process";
26
+ import { execFile, spawn } from "node:child_process";
27
27
  import { mkdtempSync, openSync, writeSync, closeSync, rmSync } from "node:fs";
28
28
  import { tmpdir } from "node:os";
29
29
  import { isAbsolute, join } from "node:path";
@@ -62,6 +62,7 @@ const SPAWN_ARG_RULES = {
62
62
  backend: { flag: "--backend", re: /^tmux$/ },
63
63
  // The flag is the kernel's (harness-names.mjs harnessFlag): the caller names it, never guessed.
64
64
  harness: { flag: null, re: /^(pi|claude|codex)$/ },
65
+ // A configuration's name, or the word that selects none (launch-contract.mjs LAUNCH_CONFIG_NONE), which this rule admits.
65
66
  launchConfig: { flag: "--launch-config", re: /^[a-z0-9][a-z0-9._-]*$/i },
66
67
  server: { flag: "--server", re: /^[a-z0-9][a-z0-9-]{0,63}$/ }, // registered server id (remote route)
67
68
  model: { flag: "--model", re: /^[^-][^\0]*$/ }, // model pattern — not option-shaped
@@ -142,11 +143,19 @@ export function writeTaskFile(taskText, io = {}) {
142
143
  * owns through it). It passes the options through as given (cwd, env, timeout, maxBuffer, no shell)
143
144
  * and calls back with `execFile`'s own error: every caller tells a timeout by `error.killed` and an
144
145
  * overflow by `error.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER'`, so an `exec` that wraps or
145
- * replaces that error turns both into a plain failure. */
146
- function runJson(bin, argv, { cwd, exec = execFile, timeout = ENVELOPE_TIMEOUT_MS, parse = parseEnvelope, strictExit = false } = {}) {
146
+ * replaces that error turns both into a plain failure.
147
+ * `detached: true` is given for a stop or retire apply and for a start: the child must run in a session of
148
+ * its own, so a signal to the client's process group (a Ctrl-C, a hang-up) never reaches it (a killed stop
149
+ * strands its home on a kernel before 0.52.0; a killed start can leave its lock, #889). An `exec` must start
150
+ * such a child that way and never drop the option: `execFile` itself does not honour it (it passes spawn a
151
+ * fixed list of options), so this home's own default for it is `execFileInSession`. Such a child is given no
152
+ * deadline (`timeout: 0`, the default of an apply): execFileInSession arms its kill only for a positive one,
153
+ * and the caller's own wait ends instead (cliStart's START_WAIT_MS; instance-lifecycle.mjs APPLY_WAIT_MS). */
154
+ function runJson(bin, argv, { cwd, exec, timeout = ENVELOPE_TIMEOUT_MS, parse = parseEnvelope, strictExit = false, detached = false } = {}) {
155
+ const run = exec ?? (detached ? execFileInSession : execFile);
147
156
  return new Promise((resolveP, rejectP) => {
148
157
  try {
149
- exec(bin, argv, { cwd, encoding: "utf8", timeout, maxBuffer: 4 * 1024 * 1024, shell: false },
158
+ run(bin, argv, { cwd, encoding: "utf8", timeout, maxBuffer: 4 * 1024 * 1024, shell: false, ...(detached ? { detached: true } : {}) },
150
159
  (err, stdout) => {
151
160
  // New reads require a clean exit for success. Keep the historical
152
161
  // envelope-wins policy for existing mutations unless opted in.
@@ -300,6 +309,14 @@ export function cliServerRemove(bin, id, io = {}) {
300
309
  if (typeof id !== "string" || !MACHINE_ID.test(id)) return Promise.resolve(badMachineArgs());
301
310
  return runJson(bin, ["server", "remove", id, "--json"], { cwd: io.cwd || process.cwd(), exec: io.exec, timeout: io.timeout });
302
311
  }
312
+ /** `oats server forget <server> --instance <instance> --json` (#1131): drop this computer's saved route to a
313
+ * remote instance its host no longer lists. Both values are one roster row's identity, each one argv entry,
314
+ * never option-shaped. A clean exit is required for success (`strictExit`): an answer the CLI did not finish
315
+ * printing is the adapter's own error, never the kernel's. */
316
+ export function cliServerForget(bin, { server, instance } = {}, io = {}) {
317
+ if (!argText(server, 256) || !argText(instance, 256)) return Promise.resolve({ schemaVersion: 1, ok: false, error: { code: "E_BAD_ARGS", message: "Invalid forget arguments" } });
318
+ return runJson(bin, ["server", "forget", server, "--instance", instance, "--json"], { cwd: io.cwd || process.cwd(), exec: io.exec, timeout: io.timeout || 15_000, strictExit: true });
319
+ }
303
320
  /** `oats server connect <id> --ssh <host> --dir <folder on the host> [--install-oats] --json`, in the deployment's scope. */
304
321
  export function cliServerConnect(bin, { id, host, folder, installOats, workspaceDir }, io = {}) {
305
322
  if (machineFieldProblem({ id, host, folder }) || !absoluteReadPath(workspaceDir)) return Promise.resolve(badMachineArgs());
@@ -417,9 +434,24 @@ function parseRosterEnvelope(stdout) {
417
434
  return doc;
418
435
  }
419
436
 
420
- /** One bounded aggregate read; the CLI owns registry and saved-route resolution. */
437
+ /** A value the kernel takes for `server roster --workspace-key` (feature roster-workspace-key): a
438
+ * registration's key grammar (not empty, no whitespace or control character), and not an option
439
+ * (the kernel refuses a value that starts with `--`). */
440
+ export const ROSTER_WORKSPACE_KEY = /^(?!--)[^\s\x00-\x1f\x7f]{1,2048}$/;
441
+ /** At most this many keys in one read: one per open window. */
442
+ export const ROSTER_WORKSPACE_KEYS_MAX = 64;
443
+
444
+ /** One bounded aggregate read; the CLI owns registry and saved-route resolution. `io.workspaceKeys`, only
445
+ * for a CLI that lists `roster-workspace-key`: the read probes those workspaces' registrations (and those
446
+ * of unknown workspace, and saved routes) and no other; each is one `--workspace-key=<key>` argv element.
447
+ * None, or an empty list, is the unfiltered read. A key the kernel would refuse is refused here. */
421
448
  export function cliRemoteRoster(bin, io = {}) {
422
- return runJson(bin, ["server", "roster", "--json"], { cwd: io.cwd || process.cwd(), exec: io.exec, timeout: io.timeout || 60_000, parse: parseRosterEnvelope });
449
+ const keys = io.workspaceKeys ?? [];
450
+ if (!Array.isArray(keys) || keys.length > ROSTER_WORKSPACE_KEYS_MAX || !keys.every((k) => typeof k === "string" && ROSTER_WORKSPACE_KEY.test(k))) {
451
+ throw Object.assign(new Error("Invalid workspace keys for the roster read"), { code: "E_BAD_ARGS" });
452
+ }
453
+ const argv = ["server", "roster", ...[...new Set(keys)].map((k) => `--workspace-key=${k}`), "--json"];
454
+ return runJson(bin, argv, { cwd: io.cwd || process.cwd(), exec: io.exec, timeout: io.timeout || 60_000, parse: parseRosterEnvelope });
423
455
  }
424
456
 
425
457
  /** Local retire predates the envelope; preserve its incomplete-cleanup result. */
@@ -448,7 +480,9 @@ function flagFor(harnessFlag) {
448
480
  throw Object.assign(new Error("The kernel's harness flag was not named"), { code: "E_BAD_ARGS" });
449
481
  }
450
482
 
451
- /** Shared explicit launch choices; every value remains one argv entry. */
483
+ /** Shared explicit launch choices; every value remains one argv entry. `launchConfig` is a configuration's
484
+ * name or the word that selects none (launch-contract.mjs LAUNCH_CONFIG_NONE): `--launch-config none`
485
+ * asks for the bare harness, alone or beside a harness. */
452
486
  export function launchChoiceArgv({ launchConfig, harness, model, yolo, harnessFlag } = {}) {
453
487
  const argv = [];
454
488
  for (const [key, v] of Object.entries({ launchConfig, harness, model })) {
@@ -464,7 +498,56 @@ export function launchChoiceArgv({ launchConfig, harness, model, yolo, harnessFl
464
498
  return argv;
465
499
  }
466
500
 
467
- /** Start/restart is owned by the kernel, never a GUI stop-then-spawn pair. */
501
+ /** `execFile`'s shape, return and errors, for a child in a session of its own (`detached`: a new session and
502
+ * process group). `execFile` drops `detached`, so this is the `exec` a kernel caller of this home uses for a
503
+ * stop or retire apply and a start. Like `execFile` it collects stdout and stderr (`encoding`, default utf8),
504
+ * ends the child with `killSignal` (SIGTERM) when `timeout` (0: none) passes or an output passes `maxBuffer`,
505
+ * and calls back once the child's streams close: `(null, stdout, stderr)` on a clean exit; else an Error with
506
+ * `code` (the exit status, or a system code), `killed` and `signal`, or the overflow's own error, whose `code`
507
+ * is ERR_CHILD_PROCESS_STDIO_MAXBUFFER. stdin is a pipe, as `execFile`'s, that nobody writes. */
508
+ export function execFileInSession(bin, argv, options = {}, callback = () => {}) {
509
+ const { cwd, env, encoding = "utf8", timeout = 0, maxBuffer = 1024 * 1024, killSignal = "SIGTERM" } = options;
510
+ const child = spawn(bin, argv, { cwd, env, shell: false, detached: true, windowsHide: true });
511
+ const chunks = { stdout: [], stderr: [] }, sizes = { stdout: 0, stderr: 0 };
512
+ let ex = null, killed = false, timer = null, exited = false;
513
+ const text = name => { const all = Buffer.concat(chunks[name]); return encoding && encoding !== "buffer" ? all.toString(encoding) : all; };
514
+ function kill() { killed = true; try { child.kill(killSignal); } catch (error) { ex ??= error; exit(); } }
515
+ function exit(code = null, signal = null) {
516
+ if (exited) return; exited = true; clearTimeout(timer);
517
+ const stdout = text("stdout"), stderr = text("stderr");
518
+ if (!ex && code === 0 && signal === null) { callback(null, stdout, stderr); return; }
519
+ const cmd = [bin, ...argv].join(" ");
520
+ if (!ex) ex = Object.assign(new Error(`Command failed: ${cmd}\n${stderr}`), { code, killed: child.killed || killed, signal });
521
+ ex.cmd = cmd; callback(ex, stdout, stderr);
522
+ }
523
+ for (const name of ["stdout", "stderr"]) child[name].on("data", chunk => {
524
+ if (ex) return;
525
+ const room = maxBuffer - sizes[name];
526
+ if (chunk.length > room) {
527
+ chunks[name].push(chunk.subarray(0, Math.max(room, 0))); sizes[name] = maxBuffer;
528
+ ex = Object.assign(new RangeError(`${name} maxBuffer length exceeded`), { code: "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" }); kill(); return;
529
+ }
530
+ chunks[name].push(chunk); sizes[name] += chunk.length;
531
+ });
532
+ child.on("close", exit);
533
+ child.on("error", error => { ex = error; child.stdout?.destroy(); child.stderr?.destroy(); exit(); });
534
+ if (timeout > 0) { timer = setTimeout(kill, timeout); }
535
+ return child;
536
+ }
537
+
538
+ /** How long a client waits for a start's answer. The wait ends; the start does not. */
539
+ export const START_WAIT_MS = ENVELOPE_TIMEOUT_MS;
540
+
541
+ /** Start/restart is owned by the kernel, never a GUI stop-then-spawn pair. A start runs in a session of its own
542
+ * (`detached`, execFileInSession) with no deadline of its own (`timeout: 0`, no kill timer), so neither a signal
543
+ * to the client's group nor a deadline ends it (#889: a start killed mid-way can leave its lock). The client
544
+ * waits for its answer `io.wait` (START_WAIT_MS, 60 s); `io.after(ms, fn)` runs fn once after ms and answers a
545
+ * cancel. When the wait ends first, the start answers the code `E_START_UNCONFIRMED`, with no message: nothing is
546
+ * known of the start, and each client words that in its own words, under no speaker (it is not the kernel's).
547
+ * The child goes on: what it prints
548
+ * is still read, so it neither blocks on a full pipe nor writes to a closed one, and its answer, when it comes
549
+ * after the wait, is not kept. A start has no entry to keep it on, and its answer says nothing the roster
550
+ * does not: after a failed start the row is read again. */
468
551
  export function cliStart(bin, { home, workspaceDir, server, restart = false, ...choices }, io = {}) {
469
552
  if (typeof home !== "string" || !home.startsWith("/") || home.includes("\0")
470
553
  || (server !== undefined && (typeof server !== "string" || !/^[a-z0-9][a-z0-9-]{0,63}$/.test(server)))
@@ -474,11 +557,19 @@ export function cliStart(bin, { home, workspaceDir, server, restart = false, ...
474
557
  let options;
475
558
  try { options = launchChoiceArgv(choices); }
476
559
  catch (e) { return Promise.resolve({ schemaVersion: 1, ok: false, error: { code: e.code, message: e.message } }); }
477
- return runJson(bin, ["session", restart ? "restart" : "start", "--home", home,
560
+ const { wait = START_WAIT_MS, after = waitTimer } = io;
561
+ let cancel = () => {};
562
+ const answered = runJson(bin, ["session", restart ? "restart" : "start", "--home", home,
478
563
  ...(server ? ["--server", server] : []), ...options, "--json"], {
479
- cwd: workspaceDir, exec: io.exec, timeout: io.timeout,
564
+ cwd: workspaceDir, exec: io.exec, timeout: 0, detached: true,
565
+ }).finally(() => cancel());
566
+ const waited = new Promise((resolve) => {
567
+ cancel = after(wait, () => resolve({ schemaVersion: 1, ok: false, error: { code: "E_START_UNCONFIRMED" } }));
480
568
  });
569
+ return Promise.race([answered, waited]);
481
570
  }
571
+ /** A wait's timer that keeps no process alive: `after(ms, fn)` -> cancel. */
572
+ const waitTimer = (ms, fn) => { const timer = setTimeout(fn, ms); timer.unref?.(); return () => clearTimeout(timer); };
482
573
 
483
574
  /** Named configuration data travels in private JSON files, not shell text. */
484
575
  export async function cliLaunchConfig(bin, { action, name, definition, keepEnv, context, server, home, soul, agentsRoot, choices, localCwd }, io = {}) {
@@ -524,8 +615,8 @@ export function operationArgs(args) {
524
615
  return entries.flatMap(([k, v]) => ['--arg', `${k}=${v}`]);
525
616
  }
526
617
  /** `maxAge` (feature observe-max-age) is inspect's alone; `features` is the probe's list and
527
- * gates the flag, so an undeclared kernel gets the flagless argv even when a value is given. */
528
- export async function cliCapability(bin, { action, context, server, soul, agentsRoot, home, operation, args, localCwd, maxAge, instructions = false, features }, io = {}) {
618
+ * gates the flags (also `instructions` and `skills`), so an undeclared kernel gets the flagless argv even when a value is given. */
619
+ export async function cliCapability(bin, { action, context, server, soul, agentsRoot, home, operation, args, localCwd, maxAge, instructions = false, skills = false, features }, io = {}) {
529
620
  const bad = message => { throw Object.assign(new Error(message), { code: 'E_BAD_ARGS' }); };
530
621
  const value = (v, label) => {
531
622
  if (typeof v !== 'string' || !v || v.startsWith('-') || v.includes('\0')) bad(`Invalid ${label}`);
@@ -555,7 +646,11 @@ export async function cliCapability(bin, { action, context, server, soul, agents
555
646
  // row names the feature (packages/desktop: server/capabilities.mjs, renderer/composed-gate.mjs): a host without it refuses the flag.
556
647
  if (instructions && (action !== 'inspect' || !soul || home)) bad('Composed instructions belong to a soul inspection');
557
648
  const composed = instructions && Array.isArray(features) && features.includes('soul-composed-instructions') ? ['--instructions'] : [];
558
- return await runJson(bin, [...argv, ...target, ...composed, ...maxAgeArgv(features, maxAge), '--json'], {
649
+ // --skills (feature soul-skills) adds the soul's own skills (souls[0].skills): inspect --soul only, gated the same
650
+ // way; routed, the caller asks only for a host whose roster row names soul-skills (composed-gate.mjs hostReportsSkills).
651
+ if (skills && (action !== 'inspect' || !soul || home)) bad('Skills belong to a soul inspection');
652
+ const skillsArgv = skills && Array.isArray(features) && features.includes('soul-skills') ? ['--skills'] : [];
653
+ return await runJson(bin, [...argv, ...target, ...composed, ...skillsArgv, ...maxAgeArgv(features, maxAge), '--json'], {
559
654
  cwd: localCwd, exec: io.exec, timeout: io.timeout ?? (action === 'run' ? 300_000 : ENVELOPE_TIMEOUT_MS),
560
655
  });
561
656
  }
@@ -13,7 +13,7 @@
13
13
  // Every candidate is canonicalized to an absolute executable and accepted
14
14
  // ONLY if executable and `<bin> version --json` returns the v1 probe:
15
15
  // {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
16
- // Desktop accepts desktopApi === 1 and semver >=0.25.8 <0.56.0 (the band is
16
+ // Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.57.0 (the band is
17
17
  // spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
18
18
  // API version — not source adjacency — is authoritative.
19
19
  //
@@ -44,17 +44,15 @@ export const DESKTOP_API = 1;
44
44
  // surface (`version --json` probe, `spawn --json`, the retained lifecycle
45
45
  // verbs — test/cli-json-contract.test.mjs) is unchanged; the removed verbs
46
46
  // (`catalog`, install/use/…) surface as typed E_USAGE through the adapter.
47
- // Widened through 0.26.x for package-approval removal (F2b, maintainer
48
- // decision): the floor is 0.25.8 — not 0.26.0 — because main's kernel keeps
49
- // reporting 0.25.8 until 0.26.0 is tagged, and the Desktop must run against
50
- // it. The REAL gate is the positive `packages-no-approval` feature fence
51
- // (workspace-cli WORKSPACE_FEATURES, deployment-contract DEPLOYMENT_FEATURES):
52
- // released 0.25.x kernels lack it and get the "update OATS" state.
47
+ // Widened through 0.26.x for package-approval removal (F2b). The floor is
48
+ // the first kernel the Desktop's feature gates let through (workspace-cli
49
+ // WORKSPACE_FEATURES, deployment-contract DEPLOYMENT_FEATURES); those gates
50
+ // stay the REAL gate.
53
51
  // Widened through 0.43.x for the 0.43.0 release: schedule and trigger rows
54
52
  // carry a `description` for every kind and `<kind> update <id> --description`
55
53
  // sets one (feature `automation-descriptions`, which gates the Desktop's
56
54
  // summary writes). The Desktop v1 surface is otherwise unchanged.
57
- export const ACCEPT_RANGE = { min: [0, 25, 8], maxExclusive: [0, 56, 0] };
55
+ export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 57, 0] };
58
56
  /** The band as humans read it — derived, never hand-spelled, so the probe
59
57
  * rejection reason, the backend's /api status and the degradation card can
60
58
  * never disagree with the numbers actually enforced above. */
@@ -109,7 +107,10 @@ export function parseSemver(v) {
109
107
  }
110
108
  const cmp = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
111
109
 
112
- /** Accept/reject one probe payload. Returns { ok } or { ok:false, reason }. */
110
+ /** Accept/reject one probe payload. Returns { ok } or { ok:false, reason }, and { ok:false, reason, above:true }
111
+ * when the payload's sole failure is a released version at or above the band's ceiling: every other check
112
+ * passed first, so a prerelease, an unparsable version or another API is never `above`. A Desktop older than
113
+ * its CLI says so from this flag (views/cli-status.mjs), never from the reason's words. */
113
114
  export function acceptProbe(payload) {
114
115
  if (!payload || typeof payload !== "object") return { ok: false, reason: "no probe payload" };
115
116
  if (payload.schemaVersion !== 1) return { ok: false, reason: `unexpected schemaVersion ${payload.schemaVersion}` };
@@ -122,9 +123,8 @@ export function acceptProbe(payload) {
122
123
  // in-range version is not a released CLI — Desktop pairs with released
123
124
  // kernels only.
124
125
  if (v.prerelease) return { ok: false, reason: `prerelease version ${payload.version} not accepted (need a released ${ACCEPT_RANGE_TEXT})` };
125
- if (cmp(v.nums, ACCEPT_RANGE.min) < 0 || cmp(v.nums, ACCEPT_RANGE.maxExclusive) >= 0) {
126
- return { ok: false, reason: `version ${payload.version} outside ${ACCEPT_RANGE_TEXT}` };
127
- }
126
+ if (cmp(v.nums, ACCEPT_RANGE.maxExclusive) >= 0) return { ok: false, reason: `version ${payload.version} outside ${ACCEPT_RANGE_TEXT}`, above: true };
127
+ if (cmp(v.nums, ACCEPT_RANGE.min) < 0) return { ok: false, reason: `version ${payload.version} outside ${ACCEPT_RANGE_TEXT}` };
128
128
  return { ok: true };
129
129
  }
130
130
 
@@ -211,7 +211,9 @@ export function cliRecord(payload, { bin, source }) {
211
211
  * evaluated lazily: expensive helpers never run once a candidate wins.
212
212
  * Returns:
213
213
  * { ok:true, bin, source, version }
214
- * { ok:false, tried: [{path, source, reason}] } — stable diagnostics
214
+ * { ok:false, tried: [{path, source, reason}] } — stable diagnostics; an entry whose probe was
215
+ * refused only for being above the band also has
216
+ * `version` and `above: true` (acceptProbe)
215
217
  */
216
218
  export async function discover(io, probe) {
217
219
  const tried = [];
@@ -238,7 +240,7 @@ export async function discover(io, probe) {
238
240
  }
239
241
  const a = acceptProbe(payload);
240
242
  if (a.ok) return cliRecord(payload, { bin: path, source: src.source });
241
- tried.push({ path, source: src.source, reason: a.reason, version: payload?.version });
243
+ tried.push({ path, source: src.source, reason: a.reason, version: payload?.version, ...(a.above === true ? { above: true } : {}) });
242
244
  }
243
245
  }
244
246
  return { ok: false, tried };
@@ -12,7 +12,7 @@
12
12
  * test/inventory.test.mjs holds that its page reaches no module that imports a Node builtin. */
13
13
  import { dirname } from 'node:path';
14
14
  import { livenessOrigin } from './liveness.mjs';
15
- import { knownOrigin, hasRuntimeError } from './instance-presentation.mjs';
15
+ import { knownOrigin, hasRuntimeError, byRuntimeState } from './instance-presentation.mjs';
16
16
 
17
17
  const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
18
18
 
@@ -109,7 +109,8 @@ export function panelInstance(i) {
109
109
  };
110
110
  }
111
111
 
112
- /** The panel's rows: each row merged with its liveness answer and projected, running first, then by name.
112
+ /** The panel's rows: each row merged with its liveness answer and projected, in the roster's order
113
+ * (`byRuntimeState`: running, unknown, stopped; by name within each).
113
114
  * `answers` are `livenessAnswers`'.
114
115
  *
115
116
  * The merged row's `runtimeErrorOrigin` is set here or removed, whatever the row carried: when the
@@ -120,7 +121,7 @@ export function panelInstances(rows, answers) {
120
121
  const answer = answers[index], { runtimeErrorOrigin: _carried, ...merged } = { ...row, ...answer };
121
122
  const origin = record(answer) && Object.hasOwn(answer, "runtimeError") ? answer.runtimeErrorOrigin : "kernel";
122
123
  return panelInstance(hasRuntimeError(merged) ? { ...merged, runtimeErrorOrigin: origin } : merged);
123
- }).sort((a, b) => (a.running === b.running ? String(a.instance).localeCompare(b.instance) : a.running ? -1 : 1));
124
+ }).sort(byRuntimeState);
124
125
  }
125
126
 
126
127
  /** A deployment's entry before the first CLI probe has settled, when there is no verdict to report:
@@ -19,7 +19,8 @@ const EVERY_NOT_NOTE_TEXT = new RegExp(NOT_NOTE_TEXT.source, 'gu');
19
19
  * what follows stops at the next `/`, and every `://` holds one. Asked only whether it matches: this form
20
20
  * and the scheme-first one match the same texts, not the same part of them. */
21
21
  export const UNSAFE = /[\x00-\x08\x0b-\x1f\x7f]|:\/\/(?<=[a-z][a-z0-9+.-]*:\/\/)[^\s/]*@|(?:token|authorization|password|secret|api[_ -]?key)\s*[:=]\s*\S+|(?:gh[pousr]_|github_pat_)[A-Za-z0-9_]{16,}/i;
22
- export const DETAIL_WITHHELD = '[Detail withheld]';
22
+ /** What stands in for a withheld text. The name is kept on purpose until the terminal client's own change renames it. */
23
+ export const DETAIL_WITHHELD = '[withheld]';
23
24
  export const MAX_DISPLAY_LINE = 2048;
24
25
 
25
26
  /** One line: tab, line feed and the line and paragraph separators each become a space, runs of spaces