@siuver/omp-debug-mode 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## Unreleased
+
+## 0.1.5 - 2026-08-25
+
+- Tightened the injected methodology, start prompt, and proceed prompt so a `runtime_probe` round must write `@omp-probe` instrumentation in the same turn before emitting closing tags, and `<reproduction_steps>` lists only user actions.
+- Replaced the `idle`/`round`/`waiting`/`cleanup` phases plus the redundant `active` flag with a discriminated union over four stages named after whose turn it is: `investigating`, `open`, `awaiting_evidence`, and `cleaning_up`. A round that settles without closing is now the explicit `open` stage with its own status label, widget, and explanation instead of a silent stop that looked like the reproduction gate.
+- Moved every transition into one pure reducer (`src/machine.ts`) that returns declarative effects (notify, prompt, continue, teardown) for the runtime shell to apply, so state changes no longer hand-reset a different subset of fields per call site and the run-creation failure path no longer needs a manual rollback.
+- Made round-scoped data structural: each round record owns its run id, evidence plan, reproduction steps, probe ids, and per-reason nudge budgets, instead of being filtered out of session-wide arrays by a mutable round counter. Probe nudges and closing-tag nudges now have independent budgets.
+- Closing a `runtime_probe` round now requires probes the ledger actually finds on disk, not just a plan that names the method; the ledger is reconciled before every settle, so instrumentation that was written and then deleted no longer reaches the gate.
+- `/debug-proceed`, `/debug-done`, and `/debug-evidence` now work from an `open` round after a confirmation instead of failing with "not waiting for reproduction"; they only refuse while an agent turn is actually running.
+- Cleanup that leaves markers behind is sent back once with the remaining probes listed before teardown gives up and warns, instead of tearing down on the first attempt regardless.
+- Session restore now migrates the pre-`rounds` persisted layout, and an unknown or `investigating` stage resolves to `open` rather than dropping the user into a reproduction gate that was never opened.
+
 ## 0.1.4 - 2026-08-21
 
 - Added least-user-intervention evidence planning: the agent chooses `agent_inspection`, `runtime_probe`, `user_report`, or `user_artifact` per hypothesis, must justify user-assisted methods, and batches compatible hypotheses into the fewest reproductions or captures.

package/README.md

@@ -10,11 +10,26 @@ The plugin makes the agent form 3-5 hypotheses, choose the cheapest reliable evi
 | --- | --- |
 | `/debug-mode <problem>` | Starts a debugging session from a symptom, expected result, actual result, and reproduction description. |
 | `/debug-proceed [details]` | Continues with captured evidence: optional details are recorded as a user-report observation, then the agent evaluates hypotheses and may fix only with evidence before asking for verification. |
-| `/debug-evidence [<request-id>] <path>` | Attaches one user-provided evidence file to the current waiting round. If the first token matches a pending current-round request ID, the file is linked to that request; otherwise the whole argument is treated as the path (spaces allowed). Without an argument it opens an input dialog (interactive UI only). Files are referenced in place and never copied or deleted. |
+| `/debug-evidence [<request-id>] <path>` | Attaches one user-provided evidence file to the current round. If the first token matches a pending current-round request ID, the file is linked to that request; otherwise the whole argument is treated as the path (spaces allowed). Without an argument it opens an input dialog (interactive UI only). Files are referenced in place and never copied or deleted. |
 | `/debug-done` | Marks the problem as fixed: the agent removes every probe and summarizes the result. |
-| `/debug-status` | Shows the current phase, round, run, live probes, captured log counts, pending evidence requests, and attached/unavailable artifacts. |
+| `/debug-status` | Shows the current stage, round, run, live probes, captured log counts, pending evidence requests, and attached/unavailable artifacts. |
 | `/debug-abort` | Stops debug mode and removes its logs after confirmation while leaving code changes in the working tree. |
 
+## Stages
+
+The workflow tracks one thing: whose move it is. Every stage other than `investigating` belongs to you, and each has its own status label and widget so a stopped agent never looks like a stopped workflow.
+
+| Stage | Meaning | What you do |
+| --- | --- | --- |
+| `investigating` | An agent turn is in flight. | Wait. |
+| `open` | The round settled without closing — a clarifying question, or declared instrumentation that never reached the code. | Reply normally. `/debug-proceed` closes the round anyway after a confirmation. |
+| `awaiting_evidence` | The round closed properly and is at the reproduction gate. | Reproduce, capture, then `/debug-proceed`. |
+| `cleaning_up` | `/debug-done` was accepted; probes are being removed. | Wait. |
+
+Transitions live in one pure reducer (`src/machine.ts`), which returns declarative effects — notify, inject prompt, continue the turn, tear down — that the runtime shell applies. Every round is a record holding its own run id, evidence plan, reproduction steps, probe ids, and nudge budgets, so round-scoped data is never derived by filtering a session-wide array on a mutable counter.
+
+A resumed session never lands in `investigating`, because no agent turn survives a restart; an unrecognised persisted stage resolves to `open`, on the conservative reading that the agent owes you something rather than the reverse.
+
 ## Evidence Methods
 
 For every hypothesis, the agent must pick one of four methods, in least-user-intervention order:
