@tiphareth/dsh-hardssh 0.1.2 → 0.2.3

package/src/ssh/store.ts

@@ -29,6 +29,75 @@ interface StoreFile {
   hosts: SshHostEntry[]
 }
 
+/** One parsed Host block from `~/.ssh/config`. */
+interface SshConfigBlock {
+  pattern: string
+  props: Record<string, string>
+}
+
+/** Parse `~/.ssh/config` into importable candidate payloads. Pure (no store
+ *  writes): the caller applies each candidate through ITS OWN create, so the
+ *  plaintext `HostStore` and the secret-aware `SecureHostStore` share one
+ *  parser while differing only in how an entry's secrets are stored. */
+function parseSshConfigToImport(configPath: string): {
+  candidates: HostPayload[]
+  /** Wildcard / no-HostName patterns (reported as skipped, not importable). */
+  invalidNames: string[]
+  /** Total Host blocks parsed (including non-importable ones). */
+  totalBlocks: number
+} {
+  const lines = readFileSync(configPath, 'utf8').split(/\r?\n/)
+  const blocks: SshConfigBlock[] = []
+  let current: SshConfigBlock | undefined
+  for (const raw of lines) {
+    const line = raw.trim()
+    if (line === '' || line.startsWith('#')) continue
+    const match = /^([A-Za-z0-9_\-]+)\s+(.+)$/.exec(line)
+    if (match === null) continue
+    const key = match[1].toLowerCase()
+    const value = match[2].trim()
+    if (key === 'host') {
+      current = { pattern: value, props: {} }
+      blocks.push(current)
+    } else if (current !== undefined) {
+      current.props[key] = value
+    }
+  }
+  const candidates: HostPayload[] = []
+  const invalidNames: string[] = []
+  for (const block of blocks) {
+    const pattern = block.pattern.split(/\s+/)[0]
+    if (pattern.includes('*') || pattern.includes('?')) {
+      if (pattern !== '') invalidNames.push(pattern)
+      continue
+    }
+    const hostName = block.props.hostname
+    if (hostName === undefined || hostName === '') {
+      if (pattern !== '') invalidNames.push(pattern)
+      continue
+    }
+    candidates.push({
+      alias: pattern,
+      host: hostName,
+      port: block.props.port !== undefined ? Number.parseInt(block.props.port, 10) : 22,
+      user: block.props.user ?? process.env.USER ?? 'root',
+      auth: {
+        kind: block.props.identityfile !== undefined ? 'key' : 'password',
+        keyPath: block.props.identityfile,
+        password: block.props.password,
+      },
+      proxyJump: block.props.proxyjump !== undefined
+        ? block.props.proxyjump.split(',').map(hop => hop.trim()).filter(hop => hop !== '')
+        : [],
+      description: block.props.description,
+      environment: block.props.environment,
+      tags: (block.props.tags ?? '').split(',').map(tag => tag.trim()).filter(tag => tag !== ''),
+      location: block.props.location,
+    })
+  }
+  return { candidates, invalidNames, totalBlocks: blocks.length }
+}
+
 /** Payload shape the validator enforces: full create vs partial patch. */
 export type HostPayloadValidationMode = 'create' | 'patch'
 
@@ -151,6 +220,11 @@ export class HostStore {
     return file.hosts
   }
 
