pi-legion 0.16.0 → 2.0.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/CONTRIBUTING.md +58 -0
- package/README.md +313 -640
- package/agents/advisor.md +7 -5
- package/agents/centurion.md +53 -0
- package/agents/designer.md +33 -33
- package/agents/planner.md +1 -2
- package/agents/prototype.md +2 -2
- package/agents/reviewer.md +67 -31
- package/agents/scout.md +6 -2
- package/agents/worker.md +12 -3
- package/docs/contracts/esc-abort-v1.md +131 -0
- package/docs/contracts/esc-cascade-v2.md +100 -0
- package/docs/design.md +44 -25
- package/docs/legion-v2-contract.md +461 -0
- package/docs/legion-v2-delivery.md +62 -0
- package/docs/retire-hardening-contract.md +125 -0
- package/docs/subagents-teams.md +76 -0
- package/docs/tui-viewer-contract.md +276 -0
- package/docs/vexillatio-contract.md +162 -0
- package/index.ts +1462 -286
- package/package.json +12 -9
- package/skills/pi-legion/SKILL.md +74 -96
- package/src/agents/agents.ts +6 -11
- package/src/agents/overrides.ts +2 -1
- package/src/agents/paths.ts +1 -1
- package/src/agents/settings.ts +268 -20
- package/src/api.ts +47 -48
- package/src/{herdr → backends/legacy}/client.ts +14 -69
- package/src/{shared → backends/legacy}/cursor-chat.ts +2 -2
- package/src/{herdr → backends/legacy}/runner.ts +22 -9
- package/src/backends/legacy/types.ts +138 -0
- package/src/extension/auto-doctor.ts +144 -0
- package/src/extension/budget.ts +2 -2
- package/src/extension/child-guard.ts +214 -201
- package/src/extension/event-bus.ts +263 -0
- package/src/extension/legion-commands.ts +719 -0
- package/src/extension/legion-doctor.ts +888 -0
- package/src/extension/legion-stop.ts +150 -0
- package/src/extension/legion-tools.ts +816 -0
- package/src/extension/notify.ts +24 -19
- package/src/extension/playbook.ts +20 -89
- package/src/extension/recycle.ts +2 -7
- package/src/extension/runtime.ts +655 -105
- package/src/extension/scout-guard.ts +483 -0
- package/src/extension/slash.ts +89 -438
- package/src/extension/spawn-hints.ts +79 -0
- package/src/extension/summary.ts +17 -58
- package/src/legion/budget.ts +165 -0
- package/src/legion/db.ts +242 -0
- package/src/legion/events.ts +150 -0
- package/src/legion/mail.ts +412 -0
- package/src/legion/nodes.ts +461 -0
- package/src/legion/rebuild.ts +533 -0
- package/src/legion/state-machine.ts +313 -0
- package/src/legion/usage.ts +101 -0
- package/src/runs/acceptance.ts +82 -25
- package/src/runs/args.ts +51 -5
- package/src/runs/hygiene.ts +335 -0
- package/src/runs/orchestrator.ts +790 -1683
- package/src/runs/owner.ts +61 -0
- package/src/runs/provision.ts +135 -0
- package/src/runs/store.ts +44 -17
- package/src/runs/verify-queue.ts +195 -0
- package/src/shared/name.ts +29 -0
- package/src/shared/output-cap.ts +57 -0
- package/src/shared/progress.ts +57 -135
- package/src/shared/session.ts +243 -171
- package/src/shared/types.ts +107 -208
- package/src/supervisor/child-memory.ts +140 -0
- package/src/supervisor/proc-tree.ts +103 -0
- package/src/supervisor/rpc-supervisor.ts +1033 -0
- package/src/supervisor/types.ts +153 -0
- package/src/supervisor/ui-proxy.ts +226 -0
- package/src/tui/chat-items.ts +330 -0
- package/src/tui/live-overlay.ts +874 -0
- package/src/tui/status.ts +553 -27
- package/src/tui/tree-view.ts +808 -0
- package/src/tui/viz/canvas.ts +119 -0
- package/src/tui/viz/layout.ts +111 -0
- package/src/tui/viz/model.ts +123 -0
- package/src/tui/viz/palette.ts +188 -0
- package/src/tui/viz/panels.ts +530 -0
- package/src/tui/viz/railway.ts +313 -0
- package/src/tui/viz/rate.ts +211 -0
- package/src/tui/viz/view.ts +228 -0
- package/src/extension/parent-label.ts +0 -115
- package/src/profiles/classify.ts +0 -375
- package/src/profiles/profiles.ts +0 -730
- package/src/runs/layout.ts +0 -258
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Process-ownership markers for run dirs and RPC child temp dirs (#38).
|
|
3
|
+
*
|
|
4
|
+
* The parent writes its pid next to the state it owns. A later session's
|
|
5
|
+
* startup sweep only touches state whose owner pid is gone, so concurrent pi
|
|
6
|
+
* sessions in the same project never clean up each other's live data.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import * as fs from "node:fs";
|
|
10
|
+
import * as os from "node:os";
|
|
11
|
+
import * as path from "node:path";
|
|
12
|
+
|
|
13
|
+
export const RUN_OWNER_FILE = "owner.json";
|
|
14
|
+
export const TEMP_OWNER_FILE = ".owner";
|
|
15
|
+
|
|
16
|
+
export interface OwnerRecord {
|
|
17
|
+
pid: number;
|
|
18
|
+
host: string;
|
|
19
|
+
at: number;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export function writeOwnerFile(file: string, pid: number = process.pid): void {
|
|
23
|
+
const record: OwnerRecord = { pid, host: os.hostname(), at: Date.now() };
|
|
24
|
+
fs.writeFileSync(file, `${JSON.stringify(record)}\n`, { mode: 0o600 });
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export function writeRunOwner(runDir: string, pid: number = process.pid): void {
|
|
28
|
+
writeOwnerFile(path.join(runDir, RUN_OWNER_FILE), pid);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export function readOwnerFile(file: string): OwnerRecord | undefined {
|
|
32
|
+
try {
|
|
33
|
+
const raw = JSON.parse(fs.readFileSync(file, "utf8")) as Partial<OwnerRecord>;
|
|
34
|
+
if (typeof raw.pid !== "number" || !Number.isSafeInteger(raw.pid) || raw.pid <= 0) return undefined;
|
|
35
|
+
return { pid: raw.pid, host: typeof raw.host === "string" ? raw.host : "", at: typeof raw.at === "number" ? raw.at : 0 };
|
|
36
|
+
} catch {
|
|
37
|
+
return undefined;
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** True when `pid` names a live process (EPERM still means "exists"). */
|
|
42
|
+
export function isPidAlive(pid: number): boolean {
|
|
43
|
+
if (!Number.isSafeInteger(pid) || pid <= 0) return false;
|
|
44
|
+
try {
|
|
45
|
+
process.kill(pid, 0);
|
|
46
|
+
return true;
|
|
47
|
+
} catch (error) {
|
|
48
|
+
return (error as NodeJS.ErrnoException).code === "EPERM";
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* Ownership verdict for a marker file: "live" (owner running, or on another
|
|
54
|
+
* host so we cannot tell), "dead" (owner gone), or "unknown" (no marker).
|
|
55
|
+
*/
|
|
56
|
+
export function ownerState(file: string, alive: (pid: number) => boolean = isPidAlive): "live" | "dead" | "unknown" {
|
|
57
|
+
const owner = readOwnerFile(file);
|
|
58
|
+
if (!owner) return "unknown";
|
|
59
|
+
if (owner.host && owner.host !== os.hostname()) return "live";
|
|
60
|
+
return alive(owner.pid) ? "live" : "dead";
|
|
61
|
+
}
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Post-create provisioning for child worktrees.
|
|
3
|
+
*
|
|
4
|
+
* A fresh `git worktree add` is a bare checkout: no `node_modules`, no
|
|
5
|
+
* language-specific dependency state. Children then spend turns (observed
|
|
6
|
+
* in the wild: repeated ln -s / unlink dances) recreating the environment
|
|
7
|
+
* before they can run the project's own verifier — and plugin-run verify
|
|
8
|
+
* commands would fail red for the wrong reason.
|
|
9
|
+
*
|
|
10
|
+
* `worktreeBootstrap` (legion settings) declares how to prepare the tree:
|
|
11
|
+
* - "npm-install": run the repo's own install command if a package
|
|
12
|
+
* manager manifest is present (npm ci / npm install fallback).
|
|
13
|
+
* - any other non-empty string: an arbitrary shell command, run with
|
|
14
|
+
* bash -lc in the worktree cwd (e.g. "pnpm install --frozen-lockfile",
|
|
15
|
+
* "ln -sfn ../../node_modules ./node_modules").
|
|
16
|
+
*
|
|
17
|
+
* Idempotency: a marker file (`.pi-provisioned`, JSON with the applied mode)
|
|
18
|
+
* makes provisioning a no-op on resume of the same worktree. Failure throws
|
|
19
|
+
* SubagentError; the orchestrator's existing launch rollback removes the
|
|
20
|
+
* whole worktree, so provisioning never leaves a half-prepared tree behind.
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
import { execFileSync } from "node:child_process";
|
|
24
|
+
import * as fs from "node:fs";
|
|
25
|
+
import * as path from "node:path";
|
|
26
|
+
import { ErrorCodes, SubagentError } from "../shared/types.ts";
|
|
27
|
+
|
|
28
|
+
export const PROVISION_MARKER = ".pi-provisioned";
|
|
29
|
+
|
|
30
|
+
export const BOOTSTRAP_MODE_INSTALL = "npm-install";
|
|
31
|
+
|
|
32
|
+
export interface ProvisionResult {
|
|
33
|
+
/** Mode actually applied, or "skip" when the marker was already present. */
|
|
34
|
+
applied: string;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
export function provisionMarkerPath(worktreePath: string): string {
|
|
38
|
+
return path.join(worktreePath, PROVISION_MARKER);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
function readMarker(worktreePath: string): { mode?: string } | null {
|
|
42
|
+
try {
|
|
43
|
+
return JSON.parse(
|
|
44
|
+
fs.readFileSync(provisionMarkerPath(worktreePath), "utf8"),
|
|
45
|
+
) as { mode?: string };
|
|
46
|
+
} catch {
|
|
47
|
+
return null;
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
function writeMarker(worktreePath: string, mode: string): void {
|
|
52
|
+
const file = provisionMarkerPath(worktreePath);
|
|
53
|
+
const payload = JSON.stringify({ mode, at: new Date().toISOString() });
|
|
54
|
+
// Atomic tmp+rename (same shape as the RunStore): a partial marker would
|
|
55
|
+
// let a later resume skip provisioning on a half-prepared tree.
|
|
56
|
+
const tmp = `${file}.tmp`;
|
|
57
|
+
fs.writeFileSync(tmp, payload, { mode: 0o600 });
|
|
58
|
+
fs.renameSync(tmp, file);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** Repo-relative manifests, in resolution order, for the npm-install mode. */
|
|
62
|
+
function installCommandFor(worktreePath: string): string | null {
|
|
63
|
+
if (fs.existsSync(path.join(worktreePath, "pnpm-lock.yaml"))) {
|
|
64
|
+
return "pnpm install --frozen-lockfile";
|
|
65
|
+
}
|
|
66
|
+
if (fs.existsSync(path.join(worktreePath, "bun.lockb"))) {
|
|
67
|
+
return "bun install --frozen-lockfile";
|
|
68
|
+
}
|
|
69
|
+
if (fs.existsSync(path.join(worktreePath, "yarn.lock"))) {
|
|
70
|
+
return "yarn install --frozen-lockfile";
|
|
71
|
+
}
|
|
72
|
+
if (fs.existsSync(path.join(worktreePath, "package-lock.json"))) {
|
|
73
|
+
return "npm ci";
|
|
74
|
+
}
|
|
75
|
+
if (fs.existsSync(path.join(worktreePath, "package.json"))) {
|
|
76
|
+
return "npm install";
|
|
77
|
+
}
|
|
78
|
+
return null;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
function shellEnv(): NodeJS.ProcessEnv {
|
|
82
|
+
const env = { ...process.env };
|
|
83
|
+
delete env.npm_config_prefix;
|
|
84
|
+
return env;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
function resolveCommand(mode: string, worktreePath: string): string | null {
|
|
88
|
+
if (mode === BOOTSTRAP_MODE_INSTALL) return installCommandFor(worktreePath);
|
|
89
|
+
const trimmed = mode.trim();
|
|
90
|
+
return trimmed ? trimmed : null;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Prepare a freshly created worktree according to `mode`.
|
|
95
|
+
* A missing/blank mode is a no-op (provisioning is opt-in); so is a marker
|
|
96
|
+
* from a previous provisioning pass, so resume never re-installs.
|
|
97
|
+
*/
|
|
98
|
+
export function provisionWorktree(opts: {
|
|
99
|
+
worktreePath: string;
|
|
100
|
+
mode?: string;
|
|
101
|
+
timeoutMs?: number;
|
|
102
|
+
}): ProvisionResult {
|
|
103
|
+
const mode = (opts.mode ?? "").trim();
|
|
104
|
+
if (!mode) return { applied: "skip" };
|
|
105
|
+
const marker = readMarker(opts.worktreePath);
|
|
106
|
+
if (marker?.mode === mode) return { applied: "skip" };
|
|
107
|
+
|
|
108
|
+
const command = resolveCommand(mode, opts.worktreePath);
|
|
109
|
+
// npm-install with no manifest: a repo with nothing to install is
|
|
110
|
+
// provisioned by definition — record the marker and move on.
|
|
111
|
+
if (!command) {
|
|
112
|
+
writeMarker(opts.worktreePath, mode);
|
|
113
|
+
return { applied: mode };
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
try {
|
|
117
|
+
execFileSync("bash", ["-lc", command], {
|
|
118
|
+
cwd: opts.worktreePath,
|
|
119
|
+
stdio: ["ignore", "pipe", "pipe"],
|
|
120
|
+
timeout: opts.timeoutMs ?? 600_000,
|
|
121
|
+
// npm lifecycle scripts export npm_config_prefix. A login shell
|
|
122
|
+
// that sources nvm then refuses to start and `npm` disappears
|
|
123
|
+
// from PATH. Local installs do not need that prefix.
|
|
124
|
+
env: shellEnv(),
|
|
125
|
+
});
|
|
126
|
+
} catch (error) {
|
|
127
|
+
const detail = error instanceof Error ? error.message : String(error);
|
|
128
|
+
throw new SubagentError(
|
|
129
|
+
`worktree bootstrap failed (${mode}): ${detail.slice(0, 500)}`,
|
|
130
|
+
ErrorCodes.START_FAILED,
|
|
131
|
+
);
|
|
132
|
+
}
|
|
133
|
+
writeMarker(opts.worktreePath, mode);
|
|
134
|
+
return { applied: mode };
|
|
135
|
+
}
|
package/src/runs/store.ts
CHANGED
|
@@ -18,6 +18,7 @@
|
|
|
18
18
|
import * as fs from "node:fs";
|
|
19
19
|
import * as path from "node:path";
|
|
20
20
|
import { randomBytes } from "node:crypto";
|
|
21
|
+
import { writeRunOwner } from "./owner.ts";
|
|
21
22
|
import {
|
|
22
23
|
MAX_NESTED_PATH_ENTRIES,
|
|
23
24
|
SubagentError,
|
|
@@ -27,6 +28,12 @@ import {
|
|
|
27
28
|
type RunRecord,
|
|
28
29
|
} from "../shared/types.ts";
|
|
29
30
|
|
|
31
|
+
/** M2 tree identity is an additive field on persisted v1 run/child records. */
|
|
32
|
+
declare module "../shared/types.ts" {
|
|
33
|
+
interface ChildRecord { nodeId?: string; }
|
|
34
|
+
interface RunRecord { nodeId?: string; }
|
|
35
|
+
}
|
|
36
|
+
|
|
30
37
|
export interface StoreOptions {
|
|
31
38
|
rootDir: string;
|
|
32
39
|
/** Injectable clock (ms epoch) for tests. Defaults to Date.now. */
|
|
@@ -39,7 +46,7 @@ const CORRUPT_SUFFIX = ".corrupt";
|
|
|
39
46
|
const ARTIFACT_DIR = "out";
|
|
40
47
|
const SESSION_EXT = ".jsonl";
|
|
41
48
|
|
|
42
|
-
/** 16 hex chars of entropy
|
|
49
|
+
/** 16 hex chars of entropy give each persisted child a stable owner token. */
|
|
43
50
|
function newOwnerToken(): string {
|
|
44
51
|
return randomBytes(8).toString("hex");
|
|
45
52
|
}
|
|
@@ -80,17 +87,14 @@ export function sanitizeNameForFs(name: string): string {
|
|
|
80
87
|
}
|
|
81
88
|
|
|
82
89
|
/**
|
|
83
|
-
* Resolve a child handle across runs
|
|
90
|
+
* Resolve a child handle across runs within the current cwd.
|
|
84
91
|
*
|
|
85
|
-
* Names are reused after
|
|
86
|
-
*
|
|
87
|
-
* retired record. Filter by `parentPaneId` when we have one, then prefer a
|
|
88
|
-
* live child, then the newest run.
|
|
92
|
+
* Names are reused after retirement, so prefer a live child and then the newest
|
|
93
|
+
* run record. The v2 RPC name registry replaces parent-pane scoping.
|
|
89
94
|
*/
|
|
90
95
|
export function pickChildByName(
|
|
91
96
|
runs: readonly RunRecord[],
|
|
92
97
|
name: string,
|
|
93
|
-
opts?: { parentPaneId?: string },
|
|
94
98
|
): { run: RunRecord; child: ChildRecord } | null {
|
|
95
99
|
const matches: Array<{ run: RunRecord; child: ChildRecord }> = [];
|
|
96
100
|
for (const run of runs) {
|
|
@@ -99,16 +103,10 @@ export function pickChildByName(
|
|
|
99
103
|
}
|
|
100
104
|
if (matches.length === 0) return null;
|
|
101
105
|
|
|
102
|
-
const
|
|
103
|
-
const pool = owner
|
|
104
|
-
? matches.filter((m) => m.run.herdr.parentPaneId === owner)
|
|
105
|
-
: matches;
|
|
106
|
-
if (pool.length === 0) return null;
|
|
107
|
-
|
|
108
|
-
const live = pool.filter(
|
|
106
|
+
const live = matches.filter(
|
|
109
107
|
(m) => m.child.state !== "retired" && m.child.state !== "exited",
|
|
110
108
|
);
|
|
111
|
-
const pickFrom = live.length > 0 ? live :
|
|
109
|
+
const pickFrom = live.length > 0 ? live : matches;
|
|
112
110
|
const ranked = [...pickFrom].sort((a, b) =>
|
|
113
111
|
b.run.createdAt.localeCompare(a.run.createdAt),
|
|
114
112
|
);
|
|
@@ -139,6 +137,7 @@ export class RunStore {
|
|
|
139
137
|
private readonly nowFn: () => number;
|
|
140
138
|
/** Per-runId write mutex: maps runId → tail of the write chain. */
|
|
141
139
|
private readonly locks = new Map<string, Promise<unknown>>();
|
|
140
|
+
private readonly ownedRuns = new Set<string>();
|
|
142
141
|
|
|
143
142
|
constructor(opts: StoreOptions) {
|
|
144
143
|
if (!opts.rootDir || typeof opts.rootDir !== "string") {
|
|
@@ -253,6 +252,7 @@ export class RunStore {
|
|
|
253
252
|
cwd: string;
|
|
254
253
|
path?: NestedPathEntry[];
|
|
255
254
|
maxDepth?: number;
|
|
255
|
+
nodeId?: string;
|
|
256
256
|
herdr?: RunRecord["herdr"];
|
|
257
257
|
}): RunRecord {
|
|
258
258
|
if (typeof input.task !== "string" || input.task.length === 0) {
|
|
@@ -273,10 +273,14 @@ export class RunStore {
|
|
|
273
273
|
runId: newRunId(),
|
|
274
274
|
task: input.task,
|
|
275
275
|
cwd: input.cwd,
|
|
276
|
-
|
|
276
|
+
...(input.nodeId ? { nodeId: input.nodeId } : {}),
|
|
277
|
+
herdr: {
|
|
278
|
+
...(input.herdr ?? {}),
|
|
279
|
+
...(input.nodeId ? { node_id: input.nodeId } : {}),
|
|
280
|
+
},
|
|
277
281
|
path: (input.path ?? []).slice(0, MAX_NESTED_PATH_ENTRIES),
|
|
278
282
|
depth: input.path?.length ?? 0,
|
|
279
|
-
maxDepth: input.maxDepth ??
|
|
283
|
+
maxDepth: input.maxDepth ?? MAX_NESTED_PATH_ENTRIES,
|
|
280
284
|
children: [],
|
|
281
285
|
budget: { spawned: 0, limit: null, granted: 0 },
|
|
282
286
|
createdAt: nowIso,
|
|
@@ -298,6 +302,16 @@ export class RunStore {
|
|
|
298
302
|
this.runFile(record.runId),
|
|
299
303
|
`${JSON.stringify(record, null, "\t")}\n`,
|
|
300
304
|
);
|
|
305
|
+
// Record which process last wrote this run so the startup sweep (#38)
|
|
306
|
+
// can tell a live concurrent session from a hard-killed one.
|
|
307
|
+
if (!this.ownedRuns.has(record.runId)) {
|
|
308
|
+
try {
|
|
309
|
+
writeRunOwner(path.dirname(this.runFile(record.runId)));
|
|
310
|
+
this.ownedRuns.add(record.runId);
|
|
311
|
+
} catch {
|
|
312
|
+
// best effort: a missing owner file only makes the sweep more conservative
|
|
313
|
+
}
|
|
314
|
+
}
|
|
301
315
|
}
|
|
302
316
|
|
|
303
317
|
/**
|
|
@@ -383,6 +397,19 @@ export class RunStore {
|
|
|
383
397
|
});
|
|
384
398
|
}
|
|
385
399
|
|
|
400
|
+
async removeChild(runId: string, name: string, expectedNodeId?: string): Promise<RunRecord> {
|
|
401
|
+
return this.updateRun(runId, (run) => {
|
|
402
|
+
const index = run.children.findIndex((child) => child.name === name);
|
|
403
|
+
if (index < 0) return;
|
|
404
|
+
const existing = run.children[index]!;
|
|
405
|
+
if (expectedNodeId !== undefined && existing.nodeId !== expectedNodeId) {
|
|
406
|
+
throw new SubagentError(`child identity mismatch while removing ${name}`, ErrorCodes.INVALID_PARAMS);
|
|
407
|
+
}
|
|
408
|
+
run.children.splice(index, 1);
|
|
409
|
+
run.budget.spawned = Math.max(0, run.budget.spawned - 1);
|
|
410
|
+
});
|
|
411
|
+
}
|
|
412
|
+
|
|
386
413
|
async updateChild(
|
|
387
414
|
runId: string,
|
|
388
415
|
name: string,
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tree-wide (machine-wide by default) concurrency limit for acceptance /
|
|
3
|
+
* verify commands. Each verify (`npm test`, `tsc`, …) can peak near 1 GB, so N
|
|
4
|
+
* workers verifying at once is the dominant memory spike.
|
|
5
|
+
*
|
|
6
|
+
* Cross-process semaphore: `limit` slot files `slot-<i>.lock` in a shared dir,
|
|
7
|
+
* acquired with O_EXCL create. A holder records its pid; a slot whose holder
|
|
8
|
+
* pid is dead (crash / SIGKILL) is reclaimed. Waiters poll; the wait is not
|
|
9
|
+
* counted against the command timeout but is capped overall — past the cap the
|
|
10
|
+
* command runs anyway (a hung-but-alive holder must not deadlock the tree).
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import * as fs from "node:fs";
|
|
14
|
+
import * as os from "node:os";
|
|
15
|
+
import * as path from "node:path";
|
|
16
|
+
import { isPidAlive, readOwnerFile } from "./owner.ts";
|
|
17
|
+
|
|
18
|
+
export const VERIFY_CONCURRENCY_ENV = "PI_LEGION_VERIFY_CONCURRENCY";
|
|
19
|
+
export const VERIFY_QUEUE_MAX_MS_ENV = "PI_LEGION_VERIFY_QUEUE_MAX_MS";
|
|
20
|
+
export const VERIFY_LOCK_DIR_ENV = "PI_LEGION_VERIFY_LOCK_DIR";
|
|
21
|
+
export const DEFAULT_VERIFY_CONCURRENCY = 2;
|
|
22
|
+
export const DEFAULT_VERIFY_QUEUE_MAX_MS = 30 * 60_000;
|
|
23
|
+
const POLL_MS = 500;
|
|
24
|
+
|
|
25
|
+
export interface VerifyQueueConfig {
|
|
26
|
+
limit: number;
|
|
27
|
+
maxWaitMs: number;
|
|
28
|
+
lockDir: string;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export function resolveVerifyQueueConfig(env: NodeJS.ProcessEnv = process.env): VerifyQueueConfig {
|
|
32
|
+
const num = (key: string, fallback: number) => {
|
|
33
|
+
const raw = env[key]?.trim();
|
|
34
|
+
const n = raw ? Number(raw) : NaN;
|
|
35
|
+
return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
|
|
36
|
+
};
|
|
37
|
+
const uid = typeof process.getuid === "function" ? process.getuid() : os.userInfo().username;
|
|
38
|
+
return {
|
|
39
|
+
limit: num(VERIFY_CONCURRENCY_ENV, DEFAULT_VERIFY_CONCURRENCY),
|
|
40
|
+
maxWaitMs: num(VERIFY_QUEUE_MAX_MS_ENV, DEFAULT_VERIFY_QUEUE_MAX_MS),
|
|
41
|
+
lockDir: env[VERIFY_LOCK_DIR_ENV]?.trim() || path.join(os.tmpdir(), `pi-legion-verify-${uid}`),
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
export interface VerifyQueueEvent {
|
|
46
|
+
phase: "waiting" | "acquired" | "released" | "overflow";
|
|
47
|
+
command: string;
|
|
48
|
+
waitedMs: number;
|
|
49
|
+
holders: number;
|
|
50
|
+
limit: number;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
let listener: ((event: VerifyQueueEvent) => void) | undefined;
|
|
54
|
+
/** UI hook (root process): show "verify queued …" status. */
|
|
55
|
+
export function setVerifyQueueListener(fn: ((event: VerifyQueueEvent) => void) | undefined): void {
|
|
56
|
+
listener = fn;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
export interface VerifySlot {
|
|
60
|
+
waitedMs: number;
|
|
61
|
+
/** True when the overall wait cap expired and the command runs unthrottled. */
|
|
62
|
+
overflow: boolean;
|
|
63
|
+
release(): void;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
function tryAcquire(file: string, command: string): boolean {
|
|
67
|
+
try {
|
|
68
|
+
const fd = fs.openSync(file, "wx", 0o600);
|
|
69
|
+
fs.writeSync(fd, `${JSON.stringify({ pid: process.pid, host: os.hostname(), at: Date.now(), command: command.slice(0, 200) })}\n`);
|
|
70
|
+
fs.closeSync(fd);
|
|
71
|
+
return true;
|
|
72
|
+
} catch (error) {
|
|
73
|
+
if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
|
|
74
|
+
}
|
|
75
|
+
// Reclaim a slot whose holder process is gone (crash, SIGKILL, reboot).
|
|
76
|
+
const owner = readOwnerFile(file);
|
|
77
|
+
const sameHost = !owner?.host || owner.host === os.hostname();
|
|
78
|
+
const stale = owner ? sameHost && !isPidAlive(owner.pid) : isOldUnreadable(file);
|
|
79
|
+
if (!stale) return false;
|
|
80
|
+
try { fs.unlinkSync(file); } catch { return false; }
|
|
81
|
+
return tryAcquire(file, command);
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** A slot file we cannot parse (torn write) is stale once it is a minute old. */
|
|
85
|
+
function isOldUnreadable(file: string): boolean {
|
|
86
|
+
try { return Date.now() - fs.statSync(file).mtimeMs > 60_000; } catch { return true; }
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
function countHolders(dir: string, limit: number): number {
|
|
90
|
+
let n = 0;
|
|
91
|
+
for (let i = 0; i < limit; i++) if (fs.existsSync(path.join(dir, `slot-${i}.lock`))) n++;
|
|
92
|
+
return n;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
export async function acquireVerifySlot(command: string, config: VerifyQueueConfig = resolveVerifyQueueConfig(), signal?: AbortSignal): Promise<VerifySlot> {
|
|
96
|
+
const noop: VerifySlot = { waitedMs: 0, overflow: false, release() {} };
|
|
97
|
+
if (config.limit <= 0) return noop;
|
|
98
|
+
try {
|
|
99
|
+
fs.mkdirSync(config.lockDir, { recursive: true, mode: 0o700 });
|
|
100
|
+
} catch {
|
|
101
|
+
return noop; // cannot coordinate: never block verification on the lock dir
|
|
102
|
+
}
|
|
103
|
+
const start = Date.now();
|
|
104
|
+
let announced = false;
|
|
105
|
+
for (;;) {
|
|
106
|
+
const offset = process.pid % config.limit; // spread first probes across slots
|
|
107
|
+
for (let k = 0; k < config.limit; k++) {
|
|
108
|
+
const file = path.join(config.lockDir, `slot-${(offset + k) % config.limit}.lock`);
|
|
109
|
+
let got = false;
|
|
110
|
+
try { got = tryAcquire(file, command); } catch { return noop; }
|
|
111
|
+
if (!got) continue;
|
|
112
|
+
const waitedMs = Date.now() - start;
|
|
113
|
+
listener?.({ phase: "acquired", command, waitedMs, holders: countHolders(config.lockDir, config.limit), limit: config.limit });
|
|
114
|
+
let released = false;
|
|
115
|
+
const release = () => {
|
|
116
|
+
if (released) return;
|
|
117
|
+
released = true;
|
|
118
|
+
process.removeListener("exit", release);
|
|
119
|
+
try {
|
|
120
|
+
if (readOwnerFile(file)?.pid === process.pid) fs.unlinkSync(file);
|
|
121
|
+
} catch { /* already gone */ }
|
|
122
|
+
listener?.({ phase: "released", command, waitedMs, holders: countHolders(config.lockDir, config.limit), limit: config.limit });
|
|
123
|
+
};
|
|
124
|
+
process.once("exit", release);
|
|
125
|
+
return { waitedMs, overflow: false, release };
|
|
126
|
+
}
|
|
127
|
+
const waitedMs = Date.now() - start;
|
|
128
|
+
if (waitedMs >= config.maxWaitMs || signal?.aborted) {
|
|
129
|
+
listener?.({ phase: "overflow", command, waitedMs, holders: config.limit, limit: config.limit });
|
|
130
|
+
return { waitedMs, overflow: true, release() {} };
|
|
131
|
+
}
|
|
132
|
+
if (!announced || waitedMs % 5_000 < POLL_MS) {
|
|
133
|
+
announced = true;
|
|
134
|
+
listener?.({ phase: "waiting", command, waitedMs, holders: countHolders(config.lockDir, config.limit), limit: config.limit });
|
|
135
|
+
}
|
|
136
|
+
await new Promise((resolve) => setTimeout(resolve, POLL_MS + Math.floor(Math.random() * 200)));
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/** Prefix for command output so the reader sees the queue wait. */
|
|
141
|
+
export function queueNote(slot: VerifySlot, limit: number): string {
|
|
142
|
+
if (slot.overflow) return `[verify queue: waited ${Math.round(slot.waitedMs / 1000)}s, cap reached — ran without a slot]\n`;
|
|
143
|
+
if (slot.waitedMs >= 1_000) return `[verify queue: waited ${Math.round(slot.waitedMs / 1000)}s for one of ${limit} slots]\n`;
|
|
144
|
+
return "";
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/** Read-only view of verify slot files for `/legion doctor`. */
|
|
148
|
+
export interface VerifySlotInfo {
|
|
149
|
+
index: number;
|
|
150
|
+
file: string;
|
|
151
|
+
pid?: number;
|
|
152
|
+
host?: string;
|
|
153
|
+
command?: string;
|
|
154
|
+
at?: number;
|
|
155
|
+
alive?: boolean;
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
export function inspectVerifySlots(config: VerifyQueueConfig = resolveVerifyQueueConfig()): {
|
|
159
|
+
config: VerifyQueueConfig;
|
|
160
|
+
holders: VerifySlotInfo[];
|
|
161
|
+
inUse: number;
|
|
162
|
+
} {
|
|
163
|
+
const holders: VerifySlotInfo[] = [];
|
|
164
|
+
if (config.limit <= 0) return { config, holders, inUse: 0 };
|
|
165
|
+
for (let i = 0; i < config.limit; i++) {
|
|
166
|
+
const file = path.join(config.lockDir, `slot-${i}.lock`);
|
|
167
|
+
if (!fs.existsSync(file)) continue;
|
|
168
|
+
let pid: number | undefined;
|
|
169
|
+
let host: string | undefined;
|
|
170
|
+
let command: string | undefined;
|
|
171
|
+
let at: number | undefined;
|
|
172
|
+
try {
|
|
173
|
+
const raw = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
|
|
174
|
+
if (typeof raw.pid === "number") pid = raw.pid;
|
|
175
|
+
if (typeof raw.host === "string") host = raw.host;
|
|
176
|
+
if (typeof raw.command === "string") command = raw.command;
|
|
177
|
+
if (typeof raw.at === "number") at = raw.at;
|
|
178
|
+
} catch {
|
|
179
|
+
const owner = readOwnerFile(file);
|
|
180
|
+
pid = owner?.pid;
|
|
181
|
+
host = owner?.host;
|
|
182
|
+
at = owner?.at;
|
|
183
|
+
}
|
|
184
|
+
holders.push({
|
|
185
|
+
index: i,
|
|
186
|
+
file,
|
|
187
|
+
pid,
|
|
188
|
+
host,
|
|
189
|
+
command,
|
|
190
|
+
at,
|
|
191
|
+
alive: typeof pid === "number" ? isPidAlive(pid) : undefined,
|
|
192
|
+
});
|
|
193
|
+
}
|
|
194
|
+
return { config, holders, inUse: holders.length };
|
|
195
|
+
}
|
package/src/shared/name.ts
CHANGED
|
@@ -47,3 +47,32 @@ export function makeName(agent: string, index: number): string {
|
|
|
47
47
|
// Defensive: if truncation somehow produced something invalid, fall back.
|
|
48
48
|
return VALID_NAME.test(name) ? name : `agent${suffix}`;
|
|
49
49
|
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* Allocate sibling names for a batch of agent roles under one parent (#42 / §2.6).
|
|
53
|
+
*
|
|
54
|
+
* Only `existing` (this parent's current children) and `isAlive` (in-process
|
|
55
|
+
* supervisor) constrain the sequence — historical runs from other sessions
|
|
56
|
+
* must not push the counter up.
|
|
57
|
+
*/
|
|
58
|
+
export function allocateSiblingNames(
|
|
59
|
+
agentNames: readonly string[],
|
|
60
|
+
existing: Iterable<string>,
|
|
61
|
+
isAlive: (name: string) => boolean = () => false,
|
|
62
|
+
): string[] {
|
|
63
|
+
const taken = new Set(existing);
|
|
64
|
+
const counters = new Map<string, number>();
|
|
65
|
+
const out: string[] = [];
|
|
66
|
+
for (const agent of agentNames) {
|
|
67
|
+
let index = counters.get(agent) ?? 0;
|
|
68
|
+
for (;; index += 1) {
|
|
69
|
+
const candidate = makeName(agent, index);
|
|
70
|
+
if (taken.has(candidate) || isAlive(candidate)) continue;
|
|
71
|
+
taken.add(candidate);
|
|
72
|
+
counters.set(agent, index + 1);
|
|
73
|
+
out.push(candidate);
|
|
74
|
+
break;
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
return out;
|
|
78
|
+
}
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Byte-capped accumulation for spawned-process output (#35).
|
|
3
|
+
*
|
|
4
|
+
* `spawn` + manual `data` concatenation has no built-in limit (Node's
|
|
5
|
+
* maxBuffer applies only to the exec* family), so a runaway command can
|
|
6
|
+
* exhaust host memory. Each stream is capped; on overflow the collector keeps
|
|
7
|
+
* the first `maxBytes` bytes, appends a truncation marker, and calls
|
|
8
|
+
* `onOverflow` once so the caller can kill the child.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
export const DEFAULT_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
|
|
12
|
+
export const MAX_OUTPUT_BYTES_ENV = "PI_LEGION_MAX_OUTPUT_BYTES";
|
|
13
|
+
|
|
14
|
+
/** Resolve the per-stream cap from env; garbage / <=0 → default. */
|
|
15
|
+
export function resolveMaxOutputBytes(env: NodeJS.ProcessEnv = process.env): number {
|
|
16
|
+
const raw = env[MAX_OUTPUT_BYTES_ENV]?.trim();
|
|
17
|
+
if (!raw) return DEFAULT_MAX_OUTPUT_BYTES;
|
|
18
|
+
const n = Number(raw);
|
|
19
|
+
return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_MAX_OUTPUT_BYTES;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
export interface CappedOutput {
|
|
23
|
+
push(chunk: Buffer | string): void;
|
|
24
|
+
readonly truncated: boolean;
|
|
25
|
+
readonly bytesSeen: number;
|
|
26
|
+
text(): string;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export function createCappedOutput(maxBytes: number, onOverflow?: () => void): CappedOutput {
|
|
30
|
+
const parts: Buffer[] = [];
|
|
31
|
+
let kept = 0;
|
|
32
|
+
let seen = 0;
|
|
33
|
+
let truncated = false;
|
|
34
|
+
return {
|
|
35
|
+
push(chunk) {
|
|
36
|
+
const buf = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
|
|
37
|
+
seen += buf.length;
|
|
38
|
+
if (truncated) return;
|
|
39
|
+
const room = maxBytes - kept;
|
|
40
|
+
if (buf.length <= room) {
|
|
41
|
+
parts.push(buf);
|
|
42
|
+
kept += buf.length;
|
|
43
|
+
return;
|
|
44
|
+
}
|
|
45
|
+
if (room > 0) parts.push(buf.subarray(0, room));
|
|
46
|
+
kept = maxBytes;
|
|
47
|
+
truncated = true;
|
|
48
|
+
onOverflow?.();
|
|
49
|
+
},
|
|
50
|
+
get truncated() { return truncated; },
|
|
51
|
+
get bytesSeen() { return seen; },
|
|
52
|
+
text() {
|
|
53
|
+
const body = Buffer.concat(parts).toString("utf8");
|
|
54
|
+
return truncated ? `${body}\n[output truncated: exceeded ${maxBytes} bytes; process killed]` : body;
|
|
55
|
+
},
|
|
56
|
+
};
|
|
57
|
+
}
|