dsh-remote 0.8.46 → 0.8.48

package/lib/credential.js

@@ -1,177 +1,177 @@
-// dsh-remote — optional OS-keychain password storage.
-// Machines keep their password in the OS credential store instead of the
-// plaintext machines.json when the user enables "加密保存密码" per machine.
-// Every backend is best-effort: any failure resolves to {ok:false} and the
-// caller (persistPassword) falls back to plaintext + a user-visible warning
-// (the feature must never block connecting, and must never silently drop the
-// credential — issue #30).
-//
-// Backends:
-//   darwin  → `security` (login keychain, generic password)
-//   win32   → DPAPI via PowerShell (CurrentUser scope), files under
-//             $DSH_HOME/remote-workspaces/.secrets/
-//   linux   → `secret-tool` (libsecret / gnome-keyring), optional
-//   else    → unsupported (plain)
-import { execFile } from 'node:child_process'
-import { mkdirSync, writeFileSync, readFileSync, unlinkSync } from 'node:fs'
-import { join as joinPath } from 'node:path'
-
-const SERVICE = 'dsh-remote'
-const TIMEOUT = 8000
-
-// Windows PowerShell 5.1 does not preload System.Security, so
-// [System.Security.Cryptography.ProtectedData] is "not found" until the assembly
-// is added (issue #30: without this the whole DPAPI call failed and the caller
-// silently lost the password). `-ErrorAction SilentlyContinue` keeps the line
-// harmless on PowerShell 7, where the type is already available.
-const PS_SECURITY_ASSEMBLY = 'Add-Type -AssemblyName System.Security -ErrorAction SilentlyContinue;'
-
-function run(bin, args, input) {
-  return new Promise((resolve, reject) => {
-    execFile(bin, args, { timeout: TIMEOUT, maxBuffer: 1 << 20, ...(input != null ? { input } : {}) }, (err, stdout, stderr) => {
-      if (err) return reject(err)
-      resolve(String(stdout || '').trim())
-    })
-  })
-}
-
-export function platformBackend() {
-  if (process.platform === 'darwin') return 'keychain'
-  if (process.platform === 'win32') return 'windows'
-  return 'secret' // linux (secret-tool may be absent → falls back)
-}
-
-function account(machineId) {
-  // Only machine ids are stored; sanitize just in case.
-  return String(machineId || '').replace(/[^a-zA-Z0-9._-]/g, '_')
-}
-
-/** Redact a failed command's diagnostics: execFile puts the FULL command line
- * (which carries the password as an argv) into `err.message`, and this string is
- * shown in the settings UI — so the secret must never survive it. */
-function safeReason(err, password) {
-  const raw = [err && err.stderr, err && err.message, err && err.code]
-    .filter(Boolean).map(String).join(' ')
-  const secret = String(password == null ? '' : password)
-  const scrubbed = secret ? raw.split(secret).join('***') : raw
-  return scrubbed.replace(/\s+/g, ' ').trim().slice(0, 300)
-}
-
-/** PowerShell one-liner that DPAPI-protects a password (CurrentUser scope).
- *  Exported because the issue #30 fix (the mandatory Add-Type preamble) is only
- *  observable here — a Windows host cannot be exercised from the test suite. */
-export function dpapiProtectScript(password) {
-  return PS_SECURITY_ASSEMBLY +
-    `$p='${String(password).replace(/'/g, "''")}';` +
-    `$s=[System.Security.Cryptography.ProtectedData]::Protect([Text.Encoding]::UTF8.GetBytes($p),$null,[System.Security.Cryptography.DataProtectionScope]::CurrentUser);` +
-    `[Convert]::ToBase64String($s)`
-}
-
-/** PowerShell one-liner that reverses dpapiProtectScript(). */
-export function dpapiUnprotectScript(b64) {
-  return PS_SECURITY_ASSEMBLY +
-    `$s=[Convert]::FromBase64String('${String(b64).replace(/'/g, "''")}');` +
-    `[Text.Encoding]::UTF8.GetString([System.Security.Cryptography.ProtectedData]::Unprotect($s,$null,[System.Security.Cryptography.DataProtectionScope]::CurrentUser))`
-}
-
-/** Save a password to the OS store. Resolves {ok, backend, error} — ok:false on
- * any failure (caller falls back to plaintext). `error` is a password-free
- * diagnostic for the UI. */
-export async function saveSecret(machineId, password, secretsDir) {
-  const acc = account(machineId)
-  try {
-    if (process.platform === 'darwin') {
-      await run('security', ['add-generic-password', '-U', '-s', SERVICE, '-a', acc, '-w', String(password)])
-      return { ok: true, backend: 'keychain', error: '' }
-    }
-    if (process.platform === 'win32') {
-      // DPAPI-encrypt and store under the harness home.
-      const script = dpapiProtectScript(password)
-      const b64 = await run('powershell', ['-NoProfile', '-STA', '-Command', script])
-      if (!b64) return { ok: false, backend: 'windows', error: 'DPAPI returned no ciphertext' }
-      mkdirSync(secretsDir || '.', { recursive: true })
-      writeFileSync(joinPath(secretsDir || '.', acc + '.bin'), b64, 'utf8')
-      return { ok: true, backend: 'windows', error: '' }
-    }
-    if (process.platform === 'linux') {
-      await run('secret-tool', ['store', '--label=' + SERVICE, 'service', SERVICE, 'account', acc], String(password) + '\n')
-      return { ok: true, backend: 'secret', error: '' }
-    }
-  } catch (err) {
-    return { ok: false, backend: platformBackend(), error: safeReason(err, password) || 'secret store write failed' }
-  }
-  return { ok: false, backend: platformBackend(), error: `unsupported platform: ${process.platform}` }
-}
-
-/** Decide where a machine password is persisted (issue #30).
- *
- * The contract the settings UI relies on: a password is NEVER dropped. When the
- * requested OS store fails (missing DPAPI assembly, locked keychain, absent
- * secret-tool), this falls back to plaintext in machines.json and reports
- * `warning: 'secret-store-failed'` so the caller can tell the user instead of
- * silently saving a credential-less machine.
- *
- * `save` is injectable so the fallback is unit-testable on any platform.
- *
- * @returns {Promise<{stored:'secret'|'plain'|'none', credentialBackend:string, password:string, warning:string, error:string}>}
- */
-export async function persistPassword({ backend, machineId, password, secretsDir, save = saveSecret }) {
-  const pw = password == null ? '' : String(password)
-  const want = backend && backend !== 'plain' ? backend : 'plain'
-  if (!pw) return { stored: 'none', credentialBackend: want, password: '', warning: '', error: '' }
-  if (want === 'plain') return { stored: 'plain', credentialBackend: 'plain', password: pw, warning: '', error: '' }
-  let res
-  try {
-    res = await save(machineId, pw, secretsDir)
-  } catch (err) {
-    res = { ok: false, error: safeReason(err, pw) }
-  }
-  if (res && res.ok) {
-    return { stored: 'secret', credentialBackend: res.backend || want, password: '', warning: '', error: '' }
-  }
-  return {
-    stored: 'plain',
-    credentialBackend: 'plain',
-    password: pw,
-    warning: 'secret-store-failed',
-    error: String((res && res.error) || '') || 'secret store write failed',
-  }
-}
-
-/** Fetch a stored password. Resolves string|null. */
-export async function getSecret(machineId, secretsDir) {
-  const acc = account(machineId)
-  try {
-    if (process.platform === 'darwin') {
-      return await run('security', ['find-generic-password', '-s', SERVICE, '-a', acc, '-w'])
-    }
-    if (process.platform === 'win32') {
-      const b64 = readFileSync(joinPath(secretsDir || '.', acc + '.bin'), 'utf8').trim()
-      if (!b64) return null
-      const script = dpapiUnprotectScript(b64)
-      return await run('powershell', ['-NoProfile', '-STA', '-Command', script])
-    }
-    if (process.platform === 'linux') {
-      return await run('secret-tool', ['lookup', 'service', SERVICE, 'account', acc])
-    }
-  } catch { /* fall through */ }
-  return null
-}
-
-/** Delete a stored password (idempotent). */
-export async function deleteSecret(machineId, secretsDir) {
-  const acc = account(machineId)
-  try {
-    if (process.platform === 'darwin') {
-      await run('security', ['delete-generic-password', '-s', SERVICE, '-a', acc]).catch(() => {})
-      return
-    }
-    if (process.platform === 'win32') {
-      try { unlinkSync(joinPath(secretsDir || '.', acc + '.bin')) } catch { /* absent */ }
-      return
-    }
-    if (process.platform === 'linux') {
-      await run('secret-tool', ['clear', 'service', SERVICE, 'account', acc]).catch(() => {})
-    }
-  } catch { /* best effort */ }
-}
+// dsh-remote — optional OS-keychain password storage.
+// Machines keep their password in the OS credential store instead of the
+// plaintext machines.json when the user enables "加密保存密码" per machine.
+// Every backend is best-effort: any failure resolves to {ok:false} and the
+// caller (persistPassword) falls back to plaintext + a user-visible warning
+// (the feature must never block connecting, and must never silently drop the
+// credential — issue #30).
+//
+// Backends:
+//   darwin  → `security` (login keychain, generic password)
+//   win32   → DPAPI via PowerShell (CurrentUser scope), files under
+//             $DSH_HOME/remote-workspaces/.secrets/
+//   linux   → `secret-tool` (libsecret / gnome-keyring), optional
+//   else    → unsupported (plain)
+import { execFile } from 'node:child_process'
+import { mkdirSync, writeFileSync, readFileSync, unlinkSync } from 'node:fs'
+import { join as joinPath } from 'node:path'
+
+const SERVICE = 'dsh-remote'
+const TIMEOUT = 8000
+
+// Windows PowerShell 5.1 does not preload System.Security, so
+// [System.Security.Cryptography.ProtectedData] is "not found" until the assembly
+// is added (issue #30: without this the whole DPAPI call failed and the caller
+// silently lost the password). `-ErrorAction SilentlyContinue` keeps the line
+// harmless on PowerShell 7, where the type is already available.
+const PS_SECURITY_ASSEMBLY = 'Add-Type -AssemblyName System.Security -ErrorAction SilentlyContinue;'
+
+function run(bin, args, input) {
+  return new Promise((resolve, reject) => {
+    execFile(bin, args, { timeout: TIMEOUT, maxBuffer: 1 << 20, ...(input != null ? { input } : {}) }, (err, stdout, stderr) => {
+      if (err) return reject(err)
+      resolve(String(stdout || '').trim())
+    })
+  })
+}
+
+export function platformBackend() {
+  if (process.platform === 'darwin') return 'keychain'
+  if (process.platform === 'win32') return 'windows'
+  return 'secret' // linux (secret-tool may be absent → falls back)
+}
+
+function account(machineId) {
+  // Only machine ids are stored; sanitize just in case.
+  return String(machineId || '').replace(/[^a-zA-Z0-9._-]/g, '_')
+}
+
+/** Redact a failed command's diagnostics: execFile puts the FULL command line
+ * (which carries the password as an argv) into `err.message`, and this string is
+ * shown in the settings UI — so the secret must never survive it. */
+function safeReason(err, password) {
+  const raw = [err && err.stderr, err && err.message, err && err.code]
+    .filter(Boolean).map(String).join(' ')
+  const secret = String(password == null ? '' : password)
+  const scrubbed = secret ? raw.split(secret).join('***') : raw
+  return scrubbed.replace(/\s+/g, ' ').trim().slice(0, 300)
+}
+
+/** PowerShell one-liner that DPAPI-protects a password (CurrentUser scope).
+ *  Exported because the issue #30 fix (the mandatory Add-Type preamble) is only
+ *  observable here — a Windows host cannot be exercised from the test suite. */
+export function dpapiProtectScript(password) {
+  return PS_SECURITY_ASSEMBLY +
+    `$p='${String(password).replace(/'/g, "''")}';` +
+    `$s=[System.Security.Cryptography.ProtectedData]::Protect([Text.Encoding]::UTF8.GetBytes($p),$null,[System.Security.Cryptography.DataProtectionScope]::CurrentUser);` +
+    `[Convert]::ToBase64String($s)`
+}
+
+/** PowerShell one-liner that reverses dpapiProtectScript(). */
+export function dpapiUnprotectScript(b64) {
+  return PS_SECURITY_ASSEMBLY +
+    `$s=[Convert]::FromBase64String('${String(b64).replace(/'/g, "''")}');` +
+    `[Text.Encoding]::UTF8.GetString([System.Security.Cryptography.ProtectedData]::Unprotect($s,$null,[System.Security.Cryptography.DataProtectionScope]::CurrentUser))`
+}
+
+/** Save a password to the OS store. Resolves {ok, backend, error} — ok:false on
+ * any failure (caller falls back to plaintext). `error` is a password-free
+ * diagnostic for the UI. */
+export async function saveSecret(machineId, password, secretsDir) {
+  const acc = account(machineId)
+  try {
+    if (process.platform === 'darwin') {
+      await run('security', ['add-generic-password', '-U', '-s', SERVICE, '-a', acc, '-w', String(password)])
+      return { ok: true, backend: 'keychain', error: '' }
+    }
+    if (process.platform === 'win32') {
+      // DPAPI-encrypt and store under the harness home.
+      const script = dpapiProtectScript(password)
+      const b64 = await run('powershell', ['-NoProfile', '-STA', '-Command', script])
+      if (!b64) return { ok: false, backend: 'windows', error: 'DPAPI returned no ciphertext' }
+      mkdirSync(secretsDir || '.', { recursive: true })
+      writeFileSync(joinPath(secretsDir || '.', acc + '.bin'), b64, 'utf8')
+      return { ok: true, backend: 'windows', error: '' }
+    }
+    if (process.platform === 'linux') {
+      await run('secret-tool', ['store', '--label=' + SERVICE, 'service', SERVICE, 'account', acc], String(password) + '\n')
+      return { ok: true, backend: 'secret', error: '' }
+    }
+  } catch (err) {
+    return { ok: false, backend: platformBackend(), error: safeReason(err, password) || 'secret store write failed' }
+  }
+  return { ok: false, backend: platformBackend(), error: `unsupported platform: ${process.platform}` }
+}
+
+/** Decide where a machine password is persisted (issue #30).
+ *
+ * The contract the settings UI relies on: a password is NEVER dropped. When the
+ * requested OS store fails (missing DPAPI assembly, locked keychain, absent
+ * secret-tool), this falls back to plaintext in machines.json and reports
+ * `warning: 'secret-store-failed'` so the caller can tell the user instead of
+ * silently saving a credential-less machine.
+ *
+ * `save` is injectable so the fallback is unit-testable on any platform.
+ *
+ * @returns {Promise<{stored:'secret'|'plain'|'none', credentialBackend:string, password:string, warning:string, error:string}>}
+ */
+export async function persistPassword({ backend, machineId, password, secretsDir, save = saveSecret }) {
+  const pw = password == null ? '' : String(password)
+  const want = backend && backend !== 'plain' ? backend : 'plain'
+  if (!pw) return { stored: 'none', credentialBackend: want, password: '', warning: '', error: '' }
+  if (want === 'plain') return { stored: 'plain', credentialBackend: 'plain', password: pw, warning: '', error: '' }
+  let res
+  try {
+    res = await save(machineId, pw, secretsDir)
+  } catch (err) {
+    res = { ok: false, error: safeReason(err, pw) }
+  }
+  if (res && res.ok) {
+    return { stored: 'secret', credentialBackend: res.backend || want, password: '', warning: '', error: '' }
+  }
+  return {
+    stored: 'plain',
+    credentialBackend: 'plain',
+    password: pw,
+    warning: 'secret-store-failed',
+    error: String((res && res.error) || '') || 'secret store write failed',
+  }
+}
+
+/** Fetch a stored password. Resolves string|null. */
+export async function getSecret(machineId, secretsDir) {
+  const acc = account(machineId)
+  try {
+    if (process.platform === 'darwin') {
+      return await run('security', ['find-generic-password', '-s', SERVICE, '-a', acc, '-w'])
+    }
+    if (process.platform === 'win32') {
+      const b64 = readFileSync(joinPath(secretsDir || '.', acc + '.bin'), 'utf8').trim()
+      if (!b64) return null
+      const script = dpapiUnprotectScript(b64)
+      return await run('powershell', ['-NoProfile', '-STA', '-Command', script])
+    }
+    if (process.platform === 'linux') {
+      return await run('secret-tool', ['lookup', 'service', SERVICE, 'account', acc])
+    }
+  } catch { /* fall through */ }
+  return null
+}
+
+/** Delete a stored password (idempotent). */
+export async function deleteSecret(machineId, secretsDir) {
+  const acc = account(machineId)
+  try {
+    if (process.platform === 'darwin') {
+      await run('security', ['delete-generic-password', '-s', SERVICE, '-a', acc]).catch(() => {})
+      return
+    }
+    if (process.platform === 'win32') {
+      try { unlinkSync(joinPath(secretsDir || '.', acc + '.bin')) } catch { /* absent */ }
+      return
+    }
+    if (process.platform === 'linux') {
+      await run('secret-tool', ['clear', 'service', SERVICE, 'account', acc]).catch(() => {})
+    }
+  } catch { /* best effort */ }
+}

