@azure-id/orc 0.55.0

package/mock-run/extra-recovery.md

@@ -0,0 +1,330 @@
+# Mock run — when a different AI model stops half-way
+
+> A worker on another model wrote most of a file and then lost its connection.
+> ORC can tell you exactly what it left behind, whose fault it was, and hand the
+> rest to somebody who continues instead of starting again.
+
+---
+
+## 1. What this is about
+
+You told ORC that small tasks may run on a cheaper model — DeepSeek, GLM, Kimi,
+a model on your own laptop. That is `orc extra`, and it works.
+
+Then one of those workers stops in the middle. The wifi drops. The provider
+returns an error. The laptop sleeps. You close the terminal.
+
+**The worker has already changed files on your disk.** It wrote five of six
+lines and never wrote the sixth. Nothing warns you, and the build may even still
+pass, because the file it half-wrote is not wired up yet.
+
+Before ORC 0.54.0, ORC sent the same task again from the start — to a Claude
+worker this time — as if nothing had happened. That new worker arrives at a file
+that is already two-thirds written and has three bad choices:
+
+- write the file again, and throw away work you already paid for;
+- edit a file it thinks it knows and get it wrong, because its idea of the file
+  is out of date;
+- read the file first and then guess whether what is there is good work, an
+  old attempt, or rubbish. It has no way to tell.
+
+This release removes that. **A failed dispatch is a position, not a blank page.**
+
+---
+
+## 2. The story
+
+You run a normal build. One task goes to your DeepSeek connection.
+
+```
+/orc
+```
+
+```
+  extra: [0,40) → dipkshit/deepseek-v4-flash via api
+  wave 1 · 3 tasks
+```
+
+Task `T-2` has to add a health route. The worker starts. It writes
+`src/routes/health.js`. Then your wifi drops.
+
+```
+  ❌ dipkshit/deepseek-v4-flash — connection-lost-local:
+     the connection was established and then died mid-response
+```
+
+ORC stops and tells you what it found.
+
+---
+
+## 3. What ORC knows, and why it knows it
+
+Before that dispatch sent a single byte, ORC wrote down what your repository
+looked like. Not the whole repository — only the files that task was allowed to
+touch, plus the list of everything git already saw as changed.
+
+That record is called the **journal**. It lives in
+`.claude/orc/extra-journal/T-2/`.
+
+**ORC writes it itself, while the dispatch runs.** It is not something the run
+remembers to do at the end. This matters: if the process is killed, there is no
+end. The record is already on disk.
+
+Now ask what happened. This read is **free** — no model, no tokens:
+
+```
+orc extra reconcile T-2
+```
+
+```
+  T-2 · attempt 1 of 1 — RESUMABLE
+  the worktree moved off the baseline — there is a position
+  dipkshit/deepseek-v4-flash · engine api · band [0,40)
+  ended: failed · connection-lost-local (retryable)
+
+  attributed: NETWORK
+  the connection to deepseek failed, and an UNAUTHENTICATED probe of
+  https://api.deepseek.com/v1/models also failed inside 3s. That points at this
+  machine's network, not at the provider.
+    · 3 turn(s) completed
+    · 1 file(s) were written before it stopped
+    · network probe: ECONNREFUSED after 3000ms
+  ⚠ a Claude fallback would fail too — falling back here burns a second failure
+    and a second cost for nothing.
+
+  the position:
+    src/routes/health.js — created (+7 −0)
+    src/app.js — untouched
+  last action: turn 4 of 12 · Write src/routes/health.js · ok
+  fidelity: per-turn — every turn and every tool call was recorded as it happened.
+  tokens so far: 8140/0/0/512 — read from the journal's per-turn vector. It is a
+  FLOOR — the true total may be higher, because the dispatch died before it
+  could report.
+
+  acceptance (carried forward, UNEVALUATED):
+    · GET /health returns 200 {status:'ok'}
+
+  resume target: hold
+  attributed to this machine's NETWORK. A Claude fallback would fail too, so
+  hold the wave and say why — do not spend a second failure finding that out.
+```
+
+Read that last part again, because it is the point of the whole release.
+
+**ORC did not send the task to Claude.** Your internet is down. A Claude worker
+would fail for exactly the same reason, and you would have paid for two failures
+instead of one. So ORC stopped and told you what to fix.
+
+---
+
+## 4. Whose fault was it
+
+This is a real question with a real answer, and each answer means something
+different for what you do next.
+
+| verdict | what it means | what you do |
+|---|---|---|
+| `provider` | the other company's endpoint answered, and said no | send the task to Claude instead — that works |
+| `network` | your machine could not reach anything | fix your connection; nothing else will work |
+| `local` | something on this computer — a missing program, a disk error | fix it here |
+| `worker` | the conversation was fine and the model ran out of turns or gave up | the task was too big for that band |
+| `orc` | ORC built a request the endpoint refused | **an ORC bug**, and ORC says so |
+
+ORC tells `provider` and `network` apart by making **one cheap request with no
+key attached**, with a three-second limit. If that request gets any answer at
+all — even a "wrong key" answer — the network is fine and the problem is the
+endpoint. If it gets nothing, the problem is your machine.
+
+`orc` is on that list on purpose. This is a report about somebody else's
+service. A report that can never blame the person who wrote it is not a report
+you should trust.
+
+---
+
+## 5. Continuing instead of starting again
+
+Your wifi comes back. Now you continue:
+
+```
+orc extra resume-slice T-2 --out .orc/T-2.resume.json
+```
+
+```
+  ✔ resuming T-2 on dipkshit/deepseek-v4-flash in a NEW session — 1 file(s)
+    already changed on disk are carried into the slice, not re-done.
+
+  target: extra dipkshit
+  `connection-lost-local` is retryable, so the same profile gets it again in a
+  NEW session — carrying the position it left behind.
+
+  carried into the slice:
+    src/routes/health.js — created (+7 −0)
+    src/app.js — untouched
+
+  /repo/.orc/T-2.resume.json
+  orc extra dispatch --task /repo/.orc/T-2.resume.json --json
+```
+
+The new task file is the old one, plus a note at the top that ORC wrote:
+
+> This task was already started by a worker that was cut off before it finished.
+> **The repository already contains its partial work.** Do not start over and do
+> not rewrite a file that is already correct. Read each file listed below before
+> changing it. Finish the task; change nothing that is already done.
+>
+> `src/routes/health.js` — **created** by the previous attempt (+7 / −0 lines).
+> `src/app.js` — **untouched**.
+>
+> Last recorded action: turn 4 of 12 · `Write src/routes/health.js` · ok.
+> The previous attempt ended: `connection-lost-local` (attributed: network).
+
+Then it runs like any other dispatch. There is no special mode and no new kind
+of worker. Every rule that already protected you still applies.
+
+The next worker reads the file, sees the six lines, adds the missing line, and
+is done.
+
+---
+
+## 6. Four things a resume may never do
+
+These are rules, not settings.
+
+**It may never add a file to the list.** The task said which files it may
+change. A continuation that could add one would widen that list through the one
+door nobody is watching.
+
+**It may never change what "done" means.** The goal was set before any of this
+happened. A failure must not be allowed to lower its own bar.
+
+**It may never change the score.** So it lands on the same band and the same
+model. A resume is not a discount.
+
+**It may never continue a task that changed.** ORC saved a fingerprint of the
+original task. If the plan moved in between, ORC refuses and shows you both
+fingerprints, because continuing a stale task quietly produces work nobody
+asked for.
+
+---
+
+## 7. When ORC refuses
+
+Six refusals, each with its own name, and each one writes nothing.
+
+| name | what it means |
+|---|---|
+| `not-resumable` | nothing was written, so starting again is the right move |
+| `in-flight` | that worker may still be running. Two workers on one file is worse than one lost worker |
+| `reverted-file` | a file went **backwards** — closer to the last commit than it was. Something may have been deleted, and that is your call |
+| `slice-drifted` | the task changed between attempts |
+| `resume-cap` | you have already resumed this task twice (`extra_resume_max`) |
+| `resume-disabled` | you turned `extra_resume` off |
+
+`in-flight` is the important one. A dropped connection does **not** prove the
+worker stopped. The other company's servers may still be sending. ORC waits for
+one of two things: the process is gone, or the time it reserved has run out.
+
+And it says the honest part out loud: after that time has passed, a process with
+the same number is treated as somebody else's. That is a reasonable guess, not
+proof, and ORC tells you which it is.
+
+---
+
+## 8. Dispatches that never came back at all
+
+If the process was killed — you closed the terminal, the machine slept — ORC
+never got to write down how it ended. That record has a beginning and no end.
+
+ORC notices before your next run starts:
+
+```
+⚠ 1 foreign dispatch from an earlier run never reported back
+  T-9 · local-opencode/deepseek-chat · started 11:15 · 1 declared file, 1 changed on disk
+  orc extra reconcile T-9   →   resumable
+```
+
+**It tells you. It never continues it on its own.** Quietly finishing somebody
+else's half-written change in your repository is not a thing ORC does without
+asking — the same rule that makes ORC announce every task that leaves Claude.
+
+It also does not stop your run. It is something to know, not a wall.
+
+That killed dispatch cost real money, too. ORC recovers what it recorded and
+writes it into the spending log, marked clearly:
+
+> tokens recovered from the journal. This is a **floor** — the real total may be
+> higher, because the dispatch died before it could report.
+
+A number that might be too low is useful. A number that pretends to be exact is
+not.
+
+---
+
+## 9. In the panel
+
+```
+orc ui
+```
+
+**Extra ▸ Recovery** lists every recorded dispatch. Click one and it opens in
+place: which files changed and by how many lines, the last thing the worker did,
+whose fault it was, and what the task had to achieve.
+
+Two things about that screen:
+
+- **The free read is a button. The paid one is a command you copy.** Reconciling
+  costs nothing, so you can press it. Continuing the task costs money and runs a
+  worker, so the panel gives you the command and you run it where work runs. The
+  panel never runs work for you.
+- **Every row keeps its place.** A dispatch with nothing to resume still shows,
+  saying so. If ORC hid it, "there was nothing there" and "ORC never looked"
+  would look the same.
+
+**Extra ▸ Spending** now also shows how often each connection actually finishes:
+
+```
+dipkshit    41 dispatch(es) · 6 failed · 4 resumed · 1 never reported back   15% did not finish
+            provider 2 · network 3 · local 0 · worker 1 · orc 0 · unattributed 0
+            average time before a failure: 38s
+```
+
+Under ten dispatches it says **sample too small** and shows no percentage. A
+rate worked out from three tries is noise with a percent sign on it.
+
+---
+
+## 10. What you can change
+
+Two settings, and that is on purpose.
+
+| setting | default | what it does |
+|---|---|---|
+| `extra_resume` | `on` | Continue a stopped dispatch instead of starting it again. On by default, because off is the broken behaviour. |
+| `extra_resume_max` | `2` | How many times one task may be continued before ORC hands it to Claude and tells you. |
+
+There is deliberately **no** setting for where a resume goes — ORC works that
+out from what failed. There is **no** way to switch the journal off: a record you
+can turn off is turned off on the day you needed it.
+
+---
+
+## 11. What it will not do
+
+**It will not tell you whether a file is finished.** ORC will not count brackets
+or guess that a line looks cut off. A checker that is right eight times in ten
+teaches you to trust it the other two, and that is worse than having none. ORC
+gives you the facts — what changed, what did not, what the worker last did — and
+the worker that continues makes the judgement. Your build, your tests and the
+reviewer are what decide whether the work is done, exactly as before.
+
+**It will not continue anything by itself.** Every one of these steps is
+something you asked for.
+
+---
+
+## 12. The one line to remember
+
+> **A failed dispatch is a position, not a blank page.**
+
+ORC knows what was there before, it knows what is there now, and it can tell the
+next worker the difference — instead of pretending the first one never ran.

