@hienlh/ppm 0.23.24 → 0.23.25

package/src/services/chat-session-processes/session-processes.service.ts

@@ -0,0 +1,416 @@
+/**
+ * Stops what an AI chat left running: servers, emulators and daemons its commands started and
+ * walked away from. Linux with a systemd user manager only; anywhere else nothing is routed and
+ * nothing is stopped, exactly as before.
+ *
+ * Every command of a chat runs in a scope under the session's slice (`session-shell-scripts.ts`),
+ * so whatever it leaves behind stays findable in cgroupfs however it detached — `&`, `nohup`,
+ * `setsid`, `env -i`, a double-forking daemon, or `systemd-run` through the shim. A sweep stops a
+ * session's leftovers once the session has been idle `leftover_processes_idle_minutes`; deleting
+ * the session stops all of it at once. A process descending from a live CLI is a command or MCP
+ * server running right now and is never stopped by a sweep.
+ *
+ * At 0, the default, commands are routed all the same, but the sweep and a deletion only log what
+ * they would have stopped. What PPM's own restart and shutdown stop is still stopped: those are
+ * the commands that died with PPM's cgroup before they had scopes of their own.
+ */
+import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { LOG_ONLY_IDLE_MINUTES } from "../../shared/leftover-processes.ts";
+import { createLogger } from "../logger.ts";
+import { getPpmDir } from "../ppm-dir.ts";
+import { advanceClock, describeUnits, idlePastLimit, isCommandScope, unitsToStop, type SessionClock, type UnitSnapshot } from "./leftover-decisions.ts";
+import { installSessionShell } from "./session-shell-scripts.ts";
+import {
+  instanceSliceName, instanceTag, SESSION_SHELL_DIR, SLICE_ENV, sessionIdOfSlice, sessionSliceName, withSessionSlice, type SessionShell,
+} from "./session-slice.ts";
+
+const log = createLogger("chat-procs");
+
+const CGROUP_ROOT = "/sys/fs/cgroup";
+const SWEEP_INTERVAL_MS = 60_000;
+const PROBE_TIMEOUT_MS = 5_000;
+
+interface Tracking {
+  instance: string;
+  shell: SessionShell;
+  systemdRun: string;
+  systemctl: string;
+  /** The last probe failed: new CLIs are spawned without routing and the prefix runs commands untracked. */
+  failing: boolean;
+  /** cgroupfs directory of this PPM's slice; every session slice of it is a directory inside. */
+  instanceDir: string;
+  /** The cgroup PPM's own processes, its CLIs included, run in. */
+  ownCgroup: string;
+  idleMinutes: () => number;
+}
+
+let tracking: Tracking | null = null;
+
+export interface SweepDeps {
+  /** Whether the session is working now (a turn, an approval, background work) and when it last was. */
+  activity: (sessionId: string) => { busy: boolean; lastActiveAt?: number };
+  /** Told after a sweep or a deletion stopped units of a session. */
+  onStopped?: (sessionId: string, summary: string) => void;
+}
+
+// Survive Bun --hot reloads: one timer, whichever module copy registered last.
+const HOT_KEY = "__PPM_LEFTOVER_SWEEPER__" as const;
+const hot = ((globalThis as any)[HOT_KEY] ??= { stop: null, deps: null, startupDone: false }) as {
+  stop: (() => void) | null;
+  deps: SweepDeps | null;
+  startupDone: boolean;
+};
+const clocks = new Map<string, SessionClock>();
+/** With no limit set: the units each session's log has named already, so each is named once. */
+const reported = new Map<string, Set<string>>();
+
+async function run(cmd: string[], timeoutMs = PROBE_TIMEOUT_MS): Promise<{ code: number | null; out: string; err: string }> {
+  try {
+    const proc = Bun.spawn(cmd, { stdout: "pipe", stderr: "pipe" });
+    const timer = setTimeout(() => proc.kill(), timeoutMs);
+    const [out, err, code] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]);
+    clearTimeout(timer);
+    return { code, out, err };
+  } catch (e) {
+    return { code: null, out: (e as Error).message, err: (e as Error).message };
+  }
+}
+
+function readOwnCgroup(): string | null {
+  try {
+    const line = readFileSync("/proc/self/cgroup", "utf8").split("\n").find((l) => l.startsWith("0::"));
+    return line ? line.slice(3) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Turn routing on when this host can do it: `systemd-run --user --scope` must work, which also
+ * rules out a PPM with no user manager to talk to (a container, a bare SSH login).
+ */
+export async function initChatSessionProcesses(opts: { dbPath: string; idleMinutes: () => number }): Promise<boolean> {
+  if (process.platform !== "linux" || !process.env.XDG_RUNTIME_DIR) return false;
+  const systemdRun = Bun.which("systemd-run");
+  const systemctl = Bun.which("systemctl");
+  if (!systemdRun || !systemctl) return false;
+  const probe = await run([systemdRun, "--user", "--scope", "--quiet", "--collect", "--", "true"]);
+  if (probe.code !== 0) {
+    log.info(`chat commands are not tracked: systemd-run --user --scope failed (${probe.out.trim().slice(0, 200) || probe.code})`);
+    return false;
+  }
+  const appSlice = (await run([systemctl, "--user", "show", "-p", "ControlGroup", "--value", "app.slice"])).out.trim();
+  const ownCgroup = readOwnCgroup();
+  if (!appSlice || !existsSync(CGROUP_ROOT + appSlice) || !ownCgroup) {
+    log.info(`chat commands are not tracked: no cgroup for app.slice (${appSlice || "none"})`);
+    return false;
+  }
+  const instance = instanceTag(opts.dbPath);
+  const shell = installSessionShell(join(getPpmDir(), "bin", SESSION_SHELL_DIR), systemdRun);
+  // Left by a server that saw systemd-run failing; it works now.
+  rmSync(shell.untracked, { force: true });
+  tracking = {
+    instance,
+    shell,
+    systemdRun,
+    systemctl,
+    failing: false,
+    // A '-' is a level: app-ppmchat-<instance>.slice sits in app-ppmchat.slice, in app.slice.
+    instanceDir: join(CGROUP_ROOT + appSlice, "app-ppmchat.slice", instanceSliceName(instance)),
+    ownCgroup,
+    idleMinutes: opts.idleMinutes,
+  };
+  const limit = opts.idleMinutes();
+  log.info(`chat commands run under ${instanceSliceName(instance)}; what a chat leaves running is ${limit > 0
+    ? `stopped after ${limit} idle minutes`
+    : `never stopped, only logged after ${LOG_ONLY_IDLE_MINUTES} idle minutes (no limit set)`}`);
+  if (hot.deps) startupSweep(hot.deps);
+  return true;
+}
+
+/** Whether chats' commands are being routed into session slices on this host. */
+export function chatSessionProcessesTracked(): boolean {
+  return tracking !== null;
+}
+
+/**
+ * The environment a chat's Claude CLI is spawned with. Routed whatever the limit, 0 included, so
+ * that with no limit set the log can still name what one would stop.
+ */
+export function chatSessionCliEnv(sessionId: string | undefined, env: Record<string, string | undefined>): Record<string, string | undefined> {
+  const t = tracking;
+  const slice = t && !t.failing && sessionId ? sessionSliceName(t.instance, sessionId) : null;
+  const out = withSessionSlice(env, slice, t?.shell ?? null);
+  if (t && slice && !out[SLICE_ENV]) {
+    noteUntracked(t.shell.prefix.includes(" -")
+      ? `the path of PPM's directory contains " -", which the CLI cannot take in a shell prefix (${t.shell.prefix})`
+      : "CLAUDE_CODE_SHELL_PREFIX is set in PPM's environment, and a prefix of the user's own wins");
+  }
+  return out;
+}
+
+const toldUntracked = new Set<string>();
+
+/** Once per reason: Settings shows a limit, so the log has to say why nothing is stopped. */
+function noteUntracked(why: string): void {
+  if (toldUntracked.has(why)) return;
+  toldUntracked.add(why);
+  log.info(`chat commands are not tracked, so nothing they leave running is stopped: ${why}`);
+}
+
+/**
+ * Probes `systemd-run --user --scope` again. The startup probe proves it worked once; if the user
+ * manager restarts or its bus stops answering, every Bash call and MCP server start would fail
+ * with systemd's error, indistinguishable from the command's own. So while the probe fails the
+ * `untracked` file is there and the prefix runs each command as the CLI would have, new CLIs are
+ * spawned without routing, and nothing is swept; once it works again, all three come back. A
+ * command started between the failure and this probe, at most a minute, still fails.
+ * `systemdRun` is for tests.
+ */
+export async function recheckRouting(systemdRun?: string): Promise<boolean> {
+  const t = tracking;
+  if (!t) return false;
+  const probe = await run([systemdRun ?? t.systemdRun, "--user", "--scope", "--quiet", "--collect", "--", "true"]);
+  const ok = probe.code === 0;
+  // The file is shared with the other PPM on this ~/.ppm, so it follows every probe, not only a change.
+  try {
+    if (ok) rmSync(t.shell.untracked, { force: true });
+    else writeFileSync(t.shell.untracked, "");
+  } catch (e) {
+    log.warn(`could not ${ok ? "remove" : "write"} ${t.shell.untracked}: ${(e as Error).message}`);
+  }
+  if (ok === t.failing) {
+    if (ok) log.info("chat commands are tracked again: systemd-run --user --scope works");
+    else log.warn(`chat commands run untracked until systemd-run --user --scope works again: it failed (${probe.err.trim().slice(0, 200) || probe.code})`);
+  }
+  t.failing = !ok;
+  return ok;
+}
+
+/** Every minute: the probe, then the sweep if it passed. */
+async function tick(deps: SweepDeps): Promise<void> {
+  if (!tracking) return;
+  if (await recheckRouting()) sweepLeftovers(deps, "idle");
+}
+
+// ── Snapshot ────────────────────────────────────────────────────────────
+
+function readInts(path: string): number[] {
+  try {
+    return readFileSync(path, "utf8").split("\n").filter(Boolean).map(Number);
+  } catch {
+    return [];
+  }
+}
+
+/** Every pid in a cgroup and the cgroups below it (a service may delegate its own). */
+function pidsUnder(dir: string): number[] {
+  const pids = readInts(join(dir, "cgroup.procs"));
+  try {
+    for (const e of readdirSync(dir, { withFileTypes: true })) if (e.isDirectory()) pids.push(...pidsUnder(join(dir, e.name)));
+  } catch {}
+  return pids;
+}
+
+function procStat(pid: number): { comm: string; ppid: number } | null {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    const close = stat.lastIndexOf(")");
+    return { comm: stat.slice(stat.indexOf("(") + 1, close), ppid: Number(stat.slice(close + 2).split(" ")[1]) };
+  } catch {
+    return null;
+  }
+}
+
+function cgroupOf(pid: number): string | null {
+  try {
+    const line = readFileSync(`/proc/${pid}/cgroup`, "utf8").split("\n").find((l) => l.startsWith("0::"));
+    return line ? line.slice(3) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Some ancestor runs in PPM's own cgroup: the process belongs to a live CLI's command or MCP server. */
+function descendsFromPpm(pid: number, ownCgroup: string): boolean {
+  let p = procStat(pid)?.ppid ?? 0;
+  for (let hops = 0; p > 1 && hops < 64; hops++) {
+    if (cgroupOf(p) === ownCgroup) return true;
+    p = procStat(p)?.ppid ?? 0;
+  }
+  return false;
+}
+
+function populated(dir: string): boolean {
+  try {
+    return /^populated 1$/m.test(readFileSync(join(dir, "cgroup.events"), "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+/** This PPM's session slices that still hold a process, by session id. */
+function sessionSlices(t: Tracking): Map<string, string> {
+  const out = new Map<string, string>();
+  let names: string[] = [];
+  try { names = readdirSync(t.instanceDir); } catch { return out; }
+  for (const name of names) {
+    const sessionId = sessionIdOfSlice(t.instance, name);
+    if (sessionId && populated(join(t.instanceDir, name))) out.set(sessionId, name);
+  }
+  return out;
+}
+
+function snapshotUnits(t: Tracking, slice: string): UnitSnapshot[] {
+  const sliceDir = join(t.instanceDir, slice);
+  const units: UnitSnapshot[] = [];
+  let entries: string[] = [];
+  try { entries = readdirSync(sliceDir); } catch { return units; }
+  for (const name of entries) {
+    if (name.endsWith(".slice") || !/\.(scope|service|socket|timer|path|mount)$/.test(name)) continue;
+    const pids = pidsUnder(join(sliceDir, name));
+    if (!pids.length) continue;
+    units.push({
+      name,
+      comms: pids.map((p) => procStat(p)?.comm ?? "?"),
+      attached: pids.some((p) => descendsFromPpm(p, t.ownCgroup)),
+    });
+  }
+  return units;
+}
+
+// ── Stopping ────────────────────────────────────────────────────────────
+
+/** `systemctl stop`'s exit status for a unit that is not loaded: one that has gone already. */
+const NOT_LOADED = 5;
+
+/**
+ * SIGTERM through systemd, SIGKILL when the unit's stop times out; does not wait for either.
+ * `systemctl stop a b c` enqueues nothing at all when any one of them is no longer loaded ("Failed
+ * to enqueue jobs: Unit … not loaded."), and a unit ending between the snapshot and the stop is
+ * ordinary, so a stop that failed is made again one unit at a time.
+ */
+function stopUnits(t: Tracking, names: string[]): void {
+  if (!names.length) return;
+  const stop = (units: string[]) => run([t.systemctl, "--user", "stop", "--no-block", ...units]);
+  void stop(names).then(async ({ code }) => {
+    if (code === 0) return;
+    for (const name of names) {
+      const one = await stop([name]);
+      if (one.code !== 0 && one.code !== NOT_LOADED) log.warn(`systemctl stop ${name} failed (${one.code}): ${one.err.trim().slice(0, 300)}`);
+    }
+  });
+}
+
+/** No limit is set: names what would have been stopped, each unit once while it lasts, and stops nothing. */
+function logWouldStop(sessionId: string, what: string, units: UnitSnapshot[]): void {
+  const named = reported.get(sessionId);
+  const fresh = units.filter((u) => !named?.has(u.name));
+  reported.set(sessionId, new Set(units.map((u) => u.name)));
+  if (fresh.length) log.info(`session=${sessionId} would have stopped ${what}, had a limit been set: ${describeUnits(fresh)}`);
+}
+
+function sweepSession(t: Tracking, deps: SweepDeps, sessionId: string, slice: string, why: "idle" | "startup", now: number): void {
+  const limit = t.idleMinutes();
+  if (why === "idle") {
+    const { busy, lastActiveAt } = deps.activity(sessionId);
+    const clock = advanceClock(clocks.get(sessionId), now, busy, lastActiveAt);
+    clocks.set(sessionId, clock);
+    if (!idlePastLimit(clock, now, busy, (limit > 0 ? limit : LOG_ONLY_IDLE_MINUTES) * 60_000)) return;
+  }
+  const stop = unitsToStop(snapshotUnits(t, slice), why);
+  if (!stop.length) return;
+  if (why === "idle" && limit <= 0) {
+    logWouldStop(sessionId, `what it left running after ${LOG_ONLY_IDLE_MINUTES} idle minutes`, stop);
+    return;
+  }
+  const summary = why === "idle"
+    ? `stopped what it left running after ${t.idleMinutes()} idle minutes: ${describeUnits(stop)}`
+    : `stopped what its commands left running before PPM restarted: ${describeUnits(stop)}`;
+  log.info(`session=${sessionId} ${summary}`);
+  deps.onStopped?.(sessionId, summary);
+  stopUnits(t, stop.map((u) => u.name));
+}
+
+/** One pass over every session slice of this PPM. */
+export function sweepLeftovers(deps: SweepDeps, why: "idle" | "startup", now = Date.now()): void {
+  const t = tracking;
+  if (!t) return;
+  const slices = sessionSlices(t);
+  for (const id of clocks.keys()) if (!slices.has(id)) clocks.delete(id);
+  for (const id of reported.keys()) if (!slices.has(id)) reported.delete(id);
+  for (const [sessionId, slice] of slices) {
+    try {
+      sweepSession(t, deps, sessionId, slice, why, now);
+    } catch (e) {
+      log.warn(`session=${sessionId} leftover sweep failed: ${(e as Error).message}`);
+    }
+  }
+}
+
+function startupSweep(deps: SweepDeps): void {
+  if (hot.startupDone) return;
+  hot.startupDone = true;
+  sweepLeftovers(deps, "startup");
+}
+
+/** The chat layer's view of each session, and a sweep every minute once routing is on. */
+export function registerLeftoverSweeper(deps: SweepDeps): () => void {
+  hot.stop?.();
+  hot.deps = deps;
+  if (tracking) startupSweep(deps);
+  const timer = setInterval(() => {
+    tick(deps).catch((e) => log.warn(`leftover sweep failed: ${(e as Error).message}`));
+  }, SWEEP_INTERVAL_MS);
+  (timer as { unref?: () => void }).unref?.();
+  hot.stop = () => clearInterval(timer);
+  return hot.stop;
+}
+
+/** The chat was deleted: everything it started goes, running or not — once a limit is set. */
+export function stopChatSessionProcesses(sessionId: string): void {
+  const t = tracking;
+  if (!t) return;
+  clocks.delete(sessionId);
+  const slice = sessionSliceName(t.instance, sessionId);
+  if (!slice || !sessionSlices(t).has(sessionId)) return;
+  const units = snapshotUnits(t, slice);
+  if (t.idleMinutes() <= 0) {
+    logWouldStop(sessionId, "everything it was running, as it was deleted", units);
+    return;
+  }
+  if (units.length) {
+    const summary = `stopped everything it was running, as it was deleted: ${describeUnits(units)}`;
+    log.info(`session=${sessionId} ${summary}`);
+    hot.deps?.onStopped?.(sessionId, summary);
+  }
+  stopUnits(t, [slice]);
+}
+
+/**
+ * PPM is shutting down: its chats' commands and MCP servers go with it, as they did when they ran
+ * inside PPM's own cgroup. Units an agent started with `systemd-run` stay, as they always have.
+ * Synchronous because `process.exit` follows.
+ */
+export function stopCommandScopesSync(): void {
+  const t = tracking;
+  if (!t) return;
+  const names: string[] = [];
+  for (const slice of sessionSlices(t).values()) {
+    try {
+      for (const name of readdirSync(join(t.instanceDir, slice))) if (isCommandScope(name)) names.push(name);
+    } catch {}
+  }
+  const stop = (units: string[]) =>
+    Bun.spawnSync([t.systemctl, "--user", "stop", "--no-block", ...units], { stdout: "ignore", stderr: "ignore" }).exitCode;
+  // One scope gone since the listing makes the whole stop enqueue nothing, as in `stopUnits`.
+  if (names.length && stop(names) !== 0) for (const name of names) stop([name]);
+}
+
+/** Routing off again, for whatever a test process runs next. */
+export function resetChatSessionProcessesForTest(): void {
+  tracking = null;
+  clocks.clear();
+  reported.clear();
+}

package/src/services/chat-session-processes/session-shell-scripts.ts

@@ -0,0 +1,87 @@
+/**
+ * The two shell scripts that put a chat's processes into its session slice.
+ *
+ * `run` is the CLI's `CLAUDE_CODE_SHELL_PREFIX`. The CLI calls it with ONE argument, the whole
+ * command line it built for its shell (snapshot `source`, the `eval` of the command, the `pwd`
+ * that tracks the working directory) — for every Bash tool call, and for every stdio MCP server
+ * too. It re-runs that line in the user's shell inside a fresh scope under the session's slice.
+ * `systemd-run --scope` execs the command in place, so the pid the CLI holds, the exit code and
+ * the process group are all unchanged.
+ *
+ * `path/systemd-run` stands first on the CLI's PATH. An agent that starts something with
+ * `systemd-run --user` (an emulator, a scratch server) would otherwise put it outside the slice,
+ * where nothing would ever stop it; the shim adds the session's slice unless the call names a
+ * slice itself, which is how a unit that must outlive the chat opts out (`--slice=app.slice`).
+ *
+ * Both call the real `systemd-run` by its absolute path: the shim is first on PATH, and the
+ * prefix must not go through it.
+ *
+ * While the `untracked` file exists the prefix runs every command as the CLI would have, outside
+ * any scope: PPM found `systemd-run` failing (its user manager restarted, its bus stopped
+ * answering) and has not seen it work again, and a command must not fail for that.
+ */
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { COMMAND_SCOPE_PREFIX, SLICE_ENV, type SessionShell } from "./session-slice.ts";
+
+const quote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`;
+
+export function prefixScript(systemdRun: string, untracked: string): string {
+  return `#!/bin/sh
+# Written by PPM: runs one command of an AI chat inside that chat's systemd slice, so PPM can
+# stop whatever the command leaves running. $1 is the whole command line the Claude CLI built.
+shell=\${CLAUDE_CODE_SHELL:-\${SHELL:-/bin/bash}}
+case "$shell" in */zsh|*/bash) ;; *) shell=/bin/bash ;; esac
+[ -n "$${SLICE_ENV}" ] || exec "$shell" -c "$1"
+[ ! -e ${quote(untracked)} ] || exec "$shell" -c "$1"
+read -r id < /proc/sys/kernel/random/uuid
+exec ${quote(systemdRun)} --user --scope --quiet --collect --slice="$${SLICE_ENV}" --unit="${COMMAND_SCOPE_PREFIX}$id" --description="PPM chat command" -- "$shell" -c "$1"
+`;
+}
+
+export function shimScript(systemdRun: string): string {
+  return `#!/bin/sh
+# Written by PPM: a \`systemd-run --user\` started by an AI chat lands in that chat's slice, so PPM
+# stops it with everything else the chat left running. Naming a slice yourself keeps a unit out.
+if [ -n "$${SLICE_ENV}" ]; then
+  user=; slice=
+  for a in "$@"; do
+    case "$a" in
+      --) break ;;
+      --user) user=1 ;;
+      --slice|--slice=*|--slice-inherit) slice=1 ;;
+    esac
+  done
+  if [ -n "$user" ] && [ -z "$slice" ]; then exec ${quote(systemdRun)} --slice="$${SLICE_ENV}" "$@"; fi
+fi
+exec ${quote(systemdRun)} "$@"
+`;
+}
+
+/**
+ * Replaced in one step, never rewritten in place: dev and prod share this directory, and a
+ * command of one may start the script while the other is writing it.
+ */
+function writeIfChanged(path: string, content: string): void {
+  let current: string | null = null;
+  try { current = readFileSync(path, "utf8"); } catch {}
+  if (current === content) {
+    chmodSync(path, 0o755);
+    return;
+  }
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync(temp, content);
+  chmodSync(temp, 0o755);
+  renameSync(temp, path);
+}
+
+/** Writes both scripts under `dir` (rewritten only when PPM changed them) and says where they are. */
+export function installSessionShell(dir: string, systemdRun: string): SessionShell {
+  const pathDir = join(dir, "path");
+  mkdirSync(pathDir, { recursive: true });
+  const prefix = join(dir, "run");
+  const untracked = join(dir, "untracked");
+  writeIfChanged(prefix, prefixScript(systemdRun, untracked));
+  writeIfChanged(join(pathDir, "systemd-run"), shimScript(systemdRun));
+  return { prefix, pathDir, untracked };
+}

package/src/services/chat-session-processes/session-slice.ts

@@ -0,0 +1,86 @@
+/**
+ * Where a chat session's processes live, by name. Every command a chat's Claude CLI runs goes
+ * into a scope under one systemd slice per session, `app-ppmchat-<instance>-<session>.slice`, so
+ * what the chat left running can be found and stopped long after the command that started it.
+ *
+ * A '-' in a slice name is a level of the tree: all of one PPM's sessions sit under
+ * `app-ppmchat-<instance>.slice`, inside `app.slice`. The instance is named after the database
+ * because dev and prod share ~/.ppm, and one PPM must never judge another's sessions idle.
+ */
+import { createHash } from "node:crypto";
+
+/** What the CLI's commands read to know their session's slice. */
+export const SLICE_ENV = "PPM_CHAT_SLICE";
+/** Directory, under the PPM dir's `bin/`, holding the two scripts; how an inherited copy is recognised. */
+export const SESSION_SHELL_DIR = "chat-session-shell";
+/** Name prefix of the scope every command runs in, as opposed to a unit the agent made itself. */
+export const COMMAND_SCOPE_PREFIX = "ppmcmd-";
+
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+export function instanceTag(dbPath: string): string {
+  return createHash("sha256").update(dbPath).digest("hex").slice(0, 8);
+}
+
+export function instanceSliceName(instance: string): string {
+  return `app-ppmchat-${instance}.slice`;
+}
+
+/** Null for an id that is not a lowercase UUID: it could not be read back from the name. */
+export function sessionSliceName(instance: string, sessionId: string): string | null {
+  if (!SESSION_ID.test(sessionId)) return null;
+  return `app-ppmchat-${instance}-${sessionId.replace(/-/g, "")}.slice`;
+}
+
+export function sessionIdOfSlice(instance: string, sliceName: string): string | null {
+  const prefix = `app-ppmchat-${instance}-`;
+  if (!sliceName.startsWith(prefix) || !sliceName.endsWith(".slice")) return null;
+  const hex = sliceName.slice(prefix.length, -".slice".length);
+  if (!/^[0-9a-f]{32}$/.test(hex)) return null;
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+/**
+ * The PPM session a CLI is spawned for. A fork's first CLI resumes its source under an id the
+ * CLI picks itself, so it is left untracked rather than filed under the session it came from.
+ */
+export function chatSessionIdOf(options: { sessionId?: string; resume?: string; forkSession?: boolean } | undefined): string | undefined {
+  if (!options) return undefined;
+  return options.sessionId ?? (options.forkSession ? undefined : options.resume);
+}
+
+export interface SessionShell {
+  /** The `CLAUDE_CODE_SHELL_PREFIX` script. */
+  prefix: string;
+  /** Directory put first on the CLI's PATH, holding the `systemd-run` shim. */
+  pathDir: string;
+  /** File that, while it exists, has the prefix run every command untracked: `systemd-run` is failing. */
+  untracked: string;
+}
+
+const isOurs = (path: string) => path.includes(`/${SESSION_SHELL_DIR}/`);
+
+/**
+ * The CLI's environment with its commands routed into `slice`, or with no routing at all when
+ * `slice` is null. Either way an inherited routing is dropped first: a PPM started from inside
+ * a chat would otherwise file its own sessions' commands under that chat.
+ */
+export function withSessionSlice(
+  env: Record<string, string | undefined>,
+  slice: string | null,
+  shell: SessionShell | null,
+): Record<string, string | undefined> {
+  const out = { ...env };
+  delete out[SLICE_ENV];
+  if (out.CLAUDE_CODE_SHELL_PREFIX && isOurs(out.CLAUDE_CODE_SHELL_PREFIX)) delete out.CLAUDE_CODE_SHELL_PREFIX;
+  if (out.PATH === undefined) return out;
+  const path = out.PATH.split(":").filter((dir) => dir && !isOurs(`${dir}/`));
+  out.PATH = path.join(":");
+  // The CLI splits a prefix at its last " -" into program and flags, so such a path cannot be
+  // passed at all. A prefix of the user's own wins, and the session goes untracked.
+  if (!slice || !shell || shell.prefix.includes(" -") || out.CLAUDE_CODE_SHELL_PREFIX) return out;
+  out[SLICE_ENV] = slice;
+  out.CLAUDE_CODE_SHELL_PREFIX = shell.prefix;
+  out.PATH = [shell.pathDir, ...path].join(":");
+  return out;
+}