@howaboua/pi-agent-comms 0.0.1 → 0.0.3

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 (47) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +1 -1
  3. package/dist/viewer/web/app.js +6 -6
  4. package/dist/viewer/web/render.js +2 -2
  5. package/docs/BOARD.md +1 -1
  6. package/docs/NOTES.md +19 -2
  7. package/package.json +75 -74
  8. package/src/board/activity.ts +1 -0
  9. package/src/board/briefing.ts +2 -2
  10. package/src/board/delivery.ts +8 -6
  11. package/src/board/runtime/activation.ts +2 -3
  12. package/src/board/runtime/catchup.ts +1 -1
  13. package/src/board/settings/panel.ts +11 -8
  14. package/src/board/viewer/web/app.js +6 -6
  15. package/src/board/viewer/web/render.js +2 -2
  16. package/src/guidance.ts +14 -14
  17. package/src/notes/AGENTS.md +3 -3
  18. package/src/notes/activation.ts +1 -0
  19. package/src/notes/bridge.ts +4 -2
  20. package/src/notes/context-owner.ts +5 -5
  21. package/src/notes/feature.ts +67 -1
  22. package/src/notes/fresh-notes.ts +46 -5
  23. package/src/notes/history-search-pruning.mjs +110 -76
  24. package/src/notes/history-search-worker.mjs +1 -1
  25. package/src/notes/history-windows.ts +1 -1
  26. package/src/notes/index.ts +9 -3
  27. package/src/notes/integrations.ts +83 -45
  28. package/src/notes/lifecycle.ts +11 -2
  29. package/src/notes/model-roles.ts +2 -2
  30. package/src/notes/notes-lookup.ts +1 -1
  31. package/src/notes/rollover.ts +34 -5
  32. package/src/notes/session-pruning-cleanup.mjs +164 -0
  33. package/src/notes/session-pruning-exit.mjs +312 -0
  34. package/src/notes/session-pruning-screen.ts +1 -1
  35. package/src/notes/session-pruning-sparse.mjs +133 -0
  36. package/src/notes/session-pruning-state.mjs +123 -0
  37. package/src/notes/session-pruning-transaction.ts +1 -0
  38. package/src/notes/session-pruning.ts +34 -1
  39. package/src/notes/settings-controls.ts +23 -17
  40. package/src/notes/settings-screen.ts +2 -6
  41. package/src/notes/settings.ts +13 -6
  42. package/src/notes/shared-notes.ts +52 -30
  43. package/src/notes/tool-contracts.ts +24 -5
  44. package/src/notes/tools.ts +51 -29
  45. package/src/notes/tree-checkpoint.ts +12 -13
  46. package/src/notes/window-message.ts +6 -18
  47. package/src/notes/windows.ts +10 -11