package/lib/deploy-tasks.js

@@ -1,142 +1,142 @@
-// dsh-remote — host-side deploy task manager.
-//
-// WHY THIS EXISTS: `install` used to be a single long HTTP request (npm can
-// legitimately take minutes). If the browser tab closed — or the fetch was
-// cancelled — the RESPONSE was lost and, with it, every trace of what the
-// deploy did: the user could not see the progress again, could not tell whether
-// it succeeded, and clicking the button again would start a SECOND concurrent
-// npm install into the same prefix. High availability here means:
-//
-//   · the deploy runs on the HOST, not tied to any request lifecycle;
-//   · every step's outcome is recorded as it happens;
-//   · the UI can re-attach at any time and see the live state;
-//   · a second click while one is running RE-ATTACHES instead of restarting;
-//   · the result (including the machine's webAttachCommand) is recorded even
-//     if no client ever polls for it.
-//
-// One deploy per machine at a time — npm --prefix into the same directory from
-// two processes corrupts the tree. A NEW request for a machine that already has
-// a running or finished deploy returns the EXISTING task (resume semantics);
-// `force: true` starts a fresh one after the previous is finished.
-
-/** A deploy task's lifecycle: queued → running → done | failed | cancelled. */
-export class DeployTasks {
-  constructor() {
-    /** @type {Map<string, object>} machineId → task */
-    this.byMachine = new Map()
-    /** @type {Map<string, object>} taskId → task (for stable polling) */
-    this.byId = new Map()
-    this.nextId = 1
-  }
-
-  /**
-   * The task for a machine, if one exists in ANY state.
-   * @returns {object|null}
-   */
-  forMachine(machineId) {
-    return this.byMachine.get(String(machineId || '')) || null
-  }
-
-  get(id) {
-    return this.byId.get(String(id || '')) || null
-  }
-
-  /**
-   * Start a deploy for a machine, unless one is already running.
-   *
-   * @param {string} machineId
-   * @param {Function} fn - async (ctx) => result. ctx = { progress(patch) }.
-   * @returns {{task: object, reused: boolean}} the task plus whether it already
-   *   existed (caller reports "resumed" so the UI does not claim a fresh start).
-   */
-  start(machineId, label, fn) {
-    const mid = String(machineId || '')
-    const existing = this.byMachine.get(mid)
-    if (existing && (existing.status === 'queued' || existing.status === 'running')) {
-      return { task: existing, reused: true }
-    }
-    const id = `deploy-${this.nextId++}`
-    const task = {
-      id,
-      machineId: mid,
-      kind: 'deploy',
-      label: String(label || ''),
-      status: 'queued',
-      // Steps are appended as they finish; `steps` is what the UI renders.
-      steps: [],
-      // The current in-flight step, so a re-attached UI can show "正在安装…"
-      // rather than a stale list with no hint that more is coming.
-      current: '',
-      progress: {},
-      result: null,
-      error: null,
-      startedAt: null,
-      finishedAt: null,
-      cancelled: false,
-    }
-    this.byMachine.set(mid, task)
-    this.byId.set(id, task)
-    // Deliberately NOT queued through the shared TaskManager: that one is
-    // single-flight across ALL tasks (one sync at a time), while deploys to
-    // DIFFERENT machines must run in parallel.
-    task.status = 'running'
-    task.startedAt = new Date().toISOString()
-    const ctx = {
-      progress: (p) => { task.progress = { ...task.progress, ...p } },
-      get cancelled() { return !!task.cancelled },
-    }
-    Promise.resolve()
-      .then(() => fn(ctx))
-      .then((result) => {
-        task.result = result || null
-        task.status = task.cancelled ? 'cancelled' : 'done'
-      })
-      .catch((err) => {
-        task.error = String((err && err.message) || err)
-        // A step-level failure carries the step list (and hints) as structured
-        // data so the UI can render exactly what the old single-response flow
-        // rendered — re-attaching must lose nothing.
-        if (err && err.detail && typeof err.detail === 'object') task.detail = err.detail
-        task.status = task.cancelled ? 'cancelled' : 'failed'
-      })
-      .finally(() => {
-        task.current = ''
-        task.finishedAt = new Date().toISOString()
-      })
-    return { task, reused: false }
-  }
-
-  /** Cooperative cancel (a running npm step still finishes; later steps stop). */
-  cancel(machineId) {
-    const t = this.byMachine.get(String(machineId || ''))
-    if (!t) return false
-    if (t.status === 'queued' || t.status === 'running') {
-      t.cancelled = true
-      return true
-    }
-    return false
-  }
-
-  /** Serializable view for the UI. */
-  describe(t) {
-    if (!t) return null
-    return {
-      id: t.id,
-      machineId: t.machineId,
-      kind: t.kind,
-      status: t.status,           // queued | running | done | failed | cancelled
-      steps: t.steps,             // [{id,title,ok,code,output}]
-      current: t.current,         // in-flight step title ('' when none)
-      progress: t.progress,
-      result: t.result,
-      error: t.error,
-      detail: t.detail || null,
-      startedAt: t.startedAt,
-      finishedAt: t.finishedAt,
-    }
-  }
-
-  list() {
-    return [...this.byMachine.values()].map((t) => this.describe(t))
-  }
-}
+// dsh-remote — host-side deploy task manager.
+//
+// WHY THIS EXISTS: `install` used to be a single long HTTP request (npm can
+// legitimately take minutes). If the browser tab closed — or the fetch was
+// cancelled — the RESPONSE was lost and, with it, every trace of what the
+// deploy did: the user could not see the progress again, could not tell whether
+// it succeeded, and clicking the button again would start a SECOND concurrent
+// npm install into the same prefix. High availability here means:
+//
+//   · the deploy runs on the HOST, not tied to any request lifecycle;
+//   · every step's outcome is recorded as it happens;
+//   · the UI can re-attach at any time and see the live state;
+//   · a second click while one is running RE-ATTACHES instead of restarting;
+//   · the result (including the machine's webAttachCommand) is recorded even
+//     if no client ever polls for it.
+//
+// One deploy per machine at a time — npm --prefix into the same directory from
+// two processes corrupts the tree. A NEW request for a machine that already has
+// a running or finished deploy returns the EXISTING task (resume semantics);
+// `force: true` starts a fresh one after the previous is finished.
+
+/** A deploy task's lifecycle: queued → running → done | failed | cancelled. */
+export class DeployTasks {
+  constructor() {
+    /** @type {Map<string, object>} machineId → task */
+    this.byMachine = new Map()
+    /** @type {Map<string, object>} taskId → task (for stable polling) */
+    this.byId = new Map()
+    this.nextId = 1
+  }
+
+  /**
+   * The task for a machine, if one exists in ANY state.
+   * @returns {object|null}
+   */
+  forMachine(machineId) {
+    return this.byMachine.get(String(machineId || '')) || null
+  }
+
+  get(id) {
+    return this.byId.get(String(id || '')) || null
+  }
+
+  /**
+   * Start a deploy for a machine, unless one is already running.
+   *
+   * @param {string} machineId
+   * @param {Function} fn - async (ctx) => result. ctx = { progress(patch) }.
+   * @returns {{task: object, reused: boolean}} the task plus whether it already
+   *   existed (caller reports "resumed" so the UI does not claim a fresh start).
+   */
+  start(machineId, label, fn) {
+    const mid = String(machineId || '')
+    const existing = this.byMachine.get(mid)
+    if (existing && (existing.status === 'queued' || existing.status === 'running')) {
+      return { task: existing, reused: true }
+    }
+    const id = `deploy-${this.nextId++}`
+    const task = {
+      id,
+      machineId: mid,
+      kind: 'deploy',
+      label: String(label || ''),
+      status: 'queued',
+      // Steps are appended as they finish; `steps` is what the UI renders.
+      steps: [],
+      // The current in-flight step, so a re-attached UI can show "正在安装…"
+      // rather than a stale list with no hint that more is coming.
+      current: '',
+      progress: {},
+      result: null,
+      error: null,
+      startedAt: null,
+      finishedAt: null,
+      cancelled: false,
+    }
+    this.byMachine.set(mid, task)
+    this.byId.set(id, task)
+    // Deliberately NOT queued through the shared TaskManager: that one is
+    // single-flight across ALL tasks (one sync at a time), while deploys to
+    // DIFFERENT machines must run in parallel.
+    task.status = 'running'
+    task.startedAt = new Date().toISOString()
+    const ctx = {
+      progress: (p) => { task.progress = { ...task.progress, ...p } },
+      get cancelled() { return !!task.cancelled },
+    }
+    Promise.resolve()
+      .then(() => fn(ctx))
+      .then((result) => {
+        task.result = result || null
+        task.status = task.cancelled ? 'cancelled' : 'done'
+      })
+      .catch((err) => {
+        task.error = String((err && err.message) || err)
+        // A step-level failure carries the step list (and hints) as structured
+        // data so the UI can render exactly what the old single-response flow
+        // rendered — re-attaching must lose nothing.
+        if (err && err.detail && typeof err.detail === 'object') task.detail = err.detail
+        task.status = task.cancelled ? 'cancelled' : 'failed'
+      })
+      .finally(() => {
+        task.current = ''
+        task.finishedAt = new Date().toISOString()
+      })
+    return { task, reused: false }
+  }
+
+  /** Cooperative cancel (a running npm step still finishes; later steps stop). */
+  cancel(machineId) {
+    const t = this.byMachine.get(String(machineId || ''))
+    if (!t) return false
+    if (t.status === 'queued' || t.status === 'running') {
+      t.cancelled = true
+      return true
+    }
+    return false
+  }
+
+  /** Serializable view for the UI. */
+  describe(t) {
+    if (!t) return null
+    return {
+      id: t.id,
+      machineId: t.machineId,
+      kind: t.kind,
+      status: t.status,           // queued | running | done | failed | cancelled
+      steps: t.steps,             // [{id,title,ok,code,output}]
+      current: t.current,         // in-flight step title ('' when none)
+      progress: t.progress,
+      result: t.result,
+      error: t.error,
+      detail: t.detail || null,
+      startedAt: t.startedAt,
+      finishedAt: t.finishedAt,
+    }
+  }
+
+  list() {
+    return [...this.byMachine.values()].map((t) => this.describe(t))
+  }
+}