@awebai/oats 0.69.23 → 0.70.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 (88) hide show
  1. package/bin/oats.mjs +112 -20
  2. package/docs/capabilities.md +697 -11
  3. package/docs/capability-manifest.schema.json +66 -0
  4. package/docs/configuration.md +27 -7
  5. package/docs/design/2026-11-19-sandboxes.md +595 -121
  6. package/docs/design/2026-11-20-provider-home-lifecycle.md +322 -0
  7. package/docs/design/README.md +7 -3
  8. package/docs/desktop-cli-api.md +330 -9
  9. package/docs/desktop.md +181 -48
  10. package/docs/execution-targets.md +210 -4
  11. package/docs/first-team.md +11 -0
  12. package/docs/implementation.md +24 -3
  13. package/docs/integrations.md +2 -2
  14. package/docs/knowledge-capability-authoring.md +1 -1
  15. package/docs/knowledge-reference/proposal.md +10 -0
  16. package/docs/knowledge.md +20 -11
  17. package/docs/official-catalog.md +2 -2
  18. package/docs/packages.md +7 -7
  19. package/docs/release-notes/v0.69.24.md +264 -0
  20. package/docs/release-notes/v0.70.0.md +155 -0
  21. package/docs/souls-and-instances.md +57 -0
  22. package/docs/trust-model.md +8 -1
  23. package/docs/tui.md +21 -1
  24. package/docs/upgrading.md +19 -5
  25. package/docs/workspaces.md +13 -5
  26. package/lib/automation-scope.mjs +1 -1
  27. package/lib/capability-show.mjs +20 -1
  28. package/lib/command-flags.mjs +2 -2
  29. package/lib/compile-cache.mjs +1 -1
  30. package/lib/core.mjs +1455 -203
  31. package/lib/errors.mjs +4 -1
  32. package/lib/home-integrity.mjs +329 -0
  33. package/lib/hook-env.mjs +107 -0
  34. package/lib/host-run.mjs +11 -3
  35. package/lib/instance-events.mjs +32 -5
  36. package/lib/instance-git.mjs +9 -0
  37. package/lib/instance-inspect.mjs +107 -9
  38. package/lib/instance-lifecycle.mjs +15 -3
  39. package/lib/instance-listing.mjs +101 -8
  40. package/lib/instance-resolution.mjs +85 -2
  41. package/lib/instance-upgrade.mjs +170 -14
  42. package/lib/kernel-features.mjs +10 -1
  43. package/lib/node-version.mjs +9 -0
  44. package/lib/provider-call-child.mjs +60 -0
  45. package/lib/provider-resume.mjs +83 -0
  46. package/lib/provider-test-seams.mjs +20 -0
  47. package/lib/read-call.mjs +2 -0
  48. package/lib/remote.mjs +33 -1
  49. package/lib/reserved-launch-env.mjs +8 -1
  50. package/lib/retire-admission.mjs +12 -1
  51. package/lib/sandbox-allowances.mjs +329 -0
  52. package/lib/schedule.mjs +14 -4
  53. package/lib/servers.mjs +38 -5
  54. package/lib/session-inspect.mjs +123 -87
  55. package/lib/session-providers.mjs +575 -0
  56. package/lib/session-receipt.mjs +93 -0
  57. package/lib/session-resume.mjs +68 -15
  58. package/lib/stable-node.mjs +3 -0
  59. package/lib/triggers.mjs +3 -1
  60. package/lib/upgrade-state.mjs +6 -1
  61. package/lib/worktree-hooks.mjs +18 -2
  62. package/lib/worktree.mjs +21 -7
  63. package/package-catalog.json +2 -2
  64. package/package.json +2 -1
  65. package/packages/client/capability-list.mjs +21 -0
  66. package/packages/client/cli-adapter.mjs +19 -4
  67. package/packages/client/cli-locator.mjs +5 -1
  68. package/packages/client/deployment-data.mjs +23 -1
  69. package/packages/client/deployment-panel.mjs +25 -3
  70. package/packages/client/home-board.mjs +33 -19
  71. package/packages/client/inspect-boundary.mjs +18 -8
  72. package/packages/client/instance-acts.mjs +30 -3
  73. package/packages/client/instance-board.mjs +206 -0
  74. package/packages/client/instance-presentation.mjs +55 -0
  75. package/packages/client/liveness.mjs +15 -4
  76. package/packages/client/own-codes.mjs +5 -1
  77. package/packages/client/remote-roster.mjs +6 -1
  78. package/packages/client/session-backends.mjs +31 -0
  79. package/packages/client/session-start.mjs +18 -6
  80. package/packages/client/spawn-apply-cli.mjs +5 -3
  81. package/packages/client/spawn-apply-contract.mjs +25 -2
  82. package/packages/client/spawn-apply.mjs +5 -1
  83. package/packages/client/spawn-messages.mjs +3 -0
  84. package/packages/client/terminal-contract.mjs +4 -0
  85. package/packages/client/waiting-on-you.mjs +12 -2
  86. package/packages/tui/lib/model.mjs +14 -3
  87. package/packages/tui/lib/store.mjs +12 -3
  88. package/skills/oats-getting-started/SKILL.md +3 -3
