dsh-acp-replay 0.1.0 → 0.1.2

package/README.md

@@ -2,7 +2,9 @@
 
 A community ACP bridge for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) that answers `session/load`, so a client can rebuild a session transcript after its own restart.
 
-**Status: prototype.** It works end to end on `dsh 0.1.5-rc.1`, but it is a vendored fork of `@deepseek-ai/dsh-acp` and needs a rebase whenever that package changes.
+**Status: prototype.** It works end to end on `dsh 0.1.5-rc.1` through `0.1.5-rc.3`, but it is a vendored fork of `@deepseek-ai/dsh-acp` and needs a rebase whenever that package changes. `0.1.6-alpha.1` changed the persistence API and, per a field report on 2026-09-23, answers no ACP request with either profile; the guard below is what reports why.
+
+Published on npm as `dsh-acp-replay`. Its version is independent of the harness version it targets, which `peerDependencies` states. `0.1.2` ships `test/*.mjs` and exposes the self-check and the pin check as bins, so both run from an installed copy. (`0.1.5-rc.1` was published with an incomplete file list, so it fails to load; it is deprecated.)
 
 ## Why this exists
 
@@ -40,7 +42,30 @@ Use the shipped bridge instead ("dsh --profile acp"), or update this plugin for
 https://github.com/zheng1/dsh-acp-replay
 ```
 
-Run `node test/selfcheck.mjs` after a harness upgrade to get that answer without a full client.
+Run the self-check after a harness upgrade to get that answer without a full client. From a checkout that is `node test/selfcheck.mjs`; from an installed copy it is `npx dsh-acp-replay-selfcheck`, and a global install puts the same command on `PATH`. `dsh-acp-replay-pincheck` runs both profiles and prints which of the upgrade outcomes below applies.
+
+The self-check reports "no ACP initialize response" when the harness never answers, which is also what a failed mount looks like. `dsh` rewrites the profile's `cordis.yml` while preparing it, so a sandbox that denies writes to `DSH_HOME` exits on EPERM before answering; the check says so when it sees `EPERM` or `prepareProfile` in the captured stderr, and prints that stderr otherwise.
+
+## Upgrading the harness pin
+
+The pin is the harness version whose `dsh-acp` this fork was rebased against. Check the candidate before moving it:
+
+```
+$ DSH_BIN=~/.local/bin/dsh npx dsh-acp-replay-pincheck
+harness: /Users/you/.local/bin/dsh (0.1.5-rc.3)
+shipped profile "acp"             does not advertise loadSession
+bridge profile "acp-replay"       advertises loadSession (image: yes)
+
+PIN: bridge — upgrade the harness and move the pin; this bridge answers session/load on it
+```
+
+| Outcome | Meaning | What to do |
+| --- | --- | --- |
+| `upstream` | The shipped profile advertises `loadSession` too | Drop the bridge and unpin; point the client back at `dsh --profile acp` |
+| `bridge` | Only the bridged profile advertises it | Upgrade the harness, then move the pin |
+| `refuses` | Neither profile advertises it | Stay on the pinned harness |
+
+`test/replay-check.mjs` is the other half of that check: it records a session and replays it in a new process, so use a session with real content. A 376-byte session legitimately replays nothing, and zero counts then look like a broken bridge.
 
 ## Use it
 
@@ -95,6 +120,21 @@ npm run build                    # tsc -> lib/
 npm test                         # guard behaviour (node:test)
 ```
 
+### pnpm
+
+Reported from a field install with pnpm 12 (this repository is developed with pnpm 10, where a plain install is enough): pnpm 12 fails on `ERR_PNPM_IGNORED_BUILDS` even when the dependency tree resolved, and `--ignore-scripts` does not bypass it. Declaring the builds is what works:
+
+```yaml
+allowBuilds:
+  "@deepseek-ai/dsh-subprocess-local": true
+  "@google/genai": true
+  koffi: true
+  node-pty: true
+  protobufjs: true
+```
+
+`@deepseek-ai/dsh-subprocess-local` is the one that matters: its postinstall restores the executable bit on node-pty's `spawn-helper`. A packaged prebuild already ships that file `0755`, so skipping the script is invisible until an install lacks the bit and pty support disappears without a message.
+
 ## Verified
 
 Against `dsh 0.1.5-rc.1`, a scratch `DSH_HOME`, and a real API key:
