` installed the bundle in
~449 ms; `dsh --profile --dump-config` composed the `iterate-plugin` bundle
patch into the profile; `dsh plugin --profile
remove iterate-plugin`
uninstalled in ~602 ms and left zero references in the composed config. A full
runtime boot was **not** exercised here (no model provider in the disposable
profile), so `dshOperations` start/rollback stay `unknown`/`partial` — see
`CHANGELOG.md` for the exact commands and timings.
### Runtime permissions (conservative disclosure)
The plugin runs with the **same process capabilities as the DSH host** and touches the
following capabilities; elevated capability means a DSH Profile install stays
`user-reviewed`/guarded rather than auto-approved:
- **Files** — reads and writes project-local state under `/.iterate/`
(decision log, checkpoint, transcript, fix backups/registry, quality gate,
experience bank, defense events). `iterate_fix` / `iterate_triage` also apply
in-place edits to the user's source files (path-traversal protected to the
resolved project root, backups taken before every fix, rollback on failure).
The client half persists triage verdicts to `localStorage`.
- **Commands** — the plugin's own tools execute a small, strictly bounded command
surface inside the dsh host process, only when the model calls them: `iterate_validate`
runs one of the **exact-match whitelisted** commands configured in
`iterate.config.yaml` `validation.commands` (yes, it shells out via
`node:child_process`, timeout-capped to ≤600 s); `iterate_review` (changed-only
scope) runs `git diff --name-only -z ` in the project root. Nothing else
spawns a process. The client "command buttons" only copy paste-able instruction
text; they do not spawn processes.
- **Credentials** — this plugin does **not** read or transmit credentials at
runtime. The sibling **iterate-skill / iterate-harness** components may read git
credentials / GitHub tokens when the user runs their own Git/API operations; those
are separate packages and are never loaded by this plugin.
- **Network** — no network access at runtime (everything is local to the project).
### Dependencies
Runtime dependency: `js-yaml` (pinned exact version). The three DSH host
modules the plugin is built against — `@deepseek-ai/cordis`,
`@deepseek-ai/dsh-tools`, `@deepseek-ai/dsh-util-values` — are declared as
**optional `peerDependencies`** so the host's own copies are used instead of a
second one bundled with the plugin (no duplicate module instances; `dsh`
supplies them). They stay pinned in `devDependencies` for local builds and
tests, in lockstep with the newest `dsh.compatibility.dshReleases` entry.
#### Upstream adoption (v3.8.0 → dsh `0.2.1-alpha.4`)
- **Adopted — the `engines.dsh` compatibility contract.** As of `0.2.1-alpha.4`
the dsh runtime decides a third-party plugin's compatibility **from
`engines.dsh` when it is declared** (a semver range, prereleases included),
ignoring `peerDependencies`; when it is absent the runtime falls back to
checking the exact `@deepseek-ai/dsh-*` peer versions. The plugin now declares
`engines.dsh: ">=0.1.1-rc.1"` — the same lower bound as the oldest
`dshReleases` entry — so a current runtime loads it without flagging the
exact-pinned peer list, while every host-specific capability stays
feature-detected (a missing `WorkingDirectoryService`, `ask.displayReason`,
`ctx.jobs`, etc. still degrade to the safe fallback). Earlier runtimes keep
using the `@deepseek-ai/dsh-*` peer versions, which are extended through
`0.2.1-alpha.4`.
- **`0.2.1-alpha.3` / `0.2.1-alpha.4` are otherwise host-level releases** — Web
sign-in, secret/token masking, minimal-mode image reading, `/compact`, plugin
hot-reload, custom plugin index sources, and per-model reasoning-level UI. None
expose a tool/agent/session API this plugin consumes (`defineTool`, `JsonValue`,
`exec.*`, `tools/pre-execute`, `presentCall`), so no further adoption is
required this cycle.
- All five `@deepseek-ai/*` packages are pinned to the exact `0.2.1-alpha.4`
(`@deepseek-ai/cordis` stays `4.0.5-alpha.2`).
#### Upstream adoption (v3.7.0 → dsh `0.2.1-alpha.2`)
- **Adopted — the mutable session working directory.** `src/working-directory.ts`
resolves the project root through `ctx.get('workingDirectory').get(session)`
when the host offers it (feature-detected; `header.cwd` fallback on a missing
service, a throwing service, hostile getters or a non-string result). Needed
because as of `0.2.1-alpha.2` the immutable header keeps the *original*
project by design, so reading it after a directory switch would anchor the
review to the wrong checkout.
- **Evaluated, not adopted:**
- *Session state-record APIs* (experimental plugins writing/reading their own
session records) — reaching into shell-owned record internals is fragile
across alpha releases, and iterate's cross-session state already lives in
`.iterate/`.
- *Shared `AGENTS.md` agents directory (`DSH_AGENTS_HOME`)* — a host-level
instruction concern; the plugin injects its own workflow prompt.
- *Experimental Git Worktrees plugin* — an upstream agent-workflow feature;
the plugin's own `git.use_worktree` config predates it and is unrelated
(per-round git hygiene for the iterate loop).
- *Removal of the `both` tool-presentation mode* — the plugin never set a
presentation mode (it renders `presentCall` cards), so nothing to migrate.
- *Installing the dsh CLI globally from the plugin* — disk cost for a plugin
that never shells out at runtime.
- All five `@deepseek-ai/*` packages are pinned to the exact `0.2.1-alpha.2`
(`@deepseek-ai/cordis` stays `4.0.5-alpha.1`). No
install-time lifecycle scripts (`preinstall`/`install`/`postinstall`/`prepare`);
only `prepublishOnly` (build) runs on publish.
### Failure bounds
- All writes are atomic (temp + rename) and confined under `.iterate/`; a crash
mid-write cannot corrupt the checkpoint/transcript.
- Persistence failures surface as structured `{ ok: false, error }` results instead
of silent success.
- Fix edits are applied to backups first and rolled back on validation failure.
- The UI degrades gracefully when a slot/service is unavailable.
---
## 🎨 Design
The plugin follows dsh's "everything-is-a-plugin" architecture:
- **Does exactly two things** — injects the system prompt teaching the model the iterate workflow + registers 19 pure-function tools
- **All orchestration runs through dsh native `workflow` + `agent` + `parallel`**
- **Core logic is entirely pure functions** (dedupe / filter / sort / converge / meta-audit / diff computation / history filtering / cleanup reporting) — unit-testable, no I/O
- **Security model** — file writes confined to the resolved project root (path-traversal protection); always back up before writing, roll back on failure; config writes also back up + roll back; `iterate_prune` is dry-run by default and only clears artifacts under `.iterate/` with every cleanup logged; `iterate_fix` caps content length and `iterate_triage` caps entry count to fend off abnormal oversized payloads
- **Build-free UI** — `lib/client.js` uses a `React.createElement` tree + injected `
