Command behavior lookup
Check the scope of a proposed repair before running it.
Open this resource →Connection diagnostics
Find the failed part of a connection
Read device and repository evidence, repair the affected state, and retain the parts that still work.
A connection has several independent results. Identify the failed result before you refresh content, change trust, or remove authorization.
01 / Connection diagnostics
Capture a useful problem report
Record the agent and repository where the issue occurs. Read current status. Run doctor for that combination before changing installation or enrollment.
Keep the diagnostic category and bounded reason. Remove enrollment codes, provider keys, and private source from anything you share with an administrator.
npx @betterloop/setup status
npx @betterloop/setup doctor --harness codex --project /path/to/repository| Part of the connection | Evidence available | Limit of that evidence |
|---|---|---|
| Installation | Presence of the selected agent and Betterloop-owned integration | The files can be present before any hook has run. |
| Authentication | Native access to the model provider | This account connection does not establish enrollment in the team. |
| Signed policy | Signature, scope, expiry, and supported release format | A valid release cannot implement a control absent from the selected adapter. |
| Activation | An observed invocation at a supported hook event | One observed event does not cover all possible session execution routes. |
| Coverage | Support and stated conditions for each configured control | The connected client supplies this report. It is not independent device attestation. |
| Resource readiness | Preparation, authorization, native trust, and discovery results | A prepared definition does not establish that the resource was used in later work. |
Choose the repair that matches this evidence. For example, native sign-in repairs provider access. It does not require removal of the shared device enrollment.
02 / Connection diagnostics
Repair release, activation, or knowledge state
When the signed release needs attention
Select the affected repository and agent when running sync. It refreshes signed rules and learning. It also retries bounded events and reports coverage.
betterloop sync --harness codex --project /path/to/repository
betterloop doctor --harness codex --project /path/to/repositoryIf validity still fails, read the named release dependency. Ask the administrator to confirm publication and the required runtime compatibility.
Setup reports an unavailable signed runtime variant before consuming the enrollment code. Treat that result as a release dependency requiring resolution.
When plugin files exist without activation
Read the native hook enablement state. For Codex, open /hooks. Review the Betterloop definitions. Complete their native trust requirement.
Open a fresh session in the intended repository. Allow a supported hook event to occur. Run doctor again to inspect activation evidence.
If the host blocks installation, inspect its version and managed settings. Resolve the native restriction reported by setup before accepting installation as complete.
When knowledge selection is unresolved
Obtain the intended project identifier from the administrator. Select it for the correct working repository with --knowledge-project.
betterloop sync --harness codex --project /path/to/repository --knowledge-project PROJECT_IDFor an unavailable external reference, inspect source authorization separately. Knowledge discovery neither supplies private credentials nor automatically retrieves private document contents.
03 / Connection diagnostics
Choose the operation with the intended scope
| Operation | State affected | State retained or restricted |
|---|---|---|
| forget | Archives the chosen repository cache | The device authorization remains connected. |
| uninstall | Turns off one selected integration and revokes its restricted agent credentials | The native agent, provider credentials, and unrelated plugins stay installed. |
| disconnect | Disables managed agents, revokes the device, and archives the connection | An archive cannot restore revoked authorization. Reconnection needs fresh enrollment. |
betterloop forget --harness codex --project /path/to/repositoryAfter forget, run sync for that repository. Check doctor afterward. An archived cache is not evidence of the current reviewed release.
betterloop uninstall --harness codexA team or organization change requires explicit disconnection from the previous enrollment. Obtain fresh enrollment for the intended connection. Open new sessions after the switch.
betterloop disconnectMoving an older runtime connection
Use setup --migrate for an intentional legacy migration. The first migration needs fresh device enrollment and a matching legacy team.
Setup validates owned integrations before replacing them. It privately archives previous caches and credentials. Unidentified native enrollments need explicit disconnection.
04 / Connection diagnostics
Resume after interruption or network loss
Setup uses ~/.betterloop/setup.lock to serialize installation changes. Library operations use ~/.betterloop/device/library.lock for their own changes.
Before clearing an interrupted operation’s lock, confirm that its process exited. Inspect the directory. Remove it only if it is empty and abandoned.
Rerun the interrupted operation afterward. An active process still owns its lock. Removing that lock would allow conflicting local changes.
Recovery archives reside under ~/.betterloop/removed/. Their retained private state does not make revoked credentials valid again.
Restore connectivity before reassessing delivery
Hook decisions use verified local caches without a network request for each decision. Valid unexpired caches can continue during a temporary outage.
Coverage decreases when policy becomes invalid or expired, or a known revocation applies. Supported gates deny actions when required policy cannot be evaluated.
Native hook failures can still permit execution. This local policy behavior does not provide an operating-system sandbox. Check the actual supported action route.
After connectivity returns, run sync. Inspect release expiry, revocations, and required controls. The bounded queue retries pending report delivery.
Illustrative repair: one resource and one agent
A Harbor developer installs a resource for Claude Code and Codex. Claude Code succeeds. Codex reports a native trust problem. The developer retains the successful selection.
They complete the Codex trust step and repeat the operation for Codex alone. They inspect library status and doctor without revoking the shared device.
That local installation result does not prove later execution. Resource activity needs its own evidence. The team keeps the successful installation and execution conclusions separate.
An unapproved-repository report can fail delivery without blocking development. Required policy evaluation can still deny a supported action. Distinguish these two failure categories.
Sync cannot implement an unsupported adapter control. Resolve that requirement through a compatible agent choice or a reviewed change to the rollout decision.