@sagmans/dsh-tui 0.13.0 → 0.14.0

package/.agents/skills/dsh-tui-dogfood/SKILL.md

@@ -4,6 +4,21 @@ description: "Use when a dsh plugin checkout must be tested against a real profi
 ---
 # Dogfood a dsh plugin checkout
 
+For a dsh-tui checkout, run `pnpm verify` after development. It runs golden
+frames and all free dogfood scenarios automatically. `pnpm dogfood` starts the
+installed Harness with the base bundle and worktree in credential-free scratch
+homes. In a Herdr-managed caller, the same free gate also runs real native-pane workflows in an owned disposable named session.
+Without that prerequisite, Herdr evidence remains `environment-not-run`; portable PTY checks still run.
+When tmux is installed, the free gate also verifies its private server and actual restoration.
+Native controllers do not launch the caller's configured shell or source its startup files.
+Read `FEATURES.md` in the checkout for scope and evidence rules.
+
+Paid live-model use requires an explicit human request. List scenarios with
+`pnpm dogfood:paid --list`, then select one with `--scenario`, `--home`,
+`--provider`, and `--model`. Use a cloned profile for its credentials and model
+adapter. Never submit a model prompt automatically, even a short smoke prompt.
+
+
 A fresh `DSH_HOME` misses the installed bundles, profile patch, settings, and themes.
 A run against the real home writes real sessions and state. Clone the source
 home and relink only the plugin under test inside the clone.
@@ -23,8 +38,9 @@ runs `pnpm run build` only when the checkout declares a build script. It adds
 the bundle once if absent from the cloned profile, updates only its dependency,
 restores local links from `link:` specifications, and launches
 `dsh --profile tui` by default. For this TUI, the packaged helper checks
-the launcher against compatible releases in the checkout’s `package.json` before
-cloning. This checkout uses the installed `dsh 0.2.0-rc.2` line for PTY tests. Never
+the launcher against `dsh.compatibility.dshReleases` in the checkout’s
+`package.json` before cloning, not against the declared version range. This
+checkout lists only installed `dsh 0.2.0-rc.2` as verified for PTY tests. Never
 substitute `pnpm dsh` or a `--dsh` path from a Harness source checkout: that
 host may migrate the cloned `settings.yaml`. The legacy
 `scripts/dogfood/run-tui-from-worktree.sh` remains available in dsh-tui and

package/.agents/skills/dsh-tui-dogfood/references/home-state.md

@@ -8,7 +8,7 @@ profile. It gives the operational detail behind [../SKILL.md](../SKILL.md).
 | Entry | Kind | What reads or writes it |
 | --- | --- | --- |
 | `.credentials.yaml` | secret | the provider layer, at start-up; read-only |
-| `settings.yaml`, `settings.yaml.imported` | config | the `dsh-tui:` section: theme, tokens, dock, stash, prompt history |
+| `settings.yaml`, `settings.yaml.imported` | legacy config | On verified `0.2.0-rc.2`, settings migration renames the file before attempting a one-time import into profile entries. Rejected sections remain in `.imported`; neither file is the live TUI configuration. |
 | `themes/` | data | created and watched at start-up; saving a file changes the live surface |
 | `prompt-history.json` | data | the editor's history recall; appended as prompts are sent |
 | `tui-stash/` | data | the parked-draft bank, one file per session, behind a lock |
@@ -20,9 +20,9 @@ profile. It gives the operational detail behind [../SKILL.md](../SKILL.md).
 
 ## Home state versus profile state
 
-Credentials, settings, themes, history, the stash, storages, and sessions belong
-to the **home**: every profile in it shares them. The bundle list and the patch
-overlay belong to the **profile**: a new profile name starts from the base plus
+Credentials, themes, history, the stash, storages, and sessions belong to the
+**home**: every profile in it shares them. On verified `0.2.0-rc.2`, live settings,
+the bundle list, and the patch overlay belong to the **profile**: a new profile name starts from the base plus
 whatever is added to it, and inherits none of another profile's bundles or
 patches. That is the trap behind "test it in a profile named after the feature" —
 the run is compositionally thinner than the developer's own while still writing

package/.agents/skills/dsh-tui-dogfood/scripts/clone-links.mjs

@@ -2,14 +2,12 @@
 /**
  * Link policy for the dogfood clone.
  *
- * A cloned home is a sandbox: a dogfood run may write only inside it. Two kinds
- * of link are legitimate there — a package entry that resolves to an installed
- * package or another checkout, and a link that stays inside the clone. A link
- * that escapes is either copied in or refused, and which one depends on who
- * writes the entry: the instruction files below are only read, so the bytes come
- * along; everything else (credentials, settings, storages, sessions, profiles)
- * is state the run may write, and a link out of the clone would let that write
- * reach the developer's own home. Refusing is the safe answer there.
+ * Protect mutable home state from writes reaching the source home. Package
+ * links remain external for dependency loading; writes through them are not
+ * isolated. Other links must stay inside the clone. The instruction files below
+ * are only read, so their external targets can be copied into the clone instead
+ * of blocking a run. Refuse escaping links for other home entries so writes
+ * cannot follow them into the developer's own home.
  *
  * Usage: clone-links.mjs check|materialize <home> <source>
  */