@@ -40,15 +55,21 @@ Each round closes with an exact machine-readable block that covers every hypothe
 </evidence_plan>
 ```
 
-Every field is validated: `id` must be unique and non-empty, `hypothesisIds` must reference one or more real hypotheses, `method` must be one of the four literals above, `rationale`/`title` must be non-empty, and `instructions` must contain actionable steps (`artifactHint` describes the expected file kind for `user_artifact`). A malformed plan is rejected entirely — no hypothesis is ever silently dropped. Plans are capped at 12 entries per round. The plan is combined with the existing `<reproduction_steps>` block, which describes the single combined reproduction/capture sequence.
+Every field is validated: `id` must be unique and non-empty, `hypothesisIds` must reference one or more real hypotheses, `method` must be one of the four literals above, `rationale`/`title` must be non-empty, and `instructions` must contain actionable steps (`artifactHint` describes the expected file kind for `user_artifact`). A malformed plan is rejected entirely — no hypothesis is ever silently dropped. Plans are capped at 12 entries per round. The plan is combined with the existing `<reproduction_steps>` block, which describes the single combined reproduction/capture sequence the user performs now. The injected methodology forbids emitting those closing tags for a `runtime_probe` round until `@omp-probe` markers are already in the working tree, and forbids listing planned agent work (installing probes, reading logs, analyzing) as reproduction steps.
 
 ## The Reproduction Gate
 
-A round ends at the gate when the Agent emits a `<reproduction_steps>` block, not merely when it stops talking. So a clarifying question mid-round leaves you talking to the Agent normally, while an instrumented round that forgot its steps is asked once to finish properly and is then gated anyway so the workflow cannot stall.
+A round may only close when its declarations are backed by observable facts. Emitting the tags is the declaration; the probe ledger is the proof:
+
+- Both `<evidence_plan>` and `<reproduction_steps>` must be present.
+- A plan selecting `runtime_probe` additionally needs at least one `@omp-probe` marker that the ledger actually finds on disk for this round. A probe that was written and then deleted counts as missing.
+- `agent_inspection`, `user_report`, and `user_artifact` plans need no markers at all, and expect no JSONL logs.
+
+Anything short of that is one automatic nudge — and the two nudge budgets are separate, so being sent back for missing probes never consumes the budget for missing closing tags. When a budget is spent the round becomes `open` rather than being gated on evidence that does not exist. A clarifying question mid-round is `open` too, which is the ordinary case: reply and the agent picks the round back up.
 
-Rounds must also close with a valid `<evidence_plan>`. If the plan block is missing, the agent is nudged once for the exact JSON block plus the reproduction steps; after that the gate proceeds anyway with a note that the next round will be asked to declare a method. A round with neither probes nor a valid evidence plan gets the "no runtime evidence" warning; a valid plan that chose a non-probe route (e.g. `agent_inspection` or `user_artifact`) is a properly closed round and produces no such warning — and for `user_report`/`user_artifact` plans, no JSONL logs are expected at all.
+A round with reproduction steps but no plan at all still gates (older sessions closed this way) and gets the "no runtime evidence" warning.
 
-At the gate a widget shows the reproduction steps, any pending user requests (title, instructions, artifact hint), a live counter of captured observations, an `evidence: <pending> pending, <attached> attached` counter, and the list of commands you can use, so you can tell what evidence the round is waiting on and how to act. The widget always ends with the live log counter. Every round stops at the widget and you interact through commands only.
+At the gate a widget shows the reproduction steps, any pending user requests (title, instructions, artifact hint), a live counter of captured observations, an `evidence: <pending> pending, <attached> attached` counter, and the list of commands you can use, so you can tell what evidence the round is waiting on and how to act. The widget always ends with the live log counter. An `open` round gets its own, smaller widget naming why it is open and stating that a reply is the way forward. Every round stops at a widget and you interact through commands only.
 
 Pending requests resolve like this:
 
@@ -56,7 +77,7 @@ Pending requests resolve like this:
 - A `user_report` request is pending until `/debug-proceed <details>` records an observation for the current round; one details submission can satisfy several report requests at once.
 - `agent_inspection` and `runtime_probe` requests never create user work.
 
-If user requests are still pending when you run `/debug-proceed`, the plugin asks "Proceed without all requested evidence?" — confirming is allowed so an unavailable external capture can never deadlock the session; cancelling keeps you at the gate. `/debug-proceed` and `/debug-done` ask for confirmation when the round captured no runtime logs and has no valid non-probe evidence plan.
+If user requests are still pending when you run `/debug-proceed`, the plugin asks "Proceed without all requested evidence?" — confirming is allowed so an unavailable external capture can never deadlock the session; cancelling keeps you at the gate. `/debug-proceed` and `/debug-done` ask for confirmation when the round captured no runtime logs and has no valid non-probe evidence plan, and again when the round is `open` rather than gated. They only refuse outright while an agent turn is actually running.
 
 ## Attaching Evidence Files
 
@@ -75,13 +96,13 @@ Example: for a GPU-rendering symptom whose disputed state only exists inside a f
 
 ## Workflow
 1. Run `/debug-mode <problem description>`.
-2. The Agent records 3-5 hypotheses and picks an evidence method for each under the least-user-intervention priority. If the route is `runtime_probe`, it inserts minimal probes marked with `@omp-probe <id>` inside `#region agent log` blocks; round 1 does not apply a product fix. The start prompt and a per-turn `debug-mode-context` message name the exact JSONL path and require every probe to append to it, including `hypothesisId`; console output (including Unity `Debug.Log`) is supplemental only. The context filter keeps the newest of those messages so the model sees the contract instead of dropping it.
+2. The Agent records 3-5 hypotheses and picks an evidence method for each under the least-user-intervention priority. If the route is `runtime_probe`, it inserts minimal probes marked with `@omp-probe <id>` inside `#region agent log` blocks in the same turn, before emitting the closing tags; round 1 does not apply a product fix (probe edits are not a product fix). The start prompt and a per-turn `debug-mode-context` message name the exact JSONL path and require every probe to append to it, including `hypothesisId`; console output (including Unity `Debug.Log`) is supplemental only. The context filter keeps the newest of those messages so the model sees the contract instead of dropping it. `<reproduction_steps>` are user actions only (reproduce, capture, restart).
 
 3. When the Agent reaches the gate, follow the `<reproduction_steps>` in the real application so the instrumented code writes its observations, watching the widget counter climb — or supply the requested evidence with `/debug-evidence` or `/debug-proceed <details>`. Restart the app or service if the instrumented build would otherwise be stale.
 
 4. Continue with `/debug-proceed [details]` (optionally record a user observation, then evaluate evidence), `/debug-done` (clean up and summarize), `/debug-evidence` (attach a file), or `/debug-status` (inspect the current round state). Each round stops at the widget; all interaction is command-driven.
 5. On Proceed, the Agent reads the evidence (logs, your observations, attached artifacts), cites the evidence method plus log-line numbers or artifact/report paths for each hypothesis, and only then may apply a fix. Probes stay in place. Reproduce again to verify. If verification fails, rejected-hypothesis code changes are reverted before the next round.
