@rjfan/dsh-presence 0.18.0 → 0.20.1

package/index.js

@@ -4,13 +4,12 @@
 import z from '@deepseek-ai/schemastery';
 import { readFileSync } from 'node:fs';
 import { PresencePool } from './src/pool.js';
+import { JobStore } from './src/job-store.js';
 import { definePresenceTools } from './src/tools.js';
 import { presenceRoutes } from './src/api.js';
-import { activeWorkspace } from './src/workspaces.js';
 import { shared } from './src/shared.js';
 import { mountsRoot, parseMountPath } from './src/mounts.js';
-import { installToolInterceptor } from './src/intercept.js';
-import { lookupObservation, recordObservation } from './src/observed-store.js';
+import { installObservationBridge, installToolInterceptor } from './src/intercept.js';
 import { TunnelStore } from './src/tunnel-store.js';
 import { PortDiscovery } from './src/port-discovery.js';
 import { installJobNotifier } from './src/job-notifier.js';
@@ -70,7 +69,11 @@ export function apply(ctx, config = {}) {
     ...config,
   };
 
-  const pool = new PresencePool(settings);
+  // The job registry outlives the process: detached jobs are still on the
+  // machine after a restart, and the store is what makes them visible again
+  // (as `unknown` until a pid probe proves otherwise).
+  const jobStore = new JobStore();
+  const pool = new PresencePool(settings, { jobStore });
   shared.pool = pool;
   shared.mountsRoot = mountsRoot();
   // D1/D2: saved forwards and the listening-port scanner share one lifecycle