package/mock-run/extra-slots.md

@@ -0,0 +1,177 @@
+# Mock run — the jobs that have no score
+
+> Four ORC lanes never give a task a score. They give one job to one agent. This
+> walkthrough shows you how to send one of those jobs to a cheaper model, and
+> what ORC tells you before it does.
+
+---
+
+## 1. What this is about
+
+`orc extra` lets a task run on a different AI model — DeepSeek, GLM, Kimi, or a
+model on your own laptop. Until now you told it **which score ranges** may go
+there:
+
+```
+[0,30)   → deepseek/deepseek-chat
+[30,55)  → glm/glm-4.6
+```
+
+That works for `/orc`, `/orc-ultra`, `/orc-mini` and `/orc-diy`, because those
+lanes give every task a score.
+
+**Four lanes never do.** `/orc-quick`, `/orc-fast`, `/orc-doc` and `/orc-wiki`
+give one job to one agent and no score at all. So they get **positions** instead
+of ranges. A position is one job with one name:
+
+| position | the lane | the job |
+|---|---|---|
+| `quick-executor` | `/orc-quick` | writing the code for one quick entry |
+| `fast-executor` | `/orc-fast` | the single executor of a fast run |
+| `doc-writer` | `/orc-doc` | writing one part of a document |
+| `doc-checker` | `/orc-doc` | reading one part back and reporting on it |
+| `wiki-scanner-deep` | `/orc-wiki` | a full scan of one area |
+| `wiki-scanner-light` | `/orc-wiki` | a small update to a doc that exists |
+
+---
+
+## 2. Looking at the positions
+
+```
+$ orc extra role
+```
+
+```
+ORC · extra — the positions
+───────────────────────────
+
+  quick-executor      claude · orc-executor-sonnet-4-6-med    /orc-quick
+  fast-executor       claude · orc-executor-sonnet-4-6-high   /orc-fast
+  doc-writer          claude · orc-doc-writer-opus-5-med      /orc-doc
+  doc-checker         claude · orc-doc-checker-opus-5-low     /orc-doc
+  wiki-scanner-deep   claude · orc-wiki-scanner-opus-4-8-high /orc-wiki
+  wiki-scanner-light  claude · orc-wiki-scanner-sonnet-5-high /orc-wiki
+
+  what each position is
+    quick-executor      asked at the gate
+    fast-executor       announced: the F0 preflight `extra:` line, before wave 1
+    doc-writer          announced: before the wave, naming the sections
+    ...
+
+  A slot with no row is not a hole — it is Claude, and it is printed so "I left
+  the checker on Claude on purpose" and "there is no checker" never look the same.
+```
+
+**All six are always listed, even the ones you have not touched.** A row you did
+not fill in is not missing — it runs on the Claude agent printed beside it, and
+you can see which one that is without going to look.
+
+---
+
+## 3. Giving one job to a cheaper model
+
+You already connected DeepSeek and tested it (`orc extra add`, then
+`orc extra ping`). Now give it the doc **writer** job — and only that one:
+
+```
+$ orc extra role set doc-writer ds/deepseek-chat
+```
+
+```
+doc-writer → ds/deepseek-chat   /orc-doc
+  takes this position off: orc-doc-writer-opus-5-med
+```
+
+Two things it will not do:
+
+- **It will not let you point a job at a connection that never answered.** You
+  get a refusal that names the connection and the command that tests it.
+- **It will not change any other job.** The doc *checker* is still on Claude, and
+  `orc extra role` will keep saying so.
+
+---
+
+## 4. What the document lane tells you, before it spends anything
+
+A document is the one thing where the model is visible in the result — it is the
+writing. So `/orc-doc` says which model writes which sections **before** the
+wave, not after:
+
+```
+$ orc doc next prd-billing
+```
+
+```
+extra: writer — sections 03-scope, 04-users will be written off Claude.
+  writer → deepseek/deepseek-chat (via ds, displaces orc-doc-writer-opus-5-med).
+  A document's voice is the deliverable, so this is said before the wave, not
+  after it.
+```
+
+The **checker** is not mentioned, because the checker is not going anywhere. Two
+different jobs, two different answers — that is the whole point of a position.
+
+You can also switch it off for one document without touching the position:
+
+```
+$ orc doc extra prd-billing --set off
+```
+
+---
+
+## 5. The quick lane ASKS. It always asks.
+
+`/orc-quick` never picks an agent for you. So a position there does not route
+anything — it just **adds a third line to the menu you already read**:
+
+```
+Which executor for entry 2 — "add retry header"?
+
+  1. orc-executor-sonnet-4-6-med    cheap, fits a 3-file change
+  2. orc-executor-opus-5-low        thinks harder, about 3× the cost
+  3. deepseek/deepseek-chat         via profile `ds` — sends this slice to a third party
+```
+
+- It is **never** the default.
+- It does **not** stick to the next entry.
+- If it fails, the same menu comes back with the reason. ORC does not quietly
+  pick option 1 for you.
+
+---
+
+## 6. What ORC costs, and where it went
+
+A job that ran somewhere else is written down like any other:
+
+```
+$ orc extra stats
+```
+
+```
+  ds / slot:doc-writer      4 dispatches   in 41.2k · cw 0 · cr 128.0k · out 9.1k   $0.03
+  ds / [0,30)              11 dispatches   in 88.0k · cw 0 · cr 210.4k · out 22.6k  $0.07
+```
+
+Each position gets its own line, so "the doc writer cost this much" is a
+question you can answer.
+
+---
+
+## 7. The one rule underneath all of it
+
+> **Extra decides whether a Claude agent runs at all. `opus5_only` and the score
+> tables only decide which Claude agent runs where extra did not take it.**
+
+If you gave `doc-writer` to DeepSeek, `opus5_only` is not consulted for that job
+at all. It is still fully in charge of `doc-checker`, because you left that one
+alone. `orc config list` prints both facts, so a setting is never quietly doing
+nothing.
+
+---
+
+## 8. What this walkthrough did not do
+
+- It never sent your code anywhere without printing a line about it first.
+- It never picked a model for you in `/orc-quick`.
+- It added **no new settings** to your config file. A position is a row you set
+  with one command and remove with one command.

