Recover an API task startup

Scope and prerequisites

Use the absolute path of the affected API worktree on Shipyard. Identify its owner and active writers. Never use the primary checkout as a substitute target.

Diagnose

Read .worktree/orca-task.json if present, and inspect .worktree/orca-setup.log / orca-api.log privately. Run the lifecycle status command. Missing state can mean first setup never completed, not that it is safe to reseed. Inspect docker ps and task-specific Compose status without printing interpolated secrets through docker compose config.

Classify the failure: package install, port conflict, database readiness, migration, authorization sync, CDC or application health. A lifecycle lock may mean another setup is legitimately running; do not delete the lock file. Confirm branch contains the reviewed worktree scripts and reload fix.

Repair

An initialized task may be restarted through orca-task.py setup --root "$TASK_ROOT" after fixing the identified cause. That path preserves data. A failed first attempt deliberately refuses automatic reseeding; preserve markers and logs, identify the incomplete stage and use the current repository’s recovery instructions before any explicit retry.

Do not remove orca-initial-setup, reset volumes, rerun arbitrary seed commands or kill unrelated writers to bypass a guard. Package failures use the access recipe. Database/authorization failures use the database recipe.

Verify and escalate

Confirm direct /health and the required application behavior. If schema/data recovery is necessary, document the target and preservation plan before proceeding. Source changes to lifecycle behavior belong to the application repository; this personal wrapper is not a replacement for its invariants.