@phren/cli 0.3.79 → 0.3.80

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.
Files changed (37) hide show
  1. package/dist/bridge/dispatch.js +17 -3
  2. package/dist/bridge/housekeeping/command.d.ts +5 -0
  3. package/dist/bridge/housekeeping/command.js +106 -0
  4. package/dist/bridge/housekeeping/housekeeper.d.ts +123 -0
  5. package/dist/bridge/housekeeping/housekeeper.js +459 -0
  6. package/dist/bridge/housekeeping/inventory.d.ts +145 -0
  7. package/dist/bridge/housekeeping/inventory.js +276 -0
  8. package/dist/bridge/housekeeping/report.d.ts +672 -0
  9. package/dist/bridge/housekeeping/report.js +168 -0
  10. package/dist/bridge/housekeeping/safety.d.ts +177 -0
  11. package/dist/bridge/housekeeping/safety.js +466 -0
  12. package/dist/bridge/owner-proof.js +1 -0
  13. package/dist/bridge/push.js +3 -1
  14. package/dist/bridge/resources.d.ts +8 -0
  15. package/dist/bridge/resources.js +18 -5
  16. package/dist/bridge/server-pane-routes.d.ts +6 -0
  17. package/dist/bridge/server-pane-routes.js +1 -1
  18. package/dist/bridge/server-routes.d.ts +5 -0
  19. package/dist/bridge/server-routes.js +44 -3
  20. package/dist/bridge/server.js +44 -8
  21. package/dist/bridge-hook.mjs +2980 -1226
  22. package/dist/cli-registry.js +18 -1
  23. package/dist/fanout/command.js +42 -15
  24. package/dist/heavy/budget-status.d.ts +26 -0
  25. package/dist/heavy/budget-status.js +26 -0
  26. package/dist/heavy/budget.d.ts +39 -0
  27. package/dist/heavy/budget.js +57 -0
  28. package/dist/heavy/command.d.ts +15 -0
  29. package/dist/heavy/command.js +119 -0
  30. package/dist/heavy/reap.d.ts +70 -0
  31. package/dist/heavy/reap.js +211 -0
  32. package/dist/heavy/slots.d.ts +58 -0
  33. package/dist/heavy/slots.js +142 -0
  34. package/dist/modules/registry.js +4 -3
  35. package/package.json +1 -1
  36. package/starter/global/skills/conductor/SKILL.md +10 -0
  37. package/starter/global/skills/fanout/SKILL.md +30 -0