package/mock-run/media/README.md

@@ -0,0 +1,43 @@
+# mock-run/media — where the demo video goes
+
+This folder holds the screen recordings the mocked runs link to. It ships empty
+on purpose: the files are big, and they go out of date faster than the docs do.
+
+## Add the `orc ui` walkthrough
+
+1. Start the panel on canned data, so nothing private is on screen:
+
+   ```bash
+   orc ui --fixtures
+   ```
+
+2. Record it. Keep it under about two minutes. A good route is:
+   Overview → Worth doing → Settings (stage two edits, apply) → Flow (the
+   stepper) → Crosslink (the graph) → **Mocked Skill Use** → Maintenance
+   (preview, then apply).
+
+3. Save the files here with **these exact names** — the links in
+   [`../orc-ui.md`](../orc-ui.md) and in the repository `README.md` already
+   point at them:
+
+   | File | What it is |
+   |---|---|
+   | `orc-ui-demo.mp4` | the recording (H.264 mp4 plays everywhere) |
+   | `orc-ui-demo-poster.png` | one still frame, used as the clickable image |
+
+4. Delete the placeholder comment block at the top of `../orc-ui.md`.
+
+## Playing it on GitHub
+
+A `<video>` tag with a repo-relative `src` does **not** play inline on
+github.com. Two things that do work:
+
+- the image link that is already in the docs — clicking it opens the file, or
+- drag `orc-ui-demo.mp4` into a GitHub issue or pull request comment, copy the
+  `https://github.com/user-attachments/...` URL that GitHub generates, and paste
+  that URL on its own line in the markdown. GitHub renders that as a player.
+
+## Size
+
+Keep each file under about 10 MB. If the recording is bigger, host it somewhere
+else and link it instead — a repository is a bad video host.