@awebai/oats 0.49.0 → 0.51.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 +150 -34
- package/docs/capabilities.md +172 -2
- package/docs/capability-manifest.schema.json +42 -0
- package/docs/configuration.md +97 -0
- package/docs/desktop-cli-api.md +268 -22
- package/docs/desktop.md +13 -0
- package/docs/execution-targets.md +120 -9
- package/docs/implementation.md +26 -6
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +20 -7
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +28 -14
- package/docs/release-lane.md +41 -0
- package/docs/release-notes/v0.50.0.md +279 -0
- package/docs/release-notes/v0.51.0.md +156 -0
- package/docs/schedules.md +228 -15
- package/docs/servers.md +21 -2
- package/docs/souls-and-instances.md +92 -8
- package/docs/workspaces.md +2 -2
- package/lib/capability-show.mjs +14 -1
- package/lib/claim.mjs +126 -0
- package/lib/core.mjs +428 -102
- package/lib/instance-events.mjs +3 -7
- package/lib/instance-git.mjs +8 -5
- package/lib/instance-inspect.mjs +44 -15
- package/lib/refused-text.mjs +17 -0
- package/lib/retained-after-retire.mjs +387 -0
- package/lib/schedule.mjs +8 -2
- package/lib/servers.mjs +20 -4
- package/lib/session-viewer.mjs +87 -10
- package/lib/trigger-sources.mjs +234 -0
- package/lib/triggers.mjs +521 -60
- package/lib/worktree-hooks.mjs +24 -9
- package/lib/worktree.mjs +14 -86
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +1 -1
package/lib/core.mjs
CHANGED
|
@@ -45,11 +45,12 @@ import { createHash, randomUUID } from "node:crypto";
|
|
|
45
45
|
import { fileURLToPath } from "node:url";
|
|
46
46
|
import { initializeNativeHistory, prepareNativeStart } from "../packages/record/lib/native-history.mjs";
|
|
47
47
|
import { noteRuntimeName } from "./deprecation.mjs";
|
|
48
|
-
import { attachSessionTarget } from "./session-viewer.mjs";
|
|
48
|
+
import { attachSessionTarget, requireDetachKey } from "./session-viewer.mjs";
|
|
49
49
|
import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
|
|
50
50
|
import { appendEvent, liveWaiting, recordStartBoundary } from "./instance-events.mjs";
|
|
51
51
|
import { killGroup } from "./process-group.mjs";
|
|
52
52
|
import { interruptExitStatus, originRemoteOf, runWorktreeHooks, selfIdentity, processLiveness, processStartToken, signalGuard, terminateRecordedGroup, treeStillThere, unknownGroupNote, unverifiedGroupWarning, worktreeHooksOf } from "./worktree-hooks.mjs";
|
|
53
|
+
import { CLAIM_WAIT_MS, acquireClaim, releaseClaim, removeGoneClaim } from "./claim.mjs";
|
|
53
54
|
import { captureLoginEnvironment } from "./login-environment.mjs";
|
|
54
55
|
|
|
55
56
|
import { oatsError, herdrInstanceBusy, herdrInstanceRemoved, herdrSettingRemoved, HERDR_REMOVED } from "./errors.mjs";
|
|
@@ -126,6 +127,11 @@ export function legacyLocalAgents(root) {
|
|
|
126
127
|
return { code: "legacy-local-agents", dirs, instances,
|
|
127
128
|
message: `${instances.length} instance home${instances.length === 1 ? "" : "s"} under local-agents/ ${instances.length === 1 ? "is" : "are"} from OATS 0.25 and ${instances.length === 1 ? "is" : "are"} not managed by this kernel; retire ${instances.length === 1 ? "it" : "them"} with the 0.25 kernel or delete the directory once ${instances.length === 1 ? "it is" : "they are"} stopped${instances.length ? ` (${instances.join(", ")})` : ""}` };
|
|
128
129
|
}
|
|
130
|
+
/** The instances directories under the agents root `root`: `<root>/<agent>/instances`, one per
|
|
131
|
+
* agent directory, whether or not it exists. */
|
|
132
|
+
export function instancesDirs(root) {
|
|
133
|
+
return subdirs(root).map((agent) => join(root, agent, "instances"));
|
|
134
|
+
}
|
|
129
135
|
/** The instance homes under the agents root `root` (a directory <root>/<agent>/instances/<name>
|
|
130
136
|
* whose instance.json records that name) that other users on the machine can read or enter (any
|
|
131
137
|
* group or other permission bit): one `home-readable` problem naming them, with the exact chmod,
|
|
@@ -583,7 +589,7 @@ export const RESERVED_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME
|
|
|
583
589
|
"OATS_TEST_LOGIN_SHELL",
|
|
584
590
|
// The test seams of #796, the same: a worktree hook's fixed timeout, the fetch timeout of
|
|
585
591
|
// `oats worktree add` (lib/worktree-hooks.mjs, lib/worktree.mjs), and the `ps` path of a
|
|
586
|
-
// process's start time on a host with procfs (lib/worktree-hooks.mjs processStart).
|
|
592
|
+
// process's start time on a host with procfs, and the `ps` it runs (lib/worktree-hooks.mjs processStart).
|
|
587
593
|
"OATS_TEST_WORKTREE_HOOK_TIMEOUT_MS", "OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS", "OATS_TEST_PROCESS_START_PS"]);
|
|
588
594
|
export const LAUNCH_REF_PREFIX = "OATS_LAUNCH_REF_";
|
|
589
595
|
const reservedLaunchEnv = (n) => RESERVED_LAUNCH_ENV.has(n) || n.startsWith(LAUNCH_REF_PREFIX);
|
|
@@ -1966,12 +1972,22 @@ export function explicitInstanceName(name) {
|
|
|
1966
1972
|
return name;
|
|
1967
1973
|
}
|
|
1968
1974
|
|
|
1969
|
-
function tmuxAlive(session) { return !!shTry(`tmux has-session -t ${shq(session)} 2>/dev/null && echo yes`); }
|
|
1970
1975
|
/** The window names of `session` on the user's DEFAULT tmux server: only for a home that records no
|
|
1971
1976
|
* socket (listInstances). OATS creates nothing there: new sessions live on the OATS server below. */
|
|
1972
|
-
export function tmuxWindows(session = DEFAULT_TMUX_SESSION) {
|
|
1973
|
-
|
|
1974
|
-
|
|
1977
|
+
export function tmuxWindows(session = DEFAULT_TMUX_SESSION) { return defaultTmuxWindows(session).windows; }
|
|
1978
|
+
/** tmuxWindows' read, keeping a missing socket file apart (#624): `{ windows }`, with `missingSocket`
|
|
1979
|
+
* (tmux's words) when the default server's socket file is missing. Any other failure reads as no
|
|
1980
|
+
* session. `has-session` first, as ever: it is the read-only probe a caller may expect for a home
|
|
1981
|
+
* that records no socket, and it words a missing socket file as list-windows does. */
|
|
1982
|
+
function defaultTmuxWindows(session) {
|
|
1983
|
+
const run = (args) => execFileSync("tmux", args, { encoding: "utf8", timeout: 10000, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
|
|
1984
|
+
try {
|
|
1985
|
+
run(["has-session", "-t", session]);
|
|
1986
|
+
return { windows: run(["list-windows", "-t", session, "-F", "#{window_name}"]).split("\n").filter(Boolean) };
|
|
1987
|
+
} catch (e) {
|
|
1988
|
+
// Either read: the socket file can go between the two.
|
|
1989
|
+
return tmuxServerAbsence(e) === "missing-socket" ? { windows: [], missingSocket: tmuxFailure(e, "tmux failed") } : { windows: [] };
|
|
1990
|
+
}
|
|
1975
1991
|
}
|
|
1976
1992
|
|
|
1977
1993
|
// ---------- the OATS tmux server ----------
|
|
@@ -2003,8 +2019,11 @@ const exitedByItself = (e) => Number.isInteger(e?.status) && e.signal == null &&
|
|
|
2003
2019
|
/** What the OATS server holds, as `list-sessions` answers: whether it runs, its socket (any session
|
|
2004
2020
|
* names it), and whether a session named exactly `session` is there. No server and no such session
|
|
2005
2021
|
* are the only answers that mean absent, and "no server" is read only from a call that exited by
|
|
2006
|
-
* itself: a line a cut-off call left behind is not tmux's answer. Any other failure is not absence.
|
|
2007
|
-
|
|
2022
|
+
* itself: a line a cut-off call left behind is not tmux's answer. Any other failure is not absence.
|
|
2023
|
+
* A missing socket file is absence only when `missingSocket(detail)` (a session start's check of its
|
|
2024
|
+
* home, missingSocketUnestablished) answers null; its reason refuses the start (#624). Without it, as
|
|
2025
|
+
* today. */
|
|
2026
|
+
function oatsTmuxSessionSocket(session, io, missingSocket) {
|
|
2008
2027
|
let listed;
|
|
2009
2028
|
try { listed = tmuxOatsServer(["list-sessions", "-F", "#{session_name}\t#{socket_path}"], io); }
|
|
2010
2029
|
catch (e) {
|
|
@@ -2012,7 +2031,10 @@ function oatsTmuxSessionSocket(session, io) {
|
|
|
2012
2031
|
// A tmux that could not be run at all is the one failure a person can act on: say so.
|
|
2013
2032
|
if (e?.code === "ENOENT") throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `could not read the OATS tmux server for session ${session}: tmux was not found through this process's PATH. Run this command with a PATH that holds tmux`);
|
|
2014
2033
|
if (!exitedByItself(e)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `could not read the OATS tmux server for session ${session}: tmux list-sessions did not exit by itself (${typeof e?.code === "string" ? e.code : e?.signal || "no exit status"})`);
|
|
2015
|
-
|
|
2034
|
+
const absence = tmuxServerAbsence(e);
|
|
2035
|
+
const why = absence === "missing-socket" && missingSocket ? missingSocket(tmuxFailure(e, "tmux list-sessions failed")) : null;
|
|
2036
|
+
if (why) throw oatsError("E_SESSION_UNKNOWN", `cannot establish whether the OATS tmux server for session ${session} is running, so nothing was started: ${why}`);
|
|
2037
|
+
if (absence) return { server: null, present: false };
|
|
2016
2038
|
throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `could not read the OATS tmux server for session ${session}: ${tmuxFailure(e, "tmux list-sessions failed")}`);
|
|
2017
2039
|
}
|
|
2018
2040
|
let server = null, present = false;
|
|
@@ -2280,10 +2302,10 @@ function oatsWindowEnvironment() {
|
|
|
2280
2302
|
* again there when that server has gone. undefined when this process has no tmux to run: the
|
|
2281
2303
|
* caller's backend check refuses that.
|
|
2282
2304
|
*/
|
|
2283
|
-
function planOatsTmuxSession(session, io, { preview = false } = {}) {
|
|
2305
|
+
function planOatsTmuxSession(session, io, { preview = false, missingSocket } = {}) {
|
|
2284
2306
|
if (!io?.exec && !which("tmux")) return undefined;
|
|
2285
2307
|
let server, present;
|
|
2286
|
-
try { ({ server, present } = oatsTmuxSessionSocket(session, io)); }
|
|
2308
|
+
try { ({ server, present } = oatsTmuxSessionSocket(session, io, missingSocket)); }
|
|
2287
2309
|
catch (e) { if (preview) return undefined; throw e; } // a preview reports, it does not refuse on a read
|
|
2288
2310
|
if (present || preview) return { server, present };
|
|
2289
2311
|
return { server, present, env: oatsSessionEnvironment(session, io, { startsServer: !server }), startsServer: !server };
|
|
@@ -2359,10 +2381,12 @@ function launchLookup(configEnv, env, pane, configName, cwd) {
|
|
|
2359
2381
|
* second lookup. tmux starts a server once: the first successful creator determines its initial
|
|
2360
2382
|
* environment, and nothing here changes a running server's. E_RUNTIME_ENDPOINT_UNKNOWN when the
|
|
2361
2383
|
* server cannot be read or names no socket, when this caller may not create the session, or when
|
|
2362
|
-
* its own PATH names no tmux to create it with (creatorTmux).
|
|
2384
|
+
* its own PATH names no tmux to create it with (creatorTmux). `missingSocket` is a session start's
|
|
2385
|
+
* check of its home when the server's socket file is missing (oatsTmuxSessionSocket): with a reason,
|
|
2386
|
+
* E_SESSION_UNKNOWN and no server is created at that path.
|
|
2363
2387
|
*/
|
|
2364
|
-
export function ensureOatsTmuxSession(session, hq, io, plan) {
|
|
2365
|
-
let { server: socket, present } = oatsTmuxSessionSocket(session, io);
|
|
2388
|
+
export function ensureOatsTmuxSession(session, hq, io, plan, missingSocket) {
|
|
2389
|
+
let { server: socket, present } = oatsTmuxSessionSocket(session, io, missingSocket);
|
|
2366
2390
|
if (!present) {
|
|
2367
2391
|
// The executable is chosen here, where the creation is about to run, and nowhere earlier: a
|
|
2368
2392
|
// session that exists needs none, so nothing is refused for it.
|
|
@@ -2375,7 +2399,7 @@ export function ensureOatsTmuxSession(session, hq, io, plan) {
|
|
|
2375
2399
|
try { created = (io?.exec || execFileSync)(tmux, ["-u", ...address, "new-session", "-d", "-s", session, "-n", "hq", "-c", hq, "-P", "-F", "#{socket_path}\t#{window_id}"], { encoding: "utf8", timeout: 10000, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "pipe"], env }).trim(); }
|
|
2376
2400
|
catch (e) {
|
|
2377
2401
|
if (oatsCoded(e)) throw e;
|
|
2378
|
-
const again = oatsTmuxSessionSocket(session, io);
|
|
2402
|
+
const again = oatsTmuxSessionSocket(session, io, missingSocket);
|
|
2379
2403
|
if (!again.present) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `could not create tmux session ${session} on the OATS tmux server: ${tmuxFailure(e, "tmux new-session failed")}`);
|
|
2380
2404
|
socket = again.server;
|
|
2381
2405
|
}
|
|
@@ -4377,7 +4401,9 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
|
|
|
4377
4401
|
relativeTo: relation ? relativeTo : undefined,
|
|
4378
4402
|
spawnOrigin: relation || (parentInstance && parentInstance !== instance) ? "instance" : "operator",
|
|
4379
4403
|
policy: { childSpawns: ownChildPolicy },
|
|
4380
|
-
...(triggerEventFile ? { trigger: { id: o.triggerEvent.trigger, key: o.triggerEvent.key ?? null, source: o.triggerEvent.source, repo: o.triggerEvent.repo, number: o.triggerEvent.number, subject: o.triggerEvent.subject ?? null, url: o.triggerEvent.url ?? null, event: o.triggerEvent.event, headSha: o.triggerEvent.headSha ?? null, observedAt: o.triggerEvent.observedAt ?? null, eventFile: triggerEventFile
|
|
4404
|
+
...(triggerEventFile ? { trigger: { id: o.triggerEvent.trigger, key: o.triggerEvent.key ?? null, source: o.triggerEvent.source, repo: o.triggerEvent.repo ?? null, number: o.triggerEvent.number ?? null, subject: o.triggerEvent.subject ?? null, url: o.triggerEvent.url ?? null, event: o.triggerEvent.event, headSha: o.triggerEvent.headSha ?? null, observedAt: o.triggerEvent.observedAt ?? null, eventFile: triggerEventFile,
|
|
4405
|
+
// A capability source's event carries its declared fields (a pull request's never does).
|
|
4406
|
+
...(o.triggerEvent.fields && typeof o.triggerEvent.fields === "object" ? { fields: o.triggerEvent.fields } : {}) } } : {}),
|
|
4381
4407
|
// K6c: a decision-bound spawn records what bound it, so a retry with the
|
|
4382
4408
|
// same key replays this receipt instead of spawning again.
|
|
4383
4409
|
// The FULL bound decision (placement + effective), exactly as the fence
|
|
@@ -4614,26 +4640,42 @@ export function servedIdentityLine(identity) {
|
|
|
4614
4640
|
return `alias ${identity.alias || "?"} on ${identity.team || "?"}`;
|
|
4615
4641
|
}
|
|
4616
4642
|
/** The window names of `session` on the tmux server at `socket`: `{ windows }`, empty when the server
|
|
4617
|
-
* or the session is gone
|
|
4643
|
+
* or the session is gone, with `missingSocket` (tmux's words) when the socket file is missing, which
|
|
4644
|
+
* alone does not say the server is gone (#624); `{ error }` when the server could not be read. */
|
|
4618
4645
|
function recordedTmuxWindows(socket, session) {
|
|
4619
4646
|
try { return { windows: tmuxOn(socket, ["list-windows", "-t", `=${session}`, "-F", "#{window_name}"]).split("\n").filter(Boolean) }; }
|
|
4620
4647
|
catch (e) {
|
|
4621
|
-
|
|
4648
|
+
const absence = tmuxServerAbsence(e);
|
|
4649
|
+
if (absence === "missing-socket") return { windows: [], missingSocket: tmuxFailure(e, "tmux list-windows failed") };
|
|
4650
|
+
if (absence || /can't find session/i.test(String(e.stderr ?? ""))) return { windows: [] };
|
|
4622
4651
|
return { error: String(e.stderr ?? e.message ?? "").trim() || "tmux list-windows failed" };
|
|
4623
4652
|
}
|
|
4624
4653
|
}
|
|
4625
|
-
/** A status row's liveness from its session's windows: unknown (not false) when the server could not
|
|
4626
|
-
|
|
4627
|
-
|
|
4654
|
+
/** A status row's liveness from its session's windows: unknown (not false) when the server could not
|
|
4655
|
+
* be read, and, for a row whose server holds its endpoint (`endpoint`), when its socket file is
|
|
4656
|
+
* missing while a process works in the home or the scan (`scanHome()`, processesInHome's answer for
|
|
4657
|
+
* it) cannot tell (#624). */
|
|
4658
|
+
function tmuxLiveness({ windows, error, missingSocket }, window, scanHome, endpoint) {
|
|
4659
|
+
if (error) return { running: null, runtimeState: "unreachable", runtimeError: error };
|
|
4660
|
+
const running = windows.includes(window);
|
|
4661
|
+
const why = !running && missingSocket && endpoint ? missingSocketUnestablished(missingSocket, scanHome()) : null;
|
|
4662
|
+
return why ? { running: null, runtimeState: "unreachable", runtimeError: why } : { running };
|
|
4628
4663
|
}
|
|
4629
|
-
export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
|
|
4664
|
+
export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io) {
|
|
4630
4665
|
// Liveness reads each home's RECORDED endpoint (a pre-0.31 home records pi-agents): the recorded
|
|
4631
4666
|
// socket, never the ambient $TMUX server, once per socket and session per call, so status costs no
|
|
4632
4667
|
// more child processes as homes grow. A home without a recorded socket reads the default server.
|
|
4668
|
+
// A row whose socket file is missing is checked against one process scan of the host, made the
|
|
4669
|
+
// first time a row needs it and shared by every row (`io` reaches it: processesInHome).
|
|
4670
|
+
let hostScan;
|
|
4671
|
+
const scanOf = (home) => () => {
|
|
4672
|
+
hostScan ??= hostProcesses(io);
|
|
4673
|
+
return hostScan.ok ? { ok: true, processes: processesWorkingIn(hostScan.processes, home) } : hostScan;
|
|
4674
|
+
};
|
|
4633
4675
|
const tmuxByEndpoint = new Map();
|
|
4634
4676
|
const windowsOf = (session, socket) => {
|
|
4635
4677
|
const key = JSON.stringify([socket ?? null, session]);
|
|
4636
|
-
if (!tmuxByEndpoint.has(key)) tmuxByEndpoint.set(key, socket ? recordedTmuxWindows(socket, session) :
|
|
4678
|
+
if (!tmuxByEndpoint.has(key)) tmuxByEndpoint.set(key, socket ? recordedTmuxWindows(socket, session) : defaultTmuxWindows(session));
|
|
4637
4679
|
return tmuxByEndpoint.get(key);
|
|
4638
4680
|
};
|
|
4639
4681
|
const readInstancesOf = (agentDir) => {
|
|
@@ -4677,7 +4719,10 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
|
|
|
4677
4719
|
// A home opened in Herdr (removed in 0.31.0) is listed, never observed: its row says so.
|
|
4678
4720
|
const liveness = recordsHerdr(meta, readJsonOrUndefined(findRetirementBaseline(home)))
|
|
4679
4721
|
? { running: null, runtimeState: "unsupported", runtimeError: `E_HERDR_REMOVED: ${herdrInstanceRemoved(e.name).message}` }
|
|
4680
|
-
: tmuxLiveness(windowsOf(meta.tmux?.session || tmuxSession, meta.tmux?.socket), meta.tmux?.window || meta.instance || e.name)
|
|
4722
|
+
: tmuxLiveness(windowsOf(meta.tmux?.session || tmuxSession, meta.tmux?.socket), meta.tmux?.window || meta.instance || e.name, scanOf(home),
|
|
4723
|
+
// A home that records no socket and no launch (--no-launch) reads the default server only
|
|
4724
|
+
// by default: that server's missing socket says nothing about it, and stays "not running".
|
|
4725
|
+
!!meta.tmux?.socket || meta.launched === true);
|
|
4681
4726
|
const identity = servedIdentityOf(meta);
|
|
4682
4727
|
// Feature desktop-facts: `startedAt` — the last session start or restart (the receipt's restarts[]),
|
|
4683
4728
|
// else the spawn's own launch (createdAt), else null (never launched); `identityAddress` — the
|
|
@@ -5084,7 +5129,15 @@ function retirementStateRoot(home) {
|
|
|
5084
5129
|
// Independent of the bytes it authenticates, but colocated with the agent's
|
|
5085
5130
|
// already instance-owned storage rather than the source repository or user
|
|
5086
5131
|
// config home. Retiring <instances>/<name> never removes this sibling.
|
|
5087
|
-
return
|
|
5132
|
+
return instancesRetirementRoot(dirname(home));
|
|
5133
|
+
}
|
|
5134
|
+
/** The retirement state of the homes in the instances directory `instances`. */
|
|
5135
|
+
function instancesRetirementRoot(instances) {
|
|
5136
|
+
return join(instances, ".oats-retirement");
|
|
5137
|
+
}
|
|
5138
|
+
/** Where retire writes the recovery copies of the homes in the instances directory `instances`. */
|
|
5139
|
+
export function retirementRecoveryRoot(instances) {
|
|
5140
|
+
return join(instancesRetirementRoot(instances), "recovery");
|
|
5088
5141
|
}
|
|
5089
5142
|
|
|
5090
5143
|
/** A home's identity as a receipt records it: its on-disk spelling, own name included. A home that
|
|
@@ -5648,16 +5701,38 @@ function extraWorktreesOf(home) {
|
|
|
5648
5701
|
}
|
|
5649
5702
|
return trees;
|
|
5650
5703
|
}
|
|
5704
|
+
/** Where retire re-homes the worktrees it retains, one directory per repository under it. */
|
|
5705
|
+
export function retainedWorktreesRoot(workspace) {
|
|
5706
|
+
return join(workspace, ".agents", "worktrees");
|
|
5707
|
+
}
|
|
5708
|
+
/** The longest retained-worktree leaf before its `-N` suffix, in bytes (awebai/oats#821). The
|
|
5709
|
+
* leaf is one path component, so it must fit NAME_MAX (255 on the usual filesystems). 16 bytes
|
|
5710
|
+
* are kept as a margin, as the test fixtures keep: nothing appends to the leaf's name today
|
|
5711
|
+
* (`git worktree move` renames to the path it is given, which does not exist, and adds nothing),
|
|
5712
|
+
* so the margin is headroom only. 8 more are kept for the `-N` suffix (`-` and up to seven
|
|
5713
|
+
* digits). A leaf is then at most 231 bytes, and at most 239 with its suffix. */
|
|
5714
|
+
export const RETAINED_LEAF_MAX = 255 - 16 - 8;
|
|
5651
5715
|
/** Where a retired worktree is re-homed: `<workspace>/.agents/worktrees/<repoName>/<leaf>`,
|
|
5652
|
-
* the leaf being the branch, else `detached-<commit
|
|
5653
|
-
* `taken` holds it), `<leaf>-2`, `-3`, …
|
|
5654
|
-
*
|
|
5716
|
+
* the leaf being the branch, else `detached-<commit>`, with every run of characters outside
|
|
5717
|
+
* `[A-Za-z0-9._-]` made `-`; when that exists (or `taken` holds it), `<leaf>-2`, `-3`, … A leaf
|
|
5718
|
+
* over RETAINED_LEAF_MAX is cut to fit, its trailing `-` trimmed, and followed by `-` and 6 hex
|
|
5719
|
+
* of the SHA-256 of the full branch name: deterministic, readable, and one per branch. The
|
|
5720
|
+
* character class keeps the leaf ASCII, so its length in characters is its length in bytes;
|
|
5721
|
+
* widen the class and the bound must measure bytes. The one naming rule of work/ and of the
|
|
5722
|
+
* extra trees, the plan's `movedTo` and the apply's alike. Creates nothing. */
|
|
5655
5723
|
function retainedWorktreeDest(workspace, repo, branch, commit, taken = new Set()) {
|
|
5656
5724
|
const repoName = basename(realPathOrNearest(repo)).replace(/\.git$/, "") || "repo";
|
|
5657
|
-
const
|
|
5658
|
-
const
|
|
5659
|
-
|
|
5660
|
-
|
|
5725
|
+
const name = branch ?? `detached-${(commit || "unknown").slice(0, 12)}`;
|
|
5726
|
+
const flat = name.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "work";
|
|
5727
|
+
const hash = () => createHash("sha256").update(name, "utf8").digest("hex").slice(0, 6);
|
|
5728
|
+
/** The leaf in `room` bytes: as it is when it fits, else cut and hashed. */
|
|
5729
|
+
const fit = (room) => flat.length <= room ? flat : `${flat.slice(0, room - 7).replace(/-+$/, "")}-${hash()}`;
|
|
5730
|
+
const retainedRoot = join(retainedWorktreesRoot(workspace), repoName);
|
|
5731
|
+
let dest = join(retainedRoot, fit(RETAINED_LEAF_MAX));
|
|
5732
|
+
// The 8 bytes kept for `-N` hold `-2` to `-9999999`; a longer suffix takes its extra bytes from
|
|
5733
|
+
// the leaf's readable part, never its hash, so a leaf with its suffix never passes
|
|
5734
|
+
// RETAINED_LEAF_MAX + 8.
|
|
5735
|
+
for (let n = 2; existsSync(dest) || taken.has(dest); n++) dest = join(retainedRoot, `${fit(Math.min(RETAINED_LEAF_MAX, RETAINED_LEAF_MAX + 7 - String(n).length))}-${n}`);
|
|
5661
5736
|
taken.add(dest);
|
|
5662
5737
|
return dest;
|
|
5663
5738
|
}
|
|
@@ -5712,7 +5787,7 @@ function retirementBaselineValid(baseline, home) {
|
|
|
5712
5787
|
* as not copied (none without a valid baseline). */
|
|
5713
5788
|
export function retirementRecoveryFacts(home) {
|
|
5714
5789
|
const baseline = readJsonOrUndefined(findRetirementBaseline(home));
|
|
5715
|
-
return { recoveryRoot:
|
|
5790
|
+
return { recoveryRoot: retirementRecoveryRoot(dirname(home)), disposableHome: retirementBaselineValid(baseline, home) ? baselineDisposableHome(baseline) : [] };
|
|
5716
5791
|
}
|
|
5717
5792
|
function writeRetirementBaseline(home, work, mode, capabilities, runtime, { exclusive = false, incarnationId, executionBinding } = {}) {
|
|
5718
5793
|
if (mode === "directory") assertDirectoryRoots(home);
|
|
@@ -5852,21 +5927,104 @@ export function inspectInstanceSession(home) {
|
|
|
5852
5927
|
* fallback shell nor a dead pane. Only such a session can be waiting on a human. */
|
|
5853
5928
|
function harnessRunning(observed) { return observed?.present === true && observed.state !== "shell" && observed.state !== "stopped"; }
|
|
5854
5929
|
|
|
5855
|
-
/**
|
|
5856
|
-
*
|
|
5857
|
-
*
|
|
5858
|
-
*
|
|
5859
|
-
*
|
|
5860
|
-
*
|
|
5861
|
-
function
|
|
5930
|
+
/** How a failed tmux call reads the server it addressed (#624). "gone": no server listens on the
|
|
5931
|
+
* socket (`no server running on`, or a refused connection), which is definitive. "missing-socket":
|
|
5932
|
+
* the socket file is not there (`No such file or directory`). After a reboot the server is gone,
|
|
5933
|
+
* but a tmux server outlives its removed socket file, so that alone establishes nothing: a caller
|
|
5934
|
+
* concludes stopped from it only when no process works in the home (missingSocketUnestablished).
|
|
5935
|
+
* null: anything else. */
|
|
5936
|
+
function tmuxServerAbsence(e) {
|
|
5937
|
+
const text = String(e?.stderr ?? e?.message ?? "");
|
|
5938
|
+
if (/no server running on |(?:error connecting to|failed to connect to) .*Connection refused/i.test(text)) return "gone";
|
|
5939
|
+
if (/(?:error connecting to|failed to connect to) .*No such file or directory/i.test(text)) return "missing-socket";
|
|
5940
|
+
return null;
|
|
5941
|
+
}
|
|
5942
|
+
function tmuxServerLost(e) { return tmuxServerAbsence(e) !== null; }
|
|
5943
|
+
/** tmux's own way back for a server that lost its socket file (tmux(1), `-S`). Named, never performed. */
|
|
5944
|
+
const TMUX_SOCKET_REMEDY = "tmux recreates a removed socket file when its server process receives SIGUSR1";
|
|
5945
|
+
/** Processes as a refusal names them: pid and program, at most five, then how many more. */
|
|
5946
|
+
function namedProcesses(processes) {
|
|
5947
|
+
return `${processes.slice(0, 5).map((p) => `pid ${p.pid} ${p.command}`).join(", ")}${processes.length > 5 ? `, and ${processes.length - 5} more` : ""}`;
|
|
5948
|
+
}
|
|
5949
|
+
/** A missing socket file (`detail`, tmux's words) checked against `scan`, processesInHome's answer
|
|
5950
|
+
* for the home (#624): null when it ran and found no process there, so the server is taken as gone,
|
|
5951
|
+
* as after a reboot; otherwise why the state is not established. Any process working in the home
|
|
5952
|
+
* counts, a person's shell included: the words name it, so the person can act on it. */
|
|
5953
|
+
function missingSocketUnestablished(detail, scan) {
|
|
5954
|
+
if (!scan.ok) return `${detail}; whether a process still works in this home could not be established (${scan.error})`;
|
|
5955
|
+
if (scan.processes.length) return `${detail}; a process still works in this home (${namedProcesses(scan.processes)}), so its tmux server may still be running without its socket file: ${TMUX_SOCKET_REMEDY}`;
|
|
5956
|
+
return null;
|
|
5957
|
+
}
|
|
5958
|
+
/** Whether this host's /proc can be read: Linux, and this process's own `cwd` link resolves. */
|
|
5959
|
+
function procReadable() {
|
|
5960
|
+
if (process.platform !== "linux") return { ok: false, error: "this host has no /proc to read (it is not Linux)" };
|
|
5961
|
+
try { readlinkSync("/proc/self/cwd"); return { ok: true }; }
|
|
5962
|
+
catch (e) { return { ok: false, error: `/proc/self/cwd cannot be read (${e.code || e.message})` }; }
|
|
5963
|
+
}
|
|
5964
|
+
/** Which process scan this host offers, checked cheaply and without scanning (doctor reports it):
|
|
5965
|
+
* /proc on Linux, else lsof when it is on PATH. → { mechanism: "proc" | "lsof" } | { mechanism: null, error } */
|
|
5966
|
+
export function processScanAvailability() {
|
|
5967
|
+
const proc = procReadable();
|
|
5968
|
+
if (proc.ok) return { mechanism: "proc" };
|
|
5969
|
+
if (process.env.PATH !== undefined && lookupOnPath("lsof", process.env.PATH)) return { mechanism: "lsof" };
|
|
5970
|
+
return { mechanism: null, error: `${proc.error}, and lsof is not on PATH` };
|
|
5971
|
+
}
|
|
5972
|
+
/** Doctor's information line when this host has no process scan (`availability`, from
|
|
5973
|
+
* processScanAvailability); none when it has one. */
|
|
5974
|
+
export function processScanInformation(availability = processScanAvailability()) {
|
|
5975
|
+
if (availability.mechanism) return [];
|
|
5976
|
+
return [`process-scan-unavailable: ${availability.error}; retire refuses where it must rule out a live process in an instance home (a home without its session receipt, a missing recorded tmux socket, a Herdr home), and session start/stop refuse when a recorded tmux socket is missing; install lsof`];
|
|
5977
|
+
}
|
|
5862
5978
|
/**
|
|
5863
|
-
*
|
|
5864
|
-
* directory
|
|
5865
|
-
*
|
|
5866
|
-
*
|
|
5867
|
-
*
|
|
5979
|
+
* Every live process on the host (other than this one and its direct children) with its working
|
|
5980
|
+
* directory, from one scan: /proc on Linux (`io.procRoot` names another root), else one `lsof -a -d
|
|
5981
|
+
* cwd` listing; an injected `io.exec` stands in for the host's commands, so it is lsof's. Each cwd
|
|
5982
|
+
* is kept in its on-disk spelling (canonicalHomePath); one the kernel reports deleted (`<path>
|
|
5983
|
+
* (deleted)`) is kept as both spellings. A process this user may not inspect (another user's, or a
|
|
5984
|
+
* non-dumpable one) is not seen by either mechanism.
|
|
5985
|
+
* → { ok: true, processes: [{pid, command, cwds}] } | { ok: false, error }
|
|
5868
5986
|
*/
|
|
5869
|
-
|
|
5987
|
+
function hostProcesses(io) {
|
|
5988
|
+
const rows = typeof io?.procRoot === "string" ? procRows(io.procRoot)
|
|
5989
|
+
: !io?.exec && procReadable().ok ? procRows("/proc")
|
|
5990
|
+
: lsofRows(io);
|
|
5991
|
+
if (!rows.ok) return rows;
|
|
5992
|
+
const processes = [];
|
|
5993
|
+
for (const { pid, ppid, command, cwd } of rows.rows) {
|
|
5994
|
+
if (!pid || pid === process.pid || ppid === process.pid || typeof cwd !== "string") continue;
|
|
5995
|
+
const spellings = cwd.endsWith(" (deleted)") ? [cwd, cwd.slice(0, -" (deleted)".length)] : [cwd];
|
|
5996
|
+
processes.push({ pid, command: command ?? "?", cwds: spellings.map((p) => canonicalHomePath(p)) });
|
|
5997
|
+
}
|
|
5998
|
+
return { ok: true, processes };
|
|
5999
|
+
}
|
|
6000
|
+
/** The processes of a hostProcesses listing that work in `home`, compared in its on-disk spelling. */
|
|
6001
|
+
function processesWorkingIn(processes, home) {
|
|
6002
|
+
const realHome = canonicalHomePath(home);
|
|
6003
|
+
return processes.filter((p) => p.cwds.some((cwd) => cwd === realHome || cwd.startsWith(`${realHome}/`))).map(({ pid, command }) => ({ pid, command }));
|
|
6004
|
+
}
|
|
6005
|
+
/** /proc read as a scan: each numeric entry's `cwd` link, `comm` and `stat` (its ppid is the second
|
|
6006
|
+
* field after the last `)`, which ends the command). A pid that cannot be read (it ended meanwhile,
|
|
6007
|
+
* this user may not inspect it, or any other failure on that one pid) is not seen. A root that
|
|
6008
|
+
* cannot be listed, or one that lists no readable process, is a failed scan, never an empty one. */
|
|
6009
|
+
function procRows(root) {
|
|
6010
|
+
let names;
|
|
6011
|
+
try { names = readdirSync(root); }
|
|
6012
|
+
catch (e) { return { ok: false, error: `${root} cannot be read (${e.code || e.message})` }; }
|
|
6013
|
+
const rows = [];
|
|
6014
|
+
for (const name of names) {
|
|
6015
|
+
if (!/^\d+$/.test(name)) continue;
|
|
6016
|
+
try {
|
|
6017
|
+
const cwd = readlinkSync(join(root, name, "cwd"));
|
|
6018
|
+
const command = readFileSync(join(root, name, "comm"), "utf8").replace(/\n$/, "");
|
|
6019
|
+
const stat = readFileSync(join(root, name, "stat"), "utf8");
|
|
6020
|
+
rows.push({ pid: Number(name), ppid: Number(stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/)[1]), command, cwd });
|
|
6021
|
+
} catch { /* not seen */ }
|
|
6022
|
+
}
|
|
6023
|
+
// A real /proc always lists at least this process.
|
|
6024
|
+
if (!rows.length) return { ok: false, error: `${root} listed no process` };
|
|
6025
|
+
return { ok: true, rows };
|
|
6026
|
+
}
|
|
6027
|
+
function lsofRows(io) {
|
|
5870
6028
|
let out;
|
|
5871
6029
|
try { out = (io?.exec || execFileSync)("lsof", ["-a", "-d", "cwd", "-F", "pRcn", "-w"], { encoding: "utf8", timeout: 20000, maxBuffer: 16 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }); }
|
|
5872
6030
|
catch (e) {
|
|
@@ -5877,7 +6035,7 @@ export function processesInHome(home, io) {
|
|
|
5877
6035
|
// listing.
|
|
5878
6036
|
const completed = e?.status === 1 && e.signal == null && e.code === undefined;
|
|
5879
6037
|
if (completed && typeof e.stdout === "string") out = e.stdout;
|
|
5880
|
-
else return { ok: false, error: e?.code === "ENOENT" ? "lsof is not on PATH"
|
|
6038
|
+
else return { ok: false, error: e?.code === "ENOENT" ? "lsof is not on PATH; install lsof"
|
|
5881
6039
|
: e?.code === "ETIMEDOUT" ? "lsof timed out"
|
|
5882
6040
|
: e?.code === "ENOBUFS" ? "lsof printed more output than the scan reads"
|
|
5883
6041
|
: e?.signal ? `lsof was ended by ${e.signal}`
|
|
@@ -5885,21 +6043,27 @@ export function processesInHome(home, io) {
|
|
|
5885
6043
|
}
|
|
5886
6044
|
// A listing holds at least one process (lsof and its caller are always in it), whichever exit it came with.
|
|
5887
6045
|
if (!/^p\d+$/m.test(String(out))) return { ok: false, error: "lsof listed no process" };
|
|
5888
|
-
|
|
5889
|
-
const realHome = canonicalHomePath(home);
|
|
5890
|
-
const processes = [];
|
|
6046
|
+
const rows = [];
|
|
5891
6047
|
let cur = {};
|
|
5892
6048
|
for (const line of String(out).split("\n")) {
|
|
5893
6049
|
const tag = line[0], value = line.slice(1);
|
|
5894
|
-
if (tag === "p") cur = { pid: Number(value) };
|
|
6050
|
+
if (tag === "p") { cur = { pid: Number(value) }; rows.push(cur); }
|
|
5895
6051
|
else if (tag === "R") cur.ppid = Number(value);
|
|
5896
6052
|
else if (tag === "c") cur.command = value;
|
|
5897
|
-
else if (tag === "n"
|
|
5898
|
-
const cwd = canonicalHomePath(value);
|
|
5899
|
-
if (cwd === realHome || cwd.startsWith(`${realHome}/`)) processes.push({ pid: cur.pid, command: cur.command ?? "?" });
|
|
5900
|
-
}
|
|
6053
|
+
else if (tag === "n") cur.cwd = value;
|
|
5901
6054
|
}
|
|
5902
|
-
return { ok: true,
|
|
6055
|
+
return { ok: true, rows };
|
|
6056
|
+
}
|
|
6057
|
+
/**
|
|
6058
|
+
* The live processes (other than this one and its direct children) whose working directory is
|
|
6059
|
+
* inside `home`, from one scan of the host (hostProcesses: /proc on Linux, else lsof). A pid and a
|
|
6060
|
+
* program name, never an argument list.
|
|
6061
|
+
* → { ok: true, processes: [{pid, command}] } | { ok: false, error } (the scan could not run, did
|
|
6062
|
+
* not complete or listed no process: a caller must treat that as unknown, never as none).
|
|
6063
|
+
*/
|
|
6064
|
+
export function processesInHome(home, io) {
|
|
6065
|
+
const scan = hostProcesses(io);
|
|
6066
|
+
return scan.ok ? { ok: true, processes: processesWorkingIn(scan.processes, home) } : scan;
|
|
5903
6067
|
}
|
|
5904
6068
|
|
|
5905
6069
|
/**
|
|
@@ -5920,7 +6084,7 @@ export function observeSessionWithoutReceipt(home, meta, io) {
|
|
|
5920
6084
|
if (!recorded.absent) return recorded;
|
|
5921
6085
|
const scan = processesInHome(home, io);
|
|
5922
6086
|
if (!scan.ok) return { absent: false, backend: recorded.backend, note: `could not scan for a process working in this home (${scan.error})` };
|
|
5923
|
-
if (scan.processes.length) return { absent: false, backend: recorded.backend, note: `a process works in this home (${scan.processes
|
|
6087
|
+
if (scan.processes.length) return { absent: false, backend: recorded.backend, note: `a process works in this home (${namedProcesses(scan.processes)}); stop it, then retire` };
|
|
5924
6088
|
return recorded;
|
|
5925
6089
|
}
|
|
5926
6090
|
function recordedSessionAbsence(home, meta, io) {
|
|
@@ -5943,6 +6107,13 @@ function recordedSessionAbsence(home, meta, io) {
|
|
|
5943
6107
|
if (inHome) return { absent: false, backend: "tmux", note: `a tmux pane (${inHome[0]}:${inHome[1]}) on ${tmux.socket} works in this home` };
|
|
5944
6108
|
return { absent: true, backend: "tmux", note: `no session receipt (a home from before 0.25.9); the recorded window ${where} is gone` };
|
|
5945
6109
|
}
|
|
6110
|
+
/** K3: quiesce one instance's session and RETAIN everything else — home,
|
|
6111
|
+
* worktree, transcript, launch configuration — so `restart` can bring it back.
|
|
6112
|
+
* Exactly restart's stop half under the same independent endpoint authority
|
|
6113
|
+
* (`instanceSessionTarget`), bounded and never escalated: a harness still
|
|
6114
|
+
* there after the grace is reported still running, nothing is killed harder.
|
|
6115
|
+
* A no-launch or already-idle instance is a no-op that says so. A missing socket
|
|
6116
|
+
* file is idle only when no process works in the home (#624). */
|
|
5946
6117
|
export function stopInstanceSession(home, o = {}) {
|
|
5947
6118
|
if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session stop needs an absolute instance home");
|
|
5948
6119
|
if (o.graceMs !== undefined && (!Number.isSafeInteger(o.graceMs) || o.graceMs < 1 || o.graceMs > 300000)) throw oatsError("E_BAD_ARGS", "stop grace must be 1-300000 ms");
|
|
@@ -5952,7 +6123,12 @@ export function stopInstanceSession(home, o = {}) {
|
|
|
5952
6123
|
if (!s.target) return { home: s.home, backend: null, stopped: false, alreadyIdle: true, state: "not-launched", receipt: null };
|
|
5953
6124
|
let before;
|
|
5954
6125
|
try { before = inspectSessionTarget(s.target); }
|
|
5955
|
-
catch (e) {
|
|
6126
|
+
catch (e) {
|
|
6127
|
+
const absence = tmuxServerAbsence(e);
|
|
6128
|
+
const why = absence === "missing-socket" ? missingSocketUnestablished(tmuxFailure(e, e.message), processesInHome(realHome, o.io)) : null;
|
|
6129
|
+
if (absence && !why) before = { present: false, state: "stopped" };
|
|
6130
|
+
else throw oatsError("E_SESSION_UNAVAILABLE", `cannot establish whether ${basename(realHome)} is running, so nothing was stopped: ${why ?? e.message}`);
|
|
6131
|
+
}
|
|
5956
6132
|
if (!before.present || before.state === "shell" || before.state === "stopped") return { home: s.home, backend: s.target.backend, stopped: false, alreadyIdle: true, state: before.state, receipt: null };
|
|
5957
6133
|
const receipt = stopHarness(s.target, { graceMs: o.graceMs ?? 20000, kill: o.io?.kill, sleep: o.io?.sleep });
|
|
5958
6134
|
writeJsonAtomic(join(realHome, ".oats-stop.json"), { instance: basename(realHome), at: new Date().toISOString(), stop: receipt, retained: ["home", "work", "transcript", "launch"] });
|
|
@@ -5972,10 +6148,11 @@ function stopRecordedChildren(children) {
|
|
|
5972
6148
|
});
|
|
5973
6149
|
}
|
|
5974
6150
|
|
|
5975
|
-
export async function attachInstanceSession(home) {
|
|
6151
|
+
export async function attachInstanceSession(home, { detachKey } = {}) {
|
|
6152
|
+
if (detachKey !== undefined) requireDetachKey(detachKey);
|
|
5976
6153
|
const s = instanceSessionTarget(home);
|
|
5977
6154
|
if (!s.target) throw oatsError("E_SESSION_NOT_RUNNING", "instance was not launched");
|
|
5978
|
-
return attachSessionTarget(s.target);
|
|
6155
|
+
return attachSessionTarget(s.target, { detachKey });
|
|
5979
6156
|
}
|
|
5980
6157
|
|
|
5981
6158
|
export function inputInstanceSession(home, text) {
|
|
@@ -6359,7 +6536,16 @@ export function startInstanceSession(home, o = {}) {
|
|
|
6359
6536
|
// spawned records no modules, and there is no scope configuration left to
|
|
6360
6537
|
// re-resolve it against. Retire still works on it.
|
|
6361
6538
|
if (!isWorkspaceHome(readMeta())) throw preWorkspaceHome(realHome, "nothing was started");
|
|
6362
|
-
|
|
6539
|
+
// A missing socket file is a stopped server only when no process works in this home (#624): its
|
|
6540
|
+
// check, for a recorded session and for the OATS server lookup. A failed read of a recorded session
|
|
6541
|
+
// is `{ stopped: true }` when its server is gone (or its socket file is missing and that check
|
|
6542
|
+
// passes), else `{ stopped: false, why }`: the check's reason, or null for another failure.
|
|
6543
|
+
const missingSocket = (detail) => missingSocketUnestablished(detail, processesInHome(realHome, rawIo));
|
|
6544
|
+
const lostServer = (e) => {
|
|
6545
|
+
const absence = tmuxServerAbsence(e);
|
|
6546
|
+
const why = absence === "missing-socket" ? missingSocket(tmuxFailure(e, e.message)) : null;
|
|
6547
|
+
return absence && !why ? { stopped: true } : { stopped: false, why };
|
|
6548
|
+
};
|
|
6363
6549
|
const launchFailure = (error) => {
|
|
6364
6550
|
// execFileSync errors embed argv (including capability environment) in
|
|
6365
6551
|
// message; backend stderr can echo it too. Neither belongs in the API.
|
|
@@ -6435,8 +6621,9 @@ export function startInstanceSession(home, o = {}) {
|
|
|
6435
6621
|
checkRoots();
|
|
6436
6622
|
try { st = inspectSessionTarget(pending.target, o.io); }
|
|
6437
6623
|
catch (e) {
|
|
6438
|
-
|
|
6439
|
-
|
|
6624
|
+
const lost = lostServer(e);
|
|
6625
|
+
if (lost.stopped) st = { present: false, state: "stopped" };
|
|
6626
|
+
else throw oatsError("E_SESSION_UNKNOWN", `an earlier start of ${basename(realHome)} recorded a session (tmux ${pending.target.session}:${pending.target.window} on ${pending.target.socket}) that cannot be observed now: ${lost.why ?? (String(e.stderr ?? e.message ?? "").trim() || e.message)}; the receipt ${pendingPath} is kept and nothing was started`);
|
|
6440
6627
|
}
|
|
6441
6628
|
// A launch may still consist entirely of shells (startup files, a
|
|
6442
6629
|
// shell-script harness). Only its own completion marker proves this
|
|
@@ -6512,18 +6699,19 @@ export function startInstanceSession(home, o = {}) {
|
|
|
6512
6699
|
const planSession = receipt.target?.session || meta.tmux?.session || DEFAULT_TMUX_SESSION;
|
|
6513
6700
|
let sessionPlanRead;
|
|
6514
6701
|
const sessionPlan = () => {
|
|
6515
|
-
if (!sessionPlanRead) { try { sessionPlanRead = { plan: planOatsTmuxSession(planSession, o.io) }; } catch (e) { sessionPlanRead = { error: e }; } }
|
|
6702
|
+
if (!sessionPlanRead) { try { sessionPlanRead = { plan: planOatsTmuxSession(planSession, o.io, { missingSocket }) }; } catch (e) { sessionPlanRead = { error: e }; } }
|
|
6516
6703
|
if (sessionPlanRead.error) throw sessionPlanRead.error;
|
|
6517
6704
|
return sessionPlanRead.plan;
|
|
6518
6705
|
};
|
|
6519
6706
|
// The recorded target, observed once: by the plan's lookup, which must know whether the pane will
|
|
6520
|
-
// be reused before it chooses where to look, or by the gate below. A lost server is a stopped one
|
|
6521
|
-
// any other failure is the gate's refusal (E_SESSION_UNKNOWN), and the lookup does
|
|
6707
|
+
// be reused before it chooses where to look, or by the gate below. A lost server is a stopped one
|
|
6708
|
+
// (lostServer); any other failure is the gate's refusal (E_SESSION_UNKNOWN), and the lookup does
|
|
6709
|
+
// not decide it.
|
|
6522
6710
|
let recordedRead;
|
|
6523
6711
|
const recordedState = () => {
|
|
6524
6712
|
if (!recordedRead) {
|
|
6525
6713
|
try { recordedRead = { state: receipt.target ? inspectSessionTarget(receipt.target, o.io) : { present: false, state: "not-launched" } }; }
|
|
6526
|
-
catch (e) {
|
|
6714
|
+
catch (e) { const lost = lostServer(e); recordedRead = lost.stopped ? { state: { present: false, state: "stopped" } } : { error: lost.why ? new Error(lost.why) : e }; }
|
|
6527
6715
|
}
|
|
6528
6716
|
return recordedRead;
|
|
6529
6717
|
};
|
|
@@ -6553,7 +6741,7 @@ export function startInstanceSession(home, o = {}) {
|
|
|
6553
6741
|
const recorded = recordedState();
|
|
6554
6742
|
if (reusable(recorded.state)) return panePath(receipt.target.socket, receipt.target.session, o.io, realHome);
|
|
6555
6743
|
if (recorded.error) return undefined; // the gate refuses below; the lookup does not decide it
|
|
6556
|
-
const preview = planOatsTmuxSession(planSession, o.io, { preview: true });
|
|
6744
|
+
const preview = planOatsTmuxSession(planSession, o.io, { preview: true, missingSocket });
|
|
6557
6745
|
if (!preview || preview.server) return expectedPanePath(preview, planSession, o.io, realHome);
|
|
6558
6746
|
try { return expectedPanePath(sessionPlan(), planSession, o.io, realHome); } catch (e) { if (oatsCoded(e)) return undefined; throw e; }
|
|
6559
6747
|
};
|
|
@@ -6662,7 +6850,12 @@ export function startInstanceSession(home, o = {}) {
|
|
|
6662
6850
|
writeJsonAtomic(join(realHome, ".oats-restart.json"), { instance: meta.instance, at: new Date().toISOString(), stop: stopReceipt, next: { harness: launchPlan?.harness || harness, launchConfig: launchPlan?.recipe?.launchConfig ?? meta.launch?.launchConfig ?? null, model: model ?? null } }, 0o600);
|
|
6663
6851
|
appendEvent(realHome, { kind: stopReceipt.exited ? "restarted" : "stop-refused", data: { phase: "restart-stop", signal: stopReceipt.signal, waitedMs: stopReceipt.waitedMs, stillRunning: stopReceipt.stillRunning ?? [] } });
|
|
6664
6852
|
if (!stopReceipt.exited) throw oatsError("E_SESSION_STOP_FAILED", `${meta.instance} was asked to stop (${stopReceipt.signal} to ${stopReceipt.requested.map((r) => `${r.comm} pid ${r.pid}`).join(", ")} at ${stopReceipt.sentAt}) and was still running after ${stopReceipt.waitedMs} ms (${stopReceipt.state}); nothing was escalated and nothing was started; stop it yourself, or retry with a longer --stop-grace. Receipt: ${join(realHome, ".oats-restart.json")}`);
|
|
6665
|
-
try { state = inspectSessionTarget(target, o.io); }
|
|
6853
|
+
try { state = inspectSessionTarget(target, o.io); }
|
|
6854
|
+
catch (e) {
|
|
6855
|
+
const lost = lostServer(e);
|
|
6856
|
+
if (lost.stopped) state = { present: false, state: "stopped" };
|
|
6857
|
+
else throw oatsError("E_SESSION_UNKNOWN", `after the stop, cannot establish the state of ${meta.instance}, so nothing was started: ${lost.why ?? (String(e.stderr ?? e.message ?? "").trim() || e.message)}`);
|
|
6858
|
+
}
|
|
6666
6859
|
if (state.present && state.state !== "shell") throw oatsError("E_SESSION_UNKNOWN", `${meta.instance} read as stopped and then as ${state.state} again; nothing was started`);
|
|
6667
6860
|
}
|
|
6668
6861
|
// The kernel that launches the harness is the one the agent's plain `oats` runs.
|
|
@@ -6710,7 +6903,7 @@ export function startInstanceSession(home, o = {}) {
|
|
|
6710
6903
|
// A replacement window (never launched, recorded window gone, recorded server gone) is created
|
|
6711
6904
|
// on the OATS server, wherever the home was recorded: one socket from here to the record.
|
|
6712
6905
|
const recordedSocket = socket ? resolve(socket) : null;
|
|
6713
|
-
socket = ensureOatsTmuxSession(session, hq, o.io, tmuxSessionPlan);
|
|
6906
|
+
socket = ensureOatsTmuxSession(session, hq, o.io, tmuxSessionPlan, missingSocket);
|
|
6714
6907
|
if (lookAgain(() => panePath(socket, session, o.io, realHome))) { planExtra.launch = launchPlan.recipe; windowCmd = windowCommand(); }
|
|
6715
6908
|
let names;
|
|
6716
6909
|
try { names = tmuxOn(socket, ["list-windows", "-t", `=${session}`, "-F", "#{window_name}"], o.io).split("\n").filter(Boolean); }
|
|
@@ -7237,7 +7430,7 @@ function mirrorTopLevel(source, dest) {
|
|
|
7237
7430
|
for (const e of entriesAsBytes(source)) if (!e.name.equals(GIT_NAME)) copyTreeSafe(joinBytes(source, e.name), joinBytes(dest, e.name));
|
|
7238
7431
|
}
|
|
7239
7432
|
|
|
7240
|
-
const RECOVERABLE_GIT_ADMIN = [
|
|
7433
|
+
export const RECOVERABLE_GIT_ADMIN = [
|
|
7241
7434
|
"MERGE_HEAD", "MERGE_MSG", "AUTO_MERGE", "CHERRY_PICK_HEAD", "REVERT_HEAD", "REBASE_HEAD",
|
|
7242
7435
|
"BISECT_LOG", "BISECT_START", "BISECT_NAMES", "rebase-apply", "rebase-merge", "sequencer",
|
|
7243
7436
|
];
|
|
@@ -7738,7 +7931,9 @@ function homeOnlyRecovery(observation, meta) {
|
|
|
7738
7931
|
* (tree-copy.mjs), and a read-only one (a Go module cache, 0555) keeps
|
|
7739
7932
|
* rmSync from unlinking what is in it: each directory is made u+rwx first,
|
|
7740
7933
|
* before it is read (an unreadable one could not be listed), symbolic links
|
|
7741
|
-
* are never followed, and then the tree is removed.
|
|
7934
|
+
* are never followed, and then the tree is removed. Names are listed and
|
|
7935
|
+
* joined as bytes, as the copier writes them, so a directory whose name is
|
|
7936
|
+
* not UTF-8 is reached too (#827). Never throws: a cleanup
|
|
7742
7937
|
* must not replace the error that made it (#659). → null when the staging is
|
|
7743
7938
|
* gone, else the clause a refusal adds to name what is left. */
|
|
7744
7939
|
function removeStaging(staging) {
|
|
@@ -7748,9 +7943,9 @@ function removeStaging(staging) {
|
|
|
7748
7943
|
const st = lstatSync(dir);
|
|
7749
7944
|
if (!st.isDirectory()) return;
|
|
7750
7945
|
if ((st.mode & 0o700) !== 0o700) chmodSync(dir, (st.mode & 0o7777) | 0o700);
|
|
7751
|
-
names =
|
|
7946
|
+
names = entriesAsBytes(dir).map((e) => e.name);
|
|
7752
7947
|
} catch { return; }
|
|
7753
|
-
for (const name of names) open(
|
|
7948
|
+
for (const name of names) open(joinBytes(dir, name));
|
|
7754
7949
|
};
|
|
7755
7950
|
try { open(staging); rmSync(staging, { recursive: true, force: true }); } catch { /* named below */ }
|
|
7756
7951
|
try { lstatSync(staging); } catch (e) { if (e?.code === "ENOENT") return null; }
|
|
@@ -7764,7 +7959,7 @@ function removeStaging(staging) {
|
|
|
7764
7959
|
* will add to. → { receipt, manifest }: the receipt retire reports, and
|
|
7765
7960
|
* recovery.json as written. */
|
|
7766
7961
|
function writeRetirementRecovery(observation, meta, instance, phase) {
|
|
7767
|
-
const recoveryRoot =
|
|
7962
|
+
const recoveryRoot = retirementRecoveryRoot(dirname(observation.home));
|
|
7768
7963
|
mkdirSync(recoveryRoot, { recursive: true });
|
|
7769
7964
|
if (observation.directory && realpathSync(recoveryRoot) !== join(realpathSync(dirname(observation.home)), ".oats-retirement", "recovery")) {
|
|
7770
7965
|
throw oatsError("E_WORK_PRESERVATION_FAILED", "directory recovery storage was redirected; retain the source home rather than copying into an unowned or disposable location");
|
|
@@ -7984,7 +8179,9 @@ function scheduleDeferredSelfRetirement(root, found, name, o, session) {
|
|
|
7984
8179
|
} catch { /* the marker alone then shows RETIRING; status names its age */ }
|
|
7985
8180
|
});
|
|
7986
8181
|
child.unref();
|
|
7987
|
-
|
|
8182
|
+
// The marker names its completion (pid and start time; the start is null when it cannot be read):
|
|
8183
|
+
// while that process lives, any other retire of this home is refused (refusePendingCompletion).
|
|
8184
|
+
writeFileSync(marker, JSON.stringify({ ...intent, completionPid: child.pid, completionStart: processStartToken(child.pid) }, null, 2) + "\n");
|
|
7988
8185
|
return {
|
|
7989
8186
|
retired: name, agent: found.agent.name, deferred: true, pendingMarker: marker,
|
|
7990
8187
|
resultPath, logPath, completesInSec: delaySec, completionPid: child.pid,
|
|
@@ -8006,6 +8203,9 @@ const OBSOLETE_DELETE_BRANCH_SENTENCE = "this self-retire was requested with --d
|
|
|
8006
8203
|
/** The one internal option that says the retirement completes such an intent.
|
|
8007
8204
|
* A symbol, so no caller can set it from parsed arguments or JSON. */
|
|
8008
8205
|
const OBSOLETE_DELETE_BRANCH = Symbol("an older self-retire intent with --delete-branch");
|
|
8206
|
+
/** The one internal option that says the retirement is a deferred self-retire's completion
|
|
8207
|
+
* (completeDeferredRetirement). A symbol, so no caller can set it from parsed arguments or JSON. */
|
|
8208
|
+
const COMPLETES_DEFERRED = Symbol("the completion of a deferred self-retire");
|
|
8009
8209
|
export const RETIRE_DELETE_BRANCH_REFUSED = "oats retire no longer deletes branches: --delete-branch is not accepted. Retire without it; the branch is left in the repository. Inspect it there and delete it with Git if it is no longer wanted.";
|
|
8010
8210
|
|
|
8011
8211
|
export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
|
|
@@ -8037,6 +8237,10 @@ export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
|
|
|
8037
8237
|
...(Array.isArray(intent.options?.plannedExtraWorktrees) ? { plannedExtraWorktrees: intent.options.plannedExtraWorktrees } : {}),
|
|
8038
8238
|
...(Array.isArray(intent.options?.children) ? { children: intent.options.children } : {}),
|
|
8039
8239
|
...(obsoleteDeleteBranch ? { [OBSOLETE_DELETE_BRANCH]: true } : {}),
|
|
8240
|
+
// The retire that scheduled this completion may still hold the home's claim, about to write
|
|
8241
|
+
// the marker and return: it is waited for, so the two are ordered by the claim and never by
|
|
8242
|
+
// which process is faster.
|
|
8243
|
+
[COMPLETES_DEFERRED]: true,
|
|
8040
8244
|
});
|
|
8041
8245
|
} catch (e) {
|
|
8042
8246
|
record({ ok: false, error: { code: e.code, message: e.message }, ...(e.details?.childrenStopped ? { childrenStopped: e.details.childrenStopped } : {}), ...(obsoleteDeleteBranch ? { warnings: [OBSOLETE_DELETE_BRANCH_SENTENCE] } : {}), retry: `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}` });
|
|
@@ -8066,30 +8270,153 @@ export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
|
|
|
8066
8270
|
* (awebai/oats#693): the CLI cleans that home's wake schedules. A symbol, so
|
|
8067
8271
|
* the printed and JSON receipt, and a recorded one, do not carry it. */
|
|
8068
8272
|
export const RETIRE_SELECTED_HOME = Symbol("oats.retireSelectedHome");
|
|
8069
|
-
|
|
8070
|
-
|
|
8071
|
-
|
|
8072
|
-
|
|
8073
|
-
|
|
8074
|
-
|
|
8075
|
-
|
|
8076
|
-
|
|
8077
|
-
|
|
8078
|
-
|
|
8079
|
-
|
|
8080
|
-
|
|
8273
|
+
/** An option of retireInstance: a function it calls once it holds the home's claim, has resolved
|
|
8274
|
+
* the home again and has found no pending self-retire, before it reads anything else. What the
|
|
8275
|
+
* function throws is the retire's answer, and nothing was done; what it returns, `{ children?,
|
|
8276
|
+
* plannedExtraWorktrees? }`, sets those two options. `oats retire` reads here what the retire
|
|
8277
|
+
* acts on, so that it is the state the retire starts from, never one another retire changed
|
|
8278
|
+
* afterwards: a guarded apply its plan, once, refusing a revision that is not the one shown
|
|
8279
|
+
* (E_PLAN_STALE); a plain or `--self` retire its recorded children. Against a retire in flight
|
|
8280
|
+
* the answer is that it is running, and neither is read. A symbol, so no caller can set it from
|
|
8281
|
+
* parsed arguments or JSON. */
|
|
8282
|
+
export const RETIRE_UNDER_CLAIM = Symbol("oats.retireUnderClaim");
|
|
8283
|
+
/** How many times a retire starts over because the name resolved to another home once it held the
|
|
8284
|
+
* claim of the first (that one removed, a same-named home of another agent made, in between). */
|
|
8285
|
+
const RETIRE_CLAIM_RESTARTS = 2;
|
|
8286
|
+
|
|
8287
|
+
/** The claim file of a retire of `home`: `<instances>/.oats-retirement/claims/<name>.lock`. Beside
|
|
8288
|
+
* the homes, never inside one: a home's bytes are what its retire observes, copies and removes. */
|
|
8289
|
+
function retireClaimPath(home) {
|
|
8290
|
+
return join(instancesRetirementRoot(dirname(home)), "claims", `${basename(home)}.lock`);
|
|
8291
|
+
}
|
|
8292
|
+
|
|
8293
|
+
/** The refusals of a retire of `name` (home `home`) that cannot take its claim `lock`, as
|
|
8294
|
+
* lib/claim.mjs asks for them. All E_LIFECYCLE_BUSY, one line, saying that nothing was done;
|
|
8295
|
+
* `details.lock` is the file that names the holder. */
|
|
8296
|
+
function retireClaimRefusals(name, home, lock) {
|
|
8297
|
+
const refuse = (message, details) => Object.assign(oatsError("E_LIFECYCLE_BUSY", message), { details: { instance: name, home, ...details } });
|
|
8298
|
+
return {
|
|
8299
|
+
busy: (holder, unknown, at = lock) => {
|
|
8300
|
+
const details = { lock: at, pid: holder?.pid ?? null, since: holder?.at ?? null };
|
|
8301
|
+
return unknown
|
|
8302
|
+
? refuse(`whether the retire of ${name} that holds ${at} (pid ${holder?.pid ?? "?"}, recorded start ${holder?.processStart ?? "none"}) still runs cannot be read (${unknown}); nothing was done — check that pid by hand, and if it is not an oats retire, remove ${at}, then retry`, { ...details, unknown })
|
|
8303
|
+
: refuse(`a retire of ${name} is already running (pid ${holder?.pid ?? "?"}, since ${holder?.at ?? "?"}); nothing was done — wait for it to finish`, details);
|
|
8304
|
+
},
|
|
8305
|
+
ownStartUnreadable: (reason, at) => refuse(`this process's start time cannot be read (${reason}), so oats retire cannot hold ${at} verifiably; nothing was done`, { lock: at }),
|
|
8306
|
+
unreadableClaim: (at) => refuse(`${at} is not a readable claim; inspect it and remove it if no oats retire holds it; nothing was done`, { lock: at }),
|
|
8307
|
+
};
|
|
8308
|
+
}
|
|
8309
|
+
|
|
8310
|
+
/** The homes `name` resolves to under `root`, and the one a retire acts on. Names are unique per
|
|
8311
|
+
* agent dir only: two agents can own an instance of the same name (dev --purpose foo-1 and agent
|
|
8312
|
+
* dev-foo). Retirement is destructive, so a name that resolves to several homes is refused unless
|
|
8313
|
+
* the caller says which home (--home), and a home is accepted only when it is one of that name's
|
|
8314
|
+
* homes under this root. */
|
|
8315
|
+
function resolveRetireHome(root, name, o) {
|
|
8081
8316
|
const matches = findInstanceHomes(root, name);
|
|
8082
8317
|
if (!matches.length) throw oatsError("E_SESSION_UNKNOWN", `no instance named "${name}"`);
|
|
8083
8318
|
const sameHome = (a, b) => { try { return realpathSync(a) === realpathSync(b); } catch { return resolve(a) === resolve(b); } };
|
|
8084
|
-
let found;
|
|
8085
8319
|
if (o.home) {
|
|
8086
|
-
found = matches.find((m) => sameHome(m.home, o.home));
|
|
8320
|
+
const found = matches.find((m) => sameHome(m.home, o.home));
|
|
8087
8321
|
if (!found) throw oatsError("E_HOME_MISMATCH", `instance "${name}" has no home at ${o.home} under this agents root (its home${matches.length === 1 ? " is" : "s are"} ${matches.map((m) => m.home).join(", ")})`);
|
|
8088
|
-
|
|
8322
|
+
return found;
|
|
8323
|
+
}
|
|
8324
|
+
if (matches.length > 1) {
|
|
8089
8325
|
throw oatsError("E_AMBIGUOUS_INSTANCE", `"${name}" names ${matches.length} instances under this agents root (${matches.map((m) => `${m.agent.name}: ${m.home}`).join("; ")}); retire with --home <path> to say which`);
|
|
8090
|
-
} else {
|
|
8091
|
-
found = matches[0];
|
|
8092
8326
|
}
|
|
8327
|
+
return matches[0];
|
|
8328
|
+
}
|
|
8329
|
+
|
|
8330
|
+
/** `name` has no home under `root`: remove a retire claim of that name whose holder is gone, in
|
|
8331
|
+
* each instances directory the lookup searches (a retire killed after it removed the home and
|
|
8332
|
+
* before it released). One whose holder is alive, unknown or unreadable is left as it is. `name`
|
|
8333
|
+
* is the caller's: no path is built from one outside the instance-name grammar. */
|
|
8334
|
+
function removeAbandonedRetireClaims(root, name) {
|
|
8335
|
+
if (typeof name !== "string" || !INSTANCE_NAME_RE.test(name)) return;
|
|
8336
|
+
const dirs = new Set([...listAgents(root).map((a) => a._dir), ...capabilityAgentDirs(root).map((c) => c.dir)]);
|
|
8337
|
+
for (const dir of dirs) {
|
|
8338
|
+
const home = join(dir, "instances", name);
|
|
8339
|
+
const lock = retireClaimPath(home);
|
|
8340
|
+
// Whatever stops the removal, the answer is the same: there is no such instance.
|
|
8341
|
+
try { removeGoneClaim(lock, { ...retireClaimRefusals(name, home, lock), waitMs: 0 }); } catch { /* left as it is */ }
|
|
8342
|
+
}
|
|
8343
|
+
}
|
|
8344
|
+
|
|
8345
|
+
/** A deferred self-retire is scheduled for `home` and its completion has not started: every other
|
|
8346
|
+
* retire of the home is refused while that completion lives. The pending marker
|
|
8347
|
+
* (scheduleDeferredSelfRetirement) names it. Nothing refuses when there is no marker, when the
|
|
8348
|
+
* completion left its outcome (it failed: this retire retries it), when the marker names no
|
|
8349
|
+
* completion (an older kernel wrote it), when this process is that completion, or when that
|
|
8350
|
+
* process is gone (it died: this retire does what it owed). */
|
|
8351
|
+
function refusePendingCompletion(name, home) {
|
|
8352
|
+
const marker = retirePendingMarkerPath(home);
|
|
8353
|
+
if (!existsSync(marker) || existsSync(deferredRetireResultPath(home))) return;
|
|
8354
|
+
const pending = readJsonOrUndefined(marker);
|
|
8355
|
+
const pid = pending?.completionPid;
|
|
8356
|
+
if (!Number.isSafeInteger(pid) || pid === process.pid) return;
|
|
8357
|
+
const live = processLiveness({ pid, processStart: pending.completionStart });
|
|
8358
|
+
if (live.state === "gone") return;
|
|
8359
|
+
const start = typeof pending.completionStart === "string" ? pending.completionStart : "none";
|
|
8360
|
+
const details = { instance: name, home, lock: marker, pid, since: pending.requestedAt ?? null };
|
|
8361
|
+
if (live.state === "alive") throw Object.assign(oatsError("E_LIFECYCLE_BUSY", `a retire of ${name} is already scheduled (its completion, pid ${pid}, requested at ${pending.requestedAt ?? "?"}); nothing was done — wait for it to finish`), { details });
|
|
8362
|
+
throw Object.assign(oatsError("E_LIFECYCLE_BUSY", `whether the completion of the scheduled retire of ${name} that ${marker} names (pid ${pid}, recorded start ${start}) still runs cannot be read (${live.reason}); nothing was done — check that pid by hand, and if it is not an oats retire, remove ${marker}, then retry`), { details: { ...details, unknown: live.reason } });
|
|
8363
|
+
}
|
|
8364
|
+
|
|
8365
|
+
/** Retire one instance. One retire of a home at a time (awebai/oats#863): the home's claim
|
|
8366
|
+
* (retireClaimPath; lib/claim.mjs) is taken as soon as the home is resolved, before anything the
|
|
8367
|
+
* retire acts on is read, and held until this returns or throws. Any other retire of that home
|
|
8368
|
+
* is refused at once (E_LIFECYCLE_BUSY) before it stops, copies or runs anything; `--force` does
|
|
8369
|
+
* not bypass it. A claim left by a killed retire is taken over. Every apply path runs this
|
|
8370
|
+
* function: the CLI, the deferred completion, and `--server` on the host. Synchronous. */
|
|
8371
|
+
export function retireInstance(root, name, o = {}) {
|
|
8372
|
+
if (o.deleteBranch) throw oatsError("E_BAD_ARGS", RETIRE_DELETE_BRANCH_REFUSED);
|
|
8373
|
+
let found;
|
|
8374
|
+
try { found = resolveRetireHome(root, name, o); }
|
|
8375
|
+
catch (e) {
|
|
8376
|
+
if (e.code === "E_SESSION_UNKNOWN") removeAbandonedRetireClaims(root, name);
|
|
8377
|
+
throw e;
|
|
8378
|
+
}
|
|
8379
|
+
for (let restarts = 0; ; restarts++) {
|
|
8380
|
+
const lock = retireClaimPath(found.home);
|
|
8381
|
+
const refusals = retireClaimRefusals(name, found.home, lock);
|
|
8382
|
+
// The retirement root as retire makes it for its recovery copies; the claims are private.
|
|
8383
|
+
mkdirSync(instancesRetirementRoot(dirname(found.home)), { recursive: true });
|
|
8384
|
+
mkdirSync(dirname(lock), { recursive: true, mode: 0o700 });
|
|
8385
|
+
// No waiting: a live holder is refused at once. Only a deferred completion waits, for the
|
|
8386
|
+
// retire that scheduled it to return.
|
|
8387
|
+
const me = acquireClaim(lock, { ...refusals, waitMs: o[COMPLETES_DEFERRED] ? CLAIM_WAIT_MS : 0 });
|
|
8388
|
+
try {
|
|
8389
|
+
// Resolved again under the claim: another retire may have removed the home between the
|
|
8390
|
+
// first resolution and the claim. Gone is what a retire of a retired instance answers.
|
|
8391
|
+
const now = resolveRetireHome(root, name, o);
|
|
8392
|
+
if (retireClaimPath(now.home) !== lock) {
|
|
8393
|
+
// The name is another home's now, whose claim this does not hold: start over on that one.
|
|
8394
|
+
if (restarts >= RETIRE_CLAIM_RESTARTS) throw Object.assign(oatsError("E_LIFECYCLE_BUSY", `the home of ${name} changed while its claim was being taken (it is now ${now.home}); nothing was done — retry`), { details: { instance: name, home: now.home, lock: retireClaimPath(now.home) } });
|
|
8395
|
+
found = now;
|
|
8396
|
+
continue;
|
|
8397
|
+
}
|
|
8398
|
+
// Every retire that runs here, in this process: a `--self` that only schedules answers that
|
|
8399
|
+
// one is already scheduled (scheduleDeferredSelfRetirement).
|
|
8400
|
+
if (o.self !== true || o.keepDir) refusePendingCompletion(name, now.home);
|
|
8401
|
+
// What the caller confirms once nobody else can be retiring this home (a guarded apply reads
|
|
8402
|
+
// its plan and checks the revision): after the two answers above, before the retire reads
|
|
8403
|
+
// anything of the home. What it returns of the plan binds the retire.
|
|
8404
|
+
const confirmed = o[RETIRE_UNDER_CLAIM]?.();
|
|
8405
|
+
const bound = confirmed ? { ...o, ...(confirmed.children ? { children: confirmed.children } : {}), ...(confirmed.plannedExtraWorktrees ? { plannedExtraWorktrees: confirmed.plannedExtraWorktrees } : {}) } : o;
|
|
8406
|
+
return retireClaimed(root, name, bound, now);
|
|
8407
|
+
} finally {
|
|
8408
|
+
releaseClaim(lock, me);
|
|
8409
|
+
}
|
|
8410
|
+
}
|
|
8411
|
+
}
|
|
8412
|
+
|
|
8413
|
+
/** The retire of the home `found`, under its claim (retireInstance). */
|
|
8414
|
+
function retireClaimed(root, name, o, found) {
|
|
8415
|
+
const session = o.tmuxSession || DEFAULT_TMUX_SESSION;
|
|
8416
|
+
// self-retire: the caller IS the instance. Without --keep-dir the whole
|
|
8417
|
+
// retirement is deferred to a detached external completion (below); with
|
|
8418
|
+
// --keep-dir the old in-process path runs and kills the window LAST.
|
|
8419
|
+
const self = o.self === true;
|
|
8093
8420
|
const metaPath = join(found.home, "instance.json");
|
|
8094
8421
|
// A QUARANTINED home (spawn failed after a required hook and compensation did
|
|
8095
8422
|
// not finish) has no instance.json — it never got that far. Its marker carries
|
|
@@ -8287,15 +8614,14 @@ export function retireInstance(root, name, o = {}) {
|
|
|
8287
8614
|
} catch (e) {
|
|
8288
8615
|
const detail = String(e.stderr ?? e.message ?? "").trim();
|
|
8289
8616
|
const unestablished = (why) => oatsError("E_RUNTIME_QUIESCE_FAILED", `could not establish that ${runtimeSession}:${runtimeWindow} stopped on ${runtimeSocket}: ${why}`);
|
|
8290
|
-
if (!/no server running|
|
|
8291
|
-
|
|
8292
|
-
|
|
8293
|
-
//
|
|
8294
|
-
//
|
|
8295
|
-
// without its receipt.
|
|
8296
|
-
const
|
|
8297
|
-
if (
|
|
8298
|
-
if (scan.processes.length) throw unestablished(`${detail}; a process still works in this home (${scan.processes.slice(0, 5).map((p) => `pid ${p.pid} ${p.command}`).join(", ")}${scan.processes.length > 5 ? `, and ${scan.processes.length - 5} more` : ""})`);
|
|
8617
|
+
if (!/no server running|can't find session|no sessions/i.test(detail)) {
|
|
8618
|
+
const absence = tmuxServerAbsence(e);
|
|
8619
|
+
if (!absence) throw unestablished(detail || "tmux inspection failed");
|
|
8620
|
+
// A missing socket file, in any tmux's words (a reboot clears tmux's socket directory). A server
|
|
8621
|
+
// outlives its socket file, so that alone does not say the window is gone: it is taken as gone
|
|
8622
|
+
// only when no process works in the home, as for a home without its receipt (#624).
|
|
8623
|
+
const why = absence === "missing-socket" ? missingSocketUnestablished(detail, processesInHome(found.home)) : null;
|
|
8624
|
+
if (why) throw unestablished(why);
|
|
8299
8625
|
}
|
|
8300
8626
|
}
|
|
8301
8627
|
sessionStopped = true;
|