package/lib/servers.mjs CHANGED
@@ -35,7 +35,9 @@ import { shellWord } from "./shell-word.mjs";
35
35
  import { DETACH_KEY_FEATURE, requireDetachKey } from "./session-viewer.mjs";
36
36
  import { LOGIN_CAPTURE_MAX_BYTES, LOGIN_SHELLS, loginPathEmitter, quoteFor, readLoginFrame } from "./login-environment.mjs";
37
37
  import { compareSemver } from "./semver.mjs";
38
- import { SPAWN_TASK_STDIN_FEATURE } from "./kernel-features.mjs";
38
+ import { SESSION_PROVIDERS_FEATURE, SPAWN_TASK_STDIN_FEATURE } from "./kernel-features.mjs";
39
+ import { relayedProviderRow, withoutRelayedEndpoint } from "./session-providers.mjs";
40
+ import { readModuleCopy } from "./home-integrity.mjs";
39
41
  import { sameRepo } from "./repo-moves.mjs";
40
42
  import { OATS_PACKAGE_NAME } from "./version.mjs";
41
43
  import { readRemoteBoard } from "./instance-board.mjs";
@@ -330,9 +332,24 @@ export function operatorSshArgv(alias, words) {
330
332
 
331
333
  // ------------------------------------------------------------------ running
332
334
 
335
+ /** A host's envelope without a session provider's locator (feature session-providers): a provider
336
+ * home's endpoint, and the thread id a status row carries on its own host, are for the host where
337
+ * the home lives, and are never relayed. An answer's own `session` (a spawn's, a start's, an
338
+ * inspect's) and every roster row's are cut to `{ provider }`, whatever the host sent. */
339
+ function withoutProviderLocators(envelope) {
340
+ const result = envelope?.result;
341
+ if (envelope?.ok !== true || !result || typeof result !== "object") return envelope;
342
+ const rows = (agents) => agents.map((a) => (a && Array.isArray(a.instances) ? { ...a, instances: a.instances.map(withoutRelayedEndpoint) } : a));
343
+ const roster = (doc) => (doc && Array.isArray(doc.agents) ? { ...doc, agents: rows(doc.agents) } : doc);
344
+ const cut = Array.isArray(result.roots) ? { ...result, roots: result.roots.map(roster) } : roster(withoutRelayedEndpoint(result));
345
+ return { ...envelope, result: cut };
346
+ }
333
347
  /** Parse the remote kernel's JSON envelope; anything else on stdout is a
334
348
  * routing failure with the raw text attached, never a guess. */
335
349
  export function parseRemoteEnvelope(stdout) {
350
+ return withoutProviderLocators(parseRemoteEnvelopeAsSent(stdout));
351
+ }
352
+ function parseRemoteEnvelopeAsSent(stdout) {
336
353
  const text = String(stdout || "").trim();
337
354
  let doc;
338
355
  try {
@@ -499,6 +516,7 @@ export function dropRemoteProbes(serverId) {
499
516
 
500
517
  function probeRemote(target, io) {
501
518
  const { envelope } = runRemote(target, ["version", "--json"], { ...io, timeoutMs: 60000 });
519
+ if (!envelope.ok) throw relayedFailure(envelope, "version --json");
502
520
  const probe = envelope.result || {};
503
521
  if (probe.desktopApi !== 1 || typeof probe.version !== "string") {
504
522
  throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats at ${target.sshHost} answered an unknown version payload: ${JSON.stringify(probe).slice(0, 200)}`);
@@ -561,7 +579,10 @@ export function checkRemoteSupport(remote, target, oatsArgs, roster) {
561
579
  // A wake schedule at spawn is saved by the host: it must advertise schedules.
562
580
  if (["--wake-json", "--wake-every", "--wake-cron"].some((f) => oatsArgs.includes(f)) && !remote.features.includes("schedule")) refuse("a wake schedule at spawn (the host must advertise the schedule feature)");
563
581
  const backend = flagOf("--backend");
564
- if (backend && !remote.sessionBackends.includes(backend)) refuse(`session backend ${backend}`);
582
+ // A backend that is none of the host's built-in ones is a session provider (a capability's, resolved
583
+ // against the instance's modules there): relayed only to a host that lists the feature. A host
584
+ // without it knows tmux alone, and is never asked for another.
585
+ if (backend && !remote.sessionBackends.includes(backend) && !remote.features.includes(SESSION_PROVIDERS_FEATURE)) refuse(`session backend ${backend} (a session provider: the host must advertise ${SESSION_PROVIDERS_FEATURE})`);
565
586
  if (oatsArgs.includes("--yolo") && !remote.launchOptions.includes("yolo")) refuse("the yolo launch option");
566
587
  return { harness, backend, yolo: oatsArgs.includes("--yolo") };
567
588
  }
@@ -1129,6 +1150,14 @@ const rowBoard = (i) => (Object.hasOwn(i, "board") ? { board: readRemoteBoard(i.
1129
1150
  /** `retire` (feature status-retire-state) as `waitingOnYou` is, relayed ONLY when the host's row has the
1130
1151
  * key: a host whose kernel predates the feature omits it, and its rows say nothing. Absent is the
1131
1152
  * only reading of "no retire", so a value the kernel's own read refuses is dropped, never null. */
1153
+ /** `moduleCopy` (a provider home's: which copy of its modules its kernel runs, and whether the home's
1154
+ * record of them is the receipt's; lib/home-integrity.mjs) as `retire` is: relayed ONLY when the
1155
+ * host's row has the key and this kernel's own read takes its value. A tmux home's row, and a
1156
+ * host whose kernel predates it, say nothing. */
1157
+ const rowModuleCopy = (i) => {
1158
+ const moduleCopy = Object.hasOwn(i, "moduleCopy") ? readModuleCopy(i.moduleCopy) : undefined;
1159
+ return moduleCopy ? { moduleCopy } : {};
1160
+ };
1132
1161
  const rowRetire = (i) => {
1133
1162
  const retire = Object.hasOwn(i, "retire") ? readRetireState(i.retire) : undefined;
1134
1163
  return retire ? { retire } : {};
@@ -1246,10 +1275,12 @@ export async function rosterGroups({ server, workspaceKeys, io = {} } = {}) {
1246
1275
  const snap = routeOf(i);
1247
1276
  g.instances.push({
1248
1277
  server: g.server, instance: i.instance, agent: a.name, home: i.home || snap?.home, agentsRoot: result.root,
1249
- harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null,
1278
+ // A session provider's row (feature session-providers): its backend's name, `session`, `open`
1279
+ // and `runtimeState`, relayed in the kernel's own shapes only (relayedProviderRow).
1280
+ harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null, ...(relayedProviderRow(i) ?? {}),
1250
1281
  ...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
1251
1282
  running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
1252
- ...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowPinned(i), ...rowBoard(i), ...rowRelatedWork(i, g.probe.features), ...rowSessionEnd(i),
1283
+ ...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowModuleCopy(i), ...rowBackground(i), ...rowPinned(i), ...rowBoard(i), ...rowRelatedWork(i, g.probe.features), ...rowSessionEnd(i),
1253
1284
  // Every row the host reports is addressed by its home, saved
1254
1285
  // route or not; savedRoute says only that it was spawned from here.
1255
1286
  retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, addressable: true, missingRemotely: false,
@@ -1663,7 +1694,9 @@ function probeHostOats(target, io) {
1663
1694
  const r = runHostCommand(target, [target.oatsPath, "version", "--json"], { ...io, timeoutMs: 60000 });
1664
1695
  if (r.status === 255) throw sshFailed(target, r);
1665
1696
  if (r.status === 126 || r.status === 127) return { missing: true };
1666
- const probe = parseRemoteEnvelope(r.stdout).result || {};
1697
+ const envelope = parseRemoteEnvelope(r.stdout);
1698
+ if (!envelope.ok) throw relayedFailure(envelope, "version --json");
1699
+ const probe = envelope.result || {};
1667
1700
  if (probe.desktopApi !== 1 || typeof probe.version !== "string") throw serverError("E_REMOTE_INCOMPATIBLE", `${target.oatsPath} at ${target.sshHost} answered an unknown version payload: ${JSON.stringify(probe).slice(0, 200)}`);
1668
1701
  return { version: probe.version, features: Array.isArray(probe.features) ? probe.features.map(String) : [] };
1669
1702
  }
@@ -1,14 +1,17 @@
1
- /** inspectInstanceSession: what a home's tmux session is, read under the home's runtime authority (its
2
- * recorded launch and receipts, the retirement baseline, the Herdr refusal) and the agent pane's
3
- * liveness. A leaf (awebai/oats#1630): `oats session inspect` reads it without loading core.mjs, which
1
+ /** inspectInstanceSession: what a home's session is, read under the home's runtime authority (its
2
+ * recorded launch and receipts, the retirement baseline, the Herdr refusal): a tmux session's agent
3
+ * pane and its liveness, or, for a home on a session provider (lib/session-providers.mjs), the
4
+ * provider's own answer. A leaf (awebai/oats#1630): `oats session inspect` reads it without loading core.mjs, which
4
5
  * imports these helpers and re-exports what it exported. */
5
6
  import { realPathOrNearest, canonicalHomePath } from "./real-path.mjs";
6
- import { existsSync, readFileSync, lstatSync } from "node:fs";
7
- import { isAbsolute, join, resolve, dirname, basename } from "node:path";
8
- import { createHash } from "node:crypto";
7
+ import { existsSync, readFileSync } from "node:fs";
8
+ import { isAbsolute, join, resolve, basename } from "node:path";
9
+ import { RETIRE_BASELINE_VERSION, findRetirementBaseline, instancesRetirementRoot, isPlainObject, legacyRetirementBaselinePath, readJsonOrUndefined, receiptHomeIdentity, receiptRecordsHome, retirementBaselinePath } from "./session-receipt.mjs";
9
10
  import { inspectSessionTarget } from "./session-input.mjs";
10
11
  import { liveWaiting } from "./instance-events.mjs";
11
12
  import { oatsError, herdrInstanceRemoved } from "./errors.mjs";
13
+ import { receiptTrust, trustedRecord } from "./home-integrity.mjs";
14
+ import { homeSessionProvider, isSessionProviderName, inspectProviderSession, launchSentOf, providerEndpointDifferences, providerRuntimeOf, unsettledLaunchSaid } from "./session-providers.mjs";
12
15
 
13
16
  /** A cleanup descriptor is usable only if it can DRIVE the retry, so it is checked
14
17
  * as the strict contract its one producer writes — the rollback above — and to the
@@ -27,76 +30,6 @@ import { oatsError, herdrInstanceRemoved } from "./errors.mjs";
27
30
  *
28
31
  * Anything else reads as ABSENT — no more retryable than a missing marker — so the
29
32
  * home fails closed by default and `--force` can clear it. */
30
- function isPlainObject(v) { return !!v && typeof v === "object" && !Array.isArray(v); }
31
-
32
- // The stored digests are versioned apart (`digestVersion`, BASELINE_DIGEST_VERSION): this version
33
- // also gates runtime, directory-home and provider-exclusion authority, so a bump would refuse them all.
34
- const RETIRE_BASELINE_VERSION = 2;
35
-
36
- function retirementStateRoot(home) {
37
- // Independent of the bytes it authenticates, but colocated with the agent's
38
- // already instance-owned storage rather than the source repository or user
39
- // config home. Retiring <instances>/<name> never removes this sibling.
40
- return instancesRetirementRoot(dirname(home));
41
- }
42
- /** The retirement state of the homes in the instances directory `instances`. */
43
- function instancesRetirementRoot(instances) {
44
- return join(instances, ".oats-retirement");
45
- }
46
-
47
- /** A home's identity as a receipt records it: its on-disk spelling, own name included. A home that
48
- * is a symlink is not followed: its parent's on-disk spelling and its name as given (a home
49
- * exchanged for a symlink is not the home it points at). */
50
- function receiptHomeIdentity(home) {
51
- let st;
52
- try { st = lstatSync(home); } catch { /* not there: spelled as the nearest existing ancestor */ }
53
- return st && !st.isSymbolicLink() ? canonicalHomePath(home) : join(canonicalHomePath(dirname(home)), basename(home));
54
- }
55
-
56
- /** Whether a receipt's recorded home is this home, whatever spelling either was written in.
57
- * `current` is the home as the caller resolves it for the comparison. */
58
- function receiptRecordsHome(baseline, current) {
59
- return typeof baseline?.home === "string" && receiptHomeIdentity(baseline.home) === current;
60
- }
61
-
62
- function retirementBaselineFile(identity) {
63
- return join(retirementStateRoot(identity), "baselines", `${createHash("sha256").update(identity).digest("hex")}.json`);
64
- }
65
-
66
- /** Where a spawn writes a home's receipt: keyed by its canonical identity. */
67
- export function retirementBaselinePath(home) {
68
- return retirementBaselineFile(receiptHomeIdentity(home));
69
- }
70
-
71
- /** Where a kernel before 0.49.0 wrote it: keyed by the parent's realpath in the spawn's own
72
- * spelling, which on a case-insensitive filesystem need not be the on-disk one. */
73
- function legacyRetirementBaselinePath(home) {
74
- return retirementBaselineFile(join(realPathOrNearest(dirname(home)), basename(home)));
75
- }
76
-
77
- /** The receipt every reader uses: the canonical one if it exists, else one an earlier kernel left
78
- * under this caller's spelling, else the canonical path (absent). Read-only: a receipt found at the
79
- * legacy key is used where it is, never moved, copied or rewritten elsewhere.
80
- *
81
- * Limits. A legacy receipt written under spelling S is found only from S, or from the canonical
82
- * spelling when that is S: a third spelling of such a home misses it (address the home as
83
- * `oats status` prints it, the spawn's spelling). Receipts outlive retire, so a reused name can
84
- * leave an earlier incarnation's receipt behind; the canonical one wins, which is right for every
85
- * home spawned from 0.49.0 on. It is wrong in one case: two incarnations of the same name, both
86
- * spawned by a kernel before 0.49.0 under different spellings, the earlier one under the canonical
87
- * spelling. The later home then reads the earlier one's receipt. Its stale endpoint disagrees with
88
- * instance.json (E_RUNTIME_AUTHORITY_MISMATCH) unless the later incarnation sits at the same
89
- * endpoint, where session control already targets the right session. Retire finds the home
90
- * fingerprint changed and preserves the home, less the stale receipt's disposable roots; a
91
- * directory-work disagreement is E_WORK_INSPECTION_FAILED; and a start's record rewrites the stale
92
- * file, as a kernel before 0.49.0 already does when a caller's spelling matches an earlier
93
- * incarnation's. */
94
- export function findRetirementBaseline(home) {
95
- const canonical = retirementBaselinePath(home);
96
- if (existsSync(canonical)) return canonical;
97
- const legacy = legacyRetirementBaselinePath(home);
98
- return legacy !== canonical && existsSync(legacy) ? legacy : canonical;
99
- }
100
33
 
101
34
  /** Herdr (removed in 0.31.0) is recognised in a home only to refuse: its instance.json records a
102
35
  * Herdr session target or `backend: "herdr"`, or its independent receipt records a session target
@@ -105,22 +38,59 @@ function recordsHerdr(meta, baseline) {
105
38
  return (isPlainObject(meta) && (meta.sessionTarget !== undefined || meta.backend === "herdr"))
106
39
  || (isPlainObject(baseline?.runtime) && baseline.runtime.sessionTarget !== undefined);
107
40
  }
108
- function readJsonOrUndefined(path) { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return undefined; } }
109
41
  /** Refuse any session operation on a home opened in Herdr, from its files as they are (either may be
110
42
  * missing or unreadable): before any receipt validation, so the refusal is never an endpoint error. */
111
43
  function refuseHerdrHome(home) {
112
44
  if (recordsHerdr(readJsonOrUndefined(join(home, "instance.json")), readJsonOrUndefined(findRetirementBaseline(home)))) throw herdrInstanceRemoved(basename(home));
113
45
  }
114
46
 
47
+ /** What a receipt authorises: `{ launched: false }` (with `planned: { backend, provider }` for a home
48
+ * that will launch on a session provider), `{ launched: true, tmux }` for a tmux session, or
49
+ * `{ launched: true, session }` for a session provider's (`session`: providerRuntimeOf's
50
+ * `{ backend, provider, endpoint, stoppedAt }`); undefined when it is none of these. */
115
51
  function runtimeAuthorityOf(baseline) {
116
52
  const runtime = baseline?.runtime;
117
53
  if (!isPlainObject(runtime) || typeof runtime.launched !== "boolean") return undefined;
118
- if (!runtime.launched) return { launched: false };
54
+ if (!runtime.launched) {
55
+ if (runtime.backend === undefined && runtime.provider === undefined) return { launched: false };
56
+ if (!isSessionProviderName(runtime.backend) || typeof runtime.provider !== "string" || !runtime.provider || runtime.launchSent !== undefined) return undefined;
57
+ return { launched: false, planned: { backend: runtime.backend, provider: runtime.provider, launchSent: null } };
58
+ }
119
59
  if (runtime.sessionTarget !== undefined) return undefined;
60
+ // A launch that was sent for a home never launched, and has no recorded outcome (lib/session-providers.mjs
61
+ // launchSentOf): no endpoint yet. The home is still a planned one, whose record says not launched.
62
+ if (runtime.tmux === undefined && runtime.endpoint === undefined) {
63
+ const launchSent = launchSentOf(runtime);
64
+ if (!launchSent || !isSessionProviderName(runtime.backend) || typeof runtime.provider !== "string" || !runtime.provider) return undefined;
65
+ return { launched: false, planned: { backend: runtime.backend, provider: runtime.provider, launchSent } };
66
+ }
67
+ if (runtime.tmux === undefined) {
68
+ const session = providerRuntimeOf(runtime);
69
+ return session ? { launched: true, session: { backend: session.backend, provider: session.provider, endpoint: session.endpoint, stoppedAt: session.stoppedAt, launchSent: session.launchSent } } : undefined;
70
+ }
120
71
  const tmux = runtime.tmux;
121
72
  if (!isPlainObject(tmux) || ![tmux.session, tmux.window, tmux.socket].every((v) => typeof v === "string" && v.length > 0)) return undefined;
122
73
  return { launched: true, tmux: { session: tmux.session, window: tmux.window, socket: resolve(tmux.socket) } };
123
74
  }
75
+ /** The fields of instance.json's session that differ from the receipt's, for a home on a session
76
+ * provider, launched (`authority.session`) or planned (`authority.planned`: no endpoint yet). */
77
+ function providerDifferences(meta, authority) {
78
+ // While the receipt says a launch is unsettled, the record's endpoint is not compared: the
79
+ // launch that would have written it may have ended at any point (docs/design/2026-11-20-provider-home-lifecycle.md).
80
+ if (authority.session && !authority.session.launchSent) return providerEndpointDifferences(meta, authority.session);
81
+ const named = authority.session ?? authority.planned;
82
+ return [
83
+ ...(meta?.backend === named.backend ? [] : ["backend"]),
84
+ ...(meta?.session?.provider === named.provider ? [] : ["session.provider"]),
85
+ ];
86
+ }
87
+ /** The fields of instance.json's endpoint, of whichever backend the receipt records, that differ
88
+ * from the receipt's: tmux's labels, or a session provider's. A receipt that records no endpoint
89
+ * (never launched, planned on tmux) has none to differ from. */
90
+ function endpointDifferences(meta, authority) {
91
+ if (authority.session || authority.planned) return providerDifferences(meta, authority);
92
+ return authority.launched ? tmuxEndpointDifferences(meta, authority) : [];
93
+ }
124
94
 
125
95
  /** The fields of instance.json's tmux endpoint that differ from the one the independent receipt
126
96
  * authorises, as fixed labels in a fixed order: `tmux.session`, `tmux.window`, `tmux.socket`. */
@@ -133,6 +103,8 @@ function tmuxEndpointDifferences(meta, authority) {
133
103
  }
134
104
  /** instance.json's tmux endpoint is the one the independent receipt authorises. */
135
105
  function tmuxEndpointAgrees(meta, authority) { return tmuxEndpointDifferences(meta, authority).length === 0; }
106
+ /** instance.json's endpoint, of whichever backend the receipt records, is the one it authorises. */
107
+ function endpointAgrees(meta, authority) { return endpointDifferences(meta, authority).length === 0; }
136
108
 
137
109
  /** Whether a blocked or incomplete launch prompt explains metadata's `launched: false` beside a
138
110
  * launched receipt. */
@@ -142,18 +114,23 @@ function promptRetained(meta, authority) {
142
114
  /** A blocked prompt is a retained runtime, not evidence that no process exists.
143
115
  * The independent launched receipt and exact endpoint agreement remain mandatory. */
144
116
  function launchStateAgrees(meta, authority) {
145
- return meta.launched === authority.launched || (promptRetained(meta, authority) && tmuxEndpointAgrees(meta, authority));
117
+ // A launch that was sent for a home never launched (lib/session-providers.mjs launchSentOf): the
118
+ // record says `launched: true` meanwhile, so that a kernel from before session providers refuses
119
+ // the home; the two files are written one after the other, so either value agrees.
120
+ if ((authority.session ?? authority.planned)?.launchSent) return true;
121
+ return meta.launched === authority.launched || (promptRetained(meta, authority) && !authority.session && tmuxEndpointAgrees(meta, authority));
146
122
  }
147
123
 
148
124
  /** The refusal for instance.json that disagrees with the independent receipt. `details.fields` names
149
125
  * what differs, from a fixed vocabulary in a fixed order: `launched` (unless a blocked or incomplete
150
- * launch prompt explains metadata's `launched: false`), then, for a launched receipt, each differing
151
- * tmux endpoint field. Labels only: never a path, a value or the receipt. Callers throw it only once
126
+ * launch prompt explains metadata's `launched: false`), then each differing endpoint field: for a
127
+ * launched tmux receipt `tmux.session`, `tmux.window`, `tmux.socket`; for a session provider's
128
+ * `backend`, `session.provider`, `session.endpoint`. Labels only: never a path, a value or the receipt. Callers throw it only once
152
129
  * their own comparison has refused, so these labels diagnose a refusal and never decide one. */
153
130
  function authorityMismatch(message, meta, authority) {
154
131
  const fields = [
155
- ...(meta.launched === authority.launched || promptRetained(meta, authority) ? [] : ["launched"]),
156
- ...(authority.launched ? tmuxEndpointDifferences(meta, authority) : []),
132
+ ...(meta.launched === authority.launched || promptRetained(meta, authority) || (authority.session ?? authority.planned)?.launchSent ? [] : ["launched"]),
133
+ ...endpointDifferences(meta, authority),
157
134
  ];
158
135
  return Object.assign(oatsError("E_RUNTIME_AUTHORITY_MISMATCH", message), { details: { fields } });
159
136
  }
@@ -194,9 +171,31 @@ function instanceSessionTarget(home, { absentMeta } = {}) {
194
171
  if (!isPlainObject(meta)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read ${recordPath}: it holds no JSON object`);
195
172
  const authority = baseline.version === RETIRE_BASELINE_VERSION && receiptRecordsHome(baseline, canonicalHomePath(home)) && runtimeAuthorityOf(baseline);
196
173
  if (!authority) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or invalid for ${home}`);
197
- if (!launchStateAgrees(meta, authority) || (authority.launched && !tmuxEndpointAgrees(meta, authority))) throw authorityMismatch("instance metadata disagrees with independent session receipt", meta, authority);
198
- return { home, target: authority.launched ? { backend: "tmux", ...authority.tmux } : undefined, meta };
174
+ // A home that is being spawned: its receipt is there (a directory home's is written before the
175
+ // spawn's hooks run; planned, never launched) and its record is still the one its files were
176
+ // composed with (lib/materialize.mjs: its modules, and no agent, no launch, no backend yet).
177
+ // The spawn's hooks, and a provider's readiness check, run in between. Nothing contradicts
178
+ // anything: the session is not recorded yet, and a read says so (a presence read that a hook
179
+ // sets off lands here on every spawn).
180
+ const composedOnly = meta.agent === undefined && meta.launch === undefined && meta.backend === undefined && meta.tmux === undefined;
181
+ if (composedOnly && (authority.planned ? !authority.planned.launchSent : authority.launched !== true)) {
182
+ // (Whether that spawn still runs is not told here: one that ended before its record reads the same.)
183
+ throw oatsError("E_SESSION_UNAVAILABLE", `${basename(home)} is being spawned, or its spawn ended before its record was written: its session ${authority.planned ? `is planned on ${authority.planned.backend}` : "is planned"}, and its record is not there yet`);
184
+ }
185
+ if (!launchStateAgrees(meta, authority) || !endpointAgrees(meta, authority)) throw authorityMismatch("instance metadata disagrees with independent session receipt", meta, authority);
186
+ // `unsettled`: a launch that was sent to the home's provider and never recorded, whether the home
187
+ // was launched before or not: `{ backend, provider, launchSent }`, or null. The one place that says so.
188
+ const recorded = authority.session ?? authority.planned ?? null;
189
+ // A provider home's capability rows (settings, hook commands) are its receipt's, never its own
190
+ // record's, which its agent can write (lib/home-integrity.mjs): every verb reads them here.
191
+ meta = trustedRecord(meta, receiptTrust(baseline, home));
192
+ return { home, target: authority.tmux ? { backend: "tmux", ...authority.tmux } : undefined, meta,
193
+ ...(authority.session ? { session: authority.session } : {}), ...(authority.planned ? { planned: authority.planned } : {}),
194
+ unsettled: recorded?.launchSent ? { backend: recorded.backend, provider: recorded.provider, launchSent: recorded.launchSent } : null };
199
195
  }
196
+ /** The answer for a tmux-only path that meets a home on a session provider (`s`: instanceSessionTarget's
197
+ * answer): the home has no tmux endpoint to read or act on. Undefined for any other home. */
198
+ function providerHomeOf(s) { return s.session ?? s.planned; }
200
199
 
201
200
  /** `wakeHold` (feature wake-hold): whether this home's capabilities said its dialogs become the claims
202
201
  * a wake holds on, from the home's record (instance.json `dialogClaims`): `on-claims` if any entry is
@@ -207,11 +206,47 @@ function wakeHoldOf(meta) {
207
206
  return answers.includes("reported") ? "on-claims" : answers.includes("none") ? "not-exposed" : "unknown";
208
207
  }
209
208
 
210
- /** `io` (`{ exec }`) is the tmux and process-table seam inspectSessionTarget takes. */
209
+ /** What a provider home's `session` is in an answer: the capability that supplies its backend and
210
+ * the endpoint the kernel recorded (null before the first launch). */
211
+ export function sessionOf(session) { return { provider: session.provider, endpoint: session.endpoint ?? null }; }
212
+ /** A launched provider home's session, as inspect answers it (docs/desktop-cli-api.md): the
213
+ * provider's own `{ present, state, running, open }`, with the kernel's `backend`, `session`,
214
+ * `waitingOnYou` and `wakeHold`; no pane and no size. Kernel-owned: a home OATS stopped (`stoppedAt`)
215
+ * answers stopped WITHOUT calling the provider, so a session the provider would restart on the next
216
+ * input reads as OATS left it. A provider that fails, refuses or answers outside the contract's
217
+ * words is E_SESSION_UNAVAILABLE, never stopped. `waitingOnYou` is a producer's claim, read
218
+ * whenever the session is not stopped (providerMayWait): an idle session can be the one waiting
219
+ * on a person. */
220
+ function inspectProviderHome(s, wakeHold, io) {
221
+ const answer = { home: s.home, backend: s.session.backend };
222
+ const kernel = { wakeHold, session: sessionOf(s.session) };
223
+ if (s.session.stoppedAt !== null) return { ...answer, present: false, state: "stopped", running: false, waitingOnYou: null, ...kernel, open: null };
224
+ const found = homeSessionProvider(s.home, s.meta, s.session.provider, s.session.backend);
225
+ if (found.problem) throw oatsError("E_SESSION_UNAVAILABLE", `cannot inspect session: ${found.problem}`);
226
+ const inspected = inspectProviderSession(found.binding, s.session.endpoint, { io });
227
+ if (inspected.unavailable) throw oatsError("E_SESSION_UNAVAILABLE", `cannot inspect session: ${inspected.unavailable}`);
228
+ const { present, state, running, open } = inspected.observed;
229
+ return { ...answer, present, state, running, waitingOnYou: providerMayWait(inspected.observed) ? liveWaiting(s.home) : null, ...kernel, open };
230
+ }
231
+ /** Whether a provider's session, as observed, can be waiting on a human: whenever it is not stopped
232
+ * (`running` true or null). An agent that waits on a question is idle where its provider runs it,
233
+ * so it reads `running: null`: the claim is shown then too. Never for a session that is gone (a
234
+ * lost one included) or in error, nor for a home OATS stopped, which is never observed. */
235
+ function providerMayWait(observed) { return observed.present === true && observed.running !== false; }
236
+
237
+ /** `io` (`{ exec }`) is the tmux and process-table seam inspectSessionTarget takes; for a home on a
238
+ * session provider, `io.spawnSync` is the provider call's. */
211
239
  export function inspectInstanceSession(home, { io, absentMeta } = {}) {
212
240
  if (typeof home === "string" && isAbsolute(home) && !existsSync(home)) return { home: realPathOrNearest(home), backend: null, present: false, state: "stopped", running: false, waitingOnYou: null, wakeHold: wakeHoldOf(null) };
213
241
  const s = instanceSessionTarget(home, { absentMeta });
214
242
  const wakeHold = wakeHoldOf(s.meta);
243
+ // A launch that was sent and never recorded (launchSentOf), on a home launched before or not: a
244
+ // session may run that no record names. Unknown, never "not launched" or "stopped", until a stop
245
+ // or a start has settled it.
246
+ if (s.unsettled) throw oatsError("E_SESSION_UNAVAILABLE", unsettledLaunchSaid(basename(s.home), s.unsettled.backend, s.unsettled.launchSent));
247
+ if (s.session) return inspectProviderHome(s, wakeHold, io);
248
+ // A home that will launch on a session provider says which: nothing was launched yet.
249
+ if (s.planned) return { home: s.home, backend: s.planned.backend, present: false, state: "not-launched", running: false, waitingOnYou: null, wakeHold, session: sessionOf(s.planned), open: null };
215
250
  if (!s.target) return { home: s.home, backend: null, present: false, state: "not-launched", running: false, waitingOnYou: null, wakeHold };
216
251
  let observed;
217
252
  try { observed = inspectSessionTarget(s.target, io, { includeSize: true }); }
@@ -226,4 +261,5 @@ export function inspectInstanceSession(home, { io, absentMeta } = {}) {
226
261
  * fallback shell nor a dead pane. Only such a session can be waiting on a human. */
227
262
  function harnessRunning(observed) { return observed?.present === true && observed.state !== "shell" && observed.state !== "stopped"; }
228
263
 
229
- export { RETIRE_BASELINE_VERSION, authorityMismatch, harnessRunning, instanceSessionTarget, instancesRetirementRoot, isPlainObject, launchStateAgrees, missingSessionReceipt, readJsonOrUndefined, receiptHomeIdentity, receiptRecordsHome, recordsHerdr, refuseHerdrHome, runtimeAuthorityOf, tmuxEndpointAgrees };
264
+ // (The receipt's own primitives are lib/session-receipt.mjs's, exported here as they were.)
265
+ export { RETIRE_BASELINE_VERSION, findRetirementBaseline, retirementBaselinePath, authorityMismatch, endpointAgrees, harnessRunning, providerHomeOf, providerMayWait, instanceSessionTarget, instancesRetirementRoot, isPlainObject, launchStateAgrees, missingSessionReceipt, readJsonOrUndefined, receiptHomeIdentity, receiptRecordsHome, recordsHerdr, refuseHerdrHome, runtimeAuthorityOf, tmuxEndpointAgrees };