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.

Author: myobie

CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## Unreleased
 
+### `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.
+- The exit status is unchanged. `pty kill` still exits 0 when the daemon stops,
+  even with survivors.
+- 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 +51,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

@@ -127,6 +127,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

@@ -42,9 +42,12 @@ import {
   getPidPath,
   getMetadataPath,
   DEFAULT_SESSION_DIR,
+  hasProcessExitedForReap,
   type SessionInfo,
   type SessionMetadata,
 } from "./sessions.ts";
+import { snapshotDescendantProcesses } from "./process-tree.ts";
+import { aftermathOf, killOutcomeLines } from "./kill-report.ts";
 import { spawnDaemon, resolveCommand } from "./spawn.ts";
 import {
   acquireEventLock, appendEventSyncLocked, EventFollower, EventWriter, EventType, releaseEventLock,
@@ -2637,6 +2640,12 @@ 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);
+
   try {
     process.kill(session.pid, "SIGTERM");
   } catch {
@@ -2662,7 +2671,12 @@ async function cmdKill(name: string): Promise<void> {
     return;
   }
   cleanupSocket(name);
-  console.log(`Session "${name}" killed.`);
+  const outcome = killOutcomeLines(
+    name,
+    aftermathOf(before, readProcessStartToken, hasProcessExitedForReap),
+  );
+  for (const line of outcome.out) console.log(line);
+  for (const line of outcome.err) console.error(line);
 
   if (wasPermanent && session.metadata?.tags?.ptyfile) {
     console.error(`Note: this session is managed by ${session.metadata.tags.ptyfile}`);

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

src/kill-report.ts

@@ -0,0 +1,85 @@
+/** What `pty kill` may claim, and how it says it.
+ *
+ * The command signals the daemon and waits for that one PID. The child, and
+ * everything the child started, is a separate question. This module answers it
+ * from a snapshot taken before the signal, and turns the answer into the lines
+ * the command prints.
+ *
+ * Kept out of `cli.ts` because that module runs `main()` on import and cannot
+ * be loaded by a test.
+ */
+
+import type { ProcessIdentity } from "./process-tree.ts";
+
+/** What the pre-kill snapshot looks like once the daemon has gone. */
+export interface Aftermath {
+  /** The start token still matches, so this is the same process and it is
+   *  still running. */
+  survived: number[];
+  /** The PID has not exited but its start token could not be read. We cannot
+   *  tell whether it is the same process or a PID the kernel has reused.
+   *
+   *  This case gets its own list rather than joining either side. Folding it
+   *  into `survived` would invent a survivor; dropping it would repeat the
+   *  defect this module exists to remove, which is a failure to measure
+   *  reported as an answer. */
+  unknown: number[];
+}
+
+export function allGone(after: Aftermath): boolean {
+  return after.survived.length === 0 && after.unknown.length === 0;
+}
+
+/** Re-check a snapshot against the live process table.
+ *
+ *  `exited` must be `hasProcessExitedForReap`, not `!isProcessAlive`. A zombie
+ *  answers `kill(pid, 0)` and keeps a readable start token, so the two cheaper
+ *  predicates both call it a survivor. It is a dead process waiting to be
+ *  reaped, and reporting it as still running would be this command
+ *  over-claiming again, only in the other direction.
+ */
+export function aftermathOf(
+  before: ProcessIdentity[],
+  readStartToken: (pid: number) => string | null,
+  exited: (pid: number) => boolean,
+): Aftermath {
+  const after: Aftermath = { survived: [], unknown: [] };
+  for (const identity of before) {
+    if (exited(identity.pid)) continue;
+    const token = readStartToken(identity.pid);
+    if (token === identity.processStartToken) after.survived.push(identity.pid);
+    // A different token is a PID the kernel handed to somebody else.
+    else if (token === null) after.unknown.push(identity.pid);
+  }
+  return after;
+}
+
+/** Say what was verified, and nothing more.
+ *
+ *  `killed` is a claim about the whole tree, so it appears only when every
+ *  process in the snapshot is gone. Otherwise standard output carries the part
+ *  that was verified — the daemon stopped — and standard error carries what
+ *  survived it. The two never appear together, so a reader who greps for the
+ *  success line cannot find it beside a warning that contradicts it.
+ */
+export function killOutcomeLines(
+  name: string,
+  after: Aftermath,
+): { out: string[]; err: string[] } {
+  if (allGone(after)) return { out: [`Session "${name}" killed.`], err: [] };
+  const err: string[] = [];
+  if (after.survived.length > 0) {
+    err.push(
+      `Session "${name}": ${after.survived.length} process(es) survived the kill ` +
+      `and are still running: ${after.survived.join(", ")}`,
+    );
+  }
+  if (after.unknown.length > 0) {
+    err.push(
+      `Session "${name}": ${after.unknown.length} process(es) may still be running: ` +
+      `${after.unknown.join(", ")}. Their start tokens could not be read, so this ` +
+      "is not a conclusion.",
+    );
+  }
+  return { out: [`Session "${name}" daemon stopped.`], err };
+}

src/server.ts

@@ -1395,10 +1395,16 @@ export class PtyServer {
         }
         const survivingDescendants = await descendantsDone;
         if (survivingDescendants.length > 0) {
+          const pids = survivingDescendants.map((d) => d.pid);
           console.error(
             `pty daemon "${this.name}": ${survivingDescendants.length} child process(es) ` +
-            "did not exit after exact TERM and KILL signals",
+            `did not exit after exact TERM and KILL signals: ${pids.join(", ")}`,
           );
+          // And somewhere a person can find it. The warning above goes to this
+          // daemon's standard error, which has had no reader since the command
+          // that launched it stopped listening — so the one moment it has
+          // something worth saying is the one moment nobody is there.
+          this.emitEvent(EventType.SESSION_DESCENDANTS_SURVIVED, { data: { pids } });
         }
         if (this.exited) await this.saveExitMetadataUntilSettled(this.exitCode);
         try { await this.eventWriter.flush(); } catch {}

src/sessions.ts

@@ -798,7 +798,12 @@ type ReapObservedResult =
     signalled: boolean;
   };
 
-function hasProcessExitedForReap(pid: number): boolean {
+/** Is `pid` gone for reaping purposes? A zombie counts as exited.
+ *
+ *  Exported because `pty kill` needs the same question answered. `!isProcessAlive`
+ *  is not a substitute: an unreaped process still answers `kill(pid, 0)` and still
+ *  has a readable start token, so the cheap predicates call a corpse a survivor. */
+export function hasProcessExitedForReap(pid: number): boolean {
   if (!isProcessAlive(pid)) return true;
   try {
     if (process.platform === "linux") {
@@ -810,12 +815,26 @@ function hasProcessExitedForReap(pid: number): boolean {
       encoding: "utf8",
       timeout: 1000,
     }).trim();
-    return state === "" || state.startsWith("Z");
+    return reapedFromPsState(state, () => isProcessAlive(pid));
   } catch {
     return !isProcessAlive(pid);
   }
 }
 
+/** Read a `ps -o stat=` field. `stillAlive` is asked only when the field is
+ *  empty, and it is a FRESH answer rather than the one taken before `ps` ran.
+ *
+ *  An empty field is two answers wearing one shape: the process is gone, or
+ *  `ps` did not manage to say. Reading it as "gone" is a failure folded into an
+ *  answer about what is there — so on an empty field we ask the kernel again
+ *  instead of reading silence as death. Under load on macOS `ps` is exactly
+ *  the thing that goes quiet. */
+export function reapedFromPsState(state: string, stillAlive: () => boolean): boolean {
+  if (state.startsWith("Z")) return true;
+  if (state === "") return !stillAlive();
+  return false;
+}
+
 /** Signal only after proving ownership, then reacquire after daemon shutdown
  *  so its final event/metadata flush cannot recreate artifacts after cleanup. */
 async function reapObservedSession(