@@ -0,0 +1,211 @@
1
+ import { execFile } from "node:child_process";
2
+ import * as fs from "node:fs";
3
+ import * as path from "node:path";
4
+ import { promisify } from "node:util";
5
+ import { parseEtime, parsePs, withStartTimes } from "../bridge/resources.js";
6
+ import { minutes, slotsRoot } from "./slots.js";
7
+ const exec = promisify(execFile);
8
+ const SHELLS = new Set(["sh", "bash", "zsh", "dash", "fish", "ksh"]);
9
+ const AGENTS = [[/^claude$|claude\/versions\//, "claude"], [/^codex(-.*)?$/, "codex"], [/^\.?opencode$/, "opencode"], [/^phren-agent$/, "phren agent"]];
10
+ /** What a process is, when it is something agents start and forget. */
11
+ export function classify(row, parentGone) {
12
+ const base = path.basename(row.command), args = row.args;
13
+ // `until ! pgrep -f text; do sleep 5; done`: pgrep sees this shell's own command line, so it never ends.
14
+ // `pgrep -x name` matches the program name only and is fine; `-f` is the one that matches itself.
15
+ if (SHELLS.has(base.replace(/^-/, "")) && /\b(?:until|while)\b.*\bpgrep\s+(?:-[a-zA-Z]*\s+)*-[a-zA-Z]*f/.test(args))
16
+ return { kind: "wait loop", name: "pgrep -f wait loop" };
17
+ if (/GradleDaemon|org\.gradle\.launcher\.daemon/.test(args))
18
+ return { kind: "build daemon", name: "Gradle daemon" };
19
+ if (/KotlinCompileDaemon|kotlin-daemon/.test(args))
20
+ return { kind: "build daemon", name: "Kotlin daemon" };
21
+ if (/\bturbo(?:\.exe)?\s+daemon\b/.test(args))
22
+ return { kind: "build daemon", name: "turbo daemon" };
23
+ if (/\btsc(?:\.js)?\b.*\s(?:--watch|-w)(?:\s|$)/.test(args))
24
+ return { kind: "build daemon", name: "tsc --watch" };
25
+ if (/\bvitest(?:\.mjs)?\b/.test(args) && !/\bvitest(?:\.mjs)?\s+(?:run|bench|list)\b|\s--run\b/.test(args) && !/\/vitest\/dist\/workers?\//.test(args))
26
+ return { kind: "test watcher", name: "vitest (watch)" };
27
+ if (/\bjest(?:\.js)?\b.*\s--watch(?:All)?\b/.test(args))
28
+ return { kind: "test watcher", name: "jest --watch" };
29
+ if (/\b(next|nuxt|astro|remix|storybook|wrangler)\b(?:\.m?js)?\s+dev\b/.test(args))
30
+ return { kind: "dev server", name: `${/\b(next|nuxt|astro|remix|storybook|wrangler)\b/.exec(args)[1]} dev` };
31
+ if (/\bvite(?:\.m?js)?\b(?!\s+build)/.test(args) && !/\bvitest\b/.test(args))
32
+ return { kind: "dev server", name: "vite" };
33
+ if (/webpack-dev-server|\bwebpack(?:\.js)?\s+serve\b/.test(args))
34
+ return { kind: "dev server", name: "webpack dev server" };
35
+ if (/\b(?:nodemon|tsx\s+watch)\b/.test(args))
36
+ return { kind: "dev server", name: /nodemon/.test(args) ? "nodemon" : "tsx watch" };
37
+ if (/\buvicorn\b.*--reload|\bpython3?\s+-m\s+http\.server\b|\brails\s+s(?:erver)?\b/.test(args))
38
+ return { kind: "dev server", name: base };
39
+ if (parentGone && /--headless\b/.test(args) && /chrom|firefox|headless_shell/i.test(row.command + args) && !/--type=/.test(args))
40
+ return { kind: "headless browser", name: "headless browser" };
41
+ return undefined;
42
+ }
43
+ /** The agent above a process, by ancestry or (Linux) by the session ids agents put in their children's environment. */
44
+ function startedBy(row, byPid, env) {
45
+ let current = byPid.get(row.ppid);
46
+ for (let depth = 0; current && depth < 24; depth++, current = byPid.get(current.ppid)) {
47
+ const base = path.basename(current.command);
48
+ const agent = AGENTS.find(([pattern]) => pattern.test(base) || pattern.test(current.command));
49
+ if (agent)
50
+ return `${agent[1]} (pid ${current.pid})`;
51
+ }
52
+ const vars = env(row.pid);
53
+ if (!vars)
54
+ return undefined;
55
+ const id = (name) => new RegExp(`(?:^|\\0)${name}=([^\\0]+)`).exec(vars)?.[1];
56
+ if (id("PHREN_FANOUT_JOB"))
57
+ return `fan-out worker ${id("PHREN_FANOUT_JOB")} (gone)`;
58
+ if (id("CLAUDE_CODE_SESSION_ID") || id("CLAUDECODE"))
59
+ return `claude session ${id("CLAUDE_CODE_SESSION_ID")?.slice(0, 8) ?? ""} (gone)`.replace(" ", " ");
60
+ if (id("CODEX_THREAD_ID") || id("CODEX_SESSION_ID"))
61
+ return `codex thread ${(id("CODEX_THREAD_ID") ?? id("CODEX_SESSION_ID")).slice(0, 8)} (gone)`;
62
+ return undefined;
63
+ }
64
+ /**
65
+ * Report rows from a process table. `cpu` is each pid's cumulative CPU
66
+ * seconds; `samples` is what an earlier report saw, so a process whose CPU
67
+ * time has not moved since is idle at least that long. Returns the samples to
68
+ * keep for next time. Without `all`, only work an agent started (or whose
69
+ * parent is gone) is listed.
70
+ */
71
+ export function reapRows(rows, options) {
72
+ const byPid = new Map(rows.map(row => [row.pid, row])), children = new Map();
73
+ for (const row of rows)
74
+ children.set(row.ppid, [...children.get(row.ppid) ?? [], row]);
75
+ const env = options.env ?? (() => undefined), samples = {}, found = [];
76
+ // The report's own shell and its callers are never listed: they are running this.
77
+ const claimed = new Set();
78
+ for (let pid = options.self, depth = 0; pid && pid > 1 && depth < 64; pid = byPid.get(pid)?.ppid, depth++)
79
+ claimed.add(pid);
80
+ for (const row of [...rows].sort((a, b) => a.pid - b.pid)) {
81
+ if (claimed.has(row.pid))
82
+ continue;
83
+ const parentGone = row.ppid <= 1 || !byPid.has(row.ppid);
84
+ const kind = classify(row, parentGone);
85
+ if (!kind)
86
+ continue;
87
+ const by = startedBy(row, byPid, env) ?? (parentGone ? "parent gone" : undefined);
88
+ if (!by && !options.all)
89
+ continue;
90
+ // A server's children (esbuild, workers) count toward it and are not listed again.
91
+ let rss = 0;
92
+ const stack = [row];
93
+ while (stack.length) {
94
+ const next = stack.pop();
95
+ claimed.add(next.pid);
96
+ rss += next.rssKB * 1024;
97
+ stack.push(...children.get(next.pid) ?? []);
98
+ }
99
+ const key = `${row.pid}:${row.startedAt ?? 0}`, cpuSeconds = options.cpu.get(row.pid);
100
+ let idleMs;
101
+ if (cpuSeconds !== undefined) {
102
+ const before = options.samples[key];
103
+ const since = before && before.cpuSeconds === cpuSeconds ? before.since : options.now;
104
+ samples[key] = { cpuSeconds, since };
105
+ if (before)
106
+ idleMs = options.now - since;
107
+ }
108
+ const ageMs = row.startedAt ? options.now - row.startedAt : undefined;
109
+ const cwd = options.cwd?.(row.pid);
110
+ const ancestors = [];
111
+ for (let up = byPid.get(row.ppid); up && ancestors.length < 64; up = byPid.get(up.ppid))
112
+ ancestors.push(up.pid);
113
+ const pane = [row.pid, ...ancestors].map(pid => options.owners?.get(pid)).find(Boolean);
114
+ found.push({ ...kind, pid: row.pid, ...(row.startedAt ? { startedAt: row.startedAt } : {}), ancestors, ...(pane ? { pane } : {}), ...(ageMs !== undefined ? { ageMs } : {}), ...(idleMs !== undefined ? { idleMs } : {}),
115
+ ...(ageMs && cpuSeconds !== undefined ? { cpuShare: Math.min(1, cpuSeconds * 1000 / ageMs) } : {}),
116
+ rssBytes: rss, by: by ?? "you", ...(cwd ? { cwd } : {}), stop: `kill ${row.pid}` });
117
+ }
118
+ found.sort((a, b) => (b.idleMs ?? -1) - (a.idleMs ?? -1) || (b.ageMs ?? 0) - (a.ageMs ?? 0));
119
+ return { rows: found, samples };
120
+ }
121
+ /** `ps -o pid=,time=` cumulative CPU: `[[dd-]hh:]mm:ss[.cc]`. */
122
+ export function parseCpuTimes(output) {
123
+ const cpu = new Map();
124
+ for (const line of output.split("\n")) {
125
+ const match = /^\s*(\d+)\s+(\S+)\s*$/.exec(line);
126
+ const seconds = match ? parseEtime(match[2].replace(/\.\d+$/, "")) : undefined;
127
+ if (match && seconds !== undefined)
128
+ cpu.set(Number(match[1]), seconds);
129
+ }
130
+ return cpu;
131
+ }
132
+ /** Databases cloned from a test template (`hub_test_797` beside `hub_test`): name, template, size and open connections. */
133
+ export function testClones(rows) {
134
+ const names = new Set(rows.map(row => row.name));
135
+ return rows.flatMap(row => {
136
+ // Strip `_suffix` parts until another database's name is left.
137
+ let template = /^(.*)_[a-z0-9]+$/i.exec(row.name)?.[1];
138
+ while (template && !names.has(template))
139
+ template = /^(.*)_[a-z0-9]+$/i.exec(template)?.[1];
140
+ if (!template || !/test/i.test(template))
141
+ return [];
142
+ return [{ name: row.name, template, ...(row.bytes !== undefined ? { bytes: row.bytes } : {}), connections: row.connections, stop: `dropdb '${row.name.replace(/'/g, "'\\''")}'` }];
143
+ });
144
+ }
145
+ async function postgresClones() {
146
+ const sql = "select datname, pg_database_size(datname), (select count(*) from pg_stat_activity a where a.datname = d.datname) from pg_database d where not datistemplate and datallowconn";
147
+ try {
148
+ const { stdout } = await exec("psql", ["-XAtq", "-F", "\t", "-d", "postgres", "-c", sql], { timeout: 5_000, env: { ...process.env, PGCONNECT_TIMEOUT: "3" } });
149
+ const rows = stdout.split("\n").filter(Boolean).map(line => { const [name, bytes, connections] = line.split("\t"); return { name, bytes: Number(bytes), connections: Number(connections) || 0 }; });
150
+ return { databases: testClones(rows) };
151
+ }
152
+ catch (error) {
153
+ const code = error.code;
154
+ return { databases: [], note: code === "ENOENT" ? "psql not installed; Postgres not checked" : "Postgres not reachable with psql's defaults (PGHOST, PGUSER); not checked" };
155
+ }
156
+ }
157
+ function samplesFile() { return path.join(path.dirname(slotsRoot()), "reap-samples.json"); }
158
+ export async function runReap(args) {
159
+ if (args.some(arg => arg !== "--json" && arg !== "--all"))
160
+ throw new Error("Usage: phren reap [--all] [--json]");
161
+ const ps = (format) => exec("/bin/ps", ["-axo", format], { timeout: 5_000, maxBuffer: 16 * 1024 * 1024, env: { ...process.env, LC_ALL: "C" } }).then(r => r.stdout);
162
+ const [stats, argv, elapsed, times] = await Promise.all([ps("pid=,ppid=,pgid=,pcpu=,rss=,comm="), ps("pid=,args="), ps("pid=,etime=").catch(() => ""), ps("pid=,time=").catch(() => "")]);
163
+ const now = Date.now(), rows = withStartTimes(parsePs(stats, argv), elapsed, now);
164
+ let previous = {};
165
+ try {
166
+ previous = JSON.parse(fs.readFileSync(samplesFile(), "utf8"));
167
+ }
168
+ catch { /* First report. */ }
169
+ const linux = process.platform === "linux";
170
+ const report = reapRows(rows, { now, cpu: parseCpuTimes(times), samples: previous, all: args.includes("--all"), self: process.pid,
171
+ env: pid => linux ? (() => { try {
172
+ return fs.readFileSync(`/proc/${pid}/environ`, "utf8");
173
+ }
174
+ catch {
175
+ return undefined;
176
+ } })() : undefined,
177
+ cwd: pid => linux ? (() => { try {
178
+ return fs.readlinkSync(`/proc/${pid}/cwd`);
179
+ }
180
+ catch {
181
+ return undefined;
182
+ } })() : undefined });
183
+ try {
184
+ fs.mkdirSync(path.dirname(samplesFile()), { recursive: true, mode: 0o700 });
185
+ fs.writeFileSync(samplesFile(), JSON.stringify(report.samples), { mode: 0o600 });
186
+ }
187
+ catch { /* Idle times start over next time. */ }
188
+ const pg = await postgresClones();
189
+ if (args.includes("--json")) {
190
+ console.log(JSON.stringify({ processes: report.rows, databases: pg.databases, ...(pg.note ? { note: pg.note } : {}) }, null, 2));
191
+ return 0;
192
+ }
193
+ const mb = (bytes) => bytes >= 1024 ** 3 ? `${(bytes / 1024 ** 3).toFixed(1)} GB` : `${Math.round(bytes / 1024 ** 2)} MB`;
194
+ if (!report.rows.length && !pg.databases.length)
195
+ console.log("Nothing left running by agents.");
196
+ for (const row of report.rows) {
197
+ const idle = row.idleMs !== undefined ? `idle ${minutes(row.idleMs)}` : `idle unknown${row.cpuShare !== undefined ? `, ${(row.cpuShare * 100).toFixed(1)}% CPU over its life` : ""}`;
198
+ console.log(`${row.kind}: ${row.name}, pid ${row.pid}, ${row.ageMs !== undefined ? `up ${minutes(row.ageMs)}` : "age unknown"}, ${idle}, ${mb(row.rssBytes)}, started by ${row.by}${row.cwd ? `, in ${row.cwd}` : ""}`);
199
+ console.log(` stop: ${row.stop}`);
200
+ }
201
+ for (const db of pg.databases) {
202
+ console.log(`test database: ${db.name} (clone of ${db.template})${db.bytes !== undefined ? `, ${mb(db.bytes)}` : ""}, ${db.connections} connection${db.connections === 1 ? "" : "s"}`);
203
+ console.log(` stop: ${db.stop}`);
204
+ }
205
+ if (pg.note)
206
+ console.log(pg.note);
207
+ if (report.rows.some(row => row.idleMs === undefined))
208
+ console.log("Idle time shows from the second report on: run phren reap again later.");
209
+ console.log("Nothing was stopped. Run the stop commands you want.");
210
+ return 0;
211
+ }
@@ -0,0 +1,58 @@
1
+ import { type Budget, type Pressure } from "./budget.js";
2
+ /**
3
+ * A computer-wide counting semaphore in a directory: one small JSON ticket per
4
+ * waiting or running job, ordered by priority and then arrival. Any shell on
5
+ * the computer joins it through `phren heavy`, and `phren fanout run` through
6
+ * its `workers` pool, so agents in different panes, harnesses and stores share
7
+ * one count. A ticket whose process is gone is dropped by the next reader, so
8
+ * a killed job never holds its slot.
9
+ */
10
+ export declare const PRIORITIES: {
11
+ readonly release: 2;
12
+ readonly normal: 1;
13
+ readonly low: 0;
14
+ };
15
+ export type PriorityName = keyof typeof PRIORITIES;
16
+ export interface Ticket {
17
+ id: string;
18
+ pid: number;
19
+ priority: number;
20
+ createdAt: number;
21
+ label: string;
22
+ state: "waiting" | "running";
23
+ startedAt?: number;
24
+ }
25
+ export declare function slotsRoot(env?: NodeJS.ProcessEnv): string;
26
+ export declare function priorityName(priority: number): PriorityName;
27
+ /** Tickets of a pool, with dead holders' and waiters' tickets removed. */
28
+ export declare function readTickets(dir: string, isAlive?: (pid: number) => boolean): Ticket[];
29
+ /** Waiters in the order they will start: release work first, then by arrival. */
30
+ export declare function queueOrder(tickets: readonly Ticket[]): Ticket[];
31
+ export declare function minutes(ms: number): string;
32
+ export interface AcquireOptions {
33
+ pool: string;
34
+ slots: number;
35
+ priority: number;
36
+ label: string;
37
+ budget: Budget;
38
+ pressure: () => Promise<Pressure | undefined>;
39
+ /** Called each time the reason for waiting changes, and once on start. */
40
+ report: (message: string) => void;
41
+ pollMs?: number;
42
+ timeoutMs?: number;
43
+ root?: string;
44
+ pid?: number;
45
+ now?: () => number;
46
+ sleep?: (ms: number) => Promise<void>;
47
+ }
48
+ export interface Held {
49
+ id: string;
50
+ release: () => void;
51
+ waitedMs: number;
52
+ }
53
+ /** Waits for a slot. Throws `QueueTimeout` after `timeoutMs`; the ticket is removed either way. */
54
+ export declare function acquire(options: AcquireOptions): Promise<Held>;
55
+ export declare class QueueTimeout extends Error {
56
+ }
57
+ export declare function poolStatus(pool: string, root?: string): Ticket[];
58
+ export declare function pools(root?: string): string[];
@@ -0,0 +1,142 @@
1
+ import { randomBytes } from "node:crypto";
2
+ import * as fs from "node:fs";
3
+ import { homedir } from "node:os";
4
+ import * as path from "node:path";
5
+ import { withFileLock } from "../governance/locks.js";
6
+ import { pressureReason } from "./budget.js";
7
+ /**
8
+ * A computer-wide counting semaphore in a directory: one small JSON ticket per
9
+ * waiting or running job, ordered by priority and then arrival. Any shell on
10
+ * the computer joins it through `phren heavy`, and `phren fanout run` through
11
+ * its `workers` pool, so agents in different panes, harnesses and stores share
12
+ * one count. A ticket whose process is gone is dropped by the next reader, so
13
+ * a killed job never holds its slot.
14
+ */
15
+ export const PRIORITIES = { release: 2, normal: 1, low: 0 };
16
+ export function slotsRoot(env = process.env) {
17
+ return env.PHREN_SLOTS_DIR || path.join(env.XDG_STATE_HOME || path.join(homedir(), ".local", "state"), "phren", "slots");
18
+ }
19
+ function alive(pid) {
20
+ try {
21
+ process.kill(pid, 0);
22
+ return true;
23
+ }
24
+ catch (error) {
25
+ return error.code === "EPERM";
26
+ }
27
+ }
28
+ export function priorityName(priority) {
29
+ return Object.keys(PRIORITIES).find(name => PRIORITIES[name] === priority) ?? "normal";
30
+ }
31
+ /** Tickets of a pool, with dead holders' and waiters' tickets removed. */
32
+ export function readTickets(dir, isAlive = alive) {
33
+ let names;
34
+ try {
35
+ names = fs.readdirSync(dir);
36
+ }
37
+ catch {
38
+ return [];
39
+ }
40
+ const tickets = [];
41
+ for (const name of names.filter(n => n.endsWith(".json"))) {
42
+ const file = path.join(dir, name);
43
+ try {
44
+ const ticket = JSON.parse(fs.readFileSync(file, "utf8"));
45
+ if (!Number.isInteger(ticket.pid) || !isAlive(ticket.pid)) {
46
+ fs.rmSync(file, { force: true });
47
+ continue;
48
+ }
49
+ tickets.push(ticket);
50
+ }
51
+ catch { /* Partly written or removed meanwhile. */ }
52
+ }
53
+ return tickets;
54
+ }
55
+ /** Waiters in the order they will start: release work first, then by arrival. */
56
+ export function queueOrder(tickets) {
57
+ return tickets.filter(t => t.state === "waiting").sort((a, b) => b.priority - a.priority || a.createdAt - b.createdAt || a.id.localeCompare(b.id));
58
+ }
59
+ /**
60
+ * Whether ticket `id` may start now. The pressure gate holds only while
61
+ * another job in the pool runs: with the pool empty the first job always
62
+ * starts (with a warning), so pressure from outside the pool can slow work
63
+ * but never stop it for good.
64
+ */
65
+ function decide(tickets, id, slots, pressure, budget, now = Date.now()) {
66
+ const running = tickets.filter(t => t.state === "running");
67
+ const order = queueOrder(tickets), position = order.findIndex(t => t.id === id);
68
+ const busy = running.map(t => `${t.label} (pid ${t.pid}, ${minutes(now - (t.startedAt ?? t.createdAt))})`).join(", ");
69
+ if (running.length >= slots)
70
+ return { start: false, reason: `all ${slots} slot${slots === 1 ? "" : "s"} busy: ${busy}` };
71
+ if (position > 0)
72
+ return { start: false, reason: `${position} job${position === 1 ? "" : "s"} ahead (${order.slice(0, position).map(t => `${t.label}, ${priorityName(t.priority)}`).join("; ")})` };
73
+ const pressed = pressure && pressureReason(pressure, budget);
74
+ if (pressed && running.length)
75
+ return { start: false, reason: `${pressed}; ${running.length} running: ${busy}` };
76
+ return pressed ? { start: true, warning: `${pressed}; starting anyway because nothing else in this pool is running` } : { start: true };
77
+ }
78
+ export function minutes(ms) {
79
+ if (ms < 60_000)
80
+ return `${Math.max(0, Math.round(ms / 1000))}s`;
81
+ const m = Math.round(ms / 60_000);
82
+ return m < 60 ? `${m}m` : `${Math.floor(m / 60)}h ${m % 60}m`;
83
+ }
84
+ /** Waits for a slot. Throws `QueueTimeout` after `timeoutMs`; the ticket is removed either way. */
85
+ export async function acquire(options) {
86
+ if (!/^[a-z0-9][a-z0-9-]{0,40}$/.test(options.pool))
87
+ throw new Error("Pool names are lowercase letters, digits and dashes.");
88
+ const dir = path.join(options.root ?? slotsRoot(), options.pool), now = options.now ?? Date.now;
89
+ fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
90
+ const id = `${now()}-${randomBytes(6).toString("hex")}`, file = path.join(dir, `${id}.json`), began = now();
91
+ const ticket = { id, pid: options.pid ?? process.pid, priority: options.priority, createdAt: began, label: options.label.slice(0, 120), state: "waiting" };
92
+ const write = () => { const tmp = `${file}.tmp`; fs.writeFileSync(tmp, JSON.stringify(ticket), { mode: 0o600 }); fs.renameSync(tmp, file); };
93
+ const release = () => { fs.rmSync(file, { force: true }); };
94
+ write();
95
+ const sleep = options.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
96
+ let said = "";
97
+ try {
98
+ for (;;) {
99
+ const pressure = await options.pressure().catch(() => undefined);
100
+ const decision = withFileLock(path.join(dir, ".queue"), () => {
101
+ const result = decide(readTickets(dir), id, options.slots, pressure, options.budget, now());
102
+ if (result.start) {
103
+ ticket.state = "running";
104
+ ticket.startedAt = now();
105
+ write();
106
+ }
107
+ return result;
108
+ });
109
+ if (decision.start) {
110
+ const waited = now() - began;
111
+ options.report(`${decision.warning ? `warning: ${decision.warning}. ` : ""}started${waited >= 1_000 ? ` after waiting ${minutes(waited)}` : ""}`);
112
+ return { id, release, waitedMs: waited };
113
+ }
114
+ if (decision.reason !== said) {
115
+ said = decision.reason;
116
+ options.report(`queued: ${decision.reason}`);
117
+ }
118
+ if (options.timeoutMs !== undefined && now() - began >= options.timeoutMs)
119
+ throw new QueueTimeout(`gave up after ${minutes(now() - began)} in the queue: ${said}`);
120
+ await sleep(options.pollMs ?? 5_000);
121
+ }
122
+ }
123
+ catch (error) {
124
+ release();
125
+ throw error;
126
+ }
127
+ }
128
+ export class QueueTimeout extends Error {
129
+ }
130
+ export function poolStatus(pool, root = slotsRoot()) {
131
+ const dir = path.join(root, pool);
132
+ const tickets = readTickets(dir);
133
+ return [...tickets.filter(t => t.state === "running").sort((a, b) => (a.startedAt ?? 0) - (b.startedAt ?? 0)), ...queueOrder(tickets)];
134
+ }
135
+ export function pools(root = slotsRoot()) {
136
+ try {
137
+ return fs.readdirSync(root, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name).sort();
138
+ }
139
+ catch {
140
+ return [];
141
+ }
142
+ }
@@ -26,7 +26,7 @@ export const BUILTIN_MODULES = [
26
26
  ]),
27
27
  ],
28
28
  cliCommands: [
29
- "init", "quickstart", "add", "agent", "projects", "search", "status", "doctor", "web-ui", "graph", "shell",
29
+ "init", "quickstart", "add", "agent", "projects", "search", "status", "doctor", "web-ui", "graph", "shell", "heavy", "reap",
30
30
  "add-finding", "pin", "review", "session-context", "sessions", "finding", "note", "notes",
31
31
  "search-fragments", "related-docs", "truths", "promote", "skills", "detect-skills", "hooks", "config",
32
32
  "maintain", "dream", "consolidation-status", "quality-feedback", "mcp-mode", "hooks-mode", "preset", "snippet",
@@ -70,7 +70,7 @@ export const BUILTIN_MODULES = [
70
70
  cliCommands: [
71
71
  "bridge", "bridge install", "bridge update", "bridge uninstall", "bridge rollback", "bridge status",
72
72
  "browser", "bridge doctor", "bridge usage", "bridge usage-statusline", "bridge hook", "bridge serve", "bridge ssh", "pair", "unpair",
73
- "bridge fanouts archive", "bridge accounts", "bridge askpass", "canary", "computers", "computers mcp", "usage", "sudo", "secret-exec",
73
+ "bridge fanouts archive", "bridge accounts", "bridge askpass", "canary", "computers", "computers mcp", "housekeeping", "usage", "sudo", "secret-exec",
74
74
  ],
75
75
  agentHooks: [
76
76
  { agents: ["codex"], events: ["SessionStart", "UserPromptSubmit", "Stop", "PermissionRequest"], handler: "bridge-hook.mjs hook codex" },
@@ -84,12 +84,13 @@ export const BUILTIN_MODULES = [
84
84
  ...routes("GET", [
85
85
  "/v1/health", "/v1/health/details", "/v1/health/peers", "/v1/muxes", "/v1/terminals/resolve", "/v1/activity", "/v1/metrics", "/v1/web-servers", "/v1/simulators", "/v1/browsers", "/v1/browsers/recordings", "/v1/browsers/recordings/index", "/v1/browsers/recordings/frame",
86
86
  "/v1/simulators/screenshot", "/v1/simulators/apps", "/v1/files", "/v1/models", "/v1/harnesses", "/v1/projects/files",
87
- "/v1/uploads/image", "/v1/files/range", "/v1/files/resolve", "/v1/usage", "/v1/resources", "/v1/speech/voices", "/v1/push/status", "/v1/projects/locate", "/v1/projects/repos",
87
+ "/v1/uploads/image", "/v1/files/range", "/v1/files/resolve", "/v1/usage", "/v1/resources", "/v1/housekeeping", "/v1/speech/voices", "/v1/push/status", "/v1/projects/locate", "/v1/projects/repos",
88
88
  "/v1/workspaces", "/v1/workspaces/panes", "/v1/workspaces/layout", "/v1/transcripts/blob", "/v1/transcripts/history", "/v1/sudo", "/v1/secrets",
89
89
  "/v1/conversations/search",
90
90
  "/v1/subagents", "/v1/subagents/transcript", "/v1/subagents/messages", "/v1/sessions/move", "/v1/sessions/moves", "/v1/sessions/move/computers", "/v1/sessions/move/availability", "/v1/sessions/move/intent", "/v1/sessions/move/launch", "/v1/dispatch/relocation", "/v1/dispatch/arrival",
91
91
  ]),
92
92
  ...routes("POST", [
93
+ "/v1/housekeeping/approve", "/v1/housekeeping/dismiss", "/v1/housekeeping/restore", "/v1/housekeeping/scan",
93
94
  "/v1/push/register", "/v1/push/forget", "/v1/push/answer", "/v1/push/target", "/v1/push/presence", "/v1/files", "/v1/files/delete", "/v1/projects/add", "/v1/simulators/action",
94
95
  "/v1/workspaces/launch", "/v1/workspaces/create", "/v1/workspaces/focus", "/v1/workspaces/rename",
95
96
  "/v1/workspaces/close", "/v1/sessions/rename", "/v1/sessions/seen", "/v1/sessions/move", "/v1/accounts/claude/add", "/v1/accounts/claude/settings", "/v1/accounts/allowed-pools", "/v1/sessions/move/abort", "/v1/sessions/move/launch", "/v1/prompt", "/v1/prompt/status", "/v1/prompt/after-turn", "/v1/prompt/after-turn/list", "/v1/prompt/after-turn/edit", "/v1/prompt/after-turn/cancel", "/v1/prompt/queue", "/v1/model", "/v1/settings", "/v1/agents/permission-mode", "/v1/side-question/dismiss", "/v1/keys", "/v1/secret", "/v1/upload",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@phren/cli",
3
- "version": "0.3.79",
3
+ "version": "0.3.80",
4
4
  "description": "Knowledge layer for AI agents - CLI, MCP server, and data layer",
5
5
  "type": "module",
6
6
  "bin": {
@@ -104,6 +104,16 @@ A worker that needs root runs `sudo -A <command>`: its launch sets
104
104
  `SUDO_ASKPASS`, and the owner approves the exact command and types the
105
105
  password on the phone. Plain `sudo` fails without a terminal.
106
106
 
107
+ Each computer has a budget for agent work (`~/.config/phren/budget.yaml`):
108
+ workers launched with `phren fanout run` queue past it, `dispatch` to
109
+ `anywhere` passes over a computer whose memory or load is over it (the
110
+ receipt's `skipped` says so), and an agent that names such a computer gets
111
+ `over_budget`. Have every worker run full test suites and native builds as
112
+ `phren heavy -- <command>` (`--priority release` for release work) instead of
113
+ its own lock, stop the servers and daemons it started before it reports, and
114
+ never wait with a `pgrep -f` loop, which matches itself. `phren reap` lists
115
+ what agents left running with the command to stop each; it stops nothing.
116
+
107
117
  You are the one conductor for this computer and every computer linked with
108
118
  it; a second conductor in the group is refused at launch. Conductors on
109
119
  computers that are not linked share only the store, so claim a task before you
@@ -27,3 +27,33 @@ to send a bounded follow-up, and `phren fanout review JOB` for a review round.
27
27
  Codex resumes inherit their original sandbox; ask a resumed author to review
28
28
  without edits. Use a fresh review-tier worker for an enforced read-only sandbox.
29
29
  Archive completed jobs with `phren fanout archive`.
30
+
31
+ ## Sharing one computer
32
+
33
+ Workers share the computer's memory, CPU, git state and processes with every
34
+ other agent on it. On a 31 GB Linux box, 5 to 10 agents with full test runs
35
+ ran it out of memory three times in a day.
36
+
37
+ - `phren fanout run` waits for this computer's worker budget (about one worker
38
+ per 7 GB, set in `~/.config/phren/budget.yaml`) and says on stderr when it
39
+ queued and why. `--priority release` goes first; `--wait 0` fails at once.
40
+ - Run every heavy job (a full test suite, a Gradle or Xcode build) as
41
+ `phren heavy -- <command>`, with `--priority release` for release work. It
42
+ allows N at once (about one per 12 GB) and replaces any lock of your own.
43
+ `phren heavy status` shows who runs and who waits.
44
+ - Stop what you started before you finish: dev servers, watchers, browsers,
45
+ build daemons (`./gradlew --stop`) and test database clones (`dropdb`).
46
+ `phren reap` lists what agents left running with the command that stops
47
+ each; it stops nothing, and the owner says which to stop.
48
+ - Never wait with `until ! pgrep -f <text>`: `pgrep -f` matches the waiting
49
+ shell's own command line, so the loop never ends (26 were found running
50
+ hours after their agents finished). Wait on a PID or a file, with a
51
+ deadline: `for i in $(seq 360); do kill -0 "$pid" 2>/dev/null || break; sleep 5; done`,
52
+ or poll the job's `exit.txt`.
53
+ - Commit in small steps, each one building, so a usage-limit stop loses
54
+ nothing that is not in a commit.
55
+ - `git stash` and the rerere cache belong to the repository, not the
56
+ worktree: every worktree sees the same stash list and replays the same
57
+ recorded resolutions. Never `git stash pop` (one agent's pop applied
58
+ another session's old stash); commit work in progress on your own branch
59
+ instead. After a merge that rerere resolved, read the diff before you commit.