@@ -114,9 +154,31 @@ Against `dsh 0.1.5-rc.1`, a scratch `DSH_HOME`, and a real API key:
 
 Paseo's ACP adapter takes the `loadSession` branch only when the agent advertises the capability, primes its timeline from `streamHistory()`, and needed no change for this to work.
 
+**Independent confirmation** (`dsh 0.1.5-rc.2`, Paseo 0.9.1 daemon, macOS, own `DSH_HOME`):
+
+| Probe | Shipped `acp` | `dsh-acp-replay` |
+| --- | --- | --- |
+| `initialize.agentCapabilities.loadSession` | absent (`sessionCapabilities: { close, list, resume }`) | `true` |
+| `session/load` on a persisted session | no replay | `user_message_chunk` ×1, `agent_message_chunk` ×17, `tool_call` ×24 |
+
+That client-side branch was read off the shipped Paseo 0.9.1 build: its ACP client tests `agentCapabilities.loadSession` first and only falls back to `unstable_resumeSession`, and `dsh` reaches the client through the generic ACP path, so the shipped bridge takes the second branch. Switching the provider to this bridge rendered the conversations that had reopened blank, and `paseo provider diagnostic dsh` reported Ready.
+
+**The self-check from an installed copy** (`0.1.1`, an `npm install` of the packed tarball, `dsh 0.1.5-rc.1`, scratch `DSH_HOME`) — the check that could not be run before `0.1.1`, because `test/` was not in the published file list:
+
+```
+$ DSH_PROFILE=acp-replay dsh-acp-replay-selfcheck
+OK: profile "acp-replay" advertises loadSession (image: yes)
+
+$ DSH_PROFILE=acp dsh-acp-replay-selfcheck
+FAIL: the bridge answered but does not advertise loadSession        # exit 1
+```
+
+**`0.1.1` changed no served code.** A downstream field check diffed the published `0.1.1` tarball against the installed `0.1.0`: `lib/` and `cordis.patch.yml` byte-identical, `package.json` differing only in the version, the `bin` entry, and `files`. After the upgrade the same 1.2 MB session replayed to identical counts (`user_message_chunk` 17, `agent_message_chunk` 90, `agent_thought_chunk` 103, `tool_call` 114, `tool_call_update` 114, `usage_update` 113) and the provider diagnostic stayed Ready.
+
 ## Not verified / known limits
 
 - Tool-call replay is mapped but not exercised by the test above.
+- The `0.1.6-alpha.1` no-response finding above is a field report; this repository has not re-probed an alpha harness. npm `latest` is `0.1.5-rc.2` and `next` is `0.1.5-rc.3`, both of which work.
 - An older host (`dsh 0.1.2-rc.1`) exposes a different persistence API (`load`/`inspect` instead of `open`/`read`), so this fork targets `0.1.5-rc.1` and newer only.
 - Replayed history is delivered before `session/load` returns, one notification at a time; a very long session makes that call proportionally long.
 - The profile's own help text still reads `--profile acp` (it comes from the bundled `dsh-acp-app` command provider, not from this package).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-acp-replay",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Community ACP bridge for DeepSeek Harness that supports session/load by replaying a persisted session's transcript",
   "type": "module",
   "main": "lib/index.js",
@@ -13,10 +13,15 @@
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json"
   },
