@azure-id/orc 0.55.2 → 0.56.1

package/README.md

@@ -7,14 +7,14 @@
 *Intake → analyze → plan → score → parallel subagents → review → verify → ship.*
 
 ![npm](https://img.shields.io/npm/v/%40azure-id%2Forc?style=for-the-badge&color=cb3837&logo=npm)
-![Version](https://img.shields.io/badge/version-0.55.2-blue.svg?style=for-the-badge)
+![Version](https://img.shields.io/badge/version-0.56.0-blue.svg?style=for-the-badge)
 ![License](https://img.shields.io/badge/license-MIT-green.svg?style=for-the-badge)
 ![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg?style=for-the-badge)
 ![Claude Code](https://img.shields.io/badge/Claude_Code-Skills-purple.svg?style=for-the-badge)
 ![Dependencies](https://img.shields.io/badge/dependencies-zero-lightgrey.svg?style=for-the-badge)
 ![GitHub stars](https://img.shields.io/github/stars/azure-id/orc?style=for-the-badge&color=yellow)
 
-**Latest: v0.55.2** · updated 2026-08-27 · [full changelog](CHANGELOG.md)
+**Latest: v0.56.1** · updated 2026-08-28 · [full changelog](CHANGELOG.md)
 
 **On npm: [`@azure-id/orc`](https://www.npmjs.com/package/@azure-id/orc)** — `npm i -g @azure-id/orc`
 
@@ -24,6 +24,38 @@
 
 ---
 
+> [!CAUTION]
+> **Upgrading from a version before v0.56.0? Do this once.**
+>
+> The package moved from the unscoped `orc` to **`@azure-id/orc`**. Both declare
+> the same `orc` command, and npm will not hand that command to the new package
+> while the old one still holds it — so **every** install source fails with the
+> same error, and `orc upgrade` cannot fix itself:
+>
+> ```text
+> npm error code EEXIST
+> npm error File exists: C:\Users\you\AppData\Roaming\npm\orc
+> ```
+>
+> Run these two lines once. Nothing in your `.claude/` is touched, and your
+> `orc.config.yaml` survives:
+>
+> ```bash
+> npm uninstall -g orc          # release the `orc` command from the old package
+> npm i -g @azure-id/orc        # install the current one
+> orc update                    # re-apply into this project (add --global for ~/.claude)
+> ```
+>
+> **From v0.56.0 onward `orc upgrade` handles this for you** — it removes the old
+> package first, then installs, and says so while it does it. `orc doctor` also
+> reports the old package by name if it is still there.
+>
+> Do **not** reach for `npm i -g -f`. `--force` overwrites the command file and
+> leaves the superseded package installed underneath, owning nothing and never
+> updated again.
+
+---
+
 > [!IMPORTANT]
 > **`orc-open` is released — ORC for non-Claude agents.**
 > A provider-agnostic port of the pipeline:
@@ -178,8 +210,11 @@ You do not have to run a command to hear about it: the same notice appears
 inside Claude Code through ORC's hooks, at **zero model tokens** — hooks are
 scripts Claude Code runs, not model turns.
 
-If the GitHub spec fails to install (common under **NVM**), `orc upgrade` retries
-with a plain tarball by itself.
+`orc upgrade` tries the npm registry first, then a plain tarball, then the
+GitHub spec — and it remembers which one worked. If the old unscoped `orc`
+package is still installed, it removes that first (announced), because npm
+cannot give the `orc` command to `@azure-id/orc` while another package owns it.
+See the caution at the top of this README for the one-time manual version.
 
 </details>
 
@@ -324,6 +359,8 @@ orc ui --stop          # shut this project's server down
 | Crosslink | **Design** (the boundary as a graph) and **Settings** (each peer's freshness) | `crosslink add` / `remove` |
 | Promises · Boundary · Self-serve | the pact ledger, the boundary cards, and the surfaces a non-developer can change | `pact check`, `pact sync`, `handoff set` |
 | **Docs** | every `/orc-doc` document as a **ribbon** — one block per section, sized by its length and coloured by its state — plus the section files with their sub-parts, the wave strip, the lint health card and the wave preview | `doc compile` · `doc migrate` |
+| **Extra** | **six tabs**: the connection setup, the local tools and their state, the band ladder and the six positions, spending per profile per band, and **Recovery** — every dispatch that never reported back, with what it left on disk | `extra add` / `ping` / `route` / `role` |
+| **Challenge** | every `/orc-challenge` cycle: the frozen goal, the council roster and what each lens raised, the findings with their dispositions, and whether the pass is computed or blocked | `challenge record` · `accept` · `rebut` |
 | **Mocked Skill Use** | every mocked run that ships with ORC, grouped and searchable, with a reading pane | — |
 | Learn | the `orc onboarding` walkthrough, one section at a time | — |
 | Experiment | every lane with a copy button; opens a Claude session in a terminal | — |
@@ -349,6 +386,77 @@ CSS.
 
 ---
 
+## Running part of the ladder somewhere else — `orc extra`
+
+**The orchestrator is always Claude.** What Extra changes is *who executes a
+slice*: a score band you own, or one of six named positions, can point at
+DeepSeek, GLM, Kimi, MiniMax, Qwen, a local Ollama, or a coding CLI you already
+have signed in (opencode, codex). Everything downstream — the smoke gate, the TDD
+gate, the reviewer, the worktree-delta check — is engine-blind, so nothing learns
+the work was foreign.
+
+**Off by default, and it cannot be armed until something has actually answered.**
+
+```bash
+orc extra providers              # the shipped, dated catalog — providers, never models
+orc extra tools                  # local CLIs: absent · outdated · unauthenticated · ready
+orc extra add ds --provider deepseek --engine api --env-key DEEPSEEK_API_KEY
+orc extra ping ds                # the connection gate: a ladder, and nothing reads stronger than it is
+orc extra models ds --test <id>  # a LISTED model can still be dead upstream
+orc extra health ds --model <id> # …and a working model is not one that FINISHES
+orc extra route set 40-55 ds/deepseek-chat     # a score band
+orc extra role set doc-writer ds/deepseek-chat # or a named position
+orc config set extra_enabled true
+```
+
+- **The catalog ships providers and never models.** A shipped model id is wrong
+  within a quarter and wrong *silently* — a 404 mid-wave. `orc extra ping` reads
+  the live list and caches it; nothing invents a name. Same for price: a cost
+  figure ORC did not price itself is never printed, it reads as an em dash.
+- **Every armed run says so before wave 1.** Routing work off Claude silently is
+  the failure this whole subsystem is shaped around.
+- **Two hard hold-backs**: a task with a cited `risk[]` (auth, money, migration,
+  security, concurrency, data-integrity) stays on Claude unless you say
+  otherwise, and a `/orc-boundary` REFUSE area holds even in `warn`.
+- **A foreign return is foreign input.** It is the only foreign class that edits
+  your worktree, so what it says it did is a *claim*, checked against the tree.
+- **Your key never reaches a command line.** It travels on stdin into an
+  encrypted vault, or it stays in an environment variable, or the tool holds its
+  own — and the passphrase is a **deadline**, not a second factor.
+- **Six positions for the lanes that pin an agent instead of scoring a task**:
+  `quick-executor` · `fast-executor` · `doc-writer` · `doc-checker` ·
+  `wiki-scanner-deep` · `wiki-scanner-light`. A position with no row keeps its
+  slot and reads as its pinned Claude agent — "I left the checker on Claude on
+  purpose" and "there is no checker" must never look the same.
+
+**When a foreign worker fails, it is a position and not a blank page.** ORC
+journals the baseline *before the first byte leaves the machine*, so a worker cut
+off mid-write is **reconciled and resumed** — never re-dispatched from scratch
+onto a file that is already two-thirds written.
+
+- **`extra_stall_s` (default 180)** stops a worker that has produced nothing for
+  that long. It is reset by observable progress — the worker's stream, its
+  stderr, or a declared file that changed on disk — so it never fires on one that
+  is merely slow. `stalled` is retryable, which is what makes the resume ORC's
+  own spelling of typing `continue`.
+- **`extra_fallback_agent` (default `band`)** decides who picks the task up.
+  `ask` stops and puts the menu to you; any installed agent name pins one. It
+  changes *who*, never the score, the declared files or the acceptance criteria.
+- **Every dispatch writes its own spend record**, so a cost report never depends
+  on a run remembering to narrate what it spent. `orc extra stats` merges the
+  spend log, the traces and saved returns, and always says how many rows came
+  from each.
+
+**`/orc-quick` is inert here** and announces it — that lane asks which agent
+before every dispatch, so no setting may pre-answer it. **`/orc-challenge` never
+routes foreign**: swapping a lens for a different model does not make the lane
+cheaper, it changes what is being measured.
+
+**The whole subsystem, with every command and key:
+[guides/extra-models.md](guides/extra-models.md).**
+
+---
+
 ## How the model is picked
 
 Each task is scored 0–100 by **arithmetic, not judgement**: the planner reports
@@ -389,12 +497,13 @@ clobbers. `orc ui` ▸ Settings edits the same keys through the same validators.
 
 ```
 templates/
-├── skills/       29 skills — the lanes above, plus the ones with no command of
-│                 their own: context-combiner, orc-advisor, orc-judge,
-│                 orc-analyze-mini, and _shared/ (cross-lane contract prose)
-├── commands/     27 slash commands
+├── skills/       31 skill folders, 38 SKILL.md files (a lane may ship subskills) —
+│                 the lanes above, plus the ones with no command of their own:
+│                 context-combiner, orc-advisor, orc-judge, orc-analyze-mini,
+│                 and _shared/ (cross-lane contract prose)
+├── commands/     29 slash commands
 ├── hooks/        effort guard (PreToolUse) · statusline warning · behavior trace
-└── agents/       40 model-pinned subagents + MODEL-MAPPING.md
+└── agents/       51 model-pinned subagents + MODEL-MAPPING.md
 bin/cli.js        installer, config editor, flow composer, run-state reader, and
                   the deterministic half of every lane. Every read speaks --json
 bin/webui/        `orc ui` — the local control panel: css/ + js/ + i18n/<lang>/ +
@@ -465,6 +574,76 @@ a current audit: [EVAL-REPORT.md](EVAL-REPORT.md).
 **Full history: [CHANGELOG.md](CHANGELOG.md)** — or `orc changelog`, which prints
 only what is newer than the version you have.
 
+### v0.56.1 - a worker that is alive and doing nothing _(2026-08-28)_
+
+**Still on the unscoped `orc` package?** Do this once before anything else -
+your `orc upgrade` is the pre-v0.56.0 one and it cannot install itself:
+
+- **Step 1 - release the command from the old package:** `npm uninstall -g orc`
+- **Step 2 - install the current package:** `npm i -g @azure-id/orc`
+- **Step 3 - re-apply it to your project:** `orc update`
+
+**Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
+
+**An opencode dispatch that goes quiet mid-task used to burn the whole
+fifteen-minute wall clock and then report `timeout`.** That word is a statement
+about ORC's patience and reads as a budget somebody should raise. It was a
+POSITION somebody should resume from.
+
+- **`extra_stall_s` (default 180, `0` disables)** stops a foreign worker that
+  has produced NOTHING for that long. Reset by observable progress - the
+  worker's stream, its stderr, or a declared file that changed on disk - so it
+  never fires on a worker that is merely slow. Engine `cli` only.
+- **`stalled` is its own failure class and it is RETRYABLE**, so
+  `orc extra reconcile` reads the position and `extra_resume` continues from
+  what is on disk instead of starting over. That is ORC's spelling of typing
+  `continue`. There is deliberately no stdin nudge: `opencode run` is not an
+  interactive session, so a keystroke nobody reads would be a fake fix.
+- **Every engine-`cli` return carries a `timeline`** - first byte, last
+  progress, longest quiet gap, both budgets - on success as well as failure.
+- **`orc extra health <profile> [--model <id>]`** answers "does this model
+  stall", through the SAME watchdog a dispatch uses. A listed model is not a
+  working model, and a working model is not a model that finishes.
+- **`extra_fallback_agent` (default `band`)** decides who picks the task up.
+  `ask` STOPS and puts the menu to you; any installed agent name pins one. Under
+  `ask` the lane does not choose. It changes WHO, never the score, the declared
+  files or the acceptance criteria. INERT in `/orc-quick`.
+
+### v0.56.0 - a rename moved the command, and nobody could reach the fix _(2026-08-27)_
+
+**READ THIS FIRST IF YOUR `orc upgrade` IS FAILING.** On a version before
+v0.56.0, this release cannot install itself - your `orc upgrade` is the OLD one.
+Run these three lines once, by hand:
+
+- **Step 1 - release the command from the old package:** `npm uninstall -g orc`
+- **Step 2 - install the current package:** `npm i -g @azure-id/orc`
+- **Step 3 - re-apply it to your project:** `orc update` (add `--global` to also
+  refresh `~/.claude`)
+
+Then `orc version` should print 0.56.0 or newer. Your `.claude/` and your
+`orc.config.yaml` are untouched. **Do not use `npm i -g -f`.**
+
+**The package moved from the unscoped `orc` to `@azure-id/orc`, and every
+upgrade path in the field died at once.** Both names declare the same `orc` bin,
+and npm will not link it for the new package while the old one owns it - so the
+tarball, the `github:` spec and the registry all failed with the same `EEXIST`
+on the command file. It is a FILE conflict, not a source problem, which is why
+changing sources never helped and `npm i -g -f` was the only thing that worked.
+
+- **`orc upgrade` evicts the legacy package BEFORE trying any source**, because
+  the collision fails every source identically. Announced, never silent.
+  Detection is by OWNERSHIP - a package that does not declare the `orc` bin is
+  never touched.
+- **The npm registry is tried first**, then the tarball, then the `github:` spec.
+  `freshCliPath()` now resolves the SCOPED directory, so step 2 stops re-applying
+  the templates step 1 just superseded.
+- **`--force` is kept for the one case it fits** - an orphaned command file no
+  package owns - and never for an unrelated `EEXIST`.
+- **`orc doctor` reports `legacy-global-package` by name.** Not `--fix`-able on
+  purpose: `--fix` is scoped to this project's `.claude/`.
+- **A CAUTION at the top of this README** carries the one-time manual fix, since
+  anyone still on the old package does not have this code yet.
+
 ### v0.55.2 - a gate that is never probed is a gate that is always off _(2026-08-27)_
 
 **`/orc-quick` and `/orc-fast` documented the foreign-worker option and then