@anhlp/alp-cli 0.0.1-beta.3 → 0.0.1-beta.6

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 (69) hide show
  1. package/dist/THIRD-PARTY-NOTICES.txt +51 -1
  2. package/dist/acp/main.js +1 -1
  3. package/dist/acp.js +300 -92
  4. package/dist/alp-web/THIRD-PARTY-NOTICES.txt +3256 -0
  5. package/dist/alp-web/alp-boundary.json +16 -0
  6. package/dist/alp-web/apple-touch-icon.png +0 -0
  7. package/dist/alp-web/assets/TerminalPanel-CqTsgY-W.js +22 -0
  8. package/dist/alp-web/assets/TerminalPanel-DLuoa74B.css +1 -0
  9. package/dist/alp-web/assets/highlighter-BnicKQ_d.js +18 -0
  10. package/dist/alp-web/assets/index-BMbDUCHW.css +1 -0
  11. package/dist/alp-web/assets/index-B_RFaj2C.js +59 -0
  12. package/dist/alp-web/favicon-attention.svg +6 -0
  13. package/dist/alp-web/favicon-running.svg +6 -0
  14. package/dist/alp-web/favicon.svg +5 -0
  15. package/dist/alp-web/index.html +20 -0
  16. package/dist/alp-web.js +10119 -0
  17. package/dist/alpd.js +30333 -15153
  18. package/dist/backup.js +2 -2
  19. package/dist/build-manifest.json +120 -2
  20. package/dist/cli.js +34 -3
  21. package/dist/daemon.d.ts +1 -1
  22. package/dist/daemon.js +5 -0
  23. package/dist/interfaces.d.ts +22 -2
  24. package/dist/interfaces.js +182 -37
  25. package/dist/paths.d.ts +1 -0
  26. package/dist/paths.js +2 -1
  27. package/dist/roles.d.ts +15 -0
  28. package/dist/roles.js +18 -0
  29. package/dist/schedules.d.ts +2 -0
  30. package/dist/schedules.js +45 -0
  31. package/dist/self-update.d.ts +152 -0
  32. package/dist/self-update.js +390 -0
  33. package/dist/sessions.d.ts +7 -1
  34. package/dist/sessions.js +44 -12
  35. package/dist/tasks.js +22 -8
  36. package/dist/terminal-native/README.md +201 -0
  37. package/dist/terminal-native/prebuilt/darwin-arm64/manifest.json +11 -0
  38. package/dist/terminal-native/prebuilt/darwin-arm64/terminal-owner +0 -0
  39. package/dist/terminal-native/prebuilt/darwin-x64/manifest.json +11 -0
  40. package/dist/terminal-native/prebuilt/darwin-x64/terminal-owner +0 -0
  41. package/dist/terminal-native/prebuilt/linux-arm64-glibc/manifest.json +10 -0
  42. package/dist/terminal-native/prebuilt/linux-arm64-glibc/terminal-owner +0 -0
  43. package/dist/terminal-native/prebuilt/linux-arm64-musl/manifest.json +10 -0
  44. package/dist/terminal-native/prebuilt/linux-arm64-musl/terminal-owner +0 -0
  45. package/dist/terminal-native/prebuilt/linux-x64-glibc/manifest.json +10 -0
  46. package/dist/terminal-native/prebuilt/linux-x64-glibc/terminal-owner +0 -0
  47. package/dist/terminal-native/prebuilt/linux-x64-musl/manifest.json +10 -0
  48. package/dist/terminal-native/prebuilt/linux-x64-musl/terminal-owner +0 -0
  49. package/dist/terminal-native/terminal-owner.c +389 -0
  50. package/dist/terminal.d.ts +13 -0
  51. package/dist/terminal.js +80 -0
  52. package/dist/usage.d.ts +1 -1
  53. package/dist/usage.js +22 -7
  54. package/dist/web-service.d.ts +56 -0
  55. package/dist/web-service.js +143 -0
  56. package/package.json +11 -4
  57. package/src/backup.js +1 -1
  58. package/src/cli.js +40 -4
  59. package/src/daemon.js +3 -0
  60. package/src/interfaces.js +227 -32
  61. package/src/paths.js +3 -1
  62. package/src/roles.js +28 -0
  63. package/src/schedules.js +38 -0
  64. package/src/self-update.js +406 -0
  65. package/src/sessions.js +44 -13
  66. package/src/tasks.js +22 -8
  67. package/src/terminal.js +78 -0
  68. package/src/usage.js +22 -7
  69. package/src/web-service.js +187 -0
@@ -7,9 +7,11 @@ export function answerer(client: any): {
7
7
  close(): void;
8
8
  };
9
9
  /** Streams a tree until its root is idle; the first Ctrl-C interrupts it, the second detaches. */
