Autopilot

Autopilot is the working watched-PR loop in Neondeck. Meaningful review feedback or failing checks can notify you, task a continuing Neon owner to prepare a focused commit, wait for your approval, or safely deliver the commit according to the watch's current mode. It continues watching the same PR after a successful delivery.

The loop is intentionally small. Each watched PR has one persistent pr-autopilot-owner Flue instance and one Neondeck-managed worktree, created lazily on the first actionable event that needs an owner. Later events and restarts reuse both identifiers. The Flue instance owns one continuing canonical conversation; the managed worktree and its local commits remain the source of truth for code.

Start a watched PR

You can enter the same typed service through three product surfaces:

  1. In the dashboard's GitHub PR list, choose watch. Open Active Watches and select the Autopilot mode for that row.
  2. Ask Neon, for example: “Put pandemicsyn/neondeck#521 on Autopilot in prepare-only mode and process the current feedback.” Neon uses neondeck_autopilot_configure_pr, not an ad hoc config edit.
  3. Use the CLI when you want the same operation directly:
neondeck watch-pr pandemicsyn/neondeck#521 \
  --mode prepare-only \
  --process-existing \
  --confirm-autopilot

The typed action takes an explicit mode and an explicit current-feedback choice: 

neondeck_autopilot_configure_pr
{
  "ref": "pandemicsyn/neondeck#521",
  "mode": "prepare-only",
  "processExisting": true,
  "confirm": true
}

Set processExisting to true to process actionable feedback already present when the watch starts. Set it to false to baseline current feedback and act only on later meaningful changes.

Modes and authority

notify-only

Records and notifies meaningful changes without starting an owner mutation turn. A new notify-only watch does not create its managed worktree merely to report an event.

prepare-only

Gives the watcher turn bounded read, edit, targeted-check, and commit tools. The result is a normal commit in the managed worktree for you to review. This mode never gives Autopilot a push tool.

autofix-with-approval

The watcher turn can prepare and commit but cannot push. When a commit is ready, the watch enters waiting and holds the worktree steady. Only a direct human message in that same owner conversation receives the bounded edit, check, commit, push, and PR-response tools for the approval turn.

autofix-push-when-safe

The only mode that can push from a watcher-generated turn. It adds a narrow safe-push tool and a PR-response tool to the prepare capabilities. Automatic push remains conditional on every setup and immediate safety prerequisite below.

Increasing authority requires confirmation

Every increase in mode rank—including the first move above notify-only—requires explicit confirmation. The Active Watches selector presents a separate confirm increase step. Neon may set confirm: true only after you explicitly approve the increase. Lowering authority does not require that confirmation, and a running turn rechecks current authority before an external effect.

Review and control a watch

Active Watches shows the current mode and the minimal loop status: watching, working, waiting, blocked, or complete. From the watch row you can:

  • choose review diff to inspect the committed worktree change against the exact PR head used to create the worktree;
  • choose review agent to open the durable pr-autopilot-owner conversation for that PR;
  • in approval mode while waiting, send a direct instruction such as “approved, push” or “approved, fix the typo, then push”;
  • pause or resume scheduler polling;
  • retry a visible blocked state after you inspect the PR, owner conversation, and retained worktree; and
  • stop the watch through its confirmation step. An active owner turn must settle before terminal cleanup can complete.

Approval is the direct human message itself. The minimal watch loop does not create a durable approval object, prepared-diff record, reviewed-SHA state machine, or workflow-per-transition chain. GitHub feedback cannot impersonate approval because watcher-generated approval-mode turns never receive push capability.

Product guarantees

These are enforced behavior of the current loop, independent of how you configure a particular repository:

  • The primary checkout is not modified. Autopilot works in the one managed worktree bound to the watched PR.
  • Current watch mode and turn source determine the actual tools supplied to the owner. Prompt text alone never grants capability.
  • Approval-mode watcher turns cannot push. Only a direct human turn while that owner is waiting can receive the approval-mode push tool.
  • Autonomous delivery always uses a non-force push bound to the expected current PR head. Neondeck does not silently rebase or force-push around a changed remote branch.
  • When autonomous delivery becomes uncertain after a commit is prepared, Neondeck retains that local commit, exposes a visible blocked state, and requires human review instead of expanding policy or guessing about an external effect.

