@yemi33/minions 0.1.2448 → 0.1.2449

package/docs/internal-install.md

@@ -17,7 +17,25 @@ registry such as `ProjectFeed-ISS@Release`.
 
 No manually created PAT is required, accepted, or stored.
 
-## One command
+## Entry points
+
+Without a checkout, download the launcher for your platform from the
+[Minions page](https://icy-water-0224cc51e.2.azurestaticapps.net/minions) and run
+it from your download folder:
+
+```powershell
+# Windows — https://icy-water-0224cc51e.2.azurestaticapps.net/minions/install-minions.ps1
+az login
+powershell -ExecutionPolicy Bypass -File .\install-minions.ps1
+```
+
+```bash
+# Linux / macOS — https://icy-water-0224cc51e.2.azurestaticapps.net/minions/install-minions.sh
+az login
+bash ./install-minions.sh
+```
+
+From a repository checkout, the in-repo wrappers are equivalent:
 
 ```powershell
 # Windows (PowerShell)
@@ -34,8 +52,16 @@ scripts\install-internal-minions.ps1
 node bin/install-internal-minions.js
 ```
 
-All three entry points are thin wrappers over `bin/install-internal-minions.js`,
-so behavior cannot drift between platforms.
+**Every one of these routes ends in `bin/install-internal-minions.js`**, which is
+why they cannot drift apart. The in-repo wrappers are thin shims over it; the
+downloadable launchers stage the verified package into a throwaway folder and
+hand the migration to the copy that ships inside it. The rest of this document
+describes that installer, so it describes all of them.
+
+The downloadable launchers take no options of their own — each one always stages
+the newest published version. Every [option below](#options), including
+`--version` to pin an exact build, belongs to `bin/install-internal-minions.js`,
+so reach it through the `node` route to pass one.
 
 ## Prerequisites
 
@@ -53,14 +79,66 @@ so behavior cannot drift between platforms.
 | `--registry <url>` | the ISS `ProjectFeed-ISS` feed | Override the Azure Artifacts npm registry. Must be `https`. |
 | `--package <name>` | `@opg-microsoft/minions` | Override the internal package name. Must be scoped. |
 | `--backup-dir <dir>` | `<runtime root>/backups/internal-install-<timestamp>` | Where the pre-migration backup is written. |
+| `--runtime-root <dir>` | resolved (see [Runtime root](#runtime-root)) | Pin the runtime root (`MINIONS_HOME`) this run reads, backs up, synchronizes, and restarts. Required to disambiguate when more than one candidate root carries runtime state. It is also the flag `minions update` prints when it refuses a cross-channel public install; quote the path if it contains spaces. |
 | `--keep-public` | off | Leave an existing `@yemi33/minions` global install in place instead of replacing it. |
 | `--no-restart` | off | Sync runtime files but skip the health-verified restart. |
 | `--force` | off | Proceed even while agents are active (see [Active agents](#active-agents)). |
 | `--dry-run` | off | Print the resolved plan and the exact commands; change nothing. |
 | `--help` | — | Usage. |
 
-Exit codes: `0` success, `1` failure, `2` usage error, `3` refused because agents
-are active.
+Exit codes: `0` success, `1` failure, `2` usage error, `3` refused (active agents,
+an ambiguous runtime root, or a `minions` shim the installer cannot prove it owns).
+
+## Runtime root
+
+The runtime root is the `MINIONS_HOME` directory this run backs up, synchronizes,
+and restarts. It is resolved **once**, before a token is acquired or npm is
+touched, and then pinned as an explicit `MINIONS_HOME` onto every child process
+the installer spawns (`backup-state`, `minions init --force`, `minions restart`)
+so no step can re-resolve to a different root. An inherited `MINIONS_TEST_DIR` is
+stripped from that environment, because it outranks `MINIONS_HOME` in
+`engine/core/shared.js#resolveMinionsHome` and would silently un-pin every child. The
+pinned root and how it was chosen are printed at the top of the run and in the
+`--dry-run` plan.
+
+`resolveAuthoritativeRuntimeRoot()` enumerates every candidate the engine itself
+could pick, deduplicates them by resolved path (highest-priority source wins),
+and scores each by whether it carries a **non-empty** `engine/state.db` (a
+zero-byte database is an aborted init, not a runtime worth protecting):
+
+| Candidate | Source |
+|---|---|
+| `--runtime-root <dir>` | explicit operator pin — always wins |
+| `MINIONS_HOME` | explicit environment pin |
+| `~/.minions-root` | the root pointer `minions init` last recorded, which `engine/core/shared.js#resolveMinionsHome` consults |
+| `~/.minions` | the default |
+| the cwd / repo checkout | the nearest ancestor of the working directory containing both `.git` and `engine.js` — the same shape `resolveMinionsHome`'s `preferSourceCheckout` branch would return |
+
+A candidate that carries state outranks one that does not, so **a repo checkout
+never wins over a root that already has state**. When two or more candidates
+carry a non-empty `engine/state.db` and no `--runtime-root` was given, the
+installer **refuses** (exit `3`) and names every candidate plus the exact
+`--runtime-root <path>` command to disambiguate — nothing is downloaded,
+uninstalled, or modified. The installer never guesses which runtime is
+authoritative.
+
+## Install-channel marker
+
+`minions init` records the runtime's version in `.minions-version` and its source
+commit in `.minions-commit`. Neither says **which npm distribution** produced the
+root, so an internal `@opg-microsoft/minions` root and a public
+`@yemi33/minions` root are otherwise indistinguishable on disk. `init` therefore
+also writes `.minions-package` beside them:
+
+```json
+{ "name": "@opg-microsoft/minions", "version": "1.0.76", "installedAt": "2026-07-29T00:00:00.000Z" }
+```
+
+Read it with `shared.readRuntimeChannel(runtimeRoot)`, which returns
+`{ name, version }` or `null`. A **missing** marker means *unknown*, never an
+error: every root initialized before the marker existed has none, and a legacy
+root must keep working. A marker that is corrupt, or that names a package this
+repo would refuse to put on an npm command line, is unknown for the same reason.
 
 ## What it does, in order
 
@@ -69,7 +147,7 @@ The ordering is the safety contract, not a formality. `planSteps()` in
 by `test/unit/install-internal-minions.test.js`.
 
 1. **`acquire-token`** — `az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798`
-   (the same ADO resource id `engine/ado-token.js` uses).
+   (the same ADO resource id `engine/ado/token.js` uses).
 2. **`validate-feed`** — `npm view <package>@<spec> version` against the feed, and
    resolve `latest` to a concrete version. **A feed that is unreachable, or a
    version that does not exist, fails here — before anything is removed.**
@@ -78,26 +156,95 @@ by `test/unit/install-internal-minions.test.js`.
    safe:** the artifact is on local disk before the public package is removed, so
    a feed, network, or auth failure during the global install is recoverable
    offline. Skipped only when no install will run (see step 6).
-4. **`backup-state`** — checkpoints and copies the SQLite state
-   (`engine/state-operations.js#backupState`: `PRAGMA wal_checkpoint(TRUNCATE)` +
-   `VACUUM INTO`), then copies `config.json`, `routing.md`, `pinned.md`, parks a
+4. **`quiesce-services`** — stops any engine/dashboard running against the
+   **pinned** runtime root before anything is backed up, uninstalled, or
+   installed. Running services are detected from the pid files the runtime
+   already writes plus `engine/control.json`; they are stopped through the
+   installed CLI (see *Which stop verb is issued* below), and the run then polls
+   until the database handles are actually released. Release requires **both**
+   signals: the processes are dead *and* `engine/state.db-shm` is absent or
+   empty — a live shared-memory index means a connection still holds the WAL. If
+   the handles are not released within the bounded timeout the run **fails
+   closed**, before any uninstall or package mutation, and prints which stop path
+   was taken, the exact argv it issued, and the exact PIDs still holding the
+   database. Whether services were actually stopped is recorded so a rollback can
+   restart them. Skipped on a machine with no existing runtime.
+
+   When the run does fail closed here, end the holders it names yourself — the
+   refusal prints each surviving process by name and PID, and the dashboard is
+   the usual one — then re-run the installer.
+
+   ### Which stop verb is issued
+
+   The installer prefers `minions stop --all --wait`, and falls back to the bare
+   `minions stop` for a CLI that does not have the whole-stack verb.
+
+   A bare `minions stop` is **engine-only** by contract: it is delegated to
+   `engine.js stop`, which writes stop intent and returns, so it asks only the
+   engine to stand down. The dashboard and the supervisor hold `engine/state.db`
+   independently, so on a healthy stack the `-shm` gate above could never go
+   green after a "successful" stop and every migration was refused with the
+   engine, dashboard, and supervisor PIDs all still alive. `stop --all --wait`
+   tears the whole stack down in order and blocks until the handles are
+   released — which is why this step polls for the release instead of trusting
+   the stop.
+
+   During a public → internal migration the resolved CLI is frequently the
+   **older public package**, which predates that verb, so support is detected by
+   running `minions help` against the resolved CLI and reading whether its own
+   usage advertises `stop --all` and `--wait`. The probe is **behavioral, not a
+   version comparison** — the internal feed and the public registry version
+   independently, so there is no version ordering to compare across them, and the
+   cost of a wrong guess is an unknown flag passed to a live teardown command.
+   `help` is used rather than `stop --help` because `stop` is in the CLI's engine
+   delegation set: an older CLI would forward `stop --help` to `engine.js stop`
+   and actually stop the engine as a side effect of being asked a question.
+
+   An unreadable, empty, or unrecognized probe answer **falls back** to the
+   legacy `minions stop`. Either way the run then polls for the `-shm` release
+   itself — the CLI's own verdict is never trusted — so the fail-closed gate is
+   identical on both paths. There is no `--force` skip for it, and a stale
+   non-empty `-shm` is never accepted.
+5. **`backup-state`** — writes a consistent standalone copy of the SQLite state
+   (`engine/persistence/state-operations.js#backupState`: a best-effort
+   `PRAGMA wal_checkpoint(PASSIVE)` followed by an authoritative `VACUUM INTO`),
+   then copies `config.json`, `routing.md`, `pinned.md`, parks a
    copy of the downloaded tarball beside the backup, and writes a `manifest.json`
-   describing the from/to packages, the artifact, and the preserved paths.
+   describing the from/to packages, the artifact, the preserved paths, the
+   pinned runtime root **and how it was resolved**, whether services were
+   stopped, the pre-migration `summarizeState()` census, and the list of
+   retained artifacts.
    Skipped on a machine with no existing runtime.
-   The backup runs against the **runtime's own** `engine/state-operations.js`,
+   The checkpoint is deliberately `PASSIVE` and non-fatal: an exclusive
+   `TRUNCATE`/`RESTART` checkpoint blocks on any other reader, so with the engine
+   or dashboard connected it stalls on the busy timeout or raises `SQLITE_BUSY`
+   and would abort the backup. `VACUUM INTO` reads a snapshot that already
+   includes committed WAL frames, so it is the authoritative step and the only
+   one allowed to fail the backup. `backupState` reports
+   `{ ok, path, bytes, checkpointed, walBytesAtStart }` so callers can see
+   whether quiescence was actually achieved. The `VACUUM INTO` snapshot is the
+   authoritative backup — a bare byte-copy of a live `state.db` alone loses
+   committed-but-uncheckpointed transactions. Because the database is quiesced
+   by the previous step, the run **also** retains the ORIGINAL
+   `engine/state.db`, `engine/state.db-wal`, and `engine/state.db-shm`
+   byte-for-byte under `<backup-dir>/original/`, beside the snapshot. Those
+   bytes are what the state-restoring rollback puts back, and **the retained
+   originals — and everything else in the backup directory — are never deleted
+   by this installer, under any outcome.**
+   The backup runs against the **runtime's own** `engine/persistence/state-operations.js`,
    which `minions init` copies into the runtime root and which is therefore always
    present and version-matched to that runtime's `engine/state.db`. It does not
    depend on a globally installed CLI: `minions init` deliberately excludes `bin/`
    from the runtime-root copy, and the published public package predates the
    `minions state` command. An installed CLI's `minions state backup` is kept only
    as a fallback for runtime roots that predate the SQL store layout.
-5. **`uninstall-public`** — removes an existing global `@yemi33/minions` so the two
+6. **`uninstall-public`** — removes an existing global `@yemi33/minions` so the two
    packages never race for the same `minions` bin shim. **Gated:** it runs only
    once `assessCutoverReadiness()` confirms the internal artifact is downloaded
    (or already installed at the target version) *and* a state backup exists
    whenever there was a runtime to back up. Skipped with `--keep-public`, or when
    no public install is present.
-6. **`repair-shims`** — clears **orphaned** `minions` shims under `npm prefix -g`.
+7. **`repair-shims`** — clears **orphaned** `minions` shims under `npm prefix -g`.
    `npm uninstall -g` has just removed the shims it still owned, so anything left
    under the prefix that dispatches into `@yemi33/minions` or
    `@opg-microsoft/minions` with no usable package behind it is a leftover from a
@@ -115,7 +262,7 @@ by `test/unit/install-internal-minions.test.js`.
    directory entry as absent while npm still aborts on it. Each deletion is
    re-probed afterwards, so a delete that quietly no-ops is reported as a
    failure with its path rather than as a cleared shim.
-7. **`install-internal`** — `npm install -g <package>@<resolved-version>` against the
+8. **`install-internal`** — `npm install -g <package>@<resolved-version>` against the
    feed. **If that fails, the script installs the already-downloaded tarball**
    (`npm install -g <backup-dir>/<package>.tgz` — no registry, no token, so it
    still works when the feed is exactly what failed) rather than leaving the
@@ -125,9 +272,9 @@ by `test/unit/install-internal-minions.test.js`.
    `uninstall-public` is planned. `npm uninstall -g` takes the shim with the
    package that owns it, so skipping the install alongside an uninstall would
    remove the command with nothing to restore it.
-8. **`verify-install`** — re-reads the installed `package.json` from disk and fails
+9. **`verify-install`** — re-reads the installed `package.json` from disk and fails
    loudly if npm did not actually land the resolved version.
-9. **`verify-shim`** — resolves the global npm prefix and proves the `minions`
+10. **`verify-shim`** — resolves the global npm prefix and proves the `minions`
    command itself dispatches into the internal package (`minions.cmd` /
    `minions.ps1` / the sh shim on Windows, the `<prefix>/bin/minions` symlink
    elsewhere). Owning the package directory is not the same as owning the
@@ -136,14 +283,52 @@ by `test/unit/install-internal-minions.test.js`.
    `@yemi33/minions` is a hard failure with the repair commands printed, and so
    is a shim whose link target no longer exists — naming the right package is
    not the same as being able to run it.
-10. **`sync-init`** — `minions init --force --skip-start`, the supported runtime
+11. **`sync-init`** — `minions init --force --skip-start`, the supported runtime
     synchronization. It overwrites `.js`/`.html` runtime files and adds files the
     new version requires. `--force` would otherwise also rewrite the shipped
     `routing.md` and `knowledge/agents/*.md` with package defaults, so the
     installer snapshots those before the sync and puts them back after it.
-11. **`restart`** — `minions restart`, which is health-verified
-    (`engine/restart-health.js`: PID + HTTP probe). Skipped with `--no-restart`.
-12. **`cleanup`** — always runs, on success and on every failure path. The
+12. **`verify-continuity`** — the last gate before `cleanup`, and it runs while
+    the services are still quiesced, **before** `restart`. The preserved-path
+    check is presence-only, so an **emptied** `engine/state.db` passes it; this
+    step instead re-runs the runtime's own `summarizeState()` against the pinned
+    root, out-of-process, and feeds the pre- and post-migration censuses to its
+    `compareStateSummaries`. Running it before the restart is deliberate: a
+    census taken against a live engine races it, and `getDb()` applies pending
+    migrations on open (`engine/db/index.js`), so a quiesced pre-restart census
+    still exercises the migrations deterministically. It also bounds the blast
+    radius of the failure action — the state-restoring rollback overwrites
+    `engine/state.db{,-wal,-shm}` with the retained pre-migration bytes, which
+    after a restart would destroy every write the restarted engine and dashboard
+    had already made, including the migrations that had just succeeded.
+
+    The gate is an explicit **allowlist** of durable tables
+    (`CONTINUITY_DURABLE_TABLES`: work items, pull requests, plans, PRDs and
+    their items/verify PRs, memory records, inbox entries, QA runs and
+    sessions). Everything else is passed to `compareStateSummaries` as
+    `ignoreTables`, because most of the SQL state legitimately shrinks across a
+    cutover: `cc_sessions`/`doc_sessions` are invalidated when the
+    `prompts/cc-system.md` hash changes — which `sync-init` ships by definition —
+    `pending_rebases` is rewritten wholesale every tick, `worktree_pool`,
+    `managed_processes`, `schedule_runs`, `metrics` and friends are runtime
+    bookkeeping, `pr_mirror_hashes` is dropped outright by migration 018, and
+    `logs`/`events`/`dispatches`/`cooldowns` are capped, consumed, or expire. A
+    denylist of volatile tables fails open on every table nobody remembered to
+    enumerate; an allowlist fails closed. A durable table may declare
+    `repairedByMigration`, the schema version of a shipped repair migration that
+    deletes rows from it by design (PRD tables and migration 024) — the gate is
+    lifted for that table only on a run that actually crosses that version.
+
+    Any row-count regression, missing table, or non-empty → empty transition in a
+    gated table is a **hard failure** that triggers the state-restoring rollback
+    below. A census that cannot be *taken* is warned about loudly but is not
+    treated as proof of loss, so a healthy runtime is never rolled backward on
+    missing evidence.
+13. **`restart`** — `minions restart`, which is health-verified
+    (`engine/recovery/restart-health.js`: PID + HTTP probe). Skipped with `--no-restart`.
+    It is the final action of the run, so the machine is only brought back up on
+    state `verify-continuity` already proved survived.
+14. **`cleanup`** — always runs, on success and on every failure path. The
     temporary npm config always goes; the downloaded artifact is retained (and its
     path printed) when the run ended with the machine still needing it.
 
@@ -155,8 +340,35 @@ cannot be honoured by the install and ignored by the probe.
 
 After `sync-init` the script re-checks every runtime path that existed
 beforehand (`config.json`, `engine/state.db`, `notes/`, `notes.md`, `plans/`,
-`knowledge/`, `projects/`, `pinned.md`). A path that existed before and is
-missing after is a hard failure pointing at the backup, not a silent data loss.
+`knowledge/`, `projects/`, `pinned.md`, `pipelines/`, `prompts/`, `playbooks/`,
+`agents/`). A path that existed before and is missing after is a hard failure
+pointing at the backup, not a silent data loss. That check is presence-only by
+construction, so `verify-continuity` backs it with a row-level census; the
+artifacts that live purely in SQL (schedules, pipelines runs, watches, meetings,
+QA state) are covered by the census rather than by the path list.
+
+### State-restoring rollback
+
+`rollbackPackageIfNeeded()` is package-scoped and deliberately never touches
+state. When `verify-continuity` proves state was **lost**, a separate
+state-restoring rollback runs — it is only ever reached once the retained
+original bytes are known to be strictly better than what is on disk. It:
+
+1. quiesces services again — through the same probed stop path and the same
+   `-shm` gate as `quiesce-services`, aborting without restoring anything if the
+   database is still held (so the backup stays intact and nothing is written into
+   a live database), and reporting the stop path and holding PIDs the same way,
+2. restores `engine/state.db`, `engine/state.db-wal`, and `engine/state.db-shm`
+   from `<backup-dir>/original/`,
+3. restores `config.json`, `routing.md`, and `pinned.md` from the backup, and
+   restores the reseedable snapshot through the **same** `restoreReseededFiles`
+   copier the normal `sync-init` repair uses,
+4. reinstalls the previous package, restarts, and **re-verifies** the census
+   against the pre-migration one,
+5. reports precisely what was restored, removed, or failed.
+
+Every step re-copies the same retained bytes, so a re-run converges rather than
+compounding: the rollback is idempotent.
 
 ## What this is not
 
@@ -173,7 +385,7 @@ and a re-run:
 
 | State | Preserved how |
 |---|---|
-| `engine/state.db` — work items, dispatches, PR records, schedules, pipelines, watches, meetings, PRDs, QA state, small state | Never replaced. Checkpointed to the backup directory (`PRAGMA wal_checkpoint(TRUNCATE)` + `VACUUM INTO`) before the package changes; the **live** database stays in place and the new version runs its own idempotent startup migrations against it. |
+| `engine/state.db` — work items, dispatches, PR records, schedules, pipelines, watches, meetings, PRDs, QA state, small state | Never replaced. Services are quiesced first, then the state is checkpointed into the backup directory (`PRAGMA wal_checkpoint(PASSIVE)` + `VACUUM INTO`) and the original `state.db`/`-wal`/`-shm` bytes are retained under `<backup-dir>/original/` before the package changes; the **live** database stays in place and the new version runs its own idempotent startup migrations against it. A row-level census taken before and after proves nothing was lost, and restores from the retained originals if it was. |
 | `config.json` | `minions init` never overwrites it (`neverOverwrite` in `bin/minions.js`), and it is copied into the backup directory as well. |
 | `routing.md`, `knowledge/agents/*.md` | Shipped by the package, so `init --force` *would* rewrite them. Snapshotted before `sync-init` and restored byte-for-byte after it. |
 | `notes.md`, `notes/`, `pinned.md`, `plans/`, `prd/`, `projects/`, `agents/` | Not shipped by the package, so the sync never touches them. Existence is re-verified after the sync. |
@@ -206,7 +418,7 @@ it does **not** cover rewriting the files underneath a live dispatch.
 
 So the script counts live agent PID files under `<runtime root>/engine/tmp/`
 (both the per-dispatch directory layout and the legacy flat layout, matching
-`engine/shared.js#forEachPidFile`) and **defers with exit code 3** when any are
+`engine/core/shared.js#forEachPidFile`) and **defers with exit code 3** when any are
 alive. Stale PID files from a crashed run do not block anything — each PID is
 liveness-checked.
 
@@ -236,31 +448,118 @@ installed: it resolves the active package name from the installed manifest and
 reinstalls *that* package, so an internal install upgrades itself instead of
 pulling in the public one.
 
-It does **not** configure a registry. `minions update` shells out to plain
-`npm view <pkg> version` / `npm install -g <pkg>@<version>`
-(`engine/shared.js#buildNpmViewVersionCommand` / `#buildNpmGlobalInstallCommand`),
-so on the internal channel it only reaches `ProjectFeed-ISS` when your **own**
-npm configuration already has a persistent scoped registry entry and credentials
-for the feed — for example `@opg-microsoft:registry=<base feed URL>` in your user
-`.npmrc`. This script's npm config is deliberately temporary and is deleted after
-every run, so it leaves nothing behind for `minions update` to reuse.
-
-Re-running this script is therefore the upgrade path that always works: it
-acquires its own short-lived token per run and is idempotent. It is also the
-**channel bootstrap** — what moves a machine onto the internal ProjectFeed-ISS
-channel (including replacing a public `@yemi33/minions` install) and what installs
-the internal package on a machine that has no Minions at all.
+### The runtime root is the channel authority
+
+The manifest at `PKG_ROOT` only answers *which package an install would pull* —
+it is **not** proof of which channel the runtime is on. It resolves the public
+`@yemi33/minions` both from an opg repo checkout (whose own `package.json`
+carries that name) and from a leftover public global shim standing in front of an
+internal runtime. Either way an unguarded update would drop a stale public build
+on top of a newer internal runtime.
+
+So the **runtime root** decides. `minions init` records the installing
+distribution in `<runtime root>/.minions-package`
+(`{ name, version, installedAt }`), and `minions update` gates on it via
+`shared.resolveUpdateChannel({ pkgRoot, runtimeRoot })`
+(`engine/core/shared.js`):
+
+| Runtime marker | Update would install | Behavior |
+|---|---|---|
+| `@opg-microsoft/minions` | `@opg-microsoft/minions` | Proceeds (in-channel upgrade) |
+| `@yemi33/minions` | `@yemi33/minions` | Proceeds (in-channel upgrade) |
+| internal (any non-public scope) | `@yemi33/minions` | **REFUSED before any npm call**, exit 1 |
+| `@yemi33/minions` | internal | Proceeds, warns (legitimate cutover) |
+| *(no marker — legacy root)* | anything | Proceeds, warns naming both channels |
+
+The refusal never attempts a public downgrade and never reaches the registry. It
+prints the supported remediation — this installer, with the runtime root pinned:
+
+```
+scripts\install-internal-minions.ps1 --runtime-root "<runtime root>" --package @opg-microsoft/minions
+./scripts/install-internal-minions.sh --runtime-root "<runtime root>" --package @opg-microsoft/minions
+node bin/install-internal-minions.js --runtime-root "<runtime root>" --package @opg-microsoft/minions
+```
+
+There is deliberately **no override flag** for a cross-channel public install: a
+public build is a different distribution of the same `minions` bin, not an older
+version of the internal one. Re-run this installer instead.
+
+### Downgrade guard
+
+Within a single channel, `minions update` also refuses a target version that is
+semver-lower than the installed one, because `npm view` can resolve *backwards*
+off a stale local packument — the install then succeeds and the post-install
+version-advance check still passes, while the runtime silently moves to an older
+build. The comparison is numeric (`1.0.9` is not newer than `1.0.76`).
+
+```
+minions update                     # refuses a lower target version
+minions update --allow-downgrade   # installs it anyway
+```
+
+The refusal points at `npm cache clean --force`, which is the usual fix.
+
+### Registry configuration
+
+On the **internal channel**, `minions update` resolves and installs from this
+feed itself — it does **not** rely on your own npm configuration, and it leaves
+nothing persistent behind. When the installed package is served by a private
+feed (`bin/install-internal-minions.js#resolveInternalFeed`; today
+`@opg-microsoft/minions` → the ISS `ProjectFeed-ISS` base registry), the update:
+
+1. acquires a **short-lived** Azure DevOps token through your existing Azure CLI
+   login (`az account get-access-token`) — no PAT, never in argv, logs, or errors;
+2. stages it in a **0600 temporary npm userconfig** in the OS temp dir, which is
+   deleted on success and on every failure path (including a non-zero exit);
+3. runs `npm view` / `npm install -g` against the feed with the scoped registry
+   **pinned on the command line** (`--@opg-microsoft:registry=<feed>`).
+
+Step 3 is what makes the route deterministic. npm resolves a *scoped* package
+through `@scope:registry`, and `--registry` only sets the *default* registry — so
+an ambient `@opg-microsoft:registry=<public proxy>` line silently redirected the
+update and npm answered `E404` for a package that exists in the feed. npm's
+precedence is `cli > env > ./.npmrc > --userconfig > global`, so a `.npmrc` in
+your current directory also outranks the temporary userconfig; only the
+command-line pin is authoritative. Feed failures now report the feed that was
+queried plus the two real causes (Azure CLI sign-in, or Azure Artifacts read
+permission / a version that is not published) instead of a public-registry 404.
+
+`--registry <url>` overrides the feed for one run and is accepted only on an
+internal channel. The **public** channel is untouched: `@yemi33/minions` still
+updates through plain `npm view` / `npm install -g`
+(`engine/core/shared.js#buildNpmViewVersionCommand` / `#buildNpmGlobalInstallCommand`)
+against whatever registry your npm config points at.
+
+```
+minions update                                # internal: feed + Azure CLI auth, public: plain npm
+minions update --registry <url>               # internal only: override the feed for this run
+```
+
+Re-running this script remains the **channel bootstrap** — what moves a machine
+onto the internal ProjectFeed-ISS channel (including replacing a public
+`@yemi33/minions` install), what installs the internal package on a machine that
+has no Minions at all, and what repairs a half-finished cutover. It is
+idempotent, so it always works as a recovery path; routine in-channel upgrades no
+longer need it.
 
 ## Troubleshooting
 
 | Symptom | Cause | Fix |
 |---|---|---|
+| `REFUSED: this would install the public package over an internal runtime` | `minions update` resolved `@yemi33/minions` (repo checkout, or a leftover public global shim) while `<runtime root>/.minions-package` says the runtime is internal | Nothing was installed and the registry was never contacted. Re-run this installer with the printed `--runtime-root "<path>" --package <internal pkg>`. |
+| `REFUSED: … would downgrade the installed …` | `npm view` resolved an older version off a stale local packument | `npm cache clean --force`, then `minions update`. To install the older version deliberately: `minions update --allow-downgrade`. |
+| `Runtime channel is unknown (no .minions-package marker)` | Legacy runtime root that predates the channel marker | Warning only — the update proceeds as before. Run `minions init` to record the channel. |
 | `could not acquire an Azure DevOps token` | Not signed in, or no subscription selected | `az login`, then `az account set --subscription <id>` |
+| `Could not acquire an Azure DevOps token for the internal feed` (from `minions update`) | Same cause, raised by the in-place updater before any npm call | `az login`, then re-run `minions update`. Nothing was installed and no credential was written. |
+| `Could not read <pkg>@latest from the internal feed` (from `minions update`) | No Azure Artifacts read access to `ProjectFeed-ISS`, or that version is not published to the feed | Request read on `ProjectFeed-ISS`. This replaces the old misleading public-registry `E404`: the update pins the feed on the command line, so it is never the ambient registry answering. |
+| `--registry applies only to an internal channel install` | `minions update --registry <url>` on a public install | Drop the flag; the public channel updates through your own npm registry. |
 | `could not read <pkg>@<spec> from the feed` | No feed read permission, or the version does not exist | Request Azure Artifacts read on `ProjectFeed-ISS`; check `--version`. Nothing was uninstalled. |
 | `REFUSED: N agent process(es) are still running` | Active dispatches | Wait for idle, or re-run with `--force` |
+| `REFUSED: the runtime did not release engine/state.db` | A daemon still holds the WAL — usually the dashboard, which `minions stop` leaves running by design | Nothing was uninstalled or modified. Run `minions stop`, then end whatever the error still names — it prints every surviving holder by name and PID — and re-run. |
+| `REFUSED: N candidate runtime roots carry a non-empty engine/state.db` | More than one directory the engine could boot from holds real state — typically `~/.minions` plus a Minions source checkout you launched the installer from | Nothing was downloaded, uninstalled, or modified. The message names every candidate and prints the exact `--runtime-root <path>` command for each; re-run pinned to the one you mean. See [Runtime root](#runtime-root). |
 | `expected <pkg>@<v> on disk, found …` | Stale npm metadata cache | `npm cache clean --force`, then re-run |
 | `refusing to uninstall @yemi33/minions — …` | The artifact or the backup is missing | Nothing was removed. Re-run; the message names which precondition failed. |
-| `no way to back up the existing runtime state was found` | The runtime root has neither `engine/state-operations.js` nor a resolvable CLI | Nothing was uninstalled. The error lists every path that was probed; run `minions init --force` against the existing install to restore its engine files, then re-run. |
+| `no way to back up the existing runtime state was found` | The runtime root has neither `engine/persistence/state-operations.js` nor a resolvable CLI | Nothing was uninstalled. The error lists every path that was probed; run `minions init --force` against the existing install to restore its engine files, then re-run. |
 | `the minions shim … still points at @yemi33/minions` | A previous half-finished cutover left the public shim in place | `npm uninstall -g @yemi33/minions`, then re-run. The install commands are printed with the error. |
 | `npm ERR! EEXIST … <prefix>\minions` on `npm install -g` | **Orphaned shim** — a prior uninstall or interrupted migration removed the package directory but left the `minions` command behind, so nothing reported the old package as installed and npm refused to overwrite the leftover. | Handled automatically by `repair-shims`: just re-run the installer. Details below. |
 | `REFUSED: … is named minions but was not generated by npm for …` | A file called `minions` under `npm prefix -g` could not be attributed to `@yemi33/minions` or `@opg-microsoft/minions` | The installer never deletes a file it cannot prove it owns. Inspect the named path, move or rename it (or remove it yourself if it is a leftover), then re-run. Nothing was modified. |

package/docs/kb-dedup-duplicate-pair-investigation.md

@@ -6,7 +6,7 @@ distinct events sharing a naming pattern, before any fix is proposed.
 
 ## Background
 
-`engine/consolidation.js:1156-1290` content-hashes and dedups
+`engine/memory/consolidation.js:1156-1290` content-hashes and dedups
 engine-authored SYSTEM ALERTS (via `shared.isEngineSystemAlert` +
 `alertHash` frontmatter, see `_alertHashExists`) at **write time** —
 recurring identical alerts never get a `-2`/`-3` full-body copy. Agent-authored
@@ -16,7 +16,7 @@ so any note that gets classified into `knowledge/<category>/` twice under the
 same computed filename (`${date}-${agent}-${titleSlug}.md`) always produces a
 full-body `-2`/`-3` copy at consolidation time.
 
-Separately, `engine/kb-sweep.js` Pass 1 (`_hashDedup`, `kb-sweep.js:34-37,
+Separately, `engine/memory/kb-sweep.js` Pass 1 (`_hashDedup`, `kb-sweep.js:34-37,
 155-176`) content-hashes **every** KB entry regardless of category and
 archives byte-identical duplicates to `knowledge/_swept/`, keeping the most
 recent. This pass is category-agnostic and *would* catch true agent-authored
@@ -98,7 +98,7 @@ last-completed-sweep timestamp).
    inbox note that hashes/formats similarly — or, per the `-2`/`-3`
    evidence above, the identical inbox note re-processed), each pass
    writes a fresh, full-body `-N` copy via `shared.uniquePath`.
-2. `engine/kb-sweep.js` Pass 1 (`_hashDedup`) *does* eventually catch and
+2. `engine/memory/kb-sweep.js` Pass 1 (`_hashDedup`) *does* eventually catch and
    archive these byte-identical copies (category-agnostic, keeps most
    recent) — but only on its own schedule (`AUTO_SWEEP_INTERVAL_MS = 4h`
    default, `kb-sweep.js:26`) or on manual trigger, not at consolidation
@@ -128,9 +128,9 @@ similarity, since many genuinely distinct events share a title stem.
 
 ## Sources
 
-- `engine/consolidation.js:1156-1300` (`isEngineSystemAlert`/`alertHash`
+- `engine/memory/consolidation.js:1156-1300` (`isEngineSystemAlert`/`alertHash`
   dedup, `classifyToKnowledgeBase`)
-- `engine/kb-sweep.js:20-37,155-176` (`_hashEntry`, `_hashDedup`, sweep
+- `engine/memory/kb-sweep.js:20-37,155-176` (`_hashEntry`, `_hashDedup`, sweep
   interval constant)
 - `engine/kb-sweep-state.json` (`completedAtIso: 2026-07-07T21:49:00.186Z`)
 - `knowledge/reviews/2026-07-07-ripley-review-github-opg-microsoft-minions-740-fix-contam{,-2,-3}.md`

package/docs/kb-pr3223-cascade-archiving.md

@@ -8,7 +8,7 @@
 
 - `source_plan` is a plan Markdown basename.
 - Plan archive responses retain their documented compatibility fields.
-- PRD archive and cascade updates use `engine/prd-store.js` transactions.
+- PRD archive and cascade updates use `engine/planning/prd-store.js` transactions.
 - Work-item cancellation uses scoped SQL work-item mutations.
 
 Use the current `handlePlansArchive` implementation and its behavioral tests as

package/docs/kb-pr696-merge-conflict-docs.md

@@ -1,15 +1,15 @@
 # KB PR #696 – Merge Conflict Resolution in KB-Sweep Documentation
 
-PR #696 resolved a merge conflict in `docs/kb-sweep.md:97-103` where both branch and main branches cited stale line numbers to `engine/kb-sweep.js`. Upstream code shifts had invalidated both references. Resolution consolidated the "Pass 1, 1.5, and 2" structure and verified the correct current location of `NORMALIZE_CONCURRENCY = 5` at `engine/kb-sweep.js:30`.
+PR #696 resolved a merge conflict in `docs/kb-sweep.md:97-103` where both branch and main branches cited stale line numbers to `engine/memory/kb-sweep.js`. Upstream code shifts had invalidated both references. Resolution consolidated the "Pass 1, 1.5, and 2" structure and verified the correct current location of `NORMALIZE_CONCURRENCY = 5` at `engine/memory/kb-sweep.js:30`.
 
 ## Key Findings
 
 - Merge conflict in `docs/kb-sweep.md:97-103` ("Pass 3 — Per-Entry Rewrite" section) with stale line citations
-- Branch cited `engine/kb-sweep.js:L26`, main cited `L30` with outdated "Pass 1 and 2" wording
+- Branch cited `engine/memory/kb-sweep.js:L26`, main cited `L30` with outdated "Pass 1 and 2" wording
 - Root cause: upstream commits shifted line numbers; neither reference remained valid post-merge
-- Resolved by merging branch's "Pass 1, 1.5, and 2" structure with main's corrected line reference to `engine/kb-sweep.js:30`
-- Verified `NORMALIZE_CONCURRENCY = 5` present at `engine/kb-sweep.js:30` in merged state
-- Syntax validation passed for `engine/shared.js`, `engine/kb-sweep.js`, `engine.js`, `dashboard.js`
+- Resolved by merging branch's "Pass 1, 1.5, and 2" structure with main's corrected line reference to `engine/memory/kb-sweep.js:30`
+- Verified `NORMALIZE_CONCURRENCY = 5` present at `engine/memory/kb-sweep.js:30` in merged state
+- Syntax validation passed for `engine/core/shared.js`, `engine/memory/kb-sweep.js`, `engine.js`, `dashboard.js`
 
 ## Action Items
 
@@ -20,4 +20,4 @@ PR #696 resolved a merge conflict in `docs/kb-sweep.md:97-103` where both branch
 - PR #696: https://github.com/opg-microsoft/minions/pull/696
 - Merge commit: b91cb386
 - Fix comment: https://github.com/opg-microsoft/minions/pull/696#issuecomment-4905945906
-- Correct citation: `engine/kb-sweep.js:30` (`NORMALIZE_CONCURRENCY = 5`)
+- Correct citation: `engine/memory/kb-sweep.js:30` (`NORMALIZE_CONCURRENCY = 5`)