Skip to content
Pocketto
Core & Enterprise

Recovery and rollback

Fix lifecycle problems forward without destroying state: when to repair, drain, disable, or replay, and why local commits and pending events survive.

Recovery in Pocketto follows one rule: fix forward without destroying state. Local commits and pending events survive almost every failure mode.

Projection write failure

If a projection write fails after the authoritative lifecycle commit, the error is PROJECTION_REPAIR_REQUIRED with the committed event and revision identified. The repair order is:

npx -y pocketto-pi lifecycle repair <spec_dir> --json --contract 3
npx -y pocketto-pi lifecycle drain <spec_dir> --json --contract 3

repair reconciles lifecycle-owned log.json projection fields while preserving task statuses, done_sha, corrections, and delivery state. It fails closed (LIFECYCLE_REPAIR_STATE_UNRECOVERABLE) when task state is unrecoverable. It never guesses. drain then replays the deferred event; it creates no new events.

Interrupted structuring

If structure was killed while writing execution-plan/ or log.json, re-run structure --reset on that plan before continuing. It rebuilds both from scratch and is the only way to guarantee they are back in sync. Do not hand-edit log.json to fix a partial write.

Disabling Enterprise

To disable a faulty or unwanted adapter without deleting Core or lifecycle state:

# read-only check first
node <package-root>/enterprise/cli.js preflight <project-root> --json
# remove ONLY the registration file
rm <project-root>/.pocket/lifecycle-adapter.json

What to preserve: .pocket-meta.json, log.json, lifecycle.json, pending lifecycle events, and remote markers. Local execution continues; pending events keep their original IDs.

A lifecycle drain while the registration is missing does not replay: the event stays pending, the drain reports adapter-unavailable, and no remote call is made.

Replaying after a fix

Replay only after the adapter is pinned to the last compatible v4 release or reinstalled:

npx -y pocketto-pi lifecycle drain <spec_dir> --json --contract 3

The replay uses the original event IDs, with no retrospective duplicates.

What never happens automatically

  • No automatic downgrade or destructive conversion of v4 state.
  • Active v3 plans stay on their v3 path (see Compatibility).
  • A terminal or attempts-exhausted event is never revived by editing lifecycle state: that is a manual-resolution boundary.
  • Never delete lifecycle.json, log.json, or .pocket-meta.json to "reset" Enterprise.

GH_UNKNOWN recovery (missing label)

If a spec-approved delivery reports GH_UNKNOWN, that alone is not evidence of a missing label. The documented recovery procedure for issue #70 verifies the origin, performs an exact read-only label lookup, and asks for your explicit consent before creating pocket-plan. This is a documented workaround, not a runtime fix. See Human authorization and the upstream procedure in the repository's skills/pocket-enterprise/references/issue-reconciliation.md.

Lifecycle events

Pocketto's neutral lifecycle event model: what lifecycle.json records, when each event is committed, and the four lifecycle CLI commands.

Human authorization

The decisions Pocketto always leaves to you, including consent, pushes, merges, issue closures, and label creation. These are guarantees, not settings.

On this page

Projection write failureInterrupted structuringDisabling EnterpriseReplaying after a fixWhat never happens automaticallyGH_UNKNOWN recovery (missing label)Related documentation