@banbolee/dsh-fish-shell 0.4.1 → 0.5.0

package/policy.js

@@ -0,0 +1,346 @@
+/**
+ * Per-agent fish policy for DeepSeek Harness: whatever agent preset a session
+ * uses (standard, ptc, cordis, minimal, or a third-party preset), its agent
+ * must see the host-global `fish` tool and never a `bash` tool inherited from
+ * the preset's standing scope.
+ *
+ * The bundle's patch (`cordis.patch.yml`) disables the host bash executor and
+ * host `tool-bash`, mounts the fish executor and the host-global `fish` tool,
+ * and NO LONGER changes the preset roster default. Presets keep registering
+ * their own `bash`-named tool (standard/minimal do), and the model would see
+ * a lying "bash" card that actually executes fish — or, under `minimal`, a
+ * real persistent PTY bash. This plugin fixes that at the agent boundary:
+ *
+ *   - `agent/created` (fired synchronously at the agent publication edge,
+ *     before its first turn — the same hook dsh-tool-subagent uses) applies
+ *     the policy to the new agent.
+ *   - `tools/change` (fired after any preset recompose, e.g. `/preset`)
+ *     reconciles every live agent. The reconcile is re-entrancy-guarded: the
+ *     policy's own restriction/prompt/persistent registrations and disposals
+ *     synchronously fire `tools/change` themselves, and without a guard one
+ *     external change cascades into a factorial dispatch storm across agents.
+ *     Events arriving mid-round are coalesced into at most ONE catch-up
+ *     round, and agents whose preset parent scope is unchanged are skipped
+ *     entirely (their installed state — including the persistent fish tool —
+ *     is left untouched).
+ *   - When the inherited `bash` tool is the PERSISTENT form (the official
+ *     `dsh-tool-bash-persistent` signature: parameters hold only `command`
+ *     and the output schema is a plain string — the `minimal` preset), the
+ *     policy first registers a persistent `fish` tool at the agent scope
+ *     (`persistent.js`), which shadows the host-global one-shot fish, so
+ *     minimal sessions keep their persistent semantics (cwd, variables,
+ *     functions) in fish. On a preset switch the previous persistent fish is
+ *     removed BEFORE probing fish visibility: an agent-scope persistent fish
+ *     must never count as "inherited fish visible", or a switch into a
+ *     deny-fish allowlist preset would wrongly keep bash hidden.
+ *   - `tools.restrict({ deny: ['bash'] })` through `agent.ctx` filters the
+ *     bash the agent INHERITS from the global and preset-ancestor layers.
+ *   - The preset's static `tool:bash` prompt section is not removed by the
+ *     restriction, so an empty agent-scoped section with the same name
+ *     shadows it (scoped sections shadow ancestor/global ones). Installation
+ *     is transactional: a failure (e.g. a third-party agent that registered
+ *     its own `tool:bash` section) rolls back everything THIS call created,
+ *     so no half-installed restriction leaks.
+ *   - Plugin teardown (unload/disable/HMR) strips the policy from every live
+ *     agent: the bash restriction, the `tool:bash` shadow, and any
+ *     persistent fish registration are removed so nothing outlives the
+ *     plugin.
+ *
+ * The plugin uses the injected `tools` / `systemPrompt` services and
+ * `ctx.get('agents')`; `persistent.js` (imported only for the persistent
+ * form) brings in `@deepseek-ai/dsh-tools`' `defineTool`, and
+ * `@deepseek-ai/dsh-scope`'s `scopeParentOf` identifies the preset standing
+ * scope an agent's policy was installed under.
+ *
+ * @module @banbolee/dsh-fish-shell/policy
+ */
+
+import { scopeParentOf } from '@deepseek-ai/dsh-scope'
+import { registerPersistentFish } from './persistent.js'
+
+export const name = 'fish-preset-policy'
+export const inject = ['tools', 'systemPrompt']
+
+const PLUGIN_TAG = '@banbolee/dsh-fish-shell'
+
+/** Agents currently being reconciled (guards the synchronous tools/change
+ * re-entry that restriction/prompt registration and disposal trigger). */
+const installing = new WeakSet()
+/** Agents already warned about an invisible fish tool (warn once per agent). */
+const warned = new WeakSet()
+/** Agents uninstalled via `agent/disposed`: a tools/change fired by the
+ * uninstall's own disposals must not re-install a dying agent. */
+const removed = new WeakSet()
+/** Per-agent policy state, including disposers that must move with /preset. */
+const states = new WeakMap()
+/** Live agents with policy installed; traversable so plugin teardown can
+ * strip every registration (a WeakMap would be unreachable on teardown). */
+const liveAgents = new Set()
+/** Global reconcile re-entrancy guard: a tools/change arriving while a
+ * reconcile round is in flight marks `reconcilePending` instead of starting a
+ * nested round; the current round runs exactly one coalesced catch-up round
+ * afterwards. */
+let reconciling = false
+let reconcilePending = false
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function disposeQuietly(disposer, label, agent) {
+  if (disposer === undefined) return
+  try {
+    const result = disposer()
+    // Async disposers (persistent fish cleanup) are awaited out-of-band so a
+    // failing teardown is recorded instead of unhandled.
+    if (result !== undefined && typeof result.then === 'function') {
+      void Promise.resolve(result).catch((error) => {
+        console.warn(`${PLUGIN_TAG}: could not dispose ${label} for agent ${agent.id ?? '(unnamed)'}:`, String(error))
+      })
+    }
+  } catch (error) {
+    console.warn(`${PLUGIN_TAG}: could not dispose ${label} for agent ${agent.id ?? '(unnamed)'}:`, String(error))
+  }
+}
+
+function disposeState(agent, state) {
+  disposeQuietly(state.prompt, 'tool:bash prompt shadow', agent)
+  disposeQuietly(state.restriction, 'bash restriction', agent)
+  disposeQuietly(state.persistentFish, 'persistent fish tool', agent)
+}
+
+function removeTransientPolicy(agent, state) {
+  disposeQuietly(state?.prompt, 'tool:bash prompt shadow', agent)
+  disposeQuietly(state?.restriction, 'bash restriction', agent)
+}
+
+/**
+ * Detect the official persistent-bash tool signature (`dsh-tool-bash-
+ * persistent`): a definition whose parameters carry ONLY `command` and whose
+ * output schema is a plain string. The one-shot bash tool (command +
+ * description + workdir + timeoutMs + run_in_background +
+ * sandbox_permissions…) and every other tool shape fall through.
+ * @param definition - the tool definition an agent resolves for `bash`.
+ * @returns true when the agent's bash is the persistent PTY form.
+ */
+export function isPersistentBashForm(definition) {
+  if (!isPlainObject(definition)) return false
+  const schema = definition.output?.schema
+  if (!isPlainObject(schema) || schema.type !== 'string') return false
+  const parameters = definition.parameters
+  if (!isPlainObject(parameters)) return false
+  // Official persistent bash: parameters is a property map holding ONLY
+  // `command` (schemastery shape, no JSON-Schema wrapper).
+  const keys = Object.keys(parameters)
+  if (keys.length === 1 && keys[0] === 'command') return true
+  // Defensive: a JSON-Schema-normalized variant with `properties` holding
+  // only `command`.
+  const properties = parameters.properties
+  return isPlainObject(properties) && Object.keys(properties).length === 1 && Object.hasOwn(properties, 'command')
+}
+
+/** Remove every policy-owned registration for an agent. */
+export function uninstallFishPolicy(agent) {
+  liveAgents.delete(agent)
+  removed.add(agent)
+  const state = states.get(agent)
+  if (state === undefined) return
+  states.delete(agent)
+  disposeState(agent, state)
+}
+
+/**
+ * Apply the fish policy to one agent: hide its inherited `bash` tool and
+ * shadow the `tool:bash` prompt guidance, leaving only the appropriate `fish`
+ * tool. Recomputed on every preset switch (the agent's parent scope key
+ * changed); an unchanged preset parent makes the call a no-op so unrelated
+ * `tools/change` events cannot churn the restriction or reset the persistent
+ * fish. Installation is transactional: nothing is committed to `states`
+ * until every registration succeeded, and a failure rolls back only the
+ * disposers THIS call created.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx - the policy plugin's context.
+ * @param {object} agent - the live agent (its `ctx` is the agent's scoped context).
+ */
+export function installFishPolicy(ctx, agent) {
+  if (installing.has(agent)) return
+  // The agent was uninstalled (agent/disposed): a tools/change fired by that
+  // uninstall's own disposals must not re-install a dying agent.
+  if (removed.has(agent)) return
+
+  installing.add(agent)
+  const previous = states.get(agent)
+  const parentKey = scopeParentOf(agent)
+  try {
+    // Fast path: the agent already has a policy installed under the SAME
+    // preset parent scope. Nothing relevant changed for this agent, so an
+    // unrelated tools/change (host tools, other agents' registrations) must
+    // not dispose and re-register anything — that churn is what turned one
+    // external change into a factorial dispatch storm across agents, and it
+    // would reset a persistent fish (dropping its PTY) for no reason.
+    if (previous !== undefined && previous.parentKey === parentKey) return
+
+    // Preset switch or first install: lift everything this policy owns so the
+    // probes below see the target preset's true inherited surface. The old
+    // persistent fish is removed BEFORE probing fish visibility — an
+    // agent-scope persistent fish would otherwise count as "fish visible" and
+    // let a deny-fish allowlist preset pass through with bash still hidden.
+    removeTransientPolicy(agent, previous)
+    disposeQuietly(previous?.persistentFish, 'persistent fish tool', agent)
+
+    const bash = ctx.tools.get('bash', agent)
+    if (bash === undefined) {
+      states.delete(agent)
+      return
+    }
+
+    const wantsPersistent = isPersistentBashForm(bash)
+    const fish = ctx.tools.get('fish', agent)
+    if (fish === undefined) {
+      // The preset deliberately excludes the global fish tool (an allowlist),
+      // so there is nothing to swap bash for — leave the preset as authored and
+      // warn once per agent instead of mutating it.
+      if (!warned.has(agent)) {
+        warned.add(agent)
+        console.warn(
+          `${PLUGIN_TAG}: agent ${agent.id ?? '(unnamed)'} has no visible fish tool `
+          + '(its preset allowlist excludes the global fish tool); leaving its inherited bash tool in place',
+        )
+      }
+      states.delete(agent)
+      return
+    }
+
+    // Transactional install. `persistentFish` is created by THIS call (the
+    // previous one, if any, was already removed above as part of the switched-
+    // away state), so the failure path below rolls back exactly what this call
+    // created and never destroys a registration it reused.
+    let persistentFish
+    if (wantsPersistent) {
+      // The minimal preset's persistent bash is swapped for persistent fish
+      // at the agent scope (shadowing the host-global one-shot fish) BEFORE
+      // bash is hidden, so minimal sessions keep persistent semantics.
+      persistentFish = registerPersistentFish(ctx, agent.ctx)
+    }
+    const created = []
+    try {
+      const restriction = agent.ctx.tools.restrict({ deny: ['bash'] })
+      created.push(() => disposeQuietly(restriction, 'bash restriction', agent))
+      const prompt = agent.ctx.systemPrompt.section({
+        name: 'tool:bash',
+        order: agent.ctx.systemPrompt.getSectionOrder('TOOL_BASH'),
+        text: '',
+      })
+      created.push(() => disposeQuietly(prompt, 'tool:bash prompt shadow', agent))
+      states.set(agent, {
+        kind: wantsPersistent ? 'persistent' : 'one-shot',
+        parentKey,
+        persistentFish,
+        restriction,
+        prompt,
+      })
+    } catch (error) {
+      // Roll back in reverse registration order, then drop this call's new
+      // persistent fish. The previous state's entries were already removed
+      // above, so `states` ends up consistent: no restriction, no shadow, no
+      // persistent fish — bash stays visible and the failure is surfaced.
+      for (let index = created.length - 1; index >= 0; index -= 1) created[index]()
+      disposeQuietly(persistentFish, 'persistent fish tool', agent)
+      throw error
+    }
+  } catch (error) {
+    states.delete(agent)
+    console.warn(`${PLUGIN_TAG}: could not hide bash for agent ${agent.id ?? '(unnamed)'}:`, String(error))
+  } finally {
+    installing.delete(agent)
+  }
+}
+
+/** Apply the policy to every live agent (no-op when the agents service is
+ * absent). Re-entrant calls (a registration/disposal mid-round fires
+ * `tools/change` synchronously) are absorbed into at most ONE coalesced
+ * catch-up round, so an external change dispatches a small constant number
+ * of times regardless of how many agents are live. */
+function reconcile(ctx, catchUp = false) {
+  if (reconciling) {
+    reconcilePending = true
+    return
+  }
+  reconciling = true
+  try {
+    for (const agent of ctx.get('agents')?.list() ?? []) {
+      liveAgents.add(agent)
+      try {
+        installFishPolicy(ctx, agent)
+      } catch (error) {
+        console.warn(`${PLUGIN_TAG}: policy reconcile failed for agent ${agent.id ?? '(unnamed)'}:`, String(error))
+      }
+    }
+  } finally {
+    reconciling = false
+  }
+  if (reconcilePending && !catchUp) {
+    // One coalesced catch-up round for changes that arrived mid-round (e.g.
+    // another plugin's listener mutated the tool surface). The catch-up round
+    // itself never re-triggers: every installed agent fast-paths on its
+    // parent key, so dispatch count stays bounded.
+    reconcilePending = false
+    reconcile(ctx, true)
+  } else {
+    reconcilePending = false
+  }
+}
+
+/**
+ * Cordis plugin entry: install the per-agent fish policy at the agent
+ * publication edge and on every tools/change, cover agents that already
+ * exist (plugin hot-reload), and strip every live-agent registration on
+ * plugin teardown.
+ * @param {import('@deepseek-ai/cordis').Context} ctx - the harness context.
+ */
+export function apply(ctx) {
+  // Set while this plugin's teardown runs so the listeners below (still
+  // registered — they were created before the teardown effect, which cordis
+  // disposes first) cannot re-install a policy being torn down.
+  let disposed = false
+  // `agent/created` fires synchronously at the agent publication boundary
+  // (before the agent's first turn); a synchronous listener error would
+  // propagate into the publish path, so every failure is contained here.
+  ctx.on('agent/created', ({ agent }) => {
+    if (disposed) return
+    liveAgents.add(agent)
+    try {
+      installFishPolicy(ctx, agent)
+    } catch (error) {
+      console.warn(`${PLUGIN_TAG}: agent/created policy install failed for ${agent.id ?? '(unnamed)'}:`, String(error))
+    }
+  })
+  ctx.on('agent/disposed', ({ agent }) => {
+    if (disposed) return
+    try {
+      uninstallFishPolicy(agent)
+    } catch (error) {
+      console.warn(`${PLUGIN_TAG}: agent/disposed policy cleanup failed for ${agent.id ?? '(unnamed)'}:`, String(error))
+    }
+  })
+  ctx.on('tools/change', () => {
+    if (disposed) return
+    reconcile(ctx)
+  })
+  // Plugin-owned teardown (unload/disable/HMR): registered LAST so cordis
+  // disposes it FIRST (effects run in reverse registration order) — while
+  // this loop's own tools/change events are still delivered, `disposed`
+  // above makes the listeners no-ops, so uninstalling cannot re-install.
+  ctx.effect(() => () => {
+    disposed = true
+    for (const agent of [...liveAgents]) {
+      try {
+        uninstallFishPolicy(agent)
+      } catch (error) {
+        console.warn(`${PLUGIN_TAG}: policy teardown failed for agent ${agent.id ?? '(unnamed)'}:`, String(error))
+      }
+    }
+    liveAgents.clear()
+  }, 'fish preset policy teardown')
+  reconcile(ctx)
+}

