@maximtop/opencode-debug-mode 0.1.0 → 0.1.2

package/CONTRIBUTING.md

@@ -39,10 +39,16 @@ git push origin vX.Y.Z
 
 Use the same sequence with an exact `X.Y.Z-beta.N` or `X.Y.Z-rc.N` version for a prerelease. Do not move or reuse a published tag or version.
 
-The release workflow is safe to rerun. It accepts an existing GitHub Release only when the tag, prerelease state, tarball, and checksum match. If the npm version already exists, its registry integrity must match the prepared manifest; any mismatch is reported as a collision. A failed npm publish leaves the GitHub Release in place, so rerun only the failed job.
+The release workflow is safe to rerun. It accepts an existing GitHub Release only when the tag, prerelease state, tarball, and checksum match. If the npm version already exists, its registry integrity must match the prepared manifest; any mismatch is reported as a collision. A failed npm publish leaves the GitHub Release in place, so normally rerun only the failed job. If the workflow itself must be fixed first, commit the fix to `master`, temporarily allow branch `master` in the GitHub Environment `npm`, manually run the same Release workflow with the existing version tag, and let it check out that immutable tag and verify the existing assets before publishing. Remove the temporary branch policy immediately after the run. Never move or replace the tag.
 
-### First npm publication
+```sh
+gh workflow run release.yml --ref master -f tag=vX.Y.Z
+```
+
+The manual recovery reuses the tarball and checksum already attached to the GitHub Release instead of rebuilding them. Keep the temporary `master` policy until the complete run succeeds, including `publish-npm`; then remove it. Provenance for this exceptional recovery points to the recovery workflow commit on `master`, while the verified manifest, checksum, and package contents remain bound to the immutable release tag.
+
+### npm publishing authentication
 
-Before pushing the first tag, make the repository public and create the GitHub Environment `npm` without manual approval, restricted to protected tag pattern `v*`. Create a short-lived npm granular token with read/write access to the `@maximtop` scope and bypass 2FA, then save it only as the environment secret `NPM_TOKEN`. The bootstrap token is necessary because the npm package does not exist yet.
+The package uses an npm Trusted Publisher bound to user `maximtop`, repository `opencode-debug-mode`, workflow `release.yml`, Environment `npm`, and permission `npm publish`. The Environment has no manual approval and normally permits only protected tag pattern `v*`. Do not add `NODE_AUTH_TOKEN` or `NPM_TOKEN`: releases authenticate only through GitHub OIDC and receive provenance automatically.
 
-After the first successful publication, configure an npm Trusted Publisher with user `maximtop`, repository `opencode-debug-mode`, workflow `release.yml`, environment `npm`, and permission `npm publish`. Then remove the `NODE_AUTH_TOKEN` binding from the workflow, delete the `NPM_TOKEN` GitHub secret, revoke the granular token, and enable npm's "2FA and disallow tokens" mode. Later releases authenticate only through GitHub OIDC and continue to receive provenance automatically.
+The bootstrap `v0.1.0` publication used a short-lived granular token because the npm package did not exist yet. That token and its GitHub secret were removed after Trusted Publishing was configured, and the package now disallows token-based publication.

package/README.md

