@volter/teams 0.2.52 → 0.2.54

package/board-process-guard.mjs

@@ -1,20 +1,42 @@
 #!/usr/bin/env node
-// The board's native PreToolUse command policy. No process lookup or signal occurs here.
+// The board's native PreToolUse command policy. It reads the command; it looks a process up only when the command kills
+// one by PID, and never signals anything.
+//
+// A kill by name or pattern is refused. So is a kill by PID that is a pattern in disguise: on volter-desktop
+// (2026-10-10 04:27Z) a session ended a test run with `for p in $(list); do taskkill //PID $p //F; done`, `list` matched
+// processes by a folder name that came out empty, and every process of the machine's user (Explorer, the terminal and
+// every session in it, the browser) was ended past this guard, which let any kill by PID through. A kill whose PIDs are
+// built at run time is now refused outright, whatever its form.
+//
+// A PID written out as a number (or `$!`, the shell's own last child) is the rule's own allowed kill, and goes through
+// for a process this session started: one running under it, or one its harness marked when it ran it, which is how a
+// process started with `&` or `nohup` is still known after the Bash call's shell returned and left it re-parented.
+// One that is another's is refused (`deny`, which blocks whatever the permission mode is; never `ask`, whose effect
+// under a board session's `bypassPermissions` is undocumented, so it would either stall a machine nobody is at or do
+// nothing). Where a process's environment cannot be read (Windows), whose it is cannot be read either: there the form
+// of the kill is all this guard judges, and one written-out PID goes through unjudged (docs/adr/0030). A kill made
+// inside a program (`process.kill` in a script) is that program's, and is not read here.
+import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { resolve } from 'node:path';
 export const processGuardReason = 'Pattern kills are refused for board sessions. Kill only the PID this session recorded when it started that process; use the owning service door for a service.';