package/terminal-fish.js

@@ -0,0 +1,317 @@
+/**
+ * Library: the persistent `fish` PTY backend for DeepSeek Harness — a
+ * `BashTerminalBackend` subclass that spawns `fish --no-config -i`
+ * (config-overridable) instead of bash, with a fish prompt that speaks the
+ * shared `LocalPtySession` readiness contract (OSC `133;D;<status>` + a
+ * `dsh> ` prompt tail), and the same sandbox confinement and mode fence as
+ * the official bash backend.
+ *
+ * The readiness contract was verified against real fish 4.0.0: with
+ * `TERM=dumb` (the backend's child environment, same as official bash),
+ * fish's reader emits no cursor/redraw sequences after the prompt text, so
+ * the sanitizer sees exactly `dsh> ` after the OSC marker and readiness
+ * settles promptly. The prompt setup is submitted as ONE line (semicolon
+ * function bodies) and builds the ESC/BEL bytes at runtime through fish
+ * `printf` escapes (`\x1b`, `\x07`), mirroring the official pwsh prompt's
+ * runtime-escape approach — raw ESC bytes in submitted PTY input are
+ * unreliable under a line editor.
+ *
+ * This module is NOT mounted by the bundle patch (there is no `fish-terminal`
+ * host row): the `terminals` service is entry-local to the `minimal` preset
+ * and invisible at the host/agent plane, so a patch row would stay pending
+ * forever in host-plane profiles. Instead the policy's persistent tool
+ * (`persistent.js`) constructs one `FishTerminalBackend` itself and drives
+ * its sessions directly. `apply` below is kept for direct assembly and
+ * tests (a context that already mounts the `terminals` registry).
+ *
+ * `@deepseek-ai/dsh-terminal-bash` does not export its private
+ * `ensureSandboxModeFence`/`spawnArgv`/`startupSession` helpers, so the
+ * minimal pieces this backend needs are copied here (marked with their
+ * official source) rather than monkey-patching the official module.
+ *
+ * @module @banbolee/dsh-fish-shell/terminal-fish
+ */
+
+import { BashTerminalBackend } from '@deepseek-ai/dsh-terminal-bash'
+import { TerminalBackendCleanupError } from '@deepseek-ai/dsh-terminal'
+
+/** Cordis plugin name (used only for direct assembly/tests; the bundle patch
+ * does NOT mount this plugin row — see the module doc). */
+export const name = 'fish-terminal'
+/** Required services: terminal registry, shared confinement policy, projection registry, and process substrate. */
+export const inject = [
+  'terminals',
+  'sandboxPolicy',
+  'sessionProjections',
+  'subprocess',
+]
+
+/** Exact printable prompt emitted after the private marker (shared with the
+ * official bash/pwsh backends' readiness contract). */
+const CONTROLLED_PROMPT = 'dsh> '
+/** Default fish executable (resolved on PATH by the subprocess provider). */
+const DEFAULT_FISH_SHELL = 'fish'
+/** Default fish arguments: interactive, without user config interference.
+ * `--no-config` exists since fish 3.3 (the README is POSIX-only anyway) and
+ * avoids a user `fish_prompt`/alias shadowing the controlled prompt. */
+const DEFAULT_FISH_ARGS = ['--no-config', '-i']
+
+/**
+ * Defaults for the shared PTY/readiness surface, mirroring the official
+ * `@deepseek-ai/dsh-terminal-bash` Config schema (the official module
+ * materializes them through schemastery defaults; this backend has no
+ * schemastery dependency, so defaulting is explicit here).
+ */
+const DEFAULT_PTY_CONFIG = {
+  rows: 40,
+  cols: 160,
+  scrollbackLines: 1e4,
+  scrollbackMaxBytes: 4 * 1024 * 1024,
+  maxReadBytes: 256 * 1024,
+  pollIntervalMs: 50,
+  exactProbeAfterMs: 150,
+  idleSilenceMs: 3e3,
+  handoffGraceMs: 500,
+  timeoutMs: 3e4,
+  disposeGraceMs: 3e3,
+}
+
+/**
+ * One-line fish prompt setup submitted before readiness: suppresses the
+ * greeting and right prompt, and defines a prompt that emits the shared OSC
+ * `133;D;<status>` + BEL marker followed by exactly `dsh> `. ESC/BEL are
+ * built at runtime via fish `printf` escapes (no raw control bytes in
+ * submitted input; verified against fish 4.0.0).
+ */
+export const FISH_PROMPT_SETUP = 'function fish_greeting; end; function fish_prompt; printf \'\\x1b]133;D;%s\\x07\' $status; echo -n \'dsh> \'; end; function fish_right_prompt; end;'
+
+/**
+ * Resolve the effective fish shell specification: an unset or empty
+ * `shellPath`/`shellArgs` selects the defaults, a non-empty explicit value
+ * wins. Mirrors the official `resolveConfig` (minus dialect selection).
+ * @param config - the plugin configuration.
+ * @returns the fully resolved configuration.
+ */
+export function resolveConfig(config) {
+  return {
+    backendType: config.backendType?.length > 0 ? config.backendType : 'fish',
+    shellPath: config.shellPath !== undefined && config.shellPath.length > 0 ? config.shellPath : DEFAULT_FISH_SHELL,
+    shellArgs: config.shellArgs !== undefined && config.shellArgs.length > 0 ? config.shellArgs : DEFAULT_FISH_ARGS,
+    ...DEFAULT_PTY_CONFIG,
+    ...Object.fromEntries(Object.entries(config).filter(([key]) => key in DEFAULT_PTY_CONFIG && config[key] !== undefined)),
+  }
+}
+
+/**
+ * Validate the effective configuration (mirrors the official
+ * `validateConfig`).
+ * @param config - the fully resolved configuration.
+ * @returns the narrowed configuration.
+ */
+export function validateConfig(config) {
+  const resolved = config
+  if (resolved.backendType.length === 0) throw new Error('terminal-fish: backendType must be non-empty')
+  if (resolved.shellPath.length === 0) throw new Error('terminal-fish: shellPath must be non-empty')
+  for (const [field, value] of Object.entries(resolved)) {
+    if (typeof value === 'number' && (!Number.isSafeInteger(value) || value <= 0)) {
+      throw new Error(`terminal-fish: ${field} must be a positive safe integer`)
+    }
+  }
+  if (resolved.maxReadBytes > resolved.scrollbackMaxBytes) throw new Error('terminal-fish: maxReadBytes must not exceed scrollbackMaxBytes')
+  if (resolved.handoffGraceMs < resolved.pollIntervalMs) throw new Error('terminal-fish: handoffGraceMs must be at least pollIntervalMs so one readiness poll runs inside the grace window')
+}
+
+/**
+ * Fish child environment: the official bash `childEnvironment` common set
+ * (TERM=dumb so the reader emits no cursor/redraw sequences, PAGER=cat,
+ * harness identity facts) minus the bash-only PS1/PROMPT_COMMAND.
+ * @param spec - the spawn specification.
+ * @returns the child environment.
+ */
+export function childEnvironment(spec) {
+  return {
+    TERM: 'dumb',
+    PAGER: 'cat',
+    GIT_PAGER: 'cat',
+    DSH_SHELL: '1',
+    DSH_SESSION_ID: spec.owner.id,
+    DSH_PTY_SESSION_ID: spec.sessionId,
+  }
+}
+
+// Copied from the official `@deepseek-ai/dsh-terminal-bash` (not exported
+// there): a per-owner fence refusing `sandbox/mode` changes while persistent
+// terminal sessions are open or being created.
+//
+// Self-managed adaptation: the official copy asks the terminals registry
+// (`state.pty.hasOwnerActivity(owner)`) whether the owner has activity, but
+// the policy's persistent tool drives sessions WITHOUT a registry. Activity
+// checkers are therefore injectable and AGGREGATED per owner: every
+// `registerPersistentFish` manager that spawned for an owner contributes its
+// own checker (the manager's owner→session tracking), and the fence refuses
+// the mode change while ANY checker reports activity. Aggregation matters
+// because managers can churn (persistent→one-shot→persistent): a single-slot
+// overwrite would silently forget the first manager's still-open sessions.
+// A call without a checker (the backend's own fence probe on every spawn)
+// adds nothing, so it cannot clobber policy checkers; when no checker was
+// ever contributed the fence falls back to the terminals registry probe
+// (`ctx.terminals` may be absent — missing services resolve to `undefined`
+// on a Cordis context, never a throw).
+const sandboxModeFences = new WeakMap()
+export function ensureSandboxModeFence(ctx, owner, hasActivity) {
+  let state = sandboxModeFences.get(owner)
+  if (state === undefined) {
+    state = { ctx, checkers: new Set() }
+    sandboxModeFences.set(owner, state)
+    owner.ctx.on('internal/dispatch', (_mode, eventName, args) => {
+      if (eventName !== 'session/event') return
+      const [session, event] = args
+      if (session !== owner.session || event.type !== 'sandbox/mode') return
+      const current = sandboxModeFences.get(owner)
+      if (current === undefined) return
+      const currentMode = current.ctx.get('sessionProjections')?.stateOf(session, 'sandboxMode') ?? current.ctx.get('sandboxPolicy')?.defaultMode
+      if (event.data.mode === currentMode) return
+      const active = current.checkers.size > 0
+        ? [...current.checkers].some((check) => check())
+        : current.ctx.get('terminals')?.hasOwnerActivity(owner) ?? false
+      if (active) throw new Error(`cannot change sandbox mode from "${currentMode}" to "${event.data.mode}" while persistent terminal sessions are open or being created; wait for creation to settle and close them first`)
+    }, { global: true })
+  } else {
+    state.ctx = ctx
+  }
+  if (hasActivity !== undefined) state.checkers.add(hasActivity)
+}
+
+/**
+ * Confine the fish argv through the shared sandbox policy, exactly like the
+ * official `spawnArgv` (which is private to `@deepseek-ai/dsh-terminal-bash`
+ * and therefore copied here).
+ * @param ctx - the plugin context carrying the sandbox provider.
+ * @param config - the resolved backend configuration.
+ * @param policy - the resolved execution policy for this session.
+ * @returns the (possibly confined) argv.
+ */
+export function spawnArgv(ctx, config, policy) {
+  const argv = [config.shellPath, ...config.shellArgs]
+  if (policy.mode === 'danger-full-access') return argv
+  const sandbox = ctx.get('sandbox')
+  if (sandbox === undefined) throw new Error(`terminal-fish: sandbox mode "${policy.mode}" requires a ctx.sandbox provider in the execution world`)
+  return sandbox.confine(argv, {
+    ...policy,
+    mode: policy.mode,
+  }).argv
+}
+
+/**
+ * Bring the fish session to readiness: submit the prompt setup once, then
+ * poll with empty sends until the fish prompt satisfies the shared
+ * readiness contract (OSC `133;D;` + `dsh> ` tail). Mirrors the official
+ * `startupSession` pwsh branch, with a startup deadline race.
+ * @param session - the backend session.
+ * @param timeoutMs - readiness deadline.
+ * @param signal - optional cancellation.
+ */
+export async function startupSession(session, timeoutMs, signal) {
+  let startupOperation
+  const start = async () => {
+    let viewport = ''
+    for (;;) {
+      const first = viewport.length === 0
+      startupOperation = session.startSend({
+        text: first ? FISH_PROMPT_SETUP : '',
+        submit: first,
+        ...(signal !== undefined ? { signal } : {}),
+      })
+      const result = await startupOperation.done
+      if (result.waitReason === 'session_exit') throw new Error('PTY shell exited during startup')
+      if (result.waitReason === 'timeout') throw new Error('PTY shell did not reach readiness before startup timeout')
+      viewport = result.viewport
+      if (result.waitReason === 'stdin_read') break
+    }
+    session.motd = viewport
+  }
+  const races = []
+  let onAbort
+  if (signal !== undefined) {
+    const aborted = Promise.withResolvers()
+    onAbort = () => {
+      aborted.reject(signal.reason)
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    races.push(aborted.promise)
+  }
+  const deadline = Promise.withResolvers()
+  const deadlineTimer = setTimeout(() => {
+    startupOperation?.cancel()
+    deadline.reject(new Error('PTY shell did not reach readiness before startup timeout'))
+  }, timeoutMs)
+  races.push(deadline.promise)
+  try {
+    signal?.throwIfAborted()
+    await Promise.race([start(), ...races])
+  } finally {
+    clearTimeout(deadlineTimer)
+    if (signal !== undefined && onAbort !== undefined) signal.removeEventListener('abort', onAbort)
+  }
+}
+
+/**
+ * Local fish PTY backend registered under the configured type (`fish`):
+ * spawns `fish --no-config -i` (config-overridable) with the fish child
+ * environment, confined through the shared sandbox policy, and brings it to
+ * readiness with the fish prompt setup. Everything else (bounded output,
+ * readiness polling, terminal-protocol replies, cleanup) is inherited from
+ * `BashTerminalBackend`/`LocalPtySession`.
+ */
+export class FishTerminalBackend extends BashTerminalBackend {
+  async spawn(spec) {
+    spec.signal?.throwIfAborted()
+    ensureSandboxModeFence(this.ctx, spec.owner)
+    // Resolve services through `ctx.get` (never property access): the
+    // backend may be constructed with a plugin context whose inject list
+    // does not declare these services (the policy plugin's ctx), and Cordis
+    // property access would throw "cannot get property … without inject".
+    // `ctx.get` resolves any registered service regardless of inject.
+    const policy = this.ctx.get('sandboxPolicy').resolve({ session: spec.owner.session })
+    const argv = spawnArgv(this.ctx, this.config, policy)
+    if (argv[0] === undefined) throw new Error('terminal-fish: sandbox returned empty argv')
+    const terminal = await this.spawnTerminal({
+      argv,
+      cwd: spec.cwd ?? policy.workspaceRoot,
+      env: childEnvironment(spec),
+      rows: this.config.rows,
+      cols: this.config.cols,
+      graceMs: this.config.disposeGraceMs,
+      signal: spec.signal,
+    })
+    const session = this.createSession(terminal, this.config)
+    try {
+      await startupSession(session, this.config.timeoutMs, spec.signal)
+      return session
+    } catch (error) {
+      try {
+        await session.close('PTY startup failed')
+      } catch (closeError) {
+        throw new TerminalBackendCleanupError(error, closeError)
+      }
+      throw error
+    }
+  }
+}
+
+/**
+ * Register the local fish PTY backend in a `terminals` registry. The bundle
+ * patch does NOT mount this plugin (host-plane profiles have no `terminals`
+ * service); this entry point is for direct assembly and tests — and for the
+ * real `minimal` preset composition, whose entry-local registry can pick the
+ * backend up explicitly. Plugin configuration mirrors the official
+ * `@deepseek-ai/dsh-terminal-bash` Config surface (sans dialect), with fish
+ * defaults: backend type `fish`, `fish --no-config -i` argv.
+ * @param ctx - the harness context.
+ * @param config - optional backend configuration.
+ */
+export function apply(ctx, config = {}) {
+  const resolved = resolveConfig(config)
+  validateConfig(resolved)
+  ctx.terminals.registerBackend(new FishTerminalBackend(ctx, resolved))
+}