+  /** The ssh-config path this store reads (override or the default). */
+  get sshConfigOverridePath(): string | undefined {
+    return this.sshConfigOverride
+  }
+
   /** Find one entry by alias. */
   find(alias: string): SshHostEntry | undefined {
     return this.list().find(entry => entry.alias === alias)
@@ -290,7 +364,8 @@ export class HostStore {
   /**
    * Import hosts from `~/.ssh/config`: Host blocks with a single non-wildcard
    * pattern and a HostName become entries (key auth via IdentityFile, jump
-   * hosts via ProxyJump). Existing aliases are skipped.
+   * hosts via ProxyJump). Existing aliases are skipped. Each entry is created
+   * through this store's own `create`, which keeps plaintext secrets inline.
    * @returns import statistics.
    */
   importFromSshConfig(): ImportResult {
@@ -298,73 +373,24 @@ export class HostStore {
     this.skippedNames = new Set<string>()
     const configPath = this.sshConfigOverride ?? sshConfigPath()
     if (!existsSync(configPath)) return { parsed: 0, added: 0, skipped: 0, skippedNames: [] }
-    const lines = readFileSync(configPath, 'utf8').split(/\r?\n/)
-    const blocks: { pattern: string; props: Record<string, string> }[] = []
-    let current: { pattern: string; props: Record<string, string> } | undefined
-    const skip = (name: string, seen: Set<string>): void => {
-      if (name !== '' && !seen.has(name)) {
-        seen.add(name)
-        this.skippedNames.add(name)
-      }
-    }
-    for (const raw of lines) {
-      const line = raw.trim()
-      if (line === '' || line.startsWith('#')) continue
-      const match = /^([A-Za-z0-9_\-]+)\s+(.+)$/.exec(line)
-      if (match === null) continue
-      const key = match[1].toLowerCase()
-      const value = match[2].trim()
-      if (key === 'host') {
-        current = { pattern: value, props: {} }
-        blocks.push(current)
-      } else if (current !== undefined) {
-        current.props[key] = value
-      }
-    }
+    const { candidates, invalidNames, totalBlocks } = parseSshConfigToImport(configPath)
+    for (const name of invalidNames) this.skippedNames.add(name)
     let added = 0
-    for (const block of blocks) {
-      const pattern = block.pattern.split(/\s+/)[0]
-      if (pattern.includes('*') || pattern.includes('?')) {
-        skip(pattern, this.skippedNames)
-        continue
-      }
-      const hostName = block.props.hostname
-      if (hostName === undefined || hostName === '') {
-        skip(pattern, this.skippedNames)
-        continue
-      }
-      const existing = this.list().some(entry => entry.alias === pattern)
-      if (existing) {
-        skip(pattern, this.skippedNames)
+    for (const payload of candidates) {
+      const alias = payload.alias ?? ''
+      if (alias !== '' && this.list().some(entry => entry.alias === alias)) {
+        this.skippedNames.add(alias)
         continue
       }
-      const payload: HostPayload = {
-        alias: pattern,
-        host: hostName,
-        port: block.props.port !== undefined ? Number.parseInt(block.props.port, 10) : 22,
-        user: block.props.user ?? process.env.USER ?? 'root',
-        auth: {
-          kind: block.props.identityfile !== undefined ? 'key' : 'password',
-          keyPath: block.props.identityfile,
-          password: block.props.password,
-        },
-        proxyJump: block.props.proxyjump !== undefined
-          ? block.props.proxyjump.split(',').map(hop => hop.trim()).filter(hop => hop !== '')
-          : [],
-        description: block.props.description,
-        environment: block.props.environment,
-        tags: (block.props.tags ?? '').split(',').map(tag => tag.trim()).filter(tag => tag !== ''),
-        location: block.props.location,
-      }
       try {
         this.create(payload)
         added += 1
       } catch {
         // Unusable entry (bad alias grammar etc.) — count as skipped.
-        skip(pattern, this.skippedNames)
+        if (alias !== '') this.skippedNames.add(alias)
       }
     }
-    return { parsed: blocks.length, added, skipped: this.skippedNames.size, skippedNames: [...this.skippedNames] }
+    return { parsed: totalBlocks, added, skipped: this.skippedNames.size, skippedNames: [...this.skippedNames] }
   }
 
   private skippedNames = new Set<string>()
@@ -426,13 +452,15 @@ export interface ResolvedAuth {
  *
  * - **'none' (default, VSCode Remote-SSH style)**: secrets are NEVER
  *   persisted. create/update strip the password/passphrase from the entry
- *   (kind + keyPath stay); the engine prompts once per session and holds the
- *   credential in-memory (session password table). The plaintext HostStore
+ *   (kind + keyPath stay); the engine prompts once and holds the credential
+ *   in-memory for that CONNECTION's lifetime (the pool's retirement drops it).
+ *   The plaintext HostStore
  *   remains untouched, so existing v1 tests and dual-format reads keep
  *   working.
  */
 export class SecureHostStore {
   private readonly inner: HostStore
+  private readonly pendingSecretCleanup = new Set<string>()
 
   constructor(
     private readonly vault: import('./vault.ts').Vault | undefined,
@@ -447,20 +475,71 @@ export class SecureHostStore {
   find(alias: string): SshHostEntry | undefined { return this.inner.find(alias) }
   summarize(entry: SshHostEntry): SshHostSummary { return this.inner.summarize(entry) }
   get path(): string { return this.inner.path }
-  /** Legacy ssh-config import (delegates; passwords imported stay inline —
-   *  a follow-up may route them through the vault). */
-  importFromSshConfig(): ImportResult { return this.inner.importFromSshConfig() }
+  /** The ssh-config path the underlying store reads (override or default). */
+  get sshConfigOverridePath(): string | undefined { return this.inner.sshConfigOverridePath }
+
+  /** ssh-config import routed through THIS store's `create`, so every imported
+   *  credential is handled per `secretStorage` (never persisted in 'none' mode,
+   *  vault-encrypted in 'vault' mode) instead of being stored inline. */
+  async importFromSshConfig(): Promise<ImportResult> {
+    const configPath = this.inner.sshConfigOverridePath ?? sshConfigPath()
+    if (!existsSync(configPath)) return { parsed: 0, added: 0, skipped: 0, skippedNames: [] }
+    const { candidates, invalidNames, totalBlocks } = parseSshConfigToImport(configPath)
+    const skipped = new Set<string>(invalidNames.filter(name => name !== ''))
+    let added = 0
+    for (const payload of candidates) {
+      const alias = payload.alias ?? ''
+      if (alias !== '' && this.inner.list().some(entry => entry.alias === alias)) {
+        skipped.add(alias)
+        continue
+      }
+      try {
+        await this.create(payload)
+        added += 1
+      } catch {
+        if (alias !== '') skipped.add(alias)
+      }
+    }
+    return { parsed: totalBlocks, added, skipped: skipped.size, skippedNames: [...skipped] }
+  }
+
+  /** Deferred best-effort cleanup queue (diagnostics/tests; contains no plaintext). */
+  pendingSecretCleanupRefs(): string[] { return [...this.pendingSecretCleanup] }
+
+  private async removeSecret(ref: string): Promise<unknown | undefined> {
+    if (this.vault === undefined) return undefined
+    try {
+      await this.vault.remove(ref)
+      this.pendingSecretCleanup.delete(ref)
+      return undefined
+    } catch (error) {
+      this.pendingSecretCleanup.add(ref)
+      return error
+    }
+  }
+
+  private async retryPendingCleanup(): Promise<void> {
+    for (const ref of [...this.pendingSecretCleanup]) await this.removeSecret(ref)
+  }
 
-  /** Create: secrets are stashed per mode; entry only keeps kind (+ keyPath). */
+  /** Create: secrets are staged, then rolled back if host persistence fails. */
   async create(payload: HostPayload): Promise<SshHostEntry> {
     // Validate the raw wire input first. In 'none' mode a password-kind host
     // may omit the password (typed at connect time, VSCode-style); 'vault'
     // mode keeps the strict rule so every credential gets stashed.
     const rawError = validateHostPayload(payload, 'create', this.mode === 'none')
     if (rawError !== undefined) throw new Error(rawError)
+    await this.retryPendingCleanup()
     const ref = await this.stashSecrets(payload.alias ?? '', payload.auth)
-    const entry = this.inner.create(stripSecrets(payload, ref, this.mode), true)
-    return entry
+    try {
+      return this.inner.create(stripSecrets(payload, ref, this.mode), true)
+    } catch (error) {
+      if (ref !== undefined) {
+        const cleanupError = await this.removeSecret(ref)
+        if (cleanupError !== undefined) throw new AggregateError([error, cleanupError], 'host create failed and staged vault secret rollback failed')
+      }
+      throw error
+    }
   }
 
   /** Update: auth present -> re-stash (or strip in none mode); absent → keep. */
@@ -480,18 +559,36 @@ export class SecureHostStore {
         && existing.auth.secretRef !== undefined
       if (!keepOldRef) throw new Error(rawError)
     }
+    await this.retryPendingCleanup()
     const ref = await this.stashSecrets(alias, patch.auth)
-    const effectiveRef = ref ?? (this.mode === 'vault' ? existing.auth.secretRef : undefined)
-    return this.inner.update(alias, stripSecrets(patch, effectiveRef, this.mode), true)
+    const sameCredential = patch.auth.kind === existing.auth.kind
+      && (patch.auth.kind === 'password'
+        || (patch.auth.keyPath === undefined || expandHome(patch.auth.keyPath.trim()) === existing.auth.keyPath))
+    const effectiveRef = ref ?? (this.mode === 'vault' && sameCredential ? existing.auth.secretRef : undefined)
+    let updated: SshHostEntry
+    try {
+      updated = this.inner.update(alias, stripSecrets(patch, effectiveRef, this.mode), true)
+    } catch (error) {
+      if (ref !== undefined) {
+        const cleanupError = await this.removeSecret(ref)
+        if (cleanupError !== undefined) throw new AggregateError([error, cleanupError], 'host update failed and staged vault secret rollback failed')
+      }
+      throw error
+    }
+    if (existing.auth.secretRef !== undefined && existing.auth.secretRef !== effectiveRef) {
+      // Host persistence is committed. Cleanup failure is deferred and must not
+      // make callers retry an already-applied host update.
+      await this.removeSecret(existing.auth.secretRef)
+    }
+    return updated
   }
 
-  /** Delete: drop the host (and its vault secrets in vault mode, best-effort). */
+  /** Delete the host first; vault cleanup can then only leave an orphan. */
   async delete(alias: string): Promise<void> {
+    await this.retryPendingCleanup()
     const entry = this.inner.find(alias)
-    if (entry !== undefined && entry.auth.secretRef !== undefined && this.vault !== undefined) {
-      await this.vault.remove(entry.auth.secretRef).catch(() => undefined)
-    }
     this.inner.delete(alias)
+    if (entry?.auth.secretRef !== undefined) await this.removeSecret(entry.auth.secretRef)
   }
 
   /** Resolve the authentication for one entry (vault reveal when needed). */

package/src/ssh/terminal/service.ts

@@ -0,0 +1,177 @@
+import type { Client, ClientChannel } from 'ssh2'
+import type { ExecSession, ShellSession } from '../engine.ts'
+
+/** A fresh SSH channel (shell/exec) must open within this budget; a dead or
+ *  half-open connection would otherwise leave the open promise hanging. */
+const CHANNEL_OPEN_TIMEOUT_MS = 10_000
+
+/**
+ * Narrow connection dependency used by the standalone terminal transports.
+ * `connectStandalone` must reach the store itself (the not-found wording is
+ * this component's own contract) and must always return a PRIVATE connection
+ * — never a pooled one.
+ */
+export interface TerminalConnectionAccess {
+  connectStandalone(alias: string): Promise<{ client: Client; hops: Client[] }>
+}
+
+/**
+ * Owns the standalone PTY-shell / streaming-exec transports: one exclusive
+ * connection per session (closing a shell can therefore never tear down a
+ * pooled exec or tunnel sharing the alias), the channel-open deadline,
+ * idempotent teardown and session assembly.
+ */
+export class TerminalService {
+  /** Teardowns of live standalone transports, so dispose() can close sessions
+   *  that the caller never closed explicitly (openShell/openExec own their
+   *  whole connection and would otherwise outlive the engine). */
+  private readonly activeTeardowns = new Set<() => void>()
+
+  constructor(private readonly connection: TerminalConnectionAccess) {}
+
+  /**
+   * Open one standalone channel on its own connection (never a pooled one).
+   * Shared by openShell/openExec: alias lookup, jump chain, channel-open
+   * timeout, idempotent teardown, and late-callback cleanup live here, so the
+   * two public methods keep only their session-specific assembly.
+   */
+  private async openStandaloneChannel(
+    alias: string,
+    open: (client: Client, callback: (error: Error | undefined, stream?: ClientChannel) => void) => void,
+  ): Promise<{ stream: ClientChannel; teardown: () => void }> {
+    const { client, hops } = await this.connection.connectStandalone(alias)
+    return await new Promise<{ stream: ClientChannel; teardown: () => void }>((resolve, reject) => {
+      let settled = false
+      let tornDown = false
+      const teardown = (): void => {
+        if (tornDown) return
+        tornDown = true
+        this.activeTeardowns.delete(teardown)
+        try { client.end() } catch { /* closed */ }
+        for (const hop of hops) { try { hop.end() } catch { /* closed */ } }
+      }
+      this.activeTeardowns.add(teardown)
+      const timer = setTimeout(() => {
+        if (settled) return
+        settled = true
+        teardown()
+        reject(new Error(`channel on '${alias}' did not open within ${CHANNEL_OPEN_TIMEOUT_MS} ms`))
+      }, CHANNEL_OPEN_TIMEOUT_MS)
+      timer.unref?.()
+      open(client, (error, stream) => {
+        if (settled) {
+          // Late arrival after the timeout: the connection is being torn
+          // down; close any channel that finally opened instead of leaking it.
+          if (stream !== undefined) {
+            try { stream.close() } catch { /* already closed */ }
+          }
+          teardown()
+          return
+        }
+        settled = true
+        clearTimeout(timer)
+        if (error !== undefined) {
+          teardown()
+          reject(error)
+          return
+        }
+        if (stream === undefined) {
+          teardown()
+          reject(new Error(`channel on '${alias}' opened without a stream`))
+          return
+        }
+        resolve({ stream, teardown })
+      })
+    })
+  }
+
+  /** Open a PTY shell session for the web terminal (standalone connection). */
+  async openShell(alias: string, size: { cols: number; rows: number }): Promise<ShellSession> {
+    // The shell is a long-lived exclusive stream: use its own connection so
+    // closing it can never tear down a pooled exec/tunnel sharing the alias.
+    const { stream, teardown } = await this.openStandaloneChannel(alias, (client, callback) => {
+      client.shell({ term: 'xterm-256color', cols: size.cols, rows: size.rows }, callback)
+    })
+    const session: ShellSession = {
+      send: (data) => { try { stream.write(data) } catch { /* channel gone */ } },
+      resize: (cols, rows) => { try { stream.setWindow(rows, cols, rows, cols) } catch { /* channel gone */ } },
+      signal: (name) => { try { stream.signal(name) } catch { /* channel gone */ } },
+      close: () => {
+        try { stream.close() } catch { /* channel gone */ }
+        teardown()
+      },
+      pause: () => { try { stream.pause() } catch { /* channel gone */ } },
+      resume: () => { try { stream.resume() } catch { /* channel gone */ } },
+    }
+    stream.on('data', (chunk: Buffer) => { session.onData?.(chunk) })
+    stream.on('close', (code: number | null) => {
+      teardown()
+      session.onExit?.(code)
+    })
+    stream.on('error', (streamError: Error) => {
+      teardown()
+      session.onExit?.(null, streamError instanceof Error ? streamError.message : String(streamError))
+    })
+    return session
+  }
+
+  /**
+   * Open a streaming exec channel (no PTY) for the remote subprocess seam.
+   * Like the PTY shell, the channel rides its own connection so closing it
+   * can never tear down a pooled exec/tunnel sharing the alias.
+   */
+  async openExec(alias: string, command: string): Promise<ExecSession> {
+    const { stream, teardown } = await this.openStandaloneChannel(alias, (client, callback) => {
+      client.exec(command, callback)
+    })
+    let exitListener: ExecSession['onExit']
+    let exitRecord: { code: number | null; error?: string } | undefined
+    let exitDelivered = false
+    const deliverExit = (): void => {
+      if (exitDelivered || exitRecord === undefined || exitListener === undefined) return
+      exitDelivered = true
+      exitListener(exitRecord.code, exitRecord.error)
+    }
+    const finish = (code: number | null, error?: string): void => {
+      if (exitRecord !== undefined) return
+      exitRecord = error === undefined ? { code } : { code, error }
+      teardown()
+      deliverExit()
+    }
+    const session: ExecSession = {
+      stdin: stream,
+      send: (data) => { try { stream.write(data) } catch { /* channel gone */ } },
+      end: (data) => {
+        try {
+          if (data !== undefined && data !== '') stream.write(data)
+          stream.end()
+        } catch { /* channel gone */ }
+      },
+      get onExit() { return exitListener },
+      set onExit(listener) {
+        exitListener = listener
+        deliverExit()
+      },
+      resize: () => { /* exec channels have no PTY */ },
+      signal: (name) => { try { stream.signal(name) } catch { /* channel gone */ } },
+      close: () => {
+        try { stream.close() } catch { /* channel gone */ }
+        teardown()
+      },
+      pause: () => { try { stream.pause() } catch { /* channel gone */ } },
+      resume: () => { try { stream.resume() } catch { /* channel gone */ } },
+    }
+    stream.on('data', (chunk: Buffer) => { session.onData?.(chunk) })
+    stream.stderr.on('data', (chunk: Buffer) => { session.onErrData?.(chunk) })
+    stream.on('close', (code: number | null) => { finish(code) })
+    stream.on('error', (streamError: Error) => {
+      finish(null, streamError instanceof Error ? streamError.message : String(streamError))
+    })
+    return session
+  }
+
+  /** Close every standalone transport this service still owns. */
+  dispose(): void {
+    for (const teardown of [...this.activeTeardowns]) teardown()
+  }
+}

package/src/ssh/tools.ts

@@ -13,6 +13,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { SshEngine } from './engine.ts'
+import { secureLocalTransferPath } from './local-transfer-policy.ts'
 import type { ClusterResult, ExecResult, SshHostSummary, TunnelInfo } from './protocol.ts'
 
 /**
@@ -23,15 +24,23 @@ export type ToolEnvelope<T extends object> =
   | ({ ok: true } & T)
   | { ok: false; error: string }
 
-/** Run one tool operation and fold every thrown error into a failure envelope. */
+/** Run one tool operation and fold every thrown error into a failure envelope.
+ *
+ *  The message passes the engine's leak guard before it reaches the model: a
+ *  rejected connect/resolve can embed a credential, and this envelope is the
+ *  one place every tool's failure text is produced. */
 async function captureToolResult<T extends object>(
+  engine: Pick<SshEngine, 'redact'>,
   operation: () => T | Promise<T>,
 ): Promise<ToolEnvelope<T>> {
   try {
     const value = await operation()
     return { ok: true, ...value }
   } catch (error) {
-    return { ok: false, error: error instanceof Error ? error.message : String(error) }
+    const message = error instanceof Error ? error.message : String(error)
+    // Tolerate engine doubles that predate the redactor (tests inject minimal
+    // fakes); the production engine always provides it.
+    return { ok: false, error: typeof engine.redact === 'function' ? engine.redact(message) : message }
   }
 }
 
@@ -135,7 +144,7 @@ export function sshListTool(engine: SshEngine) {
       },
     },
     async execute(args) {
-      return captureToolResult(() => ({ hosts: engine.list(args.query) }))
+      return captureToolResult(engine, () => ({ hosts: engine.list(args.query) }))
     },
   })
 }
@@ -149,7 +158,7 @@ export function sshExecTool(engine: SshEngine) {
     parameters: {
       alias: { type: 'string', required: true, description: 'Host alias from ssh_list.' },
       command: { type: 'string', required: true, description: 'The shell command to run remotely.' },
-      timeoutMs: { type: 'integer', description: 'Timeout in milliseconds (default 60000).' },
+      timeoutMs: { type: 'integer', description: 'Timeout in milliseconds (default 60000). Enforced on the server as well (coreutils timeout), so a timed-out command is stopped instead of left running.' },
     },
     output: {
       schema: {
@@ -172,7 +181,7 @@ export function sshExecTool(engine: SshEngine) {
       },
     },
     async execute(args) {
-      return captureToolResult(() => engine.exec(args.alias, args.command, args.timeoutMs))
+      return captureToolResult(engine, () => engine.exec(args.alias, args.command, args.timeoutMs))
     },
   })
 }
@@ -181,11 +190,11 @@ export function sshExecTool(engine: SshEngine) {
 export function sshUploadTool(engine: SshEngine) {
   return defineTool({
     name: 'ssh_upload',
-    description: 'Upload a local file to a configured SSH host. The local path is on THIS machine (the dsh host). ' +
+    description: 'Upload a local file from the invoking session workspace to a configured SSH host. Local paths outside that workspace are rejected. ' +
       'Triggers: upload file to server, deploy artifact, copy config to server.',
     parameters: {
       alias: { type: 'string', required: true, description: 'Host alias from ssh_list.' },
-      localPath: { type: 'string', required: true, description: 'Absolute local file path on this machine.' },
+      localPath: { type: 'string', required: true, description: 'Absolute source path inside the invoking session workspace.' },
       remotePath: { type: 'string', required: true, description: 'Destination path on the remote host (parent dirs are created).' },
     },
     output: {
@@ -204,9 +213,10 @@ export function sshUploadTool(engine: SshEngine) {
         return text(`uploaded ${value.files ?? 1} file(s), ${value.transferredBytes ?? 0} bytes`)
       },
     },
-    async execute(args) {
-      return captureToolResult(async () => {
-        const outcome = await engine.upload(args.alias, args.localPath, args.remotePath, false)
+    async execute(args, exec) {
+      return captureToolResult(engine, async () => {
+        const source = secureLocalTransferPath(exec, args.localPath, 'upload-source')
+        const outcome = await engine.upload(args.alias, source, args.remotePath, false)
         return { transferredBytes: outcome.bytes, files: outcome.files }
       })
     },
@@ -217,12 +227,12 @@ export function sshUploadTool(engine: SshEngine) {
 export function sshDownloadTool(engine: SshEngine) {
   return defineTool({
     name: 'ssh_download',
-    description: 'Download a remote FILE from a configured SSH host to a local path on this machine. Directory download is not supported — download files individually. ' +
+    description: 'Download a remote FILE into the invoking session workspace. Local paths outside that workspace are rejected; directory download is unsupported. ' +
       'Triggers: download file from server, fetch remote log/artifact.',
     parameters: {
       alias: { type: 'string', required: true, description: 'Host alias from ssh_list.' },
       remotePath: { type: 'string', required: true, description: 'Remote file path.' },
-      localPath: { type: 'string', required: true, description: 'Absolute destination path on this machine.' },
+      localPath: { type: 'string', required: true, description: 'Absolute destination path inside the invoking session workspace.' },
     },
     output: {
       schema: {
@@ -239,9 +249,10 @@ export function sshDownloadTool(engine: SshEngine) {
         return text(`downloaded ${value.bytes ?? 0} bytes`)
       },
     },
-    async execute(args) {
-      return captureToolResult(async () => {
-        const outcome = await engine.download(args.alias, args.remotePath, args.localPath)
+    async execute(args, exec) {
+      return captureToolResult(engine, async () => {
+        const destination = secureLocalTransferPath(exec, args.localPath, 'download-destination')
+        const outcome = await engine.download(args.alias, args.remotePath, destination)
         return { bytes: outcome.bytes }
       })
     },
@@ -315,7 +326,7 @@ export function sshTunnelTool(engine: SshEngine) {
     },
     async execute(args) {
       if (args.action === 'list') {
-        return captureToolResult(() => ({ tunnels: engine.listTunnels() }))
+        return captureToolResult(engine, () => ({ tunnels: engine.listTunnels() }))
       }
       if (args.action === 'start') {
         const alias = args.alias
@@ -323,7 +334,7 @@ export function sshTunnelTool(engine: SshEngine) {
         if (alias === undefined || remotePort === undefined) {
           return { ok: false, error: 'alias and remotePort are required for start' }
         }
-        return captureToolResult(async () => ({
+        return captureToolResult(engine, async () => ({
           tunnel: await engine.startTunnel(alias, {
             remotePort,
             remoteHost: args.remoteHost,
@@ -336,14 +347,14 @@ export function sshTunnelTool(engine: SshEngine) {
         if (tunnelId === undefined) {
           return { ok: false, error: 'tunnelId is required for stop' }
         }
-        return captureToolResult(() => {
+        return captureToolResult(engine, () => {
           const stopped = engine.stopTunnel(tunnelId)
           if (!stopped) throw new Error(`tunnel '${tunnelId}' not found`)
           return { stopped: 1 }
         })
       }
       if (args.action === 'stop-all') {
-        return captureToolResult(() => ({ stopped: engine.stopAllTunnels(args.alias) }))
+        return captureToolResult(engine, () => ({ stopped: engine.stopAllTunnels(args.alias) }))
       }
       return { ok: false, error: `unknown action '${String(args.action)}'` }
     },
@@ -384,6 +395,14 @@ export function sshClusterTool(engine: SshEngine) {
                 stderr: { type: 'string' },
                 durationMs: { type: 'integer' },
                 error: { type: 'string' },
+                // Typed per-host failure detail (B-14): additive optional
+                // fields, so an agent can retry by machine code instead of
+                // parsing a message. Never carries a credential value.
+                code: { type: 'string', enum: ['NEEDS_PASSWORD', 'HOST_KEY_UNKNOWN', 'HOST_KEY_MISMATCH', 'ALIAS_NOT_FOUND', 'ABORTED', 'TIMEOUT', 'ERROR'] },
+                secret: { type: 'string', enum: ['password', 'passphrase'] },
+                hostKeyFingerprint: { type: 'string' },
+                expected: { type: 'string' },
+                actual: { type: 'string' },
               },
             },
           },
@@ -396,7 +415,10 @@ export function sshClusterTool(engine: SshEngine) {
       },
     },
     async execute(args) {
-      return captureToolResult(() => engine.cluster(args))
+      // The engine returns a bare array; the envelope (and this tool's own
+      // output schema) requires a `results` field. Spreading the array
+      // produced numeric keys instead, so the payload was unusable.
+      return captureToolResult(engine, async () => ({ results: await engine.cluster(args) }))
     },
   })
 }