Diagnostics and bounded recovery

Recover without bypassing p-track safeguards

Start with the narrowest diagnostic, preserve authoritative data and recovery artifacts, and use destructive controls only when their stated scope is acceptable.

Project and database errors

“No p-track project found”

p-track resolves the deepest canonical project root in the attested active-generation marker. Confirm where you are, then change to the registered project:

pwd
git rev-parse --show-toplevel
cd /path/to/repository
ptrack context

If this repository has never been initialized, run ptrack init once at its intended root. Do not initialize a different directory merely to silence the error; see Start Here.

Database busy or read timeout

Project and global databases wait for their file lock for one second. Let an active p-track operation finish, close an unintended duplicate p-track process that has the same database open, and retry. Do not delete .ptrack/ptrack.redb, global.redb, active-generation.json, or a cutover lock.

Database format is newer than this p-track

An error such as invalid database manifest: collection plans requires codec 3 schema 1..=8, found codec 3 schema 9 means a newer p-track has written to this database and this binary is older. Nothing is damaged. Upgrade every copy of p-track you use (the desktop app, the CLI on your PATH, and copies on other machines) and retry. Do not force the database open, downgrade it, or edit its schema.

One project is unavailable

A project whose .ptrack/ptrack.redb is missing, for example after git clean -fdx, is reported as unavailable, and every other registered project keeps working. p-track also tightens a project database whose permissions were loosened (for example to 0644) back to owner-only instead of refusing it. A project database that another process holds busy affects only commands for that project. Restore the missing database from a backup or run ptrack init again in that project; if the project folder moved, quit p-track and run ptrack relocate in the new location.

Desktop project and board state

If Open Project or Switch Project reports active terminals, agent runs, or resource operations, inspect the confirmation instead of repeating the action. Confirming stops the counted resources and cleans up the current project before switching; canceling keeps the current workspace. If the confirmation expires or resources change, start the switch again so p-track can recount them.

A task transition confirmation is tied to the exact task, status, linked resources, and association revisions shown. If the board says the task or linked resources changed, the status was not updated. Close the stale prompt, refresh the workspace, inspect the current task and live resources, then request the transition again.

Desktop reopened wrong, or the window is misplaced

If p-track reopened a project you did not expect, turn off Reopen the last project when p-track starts in Settings ▸ Startup; if it landed on the Projects screen instead, look for the recent entry marked Preselected — that is the project p-track recorded, and it moved, because p-track never opens a relocated project on its own. Confirm its new location yourself with Locate… on it. A window restored onto a display that is no longer connected is recentered on the primary display automatically, so no reset is needed for that case.

When the sidebar, panels, or window geometry are unusable, use Settings ▸ Data & Diagnostics ▸ Reset Window Layout. It restores the default window and layout immediately and touches nothing else. Reach for Reset Application State only when you accept losing every setting and saved terminal workspace; plans, tasks, notes, and Recent projects are not touched. If you close the window while an operation is still running, p-track keeps the window open, says it could not close yet, and leaves every service, including updates, usable; try again once the operation finishes. Quitting with Cmd+Q stops terminals and agents with a bounded wait before the app exits. Stored window and layout records that p-track cannot read are reported and replaced by defaults in memory, not overwritten, so an unreadable record left by a newer version survives a downgrade.

Terminal recovery

Restored tabs and split descriptors start as stopped panes. Opening one creates a new session. The prior process, terminal contents, output, and scrollback are not restored.

Control	Use it for	Boundary
Restart terminal	An ordinary pane with a failed or exited process or stream.	Closes the old session and creates a fresh one.
Relaunch linked agent	A linked-agent pane that stopped.	Launch again from its plan or task; ordinary restart is intentionally unavailable so fresh authority can be bound.
Retry terminal renderer	A selected, visible pane using the fallback renderer.	Rebuilds rendering without restarting the PTY.
Force stop terminal	A selected current session that cannot stop normally.	Requires confirmation and targets that session.
Reset terminal workspace	A repaired or discarded layout that remains unusable.	Replaces the saved layout and terminates every live session represented by the workspace.

Terminal diagnostics are content-free: they report bounded process, stream, renderer, layout, update-time, retry, and repair state. They do not include terminal output, commands, clipboard text, environment values, credentials, or stream URLs. See terminal diagnostics and recovery.

Agents, associations, and stale runs

After a Desktop restart, a previously launched agent is marked stale because its hosting terminal ended and the new process cannot know its outcome. Relaunch it from the intended plan or task. An external agent may resume heartbeats only with its existing lease token; otherwise its lease expires and the run becomes stale.

An association provides validated project, plan, or task context. It grants no task, filesystem, network, command, or Git authority.
A worktree claim only records a verified, existing host-observed worktree that contains the run's working directory. It does not create a worktree, move the agent, change its CWD, or run Git.
A handoff is a bounded proposal and preview. Sending or acknowledging it grants no authority and changes no task or project memory.
A workflow proposal remains a proposal when approved. It executes no command, Git or hosting action, or task change.

When one of these actions is rejected as stale, refresh Overview and repeat it against the current live run and association revision. Read the full authority boundary summary.

Updater recovery

If the updater enters recovery-required state, close p-track and preserve the update state under $PTRACK_HOME/updates or ~/.ptrack/updates. On Linux, keep every .pending-apply-*.json journal with its sibling .ptrack-backup-* executable until the installed target is identified. Settings ▸ Data & Diagnostics reports those paths and the recovery-required status read-only, so you can confirm the state before closing the app.

Do not delete a journal or backup, and do not copy a staged payload into place. Reinstall the same or a newer package from the official GitHub Releases page as the conservative fallback. The update recovery guide describes the artifacts and platform-specific boundary.

Frequently asked corrections

Does selecting a plan in the Desktop sidebar change the CLI active plan?: Yes. Choosing a plan makes it your current plan, exactly as ptrack plan use <id> does, so ptrack next and agents follow it. A plan claimed by someone else, or a done or archived plan, cannot become current.
Does p-track check for updates automatically?: Not by default. Automatic checks remain off until you explicitly opt in from Settings ▸ Updates or About & Updates; a manual check does not silently download or install.
Why did an OS notification not appear?: Each category is off by default under Settings ▸ Notifications, and notifications are suppressed while any p-track window is focused. Check the operating system's notification permission for p-track. Linux also needs a running desktop notification service. Permission denial or an unavailable service does not interrupt agent tracking.
Does Reset Application State delete my plans or tasks?: No. It clears settings, the startup, notification, and update-check opt-ins, window and layout state, and saved terminal workspaces. Plans, tasks, notes, and Recent projects are not touched.
Does ptrack backup capture everything, and can p-track restore it?: No. It copies the project database, not runtime state or WebView localStorage, and there is no built-in restore command. Follow the documented backup limits; this page does not prescribe an unverified restore procedure.
Are interactive terminal paths verified on every platform?: No. End-to-end clipboard, shortcut, context-menu, restart, and shutdown acceptance is verified on macOS only. Windows and Linux implementations exist, but this Help Center does not claim those interactive paths passed end to end.