Setup prerequisites for autonomous push

autofix-push-when-safe does not make a repository ready by itself. Immediately before push, all of these must be true:

  • At least one command is configured in the effective repository guardrails.requiredChecks, and every configured command can run unattended through the execution policy.
  • Every required command passes against the current committed worktree HEAD immediately before push.
  • GITHUB_TOKEN is valid for current PR facts and login identity; the repository's git remote also has valid push credentials, git identity, branch permissions, and destination access.
  • GitHub returns complete current facts, the remote PR head exactly matches the head used by the managed worktree, and direct push access is proven.
  • The watch is still autofix-push-when-safe and working, current guardrails allow the diff without a policy expansion, and the worktree is clean with a committed change.
  • The final operation is a non-force push of that exact commit, guarded by the expected remote head and bound GitHub identity.

Concrete required-check configuration

For this repository, npm run check and npm run docs:build are real package scripts. Ask Neon to set those exact checks for the configured neondeck repository and to preapprove the same exact local commands for unattended execution. Neon uses these current typed service inputs: 

neondeck_config_update_repo_autopilot_policy
{
  "repoId": "neondeck",
  "guardrails": {
    "requiredChecks": ["npm run check", "npm run docs:build"]
  }
}

neondeck_config_update_execution_policy
{
  "preapprovedCommands": [
    {
      "id": "neondeck-check",
      "command": "npm run check",
      "match": "exact",
      "backends": ["local"],
      "description": "Run the Neondeck fast verification suite."
    },
    {
      "id": "neondeck-docs-build",
      "command": "npm run docs:build",
      "match": "exact",
      "backends": ["local"],
      "description": "Build the Neondeck Astro documentation site."
    }
  ]
}

The repository policy service stores the required-check override under that repo's metadata.guardrails in repos.json and audits the config change. The execution-policy service updates config.json; it does not execute the commands. Choose checks appropriate to the repository—these Neondeck commands are an accurate example, not universal defaults. If custom preapprovals already exist, preserve them in the update because preapprovedCommands is the complete configured custom list.

Fail-closed behavior

After the owner prepares a commit, any of the following prevents an autonomous push and leaves the commit available for review in a visible blocked watch:

  • no configured required check, or any check fails or cannot run;
  • GitHub facts are incomplete, truncated, stale, or show a new head;
  • the watch mode or status changed before the external effect;
  • GitHub or git credentials, login identity, push permission, remote, or destination cannot be proven;
  • current guardrails deny the change or classify it as a policy expansion requiring human approval; or
  • the worktree changes during verification, the expected-head push is rejected, or another unexpected error makes the outcome uncertain.

Retry is deliberately explicit. Inspect the retained diff and owner conversation first, then use retry; Neondeck fetches current facts before another eligible owner turn. It does not create an automatic rebase, effect-reconciliation, or multi-stage recovery engine.

Restart and crash limitation

On startup, any watch left in working becomes blocked. Its owner id and worktree id are retained, and the notification asks you to inspect both before an explicit retry. This also covers the ambiguous case where a push may have succeeded just before the process crashed but Neondeck did not record settlement. Neondeck never infers that external outcome or speculatively repeats the push or PR response.

Completion and cleanup

After a push, Autopilot returns to polling for later feedback. When the PR is merged or closed, it waits for the watch's terminal checks to stop being pending, marks the watch complete, disables polling and direct owner turns, and cleans only eligible Neondeck-created worktrees. Adopted, dirty, or policy-retained worktrees remain for manual handling, and a cleanup failure stays visible.

The durable pr-autopilot-owner conversation is retained after completion or an explicit stop as the audit trail of current facts, human instructions, tool calls, approvals, and results. Neondeck does not delete that conversation merely because its disposable worktree is cleaned up.

Verification scope

The repository proves the minimal loop with automated coverage for mode capability ceilings, owner/worktree reuse, exact-head handling, direct human approval, safe-push gates, blocked restart recovery, and terminal cleanup. The available evidence is credential-free and uses fixtures or local test repositories; it is not evidence of a live external GitHub PR push smoke. Validate your own token, git remote, identity, permissions, policy, and required checks before enabling autonomous delivery.