@rubytech/create-maxy-code 0.1.92 → 0.1.93

package/payload/platform/services/claude-session-manager/dist/pty-spawner.js

@@ -26,8 +26,11 @@
 import { mkdirSync, writeFileSync, existsSync, readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { defaultSystemctlRunner, scopeUnitName, stopScopeUnit, } from './systemd-scope.js';
 import { startUrlCapture } from './url-capture.js';
-import { jsonlPathForSessionId } from './jsonl-path.js';
+import { jsonlPathForSessionId, sidecarPathForSessionId } from './jsonl-path.js';
+import { writeSidecar, updateSidecar } from './session-sidecar.js';
 import { probeMcpServerTools, } from './mcp-tools-probe.js';
 // CSI (Cursor / Style) escape sequence: ESC `[` <args> <final-letter>.
 const PTY_TAIL_CSI = /\x1b\[[0-9;?]*[A-Za-z]/g;
@@ -56,6 +59,57 @@ function formatTailForLog(tail) {
 }
 import { composeAppendSystemPrompt, } from './system-prompt.js';
 import { discoverHooks } from './hooks-discovery.js';
+const livePtys = new Map();
+/** Returns true when the manager has a live PtyHandle for `sessionId`.
+ *  False for exited rows (the tracker is removed) and for sessions the
+ *  manager never spawned (e.g. a JSONL-only archived row). */
+export function isLive(sessionId) {
+    const t = livePtys.get(sessionId);
+    return t !== undefined && !t.exited;
+}
+/** Test seam — read-only access to the tracker for a given session.
+ *  Production routes never call this; they use the dedicated mutation
+ *  exports (`writeInputToPty`, `killSession`, `onPtyExit`, etc.) so
+ *  the PtyHandle stays encapsulated inside the module. */
+export function getPtyTrackerForTests(sessionId) {
+    return livePtys.get(sessionId);
+}
+/** Register a callback to fire when the PTY for `sessionId` exits.
+ *  Returns true when the tracker exists (callback was wired); false
+ *  when no live PTY is tracked for that id (the caller's contract
+ *  fires regardless — e.g. `attachPublicAudit` skips on no-tracker).
+ *  Routes call this instead of reaching into the tracker for `.pty`. */
+export function onPtyExit(sessionId, cb) {
+    const t = livePtys.get(sessionId);
+    if (!t)
+        return false;
+    t.pty.onExit(cb);
+    return true;
+}
+/** Iterate every live tracker. Used by index.ts's shutdown loop to
+ *  SIGTERM each PTY synchronously, and by checkSlotsAndMaybeEvict's
+ *  LRU search to walk specialists when the cap is hit. */
+export function forEachLivePty(cb) {
+    for (const t of livePtys.values())
+        cb(t);
+}
+/** Count of live trackers. Surfaced by /healthz so the operator can
+ *  see process-side liveness without scanning the watcher's row index. */
+export function livePtyCount() {
+    return livePtys.size;
+}
+/** Test-only — clear the tracker map between vitest cases. Production
+ *  never invokes this; the only legitimate eviction is PTY exit. */
+export function __resetPtyTrackerForTests() {
+    livePtys.clear();
+}
+/** Test-only — directly register a tracker without going through
+ *  `spawnClaudeSession`. Used by FD-release / natural-exit tests that
+ *  need to construct a known PtyHandle + tracker pair and exercise
+ *  `killSession` / `handlePtyNaturalExit` against it. */
+export function __registerPtyTrackerForTests(tracker) {
+    livePtys.set(tracker.sessionId, tracker);
+}
 /** Task 171 — specialists whose `--agent <name>` spawn has no human in the
  *  loop: no operator browser tab, no chat channel, no `claude.ai/code/session_<id>`
  *  URL to open. For these, `--remote-control` is dead weight (one outbound
@@ -323,15 +377,22 @@ function checkSlotsAndMaybeEvict(deps, args) {
             deps.logger(`[pty-cap] specialist-cap-reached account=${deps.accountId} current=${specialistRows.length} cap=${deps.specialistCap} evicted=none`);
             return { kind: 'specialist-cap-reached', currentCount: specialistRows.length, cap: deps.specialistCap };
         }
-        const victim = deps.store.get(idleOldest.sessionId);
+        const victim = livePtys.get(idleOldest.sessionId);
         if (victim && !victim.exited) {
+            // Task 250 — eviction routes through systemctl stop of the scope
+            // unit, matching the operator-stop and reaper paths. Without this,
+            // an evicted specialist would only die when the manager process
+            // closes its master fd (and the SIGHUP wrap inside the scope makes
+            // it not die at all). systemctl stop gives systemd the cgroup-level
+            // SIGTERM→SIGKILL escalation, with TimeoutStopSec=5 as the ceiling.
             try {
-                victim.pty.kill('SIGTERM');
+                const run = deps.runSystemctl ?? defaultSystemctlRunner;
+                stopScopeUnit(run, victim.scopeUnitToken);
             }
-            catch { /* fire-and-forget */ }
+            catch { /* fire-and-forget — boot-seed orphan-stop will catch leaks */ }
         }
