@rjfan/dsh-presence 0.19.0 → 0.20.1

package/index.js

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

package/package.json

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

package/src/api.js

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

package/src/intercept.js

@@ -8,6 +8,7 @@
 
 import { parseMountPath, parsePresenceUrl, resolveRemoteInput } from './mounts.js';
 import { remoteGlobDetailed, remoteGrep, splitGlobPattern } from './remote-search.js';
+import { canonicalObservation, lookupObservation, recordObservation } from './observed-store.js';
 
 const LIMIT = 200;
 
@@ -131,3 +132,152 @@ export function installToolInterceptor(ctx, { pool, cwdOf }) {
     }
   });
 }
+
+/**
+ * Bridge between the Presence file tools and the harness read-before-edit
+ * policy (plugin `fs-observation-policy`).
+ *
+ * The policy records an authoritative observation only when a tool emits
+ * `fs/observed` with a resolved target and the returned version. Its state is a
+ * WeakMap keyed by the live Session object inside that plugin — it is not a
+ * service, so it cannot be read or written directly from here. What IS possible
+ * (and what this bridge does) is to publish the same event the built-in tools
+ * publish:
+ *  - after `presence_read`/`presence_write`/`presence_edit` succeed (through the
+ *    `observe` callback the tools call), so a later built-in `edit` on the same
+ *    remote file passes;
+ *  - after a built-in `read`/`read_image`, so the persisted record survives
+ *    compaction (the guard's own WeakMap does not);
+ *  - just before a built-in `edit`/`write`, re-publishing the recorded version
+ *    when the file is still at exactly that version. A changed file is never
+ *    auto-approved.
+ *
+ * `exec cat` (or any command that happens to read a file) is deliberately NOT
+ * turned into an observation: a shell command carries neither a target identity
+ * nor a version, and fabricating one would defeat the guard.
+ *
+ * @param ctx - plugin context (event owner).
+ * @param options.cwdOf - async (exec) => session cwd or null.
+ * @param options.late - late-bound services (`fs`).
+ * @returns `{ observe, resolveObservation }`; `observe` is the callback
+ *   `definePresenceTools` expects, `resolveObservation` is useful for probes.
+ */
+export function installObservationBridge(ctx, { cwdOf, late }) {
+  const sessionIdOf = (exec) => exec?.agent?.session?.id ?? exec?.agent?.session?.header?.id ?? null;
+
+  const explicitHostOf = (exec) => {
+    const host = exec?.arguments?.host;
+    return typeof host === 'string' && host.trim() ? host.trim() : null;
+  };
+
+  /**
+   * Resolve a tool path spelling to `{ target, canonical }`. A remote spelling
+   * becomes the canonical `presence://host/path` target directly (so a local
+   * session that passed `host` explicitly still records the right identity);
+   * a genuinely local path falls back to the provider's own target, keeping the
+   * pre-0.20 local repair behavior.
+   */
+  const resolveObservation = async (exec, path) => {
+    if (typeof path !== 'string' || path === '') return null;
+    let cwd = null;
+    try {
+      cwd = (await cwdOf(exec)) ?? null;
+    } catch {
+      cwd = null;
+    }
+    const explicitHost = explicitHostOf(exec);
+    const canonical = canonicalObservation(path, { cwd, host: explicitHost });
+    if (canonical) {
+      // The presence provider's identity IS the presence URL; the policy only
+      // reads `targetKey`, and every other `fs/observed` listener can stat this
+      // target through the same provider.
+      return { target: { targetKey: canonical.key, displayPath: canonical.key }, canonical };
+    }
+    // A relative spelling cannot be mapped when the call named a different host
+    // than the mounted workspace: resolving it through the provider would record
+    // the mounted machine's file, which is NOT the file the tool touched. Never
+    // fabricate a target that belongs to another machine.
+    if (explicitHost && cwd && parseMountPath(cwd)) return null;
+    const fs = late?.fs;
+    if (!fs || typeof fs.resolve !== 'function') return null;
+    try {
+      const target = await fs.resolve(path, cwd ? { cwd } : undefined);
+      if (!target) return null;
+      return { target, canonical: canonicalObservation(target, { cwd }) };
+    } catch {
+      return null;
+    }
+  };
+
+  /** Record that this session saw the file at its current version. */
+  const observe = async (exec, path, options = {}) => {
+    try {
+      const resolved = await resolveObservation(exec, path);
+      if (!resolved) return;
+      const fs = late?.fs;
+      const stat = fs && typeof fs.stat === 'function' ? await fs.stat(resolved.target) : null;
+      const observation = stat ? { kind: 'present', version: stat.version } : { kind: 'absent' };
+      // The built-in read/write tools already publish their own event; a second
+      // one would only churn `changes` listeners. Presence tools have no other
+      // publisher, so they always publish here.
+      if (options.publish !== false) ctx.emit('fs/observed', resolved.target, observation, { agent: exec?.agent });
+      if (stat && options.remember !== false) {
+        recordObservation(
+          sessionIdOf(exec),
+          resolved.canonical ?? String(resolved.target.targetKey ?? ''),
+          stat.version,
+          { cwd: null },
+        );
+      }
+    } catch {
+      /* the observation is an optimization, never a failure */
+    }
+  };
+
+  /** Re-publish a recorded observation if the file is still at that version. */
+  const repair = async (exec, path) => {
+    const sessionId = sessionIdOf(exec);
+    if (!sessionId) return null;
+    const resolved = await resolveObservation(exec, path);
+    if (!resolved) return null;
+    const targetKey = resolved.canonical?.key ?? String(resolved.target.targetKey ?? '');
+    const recorded = lookupObservation(sessionId, resolved.canonical ?? targetKey);
+    if (!recorded) return null;
+    const fs = late?.fs;
+    const stat = fs && typeof fs.stat === 'function' ? await fs.stat(resolved.target) : null;
+    if (!stat || stat.version !== recorded) return null;
+    ctx.emit('fs/observed', resolved.target, { kind: 'present', version: stat.version }, { agent: exec.agent });
+    return stat.version;
+  };
+
+  // Built-in read/read_image: remember what the session has seen, so the record
+  // survives compaction even though the guard's WeakMap does not.
+  ctx.on('tools/post-execute', async (exec, result, next) => {
+    try {
+      if (!result?.isError && (exec?.name === 'read' || exec?.name === 'read_image')) {
+        await observe(exec, exec.arguments?.file_path, { publish: false });
+      }
+    } catch {
+      /* best effort */
+    }
+    return next();
+  });
+
+  // Built-in edit/write on a remote target: if this session read the file at
+  // the same version we recorded, re-publish the observation so the guard
+  // passes. A changed file is left alone: the guard's refusal is the point.
+  ctx.on('tools/pre-execute', async (exec, next) => {
+    try {
+      if (exec?.name === 'edit' || exec?.name === 'write') {
+        const path = exec.arguments?.file_path;
+        if (typeof path === 'string' && path !== '') await repair(exec, path);
+      }
+    } catch {
+      /* best effort: a failed repair leaves the original guard behavior */
+    }
+    return next();
+  });
+
+  return { observe, resolveObservation };
+}
+