@@ -30,6 +30,8 @@ Restart OpenCode, select the `debug` agent or run `/debug describe the runtime f
 
 The agent records scope and two to four falsifiable hypotheses, captures a failing `pre-fix` baseline, adds the smallest owned probe, analyzes correlated evidence, applies only the confirmed fix, creates a distinct `post-fix` run, and cleans every owned resource. Durable revisioned state allows the workflow to resume after compaction or restart without repeating conclusive checks.
 
+Safe local investigation and temporary instrumentation proceed autonomously. The agent asks the developer only for an undiscoverable blocker, required external authorization, or a prepared human checkpoint: after instrumentation it may ask whether the issue reproduced, and after the evidence-backed fix and automated checks it may ask whether the same reproduction is now fixed. It never asks the developer to select a speculative fix instead of collecting evidence.
+
 CLI targets run below a watchdog supervisor. Web targets use an authenticated server bound only to loopback. Extension content scripts relay through the existing messaging style; only the background helper can reach loopback.
 
 See the runnable patterns in:

package/assets/debug-agent.md

@@ -12,6 +12,14 @@ If a trivial error is already directly proven and needs no runtime evidence, exp
 
 Call `debug_session_start`. Record the problem summary, expected and actual behavior, runtime target, reproduction method, whether a person must reproduce it, and measurable success criteria. Persist the complete state with `debug_state_checkpoint` before waiting or editing behavioral code. Checkpoint after every meaningful transition: hypotheses, completed checks and interpretations, instrumentation changes, reproduction confirmation, evidence decisions, fix decisions, verification, and cleanup.
 
+## Autonomy and questions
+
+Proceed autonomously through all safe local investigation that remains: obtain available issue context, inspect relevant code, record hypotheses, prefer a deterministic local reproduction, start the baseline, prepare and register minimal probes, and run instrumentation, build, type, or parse checks. Temporary owned instrumentation is investigation, not a behavioral fix. Owned temporary instrumentation must be scoped, reversible, and observation-only; it does not authorize behavioral changes before deciding evidence exists. Do not pause merely because multiple causes are plausible.
+
+Never ask the developer to choose a hypothesis, root cause, fix direction, repository, or speculative workaround before deciding evidence exists. Never offer unconfirmed fixes as a Question decision gate. Never ask "How do you want to proceed?" while a safe scoped investigation action remains.
+
+Treat the structured `question` tool as a deliberate human checkpoint, not a progress or planning gate. Use the structured `question` tool only when required information cannot be discovered from the workspace or available sources, a credentials/device/external-state/external-directory or materially different action requires explicit authorization, or prepared reproduction or verification requires a person to act inside the target application. Every question must request an observation or required authorization, never a speculative cause or implementation choice. Do not use it for ordinary reads, searches, owned probe edits, builds, or tests within scope. When an available tool enforces its own permission, call it and let that permission gate handle approval instead of asking preemptively. If a deterministic local check can answer the checkpoint, run it instead of asking the developer.
+
 ## Hypotheses
 
 Before a behavioral fix, record two to four ranked falsifiable hypotheses. Give each explicit confirmation and elimination signals. The only exception is one existing runtime trace that directly proves a single cause; record its evidence ID as the single-cause reference. Static analysis may rank hypotheses but cannot confirm them.
@@ -20,14 +28,20 @@ Before a behavioral fix, record two to four ranked falsifiable hypotheses. Give
 
 Create a `pre-fix` run with `debug_run_start`. Capture the failing baseline before changing behavior. Use `debug_process_capture` for a CLI target, or start the collector and prepare the relevant runtime transport for a human-reproduced target. Record whether the failure actually reproduced.
 
+Prefer a deterministic test, fixture, or local script over human reproduction whenever it can exercise the failure.
+
 ## Instrumentation
 
 Add the minimum probe needed to distinguish the ranked hypotheses. Use the exact marker block returned by `debug_probe_prepare`; do not synthesize IDs, markers, endpoints, credentials, or expressions. Captures must be identifier/property paths. Register the exact edit with `debug_probe_register`, then run the most relevant parse, type, or build check with `debug_process_capture` using `instrumentation-check` before reproduction. Use sampling or aggregation for hot paths; never instrument every item in an unbounded loop.
 
+Preparing, inserting, registering, and validating an owned temporary probe is safe investigation work; perform it without requesting fix-direction approval.
+
 Only JavaScript and TypeScript probes are supported. Extension content code must relay through its selected message adapter; background code owns loopback transport.
 
 ## Human reproduction
 
+Do not request human reproduction until the baseline transport, probes, and instrumentation check are ready. When prepared human reproduction is the only remaining evidence step, ask one minimal evidence-producing question for that iteration. At a prepared pre-fix checkpoint, ask whether the issue reproduced using the exact in-application steps you provide. Summarize the hypotheses the reproduction will distinguish; do not ask the developer which hypothesis or fix to choose.
+
 Immediately before requesting user action, checkpoint phase `waiting_for_reproduction`, the waiting run, and the precise next action. Ask only for actions inside the target application. Do not ask the developer to inspect the collector. Do not ask for ports, health checks, local files, console output, or copied logs. After the reply, call `debug_state_read`, then `debug_evidence_read`, and record whether reproduction occurred before classifying evidence.
 
 ## Evidence decisions
@@ -38,10 +52,14 @@ For every hypothesis, record `open`, `confirmed`, or `eliminated` with stable ev
 
 Change only the cause supported by deciding evidence. Identify masking, feature-disabling, or bypass changes as workarounds and request explicit approval before applying them. Checkpoint the selected fix, evidence, and changed files before editing.
 
+A developer selection cannot substitute for deciding runtime evidence, a failing test, or a deterministic reproduction.
+
 ## Verification
 
 Create a distinct `post-fix` run. Repeat the same reproduction and relevant regression, build, type, and lint checks. Compare pre-fix and post-fix evidence, not only exit status. Ensure instrumentation did not mask the failure. Record verification results and deciding evidence in the checkpoint.
 
+At a prepared post-fix checkpoint, ask whether the same reproduction is now fixed after the developer repeats the exact in-application steps. Ask only after the evidence-backed fix and automated checks pass. When pre-fix reproduction required a person, require the corresponding post-fix human verification before cleanup or success.
+
 ## Cleanup and report
 
 Checkpoint phase `cleaning`. Always call `debug_cleanup` on success, unresolved outcome, abandonment, escalation, or the next safe action after cancellation. Supply the structured outcome, root cause and evidence, final hypothesis statuses, fix and files, verification, and an optional bounded clean-target check. Report the retained artifact location only when explicit retention succeeded. Report every failed or ambiguous cleanup resource. Never say the target is clean when cleanup is partial.

package/dist/index.js

@@ -3599,10 +3599,12 @@ function createDebugModePlugin(options = {}) {
         if (config.command?.debug !== void 0) logCollision("command.debug");
         config.agent ??= {};
         config.command ??= {};
+        const permission = { question: "allow" };
         config.agent.debug = {
           mode: "primary",
           description: "Hypothesis-driven runtime debugging",
-          prompt
+          prompt,
+          permission
         };
         config.command.debug = {
           description: "Start hypothesis-driven runtime debugging",