@@ -25,8 +23,9 @@ import { pathToFileURL } from 'node:url'
 export const INSTRUCTION_ENTRIES = new Set(['AGENTS.md', 'CLAUDE.md'])
 
 /**
- * Paths whose whole purpose is to point at an installed package, which may live
- * outside the clone. A link here is expected; a link anywhere else is not.
+ * Package entries may resolve externally so cloned profiles can load installed
+ * packages or checkouts, except source-home targets. Other retained links must stay
+ * inside the clone to keep home-state writes local.
  */
 export const packageEntry = (parts) => parts[0] === 'profiles' && (
   parts[1] === 'node_modules' && parts.length > 2 ||
@@ -34,8 +33,14 @@ export const packageEntry = (parts) => parts[0] === 'profiles' && (
   parts[2] === '.dsh-module-fallback' && parts[3] === 'node_modules' && parts.length > 4
 )
 
+/**
+ * Boundary checks require physical absolute paths; this lexical check cannot resolve aliases.
+ * The separator prevents sibling names sharing a prefix from passing the home boundary.
+ */
 export const inside = (root, file) => file === root || file.startsWith(root + path.sep)
 
+// Keep the read-only exception scoped to home instruction entries; matching names
+// inside mutable state do not establish read-only use.
 const instruction = (home, file) => {
   const parts = path.relative(home, file).split(path.sep)
   return parts.length === 1 && INSTRUCTION_ENTRIES.has(parts[0])
@@ -59,7 +64,6 @@ export function destination(file) {
 const entries = (root) => fs.readdirSync(root, { withFileTypes: true })
 const partsOf = (home, file) => path.relative(home, file).split(path.sep)
 
-/** Every reason the clone cannot be run as a sandbox, in the order they are met. */
 export function problems(home, source) {
   const found = []
   const visit = (dir) => {
@@ -73,6 +77,8 @@ export function problems(home, source) {
       } else if (entry.isDirectory()) {
         visit(file)
       } else if (entry.isFile() && !packageEntry(parts) && fs.lstatSync(file).nlink > 1) {
+        // Hardlink names share writable contents; the link count cannot prove every name stays inside the clone.
+        // Reject non-package hardlinks conservatively rather than risk writes reaching another home.
         found.push('unsafe cloned hardlink outside package modules: ' + file)
       }
     }
@@ -93,6 +99,8 @@ export function materialize(home) {
         const target = destination(path.resolve(dir, fs.readlinkSync(file)))
         if (inside(home, target)) continue
         if (!fs.existsSync(target)) {
+          // No instruction content exists to copy; dropping the external link lets
+          // boundary validation proceed without retaining an escape path.
           fs.rmSync(file)
           console.log('materialize: dropped dangling link ' + path.relative(home, file))
           report.dropped += 1

package/.agents/skills/dsh-tui-dogfood/scripts/run-plugin-from-worktree.sh

@@ -4,8 +4,12 @@ set -euo pipefail
 
 name="$(basename "${BASH_SOURCE[0]}")"
 TUI_PACKAGE_NAME='@sagmans/dsh-tui'
+ISOLATED_ENV_PREFIXES=('HERDR_' 'DSH_TUI_MOSHI_')
+CLEAN_PREVIEW_PREFIX='would remove'
 # The link policy is shared with the validator, so both read one rule set.
 helper_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+# Default to the caller checkout so this packaged helper is not tied to its install location;
+# the legacy wrapper overrides it to remain anchored when invoked from another directory.
 default_repo="${DSH_DOGFOOD_DEFAULT_REPO:-$PWD}"
 default_repo="$(cd "$default_repo" && pwd -P)"
 
@@ -54,6 +58,7 @@ EOF
 
 target=""
 home=""
+# Agent sessions may set DSH_HOME to scratch state, not the developer home to clone.
 source_home="$HOME/.dsh"
 profile="tui"
 dsh_bin="${DSH_BIN:-}"
@@ -93,6 +98,8 @@ if [[ -n "$source_home" ]]; then source_home="${source_home/#\~/$HOME}"; fi
 
 # --- the repository's worktrees ---------------------------------------------
 
+# Git discovery is best-effort so an unavailable registry does not block the
+# sibling-directory fallback; the chosen directory still needs a plugin manifest.
 worktree_lines() {
   git -C "$default_repo" worktree list --porcelain 2>/dev/null || true
 }
@@ -143,6 +150,8 @@ resolve_target() {
   local hit sibling
   hit="$(resolve_by_name "$target")"
   if [[ -z "$hit" ]]; then
+    # Anchor sibling lookup to the selected repository, not the caller's cwd,
+    # so neighboring plugin checkouts need not appear in its Git worktree registry.
     sibling="$(cd "$default_repo/.." 2>/dev/null && pwd -P)/$target"
     if [[ -d "$sibling" ]]; then hit="$sibling"; fi
   fi
@@ -195,6 +204,7 @@ else
   [[ -d "$source_home" ]] || die "no home to clone at $source_home; pass --source-home"
   source_home="$(cd "$source_home" && pwd -P)"
 fi
+# Physical paths keep parent symlink aliases from bypassing overlap checks.
 [[ ! -L "$home" ]] || die "scratch home cannot be a symlink: $home"
 home="$(node -e "const fs=require('node:fs'),p=require('node:path');let x=p.resolve(process.argv[1]),b=x;while(!fs.existsSync(b))b=p.dirname(b);console.log(p.join(fs.realpathSync(b),p.relative(b,x)))" "$home")"
 [[ ! -L "$home" ]] || die "scratch home cannot be a symlink: $home"
@@ -203,10 +213,12 @@ user_home="$(cd "$HOME" && pwd -P)"
 [[ "$home/" != "$user_home/"* && "$user_home/" != "$home/"* ]] || die "scratch home cannot overlap the user home"
 [[ "$home/" != "$target_path/"* && "$target_path/" != "$home/"* ]] || die "scratch home cannot overlap the target checkout"
 [[ "$home" != / ]] || die "scratch home cannot be filesystem root"
+# Marker identities occupy one line each; embedded newlines would break identity checks.
 for path in "$home" "$source_home" "$target_path"; do [[ "$path" != *$'\n'* ]] || die "paths cannot contain newlines"; done
 marker="$home/.dsh-dogfood"
 profile_json="$home/profiles/$profile/package.json"
 
+# Credential permission changes must not affect a shared inode or an external symlink target.
 check_credentials() {
   [[ ! -L "$home/.credentials.yaml" ]] || die "cloned credentials cannot be a symlink"
   [[ -e "$home/.credentials.yaml" ]] || return 0
@@ -253,6 +265,11 @@ fi
 if [[ "$action" == "clean" ]]; then
   [[ -d "$home" ]] || { note "nothing at $home"; exit 0; }
   validate_marker
+  # Preview must honor cleanup guards without deleting the state being inspected.
+  if [[ "$dry_run" == 1 ]]; then
+    note "$CLEAN_PREVIEW_PREFIX $home"
+    exit 0
+  fi
   rm -rf "$home"
   note "removed $home"
   exit 0
@@ -285,9 +302,8 @@ fi
 
 if [[ -d "$home" && "$action" != "clean" && "$dry_run" != 1 ]]; then
   validate_marker
-  # A marker that still reads 0 belongs to a run the kernel killed before it could
-  # clean up: the identity matches, so --reseed takes it, but nothing may reuse a
-  # home whose copy stopped halfway. A marker without the line predates this.
+  # Copy or later setup failures can leave ready=0; require --reseed rather than
+  # reuse an incomplete clone.
   [[ "$reseed" == 1 ]] || [[ "$(marker_value ready)" != 0 ]] || die "$home is a half-seeded clone; pass --reseed to clone it again"
   check_credentials
   chmod 700 "$home"
@@ -311,7 +327,7 @@ if [[ ! -d "$home" ]]; then
   chmod 700 "$home"
   # Written before the copy, so whatever the copy does this directory is one that
   # --clean and --reseed already own: an interrupted clone is recoverable rather
-  # than a husk neither action will touch. The copy marks it ready when it lands.
+  # than a husk neither action will touch. It becomes reusable only after setup.
   printf 'home=%s\nsource=%s\ntarget=%s\nprofile=%s\nready=0\n' "$home" "$source_home" "$target_path" "$profile" > "$marker"
   chmod 600 "$marker"
   if [[ "$fresh" == 1 ]]; then
@@ -342,6 +358,7 @@ check_clone_links
 
 # --- build, link, run --------------------------------------------------------
 
+# Linked TUI profiles load lib/, not src/, so rebuilding makes source edits visible to the run.
 if [[ "$build" == 1 && ! -d "$target_path/node_modules" ]]; then
   die "$target_path has no node_modules; run pnpm install there first (or pass --no-build)"
 fi
@@ -392,6 +409,8 @@ const state = (file) => fs.lstatSync(file, { throwIfNoEntry: false })
 for (const part of [directory, path.dirname(directory), moduleDir]) {
   if (state(part)?.isSymbolicLink()) throw Error("unsafe symlink in profile path: " + part)
 }
+// Reject invalid names and unsafe existing destinations before replacing links;
+// target-boundary checks run afterward and do not roll back earlier relinking.
 for (const [name, spec] of entries) {
   if (!packagePattern.test(name)) throw Error("invalid link dependency name: " + name)
   if (name.includes("\n") || spec.includes("\n") || spec.includes("\0")) throw Error("unsafe link dependency: " + name)
@@ -417,8 +436,8 @@ if ! node -e "process.exit(require(process.argv[1]).dsh.profile.bundles.includes
   die "profile '$profile' does not list $package_name after relink (bundles: $bundles)"
 fi
 
-# The home is finished: it points at the target and its bundles answer, so it is
-# ready to be reused rather than re-seeded.
+# Completed setup permits clone reuse; link safety and bundle membership checks
+# do not prove that the bundles load or answer at runtime.
 printf 'home=%s\nsource=%s\ntarget=%s\nprofile=%s\nready=1\n' "$home" "$source_home" "$target_path" "$profile" > "$marker"
 chmod 600 "$marker"
 
@@ -431,9 +450,12 @@ printf 'profile: %s (%s)\n' "$profile" "$bundles" >&2
 # started with them claims that pane's agent row for this run: the row comes back
 # released, and the pane's real agent disappears from Herdr's pickers until it is
 # restarted. The clone is launched as a surface in a bare terminal instead.
-while IFS= read -r herdr_var; do
-  unset "$herdr_var"
-done < <(env | sed -n 's/^\(HERDR_[A-Za-z0-9_]*\)=.*/\1/p')
+# Incidental model notifications must not borrow the caller's production token.
+for isolated_prefix in "${ISOLATED_ENV_PREFIXES[@]}"; do
+  while IFS= read -r isolated_var; do
+    if [[ "$isolated_var" == "$isolated_prefix"* ]]; then unset "$isolated_var"; fi
+  done < <(compgen -e)
+done
 
 run_command=(env "DSH_HOME=$home" "$dsh_bin" --profile "$profile")
 if [[ "${#passthrough[@]}" -gt 0 ]]; then

package/.agents/skills/dsh-tui-update-models/SKILL.md

@@ -13,7 +13,7 @@ the ctx gauge. Find the owner first; then edit exactly one place.
 | Where the wiring is | What it owns |
 | --- | --- |
 | `~/.dsh/profiles/<profile>/cordis.patch.yml` | The patch layer: applied after every bundle layer, last entry wins. Holds the catalog or `llm-pi-ai` config a developer actually edits. |
-| `~/.dsh/settings.yaml` | Host settings, hot-reloaded. A `llm-pi-ai:` or `llm-deepseek:` section overrides that adapter's patch entry without a restart - it is what the web Models page writes, and what an additive sign-in declares a route in. The legacy `dsh-provider-extra:` section carries `extraModels` and `codexExtraModels` only. **A catalog is never settings-owned**: managed mode installs no section, reads no overlay, and turns off settings projection for its own Config, so the profile patch is the only place a catalog exists. |
+| `~/.dsh/settings.yaml`, `settings.yaml.imported` | Legacy input, not a live overlay on verified `0.2.0-rc.2`. Settings migration renames the file before attempting a one-time import into matching profile entries. Configure adapter rows in the active profile patch. Keep catalog edits in that patch and consult the installed catalog documentation. |
 | `~/.dsh/profiles/<profile>/package.json` | Bundles and their dependency specs (`link:` for a checkout, a range for a release). |
 | `node_modules/<bundle>/cordis.patch.yml` | The bundle's own defaults: disabled base rows, inserted rows, default config. |
 | `node_modules/@earendil-works/pi-ai/dist/providers/data/<source>.json` | Installed per-provider catalog: ids, and the cost/context/effort data a template clone or a `filter` match inherits. |

package/.agents/skills/dsh-tui-update-models/references/model-wiring.md

@@ -12,12 +12,12 @@ Companion to [SKILL.md](../SKILL.md): exact fields, files, and checks.
 4. The model directory a profile sees is owned by whichever row is enabled:
    `llm-pi-ai` (additive provider config), `dsh-provider-extra` (owned catalog),
    or both, if the profile is not using exclusive ownership.
-5. `$DSH_HOME/settings.yaml` sits over the adapter rows, not over a catalog. A
-   `llm-pi-ai:` or `llm-deepseek:` section reshapes that adapter per request; a
-   `dsh-provider-extra:` section reshapes only the legacy routes'
-   `extraModels`/`codexExtraModels`, and only where no `models`/`codexModels`
-   selection is declared. A managed catalog reads no settings overlay at all, so
-   a catalog edit lands in the profile patch or nowhere.
+5. On verified `0.2.0-rc.2`, settings forms read and update Config-backed
+   profile entries. `$DSH_HOME/settings.yaml` is legacy input, not a live adapter
+   overlay. Migration renames it to `.imported` before a one-time import; rejected
+   sections remain only in that renamed file. Edit adapter and catalog config in
+   the active profile patch. Do not assume legacy per-request settings behavior
+   on a host that exposes only Config-backed forms.
 
 Exclusive ownership is a set of disable rows plus the catalog itself:
 

package/.agents/skills/dsh-tui-update-models/scripts/dump-model-catalog.mjs

@@ -1,30 +1,28 @@
 #!/usr/bin/env node
 /**
- * Print the model directory a dsh profile resolves, with the provenance of
- * every field.
+ * Inspect the profile's owned catalog and inherited model facts without
+ * composing the profile.
  *
  * The surface reads prices, context windows, and reasoning levels from the
  * composition, not from the vendor's page, so an inherited or stale value is
  * invisible in the UI. This reads the same two inputs the resolver does - the
  * owned catalog in the profile patch, and the installed pi-ai provider data -
- * and names where each number came from: "installed" for the source's own
- * entry, "template:<id>" for a clone, "route" for the protocol a sourceless
- * route declares once for every model it serves, "metadata" for what the
- * catalog declares.
+ * to expose inheritance and overrides that the UI does not distinguish.
+ * Installed facts are the unlabeled baseline; "template:<id>", "route", and
+ * "metadata" identify departures from it.
  *
  * An entry the catalog spells out completely needs no installed entry at all,
  * so a missing harness install must not hide it. A `filter` route is the
  * exception: its membership is the installed catalog's, so it cannot be read
- * without that install. A declaration the plugin's resolver would refuse is
- * reported as a refusal here too, because a catalog that cannot compose serves
- * nothing.
+ * without provider data. Selected resolution checks expose unusable declarations,
+ * but this inspection does not validate every template, schema, or ownership rule.
+ * Compose the candidate before trusting it as a usable profile.
  *
  * Usage: dump-model-catalog.mjs [--home <dsh home>] [--profile <name>]
  *                               [--data <pi-ai data dir>] [--json]
  *
- * `--data` names the installed provider-data directory to inherit from, which
- * is how a reading is checked where no harness is installed - a `filter` route
- * and every template clone need one.
+ * `--data` supplies inherited facts when no harness is installed, so filter
+ * membership and template-derived values can still be inspected offline.
  */
 import { execFileSync } from 'node:child_process'
 import { readFileSync, realpathSync } from 'node:fs'
@@ -55,6 +53,7 @@ export function supportedLevels(levelMap) {
   })
 }
 
+/** Defaults target the documented TUI patch; DSH_HOME keeps inspection on the caller-selected home. */
 function parseArgs(argv) {
   const options = { home: process.env.DSH_HOME ?? join(homedir(), '.dsh'), profile: 'tui', data: undefined, json: false }
   for (let index = 0; index < argv.length; index += 1) {
@@ -80,7 +79,10 @@ function dataDirectory() {
   }
 }
 
-/** Every JSON patch entry that configures the owned catalog, last one winning. */
+/**
+ * The catalog:setup flow map is the machine-readable inspection boundary;
+ * block YAML needs list-models composition. Later patch entries take precedence.
+ */
 export function catalogConfig(patch) {
   const lines = readFileSync(patch, 'utf8').split('\n')
   let catalog
@@ -92,6 +94,10 @@ export function catalogConfig(patch) {
   return catalog
 }
 
+/**
+ * Unusable inherited data must not prevent inspection of fully declared models.
+ * Read and parse failures lose their diagnostics here; dependent entries get resolution errors instead.
+ */
 export function providerData(directory, source) {
   if (directory === undefined || source === undefined) return undefined
   try {
@@ -229,6 +235,8 @@ function rowsOf(catalog, directory) {
         ...(result.requestMax === undefined ? {} : { requestMax: result.requestMax }),
         ...(result.aliases === undefined ? {} : { aliases: result.aliases }),
         ...(result.tiers === undefined ? {} : { tiers: result.tiers }),
+        // Installed facts are the baseline; name only other origins to expose
+        // template inheritance and catalog overrides without repeating that baseline.
         origins: INHERITED_FIELDS
           .map(field => [field, result.origins[field]])
           .filter(([, origin]) => origin !== INSTALLED)

package/README.md

@@ -108,7 +108,9 @@ The profile then keeps `@deepseek-ai/dsh-base` and no application, so `dsh --pro
 
 ### Use the installed Harness launcher
 
-Run `dsh --version` and confirm the release is inside the supported window (`>=0.2.0-rc.2 <0.3.0`) before launching this plugin. `pnpm dsh` from a Harness source checkout runs its development host, not the installed release. That host can migrate `settings.yaml` and is outside this plugin's supported range; do not use it for TUI dogfooding.
+The manifest declares `>=0.2.0-rc.2 <0.3.0`, but lists only `0.2.0-rc.2` as a verified release. Range membership alone does not prove compatibility. Run `dsh --version` and use that installed release for dogfooding. `pnpm dsh` from a Harness source checkout runs a development host, not the verified installed release. It can migrate `settings.yaml`; do not use it for TUI dogfooding.
+
+The surface probes required and optional services at startup, and selects settings APIs by capability. These checks do not validate the host version or prove full-profile behavior. The dogfood helper and PTY driver separately check the launcher against the manifest's verified releases.
 
 ## Troubleshooting
 
@@ -118,7 +120,7 @@ Two facts explain most failures.
 
 **`dsh plugin install` removes a bundle it cannot resolve, and says nothing.** The command reconciles `dsh.profile.bundles` against the installed dependencies. A bundle whose path does not resolve leaves the list, and the command still exits 0. The next launch composes `@deepseek-ai/dsh-base` alone. No application plugin mounts, so nothing reads the command line: `dsh --profile tui` then prints nothing and never exits, and `--help` waits with it.
 
-**npm reports `overriding peer dependency` while a harness tree resolves, and the lines are not failures.** The harness floats its own prereleases, so its dependencies hold overlapping ranges over the same packages and npm names each range it overrides; the install still exits 0. A plugin profile does not have that shape — `dsh plugin add` resolves one copy of every package this bundle mounts. The plugin's own peers are optional so that npm keeps the host's copy instead of nesting a private one.
+**npm can report `overriding peer dependency` while a harness tree resolves.** A warning alone does not mean the install failed; check its exit status. This plugin pins its mounted harness dependencies to `0.2.0-rc.2` and declares optional harness peers as `*`. Optional peers avoid automatic installation when absent; neither open peers nor exact dependencies guarantee consumer deduplication. The consumer install smoke checks package-copy counts for its selected release and install paths, not every host in the declared range.
 
 | Symptom | Cause | Fix |
 |---|---|---|
@@ -127,7 +129,7 @@ Two facts explain most failures.
 | `dsh-tui: both stdin and stdout must be TTYs` | stdin or stdout is a pipe, a file, or a CI runner | run the command from a terminal |
 | Node warnings, such as `ExperimentalWarning: stripTypeScriptTypes …`, appear after exit | the TUI holds runtime warnings until it returns the terminal to your shell; startup warnings remain visible before the TUI starts | read the warnings in your shell after exit; no warning-suppression flag is needed |
 | Changes under `src/` have no effect | a linked profile loads `lib/`, not `src/` | `pnpm run build` in the plugin checkout |
-| TUI preferences disappear after launching a Harness source checkout | that host treats `settings.yaml` as migration input, not live preferences | use an installed release inside the supported window with a cloned home; preserve the original settings file |
+| TUI preferences disappear after launching a Harness source checkout | that host treats `settings.yaml` as migration input, not live preferences | use the verified installed release with a cloned home; preserve the original settings file |
 | `--preset <id>` is refused, because the session's agent preset is fixed | a session keeps the mode that composed it, and this session already took a turn | `/preset <id>` before the first turn, or resume without `--preset` |
 | `--resume <id>` starts a new session | the id is a bare UUID | pass the stored id, `tui-session-…` included; a bare `--resume` opens the picker |
 | `dsh: profile "tui" does not exist` | the profile is not created yet | the `add` command creates it |
@@ -446,6 +448,8 @@ an action with one, so the surface can be restyled and rebound without touching
 code. On the supported line a preference lives in the active profile's own patch,
 under the TUI entry's `config`; `/theme <name>` writes a chosen theme there for
 you. Use the actual entry ID, normally `tui`, not the legacy `dsh-tui` namespace.
+Merge preferences into the existing `config`; preserve its startup `!!js` fields.
+The verified host replaces `config` wholesale, so a partial replacement loses the launch identity.
 
 ```yaml
 - id: tui
@@ -500,27 +504,27 @@ The plugin exports a Config schema for all preferences shown above, including
 `prefix`, `prefixWindow`, and `keys`. Launch fields such as `sessionId`,
 `model`, and `provider` remain separate from live preference edits.
 The settings service owns persistence. TUI does not create another preference store.
-It uses released `installSection` or `register` APIs, or Config-backed
+It uses legacy section-style `installSection` or `register` APIs, or Config-backed
 `describe` and revision-checked `update` APIs. Unsupported or read-only writes
 show a notice instead of reporting success. A rejected theme selection restores
 the applied theme, and `/theme tokens` reports that same appearance.
 
 On Config-backed hosts, absent `history.enabled` and `history.ghost` stay off.
 Set each switch to `true` explicitly to enable it. This prevents recording while
-the host's asynchronous legacy import is pending or has failed. Released section
-hosts retain their existing defaults. If the host reports unreadable preferences,
+the host's asynchronous legacy import is pending or has failed. Legacy section-style
+settings providers retain their existing defaults. If the host reports unreadable preferences,
 history stays off. Readable `false` switches survive errors in other fields.
 Malformed updates retain the last valid appearance and do not overwrite their source.
 
 When public descriptors expose raw user layers, history checks those layers at use
 time. A readable opt-out survives rejected siblings even without a change event.
 Another rejected opt-in cannot clear this protection; a valid committed update can.
-A released-provider limit remains: after an absent user section, rejected scalar
+A section-provider limit remains: after an absent user section, rejected scalar
 sections can produce identical public descriptors. TUI cannot detect that transition
-without host validity metadata, so normal released defaults remain active.
+without host validity metadata, so section-provider defaults remain active.
 
-The inspected source host has no legacy import alias from `dsh-tui` to `tui`.
-Exporting Config does not resolve that namespace mismatch. The host can rename
+The verified `0.2.0-rc.2` settings service has no legacy import alias from `dsh-tui` to `tui`.
+Exporting Config does not resolve that namespace mismatch. The service renames
 `settings.yaml` to `settings.yaml.imported` before import completes.
 TUI does not retry or restore that file automatically. Preserve current privacy
 opt-outs and copy only the intended legacy fields into the actual TUI entry's
@@ -804,8 +808,8 @@ The mode is re-read rather than remembered: resuming mounts what that session's
 The package is a Cordis plugin bundle that stacks over `@deepseek-ai/dsh-base`:
 
 - `@sagmans/dsh-tui/startup` parses this app's own flags and publishes the launch identity.
-- The roster of modes holds the id a session starts in when nobody names one: `@deepseek-ai/dsh-agent-preset-registry` owns that service on the supported line, and each mode arrives as a row of `@deepseek-ai/dsh-agent-preset`, so this bundle declares the four modes itself. Both are mounted through this bundle's own `host/roster` entry point, because a patch row is applied before any service exists and the registry and the modes arrive with the harness's own agent services — after the surface that needs the roster. A mode names a selection rather than a composition: the plugins an agent runs on belong to the bundle shipping each of them, and the profile's own layers compose them, so a mode here declares no plugin row and the patch disables none. The one row a mode does own is its presentation: `ptc` mounts `@deepseek-ai/dsh-agent-tool-presentation` with `mode: ptc`, because the form an agent's tools take is declared per agent — a session's own row cannot say it, and a mode without the row presents natively whatever its id says.
-- `@deepseek-ai/dsh-cordis-host-runner` is the host machinery creator mode needs, and the base mounts no such row, so a terminal profile mounts it through this bundle's own `host/runner` entry point. The code runtime PTC mode runs programs against is a base row of its own (`ptc-runtime`) on the supported line, so this bundle mounts none of its own. Both packages are plain dependencies: a profile resolves exactly one copy of each, and the harness reads its runtime version off the runner it mounts.
+- The roster of modes holds the id a session starts in when nobody names one: `@deepseek-ai/dsh-agent-preset-registry` owns that service on the supported line, and each mode arrives as a row of `@deepseek-ai/dsh-agent-preset`, so this bundle declares the four modes itself. Both are mounted through this bundle's own `host/roster` entry point, because a patch row is applied before any service exists and the registry and the modes arrive with the harness's own agent services — after the surface that needs the roster. A mode names a selection rather than a composition: the plugins an agent runs on belong to the bundle shipping each of them, and the profile's own layers compose them, so the other shipped modes declare no plugin row and the patch disables none. The one row a mode does own is its presentation: `ptc` mounts `@deepseek-ai/dsh-agent-tool-presentation` with `mode: ptc`, because the form an agent's tools take is declared per agent — a session's own row cannot say it, and a mode without the row presents natively whatever its id says.
+- `@deepseek-ai/dsh-cordis-host-runner` is the host machinery creator mode needs, and the base mounts no such row, so a terminal profile mounts it through this bundle's own `host/runner` entry point. The code runtime PTC mode runs programs against is a base row of its own (`ptc-runtime`) on the supported line, so this bundle mounts none of its own. The registry, preset, and runner packages are plain dependencies pinned to `0.2.0-rc.2`; these pins do not guarantee one copy in every consumer tree.
 - `@sagmans/dsh-tui` owns the terminal: it creates or resumes one agent through `ctx.agents`, folds `session/event` into transcript rows and work state, renders them with `@earendil-works/pi-tui`, and releases the terminal on exit, on a boot failure, and on a signal.
 - `@sagmans/dsh-tui/todo-guard` is the one advisory row this bundle adds to the agent plane: it watches the harness's own `todos` and `plan` projections and rides the next tool result with a reminder when a plan ages. See [Todo discipline](#todo-discipline).
 
@@ -823,7 +827,7 @@ A PTC card is the one card with children: every call the `run_code` program disp
 
 A card's header names the tool, then, on a skill card, the skill it loaded in the `tool.skill` colour, then the argument the call was made with — a path or a command — in the `tool.args` colour, then the facts the result measured: a read reports its line range, line count, and token size; a file change that carried no prior content to compare against reports its lines and tokens; one that did reports added, changed, and removed lines as `+n ~n -n` in green, yellow, and red. Each stat is its own token, so any of them can be recoloured or hidden independently, and so are the elements a call in flight is drawn with — hiding `tool.running.elapsed` leaves the name in its running colour, hiding `tool.running.title` leaves the seconds counting, hiding `tool.elapsed.done` takes the total off a program's settled row, and a dispatched row is toned the same way per state with `tool.subcall.running` and `tool.subcall.title`. A state is only how a name is painted, so hiding one of those colours leaves the name in the colour a call with no state is read in rather than taking the name away. Hiding `tool.skill` is the same promise for a subject: the skill keeps its name in the label's colour. `/export` and a dispatched row spell the name too, so the words survive where no colour is.
 
-The bundle also takes the base's global agent rows out of the composition, twenty-three of them. Every one is a row the shipped modes supply per session instead, so leaving it mounted registers the same tool names in two layers and doubles each prompt section it owns. What stays mounted is the host: sessions, storage, models, permissions, jobs, and the command registry.
+The bundle disables no base row. The profile's layers supply the agent tools, prompt sections, skills, and planning. The shipped modes do not duplicate those rows; PTC adds only its tool-presentation row.
 
 ### Todo discipline
 
@@ -882,18 +886,51 @@ rows = [
 
 With that row present, a pane waiting on a decision names the tool that asked instead of showing a colour alone. A label longer than the 80 characters Herdr holds whole is cut here rather than server-side, so the ellipsis lands where this surface put it; the message that rides the state report keeps its own, longer bound.
 
+## Moshi notifications
+
+[Moshi](https://getmoshi.app/docs/notifications) can send optional notifications for the session this terminal drives.
+Set `DSH_TUI_MOSHI_TOKEN` in the process environment before you start `dsh --profile tui`.
+Use a Moshi API token, not the host secret used by `moshi-hook`.
+The reporter is disabled when this variable is absent or empty.
+It works without Herdr or the Moshi daemon.
+
+Load the token through your secret manager. Do not put it in profile YAML, shell history, or a conversation.
+Unset `DSH_TUI_MOSHI_TOKEN` and restart the surface to disable notifications.
+
+The reporter sends these fixed messages:
+
+- **DSH needs attention:** “Return to the terminal to continue.” An agent approval or question triggers this notification.
+- **DSH finished:** “The current session is ready for input.” The driven agent and its background work must both stop.
+
+Reader navigation does not trigger attention notifications. Duplicate status events do not produce duplicate notifications.
+A finished run can include cancellation or failure; the message does not report task success.
+Switching sessions discards queued notifications and aborts outstanding delivery.
+Notifications already delivered cannot be recalled.
+
+The only JSON fields sent to `https://api.getmoshi.app/api/webhook` are `token`, `title`, and `message`.
+The message contains no transcript, prompt, tool arguments, approval text, working directory, or session/pane identifiers.
+The token selects its owning Moshi device; the reporter does not request multi-device delivery.
+Requests abort after three seconds. Network and HTTP failures remain silent, with no retries.
+Notification delivery never blocks agent work or terminal teardown.
+
+This integration does not provide native Chat View, Live Activity, remote approval controls, or automatic pane navigation.
+Use the existing Moshi SSH connection to return to the terminal.
+
 ## Development
 
 ```sh
-pnpm install
-pnpm run typecheck
-pnpm test
-pnpm run build
+pnpm install --frozen-lockfile
+pnpm verify
 ```
 
 **A linked profile loads the built entry point**, so edits under `src/` are invisible to `dsh --profile tui` until `pnpm run build` runs. The PTY driver rebuilds, checks nested links in the isolated `--home`, and rejects a launcher whose version `dsh.compatibility.dshReleases` does not list.
 
-Clone your configured home with the dogfood helper for realistic runs. A minimal throwaway home can also expose startup failures without touching your real state:
+`pnpm verify` preserves golden snapshots and automatically drives free real-profile
+scenarios without credentials. [FEATURES.md](FEATURES.md) owns feature inventory
+and evidence rules. Unit suites are not maintained.
+
+Paid model use runs only on explicit demand. For those checks, clone your
+configured home with the dogfood helper. These commands include paid model calls:
 
 ```sh
 S=$(mktemp -d)
@@ -905,10 +942,11 @@ node tools/pty-drive.mjs --home "$S" --seconds 20 --prompt ''
 node tools/pty-drive.mjs --home "$S" --prompt 'Run: echo hi' --click 20:12
 ```
 
-A minimal home starts on the shipped defaults: `settings.yaml` is legacy on the
-supported line, where the launcher renames it before import, so a preference
-copied there is read by nothing. Use the dogfood clone above when a run needs
-your own preferences.
+A minimal home starts on the shipped defaults. On verified `0.2.0-rc.2`, the
+settings service renames legacy `settings.yaml` before attempting a one-time
+import into matching profile entries. Rejected sections remain only in
+`settings.yaml.imported`. Use the active profile patch for current preferences,
+or the dogfood clone above when a run needs your own composition.
 
 Test specs import plugin sources through the `@/` alias. Under this test runner the spec file is resolved with a root-relative id, so parent-relative imports (`../src/...`) do not resolve; the alias and its matching `tsconfig.test.json` path mapping avoid that.
 
@@ -1026,7 +1064,7 @@ discipline as this one.
 
 | Plugin | What it adds |
 |---|---|
-| [`@sagmans/dsh-auto-compact`](https://github.com/sagmans/dsh-auto-compact) | An absolute token trigger for automatic compaction: the conversation condenses at `min(thresholdTokens, contextWindow × thresholdRatio)` instead of the window ratio alone, so a large-window model pays a fixed price, with per-route overrides. Its patch swaps the shipped `compaction-basic` backend — the same row this bundle already takes out of the global composition — so the profile still keeps exactly one compaction service, and this surface needs no setting for it. |
+| [`@sagmans/dsh-auto-compact`](https://github.com/sagmans/dsh-auto-compact) | An absolute token trigger for automatic compaction: the conversation condenses at `min(thresholdTokens, contextWindow × thresholdRatio)` instead of the window ratio alone, so a large-window model pays a fixed price, with per-route overrides. Its patch swaps the shipped `compaction-basic` backend — a row this bundle does not disable — so the profile still keeps exactly one compaction service, and this surface needs no setting for it. |
 | [`@sagmans/dsh-provider-extra`](https://github.com/sagmans/dsh-provider-extra) | Extra provider routes: OpenCode Go, which sends the live conversation id in `x-opencode-session` for routing and prompt caching, and OpenAI Codex over a ChatGPT subscription's OAuth flow with the harness credential store. Its routes join the `/model` picker like every configured provider. TUI also works without this package, using the core `llm` and `agentDefaultModel` services. |
 
 ```sh

package/cordis.patch.yml

@@ -29,6 +29,8 @@
     - id: tui-keymaps
       name: '@sagmans/dsh-tui/keymaps'
 
+    # Parse launcher intent once; injection keeps the surface behind committed startup state
+    # and prevents --help or usage errors from mounting the interactive screen.
     - id: tui-startup
       name: '@sagmans/dsh-tui/startup'
 

package/lib/agent/fork.d.ts

@@ -3,12 +3,14 @@ export interface ForkEvent {
     readonly type: string;
     readonly data?: unknown;
     readonly seq?: number;
+    /** Re-folding a log must preserve the clock of its recorded work. */
+    readonly time?: number;
 }
 /** Where a fork may branch, and how much of the log the child inherits. */
 export interface ForkPoint {
     /** Events the child inherits, counted from the start of the log. */
     readonly inheritedEvents: number;
-    /** Seq of the turn/end the cut is anchored to. */
+    /** Boundary label for the fork notice, not the inherited-prefix offset. */
     readonly boundarySeq: number;
 }
 /**

package/lib/agent/fork.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fork.d.ts","sourceRoot":"","sources":["../../src/agent/fork.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,2EAA2E;AAC3E,MAAM,WAAW,SAAS;IACxB,oEAAoE;IACpE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,GAAG,SAAS,CAY7E"}
+{"version":3,"file":"fork.d.ts","sourceRoot":"","sources":["../../src/agent/fork.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,2EAA2E;AAC3E,MAAM,WAAW,SAAS;IACxB,oEAAoE;IACpE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,GAAG,SAAS,CAc7E"}

package/lib/agent/fork.js

@@ -20,6 +20,8 @@ export function forkPoint(events) {
     let cut = boundary + 1;
     while (cut < events.length && events[cut]?.type !== 'turn/start')
         cut += 1;
+    // The notice still needs a boundary label when seq is absent; only the array
+    // cut determines inheritance, so this index does not stand in for a durable seq.
     return { inheritedEvents: cut, boundarySeq: events[boundary]?.seq ?? boundary };
 }
 //# sourceMappingURL=fork.js.map