-6. On `/debug-done`, the Agent removes every probe and summarizes the root cause and fix in 1-2 lines.
+6. On `/debug-done`, the Agent removes every probe and summarizes the root cause and fix in 1-2 lines. If the ledger is still not empty when that turn settles, cleanup is sent back once with the remaining markers listed; a second incomplete attempt tears down anyway and warns you which probes are still in your source.
 
 The extension also provides the read-only `get_debug_logs`, `list_debug_probes`, and `list_debug_evidence` tools so the Agent can inspect runtime evidence, review pending/satisfied requests with their methods and rationales, and verify cleanup.
 
@@ -107,7 +128,7 @@ When you run `/debug-proceed [details]`, the plugin records non-empty details as
 
 ## Probe Ledger
 
-The plugin tracks every `@omp-probe <id>` marker the Agent writes, resolving each file against the session working directory. Before each round and on every `list_debug_probes` call it rescans those files so the ledger matches the code on disk: markers the Agent has since deleted drop out, and a file that exists but cannot be read is reported as *unverified* rather than assumed clean. That way a failed read can never make teardown claim the probes are gone while they are still in your source. Rounds that choose non-probe evidence methods simply add no markers, and cleanup still verifies that no leftover markers remain before finishing.
+The plugin tracks every `@omp-probe <id>` marker the Agent writes, resolving each file against the session working directory, and attributes it to the round that introduced it. Before each turn, before a round is allowed to close, and on every `list_debug_probes` call it rescans those files so the ledger matches the code on disk: markers the Agent has since deleted drop out, and a file that exists but cannot be read is reported as *unverified* rather than assumed clean. That way a failed read can never make teardown claim the probes are gone while they are still in your source, and a `runtime_probe` round cannot reach the gate on a promise. Rounds that choose non-probe evidence methods simply add no markers, and cleanup still verifies that no leftover markers remain before finishing.
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siuver/omp-debug-mode",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "description": "Evidence-driven, human-in-the-loop debugging with autonomous probes and user-assisted artifacts for oh-my-pi.",
   "license": "MIT",