-        deps.store.remove(idleOldest.sessionId);
-        deps.logger(`[pty-cap] specialist-cap-reached account=${deps.accountId} current=${specialistRows.length} cap=${deps.specialistCap} evicted=${idleOldest.sessionId}`);
+        livePtys.delete(idleOldest.sessionId);
+        deps.logger(`[pty-cap] specialist-cap-reached account=${deps.accountId} current=${specialistRows.length} cap=${deps.specialistCap} evicted=${idleOldest.sessionId} pty-tracker-size=${livePtys.size}`);
     }
     if (liveRows.length >= deps.totalPtyCap - deps.operatorReserve) {
         deps.logger(`[pty-cap] operator-slots-reserved total=${liveRows.length} reserve=${deps.operatorReserve} totalCap=${deps.totalPtyCap} rejected-specialist=${args.senderId}`);
@@ -495,6 +556,13 @@ export async function spawnClaudeSession(deps, args) {
     }
     const startedAt = new Date().toISOString();
     const start = Date.now();
+    // Task 250 — mint the systemd scope unit token before any argv work so
+    // both the spawn adapter and the eventual StoredSession agree on which
+    // unit name the manager will later target via `systemctl --user stop`.
+    // Resume spawns use the prior canonical sessionId (already a UUID, hence
+    // already a valid systemd unit token); fresh spawns mint a fresh UUID.
+    // Either way the value is opaque to systemd.
+    const unitToken = args.resumeClaudeSessionId ?? randomUUID();
     const composedHost = deps.tunnelUrlOverride !== undefined
         ? { ...deps.host, tunnelUrl: deps.tunnelUrlOverride }
         : deps.host;
@@ -805,7 +873,7 @@ export async function spawnClaudeSession(deps, args) {
     const ptySpawnStart = Date.now();
     let pty;
     try {
-        pty = deps.spawnPty(deps.claudeBin, argv, spawnEnv);
+        pty = deps.spawnPty(deps.claudeBin, argv, spawnEnv, unitToken);
     }
     catch (err) {
         const e = err;
@@ -817,14 +885,23 @@ export async function spawnClaudeSession(deps, args) {
     deps.logger(`pty-spawned pid=${pty.pid} ms=${Date.now() - ptySpawnStart}`);
     const tail = attachPtyTail(pty);
     // URL capture runs in parallel; its result is patched onto the
-    // session row when (if) it fires. The spawn promise does not block on
+    // sidecar when (if) it fires. The spawn promise does not block on
     // it. A timeout here is logged but not a failure — the operator's
     // iframe URL falls back to UI-side construction from bridgeSessionId.
     //
     // Task 171 — headless spawns never emit the `/remote-control is active`
     // banner (the flag is absent), so the handler is not attached and no
     // PTY bytes are consumed by a regex that will never match.
+    //
+    // Task 260 — `capturedUrl` is the value SpawnedSession returns to the
+    // caller (the route includes it in the immediate /spawn response when
+    // the banner happens to land before the spawn promise resolves). The
+    // canonical surface is the sidecar; the captured value is also written
+    // there via `updateSidecar` so the watcher's row picks it up.
     let capturedUrl = null;
+    // Mutable holder so the URL callback can find the row once sessionId
+    // is known. The PID-file event below sets sessionIdRef.current.
+    const sessionIdRef = { current: null };
     if (!headless) {
         startUrlCapture({
             pty,
@@ -836,9 +913,16 @@ export async function spawnClaudeSession(deps, args) {
                 const sid = sessionIdRef.current;
                 if (!sid)
                     return;
-                const live = deps.store.get(sid);
-                if (live)
-                    live.url = url;
+                const sidecarPath = sidecarPathForSessionId(deps.spawnCwd, sid);
+                const written = updateSidecar(sidecarPath, { url }, deps.logger);
+                if (!written) {
+                    deps.logger(`[session-sidecar] url-update-skipped sessionId=${sid.slice(0, 8)} reason=sidecar-missing`);
+                    return;
+                }
+                // Force the watcher to re-read the sidecar so its row index
+                // surfaces the new URL to /events and /list. fs.watch does not
+                // fire for sidecar writes (we only watch *.jsonl and PID files).
+                deps.watcher.refreshSidecar(sid);
                 deps.onUrlCaptured?.(sid);
             },
             onTimeout: () => {
@@ -846,18 +930,15 @@ export async function spawnClaudeSession(deps, args) {
             },
         });
     }
-    // Mutable holder so the URL callback can find the row once sessionId
-    // is known. The PID-file event below sets sessionIdRef.current.
-    const sessionIdRef = { current: null };
     // Wait for the watcher's PID-file event. The watcher resolves
     // synchronously if the file already exists (race-safe boot scan).
     // Task 258 — for /resume, the archived jsonl was already restored to
     // the top-level path before this spawn ran; claude --resume appends to
     // it and (per Task 186) rewrites its pid file to carry the prior
-    // canonical sessionId. The StoredSession is keyed on the prior
-    // canonical id passed in via resumeClaudeSessionId so the wire/store
-    // identity is stable even during the brief window where claude's pid
-    // file still carries a fresh mint.
+    // canonical sessionId. The PtyTracker (Task 260) is keyed on the
+    // prior canonical id passed in via resumeClaudeSessionId so the
+    // wire identity is stable even during the brief window where claude's
+    // pid file still carries a fresh mint.
     let row;
     try {
         row = await deps.watcher.waitForPid(pty.pid, deps.pidFileTimeoutMs);
@@ -872,25 +953,62 @@ export async function spawnClaudeSession(deps, args) {
     }
     const sessionId = args.resumeClaudeSessionId ?? row.sessionId;
     sessionIdRef.current = sessionId;
-    const session = {
+    const specialist = args.specialist ?? row.agent ?? null;
+    const hidden = args.hidden === true;
+    // Task 260 — write the sidecar BEFORE registering the tracker. The
+    // sidecar is the canonical record of spawn metadata; the watcher
+    // row will read it the moment the JSONL CREATE event fires (the
+    // first user turn flush). If the write fails — disk full, RO mount,
+    // unexpected eperm — refuse the spawn loudly rather than launch a
+    // metadata-less PTY that the wire payload could not honour. The
+    // PTY is killed in the catch so no orphan claude child remains.
+    const sidecar = {
+        senderId: args.senderId,
+        role: args.role,
+        channel: args.channel,
+        url: capturedUrl,
+        startedAt,
+        permissionMode: args.permissionMode ?? null,
+        model: args.model ?? null,
+        hidden,
+        specialist,
+    };
+    const sidecarPath = sidecarPathForSessionId(deps.spawnCwd, sessionId);
+    try {
+        writeSidecar(sidecarPath, sidecar, deps.logger);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        pty.kill('SIGKILL');
+        const stderrTail = tail.getTail();
+        tail.dispose();
+        deps.logger(`spawn-failed reason=sidecar-write-failed sessionId=${sessionId.slice(0, 8)} path=${sidecarPath} err=${JSON.stringify(detail)} stderr-tail=${formatTailForLog(stderrTail)}`);
+        return { ok: false, reason: 'sidecar-write-failed', stderrTail };
+    }
+    // Task 260 — the watcher's row was built BEFORE we wrote the sidecar
+    // (waitForPid resolved first), so its sidecar fields are still null.
+    // Force a re-read so subsequent /list and /events calls see the
+    // freshly-written senderId/role/channel/etc. Some test fixtures use
+    // a hand-built watcher mock that predates `refreshSidecar` on the
+    // interface — the optional-chain keeps them working without a forced
+    // sweep update.
+    deps.watcher.refreshSidecar?.(sessionId);
+    const tracker = {
         sessionId,
         bridgeSessionId: row.bridgeSessionId ?? `session_${sessionId}`,
         bridgeSuffix: row.bridgeSuffix ?? sessionId,
         pid: pty.pid,
-        url: capturedUrl,
-        startedAt,
-        senderId: args.senderId,
-        role: args.role,
-        channel: args.channel,
         pty,
         exited: false,
         fdReleased: false,
-        hidden: args.hidden === true,
-        specialist: args.specialist ?? row.agent ?? null,
+        hidden,
+        specialist,
+        scopeUnitToken: unitToken,
     };
-    deps.store.add(session);
-    if (args.hidden === true) {
-        deps.logger(`hidden-spawn specialist=${session.specialist ?? 'none'} sessionId=${session.sessionId} pid=${pty.pid}`);
+    livePtys.set(sessionId, tracker);
+    deps.logger(`[pty-tracker] op=spawn sessionId=${sessionId.slice(0, 8)} pid=${pty.pid} size=${livePtys.size}`);
+    if (hidden) {
+        deps.logger(`hidden-spawn specialist=${specialist ?? 'none'} sessionId=${sessionId} pid=${pty.pid}`);
     }
     // PTY exit: mark exited; the watcher will fire a delete event when
     // claude removes its PID file, which the http-server subscriber
@@ -898,12 +1016,12 @@ export async function spawnClaudeSession(deps, args) {
     pty.onExit((e) => {
         const stderrTail = tail.getTail();
         tail.dispose();
-        handlePtyNaturalExit({ store: deps.store, logger: deps.logger }, session, e, stderrTail);
+        handlePtyNaturalExit({ logger: deps.logger }, tracker, e, stderrTail);
     });
     const responseMs = Date.now() - start;
-    deps.logger(`spawn-response-returned sessionId=${session.sessionId} pid=${pty.pid} ms=${responseMs}`);
-    deps.logger(`spawn pid=${pty.pid} sessionId=${session.sessionId} senderId=${args.senderId} role=${args.role} channel=${args.channel} permissionMode=${args.permissionMode ?? 'default'} remoteControl=${!headless} latency-ms=${responseMs}`);
-    deps.logger(`[pty-spawn] sessionId=${session.sessionId} appendSystemPromptBytes=${Buffer.byteLength(appendSystemPrompt, 'utf8')} identityBytes=${composedBytes.identity} soulBytes=${composedBytes.soul} aboutOwnerBytes=${composedBytes.aboutOwner} dormantPluginsBytes=${composedBytes.dormantPlugins} accountDir=${deps.accountDir} role=${args.role} specialist=${args.specialist ?? 'none'} hostname=${deps.host.hostname} lanIPv4=${deps.host.lanIPv4} adminUrl=${deps.host.adminUrl} tunnelUrl=${composedHost.tunnelUrl ?? 'none'}`);
+    deps.logger(`spawn-response-returned sessionId=${sessionId} pid=${pty.pid} ms=${responseMs}`);
+    deps.logger(`spawn pid=${pty.pid} sessionId=${sessionId} senderId=${args.senderId} role=${args.role} channel=${args.channel} permissionMode=${args.permissionMode ?? 'default'} remoteControl=${!headless} latency-ms=${responseMs}`);
+    deps.logger(`[pty-spawn] sessionId=${sessionId} appendSystemPromptBytes=${Buffer.byteLength(appendSystemPrompt, 'utf8')} identityBytes=${composedBytes.identity} soulBytes=${composedBytes.soul} aboutOwnerBytes=${composedBytes.aboutOwner} dormantPluginsBytes=${composedBytes.dormantPlugins} accountDir=${deps.accountDir} role=${args.role} specialist=${args.specialist ?? 'none'} hostname=${deps.host.hostname} lanIPv4=${deps.host.lanIPv4} adminUrl=${deps.host.adminUrl} tunnelUrl=${composedHost.tunnelUrl ?? 'none'}`);
     // Task 178 — emit [pty-spawn-tool-inventory] for specialist spawns. The
     // probe runs in parallel with the real claude child's own MCP handshake
     // and is fire-and-forget: it never blocks the spawn response, and its
@@ -957,7 +1075,7 @@ export async function spawnClaudeSession(deps, args) {
             }));
         const inventoryTimeoutMs = deps.toolInventoryProbeTimeoutMs ?? 5_000;
         emitToolInventoryAsync({
-            sessionId: session.sessionId,
+            sessionId: sessionId,
             specialist: args.specialist,
             frontmatterAllowlist: specialistTools,
             resolvedServers,
@@ -975,7 +1093,7 @@ export async function spawnClaudeSession(deps, args) {
         // this task investigates): without the timer, a spawn that never
         // produces a first turn would never emit a final snapshot, and the
         // operator would have no signal at all for the broken case.
-        finalSnapshotState.set(session.sessionId, {
+        finalSnapshotState.set(sessionId, {
             specialist: args.specialist,
             frontmatterAllowlist: specialistTools,
             resolvedServers,
@@ -986,7 +1104,7 @@ export async function spawnClaudeSession(deps, args) {
             logger: deps.logger,
             spawnedAt: Date.now(),
             fired: false,
-            watchdog: setTimeout(() => fireFinalSnapshot(session.sessionId, 'first-turn-timeout'), firstTurnTimeoutMs),
+            watchdog: setTimeout(() => fireFinalSnapshot(sessionId, 'first-turn-timeout'), firstTurnTimeoutMs),
         });
     }
     // Task 183 — register the specialist spawn with the JSONL tail. The
@@ -1004,12 +1122,12 @@ export async function spawnClaudeSession(deps, args) {
     // probe block); whichever fires first wins, the other is a no-op via
     // the `fired` guard inside `fireFinalSnapshot`.
     if (isSpecialistSpawn && deps.jsonlTail) {
-        deps.jsonlTail.register(session.sessionId, {
+        deps.jsonlTail.register(sessionId, {
             specialist: args.specialist,
             argvTools: [],
-            onFirstTurn: () => fireFinalSnapshot(session.sessionId, 'first-turn'),
+            onFirstTurn: () => fireFinalSnapshot(sessionId, 'first-turn'),
         });
-        pty.onExit(() => deps.jsonlTail?.unregister(session.sessionId));
+        pty.onExit(() => deps.jsonlTail?.unregister(sessionId));
     }
     // Task 215 — PTY-exit cleanup for the final-snapshot state runs
     // INDEPENDENTLY of the JsonlTail wiring. When `deps.jsonlTail` is
@@ -1020,48 +1138,63 @@ export async function spawnClaudeSession(deps, args) {
     // against a long-dead session 60 s later.
     if (isSpecialistSpawn && specialistTools !== null) {
         pty.onExit(() => {
-            const state = finalSnapshotState.get(session.sessionId);
+            const state = finalSnapshotState.get(sessionId);
             if (state?.watchdog)
                 clearTimeout(state.watchdog);
-            finalSnapshotState.delete(session.sessionId);
+            finalSnapshotState.delete(sessionId);
         });
     }
-    deps.onSessionReady?.(session);
-    return { ok: true, session };
+    deps.onSessionReady?.(tracker);
+    return {
+        ok: true,
+        session: {
+            sessionId,
+            pid: pty.pid,
+            startedAt,
+            url: capturedUrl,
+            tracker,
+        },
+    };
 }
 /** Task 176 — natural-exit handler. Fires when the claude child exits on
  *  its own (operator `/quit`, SIGINT in the PTY, crash, network drop on
  *  `--remote-control`), with no operator `/stop` and no auto-archive in
- *  flight. Mirrors `stopSession`'s post-Task-170 fd-release + store-remove
- *  contract on the second exit branch the original task explicitly
- *  out-of-scoped. Without this, the master fd lingers in node-pty's
- *  internal socket until V8 GC finalises the IPty object and the
- *  SessionStore row survives until manager shutdown — so the shutdown
- *  loop SIGTERMs PIDs that already logged `process-exited`.
+ *  flight. Mirrors `killSession`'s post-Task-170 fd-release + tracker
+ *  removal contract on the second exit branch the original task
+ *  explicitly out-of-scoped. Without this, the master fd lingers in
+ *  node-pty's internal socket until V8 GC finalises the IPty object,
+ *  and the tracker entry survives until manager shutdown — so the
+ *  shutdown loop SIGTERMs PIDs that already logged `process-exited`.
  *
  *  Side-effect order is load-bearing: set `exited` first so any
- *  concurrent `stopSession` sees the already-exited branch; release the
+ *  concurrent `killSession` sees the already-exited branch; release the
  *  fd second (idempotent on a destroyed socket via the try/catch in
- *  `releasePtyMasterFd`); drop the row third (Map.delete on a missing
- *  key is a no-op, so the operator-request follow-up that races us is
- *  harmless). The log line carries the same `master-fd=...` suffix the
- *  operator-request path emits — every `kill … pid=<n>` line in
- *  `server.log` now ends in `master-fd=...`, no exceptions.
+ *  `releasePtyMasterFd`); drop the tracker third (Map.delete on a
+ *  missing key is a no-op, so the operator-request follow-up that
+ *  races us is harmless). The log line carries the same `master-fd=...`
+ *  suffix the operator-request path emits — every `kill … pid=<n>`
+ *  line in `server.log` now ends in `master-fd=...`, no exceptions.
  *
  *  Exported so `__tests__/stop-session-fd-release.test.ts` can verify
  *  the contract end-to-end without re-implementing the handler in test
  *  code. */
-export function handlePtyNaturalExit(deps, session, exit, stderrTail) {
-    session.exited = true;
-    // Skip if a racing `stopSession` already released the fd — second
+export function handlePtyNaturalExit(deps, tracker, exit, stderrTail) {
+    tracker.exited = true;
+    // Skip if a racing `killSession` already released the fd — second
     // destroy() on a destroyed node-pty socket throws "socket already
     // destroyed" and would turn this line's suffix into a false
     // `master-fd=close-failed`.
-    const fdSuffix = session.fdReleased ? 'master-fd=closed' : releasePtyMasterFd(session);
+    const fdSuffix = tracker.fdReleased ? 'master-fd=closed' : releasePtyMasterFd(tracker);
     if (fdSuffix === 'master-fd=closed')
-        session.fdReleased = true;
-    deps.store.remove(session.sessionId);
-    deps.logger(`kill pid=${session.pid} reason=process-exited exit-code=${exit.exitCode} signal=${exit.signal ?? 'none'} stderr-tail=${formatTailForLog(stderrTail)} ${fdSuffix}`);
+        tracker.fdReleased = true;
+    // Task 260 — only remove the tracker entry if it is still OUR tracker.
+    // A subsequent spawn could have replaced the entry under the same
+    // sessionId (LRU recycle in production; cross-fixture sessionId
+    // collision in tests).
+    if (livePtys.get(tracker.sessionId) === tracker)
+        livePtys.delete(tracker.sessionId);
+    deps.logger(`kill pid=${tracker.pid} reason=process-exited exit-code=${exit.exitCode} signal=${exit.signal ?? 'none'} stderr-tail=${formatTailForLog(stderrTail)} ${fdSuffix}`);
+    deps.logger(`[pty-tracker] op=exit sessionId=${tracker.sessionId.slice(0, 8)} pid=${tracker.pid} size=${livePtys.size}`);
 }
 /** Release the pty master fd by destroying node-pty's internal socket.
  *  Without this, the fd lingers until V8 GC finalizes the IPty object —
@@ -1070,9 +1203,9 @@ export function handlePtyNaturalExit(deps, session, exit, stderrTail) {
  *  err=..." on throw). The throw path is rescued so a destroy failure
  *  on a corner-case socket state cannot turn a logically-successful
  *  stop into a 500. Task 170. */
-function releasePtyMasterFd(s) {
+function releasePtyMasterFd(t) {
     try {
-        s.pty.destroy?.();
+        t.pty.destroy?.();
         return 'master-fd=closed';
     }
     catch (err) {
@@ -1080,42 +1213,100 @@ function releasePtyMasterFd(s) {
         return `master-fd=close-failed err=${JSON.stringify(msg)}`;
     }
 }
-/** SIGTERM-only stop. Idempotent — already-exited rows resolve immediately.
- *  Does not touch the JSONL transcript. Returns whether a PTY existed. */
+/** Task 250 + 260 — operator-request stop. Issues `systemctl --user
+ *  stop --no-block <scope>` against the PTY's scope unit (Task 250)
+ *  instead of `pty.kill('SIGTERM')`; the scope's TimeoutStopSec=5 handles
+ *  SIGTERM→SIGKILL escalation inside its own cgroup. Idempotent: a
+ *  no-such-unit response (exit code 5) is treated as success because
+ *  claude exited naturally and systemd retired the scope. The master fd
+ *  is still released locally — fd ownership stays with the manager
+ *  process and must be cleaned up there, irrespective of which process
+ *  killed claude.
+ *
+ *  Task 260 — looks up the tracker in the module-scoped `livePtys` map
+ *  (the metadata-rich SessionStore is gone). Deletes by identity (only
+ *  if `livePtys.get(sessionId) === t`) so an LRU recycle or a
+ *  cross-fixture sessionId collision in tests never clobbers a live
+ *  PTY whose tracker was registered after the current call resolved. */
 export async function stopSession(deps, sessionId) {
-    const s = deps.store.get(sessionId);
-    if (!s)
-        return { existed: false };
-    if (s.exited) {
+    const t = livePtys.get(sessionId);
+    if (!t) {
+        return { existed: false, scopeOutcome: 'no-store-entry', exitCode: null };
+    }
+    const start = Date.now();
+    const unit = scopeUnitName(t.scopeUnitToken);
+    if (t.exited) {
         // Task 176 short-circuit: if the natural-exit handler already
         // released the fd, skip the second destroy() — on real node-pty it
         // would throw "socket already destroyed" and we'd emit a false
         // `master-fd=close-failed`. Defense in depth still holds: if the
         // earlier destroy threw, fdReleased stays false and we retry here.
-        const fdSuffix = s.fdReleased ? 'master-fd=closed' : releasePtyMasterFd(s);
+        const fdSuffix = t.fdReleased ? 'master-fd=closed' : releasePtyMasterFd(t);
         if (fdSuffix === 'master-fd=closed')
-            s.fdReleased = true;
-        deps.store.remove(sessionId);
-        deps.logger(`kill sessionId=${sessionId} pid=${s.pid} reason=operator-request status=already-exited ${fdSuffix}`);
-        return { existed: true };
+            t.fdReleased = true;
+        if (livePtys.get(sessionId) === t)
+            livePtys.delete(sessionId);
+        deps.logger(`[stop-session] systemd-scope-stop unit=${unit} outcome=already-exited ms=${Date.now() - start} sessionId=${sessionId} pid=${t.pid} ${fdSuffix}`);
+        deps.logger(`[pty-tracker] op=exit sessionId=${sessionId.slice(0, 8)} pid=${t.pid} size=${livePtys.size}`);
+        return { existed: true, scopeOutcome: 'already-gone', exitCode: null };
     }
-    s.pty.kill('SIGTERM');
-    await new Promise((resolve) => {
-        const grace = setTimeout(() => {
-            if (!s.exited)
-                s.pty.kill('SIGKILL');
-            resolve();
-        }, deps.killGraceMs);
-        s.pty.onExit(() => {
-            clearTimeout(grace);
-            resolve();
-        });
-    });
-    const fdSuffix = s.fdReleased ? 'master-fd=closed' : releasePtyMasterFd(s);
+    const run = deps.runSystemctl ?? defaultSystemctlRunner;
+    const stop = stopScopeUnit(run, t.scopeUnitToken);
+    if (stop.outcome === 'error') {
+        deps.logger(`[stop-session] systemd-scope-stop unit=${unit} outcome=error exit-code=${stop.exitCode} ms=${Date.now() - start} sessionId=${sessionId} pid=${t.pid} stderr=${JSON.stringify(stop.stderr.slice(-200))}`);
+        return { existed: true, scopeOutcome: 'error', exitCode: stop.exitCode };
+    }
+    // outcome=ok or already-gone — both mean the scope is on its way out (or
+    // already retired). Release the manager-side master fd and drop the
+    // tracker entry; the watcher will observe Claude Code's PID-file delete
+    // shortly and emit the archive transition.
+    const fdSuffix = t.fdReleased ? 'master-fd=closed' : releasePtyMasterFd(t);
     if (fdSuffix === 'master-fd=closed')
-        s.fdReleased = true;
-    deps.store.remove(sessionId);
-    deps.logger(`kill sessionId=${sessionId} pid=${s.pid} reason=operator-request exit-code=0 ${fdSuffix}`);
-    return { existed: true };
+        t.fdReleased = true;
+    if (livePtys.get(sessionId) === t)
+        livePtys.delete(sessionId);
+    deps.logger(`[stop-session] systemd-scope-stop unit=${unit} outcome=${stop.outcome} ms=${Date.now() - start} sessionId=${sessionId} pid=${t.pid} ${fdSuffix}`);
+    deps.logger(`[pty-tracker] op=exit sessionId=${sessionId.slice(0, 8)} pid=${t.pid} size=${livePtys.size}`);
+    return {
+        existed: true,
+        scopeOutcome: stop.outcome,
+        exitCode: stop.outcome === 'already-gone' ? stop.exitCode : 0,
+    };
+}
+/** Task 260 — alias preserved during the http-server callsite rename
+ *  in this branch. The canonical export name is `stopSession` (Task 250). */
+export const killSession = stopSession;
+export function writeInputToPty(sessionId, text, logger, channel) {
+    const t = livePtys.get(sessionId);
+    if (!t)
+        return { ok: false, error: 'not-found' };
+    if (t.exited)
+        return { ok: false, error: 'exited' };
+    const bytes = Buffer.byteLength(text, 'utf8');
+    // Task 122 — multi-line `text` must arrive at the TUI as one submitted
+    // turn, not as keystrokes. Claude's TUI treats embedded `\n` typed via
+    // `pty.write` as a bracketed-paste boundary that buffers and never
+    // submits. Wrapping the bytes in DEC bracketed-paste markers
+    // (\e[200~ ... \e[201~) and then sending `\r` makes the TUI treat the
+    // payload as a single paste followed by an explicit submit keystroke.
+    // Single-line text keeps the previous typed-keystroke path byte-for-byte
+    // so the Sidebar timestamp stimulus is unchanged.
+    const multiline = text.includes('\n');
+    const submitMode = multiline ? 'bracketed-paste' : 'typed';
+    try {
+        if (multiline) {
+            t.pty.write(`\x1b[200~${text}\x1b[201~\r`);
+        }
+        else {
+            t.pty.write(text + '\r');
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger(`input-failed pid=${t.pid} sessionId=${sessionId} message=${msg}`);
+        return { ok: false, error: 'write-failed', detail: msg };
+    }
+    logger(`input pid=${t.pid} sessionId=${sessionId} bytes=${bytes} channel=${channel ?? 'unknown'} multiline=${multiline} submit-mode=${submitMode}`);
+    return { ok: true, bytes };
 }
 //# sourceMappingURL=pty-spawner.js.map