@@ -94,6 +97,7 @@ export function apply(ctx, config = {}) {
     // D1/D2 owners, constructed above with the pool.
     tunnelStore,
     portDiscovery,
+    jobStore,
   };
   ctx.inject(['agents'], (scope) => {
     late.agents = scope.agents;
@@ -121,88 +125,22 @@ export function apply(ctx, config = {}) {
   // The harness read-before-edit policy is event-driven: it records a target as
   // "seen" only when a tool dispatches `fs/observed`. presence_read/write/edit
   // are not the built-in fs tools, so they publish the observation themselves —
-  // otherwise an agent that read a file with presence_read still hits
-  // "file has not been read" when it tries the built-in edit.
+  // otherwise an agent that read a file with presence_read still hits "file has
+  // not been read" when it tries the built-in edit.
   //
-  // The guard's own store is a WeakMap keyed by the live Session, so a resumed or
-  // compacted agent loses it. We also persist (session, target) -> version and,
-  // just before a built-in edit/write, re-publish the observation when the file
-  // is still at that exact version. A changed file is never auto-approved.
-  const sessionIdOf = (exec) => exec?.agent?.session?.id ?? exec?.agent?.session?.header?.id ?? null;
-
-  const resolveTarget = async (exec, path) => {
-    const fs = late.fs;
-    if (!fs || typeof path !== 'string' || path === '') return null;
-    const cwd = await cwdOf(exec);
-    const target = await fs.resolve(path, cwd ? { cwd } : undefined);
-    return target ?? null;
-  };
-
-  const observe = async (exec, path, options = {}) => {
-    try {
-      const target = await resolveTarget(exec, path);
-      if (!target) return;
-      const stat = await late.fs.stat(target);
-      const observation = stat ? { kind: 'present', version: stat.version } : { kind: 'absent' };
-      ctx.emit('fs/observed', target, observation, { agent: exec.agent });
-      if (stat && options.remember !== false) {
-        recordObservation(sessionIdOf(exec), String(target.targetKey ?? ''), stat.version);
-      }
-    } catch {
-      /* the observation is an optimization, never a failure */
-    }
-  };
-
+  // The bridge (src/intercept.js) canonicalizes every path spelling to
+  // `presence://host/path`, persists (session, canonical target) -> version and,
+  // just before a built-in edit/write, re-publishes the observation when the
+  // file is still at that exact version. That repairs the guard after
+  // compaction, when its own WeakMap is gone; a changed file is never
+  // auto-approved.
   ctx.inject(['fs'], (scope) => {
     late.fs = scope.fs;
     scope.effect(() => () => {
       late.fs = undefined;
     });
   });
-
-  // Built-in read/read_image: remember what the session has seen, so the record
-  // survives compaction even though the guard's WeakMap does not.
-  ctx.on('tools/post-execute', async (exec, result, next) => {
-    try {
-      if (!result?.isError && (exec?.name === 'read' || exec?.name === 'read_image')) {
-        const path = exec.arguments?.file_path;
-        const target = await resolveTarget(exec, path);
-        if (target) {
-          const stat = await late.fs?.stat(target);
-          if (stat) recordObservation(sessionIdOf(exec), String(target.targetKey ?? ''), stat.version);
-        }
-      }
-    } catch {
-      /* best effort */
-    }
-    return next();
-  });
-
-  // Built-in edit/write on a remote target: if this session read the file at the
-  // same version we recorded, re-publish the observation so the guard passes.
-  ctx.on('tools/pre-execute', async (exec, next) => {
-    try {
-      if (exec?.name === 'edit' || exec?.name === 'write') {
-        const path = exec.arguments?.file_path;
-        if (typeof path === 'string' && late.fs) {
-          const sessionId = sessionIdOf(exec);
-          const target = await resolveTarget(exec, path);
-          if (target && sessionId) {
-            const recorded = lookupObservation(sessionId, String(target.targetKey ?? ''));
-            if (recorded) {
-              const stat = await late.fs.stat(target);
-              if (stat && stat.version === recorded) {
-                ctx.emit('fs/observed', target, { kind: 'present', version: stat.version }, { agent: exec.agent });
-              }
-            }
-          }
-        }
-      }
-    } catch {
-      /* best effort: a failed repair leaves the original guard behavior */
-    }
-    return next();
-  });
+  const { observe } = installObservationBridge(ctx, { cwdOf, late });
 
   for (const definition of definePresenceTools(pool, settings, { cwdOf, observe })) {
     ctx.tools.register(definition);
@@ -285,7 +223,20 @@ export function apply(ctx, config = {}) {
     });
   });
 
-  // Tell the model what is reachable without spending tokens on every alias.
+  // ---------------------------------------------------------------- prompts
+  //
+  // The static context is deployment-wide and token-cheap. 0.20 makes the
+  // session-scope sentence explicit: a LOCAL session and a session inside a
+  // remote workspace need opposite rules, and the 0.19 wording ("if your
+  // working directory is under the mounts root...") let a local session assume
+  // it was remote.
+  const STATIC_GUIDANCE =
+    '- Which tool: inside the workspace mount use the built-in read/write/edit/grep/glob (grep/glob are routed to the remote machine); absolute paths outside it (/data, GPFS, /scratch) need presence_read/write/edit/stat/search/glob, and listing or running commands there needs presence_exec (e.g. presence_exec {command:"ls -la /data"}); present and Office only see local files, so presence_export first.\n' +
+    '- Long jobs: presence_exec {background:true} then presence_jobs {action:"status"|"wait"}, with presence_tail to follow the log. Interactive shells: presence_terminal (tmux sessions survive reconnects). Do not start nohup/tmux new-session/& inside a foreground presence_exec for long work — a login-node session can be cleaned up; background:true already detaches with setsid, and on scheduler-managed clusters use the cluster launcher (rlaunch -d, salloc/sbatch).\n' +
+    '- Output: \\r progress bars are normalized by default (progress:"all"/"strip" available); output over the cap is spilled to a remote file whose path is returned — presence_tail it.\n' +
+    '- Destructive commands: dry-run first; confirm:true runs the whole command, confirm:"partial" runs only the safe segments; prefer presence_trash.\n' +
+    '- Hosts: transient failures are retried, then a host may show degraded with the last error; presence_hosts marks the current workspace machine.';
+
   ctx.inject(['systemPrompt'], (scope) => {
     scope.effect(() =>
       scope.systemPrompt.context({
@@ -298,8 +249,13 @@ export function apply(ctx, config = {}) {
           const live = connected.length > 0 ? `connected now: ${connected.join(', ')}` : 'none connected yet';
           return (
             `Presence ${VERSION ?? ''}${VERSION ? ':' : ''} ${hosts.length} remote machines from ~/.ssh/config (${live}). ` +
-            'If your working directory is under the presence mounts root, this session runs against that remote machine: ' +
-            'read/write/edit, the file tree, and grep/glob all reach it (grep/glob are routed to the remote machine automatically). ' +
+            'Session scope — decide this first; the two cases need opposite behaviour. ' +
+            '(a) If your working directory is under the presence mounts root (`~/.dsh/presence/mounts/<host>/<path>`), ' +
+            'this session RUNS IN that remote workspace: built-in read/write/edit, the file tree, and grep/glob all reach it ' +
+            '(grep/glob are routed to the remote machine automatically). ' +
+            '(b) If your working directory is NOT under that root, this session is LOCAL: built-in tools touch only local files, ' +
+            'so every presence_* call must pass `host` explicitly (or have PRESENCE_HOST configured once), and remote output is ' +
+            'never your workspace. ' +
             'TO CHANGE A REMOTE FILE use the built-in `edit`/`write` tools or presence_edit/presence_write — never `sed -i`, ' +
             '`perl -pi`, or shell redirects, which bypass the atomic write, the ambiguity check and the version guard. ' +
             'DESTRUCTIVE shell commands (rm -r/-f, git clean -fdx, find -delete, shred, dd of=) are dry-run first and need confirm:true; ' +
@@ -310,13 +266,112 @@ export function apply(ctx, config = {}) {
             'read_image works directly on remote images (mount path or presence:// URL) as long as the model accepts image input. ' +
             'Built-in read/write/edit and presence_read/write/edit both reach the remote workspace and share the read-before-edit guard; ' +
             'that guard is repaired automatically after compaction, so a file you already read stays editable. Prefer the built-in tools inside the workspace and presence_* outside it. ' +
-            'For long work start it with presence_exec {background:true}, then use presence_jobs {action:"wait"} instead of sleep+poll, ' +
+            'For long work start it with presence_exec {background:true}, then use presence_jobs {action:"wait"} or presence_wait instead of sleep+poll, ' +
             'and presence_jobs {action:"list"|"stop"} to manage this session\'s jobs. ' +
             'The mount path is virtual: Explorer, Office, Python and native open cannot see remote files — call presence_export first, then present the returned local path. ' +
-            'Paths may be given relative to the workspace root, as a presence:// URL, or as the local mount path.'
+            'Paths may be given relative to the workspace root, as a presence:// URL, or as the local mount path.' +
+            `\n\nGuidance:\n${STATIC_GUIDANCE}` +
+            '\n\nSession scope rules:\n' +
+            '- Local session: the globally last-opened remote workspace is not bound to this session; pass host explicitly on every presence_* call, and treat presence_exec output as remote data — not as files in your working directory.\n' +
+            '- Remote-workspace session: prefer the built-in read/write/edit/grep/glob inside the mounted workspace; use presence_read/write/edit/stat/search/glob for absolute paths elsewhere (presence_exec for listing/commands), and pass host explicitly for any machine other than the mount host.\n' +
+            '- presence_hosts marks the machine this session is mounted on (if any) and the explicit default host; check it before assuming a machine.'
           );
         },
       }),
     );
   });
+
+  // Per-agent session scope. No static text can know where *this* agent runs, so
+  // resolve the agent's working directory once when it is created and register a
+  // scoped system-prompt section (the pattern `dsh-file-reference-local` uses:
+  // `agent.ctx.inject([...])` + `scope.systemPrompt.section(...)`), disposed with
+  // the agent. The section text is a function so a `cd` into/out of a mounted
+  // workspace updates it; the resolved cwd is only the fallback.
+  const sessionScopeFibers = new Map();
+  const sessionScopeText = (cwd) => {
+    if (!cwd) return '';
+    const mounted = parseMountPath(cwd);
+    if (mounted) {
+      return (
+        `This session runs in the remote workspace ${mounted.host}:${mounted.path}; ` +
+        'built-in read/write/edit, the file tree and grep/glob reach it. ' +
+        `presence_* calls may omit host for ${mounted.host} only — pass host explicitly for any other machine — ` +
+        'and remote output is not your local workspace.'
+      );
+    }
+    return (
+      `This session is LOCAL (cwd=${JSON.stringify(cwd)}). Presence tools are optional: ` +
+      'pass host explicitly on every presence_* call (or configure PRESENCE_HOST once), and never treat remote output ' +
+      'as the workspace or as a local path.'
+    );
+  };
+  const installSessionScope = (agent) => {
+    if (!agent?.ctx || sessionScopeFibers.has(agent)) return sessionScopeFibers.get(agent) ?? null;
+    let fiber = null;
+    try {
+      fiber = agent.ctx.inject(['systemPrompt', 'workingDirectory'], async (scope) => {
+        let cwd = null;
+        try {
+          cwd = (await scope.workingDirectory.ensure(agent)) ?? null;
+        } catch {
+          cwd = null;
+        }
+        scope.systemPrompt.section({
+          name: 'presence:session-scope',
+          order: 450,
+          text: () => {
+            let current = cwd;
+            try {
+              current = scope.workingDirectory?.get?.(agent.session) ?? cwd;
+            } catch {
+              current = cwd;
+            }
+            return sessionScopeText(current);
+          },
+        });
+      });
+      sessionScopeFibers.set(agent, fiber);
+    } catch (error) {
+      console.error(`presence: could not install the per-agent session scope: ${error?.message ?? String(error)}`);
+      return null;
+    }
+    return fiber;
+  };
+  const disposeSessionScope = (agent) => {
+    const fiber = sessionScopeFibers.get(agent);
+    if (!fiber) return;
+    sessionScopeFibers.delete(agent);
+    try {
+      Promise.resolve(fiber.dispose()).catch(() => {});
+    } catch {
+      /* already gone */
+    }
+  };
+  ctx.on('agent/created', (payload) => {
+    installSessionScope(payload?.agent ?? payload);
+  });
+  ctx.on('agent/disposed', (payload) => {
+    disposeSessionScope(payload?.agent ?? payload);
+  });
+  // Agents that already exist when Presence activates need the section too; a
+  // missing `agents` service just means there is nothing to install yet.
+  ctx.inject(['agents'], (scope) => {
+    try {
+      for (const agent of scope.agents.list()) installSessionScope(agent);
+    } catch {
+      /* best effort: the static context still covers the session scope */
+    }
+  });
+  ctx.effect(() => () => {
+    const disposals = [];
+    for (const [agent, fiber] of [...sessionScopeFibers]) {
+      sessionScopeFibers.delete(agent);
+      try {
+        disposals.push(Promise.resolve(fiber.dispose()));
+      } catch {
+        /* already gone */
+      }
+    }
+    return Promise.allSettled(disposals).then(() => {});
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rjfan/dsh-presence",
-  "version": "0.18.0",
+  "version": "0.20.1",
   "type": "module",
   "description": "Work on any machine in your ssh config as if it were local: persistent connections, native file editing, search, exec and terminals, with nothing installed on the remote host.",
   "icon": "icon.svg",

package/src/api.js

@@ -296,7 +296,9 @@ export function presenceRoutes(pool, late = {}) {
         }
         // C2: the client detects running -> exited transitions from this list.
         // Trimmed to the toast fields: this poll runs every few seconds and the
-        // full pool row carries the command line (session-log sensitive).
+        // full pool row carries the command line (session-log sensitive). 0.20
+        // adds the process identity and the two log paths, so a client can show
+        // which process a persisted job belongs to and tail the right log.
         let jobs = [];
         try {
           jobs = (await pool.listJobs({ sessionId: undefined })).map((job) => ({
@@ -309,6 +311,9 @@ export function presenceRoutes(pool, late = {}) {
             startedAt: job.startedAt ?? null,
             logPath: job.logPath ?? null,
             pid: job.pid ?? null,
+            pgid: job.pgid ?? null,
+            commandLogPath: job.commandLogPath ?? null,
+            persisted: job.persisted === true,
           }));
         } catch {
           jobs = [];

package/src/core/connection.mjs

@@ -123,6 +123,42 @@ function splitLines(text) {
   return lines;
 }
 
+// Progress bars (tqdm, apt, pip, docker pull) repaint one line with `\r`, so a
+// captured stream carries every intermediate state. `last` keeps what each line
+// finally settled on; `all` turns every repaint into its own line so the log
+// stays lossless; `strip` only drops the CR bytes. `raw` is the internal escape
+// hatch for callers reading file content, where a CR may be real data.
+const PROGRESS_MODES = new Set(['last', 'all', 'strip', 'raw']);
+
+/**
+ * Normalize carriage-return progress output in one captured stream.
+ *
+ * Applied before the output cap and the spill file are computed, so the text a
+ * caller sees, the bytes counted against `maxOutputBytes` and the spilled copy
+ * all describe the same stream.
+ *
+ * @param {string} text - the captured stream decoded as latin1 (byte-faithful).
+ * @param {'last'|'all'|'strip'|'raw'} [mode] - an unknown mode falls back to
+ *   `'last'`.
+ * @returns {string} the normalized text; re-encoding it as latin1 restores the
+ *   original bytes except for the CR/LF bytes this mode rewrote.
+ */
+export function normalizeProgress(text, mode = 'last') {
+  const chosen = PROGRESS_MODES.has(mode) ? mode : 'last';
+  const value = String(text ?? '');
+  if (chosen === 'raw') return value;
+  if (chosen === 'strip') return value.replace(/\r/g, '');
+  if (chosen === 'all') return value.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  // 'last': per line, keep only what was written after its final carriage return.
+  return value
+    .split('\n')
+    .map((line) => {
+      const at = line.lastIndexOf('\r');
+      return at === -1 ? line : line.slice(at + 1);
+    })
+    .join('\n');
+}
+
 function randomToken() {
   return randomBytes(6).toString('hex');
 }
@@ -391,7 +427,10 @@ export class PresenceConnection {
   }
 
   /** Run one command over a fresh channel; the connection stays up. */
-  async exec(command, { timeoutMs = 120_000, env = null, signal, maxOutputBytes = OUTPUT_CAP_BYTES } = {}) {
+  async exec(
+    command,
+    { timeoutMs = 120_000, env = null, signal, maxOutputBytes = OUTPUT_CAP_BYTES, progress = 'last' } = {},
+  ) {
     if (this.#closed) throw new Error('connection is closed');
     if (signal?.aborted) throw new Error('command aborted');
 
@@ -415,13 +454,22 @@ export class PresenceConnection {
 
     await this.#acquire();
     try {
-      return await this.#execChannel(wrapped, { timeoutMs: budgetMs, signal, maxOutputBytes, remoteDeadline });
+      return await this.#execChannel(wrapped, { timeoutMs: budgetMs, signal, maxOutputBytes, remoteDeadline, progress });
     } finally {
       this.#release();
     }
   }
 
-  #execChannel(command, { timeoutMs = 0, signal = null, maxOutputBytes = OUTPUT_CAP_BYTES, remoteDeadline = false } = {}) {
+  #execChannel(
+    command,
+    {
+      timeoutMs = 0,
+      signal = null,
+      maxOutputBytes = OUTPUT_CAP_BYTES,
+      remoteDeadline = false,
+      progress = 'last',
+    } = {},
+  ) {
     const cap = Number(maxOutputBytes) > 0 ? Math.floor(Number(maxOutputBytes)) : Infinity;
 
     return new Promise((resolve, reject) => {
@@ -438,26 +486,27 @@ export class PresenceConnection {
         signal?.removeEventListener('abort', onAbort);
       };
 
-      /** Head of the stream for the caller, the rest onto the remote disk. */
+      /**
+       * Head of the stream for the caller, the rest onto the remote disk.
+       *
+       * Normalization happens first: CR and LF are single-byte ASCII, so
+       * decoding as latin1 rewrites only those bytes and re-encoding restores
+       * every other byte exactly, even for binary output. The returned head is
+       * decoded as UTF-8 afterwards, as before.
+       *
+       * A truncated stream always carries either the spill path or the reason
+       * the spill could not be written, so output is never dropped silently.
+       */
       const keepHead = async (chunks, kind) => {
-        const all = Buffer.concat(chunks);
-        if (all.length <= cap) return { text: all.toString('utf8'), truncated: false, file: null, bytes: 0 };
-        const text = all.subarray(0, cap).toString('utf8');
-        // One file per truncated stream, so a caller can follow the rest even
-        // after the tool output was clipped. It holds at most SPILL_MAX_BYTES:
-        // a command that prints gigabytes must not fill /tmp.
-        const file = `/tmp/presence-exec-${randomToken()}${kind === 'stdout' ? '' : `-${kind}`}.log`;
-        // Best effort, and deliberately outside the slot pool: the caller still
-        // owns a slot while this result is being built.
-        await this.#pruneSpillLogs();
-        const data = all.subarray(0, SPILL_MAX_BYTES);
-        try {
-          const written = await this.writeText(file, data);
-          return { text, truncated: true, file, bytes: written.bytes };
-        } catch {
-          // A read-only /tmp must not turn a finished command into a failure.
-          return { text, truncated: true, file: null, bytes: 0 };
+        const raw = Buffer.concat(chunks);
+        const all =
+          progress === 'raw' ? raw : Buffer.from(normalizeProgress(raw.toString('latin1'), progress), 'latin1');
+        if (all.length <= cap) {
+          return { text: all.toString('utf8'), truncated: false, file: null, bytes: 0, error: null };
         }
+        const text = all.subarray(0, cap).toString('utf8');
+        const spill = await this.#spillOutput(all, kind);
+        return { text, truncated: true, file: spill.file, bytes: spill.bytes, error: spill.error };
       };
 
       const buildResult = async (code, signalName, { timedOut, durationMs }) => {
@@ -471,16 +520,30 @@ export class PresenceConnection {
           durationMs,
           stdoutTruncated: stdout.truncated,
           stderrTruncated: stderr.truncated,
-          timedOut,
+          timedOut: Boolean(timedOut),
         };
         if (stdout.truncated) {
+          // A path is always reported; when the spill write itself failed the
+          // path is null and the reason travels with it.
           value.stdoutFile = stdout.file;
           value.stdoutFileBytes = stdout.bytes;
+          if (stdout.file === null) value.stdoutFileError = stdout.error;
         }
         if (stderr.truncated) {
           value.stderrFile = stderr.file;
           value.stderrFileBytes = stderr.bytes;
+          if (stderr.file === null) value.stderrFileError = stderr.error;
         }
+        if (timedOut) {
+          // The deadline fired: the remote `timeout` wrapper sends TERM and
+          // then KILL; when only the local deadline applies, closing the
+          // channel is the only kill there is.
+          value.killed = true;
+          value.killSequence = remoteDeadline ? ['SIGTERM', 'SIGKILL'] : ['channel-close'];
+        }
+        // The shell convention is 128 + 13 for SIGPIPE; keep the code as-is and
+        // let callers translate the meaning.
+        if (code === 141 || /^SIGPIPE$/i.test(String(signalName ?? ''))) value.sigpipe = true;
         return value;
       };
 
@@ -514,14 +577,9 @@ export class PresenceConnection {
         } catch {
           /* channel already gone */
         }
-        if (!remoteDeadline) {
-          // Nothing on the far side enforces the deadline, so do not pretend
-          // the process tree is gone; closing the channel is all we have.
-          reject(new Error(`command timed out after ${timeoutMs}ms (the remote process may still be running)`));
-          return;
-        }
-        // The remote `timeout` should have returned by now; report the deadline
-        // as hit instead of hanging the caller on a channel that never closes.
+        // Keep the output captured before the kill instead of throwing it away:
+        // the caller gets `timedOut`, the kill sequence and the partial stream
+        // (which `buildResult` spills when it is over the cap).
         buildResult(124, null, { timedOut: true, durationMs: started ? Date.now() - started : 0 }).then(resolve, reject);
       }
 
@@ -552,7 +610,8 @@ export class PresenceConnection {
         }
         started = Date.now();
         // No setEncoding: byte counts must match the cap, and the spill file has
-        // to hold the exact bytes the remote process wrote.
+        // to hold the captured stream (progress-normalized in `keepHead`, with
+        // the raw bytes preserved for every non-CR/LF byte).
         channel.on('data', (chunk) => {
           stdoutChunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), 'utf8'));
         });
@@ -603,6 +662,39 @@ export class PresenceConnection {
     }
   }
 
+  /**
+   * Write captured output past the in-memory cap to /tmp. The usual path is
+   * `/tmp/presence-exec-<token>.log`; a failed write is retried once at
+   * `/tmp/presence-exec-<token>-retry.log`, and only then does the result carry
+   * a null path plus the reason — output is never dropped without a trace.
+   *
+   * Best effort, and deliberately outside the slot pool: the caller still owns
+   * a slot while this result is being built.
+   */
+  async #spillOutput(buffer, kind) {
+    if (this.#closed) return { file: null, bytes: 0, error: 'the connection closed before the spill file was written' };
+    const file = `/tmp/presence-exec-${randomToken()}${kind === 'stdout' ? '' : `-${kind}`}.log`;
+    const retry = `${file.slice(0, -'.log'.length)}-retry.log`;
+    // It holds at most SPILL_MAX_BYTES: a command that prints gigabytes must not
+    // fill /tmp.
+    const data = buffer.subarray(0, SPILL_MAX_BYTES);
+    await this.#pruneSpillLogs();
+    let failure = null;
+    for (const path of [file, retry]) {
+      try {
+        const written = await this.writeText(path, data);
+        return { file: path, bytes: written.bytes, error: null };
+      } catch (error) {
+        failure = error;
+      }
+    }
+    return {
+      file: null,
+      bytes: 0,
+      error: String(failure?.message ?? failure ?? 'could not write the spill file'),
+    };
+  }
+
   /** Open an interactive terminal channel (PTY allocated server-side). */
   async shell({ cols = 120, rows = 32, term = 'xterm-256color' } = {}) {
     if (this.#closed) throw new Error('connection is closed');
@@ -1283,6 +1375,8 @@ export class PresenceConnection {
     const read = await this.exec(`sed -n ${shellQuote(`${first},${end}p`)} ${shellQuote(path)}`, {
       timeoutMs: 60_000,
       maxOutputBytes: budget,
+      // This is file content, not command output: a CR in the file is data.
+      progress: 'raw',
     });
     if (read.code !== 0 && read.stdout === '') {
       throw new Error(`could not read ${path}: ${read.stderr.trim() || `sed exited ${read.code}`}`);