Troubleshooting

The private form link stopped working

The form listener must remain running. A stopped listener invalidates its link.

1. In the original selected environment, start a listener for the same canonical task directory: python -m attune_harness.gui --task "$TASK" --edit --launch-json.
2. Keep the process running. Open its new private launch_url; do not reuse the previous link.
3. Select Continue form and inspect Saved answers before typing or submitting again.

Expected result: Previously saved answers remain in the authoritative task record. Unsaved typing is not guaranteed to survive. Launcher links contain private access information; keep them out of public docs, screenshots and logs.

The form says the checkpoint is stale

Opening a new form or restarting the listener can expire the prior checkpoint.

1. Open the current form for the same saved task.
2. Read the current guidance and saved answers. Review any changed scope before accepting it.
3. Submit through the current form only when its answers and intent are correct.

Expected result: The decision is bound to the current preview. Do not replay an older submission or edit task evidence to bypass the refusal.

A dependency or command is unavailable

1. Check the installed distribution in the interpreter you selected: python -c "from importlib.metadata import version; print(version('attune-harness'))".
2. Read the selected route's --help and the actual diagnostic. Follow the installed interface if it differs from this 1.3.0 guide.
3. Compare your installation with the release dependency map. A --no-deps installation omits the normal base dependencies; restore the normal install in a disposable isolated environment.

Expected result: The CLI and interpreter refer to one environment. Optional integrations are installed only for the requested journey. Do not upgrade a retained evidence environment or combine Harness and Attune-AI to clear a refusal.

A task path is refused

Use an existing canonical absolute directory for browser registration. Resolve symlinks before launching; on macOS, use /private/tmp rather than /tmp. Task directories must sit outside checkouts used for file effects. Read the route-specific refusal before moving or recreating anything.

A result is paused, rejected or failed

Inspect attune-harness status "$TASK" --format markdown and retain its evidence. A successful status command means inspection worked; it does not mean the task passed. Resolve its stated next action and current authority before resuming. Unknown or uncertain effects need reconciliation, not a blind retry.

If you need help, report the version, route, redacted diagnostic and expected result through Harness issues. Do not include private launcher links, credentials or project data.