@awebai/oats 0.51.0 → 0.53.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/README.md +3 -1
- package/bin/oats.mjs +407 -123
- package/docs/capabilities.md +75 -6
- package/docs/configuration.md +200 -91
- package/docs/desktop-cli-api.md +1563 -113
- package/docs/desktop-instance-start.md +69 -0
- package/docs/desktop.md +10 -7
- package/docs/execution-targets.md +145 -58
- package/docs/first-team.md +3 -1
- package/docs/harness-trust.md +50 -2
- package/docs/implementation.md +238 -17
- package/docs/integrations.md +13 -9
- package/docs/knowledge-reference/acceptance.md +1 -0
- package/docs/knowledge-reference/harvester.md +5 -3
- package/docs/knowledge-reference/model.md +5 -3
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -2
- package/docs/launch-prompt-completion.md +50 -48
- package/docs/macos-test-runs.md +246 -0
- package/docs/oats-local.schema.json +4 -3
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +225 -11
- package/docs/release-notes/v0.44.0.md +1 -1
- package/docs/release-notes/v0.52.0.md +933 -0
- package/docs/release-notes/v0.53.0.md +1274 -0
- package/docs/schedules.md +97 -4
- package/docs/souls-and-instances.md +332 -40
- package/docs/tui.md +584 -0
- package/docs/upgrading.md +298 -0
- package/docs/workspaces.md +3 -3
- package/lib/automations.mjs +22 -22
- package/lib/claim.mjs +278 -49
- package/lib/config-data.mjs +4 -1
- package/lib/core.mjs +1282 -289
- package/lib/errors.mjs +170 -0
- package/lib/harness-trust-write.mjs +68 -27
- package/lib/harness-trust.mjs +34 -16
- package/lib/instance-events.mjs +19 -1
- package/lib/instance-git.mjs +39 -3
- package/lib/instance-inspect.mjs +45 -17
- package/lib/instance-lifecycle.mjs +306 -57
- package/lib/instance-resolution.mjs +59 -6
- package/lib/launch-preference.mjs +236 -9
- package/lib/launch-prompt-completion.mjs +7 -43
- package/lib/launch-prompt-evidence.mjs +14 -7
- package/lib/launch-prompt-fixtures/README.md +86 -152
- package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
- package/lib/launch-prompt-fixtures.mjs +122 -109
- package/lib/launch-prompt-transport.mjs +2 -56
- package/lib/launch-prompts.mjs +102 -100
- package/lib/local-edit.mjs +118 -0
- package/lib/packages.mjs +13 -4
- package/lib/pi-bridge.mjs +308 -0
- package/lib/refused-text.mjs +11 -0
- package/lib/remote.mjs +190 -25
- package/lib/resolve.mjs +2 -1
- package/lib/retained-after-retire.mjs +2 -2
- package/lib/retire-output.mjs +12 -1
- package/lib/schedule-host.mjs +125 -22
- package/lib/schedule.mjs +73 -24
- package/lib/shell-word.mjs +13 -0
- package/lib/soul-launch-verbs.mjs +153 -0
- package/lib/stable-node.mjs +62 -0
- package/lib/system-tools.mjs +39 -0
- package/lib/teams-verbs.mjs +18 -46
- package/lib/tmux-server-scope.mjs +62 -0
- package/lib/triggers.mjs +4 -4
- package/lib/workspace.mjs +54 -30
- package/lib/worktree-hooks.mjs +98 -20
- package/lib/worktree.mjs +83 -24
- package/package-catalog.json +4 -4
- package/package.json +8 -2
- package/packages/client/attach-exit.mjs +25 -0
- package/packages/client/capability-show-contract.mjs +230 -0
- package/packages/client/capability-warnings-contract.mjs +57 -0
- package/packages/client/cli-adapter.mjs +561 -0
- package/packages/client/cli-environment.mjs +53 -0
- package/packages/client/cli-locator.mjs +253 -0
- package/packages/client/cli-probe-contract.mjs +47 -0
- package/packages/client/client-terms.mjs +60 -0
- package/packages/client/deployment-contract.mjs +72 -0
- package/packages/client/deployment-data.mjs +483 -0
- package/packages/client/deployment-facts.mjs +95 -0
- package/packages/client/deployment-label.mjs +76 -0
- package/packages/client/deployment-observer.mjs +89 -0
- package/packages/client/deployment-panel.mjs +180 -0
- package/packages/client/deployment-read-cli.mjs +57 -0
- package/packages/client/display-text.mjs +50 -0
- package/packages/client/harness-names.mjs +30 -0
- package/packages/client/inspect-contract.mjs +62 -0
- package/packages/client/instance-acts.mjs +90 -0
- package/packages/client/instance-admission.mjs +45 -0
- package/packages/client/instance-events-contract.mjs +76 -0
- package/packages/client/instance-git-contract.mjs +80 -0
- package/packages/client/instance-presentation.mjs +86 -0
- package/packages/client/instance-tree.mjs +462 -0
- package/packages/client/kernel-environment.mjs +11 -0
- package/packages/client/kernel-lines.mjs +31 -0
- package/packages/client/kernel-made.mjs +23 -0
- package/packages/client/launch-contract.mjs +51 -0
- package/packages/client/launch-prompt-outcome.mjs +200 -0
- package/packages/client/lifecycle-cli.mjs +61 -0
- package/packages/client/lifecycle-contract.mjs +413 -0
- package/packages/client/liveness-main.mjs +10 -0
- package/packages/client/liveness.mjs +48 -0
- package/packages/client/machine-contract.mjs +123 -0
- package/packages/client/own-codes.mjs +31 -0
- package/packages/client/own-environment.mjs +22 -0
- package/packages/client/panel-views.mjs +293 -0
- package/packages/client/readiness-contract.mjs +174 -0
- package/packages/client/refresh-loop.mjs +52 -0
- package/packages/client/remote-address.mjs +151 -0
- package/packages/client/remote-identity-memory.mjs +94 -0
- package/packages/client/remote-roster.mjs +153 -0
- package/packages/client/roster-sections.mjs +80 -0
- package/packages/client/session-attach.mjs +175 -0
- package/packages/client/spawn-apply-cli.mjs +104 -0
- package/packages/client/spawn-apply-contract.mjs +195 -0
- package/packages/client/spawn-decision.mjs +46 -0
- package/packages/client/spawn-messages.mjs +142 -0
- package/packages/client/spawn-preview-cli.mjs +38 -0
- package/packages/client/spawn-preview-contract.mjs +318 -0
- package/packages/client/team-members.mjs +41 -0
- package/packages/client/team-rows.mjs +45 -0
- package/packages/client/terminal-contract.mjs +57 -0
- package/packages/client/terminal-exec.mjs +21 -0
- package/packages/client/tmux-status.mjs +66 -0
- package/packages/client/waiting-on-you.mjs +88 -0
- package/packages/client/workspace-admission.mjs +45 -0
- package/packages/client/workspace-choices.mjs +95 -0
- package/packages/client/workspace-cli.mjs +142 -0
- package/packages/client/workspace-views.mjs +183 -0
- package/packages/record/README.md +21 -0
- package/packages/record/bin/setup.mjs +108 -15
- package/packages/tui/README.md +64 -0
- package/packages/tui/bin/tui.mjs +7 -0
- package/packages/tui/lib/actions.mjs +44 -0
- package/packages/tui/lib/client.mjs +35 -0
- package/packages/tui/lib/config.mjs +151 -0
- package/packages/tui/lib/main.mjs +176 -0
- package/packages/tui/lib/model.mjs +392 -0
- package/packages/tui/lib/read.mjs +473 -0
- package/packages/tui/lib/store.mjs +364 -0
- package/packages/tui/lib/term/keys.mjs +367 -0
- package/packages/tui/lib/term/screen.mjs +134 -0
- package/packages/tui/lib/term/style.mjs +43 -0
- package/packages/tui/lib/term/text.mjs +109 -0
- package/packages/tui/lib/term/tty.mjs +178 -0
- package/packages/tui/lib/term/width.mjs +124 -0
- package/packages/tui/lib/views/detail.mjs +46 -0
- package/packages/tui/lib/views/frame.mjs +256 -0
- package/packages/tui/lib/views/help.mjs +140 -0
- package/packages/tui/lib/views/instances.mjs +137 -0
- package/packages/tui/lib/views/scroll.mjs +19 -0
- package/packages/tui/lib/views/switcher.mjs +97 -0
- package/packages/tui/package.json +8 -0
- package/skills/oats-getting-started/SKILL.md +30 -23
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
- package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
- package/lib/launch-prompt-policy.mjs +0 -87
|
@@ -8,17 +8,27 @@
|
|
|
8
8
|
* make a retried apply return the first receipt rather than act twice.
|
|
9
9
|
* Unknown is reported as unknown — never as "clean" or "no children". */
|
|
10
10
|
import { createHash } from "node:crypto";
|
|
11
|
-
import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
|
|
11
|
+
import { existsSync, lstatSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
|
|
12
12
|
import { basename, join } from "node:path";
|
|
13
|
-
import { attachedWorkLink, extraWorktreePlan, findInstanceHomes, inspectInstanceSession, listAgents, listInstances, observeSessionWithoutReceipt, retirePendingMarkerPath, retirementRecoveryFacts, stopInstanceSession } from "./core.mjs";
|
|
13
|
+
import { attachedWorkLink, claimHomeFor, extraWorktreePlan, findInstanceHomes, homeClaimHolder, identifiedHomeRecord, inspectInstanceSession, instanceWork, listAgents, listInstances, observeSessionWithoutReceipt, readHomeRecord, READ_CLAIM_WHEN_UNWRITABLE, releaseHomeClaim, requireStopGrace, retireClaimPath, retirePendingMarkerPath, retirementRecoveryFacts, shq, stillRunningOf, stopInstanceSession, STOP_UNDER_CLAIM } from "./core.mjs";
|
|
14
14
|
import { groupedByOwner } from "./retire-output.mjs";
|
|
15
15
|
import { observeInstanceGit } from "./instance-git.mjs";
|
|
16
16
|
import { appendEvent } from "./instance-events.mjs";
|
|
17
|
-
import { oatsError } from "./errors.mjs";
|
|
17
|
+
import { afterFirstEffect, isAnswerCode, kernelCode, lifecycleBusy, oatsError, reportDefect } from "./errors.mjs";
|
|
18
18
|
|
|
19
19
|
export const LIFECYCLE_API = 1;
|
|
20
20
|
const KEY = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
|
|
21
|
-
|
|
21
|
+
/** A reserved name: a kernel before feature `lifecycle-claim-stop` wrote this file into each target
|
|
22
|
+
* of a stop apply and left it there when it was killed. This kernel neither writes nor reads it;
|
|
23
|
+
* a stop apply removes one it finds, once it holds that home's claim. */
|
|
24
|
+
const leftoverStopMarkerPath = (home) => join(home, ".oats-stop-pending.json");
|
|
25
|
+
/** An option of planStop: the nonces of the lifecycle claims the caller holds (a stop apply reads
|
|
26
|
+
* its plan again under its own claims), which the plan does not report as a stop in progress. A
|
|
27
|
+
* symbol, so no caller can set it from parsed arguments or JSON. */
|
|
28
|
+
const OWN_HOLDINGS = Symbol("oats.stopPlanOwnHoldings");
|
|
29
|
+
/** The warnings of a stop apply (a leftover marker that could not be removed), on its receipt
|
|
30
|
+
* under a symbol: the receipt's JSON, printed or stored, does not carry them. */
|
|
31
|
+
export const STOP_WARNINGS = Symbol("oats.stopWarnings");
|
|
22
32
|
const stopReceiptPath = (home, key) => join(home, `.oats-stop-receipt.${key}.json`);
|
|
23
33
|
|
|
24
34
|
function readJson(path) { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; } }
|
|
@@ -38,6 +48,24 @@ export function resolveInstance(ctx, root, name, { home } = {}) {
|
|
|
38
48
|
if (candidates.length > 1) throw Object.assign(oatsError("E_AMBIGUOUS_INSTANCE", `instance ${JSON.stringify(name)} has ${candidates.length} homes; pass --home <abs>`), { candidates });
|
|
39
49
|
return candidates[0];
|
|
40
50
|
}
|
|
51
|
+
/** The home a stop or a retire is about: resolved (resolveInstance), and refused when its record is
|
|
52
|
+
* there and cannot be read (core identifiedHomeRecord), before a plan reads anything of it. */
|
|
53
|
+
function resolveTarget(ctx, root, name, opts) {
|
|
54
|
+
const me = resolveInstance(ctx, root, name, opts);
|
|
55
|
+
identifiedHomeRecord(me.home);
|
|
56
|
+
return me;
|
|
57
|
+
}
|
|
58
|
+
/** The record of the home a plan is about, read for the plan's facts: the same reader and the same
|
|
59
|
+
* refusal as the resolution, so that a record which became unreadable since then (the listing
|
|
60
|
+
* reads it in between) refuses the plan instead of giving it empty facts. → the record's object,
|
|
61
|
+
* or undefined for a home without one. */
|
|
62
|
+
const targetRecord = (home) => identifiedHomeRecord(home).meta;
|
|
63
|
+
/** The record of ANOTHER home (a child's, any home's lineage) → its object, or undefined when it is
|
|
64
|
+
* absent or cannot be read: such a home decides only for itself, and is nobody's parent or child. */
|
|
65
|
+
function otherRecord(home) {
|
|
66
|
+
const record = readHomeRecord(home);
|
|
67
|
+
return record.state === "record" ? record.meta : undefined;
|
|
68
|
+
}
|
|
41
69
|
|
|
42
70
|
/** Every instance under the roots whose recorded parent chain reaches `name`,
|
|
43
71
|
* deepest first (children are acted on before their parent). Recorded
|
|
@@ -46,7 +74,7 @@ export function descendantsOf(root, name) {
|
|
|
46
74
|
const rows = [];
|
|
47
75
|
for (const a of listAgents(root)) for (const i of listInstances(root).filter((x) => x.name === a.name)) for (const inst of i.instances || []) {
|
|
48
76
|
const home = join(a._dir, "instances", inst.instance);
|
|
49
|
-
const meta =
|
|
77
|
+
const meta = otherRecord(home);
|
|
50
78
|
if (meta) rows.push({ instance: inst.instance, agent: a.name, home, parent: meta.parentInstance ?? null });
|
|
51
79
|
}
|
|
52
80
|
// Recorded parentage is a BARE name, and names are unique only per agent
|
|
@@ -70,46 +98,58 @@ export function descendantsOf(root, name) {
|
|
|
70
98
|
/** `state` is the session backend's word: "shell"/"stopped"/"not-launched" are
|
|
71
99
|
* idle; "unknown" means a NON-shell process is running whose identity tmux
|
|
72
100
|
* cannot name (the ordinary case for a launched harness). "Could not be
|
|
73
|
-
* established" is a different thing and is `present: null` with a reason
|
|
101
|
+
* established" is a different thing and is `present: null` with a reason:
|
|
102
|
+
* the kernel code of what failed, never a system error's (E_SESSION_UNAVAILABLE
|
|
103
|
+
* for one that has none; workFacts: E_GIT_FAILED). */
|
|
74
104
|
function sessionFacts(home) {
|
|
75
105
|
try { const s = inspectInstanceSession(home); return { state: s.state, present: s.present, backend: s.backend ?? null, established: true }; }
|
|
76
|
-
catch (e) { return { state: "unestablished", present: null, backend: null, established: false, reason: e
|
|
106
|
+
catch (e) { return { state: "unestablished", present: null, backend: null, established: false, reason: kernelCode(e, "E_SESSION_UNAVAILABLE") }; }
|
|
77
107
|
}
|
|
78
108
|
/** Retire's view of a home without its session receipt (before 0.25.9): the
|
|
79
109
|
* retirement needs only absence, which it can observe — `{state: "absent",
|
|
80
110
|
* present: false, established: true, note}`; live or ambiguous stays
|
|
81
111
|
* unestablished, with the note saying why (retire refuses it). */
|
|
82
|
-
function retireSessionFacts(home, session) {
|
|
112
|
+
function retireSessionFacts(home, session, meta) {
|
|
83
113
|
if (session.established || session.reason !== "E_RUNTIME_ENDPOINT_UNKNOWN") return session;
|
|
84
|
-
const meta = readJson(join(home, "instance.json"));
|
|
85
114
|
if (!meta) return session;
|
|
86
115
|
const seen = observeSessionWithoutReceipt(home, meta);
|
|
87
116
|
return seen.absent ? { state: "absent", present: false, backend: seen.backend, established: true, note: seen.note } : { ...session, note: seen.note };
|
|
88
117
|
}
|
|
89
118
|
const running = (s) => s.established && s.present === true && !["shell", "stopped", "not-launched"].includes(s.state);
|
|
90
119
|
function workFacts(home) {
|
|
91
|
-
if (!existsSync(join(home, "work")))
|
|
120
|
+
if (!existsSync(join(home, "work"))) {
|
|
121
|
+
// Not there, unless the home cannot be looked into: then nothing is known of its work.
|
|
122
|
+
try { lstatSync(join(home, "work")); } catch (e) { if (e?.code !== "ENOENT") return { observed: false, reason: "E_WORK_INSPECTION_FAILED" }; }
|
|
123
|
+
return { observed: false, reason: "no-worktree" };
|
|
124
|
+
}
|
|
92
125
|
try {
|
|
93
126
|
const g = observeInstanceGit(home);
|
|
94
127
|
return { observed: true, revision: g.observation.revision, branch: g.observation.branch, detached: g.observation.detached, drift: g.recorded.drift,
|
|
95
128
|
changed: g.summary.changed + g.summary.renamed + g.summary.copied + g.summary.unmerged, untracked: g.summary.untracked,
|
|
96
129
|
upstream: g.upstream, base: { ref: g.base.ref, ahead: g.base.ahead, behind: g.base.behind }, remote: g.remote ? { host: g.remote.host, path: g.remote.path } : null };
|
|
97
|
-
} catch (e) { return { observed: false, reason: e
|
|
130
|
+
} catch (e) { return { observed: false, reason: kernelCode(e, "E_GIT_FAILED") }; }
|
|
98
131
|
}
|
|
99
|
-
|
|
100
|
-
|
|
132
|
+
/** The facts of one target of a plan. `meta` is its record's object: the plan's own home's
|
|
133
|
+
* (targetRecord) or a child's (otherRecord). `retiring` and `stopPending` are read from the
|
|
134
|
+
* home's lifecycle claim (core homeClaimHolder), by the holder's verb: a holder that is not gone
|
|
135
|
+
* (alive, or of a liveness that cannot be read) counts, and `retiring` is also true while a
|
|
136
|
+
* self-retire is scheduled (its pending marker). A claim in `own` is the caller's and is not
|
|
137
|
+
* reported. */
|
|
138
|
+
function targetFacts(row, meta = {}, own) {
|
|
139
|
+
const held = homeClaimHolder(row.home);
|
|
140
|
+
const holds = (action) => !!held && held.action === action && held.state !== "gone" && !own?.has(held.holder.nonce);
|
|
101
141
|
return { instance: row.instance, agent: row.agent, home: row.home, depth: row.depth ?? 0, workMode: meta.work ?? null, launched: meta.launched === true,
|
|
102
142
|
session: sessionFacts(row.home), work: workFacts(row.home),
|
|
103
|
-
retiring: existsSync(retirePendingMarkerPath(row.home)), stopPending:
|
|
143
|
+
retiring: existsSync(retirePendingMarkerPath(row.home)) || holds("retire"), stopPending: holds("stop") };
|
|
104
144
|
}
|
|
105
145
|
|
|
106
146
|
/** Facts for Stop: the instance, its recorded descendants (deepest first),
|
|
107
147
|
* each with session state and dirty-work counts. `midTask` is REPORTED
|
|
108
148
|
* activity: dirty work or a running session; unknown says unknown. */
|
|
109
|
-
export function planStop(ctx, root, name, { home, recursive = true } = {}) {
|
|
110
|
-
const me =
|
|
149
|
+
export function planStop(ctx, root, name, { home, recursive = true, [OWN_HOLDINGS]: own } = {}) {
|
|
150
|
+
const me = resolveTarget(ctx, root, name, { home });
|
|
111
151
|
const kids = recursive ? descendantsOf(me.root, name) : [];
|
|
112
|
-
const targets = [...kids.map(targetFacts), targetFacts({ ...me, instance: name, depth: 0 })];
|
|
152
|
+
const targets = [...kids.map((kid) => targetFacts(kid, otherRecord(kid.home), own)), targetFacts({ ...me, instance: name, depth: 0 }, targetRecord(me.home), own)];
|
|
113
153
|
// Reported activity: a running session or dirty work is mid-task; when the
|
|
114
154
|
// session could not be established and work is not observed, say unknown.
|
|
115
155
|
for (const t of targets) t.midTask = running(t.session) || (t.work.observed && t.work.changed + t.work.untracked > 0) ? true : (!t.session.established || !t.work.observed) ? "unknown" : false;
|
|
@@ -120,52 +160,170 @@ export function planStop(ctx, root, name, { home, recursive = true } = {}) {
|
|
|
120
160
|
ambiguous: ambiguousEdges,
|
|
121
161
|
planRevision: planRevision(safety),
|
|
122
162
|
notes: [...(ambiguousEdges.length ? [`${ambiguousEdges.length} instance(s) record this name as parent but the name is not unique under this root; they are listed under ambiguous and NOT acted on`] : []),
|
|
123
|
-
...(targets.some((t) => t.retiring) ? ["a target is being retired; apply will refuse it"] : []),
|
|
163
|
+
...(targets.some((t) => t.retiring) ? ["a target is being retired; apply will refuse it"] : []),
|
|
164
|
+
...(targets.some((t) => t.stopPending) ? ["a stop holds a target's claim; apply will refuse it until that stop has ended"] : []), ...(targets.some((t) => !t.session.established) ? ["a session state could not be established; it is reported unestablished, not idle"] : [])] };
|
|
124
165
|
return plan;
|
|
125
166
|
}
|
|
126
167
|
|
|
127
|
-
/**
|
|
128
|
-
*
|
|
129
|
-
*
|
|
130
|
-
|
|
168
|
+
/** The field of a stop receipt FILE, never of an answer, that says its rows were written under the
|
|
169
|
+
* rules of feature `lifecycle-kernel-codes`: a kernel code in every failed row, and `stillRunning:
|
|
170
|
+
* []` only for a harness that exited (core.mjs stillRunningOf). A replay strips it. */
|
|
171
|
+
const STORED_UNDER_KERNEL_CODES = "lifecycleKernelCodes";
|
|
172
|
+
/** The results of a receipt stored WITHOUT that field, by a kernel from before the feature, as this
|
|
173
|
+
* kernel answers them: a replay is an answer of this kernel. Such a failed row can hold the
|
|
174
|
+
* system's own code, which becomes E_SESSION_STOP_FAILED (the row's message keeps the system's
|
|
175
|
+
* text), and `stillRunning: []`, which that kernel wrote only for a stop whose signalled processes
|
|
176
|
+
* were gone while the session did not read as idle: null, nothing established. The stored file is
|
|
177
|
+
* evidence and is never rewritten. */
|
|
178
|
+
function replayedResults(results) {
|
|
179
|
+
if (!Array.isArray(results)) return results;
|
|
180
|
+
return results.map((r) => {
|
|
181
|
+
if (!r || typeof r !== "object" || r.ok !== false) return r;
|
|
182
|
+
const code = "code" in r && !isAnswerCode(r.code) ? { code: "E_SESSION_STOP_FAILED" } : {};
|
|
183
|
+
const none = Array.isArray(r.stillRunning) && !r.stillRunning.length ? { stillRunning: null } : {};
|
|
184
|
+
return { ...r, ...code, ...none };
|
|
185
|
+
});
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/** How many times a stop apply takes its targets' claims before it gives up on a set of targets
|
|
189
|
+
* that is another one under each read (applyStop, step 4). One pass is every stop there is but
|
|
190
|
+
* the one that meets a child appearing between its two reads. */
|
|
191
|
+
const STOP_CLAIM_PASSES = 3;
|
|
192
|
+
|
|
193
|
+
/** Apply a Stop plan. A stop holds the lifecycle claim of EVERY target (core claimHomeFor, the
|
|
194
|
+
* retire's file) before it stops the first one, and until it has written its receipt
|
|
195
|
+
* (awebai/oats#866, #890). The one exception (awebai/oats#946): a target whose claim cannot be
|
|
196
|
+
* WRITTEN, for a reason of the system's that stops every other writer of this user as well
|
|
197
|
+
* (lib/claim.mjs CLAIM_UNWRITABLE_CODES: a full disk, a directory that is not writable), is
|
|
198
|
+
* read where it would have been taken, and the stop goes on when nobody holds it, holding
|
|
199
|
+
* nothing for that target and saying so (STOP_WARNINGS). In this order:
|
|
200
|
+
* 1. the plan, read for its targets and for the home of the receipt;
|
|
201
|
+
* 2. a receipt recorded under the same key is replayed (STORED_UNDER_KERNEL_CODES,
|
|
202
|
+
* replayedResults): read-only, before any claim;
|
|
203
|
+
* 3. the claim of every target, in one fixed order (by claim path), so that two overlapping
|
|
204
|
+
* stops cannot each hold half: one wins the first file both want, the other is refused at
|
|
205
|
+
* once and releases what it took. A holder is answered here, before a stale plan:
|
|
206
|
+
* E_INSTANCE_RETIRING beside a retire, E_LIFECYCLE_BUSY beside a stop, with the plan read
|
|
207
|
+
* before the claims. A claim that is only read answers the same for whoever holds it;
|
|
208
|
+
* 4. the plan again, under the claims: the plan that is acted on. Every target IT names is held
|
|
209
|
+
* by this apply before anything is done: one it does not hold (a child recorded, or readable
|
|
210
|
+
* again, since the read of 1) sends the apply back to 3 with this plan's targets, every claim
|
|
211
|
+
* released first, so that the order of 3 holds (STOP_CLAIM_PASSES bounds it). A target whose
|
|
212
|
+
* claim was only read counts as covered, and is read once more here, with the same read: the
|
|
213
|
+
* last look before the first signal, answered before a stale plan as a holder is in 3. Then
|
|
214
|
+
* the one comparison with the revision the caller sent: a child retired or re-made, a session started
|
|
215
|
+
* or ended, a self-retire scheduled since the plan was shown is E_PLAN_STALE with the fresh
|
|
216
|
+
* plan (the guarded retire's pattern, core RETIRE_UNDER_CLAIM). The plan's own refusals come
|
|
217
|
+
* from this read too: the instance itself retired since (E_SESSION_UNKNOWN), its record no
|
|
218
|
+
* longer readable (E_UNIDENTIFIED_INSTANCE_HOME);
|
|
219
|
+
* 5. a scheduled self-retire the caller was shown: E_INSTANCE_RETIRING;
|
|
220
|
+
* 6. a marker an older kernel left in a target is removed (leftoverStopMarkerPath);
|
|
221
|
+
* 7. each target is stopped, deepest first; 8. the receipt is written; 9. the claims are released.
|
|
222
|
+
* Everything through 6 is before any effect. From 7 on no answer says that nothing happened: a
|
|
223
|
+
* target's failure is a row of the receipt, and an error that would leave with a code this verb
|
|
224
|
+
* answers only before any effect is a kernel defect (lib/errors.mjs afterFirstEffect). */
|
|
131
225
|
export function applyStop(ctx, root, name, { home, recursive = true, planRevision: expected, idempotencyKey, graceMs } = {}) {
|
|
132
226
|
if (typeof expected !== "string" || !expected) throw oatsError("E_BAD_ARGS", "apply needs --plan-revision from a prior `--plan`");
|
|
133
227
|
if (typeof idempotencyKey !== "string" || !KEY.test(idempotencyKey)) throw oatsError("E_BAD_ARGS", "apply needs --idempotency-key (1-128 chars of [A-Za-z0-9._:-])");
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
const
|
|
144
|
-
|
|
228
|
+
// Here, for the whole apply: refused per target it would be one row each, after the key was used.
|
|
229
|
+
requireStopGrace(graceMs);
|
|
230
|
+
const shown = planStop(ctx, root, name, { home, recursive });
|
|
231
|
+
const prior = readJson(stopReceiptPath(shown.home, idempotencyKey));
|
|
232
|
+
if (prior && prior.idempotencyKey === idempotencyKey) {
|
|
233
|
+
// A receipt this kernel stored is replayed as stored, without the file's own field.
|
|
234
|
+
const { [STORED_UNDER_KERNEL_CODES]: current, ...stored } = prior;
|
|
235
|
+
return { ...stored, results: current === true ? stored.results : replayedResults(stored.results), replayed: true };
|
|
236
|
+
}
|
|
237
|
+
const held = [];
|
|
238
|
+
const release = () => { for (const h of held.splice(0)) releaseHomeClaim(h); };
|
|
239
|
+
// Whether the first target's stop began: the one fact that says an effect may have happened.
|
|
240
|
+
let began = false;
|
|
145
241
|
try {
|
|
242
|
+
let plan;
|
|
243
|
+
for (let before = shown, pass = 1; ; pass++) {
|
|
244
|
+
const order = before.targets.map((t) => ({ t, lock: retireClaimPath(t.home) })).sort((a, b) => (a.lock < b.lock ? -1 : a.lock > b.lock ? 1 : 0));
|
|
245
|
+
for (const { t } of order) {
|
|
246
|
+
// The refusal's details are of the target whose claim refused, which may be a child.
|
|
247
|
+
// A claim that cannot be written is read in its place (#946): held, or held by nobody.
|
|
248
|
+
try { held.push({ ...claimHomeFor("stop", t.instance, t.home, { [READ_CLAIM_WHEN_UNWRITABLE]: true }), instance: t.instance }); } catch (e) { throw Object.assign(e, { plan: before }); }
|
|
249
|
+
}
|
|
250
|
+
const fresh = planStop(ctx, root, name, { home, recursive, [OWN_HOLDINGS]: new Set(held.filter((h) => h.me).map((h) => h.me.nonce)) });
|
|
251
|
+
const mine = new Set(held.map((h) => h.lock));
|
|
252
|
+
// A claim it holds for a home the fresh plan no longer names is released with the rest.
|
|
253
|
+
if (fresh.targets.every((t) => mine.has(retireClaimPath(t.home)))) { plan = fresh; break; }
|
|
254
|
+
release();
|
|
255
|
+
if (pass === STOP_CLAIM_PASSES) throw Object.assign(lifecycleBusy("none", `the instances a stop of ${name} would stop changed each of the ${pass} times their claims were taken; nothing was stopped`, "run the command again", { instance: name, home: fresh.home }), { plan: fresh });
|
|
256
|
+
before = fresh;
|
|
257
|
+
}
|
|
258
|
+
// The targets whose claim was only read, of this plan: nothing is held for them, so the same
|
|
259
|
+
// read is made again here, the last look before the first signal. A holder that came since
|
|
260
|
+
// is answered as a held claim's is, before a stale plan.
|
|
261
|
+
const targets = new Set(plan.targets.map((t) => retireClaimPath(t.home)));
|
|
262
|
+
const unheld = held.filter((h) => !h.me && targets.has(h.lock));
|
|
263
|
+
for (const h of unheld) { try { h.look(); } catch (e) { throw Object.assign(e, { plan }); } }
|
|
264
|
+
if (plan.planRevision !== expected) throw Object.assign(oatsError("E_PLAN_STALE", `the stop plan changed since it was shown (${expected} → ${plan.planRevision}); review the fresh plan`), { plan });
|
|
265
|
+
const retiring = plan.targets.filter((t) => t.retiring);
|
|
266
|
+
if (retiring.length) throw Object.assign(oatsError("E_INSTANCE_RETIRING", `${retiring.map((t) => t.instance).join(", ")} ${retiring.length === 1 ? "is" : "are"} being retired; nothing was stopped`), { plan });
|
|
267
|
+
// The system's code, never its message. The claim's own path, also when the write that
|
|
268
|
+
// failed was a takeover's.
|
|
269
|
+
const warnings = unheld.map((h) => `${h.instance}: stopping without its claim: ${h.lock} could not be written (${h.unwritable}), and nobody holds it. A retire or a stop of ${h.instance} that starts while this one runs will not see it.`);
|
|
270
|
+
for (const t of plan.targets) {
|
|
271
|
+
const left = leftoverStopMarkerPath(t.home);
|
|
272
|
+
try { rmSync(left, { force: true }); } catch (e) { warnings.push(`${left}, a stop marker an older OATS left, could not be removed (${e?.message ?? e}); it refuses nothing, and the stop went on`); }
|
|
273
|
+
}
|
|
274
|
+
const results = [];
|
|
146
275
|
for (const t of plan.targets) {
|
|
276
|
+
began = true;
|
|
147
277
|
try {
|
|
148
|
-
const r = stopInstanceSession(t.home, { graceMs });
|
|
278
|
+
const r = stopInstanceSession(t.home, { graceMs, [STOP_UNDER_CLAIM]: true });
|
|
149
279
|
results.push({ instance: t.instance, home: t.home, ok: true, stopped: r.stopped, alreadyIdle: r.alreadyIdle, state: r.state });
|
|
150
280
|
} catch (e) {
|
|
151
|
-
|
|
281
|
+
reportDefect(e); // the error becomes a row here: its stack would otherwise be lost
|
|
282
|
+
results.push({ instance: t.instance, home: t.home, ok: false, code: kernelCode(e, "E_SESSION_STOP_FAILED"), message: e.message, stillRunning: stillRunningOf(e) });
|
|
152
283
|
}
|
|
153
284
|
}
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
285
|
+
const receipt = { lifecycleApi: LIFECYCLE_API, action: "stop", instance: name, home: plan.home, idempotencyKey, planRevision: expected, at: new Date().toISOString(),
|
|
286
|
+
ok: results.every((r) => r.ok), results, retained: ["home", "work", "transcript", "launch"], replayed: false };
|
|
287
|
+
// One receipt file per key: a retry of ANY earlier key replays its own
|
|
288
|
+
// receipt for as long as the home exists (the replay horizon).
|
|
289
|
+
try { writeFileSyncAtomic(stopReceiptPath(plan.home, idempotencyKey), { ...receipt, [STORED_UNDER_KERNEL_CODES]: true }); } catch { /* receipt is evidence, not authority */ }
|
|
290
|
+
return warnings.length ? Object.defineProperty(receipt, STOP_WARNINGS, { value: warnings }) : receipt;
|
|
291
|
+
} catch (e) {
|
|
292
|
+
throw began ? afterFirstEffect(e, "instance stop", "a target's stop had begun") : e;
|
|
293
|
+
} finally {
|
|
294
|
+
release();
|
|
295
|
+
}
|
|
161
296
|
}
|
|
162
297
|
|
|
163
|
-
|
|
298
|
+
/** Write `value` as JSON at `path` through a private file beside it, renamed over it. When the
|
|
299
|
+
* write or the rename fails the private file is removed and the error thrown is that failure's
|
|
300
|
+
* (awebai/oats#963, as core.mjs writeJsonAtomic). The removal's own failure is not answered.
|
|
301
|
+
* Exported for its test alone (test/stop-private-files.test.mjs): its one caller keeps the error
|
|
302
|
+
* to itself, so nothing but a call of it shows what it throws. */
|
|
303
|
+
export function writeFileSyncAtomic(path, value) {
|
|
164
304
|
const tmp = `${path}.${process.pid}.tmp`;
|
|
165
|
-
|
|
305
|
+
try {
|
|
306
|
+
writeFileSync(tmp, JSON.stringify(value, null, 2)); renameSync(tmp, path);
|
|
307
|
+
} catch (e) {
|
|
308
|
+
try { rmSync(tmp, { force: true }); } catch { /* the first error is the one answered */ }
|
|
309
|
+
throw e;
|
|
310
|
+
}
|
|
166
311
|
}
|
|
167
312
|
|
|
168
|
-
/**
|
|
313
|
+
/** The sentence a stop's text closes with, chosen from the receipt's rows as a client reads them
|
|
314
|
+
* (docs/desktop-cli-api.md, `stillRunning`): a failed row whose `stillRunning` names a process,
|
|
315
|
+
* or is `null` or absent (nothing established), may still run; `[]` says stopped. A receipt that
|
|
316
|
+
* is not `ok` while no failed row has anything still running is a stop that stopped its targets
|
|
317
|
+
* and could not complete its record (a write into the home refused: a full disk), and the text
|
|
318
|
+
* must not say that something still runs (awebai/oats#963). Fixed sentences; the JSON receipt
|
|
319
|
+
* is not made from this. */
|
|
320
|
+
export function stopClosingLine(receipt) {
|
|
321
|
+
if (receipt.ok) return `stopped${receipt.replayed ? " (replayed receipt)" : ""}; home, work, transcript and launch configuration retained — restart with \`oats session restart\``;
|
|
322
|
+
const mayRun = receipt.results.some((r) => !r.ok && !(Array.isArray(r.stillRunning) && r.stillRunning.length === 0));
|
|
323
|
+
return mayRun ? "some targets are still running; nothing was escalated" : "the stop did not complete its record; nothing is still running";
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
/** What the Desktop reads of a plan's notes (packages/client/lifecycle-contract.mjs): at
|
|
169
327
|
* most 64, each at most 4096 characters; it refuses a plan with more, so every note is built to fit
|
|
170
328
|
* (#658). A path is never cut: what does not fit is left to the plan JSON or the receipt. */
|
|
171
329
|
const PLAN_NOTES_MAX = 64;
|
|
@@ -257,37 +415,73 @@ const PLAN_NOT_COPIED_CAP = 16;
|
|
|
257
415
|
* is the dialog's opt-in. No retire deletes a branch: `deleteBranch` is
|
|
258
416
|
* always false. */
|
|
259
417
|
export function planRetire(ctx, root, name, { home } = {}) {
|
|
260
|
-
const me =
|
|
418
|
+
const me = resolveTarget(ctx, root, name, { home });
|
|
261
419
|
const kids = descendantsOf(me.root, name);
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
const meta =
|
|
420
|
+
// Read once, after the lineage: every fact of the plan that the record gives is of this read.
|
|
421
|
+
const recorded = targetRecord(me.home);
|
|
422
|
+
const meta = recorded || {};
|
|
423
|
+
const target = targetFacts({ ...me, instance: name, depth: 0 }, recorded);
|
|
424
|
+
target.session = retireSessionFacts(me.home, target.session, recorded);
|
|
265
425
|
// The home's extra trees and what retire does with each: listed, and bound
|
|
266
426
|
// into the revision (below), so that an apply refuses as stale when a tree
|
|
267
427
|
// was created, removed, dirtied or cleaned, or its target was taken.
|
|
268
428
|
const extraWorktrees = extraWorktreePlan(me.home, me.root);
|
|
429
|
+
// What work/ is, by the one function the retire reads too (core instanceWork, #962): the plan says
|
|
430
|
+
// what the retire will do with it.
|
|
431
|
+
const workIs = instanceWork(me.home, meta);
|
|
432
|
+
const ownTree = workIs.is === "own-tree", homeDirectory = workIs.is === "home-directory";
|
|
269
433
|
// A home spawned before #641 may record the word "HEAD" for a detached checkout: not a branch name.
|
|
270
|
-
|
|
434
|
+
// `ownWorktree` (#988, feature retire-plan-own-worktree) is that reading as a fact: whether work/
|
|
435
|
+
// is the instance's own work tree, the one this retire retains or removes. `workMode` is the
|
|
436
|
+
// record's value, which the instance can write, and `work` observes through any link: neither
|
|
437
|
+
// says whose tree it is. A stop plan does not carry it.
|
|
438
|
+
const facts = { session: target.session, work: target.work, workMode: meta.work ?? null, ownWorktree: ownTree, repo: meta.repo ?? null, recordedBranch: meta.branch === "HEAD" ? null : meta.branch ?? null,
|
|
271
439
|
extraWorktrees,
|
|
272
440
|
children: kids.map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, session: sessionFacts(c.home) })),
|
|
273
441
|
ambiguous: (kids.ambiguous || []).map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, reason: c.reason })),
|
|
274
442
|
pullRequest: "unknown" /* forge facts are the ADE's (P1); the kernel never claims 'no PR' */ };
|
|
275
|
-
|
|
443
|
+
// `retainWorktree` is the default of one option, whether the instance's own tree is retained. It
|
|
444
|
+
// follows the reading of work/ today, as the fact above does: a default is what the retire would
|
|
445
|
+
// do if nobody chose, a fact is what is there, and a client reads neither as the other.
|
|
446
|
+
// A link under a record that says `worktree` (#973): the link decides, and the plan says so.
|
|
447
|
+
const linkNotOwn = workIs.is === "link" && meta.work === "worktree";
|
|
448
|
+
const defaults = { retainWorktree: ownTree, deleteBranch: false, stopChildren: true, retainChildren: true };
|
|
449
|
+
// The repository the retire would read from Git for an own tree whose record names none.
|
|
450
|
+
const repoFromGit = ownTree && !meta.repo ? workIs.tree?.repo ?? null : null;
|
|
451
|
+
const byModeAlone = meta.work === "worktree" ? "own-tree" : meta.work === "directory" ? "directory-mode" : workIs.at;
|
|
452
|
+
const workBinding = workIs.is !== byModeAlone || repoFromGit ? { work: workIs.is, repo: repoFromGit } : null;
|
|
276
453
|
const safety = [me.home, target.session.state, target.launched, facts.work.observed ? [facts.work.revision, facts.work.branch, facts.work.changed, facts.work.untracked] : null, kids.map((c) => c.home),
|
|
277
454
|
// Only when there are any: a home without extra trees keeps the revision it had.
|
|
278
|
-
...(extraWorktrees.length ? [extraWorktrees] : [])
|
|
455
|
+
...(extraWorktrees.length ? [extraWorktrees] : []),
|
|
456
|
+
// What work/ is decides what the retire does with it (#962), so it is part of the revision: a
|
|
457
|
+
// guarded apply refuses as stale when an own tree became a directory of the home, or the other
|
|
458
|
+
// way round, since the plan was shown, and when the repository read from Git changed. A link
|
|
459
|
+
// under a record that says `worktree` is bound the same way (#973): a plan read while work/ was
|
|
460
|
+
// a link is stale once work/ is the instance's own tree, and the other way round. Only where
|
|
461
|
+
// the answer is not the one the record's mode alone gives: every other home keeps the revision
|
|
462
|
+
// it had.
|
|
463
|
+
...(workBinding ? [workBinding] : [])];
|
|
279
464
|
// What retire would preserve and where, read from the spawn baseline and the
|
|
280
465
|
// work mode: nothing is hashed, and the plan revision does not depend on it.
|
|
281
466
|
// The declared roots are listed as written, bounded so one note stays short.
|
|
282
467
|
const recovery = retirementRecoveryFacts(me.home);
|
|
283
468
|
// Attached children whose work is this home's work/ (#718): a retire that keeps the worktree
|
|
284
469
|
// repoints them to it. One note holds whatever the dialog then picks.
|
|
285
|
-
const attached =
|
|
470
|
+
const attached = ownTree ? kids.filter((c) => attachedWorkLink(c.home, me.home) !== null) : [];
|
|
286
471
|
appendEvent(me.home, { kind: "retire-planned", data: { planRevision: planRevision(safety), children: kids.length, dirty: facts.work.observed ? facts.work.changed + facts.work.untracked : null } }, { workspaceOnly: true });
|
|
287
|
-
|
|
472
|
+
const plan = { lifecycleApi: LIFECYCLE_API, action: "retire", instance: name, home: me.home, at: new Date().toISOString(), facts, defaults, planRevision: planRevision(safety),
|
|
288
473
|
notes: boundedNotes(extraWorktrees.map(extraWorktreeNote), [
|
|
289
|
-
|
|
290
|
-
|
|
474
|
+
// The two notes about a worktree that is retained are for the instance's own tree alone (#973).
|
|
475
|
+
// Not for a directory of the home (what it holds is copied and removed), not for a directory
|
|
476
|
+
// instance whose work/ is a repository of its own (the recovery note below says what is done),
|
|
477
|
+
// and not for a link: facts.work observes what the link leads to, which is another's tree
|
|
478
|
+
// (its owner's, the shared checkout, the deployment) that the retire neither keeps nor moves.
|
|
479
|
+
...(ownTree && facts.work.observed && facts.work.drift ? [driftNote(facts.work, facts.recordedBranch)] : []),
|
|
480
|
+
...(ownTree && facts.work.observed && facts.work.changed + facts.work.untracked > 0 ? [`${facts.work.changed} changed and ${facts.work.untracked} untracked file(s) would be retained with the worktree`] : []),
|
|
481
|
+
...(homeDirectory ? [HOME_DIRECTORY_NOTE] : []),
|
|
482
|
+
...(linkNotOwn ? [LINK_NOTE] : []),
|
|
483
|
+
...(homeDirectory && workIs.tree ? [`work/ is registered as a worktree of ${workIs.tree.repo}: the retire leaves its entry there until a prune (git -C ${shq(workIs.tree.repo)} worktree prune), and does not touch its branch or its commits`] : []),
|
|
484
|
+
...(repoFromGit ? [`the record names no repository for the work tree: the retire uses the one Git names for it, ${repoFromGit}, and does not write it into the record`] : []),
|
|
291
485
|
], [
|
|
292
486
|
...(kids.length ? [`${kids.length} recorded child instance(s) are stopped first (bounded SIGTERM, never escalated) and retained (their homes are not removed); a child still running after the grace refuses the retirement`] : []),
|
|
293
487
|
...(attached.length ? [`attached child instance(s) ${listWithin(attached.map((c) => c.instance), (shown) => shown.join(", "), PLAN_LIST_BUDGET) ?? attached.length} use this home's work/ as their work: a retire that keeps the worktree repoints their work link to it; with --discard-worktree the worktree is removed and their work link will dangle`] : []),
|
|
@@ -295,8 +489,63 @@ export function planRetire(ctx, root, name, { home } = {}) {
|
|
|
295
489
|
...(target.session.note ? [sessionNote(target.session)] : []),
|
|
296
490
|
"pull request state is unknown to the kernel; the ADE reports it when a forge connection exists",
|
|
297
491
|
recoveryNote(recovery),
|
|
298
|
-
...(
|
|
492
|
+
...(ownTree ? ["recovery: uncommitted worktree state is copied there too"] : homeDirectory || meta.work === "directory" ? ["recovery: work/ is copied there when it is not empty"] : []),
|
|
299
493
|
]) };
|
|
494
|
+
// For the plan's text alone (retireDefaultsLine): not part of the plan's JSON.
|
|
495
|
+
Object.defineProperty(plan, PLAN_WORK, { value: workIs.is });
|
|
496
|
+
return plan;
|
|
497
|
+
}
|
|
498
|
+
|
|
499
|
+
/** A retire plan's own answer to what work/ is (core instanceWork), kept on the plan object for its
|
|
500
|
+
* text line and never serialised: the plan's JSON has no field for it. */
|
|
501
|
+
const PLAN_WORK = Symbol("oats.retire-plan.work");
|
|
502
|
+
/** The plan's note for a real directory at work/ that is not the instance's own tree (#962). */
|
|
503
|
+
const HOME_DIRECTORY_NOTE = "work/ is a real directory of the home and not a work tree of the instance's own: the retire copies it to recovery when it is not empty (a .git in it included), checks the copy, and removes it with the home";
|
|
504
|
+
/** The same, as the plan's text says it where a `worktree` instance's says "retain worktree". */
|
|
505
|
+
const HOME_DIRECTORY_SENTENCE = "no work tree of its own (work/ is a real directory of the home: copied to recovery when not empty and then removed with the home)";
|
|
506
|
+
|
|
507
|
+
/** The plan's note for a link at work/ under a record that says `worktree` (#973). It names no
|
|
508
|
+
* target: the plan's revision does not bind where the link leads. It names the flag: a plan takes
|
|
509
|
+
* no option (`--plan --discard-worktree` answers this same plan), and no worktree step runs for a
|
|
510
|
+
* link with the flag either, which the plan says before the receipt does. */
|
|
511
|
+
const LINK_NOTE = "the record says work mode worktree, but work/ is a link and not a work tree of the instance's own: the retire removes the link with the home and does not touch what it leads to, with --discard-worktree as well";
|
|
512
|
+
/** The same, as the plan's text says it where a `worktree` instance's says "retain worktree". */
|
|
513
|
+
const LINK_SENTENCE = "no work tree of its own (work/ is a link, though the record says worktree: what it leads to is not touched)";
|
|
514
|
+
|
|
515
|
+
/** What a retire does with `work/` in each work mode that has no work tree of its own, as the plan's
|
|
516
|
+
* text says it where a `worktree` instance's says "retain worktree" (awebai/oats#959). Each is what
|
|
517
|
+
* retireInstance does (lib/core.mjs): `work/` of an attached, checkout or workspace instance is a
|
|
518
|
+
* link the spawn made, which goes with the home and whose target no step of the retire reads as a
|
|
519
|
+
* tree to move or remove; `work/` of a directory instance is the home's own directory, copied to
|
|
520
|
+
* recovery when it holds anything and then removed with the home. */
|
|
521
|
+
const RETIRE_WORK_SENTENCES = {
|
|
522
|
+
attached: "no work tree of its own (work/ links to its owner's tree and that tree is not touched)",
|
|
523
|
+
checkout: "no work tree of its own (work/ links to the shared checkout and that checkout is not touched)",
|
|
524
|
+
workspace: "no work tree of its own (work/ links to the deployment directory and that directory is not touched)",
|
|
525
|
+
directory: "no work tree (work/ is the home's own directory: copied to recovery when not empty and then removed with the home)",
|
|
526
|
+
};
|
|
527
|
+
/** The `defaults:` line of a retire plan's text. `defaults.retainWorktree` is the default of one
|
|
528
|
+
* option, whether the instance's OWN work tree is retained, and is `true` only when `work/` is
|
|
529
|
+
* that tree (below): printed as `false` for a home without one it reads as if a tree were
|
|
530
|
+
* removed, so the line says what is true of that mode's work instead. A record with no work mode, or one this kernel does not know
|
|
531
|
+
* (a value that is not a string included: it is never read as a mode's name), says so, in the
|
|
532
|
+
* kernel's words alone: the value is the record's, which the instance can write, and is never
|
|
533
|
+
* printed (`facts.workMode` of the JSON holds it). The plan's JSON is not changed by any of this.
|
|
534
|
+
*
|
|
535
|
+
* What is at `work/` comes first (#962, the plan's own answer, PLAN_WORK): a real directory that is
|
|
536
|
+
* not the instance's own tree is said as that, whatever the mode, and the instance's own tree is
|
|
537
|
+
* "retain worktree", whatever the mode (a record with no work mode whose `work/` Git confirms is a
|
|
538
|
+
* registered worktree). A link under a record that says `worktree` is said as a link, never as
|
|
539
|
+
* "retain worktree false" (#973). A plan object without that answer is read by its mode alone. */
|
|
540
|
+
export function retireDefaultsLine(plan) {
|
|
541
|
+
const mode = plan.facts.workMode;
|
|
542
|
+
const work = plan[PLAN_WORK] === "home-directory" ? HOME_DIRECTORY_SENTENCE
|
|
543
|
+
: plan[PLAN_WORK] === "link" && mode === "worktree" ? LINK_SENTENCE
|
|
544
|
+
: mode === "worktree" || plan[PLAN_WORK] === "own-tree" ? `retain worktree ${plan.defaults.retainWorktree}`
|
|
545
|
+
: typeof mode === "string" && Object.hasOwn(RETIRE_WORK_SENTENCES, mode) ? RETIRE_WORK_SENTENCES[mode]
|
|
546
|
+
: mode === null || mode === undefined ? "work mode not recorded"
|
|
547
|
+
: "work mode not known to this kernel";
|
|
548
|
+
return `defaults: ${work}, delete branch ${plan.defaults.deleteBranch}, stop children ${plan.defaults.stopChildren}`;
|
|
300
549
|
}
|
|
301
550
|
|
|
302
551
|
/** A retire plan's notes in order: `before`, one per extra tree, `after`. The extra trees are the
|
|
@@ -108,10 +108,6 @@ export function homeSoulMatches(name, meta) {
|
|
|
108
108
|
return soulNameMatches(name, soul.package && typeof soul.package === "object" ? { name: soul.name, package: soul.package.id } : { name: meta?.agent, repoKey: soul.repoKey });
|
|
109
109
|
}
|
|
110
110
|
|
|
111
|
-
/** Find the soul named `name` in a discovery: confirmed members, external souls and package
|
|
112
|
-
* souls. A bare name must be unique across all three (else E_SOUL_AMBIGUOUS naming each
|
|
113
|
-
* qualified form); `<repo>/<soul>` names a member (its key, a key suffix or its member name)
|
|
114
|
-
* or an external source, `<package>/<soul>` a package soul. */
|
|
115
111
|
/** Every soul a discovery offers, each with the rule a typed name matches it by: the confirmed
|
|
116
112
|
* members' souls (a standalone view's one row is the repo's own, unconfirmed by definition — the
|
|
117
113
|
* workspace could not be read; resolveSoul admits exactly that case), the external souls, and the
|
|
@@ -134,6 +130,48 @@ export function soulCandidates(discovery) {
|
|
|
134
130
|
return out;
|
|
135
131
|
}
|
|
136
132
|
|
|
133
|
+
/**
|
|
134
|
+
* What a read of the workspace offered, for the keys of oats-local.yaml souls.launch: the description
|
|
135
|
+
* lib/launch-preference.mjs launchKeysUnmatched decides from. Built here, once, from the discovery:
|
|
136
|
+
* `keys`: the soul key (soulKeyOf) of every offered soul (soulCandidates), sorted. souls.disabled is
|
|
137
|
+
* not consulted: a soul not run on this machine is still a soul the workspace offers.
|
|
138
|
+
* `unread`: what this read could not see (discovery.soulsUnread, the members' rows):
|
|
139
|
+
* `all`: "standalone" in the standalone view of a workspace whose host cannot be read: the souls
|
|
140
|
+
* there are one member's, and the workspace's are not known. An explicit `standalone:` is
|
|
141
|
+
* the configured view: what it offers is all it offers.
|
|
142
|
+
* `bare`: why a soul keyed by its bare name may be missing: "member-unconfirmed" (a member the
|
|
143
|
+
* workspace lists and could not confirm), else "soul-unread" (a member's or an external
|
|
144
|
+
* soul skipped with a problem); null when every such soul was read.
|
|
145
|
+
* `packages`: { <id>: "package-unlocked" | "package-soul-unread" } for a package the workspace
|
|
146
|
+
* declares and the lock does not hold, or a locked one with a soul skipped.
|
|
147
|
+
* What a read did not record, it did not establish: a discovery with no `soulsUnread` record (whatever
|
|
148
|
+
* built it; discoverWorkspace and standaloneRepo always write one) says nothing about what it skipped,
|
|
149
|
+
* so `all` is "unrecorded" and every key is left unchecked.
|
|
150
|
+
*/
|
|
151
|
+
export function soulsOffered(discovery) {
|
|
152
|
+
const keys = [...new Set(soulCandidates(discovery).map((c) => soulKeyOf(c.entry)))].sort();
|
|
153
|
+
const record = discovery?.soulsUnread;
|
|
154
|
+
const recorded = record !== null && typeof record === "object" && ["members", "external", "packages", "unlocked"].every((k) => Array.isArray(record[k]));
|
|
155
|
+
const skipped = recorded ? record : {};
|
|
156
|
+
const standalone = discovery?.standalone === true;
|
|
157
|
+
const unconfirmed = !standalone && (discovery?.members || []).some((m) => !m.confirmed);
|
|
158
|
+
const packages = {};
|
|
159
|
+
for (const id of skipped.unlocked || []) packages[id] = "package-unlocked";
|
|
160
|
+
for (const id of skipped.packages || []) packages[id] = "package-soul-unread";
|
|
161
|
+
return {
|
|
162
|
+
keys,
|
|
163
|
+
unread: {
|
|
164
|
+
all: standalone && discovery.standaloneReason !== "explicit" ? "standalone" : recorded ? null : "unrecorded",
|
|
165
|
+
bare: unconfirmed ? "member-unconfirmed" : (skipped.members?.length || skipped.external?.length) ? "soul-unread" : null,
|
|
166
|
+
packages,
|
|
167
|
+
},
|
|
168
|
+
};
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/** Find the soul named `name` in a discovery: confirmed members, external souls and package
|
|
172
|
+
* souls. A bare name must be unique across all three (else E_SOUL_AMBIGUOUS naming each
|
|
173
|
+
* qualified form); `<repo>/<soul>` names a member (its key, a key suffix or its member name)
|
|
174
|
+
* or an external source, `<package>/<soul>` a package soul. */
|
|
137
175
|
export function findSoulEntry(discovery, name) {
|
|
138
176
|
const hits = soulCandidates(discovery).filter((c) => c.matches(name)).map((c) => c.entry);
|
|
139
177
|
if (hits.length === 0) throw err("E_SOUL_UNKNOWN", `no soul ${JSON.stringify(name)} among the confirmed members, external souls or package souls of this workspace`, { name, members: (discovery.members || []).filter((m) => m.confirmed).map((m) => m.key), packages: [...new Set((discovery.packageSouls || []).map((s) => s.package))].sort() });
|
|
@@ -188,6 +226,20 @@ export async function liveTeams(home, meta, { remoteOptions, remote } = {}) {
|
|
|
188
226
|
}
|
|
189
227
|
}
|
|
190
228
|
|
|
229
|
+
/**
|
|
230
|
+
* For `session start|restart --reselect-launch`: what the home's launch layers need of the workspace
|
|
231
|
+
* (lib/core.mjs homeLaunchLayers `offered`) to say which keys of souls.launch name no soul. The workspace
|
|
232
|
+
* is read only when `needed` (the home's soul has no entry of its own and souls.launch holds a key
|
|
233
|
+
* besides "*"); otherwise → null and nothing is read. A read that fails throws its own error: a
|
|
234
|
+
* selection that could not check those keys does not go on.
|
|
235
|
+
*/
|
|
236
|
+
export async function homeSoulsOffered(home, { needed, remoteOptions, remote } = {}) {
|
|
237
|
+
if (!needed) return null;
|
|
238
|
+
const deployment = dirname(dirname(dirname(dirname(resolvePath(home)))));
|
|
239
|
+
const found = loadLocal(deployment);
|
|
240
|
+
return soulsOffered(await discoverOrStandalone(found.local, { lock: readLockIfPresent(deployment), deployment, remoteOptions, remote }));
|
|
241
|
+
}
|
|
242
|
+
|
|
191
243
|
/** The per-commit soul cache under an agent directory: `<agentDir>/souls/<commit12>/`.
|
|
192
244
|
* Each entry is IMMUTABLE once written (fetched to staging, renamed in) and is never
|
|
193
245
|
* removed by the kernel — a running instance records its own commit's directory
|
|
@@ -515,8 +567,9 @@ export async function prepareInstance(contextDir, soulName, { spawn = {}, remote
|
|
|
515
567
|
const disabled = disabledEntry(local, soulEntry);
|
|
516
568
|
if (disabled !== null) throw err("E_SOUL_DISABLED", `soul ${qualifiedSoulName(soulEntry)} is disabled on this machine (oats-local.yaml souls.disabled: ${disabled}) — remove it from that list to spawn it here`, { name: soulEntry.name, qualifiedName: qualifiedSoulName(soulEntry), entry: disabled });
|
|
517
569
|
const resolution = await resolveSoul(discovery, soulEntry, { local, lock, spawn, remoteOptions, remote });
|
|
518
|
-
// The launch layers a new selection reads (feature launch-preference): souls.launch, the soul's own launch
|
|
519
|
-
|
|
570
|
+
// The launch layers a new selection reads (feature launch-preference): souls.launch, the soul's own launch,
|
|
571
|
+
// and, from this read of the workspace, the keys of souls.launch that name no soul it offers.
|
|
572
|
+
const launch = launchLayers({ definition: soulEntry.definition, entry: soulEntry, key: soulKeyOf(soulEntry), local, offered: soulsOffered(discovery) });
|
|
520
573
|
return { local, deployment, lock, discovery, soulEntry, resolution, remoteOptions, spawn, launch };
|
|
521
574
|
}
|
|
522
575
|
|