@goodandready/dsh-kanban 0.2.32 → 0.2.34

package/lib/config.js

@@ -79,6 +79,18 @@ export const CONFIG_DEFAULTS = {
   verificationGateEnabled: true,
   verificationCommand: 'npm test',
   verificationTimeoutMs: 120000,
+  costMeterEnabled: true,
+  taskCostLimit: 0,
+  remoteMode: false,
+  remoteHost: '192.168.1.111',
+  remotePort: 22,
+  remoteUser: 'migrate',
+  remoteAuthType: 'key',
+  remoteKeyPath: '',
+  remoteSudoUser: 'vadim',
+  remoteRoot: '/mnt/external/Project/DEV',
+  remoteServerUrl: 'http://192.168.1.111:3080',
+  remoteServerToken: '',
 }
 
 /** Field descriptions reused in schema and settings card. */
@@ -117,6 +129,18 @@ export const CONFIG_HINTS = {
   verificationGateEnabled: 'Run automated verification gate (e.g. npm test) before allowing cards to move to Review.',
   verificationCommand: 'Default verification command to execute in task worktree before Review (default: npm test).',
   verificationTimeoutMs: 'Timeout in milliseconds for verification gate execution (default: 120000).',
+  costMeterEnabled: 'Enable token and cost telemetry integration via @goodandready/dsh-cost-meter.',
+  taskCostLimit: 'Cost threshold per task in USD; 0 disables threshold warnings.',
+  remoteMode: 'Enable remote execution on server 111 for tasks, worktrees, and git operations.',
+  remoteHost: 'Remote server hostname or IP address (e.g. 192.168.1.111).',
+  remotePort: 'Remote SSH port (default: 22).',
+  remoteUser: 'SSH username on remote server (e.g. migrate or vadim).',
+  remoteAuthType: 'SSH authentication mechanism: key, agent, or password.',
+  remoteKeyPath: 'Path to SSH private key file on local PC (e.g. C:/Users/.../.ssh/key).',
+  remoteSudoUser: 'Linux user to run commands as via sudo -u (e.g. vadim).',
+  remoteRoot: 'Base directory on remote server containing project repositories (/mnt/external/Project/DEV).',
+  remoteServerUrl: 'DSH server URL on 111 (http://192.168.1.111:3080) for unified board state and sessions.',
+  remoteServerToken: 'Authentication token for remote DSH server if required.',
 }
 
 /** Setting key for column WIP limit; not all columns have limits. */