+  "bin": {
+    "dsh-acp-replay-selfcheck": "./test/selfcheck.mjs",
+    "dsh-acp-replay-pincheck": "./test/pin-check.mjs"
+  },
   "files": [
     "lib/**/*.js",
     "lib/types/**/*.d.ts",
-    "cordis.patch.yml"
+    "cordis.patch.yml",
+    "test/*.mjs"
   ],
   "license": "MIT",
   "dsh": {

package/test/compat.test.mjs

@@ -0,0 +1,47 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { assertReplayHostSupport, replayHostProblems } from '../lib/compat.js'
+
+const noop = () => {}
+
+test('accepts a harness with the persistence handle API', () => {
+  const support = {
+    persistence: { create: noop, open: noop, flush: noop, stat: noop, list: noop },
+    sessionLoadMethod: 'session/load',
+  }
+  assert.deepEqual(replayHostProblems(support), [])
+  assertReplayHostSupport(support)
+})
+
+test('names the service-level read API that replaced it', () => {
+  const legacy = {
+    persistence: { load: noop, inspect: noop, stat: noop, list: noop },
+    sessionLoadMethod: 'session/load',
+  }
+  const problems = replayHostProblems(legacy)
+  assert.equal(problems.length, 1)
+  assert.match(problems[0].requirement, /sessionPersistence\.open\(\)/)
+  assert.match(problems[0].detail, /inspect, list, load, stat/)
+  assert.throws(() => assertReplayHostSupport(legacy), /cannot serve session\/load/)
+})
+
+test('refuses a host with no persistence service mounted', () => {
+  assert.throws(
+    () => assertReplayHostSupport({ persistence: undefined, sessionLoadMethod: 'session/load' }),
+    /not mounted/,
+  )
+})
+
+test('refuses an ACP SDK without the session/load constant', () => {
+  assert.throws(
+    () => assertReplayHostSupport({ persistence: { open: noop, stat: noop }, sessionLoadMethod: undefined }),
+    /session\/load method constant/,
+  )
+})
+
+test('reports the harness version when the caller knows it', () => {
+  assert.throws(
+    () => assertReplayHostSupport({ persistence: undefined, sessionLoadMethod: 'session/load', harnessVersion: '0.1.6' }),
+    /harness 0\.1\.6/,
+  )
+})

package/test/pin-check.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * Pin check: probe a candidate harness on the shipped profile and on the bridged
+ * one, and print which of the three outcomes applies, so moving the harness pin
+ * after an upgrade is one command instead of a judgement call.
+ *
+ *   upstream  the shipped profile advertises loadSession itself — drop the bridge
+ *             and unpin: point the client back at `dsh --profile acp`
+ *   bridge    only the bridged profile advertises it — upgrade the harness and
+ *             move the pin
+ *   refuses   neither profile answers with loadSession — stay on the pinned harness
+ *
+ * Usage:
+ *   DSH_BIN=~/.local/bin/dsh dsh-acp-replay-pincheck
+ *
+ * Env: DSH_BIN (default: dsh), DSH_SHIPPED_PROFILE (acp), DSH_PROFILE (acp-replay),
+ *      PIN_CHECK_TIMEOUT_MS (60000).
+ */
+
+import { spawn } from 'node:child_process'
+
+import { OUTCOMES, describeImage, explainMissingResponse, probeProfile } from './probe.mjs'
+
+const bin = process.env.DSH_BIN ?? 'dsh'
+const shippedProfile = process.env.DSH_SHIPPED_PROFILE ?? 'acp'
+const bridgeProfile = process.env.DSH_PROFILE ?? 'acp-replay'
+const timeoutMs = Number(process.env.PIN_CHECK_TIMEOUT_MS ?? 60000)
+
+function harnessVersion() {
+  return new Promise((resolve) => {
+    const child = spawn(bin, ['--version'], { stdio: ['ignore', 'pipe', 'ignore'] })
+    let stdout = ''
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString()
+    })
+    child.on('error', () => resolve(null))
+    child.on('exit', () => resolve(stdout.split('\n')[0].trim() || null))
+  })
+}
+
+function report(label, profile, result) {
+  const answered =
+    result.kind === OUTCOMES.loadSession
+      ? `advertises loadSession (${describeImage(result)})`
+      : result.message
+  return `${`${label} profile "${profile}"`.padEnd(30)} ${answered}`
+}
+
+const [version, shipped, bridged] = await Promise.all([
+  harnessVersion(),
+  probeProfile({ bin, profile: shippedProfile, timeoutMs }),
+  probeProfile({ bin, profile: bridgeProfile, timeoutMs }),
+])
+
+console.log(`harness: ${bin}${version ? ` (${version})` : ''}`)
+console.log(report('shipped', shippedProfile, shipped))
+console.log(report('bridge', bridgeProfile, bridged))
+
+let outcome
+let advice
+if (shipped.kind === OUTCOMES.loadSession) {
+  outcome = 'upstream'
+  advice = `drop the bridge and unpin; point the client at \`${bin} --profile ${shippedProfile}\``
+} else if (bridged.kind === OUTCOMES.loadSession) {
+  outcome = 'bridge'
+  advice = 'upgrade the harness and move the pin; this bridge answers session/load on it'
+} else {
+  outcome = 'refuses'
+  advice = 'stay on the pinned harness; neither profile advertises session/load'
+}
+
+console.log(`\nPIN: ${outcome} — ${advice}`)
+
+for (const result of [shipped, bridged]) {
+  const hint = explainMissingResponse(result)
+  if (hint) console.log(`\n${hint}`)
+}
+
+const answered = new Set([OUTCOMES.loadSession, OUTCOMES.noLoadSession])
+for (const [profile, result] of [
+  [shippedProfile, shipped],
+  [bridgeProfile, bridged],
+]) {
+  if (answered.has(result.kind) || result.stderr.length === 0) continue
+  console.log(`\n--- ${bin} --profile ${profile} stderr ---\n${result.stderr}`)
+}

