@awebai/oats 0.55.1 → 0.57.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.
- package/bin/oats.mjs +96 -72
- package/docs/capabilities.md +67 -3
- package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
- package/docs/desktop-cli-api.md +375 -37
- package/docs/desktop-instance-start.md +105 -12
- package/docs/desktop.md +65 -11
- package/docs/execution-targets.md +184 -9
- package/docs/harness-trust.md +128 -11
- package/docs/implementation.md +153 -11
- package/docs/integrations.md +5 -3
- package/docs/knowledge.md +117 -43
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-lane.md +26 -1
- package/docs/release-notes/v0.56.0.md +699 -0
- package/docs/release-notes/v0.57.0.md +283 -0
- package/docs/schedules.md +8 -3
- package/docs/servers.md +21 -5
- package/docs/souls-and-instances.md +134 -19
- package/docs/tui.md +215 -31
- package/docs/upgrading.md +4 -1
- package/docs/workspaces.md +26 -6
- package/lib/automations.mjs +3 -4
- package/lib/bounded-read.mjs +18 -0
- package/lib/capability-show.mjs +13 -2
- package/lib/claim.mjs +3 -4
- package/lib/core.mjs +919 -278
- package/lib/errors.mjs +39 -0
- package/lib/harness-trust-write.mjs +119 -40
- package/lib/harness-trust.mjs +31 -18
- package/lib/instance-inspect.mjs +160 -11
- package/lib/instance-lifecycle.mjs +90 -37
- package/lib/packages.mjs +8 -5
- package/lib/pi-bridge.mjs +18 -19
- package/lib/remote.mjs +88 -51
- package/lib/retire-output.mjs +9 -4
- package/lib/schedule.mjs +3 -4
- package/lib/servers.mjs +39 -6
- package/lib/session-viewer.mjs +25 -1
- package/lib/triggers.mjs +3 -4
- package/lib/workspace.mjs +6 -6
- package/lib/worktree.mjs +33 -8
- package/lib/write-through-private-file.mjs +26 -0
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +108 -13
- package/packages/client/cli-locator.mjs +16 -14
- package/packages/client/deployment-panel.mjs +4 -3
- package/packages/client/display-text.mjs +2 -1
- package/packages/client/instance-events-contract.mjs +4 -3
- package/packages/client/instance-lifecycle.mjs +235 -0
- package/packages/client/instance-presentation.mjs +9 -0
- package/packages/client/instance-tree.mjs +10 -8
- package/packages/client/kernel-lines.mjs +3 -3
- package/packages/client/launch-contract.mjs +11 -0
- package/packages/client/launch-prompt-outcome.mjs +1 -1
- package/packages/client/lifecycle-cli.mjs +12 -6
- package/packages/client/lifecycle-confirmation.mjs +407 -0
- package/packages/client/lifecycle-contract.mjs +6 -2
- package/packages/client/own-codes.mjs +1 -0
- package/packages/client/panel-views.mjs +39 -2
- package/packages/client/readiness-contract.mjs +2 -2
- package/packages/client/remote-roster.mjs +50 -5
- package/packages/client/roster-sections.mjs +3 -3
- package/packages/client/session-start.mjs +98 -0
- package/packages/client/start-gate.mjs +46 -0
- package/packages/client/start-messages.mjs +17 -0
- package/packages/client/workspace-views.mjs +2 -2
- package/packages/tui/README.md +21 -8
- package/packages/tui/lib/actions.mjs +11 -2
- package/packages/tui/lib/client.mjs +9 -2
- package/packages/tui/lib/config.mjs +39 -9
- package/packages/tui/lib/main.mjs +168 -20
- package/packages/tui/lib/model.mjs +315 -13
- package/packages/tui/lib/open.mjs +45 -0
- package/packages/tui/lib/read.mjs +171 -16
- package/packages/tui/lib/store.mjs +171 -10
- package/packages/tui/lib/term/tty.mjs +71 -12
- package/packages/tui/lib/views/act.mjs +85 -0
- package/packages/tui/lib/views/frame.mjs +145 -33
- package/packages/tui/lib/views/help.mjs +46 -11
- package/skills/oats-getting-started/SKILL.md +6 -3
|
@@ -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.
|
|
16
|
+
// Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.58.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
|
|
48
|
-
//
|
|
49
|
-
//
|
|
50
|
-
//
|
|
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,
|
|
55
|
+
export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 58, 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.
|
|
126
|
-
|
|
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,
|
|
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(
|
|
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
|
-
|
|
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
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
/** K7 API2 consumer input contract. Pure data validation; no log/kernel IO. */
|
|
2
2
|
import { absolute, record } from './readiness-contract.mjs';
|
|
3
3
|
import { remoteReason } from './remote-address.mjs';
|
|
4
|
+
import { DETAIL_WITHHELD } from './display-text.mjs';
|
|
4
5
|
const exact = (v, keys) => record(v) && Object.keys(v).every(k => keys.includes(k));
|
|
5
6
|
const name = v => typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/.test(v);
|
|
6
7
|
const text = (v, max = 4096) => typeof v === 'string' && !!v && v.length <= max && !/[\x00-\x1f\x7f]/.test(v);
|
|
@@ -15,9 +16,9 @@ export const eventsTimestamp = v => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}
|
|
|
15
16
|
export const eventsUnsafe = /[\x00-\x08\x0b-\x1f\x7f]|:\/\/(?<=[a-z][a-z0-9+.-]*:\/\/)\S+|(?:gh[pousr]_|github_pat_)[A-Za-z0-9_]{16,}|(?:token|authorization|password|secret|api[_ -]?key)\s*[:=]\s*\S+/i;
|
|
16
17
|
/** A producer or kind id: non-empty, ≤ 256, no control characters, nothing unsafe. */
|
|
17
18
|
export const eventsId = v => typeof v === 'string' && !!v && v.length <= 256 && !/[\x00-\x1f\x7f]/.test(v) && !eventsUnsafe.test(v);
|
|
18
|
-
/** What stands in for text eventsUnsafe refuses
|
|
19
|
-
* and the sidebar's claim (waitingOnYouData) reads it as "no note". */
|
|
20
|
-
export const EVENTS_WITHHELD =
|
|
19
|
+
/** What stands in for text eventsUnsafe refuses: the clients' one withheld word (display-text.mjs `DETAIL_WITHHELD`).
|
|
20
|
+
* eventsDetail and waitingMessage return it, and the sidebar's claim (waitingOnYouData) reads it as "no note". */
|
|
21
|
+
export const EVENTS_WITHHELD = DETAIL_WITHHELD;
|
|
21
22
|
/** A free-text detail: a string ≤ max (throws otherwise); unsafe text is withheld, never shown. */
|
|
22
23
|
export function eventsDetail(v, max = 2048) {
|
|
23
24
|
if (typeof v !== 'string' || v.length > max) throw Error('invalid event detail');
|
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
/** K3 transactions: immutable admitted plan -> one explicit confirmation intent.
|
|
2
|
+
* No direct Git, kernel import, PID/tmux control or legacy mutation fallback.
|
|
3
|
+
*
|
|
4
|
+
* A client makes its own boundary (createLifecycleBoundary, with its own terms) and owns it; this home makes
|
|
5
|
+
* none, and two boundaries share nothing. What a boundary holds, it holds for its own client's requests only:
|
|
6
|
+
* its limits (32 plans, 4 plan reads, a plan for 5 minutes, a kept answer for 30) and "one apply at a time".
|
|
7
|
+
* Between two clients, or between a client and `oats` run by hand, the kernel's answers are what holds: from
|
|
8
|
+
* OATS 0.52.0 (feature lifecycle-claim-stop) a stop and a retire of one home refuse each other before any
|
|
9
|
+
* effect; a start, `oats worktree add` and a status read still do not see a retire in flight (#866). A boundary
|
|
10
|
+
* made again (the Desktop's backend restarted) knows no plan of the one before it: applying one answers
|
|
11
|
+
* E_PLAN_EXPIRED. */
|
|
12
|
+
import { randomBytes } from 'node:crypto';
|
|
13
|
+
import { performance } from 'node:perf_hooks';
|
|
14
|
+
import { admitInstance, instanceSelector } from './instance-admission.mjs';
|
|
15
|
+
import { cliLifecycle } from './lifecycle-cli.mjs';
|
|
16
|
+
import { gitTargetKey } from './instance-git-contract.mjs';
|
|
17
|
+
import { hostReason } from './remote-address.mjs';
|
|
18
|
+
import { displayLine } from './display-text.mjs';
|
|
19
|
+
import { object, lifecycleOptions, lifecyclePlan, lifecycleReceipt, stoppedTargets, planReference, lifecycleChoicesApplicable,
|
|
20
|
+
lifecycleFailure, lifecycleReason, lifecycleDetailCode, answeringFeatures, busyHolder, busyHeadline, busyAbout, undescribedAnswer } from './lifecycle-contract.mjs';
|
|
21
|
+
import { requireTerms } from './client-terms.mjs';
|
|
22
|
+
const clone = value => structuredClone(value);
|
|
23
|
+
const cliIdentity = cli => JSON.stringify([cli?.bin, cli?.version, cli?.lifecycleApi,
|
|
24
|
+
Array.isArray(cli?.features) ? [...cli.features].sort() : null]);
|
|
25
|
+
export function supportsLifecycle(cli, operation, apply = false) {
|
|
26
|
+
return cli?.ok === true && cli.lifecycleApi === 1 && Array.isArray(cli.features)
|
|
27
|
+
&& cli.features.length <= 128 && cli.features.every(f => typeof f === 'string')
|
|
28
|
+
&& cli.features.includes('lifecycle-plans')
|
|
29
|
+
&& (!apply || operation !== 'retire' || cli.features.includes('retire-retention') && cli.features.includes('retire-home'));
|
|
30
|
+
}
|
|
31
|
+
/** The codes of an apply's error answer that Desktop reads as "refused, nothing was done to the instance",
|
|
32
|
+
* for a stop and for a retire alike. Every other code is an unknown outcome. Exported so that the kernel's
|
|
33
|
+
* tests can hold this list inside the kernel's own list of the codes it answers only before any effect: a
|
|
34
|
+
* code joins here only once the kernel promises that of it. The promise is about the instance (its sessions,
|
|
35
|
+
* its home), not about the workspace log: a guarded retire may have appended its plan's event there by then,
|
|
36
|
+
* so no sentence built on this list says that nothing was recorded. A routed command's router refuses
|
|
37
|
+
* E_REMOTE_INCOMPATIBLE, E_AMBIGUOUS and E_SNAPSHOT_UNKNOWN before sending, and the host's own resolution
|
|
38
|
+
* refuses them (and E_HOME_MISMATCH) before any effect. E_PLAN_STALE is not here: it is read by its own branch
|
|
39
|
+
* (interpret), by the shape of the answer, never by this set. */
|
|
40
|
+
export const BEFORE_EFFECT_CODES = Object.freeze(['E_BAD_ARGS', 'E_INSTANCE_RETIRING', 'E_LIFECYCLE_BUSY',
|
|
41
|
+
'E_HOME_MISMATCH', 'E_SESSION_UNKNOWN', 'E_AMBIGUOUS_INSTANCE', 'E_UNIDENTIFIED_INSTANCE_HOME', 'E_REMOTE_INCOMPATIBLE', 'E_AMBIGUOUS', 'E_SNAPSHOT_UNKNOWN']);
|
|
42
|
+
/** The installed CLI printed this error envelope: the kernel answered. Said by the adapter where it builds
|
|
43
|
+
* the envelope (`origin`), never inferred from the envelope's shape: the adapter's own failures and this
|
|
44
|
+
* boundary's have the same shape, and no origin. */
|
|
45
|
+
const kernelAnswered = envelope => envelope?.origin === 'kernel' && envelope.schemaVersion === 1 && envelope.ok === false;
|
|
46
|
+
/** A failed command's reason. Remote: the host's code and message under its headline. Local: the fixed
|
|
47
|
+
* sentence for `code`, and the kernel's own message beside it as `detail`, through the display filter, only
|
|
48
|
+
* when the kernel answered (kernelAnswered) and the code may show one (lifecycleDetailCode: it has its own
|
|
49
|
+
* sentence and is not one Desktop raises). Otherwise the reason is `{code, message}` alone.
|
|
50
|
+
* A code the kernel answered that has no sentence keeps its own code and reads by the fallback sentence
|
|
51
|
+
* (undescribedAnswer), with the kernel's message as its detail: "OATS couldn't be run for this." is never
|
|
52
|
+
* the sentence for an answer the kernel gave. A code that did not come from the kernel never reaches it.
|
|
53
|
+
* A kernel's E_LIFECYCLE_BUSY whose kernel (`features`: the answering kernel's) says who holds the claim
|
|
54
|
+
* reads by that (`holder`, busyHolder), local or remote, and names the target of `plan` the refusal is
|
|
55
|
+
* about when that is not the instance acted on (`about`). */
|
|
56
|
+
function failureReason(envelope, remote, terms, { code = envelope?.error?.code, features = null, plan = null } = {}) {
|
|
57
|
+
const kernel = kernelAnswered(envelope), undescribed = kernel ? undescribedAnswer(code, terms) : null;
|
|
58
|
+
const reason = undescribed || lifecycleReason(code, terms), details = envelope?.error?.details;
|
|
59
|
+
const holder = kernel ? busyHolder(code, details, features) : null, about = holder ? busyAbout(plan, details?.home) : null;
|
|
60
|
+
const busy = holder ? { holder, ...(about ? { about } : {}) } : {};
|
|
61
|
+
const message = holder ? busyHeadline(holder) : reason.message;
|
|
62
|
+
if (remote) { const host = hostReason({ ...envelope?.error, code }, remote.label, message); return host ? { ...host, ...busy } : reason; }
|
|
63
|
+
const detail = kernel && (undescribed || lifecycleDetailCode(code)) ? displayLine(envelope.error?.message) : null;
|
|
64
|
+
return { ...reason, message, ...(detail ? { detail } : {}), ...busy };
|
|
65
|
+
}
|
|
66
|
+
/** How long a boundary waits for an apply's answer. The wait ends; the apply does not (lifecycle-cli.mjs). */
|
|
67
|
+
export const APPLY_WAIT_MS = 600_000;
|
|
68
|
+
/** One client's lifecycle boundary: `lifecycleRequest(request, getContext)`, a plan or an apply.
|
|
69
|
+
* invoke the CLI call (lifecycle-cli.mjs `cliLifecycle`); now the clock of its limits (ms, monotonic)
|
|
70
|
+
* clock the wall clock (ms since the epoch), for when a running apply started (`running.since`)
|
|
71
|
+
* after `after(ms, fn)` runs fn once after ms and answers a cancel; mint the reference and key maker
|
|
72
|
+
* terms the client's own (client-terms.mjs): every reason is worded with them; required
|
|
73
|
+
* exec optional: the client's own execFile, passed to `invoke` as `invoke(bin, args, { exec })` for the plan
|
|
74
|
+
* read and for the apply alike; without it `invoke` is given no third argument and cliLifecycle's own
|
|
75
|
+
* defaults run. A given exec runs every call cliLifecycle hands it; one with `detached: true` is an apply,
|
|
76
|
+
* which it runs in a session of its own (as execFileInSession does) and never ends, neither at a deadline
|
|
77
|
+
* nor by a signal to its group.
|
|
78
|
+
* An apply's answer is awaited APPLY_WAIT_MS. When that passes the boundary answers `unknown` and the apply stays
|
|
79
|
+
* in flight here: its reference, its key, its place as the one apply. Its answer, whenever it comes, is read and
|
|
80
|
+
* kept 30 minutes like any other; the same reference meanwhile is answered at once (`unknown` while it runs, the
|
|
81
|
+
* kept answer with `repeated` after). The cost: a CLI that never answers holds this client's applies until the
|
|
82
|
+
* client is restarted; killing it instead could strand the instance (#889; a stop on a kernel before 0.52.0).
|
|
83
|
+
* Every reply given because this client's own apply is running carries `running: { target, operation, since }`:
|
|
84
|
+
* the busy refusal of another apply, and the `unknown` of that apply after its wait. The kernel's own
|
|
85
|
+
* E_LIFECYCLE_BUSY never carries it, and this client's busy refusal carries no `details`, so the kernel's busy
|
|
86
|
+
* holder (lifecycle-contract.mjs busyHolder) is never read of it.
|
|
87
|
+
* `getContext()` is read at every admission and answers the deployment the request names and what this
|
|
88
|
+
* client holds of it: `{ workspace: { id, scope, remote?, group? }, cli, localCwd, instances }`. `group` is
|
|
89
|
+
* the workspace's roster group (its `probe` says which features a routed command's host answers with,
|
|
90
|
+
* lifecycle-contract.mjs `answeringFeatures`); `instances` are that deployment's own rows. */
|
|
91
|
+
export function createLifecycleBoundary({ invoke = cliLifecycle, now = () => performance.now(), clock = () => Date.now(), mint = () => randomBytes(32).toString('hex'),
|
|
92
|
+
after = (ms, fn) => { const timer = setTimeout(fn, ms); timer.unref?.(); return () => clearTimeout(timer); }, terms, exec } = {}) {
|
|
93
|
+
requireTerms(terms, 'createLifecycleBoundary');
|
|
94
|
+
// The CLI call, with the client's exec when it gave one: the same exec for a plan read and an apply.
|
|
95
|
+
const call = (bin, args) => (exec ? invoke(bin, args, { exec }) : invoke(bin, args));
|
|
96
|
+
const plans = new Map(), actions = new Map(), reads = new Map(), beforeEffect = new Set(BEFORE_EFFECT_CODES);
|
|
97
|
+
let reservedPlans = 0, activeApply = null;
|
|
98
|
+
const sweep = () => { for (const map of [plans, actions]) for (const [key, value] of map) {
|
|
99
|
+
if (!value.pending && value.expires <= now()) map.delete(key);
|
|
100
|
+
} };
|
|
101
|
+
const denied = (code, target = null, extra = {}) => lifecycleFailure(code, terms, { target, ...extra });
|
|
102
|
+
function admitted(selector, operation, getContext, apply = false) {
|
|
103
|
+
const context = getContext();
|
|
104
|
+
const result = admitInstance(selector, { ...context, operation: 'lifecycle-plans' });
|
|
105
|
+
if (result.code) return { failure: denied(result.code, result.target, result.reason ? { reason: result.reason } : {}) };
|
|
106
|
+
if (!supportsLifecycle(context.cli, operation, apply)) return { failure: denied('E_LIFECYCLE_UNAVAILABLE', result.target) };
|
|
107
|
+
// Which kernel answers the command this read admits: its features decide how its answer is read.
|
|
108
|
+
return { ...result, identity: cliIdentity(context.cli),
|
|
109
|
+
features: answeringFeatures({ cli: context.cli, routed: !!result.remote, group: context.workspace?.group }) };
|
|
110
|
+
}
|
|
111
|
+
const same = (a, b) => !b.failure && a.bin === b.bin && a.context === b.context && a.identity === b.identity && gitTargetKey(a.target) === gitTargetKey(b.target);
|
|
112
|
+
function storePlan(plan, selection, choices) {
|
|
113
|
+
if (plans.size + reservedPlans >= 32) return null;
|
|
114
|
+
const id = mint(); if (!planReference(id) || plans.has(id) || actions.has(id)) return null;
|
|
115
|
+
const entry = { target: clone(selection.target), context: selection.context, scope: selection.scope, remote: selection.remote ? clone(selection.remote) : null, bin: selection.bin,
|
|
116
|
+
identity: selection.identity, selector: clone(selection.selector), choices: clone(choices), plan: clone(plan), id, expires: now() + 300_000 };
|
|
117
|
+
plans.set(id, entry); return entry;
|
|
118
|
+
}
|
|
119
|
+
const displayed = (entry, status = 'plan', reason = null) => ({ lifecycleApi: 1, status, target: entry.target, planRef: entry.id,
|
|
120
|
+
plan: entry.plan, options: entry.choices, receipt: null, reason });
|
|
121
|
+
async function plan(request, getContext) {
|
|
122
|
+
const choices = lifecycleOptions(request.operation, request.options);
|
|
123
|
+
if (!choices || !instanceSelector(request.selector) || Object.keys(request).some(k => !['action', 'operation', 'selector', 'options'].includes(k))) return denied('E_BAD_ARGS');
|
|
124
|
+
const selected = admitted(request.selector, request.operation, getContext);
|
|
125
|
+
if (selected.failure) return selected.failure;
|
|
126
|
+
if (plans.size + reservedPlans >= 32) return denied('E_LIFECYCLE_BUSY', selected.target);
|
|
127
|
+
const key = JSON.stringify([selected.identity, selected.context, gitTargetKey(selected.target), request.operation, choices]);
|
|
128
|
+
if (!reads.has(key) && reads.size >= 4) return denied('E_LIFECYCLE_BUSY', selected.target);
|
|
129
|
+
if (!reads.has(key)) {
|
|
130
|
+
const args = { operation: request.operation, phase: 'plan', instance: selected.target.instance, home: selected.target.home, context: selected.context,
|
|
131
|
+
...(selected.remote ? { server: selected.remote.server } : {}), choices };
|
|
132
|
+
const pending = Promise.resolve().then(() => call(selected.bin, args)).catch(() => ({ ok: false, error: { code: 'E_CLI_FAILED' } })).finally(() => reads.delete(key));
|
|
133
|
+
reads.set(key, pending);
|
|
134
|
+
}
|
|
135
|
+
reservedPlans++;
|
|
136
|
+
let envelope;
|
|
137
|
+
try { envelope = await reads.get(key); } finally { reservedPlans--; }
|
|
138
|
+
// The CLI read can be shared, but each confirmation gets its OWN ref/key.
|
|
139
|
+
const current = admitted(request.selector, request.operation, getContext);
|
|
140
|
+
if (!same(selected, current)) return denied('E_PLAN_CHANGED', selected.target);
|
|
141
|
+
if (envelope?.schemaVersion !== 1 || envelope.ok !== true) {
|
|
142
|
+
const code = envelope?.error?.code || 'E_CLI_PROTOCOL';
|
|
143
|
+
return denied(code, selected.target, { reason: failureReason(envelope, selected.remote, terms, { code, features: selected.features }) });
|
|
144
|
+
}
|
|
145
|
+
// The plan is read by the features of the kernel that made it: for a relayed plan its host's, never this computer's.
|
|
146
|
+
const data = lifecyclePlan(envelope.result, selected.target, request.operation, choices, { features: selected.features });
|
|
147
|
+
if (!data) return denied('E_CLI_PROTOCOL', selected.target);
|
|
148
|
+
const entry = storePlan(data, { ...selected, scope: getContext().workspace.scope, selector: clone(request.selector) }, choices);
|
|
149
|
+
return entry ? displayed(entry) : denied('E_LIFECYCLE_BUSY', selected.target);
|
|
150
|
+
}
|
|
151
|
+
function interpret(envelope, entry, features) {
|
|
152
|
+
const extra = { planRef: entry.id, options: entry.choices };
|
|
153
|
+
const failure = (code, status, more = {}) => denied(code, entry.target, { ...extra, status, ...more });
|
|
154
|
+
if (envelope?.schemaVersion !== 1 || typeof envelope.ok !== 'boolean') return failure('E_OUTCOME_UNKNOWN', 'unknown');
|
|
155
|
+
// A failed retire can still carry a bounded incomplete-cleanup receipt.
|
|
156
|
+
if (envelope.result) {
|
|
157
|
+
const receipt = lifecycleReceipt(envelope.result, entry.plan, entry.key, { server: entry.remote?.server ?? null, features });
|
|
158
|
+
if (!receipt) return failure('E_OUTCOME_UNKNOWN', 'unknown', { cause: lifecycleReason('E_CLI_PROTOCOL', terms) });
|
|
159
|
+
const complete = receipt.action === 'stop' ? receipt.ok : receipt.removedDir && !receipt.incomplete;
|
|
160
|
+
return { lifecycleApi: 1, status: receipt.deferred ? 'pending' : complete ? 'complete' : 'partial', target: entry.target, planRef: entry.id,
|
|
161
|
+
options: entry.choices, plan: null, receipt, reason: complete ? null : lifecycleReason(receipt.action === 'stop' ? 'E_SESSION_STOP_FAILED' : 'E_RETIRE_INCOMPLETE', terms) };
|
|
162
|
+
}
|
|
163
|
+
const code = envelope.error?.code;
|
|
164
|
+
// E_PLAN_STALE means "nothing happened" only in its documented shape: the answer carries the fresh plan, which
|
|
165
|
+
// is read for this target and act and offered for review. Any other E_PLAN_STALE (no plan, or one that does not
|
|
166
|
+
// read) is an unknown outcome: a kernel before 0.52.0 could answer it planless after a guarded retire's hooks had
|
|
167
|
+
// run (#895). The boundary reads only the shape: an E_PLAN_STALE that carried a valid plan after an effect
|
|
168
|
+
// could not be told apart by any client.
|
|
169
|
+
if (code === 'E_PLAN_STALE') {
|
|
170
|
+
const fresh = lifecyclePlan(envelope.error?.details?.plan, entry.target, entry.plan.action, entry.choices, { features });
|
|
171
|
+
if (!fresh) return failure('E_OUTCOME_UNKNOWN', 'unknown', { cause: lifecycleReason('E_CLI_PROTOCOL', terms) });
|
|
172
|
+
const replacement = storePlan(fresh, entry, entry.choices);
|
|
173
|
+
return replacement ? displayed(replacement, 'stale', lifecycleReason(code, terms)) : failure(code, 'stale', { plan: fresh });
|
|
174
|
+
}
|
|
175
|
+
if (code === 'E_CHILDREN_RUNNING' && entry.plan.action === 'retire') {
|
|
176
|
+
const fresh = lifecyclePlan(envelope.error?.details?.plan, entry.target, 'retire', entry.choices, { features });
|
|
177
|
+
const childrenStopped = fresh && stoppedTargets(envelope.error?.details?.childrenStopped, fresh.facts.children, false, { features });
|
|
178
|
+
if (!childrenStopped || childrenStopped.every(c => c.ok)) return failure('E_OUTCOME_UNKNOWN', 'unknown');
|
|
179
|
+
// This is the attempted plan, NOT a new executable confirmation: some
|
|
180
|
+
// children have already stopped. The user must explicitly read a new plan.
|
|
181
|
+
return failure(code, 'refused', { plan: fresh, childrenStopped });
|
|
182
|
+
}
|
|
183
|
+
if (beforeEffect.has(code)) return failure(code, 'refused', { reason: failureReason(envelope, entry.remote, terms, { features, plan: entry.plan }) });
|
|
184
|
+
return failure('E_OUTCOME_UNKNOWN', 'unknown', { cause: failureReason(envelope, entry.remote, terms, { features }) });
|
|
185
|
+
}
|
|
186
|
+
/** The apply of this client that is running, as a reply names it. */
|
|
187
|
+
const runningOf = entry => ({ target: clone(entry.target), operation: entry.plan.action, since: entry.started });
|
|
188
|
+
function apply(request, getContext, ws) {
|
|
189
|
+
if (Object.keys(request).some(k => !['action', 'planRef'].includes(k)) || !planReference(request.planRef)) return Promise.resolve(denied('E_BAD_ARGS'));
|
|
190
|
+
const entry = actions.get(request.planRef) || plans.get(request.planRef);
|
|
191
|
+
if (!entry) return Promise.resolve(denied('E_PLAN_EXPIRED'));
|
|
192
|
+
const context = getContext();
|
|
193
|
+
if (!context.workspace || context.workspace.id !== ws || ws !== entry.target.workspace || context.workspace.scope !== entry.scope
|
|
194
|
+
|| cliIdentity(context.cli) !== entry.identity
|
|
195
|
+
|| !supportsLifecycle(context.cli, entry.plan.action, true)) return Promise.resolve(denied('E_PLAN_CHANGED', entry.target));
|
|
196
|
+
if (entry.pending) return entry.pending;
|
|
197
|
+
if (entry.reply) return Promise.resolve({ ...entry.reply, repeated: true }); // no CLI, even if home was removed/recreated
|
|
198
|
+
// Its wait has ended and its CLI still works: answered at once, never a second wait.
|
|
199
|
+
if (entry.waited) return Promise.resolve(clone(entry.waited));
|
|
200
|
+
// The 32-action cap is no running apply: that refusal names none.
|
|
201
|
+
if (activeApply || actions.size >= 32) return Promise.resolve(denied('E_LIFECYCLE_BUSY', entry.target, activeApply ? { running: runningOf(activeApply) } : {}));
|
|
202
|
+
if (!lifecycleChoicesApplicable(entry.plan, entry.choices)) return Promise.resolve(denied('E_OPTION_UNAVAILABLE', entry.target));
|
|
203
|
+
const current = admitted(entry.selector, entry.plan.action, getContext, true);
|
|
204
|
+
if (!same(entry, current)) return Promise.resolve(denied('E_PLAN_CHANGED', entry.target));
|
|
205
|
+
// Reserve synchronously, before any awaited work. One ref = one submitted
|
|
206
|
+
// intent; loss of an HTTP response cannot mint a second idempotency key.
|
|
207
|
+
entry.key = mint(); entry.expires = Infinity; entry.started = clock(); activeApply = entry;
|
|
208
|
+
plans.delete(entry.id); actions.set(entry.id, entry);
|
|
209
|
+
const args = { operation: entry.plan.action, phase: 'apply', instance: entry.target.instance, home: entry.target.home,
|
|
210
|
+
context: entry.context, ...(entry.remote ? { server: entry.remote.server } : {}), choices: clone(entry.choices), revision: entry.plan.planRevision, key: entry.key };
|
|
211
|
+
let cancel = () => {};
|
|
212
|
+
const answered = Promise.resolve().then(() => call(entry.bin, args)).then(result => interpret(result, entry, current.features))
|
|
213
|
+
.catch(() => denied('E_OUTCOME_UNKNOWN', entry.target, { status: 'unknown', planRef: entry.id }))
|
|
214
|
+
.then(result => { entry.reply = clone(result); return result; })
|
|
215
|
+
.finally(() => { cancel(); entry.pending = null; entry.waited = null; entry.expires = now() + 30 * 60_000; if (activeApply === entry) activeApply = null; });
|
|
216
|
+
// The wait ends; the apply does not. What is answered then is what a CLI that did not answer in time reads as.
|
|
217
|
+
const waited = new Promise(resolve => { cancel = after(APPLY_WAIT_MS, () => resolve(null)); });
|
|
218
|
+
entry.pending = Promise.race([answered, waited]).then(result => {
|
|
219
|
+
if (result) return result;
|
|
220
|
+
entry.pending = null;
|
|
221
|
+
entry.waited = { ...interpret({ schemaVersion: 1, ok: false, error: { code: 'E_CLI_TIMEOUT' } }, entry, current.features), running: runningOf(entry) };
|
|
222
|
+
return clone(entry.waited);
|
|
223
|
+
});
|
|
224
|
+
return entry.pending;
|
|
225
|
+
}
|
|
226
|
+
return async function lifecycleRequest(request, getContext) {
|
|
227
|
+
try {
|
|
228
|
+
sweep();
|
|
229
|
+
if (!object(request) || !['plan', 'apply'].includes(request.action)) return denied('E_BAD_ARGS');
|
|
230
|
+
const context = getContext();
|
|
231
|
+
if (!context.workspace || typeof context.workspace.id !== 'string') return denied('E_WORKSPACE_UNKNOWN');
|
|
232
|
+
return clone(await (request.action === 'plan' ? plan(request, getContext) : apply(request, getContext, context.workspace.id)));
|
|
233
|
+
} catch { return denied('E_CLI_FAILED'); }
|
|
234
|
+
};
|
|
235
|
+
}
|
|
@@ -5,6 +5,15 @@ export function runtimeState(instance) {
|
|
|
5
5
|
return instance.running === true ? "running" : instance.running === false ? "stopped" : "unknown";
|
|
6
6
|
}
|
|
7
7
|
|
|
8
|
+
const RUNTIME_ORDER = Object.freeze({ running: 0, unknown: 1, stopped: 2 });
|
|
9
|
+
/** The roster's one order, a comparator for `sort`: running, then unknown (`running` null or anything not
|
|
10
|
+
* a boolean: it may be running, so it stands above the rows nobody needs to watch), then stopped; by name
|
|
11
|
+
* within each. Each row's place depends on that row alone, so it is a total order whatever `running` holds.
|
|
12
|
+
* Read by `clusterInstances` (instance-tree.mjs) and `panelInstances` (deployment-panel.mjs). */
|
|
13
|
+
export function byRuntimeState(a, b) {
|
|
14
|
+
return RUNTIME_ORDER[runtimeState(a)] - RUNTIME_ORDER[runtimeState(b)] || String(a.instance).localeCompare(String(b.instance));
|
|
15
|
+
}
|
|
16
|
+
|
|
8
17
|
/** The stand-in `unsupportedSession` writes for an older kernel's Herdr row: the one text of a row that is
|
|
9
18
|
* this home's own sentence. Not on the stable surface. */
|
|
10
19
|
export const HERDR_STAND_IN = `E_HERDR_REMOVED: ${HERDR_REMOVED}`;
|
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
* under a filter or a collapse, who waits below a collapsed row, and what holds a home. No document,
|
|
4
4
|
* no element: a client draws from these answers with its own means. */
|
|
5
5
|
import { waitingClaim } from './waiting-on-you.mjs';
|
|
6
|
+
import { byRuntimeState } from './instance-presentation.mjs';
|
|
6
7
|
|
|
7
8
|
export function collapseKey(workspace, instance) {
|
|
8
9
|
return `${workspace || ""}\u0000${instance}`;
|
|
@@ -60,8 +61,8 @@ export function resolveLinkId(fromInstance, name, byName) {
|
|
|
60
61
|
* cluster members related only by sibling links sit at depth 0.
|
|
61
62
|
* Nodes are keyed by instanceId (composite identity), never bare name —
|
|
62
63
|
* duplicate names across repos render as distinct nodes.
|
|
63
|
-
* Returns [{ key, instances: [{...instance, depth}] }] with clusters ranked
|
|
64
|
-
*
|
|
64
|
+
* Returns [{ key, instances: [{...instance, depth}] }] with clusters ranked by
|
|
65
|
+
* their first member in the roster's order (`byRuntimeState`), as the panel is. */
|
|
65
66
|
export function clusterInstances(instances, { links = instanceLinks } = {}) {
|
|
66
67
|
const byId = new Map(instances.map((i) => [instanceId(i), i]));
|
|
67
68
|
const byName = new Map();
|
|
@@ -85,7 +86,7 @@ export function clusterInstances(instances, { links = instanceLinks } = {}) {
|
|
|
85
86
|
adj.get(oid).add(id);
|
|
86
87
|
}
|
|
87
88
|
}
|
|
88
|
-
const rank =
|
|
89
|
+
const rank = byRuntimeState;
|
|
89
90
|
const seen = new Set();
|
|
90
91
|
const clusters = [];
|
|
91
92
|
for (const start of [...instances].sort(rank)) {
|
|
@@ -121,7 +122,7 @@ export function clusterInstances(instances, { links = instanceLinks } = {}) {
|
|
|
121
122
|
// Deterministic cluster label: the lexically-smallest ROOT name —
|
|
122
123
|
// independent of liveness, so the visible cluster name does not flip
|
|
123
124
|
// when a different member starts/stops running (review f921f7d nit).
|
|
124
|
-
//
|
|
125
|
+
// `rank` (running, unknown, stopped) still governs display ORDER within the cluster.
|
|
125
126
|
const rootNames = (roots.length ? roots : members).map((i) => i.instance).sort();
|
|
126
127
|
clusters.push({ key: rootNames[0], instances: ordered });
|
|
127
128
|
}
|
|
@@ -238,13 +239,14 @@ export const ROSTER_SORTS = Object.freeze([
|
|
|
238
239
|
Object.freeze({ id: "name", label: "Name" }),
|
|
239
240
|
]);
|
|
240
241
|
|
|
241
|
-
/** Comparator for one sibling level. "status"
|
|
242
|
-
* then by name; "name" is purely
|
|
243
|
-
* "status" so a stale persisted choice
|
|
242
|
+
/** Comparator for one sibling level. "status" is the roster's one order
|
|
243
|
+
* (`byRuntimeState`: running, unknown, stopped, then by name); "name" is purely
|
|
244
|
+
* alphabetical. Unknown ids fall back to "status" so a stale persisted choice
|
|
245
|
+
* can never break rendering. */
|
|
244
246
|
export function rosterRank(sortBy) {
|
|
245
247
|
const byName = (a, b) => String(a.instance).localeCompare(String(b.instance));
|
|
246
248
|
if (sortBy === "name") return byName;
|
|
247
|
-
return
|
|
249
|
+
return byRuntimeState;
|
|
248
250
|
}
|
|
249
251
|
|
|
250
252
|
/** Group a roster list repo → agent family (soul), each family's items in
|
|
@@ -13,11 +13,11 @@ import { originLead } from "./instance-presentation.mjs";
|
|
|
13
13
|
* the kernel's stands without its speaker:
|
|
14
14
|
*
|
|
15
15
|
* message a line, fix a line ["OATS says: <message>", "<fix>"]
|
|
16
|
-
* message withheld, fix a line ["[
|
|
16
|
+
* message withheld, fix a line ["[withheld]", "OATS says: <fix>"]
|
|
17
17
|
* message nothing, fix a line ["OATS says: <fix>"]
|
|
18
|
-
* message a line, fix withheld ["OATS says: <message>", "[
|
|
18
|
+
* message a line, fix withheld ["OATS says: <message>", "[withheld]"]
|
|
19
19
|
* message a line, fix nothing ["OATS says: <message>"]
|
|
20
|
-
* neither has a line what is there ("[
|
|
20
|
+
* neither has a line what is there ("[withheld]" for a withheld text), no lead
|
|
21
21
|
*
|
|
22
22
|
* `terms` are the client's own (client-terms.mjs), required on every call under this function's name:
|
|
23
23
|
* also where no line is led, so a caller that leaves them out fails at once and not only on the day a
|
|
@@ -12,6 +12,17 @@ const model = v => v === null || text(v, 256);
|
|
|
12
12
|
const LAUNCH_CONFIG = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
|
|
13
13
|
const CODE = /^E_[A-Z0-9_]{1,62}$/;
|
|
14
14
|
|
|
15
|
+
/** The word that selects no launch configuration: `--launch-config none` runs the harness itself, with
|
|
16
|
+
* no configuration's executable, arguments or environment, the host's default for the harness included.
|
|
17
|
+
* A client that offers the bare harness sends this constant and never a name out of a list: the kernel
|
|
18
|
+
* reads the word as no configuration whatever a list holds, and refuses a configuration of that name. */
|
|
19
|
+
export const LAUNCH_CONFIG_NONE = 'none';
|
|
20
|
+
/** Whether the kernel that answers a start is known to read the word. `features` is that kernel's own
|
|
21
|
+
* list (lifecycle-contract.mjs `answeringFeatures`: this computer's for a home here, the host's for a
|
|
22
|
+
* server's home, null when it is not known). The first release that lists `launch-config` reads the word,
|
|
23
|
+
* so the list naming it is the proof; unknown is not known. */
|
|
24
|
+
export const launchConfigNoneKnown = features => Array.isArray(features) && features.includes('launch-config');
|
|
25
|
+
|
|
15
26
|
/** Where the effective launch came from, per document: a report never says `flag`; only a home's
|
|
16
27
|
* record says `recorded` (a home from before 0.30). */
|
|
17
28
|
export const REPORT_FROM = Object.freeze(['local', 'local-default', 'soul', 'host']);
|
|
@@ -126,7 +126,7 @@ export function retainedSpawnMessage(d) {
|
|
|
126
126
|
const p = launchPromptOutcome(d.launchPrompts);
|
|
127
127
|
return `${d.instance} was retained: ${p.reason}.${inputNote(p)} Inspect its existing pane, then use oats session start --home for this home. Do not spawn again.`;
|
|
128
128
|
}
|
|
129
|
-
/** A Start or Restart of an existing home that stopped at a launch prompt, in the
|
|
129
|
+
/** A Start or Restart of an existing home that stopped at a launch prompt, in the clients' words: the
|
|
130
130
|
* kernel answers E_SPAWN_INCOMPLETE with the same retained details as a spawn. `instance` is the name the
|
|
131
131
|
* dialog started; `d` the decoded details. It claims the weaker thing for both statuses: a blocked start and
|
|
132
132
|
* one whose completion was not seen are both "not confirmed", never "failed" and never "started". */
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/** Fixed-argv installed-CLI K3 adapter. No kernel import, fallback or raw errors. */
|
|
2
2
|
import { execFile } from 'node:child_process';
|
|
3
3
|
import { isAbsolute } from 'node:path';
|
|
4
|
-
import { parseEnvelope, parseRetireEnvelope } from './cli-adapter.mjs';
|
|
4
|
+
import { parseEnvelope, parseRetireEnvelope, execFileInSession } from './cli-adapter.mjs';
|
|
5
5
|
import { object, lifecycleOptions, planRevision } from './lifecycle-contract.mjs';
|
|
6
6
|
const absolute = v => typeof v === 'string' && isAbsolute(v) && !v.includes('\0');
|
|
7
7
|
const key = v => typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(v);
|
|
@@ -28,15 +28,21 @@ export function lifecycleArgv(options) {
|
|
|
28
28
|
if (o.operation === 'stop' && !choices.recursive) args.push('--no-recursive');
|
|
29
29
|
args.push('--json'); return args;
|
|
30
30
|
}
|
|
31
|
-
/** `exec` is a client's own `execFile` (the rule is at cli-adapter.mjs `runJson`).
|
|
32
|
-
|
|
31
|
+
/** `exec` is a client's own `execFile` (the rule is at cli-adapter.mjs `runJson`).
|
|
32
|
+
* A plan is a read: it runs in the caller's process group, and its deadline (30 s, 45 s routed; `timeout` may
|
|
33
|
+
* shorten it) ends it, as every read ends. An apply is a change: it gets no deadline and runs in a session of
|
|
34
|
+
* its own (`detached: true`; this home's default for it is `execFileInSession`), so neither a deadline nor a
|
|
35
|
+
* signal to the client's group ends it while it works. Its client's boundary decides how long it waits for
|
|
36
|
+
* the answer (instance-lifecycle.mjs), and the child goes on, whatever the client does, until it answers. */
|
|
37
|
+
export function cliLifecycle(bin, options, { exec, timeout } = {}) {
|
|
33
38
|
const argv = lifecycleArgv(options);
|
|
34
39
|
if (!absolute(bin) || !argv) return Promise.resolve(failure('E_BAD_ARGS'));
|
|
35
|
-
const apply = options.phase === 'apply', limit =
|
|
40
|
+
const apply = options.phase === 'apply', limit = options.server ? REMOTE_READ_TIMEOUT : 30_000;
|
|
41
|
+
const run = exec ?? (apply ? execFileInSession : execFile);
|
|
36
42
|
return new Promise(resolve => {
|
|
37
43
|
try {
|
|
38
|
-
|
|
39
|
-
timeout: Number.isFinite(timeout) && timeout > 0 ? Math.min(timeout, limit) : limit,
|
|
44
|
+
run(bin, argv, { cwd: options.context, encoding: 'utf8', shell: false,
|
|
45
|
+
...(apply ? { detached: true } : { timeout: Number.isFinite(timeout) && timeout > 0 ? Math.min(timeout, limit) : limit }),
|
|
40
46
|
maxBuffer: (apply ? 4 : 1) * 1024 * 1024 }, (error, stdout) => {
|
|
41
47
|
if (error?.killed) return resolve(failure('E_CLI_TIMEOUT'));
|
|
42
48
|
if (error?.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') return resolve(failure('E_CLI_OUTPUT_LIMIT'));
|