Make pty kill verify and finish the kill, read the process table in one place, and stop waiting to say a name is taken (#170)

* Say what the kill verified, not what it hoped

`pty kill` signals the daemon and waits for that one pid. It then prints
`Session "X" killed.` The child, and everything the child started, is never
looked at. The word is a claim about a session made on evidence about a
daemon.

This takes a snapshot of the daemon's process tree before the signal, and
re-checks it after the daemon exits. The success line now appears only when
every process in the snapshot is gone. Otherwise the command prints
`Session "X" daemon stopped.`, which is the part it verified, and names the
survivors on standard error.

The snapshot must come first. After the daemon exits its children reparent
away, so the links that identify them are gone. The pre-kill snapshot is also
taken at a calm moment, while the daemon takes its own during shutdown, so the
command can see a process the daemon's teardown skipped.

A pid is reported as surviving only when its start token still matches. A
token that cannot be read on a process that has not exited is reported
separately as undecided, rather than being folded into either answer.

A zombie is not a survivor. It answers `kill(pid, 0)` and keeps its start
token, so the check reads the process state through `hasProcessExitedForReap`.

Two supporting changes:

A daemon that could not kill a descendant now appends
`session_descendants_survived` to the session event log, and names the pids in
its stderr warning. The daemon's stderr has no reader. The Rust tool already
writes this event; this closes the gap.

On macOS, an empty `ps -o stat=` field no longer counts as a dead process. An
empty field means the process is gone or `ps` did not answer, and under load
`ps` is the thing that goes quiet. The new check depends on this predicate, so
it had to stop reading silence as death.

This sends no additional signals.

* Make the exit status agree with the words

`pty kill` printed a survivor report and exited 0. A caller that reads only the
status reached the opposite conclusion from one that reads the output, which
leaves the honest line as decoration.

It now exits non-zero when anything survived, and when a start token could not
be read so the outcome is undecided. "I could not confirm the tree is empty" is
not success.

This is a compatibility break. A script that checks the status of `pty kill`
will fail where it used to pass, because it was passing on a false success. The
fix for such a caller is to stop treating an unverified kill as a completed one.

Nathan decided the survivor case on 2026-09-03. Silber.cos decided the
undecidable one.

* Finish the kill instead of reporting that it did not

The daemon tears down the child's tree on its way out, so the teardown races
its own exit. Whatever it does not manage is nobody's work after that, and the
command that outlives it does nothing about it.

`pty kill` now re-reads the process table after the daemon has gone. If
anything from its pre-kill snapshot is still alive, it signals the process
groups the session left behind, waits, escalates to SIGKILL, reads the table
again, and reports what is still there. It never reports the sending.

Process groups rather than pids, because a group signal needs no identity. The
snapshot drops a descendant whose start token cannot be read, and that process
is then never signalled; groups are collected from the raw listing, so it is
reached anyway. The blind spot is not solved, it is made irrelevant. A sweep
also costs one `ps` in total, against one per descendant for tokens.

The daemon's own group is never a target. The pty child calls setsid, so the
daemon sits alone in its group and signalling it reaches the daemon only. The
running process's own group is never a target either, so the command survives
to print its result.

A zombie is not a group member. `ps` lists it with its group, so counting it
makes the sweep report a group it has already emptied. A test against a real
process group found this; inspection did not.

* Do not call a tree empty while the escalation left something running

The success line and the exit status read only the pre-kill snapshot. That
snapshot drops a descendant whose start token could not be read, and it never
contained a process spawned after it was taken. So a process the sweep found
and could not kill can be absent from it entirely, and the command would print
`killed` and exit 0 over a process that had just survived SIGKILL.

That is the defect this command exists to stop making, reintroduced by the
escalation that was supposed to end it. Both halves are now required: the
snapshot must be clear AND the sweep must have left nothing behind.

Found by reading the diff rather than by a failing test, so the test came
after; it fails without the fix.

* Read the process table in one place, and stop spawning ps on Linux

Every caller that needed a fact about a process ran its own `ps` and treated
the output as fact. A subprocess can be slow, truncated or silent, and all
three look exactly like "the process is gone".

Node cannot make the syscalls the Rust tool uses, so this does what Node can.
On Linux there is now no subprocess at all: `/proc` carries ppid, pgid, state
and starttime, which is every fact the callers ask for. On macOS `ps` stays,
but the table is read once per operation rather than once per process per
poll. In the teardown loop that is the difference between 240 spawns inside a
1500 ms deadline and 60.

Silence is a third answer everywhere. Every query separates the fact from "the
table was read and this process is not in it" from "I could not find out",
with no default and no conversion that turns the last into the middle by
accident. Treating silence as death requires calling
`orAbsentWhenUnknown`, which greps in one command. That makes the mistake
visible rather than impossible.

A listing that does not contain the process that read it was truncated, not
empty. `ps` always lists itself.

`recovery.processStartToken` is untouched and still comes from `ps -o lstart=`.
Its exact text is a contract with the Rust tool through a shared registry, so
the parser takes the tail verbatim rather than re-joining split fields, which
would have rewritten `Wed Sep  3` as `Wed Sep 3`. The in-memory identity is a
separate branded type so the two can never be compared.

Production `ps` call sites: six to three, none in a per-process poll loop.

* Do not count a corpse as a surviving descendant

An unreaped descendant keeps its `/proc` row and its identity on Linux, so
matching on identity alone counted it as alive. The teardown would wait out its
whole TERM budget for a process that had already died, and then report it as
having survived a SIGKILL. That is the kill over-claiming again, in the other
direction.

macOS never had this, because `ps` stops listing a process the moment it exits.
The two platforms disagreeing is what exposed it.

Two test fixes from a real Mac run, reported by Silber.pty:

macOS has the `setsid` system call but no `setsid` executable. The real
process-group test spawned the binary, so on the one platform where process
groups are the whole escalation story, the test could not run at all. It now
uses `detached: true`, which is the same thing without the command.

The zombie test asserted the Linux mechanism rather than the conclusion. On
Linux the corpse keeps a row with state Z; on macOS it is dropped from the
listing at once. The test now asserts what every caller depends on, which is
the same on both.

A single-pid query no longer reads the whole table. `hasProcessExitedForReap`
sits inside poll loops that run every 25 ms, and asking about one pid should
not pay for every process on the machine.

* Parse what ps writes, not what the parser expected

The single-process read handed the subprocess's raw stdout to the single-line
parser. `ps` ends its output with a newline and that parser's `$` does not match
before one, so on macOS a live process read as "field-empty" and a zombie read
as NOT EXITED. The teardown would then have waited out its whole budget for a
corpse.

That is the corpse defect a third time, reintroduced by a second parsing path
that Linux never exercised, because on Linux this read goes to `/proc`.

There is one parser now. The single-process read goes through
`parsePsListing`, which splits lines first and checks that the row for the pid
it asked about is actually present, so both jobs are done by the code that was
already tested.

The other two `ps` call sites were checked for the same seam. `server.ts` and
`recovery.ts` both trim before parsing; only the path added by this branch did
not.

Nothing caught it because every test built its input the way the parser
expected. They all agreed with each other and none of them agreed with `ps`. So
there is now a test that runs the real command with the real arguments and feeds
the parser exactly what the subprocess wrote, newline and all. Reverting to the
old behaviour fails it.

Found on a real Mac by Silber.pty.

* Say "is already running" at once instead of after thirty seconds

A `pty run` that loses a creation race waited out the whole start budget and
then reported a generic publication timeout.

`wait_for_publication` compares the published metadata against its OWN pid, so
for a loser that check is false for the rest of the budget. Its only other way
out of the loop is noticing its own daemon die. When that is slow — a loaded
machine, a daemon still starting up — the loop spends the entire thirty second
default and reports a timeout, when the true answer was on disk in the first
iteration.

Measured on a Mac by Silber.pty on 2026-09-03: 30.06 s against a 30 s budget,
saying "Timed out waiting for daemon publication" instead of "is already
running".

The loop now checks whether the name is published by a live process that is not
us, and stops with the sentence `pty run` already prints when it sees a running
session before it spawns. Losing the race later should not produce a different
explanation of the same situation.

All three conditions matter and each is tested. Published, or a name whose
metadata is still being written would be refused. A different pid, or a
successful spawn would refuse itself. A live one, or stale metadata from a dead
daemon would make the name permanently unusable.

The safety property was never in question. The test that found this asserts
exactly one winner before it checks the loser message, and that assertion
passed every time. What was wrong is what the loser said, and how long it took.

* Do not call a zombie daemon a live owner

The new check refuses a session name when it is published by a live process
that is not us. It asked `pid_alive` / `isProcessAlive`, and a zombie answers
`kill(pid, 0)`. So an unreaped daemon would have counted as live and the name
would have been refused for as long as the corpse went unreaped.

That is the exact failure the liveness condition exists to prevent, arrived at
by the check that was supposed to prevent it. An unreaped daemon is the precise
case that matters here: dead, not reaped, still in the process list.

Both now ask `has_process_exited_for_reap` / `hasProcessExitedForReap`, which
reads the process state and counts a zombie as gone.

Tested against a real corpse in both languages, with the predicate the
production path actually passes. Reverting to the cheap predicate fails both.

Node also exports `hasProcessExitedForReap`, which was private.

Silber.cos asked what this check does with a zombie daemon on macOS. The answer
was worse than the question: it was wrong on both platforms.

* Do not call a name in use when nothing alive is using it

`pty run --id X` refused when a session record named X existed on disk, without
asking whether anything was answering for it. A record whose owner is a zombie
has no socket, so the name was unusable until something reaped the corpse.

That is the same failure the liveness check in the spawner exists to prevent,
one command earlier and still shipping.

The Rust tool already asks `session_exists(name) && client::is_alive(name)`
here. This adds the missing half: `isSessionAlive`, a faithful port of
`client::is_alive`, which is a socket connect.

Measured on a Mac by Silber.pty on 2026-09-03 with a real zombie owner: Rust
created a replacement in 186 ms, Node exited 1 with "is already in use".
Verified end to end on Linux with a real zombie-owned record and no socket:
Node now creates the session, and reverting the liveness condition refuses it
again.

Author: myobie

CHANGELOG.md

@@ -2,6 +2,73 @@
 
 ## Unreleased
 
+### One reader for the process table
+
+- Process facts now come from one module. On Linux it reads `/proc` and spawns
+  nothing at all. On macOS `ps` remains, but it is read once per operation
+  rather than once per process per poll — the difference between 240 spawns
+  inside a 1500 ms deadline and 60.
+- Every query separates three answers: the fact, "the table was read and this
+  process is not in it", and "I could not find out". A `ps` that is slow,
+  truncated or silent now produces the third rather than the second. There is
+  no default and no conversion that turns silence into absence by accident.
+- A listing that does not contain the process that read it is treated as
+  truncated rather than as an empty machine. `ps` always lists at least itself.
+- `recovery.processStartToken` is unchanged and still comes from
+  `ps -o lstart=`. Its exact text, including the two spaces before a
+  single-digit day, is a contract with the Rust tool through a shared registry.
+  The in-memory identity used by the teardown is a separate branded type so the
+  two cannot be compared by accident.
+- Production `ps` call sites: six down to three, and none of them inside a
+  per-process poll loop.
+
+### `pty kill` finishes the job
+
+- After the daemon has gone, `pty kill` re-reads the process table. If anything
+  from its pre-kill snapshot is still alive, it signals the process groups the
+  session left behind, waits, escalates to SIGKILL, reads the table again, and
+  reports what is still there. The daemon tears the tree down on its way out, so
+  its teardown races its own exit; the command outlives the daemon and can
+  finish the work.
+- The sweep targets process groups rather than PIDs, because a group signal
+  needs no per-process identity. A descendant whose process-start token cannot
+  be read is dropped from the snapshot and never signalled individually; its
+  group is still swept. The sweep also costs one `ps` call in total, against one
+  per descendant for tokens.
+- The daemon's own process group is never signalled. The PTY child calls
+  `setsid`, so the daemon is alone in its group. The group of the process
+  running `pty kill` is never signalled either, so the command survives to
+  report. Group id 1 and below are never signalled.
+- A zombie no longer counts as a process-group member. `ps` lists it with its
+  group, so counting it made the sweep report a group it had already emptied.
+
+### `pty kill` reports what it verified
+
+- `pty kill` prints `Session "X" killed.` only when the session's process tree
+  is gone. It takes a snapshot of the tree before it signals the daemon, and
+  re-checks that snapshot after the daemon exits. Before this, the command
+  asked about the daemon and reported about the session, so the success line
+  was a claim about processes it never looked at.
+- When something outlives the kill, the command prints
+  `Session "X" daemon stopped.` on standard output, which is the part it
+  verified, and names the surviving PIDs on standard error. A PID is called a
+  survivor only when its process-start token still matches. A PID that has not
+  exited but whose token cannot be read is reported separately as undecided.
+- A daemon that could not kill a descendant now appends
+  `session_descendants_survived` to the session event log, and its standard
+  error warning names the PIDs. The daemon's standard error has no reader, so
+  the log line is the copy a person can find.
+- `pty kill` sends no additional signals and waits no longer than before.
+- **Compatibility break.** `pty kill` now exits non-zero when anything survived,
+  and when a start token could not be read so the outcome is undecided. A script
+  that checks the status of `pty kill` will fail where it used to pass, because
+  it was passing on a false success. The fix for such a caller is to stop
+  treating an unverified kill as a completed one. A verified empty tree still
+  exits 0.
+- On macOS, an empty `ps -o stat=` field no longer counts as a dead process.
+  An empty field means the process is gone or `ps` did not answer, and under
+  load `ps` is the thing that goes quiet, so the kernel is asked again.
+
 ### Complete session termination
 
 - `pty kill` now stops the PTY child and its complete descendant tree. A
@@ -28,6 +95,12 @@
 
 ### Storage format
 
+- New event type `session_descendants_survived`, carrying `data: { pids }`.
+  A daemon appends it when it signalled its child's process tree with TERM and
+  then KILL and found processes still alive. It records what the daemon could
+  not kill; a process that left the tree before the snapshot is not in it.
+
+
 - Supporting live daemons now advertise a `recovery` capability in session
   metadata. `pty recover <name> --snapshot <file>` uses that captured
   capability to authenticate a signal-free listener/registry rebind after an

docs/disk-layout.md

@@ -133,6 +133,7 @@ Envelope: `{ session: string; type: string; ts: string; ...payload }`. Event typ
 | `session_respawn` | — (`pty gc` respawned a `strategy=permanent` session) |
 | `session_abandoned` | `reason: "cwd-gone" \| "idle", idleDays?` — (`pty gc` reaped a live permanent session detected as abandoned) |
 | `session_flapping` | `counter, limit, window` — (`pty gc` flipped a permanent session to `strategy.status=flapping` after N consecutive fast-fail respawns; subsequent ticks skip it) |
+| `session_descendants_survived` | `data: { pids }` — a daemon signalled its child's process tree with TERM and then KILL and these processes were still alive. A record of what it could not kill, not a list of everything that outlived the session: a process that left the tree before the snapshot is not in it |
 | `display_name_change` | `previous: string\|null, value: string\|null` |
 | `tags_change` | `previous, value` (full snapshots) |
 | `metadata_change` | `previous, value` containing only changed `displayName` and tag keys; absent tag values are `null` |

src/cli.ts

@@ -4,7 +4,9 @@ import * as path from "node:path";
 import * as readline from "node:readline/promises";
 import { spawnSync, execFileSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { attach, peek, send, queryStats, resolveSeqDelayMs, validateAttachStreamFdV1, type StatsResult } from "./client.ts";
+import { attach, peek, send, queryStats, resolveSeqDelayMs, validateAttachStreamFdV1, type StatsResult,
+  isSessionAlive,
+} from "./client.ts";
 import { printVersion } from "./version.ts";
 import { parseSeqValue } from "./keys.ts";
 import {
@@ -42,9 +44,16 @@ import {
   getPidPath,
   getMetadataPath,
   DEFAULT_SESSION_DIR,
+  hasProcessExitedForReap,
   type SessionInfo,
   type SessionMetadata,
 } from "./sessions.ts";
+import { snapshotDescendantProcesses } from "./process-tree.ts";
+import { aftermathOf, allGone, killOutcomeLines, verifiedEmpty } from "./kill-report.ts";
+import {
+  groupsInTree, membersOfGroups, ownProcessGroup, signalGroup, sweepGroups,
+} from "./process-groups.ts";
+import { openSource, valueOf } from "./proc-table.ts";
 import { spawnDaemon, resolveCommand } from "./spawn.ts";
 import {
   acquireEventLock, appendEventSyncLocked, EventFollower, EventWriter, EventType, releaseEventLock,
@@ -295,6 +304,14 @@ Examples:
 Terminate a running session's daemon and exact descendant tree. Metadata is kept —
 restart or \`pty rm\` it later.
 
+The daemon tears the tree down on its way out, which races its own exit. So once
+the daemon has gone, \`pty kill\` re-reads the process table, signals any process
+group the session left behind, and reports what is still there. It exits non-zero
+unless it verified the tree is empty.
+
+A descendant that calls setsid leaves the session and the group, and neither the
+tree walk nor the group sweep can reach it.
+
 Examples:
   pty kill myserver`,
 
@@ -935,7 +952,17 @@ async function main(): Promise<void> {
           console.error(e.message);
           process.exit(1);
         }
-        if (existingNames.has(explicitId) && !attachExisting) {
+        // **"In use" has to mean in use by something alive.** A name that
+        // merely exists on disk is not taken: a record whose owner is a zombie
+        // has no socket to answer, and refusing it would make that session name
+        // unusable until something reaped the corpse — the exact failure the
+        // liveness check in `spawn.ts` exists to prevent, one command earlier.
+        //
+        // The Rust tool asks `session_exists(name) && client::is_alive(name)`
+        // here. This is the same question. Measured on a Mac by Silber.pty on
+        // 2026-09-03: with a zombie owner, Rust created a replacement in 186 ms
+        // and Node exited 1.
+        if (existingNames.has(explicitId) && !attachExisting && await isSessionAlive(explicitId)) {
           console.error(`Session id "${explicitId}" is already in use.`);
           process.exit(1);
         }
@@ -2615,6 +2642,23 @@ function formatUptime(seconds: number | null): string {
   return `${d}d ${h % 24}h`;
 }
 
+/** How long the escalation gives a group to answer SIGTERM before it stops
+ *  asking. A coding agent was measured ignoring SIGTERM for ten seconds, so
+ *  this grace is a courtesy, not a plan. */
+const ESCALATE_TERM_WAIT_MS = 2_000;
+/** How long to wait after SIGKILL before reporting what is still there. */
+const ESCALATE_KILL_WAIT_MS = 1_000;
+
+/** TERM the groups, wait, KILL what is left, wait, then re-read the process
+ *  table. Returns the pids still alive in those groups. */
+async function escalateOverGroups(groups: number[]): Promise<number[]> {
+  return sweepGroups(groups, ownProcessGroup(), ESCALATE_TERM_WAIT_MS, ESCALATE_KILL_WAIT_MS, {
+    live: (targets) => membersOfGroups(targets, openSource()),
+    signal: signalGroup,
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+  });
+}
+
 async function cmdKill(name: string): Promise<void> {
   const session = await getSession(name);
 
@@ -2637,6 +2681,16 @@ async function cmdKill(name: string): Promise<void> {
     } catch {}
   }
 
+  // Take the tree BEFORE the signal. After the daemon exits its children are
+  // reparented to init or a subreaper, so the parent links that identify them
+  // as this session's processes are gone. This snapshot is the only chance to
+  // learn which processes the word "killed" would be a claim about.
+  const before = snapshotDescendantProcesses(session.pid);
+  // Groups come from the raw listing, NOT from `before`. The snapshot drops a
+  // descendant whose start token cannot be read, and that process is then never
+  // signalled. A group needs no identity, so this reaches it anyway.
+  const groups = groupsInTree(session.pid, openSource());
+
   try {
     process.kill(session.pid, "SIGTERM");
   } catch {
@@ -2662,7 +2716,24 @@ async function cmdKill(name: string): Promise<void> {
     return;
   }
   cleanupSocket(name);
-  console.log(`Session "${name}" killed.`);
+  let after = aftermathOf(before, readProcessStartToken, hasProcessExitedForReap);
+  let escalated: number[] | undefined;
+  if (!allGone(after)) {
+    escalated = await escalateOverGroups(groups);
+    // Re-measure. The report must describe the machine now, not the signals
+    // that were sent at it.
+    const again = openSource();
+    after = aftermathOf(
+      before,
+      (pid) => valueOf(again.identity(pid)),
+      hasProcessExitedForReap,
+    );
+  }
+  const outcome = killOutcomeLines(name, after, escalated);
+  for (const line of outcome.out) console.log(line);
+  for (const line of outcome.err) console.error(line);
+  // Anything left is a failure, and the status says so.
+  if (!verifiedEmpty(after, escalated)) process.exitCode = 1;
 
   if (wasPermanent && session.metadata?.tags?.ptyfile) {
     console.error(`Note: this session is managed by ${session.metadata.tags.ptyfile}`);

src/client.ts

@@ -17,6 +17,29 @@ import { getSocketPath } from "./sessions.ts";
 import { stripAnsi } from "./tui/colors.ts";
 import { BRACKETED_PASTE_START, BRACKETED_PASTE_END } from "./paste.ts";
 
+/** Can anything answer on this session's socket?
+ *
+ *  The Rust tool's `client::is_alive`, which is `connect(name).is_ok()`. A name
+ *  that merely EXISTS on disk is not a name that is in use: a record whose
+ *  owner is a zombie has no socket to answer, and refusing it would make that
+ *  session name unusable until something reaped the corpse.
+ */
+export function isSessionAlive(name: string, timeoutMs = 250): Promise<boolean> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (alive: boolean) => {
+      if (settled) return;
+      settled = true;
+      try { socket.destroy(); } catch {}
+      resolve(alive);
+    };
+    const socket = net.createConnection(getSocketPath(name));
+    socket.setTimeout(timeoutMs, () => done(false));
+    socket.once("connect", () => done(true));
+    socket.once("error", () => done(false));
+  });
+}
+
 const DETACH_KEY = 0x1c; // Ctrl+\ (legacy encoding)
 const DETACH_KEY_KITTY = "\x1b[92;5u"; // Ctrl+\ (Kitty keyboard protocol)
 

src/events.ts

@@ -19,6 +19,7 @@ export const EventType = {
   SESSION_RESPAWN: "session_respawn",
   SESSION_ABANDONED: "session_abandoned",
   SESSION_FLAPPING: "session_flapping",
+  SESSION_DESCENDANTS_SURVIVED: "session_descendants_survived",
 } as const;
 
 export type EventType = (typeof EventType)[keyof typeof EventType];
@@ -85,6 +86,21 @@ export interface SessionExecEvent extends EventBase {
   command: string;
 }
 
+/** Emitted by a daemon that signalled its child's process tree with TERM and
+ *  then KILL and found processes still alive. The daemon also warns on its own
+ *  standard error, which has had no reader since the command that launched it
+ *  stopped listening — so this log line is the copy a person can find.
+ *
+ *  A record, not a guarantee: the daemon reports what it could not kill, and
+ *  cannot report a process that left its tree before the snapshot. */
+export interface SessionDescendantsSurvivedEvent extends EventBase {
+  type: "session_descendants_survived";
+  /** The surviving pids, deepest descendant first. Nested under `data` to
+   *  match the Rust tool byte for byte; both render through the unknown-type
+   *  fallback, so the printed line is identical. */
+  data: { pids: number[] };
+}
+
 /** Emitted by `pty gc` whenever it respawns a `strategy=permanent`
  *  session that's exited/vanished. Carries no payload beyond the
  *  envelope — the restart is stateless, there is no attempt counter,
@@ -185,6 +201,7 @@ export type EventRecord =
   | SessionRespawnEvent
   | SessionAbandonedEvent
   | SessionFlappingEvent
+  | SessionDescendantsSurvivedEvent
   | UserEvent
   | DisplayNameChangeEvent
   | TagsChangeEvent