@awebai/oats 0.48.0 → 0.50.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 +326 -28
- package/docs/capabilities.md +425 -8
- package/docs/capability-manifest.schema.json +60 -5
- package/docs/configuration.md +103 -0
- package/docs/desktop-cli-api.md +542 -47
- package/docs/desktop.md +85 -5
- package/docs/execution-targets.md +50 -9
- package/docs/implementation.md +74 -1
- package/docs/integrations.md +7 -5
- package/docs/knowledge.md +167 -197
- 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.49.0.md +770 -0
- package/docs/release-notes/v0.50.0.md +279 -0
- package/docs/schedules.md +289 -53
- package/docs/servers.md +7 -0
- package/docs/souls-and-instances.md +450 -60
- package/docs/workspaces.md +3 -3
- package/injects/work-checkout.md +17 -11
- package/injects/work-worktree.md +19 -13
- package/lib/capability-contract.mjs +100 -11
- package/lib/capability-show.mjs +18 -2
- package/lib/core.mjs +1374 -394
- package/lib/instance-events.mjs +9 -10
- package/lib/instance-git.mjs +19 -10
- package/lib/instance-inspect.mjs +58 -18
- package/lib/instance-lifecycle.mjs +106 -16
- package/lib/instance-resolution.mjs +15 -3
- package/lib/launch-prompt-policy.mjs +17 -3
- package/lib/packages.mjs +1 -0
- package/lib/real-path.mjs +27 -0
- package/lib/refused-text.mjs +17 -0
- package/lib/resolve.mjs +4 -4
- package/lib/retained-after-retire.mjs +387 -0
- package/lib/retire-output.mjs +6 -1
- package/lib/schedule.mjs +9 -2
- package/lib/servers.mjs +32 -6
- package/lib/tree-copy.mjs +18 -7
- package/lib/trigger-sources.mjs +234 -0
- package/lib/triggers.mjs +705 -108
- package/lib/workspace.mjs +20 -5
- package/lib/worktree-hooks.mjs +392 -0
- package/lib/worktree.mjs +655 -0
- 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
|
@@ -28,6 +28,7 @@
|
|
|
28
28
|
* (attached as soul default is for service agents — spawn must supply workDir)
|
|
29
29
|
*/
|
|
30
30
|
import { effectiveLaunchPromptPolicy } from "./launch-prompt-policy.mjs";
|
|
31
|
+
import { canonicalHomePath, realPathOrNearest } from "./real-path.mjs";
|
|
31
32
|
import { createLaunchPromptController } from "./launch-prompts.mjs";
|
|
32
33
|
import { retainLaunchPromptFrame } from "./launch-prompt-evidence.mjs";
|
|
33
34
|
import { qualifyLaunchPromptFixtures } from "./launch-prompt-fixtures.mjs";
|
|
@@ -48,6 +49,7 @@ import { attachSessionTarget } from "./session-viewer.mjs";
|
|
|
48
49
|
import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
|
|
49
50
|
import { appendEvent, liveWaiting, recordStartBoundary } from "./instance-events.mjs";
|
|
50
51
|
import { killGroup } from "./process-group.mjs";
|
|
52
|
+
import { interruptExitStatus, originRemoteOf, runWorktreeHooks, selfIdentity, processLiveness, processStartToken, signalGuard, terminateRecordedGroup, treeStillThere, unknownGroupNote, unverifiedGroupWarning, worktreeHooksOf } from "./worktree-hooks.mjs";
|
|
51
53
|
import { captureLoginEnvironment } from "./login-environment.mjs";
|
|
52
54
|
|
|
53
55
|
import { oatsError, herdrInstanceBusy, herdrInstanceRemoved, herdrSettingRemoved, HERDR_REMOVED } from "./errors.mjs";
|
|
@@ -61,21 +63,22 @@ async function materializePreparedDefault(prepared, home) { const m = await impo
|
|
|
61
63
|
// (manifest, settings, origin, trust; no skills/inject since the copies are not
|
|
62
64
|
// there yet) and REBUILT after materialize against what actually landed. Static
|
|
63
65
|
// import: instance-resolution.mjs does not depend on core.mjs (no cycle).
|
|
64
|
-
import { cloneRemoteFor, toCapabilityRows } from "./instance-resolution.mjs";
|
|
66
|
+
import { cloneRemoteFor, resolutionContractWarnings, toCapabilityRows, verifyMemberClone } from "./instance-resolution.mjs";
|
|
65
67
|
import { GIT_FETCH_TIMEOUT_MS, GIT_TIMEOUT_MS, gitEnv } from "./remote.mjs";
|
|
66
68
|
import { loadLocal } from "./workspace.mjs";
|
|
67
69
|
import { parseConfigData } from "./config-data.mjs";
|
|
68
70
|
import { renderInstructionText } from "./instruction-composition.mjs";
|
|
69
|
-
import { APPROVED_HOOKS, PORTABLE_ENV_NAME_RE, CORE_LAUNCH_ENV, PROCESS_BOOTSTRAP_ENV, PROCESS_BOOTSTRAP_PREFIXES, manifestContractProblems, disposableHomeRootProblem, disposableHomeRootMatches } from "./capability-contract.mjs";
|
|
71
|
+
import { APPROVED_HOOKS, PORTABLE_ENV_NAME_RE, CORE_LAUNCH_ENV, PROCESS_BOOTSTRAP_ENV, PROCESS_BOOTSTRAP_PREFIXES, manifestContractProblems, disposableHomeRootProblem, disposableHomeRootMatches, contractWarningMessages, locatedContractWarnings } from "./capability-contract.mjs";
|
|
70
72
|
import { validateBindingInterface } from "./provider-binding.mjs";
|
|
71
73
|
/** Retirement/rollback tree fingerprint (exported for scope tests: kernel-field neutrality is opt-in per instance home),
|
|
72
74
|
* the exact digest a copied path is compared with (exported so a test holds it to the copier),
|
|
75
|
+
* a worktree's byte digest and the Git directories it leaves out (exported so a test holds them to exact paths),
|
|
73
76
|
* and the receipts the stored digest passes over in a home (exported so a test holds the manifest grammar to refusing each of them). */
|
|
74
|
-
export { exactTreeDigest, fingerprintTree, KERNEL_HOME_RECEIPTS };
|
|
77
|
+
export { exactTreeDigest, fingerprintTree, KERNEL_HOME_RECEIPTS, storedTreeDigest, worktreeBytes, worktreeGitPaths };
|
|
75
78
|
|
|
76
79
|
import { canonicalJson, lineAt, parseStrictJson } from "./canonical-json.mjs";
|
|
77
80
|
import { readPortableBytes } from "./bounded-read.mjs";
|
|
78
|
-
import { copyTreeSafe } from "./tree-copy.mjs";
|
|
81
|
+
import { copyTreeSafe, entriesAsBytes, joinBytes, pathBytes } from "./tree-copy.mjs";
|
|
79
82
|
import { assertSameWorktreeHead, gitRead, gitRepoRead, gitRepoRun, headName, worktreeCommitUnreached, worktreeHead } from "./instance-git.mjs";
|
|
80
83
|
/** The package and capability id grammar (namespaced, lowercase): an id names a
|
|
81
84
|
* directory (a home's module copy), so no path spelling fits it. */
|
|
@@ -123,6 +126,11 @@ export function legacyLocalAgents(root) {
|
|
|
123
126
|
return { code: "legacy-local-agents", dirs, instances,
|
|
124
127
|
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(", ")})` : ""}` };
|
|
125
128
|
}
|
|
129
|
+
/** The instances directories under the agents root `root`: `<root>/<agent>/instances`, one per
|
|
130
|
+
* agent directory, whether or not it exists. */
|
|
131
|
+
export function instancesDirs(root) {
|
|
132
|
+
return subdirs(root).map((agent) => join(root, agent, "instances"));
|
|
133
|
+
}
|
|
126
134
|
/** The instance homes under the agents root `root` (a directory <root>/<agent>/instances/<name>
|
|
127
135
|
* whose instance.json records that name) that other users on the machine can read or enter (any
|
|
128
136
|
* group or other permission bit): one `home-readable` problem naming them, with the exact chmod,
|
|
@@ -186,6 +194,11 @@ export const PACKAGED_SKILLS_DIR = join(PKG_ROOT, "skills");
|
|
|
186
194
|
// ---------- shell helpers ----------
|
|
187
195
|
function sh(cmdline) { return execSync(cmdline, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim(); }
|
|
188
196
|
function shTry(cmdline) { try { return sh(cmdline); } catch { return undefined; } }
|
|
197
|
+
/** The branch spawn records for an attached or checkout instance (#641): the
|
|
198
|
+
* name HEAD carries as headName reads it, or null when HEAD is detached or
|
|
199
|
+
* names a ref OATS carries no branch name for. Never the word "HEAD". A HEAD
|
|
200
|
+
* that cannot be read (not a Git tree) records none, as before. */
|
|
201
|
+
function recordedHeadBranch(dir) { try { return headName(dir).branch; } catch { return undefined; } }
|
|
189
202
|
/** A native PROBE (a harness binary asked about its catalogue or packages) under
|
|
190
203
|
* a preview: bounded by what is left of the shared preflight budget, run in its
|
|
191
204
|
* own process group and group-killed on timeout. Cheap lookups (`command -v`)
|
|
@@ -415,18 +428,6 @@ export function findRoot(cwd = process.cwd()) {
|
|
|
415
428
|
d = parent;
|
|
416
429
|
}
|
|
417
430
|
}
|
|
418
|
-
/** realpath of `p`, or — when `p` does not exist yet — the realpath of its
|
|
419
|
-
* nearest existing ancestor with the remaining segments re-appended. Any path
|
|
420
|
-
* decision about WHERE something will be created has to go through this: a
|
|
421
|
-
* lexical path says nothing about the destination once a symlink sits anywhere
|
|
422
|
-
* along it. */
|
|
423
|
-
function realPathOrNearest(p) {
|
|
424
|
-
try { return realpathSync(p); } catch { /* not created yet — resolve what exists */ }
|
|
425
|
-
let d = resolve(p); const tail = [];
|
|
426
|
-
while (!existsSync(d) && dirname(d) !== d) { tail.unshift(basename(d)); d = dirname(d); }
|
|
427
|
-
try { return join(realpathSync(d), ...tail); } catch { return resolve(p); }
|
|
428
|
-
}
|
|
429
|
-
|
|
430
431
|
/** Is there a Git marker (`.git` dir or worktree pointer file) at or above `dir`?
|
|
431
432
|
* Filesystem-only: it answers "does Git own this location" even when the git
|
|
432
433
|
* binary is missing, refuses the repo (dubious ownership), or cannot read its
|
|
@@ -489,10 +490,12 @@ export function canonicalDeploymentPath(p) {
|
|
|
489
490
|
// Git reports CANONICAL paths, so every comparison and every relative()
|
|
490
491
|
// below must be realpath-based: on macOS a temp/agents root reached through
|
|
491
492
|
// /var while Git reports /private/var would otherwise look "outside" the
|
|
492
|
-
// work tree and silently skip canonicalization.
|
|
493
|
-
//
|
|
493
|
+
// work tree and silently skip canonicalization. So would a root given in
|
|
494
|
+
// another letter case on a case-insensitive filesystem: Git's paths are in
|
|
495
|
+
// their on-disk spelling, and so are both sides here. The agents dir itself
|
|
496
|
+
// may not exist yet (local-only scopes), so resolve the nearest existing
|
|
494
497
|
// ancestor and re-append the remainder.
|
|
495
|
-
const realOf =
|
|
498
|
+
const realOf = canonicalHomePath;
|
|
496
499
|
const same = (a, b) => realOf(a) === realOf(b);
|
|
497
500
|
// Linked or main? `--git-dir` equals `--git-common-dir` in the MAIN worktree
|
|
498
501
|
// and points at <common>/worktrees/<name> in a linked one. This settles it
|
|
@@ -582,7 +585,11 @@ const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
|
|
|
582
585
|
* its reference aliases: a configuration may not name them. */
|
|
583
586
|
export const RESERVED_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME", "OATS_HOME", "OATS_AGENT", "OATS_SOUL", "OATS_SOUL_ID", "OATS_ROOT", "OATS_CONTEXT", "OATS_WORKSPACE", "OATS_EVENT", "OATS_SETTINGS", "OATS_SETTINGS_ORIGINS", "OATS_CLI_BIN", "PI_AGENT_INSTANCE", "PI_AGENT_HOME", "PI_AGENTS_ROOT",
|
|
584
587
|
// The test seam that replaces the login shell (lib/login-environment.mjs): never a launch's to set.
|
|
585
|
-
"OATS_TEST_LOGIN_SHELL"
|
|
588
|
+
"OATS_TEST_LOGIN_SHELL",
|
|
589
|
+
// The test seams of #796, the same: a worktree hook's fixed timeout, the fetch timeout of
|
|
590
|
+
// `oats worktree add` (lib/worktree-hooks.mjs, lib/worktree.mjs), and the `ps` path of a
|
|
591
|
+
// process's start time on a host with procfs (lib/worktree-hooks.mjs processStart).
|
|
592
|
+
"OATS_TEST_WORKTREE_HOOK_TIMEOUT_MS", "OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS", "OATS_TEST_PROCESS_START_PS"]);
|
|
586
593
|
export const LAUNCH_REF_PREFIX = "OATS_LAUNCH_REF_";
|
|
587
594
|
const reservedLaunchEnv = (n) => RESERVED_LAUNCH_ENV.has(n) || n.startsWith(LAUNCH_REF_PREFIX);
|
|
588
595
|
export function validateLaunchConfig(name, entry, where) {
|
|
@@ -725,6 +732,14 @@ function manifestHookCommands(manifest) {
|
|
|
725
732
|
|
|
726
733
|
const PACKAGED_INJECTS_DIR = join(PKG_ROOT, "injects");
|
|
727
734
|
|
|
735
|
+
/** A replayed spawn's contract warnings (contractWarningMessages), from the home's module copies in
|
|
736
|
+
* module-name order; none when they cannot be read (the replay answers what it can, as before). */
|
|
737
|
+
function replayedContractWarnings(home) {
|
|
738
|
+
let manifests;
|
|
739
|
+
try { manifests = typeof home === "string" ? capabilityManifests(home) : {}; } catch { return []; }
|
|
740
|
+
return contractWarningMessages(Object.keys(manifests).sort().flatMap((name) => locatedContractWarnings(manifests[name], `.oats/modules/${name}/oats.json`)));
|
|
741
|
+
}
|
|
742
|
+
|
|
728
743
|
function validateCapabilityManifest(m, mf) {
|
|
729
744
|
const id = m.capability;
|
|
730
745
|
if (!id) throw new Error(`capability manifest needs "capability": ${mf}`);
|
|
@@ -1072,7 +1087,7 @@ function plannedCapabilityRows(resolution) {
|
|
|
1072
1087
|
* `node <abs script> <args>`, exactly as `manifestHookCommands` renders a classic
|
|
1073
1088
|
* capability. The script must exist inside the module's copy under
|
|
1074
1089
|
* <home>/.oats/modules/<cap>/ — a path escaping it is a manifest defect. Only
|
|
1075
|
-
* the events the kernel approves (soul-scaffold, spawn, retire, launch) are kept. */
|
|
1090
|
+
* the events the kernel approves (soul-scaffold, spawn, retire, launch, worktree) are kept. */
|
|
1076
1091
|
function materializedHookCommands(row, home) {
|
|
1077
1092
|
const out = {};
|
|
1078
1093
|
const moduleDir = row.dir || join(home, ".oats", "modules", row.id);
|
|
@@ -1389,7 +1404,8 @@ export const HARNESS_PACKAGE_MANAGERS = {
|
|
|
1389
1404
|
let rows;
|
|
1390
1405
|
try { rows = JSON.parse(out); } catch { return []; }
|
|
1391
1406
|
if (!Array.isArray(rows)) return [];
|
|
1392
|
-
|
|
1407
|
+
// Claude reports projectPath in its on-disk spelling: the context is compared in it too.
|
|
1408
|
+
const target = opts.context ? canonicalHomePath(opts.context) : undefined;
|
|
1393
1409
|
return rows
|
|
1394
1410
|
.filter((r) => r && typeof r.id === "string")
|
|
1395
1411
|
// A user-scope install applies everywhere. A project/local install
|
|
@@ -1397,7 +1413,7 @@ export const HARNESS_PACKAGE_MANAGERS = {
|
|
|
1397
1413
|
.filter((r) => {
|
|
1398
1414
|
if (r.scope === "user") return true;
|
|
1399
1415
|
if (!r.projectPath || !target) return false;
|
|
1400
|
-
const owner =
|
|
1416
|
+
const owner = canonicalHomePath(r.projectPath);
|
|
1401
1417
|
return target === owner || target.startsWith(owner + sep);
|
|
1402
1418
|
})
|
|
1403
1419
|
// verifiedPresent is the "this harness confirms presence without naming a
|
|
@@ -1629,6 +1645,39 @@ function withoutAmbientLaunchPreview(env) {
|
|
|
1629
1645
|
const { OATS_LAUNCH_PREVIEW: _ambient, ...rest } = env;
|
|
1630
1646
|
return rest;
|
|
1631
1647
|
}
|
|
1648
|
+
/** The environment one capability's lifecycle hook runs with: the invoker's own
|
|
1649
|
+
* (inherited, as for every hook; the kernel adds no credentials), plus the
|
|
1650
|
+
* standard OATS_* variables (docs/capabilities.md, Commands and hooks) and the
|
|
1651
|
+
* caller's `extraEnv`. One builder for every event, so the `worktree` runner
|
|
1652
|
+
* (lib/worktree-hooks.mjs) hands its hooks exactly what every other hook gets. */
|
|
1653
|
+
export function lifecycleHookEnv(event, cap, { home, instance, agentName, soulDir, soulId, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {} }) {
|
|
1654
|
+
return {
|
|
1655
|
+
// OATS_LAUNCH_PREVIEW is the kernel's to give (prepareLaunchHooks), never
|
|
1656
|
+
// inherited: a real start's hook must not read an ambient one as a preview.
|
|
1657
|
+
...withoutAmbientLaunchPreview(process.env),
|
|
1658
|
+
// OATS_INSTANCE_HOME is the runtime-neutral contract name for the
|
|
1659
|
+
// instance home (absolute). OATS_HOME predates it and stays as a
|
|
1660
|
+
// compatibility alias: shipped capability hooks read it
|
|
1661
|
+
// (the official oats.aweb and oats.okf packages) and are versioned
|
|
1662
|
+
// independently of this kernel. Neither is OATS_HOME_DIR, which is
|
|
1663
|
+
// the package STORE root — do not conflate them.
|
|
1664
|
+
OATS_EVENT: event, OATS_INSTANCE: instance, OATS_INSTANCE_HOME: home, OATS_HOME: home, OATS_AGENT: agentName,
|
|
1665
|
+
OATS_CAPABILITY: cap.id, OATS_LAYER: cap.layer || "", OATS_ROOT: rootDir || "",
|
|
1666
|
+
OATS_SOUL: soulDir || "", OATS_SOUL_ID: stableSoulId({ soulId, home, soulDir, agentName }), OATS_CONTEXT: contextDir, OATS_WORKSPACE: workspaceDir || "", OATS_LEVEL: cap.level || "",
|
|
1667
|
+
...teamEnv(resolved),
|
|
1668
|
+
...extraEnv,
|
|
1669
|
+
// Hooks also run through direct core callers (not only bin/oats).
|
|
1670
|
+
// Author this from the running kernel, never PATH, ambient env or
|
|
1671
|
+
// a caller's extraEnv: those may point at a different executable.
|
|
1672
|
+
OATS_CLI_BIN: kernelBin(),
|
|
1673
|
+
OATS_SETTINGS: JSON.stringify(cap.settings || {}),
|
|
1674
|
+
// Where each leaf of OATS_SETTINGS came from (JSON pointer → { kind, at }; kind is
|
|
1675
|
+
// manifest-default | workspace | soul | host | spawn | anchor), so a provider can tell a
|
|
1676
|
+
// soul-set value from a host-set one. {} when the home recorded none (spawned before 0.29).
|
|
1677
|
+
OATS_SETTINGS_ORIGINS: JSON.stringify(cap.settingsOrigins || {}),
|
|
1678
|
+
OATS_META: JSON.stringify(priorMeta[cap.id] || {}),
|
|
1679
|
+
};
|
|
1680
|
+
}
|
|
1632
1681
|
export function runLifecycleHooks(event, { home, instance, agentName, soulDir, soulId, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {}, assertRoots }) {
|
|
1633
1682
|
const results = { meta: {}, briefs: [], warnings: [], order: [], launch: {}, env: {}, failures: [], contributions: [], volatileEnv: {} };
|
|
1634
1683
|
// OATS_SOUL is set for EVERY hook: a caller that does not name the soul (launch,
|
|
@@ -1650,32 +1699,7 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, s
|
|
|
1650
1699
|
try {
|
|
1651
1700
|
const stdout = execSync(cmd, {
|
|
1652
1701
|
cwd: home, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 120000,
|
|
1653
|
-
env: {
|
|
1654
|
-
// OATS_LAUNCH_PREVIEW is the kernel's to give (prepareLaunchHooks), never
|
|
1655
|
-
// inherited: a real start's hook must not read an ambient one as a preview.
|
|
1656
|
-
...withoutAmbientLaunchPreview(process.env),
|
|
1657
|
-
// OATS_INSTANCE_HOME is the runtime-neutral contract name for the
|
|
1658
|
-
// instance home (absolute). OATS_HOME predates it and stays as a
|
|
1659
|
-
// compatibility alias: shipped capability hooks read it
|
|
1660
|
-
// (the official oats.aweb and oats.okf packages) and are versioned
|
|
1661
|
-
// independently of this kernel. Neither is OATS_HOME_DIR, which is
|
|
1662
|
-
// the package STORE root — do not conflate them.
|
|
1663
|
-
OATS_EVENT: event, OATS_INSTANCE: instance, OATS_INSTANCE_HOME: home, OATS_HOME: home, OATS_AGENT: agentName,
|
|
1664
|
-
OATS_CAPABILITY: cap.id, OATS_LAYER: cap.layer || "", OATS_ROOT: rootDir || "",
|
|
1665
|
-
OATS_SOUL: soulDir || "", OATS_SOUL_ID: stableSoulId({ soulId, home, soulDir, agentName }), OATS_CONTEXT: contextDir, OATS_WORKSPACE: workspaceDir || "", OATS_LEVEL: cap.level || "",
|
|
1666
|
-
...teamEnv(resolved),
|
|
1667
|
-
...extraEnv,
|
|
1668
|
-
// Hooks also run through direct core callers (not only bin/oats).
|
|
1669
|
-
// Author this from the running kernel, never PATH, ambient env or
|
|
1670
|
-
// a caller's extraEnv: those may point at a different executable.
|
|
1671
|
-
OATS_CLI_BIN: kernelBin(),
|
|
1672
|
-
OATS_SETTINGS: JSON.stringify(cap.settings || {}),
|
|
1673
|
-
// Where each leaf of OATS_SETTINGS came from (JSON pointer → { kind, at }; kind is
|
|
1674
|
-
// manifest-default | workspace | soul | host | spawn | anchor), so a provider can tell a
|
|
1675
|
-
// soul-set value from a host-set one. {} when the home recorded none (spawned before 0.29).
|
|
1676
|
-
OATS_SETTINGS_ORIGINS: JSON.stringify(cap.settingsOrigins || {}),
|
|
1677
|
-
OATS_META: JSON.stringify(priorMeta[cap.id] || {}),
|
|
1678
|
-
},
|
|
1702
|
+
env: lifecycleHookEnv(event, cap, { home, instance, agentName, soulDir, soulId, contextDir, workspaceDir, rootDir, resolved, priorMeta, extraEnv }),
|
|
1679
1703
|
}).trim();
|
|
1680
1704
|
const lastLine = stdout.split("\n").filter(Boolean).pop() || "{}";
|
|
1681
1705
|
let o = {};
|
|
@@ -1947,12 +1971,22 @@ export function explicitInstanceName(name) {
|
|
|
1947
1971
|
return name;
|
|
1948
1972
|
}
|
|
1949
1973
|
|
|
1950
|
-
function tmuxAlive(session) { return !!shTry(`tmux has-session -t ${shq(session)} 2>/dev/null && echo yes`); }
|
|
1951
1974
|
/** The window names of `session` on the user's DEFAULT tmux server: only for a home that records no
|
|
1952
1975
|
* socket (listInstances). OATS creates nothing there: new sessions live on the OATS server below. */
|
|
1953
|
-
export function tmuxWindows(session = DEFAULT_TMUX_SESSION) {
|
|
1954
|
-
|
|
1955
|
-
|
|
1976
|
+
export function tmuxWindows(session = DEFAULT_TMUX_SESSION) { return defaultTmuxWindows(session).windows; }
|
|
1977
|
+
/** tmuxWindows' read, keeping a missing socket file apart (#624): `{ windows }`, with `missingSocket`
|
|
1978
|
+
* (tmux's words) when the default server's socket file is missing. Any other failure reads as no
|
|
1979
|
+
* session. `has-session` first, as ever: it is the read-only probe a caller may expect for a home
|
|
1980
|
+
* that records no socket, and it words a missing socket file as list-windows does. */
|
|
1981
|
+
function defaultTmuxWindows(session) {
|
|
1982
|
+
const run = (args) => execFileSync("tmux", args, { encoding: "utf8", timeout: 10000, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
|
|
1983
|
+
try {
|
|
1984
|
+
run(["has-session", "-t", session]);
|
|
1985
|
+
return { windows: run(["list-windows", "-t", session, "-F", "#{window_name}"]).split("\n").filter(Boolean) };
|
|
1986
|
+
} catch (e) {
|
|
1987
|
+
// Either read: the socket file can go between the two.
|
|
1988
|
+
return tmuxServerAbsence(e) === "missing-socket" ? { windows: [], missingSocket: tmuxFailure(e, "tmux failed") } : { windows: [] };
|
|
1989
|
+
}
|
|
1956
1990
|
}
|
|
1957
1991
|
|
|
1958
1992
|
// ---------- the OATS tmux server ----------
|
|
@@ -1984,8 +2018,11 @@ const exitedByItself = (e) => Number.isInteger(e?.status) && e.signal == null &&
|
|
|
1984
2018
|
/** What the OATS server holds, as `list-sessions` answers: whether it runs, its socket (any session
|
|
1985
2019
|
* names it), and whether a session named exactly `session` is there. No server and no such session
|
|
1986
2020
|
* are the only answers that mean absent, and "no server" is read only from a call that exited by
|
|
1987
|
-
* itself: a line a cut-off call left behind is not tmux's answer. Any other failure is not absence.
|
|
1988
|
-
|
|
2021
|
+
* itself: a line a cut-off call left behind is not tmux's answer. Any other failure is not absence.
|
|
2022
|
+
* A missing socket file is absence only when `missingSocket(detail)` (a session start's check of its
|
|
2023
|
+
* home, missingSocketUnestablished) answers null; its reason refuses the start (#624). Without it, as
|
|
2024
|
+
* today. */
|
|
2025
|
+
function oatsTmuxSessionSocket(session, io, missingSocket) {
|
|
1989
2026
|
let listed;
|
|
1990
2027
|
try { listed = tmuxOatsServer(["list-sessions", "-F", "#{session_name}\t#{socket_path}"], io); }
|
|
1991
2028
|
catch (e) {
|
|
@@ -1993,7 +2030,10 @@ function oatsTmuxSessionSocket(session, io) {
|
|
|
1993
2030
|
// A tmux that could not be run at all is the one failure a person can act on: say so.
|
|
1994
2031
|
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`);
|
|
1995
2032
|
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"})`);
|
|
1996
|
-
|
|
2033
|
+
const absence = tmuxServerAbsence(e);
|
|
2034
|
+
const why = absence === "missing-socket" && missingSocket ? missingSocket(tmuxFailure(e, "tmux list-sessions failed")) : null;
|
|
2035
|
+
if (why) throw oatsError("E_SESSION_UNKNOWN", `cannot establish whether the OATS tmux server for session ${session} is running, so nothing was started: ${why}`);
|
|
2036
|
+
if (absence) return { server: null, present: false };
|
|
1997
2037
|
throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `could not read the OATS tmux server for session ${session}: ${tmuxFailure(e, "tmux list-sessions failed")}`);
|
|
1998
2038
|
}
|
|
1999
2039
|
let server = null, present = false;
|
|
@@ -2021,7 +2061,9 @@ const KERNEL_ENV_NAMES = new Set([...RESERVED_LAUNCH_ENV, "COLORFGBG", "TMUX", "
|
|
|
2021
2061
|
"OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK", "OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME",
|
|
2022
2062
|
"OATS_LAUNCH_PREVIEW", "OATS_RETIRE_INTENT", "OATS_TRIGGER_EVENT_FILE",
|
|
2023
2063
|
"OATS_TEAM_NAME", "OATS_TEAM_SCOPE", "OATS_TEAM_ID", "OATS_TEAM_LABEL", "OATS_TEAM_LABELS", "OATS_TEAMS", "OATS_TEAMS_SOURCE",
|
|
2024
|
-
"OATS_DEFAULT_TEAM", "OATS_DEFAULT_TEAM_ID", "OATS_DEFAULT_TEAM_FROM", "OATS_WORKSPACE_NAME", "OATS_WORKSPACE_KEY"
|
|
2064
|
+
"OATS_DEFAULT_TEAM", "OATS_DEFAULT_TEAM_ID", "OATS_DEFAULT_TEAM_FROM", "OATS_WORKSPACE_NAME", "OATS_WORKSPACE_KEY",
|
|
2065
|
+
// A worktree hook's tree (#796): never inherited by what such a hook starts.
|
|
2066
|
+
"OATS_TREE", "OATS_TREE_CLONE", "OATS_TREE_REMOTE", "OATS_TREE_MEMBER", "OATS_TREE_BASE", "OATS_TREE_BASE_OID", "OATS_PURPOSE", "OATS_TREE_ORIGIN"]);
|
|
2025
2067
|
function withoutKernelEnvironment(source) {
|
|
2026
2068
|
const env = { ...source };
|
|
2027
2069
|
for (const name of Object.keys(env)) {
|
|
@@ -2259,10 +2301,10 @@ function oatsWindowEnvironment() {
|
|
|
2259
2301
|
* again there when that server has gone. undefined when this process has no tmux to run: the
|
|
2260
2302
|
* caller's backend check refuses that.
|
|
2261
2303
|
*/
|
|
2262
|
-
function planOatsTmuxSession(session, io, { preview = false } = {}) {
|
|
2304
|
+
function planOatsTmuxSession(session, io, { preview = false, missingSocket } = {}) {
|
|
2263
2305
|
if (!io?.exec && !which("tmux")) return undefined;
|
|
2264
2306
|
let server, present;
|
|
2265
|
-
try { ({ server, present } = oatsTmuxSessionSocket(session, io)); }
|
|
2307
|
+
try { ({ server, present } = oatsTmuxSessionSocket(session, io, missingSocket)); }
|
|
2266
2308
|
catch (e) { if (preview) return undefined; throw e; } // a preview reports, it does not refuse on a read
|
|
2267
2309
|
if (present || preview) return { server, present };
|
|
2268
2310
|
return { server, present, env: oatsSessionEnvironment(session, io, { startsServer: !server }), startsServer: !server };
|
|
@@ -2338,10 +2380,12 @@ function launchLookup(configEnv, env, pane, configName, cwd) {
|
|
|
2338
2380
|
* second lookup. tmux starts a server once: the first successful creator determines its initial
|
|
2339
2381
|
* environment, and nothing here changes a running server's. E_RUNTIME_ENDPOINT_UNKNOWN when the
|
|
2340
2382
|
* server cannot be read or names no socket, when this caller may not create the session, or when
|
|
2341
|
-
* its own PATH names no tmux to create it with (creatorTmux).
|
|
2383
|
+
* its own PATH names no tmux to create it with (creatorTmux). `missingSocket` is a session start's
|
|
2384
|
+
* check of its home when the server's socket file is missing (oatsTmuxSessionSocket): with a reason,
|
|
2385
|
+
* E_SESSION_UNKNOWN and no server is created at that path.
|
|
2342
2386
|
*/
|
|
2343
|
-
export function ensureOatsTmuxSession(session, hq, io, plan) {
|
|
2344
|
-
let { server: socket, present } = oatsTmuxSessionSocket(session, io);
|
|
2387
|
+
export function ensureOatsTmuxSession(session, hq, io, plan, missingSocket) {
|
|
2388
|
+
let { server: socket, present } = oatsTmuxSessionSocket(session, io, missingSocket);
|
|
2345
2389
|
if (!present) {
|
|
2346
2390
|
// The executable is chosen here, where the creation is about to run, and nowhere earlier: a
|
|
2347
2391
|
// session that exists needs none, so nothing is refused for it.
|
|
@@ -2354,7 +2398,7 @@ export function ensureOatsTmuxSession(session, hq, io, plan) {
|
|
|
2354
2398
|
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(); }
|
|
2355
2399
|
catch (e) {
|
|
2356
2400
|
if (oatsCoded(e)) throw e;
|
|
2357
|
-
const again = oatsTmuxSessionSocket(session, io);
|
|
2401
|
+
const again = oatsTmuxSessionSocket(session, io, missingSocket);
|
|
2358
2402
|
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")}`);
|
|
2359
2403
|
socket = again.server;
|
|
2360
2404
|
}
|
|
@@ -2924,7 +2968,8 @@ export function renderLaunchRecipe(recipe, { home, instance, redact = false, tru
|
|
|
2924
2968
|
if (harness === "claude") {
|
|
2925
2969
|
cmdline = `${shq(executable)}${yolo ? " --dangerously-skip-permissions" : ""}${model ? ` --model ${shq(model)}` : ""}${tail} -- ${shq(TASK_PROMPT.claude)}`;
|
|
2926
2970
|
} else if (harness === "codex") {
|
|
2927
|
-
|
|
2971
|
+
// Codex compares the key with its own working directory, in its on-disk spelling.
|
|
2972
|
+
const codexTrust = `projects={${JSON.stringify(canonicalHomePath(home))}={trust_level="trusted"}}`;
|
|
2928
2973
|
// Codex may run tool commands outside the session's process (its shared app-server daemon),
|
|
2929
2974
|
// so the env the prefix below gives the session is also set for them. A reference's value
|
|
2930
2975
|
// never goes on argv, and PATH is the execution's (CODEX_TOOL_PATH: the shim first).
|
|
@@ -3275,7 +3320,9 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
3275
3320
|
// happened (crash in the interval). Say which, never replay a half-spawn.
|
|
3276
3321
|
if (["blocked", "incomplete"].includes(prior.launchPrompts?.status)) throw retainedPromptError(prior.home, prior.instance, prior.launchPromptTarget ?? prior.tmux, prior.parentLineageCommitted === true, prior.launchPrompts);
|
|
3277
3322
|
if (prior.spawnCompleted !== true) throw unconfirmedSpawn(Object.assign(oatsError("E_SPAWN_INCOMPLETE", `${prior.instance} was created for this key but its spawn did not complete (launch or lineage unfinished); inspect it with oats session inspect --home ${prior.home} — do not spawn again`), { instance: prior.instance, home: prior.home, launched: prior.launched === true ? "unknown" : false }));
|
|
3278
|
-
|
|
3323
|
+
// The receipt's warnings that are facts of the composition (a hook event this kernel ignores),
|
|
3324
|
+
// from the home's module copies: nothing runs again, and the captured composition is unchanged.
|
|
3325
|
+
return { ...prior, replayed: true, launch: undefined, command: undefined, wake: prior.wake ?? { requested: null, saved: null, error: null }, warnings: replayedContractWarnings(prior.home) };
|
|
3279
3326
|
}
|
|
3280
3327
|
}
|
|
3281
3328
|
|
|
@@ -3669,18 +3716,22 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
3669
3716
|
// Addendum 5: where each leaf of `settings.<cap>` came from (JSON pointer → { kind, at }):
|
|
3670
3717
|
// manifest-default | workspace | soul | host | spawn, the last layer that set it.
|
|
3671
3718
|
const preparedSettingsOrigins = Object.fromEntries(o.prepared.resolution.modules.map((m) => [m.name, structuredClone(o.prepared.resolution.payloadOrigins?.[m.name] ?? {})]));
|
|
3719
|
+
// The preview's warnings are strings: the launch-prompt notice, then what a module declares and this kernel ignores.
|
|
3720
|
+
const previewWarnings = [...(promptOptedIn(launchPromptAnswers) ? [LAUNCH_PROMPT_UPDATE_WARNING] : []), ...contractWarningMessages(resolutionContractWarnings(o.prepared.resolution))];
|
|
3672
3721
|
const preparedSettings = Object.fromEntries(o.prepared.resolution.modules.map((m) => [m.name, structuredClone(o.prepared.resolution.payloads?.[m.name] && typeof o.prepared.resolution.payloads[m.name] === "object" ? o.prepared.resolution.payloads[m.name] : {})]));
|
|
3673
3722
|
return deliver({
|
|
3674
3723
|
// Team model v2: the soul's teams here (unmapped rows included) and its default — the choice a
|
|
3675
3724
|
// Desktop offers before anything is minted; joining any but the default is the provider's explicit act.
|
|
3676
3725
|
...{ modules: o.prepared.preview ?? null, teams: structuredClone(o.prepared.resolution.teams ?? []), defaultTeam: structuredClone(o.prepared.resolution.defaultTeam ?? null), resolution: o.prepared.resolution.revision, declRevision: o.prepared.resolution.declRevision ?? null, payloadRevision: o.prepared.resolution.payloadRevision ?? null, workspace: o.prepared.discovery?.key ?? null, standalone: o.prepared.discovery?.standalone === true, providers: preparedProviders, settings: preparedSettings, settingsOrigins: preparedSettingsOrigins },
|
|
3677
|
-
spawnPreviewApi: 2, preview: true, launchPromptAnswers, ...(
|
|
3726
|
+
spawnPreviewApi: 2, preview: true, launchPromptAnswers, ...(previewWarnings.length ? { warnings: previewWarnings } : {}), agent: agent.name, kind: agent.kind || "persistent", instance, home, repo: repoAbs, work,
|
|
3678
3727
|
subject: o.subject ?? { soul: agent.name, agentsRoot: root, context: null },
|
|
3679
3728
|
decision, preflight,
|
|
3680
3729
|
backendStatus: launch ? { name: backend, installed: !!which(backend), started: false } : null,
|
|
3681
3730
|
harness, model: model || null, modelSource: launchSelection.modelSource ?? null, launchConfig: launchConfig?.name ?? null, launchConfigDefault: launchConfig?.harnessDefault === true, yolo, backend,
|
|
3682
3731
|
launch: launchReport({ declared: launchChoice.declared, harness, model, launchConfig: launchConfig?.name, from: launchChoice.from, at: launchChoice.at }),
|
|
3683
3732
|
branch: plannedBranch, base: plannedBase, worktree: work === "worktree" ? join(home, "work") : null,
|
|
3733
|
+
// #796: the `worktree` hooks a worktree-mode spawn would fire, in the order they run; null in other modes.
|
|
3734
|
+
worktreeHooks: work === "worktree" ? worktreeHooksOf(resolvedCfg.capabilities).map((h) => ({ capability: h.id, required: h.required })) : null,
|
|
3684
3735
|
relation: relation || null, parentInstance: parentInstance && parentInstance !== instance ? parentInstance : null,
|
|
3685
3736
|
policy: { childSpawns: ownChildPolicy }, executable: bin, capabilities: preparedCapabilities,
|
|
3686
3737
|
skills: [...expectedResources.filter((r) => r.type === "skill-tree" && !r.deferred).flatMap((r) => r.entries || []), ...preparedSkills], task: task || null,
|
|
@@ -3977,7 +4028,7 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
3977
4028
|
// The tree belongs to its owner — retire never removes it (work/ is a symlink).
|
|
3978
4029
|
if (!o.workDir || !existsSync(o.workDir)) { rmSync(home, { recursive: true, force: true }); throw new Error(`attached mode needs workDir (got: ${o.workDir})`); }
|
|
3979
4030
|
symlinkSync(resolve(o.workDir), join(home, "work"));
|
|
3980
|
-
branch =
|
|
4031
|
+
branch = recordedHeadBranch(o.workDir);
|
|
3981
4032
|
} else if (work === "workspace") {
|
|
3982
4033
|
// Cross-repo coordinator: ./work is the deployment boundary (the directory
|
|
3983
4034
|
// holding oats-local.yaml, prepared.deployment), not a repo — member repos are
|
|
@@ -3991,10 +4042,11 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
3991
4042
|
branch = undefined; // no repo identity: the workspace is not a git tree
|
|
3992
4043
|
} else {
|
|
3993
4044
|
symlinkSync(repoAbs, join(home, "work"));
|
|
3994
|
-
branch =
|
|
4045
|
+
branch = recordedHeadBranch(repoAbs);
|
|
3995
4046
|
}
|
|
3996
4047
|
|
|
3997
|
-
|
|
4048
|
+
// What the composed modules declare and this kernel ignores (an unknown hook event), as the preview said.
|
|
4049
|
+
const warnings = [...(promptOptedIn(launchPromptAnswers) ? [LAUNCH_PROMPT_UPDATE_WARNING] : []), ...contractWarningMessages(resolutionContractWarnings(o.prepared?.resolution))];
|
|
3998
4050
|
|
|
3999
4051
|
// Establish directory ownership while these are still the kernel's own roots.
|
|
4000
4052
|
// A hook may replace either path; it must never mint authority for that target.
|
|
@@ -4049,6 +4101,32 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4049
4101
|
throw new Error(`relation "parent": failed to re-point anchor "${relativeTo}" (${e.message})`);
|
|
4050
4102
|
}
|
|
4051
4103
|
};
|
|
4104
|
+
// #796: the `worktree` hooks this spawn fires (work: worktree only), their run, and the
|
|
4105
|
+
// in-progress marker that covers a parent killed while they run.
|
|
4106
|
+
const treeHooks = work === "worktree" ? worktreeHooksOf(resolvedCfg.capabilities) : [];
|
|
4107
|
+
let worktreeRun = null, treeGuard = null, inProgressMarker = false;
|
|
4108
|
+
const writeSpawnInProgressMarker = (hook) => {
|
|
4109
|
+
const retireOwed = new Set((hookRes.order || []).filter((id) => resolvedCfg.capabilities.find((c) => c.id === id)?.hooks?.retire));
|
|
4110
|
+
writeQuarantineMarker(home, buildQuarantineMarker({
|
|
4111
|
+
instance, agent, soulDir: homeSoulTarget, soulId: preparedSoulId,
|
|
4112
|
+
incomplete: ["the spawn is running its worktree hooks; until its process is gone this home is a spawn in progress"],
|
|
4113
|
+
failed: [{ capability: "oats.kernel", event: "worktree" }],
|
|
4114
|
+
outstandingHooks: retireOwed, outstandingGit: new Set(branch ? ["worktree", "branch"] : ["worktree"]),
|
|
4115
|
+
repoAbs, work, branch, resolvedCfg, hookMeta: hookRes.meta || {}, launched: false, tmux: { session, window: instance },
|
|
4116
|
+
reason: "spawn interrupted while its worktree hooks ran",
|
|
4117
|
+
}), { inProgress: { ...selfIdentity(), startedAt: inProgressStartedAt, branch, baseOid: plannedBase.oid, ...hook } });
|
|
4118
|
+
if (!inProgressMarker) {
|
|
4119
|
+
inProgressMarker = true;
|
|
4120
|
+
writeRetirementBaseline(home, join(home, "work"), work, resolvedCfg.capabilities, { launched: false, tmux: { session, window: instance } });
|
|
4121
|
+
}
|
|
4122
|
+
};
|
|
4123
|
+
const inProgressStartedAt = new Date().toISOString();
|
|
4124
|
+
// The spawn's commit point for the marker: the final instance.json and baseline are written.
|
|
4125
|
+
const clearSpawnInProgressMarker = () => {
|
|
4126
|
+
if (!inProgressMarker) return;
|
|
4127
|
+
rmSync(join(home, ".oats-rollback-incomplete.json"), { force: true });
|
|
4128
|
+
inProgressMarker = false;
|
|
4129
|
+
};
|
|
4052
4130
|
let promptDispatched = false, promptTarget, promptResult, promptStartId;
|
|
4053
4131
|
let windowMayExist = false;
|
|
4054
4132
|
let spawnTmux;
|
|
@@ -4203,8 +4281,58 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4203
4281
|
if (requiredFailures.length) {
|
|
4204
4282
|
const detail = requiredFailures.map((f) => ` ${f.capability} ${f.event} ${f.contract === "environment" ? "environment contract" : "hook (declared required)"}: ${f.message}`).join("\n");
|
|
4205
4283
|
const code = requiredFailures.some((f) => f.contract === "environment") ? "E_HOOK_ENVIRONMENT_CONTRACT" : "E_REQUIRED_HOOK_FAILED";
|
|
4206
|
-
|
|
4284
|
+
// The spawn hooks that ran, in the worktree receipt's shape. A spawn hook keeps no log (`log: null`),
|
|
4285
|
+
// and nothing of its output is carried here.
|
|
4286
|
+
const hooks = (hookRes.order || []).map((id) => {
|
|
4287
|
+
const f = (hookRes.failures || []).find((x) => x.capability === id);
|
|
4288
|
+
const cap = resolvedCfg.capabilities.find((c) => c.id === id);
|
|
4289
|
+
return { capability: id, ok: !f, required: (cap?.requiredHooks || []).includes("spawn") || f?.contract === "environment", log: null, ...(f?.contract ? { contract: f.contract } : {}) };
|
|
4290
|
+
});
|
|
4291
|
+
throw Object.assign(oatsError(code, `a capability this soul activates could not configure itself:\n${detail}\n\nThe instance would have started with an invalid or missing capability configuration`), { details: { hooks } });
|
|
4207
4292
|
}
|
|
4293
|
+
// #796: the `worktree` event, once, for the ./work this spawn created, after the spawn hooks
|
|
4294
|
+
// succeeded and inside this transaction (lib/worktree-hooks.mjs says how it runs). A killed
|
|
4295
|
+
// parent is recovered by `oats retire` from the in-progress marker written before the first hook.
|
|
4296
|
+
if (treeHooks.length) {
|
|
4297
|
+
const tree = worktreeCanonical || realpathSync(join(home, "work"));
|
|
4298
|
+
const cloneReal = realPathOrNearest(repoAbs);
|
|
4299
|
+
// The marker names this process by pid and start; one whose start cannot be read could not be told
|
|
4300
|
+
// apart from a dead one after a kill, so the spawn does not run its worktree hooks without it.
|
|
4301
|
+
if (!processStartToken(process.pid)) throw oatsError("E_SPAWN_FAILED", `this process's start time cannot be read, so a spawn killed while its worktree hooks ran could not be recovered safely; no worktree hook ran`);
|
|
4302
|
+
writeSpawnInProgressMarker({});
|
|
4303
|
+
treeGuard = signalGuard();
|
|
4304
|
+
const treeEnv = {
|
|
4305
|
+
OATS_TREE: tree, OATS_TREE_CLONE: cloneReal, OATS_TREE_REMOTE: originRemoteOf(cloneReal),
|
|
4306
|
+
OATS_TREE_MEMBER: o.prepared?.soulEntry?.repoKey && cloneOfMember(cloneReal, o.prepared.soulEntry.repoKey) ? o.prepared.soulEntry.repoKey : "",
|
|
4307
|
+
OATS_BRANCH: branch, OATS_TREE_BASE: plannedBase.ref, OATS_TREE_BASE_OID: plannedBase.oid, OATS_PURPOSE: "", OATS_TREE_ORIGIN: "spawn",
|
|
4308
|
+
};
|
|
4309
|
+
worktreeRun = yield () => runWorktreeHooks(treeHooks, {
|
|
4310
|
+
envFor: (cap) => lifecycleHookEnv("worktree", cap, { home, instance, agentName: agent.name, soulDir: homeSoulTarget, soulId: preparedSoulId, contextDir: repoAbs, workspaceDir: workspaceOf(root), rootDir: root, resolved: resolvedCfg, priorMeta: hookRes.meta || {}, extraEnv: treeEnv }),
|
|
4311
|
+
cwd: tree, home, purpose: "", guard: treeGuard,
|
|
4312
|
+
onStart: ({ pgid, hookStart }) => writeSpawnInProgressMarker({ hookPgid: pgid, hookStart }),
|
|
4313
|
+
});
|
|
4314
|
+
warnings.push(...worktreeRun.warnings);
|
|
4315
|
+
if (worktreeRun.interrupted) {
|
|
4316
|
+
throw Object.assign(oatsError("E_INTERRUPTED", `the spawn was interrupted by ${worktreeRun.interrupted} while its worktree hooks ran; the running hook's process group was ended`),
|
|
4317
|
+
{ exitStatus: interruptExitStatus(worktreeRun.interrupted), details: { signal: worktreeRun.interrupted, hooks: worktreeRun.receipt } });
|
|
4318
|
+
}
|
|
4319
|
+
// A hook may itself remove or move the tree: the tree must still be this worktree.
|
|
4320
|
+
if (!treeStillThere(tree)) {
|
|
4321
|
+
const msg = `the tree ${tree} is no longer there (or no longer this worktree) after the worktree hooks ran`;
|
|
4322
|
+
if (treeHooks.some((h) => h.required)) worktreeRun.failures.push({ capability: "oats.kernel", event: "worktree", message: msg, required: true });
|
|
4323
|
+
else warnings.push(msg);
|
|
4324
|
+
}
|
|
4325
|
+
const logOf = (id) => worktreeRun.receipt.find((r) => r.capability === id)?.log;
|
|
4326
|
+
for (const f of worktreeRun.failures.filter((x) => !x.required)) warnings.push(`${f.capability} worktree hook failed (continuing): ${f.message}${logOf(f.capability) ? ` (log: ${logOf(f.capability)})` : ""}`);
|
|
4327
|
+
const treeFailures = worktreeRun.failures.filter((x) => x.required);
|
|
4328
|
+
if (treeFailures.length) {
|
|
4329
|
+
requiredFailures.push(...treeFailures);
|
|
4330
|
+
// The logs are in the home, which the rollback may remove: where they are is said after it (below).
|
|
4331
|
+
const detail = treeFailures.map((f) => ` ${f.capability} worktree ${f.contract === "environment" ? "environment contract" : "hook (declared required)"}: ${f.message}`).join("\n");
|
|
4332
|
+
throw Object.assign(oatsError(treeFailures.some((f) => f.contract === "environment") ? "E_HOOK_ENVIRONMENT_CONTRACT" : "E_REQUIRED_HOOK_FAILED", `a capability could not set up the new worktree:\n${detail}`), { details: { hooks: worktreeRun.receipt } });
|
|
4333
|
+
}
|
|
4334
|
+
}
|
|
4335
|
+
treeGuard?.restore();
|
|
4208
4336
|
// Hooks have finished, but no TASK, launch recipe, successful scaffold, or
|
|
4209
4337
|
// backend operation may be published until the owned roots are revalidated.
|
|
4210
4338
|
if (work === "directory") assertDirectoryRoots(home, homeReal);
|
|
@@ -4216,15 +4344,18 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4216
4344
|
}
|
|
4217
4345
|
}
|
|
4218
4346
|
const briefLines = hookRes.briefs.length ? `\n${hookRes.briefs.join("\n")}` : "";
|
|
4347
|
+
// A checkout or attached tree may be on no branch OATS can name (#641): a detached HEAD. With a
|
|
4348
|
+
// branch the text is as it always was; only a missing one is said another way.
|
|
4349
|
+
const noBranch = "no branch that OATS can name, e.g. a detached HEAD";
|
|
4219
4350
|
const workDesc = work === "worktree"
|
|
4220
4351
|
? `a dedicated git worktree of ${repoAbs} on branch "${branch}" — commit freely there`
|
|
4221
4352
|
: work === "attached"
|
|
4222
|
-
? `ATTACHED to another instance's work tree (${o.workDir}, branch ${branch}) — you share it with that instance; make your changes and commits focused, and never switch branches`
|
|
4353
|
+
? `ATTACHED to another instance's work tree (${o.workDir}, ${branch ? `branch ${branch}` : noBranch}) — you share it with that instance; make your changes and commits focused, and never switch branches`
|
|
4223
4354
|
: work === "directory"
|
|
4224
4355
|
? `an instance-owned execution directory — not a Git worktree or a link to ${repoAbs}; that path supplies configuration only`
|
|
4225
4356
|
: work === "workspace"
|
|
4226
4357
|
? `the WHOLE WORKSPACE (${realpathSync(join(home, "work"))}) — every member repo is read-context; you coordinate, you do not edit member repos (see your work-mode briefing)`
|
|
4227
|
-
: `a symlink to the ${repoAbs} checkout — you share it; work on the currently checked-out branch (${branch}) and do not switch branches without being asked`;
|
|
4358
|
+
: `a symlink to the ${repoAbs} checkout — you share it; ${branch ? `work on the currently checked-out branch (${branch})` : `work on what is checked out (${noBranch})`} and do not switch branches without being asked`;
|
|
4228
4359
|
writeFileSync(join(home, "TASK.md"), `# Instance briefing: ${instance}
|
|
4229
4360
|
|
|
4230
4361
|
You are instance "${instance}" of agent "${agent.name}".
|
|
@@ -4269,7 +4400,9 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
|
|
|
4269
4400
|
relativeTo: relation ? relativeTo : undefined,
|
|
4270
4401
|
spawnOrigin: relation || (parentInstance && parentInstance !== instance) ? "instance" : "operator",
|
|
4271
4402
|
policy: { childSpawns: ownChildPolicy },
|
|
4272
|
-
...(triggerEventFile ? { trigger: { id: o.triggerEvent.trigger, key: o.triggerEvent.key ?? null, source: o.triggerEvent.source, repo: o.triggerEvent.repo, number: o.triggerEvent.number, url: o.triggerEvent.url ?? null, event: o.triggerEvent.event, headSha: o.triggerEvent.headSha ?? null, observedAt: o.triggerEvent.observedAt ?? null, eventFile: triggerEventFile
|
|
4403
|
+
...(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,
|
|
4404
|
+
// A capability source's event carries its declared fields (a pull request's never does).
|
|
4405
|
+
...(o.triggerEvent.fields && typeof o.triggerEvent.fields === "object" ? { fields: o.triggerEvent.fields } : {}) } } : {}),
|
|
4273
4406
|
// K6c: a decision-bound spawn records what bound it, so a retry with the
|
|
4274
4407
|
// same key replays this receipt instead of spawning again.
|
|
4275
4408
|
// The FULL bound decision (placement + effective), exactly as the fence
|
|
@@ -4380,6 +4513,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
|
|
|
4380
4513
|
// the managed harness can write. No child-home transition follows launch.
|
|
4381
4514
|
writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
|
|
4382
4515
|
writeRetirementBaseline(home, join(home, "work"), work, resolvedCfg.capabilities, { launched: true, tmux: meta.tmux });
|
|
4516
|
+
clearSpawnInProgressMarker();
|
|
4383
4517
|
// Wrap the command so the window drops into an interactive shell when the
|
|
4384
4518
|
// agent exits (e.g. Ctrl-C) instead of tmux killing the window.
|
|
4385
4519
|
const windowCmd = paneCommand(executionCommand);
|
|
@@ -4415,20 +4549,21 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
|
|
|
4415
4549
|
meta.launched = false;
|
|
4416
4550
|
writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n");
|
|
4417
4551
|
writeRetirementBaseline(home, join(home, "work"), work, resolvedCfg.capabilities, { launched: false, tmux: meta.tmux });
|
|
4552
|
+
clearSpawnInProgressMarker();
|
|
4418
4553
|
}
|
|
4419
4554
|
|
|
4420
4555
|
// Ordinary launches and scaffolds commit here; opted-in launches already
|
|
4421
4556
|
// committed before dispatch so retained prompt failures keep their lineage.
|
|
4422
4557
|
commitParentLineage();
|
|
4423
4558
|
|
|
4424
|
-
appendEvent(home, { kind: "spawned", data: { agent: agent.name, work, branch: branch ?? null, harness, model: model || null, parentInstance: meta.parentInstance ?? null, relation: relation ?? null, launched: launch, hooks: hookReceipt(hookRes) } });
|
|
4559
|
+
appendEvent(home, { kind: "spawned", data: { agent: agent.name, work, branch: branch ?? null, harness, model: model || null, parentInstance: meta.parentInstance ?? null, relation: relation ?? null, launched: launch, hooks: hookReceipt(hookRes), ...(worktreeRun ? { worktreeHooks: worktreeRun.receipt } : {}) } });
|
|
4425
4560
|
if (launch) appendEvent(home, { kind: "launched", data: { harness, backend, launchConfig: launchConfig?.name ?? null } });
|
|
4426
4561
|
if (o.idempotencyKey !== undefined) {
|
|
4427
4562
|
// Only now is the spawn a finished receipt a same-key retry may replay.
|
|
4428
4563
|
meta.spawnCompleted = true;
|
|
4429
4564
|
writeFileSync(join(home, "instance.json"), JSON.stringify(meta, null, 2) + "\n"); // a kernel-owned field: the baseline fingerprint ignores it
|
|
4430
4565
|
}
|
|
4431
|
-
return deliver({ ...meta, ...(o.expectDecision !== undefined ? { replayed: false } : {}), launch: redactLaunchRecipe(recipe), command: redactLaunchCommand(cmdline), attach: launch ? `tmux -S ${shellWord(meta.tmux.socket)} attach -t ${shellWord(session)}` : `oats session attach --home ${shellWord(home)}`, warnings: spawnWarnings.length ? spawnWarnings : undefined });
|
|
4566
|
+
return deliver({ ...meta, ...(o.expectDecision !== undefined ? { replayed: false } : {}), ...(worktreeRun ? { worktreeHooks: worktreeRun.receipt } : {}), launch: redactLaunchRecipe(recipe), command: redactLaunchCommand(cmdline), attach: launch ? `tmux -S ${shellWord(meta.tmux.socket)} attach -t ${shellWord(session)}` : `oats session attach --home ${shellWord(home)}`, warnings: spawnWarnings.length ? spawnWarnings : undefined });
|
|
4432
4567
|
} catch (error) {
|
|
4433
4568
|
if (promptDispatched) {
|
|
4434
4569
|
// Once opted-in launch dispatch occurred, uncertainty retains all effects.
|
|
@@ -4465,6 +4600,20 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
|
|
|
4465
4600
|
// An interrupted compensation pass cannot establish that effects ended.
|
|
4466
4601
|
error.message += ` — rollback INCOMPLETE: cleanup could not be completed: ${cleanupError.message}`;
|
|
4467
4602
|
unconfirmedSpawn(error);
|
|
4603
|
+
} finally {
|
|
4604
|
+
// Interrupts were held through the rollback of a spawn that ran worktree hooks (#796).
|
|
4605
|
+
treeGuard?.restore();
|
|
4606
|
+
}
|
|
4607
|
+
// #796: the worktree hooks' logs are in the home. A rollback that removed it removed them: no
|
|
4608
|
+
// answer names a path that is gone (each entry's `log` is null); a retained home keeps them.
|
|
4609
|
+
if (worktreeRun && error?.details?.hooks === worktreeRun.receipt) {
|
|
4610
|
+
if (existsSync(home)) {
|
|
4611
|
+
const logs = error.details.hooks.map((h) => h.log).filter(Boolean);
|
|
4612
|
+
if (logs.length) error.message += `; the worktree hooks' logs are kept in the retained home: ${logs.join(", ")}`;
|
|
4613
|
+
} else {
|
|
4614
|
+
error.details = { ...error.details, hooks: error.details.hooks.map((h) => ({ ...h, log: null })) };
|
|
4615
|
+
error.message += "; the worktree hooks' output was logged in the instance home, which the rollback removed: run the setup in an existing instance with `oats worktree add` to see it";
|
|
4616
|
+
}
|
|
4468
4617
|
}
|
|
4469
4618
|
throw error;
|
|
4470
4619
|
}
|
|
@@ -4490,26 +4639,42 @@ export function servedIdentityLine(identity) {
|
|
|
4490
4639
|
return `alias ${identity.alias || "?"} on ${identity.team || "?"}`;
|
|
4491
4640
|
}
|
|
4492
4641
|
/** The window names of `session` on the tmux server at `socket`: `{ windows }`, empty when the server
|
|
4493
|
-
* or the session is gone
|
|
4642
|
+
* or the session is gone, with `missingSocket` (tmux's words) when the socket file is missing, which
|
|
4643
|
+
* alone does not say the server is gone (#624); `{ error }` when the server could not be read. */
|
|
4494
4644
|
function recordedTmuxWindows(socket, session) {
|
|
4495
4645
|
try { return { windows: tmuxOn(socket, ["list-windows", "-t", `=${session}`, "-F", "#{window_name}"]).split("\n").filter(Boolean) }; }
|
|
4496
4646
|
catch (e) {
|
|
4497
|
-
|
|
4647
|
+
const absence = tmuxServerAbsence(e);
|
|
4648
|
+
if (absence === "missing-socket") return { windows: [], missingSocket: tmuxFailure(e, "tmux list-windows failed") };
|
|
4649
|
+
if (absence || /can't find session/i.test(String(e.stderr ?? ""))) return { windows: [] };
|
|
4498
4650
|
return { error: String(e.stderr ?? e.message ?? "").trim() || "tmux list-windows failed" };
|
|
4499
4651
|
}
|
|
4500
4652
|
}
|
|
4501
|
-
/** A status row's liveness from its session's windows: unknown (not false) when the server could not
|
|
4502
|
-
|
|
4503
|
-
|
|
4653
|
+
/** A status row's liveness from its session's windows: unknown (not false) when the server could not
|
|
4654
|
+
* be read, and, for a row whose server holds its endpoint (`endpoint`), when its socket file is
|
|
4655
|
+
* missing while a process works in the home or the scan (`scanHome()`, processesInHome's answer for
|
|
4656
|
+
* it) cannot tell (#624). */
|
|
4657
|
+
function tmuxLiveness({ windows, error, missingSocket }, window, scanHome, endpoint) {
|
|
4658
|
+
if (error) return { running: null, runtimeState: "unreachable", runtimeError: error };
|
|
4659
|
+
const running = windows.includes(window);
|
|
4660
|
+
const why = !running && missingSocket && endpoint ? missingSocketUnestablished(missingSocket, scanHome()) : null;
|
|
4661
|
+
return why ? { running: null, runtimeState: "unreachable", runtimeError: why } : { running };
|
|
4504
4662
|
}
|
|
4505
|
-
export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
|
|
4663
|
+
export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io) {
|
|
4506
4664
|
// Liveness reads each home's RECORDED endpoint (a pre-0.31 home records pi-agents): the recorded
|
|
4507
4665
|
// socket, never the ambient $TMUX server, once per socket and session per call, so status costs no
|
|
4508
4666
|
// more child processes as homes grow. A home without a recorded socket reads the default server.
|
|
4667
|
+
// A row whose socket file is missing is checked against one process scan of the host, made the
|
|
4668
|
+
// first time a row needs it and shared by every row (`io` reaches it: processesInHome).
|
|
4669
|
+
let hostScan;
|
|
4670
|
+
const scanOf = (home) => () => {
|
|
4671
|
+
hostScan ??= hostProcesses(io);
|
|
4672
|
+
return hostScan.ok ? { ok: true, processes: processesWorkingIn(hostScan.processes, home) } : hostScan;
|
|
4673
|
+
};
|
|
4509
4674
|
const tmuxByEndpoint = new Map();
|
|
4510
4675
|
const windowsOf = (session, socket) => {
|
|
4511
4676
|
const key = JSON.stringify([socket ?? null, session]);
|
|
4512
|
-
if (!tmuxByEndpoint.has(key)) tmuxByEndpoint.set(key, socket ? recordedTmuxWindows(socket, session) :
|
|
4677
|
+
if (!tmuxByEndpoint.has(key)) tmuxByEndpoint.set(key, socket ? recordedTmuxWindows(socket, session) : defaultTmuxWindows(session));
|
|
4513
4678
|
return tmuxByEndpoint.get(key);
|
|
4514
4679
|
};
|
|
4515
4680
|
const readInstancesOf = (agentDir) => {
|
|
@@ -4529,10 +4694,17 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
|
|
|
4529
4694
|
// is preserved state awaiting cleanup, and must read that way.
|
|
4530
4695
|
const fallback = directoryRollbackPath(home);
|
|
4531
4696
|
const quarantine = existsSync(fallback) ? fallback : join(home, ".oats-rollback-incomplete.json");
|
|
4532
|
-
let rollbackIncomplete;
|
|
4697
|
+
let rollbackIncomplete, spawnInProgress;
|
|
4533
4698
|
if (existsSync(quarantine)) {
|
|
4534
4699
|
try { rollbackIncomplete = JSON.parse(readFileSync(quarantine, "utf8")); }
|
|
4535
4700
|
catch { rollbackIncomplete = { reason: "rollback incomplete" }; }
|
|
4701
|
+
// #796: a spawn still running its worktree hooks keeps a marker that names it
|
|
4702
|
+
// (`inProgress`). While that process is verifiably alive the home is a spawn in
|
|
4703
|
+
// progress, not a failed one; otherwise the marker reads as the quarantine. A process whose
|
|
4704
|
+
// start cannot be read is not shown in progress either: on a host that never reads it, the
|
|
4705
|
+
// row would say "setting up" forever. It reads as the quarantine (its `inProgress` names
|
|
4706
|
+
// the pid), and retire, which never takes it for gone, refuses it with the way out.
|
|
4707
|
+
if (rollbackIncomplete?.inProgress && processLiveness(rollbackIncomplete.inProgress).state === "alive") { rollbackIncomplete = undefined; spawnInProgress = true; }
|
|
4536
4708
|
}
|
|
4537
4709
|
// A self-retire that has been requested but not completed: the home is
|
|
4538
4710
|
// owed a retirement, not live work. Read-only here — completion is the
|
|
@@ -4544,9 +4716,12 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
|
|
|
4544
4716
|
catch { retirePending = { reason: "retire pending" }; }
|
|
4545
4717
|
}
|
|
4546
4718
|
// A home opened in Herdr (removed in 0.31.0) is listed, never observed: its row says so.
|
|
4547
|
-
const liveness = recordsHerdr(meta, readJsonOrUndefined(
|
|
4719
|
+
const liveness = recordsHerdr(meta, readJsonOrUndefined(findRetirementBaseline(home)))
|
|
4548
4720
|
? { running: null, runtimeState: "unsupported", runtimeError: `E_HERDR_REMOVED: ${herdrInstanceRemoved(e.name).message}` }
|
|
4549
|
-
: tmuxLiveness(windowsOf(meta.tmux?.session || tmuxSession, meta.tmux?.socket), meta.tmux?.window || meta.instance || e.name)
|
|
4721
|
+
: tmuxLiveness(windowsOf(meta.tmux?.session || tmuxSession, meta.tmux?.socket), meta.tmux?.window || meta.instance || e.name, scanOf(home),
|
|
4722
|
+
// A home that records no socket and no launch (--no-launch) reads the default server only
|
|
4723
|
+
// by default: that server's missing socket says nothing about it, and stays "not running".
|
|
4724
|
+
!!meta.tmux?.socket || meta.launched === true);
|
|
4550
4725
|
const identity = servedIdentityOf(meta);
|
|
4551
4726
|
// Feature desktop-facts: `startedAt` — the last session start or restart (the receipt's restarts[]),
|
|
4552
4727
|
// else the spawn's own launch (createdAt), else null (never launched); `identityAddress` — the
|
|
@@ -4574,7 +4749,7 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
|
|
|
4574
4749
|
try { const s = instanceSessionTarget(home); if (!s.target || !harnessRunning(inspectSessionTarget(s.target))) waitingOnYou = null; }
|
|
4575
4750
|
catch { waitingOnYou = null; }
|
|
4576
4751
|
}
|
|
4577
|
-
return { ...meta, ...claims, home, instance: e.name, ...facts, ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(retirePending ? { retirePending } : {}) };
|
|
4752
|
+
return { ...meta, ...claims, home, instance: e.name, ...facts, ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}) };
|
|
4578
4753
|
|
|
4579
4754
|
});
|
|
4580
4755
|
};
|
|
@@ -4738,12 +4913,12 @@ function directoryIdentity(path) {
|
|
|
4738
4913
|
// lock creation or backend observation. A metadata mode edit cannot disable it.
|
|
4739
4914
|
function sessionDirectoryGuard(home) {
|
|
4740
4915
|
let baseline;
|
|
4741
|
-
try { baseline = JSON.parse(readFileSync(
|
|
4916
|
+
try { baseline = JSON.parse(readFileSync(findRetirementBaseline(home), "utf8")); }
|
|
4742
4917
|
catch (e) { if (e.code === "ENOENT") return () => {}; throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", "independent session receipt is unreadable"); }
|
|
4743
4918
|
const expected = join(realPathOrNearest(dirname(home)), basename(home));
|
|
4744
4919
|
const check = () => {
|
|
4745
4920
|
if (baseline.directoryWork === true) {
|
|
4746
|
-
if (baseline.version !== RETIRE_BASELINE_VERSION || baseline
|
|
4921
|
+
if (baseline.version !== RETIRE_BASELINE_VERSION || !receiptRecordsHome(baseline, receiptHomeIdentity(home))) throw oatsError("E_WORK_INSPECTION_FAILED", "invalid independent directory home authority");
|
|
4747
4922
|
assertDirectoryRoots(home, expected);
|
|
4748
4923
|
for (const [name, path] of [["home", home], ["work", join(home, "work")]]) {
|
|
4749
4924
|
const actual = directoryIdentity(path), recorded = baseline.directoryRoots?.[name];
|
|
@@ -4789,6 +4964,12 @@ function fetchObservedBase(repoAbs, { key, oid, remote }) {
|
|
|
4789
4964
|
{ details: { repo: repoAbs, repoKey: key, commit: oid, remote } });
|
|
4790
4965
|
}
|
|
4791
4966
|
|
|
4967
|
+
/** Whether `clone` is a clone of the member `key`, read from its local remotes only (never the network):
|
|
4968
|
+
* OATS_TREE_MEMBER names a member only when this holds. */
|
|
4969
|
+
export function cloneOfMember(clone, key) {
|
|
4970
|
+
try { verifyMemberClone(clone, key); return true; } catch { return false; }
|
|
4971
|
+
}
|
|
4972
|
+
|
|
4792
4973
|
/** A failed spawn's compare-and-delete of the branch it created at `oid`: `git update-ref -d` refuses
|
|
4793
4974
|
* atomically if the tip moved (something was committed there), and the branch is then kept. `run`
|
|
4794
4975
|
* answers { ok, out, status, err }. → what is still owed, as messages ([] when the branch is gone). */
|
|
@@ -4802,8 +4983,11 @@ function deleteBranchAsCreated(run, repoAbs, branch, oid) {
|
|
|
4802
4983
|
}
|
|
4803
4984
|
/** Retain the home and its cleanup receipt when spawn compensation or retirement
|
|
4804
4985
|
* cannot finish. Keeping the original credentials makes cleanup retryable. */
|
|
4805
|
-
|
|
4806
|
-
|
|
4986
|
+
/** The quarantine marker (`.oats-rollback-incomplete.json`) a rollback that cannot finish leaves:
|
|
4987
|
+
* the cleanup descriptor a retry consumes (usableCleanupDescriptor). One builder for the
|
|
4988
|
+
* rollback below and for a spawn's in-progress marker (#796), which adds `inProgress`. */
|
|
4989
|
+
function buildQuarantineMarker({ instance, agent, soulDir, soulId, incomplete, failed, outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg, hookMeta, compensationMeta, launched, tmux, reason, directoryPreservation = false, orphanedWork = false }) {
|
|
4990
|
+
return {
|
|
4807
4991
|
// `reason` is optional and DEFAULTS to the spawn wording, so every existing
|
|
4808
4992
|
// caller is byte-identical; only a caller that supplies one differs. The
|
|
4809
4993
|
// quarantine shape is now reached from two events and a fixed "spawn"
|
|
@@ -4833,12 +5017,20 @@ function quarantineInstanceHome({ home, instance, agent, soulDir, soulId, incomp
|
|
|
4833
5017
|
},
|
|
4834
5018
|
createdAt: new Date().toISOString(),
|
|
4835
5019
|
};
|
|
5020
|
+
}
|
|
5021
|
+
/** Write a quarantine marker by rename, so a marker that replaces another (a spawn's
|
|
5022
|
+
* compensation over its in-progress marker) never leaves two files or a moment with none.
|
|
5023
|
+
* `extra` adds top-level fields (`inProgress`). */
|
|
5024
|
+
function writeQuarantineMarker(home, marker, extra = {}, mode) {
|
|
5025
|
+
writeJsonAtomic(join(home, ".oats-rollback-incomplete.json"), { ...marker, ...extra }, mode);
|
|
5026
|
+
}
|
|
5027
|
+
function quarantineInstanceHome({ home, instance, agent, soulDir, soulId, incomplete, failed, outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg, hookMeta, compensationMeta, launched, tmux, recordRetirementBaseline = false, reason, directoryPreservation = false, orphanedWork = false, directoryHome = realPathOrNearest(home) }) {
|
|
5028
|
+
const marker = buildQuarantineMarker({ instance, agent, soulDir, soulId, incomplete, failed, outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg, hookMeta, compensationMeta, launched, tmux, reason, directoryPreservation, orphanedWork });
|
|
4836
5029
|
try {
|
|
4837
|
-
const path = join(home, ".oats-rollback-incomplete.json");
|
|
4838
5030
|
if (work === "directory") {
|
|
4839
5031
|
assertDirectoryHome(home, directoryHome);
|
|
4840
|
-
|
|
4841
|
-
} else
|
|
5032
|
+
writeQuarantineMarker(home, marker, {}, 0o600);
|
|
5033
|
+
} else writeQuarantineMarker(home, marker);
|
|
4842
5034
|
} catch {
|
|
4843
5035
|
if (work === "directory") {
|
|
4844
5036
|
// Never write through a substituted home (even its metadata paths).
|
|
@@ -4918,21 +5110,87 @@ function usableCleanupDescriptor(marker) {
|
|
|
4918
5110
|
return true;
|
|
4919
5111
|
}
|
|
4920
5112
|
|
|
5113
|
+
// The stored digests are versioned apart (`digestVersion`, BASELINE_DIGEST_VERSION): this version
|
|
5114
|
+
// also gates runtime, directory-home and provider-exclusion authority, so a bump would refuse them all.
|
|
4921
5115
|
const RETIRE_BASELINE_VERSION = 2;
|
|
5116
|
+
/** The version of the stored digests a spawn baseline is written with (fingerprintTrees,
|
|
5117
|
+
* generatedWorkDigest); a baseline without `digestVersion` holds the legacy ones, 1. */
|
|
5118
|
+
const BASELINE_DIGEST_VERSION = 2;
|
|
5119
|
+
/** The version of a baseline's stored digests (`homeFingerprint`, `generatedWorkFingerprint`):
|
|
5120
|
+
* 1 when it has no `digestVersion` (or there is no baseline), 2 when it says 2, and undefined for
|
|
5121
|
+
* any other value, which no digest this kernel takes matches. It is never inferred. */
|
|
5122
|
+
function baselineDigestVersion(baseline) {
|
|
5123
|
+
if (!baseline || !Object.hasOwn(baseline, "digestVersion")) return 1;
|
|
5124
|
+
return baseline.digestVersion === BASELINE_DIGEST_VERSION ? BASELINE_DIGEST_VERSION : undefined;
|
|
5125
|
+
}
|
|
4922
5126
|
|
|
4923
5127
|
function retirementStateRoot(home) {
|
|
4924
5128
|
// Independent of the bytes it authenticates, but colocated with the agent's
|
|
4925
5129
|
// already instance-owned storage rather than the source repository or user
|
|
4926
5130
|
// config home. Retiring <instances>/<name> never removes this sibling.
|
|
4927
|
-
return
|
|
5131
|
+
return instancesRetirementRoot(dirname(home));
|
|
5132
|
+
}
|
|
5133
|
+
/** The retirement state of the homes in the instances directory `instances`. */
|
|
5134
|
+
function instancesRetirementRoot(instances) {
|
|
5135
|
+
return join(instances, ".oats-retirement");
|
|
5136
|
+
}
|
|
5137
|
+
/** Where retire writes the recovery copies of the homes in the instances directory `instances`. */
|
|
5138
|
+
export function retirementRecoveryRoot(instances) {
|
|
5139
|
+
return join(instancesRetirementRoot(instances), "recovery");
|
|
5140
|
+
}
|
|
5141
|
+
|
|
5142
|
+
/** A home's identity as a receipt records it: its on-disk spelling, own name included. A home that
|
|
5143
|
+
* is a symlink is not followed: its parent's on-disk spelling and its name as given (a home
|
|
5144
|
+
* exchanged for a symlink is not the home it points at). */
|
|
5145
|
+
function receiptHomeIdentity(home) {
|
|
5146
|
+
let st;
|
|
5147
|
+
try { st = lstatSync(home); } catch { /* not there: spelled as the nearest existing ancestor */ }
|
|
5148
|
+
return st && !st.isSymbolicLink() ? canonicalHomePath(home) : join(canonicalHomePath(dirname(home)), basename(home));
|
|
4928
5149
|
}
|
|
4929
5150
|
|
|
4930
|
-
|
|
4931
|
-
|
|
5151
|
+
/** Whether a receipt's recorded home is this home, whatever spelling either was written in.
|
|
5152
|
+
* `current` is the home as the caller resolves it for the comparison. */
|
|
5153
|
+
function receiptRecordsHome(baseline, current) {
|
|
5154
|
+
return typeof baseline?.home === "string" && receiptHomeIdentity(baseline.home) === current;
|
|
4932
5155
|
}
|
|
4933
5156
|
|
|
5157
|
+
function retirementBaselineFile(identity) {
|
|
5158
|
+
return join(retirementStateRoot(identity), "baselines", `${createHash("sha256").update(identity).digest("hex")}.json`);
|
|
5159
|
+
}
|
|
5160
|
+
|
|
5161
|
+
/** Where a spawn writes a home's receipt: keyed by its canonical identity. */
|
|
4934
5162
|
function retirementBaselinePath(home) {
|
|
4935
|
-
return
|
|
5163
|
+
return retirementBaselineFile(receiptHomeIdentity(home));
|
|
5164
|
+
}
|
|
5165
|
+
|
|
5166
|
+
/** Where a kernel before 0.49.0 wrote it: keyed by the parent's realpath in the spawn's own
|
|
5167
|
+
* spelling, which on a case-insensitive filesystem need not be the on-disk one. */
|
|
5168
|
+
function legacyRetirementBaselinePath(home) {
|
|
5169
|
+
return retirementBaselineFile(join(realPathOrNearest(dirname(home)), basename(home)));
|
|
5170
|
+
}
|
|
5171
|
+
|
|
5172
|
+
/** The receipt every reader uses: the canonical one if it exists, else one an earlier kernel left
|
|
5173
|
+
* under this caller's spelling, else the canonical path (absent). Read-only: a receipt found at the
|
|
5174
|
+
* legacy key is used where it is, never moved, copied or rewritten elsewhere.
|
|
5175
|
+
*
|
|
5176
|
+
* Limits. A legacy receipt written under spelling S is found only from S, or from the canonical
|
|
5177
|
+
* spelling when that is S: a third spelling of such a home misses it (address the home as
|
|
5178
|
+
* `oats status` prints it, the spawn's spelling). Receipts outlive retire, so a reused name can
|
|
5179
|
+
* leave an earlier incarnation's receipt behind; the canonical one wins, which is right for every
|
|
5180
|
+
* home spawned from 0.49.0 on. It is wrong in one case: two incarnations of the same name, both
|
|
5181
|
+
* spawned by a kernel before 0.49.0 under different spellings, the earlier one under the canonical
|
|
5182
|
+
* spelling. The later home then reads the earlier one's receipt. Its stale endpoint disagrees with
|
|
5183
|
+
* instance.json (E_RUNTIME_AUTHORITY_MISMATCH) unless the later incarnation sits at the same
|
|
5184
|
+
* endpoint, where session control already targets the right session. Retire finds the home
|
|
5185
|
+
* fingerprint changed and preserves the home, less the stale receipt's disposable roots; a
|
|
5186
|
+
* directory-work disagreement is E_WORK_INSPECTION_FAILED; and a start's record rewrites the stale
|
|
5187
|
+
* file, as a kernel before 0.49.0 already does when a caller's spelling matches an earlier
|
|
5188
|
+
* incarnation's. */
|
|
5189
|
+
function findRetirementBaseline(home) {
|
|
5190
|
+
const canonical = retirementBaselinePath(home);
|
|
5191
|
+
if (existsSync(canonical)) return canonical;
|
|
5192
|
+
const legacy = legacyRetirementBaselinePath(home);
|
|
5193
|
+
return legacy !== canonical && existsSync(legacy) ? legacy : canonical;
|
|
4936
5194
|
}
|
|
4937
5195
|
|
|
4938
5196
|
/** git's output for a large tree (status with untracked and ignored files,
|
|
@@ -4944,6 +5202,53 @@ function retirementBaselinePath(home) {
|
|
|
4944
5202
|
* loudly, and streaming is deliberately not attempted in this change. */
|
|
4945
5203
|
const GIT_MAX_BUFFER = 512 * 1024 * 1024;
|
|
4946
5204
|
|
|
5205
|
+
/** How the retire runs Git on the instance's work, its repository, a
|
|
5206
|
+
* repository under the work and a recovery clone (awebai/oats#662, #679):
|
|
5207
|
+
* argv only, no shell; optional locks off (`--no-optional-locks` and
|
|
5208
|
+
* GIT_OPTIONAL_LOCKS=0), so a status never refreshes, and so never rewrites,
|
|
5209
|
+
* the index it inspects; no helper that a repository's own configuration
|
|
5210
|
+
* names can run (fsmonitor, hooks, an external diff), nor any command a
|
|
5211
|
+
* fetch would run (GIT_NO_LAZY_FETCH=1: an object a promisor repository
|
|
5212
|
+
* lacks is a failed read, never fetched through a remote, helper, ssh
|
|
5213
|
+
* command or credential helper its configuration names; Git before 2.44
|
|
5214
|
+
* ignores the variable); and nothing of the caller's environment redirects
|
|
5215
|
+
* what is read. Git's own list of
|
|
5216
|
+
* repository-local variables (`git rev-parse --local-env-vars`: GIT_DIR,
|
|
5217
|
+
* GIT_WORK_TREE, GIT_INDEX_FILE, GIT_COMMON_DIR, the object directories,
|
|
5218
|
+
* GIT_CONFIG and GIT_CONFIG_PARAMETERS, …) and the GIT_CONFIG_KEY_<n> and
|
|
5219
|
+
* GIT_CONFIG_VALUE_<n> pairs are left out. `env` adds variables after that:
|
|
5220
|
+
* a read that names its own GIT_INDEX_FILE keeps it.
|
|
5221
|
+
* The operator's global and system configuration stay read, unlike
|
|
5222
|
+
* lib/instance-git.mjs's READ_ONLY_GIT with gitEnv(): the spawn baseline was
|
|
5223
|
+
* taken under them, and without them a status reads differently (a global
|
|
5224
|
+
* core.excludesFile, core.autocrlf, a filter), which would add a copy
|
|
5225
|
+
* attempt to every existing instance's retire. These flags leave a status as
|
|
5226
|
+
* it was. They are the operator's own; what the retire guards against is
|
|
5227
|
+
* configuration the retired agent could write.
|
|
5228
|
+
* Known limit: a filter driver that the repository's configuration names and
|
|
5229
|
+
* its .gitattributes select can still run during `git status`; turning it
|
|
5230
|
+
* off would change what status reports. */
|
|
5231
|
+
const RETIRE_GIT_FLAGS = ["--no-optional-locks", "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "-c", "diff.external="];
|
|
5232
|
+
const RETIRE_GIT_DROPPED_ENV = new Set(["GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_CONFIG", "GIT_CONFIG_PARAMETERS", "GIT_CONFIG_COUNT", "GIT_OBJECT_DIRECTORY", "GIT_DIR", "GIT_WORK_TREE", "GIT_IMPLICIT_WORK_TREE", "GIT_GRAFT_FILE", "GIT_INDEX_FILE", "GIT_NO_REPLACE_OBJECTS", "GIT_REPLACE_REF_BASE", "GIT_PREFIX", "GIT_SHALLOW_FILE", "GIT_COMMON_DIR"]);
|
|
5233
|
+
function retireGitEnv(env) {
|
|
5234
|
+
const out = {};
|
|
5235
|
+
for (const [key, value] of Object.entries(process.env)) {
|
|
5236
|
+
if (!RETIRE_GIT_DROPPED_ENV.has(key) && !/^GIT_CONFIG_(?:KEY|VALUE)_\d+$/.test(key)) out[key] = value;
|
|
5237
|
+
}
|
|
5238
|
+
return { ...out, GIT_OPTIONAL_LOCKS: "0", GIT_NO_LAZY_FETCH: "1", ...env };
|
|
5239
|
+
}
|
|
5240
|
+
/** One retire Git command in `repo` (`-C`; null for none, as for a clone) →
|
|
5241
|
+
* its stdout (a Buffer, or text with `encoding`); throws what execFileSync
|
|
5242
|
+
* throws. */
|
|
5243
|
+
function retireGit(repo, args, { env, input, encoding } = {}) {
|
|
5244
|
+
return execFileSync("git", [...RETIRE_GIT_FLAGS, ...(repo === null ? [] : ["-C", repo]), ...args],
|
|
5245
|
+
{ stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], input, encoding, maxBuffer: GIT_MAX_BUFFER, shell: false, env: retireGitEnv(env) });
|
|
5246
|
+
}
|
|
5247
|
+
/** retireGit that never throws → spawnSync's result, for a caller that reads the exit status. */
|
|
5248
|
+
function retireGitProbe(repo, args, { encoding } = {}) {
|
|
5249
|
+
return spawnSync("git", [...RETIRE_GIT_FLAGS, "-C", repo, ...args], { stdio: ["ignore", "pipe", "pipe"], encoding, maxBuffer: GIT_MAX_BUFFER, shell: false, env: retireGitEnv() });
|
|
5250
|
+
}
|
|
5251
|
+
|
|
4947
5252
|
/** Kernel-owned receipts the kernel itself appends to a home after the spawn
|
|
4948
5253
|
* baseline (events log, stop/restart receipts). They are evidence about the
|
|
4949
5254
|
* instance, not the instance's work, so the stored digest a spawn baseline is
|
|
@@ -4962,12 +5267,19 @@ const KERNEL_HOME_RECEIPT_PATTERNS = [/^\.oats-stop-receipt\..+\.json$/, /^\.oat
|
|
|
4962
5267
|
* settings.json at every launch. The stored digest passes over exactly that
|
|
4963
5268
|
* path, home-relative; the exact digest holds it, as the home copy does. */
|
|
4964
5269
|
const HARNESS_HOME_SETTINGS = new Set([join(".claude", "settings.json")]);
|
|
5270
|
+
/** Kernel state written under `.oats/` after the spawn baseline (#796): the extra
|
|
5271
|
+
* trees' records (`oats worktree add|remove`) and the `worktree` hooks' logs.
|
|
5272
|
+
* Receipts, not work: the stored digest passes over them as it does over the
|
|
5273
|
+
* kernel's top-level receipts; the exact digest and the home copy hold them.
|
|
5274
|
+
* They live under `.oats`, which a capability may not declare as its own. */
|
|
5275
|
+
const KERNEL_HOME_STATE_DIRS = new Set([join(".oats", "trees"), join(".oats", "logs")]);
|
|
4965
5276
|
/** The refusal for an entry that is not a file, a directory or a symbolic link
|
|
4966
5277
|
* (a socket, a FIFO, a device): it has no bytes to read or to copy. One
|
|
4967
5278
|
* sentence for every caller of fingerprintTree, at spawn and at retire, so it
|
|
4968
5279
|
* names neither. It does not say "remove": the entry may be a live endpoint. */
|
|
4969
5280
|
const unsupportedEntry = (path) => oatsError("E_WORK_INSPECTION_FAILED", `${path} has an unsupported filesystem type: it is not a file, a directory or a symbolic link, so it cannot be read or copied. Safely stop the process or resource that owns it, or move the entry elsewhere, before retrying`);
|
|
4970
5281
|
const PATH_SEPARATOR_BYTES = Buffer.from(sep);
|
|
5282
|
+
const GIT_NAME = Buffer.from(".git");
|
|
4971
5283
|
/** The digests of a tree, from one walk that reads each file once → { stored,
|
|
4972
5284
|
* exact }; each only when asked for (`stored` by default).
|
|
4973
5285
|
*
|
|
@@ -4975,29 +5287,39 @@ const PATH_SEPARATOR_BYTES = Buffer.from(sep);
|
|
|
4975
5287
|
* permission bits, its kind, and a file's bytes or a link's target. Entry
|
|
4976
5288
|
* names and link targets are read and hashed as bytes, never as decoded
|
|
4977
5289
|
* text: two trees that differ only in bytes that are not UTF-8 have two
|
|
4978
|
-
* digests, and an entry with such a name is read, not missed.
|
|
4979
|
-
*
|
|
4980
|
-
*
|
|
4981
|
-
* is not UTF-8.
|
|
5290
|
+
* digests, and an entry with such a name is read, not missed. copyTreeSafe
|
|
5291
|
+
* reads, joins and writes names as bytes too, so such an entry is copied.
|
|
5292
|
+
* `root` is a path, as text or as bytes.
|
|
4982
5293
|
*
|
|
4983
5294
|
* A name's text (its bytes decoded as UTF-8, the way readdirSync decodes
|
|
4984
5295
|
* them: replacement characters for bytes that are not UTF-8, a byte order
|
|
4985
|
-
* mark kept) is used only to
|
|
4986
|
-
*
|
|
4987
|
-
*
|
|
4988
|
-
*
|
|
4989
|
-
*
|
|
5296
|
+
* mark kept) is used only to test membership: the names a digest passes over
|
|
5297
|
+
* and `instance.json`, as they have always been tested, and to order the
|
|
5298
|
+
* entries for the legacy stored digest. Both digests pass over what a copy
|
|
5299
|
+
* does not carry: `excludeRoot`, names at the top level tested as text, and
|
|
5300
|
+
* `excludePaths`, exact paths under the root as bytes (a list of Buffers):
|
|
5301
|
+
* an entry is passed over only where its whole path is one of them, whatever
|
|
5302
|
+
* its kind, never by its name alone. Only the stored digest also passes over
|
|
5303
|
+
* the kernel's receipts and the harness settings of a home.
|
|
4990
5304
|
*
|
|
4991
|
-
* `stored` is the digest a spawn baseline holds
|
|
4992
|
-
*
|
|
4993
|
-
*
|
|
4994
|
-
*
|
|
4995
|
-
*
|
|
4996
|
-
*
|
|
4997
|
-
*
|
|
4998
|
-
*
|
|
4999
|
-
*
|
|
5000
|
-
*
|
|
5305
|
+
* `stored` is the digest a spawn baseline holds and is compared with, in the
|
|
5306
|
+
* version `digestVersion` names (the baseline's own: baselineDigestVersion).
|
|
5307
|
+
* Both versions hold a home's `instance.json` without the fields the kernel
|
|
5308
|
+
* writes after spawn (kernelNeutralInstanceJson), so they read alike two
|
|
5309
|
+
* `instance.json` files that parse to the same value.
|
|
5310
|
+
* - 1, the legacy digest: what a baseline without `digestVersion` holds,
|
|
5311
|
+
* written by a kernel before 0.49.0. It never changes: its framing (each
|
|
5312
|
+
* field followed by NUL, no lengths) and its order (the names as text,
|
|
5313
|
+
* compared by localeCompare, so it depends on the locale). For a tree whose
|
|
5314
|
+
* names and link targets are all valid UTF-8 it is what it was when they
|
|
5315
|
+
* were read as text: hashing a text hashes its UTF-8, which is those bytes.
|
|
5316
|
+
* Without lengths it reads alike a file whose bytes spell the entry that
|
|
5317
|
+
* follows it and those two entries.
|
|
5318
|
+
* - 2 (BASELINE_DIGEST_VERSION), what a spawn writes now: the framing of the
|
|
5319
|
+
* exact digest below, and the entries ordered by the bytes of their names,
|
|
5320
|
+
* which no locale changes. Two trees it does not read alike are two
|
|
5321
|
+
* trees, but for the receipts, the harness settings and the neutral form
|
|
5322
|
+
* of `instance.json` it passes over.
|
|
5001
5323
|
*
|
|
5002
5324
|
* `exact` is for every comparison of a tree with itself later, or with its
|
|
5003
5325
|
* copy: whether the retire hooks left it as it was. It is kept nowhere. It
|
|
@@ -5007,7 +5329,11 @@ const PATH_SEPARATOR_BYTES = Buffer.from(sep);
|
|
|
5007
5329
|
* path, its mode, its kind and its content, where the path and the content
|
|
5008
5330
|
* carry their length and the mode and the kind end in NUL, so the stream can
|
|
5009
5331
|
* be read back into its entries in one way only, and a tree is the set of
|
|
5010
|
-
* its entries. A home's `instance.json` goes in as the bytes it has.
|
|
5332
|
+
* its entries. A home's `instance.json` goes in as the bytes it has. It
|
|
5333
|
+
* follows the walk's order: the legacy digest's when the walk takes that
|
|
5334
|
+
* one too, the order of the bytes otherwise. An exact digest is compared
|
|
5335
|
+
* only with one taken with the same options (an inspection's, with the
|
|
5336
|
+
* same baseline), so the two are taken in one order.
|
|
5011
5337
|
*
|
|
5012
5338
|
* The root's own permission bits, which are no entry of the walk, are in
|
|
5013
5339
|
* the exact digest: a path the recovery copier copies is compared with its
|
|
@@ -5016,69 +5342,90 @@ const PATH_SEPARATOR_BYTES = Buffer.from(sep);
|
|
|
5016
5342
|
* its copy is made inside a directory the copier creates, so the root's bits
|
|
5017
5343
|
* are no part of what it carries, and the root is compared through its
|
|
5018
5344
|
* children alone. The stored digest never holds the root's bits. */
|
|
5019
|
-
function fingerprintTrees(root, { excludeRoot = new Set(),
|
|
5020
|
-
|
|
5021
|
-
const
|
|
5022
|
-
|
|
5023
|
-
|
|
5345
|
+
function fingerprintTrees(root, { excludeRoot = new Set(), excludePaths = [], instanceHome = false, stored = true, digestVersion = 1, exact = false, children = false } = {}) {
|
|
5346
|
+
if (stored && digestVersion !== 1 && digestVersion !== BASELINE_DIGEST_VERSION) throw new Error(`no stored digest of version ${digestVersion}`);
|
|
5347
|
+
const legacy = stored && digestVersion === 1;
|
|
5348
|
+
const excluded = new Set(excludePaths.map((path) => path.toString("hex")));
|
|
5349
|
+
// The stored digest: `s` when it is the legacy one, `v` when it is version 2.
|
|
5350
|
+
const s = legacy ? createHash("sha256") : null, v = stored && !legacy ? createHash("sha256") : null, x = exact ? createHash("sha256") : null;
|
|
5351
|
+
const digests = () => ({ stored: s || v ? `sha256:${(s || v).digest("hex")}` : undefined, exact: x ? `sha256:${x.digest("hex")}` : undefined });
|
|
5352
|
+
/** A field whose length is not fixed, in the exact digest or in version 2: its length, NUL, its bytes. */
|
|
5353
|
+
const sizedIn = (hash, bytes) => { hash.update(String(bytes.length)); hash.update("\0"); hash.update(bytes); };
|
|
5354
|
+
const sized = (bytes) => sizedIn(x, bytes);
|
|
5024
5355
|
const rootStat = lstatSync(root);
|
|
5025
5356
|
if (!rootStat.isDirectory()) {
|
|
5026
5357
|
const mode = String(rootStat.mode & 0o7777);
|
|
5027
5358
|
s?.update(mode); s?.update("\0");
|
|
5359
|
+
v?.update("entry\0"); v?.update(mode); v?.update("\0");
|
|
5028
5360
|
x?.update("entry\0"); x?.update(mode); x?.update("\0");
|
|
5029
|
-
if (rootStat.isSymbolicLink()) { const target = readlinkSync(root, "buffer"); s?.update("link\0"); s?.update(target); if (x) { x.update("link\0"); sized(target); } }
|
|
5030
|
-
else if (rootStat.isFile()) { const bytes = readFileSync(root); s?.update("file\0"); s?.update(bytes); if (x) { x.update("file\0"); sized(bytes); } }
|
|
5031
|
-
else throw unsupportedEntry(root);
|
|
5361
|
+
if (rootStat.isSymbolicLink()) { const target = readlinkSync(root, "buffer"); s?.update("link\0"); s?.update(target); if (v) { v.update("link\0"); sizedIn(v, target); } if (x) { x.update("link\0"); sized(target); } }
|
|
5362
|
+
else if (rootStat.isFile()) { const bytes = readFileSync(root); s?.update("file\0"); s?.update(bytes); if (v) { v.update("file\0"); sizedIn(v, bytes); } if (x) { x.update("file\0"); sized(bytes); } }
|
|
5363
|
+
else throw unsupportedEntry(String(root));
|
|
5032
5364
|
return digests();
|
|
5033
5365
|
}
|
|
5366
|
+
v?.update("tree\0");
|
|
5034
5367
|
x?.update(children ? "tree\0" : `tree with its mode\0${rootStat.mode & 0o7777}\0`);
|
|
5035
5368
|
// `dir` and `rel` are bytes: the directory, and its path under the root
|
|
5036
5369
|
// (empty at the root). `relText` is `rel` as text, for the name tests.
|
|
5037
|
-
// `
|
|
5038
|
-
const walk = (dir, rel, relText,
|
|
5039
|
-
// The order is the one it has always been: the names as text,
|
|
5040
|
-
// by localeCompare, on the listing as readdirSync returns it.
|
|
5041
|
-
// stable and the listing is the same whether its names come
|
|
5042
|
-
// as bytes, so a tree whose names are all valid UTF-8 is
|
|
5043
|
-
// order it always was. Names that decode alike (two that
|
|
5044
|
-
// or one and a name that really holds the replacement
|
|
5045
|
-
// the listing's order. Where that order is not fixed, two
|
|
5046
|
-
// directory can differ, which adds a copy attempt; two
|
|
5047
|
-
// cannot read alike for it, because the bytes of every
|
|
5048
|
-
|
|
5049
|
-
|
|
5370
|
+
// `storedOn` is false inside an entry the stored digest passes over.
|
|
5371
|
+
const walk = (dir, rel, relText, storedOn) => {
|
|
5372
|
+
// The legacy order is the one it has always been: the names as text,
|
|
5373
|
+
// compared by localeCompare, on the listing as readdirSync returns it.
|
|
5374
|
+
// The sort is stable and the listing is the same whether its names come
|
|
5375
|
+
// as text or as bytes, so a tree whose names are all valid UTF-8 is
|
|
5376
|
+
// walked in the order it always was. Names that decode alike (two that
|
|
5377
|
+
// are not UTF-8, or one and a name that really holds the replacement
|
|
5378
|
+
// character) keep the listing's order. Where that order is not fixed, two
|
|
5379
|
+
// reads of one directory can differ, which adds a copy attempt; two
|
|
5380
|
+
// different trees cannot read alike for it, because the bytes of every
|
|
5381
|
+
// name are hashed. Every other walk is in the order of the names' bytes
|
|
5382
|
+
// (entriesAsBytes), which is fixed.
|
|
5383
|
+
const entries = legacy
|
|
5384
|
+
? readdirSync(dir, { encoding: "buffer" }).map((bytes) => ({ bytes, name: bytes.toString("utf8") })).sort((a, b) => a.name.localeCompare(b.name))
|
|
5385
|
+
: entriesAsBytes(dir).map((e) => ({ bytes: e.name, name: e.name.toString("utf8") }));
|
|
5050
5386
|
for (const { bytes: nameBytes, name } of entries) {
|
|
5051
|
-
|
|
5387
|
+
const childRel = rel.length ? Buffer.concat([rel, PATH_SEPARATOR_BYTES, nameBytes]) : nameBytes;
|
|
5388
|
+
if ((!relText && excludeRoot.has(name)) || (excluded.size && excluded.has(childRel.toString("hex")))) continue;
|
|
5052
5389
|
const childRelText = relText ? join(relText, name) : name;
|
|
5053
|
-
const storedPassesOver = instanceHome && ((!relText && (KERNEL_HOME_RECEIPTS.has(name) || KERNEL_HOME_RECEIPT_PATTERNS.some((p) => p.test(name)))) || HARNESS_HOME_SETTINGS.has(childRelText));
|
|
5390
|
+
const storedPassesOver = instanceHome && ((!relText && (KERNEL_HOME_RECEIPTS.has(name) || KERNEL_HOME_RECEIPT_PATTERNS.some((p) => p.test(name)))) || HARNESS_HOME_SETTINGS.has(childRelText) || KERNEL_HOME_STATE_DIRS.has(childRelText));
|
|
5054
5391
|
if (storedPassesOver && !x) continue;
|
|
5055
|
-
const
|
|
5056
|
-
const
|
|
5392
|
+
const on = storedOn && !storedPassesOver;
|
|
5393
|
+
const s = on ? outerS : null, v = on ? outerV : null;
|
|
5057
5394
|
const path = Buffer.concat([dir, PATH_SEPARATOR_BYTES, nameBytes]);
|
|
5058
5395
|
const st = lstatSync(path);
|
|
5059
5396
|
const mode = String(st.mode & 0o7777);
|
|
5060
5397
|
s?.update(childRel); s?.update("\0"); s?.update(mode); s?.update("\0");
|
|
5398
|
+
if (v) { sizedIn(v, childRel); v.update(mode); v.update("\0"); }
|
|
5061
5399
|
if (x) { sized(childRel); x.update(mode); x.update("\0"); }
|
|
5062
5400
|
if (st.isSymbolicLink()) {
|
|
5063
5401
|
const target = readlinkSync(path, "buffer");
|
|
5064
5402
|
s?.update("link\0"); s?.update(target); s?.update("\0");
|
|
5403
|
+
if (v) { v.update("link\0"); sizedIn(v, target); }
|
|
5065
5404
|
if (x) { x.update("link\0"); sized(target); }
|
|
5066
5405
|
} else if (st.isFile()) {
|
|
5067
5406
|
const bytes = readFileSync(path);
|
|
5068
5407
|
// Kernel-field neutrality applies ONLY when the tree IS an instance home, and only to the
|
|
5069
5408
|
// stored digest; a work tree's instance.json is the agent's bytes.
|
|
5070
|
-
s
|
|
5409
|
+
const storedBytes = s || v ? (instanceHome && !relText && name === "instance.json" ? kernelNeutralInstanceJson(bytes) : bytes) : undefined;
|
|
5410
|
+
s?.update("file\0"); s?.update(storedBytes); s?.update("\0");
|
|
5411
|
+
if (v) { v.update("file\0"); sizedIn(v, storedBytes); }
|
|
5071
5412
|
if (x) { x.update("file\0"); sized(bytes); }
|
|
5072
|
-
} else if (st.isDirectory()) { s?.update("dir\0"); x?.update("dir\0"); walk(path, childRel, childRelText,
|
|
5073
|
-
else throw unsupportedEntry(join(root, childRelText));
|
|
5413
|
+
} else if (st.isDirectory()) { s?.update("dir\0"); v?.update("dir\0"); x?.update("dir\0"); walk(path, childRel, childRelText, on); }
|
|
5414
|
+
else throw unsupportedEntry(join(String(root), childRelText));
|
|
5074
5415
|
}
|
|
5075
5416
|
};
|
|
5076
|
-
|
|
5417
|
+
const outerS = s, outerV = v;
|
|
5418
|
+
walk(Buffer.from(root), Buffer.alloc(0), "", true);
|
|
5077
5419
|
return digests();
|
|
5078
5420
|
}
|
|
5079
|
-
/** The stored digest of a tree (fingerprintTrees): what a spawn baseline
|
|
5421
|
+
/** The legacy stored digest of a tree (fingerprintTrees, version 1): what a spawn baseline without
|
|
5422
|
+
* `digestVersion` holds and is compared with. */
|
|
5080
5423
|
function fingerprintTree(root, options = {}) {
|
|
5081
|
-
return fingerprintTrees(root, { ...options, stored: true, exact: false }).stored;
|
|
5424
|
+
return fingerprintTrees(root, { ...options, stored: true, digestVersion: 1, exact: false }).stored;
|
|
5425
|
+
}
|
|
5426
|
+
/** The stored digest of a tree in `digestVersion` (fingerprintTrees): 1, the legacy one, or 2. */
|
|
5427
|
+
function storedTreeDigest(root, digestVersion, options = {}) {
|
|
5428
|
+
return fingerprintTrees(root, { ...options, stored: true, digestVersion, exact: false }).stored;
|
|
5082
5429
|
}
|
|
5083
5430
|
/** The exact digest of a tree (fingerprintTrees): what a tree is compared with itself later, or with its copy. */
|
|
5084
5431
|
function exactTreeDigest(root, options = {}) {
|
|
@@ -5090,7 +5437,10 @@ const directoryBytes = (work) => exactTreeDigest(work);
|
|
|
5090
5437
|
|
|
5091
5438
|
/** A worktree directory whose git admin entry is gone: no `.git`, an unreadable one, or a gitfile naming an
|
|
5092
5439
|
* admin directory that no longer exists. Read from the gitfile, not asked of git, which would walk up into
|
|
5093
|
-
* whatever repository encloses the home. A `.git` directory is a repository of its own, not this case.
|
|
5440
|
+
* whatever repository encloses the home. A `.git` directory is a repository of its own, not this case.
|
|
5441
|
+
* The gitfile is parsed as Git parses it (setup.c, read_gitfile_gently): the file starts with `gitdir: `,
|
|
5442
|
+
* and the path is the rest of it with its trailing run of line feeds and carriage returns removed, white
|
|
5443
|
+
* space kept (awebai/oats#647). A file Git would not read as a gitfile names no admin entry. */
|
|
5094
5444
|
function worktreeAdminMissing(work) {
|
|
5095
5445
|
const dotGit = join(work, ".git");
|
|
5096
5446
|
let stat;
|
|
@@ -5099,9 +5449,10 @@ function worktreeAdminMissing(work) {
|
|
|
5099
5449
|
if (!stat.isFile()) return true;
|
|
5100
5450
|
let text;
|
|
5101
5451
|
try { text = readFileSync(dotGit, "utf8"); } catch { return true; }
|
|
5102
|
-
|
|
5103
|
-
|
|
5104
|
-
|
|
5452
|
+
if (!text.startsWith("gitdir: ")) return true;
|
|
5453
|
+
const path = text.slice("gitdir: ".length).replace(/[\r\n]+$/, "");
|
|
5454
|
+
if (!path) return true;
|
|
5455
|
+
return !existsSync(join(resolve(work, path), "HEAD"));
|
|
5105
5456
|
}
|
|
5106
5457
|
/** A repository's status as Git printed it, as bytes. A path that is not
|
|
5107
5458
|
* UTF-8 is in there as it is: the work state compares these bytes
|
|
@@ -5109,7 +5460,7 @@ function worktreeAdminMissing(work) {
|
|
|
5109
5460
|
* a `git status` that fails is. */
|
|
5110
5461
|
function worktreeStatusBytes(repo) {
|
|
5111
5462
|
try {
|
|
5112
|
-
return
|
|
5463
|
+
return retireGit(repo, ["status", "--porcelain=v1", "-z", "--untracked-files=all", "--ignored=matching", "--ignore-submodules=none"]);
|
|
5113
5464
|
} catch (e) {
|
|
5114
5465
|
throw oatsError("E_WORK_INSPECTION_FAILED", `could not inspect instance worktree: ${String(e.stderr ?? e.message ?? "").trim() || "git status failed"}`);
|
|
5115
5466
|
}
|
|
@@ -5152,6 +5503,48 @@ function assertStatusAgrees(source, recovered, what, repo) {
|
|
|
5152
5503
|
throw Object.assign(new Error(`${what}${shown ? `: ${shown}${more}` : ""}`), { statusDisagreement: { repo, ...diff } });
|
|
5153
5504
|
}
|
|
5154
5505
|
|
|
5506
|
+
/** The digest of a worktree's untracked (`??`) and ignored (`!!`) paths, outside the disposable
|
|
5507
|
+
* roots, that a spawn baseline stores as `generatedWorkFingerprint`, in the baseline's digest
|
|
5508
|
+
* version (baselineDigestVersion) → the digest, or undefined for a version this kernel does not
|
|
5509
|
+
* take. `statusBytes` is the worktree's status as bytes (worktreeStatusBytes). */
|
|
5510
|
+
function generatedWorkFingerprintIn(digestVersion, work, statusBytes, disposableRoots = []) {
|
|
5511
|
+
if (digestVersion === 1) return generatedWorkFingerprint(work, statusBytes.toString("utf8"), disposableRoots);
|
|
5512
|
+
if (digestVersion === BASELINE_DIGEST_VERSION) return generatedWorkDigest(work, statusBytes, disposableRoots);
|
|
5513
|
+
return undefined;
|
|
5514
|
+
}
|
|
5515
|
+
/** Version 2 of generatedWorkFingerprint. The paths are the status's bytes (untrackedOrIgnoredPaths),
|
|
5516
|
+
* so a name that is not UTF-8 is read by its own name, and they are in the order of those bytes. A
|
|
5517
|
+
* path is hashed as its length and its bytes, then, by lstat (a link is never followed): `missing`
|
|
5518
|
+
* for one that is not there, else its stored digest of version 2 (a link is its target's bytes,
|
|
5519
|
+
* whether or not the target exists). A trailing `/` (an ignored directory's row) is hashed with the
|
|
5520
|
+
* path but not used to read it, so a link in its place is read as the link. A disposable root owns
|
|
5521
|
+
* a path that is it or under it, compared as bytes, as the legacy digest compares it as text.
|
|
5522
|
+
* A path that cannot be tested (lstat fails otherwise than for an entry that is not there) or read
|
|
5523
|
+
* (an entry under it without permission, for example) is no path the digest can prove anything
|
|
5524
|
+
* of: it throws E_WORK_INSPECTION_FAILED, `could not inspect <path>: <reason>`, the path as text. */
|
|
5525
|
+
function generatedWorkDigest(work, statusBytes, disposableRoots = []) {
|
|
5526
|
+
const roots = disposableRoots.map((root) => [Buffer.from(root), Buffer.from(`${root}${sep}`)]);
|
|
5527
|
+
const owned = (path) => roots.some(([root, under]) => path.equals(root) || (path.length >= under.length && path.subarray(0, under.length).equals(under)));
|
|
5528
|
+
const paths = untrackedOrIgnoredPaths(statusBytes).filter((path) => !owned(path)).sort(Buffer.compare);
|
|
5529
|
+
const hash = createHash("sha256");
|
|
5530
|
+
for (const rel of paths) {
|
|
5531
|
+
hash.update(String(rel.length)); hash.update("\0"); hash.update(rel);
|
|
5532
|
+
const path = joinBytes(work, rel.length > 1 && rel[rel.length - 1] === 0x2f ? rel.subarray(0, -1) : rel);
|
|
5533
|
+
const uninspectable = (e) => (e?.code === "E_WORK_INSPECTION_FAILED" ? e : oatsError("E_WORK_INSPECTION_FAILED", `could not inspect ${path.toString()}: ${e.message}`));
|
|
5534
|
+
try { lstatSync(path); }
|
|
5535
|
+
catch (e) {
|
|
5536
|
+
if (e?.code !== "ENOENT" && e?.code !== "ENOTDIR") throw uninspectable(e);
|
|
5537
|
+
hash.update("missing\0"); continue;
|
|
5538
|
+
}
|
|
5539
|
+
let digest;
|
|
5540
|
+
try { digest = storedTreeDigest(path, BASELINE_DIGEST_VERSION); }
|
|
5541
|
+
catch (e) { throw uninspectable(e); }
|
|
5542
|
+
hash.update(digest); hash.update("\0");
|
|
5543
|
+
}
|
|
5544
|
+
return `sha256:${hash.digest("hex")}`;
|
|
5545
|
+
}
|
|
5546
|
+
/** The legacy generatedWorkFingerprint (digest version 1), for a baseline without `digestVersion`.
|
|
5547
|
+
* It never changes: the decoded status's paths, tested with existsSync, which follows a link. */
|
|
5155
5548
|
function generatedWorkFingerprint(work, status, disposableRoots = []) {
|
|
5156
5549
|
const owned = (path) => disposableRoots.some((root) => path === root || path.startsWith(`${root}${sep}`));
|
|
5157
5550
|
const paths = status.split("\0").filter(Boolean)
|
|
@@ -5173,12 +5566,15 @@ function retirementDisposableRoots(work, capabilities) {
|
|
|
5173
5566
|
];
|
|
5174
5567
|
const roots = [];
|
|
5175
5568
|
for (const receipt of receipts) {
|
|
5176
|
-
|
|
5569
|
+
// The manifest check (capability-contract.mjs, disposableWorkRootProblem) refuses
|
|
5570
|
+
// the first two before a spawn gets here; they stay for a copy read without it.
|
|
5571
|
+
if (typeof receipt.root !== "string" || !receipt.root || isAbsolute(receipt.root)) throw oatsError("E_CAPABILITY_BROKEN", `retirement disposable root from ${receipt.owner} must be relative`);
|
|
5177
5572
|
const normalized = receipt.root.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
|
|
5178
|
-
if (!normalized || normalized.split("/").some((part) => !part || part === "." || part === "..")) throw
|
|
5573
|
+
if (!normalized || normalized.split("/").some((part) => !part || part === "." || part === "..")) throw oatsError("E_CAPABILITY_BROKEN", `unsafe retirement disposable root from ${receipt.owner}: ${receipt.root}`);
|
|
5179
5574
|
const path = join(work, normalized);
|
|
5180
|
-
|
|
5181
|
-
if (
|
|
5575
|
+
// lstat, never existsSync: a link whose target is missing is a link all the same.
|
|
5576
|
+
if (lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink()) throw oatsError("E_CAPABILITY_BROKEN", `retirement disposable root from ${receipt.owner} is a symlink: ${normalized}`);
|
|
5577
|
+
if (roots.some((r) => normalized === r.root || normalized.startsWith(`${r.root}/`) || r.root.startsWith(`${normalized}/`))) throw oatsError("E_CAPABILITY_BROKEN", `overlapping retirement disposable roots: ${normalized}`);
|
|
5182
5578
|
roots.push({ owner: receipt.owner, root: normalized });
|
|
5183
5579
|
}
|
|
5184
5580
|
return roots;
|
|
@@ -5279,8 +5675,9 @@ function extraWorktreesOf(home) {
|
|
|
5279
5675
|
const trees = [];
|
|
5280
5676
|
let names;
|
|
5281
5677
|
try { names = readdirSync(home); } catch { return trees; }
|
|
5282
|
-
|
|
5283
|
-
const
|
|
5678
|
+
// Git reports paths in their on-disk spelling: the home and each tree are compared in it too.
|
|
5679
|
+
const realHome = canonicalHomePath(home);
|
|
5680
|
+
const inHome = (p) => { const rel = relative(realHome, canonicalHomePath(p)); return rel === "" || !(rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)); };
|
|
5284
5681
|
for (const name of names.sort(byCodeUnit)) {
|
|
5285
5682
|
if (!name.startsWith(".work-")) continue;
|
|
5286
5683
|
const path = join(home, name);
|
|
@@ -5291,28 +5688,50 @@ function extraWorktreesOf(home) {
|
|
|
5291
5688
|
if (!dirs.ok) continue;
|
|
5292
5689
|
const [gitDir, commonDir, toplevel] = dirs.out.split("\n");
|
|
5293
5690
|
if (!gitDir || !commonDir || !toplevel || realPathOrNearest(gitDir) === realPathOrNearest(commonDir)) continue;
|
|
5294
|
-
const real =
|
|
5691
|
+
const real = canonicalHomePath(path);
|
|
5295
5692
|
// A repository inside the home goes with the home: its trees are home bytes.
|
|
5296
|
-
if (
|
|
5693
|
+
if (canonicalHomePath(toplevel) !== real || inHome(commonDir)) continue;
|
|
5297
5694
|
const list = gitRead(path, ["worktree", "list", "--porcelain", "-z"]);
|
|
5298
5695
|
if (!list.ok) continue;
|
|
5299
5696
|
const records = parseWorktreeList(list.out);
|
|
5300
|
-
const self = records.find((r) =>
|
|
5697
|
+
const self = records.find((r) => canonicalHomePath(r.worktree) === real);
|
|
5301
5698
|
if (!records.length || !self) continue;
|
|
5302
5699
|
trees.push({ name, path, repo: records[0].worktree, gitDir, commonDir: realPathOrNearest(commonDir), locked: self.locked });
|
|
5303
5700
|
}
|
|
5304
5701
|
return trees;
|
|
5305
5702
|
}
|
|
5703
|
+
/** Where retire re-homes the worktrees it retains, one directory per repository under it. */
|
|
5704
|
+
export function retainedWorktreesRoot(workspace) {
|
|
5705
|
+
return join(workspace, ".agents", "worktrees");
|
|
5706
|
+
}
|
|
5707
|
+
/** The longest retained-worktree leaf before its `-N` suffix, in bytes (awebai/oats#821). The
|
|
5708
|
+
* leaf is one path component, so it must fit NAME_MAX (255 on the usual filesystems). 16 bytes
|
|
5709
|
+
* are kept as a margin, as the test fixtures keep: nothing appends to the leaf's name today
|
|
5710
|
+
* (`git worktree move` renames to the path it is given, which does not exist, and adds nothing),
|
|
5711
|
+
* so the margin is headroom only. 8 more are kept for the `-N` suffix (`-` and up to seven
|
|
5712
|
+
* digits). A leaf is then at most 231 bytes, and at most 239 with its suffix. */
|
|
5713
|
+
export const RETAINED_LEAF_MAX = 255 - 16 - 8;
|
|
5306
5714
|
/** Where a retired worktree is re-homed: `<workspace>/.agents/worktrees/<repoName>/<leaf>`,
|
|
5307
|
-
* the leaf being the branch, else `detached-<commit
|
|
5308
|
-
* `taken` holds it), `<leaf>-2`, `-3`, …
|
|
5309
|
-
*
|
|
5715
|
+
* the leaf being the branch, else `detached-<commit>`, with every run of characters outside
|
|
5716
|
+
* `[A-Za-z0-9._-]` made `-`; when that exists (or `taken` holds it), `<leaf>-2`, `-3`, … A leaf
|
|
5717
|
+
* over RETAINED_LEAF_MAX is cut to fit, its trailing `-` trimmed, and followed by `-` and 6 hex
|
|
5718
|
+
* of the SHA-256 of the full branch name: deterministic, readable, and one per branch. The
|
|
5719
|
+
* character class keeps the leaf ASCII, so its length in characters is its length in bytes;
|
|
5720
|
+
* widen the class and the bound must measure bytes. The one naming rule of work/ and of the
|
|
5721
|
+
* extra trees, the plan's `movedTo` and the apply's alike. Creates nothing. */
|
|
5310
5722
|
function retainedWorktreeDest(workspace, repo, branch, commit, taken = new Set()) {
|
|
5311
5723
|
const repoName = basename(realPathOrNearest(repo)).replace(/\.git$/, "") || "repo";
|
|
5312
|
-
const
|
|
5313
|
-
const
|
|
5314
|
-
|
|
5315
|
-
|
|
5724
|
+
const name = branch ?? `detached-${(commit || "unknown").slice(0, 12)}`;
|
|
5725
|
+
const flat = name.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "work";
|
|
5726
|
+
const hash = () => createHash("sha256").update(name, "utf8").digest("hex").slice(0, 6);
|
|
5727
|
+
/** The leaf in `room` bytes: as it is when it fits, else cut and hashed. */
|
|
5728
|
+
const fit = (room) => flat.length <= room ? flat : `${flat.slice(0, room - 7).replace(/-+$/, "")}-${hash()}`;
|
|
5729
|
+
const retainedRoot = join(retainedWorktreesRoot(workspace), repoName);
|
|
5730
|
+
let dest = join(retainedRoot, fit(RETAINED_LEAF_MAX));
|
|
5731
|
+
// The 8 bytes kept for `-N` hold `-2` to `-9999999`; a longer suffix takes its extra bytes from
|
|
5732
|
+
// the leaf's readable part, never its hash, so a leaf with its suffix never passes
|
|
5733
|
+
// RETAINED_LEAF_MAX + 8.
|
|
5734
|
+
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}`);
|
|
5316
5735
|
taken.add(dest);
|
|
5317
5736
|
return dest;
|
|
5318
5737
|
}
|
|
@@ -5360,30 +5779,31 @@ function unionNotCopied(...lists) {
|
|
|
5360
5779
|
return [...byPath.values()].sort((a, b) => byCodeUnit(a.path, b.path));
|
|
5361
5780
|
}
|
|
5362
5781
|
function retirementBaselineValid(baseline, home) {
|
|
5363
|
-
return baseline?.version === RETIRE_BASELINE_VERSION && baseline
|
|
5782
|
+
return baseline?.version === RETIRE_BASELINE_VERSION && receiptRecordsHome(baseline, canonicalHomePath(home));
|
|
5364
5783
|
}
|
|
5365
5784
|
/** What a retire plan may say about recovery without hashing anything: where a
|
|
5366
5785
|
* recovery would be written, and the home entries the spawn baseline declares
|
|
5367
5786
|
* as not copied (none without a valid baseline). */
|
|
5368
5787
|
export function retirementRecoveryFacts(home) {
|
|
5369
|
-
const baseline = readJsonOrUndefined(
|
|
5370
|
-
return { recoveryRoot:
|
|
5788
|
+
const baseline = readJsonOrUndefined(findRetirementBaseline(home));
|
|
5789
|
+
return { recoveryRoot: retirementRecoveryRoot(dirname(home)), disposableHome: retirementBaselineValid(baseline, home) ? baselineDisposableHome(baseline) : [] };
|
|
5371
5790
|
}
|
|
5372
5791
|
function writeRetirementBaseline(home, work, mode, capabilities, runtime, { exclusive = false, incarnationId, executionBinding } = {}) {
|
|
5373
5792
|
if (mode === "directory") assertDirectoryRoots(home);
|
|
5374
5793
|
const isWorktree = mode === "worktree";
|
|
5375
|
-
const
|
|
5794
|
+
const statusBytes = isWorktree && existsSync(work) ? worktreeStatusBytes(work) : Buffer.alloc(0);
|
|
5376
5795
|
const disposableReceipts = isWorktree ? retirementDisposableRoots(work, capabilities) : [];
|
|
5377
5796
|
const disposableHome = retirementDisposableHome(capabilities);
|
|
5378
5797
|
const baseline = {
|
|
5379
5798
|
version: RETIRE_BASELINE_VERSION,
|
|
5799
|
+
digestVersion: BASELINE_DIGEST_VERSION,
|
|
5380
5800
|
...(incarnationId ? { incarnationId, executionBinding } : {}),
|
|
5381
5801
|
...(mode === "directory" ? { directoryWork: true, directoryRoots: { home: directoryIdentity(home), work: directoryIdentity(work) } } : {}),
|
|
5382
|
-
home:
|
|
5383
|
-
homeFingerprint:
|
|
5802
|
+
home: canonicalHomePath(home),
|
|
5803
|
+
homeFingerprint: storedTreeDigest(home, BASELINE_DIGEST_VERSION, { excludeRoot: resolveHomeExclusions(home, disposableHome).excludeRoot, instanceHome: true }),
|
|
5384
5804
|
disposableReceipts,
|
|
5385
5805
|
disposableHome,
|
|
5386
|
-
generatedWorkFingerprint: isWorktree ?
|
|
5806
|
+
generatedWorkFingerprint: isWorktree ? generatedWorkDigest(work, statusBytes, disposableReceipts.map((r) => r.root)) : undefined,
|
|
5387
5807
|
runtime: {
|
|
5388
5808
|
launched: runtime?.launched === true,
|
|
5389
5809
|
...(runtime?.tmux ? { tmux: { session: runtime.tmux.session, window: runtime.tmux.window, ...(runtime.tmux.socket ? { socket: resolve(runtime.tmux.socket) } : {}) } } : {}),
|
|
@@ -5394,17 +5814,24 @@ function writeRetirementBaseline(home, work, mode, capabilities, runtime, { excl
|
|
|
5394
5814
|
writeFileSync(path, JSON.stringify(baseline, null, 2) + "\n", { mode: 0o600, ...(exclusive ? { flag: "wx" } : {}) });
|
|
5395
5815
|
}
|
|
5396
5816
|
|
|
5817
|
+
/** The repositories a recovery rebuilds from a clone, under a worktree at
|
|
5818
|
+
* any depth → their paths, as bytes: each directory (never a link to one)
|
|
5819
|
+
* whose `.git` stat finds, a link to one followed. Names are read as bytes,
|
|
5820
|
+
* so a directory whose name is not UTF-8 is found, not missed. The walk does
|
|
5821
|
+
* not go into a repository it found: no path is under another, and a
|
|
5822
|
+
* repository inside one is no root of its own (it comes along as its
|
|
5823
|
+
* parent's plain files, its `.git` included: repositoriesUnder's `inner`). */
|
|
5397
5824
|
function nestedGitRoots(root) {
|
|
5398
5825
|
const out = [];
|
|
5399
5826
|
const walk = (dir) => {
|
|
5400
|
-
for (const e of
|
|
5401
|
-
if (!e.isDirectory() || e.isSymbolicLink
|
|
5402
|
-
const path =
|
|
5403
|
-
if (existsSync(
|
|
5827
|
+
for (const e of entriesAsBytes(dir)) {
|
|
5828
|
+
if (!e.isDirectory() || e.isSymbolicLink()) continue;
|
|
5829
|
+
const path = joinBytes(dir, e.name);
|
|
5830
|
+
if (existsSync(joinBytes(path, GIT_NAME))) { out.push(path); continue; }
|
|
5404
5831
|
walk(path);
|
|
5405
5832
|
}
|
|
5406
5833
|
};
|
|
5407
|
-
walk(root);
|
|
5834
|
+
walk(pathBytes(root));
|
|
5408
5835
|
return out;
|
|
5409
5836
|
}
|
|
5410
5837
|
|
|
@@ -5416,7 +5843,7 @@ function nestedGitRoots(root) {
|
|
|
5416
5843
|
* whether it could be shown gone. */
|
|
5417
5844
|
function recordedBranchExists(repo, branch) {
|
|
5418
5845
|
if (!repo || !branch) return true;
|
|
5419
|
-
const r =
|
|
5846
|
+
const r = retireGitProbe(repo, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]);
|
|
5420
5847
|
return !r.error && r.status === 0;
|
|
5421
5848
|
}
|
|
5422
5849
|
|
|
@@ -5431,7 +5858,7 @@ function readJsonOrUndefined(path) { try { return JSON.parse(readFileSync(path,
|
|
|
5431
5858
|
/** Refuse any session operation on a home opened in Herdr, from its files as they are (either may be
|
|
5432
5859
|
* missing or unreadable): before any receipt validation, so the refusal is never an endpoint error. */
|
|
5433
5860
|
function refuseHerdrHome(home) {
|
|
5434
|
-
if (recordsHerdr(readJsonOrUndefined(join(home, "instance.json")), readJsonOrUndefined(
|
|
5861
|
+
if (recordsHerdr(readJsonOrUndefined(join(home, "instance.json")), readJsonOrUndefined(findRetirementBaseline(home)))) throw herdrInstanceRemoved(basename(home));
|
|
5435
5862
|
}
|
|
5436
5863
|
|
|
5437
5864
|
function runtimeAuthorityOf(baseline) {
|
|
@@ -5456,10 +5883,13 @@ function launchStateAgrees(meta, authority) {
|
|
|
5456
5883
|
["blocked", "incomplete"].includes(meta.launchPrompts?.status) && tmuxEndpointAgrees(meta, authority));
|
|
5457
5884
|
}
|
|
5458
5885
|
|
|
5459
|
-
/** The refusal for a home whose session receipt
|
|
5460
|
-
*
|
|
5461
|
-
|
|
5462
|
-
|
|
5886
|
+
/** The refusal for a home whose session receipt is at neither key its path gives (findRetirementBaseline):
|
|
5887
|
+
* the canonical one, and the one an earlier kernel used for this spelling when that differs. The
|
|
5888
|
+
* receipt is keyed by the home's path, so a moved deployment looks elsewhere. */
|
|
5889
|
+
function missingSessionReceipt(home) {
|
|
5890
|
+
const canonical = retirementBaselinePath(home), legacy = legacyRetirementBaselinePath(home);
|
|
5891
|
+
const where = legacy === canonical ? canonical : `${canonical} (nor at ${legacy}, where a kernel before 0.49.0 kept it for this spelling)`;
|
|
5892
|
+
return oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `no session receipt for ${home} at ${where}. First address the home exactly as \`oats status\` prints it (a deployment directory moved since spawn looks for the receipt elsewhere, and so does a letter-case spelling other than the spawn's, for a home spawned before 0.49.0). Otherwise the home was copied, the .oats-retirement beside it was removed, or its creation did not finish: stop its session yourself if one runs, then \`oats retire ${basename(home)} --plan\` and \`oats retire ${basename(home)}\` (work is preserved), and respawn.`);
|
|
5463
5893
|
}
|
|
5464
5894
|
|
|
5465
5895
|
/** Session control uses the independent endpoint receipt. */
|
|
@@ -5467,16 +5897,16 @@ function instanceSessionTarget(home) {
|
|
|
5467
5897
|
if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session needs an absolute instance home");
|
|
5468
5898
|
home = realPathOrNearest(home);
|
|
5469
5899
|
refuseHerdrHome(home);
|
|
5470
|
-
const receiptPath =
|
|
5900
|
+
const receiptPath = findRetirementBaseline(home);
|
|
5471
5901
|
let baseline, meta;
|
|
5472
5902
|
try {
|
|
5473
5903
|
baseline = JSON.parse(readFileSync(receiptPath, "utf8"));
|
|
5474
5904
|
meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8"));
|
|
5475
5905
|
} catch (e) {
|
|
5476
|
-
if (e.code === "ENOENT" && e.path === receiptPath) throw missingSessionReceipt(home
|
|
5906
|
+
if (e.code === "ENOENT" && e.path === receiptPath) throw missingSessionReceipt(home);
|
|
5477
5907
|
throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read session receipt for ${home}: ${e.message}`);
|
|
5478
5908
|
}
|
|
5479
|
-
const authority = baseline.version === RETIRE_BASELINE_VERSION && baseline
|
|
5909
|
+
const authority = baseline.version === RETIRE_BASELINE_VERSION && receiptRecordsHome(baseline, canonicalHomePath(home)) && runtimeAuthorityOf(baseline);
|
|
5480
5910
|
if (!authority) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or invalid for ${home}`);
|
|
5481
5911
|
if (!launchStateAgrees(meta, authority) || (authority.launched && !tmuxEndpointAgrees(meta, authority))) throw oatsError("E_RUNTIME_AUTHORITY_MISMATCH", "instance metadata disagrees with independent session receipt");
|
|
5482
5912
|
return { home, target: authority.launched ? { backend: "tmux", ...authority.tmux } : undefined };
|
|
@@ -5496,21 +5926,104 @@ export function inspectInstanceSession(home) {
|
|
|
5496
5926
|
* fallback shell nor a dead pane. Only such a session can be waiting on a human. */
|
|
5497
5927
|
function harnessRunning(observed) { return observed?.present === true && observed.state !== "shell" && observed.state !== "stopped"; }
|
|
5498
5928
|
|
|
5499
|
-
/**
|
|
5500
|
-
*
|
|
5501
|
-
*
|
|
5502
|
-
*
|
|
5503
|
-
*
|
|
5504
|
-
*
|
|
5505
|
-
function
|
|
5929
|
+
/** How a failed tmux call reads the server it addressed (#624). "gone": no server listens on the
|
|
5930
|
+
* socket (`no server running on`, or a refused connection), which is definitive. "missing-socket":
|
|
5931
|
+
* the socket file is not there (`No such file or directory`). After a reboot the server is gone,
|
|
5932
|
+
* but a tmux server outlives its removed socket file, so that alone establishes nothing: a caller
|
|
5933
|
+
* concludes stopped from it only when no process works in the home (missingSocketUnestablished).
|
|
5934
|
+
* null: anything else. */
|
|
5935
|
+
function tmuxServerAbsence(e) {
|
|
5936
|
+
const text = String(e?.stderr ?? e?.message ?? "");
|
|
5937
|
+
if (/no server running on |(?:error connecting to|failed to connect to) .*Connection refused/i.test(text)) return "gone";
|
|
5938
|
+
if (/(?:error connecting to|failed to connect to) .*No such file or directory/i.test(text)) return "missing-socket";
|
|
5939
|
+
return null;
|
|
5940
|
+
}
|
|
5941
|
+
function tmuxServerLost(e) { return tmuxServerAbsence(e) !== null; }
|
|
5942
|
+
/** tmux's own way back for a server that lost its socket file (tmux(1), `-S`). Named, never performed. */
|
|
5943
|
+
const TMUX_SOCKET_REMEDY = "tmux recreates a removed socket file when its server process receives SIGUSR1";
|
|
5944
|
+
/** Processes as a refusal names them: pid and program, at most five, then how many more. */
|
|
5945
|
+
function namedProcesses(processes) {
|
|
5946
|
+
return `${processes.slice(0, 5).map((p) => `pid ${p.pid} ${p.command}`).join(", ")}${processes.length > 5 ? `, and ${processes.length - 5} more` : ""}`;
|
|
5947
|
+
}
|
|
5948
|
+
/** A missing socket file (`detail`, tmux's words) checked against `scan`, processesInHome's answer
|
|
5949
|
+
* for the home (#624): null when it ran and found no process there, so the server is taken as gone,
|
|
5950
|
+
* as after a reboot; otherwise why the state is not established. Any process working in the home
|
|
5951
|
+
* counts, a person's shell included: the words name it, so the person can act on it. */
|
|
5952
|
+
function missingSocketUnestablished(detail, scan) {
|
|
5953
|
+
if (!scan.ok) return `${detail}; whether a process still works in this home could not be established (${scan.error})`;
|
|
5954
|
+
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}`;
|
|
5955
|
+
return null;
|
|
5956
|
+
}
|
|
5957
|
+
/** Whether this host's /proc can be read: Linux, and this process's own `cwd` link resolves. */
|
|
5958
|
+
function procReadable() {
|
|
5959
|
+
if (process.platform !== "linux") return { ok: false, error: "this host has no /proc to read (it is not Linux)" };
|
|
5960
|
+
try { readlinkSync("/proc/self/cwd"); return { ok: true }; }
|
|
5961
|
+
catch (e) { return { ok: false, error: `/proc/self/cwd cannot be read (${e.code || e.message})` }; }
|
|
5962
|
+
}
|
|
5963
|
+
/** Which process scan this host offers, checked cheaply and without scanning (doctor reports it):
|
|
5964
|
+
* /proc on Linux, else lsof when it is on PATH. → { mechanism: "proc" | "lsof" } | { mechanism: null, error } */
|
|
5965
|
+
export function processScanAvailability() {
|
|
5966
|
+
const proc = procReadable();
|
|
5967
|
+
if (proc.ok) return { mechanism: "proc" };
|
|
5968
|
+
if (process.env.PATH !== undefined && lookupOnPath("lsof", process.env.PATH)) return { mechanism: "lsof" };
|
|
5969
|
+
return { mechanism: null, error: `${proc.error}, and lsof is not on PATH` };
|
|
5970
|
+
}
|
|
5971
|
+
/** Doctor's information line when this host has no process scan (`availability`, from
|
|
5972
|
+
* processScanAvailability); none when it has one. */
|
|
5973
|
+
export function processScanInformation(availability = processScanAvailability()) {
|
|
5974
|
+
if (availability.mechanism) return [];
|
|
5975
|
+
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`];
|
|
5976
|
+
}
|
|
5506
5977
|
/**
|
|
5507
|
-
*
|
|
5508
|
-
* directory
|
|
5509
|
-
*
|
|
5510
|
-
*
|
|
5511
|
-
*
|
|
5978
|
+
* Every live process on the host (other than this one and its direct children) with its working
|
|
5979
|
+
* directory, from one scan: /proc on Linux (`io.procRoot` names another root), else one `lsof -a -d
|
|
5980
|
+
* cwd` listing; an injected `io.exec` stands in for the host's commands, so it is lsof's. Each cwd
|
|
5981
|
+
* is kept in its on-disk spelling (canonicalHomePath); one the kernel reports deleted (`<path>
|
|
5982
|
+
* (deleted)`) is kept as both spellings. A process this user may not inspect (another user's, or a
|
|
5983
|
+
* non-dumpable one) is not seen by either mechanism.
|
|
5984
|
+
* → { ok: true, processes: [{pid, command, cwds}] } | { ok: false, error }
|
|
5512
5985
|
*/
|
|
5513
|
-
|
|
5986
|
+
function hostProcesses(io) {
|
|
5987
|
+
const rows = typeof io?.procRoot === "string" ? procRows(io.procRoot)
|
|
5988
|
+
: !io?.exec && procReadable().ok ? procRows("/proc")
|
|
5989
|
+
: lsofRows(io);
|
|
5990
|
+
if (!rows.ok) return rows;
|
|
5991
|
+
const processes = [];
|
|
5992
|
+
for (const { pid, ppid, command, cwd } of rows.rows) {
|
|
5993
|
+
if (!pid || pid === process.pid || ppid === process.pid || typeof cwd !== "string") continue;
|
|
5994
|
+
const spellings = cwd.endsWith(" (deleted)") ? [cwd, cwd.slice(0, -" (deleted)".length)] : [cwd];
|
|
5995
|
+
processes.push({ pid, command: command ?? "?", cwds: spellings.map((p) => canonicalHomePath(p)) });
|
|
5996
|
+
}
|
|
5997
|
+
return { ok: true, processes };
|
|
5998
|
+
}
|
|
5999
|
+
/** The processes of a hostProcesses listing that work in `home`, compared in its on-disk spelling. */
|
|
6000
|
+
function processesWorkingIn(processes, home) {
|
|
6001
|
+
const realHome = canonicalHomePath(home);
|
|
6002
|
+
return processes.filter((p) => p.cwds.some((cwd) => cwd === realHome || cwd.startsWith(`${realHome}/`))).map(({ pid, command }) => ({ pid, command }));
|
|
6003
|
+
}
|
|
6004
|
+
/** /proc read as a scan: each numeric entry's `cwd` link, `comm` and `stat` (its ppid is the second
|
|
6005
|
+
* field after the last `)`, which ends the command). A pid that cannot be read (it ended meanwhile,
|
|
6006
|
+
* this user may not inspect it, or any other failure on that one pid) is not seen. A root that
|
|
6007
|
+
* cannot be listed, or one that lists no readable process, is a failed scan, never an empty one. */
|
|
6008
|
+
function procRows(root) {
|
|
6009
|
+
let names;
|
|
6010
|
+
try { names = readdirSync(root); }
|
|
6011
|
+
catch (e) { return { ok: false, error: `${root} cannot be read (${e.code || e.message})` }; }
|
|
6012
|
+
const rows = [];
|
|
6013
|
+
for (const name of names) {
|
|
6014
|
+
if (!/^\d+$/.test(name)) continue;
|
|
6015
|
+
try {
|
|
6016
|
+
const cwd = readlinkSync(join(root, name, "cwd"));
|
|
6017
|
+
const command = readFileSync(join(root, name, "comm"), "utf8").replace(/\n$/, "");
|
|
6018
|
+
const stat = readFileSync(join(root, name, "stat"), "utf8");
|
|
6019
|
+
rows.push({ pid: Number(name), ppid: Number(stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/)[1]), command, cwd });
|
|
6020
|
+
} catch { /* not seen */ }
|
|
6021
|
+
}
|
|
6022
|
+
// A real /proc always lists at least this process.
|
|
6023
|
+
if (!rows.length) return { ok: false, error: `${root} listed no process` };
|
|
6024
|
+
return { ok: true, rows };
|
|
6025
|
+
}
|
|
6026
|
+
function lsofRows(io) {
|
|
5514
6027
|
let out;
|
|
5515
6028
|
try { out = (io?.exec || execFileSync)("lsof", ["-a", "-d", "cwd", "-F", "pRcn", "-w"], { encoding: "utf8", timeout: 20000, maxBuffer: 16 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }); }
|
|
5516
6029
|
catch (e) {
|
|
@@ -5521,7 +6034,7 @@ export function processesInHome(home, io) {
|
|
|
5521
6034
|
// listing.
|
|
5522
6035
|
const completed = e?.status === 1 && e.signal == null && e.code === undefined;
|
|
5523
6036
|
if (completed && typeof e.stdout === "string") out = e.stdout;
|
|
5524
|
-
else return { ok: false, error: e?.code === "ENOENT" ? "lsof is not on PATH"
|
|
6037
|
+
else return { ok: false, error: e?.code === "ENOENT" ? "lsof is not on PATH; install lsof"
|
|
5525
6038
|
: e?.code === "ETIMEDOUT" ? "lsof timed out"
|
|
5526
6039
|
: e?.code === "ENOBUFS" ? "lsof printed more output than the scan reads"
|
|
5527
6040
|
: e?.signal ? `lsof was ended by ${e.signal}`
|
|
@@ -5529,20 +6042,27 @@ export function processesInHome(home, io) {
|
|
|
5529
6042
|
}
|
|
5530
6043
|
// A listing holds at least one process (lsof and its caller are always in it), whichever exit it came with.
|
|
5531
6044
|
if (!/^p\d+$/m.test(String(out))) return { ok: false, error: "lsof listed no process" };
|
|
5532
|
-
const
|
|
5533
|
-
const processes = [];
|
|
6045
|
+
const rows = [];
|
|
5534
6046
|
let cur = {};
|
|
5535
6047
|
for (const line of String(out).split("\n")) {
|
|
5536
6048
|
const tag = line[0], value = line.slice(1);
|
|
5537
|
-
if (tag === "p") cur = { pid: Number(value) };
|
|
6049
|
+
if (tag === "p") { cur = { pid: Number(value) }; rows.push(cur); }
|
|
5538
6050
|
else if (tag === "R") cur.ppid = Number(value);
|
|
5539
6051
|
else if (tag === "c") cur.command = value;
|
|
5540
|
-
else if (tag === "n"
|
|
5541
|
-
const cwd = realPathOrNearest(value);
|
|
5542
|
-
if (cwd === realHome || cwd.startsWith(`${realHome}/`)) processes.push({ pid: cur.pid, command: cur.command ?? "?" });
|
|
5543
|
-
}
|
|
6052
|
+
else if (tag === "n") cur.cwd = value;
|
|
5544
6053
|
}
|
|
5545
|
-
return { ok: true,
|
|
6054
|
+
return { ok: true, rows };
|
|
6055
|
+
}
|
|
6056
|
+
/**
|
|
6057
|
+
* The live processes (other than this one and its direct children) whose working directory is
|
|
6058
|
+
* inside `home`, from one scan of the host (hostProcesses: /proc on Linux, else lsof). A pid and a
|
|
6059
|
+
* program name, never an argument list.
|
|
6060
|
+
* → { ok: true, processes: [{pid, command}] } | { ok: false, error } (the scan could not run, did
|
|
6061
|
+
* not complete or listed no process: a caller must treat that as unknown, never as none).
|
|
6062
|
+
*/
|
|
6063
|
+
export function processesInHome(home, io) {
|
|
6064
|
+
const scan = hostProcesses(io);
|
|
6065
|
+
return scan.ok ? { ok: true, processes: processesWorkingIn(scan.processes, home) } : scan;
|
|
5546
6066
|
}
|
|
5547
6067
|
|
|
5548
6068
|
/**
|
|
@@ -5563,7 +6083,7 @@ export function observeSessionWithoutReceipt(home, meta, io) {
|
|
|
5563
6083
|
if (!recorded.absent) return recorded;
|
|
5564
6084
|
const scan = processesInHome(home, io);
|
|
5565
6085
|
if (!scan.ok) return { absent: false, backend: recorded.backend, note: `could not scan for a process working in this home (${scan.error})` };
|
|
5566
|
-
if (scan.processes.length) return { absent: false, backend: recorded.backend, note: `a process works in this home (${scan.processes
|
|
6086
|
+
if (scan.processes.length) return { absent: false, backend: recorded.backend, note: `a process works in this home (${namedProcesses(scan.processes)}); stop it, then retire` };
|
|
5567
6087
|
return recorded;
|
|
5568
6088
|
}
|
|
5569
6089
|
function recordedSessionAbsence(home, meta, io) {
|
|
@@ -5580,11 +6100,19 @@ function recordedSessionAbsence(home, meta, io) {
|
|
|
5580
6100
|
return { absent: false, backend: "tmux", note: `tmux could not list ${tmux.socket}: ${String(e.stderr ?? e.message ?? "").trim() || "tmux failed"}` };
|
|
5581
6101
|
}
|
|
5582
6102
|
if (rows.some(([s, w]) => s === tmux.session && w === tmux.window)) return { absent: false, backend: "tmux", note: `the recorded window ${where} is still present` };
|
|
5583
|
-
|
|
5584
|
-
const
|
|
6103
|
+
// tmux reports each pane's cwd in its on-disk spelling: the home is compared in it too.
|
|
6104
|
+
const realHome = canonicalHomePath(home);
|
|
6105
|
+
const inHome = rows.find(([, , cwd]) => { const p = cwd ? canonicalHomePath(cwd) : ""; return p === realHome || p.startsWith(`${realHome}/`); });
|
|
5585
6106
|
if (inHome) return { absent: false, backend: "tmux", note: `a tmux pane (${inHome[0]}:${inHome[1]}) on ${tmux.socket} works in this home` };
|
|
5586
6107
|
return { absent: true, backend: "tmux", note: `no session receipt (a home from before 0.25.9); the recorded window ${where} is gone` };
|
|
5587
6108
|
}
|
|
6109
|
+
/** K3: quiesce one instance's session and RETAIN everything else — home,
|
|
6110
|
+
* worktree, transcript, launch configuration — so `restart` can bring it back.
|
|
6111
|
+
* Exactly restart's stop half under the same independent endpoint authority
|
|
6112
|
+
* (`instanceSessionTarget`), bounded and never escalated: a harness still
|
|
6113
|
+
* there after the grace is reported still running, nothing is killed harder.
|
|
6114
|
+
* A no-launch or already-idle instance is a no-op that says so. A missing socket
|
|
6115
|
+
* file is idle only when no process works in the home (#624). */
|
|
5588
6116
|
export function stopInstanceSession(home, o = {}) {
|
|
5589
6117
|
if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session stop needs an absolute instance home");
|
|
5590
6118
|
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");
|
|
@@ -5594,7 +6122,12 @@ export function stopInstanceSession(home, o = {}) {
|
|
|
5594
6122
|
if (!s.target) return { home: s.home, backend: null, stopped: false, alreadyIdle: true, state: "not-launched", receipt: null };
|
|
5595
6123
|
let before;
|
|
5596
6124
|
try { before = inspectSessionTarget(s.target); }
|
|
5597
|
-
catch (e) {
|
|
6125
|
+
catch (e) {
|
|
6126
|
+
const absence = tmuxServerAbsence(e);
|
|
6127
|
+
const why = absence === "missing-socket" ? missingSocketUnestablished(tmuxFailure(e, e.message), processesInHome(realHome, o.io)) : null;
|
|
6128
|
+
if (absence && !why) before = { present: false, state: "stopped" };
|
|
6129
|
+
else throw oatsError("E_SESSION_UNAVAILABLE", `cannot establish whether ${basename(realHome)} is running, so nothing was stopped: ${why ?? e.message}`);
|
|
6130
|
+
}
|
|
5598
6131
|
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 };
|
|
5599
6132
|
const receipt = stopHarness(s.target, { graceMs: o.graceMs ?? 20000, kill: o.io?.kill, sleep: o.io?.sleep });
|
|
5600
6133
|
writeJsonAtomic(join(realHome, ".oats-stop.json"), { instance: basename(realHome), at: new Date().toISOString(), stop: receipt, retained: ["home", "work", "transcript", "launch"] });
|
|
@@ -6001,7 +6534,16 @@ export function startInstanceSession(home, o = {}) {
|
|
|
6001
6534
|
// spawned records no modules, and there is no scope configuration left to
|
|
6002
6535
|
// re-resolve it against. Retire still works on it.
|
|
6003
6536
|
if (!isWorkspaceHome(readMeta())) throw preWorkspaceHome(realHome, "nothing was started");
|
|
6004
|
-
|
|
6537
|
+
// A missing socket file is a stopped server only when no process works in this home (#624): its
|
|
6538
|
+
// check, for a recorded session and for the OATS server lookup. A failed read of a recorded session
|
|
6539
|
+
// is `{ stopped: true }` when its server is gone (or its socket file is missing and that check
|
|
6540
|
+
// passes), else `{ stopped: false, why }`: the check's reason, or null for another failure.
|
|
6541
|
+
const missingSocket = (detail) => missingSocketUnestablished(detail, processesInHome(realHome, rawIo));
|
|
6542
|
+
const lostServer = (e) => {
|
|
6543
|
+
const absence = tmuxServerAbsence(e);
|
|
6544
|
+
const why = absence === "missing-socket" ? missingSocket(tmuxFailure(e, e.message)) : null;
|
|
6545
|
+
return absence && !why ? { stopped: true } : { stopped: false, why };
|
|
6546
|
+
};
|
|
6005
6547
|
const launchFailure = (error) => {
|
|
6006
6548
|
// execFileSync errors embed argv (including capability environment) in
|
|
6007
6549
|
// message; backend stderr can echo it too. Neither belongs in the API.
|
|
@@ -6014,13 +6556,13 @@ export function startInstanceSession(home, o = {}) {
|
|
|
6014
6556
|
// pending receipt exists for.
|
|
6015
6557
|
const record = (meta, { id, target, model, command, startedAt, reused, launch, harness: newHarness, yolo: newYolo, stop, nativeRecordId, hookMeta, modelFrom, launchFrom, launchAt, launchDeclared, launchPrompts, launchPromptTarget }, clearPending = true) => {
|
|
6016
6558
|
checkRoots();
|
|
6017
|
-
const baselinePath =
|
|
6559
|
+
const baselinePath = findRetirementBaseline(realHome);
|
|
6018
6560
|
let baseline;
|
|
6019
6561
|
try { baseline = JSON.parse(readFileSync(baselinePath, "utf8")); } catch (e) {
|
|
6020
|
-
if (e.code === "ENOENT") throw missingSessionReceipt(realHome
|
|
6562
|
+
if (e.code === "ENOENT") throw missingSessionReceipt(realHome);
|
|
6021
6563
|
throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or unreadable for ${realHome}: ${e.message}`);
|
|
6022
6564
|
}
|
|
6023
|
-
if (baseline.version !== RETIRE_BASELINE_VERSION || baseline
|
|
6565
|
+
if (baseline.version !== RETIRE_BASELINE_VERSION || !receiptRecordsHome(baseline, canonicalHomePath(realHome)) || !runtimeAuthorityOf(baseline)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is invalid for ${realHome}`);
|
|
6024
6566
|
baseline.runtime = { launched: true, tmux: { session: target.session, window: target.window, socket: resolve(target.socket) } };
|
|
6025
6567
|
writeJsonAtomic(baselinePath, baseline, 0o600);
|
|
6026
6568
|
if (o.io?.failBeforeMetadataWrite && reused !== "adopted") throw new Error("injected metadata write failure"); // the write after THIS start's allocation
|
|
@@ -6077,8 +6619,9 @@ export function startInstanceSession(home, o = {}) {
|
|
|
6077
6619
|
checkRoots();
|
|
6078
6620
|
try { st = inspectSessionTarget(pending.target, o.io); }
|
|
6079
6621
|
catch (e) {
|
|
6080
|
-
|
|
6081
|
-
|
|
6622
|
+
const lost = lostServer(e);
|
|
6623
|
+
if (lost.stopped) st = { present: false, state: "stopped" };
|
|
6624
|
+
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`);
|
|
6082
6625
|
}
|
|
6083
6626
|
// A launch may still consist entirely of shells (startup files, a
|
|
6084
6627
|
// shell-script harness). Only its own completion marker proves this
|
|
@@ -6154,18 +6697,19 @@ export function startInstanceSession(home, o = {}) {
|
|
|
6154
6697
|
const planSession = receipt.target?.session || meta.tmux?.session || DEFAULT_TMUX_SESSION;
|
|
6155
6698
|
let sessionPlanRead;
|
|
6156
6699
|
const sessionPlan = () => {
|
|
6157
|
-
if (!sessionPlanRead) { try { sessionPlanRead = { plan: planOatsTmuxSession(planSession, o.io) }; } catch (e) { sessionPlanRead = { error: e }; } }
|
|
6700
|
+
if (!sessionPlanRead) { try { sessionPlanRead = { plan: planOatsTmuxSession(planSession, o.io, { missingSocket }) }; } catch (e) { sessionPlanRead = { error: e }; } }
|
|
6158
6701
|
if (sessionPlanRead.error) throw sessionPlanRead.error;
|
|
6159
6702
|
return sessionPlanRead.plan;
|
|
6160
6703
|
};
|
|
6161
6704
|
// The recorded target, observed once: by the plan's lookup, which must know whether the pane will
|
|
6162
|
-
// be reused before it chooses where to look, or by the gate below. A lost server is a stopped one
|
|
6163
|
-
// any other failure is the gate's refusal (E_SESSION_UNKNOWN), and the lookup does
|
|
6705
|
+
// be reused before it chooses where to look, or by the gate below. A lost server is a stopped one
|
|
6706
|
+
// (lostServer); any other failure is the gate's refusal (E_SESSION_UNKNOWN), and the lookup does
|
|
6707
|
+
// not decide it.
|
|
6164
6708
|
let recordedRead;
|
|
6165
6709
|
const recordedState = () => {
|
|
6166
6710
|
if (!recordedRead) {
|
|
6167
6711
|
try { recordedRead = { state: receipt.target ? inspectSessionTarget(receipt.target, o.io) : { present: false, state: "not-launched" } }; }
|
|
6168
|
-
catch (e) {
|
|
6712
|
+
catch (e) { const lost = lostServer(e); recordedRead = lost.stopped ? { state: { present: false, state: "stopped" } } : { error: lost.why ? new Error(lost.why) : e }; }
|
|
6169
6713
|
}
|
|
6170
6714
|
return recordedRead;
|
|
6171
6715
|
};
|
|
@@ -6195,7 +6739,7 @@ export function startInstanceSession(home, o = {}) {
|
|
|
6195
6739
|
const recorded = recordedState();
|
|
6196
6740
|
if (reusable(recorded.state)) return panePath(receipt.target.socket, receipt.target.session, o.io, realHome);
|
|
6197
6741
|
if (recorded.error) return undefined; // the gate refuses below; the lookup does not decide it
|
|
6198
|
-
const preview = planOatsTmuxSession(planSession, o.io, { preview: true });
|
|
6742
|
+
const preview = planOatsTmuxSession(planSession, o.io, { preview: true, missingSocket });
|
|
6199
6743
|
if (!preview || preview.server) return expectedPanePath(preview, planSession, o.io, realHome);
|
|
6200
6744
|
try { return expectedPanePath(sessionPlan(), planSession, o.io, realHome); } catch (e) { if (oatsCoded(e)) return undefined; throw e; }
|
|
6201
6745
|
};
|
|
@@ -6304,7 +6848,12 @@ export function startInstanceSession(home, o = {}) {
|
|
|
6304
6848
|
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);
|
|
6305
6849
|
appendEvent(realHome, { kind: stopReceipt.exited ? "restarted" : "stop-refused", data: { phase: "restart-stop", signal: stopReceipt.signal, waitedMs: stopReceipt.waitedMs, stillRunning: stopReceipt.stillRunning ?? [] } });
|
|
6306
6850
|
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")}`);
|
|
6307
|
-
try { state = inspectSessionTarget(target, o.io); }
|
|
6851
|
+
try { state = inspectSessionTarget(target, o.io); }
|
|
6852
|
+
catch (e) {
|
|
6853
|
+
const lost = lostServer(e);
|
|
6854
|
+
if (lost.stopped) state = { present: false, state: "stopped" };
|
|
6855
|
+
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)}`);
|
|
6856
|
+
}
|
|
6308
6857
|
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`);
|
|
6309
6858
|
}
|
|
6310
6859
|
// The kernel that launches the harness is the one the agent's plain `oats` runs.
|
|
@@ -6352,7 +6901,7 @@ export function startInstanceSession(home, o = {}) {
|
|
|
6352
6901
|
// A replacement window (never launched, recorded window gone, recorded server gone) is created
|
|
6353
6902
|
// on the OATS server, wherever the home was recorded: one socket from here to the record.
|
|
6354
6903
|
const recordedSocket = socket ? resolve(socket) : null;
|
|
6355
|
-
socket = ensureOatsTmuxSession(session, hq, o.io, tmuxSessionPlan);
|
|
6904
|
+
socket = ensureOatsTmuxSession(session, hq, o.io, tmuxSessionPlan, missingSocket);
|
|
6356
6905
|
if (lookAgain(() => panePath(socket, session, o.io, realHome))) { planExtra.launch = launchPlan.recipe; windowCmd = windowCommand(); }
|
|
6357
6906
|
let names;
|
|
6358
6907
|
try { names = tmuxOn(socket, ["list-windows", "-t", `=${session}`, "-F", "#{window_name}"], o.io).split("\n").filter(Boolean); }
|
|
@@ -6431,7 +6980,7 @@ export function startInstanceSession(home, o = {}) {
|
|
|
6431
6980
|
* decision: not provable. */
|
|
6432
6981
|
function inspectGit(repo, args, { absent = false, env } = {}) {
|
|
6433
6982
|
try {
|
|
6434
|
-
return
|
|
6983
|
+
return retireGit(repo, args, { env }).toString("latin1");
|
|
6435
6984
|
} catch (e) {
|
|
6436
6985
|
const detail = String(e.stderr ?? "").trim();
|
|
6437
6986
|
if (absent && e.status === 1 && !detail) return null;
|
|
@@ -6453,23 +7002,20 @@ function inspectedEntryExists(path) {
|
|
|
6453
7002
|
/** How the recovery copier resolves what it reads from a repository, read by
|
|
6454
7003
|
* the copier and by the comparison alike (repositoryGitState), so that the
|
|
6455
7004
|
* comparison holds the files the copy carries, found where the copy finds
|
|
6456
|
-
* them. Git's answer decoded as UTF-8
|
|
6457
|
-
* ends: a path that ends in white space is
|
|
6458
|
-
*
|
|
6459
|
-
*
|
|
7005
|
+
* them. Git's answer decoded as UTF-8, exactly as Git printed it but for the
|
|
7006
|
+
* one line feed that ends it: a path that begins or ends in white space is
|
|
7007
|
+
* the path Git reads, so the copier reads the file Git reads
|
|
7008
|
+
* (awebai/oats#647).
|
|
6460
7009
|
* A worktree whose `core.worktree` (per-worktree configuration) names a
|
|
6461
|
-
* directory other than `<home>/work`
|
|
6462
|
-
*
|
|
6463
|
-
|
|
6464
|
-
* resolves the excludes base the copier's way for it all the same; no test
|
|
6465
|
-
* pins it. */
|
|
6466
|
-
const copierGitText = (repo, args) => execFileSync("git", ["-C", repo, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER }).trim();
|
|
7010
|
+
* directory other than `<home>/work` never gets here: each inspection
|
|
7011
|
+
* refuses it first (assertWorktreeTopLevel, awebai/oats#648). */
|
|
7012
|
+
const copierGitText = (repo, args) => retireGit(repo, args, { encoding: "utf8" }).replace(/\n$/, "");
|
|
6467
7013
|
/** The Git directory the copier copies the index and the operation entries from. */
|
|
6468
7014
|
const copierGitDir = (repo) => copierGitText(repo, ["rev-parse", "--absolute-git-dir"]);
|
|
6469
7015
|
/** The common directory the copier reads info/exclude, info/attributes and the stash's log from. */
|
|
6470
7016
|
const copierCommonDir = (repo) => copierGitText(repo, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
|
|
6471
7017
|
/** The file the copier reads for core.excludesFile; null when it reads none:
|
|
6472
|
-
* the value is unset, cannot be read
|
|
7018
|
+
* the value is unset, empty or cannot be read. */
|
|
6473
7019
|
function copierExcludesFile(repo) {
|
|
6474
7020
|
let value = "";
|
|
6475
7021
|
try { value = copierGitText(repo, ["config", "--path", "--get", "core.excludesFile"]); } catch { /* unset: Git's default applies to both repositories alike */ }
|
|
@@ -6585,9 +7131,8 @@ function repositoryGitState(repo, { status, cloneSource } = {}) {
|
|
|
6585
7131
|
status: (status ?? worktreeStatusBytes(repo)).toString("latin1"),
|
|
6586
7132
|
head: head.ref === null ? null : head.ref.toString("latin1"),
|
|
6587
7133
|
commit: valueOf("rev-parse", "--verify", "--quiet", "HEAD"),
|
|
6588
|
-
// The index the copier copies (copierGitDir),
|
|
6589
|
-
//
|
|
6590
|
-
// the copy carries. One that is not there lists nothing.
|
|
7134
|
+
// The index the copier copies (copierGitDir), named explicitly
|
|
7135
|
+
// (GIT_INDEX_FILE), read as an index. One that is not there lists nothing.
|
|
6591
7136
|
index: inspectGit(repo, ["ls-files", "-s", "-v", "-z"], { env: { GIT_INDEX_FILE: join(copierGit, "index") } }),
|
|
6592
7137
|
resolveUndo: inspectGit(repo, ["ls-files", "--resolve-undo", "-z"], { env: { GIT_INDEX_FILE: join(copierGit, "index") } }),
|
|
6593
7138
|
indexMode: modeOf(join(copierGit, "index")),
|
|
@@ -6610,10 +7155,11 @@ function repositoryGitState(repo, { status, cloneSource } = {}) {
|
|
|
6610
7155
|
* nestedGitRoots, and (`inner`) the repositories inside those. A recovery
|
|
6611
7156
|
* rebuilds a nested repository from a clone; one inside it comes along as
|
|
6612
7157
|
* plain files, its Git directory included, which the copy's verification
|
|
6613
|
-
*
|
|
7158
|
+
* holds as bytes (worktreeGitPaths) and which no read-only Git command can
|
|
7159
|
+
* describe whole.
|
|
6614
7160
|
* A directory whose `.git` cannot be tested (inspectedEntryExists throws),
|
|
6615
7161
|
* or is a dangling symbolic link (a link `stat` cannot follow, which the
|
|
6616
|
-
* copy carries as a link and the
|
|
7162
|
+
* copy carries as a link and the copy's verification holds), is listed
|
|
6617
7163
|
* as { path, unknown: true }: it is not taken for a directory without a
|
|
6618
7164
|
* repository, and not for a repository either. So every directory with a
|
|
6619
7165
|
* `.git` entry of any kind is listed: a directory, a file, a link to
|
|
@@ -6625,17 +7171,19 @@ function repositoriesUnder(work) {
|
|
|
6625
7171
|
try { lstatSync(path); return true; }
|
|
6626
7172
|
catch (e) {
|
|
6627
7173
|
if (e.code === "ENOENT") return false;
|
|
6628
|
-
throw oatsError("E_WORK_INSPECTION_FAILED", `could not inspect ${path}: ${e.message}`);
|
|
7174
|
+
throw oatsError("E_WORK_INSPECTION_FAILED", `could not inspect ${path.toString()}: ${e.message}`);
|
|
6629
7175
|
}
|
|
6630
7176
|
};
|
|
7177
|
+
// Names are read as bytes (`path` is a Buffer), so a directory whose name
|
|
7178
|
+
// is not UTF-8 is walked like any other.
|
|
6631
7179
|
const walk = (dir, inner) => {
|
|
6632
|
-
for (const e of
|
|
6633
|
-
if (!e.isDirectory() || e.isSymbolicLink
|
|
6634
|
-
const path =
|
|
7180
|
+
for (const e of entriesAsBytes(dir)) {
|
|
7181
|
+
if (!e.isDirectory() || e.isSymbolicLink() || e.name.equals(GIT_NAME)) continue;
|
|
7182
|
+
const path = joinBytes(dir, e.name);
|
|
6635
7183
|
let repository = false;
|
|
6636
7184
|
try {
|
|
6637
|
-
repository = inspectedEntryExists(
|
|
6638
|
-
if (!repository && entryIsThere(
|
|
7185
|
+
repository = inspectedEntryExists(joinBytes(path, GIT_NAME));
|
|
7186
|
+
if (!repository && entryIsThere(joinBytes(path, GIT_NAME))) out.push({ path, unknown: true });
|
|
6639
7187
|
} catch (e) {
|
|
6640
7188
|
if (e?.code !== "E_WORK_INSPECTION_FAILED") throw e;
|
|
6641
7189
|
out.push({ path, unknown: true });
|
|
@@ -6644,7 +7192,7 @@ function repositoriesUnder(work) {
|
|
|
6644
7192
|
walk(path, inner || repository);
|
|
6645
7193
|
}
|
|
6646
7194
|
};
|
|
6647
|
-
walk(work, false);
|
|
7195
|
+
walk(pathBytes(work), false);
|
|
6648
7196
|
return out;
|
|
6649
7197
|
}
|
|
6650
7198
|
/** The work state of a worktree instance, without the bytes of its files: the
|
|
@@ -6655,12 +7203,28 @@ function repositoriesUnder(work) {
|
|
|
6655
7203
|
function worktreeGitState(work, status, cloneSource) { // `status`: the worktree's status bytes
|
|
6656
7204
|
return JSON.stringify({ worktree: repositoryGitState(work, { status, cloneSource }) });
|
|
6657
7205
|
}
|
|
6658
|
-
/** The
|
|
6659
|
-
*
|
|
6660
|
-
|
|
7206
|
+
/** The `.git` entries a worktree's bytes leave out, as paths under it in
|
|
7207
|
+
* bytes: the worktree's own, and that of each repository the copier rebuilds
|
|
7208
|
+
* from a clone (nestedGitRoots, materializeNestedRepositories). Exact paths,
|
|
7209
|
+
* never a name: any other entry named `.git` is bytes like any other
|
|
7210
|
+
* (awebai/oats#663), such as a dangling `.git` link, or the `.git` of a
|
|
7211
|
+
* repository inside a nested one, which the copy carries as plain files.
|
|
7212
|
+
* Read from the source and used for the source and its copy alike: a
|
|
7213
|
+
* rebuilt `.git` is a directory in the copy where the source's can be a
|
|
7214
|
+
* file, and the path covers both. */
|
|
7215
|
+
function worktreeGitPaths(work) {
|
|
7216
|
+
const under = pathBytes(work).length + PATH_SEPARATOR_BYTES.length;
|
|
7217
|
+
return [GIT_NAME, ...nestedGitRoots(work).map((root) => joinBytes(root.subarray(under), GIT_NAME))];
|
|
7218
|
+
}
|
|
7219
|
+
/** The bytes of a worktree, its Git directories (`gitPaths`, worktreeGitPaths of
|
|
7220
|
+
* the source) left out, as their exact digest: what a work copy is verified
|
|
7221
|
+
* with, and what proves that the hooks left the files as they were. One full
|
|
7222
|
+
* read. Kept nowhere. */
|
|
7223
|
+
const worktreeBytes = (work, gitPaths = worktreeGitPaths(work)) => exactTreeDigest(work, { excludePaths: gitPaths, children: true });
|
|
6661
7224
|
/** The byte part of an observed worktree's work state, read at most once per
|
|
6662
|
-
* observation and kept on it
|
|
6663
|
-
*
|
|
7225
|
+
* observation and kept on it with the Git directories it leaves out
|
|
7226
|
+
* (`workGitPaths`, for the copy's verification); undefined where the
|
|
7227
|
+
* observation saw no worktree. An inspection never reads it. The retire reads it before it
|
|
6664
7228
|
* writes the pre-hook recovery, the copy's verification uses it (so a pass
|
|
6665
7229
|
* that copies the work costs no extra read), and so does the proof that the
|
|
6666
7230
|
* retire hooks left the work as it was (movedByHooks). */
|
|
@@ -6668,7 +7232,11 @@ function observedWorkBytes(observation) {
|
|
|
6668
7232
|
if (observation.worktree && observation.workBytes === undefined) {
|
|
6669
7233
|
// A read that fails is an inspection that failed, with its code: where the
|
|
6670
7234
|
// retire reads before it writes, nothing else gives the failure one.
|
|
6671
|
-
try {
|
|
7235
|
+
try {
|
|
7236
|
+
const gitPaths = worktreeGitPaths(observation.work);
|
|
7237
|
+
observation.workBytes = worktreeBytes(observation.work, gitPaths);
|
|
7238
|
+
observation.workGitPaths = gitPaths;
|
|
7239
|
+
}
|
|
6672
7240
|
catch (e) {
|
|
6673
7241
|
if (e?.code === "E_WORK_INSPECTION_FAILED") throw e;
|
|
6674
7242
|
throw oatsError("E_WORK_INSPECTION_FAILED", `could not read the worktree at ${observation.work}: ${e.message}`);
|
|
@@ -6680,8 +7248,8 @@ function observedWorkBytes(observation) {
|
|
|
6680
7248
|
* one after → { home, work }. Nothing when the later observation has nothing
|
|
6681
7249
|
* to preserve. The home moved when its exact digest did: that is its bytes,
|
|
6682
7250
|
* `instance.json` as it is. (The stored digest, which a baseline is compared
|
|
6683
|
-
* with, leaves the kernel's own fields of that file out and
|
|
6684
|
-
*
|
|
7251
|
+
* with, leaves the kernel's own fields of that file out and passes over the
|
|
7252
|
+
* kernel's receipts, so it reads alike some homes that differ.)
|
|
6685
7253
|
* The work moved unless it is proven unchanged: a directory by its bytes
|
|
6686
7254
|
* (its exact digest); a worktree by its Git state and, only when that is
|
|
6687
7255
|
* equal, by its bytes. A status text or a class list alone proves nothing: a
|
|
@@ -6698,11 +7266,30 @@ function movedByHooks(before, after) {
|
|
|
6698
7266
|
return { home, work };
|
|
6699
7267
|
}
|
|
6700
7268
|
|
|
6701
|
-
|
|
7269
|
+
/** The check made before a worktree's status is trusted (awebai/oats#648):
|
|
7270
|
+
* Git's top level for the worktree at `work` is `work` itself, both in
|
|
7271
|
+
* their canonical spelling (canonicalHomePath, so a path reached through a
|
|
7272
|
+
* link, or spelled in another letter case on a case-insensitive
|
|
7273
|
+
* filesystem, is the same path). A per-worktree `core.worktree` can name
|
|
7274
|
+
* another directory: Git's status then describes that one, while the
|
|
7275
|
+
* retire reads, copies and removes `work`. That, and a top level that
|
|
7276
|
+
* cannot be read, throws E_WORK_INSPECTION_FAILED with `disclosure` (what
|
|
7277
|
+
* the retire has and has not done by then) as its last sentence. */
|
|
7278
|
+
function assertWorktreeTopLevel(work, disclosure) {
|
|
7279
|
+
const refuse = (why) => oatsError("E_WORK_INSPECTION_FAILED", `${why}, so its Git status describes another directory than the one the retire reads, copies and removes.${disclosure ? ` ${disclosure}.` : ""}`);
|
|
7280
|
+
let top;
|
|
7281
|
+
try { top = retireGit(work, ["rev-parse", "--show-toplevel"]).toString("utf8").replace(/\n$/, ""); }
|
|
7282
|
+
catch (e) { throw refuse(`could not read the top level of the worktree at ${work} (${String(e.stderr ?? e.message ?? "").trim() || "git rev-parse failed"})`); }
|
|
7283
|
+
if (!top || canonicalHomePath(top) !== canonicalHomePath(work)) {
|
|
7284
|
+
throw refuse(`Git reads the worktree at ${work} as the directory ${top || "(none)"} (its core.worktree names another directory)`);
|
|
7285
|
+
}
|
|
7286
|
+
}
|
|
7287
|
+
|
|
7288
|
+
function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktreeRemoval, directory = false, orphanedWork = false, disclosure } = {}) {
|
|
6702
7289
|
if (directory) assertDirectoryRoots(home);
|
|
6703
7290
|
const classes = [];
|
|
6704
7291
|
let baseline;
|
|
6705
|
-
const path =
|
|
7292
|
+
const path = findRetirementBaseline(home);
|
|
6706
7293
|
try {
|
|
6707
7294
|
if (existsSync(path)) baseline = JSON.parse(readFileSync(path, "utf8"));
|
|
6708
7295
|
} catch (e) {
|
|
@@ -6718,12 +7305,15 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
|
|
|
6718
7305
|
// One walk of the home, two digests: the stored one for the comparison with
|
|
6719
7306
|
// the baseline, which must not see the kernel's own fields of instance.json,
|
|
6720
7307
|
// and the exact one for the comparison after the hooks, which must see
|
|
6721
|
-
// every byte.
|
|
7308
|
+
// every byte. The stored one is in the baseline's digest version; a
|
|
7309
|
+
// version this kernel does not take matches nothing, and the walk is then
|
|
7310
|
+
// the one version 2 takes, for the exact digest alone.
|
|
7311
|
+
const digestVersion = baselineDigestVersion(baseline);
|
|
6722
7312
|
let homeDigests;
|
|
6723
|
-
const fingerprintHome = () => (homeDigests ??= fingerprintTrees(home, { excludeRoot: homeExclusions.excludeRoot, instanceHome: true, exact: true, children: true })).stored;
|
|
7313
|
+
const fingerprintHome = () => (homeDigests ??= fingerprintTrees(home, { excludeRoot: homeExclusions.excludeRoot, instanceHome: true, digestVersion: digestVersion ?? BASELINE_DIGEST_VERSION, exact: true, children: true })).stored;
|
|
6724
7314
|
if (!baselineValid) {
|
|
6725
7315
|
classes.push("unknown instance-home provenance");
|
|
6726
|
-
} else if (baseline.homeFingerprint !== fingerprintHome()) {
|
|
7316
|
+
} else if (digestVersion === undefined || baseline.homeFingerprint !== fingerprintHome()) {
|
|
6727
7317
|
classes.push("changed instance-home bytes");
|
|
6728
7318
|
}
|
|
6729
7319
|
// A mutable mode must not turn owned directory bytes into an excluded shared
|
|
@@ -6740,6 +7330,8 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
|
|
|
6740
7330
|
// For a quarantine retry whose worktree is gone, whether the recorded branch
|
|
6741
7331
|
// is still there to copy. Every other retire takes it to be there.
|
|
6742
7332
|
const branchExists = !directory && recordedBranch && !existsSync(work) ? recordedBranchExists(recordedBranch.repo, recordedBranch.branch) : true;
|
|
7333
|
+
// Before anything of the worktree is read: its status describes it, not another directory.
|
|
7334
|
+
if (!directory && isWorktree && existsSync(work)) assertWorktreeTopLevel(work, disclosure);
|
|
6743
7335
|
// A retire that will remove the worktree asks whether a ref that outlives it
|
|
6744
7336
|
// reaches its commit. `head` is kept for the check before the removal.
|
|
6745
7337
|
const unreached = worktreeRemoval?.removes && worktreeRemoval.repo && !directory && isWorktree && existsSync(work) ? worktreeCommitUnreached(worktreeRemoval.repo, work) : undefined;
|
|
@@ -6747,14 +7339,23 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
|
|
|
6747
7339
|
const worktree = isWorktree && existsSync(work);
|
|
6748
7340
|
let gitState = "", workProvable = true;
|
|
6749
7341
|
if (worktree) {
|
|
6750
|
-
// Read once, as bytes. The bytes go into the Git state
|
|
6751
|
-
//
|
|
7342
|
+
// Read once, as bytes. The bytes go into the Git state and into the
|
|
7343
|
+
// comparison with the spawn baseline (its legacy digest reads them as
|
|
7344
|
+
// text); the rows and the classes read them as text.
|
|
6752
7345
|
const statusBytes = worktreeStatusBytes(work);
|
|
6753
7346
|
const status = statusBytes.toString("utf8");
|
|
6754
7347
|
const rows = status.split("\0").filter(Boolean);
|
|
6755
7348
|
if (rows.some((row) => !row.startsWith("?? ") && !row.startsWith("!! "))) classes.push("tracked or index worktree state");
|
|
6756
7349
|
const disposableRoots = baseline?.disposableReceipts?.map((r) => r.root) || [];
|
|
6757
|
-
|
|
7350
|
+
// A path the digest cannot inspect refuses, with what this retire has
|
|
7351
|
+
// and has not done by now, as the other refusals of an inspection do.
|
|
7352
|
+
let generated;
|
|
7353
|
+
try { generated = baseline && digestVersion !== undefined ? generatedWorkFingerprintIn(digestVersion, work, statusBytes, disposableRoots) : undefined; }
|
|
7354
|
+
catch (e) {
|
|
7355
|
+
if (e?.code !== "E_WORK_INSPECTION_FAILED") throw e;
|
|
7356
|
+
throw oatsError(e.code, `${e.message}.${disclosure ? ` ${disclosure}.` : ""}`);
|
|
7357
|
+
}
|
|
7358
|
+
if (generated === undefined || baseline.generatedWorkFingerprint !== generated) classes.push("untracked or ignored worktree bytes");
|
|
6758
7359
|
const found = repositoriesUnder(work);
|
|
6759
7360
|
if (found.some((r) => !r.unknown)) classes.push("nested repository state");
|
|
6760
7361
|
// The one place where a read of the Git state that fails is decided. It
|
|
@@ -6805,15 +7406,29 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
|
|
|
6805
7406
|
return { classes: [...new Set(classes)], home, work, directory, orphanedWork, worktree, workProvable, directoryFingerprint, homeBytes: homeDigests.exact, workFingerprint, homeExclude: homeExclusions.excludeRoot, notCopied: homeExclusions.notCopied, extraTrees, branchExists, head: unreached?.head, runtimeAuthority: baselineValid ? runtimeAuthorityOf(baseline) : undefined };
|
|
6806
7407
|
}
|
|
6807
7408
|
|
|
7409
|
+
/** Copy the entries of `src` into `dest` (created), names as bytes, except
|
|
7410
|
+
* the top-level names in `excludeRoot`, tested as text the way the digests
|
|
7411
|
+
* test them (fingerprintTrees). */
|
|
6808
7412
|
function copyRecoveryTree(src, dest, { excludeRoot = new Set() } = {}) {
|
|
6809
7413
|
mkdirSync(dest, { recursive: true });
|
|
6810
|
-
for (const e of
|
|
6811
|
-
if (excludeRoot.has(e.name)) continue;
|
|
6812
|
-
copyTreeSafe(
|
|
7414
|
+
for (const e of entriesAsBytes(src)) {
|
|
7415
|
+
if (excludeRoot.has(e.name.toString("utf8"))) continue;
|
|
7416
|
+
copyTreeSafe(joinBytes(src, e.name), joinBytes(dest, e.name));
|
|
6813
7417
|
}
|
|
6814
7418
|
}
|
|
7419
|
+
/** Make the top level of `dest`, a fresh clone, the top level of `source`,
|
|
7420
|
+
* names as bytes: every entry of `dest` but its `.git` is removed, then
|
|
7421
|
+
* every entry of `source` but its `.git` is copied (copyTreeSafe). A mirror,
|
|
7422
|
+
* not an overlay: a tracked top-level entry the source deleted or renamed is
|
|
7423
|
+
* not left in the copy as the clone checked it out (awebai/oats#656). The
|
|
7424
|
+
* `.git` of `dest` is never touched: the copy's Git state is restored
|
|
7425
|
+
* separately (restoreStandaloneGitState). */
|
|
7426
|
+
function mirrorTopLevel(source, dest) {
|
|
7427
|
+
for (const e of entriesAsBytes(dest)) if (!e.name.equals(GIT_NAME)) rmSync(joinBytes(dest, e.name), { recursive: true, force: true });
|
|
7428
|
+
for (const e of entriesAsBytes(source)) if (!e.name.equals(GIT_NAME)) copyTreeSafe(joinBytes(source, e.name), joinBytes(dest, e.name));
|
|
7429
|
+
}
|
|
6815
7430
|
|
|
6816
|
-
const RECOVERABLE_GIT_ADMIN = [
|
|
7431
|
+
export const RECOVERABLE_GIT_ADMIN = [
|
|
6817
7432
|
"MERGE_HEAD", "MERGE_MSG", "AUTO_MERGE", "CHERRY_PICK_HEAD", "REVERT_HEAD", "REBASE_HEAD",
|
|
6818
7433
|
"BISECT_LOG", "BISECT_START", "BISECT_NAMES", "rebase-apply", "rebase-merge", "sequencer",
|
|
6819
7434
|
];
|
|
@@ -6860,7 +7475,7 @@ function copiedGitPathDigest(entry, at) {
|
|
|
6860
7475
|
* `cat-file --batch-check` process. */
|
|
6861
7476
|
export function missingGitObjects(repo, oids) {
|
|
6862
7477
|
if (!oids.length) return [];
|
|
6863
|
-
const out =
|
|
7478
|
+
const out = retireGit(repo, ["cat-file", "--batch-check=%(objectname) %(objecttype)"], { input: oids.join("\n") + "\n", encoding: "utf8" });
|
|
6864
7479
|
const missing = [];
|
|
6865
7480
|
for (const line of out.split("\n")) {
|
|
6866
7481
|
if (!line.endsWith(" missing")) continue;
|
|
@@ -6869,31 +7484,95 @@ export function missingGitObjects(repo, oids) {
|
|
|
6869
7484
|
return missing;
|
|
6870
7485
|
}
|
|
6871
7486
|
|
|
7487
|
+
/** A fetch into a recovery clone from the repository it copies. Protocol
|
|
7488
|
+
* version 2, whatever the user's configuration says: its upload-pack serves
|
|
7489
|
+
* an object id the source has although no ref advertises it, which is how
|
|
7490
|
+
* the copier fetches a detached HEAD and the commits only a log names. A
|
|
7491
|
+
* client setting; it runs nothing. */
|
|
7492
|
+
function copierFetch(recovered, source, refspecs, { input } = {}) {
|
|
7493
|
+
retireGit(recovered, ["-c", "protocol.version=2", "fetch", "--quiet", "--no-tags", source, ...refspecs], input === undefined ? {} : { input });
|
|
7494
|
+
}
|
|
7495
|
+
|
|
7496
|
+
/** The commits a reflog file names: the new object id of each entry, which is
|
|
7497
|
+
* what `git log -g` shows for it, the zero id left out. A file that is not
|
|
7498
|
+
* there names none. Read from the copy of the file, so that what is proven
|
|
7499
|
+
* is what the copy carries. */
|
|
7500
|
+
function reflogCommits(file) {
|
|
7501
|
+
if (!existsSync(file)) return [];
|
|
7502
|
+
const out = [];
|
|
7503
|
+
for (const line of readFileSync(file, "latin1").split("\n")) {
|
|
7504
|
+
const m = /^[0-9a-f]{40}(?:[0-9a-f]{24})? ([0-9a-f]{40}(?:[0-9a-f]{24})?) /.exec(line);
|
|
7505
|
+
if (m && !/^0+$/.test(m[1])) out.push(m[1]);
|
|
7506
|
+
}
|
|
7507
|
+
return out;
|
|
7508
|
+
}
|
|
7509
|
+
|
|
7510
|
+
/** The blobs an index listing names (`git ls-files --stage -z` or
|
|
7511
|
+
* `--resolve-undo -z`): rows `<mode> <oid> <stage>\t<path>`. Gitlink rows
|
|
7512
|
+
* (mode 160000) name commits of nested repositories, which
|
|
7513
|
+
* materializeNestedRepositories restores; they and the zero id are never
|
|
7514
|
+
* blobs here. */
|
|
7515
|
+
function indexBlobs(rows) {
|
|
7516
|
+
const out = [];
|
|
7517
|
+
for (const row of rows.toString("latin1").split("\0")) {
|
|
7518
|
+
const m = /^(\d+) ([0-9a-f]+) \d\t/.exec(row);
|
|
7519
|
+
if (m && m[1] !== "160000" && !/^0+$/.test(m[2])) out.push(m[2]);
|
|
7520
|
+
}
|
|
7521
|
+
return out;
|
|
7522
|
+
}
|
|
7523
|
+
|
|
7524
|
+
/** The one step that makes a recovery copy hold every object the Git
|
|
7525
|
+
* metadata it carries names (awebai/oats#654, #655, #657): measure, repair,
|
|
7526
|
+
* re-measure. One `cat-file --batch-check` asks which of the named objects
|
|
7527
|
+
* the copy lacks; the missing commits are fetched from `source` by id (one
|
|
7528
|
+
* fetch, with everything they reach), the missing blobs, which can be in no
|
|
7529
|
+
* commit (staged content, a resolved conflict's sides), are copied by
|
|
7530
|
+
* content (`cat-file blob` → `hash-object -w`); then the whole set is
|
|
7531
|
+
* checked again. A fetch or a read that fails is not the failure itself:
|
|
7532
|
+
* whatever is still missing after the repair is, named by its id, and the
|
|
7533
|
+
* copy is refused (E_WORK_PRESERVATION_FAILED). That covers an object the
|
|
7534
|
+
* source itself lacks, which GIT_NO_LAZY_FETCH keeps the copier from
|
|
7535
|
+
* fetching from a promisor remote. */
|
|
7536
|
+
function carryNamedObjects(source, recovered, { commits = [], blobs = [] }) {
|
|
7537
|
+
const named = [...new Set([...commits, ...blobs])];
|
|
7538
|
+
if (!named.length) return;
|
|
7539
|
+
const missing = new Set(missingGitObjects(recovered, named));
|
|
7540
|
+
const fetch = [...new Set(commits)].filter((oid) => missing.has(oid));
|
|
7541
|
+
if (fetch.length) {
|
|
7542
|
+
try { copierFetch(recovered, source, ["--stdin"], { input: fetch.join("\n") + "\n" }); }
|
|
7543
|
+
catch { /* the re-measure names what the fetch did not bring */ }
|
|
7544
|
+
}
|
|
7545
|
+
for (const oid of new Set(blobs)) {
|
|
7546
|
+
if (!missing.has(oid)) continue;
|
|
7547
|
+
let blob;
|
|
7548
|
+
try { blob = retireGit(source, ["cat-file", "blob", oid]); }
|
|
7549
|
+
catch { continue; /* the re-measure names it */ }
|
|
7550
|
+
const restored = retireGit(recovered, ["hash-object", "-w", "--stdin"], { input: blob, encoding: "utf8" }).trim();
|
|
7551
|
+
if (restored !== oid) throw new Error(`recovered Git object ${restored} did not match source ${oid}`);
|
|
7552
|
+
}
|
|
7553
|
+
const stillMissing = missingGitObjects(recovered, named);
|
|
7554
|
+
if (stillMissing.length) {
|
|
7555
|
+
const more = stillMissing.length > 3 ? ` and ${stillMissing.length - 3} more` : "";
|
|
7556
|
+
throw new Error(`the recovery lacks ${stillMissing.length} Git object(s) that its copied Git metadata names, and ${source} could not supply them: ${stillMissing.slice(0, 3).join(", ")}${more}`);
|
|
7557
|
+
}
|
|
7558
|
+
}
|
|
7559
|
+
|
|
6872
7560
|
function restoreStandaloneGitState(sourceWork, recoveredRepo) {
|
|
6873
7561
|
const sourceGit = copierGitDir(sourceWork);
|
|
6874
7562
|
const recoveredGit = join(recoveredRepo, ".git");
|
|
6875
|
-
|
|
6876
|
-
//
|
|
6877
|
-
//
|
|
6878
|
-
//
|
|
6879
|
-
//
|
|
6880
|
-
//
|
|
6881
|
-
//
|
|
6882
|
-
|
|
6883
|
-
|
|
6884
|
-
|
|
6885
|
-
|
|
6886
|
-
|
|
6887
|
-
|
|
6888
|
-
staged.add(match[2]);
|
|
6889
|
-
}
|
|
6890
|
-
for (const oid of missingGitObjects(recoveredRepo, [...staged])) {
|
|
6891
|
-
const blob = execFileSync("git", ["-C", sourceWork, "cat-file", "blob", oid], { maxBuffer: GIT_MAX_BUFFER });
|
|
6892
|
-
const restored = execFileSync("git", ["-C", recoveredRepo, "hash-object", "-w", "--stdin"], { input: blob, encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
|
|
6893
|
-
if (restored !== oid) throw new Error(`recovered Git object ${restored} did not match source ${oid}`);
|
|
6894
|
-
}
|
|
6895
|
-
const stillMissing = missingGitObjects(recoveredRepo, [...staged]);
|
|
6896
|
-
if (stillMissing.length) throw new Error(`recovered repository lacks ${stillMissing.length} staged object(s) after restore: ${stillMissing.slice(0, 3).join(", ")}`);
|
|
7563
|
+
// The blobs the copied index names, read from the index file the copier
|
|
7564
|
+
// copies (awebai/oats#647), not from Git's own idea of the index: its
|
|
7565
|
+
// staged entries and its resolve-undo records (awebai/oats#655). The clone
|
|
7566
|
+
// already holds every blob reachable from a commit; carryNamedObjects asks
|
|
7567
|
+
// once which the copy lacks and copies only those. Copying every row cost
|
|
7568
|
+
// two Git processes per index entry: a clean 9,500 file tree took ~19,000
|
|
7569
|
+
// launches and looked like a hang.
|
|
7570
|
+
const index = { env: { GIT_INDEX_FILE: join(sourceGit, "index") } };
|
|
7571
|
+
const blobs = [
|
|
7572
|
+
...indexBlobs(retireGit(sourceWork, ["ls-files", "--stage", "-z"], index)),
|
|
7573
|
+
...indexBlobs(retireGit(sourceWork, ["ls-files", "--resolve-undo", "-z"], index)),
|
|
7574
|
+
];
|
|
7575
|
+
carryNamedObjects(sourceWork, recoveredRepo, { blobs });
|
|
6897
7576
|
// The index is the selection's one exception (COPIED_GIT_PATHS): copied
|
|
6898
7577
|
// whole, compared by its entries, resolve-undo records and mode.
|
|
6899
7578
|
copyFileSync(join(sourceGit, "index"), join(recoveredGit, "index"));
|
|
@@ -6940,14 +7619,14 @@ const STATUS_CONFIG = ["core.fileMode", "core.ignoreCase", "core.precomposeUnico
|
|
|
6940
7619
|
* carried: [{ kind: "config", key, value } | { kind: "info/attributes", path }]. */
|
|
6941
7620
|
function carryStatusConfig(sourceWork, recoveredRepo) {
|
|
6942
7621
|
const get = (repo, key) => {
|
|
6943
|
-
try { return
|
|
7622
|
+
try { return retireGit(repo, ["config", "--get", key], { encoding: "utf8" }).replace(/\n$/, ""); }
|
|
6944
7623
|
catch (e) { if (e.status === 1) return null; throw e; }
|
|
6945
7624
|
};
|
|
6946
7625
|
const carried = [];
|
|
6947
7626
|
for (const key of STATUS_CONFIG) {
|
|
6948
7627
|
const value = get(sourceWork, key);
|
|
6949
7628
|
if (value === get(recoveredRepo, key)) continue;
|
|
6950
|
-
|
|
7629
|
+
retireGit(recoveredRepo, ["config", "--local", ...(value === null ? ["--unset-all", key] : [key, value])]);
|
|
6951
7630
|
carried.push({ kind: "config", key, value });
|
|
6952
7631
|
}
|
|
6953
7632
|
const common = copierCommonDir(sourceWork);
|
|
@@ -6961,71 +7640,161 @@ function carryStatusConfig(sourceWork, recoveredRepo) {
|
|
|
6961
7640
|
return carried;
|
|
6962
7641
|
}
|
|
6963
7642
|
|
|
6964
|
-
|
|
7643
|
+
/** Make a recovery clone stand on its own: give it the source's stash (the
|
|
7644
|
+
* ref, its log, and every commit the copied log names: awebai/oats#654),
|
|
7645
|
+
* prove it holds those and `commits` (what the caller's carried metadata
|
|
7646
|
+
* names) with carryNamedObjects, then remove the remote it was cloned from. */
|
|
7647
|
+
function detachRecoveryClone(source, recovered, commits = []) {
|
|
7648
|
+
const named = [...commits];
|
|
6965
7649
|
let stash;
|
|
6966
|
-
try { stash =
|
|
7650
|
+
try { stash = retireGit(source, ["rev-parse", "--verify", "--quiet", "refs/stash"], { encoding: "utf8" }).trim(); }
|
|
6967
7651
|
catch { stash = undefined; }
|
|
6968
7652
|
if (stash) {
|
|
6969
|
-
|
|
7653
|
+
copierFetch(recovered, source, ["refs/stash:refs/stash"]);
|
|
7654
|
+
named.push(stash);
|
|
6970
7655
|
const sourceCommon = copierCommonDir(source);
|
|
6971
7656
|
const stashLog = copiedGitPath(GIT_STASH_LOG, null, sourceCommon);
|
|
6972
7657
|
if (existsSync(stashLog)) {
|
|
6973
7658
|
const recoveredLog = copiedGitPath(GIT_STASH_LOG, null, join(recovered, ".git"));
|
|
6974
7659
|
mkdirSync(dirname(recoveredLog), { recursive: true });
|
|
6975
7660
|
copyFileSync(stashLog, recoveredLog);
|
|
7661
|
+
named.push(...reflogCommits(recoveredLog));
|
|
6976
7662
|
}
|
|
6977
7663
|
}
|
|
6978
|
-
|
|
6979
|
-
}
|
|
6980
|
-
|
|
7664
|
+
carryNamedObjects(source, recovered, { commits: named });
|
|
7665
|
+
try { retireGit(recovered, ["remote", "remove", "origin"]); } catch { /* no remote is already independent */ }
|
|
7666
|
+
}
|
|
7667
|
+
|
|
7668
|
+
/** A path under a Git directory for a ref name read as bytes: a branch name
|
|
7669
|
+
* need not be UTF-8, and the file Git keeps for it is named by its bytes. */
|
|
7670
|
+
const gitPathOf = (dir, ...parts) => Buffer.concat([Buffer.from(`${dir}${sep}`), ...parts]);
|
|
7671
|
+
const parentOf = (path) => path.subarray(0, path.lastIndexOf(sep.charCodeAt(0)));
|
|
7672
|
+
|
|
7673
|
+
/** Give the clone of a nested repository the source's refs where they matter
|
|
7674
|
+
* for recovering work (awebai/oats#657): every local branch under its name at
|
|
7675
|
+
* its commit, HEAD on the source's branch when the source is on one (`name`:
|
|
7676
|
+
* headName) and detached at `head` otherwise, and the source's reflogs of
|
|
7677
|
+
* HEAD and of each branch, copied over the clone's own. The branches are the
|
|
7678
|
+
* source's own `refs/heads`, not the clone's `refs/remotes/origin/*`: those
|
|
7679
|
+
* are only what the source advertises, and its configuration can hide a
|
|
7680
|
+
* branch from a clone (`uploadpack.hideRefs`). A tip the clone lacks is
|
|
7681
|
+
* fetched by id (carryNamedObjects), and the copy's branches are then
|
|
7682
|
+
* checked to be the source's, name and commit, byte for byte. Its local
|
|
7683
|
+
* configuration is not carried beyond the status settings
|
|
7684
|
+
* (carryStatusConfig): a recovery must be inert to inspect, and
|
|
7685
|
+
* configuration can name programs Git runs. → the commits the copied
|
|
7686
|
+
* reflogs name, for carryNamedObjects: a commit only a reflog reaches is not
|
|
7687
|
+
* in the clone until it is fetched. */
|
|
7688
|
+
function carryNestedRefs(source, dest, name, head) {
|
|
7689
|
+
const BRANCHES = ["for-each-ref", "--format=%(objectname)%00%(refname)", "refs/heads/"];
|
|
7690
|
+
const listing = retireGit(source, BRANCHES);
|
|
7691
|
+
const branches = [];
|
|
7692
|
+
for (let at = 0; at < listing.length;) {
|
|
7693
|
+
let end = listing.indexOf(0x0a, at);
|
|
7694
|
+
if (end < 0) end = listing.length;
|
|
7695
|
+
const row = listing.subarray(at, end);
|
|
7696
|
+
at = end + 1;
|
|
7697
|
+
if (!row.length) continue;
|
|
7698
|
+
const nul = row.indexOf(0);
|
|
7699
|
+
branches.push({ oid: row.subarray(0, nul).toString("latin1"), ref: row.subarray(nul + 1) });
|
|
7700
|
+
}
|
|
7701
|
+
carryNamedObjects(source, dest, { commits: branches.map((b) => b.oid) });
|
|
7702
|
+
if (branches.length) {
|
|
7703
|
+
retireGit(dest, ["update-ref", "--stdin"], { input: Buffer.concat(branches.flatMap(({ oid, ref }) => [Buffer.from("update "), ref, Buffer.from(` ${oid}\n`)])) });
|
|
7704
|
+
}
|
|
7705
|
+
if (!retireGit(dest, BRANCHES).equals(listing)) throw new Error(`nested recovery ${dest} does not have the local branches of its source`);
|
|
7706
|
+
if (name.branch !== null) retireGit(dest, ["symbolic-ref", "HEAD", `refs/heads/${name.branch}`]);
|
|
7707
|
+
else retireGit(dest, ["checkout", "--quiet", "--detach", head]);
|
|
7708
|
+
const recovered = retireGit(dest, ["rev-parse", "HEAD"], { encoding: "utf8" }).trim();
|
|
7709
|
+
if (recovered !== head) throw new Error(`nested recovery ${dest} is at ${recovered}, not at the commit ${head} its source has checked out`);
|
|
7710
|
+
// The reflogs last, so that nothing above writes to them after the copy.
|
|
7711
|
+
const named = [];
|
|
7712
|
+
const carryLog = (from, to) => {
|
|
7713
|
+
if (existsSync(from)) {
|
|
7714
|
+
mkdirSync(parentOf(to), { recursive: true });
|
|
7715
|
+
copyFileSync(from, to);
|
|
7716
|
+
named.push(...reflogCommits(to));
|
|
7717
|
+
} else rmSync(to, { force: true });
|
|
7718
|
+
};
|
|
7719
|
+
const destGit = join(dest, ".git");
|
|
7720
|
+
carryLog(gitPathOf(copierGitDir(source), Buffer.from("logs/HEAD")), gitPathOf(destGit, Buffer.from("logs/HEAD")));
|
|
7721
|
+
const sourceCommon = copierCommonDir(source);
|
|
7722
|
+
for (const { ref } of branches) carryLog(gitPathOf(sourceCommon, Buffer.from("logs/"), ref), gitPathOf(destGit, Buffer.from("logs/"), ref));
|
|
7723
|
+
return named;
|
|
7724
|
+
}
|
|
7725
|
+
|
|
7726
|
+
/** Rebuild each nested repository (nestedGitRoots) in the copy of a worktree
|
|
7727
|
+
* at `recoveredRepo`, from a clone, and mirror its files into it
|
|
7728
|
+
* (mirrorTopLevel). It runs after the worktree's own mirror, which put every
|
|
7729
|
+
* nested repository's plain files in place; each rebuild replaces one of
|
|
7730
|
+
* them. No root is under another (nestedGitRoots does not go into a
|
|
7731
|
+
* repository), so no mirror here removes a repository rebuilt before it.
|
|
7732
|
+
* Git is run on each repository by its path, which Node passes as UTF-8
|
|
7733
|
+
* text: a repository whose path is not valid UTF-8 cannot be named to Git,
|
|
7734
|
+
* and refuses the copy. */
|
|
6981
7735
|
function materializeNestedRepositories(sourceWork, recoveredRepo) {
|
|
6982
7736
|
const excludes = [], statusConfig = [];
|
|
6983
|
-
for (const
|
|
7737
|
+
for (const root of nestedGitRoots(sourceWork)) {
|
|
7738
|
+
const source = root.toString("utf8");
|
|
7739
|
+
if (!Buffer.from(source).equals(root)) throw new Error(`nested repository ${source} has a path that is not valid UTF-8, and Git cannot be run on such a path; rename the directory, then retire again`);
|
|
6984
7740
|
const rel = relative(sourceWork, source);
|
|
6985
7741
|
const dest = join(recoveredRepo, rel);
|
|
6986
|
-
const
|
|
7742
|
+
const name = headName(source);
|
|
7743
|
+
const head = retireGit(source, ["rev-parse", "HEAD"], { encoding: "utf8" }).trim();
|
|
6987
7744
|
rmSync(dest, { recursive: true, force: true });
|
|
6988
|
-
|
|
6989
|
-
|
|
6990
|
-
detachRecoveryClone(source, dest);
|
|
7745
|
+
retireGit(null, ["clone", "--no-local", "--quiet", source, dest]);
|
|
7746
|
+
detachRecoveryClone(source, dest, carryNestedRefs(source, dest, name, head));
|
|
6991
7747
|
restoreStandaloneGitState(source, dest);
|
|
6992
7748
|
for (const c of carryExcludes(source, dest)) excludes.push({ repo: rel, ...c });
|
|
6993
7749
|
for (const c of carryStatusConfig(source, dest)) statusConfig.push({ repo: rel, ...c });
|
|
6994
|
-
|
|
6995
|
-
if (e.name === ".git") continue;
|
|
6996
|
-
const target = join(dest, e.name);
|
|
6997
|
-
rmSync(target, { recursive: true, force: true });
|
|
6998
|
-
copyTreeSafe(join(source, e.name), target);
|
|
6999
|
-
}
|
|
7750
|
+
mirrorTopLevel(source, dest);
|
|
7000
7751
|
if (existsSync(join(dest, ".git", "objects", "info", "alternates"))) throw new Error(`nested recovery ${rel} depends on object alternates`);
|
|
7001
7752
|
assertStatusAgrees(source, dest, `nested recovery ${rel} Git state disagreed with source`, rel);
|
|
7002
7753
|
}
|
|
7003
7754
|
return { excludes, statusConfig };
|
|
7004
7755
|
}
|
|
7005
7756
|
|
|
7006
|
-
/** Bytes a path holds, never following a symlink (a link counts as its own
|
|
7757
|
+
/** Bytes a path holds, never following a symlink (a link counts as its own
|
|
7758
|
+
* entry). `path` is a string or a Buffer; names under it are read as bytes. */
|
|
7007
7759
|
function treeBytes(path) {
|
|
7008
7760
|
let st; try { st = lstatSync(path); } catch { return 0; }
|
|
7009
7761
|
if (!st.isDirectory()) return st.size;
|
|
7010
7762
|
let n = 0;
|
|
7011
|
-
for (const
|
|
7763
|
+
for (const name of readdirSync(path, { encoding: "buffer" })) n += treeBytes(joinBytes(path, name));
|
|
7012
7764
|
return n;
|
|
7013
7765
|
}
|
|
7766
|
+
/** The paths of the untracked (`??`) and ignored (`!!`) rows of
|
|
7767
|
+
* `git status --porcelain=v1 -z` output, as bytes. */
|
|
7768
|
+
function untrackedOrIgnoredPaths(z) {
|
|
7769
|
+
const out = [];
|
|
7770
|
+
for (let at = 0; at < z.length;) {
|
|
7771
|
+
let end = z.indexOf(0, at);
|
|
7772
|
+
if (end < 0) end = z.length;
|
|
7773
|
+
const row = z.subarray(at, end);
|
|
7774
|
+
at = end + 1;
|
|
7775
|
+
const xy = row.subarray(0, 3).toString("latin1");
|
|
7776
|
+
if (xy === "?? " || xy === "!! ") out.push(row.subarray(3));
|
|
7777
|
+
}
|
|
7778
|
+
return out;
|
|
7779
|
+
}
|
|
7014
7780
|
/** The outputs a recovery copies beyond committed and tracked state — a worktree's
|
|
7015
7781
|
* untracked and ignored paths (its status), or a directory's work entries —
|
|
7016
7782
|
* grouped by top-level entry with their bytes, largest first. There is no
|
|
7017
7783
|
* disposable declaration on the workspace model, so node_modules/ or build/
|
|
7018
7784
|
* outputs are copied too: the retire summary names them and what they cost. */
|
|
7019
7785
|
function preservedOutputs(work, directory) {
|
|
7020
|
-
|
|
7021
|
-
|
|
7022
|
-
|
|
7786
|
+
// Paths as bytes, so every one is read by its own name; each group is
|
|
7787
|
+
// named as text, a name that is not UTF-8 with replacement characters.
|
|
7788
|
+
const rows = directory ? readdirSync(work, { encoding: "buffer" }) : untrackedOrIgnoredPaths(worktreeStatusBytes(work));
|
|
7789
|
+
const SLASH = 0x2f;
|
|
7023
7790
|
const groups = new Map();
|
|
7024
7791
|
for (const rel of rows) {
|
|
7025
|
-
const
|
|
7026
|
-
const
|
|
7027
|
-
const
|
|
7028
|
-
|
|
7792
|
+
const trailing = rel.length > 0 && rel[rel.length - 1] === SLASH;
|
|
7793
|
+
const slash = rel.indexOf(SLASH);
|
|
7794
|
+
const first = slash < 0 ? rel : rel.subarray(0, slash);
|
|
7795
|
+
const isDir = (slash >= 0 && slash < rel.length - 1) || trailing || (directory && lstatSync(joinBytes(work, rel)).isDirectory());
|
|
7796
|
+
const key = isDir ? `${first.toString("utf8")}/` : first.toString("utf8");
|
|
7797
|
+
groups.set(key, (groups.get(key) || 0) + treeBytes(joinBytes(work, rel)));
|
|
7029
7798
|
}
|
|
7030
7799
|
const paths = [...groups].map(([path, bytes]) => ({ path, bytes })).sort((a, b) => b.bytes - a.bytes || a.path.localeCompare(b.path));
|
|
7031
7800
|
return { paths, bytes: paths.reduce((n, p) => n + p.bytes, 0) };
|
|
@@ -7034,17 +7803,18 @@ function preservedOutputs(work, directory) {
|
|
|
7034
7803
|
/** The home part of a recovery at `dest`: everything but work/ and this pass's
|
|
7035
7804
|
* excluded provider-owned entries (observation.homeExclude), verified against
|
|
7036
7805
|
* the source with that same set. The copy is hashed whole, so an excluded
|
|
7037
|
-
* entry that reached it fails the verification.
|
|
7038
|
-
*
|
|
7039
|
-
*
|
|
7040
|
-
*
|
|
7041
|
-
*
|
|
7042
|
-
*
|
|
7043
|
-
*
|
|
7806
|
+
* entry that reached it fails the verification. Source and copy are compared
|
|
7807
|
+
* in this run, so whatever version the baseline holds, the stored digest of
|
|
7808
|
+
* version 2 is what is compared (fingerprintTrees): its order is the bytes'
|
|
7809
|
+
* and its fields carry their lengths. It leaves the kernel's own fields of
|
|
7810
|
+
* instance.json out, so a kernel write there between the copy and this check
|
|
7811
|
+
* is not a disagreement. That is why this is not an exact verification of
|
|
7812
|
+
* the whole home: the stored digest also passes over the kernel's receipts
|
|
7813
|
+
* and the harness settings, and reads instance.json through a parse. */
|
|
7044
7814
|
function copyRecoveryHome(observation, dest) {
|
|
7045
7815
|
const excludeRoot = observation.homeExclude || new Set(["work"]);
|
|
7046
7816
|
copyRecoveryTree(observation.home, dest, { excludeRoot });
|
|
7047
|
-
if (
|
|
7817
|
+
if (storedTreeDigest(observation.home, BASELINE_DIGEST_VERSION, { excludeRoot, instanceHome: true }) !== storedTreeDigest(dest, BASELINE_DIGEST_VERSION, { instanceHome: true })) {
|
|
7048
7818
|
throw new Error("home recovery verification disagreed with the source");
|
|
7049
7819
|
}
|
|
7050
7820
|
}
|
|
@@ -7072,11 +7842,11 @@ function copyRecoveryWork(observation, meta, parent) {
|
|
|
7072
7842
|
try { ref = existsSync(observation.work) ? worktreeHead(observation.work) : { branch: meta.branch, commit: null }; }
|
|
7073
7843
|
catch (e) { unreadableHeads.add(e); throw e; }
|
|
7074
7844
|
if (ref.branch !== meta.branch) branchDrift = { recordedBranch: meta.branch, worktreeBranch: ref.branch, detachedAt: ref.branch === null ? ref.commit : null };
|
|
7075
|
-
if (ref.branch !== null)
|
|
7845
|
+
if (ref.branch !== null) retireGit(null, ["clone", "--no-local", "--quiet", "--branch", ref.branch, meta.repo, recoveredRepo]);
|
|
7076
7846
|
else {
|
|
7077
|
-
|
|
7078
|
-
|
|
7079
|
-
|
|
7847
|
+
retireGit(null, ["clone", "--no-local", "--quiet", "--no-checkout", meta.repo, recoveredRepo]);
|
|
7848
|
+
copierFetch(recoveredRepo, observation.work, [ref.commit]);
|
|
7849
|
+
retireGit(recoveredRepo, ["checkout", "--quiet", "--detach", ref.commit]);
|
|
7080
7850
|
}
|
|
7081
7851
|
const sourceGitContext = existsSync(observation.work) ? observation.work : meta.repo;
|
|
7082
7852
|
detachRecoveryClone(sourceGitContext, recoveredRepo);
|
|
@@ -7084,12 +7854,10 @@ function copyRecoveryWork(observation, meta, parent) {
|
|
|
7084
7854
|
restoreStandaloneGitState(observation.work, recoveredRepo);
|
|
7085
7855
|
excludes = carryExcludes(observation.work, recoveredRepo).map((c) => ({ repo: ".", ...c }));
|
|
7086
7856
|
statusConfig = carryStatusConfig(observation.work, recoveredRepo).map((c) => ({ repo: ".", ...c }));
|
|
7087
|
-
|
|
7088
|
-
|
|
7089
|
-
|
|
7090
|
-
|
|
7091
|
-
copyTreeSafe(join(observation.work, e.name), dest);
|
|
7092
|
-
}
|
|
7857
|
+
// The worktree's top level first, then each nested repository rebuilt
|
|
7858
|
+
// inside it (materializeNestedRepositories): that order is what keeps
|
|
7859
|
+
// a rebuilt repository from being removed by a mirror.
|
|
7860
|
+
mirrorTopLevel(observation.work, recoveredRepo);
|
|
7093
7861
|
const nested = materializeNestedRepositories(observation.work, recoveredRepo);
|
|
7094
7862
|
excludes.push(...nested.excludes); statusConfig.push(...nested.statusConfig);
|
|
7095
7863
|
}
|
|
@@ -7099,7 +7867,12 @@ function copyRecoveryWork(observation, meta, parent) {
|
|
|
7099
7867
|
// pre-hook recovery was written, or by the proof that the hooks moved
|
|
7100
7868
|
// nothing, or else here. Either way they are kept as the observation's
|
|
7101
7869
|
// byte state.
|
|
7102
|
-
|
|
7870
|
+
// The Git directories the comparison leaves out are the source's
|
|
7871
|
+
// (worktreeGitPaths), read with its bytes, for both sides.
|
|
7872
|
+
let sourceBytes, gitPaths;
|
|
7873
|
+
if (observation.worktree) { sourceBytes = observedWorkBytes(observation); gitPaths = observation.workGitPaths ?? worktreeGitPaths(observation.work); }
|
|
7874
|
+
else { gitPaths = worktreeGitPaths(observation.work); sourceBytes = worktreeBytes(observation.work, gitPaths); }
|
|
7875
|
+
if (sourceBytes !== worktreeBytes(recoveredRepo, gitPaths)) throw new Error("worktree recovery verification disagreed with the source");
|
|
7103
7876
|
assertStatusAgrees(observation.work, recoveredRepo, "recovered Git index/status disagreed with the source", ".");
|
|
7104
7877
|
}
|
|
7105
7878
|
// The proof of the copy: its HEAD is the commit the worktree has checked
|
|
@@ -7107,9 +7880,9 @@ function copyRecoveryWork(observation, meta, parent) {
|
|
|
7107
7880
|
// same files, so the branch's tip there proves nothing about the copy.
|
|
7108
7881
|
// With the worktree gone there is no such commit to read, and the copy
|
|
7109
7882
|
// is the recorded branch as the repository has it.
|
|
7110
|
-
const recoveredHead =
|
|
7883
|
+
const recoveredHead = retireGit(recoveredRepo, ["rev-parse", "HEAD"], { encoding: "utf8" }).trim();
|
|
7111
7884
|
const sourceHead = ref.commit
|
|
7112
|
-
??
|
|
7885
|
+
?? retireGit(meta.repo, ["rev-parse", `refs/heads/${ref.branch}`], { encoding: "utf8" }).trim();
|
|
7113
7886
|
if (recoveredHead !== sourceHead) throw new Error(ref.commit ? "recovery clone is not at the commit the worktree has checked out" : "recovery clone does not retain the instance branch tip");
|
|
7114
7887
|
copied = true;
|
|
7115
7888
|
}
|
|
@@ -7128,8 +7901,8 @@ function copyRecoveryWork(observation, meta, parent) {
|
|
|
7128
7901
|
* largest first; a directory ends in `/`. What the retire summary names as
|
|
7129
7902
|
* copied from the home. */
|
|
7130
7903
|
function preservedHome(recoveredHome) {
|
|
7131
|
-
const paths =
|
|
7132
|
-
.map((e) => ({ path: e.isDirectory() ? `${e.name}/` : e.name, bytes: treeBytes(
|
|
7904
|
+
const paths = entriesAsBytes(recoveredHome)
|
|
7905
|
+
.map((e) => ({ path: e.isDirectory() ? `${e.name.toString("utf8")}/` : e.name.toString("utf8"), bytes: treeBytes(joinBytes(recoveredHome, e.name)) }))
|
|
7133
7906
|
.sort((a, b) => b.bytes - a.bytes || a.path.localeCompare(b.path));
|
|
7134
7907
|
return { paths, bytes: paths.reduce((n, p) => n + p.bytes, 0) };
|
|
7135
7908
|
}
|
|
@@ -7151,6 +7924,32 @@ function homeOnlyRecovery(observation, meta) {
|
|
|
7151
7924
|
return !RECOVERABLE_GIT_ADMIN.some((name) => existsSync(join(gitDir, name)));
|
|
7152
7925
|
}
|
|
7153
7926
|
|
|
7927
|
+
/** Remove a recovery's staging directory, after a copy that failed or that had
|
|
7928
|
+
* nothing to keep. The copy gives each directory its source's mode
|
|
7929
|
+
* (tree-copy.mjs), and a read-only one (a Go module cache, 0555) keeps
|
|
7930
|
+
* rmSync from unlinking what is in it: each directory is made u+rwx first,
|
|
7931
|
+
* before it is read (an unreadable one could not be listed), symbolic links
|
|
7932
|
+
* are never followed, and then the tree is removed. Names are listed and
|
|
7933
|
+
* joined as bytes, as the copier writes them, so a directory whose name is
|
|
7934
|
+
* not UTF-8 is reached too (#827). Never throws: a cleanup
|
|
7935
|
+
* must not replace the error that made it (#659). → null when the staging is
|
|
7936
|
+
* gone, else the clause a refusal adds to name what is left. */
|
|
7937
|
+
function removeStaging(staging) {
|
|
7938
|
+
const open = (dir) => {
|
|
7939
|
+
let names;
|
|
7940
|
+
try {
|
|
7941
|
+
const st = lstatSync(dir);
|
|
7942
|
+
if (!st.isDirectory()) return;
|
|
7943
|
+
if ((st.mode & 0o700) !== 0o700) chmodSync(dir, (st.mode & 0o7777) | 0o700);
|
|
7944
|
+
names = entriesAsBytes(dir).map((e) => e.name);
|
|
7945
|
+
} catch { return; }
|
|
7946
|
+
for (const name of names) open(joinBytes(dir, name));
|
|
7947
|
+
};
|
|
7948
|
+
try { open(staging); rmSync(staging, { recursive: true, force: true }); } catch { /* named below */ }
|
|
7949
|
+
try { lstatSync(staging); } catch (e) { if (e?.code === "ENOENT") return null; }
|
|
7950
|
+
return `; its partial copy ${staging} could not be removed: remove it by hand`;
|
|
7951
|
+
}
|
|
7952
|
+
|
|
7154
7953
|
/** Write one verified recovery of an observed home and work: staged beside its
|
|
7155
7954
|
* final name and renamed into place. `phase` goes into recovery.json:
|
|
7156
7955
|
* "before-hooks" for the snapshot a retirement takes before its retire hooks
|
|
@@ -7158,7 +7957,7 @@ function homeOnlyRecovery(observation, meta) {
|
|
|
7158
7957
|
* will add to. → { receipt, manifest }: the receipt retire reports, and
|
|
7159
7958
|
* recovery.json as written. */
|
|
7160
7959
|
function writeRetirementRecovery(observation, meta, instance, phase) {
|
|
7161
|
-
const recoveryRoot =
|
|
7960
|
+
const recoveryRoot = retirementRecoveryRoot(dirname(observation.home));
|
|
7162
7961
|
mkdirSync(recoveryRoot, { recursive: true });
|
|
7163
7962
|
if (observation.directory && realpathSync(recoveryRoot) !== join(realpathSync(dirname(observation.home)), ".oats-retirement", "recovery")) {
|
|
7164
7963
|
throw oatsError("E_WORK_PRESERVATION_FAILED", "directory recovery storage was redirected; retain the source home rather than copying into an unowned or disposable location");
|
|
@@ -7183,10 +7982,10 @@ function writeRetirementRecovery(observation, meta, instance, phase) {
|
|
|
7183
7982
|
renameSync(staging, recovery);
|
|
7184
7983
|
return { receipt: { path: recovery, classes: observation.classes, bytes, home, ...(outputs ? { outputs } : {}), ...(repoCopy ? { repoCopy } : {}), ...(notCopied ? { notCopied } : {}) }, manifest };
|
|
7185
7984
|
} catch (e) {
|
|
7186
|
-
|
|
7187
|
-
if (unreadableHeads.has(e)) throw e;
|
|
7985
|
+
const left = removeStaging(staging);
|
|
7986
|
+
if (unreadableHeads.has(e)) { if (left) e.message += left; throw e; }
|
|
7188
7987
|
const details = e.statusDisagreement ? { home: observation.home, statusDisagreement: e.statusDisagreement } : undefined;
|
|
7189
|
-
throw Object.assign(oatsError("E_WORK_PRESERVATION_FAILED", `retirement work remains at ${observation.home}; recovery could not be verified: ${e.message}`, details), details ? { details } : {});
|
|
7988
|
+
throw Object.assign(oatsError("E_WORK_PRESERVATION_FAILED", `retirement work remains at ${observation.home}; recovery could not be verified: ${e.message}${left ?? ""}`, details), details ? { details } : {});
|
|
7190
7989
|
}
|
|
7191
7990
|
}
|
|
7192
7991
|
|
|
@@ -7253,7 +8052,11 @@ function completeRetirementRecovery({ receipt, manifest }, before, after, meta)
|
|
|
7253
8052
|
if (occupied()) throw new Error(`${final} already exists`);
|
|
7254
8053
|
renameSync(staging, final);
|
|
7255
8054
|
afterHooks = { home: wantHome, work: workCopied };
|
|
7256
|
-
} else
|
|
8055
|
+
} else {
|
|
8056
|
+
const left = removeStaging(staging);
|
|
8057
|
+
staging = undefined;
|
|
8058
|
+
if (left) throw new Error(`nothing was copied after the hooks${left}`);
|
|
8059
|
+
}
|
|
7257
8060
|
staging = undefined;
|
|
7258
8061
|
}
|
|
7259
8062
|
const classes = [...new Set([...receipt.classes, ...after.classes])];
|
|
@@ -7266,12 +8069,37 @@ function completeRetirementRecovery({ receipt, manifest }, before, after, meta)
|
|
|
7266
8069
|
const { notCopied: _was, ...kept } = receipt;
|
|
7267
8070
|
return { ...kept, classes, bytes: treeBytes(recovery), ...(notCopied.length ? { notCopied } : {}), ...(afterHooks ? { afterHooks } : {}) };
|
|
7268
8071
|
} catch (e) {
|
|
7269
|
-
|
|
7270
|
-
if (manifestStarted) rmSync(manifestTmp, { force: true });
|
|
7271
|
-
if (unreadableHeads.has(e)) throw e;
|
|
8072
|
+
const left = staging ? removeStaging(staging) : null;
|
|
8073
|
+
if (manifestStarted) { try { rmSync(manifestTmp, { force: true }); } catch { /* the original error is the refusal */ } }
|
|
8074
|
+
if (unreadableHeads.has(e)) { if (left) e.message += left; throw e; }
|
|
7272
8075
|
const details = e.statusDisagreement ? { home: after.home, statusDisagreement: e.statusDisagreement } : undefined;
|
|
7273
|
-
throw Object.assign(oatsError("E_WORK_PRESERVATION_FAILED", `retirement work remains at ${after.home}; recovery could not be verified: ${e.message}`, details), details ? { details } : {});
|
|
7274
|
-
}
|
|
8076
|
+
throw Object.assign(oatsError("E_WORK_PRESERVATION_FAILED", `retirement work remains at ${after.home}; recovery could not be verified: ${e.message}${left ?? ""}`, details), details ? { details } : {});
|
|
8077
|
+
}
|
|
8078
|
+
}
|
|
8079
|
+
|
|
8080
|
+
/** The `work` link of the instance at `kidHome` when it is attached to
|
|
8081
|
+
* `home`'s work (#718), else null: instance.json says `work: "attached"`, and
|
|
8082
|
+
* its `work` is a symbolic link that leads to `<home>/work`, as written (in
|
|
8083
|
+
* any spelling of the home) or through other links (`--work-dir` given as an
|
|
8084
|
+
* alias of the tree). The latter is seen only while `<home>/work` exists, so a
|
|
8085
|
+
* retire asks before it re-homes the worktree. → the link's target as written:
|
|
8086
|
+
* the evidence a later relink checks is still there. */
|
|
8087
|
+
export function attachedWorkLink(kidHome, home) {
|
|
8088
|
+
if (readJsonOrUndefined(join(kidHome, "instance.json"))?.work !== "attached") return null;
|
|
8089
|
+
const link = join(kidHome, "work");
|
|
8090
|
+
let written;
|
|
8091
|
+
try { written = readlinkSync(link); } catch { return null; }
|
|
8092
|
+
const target = resolve(kidHome, written);
|
|
8093
|
+
if (target === join(resolve(home), "work")) return written;
|
|
8094
|
+
try { if (basename(target) === "work" && realpathSync(dirname(target)) === realpathSync(home)) return written; } catch { /* below */ }
|
|
8095
|
+
try { return realpathSync(link) === realpathSync(join(home, "work")) ? written : null; } catch { return null; }
|
|
8096
|
+
}
|
|
8097
|
+
/** Point an attached instance's `work` link at `to`, atomically: a new link
|
|
8098
|
+
* beside it is renamed over the old one, so the link is never missing. */
|
|
8099
|
+
function relinkAttachedWork(kidHome, to) {
|
|
8100
|
+
const tmp = join(kidHome, `.work.relink-${process.pid}`);
|
|
8101
|
+
try { rmSync(tmp, { force: true }); symlinkSync(to, tmp); renameSync(tmp, join(kidHome, "work")); }
|
|
8102
|
+
catch (e) { try { rmSync(tmp, { force: true }); } catch { /* the first error is the one reported */ } throw e; }
|
|
7275
8103
|
}
|
|
7276
8104
|
|
|
7277
8105
|
/** Marker a self-retiring instance leaves BESIDE its home: the retirement is
|
|
@@ -7427,6 +8255,10 @@ export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
|
|
|
7427
8255
|
return true;
|
|
7428
8256
|
}
|
|
7429
8257
|
|
|
8258
|
+
/** The key of the home a retire selected (a string) on retireInstance's result
|
|
8259
|
+
* (awebai/oats#693): the CLI cleans that home's wake schedules. A symbol, so
|
|
8260
|
+
* the printed and JSON receipt, and a recorded one, do not carry it. */
|
|
8261
|
+
export const RETIRE_SELECTED_HOME = Symbol("oats.retireSelectedHome");
|
|
7430
8262
|
export function retireInstance(root, name, o = {}) {
|
|
7431
8263
|
if (o.deleteBranch) throw oatsError("E_BAD_ARGS", RETIRE_DELETE_BRANCH_REFUSED);
|
|
7432
8264
|
const session = o.tmuxSession || DEFAULT_TMUX_SESSION;
|
|
@@ -7460,6 +8292,7 @@ export function retireInstance(root, name, o = {}) {
|
|
|
7460
8292
|
const quarantinePath = existsSync(directoryFallbackPath) ? directoryFallbackPath : join(found.home, ".oats-rollback-incomplete.json");
|
|
7461
8293
|
let quarantine;
|
|
7462
8294
|
let markerUnusable = false;
|
|
8295
|
+
let rawMarker;
|
|
7463
8296
|
// A marker means the home is quarantined, WHETHER OR NOT instance.json exists:
|
|
7464
8297
|
// the post-launch rollback retains a home that already has one, and gating on
|
|
7465
8298
|
// its absence meant that quarantine was silently ignored — retire took the
|
|
@@ -7474,10 +8307,46 @@ export function retireInstance(root, name, o = {}) {
|
|
|
7474
8307
|
// against what the retry below consumes (reviewer-45ff039r2).
|
|
7475
8308
|
try {
|
|
7476
8309
|
const parsed = JSON.parse(readFileSync(quarantinePath, "utf8"));
|
|
8310
|
+
rawMarker = parsed;
|
|
7477
8311
|
if (isPlainObject(parsed) && usableCleanupDescriptor(parsed)) quarantine = parsed;
|
|
7478
8312
|
else markerUnusable = true;
|
|
7479
8313
|
} catch { markerUnusable = true; }
|
|
7480
8314
|
}
|
|
8315
|
+
// #796: a marker a spawn wrote before its worktree hooks (`inProgress`). While that spawn's
|
|
8316
|
+
// process is verifiably alive it is a spawn in progress, never a quarantine to retry, --force
|
|
8317
|
+
// included. Once it is gone, the hook group it left is ended when its leader is alive at the
|
|
8318
|
+
// recorded start time; a group whose leader is gone is never signalled, only reported (its id may
|
|
8319
|
+
// be another group's by now). The retry below completes the rollback from the marker like any other.
|
|
8320
|
+
// Whether that process still runs may also be unreadable (no procfs and `ps` failing): that is never
|
|
8321
|
+
// taken for gone. Retire refuses it, naming the recorded pid and start for a check by hand, and the
|
|
8322
|
+
// existing forced path (`--force`) is the way out; a forced retry then keeps the spawn's branch.
|
|
8323
|
+
// The same holds for a hook group with members whose leader's start cannot be read.
|
|
8324
|
+
const spawnGroupWarnings = [];
|
|
8325
|
+
let inProgressUnverified = false;
|
|
8326
|
+
if (isPlainObject(rawMarker?.inProgress)) {
|
|
8327
|
+
const p = rawMarker.inProgress;
|
|
8328
|
+
const live = processLiveness(p);
|
|
8329
|
+
if (live.state === "alive") throw oatsError("E_LIFECYCLE_BUSY", `${name} is still being spawned (pid ${p.pid}, running its worktree hooks since ${p.startedAt ?? "?"}); nothing was retired — wait for the spawn to end, or stop that process, then retire`);
|
|
8330
|
+
if (live.state === "unknown") {
|
|
8331
|
+
if (!o.force) throw Object.assign(oatsError("E_LIFECYCLE_BUSY", `${name}: whether its spawn (pid ${p.pid}, recorded start ${p.processStart ?? "none"}, running its worktree hooks since ${p.startedAt ?? "?"}) still runs cannot be read (${live.reason}); nothing was retired — check that pid by hand, and if it is not that spawn, run \`oats retire ${name} --force\``), { details: { pid: p.pid, processStart: p.processStart ?? null, unknown: live.reason, remedy: `oats retire ${name} --force` } });
|
|
8332
|
+
inProgressUnverified = true;
|
|
8333
|
+
spawnGroupWarnings.push(`retired with --force although whether its spawn (pid ${p.pid}) still runs could not be read (${live.reason}); its branch is kept`);
|
|
8334
|
+
}
|
|
8335
|
+
}
|
|
8336
|
+
if (quarantine?.inProgress) {
|
|
8337
|
+
const p = quarantine.inProgress;
|
|
8338
|
+
const ended = terminateRecordedGroup(p);
|
|
8339
|
+
if (ended === "survived") throw oatsError("E_LIFECYCLE_BUSY", `${name}: the worktree hook process group ${p.hookPgid} that an interrupted spawn left could not be ended (it survived SIGKILL); nothing was retired`);
|
|
8340
|
+
if (ended === "unverified") spawnGroupWarnings.push(unverifiedGroupWarning(p.hookPgid));
|
|
8341
|
+
// A group whose leader's start cannot be read may still be that spawn's hook: never signalled,
|
|
8342
|
+
// and refused like an unreadable spawn above, with the same way out.
|
|
8343
|
+
if (ended === "unknown") {
|
|
8344
|
+
const note = unknownGroupNote(p);
|
|
8345
|
+
if (!o.force) throw Object.assign(oatsError("E_LIFECYCLE_BUSY", `${name}: the worktree hook ${note}; nothing was retired — check process group ${p.hookPgid} by hand: if it is that hook, end it (kill -TERM -- -${p.hookPgid}) and retire again; if it is not, run \`oats retire ${name} --force\``), { details: { hookPgid: p.hookPgid, hookStart: p.hookStart ?? null, remedy: `oats retire ${name} --force` } });
|
|
8346
|
+
inProgressUnverified = true;
|
|
8347
|
+
spawnGroupWarnings.push(`retired with --force although the worktree ${note}; its branch is kept`);
|
|
8348
|
+
}
|
|
8349
|
+
}
|
|
7481
8350
|
const liveMeta = existsSync(metaPath) ? JSON.parse(readFileSync(metaPath, "utf8")) : undefined;
|
|
7482
8351
|
// A quarantined home may carry an instance.json that is NOT the spawn record:
|
|
7483
8352
|
// module materialization writes a pre-hook stub ({ modules, providers,
|
|
@@ -7524,7 +8393,7 @@ export function retireInstance(root, name, o = {}) {
|
|
|
7524
8393
|
// (aweb-abep). `--keep-dir` keeps the old in-process path: nothing to inspect.
|
|
7525
8394
|
// A home opened in Herdr (removed in 0.31.0) has no endpoint OATS can quiesce in-process. A
|
|
7526
8395
|
// quarantined home's cleanup descriptor overrides the live record's endpoint: either may name it.
|
|
7527
|
-
const herdrHome = recordsHerdr(meta, readJsonOrUndefined(
|
|
8396
|
+
const herdrHome = recordsHerdr(meta, readJsonOrUndefined(findRetirementBaseline(found.home))) || recordsHerdr(liveMeta);
|
|
7528
8397
|
if (self && (!o.keepDir || herdrHome)) {
|
|
7529
8398
|
return scheduleDeferredSelfRetirement(root, found, name, o, session);
|
|
7530
8399
|
}
|
|
@@ -7543,7 +8412,7 @@ export function retireInstance(root, name, o = {}) {
|
|
|
7543
8412
|
const recordedBranch = quarantine ? { repo: meta.repo, branch: meta.branch } : undefined;
|
|
7544
8413
|
// Whether this retire removes the worktree, when it gets to that step.
|
|
7545
8414
|
const worktreeRemoval = { removes: !!(o.discardWorktree || owesWorktree), repo: meta.repo };
|
|
7546
|
-
const initialObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { recordedBranch, worktreeRemoval, directory, orphanedWork });
|
|
8415
|
+
const initialObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { recordedBranch, worktreeRemoval, directory, orphanedWork, disclosure: "Nothing was stopped, run or removed" });
|
|
7547
8416
|
// A locked extra tree is known from the home as it is now: Git will neither move nor remove it, so a retire that
|
|
7548
8417
|
// would remove the home refuses here, before the session is stopped and before any retire hook runs (the hooks
|
|
7549
8418
|
// revoke identities a kept home would still need). The extra-tree step keeps its own check, for a lock that appears
|
|
@@ -7611,20 +8480,23 @@ export function retireInstance(root, name, o = {}) {
|
|
|
7611
8480
|
} catch (e) {
|
|
7612
8481
|
const detail = String(e.stderr ?? e.message ?? "").trim();
|
|
7613
8482
|
const unestablished = (why) => oatsError("E_RUNTIME_QUIESCE_FAILED", `could not establish that ${runtimeSession}:${runtimeWindow} stopped on ${runtimeSocket}: ${why}`);
|
|
7614
|
-
if (!/no server running|
|
|
7615
|
-
|
|
7616
|
-
|
|
7617
|
-
//
|
|
7618
|
-
//
|
|
7619
|
-
// without its receipt.
|
|
7620
|
-
const
|
|
7621
|
-
if (
|
|
7622
|
-
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` : ""})`);
|
|
8483
|
+
if (!/no server running|can't find session|no sessions/i.test(detail)) {
|
|
8484
|
+
const absence = tmuxServerAbsence(e);
|
|
8485
|
+
if (!absence) throw unestablished(detail || "tmux inspection failed");
|
|
8486
|
+
// A missing socket file, in any tmux's words (a reboot clears tmux's socket directory). A server
|
|
8487
|
+
// outlives its socket file, so that alone does not say the window is gone: it is taken as gone
|
|
8488
|
+
// only when no process works in the home, as for a home without its receipt (#624).
|
|
8489
|
+
const why = absence === "missing-socket" ? missingSocketUnestablished(detail, processesInHome(found.home)) : null;
|
|
8490
|
+
if (why) throw unestablished(why);
|
|
7623
8491
|
}
|
|
7624
8492
|
}
|
|
7625
8493
|
sessionStopped = true;
|
|
7626
8494
|
}
|
|
7627
|
-
|
|
8495
|
+
// What a refusal before the hooks tells the operator about the retire so far.
|
|
8496
|
+
const soFar = (kept) => `${name} is not retired and ${kept}; ${sessionStopped ? "its session has been stopped" : "this retire stopped no session"}`;
|
|
8497
|
+
// What a refusal after the hooks tells the operator about the retire so far.
|
|
8498
|
+
const afterHooks = () => `The retire hooks have run; the home, its work and the pre-hook recovery (if any) are kept; ${sessionStopped ? "its session has been stopped" : "this retire stopped no session"}`;
|
|
8499
|
+
const stableObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { recordedBranch, worktreeRemoval, directory, orphanedWork, disclosure: `No retire hook has run and nothing was deleted: ${soFar("its home and work are kept")}` });
|
|
7628
8500
|
// The bytes of the worktree as they are before the hooks: after the hooks,
|
|
7629
8501
|
// "the work did not move" is then proven, never taken from a status text.
|
|
7630
8502
|
// Read before the recovery is written, so that a worktree that cannot be
|
|
@@ -7636,8 +8508,6 @@ export function retireInstance(root, name, o = {}) {
|
|
|
7636
8508
|
// unchanged is copied again in any case, and with nothing to preserve
|
|
7637
8509
|
// before the hooks there is nothing to prove: any class after them is
|
|
7638
8510
|
// preserved.
|
|
7639
|
-
// What a refusal before the hooks tells the operator about the retire so far.
|
|
7640
|
-
const soFar = (kept) => `${name} is not retired and ${kept}; ${sessionStopped ? "its session has been stopped" : "this retire stopped no session"}`;
|
|
7641
8511
|
if (stableObservation.classes.length && stableObservation.workProvable) {
|
|
7642
8512
|
try { observedWorkBytes(stableObservation); }
|
|
7643
8513
|
catch (e) {
|
|
@@ -7740,10 +8610,17 @@ export function retireInstance(root, name, o = {}) {
|
|
|
7740
8610
|
// baseline): it does not have to be a move of the observed state. Either
|
|
7741
8611
|
// way this finishes, or refuses and keeps the home, before the worktree
|
|
7742
8612
|
// step and before the home is removed.
|
|
7743
|
-
|
|
7744
|
-
|
|
7745
|
-
|
|
7746
|
-
|
|
8613
|
+
// A refusal here says what has and has not happened, as one before the hooks
|
|
8614
|
+
// does: the hooks have run, and what is kept (#659).
|
|
8615
|
+
const finalObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { recordedBranch, worktreeRemoval, directory, orphanedWork, disclosure: afterHooks() });
|
|
8616
|
+
try {
|
|
8617
|
+
if (preHookRecovery) workRecovery = completeRetirementRecovery(preHookRecovery, stableObservation, finalObservation, meta);
|
|
8618
|
+
else if (finalObservation.classes.length) {
|
|
8619
|
+
workRecovery = preserveRetirementWork({ ...finalObservation, notCopied: unionNotCopied(stableObservation.notCopied, finalObservation.notCopied) }, meta, name);
|
|
8620
|
+
}
|
|
8621
|
+
} catch (e) {
|
|
8622
|
+
if (!e?.code) throw e;
|
|
8623
|
+
throw Object.assign(oatsError(e.code, `${e.message}. ${afterHooks()}.`, e.provenance), e.details ? { details: e.details } : {});
|
|
7747
8624
|
}
|
|
7748
8625
|
|
|
7749
8626
|
// Lineage repair: any instance pointing at the retiree (parentInstance from a
|
|
@@ -7842,8 +8719,8 @@ export function retireInstance(root, name, o = {}) {
|
|
|
7842
8719
|
try {
|
|
7843
8720
|
git(row, ["worktree", "remove", row.path]);
|
|
7844
8721
|
git(row, ["worktree", "prune"]);
|
|
7845
|
-
const real =
|
|
7846
|
-
if (existsSync(row.path) || parseWorktreeList(git(row, ["worktree", "list", "--porcelain", "-z"])).some((r) =>
|
|
8722
|
+
const real = canonicalHomePath(row.path);
|
|
8723
|
+
if (existsSync(row.path) || parseWorktreeList(git(row, ["worktree", "list", "--porcelain", "-z"])).some((r) => canonicalHomePath(r.worktree) === real)) throw new Error("it is still there after `git worktree remove`");
|
|
7847
8724
|
} catch (e) { throw failed(row, "could not be removed, or its removal could not be verified", e); }
|
|
7848
8725
|
extraWorktrees.push({ ...row, outcome: "removed" });
|
|
7849
8726
|
appendEvent(found.home, { kind: "worktree-removed", data: { branch: row.branch, extra: true, path: row.path } }, { workspaceOnly: true });
|
|
@@ -7858,10 +8735,31 @@ export function retireInstance(root, name, o = {}) {
|
|
|
7858
8735
|
}
|
|
7859
8736
|
if (!extraWorktrees.length) extraWorktrees = undefined;
|
|
7860
8737
|
}
|
|
8738
|
+
// The attached children this retire stopped whose work is this home's work/
|
|
8739
|
+
// (#718), found while work/ is still here (a link through an alias of the
|
|
8740
|
+
// tree resolves only then), each with its link as written.
|
|
8741
|
+
const attachedKids = (childrenStopped || []).filter((k) => k.ok).map((k) => ({ ...k, link: attachedWorkLink(k.home, found.home) })).filter((k) => k.link !== null);
|
|
7861
8742
|
const worktreeStep = isWorktree && !!meta.repo && !orphanedWork;
|
|
7862
8743
|
const worktreeDeferred = worktreeStep && existsSync(workPath) && outstandingBeforeWorktree.length > 0 && !o.force;
|
|
7863
8744
|
const keptForRetry = worktreeDeferred ? `git worktree ${workPath}: kept for the retry; outstanding: ${outstandingBeforeWorktree.join("; ")}` : null;
|
|
7864
8745
|
let retention = null;
|
|
8746
|
+
// The repository of work/, by its common Git directory (awebai/oats#679), read once from meta.repo: the
|
|
8747
|
+
// step's commands and the quarantine's verification below run helper-free against it (gitRepoRun,
|
|
8748
|
+
// gitRepoRead), as the extra-tree step's do. A bare repository is named as its Git directory.
|
|
8749
|
+
// → { dir } or { error }.
|
|
8750
|
+
let workRepo;
|
|
8751
|
+
const workRepoGitDir = () => {
|
|
8752
|
+
if (workRepo) return workRepo;
|
|
8753
|
+
const args = ["rev-parse", "--path-format=absolute", "--git-common-dir"];
|
|
8754
|
+
let r = gitRead(meta.repo, args);
|
|
8755
|
+
if (!r.ok) { const asGitDir = gitRepoRead(meta.repo, args); if (asGitDir.ok) r = asGitDir; }
|
|
8756
|
+
const dir = r.ok ? r.out.replace(/\n$/, "") : "";
|
|
8757
|
+
return (workRepo = dir && !dir.includes("\n") ? { dir: realPathOrNearest(dir) } : { error: r.ok ? `git rev-parse printed no single Git directory for ${meta.repo}` : r.err });
|
|
8758
|
+
};
|
|
8759
|
+
// Whether an entry is at the path: lstat, so a dangling link is an entry; one that cannot be tested counts.
|
|
8760
|
+
const entryAt = (path) => { try { lstatSync(path); return true; } catch (e) { return e?.code !== "ENOENT"; } };
|
|
8761
|
+
// A removal that work/ was not there for, from a repository that could not be read: nothing was verified.
|
|
8762
|
+
let removalUnverified;
|
|
7865
8763
|
if (worktreeStep && !worktreeDeferred) {
|
|
7866
8764
|
// A HEAD that cannot be read here is recorded as no branch and no commit, and the worktree is retained.
|
|
7867
8765
|
const ref = existsSync(workPath) ? (() => { try { return worktreeHead(workPath); } catch { return { branch: null, commit: null }; } })() : { branch: meta.branch ?? null, commit: null };
|
|
@@ -7877,14 +8775,36 @@ export function retireInstance(root, name, o = {}) {
|
|
|
7877
8775
|
catch (e) { throw oatsError("E_WORK_INSPECTION_FAILED", `${e.message}. The worktree was not removed. The home and the worktree are kept, and so is any recovery the retire wrote; retry the retire.`); }
|
|
7878
8776
|
assertSameWorktreeHead(finalObservation.head, now);
|
|
7879
8777
|
}
|
|
7880
|
-
|
|
7881
|
-
|
|
7882
|
-
|
|
8778
|
+
// The removal is verified as the extra-tree step's is: nothing is at work/ and the repository's
|
|
8779
|
+
// worktree list does not name it. A removal that did not happen, or cannot be shown to have
|
|
8780
|
+
// happened, refuses and keeps the home, --force included. One exception: nothing at work/ and a
|
|
8781
|
+
// repository that cannot be read is recorded as absent, never removed; a quarantine keeps that
|
|
8782
|
+
// as an item its retry could not verify (below).
|
|
8783
|
+
const present = entryAt(workPath);
|
|
8784
|
+
const gitDir = workRepoGitDir();
|
|
8785
|
+
if (gitDir.error && !present) {
|
|
8786
|
+
removalUnverified = gitDir.error;
|
|
8787
|
+
retention = { worktree: "absent", branch: verifiedBranch, recordedBranch: meta.branch ?? null };
|
|
8788
|
+
} else {
|
|
8789
|
+
const real = canonicalHomePath(workPath);
|
|
8790
|
+
try {
|
|
8791
|
+
if (gitDir.error) throw new Error(gitDir.error);
|
|
8792
|
+
if (present) gitRepoRun(gitDir.dir, ["worktree", "remove", "--force", workPath]);
|
|
8793
|
+
gitRepoRun(gitDir.dir, ["worktree", "prune"]);
|
|
8794
|
+
if (entryAt(workPath) || parseWorktreeList(gitRepoRun(gitDir.dir, ["worktree", "list", "--porcelain", "-z"])).some((r) => canonicalHomePath(r.worktree) === real)) throw new Error("it is still there after `git worktree remove`");
|
|
8795
|
+
} catch (e) {
|
|
8796
|
+
const done = extraWorktrees?.length ? ` Already done in this retire: ${extraWorktrees.map((r) => r.outcome === "removed" ? `${r.path} removed` : `${r.path} re-homed to ${r.movedTo}`).join(", ")}.` : "";
|
|
8797
|
+
throw oatsError("E_WORK_PRESERVATION_FAILED", `${name}: the worktree at ${workPath} could not be removed, or its removal could not be verified (${String(e?.stderr || e?.message || e || "").trim() || "unknown error"}).${done} The retire hooks have run; the home is kept, and so is any recovery the retire wrote; ${sessionStopped ? "its session has been stopped" : "this retire stopped no session"}. Check what is left at ${workPath}, then retry the retire.`);
|
|
8798
|
+
}
|
|
8799
|
+
retention = { worktree: "removed", branch: verifiedBranch, recordedBranch: meta.branch ?? null };
|
|
8800
|
+
}
|
|
7883
8801
|
} else if (existsSync(workPath)) {
|
|
7884
8802
|
const dest = retainedWorktreeDest(workspaceOf(root), meta.repo, verifiedBranch, ref.commit);
|
|
7885
8803
|
mkdirSync(dirname(dest), { recursive: true });
|
|
7886
8804
|
try {
|
|
7887
|
-
|
|
8805
|
+
const gitDir = workRepoGitDir();
|
|
8806
|
+
if (gitDir.error) throw new Error(gitDir.error);
|
|
8807
|
+
gitRepoRun(gitDir.dir, ["worktree", "move", workPath, dest]);
|
|
7888
8808
|
} catch (e) {
|
|
7889
8809
|
throw oatsError("E_WORK_PRESERVATION_FAILED", `${name}: the worktree at ${workPath} could not be re-homed to ${dest} (${String(e.stderr ?? e.message ?? "").trim()}); the home is kept so nothing is lost — resolve and retry, or pass --discard-worktree to remove the worktree instead`);
|
|
7890
8810
|
}
|
|
@@ -7927,29 +8847,31 @@ export function retireInstance(root, name, o = {}) {
|
|
|
7927
8847
|
});
|
|
7928
8848
|
stillIncomplete = ordinaryIncomplete;
|
|
7929
8849
|
}
|
|
8850
|
+
let branchDeletedByRetry = false, branchKeptReason;
|
|
7930
8851
|
if (quarantine) {
|
|
7931
8852
|
const failures = [...retryFailures];
|
|
7932
8853
|
if (keptForRetry) failures.push(keptForRetry);
|
|
7933
8854
|
// The quarantine may exist BECAUSE Git cleanup failed, so a retry has to
|
|
7934
8855
|
// redo those steps and verify them — not just rerun hooks. No retire deletes a branch.
|
|
7935
8856
|
if (meta.work === "worktree" && meta.repo) {
|
|
7936
|
-
const gitProbe = (argv) => {
|
|
7937
|
-
try { return { ok: true, out: execFileSync(argv[0], argv.slice(1), { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }) }; }
|
|
7938
|
-
catch (e2) { return { ok: false, status: e2.status, err: String(e2.stderr ?? e2.message ?? "").trim() }; }
|
|
7939
|
-
};
|
|
7940
8857
|
// A worktree this retry removed (the step above ran) must be verified gone; one it retained or kept for
|
|
7941
8858
|
// the next retry stays registered by design. The removal is not attempted a second time here: only the
|
|
7942
8859
|
// worktree step removes, after its check of HEAD, so a worktree it failed to remove is still registered
|
|
7943
8860
|
// and the next retry goes through that step again.
|
|
8861
|
+
// Its commands run helper-free against the repository's common Git directory (workRepoGitDir).
|
|
8862
|
+
const gitDir = workRepoGitDir();
|
|
7944
8863
|
if (retention?.worktree === "removed") {
|
|
7945
|
-
const wtCanonical =
|
|
7946
|
-
|
|
7947
|
-
|
|
7948
|
-
if (!wtProbe.ok) failures.push(`git worktree ${wtCanonical}: could not verify removal (${wtProbe.err || "worktree list failed"})`);
|
|
8864
|
+
const wtCanonical = canonicalHomePath(workPath);
|
|
8865
|
+
let wtProbe;
|
|
8866
|
+
if (gitDir.error) wtProbe = { ok: false, err: gitDir.error };
|
|
7949
8867
|
else {
|
|
7950
|
-
|
|
7951
|
-
|
|
8868
|
+
try { gitRepoRun(gitDir.dir, ["worktree", "prune"]); } catch { /* the list below decides */ }
|
|
8869
|
+
wtProbe = gitRepoRead(gitDir.dir, ["worktree", "list", "--porcelain", "-z"]);
|
|
7952
8870
|
}
|
|
8871
|
+
if (!wtProbe.ok) failures.push(`git worktree ${wtCanonical}: could not verify removal (${wtProbe.err || "worktree list failed"})`);
|
|
8872
|
+
else if (parseWorktreeList(wtProbe.out).some((r) => canonicalHomePath(r.worktree) === wtCanonical)) failures.push(`git worktree ${wtCanonical}: still registered`);
|
|
8873
|
+
} else if (retention?.worktree === "absent" && removalUnverified !== undefined) {
|
|
8874
|
+
failures.push(`git worktree ${realPathOrNearest(workPath)}: could not verify removal (${removalUnverified})`);
|
|
7953
8875
|
}
|
|
7954
8876
|
// The branch is a debt only when the failed spawn's rollback still owes its deletion. A retry never
|
|
7955
8877
|
// deletes it: the debt is cleared only when the branch is shown to be gone. Git's quiet exit 1 is
|
|
@@ -7957,8 +8879,38 @@ export function retireInstance(root, name, o = {}) {
|
|
|
7957
8879
|
// "could not verify", and the debt stays. The text is never matched: this read can only err
|
|
7958
8880
|
// toward keeping the debt.
|
|
7959
8881
|
const owesBranch = (quarantine.cleanup.outstanding?.git || []).includes("branch");
|
|
8882
|
+
// The one exception (#796): a spawn killed while its worktree hooks ran never reached its own
|
|
8883
|
+
// compensation. Its marker carries `inProgress` (its process verified dead above) with the branch
|
|
8884
|
+
// and the commit the spawn created it at. Once the retire hooks ran and the worktree's removal is
|
|
8885
|
+
// verified, the retry finishes that compensation: an atomic compare-and-delete at that commit,
|
|
8886
|
+
// refused when the tip moved, the branch is checked out anywhere, or the ref cannot be read. A
|
|
8887
|
+
// branch still at its creation commit holds no work. Every other quarantine keeps the rule above.
|
|
8888
|
+
const ip = quarantine.inProgress;
|
|
8889
|
+
if (owesBranch && meta.branch && ip && ip.branch === meta.branch && inProgressUnverified) branchKeptReason = "the spawn's process or its hook group could not be verified gone (retired with --force)";
|
|
8890
|
+
else if (owesBranch && meta.branch && ip && ip.branch === meta.branch && /^[0-9a-f]{40,64}$/.test(String(ip.baseOid ?? "")) && retention?.worktree === "removed" && !failures.length) {
|
|
8891
|
+
const ref = `refs/heads/${meta.branch}`;
|
|
8892
|
+
// Retire's Git, bounded and helper-free (retireGit, #809): two reads, then the one write.
|
|
8893
|
+
const tip = retireGitProbe(meta.repo, ["rev-parse", "--verify", "--quiet", "--end-of-options", ref], { encoding: "utf8" });
|
|
8894
|
+
const list = retireGitProbe(meta.repo, ["worktree", "list", "--porcelain", "-z"], { encoding: "utf8" });
|
|
8895
|
+
const listOk = !list.error && list.status === 0;
|
|
8896
|
+
const checkedOut = listOk && list.stdout.split("\0").includes(`branch ${ref}`);
|
|
8897
|
+
if (tip.error || tip.status !== 0 || tip.stderr.length) branchKeptReason = "the branch could not be read";
|
|
8898
|
+
else if (tip.stdout.trim() !== ip.baseOid) branchKeptReason = `its tip moved from ${ip.baseOid.slice(0, 12)}, where the spawn created it`;
|
|
8899
|
+
else if (!listOk) branchKeptReason = "whether it is checked out could not be read";
|
|
8900
|
+
else if (checkedOut) branchKeptReason = "it is checked out in a worktree";
|
|
8901
|
+
else {
|
|
8902
|
+
const del = retireGitProbe(meta.repo, ["update-ref", "-d", ref, ip.baseOid], { encoding: "utf8" });
|
|
8903
|
+
if (del.error || del.status !== 0) branchKeptReason = `git refused to delete it (${String(del.stderr || del.error?.message || "").trim().split("\n")[0] || "update-ref failed"})`;
|
|
8904
|
+
else branchDeletedByRetry = true;
|
|
8905
|
+
}
|
|
8906
|
+
}
|
|
7960
8907
|
if (owesBranch && meta.branch) {
|
|
7961
|
-
|
|
8908
|
+
let br;
|
|
8909
|
+
if (gitDir.error) br = { error: new Error(gitDir.error) };
|
|
8910
|
+
else {
|
|
8911
|
+
try { gitRepoRun(gitDir.dir, ["rev-parse", "--verify", "--quiet", `refs/heads/${meta.branch}`]); br = { status: 0, stderr: "" }; }
|
|
8912
|
+
catch (e2) { br = { error: e2.status === undefined || e2.status === null ? e2 : undefined, status: e2.status, stderr: String(e2.stderr ?? "") }; }
|
|
8913
|
+
}
|
|
7962
8914
|
if (!br.error && br.status === 0) failures.push(FAILED_SPAWN_BRANCH_LEFT);
|
|
7963
8915
|
else if (br.error || br.status !== 1 || br.stderr.length) failures.push(`git branch ${meta.branch}: could not verify whether it still exists (${String(br.stderr ?? "").trim() || br.error?.message || `rev-parse exit ${br.status}`})`);
|
|
7964
8916
|
}
|
|
@@ -7975,6 +8927,33 @@ export function retireInstance(root, name, o = {}) {
|
|
|
7975
8927
|
} catch { /* the quarantine stands regardless */ }
|
|
7976
8928
|
}
|
|
7977
8929
|
}
|
|
8930
|
+
// An attached child whose `work` links to this home's work/ would dangle once
|
|
8931
|
+
// the worktree is re-homed (#718): each one this retire stopped is repointed
|
|
8932
|
+
// to the retained worktree, whether or not the home is then removed (the work
|
|
8933
|
+
// has left it either way). It is a write to another instance, so it comes
|
|
8934
|
+
// last, once the move is done and seen done: the worktree is at its new path
|
|
8935
|
+
// and nothing is left at work/. One that fails is a warning; the retire is
|
|
8936
|
+
// not undone. The child's AGENTS.md still names the old path.
|
|
8937
|
+
const relinkWarnings = [];
|
|
8938
|
+
if (retention?.worktree === "retained") {
|
|
8939
|
+
const present = (p) => { try { lstatSync(p); return true; } catch { return false; } };
|
|
8940
|
+
const moved = attachedKids.length > 0 && (() => { try { return lstatSync(retention.movedTo).isDirectory(); } catch { return false; } })() && !present(workPath);
|
|
8941
|
+
for (const kid of attachedKids) {
|
|
8942
|
+
// The attachment as it was found, still: attached, and the same link. One that changed is
|
|
8943
|
+
// someone else's now, and is left as it is.
|
|
8944
|
+
const still = (() => { try { return readJsonOrUndefined(join(kid.home, "instance.json"))?.work === "attached" && readlinkSync(join(kid.home, "work")) === kid.link; } catch { return false; } })();
|
|
8945
|
+
if (!still) {
|
|
8946
|
+
relinkWarnings.push(`${kid.instance}: its attachment changed during the retire, so its work was left as it is now and not repointed to the retained worktree ${retention.movedTo}; inspect ${join(kid.home, "work")}`);
|
|
8947
|
+
continue;
|
|
8948
|
+
}
|
|
8949
|
+
try {
|
|
8950
|
+
if (!moved) throw new Error(`the worktree was not seen at ${retention.movedTo} with nothing left at ${workPath}`);
|
|
8951
|
+
relinkAttachedWork(kid.home, retention.movedTo);
|
|
8952
|
+
} catch (e) {
|
|
8953
|
+
relinkWarnings.push(`${kid.instance}: its work link could not be repointed to the retained worktree ${retention.movedTo} (${e.message}) and still points at ${kid.link}; repoint it by hand: ln -sfn ${shq(retention.movedTo)} ${shq(join(kid.home, "work"))}`);
|
|
8954
|
+
}
|
|
8955
|
+
}
|
|
8956
|
+
}
|
|
7978
8957
|
// Forcing is the operator overriding the fail-closed default with their eyes
|
|
7979
8958
|
// open: the home goes, and what remains outstanding is reported rather than
|
|
7980
8959
|
// swallowed. Without this, a quarantine whose cleanup can never succeed (a
|
|
@@ -7993,8 +8972,8 @@ export function retireInstance(root, name, o = {}) {
|
|
|
7993
8972
|
rmSync(deferredRetireResultPath(found.home).replace(/\.json$/, ".log"), { force: true });
|
|
7994
8973
|
}
|
|
7995
8974
|
|
|
7996
|
-
const result = { retired: name, agent: found.agent.name, workRecovery, retention, extraWorktrees, worktreeRemoved: isWorktree && !!retention && retention.worktree !== "retained", branchDeleted: false, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, childrenStopped, capabilityMeta: hookResults?.meta, warnings: (() => {
|
|
7997
|
-
const w = [...(hookResults?.warnings || [])];
|
|
8975
|
+
const result = { retired: name, agent: found.agent.name, workRecovery, retention, extraWorktrees, worktreeRemoved: isWorktree && !!retention && retention.worktree !== "retained", branchDeleted: false, ...(branchDeletedByRetry || branchKeptReason ? { spawnCompensation: { branch: meta.branch, branchDeleted: branchDeletedByRetry, ...(branchKeptReason ? { reason: branchKeptReason } : {}) } } : {}), removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, childrenStopped, capabilityMeta: hookResults?.meta, warnings: (() => {
|
|
8976
|
+
const w = [...spawnGroupWarnings, ...(hookResults?.warnings || []), ...relinkWarnings];
|
|
7998
8977
|
if (o[OBSOLETE_DELETE_BRANCH]) w.push(OBSOLETE_DELETE_BRANCH_SENTENCE);
|
|
7999
8978
|
if (isCapturedHome(meta) && !quarantine) {
|
|
8000
8979
|
// A captured home retires through the workspace path; its captured retire hooks do not
|
|
@@ -8005,6 +8984,7 @@ export function retireInstance(root, name, o = {}) {
|
|
|
8005
8984
|
} else if (!Array.isArray(meta?.capabilityRuntime) && !quarantine) w.push("this home records no capability hooks (an earlier kernel spawned it): no retire hook ran; any external state its capabilities created is the operator's to clean up");
|
|
8006
8985
|
return w.length ? w : undefined;
|
|
8007
8986
|
})() };
|
|
8987
|
+
result[RETIRE_SELECTED_HOME] = found.home;
|
|
8008
8988
|
if (self) {
|
|
8009
8989
|
// The caller is the instance: its process lives in the window we are about to
|
|
8010
8990
|
// kill. Detach the kill so this function can return and the caller can report
|