@rjfan/dsh-presence 0.18.0 → 0.19.0

package/index.js

@@ -313,7 +313,13 @@ export function apply(ctx, config = {}) {
             'For long work start it with presence_exec {background:true}, then use presence_jobs {action:"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' +
+            '- 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/ls/stat/search/glob; 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.'
           );
         },
       }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rjfan/dsh-presence",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "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/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}`}`);

package/src/destructive.js

@@ -8,6 +8,16 @@
 //      `git clean` -> dry run) so nothing is removed,
 //   3. refuses unset variables, workspace roots/ancestors, home, `/` and `.git`,
 //   4. otherwise returns a report of the resolved targets and requires confirm.
+//
+// 0.19.0 adds two things the P0 feedback asked for:
+//   5. a top-level split of the command line (`;`, `&&`, `||`, newlines outside
+//      quotes), so a rejected mixed command can list the segments that are safe
+//      to run on their own (`confirm:"partial"`), and
+//   6. a single-file exemption: exactly `rm -f <literal path>` for a path that
+//      resolves inside the session workspace runs directly — it cannot remove a
+//      tree, which is what the guard exists to stop.
+
+import { posix } from 'node:path';
 
 export function shq(value) {
   return `'${String(value).replaceAll("'", "'\\''")}'`;
@@ -66,6 +76,176 @@ export function shellWords(text) {
   return words;
 }
 
+/**
+ * Split one command line on top-level `;`, `&&`, `||` and newlines.
+ *
+ * Quotes (`'`, `"`, backtick), backslash escapes and `(...)` / `$(...)` nesting
+ * are honoured, so `echo "a; b"` and `echo "$(a; b)"` stay one segment. A lone
+ * `&` or `|` is a background/pipeline operator rather than a sequence boundary,
+ * so it stays inside its segment; that keeps the unit conservative (the whole
+ * pipeline is one destructive or one safe segment).
+ *
+ * @returns {string[]} trimmed, non-empty segments in command order.
+ */
+export function splitShellSegments(command) {
+  const text = String(command ?? '');
+  const segments = [];
+  let current = '';
+  let quote = null;
+  let depth = 0;
+  const flush = () => {
+    const segment = current.trim();
+    if (segment) segments.push(segment);
+    current = '';
+  };
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    if (quote === "'") {
+      current += character;
+      if (character === "'") quote = null;
+      continue;
+    }
+    if (quote === '"' || quote === '`') {
+      current += character;
+      if (character === '\\' && index + 1 < text.length) {
+        current += text[index + 1];
+        index += 1;
+      } else if (character === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (character === '\\' && index + 1 < text.length) {
+      // An escaped operator is a literal character, not a boundary.
+      current += character + text[index + 1];
+      index += 1;
+      continue;
+    }
+    if (character === "'" || character === '"' || character === '`') {
+      quote = character;
+      current += character;
+      continue;
+    }
+    if (character === '(') {
+      depth += 1;
+      current += character;
+      continue;
+    }
+    if (character === ')') {
+      if (depth > 0) depth -= 1;
+      current += character;
+      continue;
+    }
+    if (depth === 0) {
+      if (character === ';' || character === '\n' || character === '\r') {
+        flush();
+        continue;
+      }
+      if (character === '&' && text[index + 1] === '&') {
+        flush();
+        index += 1;
+        continue;
+      }
+      if (character === '|' && text[index + 1] === '|') {
+        flush();
+        index += 1;
+        continue;
+      }
+    }
+    current += character;
+  }
+  flush();
+  return segments;
+}
+
+/** Characters that make a path non-literal (glob, expansion, redirect, chaining). */
+const NOT_LITERAL_PATH = /[*?[\]$;&|<>`(){}\\~\n\r]/;
+
+/**
+ * The path of an exact `rm -f <one literal path>` command, or null.
+ *
+ * The exemption is intentionally narrow: a different verb/mount, `-r`, an
+ * extra operand, a glob, a variable, a redirect, a pipeline or a second
+ * command all keep the normal guard path.
+ */
+export function singleRmTarget(command) {
+  const text = String(command ?? '');
+  if (NOT_LITERAL_PATH.test(text)) return null;
+  const words = shellWords(text);
+  if (words.length !== 3) return null;
+  if (words[0] !== 'rm' || words[1] !== '-f') return null;
+  const target = words[2];
+  if (!target || target.startsWith('-')) return null;
+  return target;
+}
+
+function withoutTrailingSlashes(value) {
+  const text = String(value);
+  if (text === '/') return '/';
+  return text.replace(/\/+$/, '');
+}
+
+/** Absolute, lexically normalised form of `target` relative to `cwd`. */
+function absoluteRemotePath(cwd, target) {
+  if (!cwd || !target) return null;
+  try {
+    return posix.normalize(posix.join(String(cwd), String(target)));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * True when `target` is deletable under the exemption: inside the workspace,
+ * but neither the workspace root itself nor an ancestor of it.
+ */
+export function isDeletableWorkspaceFile(target, workspaceRoot) {
+  const path = withoutTrailingSlashes(target);
+  const base = withoutTrailingSlashes(workspaceRoot);
+  if (!path.startsWith('/') || !base.startsWith('/')) return false;
+  if (path === base) return false;
+  // `path` is an ancestor of the workspace root (e.g. `/tmp` for `/tmp/ws`).
+  if (base.startsWith(`${path}/`)) return false;
+  return path.startsWith(`${base}/`);
+}
+
+/** Resolve a remote path through symlinks; falls back to the parent directory. */
+async function resolveRemotePath(connection, target, cwd) {
+  const script =
+    `cd ${shq(cwd)} || exit 0; p=${shq(target)}; ` +
+    `r=$(realpath -m -- "$p" 2>/dev/null || readlink -f -- "$p" 2>/dev/null); ` +
+    `[ -n "$r" ] || r=$(cd "$(dirname -- "$p")" 2>/dev/null && printf '%s/%s' "$PWD" "$(basename -- "$p")"); ` +
+    `printf '%s\\n' "$r"`;
+  try {
+    const result = await connection.exec(`bash -c ${shq(script)}`, { timeoutMs: 15_000 });
+    const line = String(result.stdout ?? '')
+      .split('\n')
+      .map((value) => value.trim())
+      .filter(Boolean)[0];
+    return line ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The 0.19.0 single-file exemption: `rm -f <one literal path>` for a path that
+ * resolves inside the workspace, is not the workspace root and cannot be an
+ * ancestor of it. Symlinks are resolved first, so a link inside the workspace
+ * that points outside is not exempt.
+ */
+async function exemptSingleFileRm({ connection, command, cwd, workspace }) {
+  const workspaceRoot = workspace?.path ?? null;
+  if (!cwd || !workspaceRoot) return false;
+  const target = singleRmTarget(command);
+  if (!target) return false;
+  const lexical = absoluteRemotePath(cwd, target);
+  if (!lexical) return false;
+  const resolved = await resolveRemotePath(connection, target, cwd);
+  const candidate = resolved && resolved.startsWith('/') ? posix.normalize(resolved) : lexical;
+  return isDeletableWorkspaceFile(candidate, workspaceRoot);
+}
+
 function isWithin(parent, child) {
   if (!parent) return false;
   const base = parent.replace(/\/+$/, '');
@@ -74,6 +254,13 @@ function isWithin(parent, child) {
 
 /** Run the command in a shell where the destructive verb only reports. */
 async function dryRunDestructive(connection, command, kind, cwd) {
+  if (kind === 'truncate') {
+    // There is no safe replay for these verbs: `shred`/`truncate`/`mkfs`/`dd of=`
+    // write for real and a `:>` redirect cannot be shadowed. Never execute them
+    // in the dry run; report that targets cannot be resolved instead of doing
+    // the damage while claiming "nothing was executed".
+    return { targets: [], stderr: '', code: 0, skipped: true };
+  }
   let probe;
   if (kind === 'rm') {
     probe =
@@ -136,27 +323,71 @@ async function describeTargets(connection, targets, cwd) {
     });
 }
 
+/**
+ * Classify every top-level segment so a rejected command can say which parts
+ * were safe. `targets` is best effort: a segment that depends on an earlier
+ * assignment (`J=""; rm -rf $J`) cannot be dry-run on its own, so it stays empty
+ * instead of guessing.
+ */
+async function describeSplit({ connection, command, cwd, kind, resolved }) {
+  const safeSegments = [];
+  const destructiveSegments = [];
+  for (const segment of splitShellSegments(command)) {
+    const segmentKind = destructiveKind(segment);
+    if (segmentKind) destructiveSegments.push({ segment, kind: segmentKind, targets: [] });
+    else safeSegments.push(segment);
+  }
+  if (destructiveSegments.length === 0) {
+    // The classifier matched across a line break the splitter treats as a
+    // boundary; keep the whole command as the single destructive unit.
+    destructiveSegments.push({ segment: String(command).trim(), kind, targets: [] });
+  }
+  if (destructiveSegments.length === 1 && safeSegments.length === 0) {
+    // The whole command is the destructive segment: reuse the targets the
+    // guard already resolved instead of dry-running it a second time.
+    destructiveSegments[0].targets = resolved;
+    return { safeSegments, destructiveSegments };
+  }
+  for (const entry of destructiveSegments) {
+    try {
+      const segmentDry = await dryRunDestructive(connection, entry.segment, entry.kind, cwd);
+      entry.targets = await describeTargets(connection, segmentDry.targets, cwd);
+    } catch {
+      entry.targets = [];
+    }
+  }
+  return { safeSegments, destructiveSegments };
+}
+
 /**
  * Gate one destructive command.
  *
- * Returns null for a benign command (= run it), a report object for a destructive
- * command without confirmation (= do not run, show the report), and throws for
- * the unrecoverable cases (unset variable, workspace root/ancestor, home, `/`,
- * `.git`) regardless of confirmation.
+ * Returns null for a benign command (= run it) or for the single-file `rm -f`
+ * exemption, a report object for a destructive command without confirmation
+ * (= do not run, show the report), and throws for the unrecoverable cases
+ * (unset variable, workspace root/ancestor, home, `/`, `.git`) regardless of
+ * confirmation.
  *
  * @param connection - live PresenceConnection.
  * @param command - the raw command line.
  * @param cwd - remote working directory, or null.
  * @param workspace - `{ path }` of the session workspace, or null.
  * @param host - alias used in messages.
- * @param confirm - the caller already saw a report and asked to proceed.
+ * @param confirm - the caller already saw a report and asked to proceed
+ *   (`true` = whole command, `'partial'` = the caller runs split.safeSegments).
  */
 export async function guardDestructive({ connection, command, cwd = null, workspace = null, host = 'remote', confirm = false }) {
   const kind = destructiveKind(command);
   if (!kind) return null;
 
+  // 0.19.0: removing one generated file with `rm -f` is the everyday case; the
+  // guard exists to stop tree deletions. Everything that is not exactly
+  // `rm -f <literal path>` inside the workspace keeps the full guard below.
+  if (await exemptSingleFileRm({ connection, command, cwd, workspace })) return null;
+
   const dry = await dryRunDestructive(connection, command, kind, cwd);
   const resolved = await describeTargets(connection, dry.targets, cwd);
+  const split = await describeSplit({ connection, command, cwd, kind, resolved });
   const home = await connection.homePath().catch(() => null);
   const workspaceRoot = workspace?.path ?? null;
 
@@ -174,20 +405,42 @@ export async function guardDestructive({ connection, command, cwd = null, worksp
     );
   }
 
-  const report = [
+  const targetsLine =
+    resolved.length > 0
+      ? 'resolved targets:'
+      : dry.skipped
+        ? `resolved targets: (not resolvable without doing it - ${kind} commands are never replayed)`
+        : 'resolved targets: (none - the command would touch nothing)';
+  const safeLines = split.safeSegments.length > 0 ? split.safeSegments.map((segment) => `  ${segment}`) : ['  (none)'];
+  const confirmHint =
+    split.safeSegments.length > 0
+      ? 'Pass confirm:true to run the whole command, confirm:"partial" to run only the safe segments, ' +
+        'or use presence_trash for a recoverable delete.'
+      : 'Pass confirm:true to run the whole command, or use presence_trash for a recoverable delete.';
+
+  const lines = [
+    'Nothing was executed — the whole command was skipped, including non-destructive parts.',
     `destructive command needs confirmation (${kind}): nothing was executed yet`,
     `host: ${host}`,
     `command: ${String(command).replace(/\s+/g, ' ').slice(0, 400)}`,
     cwd ? `cwd: ${cwd}` : null,
-    resolved.length > 0 ? 'resolved targets:' : 'resolved targets: (none - the command would touch nothing)',
+    targetsLine,
     ...resolved.map((entry) => `  ${entry.type}  ${entry.path}  ${entry.entries}  ${entry.size}`),
-    confirm
-      ? null
-      : 'Pass confirm:true to execute it. Prefer presence_trash when the files are in a workspace (recoverable).',
-  ].filter(Boolean);
+    '',
+    'Safe segments you can run separately:',
+    ...safeLines,
+  ];
+  if (!confirm) lines.push('', confirmHint);
 
   // `targets` is the machine-readable twin of the report's target block:
   // callers that answer in JSON (presence_exec format:'json') do not need to
   // parse the text, and existing callers keep reading `report`/`resolved`.
-  return { kind, report: report.join('\n'), resolved, targets: resolved };
+  // `split` lets the caller run only the safe segments (confirm:"partial").
+  return {
+    kind,
+    report: lines.filter((line) => line !== null && line !== undefined).join('\n'),
+    resolved,
+    targets: resolved,
+    split,
+  };
 }