+export const computedKillReason = `A kill names each process by the PID this session recorded when it started it, written out as a number. A PID taken from a variable, a loop or a command's output is a pattern kill: one over a match that came out empty ended every process of a machine's user. ${processGuardReason}`;
+export const foreignKillReason = (pid) => `PID ${pid} is not a process this session started: it is neither running under this session nor marked by it (its environment names no session of this one). Kill only what this session started, by the PID it recorded; a process another session or the person started is theirs to end, through its owning service door or by asking them.`;
+// Shell bodies are read as well as nested `sh -c` / substitutions. Removing shell escapes and quotes catches split
+// words, paths and quoted embedded commands.
+const normalize = (command) => String(command).replace(/\\\r?\n/g, '').replace(/\\([a-zA-Z-])/g, '$1').replace(/["']/g, '');
+// Where a command starts: a separator, a nested `-c`, or a prefix that runs the next word (env, sudo, xargs, a loop's do…)
+const head = String.raw`(?:^|[;|&(\n{}]|\s-[a-zA-Z]*c\s+)\s*(?:(?:env|sudo|exec|command|xargs|nohup|do|then|else|!)\s+(?:--?[^\s;|&()]+\s+)*|[A-Za-z_][A-Za-z0-9_]*=[^\s;|&()]+\s+)*(?:[\w./-]+/)?`;
 export function patternKill(command) {
-  // Inspect shell bodies as well as nested `sh -c` / substitutions. Removing shell
-  // escapes and quotes catches split words, paths and quoted embedded commands.
-  const text = String(command).replace(/\\\r?\n/g, '').replace(/\\([a-zA-Z-])/g, '$1').replace(/["']/g, '');
-  const head = String.raw`(?:^|[;|&(\n{}]|\s-[a-zA-Z]*c\s+)\s*(?:(?:env|sudo|exec|command|xargs|nohup|do|then|else|!)\s+(?:--?[^\s;|&()]+\s+)*|[A-Za-z_][A-Za-z0-9_]*=[^\s;|&()]+\s+)*(?:[\w./-]+/)?`;
+  const text = normalize(command);
   return new RegExp(head + String.raw`(?:pkill|killall)(?=$|[\s;|&()])`).test(text) ||
     new RegExp(head + String.raw`pgrep\s+[^;|&\n)]*(?:--full\b|-[a-zA-Z]*f[a-zA-Z]*(?=$|\s))`).test(text) ||
     windowsPatternKill(text);
 }
 // Windows names a process by image, title or command line through its own tools (cmd, PowerShell, Git Bash's
-// `//IM`): each such kill is refused as pkill is. A kill by PID (`taskkill /PID`, `Stop-Process -Id`) stays allowed.
+// `//IM`): each such kill is refused as pkill is. A kill by PID (`taskkill /PID`, `Stop-Process -Id`) is read by
+// `pidKills` below.
 function windowsPatternKill(text) {
   return /\btaskkill(?:\.exe)?\b[^;|&\n]*\s(?:\/{1,2}|-)(?:im|fi)\b/i.test(text) ||
     /(?:^|[^\w-])(?:Stop-Process|spps)\b[^;|\n]*\s-(?:N[a-z]*|ProcessName)\b/i.test(text) ||
@@ -24,6 +46,151 @@ function windowsPatternKill(text) {
     /\bwmic\b[^;|&\n]*\bprocess\b[^;|&\n]*\bwhere\b[^;|&\n]*\b(?:name|commandline|executablepath)\b/i.test(text) ||
     /\bWin32_Process\b[^\n]*\b(?:Name|CommandLine|ExecutablePath)\b[^\n]*\b(?:Terminate|Remove-CimInstance|Remove-WmiObject|Stop-Process)\b/i.test(text);
 }
+
+/**
+ * The kills by PID in a command (`kill`, `taskkill /PID`, `Stop-Process -Id`): `{ pids, computed }`. `pids` are the PIDs
+ * written out as numbers; `computed` is set when any target is not one (a variable, a substitution, a loop's word,
+ * `xargs`' input, a pipe into Stop-Process, a process group): a list built at run time, which is a pattern kill whatever
+ * its form. `kill -0` sends no signal and `kill %1` names this shell's own job: neither is a kill here.
+ */
+export function pidKills(command) {
+  const text = normalize(command);
+  const pids = [];
+  let computed = false;
+  // `$!` is the PID of the process this shell started last, and so is a variable this command set from it
+  // (`node server.mjs & s=$!; …; kill $s`): this session's own, read as such
+  const own = new Set(['$!', '${!}']);
+  for (const [, name] of text.matchAll(/\b([A-Za-z_]\w*)=\$!/g)) { own.add(`$${name}`); own.add(`\${${name}}`); }
+  // one kill's own targets, kept apart until its whole line is read: a probe (`kill -0`, `kill -l`) signals nothing
+  // and its targets are no kill's
+  let mine = [], mineComputed = false;
+  const target = (word) => {
+    if (/^%/.test(word) || own.has(word)) return;
+    if (/^\d+$/.test(word) && Number(word) > 0) mine.push(Number(word));
+    else mineComputed = true;
+  };
+  const taken = () => { pids.push(...mine); computed ||= mineComputed; mine = []; mineComputed = false; };
+  const kills = new RegExp(head + String.raw`(kill|taskkill(?:\.exe)?|Stop-Process|spps)(?=$|[\s;|&()])([^;|&\n)]*)`, 'gi');
+  for (const [whole, tool, rest] of text.matchAll(kills)) {
+    const before = whole.slice(0, whole.length - tool.length - rest.length);
+    // its targets come from its input
+    if (/\bxargs\s/.test(before) || /^\s*\|/.test(before)) { computed = true; continue; }
+    const words = rest.trim().split(/\s+/).filter(Boolean);
+    const name = tool.toLowerCase();
+    if (name.startsWith('taskkill')) {
+      for (let i = 0; i < words.length; i++) if (/^(?:\/{1,2}|-)pid$/i.test(words[i])) target(words[++i] ?? '');
+      taken();
+    } else if (name === 'stop-process' || name === 'spps') {
+      for (let i = 0; i < words.length; i++) {
+        const id = /^-Id(?::(.+))?$/i.exec(words[i]);
+        if (id) { for (const part of (id[1] ?? words[++i] ?? '').split(',').filter(Boolean)) target(part); }
+        else if (/^-InputObject\b/i.test(words[i])) mineComputed = true;
+        else if (!words[i].startsWith('-')) for (const part of words[i].split(',').filter(Boolean)) target(part);
+      }
+      taken();
+    } else {
+      // kill: one signal (-9, -KILL, -s KILL, -n 9), then its targets; a dash-number after the signal is a group
+      let signalled = false, targets = false, probe = false;
+      for (let i = 0; i < words.length; i++) {
+        const word = words[i];
+        if (targets || (signalled && /^-\d+$/.test(word))) { target(word); targets = true; continue; }
+        if (word === '--') { targets = true; continue; }
+        if (/^-(?:l|L|-list|-table)$/.test(word)) { probe = true; break; }
+        if (/^-(?:s|n)$/.test(word)) { if (words[i + 1] === '0') probe = true; i++; signalled = true; continue; }
+        const id = /^-Id(?::(.+))?$/i.exec(word); // PowerShell's kill alias
+        if (id) { for (const part of (id[1] ?? words[++i] ?? '').split(',').filter(Boolean)) target(part); targets = true; continue; }
+        if (/^-[A-Za-z0-9]+$/.test(word) && !signalled) { if (word === '-0') probe = true; signalled = true; continue; }
+        target(word); targets = true;
+      }
+      if (probe) { mine = []; mineComputed = false; continue; }
+      taken();
+    }
+  }
+  return { pids, computed };
+}
+
+const SHELLS = /^(?:sh|bash|dash|zsh|cmd|cmd\.exe|powershell|powershell\.exe|pwsh|pwsh\.exe)$/i;
+
+/** This OS user's processes: pid → `{ ppid, name, started }` (started: Windows' FILETIME); null when they cannot be read. */
+export function processTable() {
+  try {
+    if (process.platform === 'win32') {
+      const script = "Get-CimInstance Win32_Process | ForEach-Object { '{0} {1} {2} {3}' -f $_.ProcessId, $_.ParentProcessId, $(if ($_.CreationDate) { $_.CreationDate.ToFileTimeUtc() } else { 0 }), $_.Name }";
+      const out = execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], { encoding: 'utf8', windowsHide: true, timeout: 8_000, maxBuffer: 1 << 24 });
+      return new Map(out.split(/\r?\n/).map((line) => line.trim().match(/^(\d+) (\d+) (\d+) (.*)$/)).filter(Boolean)
+        .map(([, pid, ppid, started, name]) => [Number(pid), { ppid: Number(ppid), started: Number(started) || null, name }]));
+    }
+    const out = execFileSync('ps', ['-A', '-o', 'pid=,ppid=,comm='], { encoding: 'utf8', timeout: 5_000, maxBuffer: 1 << 24 });
+    return new Map(out.split('\n').map((line) => line.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/)).filter(Boolean)
+      .map(([, pid, ppid, comm]) => [Number(pid), { ppid: Number(ppid), started: null, name: comm.split('/').pop() }]));
+  } catch { return null; }
+}
+
+/** The session this hook runs for: the harness that started it, past a shell a hook's command line ran through. */
+export function sessionProcess(table, parent = process.ppid) {
+  const row = table.get(parent);
+  return row && SHELLS.test(row.name ?? '') ? row.ppid : parent;
+}
+
+/** Whether a process's own environment can be read here: a session's background process is known by it. */
+export const ownershipReadable = (platform = process.platform) => platform === 'linux' || platform === 'darwin';
+
+/**
+ * Whether the process `pid` was started by this session, by the marks its harness gives everything it runs
+ * (`CLAUDE_CODE_SESSION_ID`, `CLAUDE_PID`: sdk/terminal/substrate/harness-markers.json). A process started with `&` or
+ * `nohup` is re-parented when the Bash call's own shell returns (its parent is init, or on Windows a pid that is gone),
+ * so its session cannot be read from its parents; its environment still names the session that ran it. A session can
+ * set those marks only on what it starts, so this says a process is its own and never that another's is.
+ */
+export function startedBySession(pid, root, sessionId, platform = process.platform) {
+  const marks = [...(sessionId ? [`CLAUDE_CODE_SESSION_ID=${sessionId}`] : []), ...(root ? [`CLAUDE_PID=${root}`] : [])];
+  if (!marks.length) return false;
+  try {
+    const text = platform === 'linux'
+      ? readFileSync(`/proc/${pid}/environ`, 'utf8').split('\0').join('\n')
+      : execFileSync('ps', ['-E', '-o', 'command=', '-p', String(pid)], { encoding: 'utf8', timeout: 3_000, maxBuffer: 1 << 22 });
+    return marks.some((mark) => text.includes(mark));
+  } catch { return false; }
+}
+
+/** Whether `pid` is `root` or started under it, parent by parent. */
+export function descends(table, pid, root) {
+  let at = pid;
+  for (let hops = 0; hops < 256; hops++) {
+    if (at === root) return true;
+    const row = table.get(at);
+    if (!row || !row.ppid || row.ppid === at) return false;
+    // Windows keeps a dead parent's pid as its children's parent, and a later process can take it: a "parent" that
+    // started after its child is not its parent
+    const parent = table.get(row.ppid);
+    if (row.started && parent?.started && parent.started > row.started) return false;
+    at = row.ppid;
+  }
+  return false;
+}
+
+/**
+ * The guard's answer to a command: null to let it run, or `{ decision, reason }`. A kill by name or pattern, or by a PID
+ * list built at run time, is denied. A PID written out that is not this session's own is put to the person at the
+ * machine (`ask`): a process another session or the person started is theirs to end, and they can say yes to it.
+ */
+export function killDecision(command, { table, session, sessionId, platform = process.platform } = {}) {
+  if (patternKill(command)) return { decision: 'deny', reason: processGuardReason };
+  const kills = pidKills(command);
+  if (kills.computed) return { decision: 'deny', reason: computedKillReason };
+  if (!kills.pids.length) return null;
+  // Whose a process is can only be read where a process's environment can: see `startedBySession`. Where it cannot
+  // (Windows), the form of the kill is all this guard judges, and one written-out PID goes through.
+  if (!ownershipReadable(platform)) return null;
+  const rows = table ?? processTable();
+  if (!rows) return null;
+  const root = session ?? sessionProcess(rows);
+  const foreign = kills.pids.filter((pid) => rows.has(pid) && !descends(rows, pid, root) && !startedBySession(pid, root, sessionId, platform));
+  // A hook's `deny` blocks whatever the session's permission mode is, and a board session runs with
+  // `--permission-mode bypassPermissions` (sdk/orchestrator/activation.mjs). `ask` is not used: what it does under
+  // that mode is undocumented, so it would either stall a machine nobody is at or do nothing at all.
+  return foreign.length ? { decision: 'deny', reason: foreign.map(foreignKillReason).join(' ') } : null;
+}
 const quote = value => `'${String(value).replaceAll("'", "'\\''")}'`;
 export function boardGuardArguments(kind, args, { cwd, enabled, node = process.execPath } = {}) {
   if (!enabled) return args;
@@ -57,8 +224,9 @@ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.ur
     const input = JSON.parse(readFileSync(0, 'utf8'));
     const command = input.tool_input?.command ?? input.tool_input?.cmd;
     if (typeof command !== 'string') throw new Error('Bash hook input has no command');
-    if (patternKill(command)) process.stdout.write(JSON.stringify({ hookSpecificOutput: {
-      hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: processGuardReason,
+    const verdict = killDecision(command, { sessionId: typeof input.session_id === 'string' ? input.session_id : null });
+    if (verdict) process.stdout.write(JSON.stringify({ hookSpecificOutput: {
+      hookEventName: 'PreToolUse', permissionDecision: verdict.decision, permissionDecisionReason: verdict.reason,
     } }) + '\n');
   } catch (error) {
     process.stderr.write(`Board process policy could not read the command: ${error.message}. ${processGuardReason}\n`);

package/browser-channel.d.ts

@@ -47,7 +47,7 @@ export function openBrowserMachine(target: { origin: string; teamId: string; mac
  */
 export function openBrowserSession(target: { origin: string; teamId: string; sessionId: string; token: string }, options?: ChannelOptions): Promise<BrowserChannel>;
 
-/** The machine's answer to a typed turn. `waiting`: filed, typed when the session's composer is free. */
+/** The machine's answer to a typed turn. `waiting`: filed, not typed yet. */
 export type BrowserTurnAnswer =
   | { code: 0; turn_id?: string; door?: 'runtime' | 'pane' | 'waiting'; text?: string }
   | { code: number; text?: string };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/teams",
-  "version": "0.2.52",
+  "version": "0.2.54",
   "type": "module",
   "description": "Volter Teams, the neutral team plane: machine identity and daemon core, the local door and server link, admission from machine grants, product doors, and the Teams server's neutral routes (company RFC 0008).",
   "license": "MIT",