@rjfan/dsh-presence 0.18.0 → 0.20.1

package/src/tools.js

@@ -1,13 +1,12 @@
 // The model-facing surface. Every tool targets one machine by its ssh alias and
-// reuses that machine's persistent connection 鈥?there is no per-call handshake
+// reuses that machine's persistent connection — there is no per-call handshake
 // and nothing is installed on the far side.
 
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { activeWorkspace } from './workspaces.js';
 import { parseMountPath, parsePresenceUrl } from './mounts.js';
 import { remoteGlobDetailed, remoteGrep, splitGlobPattern } from './remote-search.js';
 import { guardDestructive } from './destructive.js';
-import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, globSync as nodeGlobSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
 import { connect as connectTcp } from 'node:net';
@@ -15,9 +14,15 @@ import { exportDirectory, join as joinPath, dirname as dirnamePath, resolve as r
 import { makeDirectory, movePath, copyPath, chmodPath } from './path-ops.js';
 import { diffLines as buildUnifiedDiff } from './diff.js';
 import { tailRemote } from './tail.js';
+import { waitUntil } from './wait.js';
 
 const OUTPUT_CAP = 32 * 1024;
 const EXEC_OUTPUT_CAP = 16 * 1024;
+const EXEC_DEFAULT_TIMEOUT_MS = 300_000;
+const EXEC_MAX_TAIL_LINES = 5000;
+// The JSON twin of an exec/jobs report must stay one valid JSON document; this
+// is the same budget the text report uses.
+const EXEC_JSON_CAP = 32 * 1024;
 const READ_CAP = 32 * 1024 * 1024;
 const EXPORT_CAP = 64 * 1024 * 1024;
 const WAIT_PORT_TIMEOUT_MS = 15_000;
@@ -37,6 +42,86 @@ const TAIL_MAX_TIMEOUT_MS = 60_000;
 const TAIL_MAX_LINES = 5000;
 const TAIL_JSON_TEXT_CAP = 48 * 1024;
 const TAIL_JSON_MAX = 64 * 1024;
+// presence_wait: one condition, polled; a timeout is data (met:false), not an error.
+const WAIT_DEFAULT_TIMEOUT_MS = 120_000;
+const WAIT_MAX_TIMEOUT_MS = 3_600_000;
+const WAIT_DEFAULT_POLL_MS = 1_000;
+const WAIT_MIN_POLL_MS = 50;
+const WAIT_MAX_POLL_MS = 60_000;
+// One copyable example per condition, used in the tool's validation errors.
+const WAIT_EXAMPLES = {
+  file: '{"file": {"path": "/srv/app/done.marker"}}',
+  grep: '{"grep": {"path": "/srv/app/run.log", "pattern": "ready", "count": 1}}',
+  process: '{"process": {"pattern": "python3 train.py", "alive": true}}',
+  port: '{"port": {"port": 8000, "state": "open"}}',
+  job: '{"job": {"jobId": "j_123"}}',
+};
+// Batch transfers: one call may move at most this many files.
+const TRANSFER_MAX_FILES = 50;
+
+// ------------------------------------------------------- argument aliases
+//
+// Models habitually spell the same argument several ways (`file_path`,
+// `oldString`, `workdir`, ...). The JSON schema keeps one canonical name per
+// parameter; these lists are applied at execute time, and the canonical
+// spelling always wins when a caller sends more than one.
+
+const PATH_ALIASES = ['path', 'file_path', 'filePath'];
+const EDIT_OLD_ALIASES = ['old', 'oldString', 'old_string'];
+const EDIT_NEW_ALIASES = ['new', 'newString', 'new_string'];
+const EDIT_REPLACE_ALL_ALIASES = ['replaceAll', 'replace_all'];
+const EDIT_DRY_RUN_ALIASES = ['dryRun', 'dry_run'];
+const EXEC_CWD_ALIASES = ['cwd', 'workdir', 'dir'];
+const FROM_ALIASES = ['from', 'from_path', 'fromPath'];
+const TO_ALIASES = ['to', 'to_path', 'toPath'];
+// Two-path tools also accept a plain path spelling on their source/destination
+// side, so `{from, path}`-style calls resolve instead of failing.
+const SOURCE_ALIASES = [...FROM_ALIASES, ...PATH_ALIASES];
+const DESTINATION_ALIASES = [...TO_ALIASES, ...PATH_ALIASES];
+const DIFF_A_ALIASES = ['a', 'a_path', 'aPath', ...PATH_ALIASES];
+const DIFF_B_ALIASES = ['b', 'b_path', 'bPath'];
+
+/** One argument value by any accepted spelling; undefined when none is set. */
+function pickArg(args, names) {
+  if (!args || typeof args !== 'object') return undefined;
+  for (const name of names) {
+    const value = args[name];
+    if (value !== undefined && value !== null) return value;
+  }
+  return undefined;
+}
+
+function receivedArgKeys(args) {
+  const keys = Object.keys(args ?? {}).filter((key) => args?.[key] !== undefined);
+  return keys.length > 0 ? keys.join(', ') : 'nothing';
+}
+
+/**
+ * A missing required argument explains itself: which parameter, which
+ * spellings are accepted, what was sent instead, and one copyable example.
+ */
+function missingArgument(toolName, canonical, accepted, args, example) {
+  return new Error(
+    `missing "${canonical}" on ${toolName} ` +
+      `(accepted: ${accepted.join(', ')}; received: ${receivedArgKeys(args)}). ` +
+      `Example: ${example}`,
+  );
+}
+
+/**
+ * Resolve a required path parameter through its alias spellings. The message
+ * advertises the canonical name plus the DSH-style `file_path`.
+ */
+function requirePath(
+  args,
+  toolName,
+  example,
+  { names = PATH_ALIASES, canonical = 'path', accepted = ['path', 'file_path'] } = {},
+) {
+  const value = pickArg(args, names);
+  if (value === undefined || value === '') throw missingArgument(toolName, canonical, accepted, args, example);
+  return value;
+}
 
 function shq(value) {
   return `'${String(value).replaceAll("'", "'\\''")}'`;
@@ -45,21 +130,150 @@ function shq(value) {
 function clip(text, cap = OUTPUT_CAP) {
   if (typeof text !== 'string') return '';
   if (text.length <= cap) return text;
-  return `${text.slice(0, cap)}\n鈥?(${text.length - cap} more characters truncated)`;
+  return `${text.slice(0, cap)}\n... (${text.length - cap} more characters truncated)`;
 }
 
-/** Head + tail clipping: keeps the start (what ran) and the end (why it failed). */
-function clipMiddle(text, cap = EXEC_OUTPUT_CAP) {
-  if (typeof text !== 'string') return '';
-  if (text.length <= cap) return text;
-  const head = Math.floor(cap * 0.4);
-  const tail = cap - head;
+/** `presence_exec.tailLines`: a display budget, whole lines, 0..5000, 0 = off. */
+function execTailLines(value) {
+  if (value === undefined || value === null || value === '') return 0;
+  const number = Number(value);
+  if (!Number.isFinite(number)) return 0;
+  return Math.max(0, Math.min(EXEC_MAX_TAIL_LINES, Math.floor(number)));
+}
+
+/** Only the three progress modes the connection contract defines are forwarded. */
+function execProgress(value) {
+  return value === 'all' || value === 'strip' ? value : 'last';
+}
+
+/**
+ * Commands that start long-lived work: `nohup`, a trailing `&`, or
+ * `tmux new-session`. They belong in `background:true`/`presence_terminal`,
+ * where the job registry or the pty keeps them alive.
+ */
+function longLivedCommand(command) {
+  const value = String(command ?? '');
+  return /\bnohup\b/.test(value) || /tmux\s+new-session/.test(value) || /(?:^|[\s;])&(?!&)\s*$/.test(value);
+}
+
+function backgroundCommandHint(command) {
+  if (!longLivedCommand(command)) return null;
   return (
-    `${text.slice(0, head)}\n鈥?(${text.length - cap} characters truncated; full output below) 鈥n` +
-    text.slice(text.length - tail)
+    'this command starts long-lived background work; use presence_exec {background:true} with presence_jobs ' +
+    '{action:"wait"} to track it, or presence_terminal for an interactive/tmux session; nohup/tmux/& children ' +
+    'may be cleaned up when this SSH channel closes'
   );
 }
 
+/** One job-list command line, clipped so a long command cannot dominate the list. */
+function clipCommandLine(value, max = 200) {
+  const text = stripPipefailPrelude(value);
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}... (${text.length - max} more characters)`;
+}
+
+/** Head slice plus a tail chosen by `tailLines` (or by the remaining budget). */
+function execTailSlice(captured, { tailChars, tailLines }) {
+  if (tailLines > 0) {
+    const rows = captured.split('\n');
+    if (rows.length > 0 && rows.at(-1) === '') rows.pop();
+    const tail = rows.slice(-tailLines).join('\n');
+    // A few very long lines must not blow the display budget either.
+    if (tailChars > 0 && tail.length > tailChars) return tail.slice(-tailChars);
+    return tail;
+  }
+  return captured.slice(Math.max(0, captured.length - Math.max(0, tailChars)));
+}
+
+/**
+ * One `--- stdout ---` / `--- stderr ---` block of the presence_exec text
+ * report: what the caller can read inline, how much was left out, where the
+ * full stream lives, and (with `tailLines`) the last N lines of the capture.
+ */
+function execStreamSection(name, rawValue, result, { inlineCap, tailLines, plain }) {
+  const captured = plain(rawValue);
+  const truncated = (name === 'stdout' ? result.stdoutTruncated : result.stderrTruncated) === true;
+  const file = name === 'stdout' ? result.stdoutFile : result.stderrFile;
+  const fileBytes = name === 'stdout' ? result.stdoutFileBytes : result.stderrFileBytes;
+  const fileError = name === 'stdout' ? result.stdoutFileError : result.stderrFileError;
+  if (!captured && !file) return null;
+  const lines = [`--- ${name} ---`];
+  if (captured.length <= inlineCap && !truncated) {
+    lines.push(captured);
+  } else {
+    const headChars = Math.max(1, Math.floor(inlineCap * 0.4));
+    const head = captured.slice(0, headChars);
+    const tail = execTailSlice(captured, { tailChars: inlineCap - headChars, tailLines });
+    const omitted = Math.max(0, captured.length - head.length - tail.length);
+    const where = file ? `; full ${name}: ${file}` : '';
+    lines.push(head, `... (${omitted} characters omitted${where})`, tail);
+  }
+  if (file) {
+    const size = Number.isFinite(Number(fileBytes)) && Number(fileBytes) > 0 ? ` (${fileBytes} bytes)` : '';
+    lines.push(`${name}: ${file}${size}`);
+  } else if (truncated) {
+    lines.push(`${name}: full output not saved${fileError ? ` (${fileError})` : ''}`);
+  }
+  return lines.join('\n');
+}
+
+/** Character-bigram overlap, used only to suggest edit anchors. */
+function commonBigrams(left, right) {
+  if (left.length < 2 || right.length < 2) return 0;
+  const grams = new Map();
+  for (let index = 0; index < left.length - 1; index += 1) {
+    const gram = left.slice(index, index + 2);
+    grams.set(gram, (grams.get(gram) ?? 0) + 1);
+  }
+  let shared = 0;
+  for (let index = 0; index < right.length - 1; index += 1) {
+    const gram = right.slice(index, index + 2);
+    const count = grams.get(gram) ?? 0;
+    if (count > 0) {
+      grams.set(gram, count - 1);
+      shared += 1;
+    }
+  }
+  return (2 * shared) / (left.length + right.length - 2);
+}
+
+/**
+ * Up to `limit` lines that are the closest match for an anchor an edit could
+ * not find, so a stale read is easy to recognize and fix.
+ */
+function closestLines(content, needle, limit = 3) {
+  const target =
+    String(needle ?? '')
+      .split('\n')
+      .map((line) => line.trim())
+      .find((line) => line.length > 0) ?? '';
+  if (!target) return [];
+  const targetLower = target.toLowerCase();
+  const token = /[a-z0-9_$.-]{3,}/i.exec(targetLower)?.[0] ?? '';
+  const scored = [];
+  String(content ?? '')
+    .split('\n')
+    .forEach((raw, index) => {
+      const line = raw.trim();
+      if (!line) return;
+      const lower = line.toLowerCase();
+      let score = 0;
+      if (lower === targetLower) score = 1;
+      else if (lower.includes(targetLower) || targetLower.includes(lower)) {
+        score = 0.9 * (Math.min(lower.length, targetLower.length) / Math.max(lower.length, targetLower.length));
+      } else if (token && lower.includes(token)) {
+        score = 0.5;
+      } else {
+        score = commonBigrams(targetLower, lower);
+      }
+      if (score > 0.05) {
+        scored.push({ line: index + 1, text: line.length > 160 ? `${line.slice(0, 160)}...` : line, score });
+      }
+    });
+  scored.sort((left, right) => right.score - left.score || left.line - right.line);
+  return scored.slice(0, limit).map(({ line, text: value }) => ({ line, text: value }));
+}
+
 const ANSI_RE = /[\u001B\u009B][[\]()#;?]*(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]|[0-?]*[ -/]*[@-~])/g;
 
 /** Drop ANSI escapes and other control characters that corrupt model-facing text. */
@@ -97,7 +311,7 @@ function isSandboxMessage(message) {
   return /sandbox|escalation available/i.test(String(message ?? ''));
 }
 
-/** "755" | "0755" | "0o755" | 0o755 鈫?octal mode number, or undefined when unset. */
+/** "755" | "0755" | "0o755" | 0o755 → octal mode number, or undefined when unset. */
 function parseMode(value) {
   if (value === undefined || value === null || value === '') return undefined;
   if (typeof value === 'number') return Number.isFinite(value) ? value : undefined;
@@ -124,7 +338,12 @@ async function readRemoteTail(connection, logPath, lines = 20) {
   if (!logPath) return '';
   const count = Math.max(1, Math.min(200, Number(lines) || 20));
   try {
-    const result = await connection.exec(`tail -n ${count} ${shq(logPath)} 2>/dev/null; true`, { timeoutMs: 15_000 });
+    // A log tail is content, not progress output: normalize CRs into line
+    // breaks instead of keeping only the state after the last `\r`.
+    const result = await connection.exec(`tail -n ${count} ${shq(logPath)} 2>/dev/null; true`, {
+      timeoutMs: 15_000,
+      progress: 'all',
+    });
     return String(result?.stdout ?? '').replace(/\n$/, '');
   } catch {
     return '';
@@ -638,7 +857,9 @@ async function waitForJobFallback(pool, id, { timeoutMs, tailLines }) {
     const connection = await pool.connection(job.host);
     const result = await connection.exec(
       `wc -c < ${shq(job.logPath)} 2>/dev/null; tail -n ${Math.max(1, tailLines)} ${shq(job.logPath)} 2>/dev/null`,
-      { timeoutMs: 15_000 },
+      // Same reasoning as readRemoteTail: show the log content, not only the
+      // final state of each progress-bar line.
+      { timeoutMs: 15_000, progress: 'all' },
     );
     const stdout = String(result?.stdout ?? '');
     const newline = stdout.indexOf('\n');
@@ -682,9 +903,13 @@ function jobRecord(job) {
     exitCode: job.exitCode ?? null,
     exitSignal: job.exitSignal ?? null,
     pid: job.pid ?? null,
+    // The persisted registry may add these; older pools simply lack them.
+    pgid: job.pgid ?? null,
+    persisted: job.persisted === true,
     label: job.label ? stripPipefailPrelude(job.label) : null,
     startedAt: job.startedAt ?? null,
     logPath: job.logPath ?? null,
+    commandLogPath: job.commandLogPath ?? null,
     logSize: job.logSize ?? null,
     command: job.command ? stripPipefailPrelude(job.command) : null,
     cwd: job.cwd ?? null,
@@ -787,6 +1012,75 @@ function clampedNumber(value, fallback, min, max) {
   return Math.min(max, Math.max(min, Math.floor(number)));
 }
 
+/** `presence_write` mode: 'append'/'overwrite', or null when the value is an octal file mode. */
+function writeModeOf(value) {
+  if (typeof value !== 'string') return null;
+  const lower = value.trim().toLowerCase();
+  return lower === 'append' || lower === 'overwrite' ? lower : null;
+}
+
+/** A short unpredictable suffix for private staging files (never model-visible). */
+function stagingSuffix() {
+  return `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/**
+ * The files one batch transfer call names: `paths[]` (1-50) plus, for export,
+ * an optional single `path`. Missing input is a self-explaining error.
+ */
+function transferInputs(args, toolName, { single = null } = {}) {
+  const listed = Array.isArray(args.paths) ? args.paths : [];
+  const raw = single !== null && single !== undefined ? [single, ...listed] : listed;
+  const inputs = [];
+  for (const value of raw) {
+    if (typeof value !== 'string' || value.trim() === '') {
+      throw new Error(`${toolName}: every path must be a non-empty string`);
+    }
+    if (!inputs.includes(value.trim())) inputs.push(value.trim());
+  }
+  if (inputs.length > TRANSFER_MAX_FILES) {
+    throw new Error(`${toolName} moves at most ${TRANSFER_MAX_FILES} files per call, got ${inputs.length}`);
+  }
+  return inputs;
+}
+
+/** Local paths matching one glob, relative to `cwd`; the caller resolves them. */
+function localGlobPaths(pattern, cwd) {
+  const source = String(pattern ?? '').trim();
+  if (!source) return [];
+  if (typeof nodeGlobSync !== 'function') {
+    throw new Error('this Node build has no fs.globSync; pass explicit paths instead of a glob');
+  }
+  const matches = nodeGlobSync(source, { cwd });
+  const rows = [];
+  for (const entry of matches) {
+    const value = typeof entry === 'string' ? entry : String(entry?.name ?? entry);
+    if (value && !rows.includes(value)) rows.push(value);
+  }
+  return rows;
+}
+
+/**
+ * Default local destination for one export: the remote basename. An occupied
+ * name (or a name already used by this batch) gets `-<sha8>` before the
+ * extension, so nothing in the export folder is silently overwritten.
+ */
+function exportLocalTarget(folder, remoteTarget, digest, used = new Set()) {
+  const name = String(remoteTarget).split('/').filter(Boolean).pop() ?? 'export.bin';
+  const absolute = (candidate) => joinPath(folder, candidate);
+  const dot = name.lastIndexOf('.');
+  const stem = dot > 0 ? name.slice(0, dot) : name;
+  const extension = dot > 0 ? name.slice(dot) : '';
+  let candidate = name;
+  if (used.has(candidate) || existsSync(absolute(candidate))) {
+    candidate = `${stem}-${digest.slice(0, 8)}${extension}`;
+    let index = 2;
+    while (used.has(candidate)) candidate = `${stem}-${digest.slice(0, 8)}-${index++}${extension}`;
+  }
+  used.add(candidate);
+  return absolute(candidate);
+}
+
 /**
  * JSON text that stays valid: oversized text fields are shortened (twice each
  * round) instead of being cut mid-string, so callers can always JSON.parse it.
@@ -842,10 +1136,13 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
   };
 
   /**
-   * Where this call belongs. Inside a workspace the session's own directory
-   * decides the machine 鈥?every workspace in the sidebar just works, with no
-   * "make it current" step. Explicit host still wins; a session outside any
-   * remote workspace falls back to the last opened one.
+   * Where this call belongs. The session's own directory decides the machine
+   * when it is a mount path — every remote workspace in the sidebar just works,
+   * with no "make it current" step. An explicit `host` still wins, and
+   * `settings.defaultHost` (PRESENCE_HOST) is the documented opt-in for local
+   * sessions. A genuinely local session with neither must fail loudly: the
+   * globally last-activated remote workspace is another session's machine and
+   * silently borrowing it can run commands in the wrong place.
    */
   const pickScope = async (args, exec) => {
     let cwd = null;
@@ -855,15 +1152,24 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
       cwd = null;
     }
     const mounted = cwd ? parseMountPath(cwd) : null;
-    if (mounted && !args.host) return { host: mounted.host, workspace: { host: mounted.host, path: mounted.path } };
-
-    const active = activeWorkspace();
-    const host = args.host || active?.host;
-    if (!host) {
-      throw new Error('no host given and no remote workspace here; call presence_hosts then pass host');
+    const workspace = mounted ? { host: mounted.host, path: mounted.path } : null;
+    const explicitHost =
+      typeof args?.host === 'string' && args.host.trim() !== '' ? args.host.trim() : null;
+    if (explicitHost) {
+      // A workspace-relative path only makes sense on the workspace's own host:
+      // another explicit host gets no workspace context.
+      return { host: explicitHost, workspace: workspace && workspace.host === explicitHost ? workspace : null };
     }
-    const workspace = active && active.host === host ? active : null;
-    return { host, workspace };
+    if (workspace) return { host: workspace.host, workspace };
+    const configured =
+      typeof settings.defaultHost === 'string' && settings.defaultHost.trim() !== ''
+        ? settings.defaultHost.trim()
+        : null;
+    if (configured) return { host: configured, workspace: null };
+    throw new Error(
+      `this session is local (cwd=${cwd ?? 'unknown'}); pass an explicit host. ` +
+        'Remote workspaces are not bound to this session; call presence_hosts first.',
+    );
   };
 
   /** Every alias the ssh config knows, for the "known hosts" hint. */
@@ -891,7 +1197,7 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
   /**
    * Resolve any spelling of a remote path to one absolute remote path:
    * `presence://host/path`, a local mount path, `~/x`, an absolute path, or a
-   * workspace-relative path. One file, several names 鈥?all accepted.
+   * workspace-relative path. One file, several names — all accepted.
    */
   const remotePath = async (connection, workspace, path) => {
     const value = String(path);
@@ -936,7 +1242,7 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
     tool({
       name: 'presence_hosts',
       description:
-        'List the machines Presence can reach, taken from the user\'s ~/.ssh/config, with whether each one is connected right now. Call this before targeting a host for the first time. The default host (the active workspace\'s machine) is marked with "*". format:\'json\' returns one object per host: {alias, address, user, hostname, port, source, state, connected, default}.',
+        'List the machines Presence can reach, taken from the user\'s ~/.ssh/config, with whether each one is connected right now. Call this before targeting a host for the first time. The default host is this session\'s workspace machine (falling back to the configured default host) and is marked with "*". format:\'json\' returns one object per host: {alias, address, user, hostname, port, source, state, connected, default, workspace, lastError?}. state is connected|degraded|idle|error; a degraded row carries lastError.',
       parameters: {
         format: {
           type: 'string',
@@ -944,9 +1250,37 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
           description: 'Return one text block containing JSON: an array of host objects. Defaults to text.',
         },
       },
-      async execute(args) {
+      async execute(args, exec) {
         const hosts = pool.hosts();
-        const defaultHost = settings.defaultHost ?? activeWorkspace()?.host ?? null;
+        // Scope is decided by this session only: a mount path means the session
+        // runs in that remote workspace; otherwise settings.defaultHost
+        // (PRESENCE_HOST) is the documented opt-in. The globally last-activated
+        // workspace is never inherited — it may belong to another session.
+        let workspace = null;
+        try {
+          const cwd = (await cwdOf?.(exec)) ?? null;
+          workspace = cwd ? parseMountPath(cwd) : null;
+        } catch {
+          workspace = null;
+        }
+        const configured =
+          typeof settings.defaultHost === 'string' && settings.defaultHost.trim() !== ''
+            ? settings.defaultHost.trim()
+            : null;
+        const candidate = workspace?.host ?? configured;
+        // A default that is not in the host list cannot be used by this session.
+        const defaultHost = candidate && hosts.some((host) => host.alias === candidate) ? candidate : null;
+        const stateOf = (host) => host.state ?? (host.connected ? 'connected' : 'idle');
+        const stateText = (host) => {
+          const state = stateOf(host);
+          const lastError = host.lastError ?? null;
+          if (state === 'degraded') return `degraded (last error: ${lastError ?? 'unknown'})`;
+          if (state === 'error') return `error${lastError ? ` (last error: ${lastError})` : ''}`;
+          if (state === 'connected' || (state !== 'idle' && host.connected)) {
+            return `connected${host.terminals ? `, ${host.terminals} terminal(s)` : ''}`;
+          }
+          return 'not connected';
+        };
         if (args.format === 'json') {
           return jsonText(
             hosts.map((host) => ({
@@ -956,20 +1290,25 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
               hostname: host.hostname,
               port: host.port,
               source: host.source ?? 'config',
-              state: host.connected ? 'connected' : 'idle',
+              state: stateOf(host),
               connected: host.connected === true,
               default: host.alias === defaultHost,
+              workspace: workspace?.host === host.alias,
+              ...(host.lastError ? { lastError: host.lastError } : {}),
             })),
           );
         }
         if (hosts.length === 0) return 'No hosts with an explicit HostName were found in ~/.ssh/config.';
         const lines = hosts.map((host) => {
-          const state = host.connected ? `connected${host.terminals ? `, ${host.terminals} terminal(s)` : ''}` : 'not connected';
+          const state = stateText(host);
           const key = host.identityFile ? `key ${host.identityFile}` : 'default keys';
           const marker = host.alias === defaultHost ? '*' : '';
           return `${marker}${host.alias}  ${host.user ?? '?'}@${host.hostname}:${host.port}  ${state}  (${key})`;
         });
-        return `${hosts.length} host(s):\n${lines.join('\n')}`;
+        const defaultLine = defaultHost
+          ? `default: ${defaultHost} (${workspace?.host === defaultHost ? 'session workspace machine' : 'PRESENCE_HOST default'})`
+          : null;
+        return `${hosts.length} host(s):\n${lines.join('\n')}${defaultLine ? `\n${defaultLine}` : ''}`;
       },
     }),
 
@@ -1023,28 +1362,49 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
     tool({
       name: 'presence_exec',
       description:
-        'Run a shell command on a remote machine and return its exit code, stdout and stderr. Inside a workspace the machine and working directory come from the session itself, so no host is needed. The connection persists between calls. Commands run with `set -o pipefail` by default, so `cmd | tail` reports cmd\'s real failure; pass pipefail:false to disable. For servers or long jobs use background:true instead of `&`: it returns a job id, takes an optional label, and can wait until a port is listening with waitForPort. format:\'json\' returns one text block of JSON ({cwd, command, exitCode, signal, durationMs, timedOut, stdout, stderr, stdoutTruncated, stderrTruncated}) with stdout/stderr clipped to 16 KiB each; saveStdout writes a successful foreground command\'s stdout to a remote file.\n\nDESTRUCTIVE COMMANDS (`rm -r/-f`, `git clean -fdx`, `find -delete`, `shred`, `truncate`, `dd of=`) are dry-run first: the tool shows every resolved target and refuses workspace roots, ancestors, home, `/` and `.git` metadata. Re-run with confirm:true to execute; format:\'json\' returns that dry run as {dryRun:true, requiresConfirm:true, targets, command, report}. Prefer presence_trash for recoverable deletes. Output is ANSI-stripped and middle-truncated by default.',
+        'Run a shell command on a remote machine and return its exit code, stdout and stderr. In a remote-workspace session the machine and working directory come from the session itself, so no host is needed; a local session must pass host (or configure PRESENCE_HOST). The connection persists between calls. Commands run with `set -o pipefail` by default, so `cmd | tail` reports cmd\'s real failure; pass pipefail:false to disable. The text report starts with `host: <alias>  remote cwd: <absolute>`; long output is shown as a head/tail excerpt that says how many characters were omitted and where the full stream was spilled. For servers or long jobs use background:true instead of `&`: it returns a job id, takes an optional label, and can wait until a port is listening with waitForPort.\n\nDESTRUCTIVE COMMANDS (`rm -r/-f`, `git clean -fdx`, `find -delete`, `shred`, `truncate`, `dd of=`) are dry-run first: the tool shows every resolved target and refuses workspace roots, ancestors, home, `/` and `.git` metadata. Re-run with confirm:true to execute the whole command, or confirm:"partial" to execute only the non-destructive segments (the result reports executedSegments/skippedSegments). Prefer presence_trash for recoverable deletes.',
       parameters: {
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         command: { type: 'string', required: true, description: 'Command line, interpreted by the remote shell.' },
         cwd: { type: 'string', description: 'Directory to run in, absolute or workspace-relative. Defaults to the workspace root, else the remote login directory.' },
-        timeoutMs: { type: 'number', description: 'Abort after this many milliseconds (the remote process tree is killed). Defaults to 120000. Ignored for background jobs, which are meant to outlive the call.' },
+        timeoutMs: {
+          type: 'number',
+          description:
+            'Abort after this many milliseconds (the remote process tree is terminated with SIGTERM, then SIGKILL after 5s, and the partial output is returned). Defaults to 300000 (5 minutes). Ignored for background jobs, which are meant to outlive the call; use presence_jobs {action:\'wait\'} instead.',
+        },
         background: { type: 'boolean', description: 'Start detached and return immediately with pid and a remote log file. Use for servers and long-running jobs.' },
         label: { type: 'string', description: 'For background: short label shown by presence_jobs. Defaults to the command.' },
         pipefail: { type: 'boolean', description: 'Set the remote shell\'s pipefail so a failing left side of a pipeline is reported. Defaults to true; pass false to disable.' },
+        tailLines: {
+          type: 'number',
+          description:
+            'Text report only: when the output is too long, keep the first 40% of the inline budget and append the last N lines (0-5000 gives exactly that many). Defaults to 0 (character-based head+tail clipping).',
+        },
+        progress: {
+          type: 'string',
+          enum: ['last', 'all', 'strip'],
+          description:
+            'Carriage-return normalization applied before clipping: "last" keeps only the text after each line\'s final CR (progress bars keep their final state), "all" turns every remaining CR into a line break, "strip" removes CRs. Defaults to "last".',
+        },
         confirm: {
-          type: 'boolean',
-          description: 'Required to actually run a command classified as destructive; without it the tool returns a dry-run report of the resolved targets instead.',
+          oneOf: [{ type: 'boolean' }, { type: 'string', enum: ['partial'] }],
+          description:
+            'Required to actually run a command classified as destructive: true runs the whole command, "partial" runs only the non-destructive segments and reports the skipped ones. Without confirm the tool returns a dry-run report of the resolved targets and the safe segments.',
         },
         maxOutput: {
           type: 'number',
-          description: 'Max characters of stdout/stderr shown inline. Defaults to 16384 (up to 262144); the full output is always written to a log file whose path is reported.',
+          description: 'Max characters of stdout/stderr shown inline. Defaults to 16384 (up to 262144); the full output is always written to a remote file whose path is reported.',
         },
         raw: { type: 'boolean', description: 'Keep ANSI escape sequences in the output. Defaults to false (stripped).' },
         format: {
           type: 'string',
           enum: ['text', 'json'],
-          description: 'Return one text block containing JSON: {cwd, command, exitCode, signal, durationMs, timedOut, stdout, stderr, stdoutTruncated, stderrTruncated}. Streams are clipped to 16 KiB each. For a destructive command without confirm:true the JSON is {dryRun:true, requiresConfirm:true, targets, command, report}. Defaults to text.',
+          description:
+            'Return one text block containing JSON: {cwd, command, exitCode, signal, durationMs, timedOut, stdout, stderr, stdoutTruncated, stderrTruncated, hints, tailLines} with stdout/stderr clipped to 16 KiB each; spill files add stdoutFile/stderrFile/stdoutFileBytes/stderrFileBytes (and stdoutFileError/stderrFileError when a spill write failed). For a destructive command without confirm the JSON is {dryRun:true, requiresConfirm:true, targets, command, report, safeSegments, destructiveSegments, partialAvailable}; confirm:"partial" returns {dryRun:false, partial:true, executedSegments, skippedSegments}. Defaults to text.',
         },
         saveStdout: {
           type: 'string',
@@ -1056,18 +1416,87 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
         },
       },
       async execute(args, exec) {
+        const commandText = args.command;
+        if (typeof commandText !== 'string' || commandText.trim() === '') {
+          throw missingArgument('presence_exec', 'command', ['command'], args, '{"command": "uname -a"}');
+        }
         const { host, workspace } = await pickScope(args, exec);
         const connection = await pool.connection(host);
-        const directory = args.cwd ? await remotePath(connection, workspace, args.cwd) : workspace?.path;
+        const cwdInput = pickArg(args, EXEC_CWD_ALIASES);
+        const directory = cwdInput !== undefined ? await remotePath(connection, workspace, cwdInput) : workspace?.path;
         const pipefail = args.pipefail !== false;
+        const progress = execProgress(args.progress);
+        const tailLines = execTailLines(args.tailLines);
+        const timeoutMs =
+          args.timeoutMs === undefined || args.timeoutMs === null || args.timeoutMs === ''
+            ? EXEC_DEFAULT_TIMEOUT_MS
+            : Number(args.timeoutMs) || 0;
+        // The report always names the machine and the directory the command
+        // really runs in: the workspace/cwd when one applies, else the remote
+        // login directory. "remote cwd" is explicit so it is never mistaken for
+        // a local path.
+        const effectiveCwd =
+          directory ??
+          (typeof connection.homePath === 'function' ? await connection.homePath().catch(() => null) : null);
+        const scopeLine = `host: ${host}  remote cwd: ${effectiveCwd ?? '(remote login directory)'}`;
+        const backgroundHint = backgroundCommandHint(commandText);
+        const hints = backgroundHint ? [backgroundHint] : [];
 
         // Destructive commands are dry-run first: show the resolved targets, and
         // refuse the cases where an empty variable or stray glob would delete a
-        // whole tree. Nothing runs until the caller repeats the call with confirm.
-        if (!args.confirm) {
+        // whole tree. Nothing runs until the caller confirms. `confirm:"partial"`
+        // runs only the segments the guard classified as non-destructive.
+        const confirm = args.confirm;
+        const partialRequested = confirm === 'partial';
+        const confirmed = Boolean(confirm) && !partialRequested;
+        let command = commandText;
+        let partialInfo = null;
+        if (partialRequested || confirmed) {
+          const guard = await guardDestructive({
+            connection,
+            command: commandText,
+            cwd: directory ?? null,
+            workspace,
+            host,
+            confirm: true,
+          });
+          if (partialRequested && guard) {
+            const split = guard.split ?? { safeSegments: [], destructiveSegments: [] };
+            const executedSegments = (Array.isArray(split.safeSegments) ? split.safeSegments : []).filter(
+              (segment) => typeof segment === 'string' && segment.trim() !== '',
+            );
+            const skippedSegments = (Array.isArray(split.destructiveSegments) ? split.destructiveSegments : []).map(
+              (entry) => (typeof entry === 'string' ? entry : entry?.segment ?? String(entry)),
+            );
+            if (executedSegments.length === 0) {
+              const report = [
+                'partial run: the command has no non-destructive segments to run, so nothing was executed.',
+                guard.report,
+              ].join('\n');
+              if (args.format === 'json') {
+                return jsonText({
+                  dryRun: false,
+                  partial: true,
+                  executedSegments: [],
+                  skippedSegments,
+                  requiresConfirm: true,
+                  targets: guard.targets ?? [],
+                  command: commandText,
+                  report,
+                });
+              }
+              return report;
+            }
+            partialInfo = { executedSegments, skippedSegments };
+            command = executedSegments.join('; ');
+          } else if (partialRequested) {
+            // A benign command has nothing to skip: "partial" runs it whole.
+            partialInfo = { executedSegments: [commandText], skippedSegments: [] };
+          }
+        } else if (!confirm) {
           const guard = await guardDestructive({
             connection,
-            command: args.command,
+            command: commandText,
             cwd: directory ?? null,
             workspace,
             host,
@@ -1075,27 +1504,32 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
           });
           if (guard) {
             // JSON callers get the guard report as data instead of having to
-            // parse the text report; `targets` mirrors the report's target block.
+            // parse the text report; `targets` mirrors the report's target block
+            // and `safeSegments`/`destructiveSegments` back confirm:"partial".
             if (args.format === 'json') {
-              return jsonText({
+              const split = guard.split ?? null;
+              const payload = {
                 dryRun: true,
                 requiresConfirm: true,
                 targets: guard.targets ?? [],
-                command: args.command,
+                command: commandText,
                 report: guard.report,
-              });
+              };
+              if (split) {
+                payload.safeSegments = Array.isArray(split.safeSegments) ? split.safeSegments : [];
+                payload.destructiveSegments = Array.isArray(split.destructiveSegments)
+                  ? split.destructiveSegments.map((entry) => ({
+                      segment: entry?.segment ?? String(entry),
+                      kind: entry?.kind ?? null,
+                      targets: entry?.targets ?? [],
+                    }))
+                  : [];
+                payload.partialAvailable = payload.safeSegments.length > 0;
+              }
+              return jsonText(payload);
             }
             return guard.report;
           }
-        } else {
-          await guardDestructive({
-            connection,
-            command: args.command,
-            cwd: directory ?? null,
-            workspace,
-            host,
-            confirm: true,
-          });
         }
 
         if (args.background) {
@@ -1105,7 +1539,7 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
               throw new Error(`waitForPort must be a TCP port number, got ${args.waitForPort}`);
             }
           }
-          const body = `${pipefail ? pipefailPrelude() : ''}${args.command}`;
+          const body = `${pipefail ? pipefailPrelude() : ''}${command}`;
           let job;
           try {
             job = await pool.startJob(host, {
@@ -1124,6 +1558,7 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
             const size =
               job.logSize === undefined || job.logSize === null ? null : ` (${formatBytes(job.logSize)})`;
             return [
+              scopeLine,
               `background job ${job.id ?? '(unknown)'} exited immediately on ${host} (it did not stay running)`,
               `exit: ${job.exitCode ?? 'unknown'}`,
               job.logPath ? `log: ${job.logPath}${size ?? ''}` : null,
@@ -1134,6 +1569,7 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
           }
 
           const parts = [
+            scopeLine,
             `started in background on ${host}`,
             `job: ${job.id}`,
             `pid: ${job.pid}`,
@@ -1144,7 +1580,7 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
 
           if (args.timeoutMs !== undefined && args.timeoutMs !== null) {
             parts.push(
-              'note: timeoutMs does not apply to background jobs 鈥?they are meant to outlive the call; ' +
+              'note: timeoutMs does not apply to background jobs — they are meant to outlive the call; ' +
                 `use presence_jobs {action:'wait', jobId:'${job.id}', timeoutMs} to wait for it`,
             );
           }
@@ -1154,7 +1590,7 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
             parts.push(
               outcome.ready
                 ? `port ${args.waitForPort} is listening on ${host} (after ${outcome.waitedMs}ms)`
-                : `port ${args.waitForPort} is NOT listening on ${host} after ${outcome.waitedMs}ms 鈥?check the log: tail -n 50 ${job.logPath}`,
+                : `port ${args.waitForPort} is NOT listening on ${host} after ${outcome.waitedMs}ms — check the log: tail -n 50 ${job.logPath}`,
             );
           }
           if (args.saveStdout) {
@@ -1164,12 +1600,12 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
         }
 
         const saveTarget = args.saveStdout ? await remotePath(connection, workspace, args.saveStdout) : null;
-        let command = args.command;
-        if (directory) command = `cd ${shq(directory)} && ${command}`;
-        if (pipefail) command = `${pipefailPrelude()}${command}`;
+        let shellCommand = command;
+        if (directory) shellCommand = `cd ${shq(directory)} && ${shellCommand}`;
+        if (pipefail) shellCommand = `${pipefailPrelude()}${shellCommand}`;
         let result;
         try {
-          result = await connection.exec(command, { timeoutMs: args.timeoutMs ?? 120_000 });
+          result = await connection.exec(shellCommand, { timeoutMs, progress });
         } catch (error) {
           throw new Error(withSandboxNote(error?.message ?? String(error)));
         }
@@ -1197,8 +1633,8 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
           const stdoutRaw = plain(result.stdout);
           const stderrRaw = plain(result.stderr);
           const payload = {
-            cwd: directory ?? null,
-            command: args.command,
+            cwd: effectiveCwd ?? null,
+            command: commandText,
             exitCode: result.code ?? null,
             signal: result.signal ?? null,
             durationMs: result.durationMs ?? null,
@@ -1207,36 +1643,75 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
             stderr: clip(stderrRaw, EXEC_OUTPUT_CAP),
             stdoutTruncated: result.stdoutTruncated === true || stdoutRaw.length > EXEC_OUTPUT_CAP,
             stderrTruncated: result.stderrTruncated === true || stderrRaw.length > EXEC_OUTPUT_CAP,
+            hints,
+            tailLines,
           };
+          if (partialInfo) {
+            payload.dryRun = false;
+            payload.partial = true;
+            payload.executedSegments = partialInfo.executedSegments;
+            payload.skippedSegments = partialInfo.skippedSegments;
+          }
+          // Timeout/SIGPIPE facts from the connection contract; absent fields
+          // stay absent so older connections keep the same JSON shape.
+          if (result.killed !== undefined) payload.killed = result.killed === true;
+          if (Array.isArray(result.killSequence)) payload.killSequence = result.killSequence;
+          if (result.sigpipe === true) payload.sigpipe = true;
+          for (const stream of ['stdout', 'stderr']) {
+            const file = stream === 'stdout' ? result.stdoutFile : result.stderrFile;
+            const fileBytes = stream === 'stdout' ? result.stdoutFileBytes : result.stderrFileBytes;
+            const fileError = stream === 'stdout' ? result.stdoutFileError : result.stderrFileError;
+            const truncated = stream === 'stdout' ? result.stdoutTruncated === true : result.stderrTruncated === true;
+            if (file) {
+              payload[`${stream}File`] = file;
+              payload[`${stream}FileBytes`] = Number.isFinite(Number(fileBytes)) ? Number(fileBytes) : null;
+            } else if (truncated) {
+              // The capture exceeded the cap but the spill write failed: keep an
+              // explicit null plus the reason instead of dropping the fact.
+              payload[`${stream}File`] = null;
+              if (fileError) payload[`${stream}FileError`] = fileError;
+            }
+          }
           if (savedStdout) payload.savedStdout = savedStdout;
           if (saveError) payload.savedStdoutError = saveError;
           if (saveTarget && !savedStdout && !saveError) {
             payload.savedStdoutSkipped = { path: saveTarget, reason: `exit ${result.code ?? '?'} is not 0` };
           }
-          return JSON.stringify(payload, null, 2);
+          return jsonText(payload, EXEC_JSON_CAP);
         }
 
-        const parts = [`exit: ${result.code}  (${result.durationMs}ms)`];
-        if (result.timedOut) parts.push('timed out 鈥?the remote process tree was terminated');
         const inlineCap = Math.max(1000, Math.min(Number(args.maxOutput) || EXEC_OUTPUT_CAP, 256 * 1024));
-        const note = (stream) => {
-          const captured = plain(stream === 'stdout' ? result.stdout : result.stderr);
-          const truncated = stream === 'stdout' ? result.stdoutTruncated : result.stderrTruncated;
-          const file = stream === 'stdout' ? result.stdoutFile : result.stderrFile;
-          if (!truncated && captured.length <= inlineCap) return null;
-          const where = file ? `full ${stream}: ${file} on ${host}` : `no ${stream} file could be saved`;
-          return `(${truncated ? `${stream} exceeded the 256 KiB capture cap; ` : ''}showing first/last ${inlineCap} characters 鈥?${where})`;
-        };
-        if (result.stdout) {
-          parts.push(`--- stdout ---\n${clipMiddle(plain(result.stdout), inlineCap)}`);
-          const hint = note('stdout');
-          if (hint) parts.push(hint);
+        const parts = [scopeLine];
+        if (hints.length > 0) parts.push(`hint: ${hints[0]}`);
+        if (partialInfo) {
+          parts.push(
+            `partial: ran ${partialInfo.executedSegments.length} safe segment(s); ` +
+              `skipped ${partialInfo.skippedSegments.length} destructive segment(s)`,
+          );
+          for (const segment of partialInfo.skippedSegments) parts.push(`skipped: ${segment}`);
+          parts.push(`ran: ${partialInfo.executedSegments.join('; ')}`);
         }
-        if (result.stderr) {
-          parts.push(`--- stderr ---\n${clipMiddle(plain(result.stderr), inlineCap)}`);
-          const hint = note('stderr');
-          if (hint) parts.push(hint);
+        if (result.sigpipe === true) {
+          parts.push(`exit ${result.code ?? 141} (SIGPIPE — downstream closed early; usually harmless)`);
+        } else {
+          parts.push(`exit: ${result.code}  (${result.durationMs}ms)`);
         }
+        if (result.timedOut === true) {
+          parts.push(
+            `timed out after ${timeoutMs}ms — remote process tree terminated (SIGTERM, then SIGKILL after 5s); partial output below`,
+          );
+          const spillFiles = [result.stdoutFile, result.stderrFile].filter(Boolean);
+          if (spillFiles.length > 0) parts.push(`partial output saved to: ${spillFiles.join(', ')}`);
+          if (longLivedCommand(commandText)) {
+            parts.push(
+              'background children started by this command may still be running — use background:true / presence_terminal to track them',
+            );
+          }
+        }
+        const stdoutSection = execStreamSection('stdout', result.stdout, result, { inlineCap, tailLines, plain });
+        if (stdoutSection) parts.push(stdoutSection);
+        const stderrSection = execStreamSection('stderr', result.stderr, result, { inlineCap, tailLines, plain });
+        if (stderrSection) parts.push(stderrSection);
         if (result.code !== 0 && isSandboxMessage(result.stderr)) {
           parts.push(
             'note: ctx.fs does not write remote /tmp, so an escalation here cannot help; ' +
@@ -1245,9 +1720,9 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
         }
         // Nudge the model away from shell one-liners for edits: they skip the
         // atomic write, the ambiguity check and the version guard.
-        if (EDIT_SHELL.test(args.command)) {
+        if (EDIT_SHELL.test(commandText)) {
           parts.push(
-            'note: prefer presence_edit (or the built-in `edit` tool) for remote file changes 鈥?' +
+            'note: prefer presence_edit (or the built-in `edit` tool) for remote file changes — ' +
               '`sed -i`/`perl -pi`/`python -c` rewrites bypass the atomic write and the ambiguity check.',
           );
         }
@@ -1262,12 +1737,227 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
       },
     }),
 
+    tool({
+      name: 'presence_wait',
+      description:
+        'Wait for one remote condition instead of a sleep+tail loop. Exactly one condition: file {path, exists?=true, minBytes?, mtimeAfter?}, grep {path, pattern, count?=1}, process {pid?|pattern, alive?=true}, port {port, state:"open"|"closed"}, or job {jobId}. Polls every pollMs (default 1000) until met or timeoutMs (default 120000, max 3600000) expires. A timeout is data — the tool returns met:false and never throws. Returns {met, timedOut, elapsedMs, observed, condition, polls}; format:"json" returns the same object as JSON.',
+      parameters: {
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST). Ignored for a job condition, which finds the host from the job itself.',
+        },
+        timeoutMs: {
+          type: 'number',
+          description: 'How long to wait. Defaults to 120000 ms; capped at 3600000 ms (1 hour).',
+        },
+        pollMs: {
+          type: 'number',
+          description: 'Milliseconds between probes. Defaults to 1000 (min 50, max 60000).',
+        },
+        intervalMs: { type: 'number', description: 'Alias for pollMs.' },
+        file: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            path: { type: 'string', required: true, description: 'Remote path to watch.' },
+            exists: { type: 'boolean', description: 'Wait until the path exists (default true) or disappears (false).' },
+            minBytes: { type: 'number', description: 'Wait until a regular file is at least this many bytes.' },
+            mtimeAfter: {
+              oneOf: [{ type: 'number' }, { type: 'string' }],
+              description: 'Wait until the file mtime is newer than this epoch ms, epoch seconds or ISO timestamp.',
+            },
+          },
+          description: 'Condition: {path, exists?: true, minBytes?, mtimeAfter?} — mtimeAfter accepts epoch ms, epoch seconds or an ISO timestamp.',
+        },
+        grep: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            path: { type: 'string', required: true, description: 'Remote file to search.' },
+            pattern: { type: 'string', required: true, description: 'Extended regular expression to look for.' },
+            count: { type: 'number', description: 'Wait until at least this many lines match. Defaults to 1.' },
+          },
+          description: 'Condition: {path, pattern, count?: 1} — met when at least `count` lines match the extended regex.',
+        },
+        process: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            pid: { type: 'number', description: 'Process id to watch.' },
+            pattern: { type: 'string', description: 'pgrep -f pattern; exactly one of pid or pattern.' },
+            alive: { type: 'boolean', description: 'Wait until the process exists (default true) or is gone (false).' },
+          },
+          description: 'Condition: {pid?|pattern, alive?: true} — exactly one of pid or pattern (pgrep -f).',
+        },
+        port: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            port: { type: 'number', required: true, description: 'TCP port on the remote loopback.' },
+            state: { type: 'string', enum: ['open', 'closed'], description: 'Wait for the port to be open (default) or closed.' },
+          },
+          description: 'Condition: {port, state?: "open"|"closed"} — TCP probe on the remote loopback.',
+        },
+        job: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            jobId: { type: 'string', required: true, description: 'Background job id from presence_exec {background:true} or presence_jobs.' },
+          },
+          description: 'Condition: {jobId} — met when the background job has exited (state "exited").',
+        },
+        format: {
+          type: 'string',
+          enum: ['text', 'json'],
+          description: 'Return one text block containing JSON: {met, timedOut, elapsedMs, observed, condition, polls}. Defaults to text.',
+        },
+      },
+      async execute(args, exec) {
+        const kinds = ['file', 'grep', 'process', 'port', 'job'].filter(
+          (kind) => args[kind] !== undefined && args[kind] !== null,
+        );
+        if (kinds.length === 0) {
+          throw new Error(
+            'presence_wait needs exactly one condition: file, grep, process, port or job — ' +
+              'e.g. {"file": {"path": "/srv/app/done.marker"}} or {"job": {"jobId": "j_123"}}',
+          );
+        }
+        if (kinds.length > 1) {
+          throw new Error(
+            `presence_wait takes exactly one condition, got ${kinds.join(', ')}; make one call per condition ` +
+              '(or run them in sequence)',
+          );
+        }
+        const kind = kinds[0];
+        const spec = args[kind];
+        if (typeof spec !== 'object' || Array.isArray(spec)) {
+          throw new Error(`presence_wait.${kind} must be an object, e.g. ${WAIT_EXAMPLES[kind]}`);
+        }
+        const timeoutMs = clampedNumber(args.timeoutMs, WAIT_DEFAULT_TIMEOUT_MS, 1, WAIT_MAX_TIMEOUT_MS);
+        const pollMs = clampedNumber(
+          pickArg(args, ['pollMs', 'poll_ms', 'intervalMs', 'interval_ms']),
+          WAIT_DEFAULT_POLL_MS,
+          WAIT_MIN_POLL_MS,
+          WAIT_MAX_POLL_MS,
+        );
+
+        // A job condition is host-independent (the registry knows where it
+        // ran), so it never opens a connection; everything else needs one.
+        let connection = null;
+        let condition;
+        if (kind === 'job') {
+          if (typeof spec.jobId !== 'string' || spec.jobId.trim() === '') {
+            throw new Error(`presence_wait.job needs a jobId, e.g. ${WAIT_EXAMPLES.job}`);
+          }
+          condition = { kind: 'job', jobId: spec.jobId.trim() };
+        } else {
+          const { host, workspace } = await pickScope(args, exec);
+          connection = await pool.connection(host);
+          if (kind === 'file' || kind === 'grep') {
+            const rawPath = pickArg(spec, PATH_ALIASES);
+            if (rawPath === undefined || rawPath === '') {
+              throw new Error(`presence_wait.${kind} needs a path, e.g. ${WAIT_EXAMPLES[kind]}`);
+            }
+            const path = await remotePath(connection, workspace, rawPath);
+            if (kind === 'file') {
+              const minBytes =
+                spec.minBytes === undefined || spec.minBytes === null ? null : Number(spec.minBytes);
+              if (minBytes !== null && (!Number.isFinite(minBytes) || minBytes < 0)) {
+                throw new Error('presence_wait.file.minBytes must be a non-negative number');
+              }
+              condition = {
+                kind: 'file',
+                path,
+                exists: spec.exists !== false,
+                ...(minBytes !== null ? { minBytes } : {}),
+                ...(spec.mtimeAfter !== undefined && spec.mtimeAfter !== null && spec.mtimeAfter !== ''
+                  ? { mtimeAfter: spec.mtimeAfter }
+                  : {}),
+              };
+            } else {
+              if (typeof spec.pattern !== 'string' || spec.pattern === '') {
+                throw new Error(`presence_wait.grep needs a pattern, e.g. ${WAIT_EXAMPLES.grep}`);
+              }
+              condition = {
+                kind: 'grep',
+                path,
+                pattern: spec.pattern,
+                count: clampedNumber(spec.count, 1, 1, 1_000_000),
+              };
+            }
+          } else if (kind === 'process') {
+            const hasPid = spec.pid !== undefined && spec.pid !== null && spec.pid !== '';
+            const hasPattern = typeof spec.pattern === 'string' && spec.pattern !== '';
+            if (hasPid === hasPattern) {
+              throw new Error(`presence_wait.process needs exactly one of pid or pattern, e.g. ${WAIT_EXAMPLES.process}`);
+            }
+            if (hasPid) {
+              const pid = Number(spec.pid);
+              if (!Number.isInteger(pid) || pid <= 0) {
+                throw new Error(`presence_wait.process.pid must be a positive integer, got ${spec.pid}`);
+              }
+              condition = { kind: 'process', pid, alive: spec.alive !== false };
+            } else {
+              condition = { kind: 'process', pattern: spec.pattern, alive: spec.alive !== false };
+            }
+          } else {
+            const port = Number(spec.port);
+            if (!Number.isInteger(port) || port < 1 || port > 65535) {
+              throw new Error(`presence_wait.port.port must be a TCP port number, got ${spec.port}`);
+            }
+            condition = { kind: 'port', port, state: spec.state === 'closed' ? 'closed' : 'open' };
+          }
+        }
+
+        // waitUntil never throws on timeout: it reports met:false/timedOut:true.
+        const result = await waitUntil({ pool, connection, condition, timeoutMs, pollMs, signal: exec?.signal });
+        const payload = {
+          met: result.met === true,
+          timedOut: result.timedOut === true,
+          elapsedMs: Number(result.elapsedMs) || 0,
+          observed: result.observed ?? null,
+          condition,
+          polls: result.polls ?? null,
+        };
+        if (result.aborted === true) payload.aborted = true;
+        if (args.format === 'json') return jsonText(payload);
+        if (payload.aborted) {
+          return clip(
+            [
+              `wait: aborted after ${payload.elapsedMs}ms (met:${payload.met})`,
+              `condition: ${JSON.stringify(condition)}`,
+              `observed: ${JSON.stringify(payload.observed)}`,
+            ].join('\n'),
+          );
+        }
+        const polls = payload.polls === null ? '' : `, ${payload.polls} poll(s)`;
+        const headline = payload.met
+          ? `wait: met after ${payload.elapsedMs}ms${polls}`
+          : `wait: timed out after ${payload.elapsedMs}ms${polls} — condition not met (met:false)`;
+        return clip(
+          [
+            headline,
+            `condition: ${JSON.stringify(condition)}`,
+            `observed: ${JSON.stringify(payload.observed)}`,
+            payload.met ? '' : 'hint: the last observed value is above; follow it with presence_tail, presence_jobs or presence_port_probe.',
+          ]
+            .filter(Boolean)
+            .join('\n'),
+        );
+      },
+    }),
+
     tool({
       name: 'presence_read',
       description:
         'Read a text file on a remote machine. Inside a workspace, relative paths resolve against the workspace root and the machine comes from the workspace. Returns line-numbered content with a line-count footer, like reading a local file. Use offset/limit for large files. Pass `raw:true` for the exact file content with no path header, no line numbers and no footer; pass `numbered:false` for unnumbered content that keeps the path header.',
       parameters: {
-        host: { type: 'string', description: 'ssh alias. Defaults to the active workspace\'s machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         path: { type: 'string', required: true, description: 'Absolute path, ~/relative, or workspace-relative.' },
         offset: { type: 'number', description: '1-based first line to return. Defaults to 1.' },
         limit: { type: 'number', description: 'Maximum lines to return. Defaults to 2000.' },
@@ -1281,16 +1971,17 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
         },
       },
       async execute(args, exec) {
+        const pathInput = requirePath(args, 'presence_read', '{"path": "/srv/app/a.txt"}');
         const { host, workspace } = await pickScope(args, exec);
         const connection = await pool.connection(host);
-        const target = await remotePath(connection, workspace, args.path);
+        const target = await remotePath(connection, workspace, pathInput);
         const view = await readFileWindow(connection, target, { offset: args.offset, limit: args.limit });
         const raw = args.raw === true;
         const numbered = !raw && args.numbered !== false;
         const body = numbered
           ? view.lines.map((line, index) => `${view.offset + index}: ${line}`).join('\n')
           : view.rawWindow;
-        await markObserved(exec, args.path);
+        await markObserved(exec, pathInput);
         if (raw) return body;
         const footer = numbered ? `\n\n${readFooter(view)}` : '';
         return `<path>${target}</path>\n${body}${footer}`;
@@ -1308,15 +1999,34 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
           required: true,
           description: 'Remote paths (absolute, ~/..., presence://host/path, or workspace-relative). 1-50 entries.',
         },
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         raw: { type: 'boolean', description: 'Return verbatim content without line numbers. Defaults to false (numbered lines).' },
         limit: { type: 'number', description: 'Maximum lines per file. Defaults to 2000.' },
       },
       async execute(args, exec) {
+        const listed = Array.isArray(args.paths) ? args.paths : [];
+        const singlePath = listed.length === 0 ? pickArg(args, PATH_ALIASES) : undefined;
+        const inputs =
+          listed.length > 0
+            ? listed
+            : singlePath !== undefined && singlePath !== ''
+              ? [singlePath]
+              : [];
+        if (inputs.length === 0) {
+          throw missingArgument(
+            'presence_read_many',
+            'paths',
+            ['paths', 'path', 'file_path'],
+            args,
+            '{"paths": ["/srv/app/a.txt", "/srv/app/b.txt"]}',
+          );
+        }
         const { host, workspace } = await pickScope(args, exec);
         const connection = await pool.connection(host);
-        const inputs = Array.isArray(args.paths) ? args.paths : [];
-        if (inputs.length === 0) throw new Error('paths is required: pass 1-50 remote paths');
         if (inputs.length > READ_MANY_MAX_FILES) {
           throw new Error(`presence_read_many reads at most ${READ_MANY_MAX_FILES} files per call, got ${inputs.length}`);
         }
@@ -1347,31 +2057,104 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
     tool({
       name: 'presence_write',
       description:
-        'Create or fully replace a file on a remote machine. Missing parent directories are created. Inside a workspace, relative paths resolve against the workspace root. The write is atomic (temp file + rename), so a reader never sees a half-written file. An existing file keeps its mode (e.g. 0755 stays executable); pass `mode` to set one explicitly. After writing, the remote file is stat-ed and the result reports its actual size, octal mode and full sha256. Pass `ifMatchSha256` (the hash the file must currently have) to refuse the overwrite when the remote content changed since you read it.',
+        'Create or replace a file on a remote machine. Missing parent directories are created; in a remote-workspace session relative paths resolve against the workspace root. mode:"overwrite" (default) writes atomically (temp file + rename), so a reader never sees a half-written file, and an existing file keeps its mode (e.g. 0755 stays executable). mode:"append" appends content at the end of the file (creating it when missing) and reports bytesAppended, total size and the resulting sha256. An octal mode string such as "755" (or "0644") still sets the file permissions for an overwrite. After writing, the remote file is stat-ed and the result reports its actual size, octal mode and full sha256. Pass ifMatchSha256 (the hash the file must currently have) to refuse an overwrite when the remote content changed since you read it; it is overwrite-only.',
       parameters: {
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         path: { type: 'string', required: true, description: 'Absolute path, ~/relative, or workspace-relative.' },
-        content: { type: 'string', required: true, description: 'Complete new file content.' },
+        content: { type: 'string', required: true, description: 'Content to write (overwrite) or append.' },
         mode: {
-          type: 'string',
-          description: 'Octal file mode to set, e.g. "755" or "644". Defaults to the existing file\'s mode, or 644 for a new file.',
+          oneOf: [{ type: 'string' }, { type: 'number' }],
+          description:
+            'Write mode "overwrite" (default) or "append"; or an octal file mode such as "755"/"0644" for an overwrite ("append" + an octal mode cannot be combined).',
         },
         ifMatchSha256: {
           type: 'string',
-          description: 'Optimistic lock: only write when the file currently has this sha256. A mismatch (or a missing/unreadable file) is an error that reports both hashes, and nothing is written.',
+          description:
+            'Overwrite only: optimistic lock; only write when the file currently has this sha256. A mismatch (or a missing/unreadable file) is an error that reports both hashes, and nothing is written.',
         },
         format: {
           type: 'string',
           enum: ['text', 'json'],
-          description: 'Return one text block containing JSON: {path, sizeBytes, mode, sha256}. `mode` is the actual octal string such as "0644". Defaults to text.',
+          description:
+            'Return one text block containing JSON: {path, mode, sizeBytes, sha256, writeMode}. `mode` is the actual octal string such as "0644". An append adds bytesAppended and keeps sizeBytes as the resulting total size. Defaults to text.',
         },
       },
       async execute(args, exec) {
         ensureWritable();
+        const example = '{"path": "/srv/app/a.txt", "content": "hi"}';
+        const pathInput = requirePath(args, 'presence_write', example);
+        if (args.content === undefined || args.content === null) {
+          throw missingArgument('presence_write', 'content', ['content'], args, example);
+        }
+        const writeMode = writeModeOf(args.mode) ?? 'overwrite';
+        // 'append'/'overwrite' is a write mode; anything else stays an octal mode.
+        const octalInput = writeModeOf(args.mode) ? undefined : args.mode;
+        const expected = typeof args.ifMatchSha256 === 'string' ? args.ifMatchSha256.trim().toLowerCase() : '';
+        if (writeMode === 'append' && expected) {
+          throw new Error(
+            'ifMatchSha256 is only valid for an overwrite; drop it (or read the file and hash-check it yourself) before appending',
+          );
+        }
         const { host, workspace } = await pickScope(args, exec);
         const connection = await pool.connection(host);
-        const target = await remotePath(connection, workspace, args.path);
-        const expected = typeof args.ifMatchSha256 === 'string' ? args.ifMatchSha256.trim().toLowerCase() : '';
+        const target = await remotePath(connection, workspace, pathInput);
+        const targetParent = target.includes('/') ? target.slice(0, target.lastIndexOf('/')) || '/' : '';
+        const ensureParent = async () => {
+          if (!targetParent) return;
+          const made = await connection.exec(`mkdir -p ${shq(targetParent)}`, { timeoutMs: 30_000 });
+          if (made.code !== 0) {
+            throw new Error(`cannot create parent directory ${targetParent}: ${made.stderr.trim()}`);
+          }
+        };
+        const payload = Buffer.from(args.content ?? '', 'utf8');
+        const digest = createHash('sha256').update(payload).digest('hex');
+
+        if (writeMode === 'append') {
+          const before = await connection.stat(target);
+          if (before.exists && before.isDir) throw new Error(`${target} is a directory on ${host}; append needs a file`);
+          await ensureParent();
+          // Stage the appended bytes with the same atomic upload the overwrite
+          // path uses, then append them with one remote `cat`: the SSH command
+          // only carries paths, so a large payload never becomes a shell string
+          // and the existing file is never rewritten or re-chmod-ed.
+          const staging = `${targetParent === '/' ? '' : targetParent}/.presence-append-${stagingSuffix()}`;
+          try {
+            await connection.writeText(staging, payload);
+            const appended = await connection.exec(`cat -- ${shq(staging)} >> ${shq(target)}`, {
+              timeoutMs: 120_000,
+            });
+            if (appended.code !== 0) {
+              const reason = String(appended.stderr ?? '').trim() || `exit ${appended.code}`;
+              throw new Error(`append to ${target} on ${host} failed: ${reason}`);
+            }
+          } finally {
+            await connection.exec(`rm -f -- ${shq(staging)}`, { timeoutMs: 15_000 }).catch(() => {});
+          }
+          const info = await connection.stat(target);
+          const sizeBytes = info.exists ? info.size : (before.exists ? before.size : 0) + payload.length;
+          const sha256 = await remoteFileSha256(connection, target);
+          const mode = modeLabel(info.exists ? info.mode : null);
+          await markObserved(exec, pathInput);
+          if (args.format === 'json') {
+            return jsonText({
+              path: target,
+              writeMode: 'append',
+              bytesAppended: payload.length,
+              sizeBytes,
+              mode,
+              sha256,
+            });
+          }
+          return (
+            `appended ${payload.length} bytes to ${target} on ${host} ` +
+            `(total ${sizeBytes} bytes, mode ${mode ?? 'unknown'}, sha256 ${sha256 ?? 'unknown'})`
+          );
+        }
+
         if (expected) {
           const current = await remoteFileSha256(connection, target);
           if (!current) {
@@ -1387,21 +2170,15 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
             );
           }
         }
-        const parent = target.includes('/') ? target.slice(0, target.lastIndexOf('/')) : '';
-        if (parent) {
-          const made = await connection.exec(`mkdir -p ${shq(parent)}`, { timeoutMs: 30_000 });
-          if (made.code !== 0) throw new Error(`cannot create parent directory ${parent}: ${made.stderr.trim()}`);
-        }
-        const payload = Buffer.from(args.content ?? '', 'utf8');
-        const digest = createHash('sha256').update(payload).digest('hex');
-        const result = await connection.writeText(target, payload, { mode: parseMode(args.mode) });
+        await ensureParent();
+        const result = await connection.writeText(target, payload, { mode: parseMode(octalInput) });
         const info = await connection.stat(target);
         const sizeBytes = info.exists ? info.size : result.bytes;
         const mode = info.exists ? info.mode : result.mode;
         const octal = modeLabel(mode);
-        await markObserved(exec, args.path);
+        await markObserved(exec, pathInput);
         if (args.format === 'json') {
-          return jsonText({ path: target, sizeBytes, mode: octal, sha256: digest });
+          return jsonText({ path: target, writeMode: 'overwrite', sizeBytes, mode: octal, sha256: digest });
         }
         return `wrote ${sizeBytes} bytes to ${target} on ${host} mode ${octal ?? 'unknown'} sha256 ${digest}`;
       },
@@ -1410,125 +2187,371 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
     tool({
       name: 'presence_export',
       description:
-        'Copy a remote file to a real local file so desktop tools can open it. The workspace path is a virtual mount: Explorer, Office, Python and the `present` tool cannot see remote files directly. Export first, then present or open the returned local path. Files are written to the local export folder (content-addressed, deduplicated); `to` may only point inside that folder or the local workspace. Limit: 64 MiB.',
+        'Copy one or more remote files to real local files so desktop tools can open them. The workspace path is a virtual mount: Explorer, Office, Python and the `present` tool cannot see remote files directly. Export first, then present or open the returned local path. Single: `path` (or file_path) plus optional `to`. Batch: `paths` (1-50) and/or `glob` (remote-side, relative to the workspace root); every match is exported into the local export folder. The default local name is the remote basename; a name that already exists gets -<sha8> before the extension, so nothing is silently overwritten. format:\'json\' returns {files:[{remotePath, localPath, bytes, sha256}], exported, failed, errors}. Limit: 64 MiB per file.',
       parameters: {
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
-        path: { type: 'string', required: true, description: 'Remote file: absolute, workspace-relative, presence URL, or mount path.' },
-        to: { type: 'string', description: 'Optional local destination inside the export folder (defaults to a content-addressed name).' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
+        path: { type: 'string', description: 'Single remote file: absolute, workspace-relative, presence URL, or mount path.' },
+        paths: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Batch: 1-50 remote files (same spellings as path). Mutually exclusive with path.',
+        },
+        glob: {
+          type: 'string',
+          description:
+            'Batch: remote glob relative to the workspace root (or absolute with its own root), e.g. "out/*.png" or "/srv/app/logs/*.log". May be combined with paths.',
+        },
+        to: {
+          type: 'string',
+          description:
+            'Single path only: explicit local destination inside the export folder (or the local workspace). Defaults to the export folder + the remote basename.',
+        },
+        format: {
+          type: 'string',
+          enum: ['text', 'json'],
+          description:
+            'Return one text block containing JSON: {files:[{remotePath, localPath, bytes, sha256}], exported, failed, errors}. Defaults to text.',
+        },
       },
       async execute(args, exec) {
+        const single = pickArg(args, PATH_ALIASES);
+        const singlePath = typeof single === 'string' && single.trim() !== '' ? single.trim() : null;
+        const listed = Array.isArray(args.paths) ? args.paths : [];
+        const globInput = typeof args.glob === 'string' && args.glob.trim() !== '' ? args.glob.trim() : null;
+        if (!singlePath && listed.length === 0 && !globInput) {
+          throw missingArgument(
+            'presence_export',
+            'path',
+            ['path', 'file_path', 'paths', 'glob'],
+            args,
+            '{"paths": ["/srv/app/a.txt", "/srv/app/b.txt"]}',
+          );
+        }
+        if (singlePath && listed.length > 0) throw new Error('pass either path or paths, not both');
+        if (singlePath && globInput) throw new Error('pass either path or glob, not both');
+        if (!singlePath && args.to !== undefined && args.to !== null) {
+          throw new Error('to is only valid with a single path; a batch always lands in the export folder');
+        }
         const { host, workspace } = await pickScope(args, exec);
         const connection = await pool.connection(host);
-        const target = await remotePath(connection, workspace, args.path);
-        const info = await connection.stat(target);
-        if (!info.exists) throw new Error(`${target} does not exist on ${host}`);
-        if (info.isDir) throw new Error(`${target} is a directory; export files one by one, or use presence_exec with tar/scp`);
-        if (info.size > EXPORT_CAP) {
-          throw new Error(`${target} is ${info.size} bytes; export is capped at ${EXPORT_CAP} bytes 鈥?use presence_exec with scp/rsync for larger files`);
-        }
-        const { buffer } = await connection.readBytes(target, { offset: 0, length: info.size });
-        const name = target.split('/').filter(Boolean).pop() ?? 'export.bin';
         const folder = exportDirectory();
         mkdirSync(folder, { recursive: true });
-        const checksum = createHash('sha256').update(buffer).digest('hex');
-        const destination = args.to ?? joinPath(folder, `${checksum.slice(0, 12)}-${name}`);
-        const absolute = resolvePath(destination);
-
         // Writes are confined to the export folder (or the local workspace, for
         // local sessions): an agent must not be able to drop files anywhere.
         const allowedRoots = [resolvePath(folder)];
         if (workspace && !parseMountPath(workspace.path)) allowedRoots.push(resolvePath(workspace.path));
-        const contained = allowedRoots.some((root) => absolute === root || absolute.startsWith(`${root}${sep}`));
-        if (!contained) {
-          throw new Error(`refusing to write "${destination}": export targets are limited to ${folder}`);
+
+        const targets = [];
+        const addTarget = (value) => {
+          if (!targets.includes(value)) targets.push(value);
+        };
+        if (singlePath) addTarget(await remotePath(connection, workspace, singlePath));
+        if (listed.length > 0) {
+          for (const input of transferInputs(args, 'presence_export')) {
+            addTarget(await remotePath(connection, workspace, input));
+          }
+        }
+        if (globInput) {
+          // The same remote-glob semantics as presence_glob: an absolute
+          // pattern carries its own root, a relative one resolves against the
+          // workspace (or the login directory).
+          const absolutePattern = splitGlobPattern(globInput);
+          const pattern = absolutePattern ? absolutePattern.pattern : globInput;
+          const base = absolutePattern
+            ? absolutePattern.root
+            : workspace?.path ?? (await connection.homePath());
+          const baseInfo = await connection.stat(base);
+          if (!baseInfo.exists) throw new Error(`${base} does not exist on ${host}`);
+          if (!baseInfo.isDir) throw new Error(`${base} on ${host} is not a directory`);
+          const detailed = await remoteGlobDetailed(connection, {
+            root: base,
+            pattern,
+            limit: TRANSFER_MAX_FILES + 1,
+          });
+          const prefix = base.replace(/\/+$/, '');
+          for (const entry of detailed.entries) addTarget(`${prefix}/${entry.path}`);
+        }
+        if (targets.length === 0) throw new Error(`no files matched ${globInput ?? ''} on ${host}`.replace('  ', ' '));
+        if (targets.length > TRANSFER_MAX_FILES) {
+          throw new Error(`presence_export moves at most ${TRANSFER_MAX_FILES} files per call, got ${targets.length}`);
         }
 
-        mkdirSync(dirnamePath(absolute), { recursive: true });
-        writeFileSync(absolute, buffer);
+        const usedNames = new Set();
+        const files = [];
+        const errors = [];
+        for (const target of targets) {
+          try {
+            const info = await connection.stat(target);
+            if (!info.exists) throw new Error(`${target} does not exist on ${host}`);
+            if (info.isDir) {
+              throw new Error(`${target} is a directory; export files, or use presence_exec with tar/scp`);
+            }
+            if (info.size > EXPORT_CAP) {
+              throw new Error(
+                `${target} is ${info.size} bytes; export is capped at ${EXPORT_CAP} bytes — use presence_exec with scp/rsync for larger files`,
+              );
+            }
+            const { buffer } = await connection.readBytes(target, { offset: 0, length: info.size });
+            const digest = createHash('sha256').update(buffer).digest('hex');
+            const destination = singlePath
+              ? args.to ?? exportLocalTarget(folder, target, digest, usedNames)
+              : exportLocalTarget(folder, target, digest, usedNames);
+            const absolute = resolvePath(destination);
+            const contained = allowedRoots.some((root) => absolute === root || absolute.startsWith(`${root}${sep}`));
+            if (!contained) {
+              throw new Error(`refusing to write "${destination}": export targets are limited to ${folder}`);
+            }
+            mkdirSync(dirnamePath(absolute), { recursive: true });
+            writeFileSync(absolute, buffer);
+            files.push({ remotePath: target, localPath: absolute, bytes: buffer.length, sha256: digest });
+          } catch (error) {
+            // A single export keeps its all-or-nothing error; a batch reports
+            // each failure and still returns the files that did land.
+            if (singlePath) throw error;
+            errors.push({ remotePath: target, error: error?.message ?? String(error) });
+          }
+        }
         pruneExports(folder);
-        const digest = createHash('sha256').update(buffer).digest('hex');
-        return (
-          `exported ${info.size} bytes from ${target} on ${host}\n` +
-          `sha256: ${digest}\n` +
-          `local file: ${absolute}\n\n` +
-          'That path is a real local file: present it, open it in Explorer, or read it with local tools.'
-        );
+        if (args.format === 'json') {
+          return jsonText({ files, exported: files.length, failed: errors.length, errors });
+        }
+        if (files.length === 0) {
+          return clip(
+            [`exported 0 of ${targets.length} file(s) from ${host}`, ...errors.map((row) => `${row.remotePath}  error: ${row.error}`)].join('\n'),
+          );
+        }
+        if (singlePath && files.length === 1) {
+          const row = files[0];
+          return (
+            `exported ${row.bytes} bytes from ${row.remotePath} on ${host}\n` +
+            `sha256: ${row.sha256}\n` +
+            `local file: ${row.localPath}\n\n` +
+            'That path is a real local file: present it, open it in Explorer, or read it with local tools.'
+          );
+        }
+        const lines = files.map((row) => `${row.remotePath} -> ${row.localPath}  (${formatBytes(row.bytes)})`);
+        const failedLines = errors.map((row) => `FAILED ${row.remotePath}: ${row.error}`);
+        const header = `exported ${files.length}/${targets.length} file(s) from ${host} into ${folder}:`;
+        return clip([header, ...lines, ...failedLines].join('\n'));
       },
     }),
 
     tool({
       name: 'presence_import',
       description:
-        'Upload a LOCAL file to the remote machine 鈥?the missing local鈫抮emote direction of presence_export, and the only way to create binary files remotely (images, PDFs, build artifacts, attachments under ~/.dsh/attachments). Writes atomically, creates parent directories, can set a mode, and returns the sha256 so both sides can be checked. format:\'json\' returns {remotePath, localPath, sizeBytes, sha256, mode} with the full digest. Limit: 64 MiB; for larger files use presence_exec with scp/rsync.',
+        'Upload LOCAL files to a remote machine — the missing local→remote direction of presence_export, and the only way to create binary files remotely (images, PDFs, build artifacts, attachments under ~/.dsh/attachments). Writes atomically, creates parent directories, can set a mode, and returns the sha256 so both sides can be checked. Single: `source` + `to` (exact remote destination). Batch: `paths` (1-50 local paths, relative to the process cwd or absolute) and/or `glob` (local glob relative to the cwd) plus `to` as a remote directory; every file keeps its basename. format:\'json\' returns {remotePath, localPath, sizeBytes, sha256, mode} for one file, or {files:[...], imported, failed, errors} for a batch. Limit: 64 MiB per file; for larger files use presence_exec with scp/rsync.',
       parameters: {
         source: {
           type: 'string',
-          required: true,
-          description: 'Absolute local path (Windows drive paths welcome), e.g. C:\\Users\\...\\attachments\\v1\\objects\\ab\\ab12....png',
+          description:
+            'Single local file: absolute (Windows drive paths welcome) or ~/relative, e.g. C:\\Users\\...\\attachments\\v1\\objects\\ab\\ab12....png',
+        },
+        paths: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Batch: 1-50 local files, relative to the process cwd or absolute. Mutually exclusive with source.',
+        },
+        glob: {
+          type: 'string',
+          description:
+            'Batch: local glob relative to the process cwd, e.g. "shots/*.png" or "out/**/*.pdf". May be combined with paths.',
         },
         to: {
           type: 'string',
-          required: true,
-          description: 'Remote destination: absolute, workspace-relative, presence URL, or local mount path.',
+          description:
+            'Single: exact remote destination (absolute, workspace-relative, presence URL, or local mount path). Batch: remote directory that receives each basename.',
+        },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
+        mode: {
+          type: 'string',
+          description: 'Octal mode for the destination, e.g. "755". Defaults to 644 for a new file, or the existing file\'s mode.',
+        },
+        overwrite: {
+          type: 'boolean',
+          description: 'Allow replacing an existing remote file. Defaults to true; pass false to fail instead.',
         },
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
-        mode: { type: 'string', description: 'Octal mode for the destination, e.g. "755". Defaults to 644 for a new file, or the existing file\'s mode.' },
-        overwrite: { type: 'boolean', description: 'Allow replacing an existing remote file. Defaults to true; pass false to fail instead.' },
         format: {
           type: 'string',
           enum: ['text', 'json'],
-          description: 'Return one text block containing JSON: {remotePath, localPath, sizeBytes, sha256, mode}. The digest is complete, not abbreviated. Defaults to text.',
+          description:
+            'Return one text block containing JSON: {remotePath, localPath, sizeBytes, sha256, mode} for one file, or {files:[...], imported, failed, errors} for a batch. The digest is complete, not abbreviated. Defaults to text.',
         },
       },
       async execute(args, exec) {
         ensureWritable();
-        const rawSource = String(args.source ?? '').trim();
-        if (!rawSource) throw new Error('source is required');
-        const localSource = resolvePath(rawSource.startsWith('~') ? joinPath(homedir(), rawSource.slice(1)) : rawSource);
-        let localStat;
-        try {
-          localStat = statSync(localSource);
-        } catch {
-          throw new Error(`local file not found: ${localSource}`);
+        const example = '{"source": "C:\\\\Temp\\\\report.pdf", "to": "/srv/app/report.pdf"}';
+        const toInput = pickArg(args, DESTINATION_ALIASES);
+        if (toInput === undefined || toInput === '') {
+          throw missingArgument('presence_import', 'to', ['to', 'to_path', 'file_path'], args, example);
         }
-        if (!localStat.isFile()) throw new Error(`${localSource} is not a regular file`);
-        if (localStat.size > EXPORT_CAP) {
-          throw new Error(`${localSource} is ${localStat.size} bytes; import is capped at ${EXPORT_CAP} bytes 鈥?use presence_exec with scp/rsync for larger files`);
+        const rawSource = typeof args.source === 'string' ? args.source.trim() : '';
+        const listed = Array.isArray(args.paths) ? args.paths : [];
+        const globInput = typeof args.glob === 'string' && args.glob.trim() !== '' ? args.glob.trim() : null;
+        if (rawSource && (listed.length > 0 || globInput)) {
+          throw new Error('pass either source (one file) or paths/glob (a batch), not both');
         }
-
-        const buffer = readFileSync(localSource);
-        const digest = createHash('sha256').update(buffer).digest('hex');
+        if (!rawSource && listed.length === 0 && !globInput) {
+          throw missingArgument(
+            'presence_import',
+            'source',
+            ['source', 'paths', 'glob'],
+            args,
+            '{"source": "C:\\\\Temp\\\\report.pdf", "to": "/srv/app/report.pdf"}',
+          );
+        }
+        // A batch names local files relative to the process cwd; `source` keeps
+        // resolving exactly as before (absolute, or relative to the cwd).
+        const cwd = process.cwd();
+        const resolveLocal = (input) => {
+          const value = String(input);
+          const expanded = value.startsWith('~') ? joinPath(homedir(), value.slice(1)) : value;
+          return resolvePath(expanded);
+        };
+        const localCandidates = [];
+        const addLocal = (value) => {
+          const absolute = resolveLocal(value);
+          if (!localCandidates.includes(absolute)) localCandidates.push(absolute);
+        };
+        if (rawSource) addLocal(rawSource);
+        for (const value of listed) {
+          if (typeof value !== 'string' || value.trim() === '') {
+            throw new Error('presence_import: every path in paths must be a non-empty string');
+          }
+          addLocal(value.trim());
+        }
+        if (globInput) {
+          const matches = localGlobPaths(globInput, cwd);
+          if (matches.length === 0) {
+            throw new Error(`no local files match ${JSON.stringify(globInput)} under ${cwd}`);
+          }
+          for (const match of matches) addLocal(match);
+        }
+        if (localCandidates.length > TRANSFER_MAX_FILES) {
+          throw new Error(`presence_import moves at most ${TRANSFER_MAX_FILES} files per call, got ${localCandidates.length}`);
+        }
+        const batch = !rawSource;
 
         const { host, workspace } = await pickScope(args, exec);
         const connection = await pool.connection(host);
-        const target = await remotePath(connection, workspace, args.to);
-        const existing = await connection.stat(target);
-        if (existing.exists && existing.isDir) throw new Error(`${target} is a directory on ${host}`);
-        if (existing.exists && args.overwrite === false) {
-          throw new Error(`${target} already exists on ${host}; pass overwrite:true to replace it`);
-        }
-        const parent = target.includes('/') ? target.slice(0, target.lastIndexOf('/')) : '';
-        if (parent) {
-          const made = await connection.exec(`mkdir -p ${shq(parent)}`, { timeoutMs: 30_000 });
-          if (made.code !== 0) throw new Error(`cannot create parent directory ${parent}: ${made.stderr.trim()}`);
-        }
-        const mode = parseMode(args.mode) ?? (existing.exists ? undefined : 0o644);
-        const result = await connection.writeText(target, buffer, { mode });
-        const after = await connection.stat(target);
-        const modeText = modeLabel(after.exists ? after.mode : result.mode);
+        const destinationInput = await remotePath(connection, workspace, toInput);
+        let destinationDirectory = null;
+        if (batch) {
+          destinationDirectory = destinationInput.replace(/\/+$/, '') || '/';
+          const existingDir = await connection.stat(destinationDirectory);
+          if (existingDir.exists && !existingDir.isDir) {
+            throw new Error(`${destinationDirectory} exists on ${host} but is not a directory; batch import needs a directory in "to"`);
+          }
+        }
+        const usedTargets = new Set();
+        const batchTarget = (localSource, digest) => {
+          const name = localSource.split(/[\\/]/).filter(Boolean).pop() ?? 'upload.bin';
+          let candidate = `${destinationDirectory}/${name}`;
+          if (usedTargets.has(candidate)) {
+            const dot = name.lastIndexOf('.');
+            const stem = dot > 0 ? name.slice(0, dot) : name;
+            const extension = dot > 0 ? name.slice(dot) : '';
+            candidate = `${destinationDirectory}/${stem}-${digest.slice(0, 8)}${extension}`;
+          }
+          usedTargets.add(candidate);
+          return candidate;
+        };
+
+        const files = [];
+        const errors = [];
+        for (const localSource of localCandidates) {
+          try {
+            let localStat;
+            try {
+              localStat = statSync(localSource);
+            } catch {
+              throw new Error(`local file not found: ${localSource}`);
+            }
+            if (!localStat.isFile()) throw new Error(`${localSource} is not a regular file`);
+            if (localStat.size > EXPORT_CAP) {
+              throw new Error(
+                `${localSource} is ${localStat.size} bytes; import is capped at ${EXPORT_CAP} bytes — use presence_exec with scp/rsync for larger files`,
+              );
+            }
+            const buffer = readFileSync(localSource);
+            const digest = createHash('sha256').update(buffer).digest('hex');
+            const target = batch ? batchTarget(localSource, digest) : destinationInput;
+            const existing = await connection.stat(target);
+            if (existing.exists && existing.isDir) throw new Error(`${target} is a directory on ${host}`);
+            if (existing.exists && args.overwrite === false) {
+              throw new Error(`${target} already exists on ${host}; pass overwrite:true to replace it`);
+            }
+            const parent = target.includes('/') ? target.slice(0, target.lastIndexOf('/')) || '/' : '';
+            if (parent) {
+              const made = await connection.exec(`mkdir -p ${shq(parent)}`, { timeoutMs: 30_000 });
+              if (made.code !== 0) throw new Error(`cannot create parent directory ${parent}: ${made.stderr.trim()}`);
+            }
+            const mode = parseMode(args.mode) ?? (existing.exists ? undefined : 0o644);
+            const result = await connection.writeText(target, buffer, { mode });
+            const after = await connection.stat(target);
+            files.push({
+              remotePath: target,
+              localPath: localSource,
+              sizeBytes: result.bytes ?? buffer.length,
+              sha256: digest,
+              mode: modeLabel(after.exists ? after.mode : result.mode),
+            });
+          } catch (error) {
+            // A single import stays all-or-nothing; a batch reports per-file
+            // failures and still uploads the files that can be.
+            if (!batch) throw error;
+            errors.push({ localPath: localSource, error: error?.message ?? String(error) });
+          }
+        }
+
+        if (!batch) {
+          const row = files[0];
+          if (!row) {
+            throw new Error(`import of ${localCandidates[0]} failed: ${errors[0]?.error ?? 'unknown error'}`);
+          }
+          if (args.format === 'json') {
+            return jsonText({
+              remotePath: row.remotePath,
+              localPath: row.localPath,
+              sizeBytes: row.sizeBytes,
+              sha256: row.sha256,
+              mode: row.mode,
+            });
+          }
+          return (
+            `imported ${row.sizeBytes} bytes to ${row.remotePath} on ${host}${row.mode ? ` mode ${row.mode}` : ''}\n` +
+            `sha256: ${row.sha256}\n` +
+            `local source: ${row.localPath}`
+          );
+        }
         if (args.format === 'json') {
-          return jsonText({
-            remotePath: target,
-            localPath: localSource,
-            sizeBytes: result.bytes ?? buffer.length,
-            sha256: digest,
-            mode: modeText,
-          });
+          return jsonText({ files, imported: files.length, failed: errors.length, errors });
         }
-        return (
-          `imported ${buffer.length} bytes to ${target} on ${host}${modeText ? ` mode ${modeText}` : ''}\n` +
-          `sha256: ${digest}\n` +
-          `local source: ${localSource}`
+        if (files.length === 0) {
+          return clip(
+            [
+              `imported 0 of ${localCandidates.length} file(s) to ${destinationDirectory} on ${host}`,
+              ...errors.map((row) => `${row.localPath}  error: ${row.error}`),
+            ].join('\n'),
+          );
+        }
+        const lines = files.map(
+          (row) => `${row.localPath} -> ${row.remotePath}${row.mode ? ` mode ${row.mode}` : ''}  (${formatBytes(row.sizeBytes)})`,
+        );
+        const failedLines = errors.map((row) => `FAILED ${row.localPath}: ${row.error}`);
+        return clip(
+          [
+            `imported ${files.length}/${localCandidates.length} file(s) to ${destinationDirectory} on ${host}:`,
+            ...lines,
+            ...failedLines,
+          ].join('\n'),
         );
       },
     }),
@@ -1539,7 +2562,11 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
         'Delete a remote path RECOVERABLY: it is moved into `~/.dsh/presence-trash/<timestamp>/` on the same machine (no install, no extra service) and the restore path is returned. Prefer this over `rm -rf` for anything inside a workspace. Actions: trash (one path, or up to 50 paths in one call), list (recent trash containers, newest first; a single movedAtISO per entry), restore (move one back).',
       parameters: {
         action: { type: 'string', required: true, enum: ['trash', 'list', 'restore'], description: 'What to do.' },
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         path: { type: 'string', description: 'For trash: the remote path to move into the trash. For list: substring filter on trashPath/name.' },
         paths: {
           type: 'array',
@@ -1558,12 +2585,27 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
       async execute(args, exec) {
         const { host, workspace } = await pickScope(args, exec);
         const connection = await pool.connection(host);
+        const pathInput = pickArg(args, PATH_ALIASES);
+        const toInput = pickArg(args, TO_ALIASES);
         if (args.action === 'trash') {
-          if (args.path !== undefined && args.paths !== undefined) {
+          if (pathInput !== undefined && args.paths !== undefined) {
             throw new Error('pass either path or paths, not both');
           }
-          const inputs = Array.isArray(args.paths) && args.paths.length > 0 ? args.paths : args.path ? [args.path] : [];
-          if (inputs.length === 0) throw new Error('trash requires a path (or paths)');
+          const inputs =
+            Array.isArray(args.paths) && args.paths.length > 0
+              ? args.paths
+              : pathInput !== undefined && pathInput !== ''
+                ? [pathInput]
+                : [];
+          if (inputs.length === 0) {
+            throw missingArgument(
+              'presence_trash',
+              'path',
+              ['path', 'file_path', 'paths'],
+              args,
+              '{"action": "trash", "path": "/srv/app/old.log"}',
+            );
+          }
           if (inputs.length > TRASH_MAX_PATHS) {
             throw new Error(`trash moves at most ${TRASH_MAX_PATHS} paths per call, got ${inputs.length}`);
           }
@@ -1638,7 +2680,7 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
         }
         if (args.action === 'list') {
           if (typeof connection.listTrash !== 'function') throw new Error('this Presence build has no trash support; update the plugin');
-          const needle = args.path === undefined || args.path === null ? '' : String(args.path).trim();
+          const needle = pathInput === undefined || pathInput === null ? '' : String(pathInput).trim();
           // A filter should search more than the newest page, then sort/trim.
           const entries = await connection.listTrash({ limit: needle ? 1000 : 20 });
           const rows = entries
@@ -1657,23 +2699,43 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
           if (rows.length === 0) return `trash is empty on ${host}${needle ? ` for "${needle}"` : ''}`;
           return clip(rows.map((row) => `${formatMtime(row.movedAtMs ?? Number.NaN)}  ${row.trashPath}`).join('\n'));
         }
-        if (!args.trashPath) throw new Error('restore requires trashPath');
-        if (!args.to) throw new Error('restore requires to (the original location; the container does not record it)');
+        if (!args.trashPath) {
+          throw missingArgument(
+            'presence_trash',
+            'trashPath',
+            ['trashPath'],
+            args,
+            '{"action": "restore", "trashPath": "/home/me/.dsh/presence-trash/20261028-120000/a.txt", "to": "/srv/app/a.txt"}',
+          );
+        }
+        if (toInput === undefined || toInput === '') {
+          throw missingArgument(
+            'presence_trash',
+            'to',
+            ['to', 'to_path'],
+            args,
+            '{"action": "restore", "trashPath": "/home/me/.dsh/presence-trash/20261028-120000/a.txt", "to": "/srv/app/a.txt"}',
+          );
+        }
         if (typeof connection.restoreTrash !== 'function') throw new Error('this Presence build has no trash support; update the plugin');
-        const restored = await connection.restoreTrash(args.trashPath, { to: args.to });
+        const restored = await connection.restoreTrash(args.trashPath, { to: toInput });
         if (args.format === 'json') {
-          return JSON.stringify({ restored: true, from: args.trashPath, to: restored.to ?? args.to }, null, 2);
+          return JSON.stringify({ restored: true, from: args.trashPath, to: restored.to ?? toInput }, null, 2);
         }
-        return `restored ${args.trashPath} to ${restored.to ?? args.to} on ${host}`;
+        return `restored ${args.trashPath} to ${restored.to ?? toInput} on ${host}`;
       },
     }),
 
     tool({
       name: 'presence_edit',
       description:
-        'Replace exact text inside a file on a remote machine. Use this 鈥?or the built-in `edit` tool, which also reaches the remote workspace 鈥?instead of `sed -i`, `perl -pi`, or `python -c` for remote edits: it is atomic, refuses an anchor that occurs more than once unless replaceAll is set, and reports how many occurrences changed. Returns a compact diff of the changed lines (context +/-2, max 100 lines/8 KiB); dryRun:true validates the anchor and computes the same diff without writing. The file keeps its mode (an executable stays executable). Inside a workspace, relative paths resolve against the workspace root.',
+        'Replace exact text inside a file on a remote machine. Use this — or the built-in `edit` tool, which also reaches the remote workspace — instead of `sed -i`, `perl -pi`, or `python -c` for remote edits: it is atomic, refuses an anchor that occurs more than once unless replaceAll is set, and reports how many occurrences changed. Returns a compact diff of the changed lines (context +/-2, max 100 lines/8 KiB); dryRun:true validates the anchor and computes the same diff without writing. The file keeps its mode (an executable stays executable). Inside a workspace, relative paths resolve against the workspace root.',
       parameters: {
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         path: { type: 'string', required: true, description: 'Absolute path, ~/relative, or workspace-relative.' },
         old: { type: 'string', description: 'Exact text to replace, including indentation.' },
         oldString: { type: 'string', description: 'Alias for `old` (same spelling as the built-in edit tool).' },
@@ -1692,22 +2754,42 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
         },
       },
       async execute(args, exec) {
-        const oldText = args.old ?? args.oldString;
-        const newText = args.new ?? args.newString;
-        if (typeof oldText !== 'string' || oldText === '') throw new Error('old (or oldString) is required');
-        if (typeof newText !== 'string') throw new Error('new (or newString) is required');
-        const dryRun = args.dryRun === true;
+        const example = '{"path": "/srv/app/a.txt", "old": "before", "new": "after"}';
+        const pathInput = requirePath(args, 'presence_edit', example);
+        const oldText = pickArg(args, EDIT_OLD_ALIASES);
+        if (typeof oldText !== 'string' || oldText === '') {
+          throw missingArgument('presence_edit', 'old', EDIT_OLD_ALIASES, args, example);
+        }
+        const newText = pickArg(args, EDIT_NEW_ALIASES);
+        if (typeof newText !== 'string') {
+          throw missingArgument('presence_edit', 'new', EDIT_NEW_ALIASES, args, example);
+        }
+        const dryRun = pickArg(args, EDIT_DRY_RUN_ALIASES) === true;
+        const replaceAll = pickArg(args, EDIT_REPLACE_ALL_ALIASES) === true;
         if (!dryRun) ensureWritable();
         const { host, workspace } = await pickScope(args, exec);
         const connection = await pool.connection(host);
-        const target = await remotePath(connection, workspace, args.path);
+        const target = await remotePath(connection, workspace, pathInput);
         const info = await connection.stat(target);
-        if (!info.exists) throw new Error(`${target} does not exist on ${host} 鈥?nothing to edit (use presence_write to create it)`);
+        if (!info.exists) throw new Error(`${target} does not exist on ${host} — nothing to edit (use presence_write to create it)`);
         if (info.isDir) throw new Error(`${target} is a directory on ${host}`);
-        const replaceAll = Boolean(args.replaceAll ?? args.replace_all);
         const before = (await connection.readText(target, { length: Number.MAX_SAFE_INTEGER })).content;
         const occurrences = before.split(oldText).length - 1;
-        if (occurrences === 0) throw new Error('text to replace was not found');
+        if (occurrences === 0) {
+          // Another session may have changed the file since it was read; point
+          // at the closest lines so the stale anchor is easy to recognize.
+          const closest = closestLines(before, oldText, 3);
+          const message = [`text to replace was not found in ${target} on ${host}.`];
+          if (closest.length > 0) {
+            message.push('closest lines:');
+            for (const entry of closest) message.push(`  line ${entry.line}: ${entry.text}`);
+          }
+          message.push(
+            'hint: re-read the file if another session changed it; ' +
+              'ifMatchSha256 is available on presence_write for a hash-checked overwrite.',
+          );
+          throw new Error(message.join('\n'));
+        }
         if (occurrences > 1 && !replaceAll) {
           throw new Error(`text occurs ${occurrences} times; pass replaceAll or a longer anchor`);
         }
@@ -1726,7 +2808,7 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
           actualSizeBytes = result.bytes;
         }
         const diff = diffLines(before, after);
-        await markObserved(exec, args.path);
+        await markObserved(exec, pathInput);
         if (args.format === 'json') {
           return jsonText({
             path: target,
@@ -1751,9 +2833,13 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
     tool({
       name: 'presence_search',
       description:
-        'Search file contents on a remote machine with the tools that machine already has (ripgrep, falling back to grep). Smart-case: lowercase patterns match case-insensitively, any uppercase letter makes them exact 鈥?the same as the built-in grep. Inside a workspace the search root defaults to the workspace. `path` may be a single file or a directory; every match is reported as path:line:text. `include` accepts one glob (*.ts), a brace list (*.{js,jsx}) or a comma-separated list (*.txt,*.dat); spaces are trimmed. The result states the limit and whether it truncated; countOnly returns the exact number of matching lines instead. A bad regex or an unreadable/oversized tree is an error, never a silent empty result.',
+        'Search file contents on a remote machine with the tools that machine already has (ripgrep, falling back to grep). Smart-case: lowercase patterns match case-insensitively, any uppercase letter makes them exact — the same as the built-in grep. Inside a workspace the search root defaults to the workspace. `path` may be a single file or a directory; every match is reported as path:line:text. `include` accepts one glob (*.ts), a brace list (*.{js,jsx}) or a comma-separated list (*.txt,*.dat); spaces are trimmed. The result states the limit and whether it truncated; countOnly returns the exact number of matching lines instead. A bad regex or an unreadable/oversized tree is an error, never a silent empty result.',
       parameters: {
-        host: { type: 'string', description: 'ssh alias. Defaults to the active workspace\'s machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         pattern: { type: 'string', required: true, description: 'Regular expression to search for (ripgrep syntax).' },
         path: { type: 'string', description: 'File or directory to search, absolute or workspace-relative. Defaults to the workspace root, else the remote home directory.' },
         include: { type: 'string', description: 'Only files matching this glob. Accepts *.ts, *.{js,jsx}, or a comma-separated list such as *.txt,*.dat (spaces are trimmed).' },
@@ -1766,9 +2852,13 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
         },
       },
       async execute(args, exec) {
+        const pathInput = pickArg(args, PATH_ALIASES);
         const { host, workspace } = await pickScope(args, exec);
         const connection = await pool.connection(host);
-        const target = args.path ? await remotePath(connection, workspace, args.path) : workspace?.path ?? (await connection.homePath());
+        const target =
+          pathInput !== undefined && pathInput !== ''
+            ? await remotePath(connection, workspace, pathInput)
+            : workspace?.path ?? (await connection.homePath());
 
         // Fail loudly instead of pretending "no matches": a missing path or a
         // bad regex must not look like an empty result.
@@ -1785,7 +2875,7 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
           smartCase: true,
           countOnly: Boolean(args.countOnly),
         });
-        const warn = warning ? `\n(warning: some paths were not searchable 鈥?${warning.slice(0, 300)})` : '';
+        const warn = warning ? `\n(warning: some paths were not searchable — ${warning.slice(0, 300)})` : '';
 
         if (args.format === 'json') {
           const matchCount = total ?? matches.length;
@@ -1818,7 +2908,7 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
             : `showing ${matches.length} of ${total} matches (truncated; limit ${limit}) on ${host}:`
           : `${total ?? matches.length} match(es) on ${host} (not truncated; limit ${limit}):`;
         const footer = truncated
-          ? '\n(more matches exist 鈥?use countOnly for an exact total, narrow path/include, or raise limit)'
+          ? '\n(more matches exist — use countOnly for an exact total, narrow path/include, or raise limit)'
           : '';
         return `${header}\n${clip(lines.join('\n'))}${footer}${warn}`;
       },
@@ -1830,7 +2920,11 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
         'Find files on the remote machine by glob pattern. Use this instead of `glob`, which only scans the local disk and silently returns an empty result for a remote workspace. An absolute pattern such as /srv/app/*.py carries its own root and needs no path. All matches are sorted newest-first before `limit` is applied, and the result reports the total number of matches. Returns absolute paths with size and mtime when the host\'s find supports -printf; otherwise names only, and says so.',
       parameters: {
         pattern: { type: 'string', required: true, description: 'Glob relative to the search root, e.g. "src/**/*.ts", or absolute, e.g. "/srv/app/*.py".' },
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         path: { type: 'string', description: 'Directory to search from. Ignored by an absolute pattern; defaults to the workspace root.' },
         limit: { type: 'number', description: 'Maximum files to return, applied after the newest-first sort. Defaults to 200.' },
         format: {
@@ -1840,6 +2934,7 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
         },
       },
       async execute(args, exec) {
+        const pathInput = pickArg(args, PATH_ALIASES);
         const { host, workspace } = await pickScope(args, exec);
         const connection = await pool.connection(host);
         const limit = Math.max(1, args.limit ?? 200);
@@ -1848,8 +2943,8 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
         const pattern = absolute ? absolute.pattern : rawPattern;
         const base = absolute
           ? absolute.root
-          : args.path
-            ? await remotePath(connection, workspace, args.path)
+          : pathInput !== undefined && pathInput !== ''
+            ? await remotePath(connection, workspace, pathInput)
             : workspace?.path ?? (await connection.homePath());
         const info = await connection.stat(base);
         if (!info.exists) throw new Error(`${base} does not exist on ${host}`);
@@ -1887,7 +2982,7 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
           : `${totalLabel} file(s) on ${host} under ${base} (not truncated; limit ${limit}${newest}):`;
         const footer = [];
         if (detailed.truncated) {
-          footer.push(`(more files match 鈥?raise limit or narrow the pattern)`);
+          footer.push(`(more files match — raise limit or narrow the pattern)`);
         }
         if (detailed.scanCapped) {
           footer.push('(the host-side scan stopped at its file cap, so the total is a lower bound)');
@@ -1910,7 +3005,11 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
           required: true,
           description: 'Remote paths (absolute, ~/..., presence://host/path, or workspace-relative). 1-100 entries.',
         },
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         hash: {
           type: 'boolean',
           description: 'Also compute sha256 for existing regular files. Defaults to false.',
@@ -1926,8 +3025,23 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
         },
       },
       async execute(args, exec) {
-        const inputs = Array.isArray(args.paths) ? args.paths : [];
-        if (inputs.length === 0) throw new Error('paths is required: pass 1-100 remote paths');
+        const listed = Array.isArray(args.paths) ? args.paths : [];
+        const singlePath = listed.length === 0 ? pickArg(args, PATH_ALIASES) : undefined;
+        const inputs =
+          listed.length > 0
+            ? listed
+            : singlePath !== undefined && singlePath !== ''
+              ? [singlePath]
+              : [];
+        if (inputs.length === 0) {
+          throw missingArgument(
+            'presence_stat',
+            'paths',
+            ['paths', 'path', 'file_path'],
+            args,
+            '{"paths": ["/srv/app/a.txt", "/srv/app/b.txt"]}',
+          );
+        }
         if (inputs.length > STAT_MAX_PATHS) {
           throw new Error(`presence_stat reports at most ${STAT_MAX_PATHS} paths per call, got ${inputs.length}`);
         }
@@ -1963,7 +3077,11 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
       description:
         'Create a directory on a remote machine. Inside a workspace, relative paths resolve against the workspace root. `parents` defaults to true (mkdir -p): missing parents are created and an existing directory is a success. Pass parents:false to require the parent to exist. Prefer this over presence_exec for a plain mkdir.',
       parameters: {
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         path: { type: 'string', required: true, description: 'Absolute path, ~/relative, or workspace-relative.' },
         parents: {
           type: 'boolean',
@@ -1973,9 +3091,10 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
       annotations: { destructiveHint: false, readOnlyHint: false, idempotentHint: true },
       async execute(args, exec) {
         ensureWritable();
+        const pathInput = requirePath(args, 'presence_mkdir', '{"path": "/srv/app/build"}');
         const { host, workspace } = await pickScope(args, exec);
         const connection = await pool.connection(host);
-        const target = await remotePath(connection, workspace, args.path);
+        const target = await remotePath(connection, workspace, pathInput);
         const before = await connection.stat(target).catch(() => null);
         const existed = before?.exists === true && before.isDir === true;
         await makeDirectory(connection, target, { recursive: args.parents !== false });
@@ -1988,7 +3107,11 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
       description:
         'Rename or move a path on one remote machine (an atomic rename on the host). `to` is the exact new path, not a directory to move into. An existing destination file is refused unless overwrite:true; an existing destination directory is never merged into or replaced. Inside a workspace, relative paths resolve against the workspace root.',
       parameters: {
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         from: { type: 'string', required: true, description: 'Remote path to move (absolute, ~/relative, or workspace-relative).' },
         to: { type: 'string', required: true, description: 'Exact new remote path.' },
         overwrite: { type: 'boolean', description: 'Replace an existing destination file. Defaults to false.' },
@@ -1996,12 +3119,22 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
       annotations: { destructiveHint: true, readOnlyHint: false },
       async execute(args, exec) {
         ensureWritable();
+        const example = '{"from": "/srv/app/a.txt", "to": "/srv/app/b.txt"}';
+        const fromInput = requirePath(args, 'presence_move', example, {
+          names: SOURCE_ALIASES,
+          canonical: 'from',
+          accepted: ['from', 'from_path', 'file_path'],
+        });
+        const toInput = pickArg(args, TO_ALIASES);
+        if (toInput === undefined || toInput === '') {
+          throw missingArgument('presence_move', 'to', ['to', 'to_path'], args, example);
+        }
         const { host, workspace } = await pickScope(args, exec);
         const connection = await pool.connection(host);
-        const from = await remotePath(connection, workspace, args.from);
-        const to = await remotePath(connection, workspace, args.to);
+        const from = await remotePath(connection, workspace, fromInput);
+        const to = await remotePath(connection, workspace, toInput);
         const result = await movePath(connection, from, to, { overwrite: args.overwrite === true });
-        await markObserved(exec, args.to);
+        await markObserved(exec, toInput);
         return `moved ${result.from} -> ${result.to} on ${host}`;
       },
     }),
@@ -2011,7 +3144,11 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
       description:
         'Copy a file or directory on one remote machine. `to` is the exact destination path. A directory requires recursive:true and is copied with remote `cp -a`; a file is streamed through SFTP up to 8 MiB and copied with remote `cp -p` above that, so nothing large goes through this process. An existing destination is refused unless overwrite:true. Inside a workspace, relative paths resolve against the workspace root.',
       parameters: {
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         from: { type: 'string', required: true, description: 'Remote source path.' },
         to: { type: 'string', required: true, description: 'Exact remote destination path.' },
         recursive: { type: 'boolean', description: 'Copy a directory tree. Required when from is a directory. Defaults to false.' },
@@ -2020,15 +3157,25 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
       annotations: { destructiveHint: true, readOnlyHint: false },
       async execute(args, exec) {
         ensureWritable();
+        const example = '{"from": "/srv/app/a.txt", "to": "/srv/app/b.txt"}';
+        const fromInput = requirePath(args, 'presence_copy', example, {
+          names: SOURCE_ALIASES,
+          canonical: 'from',
+          accepted: ['from', 'from_path', 'file_path'],
+        });
+        const toInput = pickArg(args, TO_ALIASES);
+        if (toInput === undefined || toInput === '') {
+          throw missingArgument('presence_copy', 'to', ['to', 'to_path'], args, example);
+        }
         const { host, workspace } = await pickScope(args, exec);
         const connection = await pool.connection(host);
-        const from = await remotePath(connection, workspace, args.from);
-        const to = await remotePath(connection, workspace, args.to);
+        const from = await remotePath(connection, workspace, fromInput);
+        const to = await remotePath(connection, workspace, toInput);
         const result = await copyPath(connection, from, to, {
           recursive: args.recursive === true,
           overwrite: args.overwrite === true,
         });
-        await markObserved(exec, args.to);
+        await markObserved(exec, toInput);
         const facts = [];
         if (result.files !== undefined) facts.push(`${result.files} file(s)`);
         if (result.bytes !== undefined) facts.push(formatBytes(result.bytes));
@@ -2041,7 +3188,11 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
       description:
         'Change permissions on a remote path and report the applied octal mode. Accepts "755"/"0644"/"0o755" strings (preferred) or an octal mode number such as 0o755. With recursive:true a directory tree is changed with `chmod -R`. Inside a workspace, relative paths resolve against the workspace root.',
       parameters: {
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         path: { type: 'string', required: true, description: 'Absolute path, ~/relative, or workspace-relative.' },
         mode: {
           oneOf: [{ type: 'string' }, { type: 'number' }],
@@ -2053,12 +3204,13 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
       annotations: { destructiveHint: true, readOnlyHint: false },
       async execute(args, exec) {
         ensureWritable();
+        const pathInput = requirePath(args, 'presence_chmod', '{"path": "/srv/app/run.sh", "mode": "755"}');
         const { host, workspace } = await pickScope(args, exec);
         const connection = await pool.connection(host);
-        const target = await remotePath(connection, workspace, args.path);
+        const target = await remotePath(connection, workspace, pathInput);
         const mode = parseChmodMode(args.mode);
         const result = await chmodPath(connection, target, mode, { recursive: args.recursive === true });
-        await markObserved(exec, args.path);
+        await markObserved(exec, pathInput);
         return `chmod ${args.recursive === true ? '-R ' : ''}${result.mode} ${result.path} on ${host}`;
       },
     }),
@@ -2068,7 +3220,11 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
       description:
         'Diff a text file on a remote machine against either another remote file (`b`) or a local host-process file (`localPath`); pass exactly one of b/localPath. Returns a unified diff body (hunk headers plus +/-/context rows, no ---/+++ headers): `context` controls context lines (default 3, max 20), the diff is capped by lines/bytes and reports truncation, and identical content returns "(no changes)". format:\'json\' returns {stats:{added,removed}, diff, truncated}. Inside a workspace, relative paths resolve against the workspace root; localPath is resolved against the host process cwd.',
       parameters: {
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         a: { type: 'string', required: true, description: 'Left side: remote path (absolute, ~/relative, or workspace-relative).' },
         b: { type: 'string', description: 'Right side: another remote path. Mutually exclusive with localPath.' },
         localPath: { type: 'string', description: 'Right side: a local file on the host process. Mutually exclusive with b.' },
@@ -2081,27 +3237,34 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
       },
       annotations: { readOnlyHint: true },
       async execute(args, exec) {
-        const hasRemoteB = typeof args.b === 'string' && args.b.trim() !== '';
+        const example = '{"a": "/srv/app/old.txt", "b": "/srv/app/new.txt"}';
+        const aInput = requirePath(args, 'presence_diff', example, {
+          names: DIFF_A_ALIASES,
+          canonical: 'a',
+          accepted: ['a', 'file_path'],
+        });
+        const bInput = pickArg(args, DIFF_B_ALIASES);
+        const hasRemoteB = typeof bInput === 'string' && bInput.trim() !== '';
         const hasLocal = typeof args.localPath === 'string' && args.localPath.trim() !== '';
         if (hasRemoteB === hasLocal) {
           throw new Error('pass exactly one of b (another remote path) or localPath (a local file) as the right side');
         }
         const { host, workspace } = await pickScope(args, exec);
         const connection = await pool.connection(host);
-        const leftTarget = await remotePath(connection, workspace, args.a);
+        const leftTarget = await remotePath(connection, workspace, aInput);
         const left = await readRemoteTextForDiff(connection, leftTarget, host);
         let right;
         let rightLabel;
         if (hasRemoteB) {
-          rightLabel = await remotePath(connection, workspace, args.b);
+          rightLabel = await remotePath(connection, workspace, bInput);
           right = await readRemoteTextForDiff(connection, rightLabel, host);
-          await markObserved(exec, args.b);
+          await markObserved(exec, bInput);
         } else {
           const local = readLocalTextForDiff(args.localPath);
           right = local.content;
           rightLabel = local.path;
         }
-        await markObserved(exec, args.a);
+        await markObserved(exec, aInput);
         const context = clampedNumber(args.context, 3, 0, 20);
         const result = buildUnifiedDiff(left, right, { context });
         if (args.format === 'json') {
@@ -2128,7 +3291,11 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
       description:
         'Read the last lines of a text file on a remote machine (default 200), optionally following it: follow:true keeps polling for new bytes for timeoutMs (default 8000, max 60000) and returns everything appended meanwhile. Only an incremental byte window is read, so a large log is never pulled whole; `truncated` is true when content before the returned window was dropped. format:\'json\' returns {path, lines, bytes, followedMs, truncated, text}. Inside a workspace, relative paths resolve against the workspace root.',
       parameters: {
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         path: { type: 'string', required: true, description: 'Absolute path, ~/relative, or workspace-relative.' },
         lines: { type: 'number', description: 'How many trailing lines to return, 1-5000. Defaults to 200.' },
         follow: { type: 'boolean', description: 'Keep appending new bytes for timeoutMs before returning. Defaults to false.' },
@@ -2144,9 +3311,10 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
       },
       annotations: { readOnlyHint: true },
       async execute(args, exec) {
+        const pathInput = requirePath(args, 'presence_tail', '{"path": "/srv/app/app.log", "lines": 200}');
         const { host, workspace } = await pickScope(args, exec);
         const connection = await pool.connection(host);
-        const target = await remotePath(connection, workspace, args.path);
+        const target = await remotePath(connection, workspace, pathInput);
         const follow = args.follow === true;
         const result = await tailRemote(connection, target, {
           lines: clampedNumber(args.lines, TAIL_DEFAULT_LINES, 1, TAIL_MAX_LINES),
@@ -2154,7 +3322,7 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
           timeoutMs: clampedNumber(args.timeoutMs, TAIL_DEFAULT_TIMEOUT_MS, 0, TAIL_MAX_TIMEOUT_MS),
           signal: exec?.signal,
         });
-        await markObserved(exec, args.path);
+        await markObserved(exec, pathInput);
         if (args.format === 'json') {
           let text = result.text;
           let lines = result.lines;
@@ -2233,17 +3401,29 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
               ? 'no background jobs'
               : 'no background jobs for this session (use all:true to list every session)';
           }
-          if (args.format === 'json') return JSON.stringify(visible.map((job) => jobRecord(job)), null, 2);
+          if (args.format === 'json') {
+            return jsonText(
+              visible.map((job) => {
+                const record = jobRecord(job);
+                if (typeof record.command === 'string') record.command = clipCommandLine(record.command);
+                return record;
+              }),
+            );
+          }
           const lines = visible.map((job) => {
             // The stored command carries the pool's pipefail probe; the list
-            // should show what the caller actually asked to run.
-            const label = stripPipefailPrelude(job.label ?? job.command ?? '(no label)') || '(no label)';
+            // should show what the caller actually asked to run, label first and
+            // the command clipped to one short line.
+            const label = clipCommandLine(stripPipefailPrelude(job.label ?? '(no label)') || '(no label)');
+            const command = job.command ? clipCommandLine(stripPipefailPrelude(job.command)) : null;
             const age = job.startedAt ? `${Math.round((Date.now() - job.startedAt) / 1000)}s` : '?';
             const exit =
               job.exitCode === undefined || job.exitCode === null ? (job.state === 'running' ? '-' : '?') : job.exitCode;
             return (
-              `${job.id}  ${label}\n` +
-              `  state=${job.state ?? 'unknown'}  exit=${exit}  pid=${job.pid ?? '?'}  host=${job.host}  age=${age}  log=${job.logPath ?? '?'}`
+              `${label}\n` +
+              `  job=${job.id}  state=${job.state ?? 'unknown'}  exit=${exit}  pid=${job.pid ?? '?'}  ` +
+              `host=${job.host}  age=${age}  log=${job.logPath ?? '?'}` +
+              (command ? `\n  command: ${command}` : '')
             );
           });
           return `${visible.length} job(s):\n${lines.join('\n')}`;
@@ -2271,6 +3451,10 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
           if (body.logPath) {
             lines.push(`log: ${body.logPath}${body.logSize !== null ? ` (${formatBytes(body.logSize)})` : ''}`);
           }
+          if (body.commandLogPath && body.commandLogPath !== body.logPath) {
+            lines.push(`command log: ${body.commandLogPath}`);
+          }
+          if (body.pgid !== null) lines.push(`pgid: ${body.pgid}${body.persisted ? '  (persisted job)' : ''}`);
           return clip(lines.join('\n'));
         }
 
@@ -2400,7 +3584,11 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
         localPort: { type: 'number', description: 'For open: local port to bind. Defaults to an OS-assigned free port.' },
         remoteHost: { type: 'string', description: 'For open: remote bind host. Defaults to 127.0.0.1.' },
         forwardId: { type: 'string', description: 'For close: the id returned by open.' },
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         format: {
           type: 'string',
           enum: ['text', 'json'],
@@ -2483,7 +3671,11 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
           required: true,
           description: 'TCP ports to check (1-20 entries).',
         },
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         expect: {
           type: 'string',
           enum: ['open', 'closed'],
@@ -2575,7 +3767,11 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
           type: 'boolean',
           description: 'Wait up to timeoutMs for the remote port to accept TCP before forwarding. Defaults to true.',
         },
-        host: { type: 'string', description: 'ssh alias. Defaults to this session\'s workspace machine.' },
+        host: {
+          type: 'string',
+          description:
+            'ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         format: {
           type: 'string',
           enum: ['text', 'json'],
@@ -2692,7 +3888,7 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
     tool({
       name: 'presence_terminal',
       description:
-        'Drive a persistent interactive terminal on a remote machine. open starts a shell that survives between tool calls; pass `session` to run it inside a named tmux session on the target, so it also survives an SSH drop or an app restart 鈥?reopen with the same name to reattach. write sends keystrokes, read returns new output since the last read, close ends it. Use this for REPLs, ssh sessions, long-running interactive programs and pagers 鈥?not for one-shot commands, which presence_exec handles.',
+        'Drive a persistent interactive terminal on a remote machine. open starts a shell that survives between tool calls; pass `session` to run it inside a named tmux session on the target, so it also survives an SSH drop or an app restart — reopen with the same name to reattach. write sends keystrokes, read returns new output since the last read, close ends it. Use this for REPLs, ssh sessions, long-running interactive programs and pagers — not for one-shot commands, which presence_exec handles.',
       parameters: {
         action: {
           type: 'string',
@@ -2700,7 +3896,11 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
           enum: ['open', 'write', 'read', 'close', 'list'],
           description: 'What to do with the terminal.',
         },
-        host: { type: 'string', description: 'For open: ssh alias. Defaults to the active workspace\'s machine.' },
+        host: {
+          type: 'string',
+          description:
+            'For open: ssh alias. In a remote-workspace session defaults to that machine; a local session must pass host (or configure PRESENCE_HOST).',
+        },
         session: {
           type: 'string',
           description:
@@ -2828,7 +4028,7 @@ export function definePresenceTools(pool, settings, { cwdOf, observe } = {}) {
             return jsonText({ terminalId: args.terminalId, closed: true, session, killedSession, host });
           }
           if (killedSession) return `closed ${args.terminalId} and killed tmux session "${session}"`;
-          if (session) return `closed ${args.terminalId}; tmux session "${session}" keeps running 鈥?reopen with session:"${session}" to reattach`;
+          if (session) return `closed ${args.terminalId}; tmux session "${session}" keeps running — reopen with session:"${session}" to reattach`;
           return `closed ${args.terminalId}`;
         }
         throw new Error(`unknown action ${args.action}`);