dsh-model-pin

Readme

# dsh-model-pin

A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin for machines that cannot afford model roulette: keep every model request inside an allowed set per provider, redirect the rest to a fallback (or refuse them), and get a warning whenever a request would make a llama.cpp router reload models.

## The problem it fixes

dsh lets every chat pick its own model, and background helpers can request yet another one. On a machine that can only keep one local model loaded, each stray request either fails or evicts the loaded model: minutes of reloading, prompt cache gone (discussion #3199). Worse, subagents inherit the model their parent session was CREATED with, not the one it currently uses, so they quietly land on stale or wrong routes (#455, #1581).

dsh-model-pin enforces an allow-list at dsh's own resolution layer (the `agent/request` waterfall, whose documentation calls returning a replacement "the sanctioned switch path"). Every request from every session is resolved against the list at step boundaries: subagents, retries, and, once the pinned route is logged, session-title and compaction calls too. Persisted session data is never rewritten.

## Install

```
dsh plugin --profile web add dsh-model-pin
```

Then in `~/.dsh/profiles/web/cordis.patch.yml`:

```yaml
- id: model-pin
  config:
    providers:
      llamacpp:
        allow: [qwen3.8-q4-long, qwen3.8-fast]   # a one-entry list = single-model mode
        fallback: qwen3.8-q4-long                # default: the first allowed entry
        action: redirect                          # redirect (default) | reject
        warnOnSwitch: true
```

Unconfigured providers are never touched.

## What it looks like

```
model-pin: llamacpp session=059a680f turn 3 redirecting qwen3.8 -> qwen3.8-q4-long (not in allow)
model-pin: llamacpp model switch qwen3.8-q4-long -> qwen3.8-fast (a --models-max 1 router reloads now; the previous model's prompt cache is lost)
```

With `action: reject`, a disallowed request fails the turn with a clear message instead (`model-pin: model "x" is not in the allowed set for provider "llamacpp" (allowed: ...)`), and dsh's retry never loops on it.

## What you should know

- The web model picker does not know about the pin: it may keep displaying the model you clicked while every request actually runs on the fallback. The redirect line in the terminal (or /logs, if dsh-logbook is installed) shows what actually ran.
- The pin has the last word over the picker because it registers at profile load, before any agent exists (first-registered waterfall listeners are outermost in cordis). Another root plugin loaded before this one could still override it.
- The switch warning is observation only; it cannot block a reload. Pair it with a one-entry allow-list if you want reloads gone entirely.
- Cross-provider redirection is out of scope for v1: requests for a provider you did not configure pass through, including a subagent stuck on a deleted provider.
- Related work: [dsh-model-switch](https://github.com/NOirBRight/dsh-model-switch) is the opposite personality: a polished per-role model router with web UI panels, deliberately without global enforcement. dsh-model-pin is config-first, headless-friendly, and about restriction, not routing.

## License

MIT