@@ -133,7 +157,11 @@ const WIP_FIELD = {
  */
 export function rootOf(config, cwdOf = () => process.cwd()) {
   const named = String(config?.defaultProjectRoot ?? '').trim()
-  return named !== '' ? { path: named, set: true } : { path: cwdOf(), set: false }
+  if (named !== '') return { path: named, set: true }
+  if (config?.remoteMode && config?.remoteRoot) {
+    return { path: String(config.remoteRoot).trim(), set: true }
+  }
+  return { path: cwdOf(), set: false }
 }
 
 /**

package/lib/cost-telemetry.js

@@ -0,0 +1,146 @@
+/**
+ * Token and cost telemetry integration with @goodandready/dsh-cost-meter (#374).
+ * All functions fail-soft without throwing when cost-meter is absent.
+ */
+
+/**
+ * Check whether @goodandready/dsh-cost-meter plugin is active in current runtime.
+ *
+ * @param {object} ctx - Cordis context
+ * @returns {boolean}
+ */
+export function isCostMeterAvailable(ctx) {
+  if (!ctx || typeof ctx !== 'object') return false
+  try {
+    if (ctx.costMeter || (typeof ctx.get === 'function' && ctx.get('costMeter'))) return true
+    if (ctx.settings && typeof ctx.settings.describe === 'function') {
+      const rows = ctx.settings.describe({ redactSecrets: true })
+      if (Array.isArray(rows) && rows.some((r) => r?.ns === 'dsh-cost-meter')) return true
+    }
+    if (ctx.registry && typeof ctx.registry[Symbol.iterator] === 'function') {
+      for (const [plugin] of ctx.registry) {
+        if (plugin === '@goodandready/dsh-cost-meter' || plugin?.name === '@goodandready/dsh-cost-meter') {
+          return true
+        }
+      }
+    }
+    return false
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Extract aggregated token usage from a session's costByModel projection view.
+ *
+ * @param {object} projectionView - View object from usageByModelProjection
+ * @returns {{
+ *   totalTokens: number,
+ *   uncachedInputTokens: number,
+ *   outputTokens: number,
+ *   cacheReadTokens: number,
+ *   cacheWriteTokens: number,
+ *   turnsCount: number,
+ *   models: Array<string>
+ * }}
+ */
+export function extractSessionUsage(projectionView) {
+  const result = {
+    totalTokens: 0,
+    uncachedInputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    turnsCount: 0,
+    models: [],
+  }
+  if (!projectionView || typeof projectionView !== 'object') return result
+
+  const modelsList = Array.isArray(projectionView.models) ? projectionView.models : []
+  for (const m of modelsList) {
+    const key = (m.provider ? m.provider + '/' : '') + (m.model || '')
+    if (key && !result.models.includes(key)) result.models.push(key)
+    const slots = m.slots && typeof m.slots === 'object' ? m.slots : {}
+    for (const slotKey of Object.keys(slots)) {
+      const b = slots[slotKey] || {}
+      result.uncachedInputTokens += Number(b.uncachedInputTokens) || 0
+      result.outputTokens += Number(b.outputTokens) || 0
+      result.cacheReadTokens += Number(b.cacheReadTokens) || 0
+      result.cacheWriteTokens += Number(b.cacheWriteTokens) || 0
+    }
+  }
+
+  if (Array.isArray(projectionView.turns)) {
+    result.turnsCount = projectionView.turns.length
+    if (result.totalTokens === 0 && projectionView.turns.length > 0) {
+      for (const t of projectionView.turns) {
+        result.uncachedInputTokens += Number(t.uncachedInputTokens) || 0
+        result.outputTokens += Number(t.outputTokens) || 0
+        result.cacheReadTokens += Number(t.cacheReadTokens) || 0
+        result.cacheWriteTokens += Number(t.cacheWriteTokens) || 0
+      }
+    }
+  }
+
+  result.totalTokens = result.uncachedInputTokens + result.outputTokens + result.cacheReadTokens + result.cacheWriteTokens
+  return result
+}
+
+/**
+ * Calculate cost for token usage given rate schedule or fallback tariff.
+ * Default tariff: standard DeepSeek rates ($0.14/M input, $0.28/M output, $0.014/M cache hit).
+ *
+ * @param {{
+ *   usage: object,
+ *   schedule?: object,
+ *   usdRate?: number,
+ *   currency?: string
+ * }} options
+ * @returns {{
+ *   costUsd: number,
+ *   costFormatted: string,
+ *   currency: string
+ * }}
+ */
+export function calculateTokenCost({ usage, schedule, usdRate = 1, currency = '$' }) {
+  if (!usage || typeof usage !== 'object') {
+    return { costUsd: 0, costFormatted: currency + '0.00', currency }
+  }
+
+  const uncachedInput = Number(usage.uncachedInputTokens) || 0
+  const output = Number(usage.outputTokens) || 0
+  const cacheRead = Number(usage.cacheReadTokens) || 0
+  const cacheWrite = Number(usage.cacheWriteTokens) || 0
+
+  const rateInput = Number(schedule?.inputPerMillion ?? schedule?.input) || 0.14
+  const rateOutput = Number(schedule?.outputPerMillion ?? schedule?.output) || 0.28
+  const rateCacheRead = Number(schedule?.cacheReadPerMillion ?? schedule?.cacheHit) || 0.014
+  const rateCacheWrite = Number(schedule?.cacheWritePerMillion) || rateInput
+
+  const costUsd = (uncachedInput * rateInput + output * rateOutput + cacheRead * rateCacheRead + cacheWrite * rateCacheWrite) / 1_000_000
+  const converted = costUsd * (Number(usdRate) > 0 ? Number(usdRate) : 1)
+
+  const costFormatted = currency + (converted < 0.01 && converted > 0 ? '<0.01' : converted.toFixed(2))
+
+  return {
+    costUsd: Math.round(costUsd * 10000) / 10000,
+    costFormatted,
+    currency,
+  }
+}
+
+/**
+ * Check whether task cost exceeds configured budget limit.
+ *
+ * @param {{ costUsd: number, limit: number }} options
+ * @returns {{ exceeded: boolean, limit: number, costUsd: number }}
+ */
+export function checkCostLimit({ costUsd = 0, limit = 0 }) {
+  const numLimit = Number(limit) || 0
+  if (numLimit <= 0) return { exceeded: false, limit: 0, costUsd }
+  return {
+    exceeded: costUsd >= numLimit,
+    limit: numLimit,
+    costUsd,
+  }
+}

package/lib/index.js

@@ -51,7 +51,11 @@ import {
   handleCreateSubtask,
   handleToggleChecklistItem,
   handleCreateTaskPr,
+  handleTaskNudge,
 } from './routes.js'
+import { isCostMeterAvailable } from './cost-telemetry.js'
+import { createRemoteGitRunner, testRemoteConnection, isRemoteMode } from './remote-runner.js'
+import { shouldRelay, relayRequest, testRemoteServer } from './remote-relay.js'
 import { listImportable, importIssue, refreshTask, searchRepos, createProjectTask } from './import.js'
 import {
   runTask, resolveModel, buildStartMessage,
@@ -211,6 +215,7 @@ function urlOf(req) {
 export function apply(ctx, config) {
   let effective = withDefaults(config)
   const getConfig = () => effective
+  const getGitRunner = () => createRemoteGitRunner(getConfig(), defaultGitRunner)
 
   // Settings control live subscriptions: sync intervals and agent tools.
   // Dynamic watcher re-evaluates configurations on change without requiring restart.
@@ -867,28 +872,89 @@ export function apply(ctx, config) {
   /**
    * Return active agent state or undefined if session is inactive.
    */
-  const liveOf = (sessionId) => ctx.agents.get(sessionId)?.status
+  const liveOf = (sessionId) => {
+    try {
+      const a = ctx.agents?.get?.(sessionId);
+      if (!a) return undefined;
+      return {
+        status: a.status || (typeof a.isIdle === 'function' && a.isIdle() ? 'idle' : 'running'),
+        state: a.state || a.lifecycleState,
+        step: a.step || a.currentStep || a.stateDetail || a.activity || '',
+        activity: a.activity || a.statusDetail || '',
+      };
+    } catch {
+      return undefined;
+    }
+  };
 
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
     path: '/dsh-kanban/board',
-    handler: (req, res) => {
+    handler: async (req, res) => {
       if (req.method !== 'GET') { writeJson(res, 405, { error: 'method-not-allowed' }); return }
       if (rejectUntrusted(req, res)) return
+      const cfg = getConfig()
+      if (shouldRelay(cfg)) {
+        const url = urlOf(req)
+        const relayRes = await relayRequest({
+          config: cfg,
+          urlPath: '/dsh-kanban/board' + (url.search || ''),
+          method: 'GET',
+          headers: req.headers,
+        })
+        writeJson(res, relayRes.status, relayRes.body)
+        return
+      }
       const url = urlOf(req)
       reply(res, buildBoard({
         store,
-        config: getConfig(),
+        config: cfg,
         board: url.searchParams.get('board') || 'main',
         repo: url.searchParams.get('repo') || undefined,
         liveOf,
         sync: syncState.snapshot(),
         // Resolved project root passed with board payload for session launch modal.
-        projectRoot: rootOf(getConfig()),
+        projectRoot: rootOf(cfg),
+        costMeterAvailable: isCostMeterAvailable(ctx),
       }))
     },
   }), 'dsh-kanban: board route')
 
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-kanban/remote/test',
+    handler: async (req, res) => {
+      if (req.method !== 'POST') { writeJson(res, 405, { error: 'method-not-allowed' }); return }
+      if (rejectUntrusted(req, res)) return
+      const cfg = getConfig()
+      const sshRes = await testRemoteConnection(cfg)
+      const serverRes = cfg.remoteServerUrl ? await testRemoteServer(cfg) : { ok: false, error: 'no-server-url' }
+      writeJson(res, 200, {
+        remoteMode: isRemoteMode(cfg),
+        ssh: sshRes,
+        server: serverRes,
+      })
+    },
+  }), 'dsh-kanban: remote connection test')
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/api/dsh-kanban/remote/test',
+    handler: async (req, res) => {
+      if (req.method !== 'POST') { writeJson(res, 405, { error: 'method-not-allowed' }); return }
+      if (rejectUntrusted(req, res)) return
+      const cfg = getConfig()
+      const sshRes = await testRemoteConnection(cfg)
+      const serverRes = cfg.remoteServerUrl ? await testRemoteServer(cfg) : { ok: false, error: 'no-server-url' }
+      writeJson(res, 200, {
+        remoteMode: isRemoteMode(cfg),
+        ssh: sshRes,
+        server: serverRes,
+      })
+    },
+  }), 'dsh-kanban: remote connection test alias')
+
+
   // Snapshot endpoint handles both export and import.
   /**
    * Cached identity for Gitea client to avoid redundant API lookups on task claim.
@@ -1211,6 +1277,7 @@ export function apply(ctx, config) {
             workspaceRegistry: ctx.get('workspaceRegistry'),
             force: input?.force === true,
             cleanupTaskWorktree,
+            gitRunner: getGitRunner(),
             config: getConfig(),
             repoDir: rootOf(getConfig()).path,
             cwdOf: () => rootOf(getConfig()).path,
@@ -1223,6 +1290,7 @@ export function apply(ctx, config) {
             task: store.getTask(id),
             file: input?.file,
             discardTaskFile,
+            gitRunner: getGitRunner(),
           })
           if (resObj?.body?.success) {
             eventHub.broadcast('task:change', { taskId: id, action: 'discard', file: input?.file })
@@ -1230,13 +1298,32 @@ export function apply(ctx, config) {
           writeJson(res, resObj.status, resObj.body)
           return
         }
+        if (req.method === 'POST' && (action === 'nudge' || (input && input.action === 'nudge'))) {
+          const resObj = await handleTaskNudge({
+            store,
+            id,
+            prompt: input?.prompt || input?.text,
+            agents: ctx.agents,
+            createMessage: createUserMessage,
+            eventHub,
+          })
+          writeJson(res, resObj.status, resObj.body)
+          return
+        }
         if (req.method === 'GET' && action === 'diff') {
-          const resObj = await handleTaskDiff({ task: store.getTask(id), getTaskDiff, getTaskDiffInspector })
+          const resObj = await handleTaskDiff({
+            task: store.getTask(id),
+            getTaskDiff: (opts) => getTaskDiff({ ...opts, gitRunner: getGitRunner() }),
+            getTaskDiffInspector: (opts) => getTaskDiffInspector({ ...opts, gitRunner: getGitRunner() }),
+          })
           writeJson(res, resObj.status, resObj.body)
           return
         }
         if (req.method === 'GET' && action === 'commits') {
-          const resObj = await handleTaskCommits({ task: store.getTask(id), getTaskCommits })
+          const resObj = await handleTaskCommits({
+            task: store.getTask(id),
+            getTaskCommits: (opts) => getTaskCommits({ ...opts, gitRunner: getGitRunner() }),
+          })
           writeJson(res, resObj.status, resObj.body)
           return
         }
@@ -1246,6 +1333,7 @@ export function apply(ctx, config) {
             targetBranch: input?.targetBranch,
             workspaceRegistry: ctx.get('workspaceRegistry'),
             mergeTaskWorktree,
+            gitRunner: getGitRunner(),
           })
           writeJson(res, resObj.status, resObj.body)
           return

package/lib/remote-relay.js

@@ -0,0 +1,149 @@
+/**
+ * Remote DSH server relay client (#390).
+ * Proxies board state, task actions, and sessions between PC client and server 111.
+ * Zero Cyrillic literals in lib/ according to Issue #366 standard.
+ */
+
+/**
+ * Check whether requests should be relayed to remote DSH server.
+ *
+ * @param {object} config
+ * @returns {boolean}
+ */
+export function shouldRelay(config) {
+  return Boolean(config && config.remoteMode && config.remoteServerUrl)
+}
+
+/**
+ * Resolve target URL on remote DSH server.
+ *
+ * @param {object} config
+ * @param {string} path
+ * @returns {string}
+ */
+export function getRemoteServerUrl(config, path = '') {
+  const base = String(config?.remoteServerUrl || 'http://192.168.1.111:3080').trim().replace(/\/+$/, '')
+  const cleanPath = path ? (path.startsWith('/') ? path : '/' + path) : ''
+  return `${base}${cleanPath}`
+}
+
+/**
+ * Build request headers including DSH auth token and cookies.
+ *
+ * @param {object} config
+ * @param {object} [originalHeaders]
+ * @returns {Record<string, string>}
+ */
+export function buildRemoteHeaders(config, originalHeaders = {}) {
+  const headers = {
+    'Accept': 'application/json, text/plain, */*',
+  }
+
+  if (originalHeaders && typeof originalHeaders === 'object') {
+    if (originalHeaders['content-type']) {
+      headers['Content-Type'] = originalHeaders['content-type']
+    }
+  }
+
+  const token = String(config?.remoteServerToken || '').trim()
+  if (token) {
+    headers['Authorization'] = `Bearer ${token}`
+    headers['Cookie'] = `dsh_token=${token}`
+  }
+
+  return headers
+}
+
+/**
+ * Relay an HTTP request to remote DSH server.
+ *
+ * @param {{
+ *   config: object,
+ *   path: string,
+ *   method?: string,
+ *   body?: any,
+ *   headers?: object,
+ *   timeoutMs?: number
+ * }} options
+ * @returns {Promise<{ status: number, body: any, headers?: object }>}
+ */
+export async function relayRequest({ config, path, urlPath, method = 'GET', body, headers, timeoutMs = 15000 }) {
+  const targetPath = urlPath || path || ''
+  const url = getRemoteServerUrl(config, targetPath)
+  const reqHeaders = buildRemoteHeaders(config, headers)
+
+  const fetchOptions = {
+    method,
+    headers: reqHeaders,
+    signal: AbortSignal.timeout(timeoutMs),
+  }
+
+  if (body !== undefined && body !== null && method !== 'GET' && method !== 'HEAD') {
+    if (typeof body === 'string') {
+      fetchOptions.body = body
+      if (!fetchOptions.headers['Content-Type']) {
+        fetchOptions.headers['Content-Type'] = 'application/json'
+      }
+    } else {
+      fetchOptions.body = JSON.stringify(body)
+      fetchOptions.headers['Content-Type'] = 'application/json'
+    }
+  }
+
+  try {
+    const res = await fetch(url, fetchOptions)
+    const contentType = res.headers.get('content-type') || ''
+    let parsedBody
+    if (contentType.includes('application/json')) {
+      parsedBody = await res.json()
+    } else {
+      parsedBody = await res.text()
+    }
+
+    return {
+      status: res.status,
+      body: parsedBody,
+    }
+  } catch (err) {
+    return {
+      status: 503,
+      body: {
+        error: 'remote-server-unavailable',
+        detail: `Failed to reach remote DSH server at ${url}: ${err.message}`,
+      },
+    }
+  }
+}
+
+/**
+ * Probe remote DSH server connection and kanban board endpoint.
+ *
+ * @param {object} config
+ * @returns {Promise<{ ok: boolean, latencyMs?: number, status?: number, error?: string }>}
+ */
+export async function testRemoteServer(config) {
+  const startTime = Date.now()
+  const res = await relayRequest({
+    config,
+    urlPath: '/dsh-kanban/board',
+    method: 'GET',
+    timeoutMs: 8000,
+  })
+
+  const latencyMs = Date.now() - startTime
+
+  if (res.status === 200) {
+    return {
+      ok: true,
+      latencyMs,
+      status: res.status,
+    }
+  }
+
+  return {
+    ok: false,
+    latencyMs,
+    status: res.status,
+    error: res.body?.detail || res.body?.error || `HTTP ${res.status}`,
+  }
+}