@@ -40,6 +40,7 @@ export class NotesLifecycle {
40
40
  active = false;
41
41
  normalCompaction = false;
42
42
  newWindowRequests: NewWindowRequests = "unrestricted";
43
+ taskCompletionRollover = false;
43
44
  idleMinutes: IdleMinutes = 0;
44
45
  taskBoundaryReminder = 0;
45
46
  bridge: NotesBridge | undefined;
@@ -170,11 +171,17 @@ export class NotesLifecycle {
170
171
  ctx: ExtensionContext,
171
172
  callId: string,
172
173
  handoff?: ModelRoleHandoff,
174
+ resume = true,
175
+ parentCallId?: string,
173
176
  ): boolean {
174
177
  if (this.newWindowRequests === "off")
175
178
  throw new Error(
176
179
  "New window requests are disabled. Continue in the current window.",
177
180
  );
181
+ if (!resume && !this.taskCompletionRollover)
182
+ throw new Error(
183
+ "Task-completion rollover is disabled. Continue here, or use new_context without resume: false.",
184
+ );
178
185
  if (this.checkpoint.pending || this.admission.pending) return false;
179
186
  if (this.requests.pending) return false;
180
187
  if (
@@ -183,12 +190,13 @@ export class NotesLifecycle {
183
190
  this.windows.current?.currentWindowId,
184
191
  this.runId,
185
192
  callId,
193
+ parentCallId,
186
194
  )
187
195
  )
188
196
  throw new Error(
189
197
  "Save your progress in your own notes using a relative path, wait for the write to succeed, then call new_context next. Writing another agent's notes does not save your checkpoint.",
190
198
  );
191
- this.requests.schedule(ctx, handoff);
199
+ this.requests.schedule(ctx, handoff, resume);
192
200
  return true;
193
201
  }
194
202
  private async openWindow(
@@ -237,6 +245,7 @@ export class NotesLifecycle {
237
245
  }
238
246
  outcome(outcome: "completed" | "aborted" | "error"): void {
239
247
  this.checkpoint.outcome(outcome);
248
+ this.requests.outcome(outcome);
240
249
  }
241
250
  input(
242
251
  event: InputEvent,
@@ -302,7 +311,7 @@ export class NotesLifecycle {
302
311
  return;
303
312
  }
304
313
  if (this.admission.drain()) return;
305
- const rollover = this.requests.settled(ctx);
314
+ const rollover = this.requests.settled(ctx, event.aborted);
306
315
  if (rollover) await rollover;
307
316
  }
308
317
  }
@@ -77,8 +77,8 @@ export function createModelRoles(
77
77
  ? [
78
78
  `Current role: ${currentRole}`,
79
79
  lifecycle.gptPromptMode()
80
- ? 'Roles=user preferences, not capability limits. Switch for clear, sustained task/scope change, not one specialised prompt. Any role can do general work. Bounded specialist detour→consider subagent. Save notes→new_context({role: "name"}); omit role→keep role.'
81
- : 'Roles are user preferences, not capability limits. Switch for clear, sustained change of task or scope, not single specialised prompt. Any role can do general work. Consider subagents for a bounded specialist detour. Save notes, then call new_context({role: "name"}); omit role to keep the current role.',
80
+ ? 'Roles=user-configured model+reasoning presets, not capabilities/permissions. Each agent, including workers, chooses its own role autonomously; NO parent/user approval needed. Main work enters substantial new phase→reassess descriptions, switch for sustained better fit. Single specialised question/brief detour≠switch; any role can do general work. Change your own role, not delegate just to access one. Save notes→new_context({role: "name"})→fresh window, same session; omit role→keep preset.'
81
+ : 'Roles select user-configured model and reasoning presets, not capabilities or permissions. Each agent, including workers, chooses its own role autonomously; no parent or user approval needed. Reassess the descriptions when your main work enters a substantial new phase, and switch for a sustained better fit, not a single specialised question or brief detour. Any role can do general work. Change your own role rather than delegating just to access one. Save notes, then call new_context({role: "name"}) to open a fresh window in this session; omit role to keep the current preset.',
82
82
  ...config.roles.map((role) => `- ${role.id}: ${role.description}`),
83
83
  ].join("\n")
84
84
  : "No model roles available. Call new_context without role.";
@@ -79,7 +79,7 @@ export async function lookupNotes(
79
79
  );
80
80
  else if (lookupFailed)
81
81
  warnings.push(
82
- "Some notes could not be retrieved. Available notes are shown; retry the lookup to check for missing results.",
82
+ "Remote notes could not be checked. Local results are shown; retry to check for remote-only notes.",
83
83
  );
84
84
  if (responses.length && canProject && replacementsInScope)
85
85
  warnings.push(
@@ -7,6 +7,7 @@ import type {
7
7
  import { prepareCompactionProjection } from "./compaction-projection.js";
8
8
  import type { NotesLifecycle } from "./lifecycle.js";
9
9
  import type { ModelRoleHandoff } from "./model-roles.js";
10
+ import type { NewWindowRequests } from "./settings.js";
10
11
 
11
12
  type Rollover = {
12
13
  sessionId: string;
@@ -67,24 +68,45 @@ export class RolloverRequests {
67
68
  clear(): void {
68
69
  this.rollover = undefined;
69
70
  }
70
- schedule(ctx: ExtensionContext, handoff?: ModelRoleHandoff): void {
71
+ schedule(
72
+ ctx: ExtensionContext,
73
+ handoff?: ModelRoleHandoff,
74
+ resume = true,
75
+ ): void {
71
76
  this.rollover = {
72
77
  sessionId: ctx.sessionManager.getSessionId(),
73
78
  windowId: this.host.windows.current?.currentWindowId,
74
79
  phase: "scheduled",
75
- triggerTurn: true,
80
+ triggerTurn: resume,
76
81
  ...(handoff ? { handoff } : {}),
77
82
  };
78
83
  }
79
- settled(ctx: ExtensionContext): Promise<void> | undefined {
84
+ outcome(outcome: "completed" | "aborted" | "error"): void {
85
+ if (
86
+ this.rollover?.phase === "scheduled" &&
87
+ !this.rollover.triggerTurn &&
88
+ outcome !== "completed"
89
+ )
90
+ this.clear();
91
+ }
92
+ settled(ctx: ExtensionContext, aborted = false): Promise<void> | undefined {
80
93
  const rollover = this.rollover;
94
+ if (rollover?.phase === "scheduled" && !rollover.triggerTurn && aborted) {
95
+ this.clear();
96
+ return;
97
+ }
81
98
  if (
82
99
  rollover?.phase === "scheduled" &&
83
100
  rollover.sessionId === ctx.sessionManager.getSessionId() &&
84
101
  rollover.windowId === this.host.windows.current?.currentWindowId
85
102
  ) {
86
103
  this.rollover = undefined;
87
- return this.roll(ctx, rollover.triggerTurn, rollover.handoff);
104
+ return this.roll(
105
+ ctx,
106
+ rollover.triggerTurn,
107
+ rollover.handoff,
108
+ this.host.newWindowRequests,
109
+ );
88
110
  }
89
111
  }
90
112
 
@@ -92,8 +114,10 @@ export class RolloverRequests {
92
114
  ctx: ExtensionContext,
93
115
  triggerTurn: boolean,
94
116
  handoff?: ModelRoleHandoff,
117
+ policy: NewWindowRequests | undefined = triggerTurn
118
+ ? this.host.newWindowRequests
119
+ : undefined,
95
120
  ): Promise<void> {
96
- const policy = triggerTurn ? this.host.newWindowRequests : undefined;
97
121
  const checkOnly = !this.host.normalCompaction && policy === "pi-limits";
98
122
  if (!this.host.normalCompaction && !checkOnly) {
99
123
  await this.openWindow(ctx, triggerTurn, true, handoff);
@@ -151,6 +175,11 @@ export class RolloverRequests {
151
175
  }
152
176
  this.rollover = undefined;
153
177
  try {
178
+ if (!triggerTurn && policy !== undefined)
179
+ ctx.ui.notify(
180
+ "New context was not opened: Pi has no eligible history to compact. The current context remains.",
181
+ "warning",
182
+ );
154
183
  if (triggerTurn)
155
184
  this.sendMessage(
156
185
  {
@@ -0,0 +1,164 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import {
3
+ closeSync,
4
+ fsyncSync,
5
+ lstatSync,
6
+ openSync,
7
+ readdirSync,
8
+ renameSync,
9
+ statSync,
10
+ unlinkSync,
11
+ } from "node:fs";
12
+ import { open } from "node:fs/promises";
13
+ import { resolve } from "node:path";
14
+ import {
15
+ planSparsePruning,
16
+ scanSparseSource,
17
+ } from "./session-pruning-sparse.mjs";
18
+ import { cleanupPaths, tryCleanupLock } from "./session-pruning-state.mjs";
19
+
20
+ /** @param {string} path @param {import("node:fs").Stats} source */
21
+ function checkSource(path, source) {
22
+ const current = lstatSync(path);
23
+ if (
24
+ !current.isFile() ||
25
+ current.nlink !== 1 ||
26
+ current.dev !== source.dev ||
27
+ current.ino !== source.ino ||
28
+ current.size !== source.size ||
29
+ current.mtimeMs !== source.mtimeMs ||
30
+ current.ctimeMs !== source.ctimeMs
31
+ )
32
+ throw new Error(
33
+ "Session changed during cleanup. Nothing was replaced. Cleanup will retry on the next normal Pi exit.",
34
+ );
35
+ }
36
+
37
+ /** Open descriptors supplement the registered session owners, not replace them.
38
+ * @param {import("node:fs").Stats} source
39
+ */
40
+ function checkHolders(source) {
41
+ if (process.platform !== "linux")
42
+ throw new Error(
43
+ "Automatic session cleanup is unavailable on this platform. Retired payloads remain pruned.",
44
+ );
45
+ const holders = new Set();
46
+ for (const pid of readdirSync("/proc")) {
47
+ if (!/^\d+$/.test(pid) || Number(pid) === process.pid) continue;
48
+ const dir = `/proc/${pid}`;
49
+ try {
50
+ if (statSync(dir).uid !== process.getuid?.()) continue;
51
+ for (const fd of readdirSync(`${dir}/fd`)) {
52
+ try {
53
+ const file = statSync(`${dir}/fd/${fd}`);
54
+ if (file.dev === source.dev && file.ino === source.ino)
55
+ holders.add(pid);
56
+ } catch (error) {
57
+ if (!vanished(error)) throw error;
58
+ }
59
+ }
60
+ } catch (error) {
61
+ if (
62
+ error instanceof Error &&
63
+ "code" in error &&
64
+ (error.code === "EACCES" || error.code === "EPERM")
65
+ )
66
+ continue;
67
+ else if (!vanished(error))
68
+ throw new Error(
69
+ `Cannot inspect open holders for PID ${pid}: ${String(error)}`,
70
+ );
71
+ }
72
+ }
73
+ if (holders.size)
74
+ throw new Error(
75
+ `Session record cleanup was skipped because process(es) ${[...holders].join(", ")} still hold it open. It will retry on the next normal Pi exit.`,
76
+ );
77
+ }
78
+
79
+ /** @param {unknown} error */
80
+ function vanished(error) {
81
+ return (
82
+ error instanceof Error &&
83
+ "code" in error &&
84
+ (error.code === "ENOENT" || error.code === "ESRCH")
85
+ );
86
+ }
87
+
88
+ /** Called only by the after-exit worker.
89
+ * @param {string} file @param {string} sessionId @param {()=>void} checkOwners
90
+ */
91
+ export async function cleanSparseSession(file, sessionId, checkOwners) {
92
+ const path = resolve(file);
93
+ const source = lstatSync(path);
94
+ if (!source.isFile() || source.nlink !== 1)
95
+ throw new Error(
96
+ "Session record cleanup requires a regular session file without symbolic or hard links. Retired payloads remain pruned.",
97
+ );
98
+ checkOwners();
99
+ checkHolders(source);
100
+ const lock = cleanupPaths(path).lock;
101
+ let releaseLock;
102
+ const temp = `${path}.notes-prune-${randomUUID()}.tmp`;
103
+ /** @type {Awaited<ReturnType<typeof open>>|undefined} */
104
+ let output;
105
+ try {
106
+ releaseLock = tryCleanupLock(path);
107
+ if (!releaseLock)
108
+ throw new Error(
109
+ `Another session cleanup may be running. Only after verifying that none is active, remove the stale lock ${JSON.stringify(lock)}. Cleanup will retry on the next normal Pi exit. Do not remove an active cleanup's lock.`,
110
+ );
111
+ checkOwners();
112
+ const plan = await planSparsePruning(path, source.size);
113
+ if (plan.header.id !== sessionId)
114
+ throw new Error("Session identity changed. Cleanup was skipped.");
115
+ checkSource(path, source);
116
+ if (!plan.removed.size)
117
+ return { removed: 0, before: source.size, after: source.size };
118
+ output = await open(temp, "wx", source.mode & 0o777);
119
+ const target = output;
120
+ const generation = randomUUID();
121
+ await scanSparseSource(path, source.size, async (entry, raw) => {
122
+ if (plan.removed.has(entry.id)) return;
123
+ const parentId = plan.parents.get(entry.id) ?? null;
124
+ const replacement =
125
+ entry.type === "session"
126
+ ? {
127
+ ...entry,
128
+ notesPruning: { version: 1, sessionId: entry.id, generation },
129
+ }
130
+ : entry.parentId === parentId
131
+ ? entry
132
+ : { ...entry, parentId };
133
+ await target.writeFile(
134
+ `${replacement === entry ? raw : JSON.stringify(replacement)}\n`,
135
+ );
136
+ });
137
+ await output.sync();
138
+ await output.close();
139
+ output = undefined;
140
+ // No await from final holder/source validation through atomic replacement.
141
+ checkOwners();
142
+ checkHolders(source);
143
+ checkSource(path, source);
144
+ const after = statSync(temp).size;
145
+ renameSync(temp, path);
146
+ const directory = openSync(resolve(path, ".."), "r");
147
+ try {
148
+ fsyncSync(directory);
149
+ } finally {
150
+ closeSync(directory);
151
+ }
152
+ return { removed: plan.removed.size, before: source.size, after };
153
+ } finally {
154
+ await output?.close();
155
+ try {
156
+ unlinkSync(temp);
157
+ } catch (error) {
158
+ // oxlint-disable-next-line no-unsafe-finally -- Cleanup failure must remain visible, even when the primary operation failed.
159
+ if (!vanished(error)) throw error;
160
+ } finally {
161
+ releaseLock?.();
162
+ }
163
+ }
164
+ }
@@ -0,0 +1,312 @@
1
+ import { spawn } from "node:child_process";
2
+ import { randomUUID } from "node:crypto";
3
+ import {
4
+ existsSync,
5
+ mkdirSync,
6
+ readdirSync,
7
+ readFileSync,
8
+ renameSync,
9
+ rmdirSync,
10
+ unlinkSync,
11
+ writeFileSync,
12
+ } from "node:fs";
13
+ import { hostname } from "node:os";
14
+ import { dirname, isAbsolute, join, resolve } from "node:path";
15
+ import { setTimeout } from "node:timers/promises";
16
+ import { fileURLToPath } from "node:url";
17
+ import { cleanSparseSession } from "./session-pruning-cleanup.mjs";
18
+ import {
19
+ cleanupHeader,
20
+ cleanupPaths,
21
+ tryCleanupLock,
22
+ } from "./session-pruning-state.mjs";
23
+
24
+ /** @typedef {{pid:number; host:string; start:string; sessionId:string}} Owner */
25
+ const host = hostname();
26
+
27
+ /** Linux start time prevents a recycled PID from impersonating an owner.
28
+ * @param {number} pid
29
+ */
30
+ function processStart(pid) {
31
+ const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
32
+ return stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19] ?? "";
33
+ }
34
+
35
+ /** @param {Owner} owner */
36
+ function alive(owner) {
37
+ if (owner.host !== host) return true;
38
+ try {
39
+ return processStart(owner.pid) === owner.start;
40
+ } catch (error) {
41
+ if (missing(error)) return false;
42
+ throw error;
43
+ }
44
+ }
45
+
46
+ /** @param {unknown} error */
47
+ function missing(error) {
48
+ return (
49
+ error instanceof Error &&
50
+ "code" in error &&
51
+ (error.code === "ENOENT" || error.code === "ESRCH")
52
+ );
53
+ }
54
+
55
+ /** @param {unknown} value @returns {value is Owner} */
56
+ function isOwner(value) {
57
+ if (!value || typeof value !== "object") return false;
58
+ const data = /** @type {Record<string,unknown>} */ (value);
59
+ return (
60
+ Number.isSafeInteger(data["pid"]) &&
61
+ Number(data["pid"]) > 0 &&
62
+ typeof data["host"] === "string" &&
63
+ typeof data["start"] === "string" &&
64
+ data["start"].length > 0 &&
65
+ typeof data["sessionId"] === "string"
66
+ );
67
+ }
68
+
69
+ /** Keep a positive claim while a saved session has a live Notes runtime.
70
+ * @param {string|undefined} file @param {string} sessionId
71
+ * @returns {(()=>void)|undefined}
72
+ */
73
+ function registerCleanupOwner(file, sessionId) {
74
+ if (process.platform !== "linux" || !file || !existsSync(file)) return;
75
+ const owner = {
76
+ pid: process.pid,
77
+ host,
78
+ start: processStart(process.pid),
79
+ sessionId,
80
+ };
81
+ const directory = cleanupPaths(file).owners;
82
+ mkdirSync(directory, { recursive: true, mode: 0o700 });
83
+ const entry = join(
84
+ directory,
85
+ `${encodeURIComponent(host)}-${owner.pid}-${owner.start}-${randomUUID()}.json`,
86
+ );
87
+ writeFileSync(entry, JSON.stringify(owner), { mode: 0o600 });
88
+ const release = () => {
89
+ try {
90
+ unlinkSync(entry);
91
+ } catch (error) {
92
+ if (!missing(error)) throw error;
93
+ }
94
+ try {
95
+ rmdirSync(directory);
96
+ } catch (error) {
97
+ if (
98
+ !missing(error) &&
99
+ !(
100
+ error instanceof Error &&
101
+ "code" in error &&
102
+ error.code === "ENOTEMPTY"
103
+ )
104
+ )
105
+ throw error;
106
+ }
107
+ };
108
+ const onExit = () => {
109
+ // A failed best-effort release remains a stale claim; the worker removes
110
+ // it only after proving this PID/start identity has ended.
111
+ try {
112
+ release();
113
+ } catch {
114
+ /* Never turn normal Pi exit into a cleanup failure. */
115
+ }
116
+ };
117
+ process.once("exit", onExit);
118
+ return () => {
119
+ process.off("exit", onExit);
120
+ release();
121
+ };
122
+ }
123
+
124
+ /** @param {unknown} header @param {string} sessionId */
125
+ function generation(header, sessionId) {
126
+ if (
127
+ !header ||
128
+ typeof header !== "object" ||
129
+ !("id" in header) ||
130
+ header.id !== sessionId
131
+ )
132
+ throw new Error("Session identity changed during startup.");
133
+ if (!("notesPruning" in header) || header.notesPruning === undefined) return;
134
+ const marker = header.notesPruning;
135
+ if (
136
+ !marker ||
137
+ typeof marker !== "object" ||
138
+ !("generation" in marker) ||
139
+ typeof marker.generation !== "string"
140
+ )
141
+ throw new Error("Session pruning generation could not be validated.");
142
+ return marker.generation;
143
+ }
144
+
145
+ /** The manager is loaded before extension hooks. Serialize claim establishment
146
+ * with cleanup, then detect a rewrite that won before this startup could claim.
147
+ * @param {string|undefined} file @param {string} sessionId @param {unknown} loadedHeader
148
+ */
149
+ export async function admitSessionCleanup(file, sessionId, loadedHeader) {
150
+ if (process.platform !== "linux" || !file || !existsSync(file)) return;
151
+ const deadline = Date.now() + 120_000;
152
+ let unlock = tryCleanupLock(file);
153
+ while (!unlock) {
154
+ if (Date.now() >= deadline)
155
+ throw new Error(
156
+ `Session cleanup did not release ${JSON.stringify(cleanupPaths(file).lock)}. Verify no cleanup is active before removing a stale lock, then restart Pi.`,
157
+ );
158
+ await setTimeout(25);
159
+ unlock = tryCleanupLock(file);
160
+ }
161
+ try {
162
+ const raw = cleanupHeader(file);
163
+ const release = registerCleanupOwner(file, sessionId);
164
+ return {
165
+ release,
166
+ stale: generation(raw, sessionId) !== generation(loadedHeader, sessionId),
167
+ };
168
+ } finally {
169
+ unlock();
170
+ }
171
+ }
172
+
173
+ /** Do not delete records from another live manager of this exact saved session.
174
+ * Unknown/foreign claims are intentionally conservative. Unregistered foreign
175
+ * JSONL writers are outside the extension's ownership, as with live pruning.
176
+ * @param {string} file
177
+ */
178
+ function checkOwners(file) {
179
+ const directory = cleanupPaths(file).owners;
180
+ let entries;
181
+ try {
182
+ entries = readdirSync(directory);
183
+ } catch (error) {
184
+ if (missing(error)) return;
185
+ throw error;
186
+ }
187
+ for (const name of entries) {
188
+ const path = join(directory, name);
189
+ let owner;
190
+ try {
191
+ owner = JSON.parse(readFileSync(path, "utf8"));
192
+ } catch (error) {
193
+ if (missing(error)) continue;
194
+ throw error;
195
+ }
196
+ if (!isOwner(owner))
197
+ throw new Error(
198
+ "Session cleanup found an unrecognised live-session claim. Retired payloads remain pruned.",
199
+ );
200
+ if (alive(owner))
201
+ throw new Error(
202
+ "Session record cleanup was skipped because another process still owns this session. It will retry when that session exits.",
203
+ );
204
+ try {
205
+ unlinkSync(path);
206
+ } catch (error) {
207
+ if (!missing(error)) throw error;
208
+ }
209
+ }
210
+ }
211
+
212
+ /** @param {string} path @param {string} sessionId */
213
+ export function previousCleanupFailure(path, sessionId) {
214
+ try {
215
+ const value = JSON.parse(readFileSync(path, "utf8"));
216
+ unlinkSync(path);
217
+ return value.sessionId === sessionId && typeof value.error === "string"
218
+ ? value.error
219
+ : undefined;
220
+ } catch (error) {
221
+ if (missing(error)) return;
222
+ throw error;
223
+ }
224
+ }
225
+
226
+ /** @param {string} path @param {string} sessionId @param {unknown} error */
227
+ export function recordCleanupFailure(path, sessionId, error) {
228
+ mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
229
+ const temp = `${path}.${process.pid}.tmp`;
230
+ writeFileSync(
231
+ temp,
232
+ JSON.stringify({
233
+ sessionId,
234
+ timestamp: new Date().toISOString().slice(0, 16) + "Z",
235
+ error: error instanceof Error ? error.message : String(error),
236
+ }),
237
+ { mode: 0o600 },
238
+ );
239
+ renameSync(temp, path);
240
+ }
241
+
242
+ /** Schedule without holding Pi open; this worker does not touch the graph until
243
+ * the real owning process exits, not merely when shutdown hooks finish.
244
+ * @param {string} file @param {string} sessionId @param {string} statusPath
245
+ */
246
+ export async function scheduleSessionCleanup(file, sessionId, statusPath) {
247
+ if (!existsSync(file)) return;
248
+ if (process.platform !== "linux")
249
+ throw new Error(
250
+ "Automatic session record cleanup is unavailable on this platform. Retired payloads remain pruned.",
251
+ );
252
+ const owner = {
253
+ pid: process.pid,
254
+ host,
255
+ start: processStart(process.pid),
256
+ sessionId,
257
+ };
258
+ const child = spawn(
259
+ "node",
260
+ [fileURLToPath(import.meta.url), file, JSON.stringify(owner), statusPath],
261
+ {
262
+ detached: true,
263
+ stdio: "ignore",
264
+ windowsHide: true,
265
+ },
266
+ );
267
+ await new Promise((resolve, reject) => {
268
+ child.once("error", reject);
269
+ child.once("spawn", resolve);
270
+ });
271
+ child.unref();
272
+ }
273
+
274
+ /** @param {string} file @param {Owner} owner @param {string} statusPath */
275
+ async function afterExit(file, owner, statusPath) {
276
+ try {
277
+ const deadline = Date.now() + 120_000;
278
+ while (alive(owner)) {
279
+ if (Date.now() >= deadline)
280
+ throw new Error(
281
+ "Session record cleanup was skipped because Pi did not exit. It will retry on the next normal exit.",
282
+ );
283
+ await setTimeout(250);
284
+ }
285
+ await cleanSparseSession(file, owner.sessionId, () => checkOwners(file));
286
+ try {
287
+ unlinkSync(statusPath);
288
+ } catch (error) {
289
+ if (!missing(error)) throw error;
290
+ }
291
+ } catch (error) {
292
+ recordCleanupFailure(statusPath, owner.sessionId, error);
293
+ }
294
+ }
295
+
296
+ if (
297
+ process.argv[1] &&
298
+ resolve(process.argv[1]) === fileURLToPath(import.meta.url)
299
+ ) {
300
+ const [file, encoded, statusPath] = process.argv.slice(2);
301
+ const owner = encoded && JSON.parse(encoded);
302
+ if (
303
+ !file ||
304
+ !statusPath ||
305
+ !isAbsolute(statusPath) ||
306
+ !isOwner(owner) ||
307
+ owner.host !== host ||
308
+ process.platform !== "linux"
309
+ )
310
+ throw new Error("Invalid after-exit session cleanup request.");
311
+ await afterExit(file, owner, statusPath);
312
+ }
@@ -159,7 +159,7 @@ export async function openSessionPruningSettings(
159
159
  theme.bold(" Session auto-pruning"),
160
160
  "",
161
161
  ...wrap(
162
- "Runs once after a new context window's first completed turn commits its checkpoint. Settings follow this session on resume; new and forked sessions start Off. Forks made before restarting can retain unpruned history.",
162
+ `Retired payloads are pruned after a new window's first completed turn. ${process.platform === "linux" ? "Empty records are removed automatically after Pi exits." : "Physical record cleanup requires Linux."} Settings follow this session on resume; new and forked sessions start Off. Forks made before restarting can retain unpruned history.`,
163
163
  ),
164
164
  "",
165
165
  ...wrap(RESTART_NOTICE),