package/test/probe.mjs

@@ -0,0 +1,123 @@
+/**
+ * Shared ACP probe for the checks in this directory.
+ *
+ * Boots one profile, performs a single `initialize`, and classifies the answer.
+ * Both `selfcheck.mjs` (one profile) and `pin-check.mjs` (shipped profile plus the
+ * bridged one) are built on this, so the two report the same thing about the same
+ * harness.
+ */
+
+import { spawn } from 'node:child_process'
+
+export const OUTCOMES = {
+  loadSession: 'load-session',
+  noLoadSession: 'no-load-session',
+  noResponse: 'no-response',
+  initializeFailed: 'initialize-failed',
+  spawnFailed: 'spawn-failed',
+  exited: 'exited',
+}
+
+/**
+ * @returns {Promise<{kind: string, message: string, image: boolean | null, stderr: string}>}
+ */
+export async function probeProfile({ bin, profile, timeoutMs = 60000 }) {
+  return new Promise((resolve) => {
+    const child = spawn(bin, ['--profile', profile], { stdio: ['pipe', 'pipe', 'pipe'] })
+
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+
+    function finish(result) {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      child.kill('SIGTERM')
+      resolve({ image: null, ...result, stderr: stderr.trim() })
+    }
+
+    const timer = setTimeout(
+      () =>
+        finish({
+          kind: OUTCOMES.noResponse,
+          message: `no ACP initialize response within ${timeoutMs}ms`,
+        }),
+      timeoutMs,
+    )
+
+    child.on('error', (error) =>
+      finish({ kind: OUTCOMES.spawnFailed, message: `could not start ${bin}: ${error.message}` }),
+    )
+    child.on('exit', (code) =>
+      finish({
+        kind: OUTCOMES.exited,
+        message: `${bin} exited early with code ${code} before answering`,
+      }),
+    )
+
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString()
+    })
+
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString()
+      let index
+      while ((index = stdout.indexOf('\n')) >= 0) {
+        const line = stdout.slice(0, index).trim()
+        stdout = stdout.slice(index + 1)
+        if (line.length === 0) continue
+        let message
+        try {
+          message = JSON.parse(line)
+        } catch {
+          continue
+        }
+        if (message.id !== 1) continue
+        if (message.error) {
+          finish({
+            kind: OUTCOMES.initializeFailed,
+            message: `initialize failed: ${JSON.stringify(message.error).slice(0, 200)}`,
+          })
+          continue
+        }
+        const capabilities = message.result?.agentCapabilities
+        finish({
+          kind:
+            capabilities?.loadSession === true ? OUTCOMES.loadSession : OUTCOMES.noLoadSession,
+          message:
+            capabilities?.loadSession === true
+              ? 'advertises loadSession'
+              : 'the bridge answered but does not advertise loadSession',
+          image: capabilities?.promptCapabilities?.image === true,
+        })
+      }
+    })
+
+    child.stdin.write(
+      `${JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: { protocolVersion: 1, clientCapabilities: {} },
+      })}\n`,
+    )
+  })
+}
+
+export function describeImage(result) {
+  return result.image === true ? 'image: yes' : 'image: no'
+}
+
+/**
+ * `dsh` rewrites the profile's `cordis.yml` while preparing it, so a sandbox that
+ * denies writes to `DSH_HOME` exits on EPERM before answering — which the probe can
+ * only report as "no response", the same text a failed mount produces.
+ */
+export function explainMissingResponse(result) {
+  if (result.kind === OUTCOMES.loadSession || result.kind === OUTCOMES.noLoadSession) return null
+  if (/EPERM|prepareProfile|cordis\.yml/i.test(result.stderr)) {
+    return 'the harness could not write its profile: run this where DSH_HOME is writable (look for EPERM or prepareProfile in its stderr below)'
+  }
+  return null
+}