package/lib/remote-runner.js

@@ -0,0 +1,164 @@
+/**
+ * Remote SSH runner for git and worktree operations (#390).
+ * Allows DSH running on PC (Windows) to execute commands on remote server (111).
+ * Zero Cyrillic literals in lib/ according to Issue #366 standard.
+ */
+
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+/**
+ * Check whether remote execution mode is enabled in config.
+ *
+ * @param {object} config
+ * @returns {boolean}
+ */
+export function isRemoteMode(config) {
+  return Boolean(config && config.remoteMode)
+}
+
+/**
+ * Quote argument safely for remote POSIX shell execution.
+ *
+ * @param {string|number} s
+ * @returns {string}
+ */
+export function quoteArg(s) {
+  return "'" + String(s ?? '').replace(/'/g, "'\\''") + "'"
+}
+
+/**
+ * Build arguments array for SSH CLI process.
+ *
+ * @param {object} config
+ * @param {string} remoteCommand
+ * @returns {string[]}
+ */
+export function buildSshArgs(config, remoteCommand) {
+  const host = String(config?.remoteHost || '192.168.1.111').trim()
+  const port = Number(config?.remotePort) || 22
+  const user = String(config?.remoteUser || 'migrate').trim()
+  const keyPath = String(config?.remoteKeyPath || '').trim()
+  const sudoUser = config?.remoteSudoUser !== undefined ? String(config.remoteSudoUser).trim() : 'vadim'
+
+  const args = [
+    '-p', String(port),
+    '-o', 'BatchMode=yes',
+    '-o', 'StrictHostKeyChecking=accept-new',
+    '-o', 'ConnectTimeout=10',
+  ]
+
+  if (keyPath) {
+    args.push('-i', keyPath)
+  }
+
+  const target = `${user}@${host}`
+  args.push(target)
+
+  let fullCmd = remoteCommand
+  if (sudoUser) {
+    fullCmd = `sudo -u ${sudoUser} -H bash -c ${quoteArg(remoteCommand)}`
+  }
+
+  args.push(fullCmd)
+  return args
+}
+
+/**
+ * Create a git runner function that delegates to remote host over SSH when remoteMode is active.
+ * Conforms to (args, cwd) => Promise<{ stdout: string, stderr: string }>.
+ *
+ * @param {object} config
+ * @param {Function} [localGitRunner] fallback local runner
+ * @returns {Function}
+ */
+export function createRemoteGitRunner(config, localGitRunner) {
+  return async function remoteGitRunner(args, cwd) {
+    if (!isRemoteMode(config)) {
+      if (typeof localGitRunner === 'function') {
+        return localGitRunner(args, cwd)
+      }
+      throw new Error('[dsh-kanban] No local git runner available in non-remote mode')
+    }
+
+    const escapedArgs = (Array.isArray(args) ? args : []).map(quoteArg).join(' ')
+    const cdPart = cwd ? `cd ${quoteArg(cwd)} && ` : ''
+    const gitCmd = `${cdPart}git ${escapedArgs}`
+    const sshArgs = buildSshArgs(config, gitCmd)
+
+    try {
+      const { stdout, stderr } = await execFileAsync('ssh', sshArgs, {
+        maxBuffer: 10 * 1024 * 1024,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0', LC_ALL: 'C' },
+      })
+      return { stdout: stdout ?? '', stderr: stderr ?? '' }
+    } catch (err) {
+      const error = new Error(`[dsh-kanban-remote] git ${args?.[0] || ''} failed on ${config?.remoteHost || 'remote'}: ${err.message}`)
+      error.code = err.code ?? 1
+      error.stdout = err.stdout ?? ''
+      error.stderr = err.stderr ?? err.message ?? ''
+      throw error
+    }
+  }
+}
+
+/**
+ * Check connectivity to remote server and verify remote root directory.
+ *
+ * @param {object} config
+ * @returns {Promise<{ ok: boolean, latencyMs?: number, remoteRootFound?: boolean, error?: string }>}
+ */
+export async function testRemoteConnection(config) {
+  const root = String(config?.remoteRoot || '/mnt/external/Project/DEV').trim()
+  const probeCmd = `test -d ${quoteArg(root)} && echo REMOTE_ROOT_OK || echo REMOTE_ROOT_MISSING`
+  const sshArgs = buildSshArgs(config, probeCmd)
+
+  const startTime = Date.now()
+  try {
+    const { stdout } = await execFileAsync('ssh', sshArgs, {
+      maxBuffer: 1024 * 1024,
+      timeout: 12000,
+      env: { ...process.env, LC_ALL: 'C' },
+    })
+    const latencyMs = Date.now() - startTime
+    const trimmed = (stdout || '').trim()
+    const remoteRootFound = trimmed.includes('REMOTE_ROOT_OK')
+
+    return {
+      ok: true,
+      latencyMs,
+      remoteRootFound,
+    }
+  } catch (err) {
+    return {
+      ok: false,
+      error: err.stderr ? err.stderr.trim() : err.message,
+    }
+  }
+}
+
+/**
+ * Check if path exists on remote host.
+ *
+ * @param {string} remotePath
+ * @param {object} config
+ * @returns {Promise<boolean>}
+ */
+export async function remotePathExists(remotePath, config) {
+  if (!remotePath) return false
+  const probeCmd = `test -e ${quoteArg(remotePath)} && echo 1 || echo 0`
+  const sshArgs = buildSshArgs(config, probeCmd)
+
+  try {
+    const { stdout } = await execFileAsync('ssh', sshArgs, {
+      maxBuffer: 1024 * 1024,
+      timeout: 10000,
+      env: { ...process.env, LC_ALL: 'C' },
+    })
+    return (stdout || '').trim() === '1'
+  } catch {
+    return false
+  }
+}