Troubleshooting and support

Most troubleshooting in Cards involves inspecting local Git repositories, checking the extension's status, or managing local files. When an agent session crashes, a card won't move to Done, or a Git worktree fails to clean itself up, you need a direct path to restore your workspace without losing your progress.

Common troubleshooting steps

1. Resuming after a crashed session

If the agent subprocess exits abruptly (due to a model timeout, network interruption, or local process crash), the card may remain in the active state but the session stream will stop.

To resume the session:

1. Open the card in the Cards panel.
2. Click the Launch button again.
3. Cards detects the existing card-specific Git branch and resumes the session. It does not overwrite your previous progress or history.

---

2. Can't move a card to Done

A card moves freely between states (todo, active, needs_review, done, archived) — there is no permanent "stuck" state. If you can't move a card to done, the optional Merge Gate is enabled for it.

Why this happens: The Merge Gate is an optional gate that is off by default. When you enable it for a card, the card must pass through needs_review and have its merge approved before it can transition to done. The gate never permanently blocks a card: when it's active, the Mark as Done action offers a "Mark as done anyway?" override, and confirming it approves the merge and completes the transition in one step.

To resolve this:

1. Open the card details panel.
2. Review the changes in the Attribution Tree.
3. Click Approve Merge to merge the changes into your active branch, or click Discard Changes to clean up the worktree.
4. Move the card to done. If the Merge Gate is still enabled, choose "Mark as done anyway?" when prompted to override it.

---

3. Cleaning up orphaned worktrees

If VS Code closes unexpectedly while an agent is running, the Git worktree created for that card may remain on disk under ~/.cards/worktrees/<repoId>/cards/<cardId>/<slot>/. This can cause Git conflicts or lock files when you attempt to run new actions.

To clean up orphaned worktrees:

• From the Cards panel:
  1. In the Cards panel, open More Actions and select View Worktrees (also available as the Cards: View Worktrees command).
  2. Find the orphaned worktree in the list and click Remove. If a worktree is broken rather than orphaned, use Repair instead.
• Via the terminal: If the in-panel action does not resolve the issue, you can prune the worktrees manually from your project repository:

  # Run this inside your project directory
  git worktree prune

---

4. Registration and licensing problems

If Cards shows a Trial or Blocked status, or card creation is paused until you register or enter a license code, the fastest fix is to apply your license code directly. This works offline — the code is verified locally and never needs an internet connection.

To activate with a license code (offline):

1. Run Cards: Show License Status from the Command Palette to open the license panel.
2. Expand Replace license code.
3. Paste your CARDS_v1_... code.
4. Click Apply license.

The code is validated locally on your machine, so this path requires no connectivity or proxy access.

Online alternatives (these do require connectivity):

• Register in the browser: Run Cards: Register to complete browser-based registration against cards.management.
• Refresh the license: Run Cards: Refresh License to re-verify your seat with the server.
• Corporate proxy settings: If you use the online paths from behind a corporate proxy, verify that your VS Code proxy settings are configured correctly and that https://cards.management is whitelisted. (The offline license-code path above is unaffected.)

---

5. Worktree is missing files or contains unexpected symlinks

When a card action materializes a worktree, every git-ignored path gets one decision: unmatched paths are shared as symlinks, paths matching .worktreeignore are omitted, and paths matching .worktreeinclude are copied as real files. A file-level .worktreeignore pattern under a fully-ignored directory removes the whole directory from the worktree (a symlinked directory cannot be partially omitted); use a copy rule for the file if the rest of the directory must remain. Inside node_modules in a workspaces repo, the same rule keeps the package usable instead: the package becomes a real directory with the ruled path absent and its other files symlinked, so writes at the ruled path cannot reach the source.

To resolve this:

1. Check .worktreeignore and .worktreeinclude at the repository root — both use gitignore-style patterns, and omit wins over copy.
2. Verify both files are readable and valid. Worktree creation fails closed when either file is unreadable or invalid — nothing is linked until the config is fixed.
3. The policy is re-evaluated on every launch, so after editing either file, run the action again to apply the change. A launch whose worktree setup fails closed (for example, an unreadable config file) removes its partially-created worktree automatically — the directory, its git registration, and the branch the failed run created — before surfacing the error, so the retry starts from a clean slate. A branch that existed before the failed launch is left untouched. If cleanup itself fails, the error message names the leftover directory; remove it with the remove-worktree command before re-running.

---

Viewing diagnostics

If you encounter an unexplained error, start with the server status view to inspect the extension's health.

1. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
2. Run Cards: Show Server Status to review the current state of the Cards server and surface error conditions.
3. If you need help, run Cards: Report Issue to package up the relevant details and reach the team.

Where to get support

• GitHub Issues: Submit bug reports and reproduction steps on our GitHub repository.
• Email Support: For billing, licensing, or account issues, contact us at support@cards.management.