10
- export function follow(client: any, rootId: any, print: any, { untilIdle, interactive }: {
10
+ export function follow(client: any, rootId: any, print: any, { untilIdle, interactive, targetOnly, promptId }: {
11
11
  untilIdle: any;
12
12
  interactive?: boolean | undefined;
13
+ targetOnly?: boolean | undefined;
14
+ promptId: any;
13
15
  }): Promise<any>;
14
16
  export function run(args: any): Promise<void>;
15
17
  export function ps(args: any): Promise<void>;
@@ -26,6 +28,8 @@ export function top(args: any): Promise<void>;
26
28
  export function log(args: any): Promise<void>;
27
29
  /** The project board every agent on the project shares: live claims, then decisions and findings. */
28
30
  export function board(args: any): Promise<void>;
31
+ /** The models alpd offers now: the live catalog (t-e5ee); --refresh asks every provider again first. */
32
+ export function models(args: any): Promise<void>;
29
33
  export function printPauses({ all, runtimes, parked }: {
30
34
  all: any;
31
35
  runtimes: any;
@@ -39,3 +43,5 @@ export function resume(args: any): Promise<void>;
39
43
  export function recall(args: any): Promise<void>;
40
44
  /** alp web: opens the web app alpd serves on 127.0.0.1, with the token in the address (ALPD §61). */
41
45
  export function interrupt(args: any): Promise<void>;
46
+ /** alp compact <session>: compacts a root's context now, or at its next turn boundary (t-0e56). */
47
+ export function compact(args: any): Promise<void>;
package/dist/sessions.js CHANGED
@@ -4,7 +4,7 @@ import path from "node:path";
4
4
  import { createInterface } from "node:readline";
5
5
  import { parseArgs } from "node:util";
6
6
  import { ago, duration, renderLog, renderPs } from "@anhlp/alp-client/render";
7
- import { isTaskId } from "@anhlp/alp-core/tasks";
7
+ import { AGENT_MARKER, isAgentProcess, isTaskId } from "@anhlp/alp-core/tasks";
8
8
  import { connect } from "@anhlp/alp-client/index";
9
9
  import { UsageError } from "./usage.js";
10
10
  import { start, running, stop } from "./daemon.js";
@@ -121,7 +121,7 @@ function answerer(client) {
121
121
  }
122
122
  };
123
123
  }
124
- function follow(client, rootId, print, { untilIdle, interactive = false }) {
124
+ function follow(client, rootId, print, { untilIdle, interactive = false, targetOnly = false, promptId }) {
125
125
  const answering = interactive ? answerer(client) : void 0;
126
126
  const done = new Promise((resolve, reject) => {
127
127
  let failed = false;
@@ -144,10 +144,13 @@ function follow(client, rootId, print, { untilIdle, interactive = false }) {
144
144
  process.on("SIGINT", onSignal);
145
145
  client.onClose((error) => {
146
146
  process.off("SIGINT", onSignal);
147
+ answering?.close();
147
148
  reject(error);
148
149
  });
149
150
  let rootEnded = false;
150
151
  client.onEvent((envelope) => {
152
+ if (targetOnly && envelope.sessionId !== rootId) return;
153
+ if (promptId && envelope.event.type === "prompt.failed" && envelope.event.clientMessageId !== promptId) return;
151
154
  print(envelope);
152
155
  answering?.accept(envelope.event);
153
156
  const { sessionId, event } = envelope;
@@ -234,28 +237,36 @@ async function attach(args) {
234
237
  }
235
238
  }
236
239
  async function send(args) {
237
- const { values, positionals: [sessionId, ...words] } = parseArgs({ args, allowPositionals: true, options: { json: { type: "boolean" } } });
240
+ const { values, positionals: [sessionId, ...words] } = parseArgs({ args, allowPositionals: true, options: { json: { type: "boolean" }, prompt: { type: "boolean" } } });
238
241
  const text = words.join(" ").trim();
239
242
  if (!sessionId || !text) throw new UsageError();
240
243
  const client = await connect(await start(), { name: "alp-cli", version: "1" });
244
+ let subscriptionId;
241
245
  try {
242
246
  const { session } = await client.request("session.get", { sessionId });
243
- if (session.parentId) {
247
+ if (session.parentId && !values.prompt) {
244
248
  await client.request("session.message", { sessionId, text });
245
249
  if (!values.json) console.error(`Sent to ${session.agent} as mail from the user`);
246
250
  return;
247
251
  }
248
- const done = follow(client, sessionId, printer(values.json), { untilIdle: true, interactive: !values.json && process.stdin.isTTY });
249
252
  const live = session.status === "idle" || session.status === "running";
250
- if (live) await client.request("session.attach", { sessionId, replay: false });
251
- else await client.request("session.create", { sessionId, spec: { cwd: session.projectRoot } });
252
- const steer = live && !!session.activeTurnId;
253
- await client.request("session.prompt", { sessionId, clientMessageId: randomUUID(), delivery: steer ? "steer" : "auto", content: [{ type: "text", text }] });
254
- if (!values.json) console.error(steer ? "Steered the running turn" : live ? "Started a turn" : "Resumed the session");
253
+ if (values.prompt && !live) throw new Error("Explicit prompts require a live session; use default alp send to reopen a root");
254
+ const clientMessageId = randomUUID();
255
+ const done = follow(client, sessionId, printer(values.json), { untilIdle: true, interactive: !values.json && process.stdin.isTTY, targetOnly: !!session.parentId, promptId: clientMessageId });
256
+ if (live) {
257
+ const attached = await client.request("session.attach", { sessionId, replay: false });
258
+ subscriptionId = attached.session.id;
259
+ } else {
260
+ await client.request("session.create", { sessionId, spec: { cwd: session.projectRoot } });
261
+ subscriptionId = sessionId;
262
+ }
263
+ const steer = !values.prompt && live && !!session.activeTurnId;
264
+ await client.request("session.prompt", { sessionId, clientMessageId, delivery: steer ? "steer" : "auto", content: [{ type: "text", text }] });
265
+ if (!values.json) console.error(values.prompt ? "Submitted an explicit prompt" : steer ? "Steered the running turn" : live ? "Started a turn" : "Resumed the session");
255
266
  if (!await done) process.exitCode = 1;
256
- await client.request("session.release", { sessionId }).catch(() => {
257
- });
258
267
  } finally {
268
+ if (subscriptionId) await client.request("session.release", { sessionId: subscriptionId }).catch(() => {
269
+ });
259
270
  client.close();
260
271
  }
261
272
  }
@@ -282,6 +293,7 @@ async function answer(args) {
282
293
  const { values, positionals: [questionId, ...words] } = parseArgs({ args, allowPositionals: true, options: { dismiss: { type: "boolean" }, reason: { type: "string" } } });
283
294
  const text = words.join(" ").trim();
284
295
  if (!questionId || (values.dismiss ? text : !text)) throw new UsageError();
296
+ if (isAgentProcess()) throw new Error(`Only the user answers a question; this process runs under an ALP agent (${AGENT_MARKER})`);
285
297
  const client = await running();
286
298
  const result = await client.request("question.answer", values.dismiss ? { questionId, dismiss: true, reason: values.reason } : { questionId, text }).finally(() => client.close());
287
299
  console.log(`${values.dismiss ? "Dismissed" : "Answered"} ${result.questionId}`);
@@ -356,6 +368,18 @@ async function log(args) {
356
368
  }
357
369
  for (const line of renderLog(rootId, entries)) console.log(line);
358
370
  }
371
+ async function models(args) {
372
+ const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { refresh: { type: "boolean" }, json: { type: "boolean" } } });
373
+ if (positionals.length) throw new UsageError();
374
+ const client = await running();
375
+ const catalog = await client.request(values.refresh ? "catalog.refresh" : "catalog.get", {}).finally(() => client.close());
376
+ if (values.json) {
377
+ console.log(JSON.stringify(catalog));
378
+ return;
379
+ }
380
+ for (const [runtime, state] of Object.entries(catalog.providers ?? {})) console.log(`${runtime}: ${state.status}${state.fetchedAt ? ` (${state.fetchedAt})` : ""}${state.error ? ` \u2014 ${state.error}` : ""}`);
381
+ for (const model of catalog.models) console.log(`${model.id.padEnd(40)} ${model.label}`);
382
+ }
359
383
  async function board(args) {
360
384
  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { project: { type: "string" }, json: { type: "boolean" } } });
361
385
  if (positionals.length) throw new UsageError();
@@ -424,14 +448,22 @@ async function interrupt(args) {
424
448
  await client.request("session.interrupt", { sessionId: args[0] }).finally(() => client.close());
425
449
  console.log("Interrupted");
426
450
  }
451
+ async function compact(args) {
452
+ if (args.length !== 1) throw new UsageError();
453
+ const client = await running();
454
+ const { status } = await client.request("session.compact", { sessionId: args[0] }).finally(() => client.close());
455
+ console.log(status === "started" ? "Compacting: main writes a checkpoint, then its context is compacted" : status === "running" ? "A compaction is already running" : "Compaction queued for the next turn boundary");
456
+ }
427
457
  export {
428
458
  answer,
429
459
  answerer,
430
460
  attach,
431
461
  board,
462
+ compact,
432
463
  follow,
433
464
  interrupt,
434
465
  log,
466
+ models,
435
467
  pause,
436
468
  printPauses,
437
469
  printer,
package/dist/tasks.js CHANGED
@@ -6,9 +6,11 @@ import { parseArgs } from "node:util";
6
6
  import { exportBeads, importBeads, parseJsonl } from "@anhlp/alp-core/beads";
7
7
  import { findFormula, formulaDirs, listFormulas, pourFormula } from "@anhlp/alp-core/formulas";
8
8
  import { describeVerification } from "@anhlp/alp-core/verify";
9
+ import { scriptCommand } from "@anhlp/alp-core/packaged";
9
10
  import { ago } from "@anhlp/alp-client/render";
10
11
  import { parse as toml } from "smol-toml";
11
- import { addGate, blockersOf, checkGates, childrenOf, closeTask, compactTasks, createTask, describeGate, gateOpen, epicReport, gatesOf, linkTask, listTasks, loadTasks, readyTasks, reopenTask, resolveGate, summarize, TASKS_DIR, updateTask } from "@anhlp/alp-core/tasks";
12
+ import { addGate, blockersOf, checkGates, childrenOf, closeTask, compactTasks, createTask, describeGate, gateOpen, epicReport, gatesOf, linkTask, listTasks, loadTasks, readyTasks, rejectGate, reopenTask, resolveGate, summarize, TASKS_DIR, updateTask, isAgentProcess, AGENT_MARKER } from "@anhlp/alp-core/tasks";
13
+ import { AlpError } from "@anhlp/alp-core/errors";
12
14
  import { alpHome } from "@anhlp/alp-client/index";
13
15
  import { UsageError } from "./usage.js";
14
16
  var STATUS_MARK = { open: "\u25CB", in_progress: "\u25D0", review: "\u25D1", closed: "\u25CF" };
@@ -62,7 +64,8 @@ async function tasksCommand(args) {
62
64
  var gh = (args, { cwd }) => new Promise((resolve, reject) => {
63
65
  const bin = process.env.ALP_GH_BIN ?? "gh";
64
66
  const script = process.platform === "win32" && /\.[cm]?js$/i.test(bin);
65
- const child = spawn(script ? process.execPath : bin, script ? [bin, ...args] : args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
67
+ const run = script ? scriptCommand(bin, args) : { command: bin, args };
68
+ const child = spawn(run.command, run.args, { cwd, ...run.env ? { env: { ...process.env, ...run.env } } : {}, stdio: ["ignore", "pipe", "pipe"] });
66
69
  let stdout = "";
67
70
  let stderr = "";
68
71
  child.stdout.on("data", (chunk) => {
@@ -227,7 +230,9 @@ async function taskCommand([action, ...args]) {
227
230
  human: { type: "string" },
228
231
  timer: { type: "string" },
229
232
  pr: { type: "string" },
230
- run: { type: "string" }
233
+ run: { type: "string" },
234
+ option: repeated,
235
+ choice: { type: "string" }
231
236
  } });
232
237
  const root = await taskProject(values.project);
233
238
  const fields = {
@@ -266,7 +271,7 @@ async function taskCommand([action, ...args]) {
266
271
  task = await updateTask(root, positionals[0], { ...fields, ...values.title !== void 0 ? { title: values.title } : {}, note: values.message }, "user");
267
272
  } else if (action === "close") {
268
273
  if (positionals.length !== 1) throw new UsageError();
269
- task = await closeTask(root, positionals[0], { reason: values.reason, summary: values.message, unverified: values.unverified }, "user");
274
+ task = await closeTask(root, positionals[0], { reason: values.reason, summary: values.message, unverified: values.unverified, agent: isAgentProcess(), channel: "cli" }, "user");
270
275
  } else if (action === "reopen") {
271
276
  if (positionals.length !== 1) throw new UsageError();
272
277
  task = await reopenTask(root, positionals[0], { note: values.message }, "user");
@@ -278,11 +283,20 @@ async function taskCommand([action, ...args]) {
278
283
  } else if (action === "gate") {
279
284
  const [change, id, gate, ...rest] = positionals;
280
285
  const kinds = ["human", "timer", "pr", "run"].filter((kind) => values[kind] !== void 0);
286
+ if (["clear", "reject", "rm"].includes(change) && id && gate && isAgentProcess()) {
287
+ const { tasks: current } = await loadTasks(root);
288
+ if (current.find((entry) => entry.id === id)?.gates.find((entry) => entry.id === gate)?.kind === "human") throw new AlpError("GATE_USER_ONLY", `Only the user clears a human gate; this process runs under an ALP agent (${AGENT_MARKER}). Ask the user to decide it`);
289
+ }
281
290
  if (change === "add" && id && !gate && kinds.length === 1) {
282
291
  const kind = kinds[0];
283
- task = await addGate(root, id, kind === "human" ? { kind, note: values.human } : kind === "timer" ? { kind, until: values.timer } : { kind: `gh:${kind}`, ref: values[kind] }, "user");
284
- } else if ((change === "clear" || change === "rm") && id && gate && !rest.length && !kinds.length) {
285
- task = await resolveGate(root, id, gate, { by: "user", note: values.message, remove: change === "rm" });
292
+ if (values.option && kind !== "human") throw new UsageError();
293
+ task = await addGate(root, id, kind === "human" ? { kind, note: values.human, ...values.option ? { options: values.option } : {} } : kind === "timer" ? { kind, until: values.timer } : { kind: `gh:${kind}`, ref: values[kind] }, "user");
294
+ } else if (change === "clear" && id && gate && !rest.length && !kinds.length && !values.option) {
295
+ task = await resolveGate(root, id, gate, { by: "user", note: values.message, channel: "cli", ...values.choice !== void 0 ? { choice: values.choice } : {} });
296
+ } else if (change === "reject" && id && gate && !rest.length && !kinds.length && !values.option && values.choice === void 0) {
297
+ task = await rejectGate(root, id, gate, { by: "user", reason: values.message, channel: "cli" });
298
+ } else if (change === "rm" && id && gate && !rest.length && !kinds.length && !values.option && values.choice === void 0) {
299
+ task = await resolveGate(root, id, gate, { by: "user", note: values.message, remove: true, channel: "cli" });
286
300
  } else {
287
301
  throw new UsageError();
288
302
  }
@@ -314,7 +328,7 @@ function printTask(task, tasks) {
314
328
  task.related.length && `related ${task.related.join(", ")}`
315
329
  ].filter(Boolean);
316
330
  if (relations.length) console.log(` ${relations.join("; ")}`);
317
- for (const gate of task.gates) console.log(` ${gateOpen(gate) ? "\u23F8" : "\u2713"} gate ${describeGate(gate)}${gate.resolved ? ` (cleared by ${gate.resolved.by}${gate.resolved.note ? `: ${gate.resolved.note}` : ""})` : ""}`);
331
+ for (const gate of task.gates) console.log(` ${gateOpen(gate) ? "\u23F8" : "\u2713"} gate ${describeGate(gate)}${gate.resolved ? ` (cleared by ${gate.resolved.by}${gate.resolved.choice ? ` with "${gate.resolved.choice}"` : ""}${gate.resolved.channel ? ` in ${gate.resolved.channel}` : ""}${gate.resolved.note ? `: ${gate.resolved.note}` : ""})` : gate.rejected ? ` (rejected by ${gate.rejected.by}${gate.rejected.reason ? `: ${gate.rejected.reason}` : ""})` : ""}${gateOpen(gate) && gate.options ? ` options: ${gate.options.join(" | ")}` : ""}${gate.tampered ? " \u26A0 changed outside ALP (a task file edit cleared or removed it); reopened for you to decide" : ""}`);
318
332
  const inherited = gatesOf(task, tasks).filter((label) => label.startsWith("t-"));
319
333
  if (task.status !== "closed" && inherited.length) console.log(` waits on its parent's gates: ${inherited.join("; ")}`);
320
334
  if (task.compacted) console.log(` compacted ${task.compacted.at.slice(0, 10)} from ${task.compacted.chars} characters`);
@@ -0,0 +1,201 @@
1
+ # Terminal native owner — candidate, platform matrix incomplete
2
+
3
+ Task t-d71b. Production `src/terminals.ts` now uses this identity-bound owner,
4
+ with no node-pty fallback on macOS or Linux. Linux may use the best-effort root-only mode described below;
5
+ Windows has no protection helper and uses node-pty (ConPTY), best-effort (see "Windows" below). This candidate is NOT accepted for release:
6
+ actual Linux (beyond CI capability checks) and Windows evidence remain missing. Missing or
7
+ unverifiable backends refuse terminal capability explicitly (no plain-PTY fallback on Linux); on Linux a verified helper without full protection (any reason) offers root-only compatibility (best-effort, user decision 2026-10-29). No end-user compiler
8
+ is required. Existing session authentication and host/Paseo opt-ins still apply.
9
+
10
+ ## Protocol and lifetime
11
+
12
+ One standalone C process owns forkpty, the startup gate, every signal and root
13
+ wait/reap. JS sends terminal input on stdin and resize (`R cols rows\n`) / cleanup
14
+ (`C\n`) on fd4. PTY output is stdout; fd3 contains bounded JSON ready, root-exit,
15
+ and cleanup records. Input/output queues and identity storage are bounded. Resizes coalesce behind
16
+ writable backpressure; cleanup closes the control pipe immediately. Native startup
17
+ polls the handshake/control descriptors with a 3s deadline; failure closes the
18
+ gate and attempts only identity-bound cleanup with a bounded nonblocking reap.
19
+
20
+ The child reports `getsid(0)==getpid()` before the parent releases its startup
21
+ gate. The owner acquires root identity before release, has default SIGCHLD and no
22
+ other reaper, and uses waitid(WNOWAIT) to observe natural exit. It retains the
23
+ root's live process or zombie until all discovery/signaling ends. This reserves
24
+ the root PID and prevents unrelated sessions reusing that session number. Only
25
+ processes proven to belong to that reserved session can be discovered. Observed
26
+ identities remain authorized if they subsequently leave the session. On the full-protection path there is no
27
+ marker, environment, age, PPid, parentuniqueid, TTY, numeric PID signal or numeric
28
+ group signal fallback. Never-observed children that immediately detach can be
29
+ missed (the approved g3 limit).
30
+
31
+ Linux opens a proc TGID directory with O_RDONLY|O_DIRECTORY (not O_PATH), reads
32
+ stat relative to that SAME descriptor, and uses pidfd_send_signal on that fd with
33
+ flags0/infoNULL. Capability probing checks kernel procfs and that /proc/self PID
34
+ and SID match the caller's namespace coordinates, and requires /proc/self/status
35
+ NSpid to have exactly one field equal to getpid() (proves the procfs PID namespace
36
+ is our active one without reading PID1, so it works for non-root users; missing
37
+ NSpid denies). A mount-privileged actor remounting /proc is outside this guarantee;
38
+ failure denies capability. Linux source has NOT been
39
+ compiled or executed here; permission/race/namespace/minimum-kernel evidence is
40
+ still required.
41
+
42
+ Darwin validates the complete private flavor17 56-byte struct and audit-token
43
+ version at runtime. Discovery uses U_before → reserved getsid → audit token →
44
+ U_after, requiring equal uniqueids and a matching token pidversion. Signals
45
+ refresh only a previously known uniqueid and use proc_signal_with_audittoken.
46
+ Unknown/changed identity never authorizes a numeric signal. Cleanup reports
47
+ observed/live/uncertain separately; it does not claim universal containment.
48
+
49
+ ## Accepted finite-generation Darwin limit
50
+
51
+ The Darwin final syscall compares PID + **32-bit global pidversion**, not the
52
+ 64-bit private uniqueid. Fork AND exec increment this global generation. If the
53
+ helper is suspended after its last identity check, enough global allocations can
54
+ wrap that generation and a recycled target PID can collide. Keeping a task-name
55
+ port or checking uniqueid again does not atomically bind the eventual syscall.
56
+ This is a source-derived limitation, not an executed 2^32-operation exploit.
57
+ The user explicitly accepted ONLY this residual in g4 (2026-10-29); ordinary PID
58
+ reuse protection, all native checks, packaging, platform tests and independent
59
+ review remain required. No blanket no-wrong-process waiver is inferred.
60
+
61
+ Kernel proof anchors (oracle 275c5e36, advice only; not implementation review):
62
+
63
+ - [XNU PID/zombie/session reservation and fork generations](https://github.com/apple-oss-distributions/xnu/blob/xnu-11215.1.10/bsd/kern/kern_fork.c#L877)
64
+ - [XNU WNOWAIT and reap hash removal](https://github.com/apple-oss-distributions/xnu/blob/xnu-11215.1.10/bsd/kern/kern_exit.c#L2457)
65
+ - [XNU setsid and cross-session restrictions](https://github.com/apple-oss-distributions/xnu/blob/xnu-11215.1.10/bsd/kern/kern_prot.c#L245)
66
+ - [XNU identity-info and final audit signal comparison](https://github.com/apple-oss-distributions/xnu/blob/xnu-11215.1.10/bsd/kern/proc_info.c#L3290)
67
+ - [XNU exec increments generation](https://github.com/apple-oss-distributions/xnu/blob/xnu-11215.1.10/bsd/kern/kern_exec.c#L6475)
68
+ - [Private ABI layout](https://github.com/apple-oss-distributions/xnu/blob/xnu-12377.1.9/bsd/sys/proc_info_private.h#L41)
69
+ - [Linux stored proc-directory identity](https://github.com/torvalds/linux/blob/v6.12/fs/proc/base.c#L3244)
70
+ - [Linux procdirfd signal dispatch](https://github.com/torvalds/linux/blob/v6.12/kernel/signal.c#L3647)
71
+ - [Linux stat session coordinates](https://github.com/torvalds/linux/blob/v6.12/fs/proc/array.c#L505)
72
+
73
+ ## Build, distribution and remaining platform evidence
74
+
75
+ `node scripts/build-terminal-native.mjs` is an EXPLICIT developer build, never
76
+ terminal startup or postinstall. Darwin also accepts `--arch=x64`/`--arch=arm64`
77
+ using the existing Apple compiler and ad-hoc codesign; capability execution must
78
+ succeed before a manifest is written. Hashes bind protocol, source and binary.
79
+ `node scripts/terminal-native-assets.mjs --require-matrix` and release pack-check
80
+ FAIL until all six slots exist: Darwin arm64/x64, Linux arm64/x64 × glibc/musl.
81
+ Builds copy only verified prebuilt assets beside root, daemon, CLI and Paseo bundles;
82
+ source-package daemon consumers also carry native source/hash manifests. They do
83
+ not invoke a compiler. A rebuild replaces the generated asset directory wholesale.
84
+
85
+ ### Committed prebuilts and the rebuild procedure (t-08cf)
86
+
87
+ All six slots are committed under `prebuilt/<slot>/` (binary with its exec bit, plus
88
+ `manifest.json` binding protocol, `terminal-owner.c` SHA-256 and binary SHA-256), so a
89
+ clean checkout passes `--require-matrix`, pack-check and the release clean-tree gate.
90
+ CI and releases ship the committed binaries; nothing is compiled during build or release.
91
+
92
+ The four Linux slots come from `.github/workflows/terminal-native.yml` (glibc on the
93
+ manylinux_2_28 floor image, musl on Alpine 3.20, each executed non-root in its own libc;
94
+ glibc also in fresh/ancestor PID namespaces). On every CI run that job rebuilds each slot
95
+ from the checked-out source, then requires the COMMITTED slot's manifest to record the
96
+ same source hash as the fresh build, its binary to match its manifest hash, and the
97
+ committed binary to pass the same execution checks. Builds are not byte-reproducible, so
98
+ binary hashes are NOT compared across builds: CI enforces source binding and execution,
99
+ not bit-for-bit provenance.
100
+
101
+ When `terminal-owner.c` changes, rebuild ALL six slots in the same commit:
102
+
103
+ 1. Darwin: on macOS, `node scripts/build-terminal-native.mjs --arch=arm64` and
104
+ `--arch=x64` (x64 capability executes through Rosetta).
105
+ 2. Linux: push the source change; the terminal-native jobs fail as stale but still upload
106
+ `terminal-native-<slot>` artifacts built from that exact revision. Download them into
107
+ an empty directory (`gh run download <run-id> -p 'terminal-native-*' -D <dir>`; each
108
+ lands as `<dir>/terminal-native-<slot>/<slot>.tar`) and extract each with
109
+ `tar -C packages/daemon/native/prebuilt -xpf <tar>` (tar keeps the exec bit).
110
+ 3. `node scripts/terminal-native-assets.mjs --require-matrix`, commit all six slots, and
111
+ check the next CI run is green.
112
+
113
+ Current artifacts: Darwin arm64 executed on macOS27, Darwin x64 capability executed
114
+ through existing Rosetta on that same host. Both target macOS11.0 (LC_BUILD_VERSION),
115
+ matching [Node22's macOS floor](https://github.com/nodejs/node/blob/v22.23.0/BUILDING.md#platform-list).
116
+ This deployment target is NOT proof of runtime compatibility on macOS11 or physical
117
+ x64 hardware. Private-ABI capability validation still fails closed. Linux builds
118
+ must retain the existing libc support baseline (Node22 glibc2.28). The committed Linux
119
+ artifacts were built and capability-executed by CI run 40857935251 (GitHub-hosted
120
+ Ubuntu 24.04 kernels); minimum-kernel execution has not been proved. pidfd_send_signal (Linux5.1 syscall baseline) selects full protection. Without it
121
+ Linux runs the best-effort root-only mode described below, disclosed with a non-blocking notice.
122
+ No permission denial or artifact failure silently selects compatibility.
123
+
124
+ Async startup reserves request IDs and quota before native readiness. Revoke,
125
+ shutdown and host optout cancel startup and await native cleanup before returning;
126
+ late readiness cannot publish an orphan terminal. Root exit is delivered after
127
+ stdio drains. The helper reads the PTY to EOF and advances partial output writes
128
+ for up to one further second; an undrained tail reports explicit uncertainty. Cleanup reports observed/live/uncertain, and uncertain/live results
129
+ refuse success and stop further terminal admission. The existing real PTY cleanup
130
+ scenarios now execute through the native owner (including exec, same-session
131
+ orphans and a late child). Never-observed immediate-setsid escapes remain the
132
+ approved g3 discovery limit. Actual Linux/Windows browser keyboard and Linux
133
+ namespace/proc permissions/races remain NOT_CHECKED.
134
+
135
+ Explicit developer regressions (require a local C compiler, not end-user startup):
136
+ `node --test packages/daemon/native/tests/lifecycle.mjs` exercises delayed native
137
+ startup and a real stalled control reader. `ALP_NATIVE_BASELINE=8ed11fd` runs the
138
+ same checks against the committed pre-correction C/TS in isolated scratch space.
139
+ This mode does not change the checkout. Both cases fail on that baseline and pass
140
+ on the correction. Ordinary lifecycle tests run separately from daemon/tests.
141
+
142
+ ## Linux root-only compatibility candidate (g5)
143
+
144
+ Linux is best-effort (user decision 2026-10-29; only macOS is guaranteed). A verified
145
+ helper that fails full protection for ANY reason (ENOSYS, EPERM/EACCES, procfs or
146
+ PID-namespace mismatch) advertises `alp-terminal-owner:1:root-only`; root-only mode
147
+ only signals the unreaped session root and, after the startup capability probe, does not use procfs or pidfd, so
148
+ background jobs may survive close. A corrupt/missing binary or manifest, timeout,
149
+ crash or malformed record still refuses capability (no unverified code runs).
150
+ The owner revalidates immediately before fork; a mode change refuses before shell
151
+ launch, and alpd probes the helper again for the next create.
152
+
153
+ Root-only terminals open directly: no acknowledgment is required (user decision
154
+ 2026-10-29, Linux and Windows are best-effort like Orca/Paseo). The deprecated
155
+ `protectionAcknowledgment: "linux-root-only-v1"` parameter is still accepted on
156
+ `terminal.create`/`terminal.attach` for compatibility and ignored. Terminal records
157
+ carry `protection: "root-only"`, so clients disclose the limit: ALP Web shows one
158
+ non-blocking notice ("Limited protection on this Linux host: closing the terminal may
159
+ not stop background processes."), and the terminal stays usable. Paseo's terminal
160
+ protocol has no notice field, so the ALP bridge writes the same notice once as a
161
+ dim line into each Paseo client's view of the terminal (never into alpd's output).
162
+
163
+ Compatibility never scans or explicitly signals descendants or process groups.
164
+ Only its own direct root is signaled, before final reap, with SIGCHLD explicitly
165
+ SIG_DFL and SA_NOCLDWAIT cleared by checked sigaction. A living child or WNOWAIT
166
+ zombie continuously reserves its PID; an unexpected ECHILD permanently retires
167
+ numeric authority. Final reap is checked. This is spawn ownership, not a snapshot
168
+ or a numeric PID-reuse heuristic; helper compromise invalidates that premise.
169
+ Kernel PTY hangup and line-discipline signals may naturally affect foreground jobs.
170
+
171
+ Known reduced coverage is `coverage: "root-only"`; successful cleanup establishes
172
+ only the shell's exit. Unmanaged jobs can survive close/revoke/optout/shutdown and
173
+ keep the PTY open (`outputOpen: true` after bounded draining). This accepted known
174
+ coverage limit alone does not lock admission. Root live/lost ownership, queued
175
+ bytes not delivered, protocol loss or sticky adapter failure remain uncertainty
176
+ and retain the admission lock. No delayed signals occur after root reap.
177
+
178
+ Advice/source proof: oracle18a20d0e examined [Linux5.1 wait/ptrace reap](https://github.com/torvalds/linux/blob/v5.1/kernel/exit.c)
179
+ and [original procdirfd signal dispatch](https://github.com/torvalds/linux/blob/v5.1/kernel/signal.c).
180
+ Actual Linux compilation/execution (old and supported kernel, namespace/permission,
181
+ ptrace/exec/reuse/race) remains NOT_CHECKED here; the four shipped Linux artifacts are committed and CI capability-checked.
182
+ Darwin author regressions validate the unchanged full path only; no seam/mock or
183
+ Rosetta execution is claimed as Linux or physical-x64/minimum-macOS proof.
184
+
185
+ ## Windows (best-effort, no protection helper)
186
+
187
+ There is no Windows native owner and pack-check requires no Windows slot. On win32,
188
+ `src/terminals.ts` spawns the shell (`%ComSpec%`, else `cmd.exe`) through node-pty
189
+ (ConPTY), the same platform PTY Paseo uses; node-pty is an optional dependency, and
190
+ when it cannot load, terminals refuse with `terminal_unsupported`. Terminals report
191
+ `protection: "none"`, and clients show a "not guaranteed on Windows" notice. Closing,
192
+ revoking or turning off terminals calls node-pty `kill()` (best-effort): the shell
193
+ ends, but processes it started may keep running. This is the only production use of
194
+ node-pty. Windows behavior has NOT been executed here; only injected-owner unit tests ran.
195
+
196
+ ## Termination signals
197
+
198
+ SIGTERM, SIGINT and SIGHUP sent to the owner (for example to the daemon's process group)
199
+ start the same bound cleanup as closing its control pipe, on every platform including
200
+ macOS (deliberate: previously such a signal killed the owner before cleanup). The shell
201
+ child resets them to default before exec.
@@ -0,0 +1,11 @@
1
+ {
2
+ "protocol": 1,
3
+ "slot": "darwin-arm64",
4
+ "source": "d2fa72ce0b083e60cddbe76839365beaa80b891451b45987d968b805154d0636",
5
+ "sha256": "354f50aea9e8d5113fc9fb4fd90ccb417d8aad74b89473fdcb711c6d1253f367",
6
+ "buildHost": "v22.23.4",
7
+ "deploymentTarget": "11.0",
8
+ "executionChecked": true,
9
+ "executionProtection": "identity-bound",
10
+ "executionHost": "darwin-arm64"
11
+ }
@@ -0,0 +1,11 @@
1
+ {
2
+ "protocol": 1,
3
+ "slot": "darwin-x64",
4
+ "source": "d2fa72ce0b083e60cddbe76839365beaa80b891451b45987d968b805154d0636",
5
+ "sha256": "606a0bd9a0ae76550156d343c89efa69d97215b8bf95c6aadbf38b6468a041e5",
6
+ "buildHost": "v22.23.4",
7
+ "deploymentTarget": "11.0",
8
+ "executionChecked": true,
9
+ "executionProtection": "identity-bound",
10
+ "executionHost": "darwin-arm64"
11
+ }
@@ -0,0 +1,10 @@
1
+ {
2
+ "protocol": 1,
3
+ "slot": "linux-arm64-glibc",
4
+ "source": "d2fa72ce0b083e60cddbe76839365beaa80b891451b45987d968b805154d0636",
5
+ "sha256": "fa6e8b66f8e449d6fa294518c7f7d107e0707d2048623cc4952031b9580c31e3",
6
+ "buildHost": "v22.23.4",
7
+ "executionChecked": true,
8
+ "executionProtection": "identity-bound",
9
+ "executionHost": "linux-arm64"
10
+ }
@@ -0,0 +1,10 @@
1
+ {
2
+ "protocol": 1,
3
+ "slot": "linux-arm64-musl",
4
+ "source": "d2fa72ce0b083e60cddbe76839365beaa80b891451b45987d968b805154d0636",
5
+ "sha256": "e6935d27c14c626b3207ea8edecd4a56b6bf13c8634b97a7480928e4bd22e9d6",
6
+ "buildHost": "v20.15.1",
7
+ "executionChecked": true,
8
+ "executionProtection": "identity-bound",
9
+ "executionHost": "linux-arm64"
10
+ }
@@ -0,0 +1,10 @@
1
+ {
2
+ "protocol": 1,
3
+ "slot": "linux-x64-glibc",
4
+ "source": "d2fa72ce0b083e60cddbe76839365beaa80b891451b45987d968b805154d0636",
5
+ "sha256": "4746db2e0b89ffd81f9ab14da871a8a8a59b39d219ab9612bb86faa8d8db35b7",
6
+ "buildHost": "v22.23.4",
7
+ "executionChecked": true,
8
+ "executionProtection": "identity-bound",
9
+ "executionHost": "linux-x64"
10
+ }
@@ -0,0 +1,10 @@
1
+ {
2
+ "protocol": 1,
3
+ "slot": "linux-x64-musl",
4
+ "source": "d2fa72ce0b083e60cddbe76839365beaa80b891451b45987d968b805154d0636",
5
+ "sha256": "5d3e964057212ce231ab920426012ede944057138613712f0cf52a81f1397c2d",
6
+ "buildHost": "v20.15.1",
7
+ "executionChecked": true,
8
+ "executionProtection": "identity-bound",
9
+ "executionHost": "linux-x64"
10
+ }