package/test/probe.test.mjs

@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+
+import { OUTCOMES, describeImage, explainMissingResponse } from './probe.mjs'
+
+test('reports loadSession and the image capability', () => {
+  assert.equal(describeImage({ image: true }), 'image: yes')
+  assert.equal(describeImage({ image: false }), 'image: no')
+  assert.equal(describeImage({ image: null }), 'image: no')
+})
+
+test('explains a silent probe whose harness could not write its profile', () => {
+  const hint = explainMissingResponse({
+    kind: OUTCOMES.noResponse,
+    stderr: 'Error: EPERM: operation not permitted, open cordis.yml',
+  })
+
+  assert.match(hint ?? '', /DSH_HOME is writable/)
+})
+
+test('explains a probe that failed while preparing the profile', () => {
+  const hint = explainMissingResponse({
+    kind: OUTCOMES.exited,
+    stderr: 'prepareProfile failed: read-only file system',
+  })
+
+  assert.match(hint ?? '', /DSH_HOME is writable/)
+})
+
+test('leaves an answered probe alone', () => {
+  assert.equal(
+    explainMissingResponse({ kind: OUTCOMES.loadSession, stderr: 'EPERM cordis.yml' }),
+    null,
+  )
+  assert.equal(
+    explainMissingResponse({ kind: OUTCOMES.noLoadSession, stderr: 'prepareProfile' }),
+    null,
+  )
+})
+
+test('does not guess at an unrelated failure', () => {
+  assert.equal(
+    explainMissingResponse({ kind: OUTCOMES.noResponse, stderr: 'some other error' }),
+    null,
+  )
+})

package/test/replay-check.mjs

