dsh-gitbash-shell 0.27.0 → 0.29.0

package/src/index.js

@@ -245,8 +245,16 @@ export function effectivePresetIds(configured, { suppress, peerGitBash } = {}) {
   return list.filter((id) => id !== PEER_COVERED_PRESET_ID)
 }
 
-/** Git Bash binary default — must match src/shell.js. */
-const DEFAULT_GIT_BASH = 'C:/Program Files/Git/bin/bash.exe'
+/**
+ * The ONE bash resolver (v0.28.0, issue #11): the executor (src/shell.js) and
+ * this translation layer read the same memoized result, so "dialect translated
+ * to Q:/Git but the executor still spawns C:/Program Files/Git" cannot happen.
+ */
+import {
+  DEFAULT_GIT_BASH, GIT_BASH_DOWNLOAD_URL, bashResolutionReport,
+  effectiveConfiguredBashPath, executorConfiguredBashPath, resolveGitBashCached, settingsBashPath,
+} from './bash-path.js'
+import { adoptTerminalShell, terminalAdoptReport } from './terminal-shell.js'
 
 /** The shipped preset whose skills/ dir seeds cordis-gitbash. */
 const SKILLS_SOURCE_PRESET = 'cordis'
@@ -880,6 +888,16 @@ export const Config = Schema === null ? undefined : Schema.object({
   gitAutocrlf: live(Schema.boolean().default(true)),
   bashPath: live(Schema.string().default('')),
   adoptSidebar: live(Schema.boolean().default(true)),
+  /**
+   * Whether the OFFICIAL sidebar terminal ("new terminal") is switched to the
+   * resolved Git Bash (v0.29.0, task-25). Default ON — the user asked for
+   * exactly this ("自动检测 … 帮忙补上一个 gitbash 可以用"). On Windows without
+   * this, dsh resolves the terminal shell from the environment, which on a
+   * machine whose PATH `bash` is the WSL launcher means the new terminal starts
+   * Ubuntu, not Git Bash. Only ever writes when the terminal has NO shell of
+   * its own: an explicit choice is never overwritten.
+   */
+  autoTerminalShell: live(Schema.boolean().default(true)),
   /**
    * Dedupe switch against dsh-ptc-cordis-preset (their issue #7, v0.25.0):
    * ON while that plugin is installed AND materializing its `PTC 创造模式`
@@ -927,12 +945,15 @@ function makeLiveReader(ctx, config) {
       subagentDialect: valueOf(config.subagentDialect) !== false,
       bashPath: typeof bash === 'string' ? bash : '',
       adoptSidebar: valueOf(config.adoptSidebar) !== false,
+      // Default ON (v0.29.0): the official terminal is ours unless opted out.
+      autoTerminalShell: valueOf(config.autoTerminalShell) !== false,
     }
   }
   return {
     dialect,
     posix: () => dialect().posixPaths === true,
     adoptSidebar: () => dialect().adoptSidebar !== false,
+    autoTerminalShell: () => dialect().autoTerminalShell !== false,
     // Default OFF on both eras: only an explicit true asks for deduplication.
     suppressPeerCordis: () => (legacy || !hasConfig ? readSuppressPeerCordis(ctx) : valueOf(config.suppressPeerCordis) === true),
   }
@@ -999,7 +1020,7 @@ export function readPosixPaths(ctxLike) {
  * first. All default ON (schema defaults); never throws.
  */
 export function readDialectSettings(ctxLike) {
-  const fallback = { posixPaths: false, virtualMounts: false, globSplit: false, errorDialect: false, codePaths: false, gitAutocrlf: false, bashPath: '', subagentDialect: true }
+  const fallback = { posixPaths: false, virtualMounts: false, globSplit: false, errorDialect: false, codePaths: false, gitAutocrlf: false, bashPath: '', subagentDialect: true, autoTerminalShell: true }
   try {
     const settings = ctxLike && typeof ctxLike.get === 'function' ? ctxLike.get('settings') : undefined
     const value = settings && typeof settings.get === 'function' ? settings.get(SETTINGS_NAMESPACE) : undefined
@@ -1012,6 +1033,8 @@ export function readDialectSettings(ctxLike) {
       codePaths: v.codePaths === true,
       // An old host without the key keeps the default (delegated agents covered).
       subagentDialect: v.subagentDialect !== false,
+      // Default ON: a host without the key still gets the terminal adoption.
+      autoTerminalShell: v.autoTerminalShell !== false,
       gitAutocrlf: v.gitAutocrlf === true,
       bashPath: typeof v.bashPath === 'string' ? v.bashPath : '',
     }
@@ -1448,23 +1471,12 @@ export function buildTranslateEnv(configuredBashPath) {
     if (h && existsSync(h)) env.home = h.replace(/\\/g, '/')
   } catch { /* keep undefined */ }
   try {
-    const candidates = []
-    if (cacheKey !== '') candidates.push(cacheKey.replace(/\\/g, '/'))
-    candidates.push(DEFAULT_GIT_BASH)
-    for (const dir of String(process.env.PATH ?? '').split(';')) {
-      const clean = dir && dir.trim()
-      if (clean) candidates.push(clean.replace(/\\/g, '/') + '/bash.exe')
-    }
-    for (const candidate of candidates) {
-      try {
-        if (!existsSync(candidate)) continue
-        const root = dirname(dirname(candidate))
-        if (existsSync(join(root, 'usr', 'bin'))) {
-          env.gitRoot = root.replace(/\\/g, '/')
-          break
-        }
-      } catch { /* try the next candidate */ }
-    }
+    // v0.28.0 (issue #11): ONE resolver for the executor and this layer. Its
+    // chain is setting > default install paths > PATH > registry PATH and it
+    // refuses WSL/MSYS2/Cygwin outright; `cacheKey` is the settings bashPath,
+    // i.e. the same explicit tier the executor reads.
+    const resolution = resolveGitBashCached({ configured: cacheKey })
+    if (resolution.ok) env.gitRoot = resolution.root.replace(/\\/g, '/')
   } catch { /* keep undefined */ }
   translateEnvCache.set(cacheKey, env)
   return env
@@ -2351,7 +2363,28 @@ export async function apply(ctx, config = {}) {
   // plugins (e.g. dsh-ptc-cordis-preset) can adopt it in the presets they
   // materialize: service present, 'active: true' on Windows, 'active: false'
   // where the bundle is installed but the platform stack stayed native.
-  const gitBashCapability = { active: process.platform === 'win32', bashPath: DEFAULT_GIT_BASH }
+  /* The explicit tier of the resolution chain, in its documented priority:
+     the `gitbash-executor` row's own config > the `gitbash-shell` row/settings
+     field > empty (= run the automatic chain). Both this layer and the
+     executor resolve from this same value, so an explicit answer is never
+     substituted and never silently ignored.
+     (issue #11: the row config is where the reporter's workaround landed.) */
+  const configuredBashPath = effectiveConfiguredBashPath(executorConfiguredBashPath(ctx), settingsBashPath(ctx))
+  const bashResolution = resolveGitBashCached({ configured: configuredBashPath })
+  const gitBashCapability = {
+    active: process.platform === 'win32',
+    // Kept for existing consumers (peer plugins read `bashPath`): the resolved
+    // interpreter. When resolution failed we report the explicit value (or the
+    // historical default) so the ENOENT a consumer may hit names a real path —
+    // never a substitute shell.
+    bashPath: bashResolution.ok ? bashResolution.path : (configuredBashPath || DEFAULT_GIT_BASH),
+    // Additive (v0.28.0): the full verdict, for the guided popup and peers.
+    ok: bashResolution.ok,
+    source: bashResolution.source,
+    configured: configuredBashPath,
+    tried: bashResolution.tried,
+    downloadUrl: GIT_BASH_DOWNLOAD_URL,
+  }
   const disposeGitBash = ctx.provide('gitBash', gitBashCapability)
   ctx.effect(() => disposeGitBash, 'dsh-gitbash-shell: gitBash capability')
 
@@ -2398,6 +2431,8 @@ export async function apply(ctx, config = {}) {
             gitAutocrlf: Schema.boolean().default(true),
             bashPath: Schema.string().default(''),
             adoptSidebar: Schema.boolean().default(true),
+            // v0.29.0: official sidebar terminal adoption (default ON).
+            autoTerminalShell: Schema.boolean().default(true),
             // v0.25.0: same switch as the row Config carries on dsh >= 0.1.7
             // (the OLD era has no cross-namespace edits, so this namespace is
             // the only side that can change it here).
@@ -2571,7 +2606,7 @@ export async function apply(ctx, config = {}) {
           // untouched and the result metadata is not echoed back in MSYS form.
           if (dialect.posixPaths && dialectApplies(dialect, exec && exec.agent)) {
             echo = true
-            const env = dialect.virtualMounts ? buildTranslateEnv(dialect.bashPath) : null
+            const env = dialect.virtualMounts ? buildTranslateEnv(configuredBashPath) : null
             echoEnv = env
             if (exec && exec.arguments && typeof exec.arguments === 'object') {
               const translated = translateDispatch(exec, dialect, env)
@@ -2626,7 +2661,7 @@ export async function apply(ctx, config = {}) {
           if (!dialectApplies(dialect, exec && exec.agent)) return next()
           if (dialect.posixPaths && dialect.errorDialect && exec && result && typeof result === 'object'
             && result.isError === true && Array.isArray(result.content)) {
-            const env = dialect.virtualMounts ? buildTranslateEnv(dialect.bashPath) : null
+            const env = dialect.virtualMounts ? buildTranslateEnv(configuredBashPath) : null
             if (exec.name === 'run_code') {
               // paths only — the /dev/null hint is for file tools
               const content = rewriteErrorContent(result.content, { nulHint: false, env })
@@ -2694,12 +2729,99 @@ export async function apply(ctx, config = {}) {
     }
   }
 
+  // ── fail-loud bash report + the client-visible status route (v0.28.0) ──
+  // issue #11: the old failure mode was "every command dies with
+  // `spawn C:/Program Files/Git/bin/bash.exe ENOENT` and nothing explains it".
+  // Now the boot log names the value, the whole probe chain and where to fix
+  // it, and the client half reads the same verdict over HTTP to raise the
+  // guided popup. Nothing here substitutes another shell — by design.
+  console.log(TAG + ' bash resolution: ' + bashResolutionReport(bashResolution).split('\n').join('\n' + TAG + ' '))
+  if (process.platform === 'win32') {
+    try {
+      ctx.inject(['webServer'], (wctx) => {
+        try {
+          const route = '/dsh-gitbash-shell/api/status'
+          const read = () => {
+            const resolution = resolveGitBashCached({ configured: configuredBashPath, fresh: true })
+            return {
+              ok: resolution.ok,
+              platform: process.platform,
+              resolved: resolution.path,
+              root: resolution.root,
+              source: resolution.source,
+              configured: resolution.configured,
+              tried: resolution.tried,
+              downloadUrl: GIT_BASH_DOWNLOAD_URL,
+              settingsHint: 'Settings -> Plugins -> dsh-gitbash-shell -> "Git Bash path"',
+            }
+          }
+          const handler = (req, res) => {
+            const text = JSON.stringify(read())
+            res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'content-length': Buffer.byteLength(text) })
+            res.end(text)
+          }
+          const dispose = wctx.webServer.register({ kind: 'prefix', path: route, handler })
+          wctx.effect(() => dispose, 'dsh-gitbash-shell: bash status route')
+          console.log(TAG + ' bash status route active at ' + route + ' (read by the guided popup)')
+        } catch (error) {
+          console.log(TAG + ' bash status route failed: ' + (error?.message ?? error))
+        }
+      })
+    } catch (error) {
+      console.log(TAG + ' bash status route wiring failed: ' + (error?.message ?? error))
+    }
+  }
+
+  // ── OFFICIAL sidebar terminal adoption (v0.29.0, task-25) ──────────────
+  // User report: dsh's own "new terminal" started WSL, because
+  // `terminal-controller` falls back to the execution environment's default
+  // shell and on that machine PATH's `bash` is the System32 WSL launcher.
+  // The settings service CANNOT be used here (measured: `shell` is not a
+  // volatile field, and there is no `terminal` configurable entry), so this
+  // goes through `configEditor.edit()` — the API the official settings UI
+  // persists through — and it only ever writes when the terminal has no shell
+  // of its own. See src/terminal-shell.js for the full rationale.
+  if (process.platform === 'win32') {
+    try {
+      ctx.inject(['configEditor'], (editorCtx) => {
+        // The terminal row may activate after this plugin; retry a few times
+        // (bounded) instead of silently giving up, and never spam the log.
+        let attempts = 0
+        const run = async () => {
+          attempts += 1
+          let result
+          try {
+            result = await adoptTerminalShell(editorCtx.configEditor, {
+              platform: process.platform,
+              enabled: liveSettings.autoTerminalShell(),
+              resolved: bashResolution.ok ? bashResolution.path : '',
+            })
+          } catch (error) {
+            // adoptTerminalShell reports expected conditions itself; reaching
+            // here means something unexpected — say so instead of swallowing it.
+            console.log(`${TAG} official sidebar terminal adoption crashed: ${error?.message ?? error}`)
+            return
+          }
+          if (result.status === 'skip-row-absent' && attempts < 6) {
+            setTimeout(() => { run().catch((error) => console.log(`${TAG} official sidebar terminal adoption retry failed: ${error?.message ?? error}`)) }, 3000)
+            return
+          }
+          console.log(`${TAG} ${terminalAdoptReport(result)}`)
+        }
+        run().catch((error) => console.log(`${TAG} official sidebar terminal adoption failed: ${error?.message ?? error}`))
+      })
+    } catch (error) {
+      console.log(`${TAG} official sidebar terminal adoption wiring failed: ${error?.message ?? error}`)
+    }
+  }
+
   // ── dsh-better-sidebar terminal adoption (Windows only) ────────────────
   // The sidebar resolves its terminal shell through the settings seam per
   // open; adopt it through that seam (see adoptSidebarShell for rationale).
   // Disable with `betterSidebarShell: false` in the plugin row config.
   if (config.betterSidebarShell !== false && process.platform === 'win32') {
-    adoptSidebarShell(ctx, gitBashCapability.bashPath, () => liveSettings.adoptSidebar())
+    if (bashResolution.ok) adoptSidebarShell(ctx, bashResolution.path, () => liveSettings.adoptSidebar())
+    else console.log(TAG + ' sidebar terminal adoption skipped: no Git Bash resolved (nothing is substituted)')
   }
 
   // ── era split: declarative registration on dsh >= 0.1.7 ──────────────────

package/src/shell.js

@@ -38,10 +38,13 @@
  */
 
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
+
+import { DEFAULT_GIT_BASH, bashResolutionReport, effectiveConfiguredBashPath, resolveGitBashCached, settingsBashPath } from './bash-path.js'
+
+/** Re-exported for callers that historically read it here (the value now lives in bash-path.js). */
+export { DEFAULT_GIT_BASH }
 import z from '@deepseek-ai/schemastery'
 
-/** Default Git for Windows bash (forward slashes work on Windows too). */
-export const DEFAULT_GIT_BASH = 'C:/Program Files/Git/bin/bash.exe'
 
 /** Log prefix, matching src/index.js. */
 const TAG = '[gitbash-shell]'
@@ -95,7 +98,12 @@ export function gitBashShellConfig(z) {
     graceMs: live(z.number().default(3000)),
     // Our own knob: the base class neither declares nor `.get()`s it, and
     // `get bashPath()` below reads it as a plain value, so it stays plain.
-    bashPath: z.string().default(DEFAULT_GIT_BASH),
+    //
+    // EMPTY means AUTO (v0.28.0, issue #11): the shared resolver walks
+    // setting > default install paths > PATH > registry PATH and refuses WSL /
+    // MSYS2 / Cygwin. A hard-coded default here is what made a Git installed
+    // outside C:/Program Files look like "dsh is broken".
+    bashPath: z.string().default(''),
   })
 }
 
@@ -107,9 +115,49 @@ export class GitBashSandboxExecutor extends SandboxBashExecutor {
   static inject = ['subprocess', 'sandbox', 'sandboxPolicy']
   static Config = Config
 
-  /** Effective Git Bash path: composition/config value with the default fallback. */
+  /**
+   * Effective Git Bash path. The configured value wins when it is non-empty
+   * (the user's explicit answer is never substituted); otherwise the SHARED
+   * resolver decides — the very same result the path-dialect translation layer
+   * uses, so "dialect works, executor cannot find bash" (issue #11) is
+   * structurally impossible.
+   *
+   * A failed resolution returns '' — deliberately NOT a substitute shell. Every
+   * argv built from it then fails loudly on spawn; `apply()` has already
+   * printed the full report, and the client half shows the guided popup.
+   */
   get bashPath() {
-    return this.config.bashPath ?? DEFAULT_GIT_BASH
+    return this.bashResolution().path
+  }
+
+  /**
+   * Resolve the interpreter with the SAME merged explicit tier the main plugin
+   * uses (executor row config > `gitbash-shell` settings row > empty = auto),
+   * so both halves of the plugin always agree on which bash this process runs.
+   * @returns {object} the memoized resolution verdict.
+   */
+  bashResolution() {
+    const configured = effectiveConfiguredBashPath(this.config.bashPath, settingsBashPath(this.ctx))
+    return resolveGitBashCached({ configured })
+  }
+
+  /**
+   * The resolved Git Bash path, or a THROW that says exactly what is wrong.
+   *
+   * The throw is the design (AGENTS.md §4h): with no Git Bash there is no
+   * command execution at all — we do not substitute pwsh, cmd, WSL or MSYS2,
+   * and we do not let a bare `spawn ENOENT` be the only thing the user sees.
+   * The boot log carries the same report (src/index.js) and the client half
+   * shows the guided popup with the probed list.
+   * @returns {string} the resolved interpreter path.
+   */
+  requireBashPath() {
+    const resolution = this.bashResolution()
+    if (!resolution.ok) {
+      throw new Error('dsh-gitbash-shell: no Git for Windows bash found, so this command cannot run. '
+        + bashResolutionReport(resolution).split('\n').slice(1).join(' | '))
+    }
+    return resolution.path
   }
 
   /**
@@ -129,7 +177,7 @@ export class GitBashSandboxExecutor extends SandboxBashExecutor {
    * @returns the provider's exact argv and settlement-classification facts (a promise on dsh >= 0.1.6).
    */
   confine(command, policy, signal) {
-    return this.ctx.sandbox.confine([this.bashPath, '-c', command], policy, signal)
+    return this.ctx.sandbox.confine([this.requireBashPath(), '-c', command], policy, signal)
   }
 
   /**
@@ -219,7 +267,7 @@ export class GitBashSandboxExecutor extends SandboxBashExecutor {
     const routed = this.withParityEnv(spec)
     const route = this.gitBashRoute(routed)
     if (route === undefined) return super.execute(routed)
-    const argv = [this.bashPath, '-c', routed.command]
+    const argv = [this.requireBashPath(), '-c', routed.command]
     if (route.unconfined) this.warnConfinedUnconfined(route.mode)
     const sandbox = route.unconfined
       ? { mode: route.mode, denied: false, enforcement: 'unconfined' }
@@ -304,13 +352,13 @@ export class GitBashSandboxExecutor extends SandboxBashExecutor {
     const { mode } = policy
     if (mode === 'danger-full-access') {
       const { result } = GitBashSandboxExecutor.unwrapRunArgv(
-        await this.runArgv(spec, [this.bashPath, '-c', spec.command]))
+        await this.runArgv(spec, [this.requireBashPath(), '-c', spec.command]))
       return { ...result, sandbox: { mode, denied: false } }
     }
     if (process.platform === 'win32') {
       this.warnConfinedUnconfined(mode)
       const { result, spawnRequested } = GitBashSandboxExecutor.unwrapRunArgv(
-        await this.runArgv(spec, [this.bashPath, '-c', spec.command]))
+        await this.runArgv(spec, [this.requireBashPath(), '-c', spec.command]))
       // No spawn means no argv ran, so there is nothing to label as
       // unconfined; the parent reports the same bare sandbox facts there.
       return { ...result, sandbox: spawnRequested ? { mode, denied: false, enforcement: 'unconfined' } : { mode, denied: false } }
@@ -326,7 +374,7 @@ export class GitBashSandboxExecutor extends SandboxBashExecutor {
     const fullAccess = mode === 'danger-full-access'
     if (fullAccess || process.platform === 'win32') {
       if (!fullAccess) this.warnConfinedUnconfined(mode)
-      const proc = this.startArgv(spec, [this.bashPath, '-c', spec.command])
+      const proc = this.startArgv(spec, [this.requireBashPath(), '-c', spec.command])
       proc.sandbox = fullAccess ? { mode, denied: false } : { mode, denied: false, enforcement: 'unconfined' }
       // Match the loaded base contract: the async one (dsh >= 0.1.6) is
       // awaited by its callers, the synchronous one is consumed directly.

package/src/terminal-shell.js

@@ -0,0 +1,206 @@
+/**
+ * dsh-gitbash-shell — OFFICIAL sidebar terminal adoption (v0.29.0, task-25).
+ *
+ * THE PROBLEM (user report, Windows 11): dsh's own "new terminal" starts WSL,
+ * not Git Bash. `terminal-controller` resolves its shell from
+ * `subprocess.terminalEnvironment().defaultShell` when no `shell` is configured,
+ * and on that machine the PATH hit for `bash` is
+ * `C:\WINDOWS\system32\bash.EXE` — the Microsoft WSL launcher. The agent tools
+ * are already ours (`pwsh-sandbox` out, `gitbash-executor` in), but the sidebar
+ * terminal is a DIFFERENT row with a different shell resolution, so it kept
+ * starting WSL.
+ *
+ * WHY THIS MODULE TALKS TO `configEditor` AND NOT TO `settings`
+ * (measured on dsh 0.1.7-rc.2, probe readout in the task notes):
+ *   - `settings.update('terminal', …)` is impossible twice over:
+ *     `SettingsService.write()` requires every written path to be VOLATILE
+ *     (`volatileForm(schema)` → `undefined` ⇒ "Plugin entry … has no volatile
+ *     fields"), and `terminal-controller`'s Config declares `shell` as an
+ *     ordinary field. The probe also showed no `terminal` entry at all
+ *     ("No configurable plugin entry \"terminal\"").
+ *   - `configEditor.edit(entry, change)` is the API the official settings UI
+ *     itself persists through, documented as "ordinary fields keep normal
+ *     lifecycle rules". The probe wrote `shell` and the RUNNING
+ *     `ctx.terminalController.config.shell` carried it on the next read — no
+ *     restart. The write lands in the profile patch document through the
+ *     official YAML editor (comment-preserving, id-merged, file-locked); we
+ *     never hand-edit that file ourselves.
+ *
+ * HARD RULES (same discipline as §4h):
+ *   1. NEVER overwrite an explicit choice. If the terminal already points
+ *      somewhere else (another bash, a WSL profile, pwsh), we log and stop —
+ *      the user's decision outranks our automation.
+ *   2. NEVER write a shell we have not verified. `resolveShell` rejects an
+ *      unresolvable path with `SubprocessExecutableNotFoundError` and has NO
+ *      fallback, so a bad write would break the new-terminal button outright.
+ *      The path written here is always the one `src/bash-path.js` verified
+ *      (exists + Git-for-Windows layout + `.windows.` fingerprint + `uname -s`
+ *      = MINGW*_NT-*).
+ *   3. NEVER claim success without reading the value back. `edit()` resolving
+ *      is not proof the row carries our shell, so `adoptTerminalShell` re-reads
+ *      `configuration()` and reports `write-failed` when the value is not there
+ *      (§4h: no silent false success).
+ */
+
+import { normalizeBashPath } from './bash-path.js'
+
+/** The Loader row id of the official terminal controller. */
+export const TERMINAL_ROW_ID = 'terminal-controller'
+
+/** Profile name written for Git Bash — matches the official `profile()` output. */
+export const TERMINAL_SHELL_NAME = 'bash'
+
+/**
+ * Arguments written for Git Bash. `['-i']` is not our invention: the official
+ * `profile()` in `packages/api/terminal-controller/src/shells.ts` derives
+ * exactly `['-i']` for any shell that is not cmd/pwsh/powershell, and `-i`
+ * makes bash read its rc files in the interactive terminal.
+ */
+export const TERMINAL_SHELL_ARGS = ['-i']
+
+/**
+ * The shell profile we write into `terminal-controller`'s config.
+ * @param path - verified Git Bash path.
+ * @returns the `{ path, name, args }` profile.
+ */
+export function terminalShellProfile(path) {
+  return { path, name: TERMINAL_SHELL_NAME, args: [...TERMINAL_SHELL_ARGS] }
+}
+
+/**
+ * The effective explicit shell of the terminal row: the user patch's override
+ * wins over the composed bundle default (which is usually absent). Treats a
+ * malformed shape as "not set" so a broken hand edit cannot make us believe
+ * there is a user choice to respect.
+ * @param row - one `configEditor.configuration()` entry, or undefined.
+ * @returns the current shell profile, or undefined when unset.
+ */
+export function currentTerminalShell(row) {
+  if (row === null || row === undefined) return undefined
+  const value = row.override !== null && row.override !== undefined && 'shell' in row.override
+    ? row.override.shell
+    : (row.inherited === null || row.inherited === undefined ? undefined : row.inherited.shell)
+  if (value === null || typeof value !== 'object') return undefined
+  const path = value.path
+  if (typeof path !== 'string' || path.trim() === '') return undefined
+  return {
+    path,
+    name: typeof value.name === 'string' ? value.name : '',
+    args: Array.isArray(value.args) ? value.args : [],
+  }
+}
+
+/**
+ * Decide what to do about the terminal shell. Pure: every fact arrives as an
+ * argument, which is why the whole matrix (empty / same / other / disabled /
+ * unresolved / non-Windows) is unit-testable anywhere.
+ * @param {object} input - decision input.
+ * @param {string} input.platform - `process.platform` of the host.
+ * @param {boolean} input.enabled - the `autoTerminalShell` switch.
+ * @param {string} input.resolved - the verified Git Bash path ('' when unresolved).
+ * @param {object} [input.current] - current terminal shell profile, if any.
+ * @returns {{action: string, shell?: object, current?: object, reason: string}} the plan.
+ */
+export function planTerminalAdopt({ platform, enabled, resolved, current }) {
+  if (platform !== 'win32') return { action: 'skip-platform', reason: 'not a Windows host; the official terminal keeps its own shell' }
+  if (enabled !== true) return { action: 'skip-disabled', reason: 'the autoTerminalShell switch is off' }
+  if (typeof resolved !== 'string' || resolved.trim() === '') {
+    return { action: 'skip-unresolved', reason: 'no verified Git Bash to offer (see the bash resolution report)' }
+  }
+  if (current === undefined || current === null) {
+    return { action: 'adopt', shell: terminalShellProfile(resolved.trim()), reason: 'the terminal has no shell configured; offering the verified Git Bash' }
+  }
+  if (normalizeBashPath(current.path) === normalizeBashPath(resolved)) {
+    return { action: 'unchanged', current, reason: 'the terminal already uses this Git Bash' }
+  }
+  return {
+    action: 'kept-user-choice',
+    current,
+    reason: 'the terminal shell points at "' + current.path + '" — an explicit choice is never overwritten; clear that field (Settings → the terminal row) to let Git Bash take over',
+  }
+}
+
+/**
+ * Apply the plan through the official config editor, then READ THE VALUE BACK.
+ * @param {object} editor - `ctx.configEditor` (or a stand-in in tests).
+ * @param {object} options - adoption options.
+ * @param {string} options.platform - host platform.
+ * @param {boolean} options.enabled - `autoTerminalShell` switch.
+ * @param {string} options.resolved - verified Git Bash path ('' when unresolved).
+ * @returns {Promise<{status: string, action?: string, path?: string, current?: object, detail?: string}>}
+ *   the outcome; `status` is one of the plan actions plus `skip-row-absent`
+ *   and `write-failed`. The caller logs it — this function never lies about
+ *   success and never throws for an expected condition.
+ */
+export async function adoptTerminalShell(editor, { platform, enabled, resolved }) {
+  if (editor === null || editor === undefined || typeof editor.configuration !== 'function') {
+    return { status: 'skip-row-absent', detail: 'the config editor is unavailable, so the terminal row cannot be configured' }
+  }
+  const rows = editor.configuration()
+  const row = Array.isArray(rows) ? rows.find((candidate) => candidate.entry?.options?.id === TERMINAL_ROW_ID) : undefined
+  if (row === undefined) {
+    return { status: 'skip-row-absent', detail: 'the "' + TERMINAL_ROW_ID + '" row is not mounted in this profile' }
+  }
+  const current = currentTerminalShell(row)
+  const plan = planTerminalAdopt({ platform, enabled, resolved, current })
+  if (plan.action !== 'adopt') {
+    return { status: plan.action, current, detail: plan.reason }
+  }
+  if (typeof editor.edit !== 'function') {
+    return { status: 'write-failed', current, detail: 'the config editor exposes no edit()' }
+  }
+  try {
+    await editor.edit(row.entry, (raw) => ({ ...raw, shell: plan.shell }))
+  } catch (error) {
+    return { status: 'write-failed', current, detail: 'the official config editor refused the write: ' + (error && error.message ? error.message : String(error)) }
+  }
+  // Read back: `edit()` resolving is NOT proof the row now carries our shell.
+  let after
+  try {
+    const rowsAfter = editor.configuration()
+    after = Array.isArray(rowsAfter) ? rowsAfter.find((candidate) => candidate.entry?.options?.id === TERMINAL_ROW_ID) : undefined
+  } catch (error) {
+    return { status: 'write-failed', current, detail: 'the write succeeded but reading it back failed: ' + (error && error.message ? error.message : String(error)) }
+  }
+  const written = currentTerminalShell(after)
+  if (written === undefined || normalizeBashPath(written.path) !== normalizeBashPath(plan.shell.path)) {
+    return {
+      status: 'write-failed',
+      current,
+      detail: 'the write did not stick: the terminal row reads ' + (written === undefined ? '(no shell)' : '"' + written.path + '"'),
+    }
+  }
+  return { status: 'adopted', path: plan.shell.path, current }
+}
+
+/**
+ * The one-line log for an adoption outcome (the caller prints it). Kept here so
+ * the wording stays identical between the boot path and the tests.
+ * @param {object} result - an {@link adoptTerminalShell} result.
+ * @returns {string} the log line, without the plugin tag.
+ */
+export function terminalAdoptReport(result) {
+  switch (result.status) {
+    case 'adopted':
+      return 'official sidebar terminal switched to Git Bash: ' + result.path + ' (name bash, args -i) — new terminals use it immediately, already-open ones keep their shell'
+    case 'unchanged':
+      return 'official sidebar terminal already uses this Git Bash: ' + (result.current ? result.current.path : '') + ' (nothing written)'
+    case 'kept-user-choice':
+      return 'official sidebar terminal NOT adopted: ' + result.detail
+    case 'write-failed':
+      return 'official sidebar terminal adoption FAILED — ' + result.detail
+        + ' | next steps: (1) the new-terminal shell is UNCHANGED, so dsh keeps its own resolution;'
+        + ' (2) set the terminal by hand: add `shell: { path: <git-bash>, name: bash, args: [\'-i\'] }` to the'
+        + ' `terminal-controller` row in the profile patch and restart dsh;'
+        + ' (3) or turn this plugin\'s "autoTerminalShell" switch off to stop the attempts;'
+        + ' (4) the full cause is in the lines above.'
+    case 'skip-disabled':
+      return 'official sidebar terminal adoption is off (autoTerminalShell = false) — the new-terminal shell stays whatever dsh resolves'
+    case 'skip-unresolved':
+      return 'official sidebar terminal adoption skipped: no verified Git Bash (nothing is substituted)'
+    case 'skip-platform':
+      return 'official sidebar terminal adoption applies to Windows only'
+    default:
+      return 'official sidebar terminal adoption skipped: ' + (result.detail ?? result.status)
+  }
+}