@banbolee/dsh-fish-shell 0.7.0 → 0.8.0

package/terminal-tools.js

@@ -0,0 +1,259 @@
+/**
+ * `terminalTools` policy for the L2 interactive terminal surface of
+ * `@banbolee/dsh-fish-shell` — the D6 switch, `'allow' | 'deny'`.
+ *
+ * The bundle's patch appends a `fish-terminal-group` insert row that mounts
+ * the official `@deepseek-ai/dsh-terminal` registry, the official
+ * `@deepseek-ai/dsh-terminal-bash` backend driven with fish argv
+ * (`--no-config -i -C <prompt setup>`), and the official
+ * `@deepseek-ai/dsh-tool-terminal`, whose six `terminal_*` tools register
+ * into the HOST tool registry (the group isolates `terminals`, not `tools`).
+ * This module is the only entry the plugin itself adds for L2: a per-agent
+ * switch that can take those six tools away again.
+ *
+ *   - `terminalTools: 'allow'` (the default, matching every other tool in the
+ *     deployment) does nothing at all — `apply` returns before registering a
+ *     single listener, so an allowed mount has zero runtime footprint.
+ *   - `terminalTools: 'deny'` restricts the six tools for every live agent at
+ *     the `agent/created` publication edge and on every `tools/change`. The
+ *     official `tools.restrict` is the only enforcement point, and it REJECTS
+ *     names that are not registered at that moment, so an attempt made before
+ *     the terminal tools exist fails and is retried on the next
+ *     `tools/change` (the registry announces every registration and scoped
+ *     restriction through that event).
+ *
+ * Every `apply()` call owns its ENTIRE state — its own live-agent set, its own
+ * per-agent disposers, its own reconcile flags, and its own
+ * installing/warned/removed bookkeeping. Two mounts sharing one context (two
+ * bundle rows) or two profiles living in one process therefore cannot dedupe
+ * into, lift, or orphan each other's restrictions: each mount installs its own
+ * restriction and that mount alone lifts it on teardown, so no restriction
+ * outlives the mount that owns it.
+ *
+ * The governed names are the EXPLICIT six-name enumeration measured on a real
+ * profile (`TERMINAL_TOOL_NAMES`); a `terminal_*` wildcard is deliberately not
+ * used, so an upstream seventh tool cannot silently pass the policy — the
+ * contract test compares this constant with the bundled
+ * `@deepseek-ai/dsh-tool-terminal` surface instead.
+ *
+ * Boundaries: this policy registers no tool, wraps/replaces no host object,
+ * monkey-patches nothing, and offers no privilege-escalation entry point. It
+ * only narrows an agent's tool surface through the public
+ * `agent.ctx.tools.restrict({ deny })` API. The interactive sessions
+ * themselves inherit the host's confinement (a `workspace-write` profile is
+ * fenced by the host sandbox).
+ *
+ * @module @banbolee/dsh-fish-shell/terminal-tools
+ */
+
+/** Cordis plugin name (the patch row id is `fish-terminal-tools`). */
+export const name = 'fish-terminal-tools-policy'
+/** Required service: the tool registry the six names are restricted in. */
+export const inject = ['tools']
+
+/**
+ * The six `terminal_*` tools mounted by the bundle's `fish-terminal-group`,
+ * enumerated explicitly (never a `terminal_*` pattern): `terminal_open`,
+ * `terminal_send`, `terminal_read`, `terminal_signal`, `terminal_close`,
+ * `terminal_list`.
+ */
+export const TERMINAL_TOOL_NAMES = Object.freeze([
+  'terminal_open',
+  'terminal_send',
+  'terminal_read',
+  'terminal_signal',
+  'terminal_close',
+  'terminal_list',
+])
+
+/**
+ * Plugin configuration schema: one switch. A plain object implementing the
+ * standard-schema interface (no external validator): an absent
+ * `terminalTools` defaults to `allow`; any value other than `allow`/`deny` is
+ * rejected at mount time.
+ */
+export const Config = {
+  '~standard': {
+    version: /** @type {1} */ (1),
+    vendor: '@banbolee/dsh-fish-shell/terminal-tools',
+    /**
+     * Normalize one mount's raw configuration.
+     * @param {unknown} value
+     */
+    validate(value) {
+      const mode = /** @type {{ terminalTools?: unknown }} */ (value ?? {}).terminalTools ?? 'allow'
+      if (mode !== 'allow' && mode !== 'deny') {
+        throw new TypeError("banbo-fish-terminal-tools config.terminalTools must be 'allow' or 'deny'")
+      }
+      return { value: { terminalTools: mode } }
+    },
+  },
+}
+
+const PLUGIN_TAG = '@banbolee/dsh-fish-shell'
+
+/**
+ * One agent as this policy reads it: the harness `Agent` viewed through the
+ * two members it keys on — its session id (for warnings) and its agent-scoped
+ * context (where the restriction lands). The full runtime `Agent` face is
+ * structurally assignable to this view.
+ * @typedef {{ id?: string, ctx: import('@deepseek-ai/cordis').Context }} PolicyAgent
+ */
+
+/**
+ * Mount one `deny` policy on `ctx`, owning every piece of state it needs.
+ * Nothing in here is shared with another mount of this module.
+ * @param {import('@deepseek-ai/cordis').Context} ctx - the harness context this mount lives on.
+ */
+function mountDenyPolicy(ctx) {
+  /** Agents this mount is currently restricting (guards the synchronous
+   * `tools/change` re-entry that `tools.restrict` itself fires).
+   * @type {WeakSet<PolicyAgent>} */
+  const installing = new WeakSet()
+  /** Agents this mount already warned about a failed restriction (warn once
+   * per agent per mount).
+   * @type {WeakSet<PolicyAgent>} */
+  const warned = new WeakSet()
+  /** Agents this mount saw disposed: a `tools/change` fired by the uninstall's
+   * own disposer must not re-restrict a dying agent.
+   * @type {WeakSet<PolicyAgent>} */
+  const removed = new WeakSet()
+  /** The exact restriction disposer THIS mount installed per agent.
+   * @type {WeakMap<PolicyAgent, () => void>} */
+  const restrictions = new WeakMap()
+  /** This mount's agents with a restriction installed; traversable so its own
+   * teardown lifts exactly its own restrictions (a WeakMap would be
+   * unreachable).
+   * @type {Set<PolicyAgent>} */
+  const liveAgents = new Set()
+  /** This mount's reconcile re-entrancy guard: a `tools/change` arriving while
+   * a reconcile round is in flight marks `reconcilePending` instead of starting
+   * a nested round; the round in flight runs exactly one coalesced catch-up
+   * round afterwards. */
+  let reconciling = false
+  let reconcilePending = false
+  /** Set while THIS mount's teardown runs so its own listeners (still
+   * registered — they were created before the teardown effect, which cordis
+   * disposes first) cannot re-install a restriction being lifted. */
+  let disposed = false
+
+  /**
+   * Deny the six terminal tools for one agent, once. A failure (the tools are
+   * not registered in this profile yet, so `tools.restrict` rejects the unknown
+   * names) is warned once per agent and retried on the next `tools/change`.
+   * @param {PolicyAgent} agent - the live agent (its `ctx` is the agent's scoped context).
+   */
+  const install = (agent) => {
+    if (installing.has(agent) || removed.has(agent)) return
+    if (restrictions.has(agent)) return
+    installing.add(agent)
+    try {
+      // A fresh array: the frozen constant stays the policy's single source of
+      // names, and the toolbox never receives the shared instance.
+      const restriction = agent.ctx.tools.restrict({ deny: [...TERMINAL_TOOL_NAMES] })
+      restrictions.set(agent, restriction)
+    } catch (error) {
+      if (!warned.has(agent)) {
+        warned.add(agent)
+        console.warn(
+          `${PLUGIN_TAG}: could not deny the terminal tools for agent ${agent.id ?? '(unnamed)'} yet `
+          + '(they are not registered in this profile so far); retrying on the next tools/change:',
+          String(error),
+        )
+      }
+    } finally {
+      installing.delete(agent)
+    }
+  }
+
+  /**
+   * Lift one agent's restriction, if THIS mount installed one. The exact
+   * disposer is removed from the state BEFORE it runs: lifting a restriction
+   * synchronously fires `tools/change` as well.
+   * @param {PolicyAgent} agent - the agent whose restriction is lifted.
+   * @param {string} label - the operation name in the warning.
+   */
+  const lift = (agent, label) => {
+    const restriction = restrictions.get(agent)
+    if (restriction === undefined) return
+    restrictions.delete(agent)
+    try {
+      restriction()
+    } catch (error) {
+      console.warn(`${PLUGIN_TAG}: could not ${label} terminal tools for agent ${agent.id ?? '(unnamed)'}:`, String(error))
+    }
+  }
+
+  /**
+   * Ensure every live agent carries this mount's restriction (no-op when the
+   * `agents` service is absent). Nested calls (the restriction's own
+   * `tools/change`) are absorbed into at most ONE coalesced catch-up round, so
+   * the dispatch count stays bounded regardless of how many agents are live.
+   * @param {boolean} [catchUp] - whether this round is the coalesced catch-up (never re-triggers one).
+   */
+  const reconcile = (catchUp = false) => {
+    if (reconciling) {
+      reconcilePending = true
+      return
+    }
+    reconciling = true
+    try {
+      for (const agent of ctx.get('agents')?.list() ?? []) {
+        liveAgents.add(agent)
+        install(agent)
+      }
+    } finally {
+      reconciling = false
+    }
+    if (reconcilePending && !catchUp) {
+      reconcilePending = false
+      reconcile(true)
+    } else {
+      reconcilePending = 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, but `install` contains its own failures.
+  ctx.on('agent/created', ({ agent }) => {
+    if (disposed) return
+    liveAgents.add(agent)
+    install(agent)
+  })
+  ctx.on('agent/disposed', ({ agent }) => {
+    if (disposed) return
+    removed.add(agent)
+    liveAgents.delete(agent)
+    lift(agent, 'lift the restriction on the')
+  })
+  ctx.on('tools/change', () => {
+    if (disposed) return
+    reconcile()
+  })
+  // Plugin-owned teardown (unload/disable/HMR): registered LAST so cordis
+  // disposes it FIRST (effects run in reverse registration order) — while this
+  // loop lifts THIS mount's restrictions, `disposed` above makes its listeners
+  // no-ops, so lifting cannot re-install.
+  ctx.effect(() => () => {
+    disposed = true
+    for (const agent of [...liveAgents]) lift(agent, 'lift the restriction on the')
+    liveAgents.clear()
+  }, 'fish terminal-tools policy teardown')
+  reconcile()
+}
+
+/**
+ * Cordis plugin entry. With `terminalTools: 'deny'` the six `terminal_*` tools
+ * are taken away from every live agent — at the `agent/created` publication
+ * edge, on every `tools/change`, and for agents that already exist (plugin
+ * hot-reload) — and every restriction this mount installed is lifted on its
+ * teardown. With the default `allow` nothing is registered and the function
+ * returns.
+ * @param {import('@deepseek-ai/cordis').Context} ctx - the harness context.
+ * @param {{ terminalTools?: 'allow' | 'deny' }} [config] - validated plugin config.
+ */
+export function apply(ctx, config) {
+  if (config?.terminalTools !== 'deny') return
+  mountDenyPolicy(ctx)
+}

package/terminal.js

@@ -0,0 +1,297 @@
+/**
+ * L2 interactive PTY backend: the official `@deepseek-ai/dsh-terminal-bash`
+ * `BashTerminalBackend` with ONE addition — the harness home contract
+ * (`DSH_HOME`, and `DSH_PROFILE` / `DSH_PROFILE_DIR` when the context carries
+ * them) in the PTY child environment.
+ *
+ * Why it exists: an interactive session's child environment is the backend's
+ * own overlay (`TERM=dumb`, `PAGER=cat`, `GIT_PAGER=cat`, `DSH_SHELL`,
+ * `DSH_SESSION_ID`, `DSH_PTY_SESSION_ID`) layered on `scrubbedParentEnv()`,
+ * which drops EVERY inherited `DSH_*` name. The one-shot `fish` tool instead
+ * runs with the trusted snapshot of the `ctx.shellEnv` registry, merged after
+ * that same scrub. The two surfaces therefore disagreed about the harness
+ * home: a `dsh` nested inside an interactive session resolved `~/.dsh` (an
+ * older home with older plugin state) while the one-shot tool resolved the
+ * real harness home. This module puts both surfaces on the same home facts.
+ *
+ * How the injection stays on public seams: the base class builds the overlay
+ * with its module-private `childEnvironment()` and hands the finished terminal
+ * spec to its `spawnTerminal` CONSTRUCTOR parameter. This subclass passes a
+ * wrapper for that parameter (the official default is
+ * `(spec) => ctx.subprocess.spawnTerminal(spec)`), and the spec's `env` field
+ * is documented as "explicit environment layered after the provider's ambient
+ * scrub" — exactly where a deliberately forwarded `DSH_*` fact belongs. No
+ * official module internal, no private field and no monkey-patch is involved:
+ * argv confinement, the sandbox-mode fence, `session.initialize()` readiness,
+ * the `-C` fish prompt setup, the session factory and the config surface
+ * (`Config` is re-exported verbatim, so `backendType` keeps its `shell`
+ * default) are all the base class's own code.
+ *
+ * Where the values come from: the SAME registry the one-shot shell tools use —
+ * `ctx.shellEnv.collect()`, whose snapshot `dsh-bash-local` merges into a
+ * one-shot execution — so the two cannot drift. The three home facts are
+ * execution-independent by construction: `collect` reads `execution.agent`
+ * only to add `DSH_SESSION_ID`, and the profile facts come from the context.
+ * The snapshot is therefore taken at spawn time with an empty execution, and
+ * the session facts stay the PTY overlay's own official values: this module
+ * never rewrites `DSH_SHELL` / `DSH_SESSION_ID` / `DSH_PTY_SESSION_ID`.
+ *
+ * `DSH_SESSION_ID` / `DSH_PTY_SESSION_ID` are deliberately KEPT on a newly
+ * opened shell. Evidence: they are the official PTY facts, produced by
+ * `dsh-terminal-bash` (`spec.owner.id` / `spec.sessionId`) and by
+ * `dsh-api-terminal-controller` (`agent.id`) for the GUI terminal panel, and
+ * grep over the installed harness finds no reader of either name (only those
+ * two producers and the registry's reserved-key list). Removing them would be
+ * a deviation with no evidence behind it. What would change that: an in-tree
+ * consumer that reads the CURRENT session's identity out of these variables
+ * (e.g. a plugin resolving its caller from `$DSH_SESSION_ID`), or a nested-boot
+ * failure traced to the inherited value.
+ *
+ * Fallback, and its exact boundary: the overlay always comes from exactly ONE
+ * source. When the registry is NOT mounted at all (`ctx.get('shellEnv')` is
+ * `undefined` — a custom composition outside `dsh-base`), the three facts are
+ * read from their public owners: `resolveDshHome()` and
+ * `ctx.get('profileContext')`, which are the registry's own sources, so the
+ * values are byte-identical unless a profile configures `dshHome` on its
+ * `shell-env` row — that row is visible to the registry path only. When the
+ * service IS mounted (even if its snapshot declares fewer than three keys) the
+ * registry is the only source: nothing is merged in per key, and a throwing
+ * `collect()` PROPAGATES, because the one-shot shell path collects fail-loud
+ * too and swallowing that error would silently resolve a DIFFERENT home (the
+ * ambient `DSH_HOME`) than the one the registry recorded — the exact failure
+ * this module exists to remove.
+ *
+ * The config surface is the official one in behaviour, not only in shape: the
+ * `apply` below runs the official `resolveConfig`/`validateConfig` semantics
+ * (replicated as {@link resolveTerminalConfig} / {@link validateTerminalConfig},
+ * because the official package does not export them), so an empty
+ * `shellPath`/`shellArgs` gets the dialect defaults and an invalid duration is
+ * rejected rather than accepted. A parity test drives the official `apply` and
+ * this one with the same inputs and compares the effective config and the
+ * validation outcome.
+ *
+ * Upstream note: this subclass is only here because the official row exposes
+ * no `env` config field. If `@deepseek-ai/dsh-terminal-bash` ever grows one
+ * (or accepts an environment overlay from the registry itself), the patch row
+ * can go back to the official package and this module can be deleted — together
+ * with the `NESTED_DSH_ENTRY` contract in
+ * `tests/docs-shape-fish-shell.spec.ts`, which names this module.
+ *
+ * @module @banbolee/dsh-fish-shell/terminal
+ */
+
+import { BashTerminalBackend, Config } from '@deepseek-ai/dsh-terminal-bash'
+import { DSH_HOME_ENV, resolveDshHome } from '@deepseek-ai/dsh-home-paths'
+import { resolvePwshPath } from '@deepseek-ai/dsh-pwsh-local'
+
+/**
+ * The official backend's config schema, re-exported verbatim so cordis
+ * resolves this row with exactly the official defaults (`backendType: 'shell'`
+ * included) and the row keeps the official config surface. Also imported
+ * above, where `apply` uses it to materialize those defaults for a direct,
+ * loader-free call.
+ */
+export { Config }
+
+/** Cordis plugin name (the bundle patch decides the row id and mount point). */
+export const name = 'terminal-home'
+/**
+ * Required services: verbatim the official backend's list. The inherited
+ * `spawn()` needs all four; declaring the same list keeps activation identical
+ * to the official row.
+ */
+export const inject = [
+  'terminals',
+  'sandboxPolicy',
+  'sessionProjections',
+  'subprocess',
+]
+
+/** Environment variable holding the profile facts the registry snapshots. */
+const DSH_PROFILE_KEY = 'DSH_PROFILE'
+/** Environment variable holding the profile directory the registry snapshots. */
+const DSH_PROFILE_DIR_KEY = 'DSH_PROFILE_DIR'
+/** The home contract this module forwards, in the order it is documented. */
+const HOME_CONTRACT_KEYS = /** @type {const} */ ([DSH_HOME_ENV, DSH_PROFILE_KEY, DSH_PROFILE_DIR_KEY])
+
+/** Bash dialect default executable — the official `DEFAULT_BASH_SHELL`. */
+const DEFAULT_BASH_SHELL = '/bin/bash'
+/** Bash dialect default arguments (interactive, profile-free) — the official `DEFAULT_BASH_ARGS`. */
+const DEFAULT_BASH_ARGS = ['--noprofile', '--norc', '-i']
+/** Pwsh dialect default arguments — the official `DEFAULT_PWSH_ARGS`. */
+const DEFAULT_PWSH_ARGS = ['-NoLogo', '-NoProfile']
+
+/**
+ * The official `resolveConfig`, replicated from
+ * `@deepseek-ai/dsh-terminal-bash@0.2.0-rc.1` (`lib/index.js:27-35`; the
+ * official package does not export it). An unset or EMPTY
+ * `shellPath`/`shellArgs` selects the dialect's defaults — schemastery
+ * materializes an absent optional array as `[]` — while a non-empty explicit
+ * value always wins. This module re-exports the official schema, so both
+ * `apply`s must materialize the same effective config; the parity test drives
+ * the official `apply` and this one side by side. Keep in sync with the
+ * official source: a change there changes this row's config contract.
+ * @param {import('@deepseek-ai/dsh-terminal-bash').TerminalLocalConfig} config - the schemastery-resolved plugin configuration.
+ * @returns {ConstructorParameters<typeof BashTerminalBackend>[1]} the fully resolved configuration.
+ */
+export function resolveTerminalConfig(config) {
+  const shellDialect = config.shellDialect ?? 'bash'
+  return /** @type {ConstructorParameters<typeof BashTerminalBackend>[1]} */ ({
+    ...config,
+    shellDialect,
+    shellPath: config.shellPath !== undefined && config.shellPath.length > 0
+      ? config.shellPath
+      : shellDialect === 'pwsh' ? resolvePwshPath() : DEFAULT_BASH_SHELL,
+    shellArgs: config.shellArgs !== undefined && config.shellArgs.length > 0
+      ? config.shellArgs
+      : shellDialect === 'pwsh' ? DEFAULT_PWSH_ARGS : DEFAULT_BASH_ARGS,
+  })
+}
+
+/**
+ * The official `validateConfig`, replicated from
+ * `@deepseek-ai/dsh-terminal-bash@0.2.0-rc.1` (`lib/index.js:62-74`; not
+ * exported) with the official error text verbatim — including the
+ * `terminal-bash:` prefix, which is deliberate: the row's config surface IS the
+ * official schema, and parity with the official validator (messages compared
+ * byte for byte) is a tested contract. Every numeric field is a positive safe
+ * integer except `promptTailGraceMs`, whose zero is the documented "no
+ * extension" value and which is therefore checked on its own. Keep in sync with
+ * the official source.
+ * @param {ConstructorParameters<typeof BashTerminalBackend>[1]} config - the resolved configuration.
+ * @returns {void} throws on a value the backend cannot run with.
+ */
+export function validateTerminalConfig(config) {
+  if (config.backendType.length === 0) throw new Error('terminal-bash: backendType must be non-empty')
+  if (config.shellPath.length === 0) throw new Error('terminal-bash: shellPath must be non-empty')
+  for (const [name, value] of Object.entries(config)) {
+    if (name === 'promptTailGraceMs') continue
+    if (typeof value === 'number' && (!Number.isSafeInteger(value) || value <= 0)) {
+      throw new Error(`terminal-bash: ${name} must be a positive safe integer`)
+    }
+  }
+  if (typeof config.promptTailGraceMs === 'number' && (!Number.isSafeInteger(config.promptTailGraceMs) || config.promptTailGraceMs < 0)) {
+    throw new Error('terminal-bash: promptTailGraceMs must be a non-negative safe integer')
+  }
+  if (config.maxReadBytes > config.scrollbackMaxBytes) throw new Error('terminal-bash: maxReadBytes must not exceed scrollbackMaxBytes')
+  if (config.handoffGraceMs < config.pollIntervalMs) throw new Error('terminal-bash: handoffGraceMs must be at least pollIntervalMs so one readiness poll runs inside the grace window')
+  if (config.promptTailGraceMs !== 0 && config.promptTailGraceMs < config.pollIntervalMs) throw new Error('terminal-bash: promptTailGraceMs must be zero or at least pollIntervalMs so a nonzero tolerance contains one readiness poll')
+}
+
+/**
+ * The public profile facts `ctx.get('profileContext')` carries. Deliberately
+ * structural: the service belongs to the launcher, so this module reads the
+ * two fields it forwards instead of importing its owner's types.
+ * @typedef {{ name?: string, dir?: string } | undefined} ProfileFacts
+ */
+
+/**
+ * The registry's snapshot of the home contract, or `undefined` when the
+ * registry is NOT mounted (`ctx.get('shellEnv') === undefined`, i.e. a custom
+ * composition outside `dsh-base`). The distinction is load-bearing: a mounted
+ * registry is the ONLY source, so a key its snapshot omits stays omitted
+ * instead of being filled in from another source.
+ *
+ * `collect` is called with an empty execution on purpose: of the three keys
+ * this module forwards, none depends on the execution (only `DSH_SESSION_ID`
+ * does, and that one stays the PTY overlay's own value). A throwing `collect`
+ * is NOT swallowed either: once the registry is mounted it is the only source
+ * that can see a configured `dshHome`, and quietly falling back would resolve a
+ * different home — exactly the drift this module removes. It fails loud here
+ * for the same reason the one-shot path (`dsh-tool-bash`) does.
+ * @param {import('@deepseek-ai/cordis').Context} ctx - the backend's plugin context.
+ * @returns {Record<string, string> | undefined} the home facts the registry declares, or `undefined` when it is not mounted.
+ */
+function registryHomeContract(ctx) {
+  /** @type {import('@deepseek-ai/dsh-shell-env').ShellEnvRegistry | undefined} */
+  const registry = ctx.get('shellEnv')
+  if (registry === undefined) return undefined
+  const snapshot = registry.collect(
+    /** @type {import('@deepseek-ai/dsh-tools').ToolExecution} */ ({}),
+  )
+  /** @type {Record<string, string>} */
+  const facts = {}
+  for (const key of HOME_CONTRACT_KEYS) {
+    const value = snapshot[key]
+    if (value !== undefined) facts[key] = value
+  }
+  return facts
+}
+
+/**
+ * The harness home contract for one PTY child, from exactly ONE source:
+ *
+ *   - the mounted `ctx.shellEnv` registry (the one-shot shell tools' own
+ *     source) — its declared facts verbatim, including the case where it
+ *     declares fewer than three (the official registry always declares
+ *     `DSH_HOME`, and declares the profile pair whenever a `profileContext`
+ *     exists, so an incomplete snapshot means a foreign implementation: the
+ *     honest reading is then "this environment does not carry that fact", not
+ *     "borrow it from somewhere else");
+ *   - only when that service is NOT mounted, the public owners
+ *     `dsh-home-paths` / `profileContext`, which are the registry's own sources.
+ *
+ * A `collect` error propagates rather than switching sources — see the module
+ * doc for both rules.
+ * @param {import('@deepseek-ai/cordis').Context} ctx - the backend's plugin context.
+ * @returns {Record<string, string>} the environment overlay to merge into the child environment.
+ */
+export function harnessHomeEnvironment(ctx) {
+  const fromRegistry = registryHomeContract(ctx)
+  if (fromRegistry !== undefined) return fromRegistry
+  /** @type {ProfileFacts} */
+  const profile = ctx.get('profileContext')
+  /** @type {Record<string, string>} */
+  const environment = { [DSH_HOME_ENV]: resolveDshHome() }
+  if (profile?.name !== undefined) environment[DSH_PROFILE_KEY] = profile.name
+  if (profile?.dir !== undefined) environment[DSH_PROFILE_DIR_KEY] = profile.dir
+  return environment
+}
+
+/**
+ * One terminal spawn spec with the home contract merged into its environment:
+ * the same request object, one layer further down than the base class's own
+ * overlay (the provider applies `spec.env` after its ambient scrub).
+ * @param {import('@deepseek-ai/dsh-subprocess').SubprocessTerminalSpawnSpec} spec - the terminal request the base class built.
+ * @param {import('@deepseek-ai/cordis').Context} ctx - the backend's plugin context.
+ * @returns {import('@deepseek-ai/dsh-subprocess').SubprocessTerminalSpawnSpec} the same request with the home facts added.
+ */
+export function withHarnessHome(spec, ctx) {
+  return { ...spec, env: { ...spec.env, ...harnessHomeEnvironment(ctx) } }
+}
+
+/**
+ * The official local PTY backend with the harness home contract in its child
+ * environment. `spawn()` is NOT overridden: argv confinement, the sandbox-mode
+ * fence, readiness through `session.initialize()` and the `-C` prompt setup
+ * are the base class's own.
+ */
+export class HarnessHomeTerminalBackend extends BashTerminalBackend {
+  /**
+   * Wrap the base class's `spawnTerminal` seam so every terminal request it
+   * builds carries the home contract. The seam is deliberately not a
+   * constructor parameter: the row must not be able to lose the contract.
+   * @param {import('@deepseek-ai/cordis').Context} ctx - the harness context.
+   * @param {ConstructorParameters<typeof BashTerminalBackend>[1]} config - the resolved official backend configuration.
+   * @param {ConstructorParameters<typeof BashTerminalBackend>[3]} [createSession] - the base class's session-factory seam, for tests; omitted in production, where the base default builds the `LocalPtySession`.
+   */
+  constructor(ctx, config, createSession) {
+    super(ctx, config, (spec) => ctx.subprocess.spawnTerminal(withHarnessHome(spec, ctx)), createSession)
+  }
+}
+
+/**
+ * Register the home-carrying local PTY backend under the configured type
+ * (`shell` unless the row overrides it).
+ * @param {import('@deepseek-ai/cordis').Context} ctx - the harness context.
+ * @param {import('@deepseek-ai/dsh-terminal-bash').TerminalLocalConfig} [config] - optional backend configuration.
+ */
+export function apply(ctx, config = {}) {
+  // The exported `Config` is the official schema, so cordis has already
+  // resolved this object; resolving again keeps a direct `apply()` call (tests,
+  // direct assembly) on the same defaults. The two explicit steps after it are
+  // the official `apply`'s own: dialect defaulting, then validation.
+  const resolved = resolveTerminalConfig(Config(config))
+  validateTerminalConfig(resolved)
+  ctx.terminals.registerBackend(new HarnessHomeTerminalBackend(ctx, resolved))
+}