@@ -0,0 +1,98 @@
+import { spawn } from 'node:child_process'
+import { mkdirSync, writeFileSync } from 'node:fs'
+
+const dsh = process.env.DSH_BIN
+const home = process.env.DSH_HOME
+const profile = process.env.DSH_PROFILE ?? 'acp-replay'
+const cwd = process.env.TEST_CWD
+
+function start() {
+  const child = spawn(dsh, ['--profile', profile], {
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: { ...process.env },
+  })
+  child.stderr.on('data', (d) => process.stderr.write(`[stderr] ${String(d).slice(0, 200)}\n`))
+  const state = { buffer: '', pending: new Map(), nextId: 1, notifications: [] }
+  child.stdout.on('data', (chunk) => {
+    state.buffer += chunk.toString()
+    let i
+    while ((i = state.buffer.indexOf('\n')) >= 0) {
+      const line = state.buffer.slice(0, i).trim()
+      state.buffer = state.buffer.slice(i + 1)
+      if (!line) continue
+      const msg = JSON.parse(line)
+      if (msg.method) {
+        if (msg.method === 'session/update') state.notifications.push(msg.params)
+        if (msg.id !== undefined) {
+          if (msg.method === 'session/request_permission') {
+            const options = msg.params?.options ?? []
+            const allow = options.find((o) => String(o.kind).startsWith('allow')) ?? options[0]
+            child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: { outcome: { outcome: 'selected', optionId: allow?.optionId } } })}\n`)
+          } else {
+            child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: {} })}\n`)
+          }
+        }
+        continue
+      }
+      const resolve = state.pending.get(msg.id)
+      if (resolve) {
+        state.pending.delete(msg.id)
+        resolve(msg)
+      }
+    }
+  })
+  const request = (method, params, timeoutMs = 300000) => {
+    const id = state.nextId++
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error(`${method} timed out`)), timeoutMs)
+      state.pending.set(id, (msg) => {
+        clearTimeout(timer)
+        resolve(msg)
+      })
+      child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`)
+    })
+  }
+  return { child, request, state }
+}
+
+const phase = process.argv[2]
+
+if (phase === 'record') {
+  const { child, request, state } = start()
+  const init = await request('initialize', { protocolVersion: 1, clientCapabilities: {} })
+  console.log('loadSession advertised:', init.result?.agentCapabilities?.loadSession === true)
+  const created = await request('session/new', { cwd, mcpServers: [] })
+  const sessionId = created.result.sessionId
+  for (const text of ['Reply with exactly: ALPHA', 'Reply with exactly: BETA']) {
+    const out = await request('session/prompt', { sessionId, prompt: [{ type: 'text', text }] })
+    console.log(`prompt "${text}":`, out.error ? `ERROR ${JSON.stringify(out.error).slice(0, 160)}` : JSON.stringify(out.result))
+  }
+  const live = state.notifications.map((n) => n.update.sessionUpdate)
+  console.log('live updates:', [...new Set(live)].join(', '))
+  await request('session/close', { sessionId })
+  writeFileSync('/tmp/dsh-replay-session.txt', sessionId)
+  console.log('SESSION', sessionId)
+  child.stdin.end()
+  setTimeout(() => { child.kill('SIGTERM'); process.exit(0) }, 300)
+} else {
+  const sessionId = process.argv[3]
+  const { child, request, state } = start()
+  const init = await request('initialize', { protocolVersion: 1, clientCapabilities: {} })
+  console.log('loadSession advertised:', init.result?.agentCapabilities?.loadSession === true)
+  state.notifications.length = 0
+  const out = await request('session/load', { sessionId, cwd, mcpServers: [] })
+  if (out.error) {
+    console.log('LOAD ERROR:', JSON.stringify(out.error).slice(0, 300))
+  } else {
+    const updates = state.notifications.map((n) => n.update)
+    const kinds = updates.reduce((acc, u) => ({ ...acc, [u.sessionUpdate]: (acc[u.sessionUpdate] ?? 0) + 1 }), {})
+    console.log('replayed updates:', JSON.stringify(kinds))
+    const users = updates.filter((u) => u.sessionUpdate === 'user_message_chunk').map((u) => u.content?.text)
+    const agents = updates.filter((u) => u.sessionUpdate === 'agent_message_chunk').map((u) => u.content?.text)
+    console.log('replayed user texts:', JSON.stringify(users))
+    console.log('replayed agent texts:', JSON.stringify(agents.map((t) => (t ?? '').slice(0, 40))))
+  }
+  child.stdin.end()
+  setTimeout(() => { child.kill('SIGTERM'); process.exit(0) }, 300)
+}

package/test/selfcheck.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * Self-check for the dsh-acp-replay bridge.
+ *
+ * Boots one profile, performs one ACP `initialize`, and reports whether the
+ * bridge answered and advertised `loadSession`. Run it after any harness
+ * upgrade: if the vendored bridge no longer matches the installed DSH, the
+ * mount-time guard prints its reason to stderr and this script exits non-zero
+ * with that text, instead of leaving "the provider will not start" unexplained.
+ *
+ * Usage:
+ *   DSH_BIN=dsh DSH_PROFILE=acp-replay dsh-acp-replay-selfcheck
+ */
+
+import { OUTCOMES, describeImage, explainMissingResponse, probeProfile } from './probe.mjs'
+
+const bin = process.env.DSH_BIN ?? 'dsh'
+const profile = process.env.DSH_PROFILE ?? 'acp-replay'
+const timeoutMs = Number(process.env.SELFCHECK_TIMEOUT_MS ?? 60000)
+
+const result = await probeProfile({ bin, profile, timeoutMs })
+const ok = result.kind === OUTCOMES.loadSession
+
+console.log(
+  ok
+    ? `OK: profile "${profile}" ${result.message} (${describeImage(result)})`
+    : `FAIL: ${result.message}`,
+)
+
+const hint = explainMissingResponse(result)
+if (hint) console.log(`\n${hint}`)
+
+if (!ok && result.stderr.length > 0) {
+  console.log(`\n--- ${bin} stderr ---\n${result.stderr}`)
+}
+
+process.exit(ok ? 0 : 1)