@backburner/cli 0.1.4 → 0.1.7

package/README.md

@@ -1,154 +1,138 @@
-# Backburner CLI
+# Backburner
 
-Backburner is a local GitHub-driven agent orchestration CLI. It uses GitHub labels, issues, and pull requests as the control plane, keeps configuration and state as readable JSON on your machine, and dispatches eligible work to provider CLIs that you already have installed locally.
+Backburner turns GitHub issues into reviewable pull requests using coding agents running on your own machine.
 
-Backburner supports:
+Open an issue from your phone, get back to your day, and manage the work through GitHub comments, labels, and PR reviews. Your computer does the planning, coding, testing, committing, and pushing through the agent CLIs and credentials you already use. GitHub is the control plane; your computer is the worker.
 
-- `backburner init` for interactive or non-interactive local setup
-- `backburner run` for one orchestration cycle
-- `backburner run-loop` for repeated cycles on a fixed interval
-- `backburner journal` for reading persisted run and workflow events
-- `backburner broker` for a local GitHub broker MCP endpoint
-- a plan-first label workflow for product approval, plan approval, review requests, and parent-branch sync approval
-- local provider CLIs for Antigravity, Codex, Gemini, Claude, and OpenCode
+## How it works
 
-## Prerequisites
+1. You open an issue in a repository managed by Backburner.
+2. A product agent can clarify the problem and propose a product direction in the issue.
+3. Once product direction is approved, Backburner creates an isolated git worktree and a planning PR with a Product Spec and implementation plan.
+4. You approve the plan with a GitHub label. Local agents implement it, run the repository's checks, commit, and push.
+5. You review comments, request changes, and merge from GitHub—including from your phone.
 
-- Node.js `>=20`
-- npm
-- git
-- GitHub CLI authenticated for the account and repositories you want Backburner to manage:
+Backburner never silently merges the final PR. You remain in control of approvals and the merge.
 
-```sh
-gh auth status
-```
+## Quick start
 
-- at least one supported provider CLI on `PATH`: `agy`, `codex`, `gemini`, `claude`, or `opencode`
+You need Node.js 20 or newer, `git`, an authenticated [GitHub CLI](https://cli.github.com/), and at least one supported agent CLI on your `PATH`: `agy`, `codex`, `gemini`, `claude`, or `opencode`.
 
-Backburner uses your local `git`, `gh`, and provider CLI credentials. It does not provide hosted execution or cloud credentials.
+Install Backburner from npm:
 
-## Install
+~~~sh
+npm install --global @backburner/cli
+gh auth status
+backburner init
+~~~
 
-From a source checkout:
+Onboarding walks you through:
 
-```sh
-npm install
-npm run build
-node dist/src/cli/run.js init
-```
+- checking Node.js, `git`, GitHub authentication, and local write access;
+- choosing the directories Backburner will use;
+- creating a private `backburner-demo` repository or selecting existing repositories;
+- detecting your installed agent CLIs and configuring models and roles;
+- writing readable local configuration; and
+- creating the configured Backburner labels in each selected repository.
 
-Windows PowerShell:
-
-```powershell
-npm install
-npm run build
-node .\dist\src\cli\run.js init
-```
+When onboarding finishes:
 
-For active local development, link this checkout into your global npm bin directory:
+1. Open the first configured repository—usually `backburner-demo` if you created it.
+2. Follow the printed prefilled issue link or scan the QR code, then submit the issue.
+3. Back on your Mac, start Backburner and leave it running:
 
-```sh
-npm run link:local
-backburner init
-```
-
-To install and verify the locally packed package:
+~~~sh
+backburner run
+~~~
 
-```sh
-npm run install:local
-backburner journal --json
-```
+That is the handoff. Keep the Mac awake and online, and continue from GitHub on your phone while local agents do the work. The interactive terminal UI runs an initial cycle automatically and keeps polling; you do not need to press `r`.
 
-To install the local package into a temporary npm prefix:
+For an unattended terminal without the interactive UI:
 
-macOS/Linux:
+~~~sh
+backburner run-loop --headless --interval-minutes 5
+~~~
 
-```sh
-npm run install:local -- --prefix /tmp/backburner-local
-/tmp/backburner-local/bin/backburner journal --json
-```
+The prefilled first issue includes the configured product-approval label, so it enters the Product Spec and planning path immediately. An ordinary unlabeled issue starts with Product Discovery instead.
 
-Windows PowerShell:
+## Before onboarding a real repository
 
-```powershell
-npm run install:local -- --prefix "$env:TEMP\backburner-local"
-& "$env:TEMP\backburner-local\backburner.cmd" journal --json
-```
+Backburner intentionally gives coding agents meaningful access to selected repositories. Before you run it:
 
-Install from npm:
+- select only repositories whose code and issue content you trust;
+- keep `allowedUsers` limited to GitHub users you trust to trigger agent work;
+- understand the permission mode used by each provider CLI;
+- expect prompts, repository content, and tool results to be sent to the configured model provider;
+- treat `~/.backburner/outputs` as sensitive because state, journal entries, and logs can contain repository and provider output; and
+- start with the private demo repository if you want to observe the workflow before granting access to production code.
 
-```sh
-npm install -g @backburner/cli
-backburner init
-```
+Local execution means the worker and credentials stay on your machine; it does not mean the workflow is offline or that model providers never receive code. See [SECURITY.md](SECURITY.md) for the threat model, trust boundaries, and vulnerability-reporting process.
 
-The package bin is `backburner`.
+## What onboarding writes
 
-The npm package intentionally includes the compiled CLI under `dist/src`, `README.md`, `LICENSE`, and package metadata. Contributor docs and generated docs are kept in the source repository and are not part of the install tarball.
+By default, Backburner stores its data under `~/.backburner`:
 
-## Quick Start
+- code root: `~/.backburner/code`
+- management directory: `~/.backburner/management`
+- outputs directory: `~/.backburner/outputs`
+- state directory: `~/.backburner/outputs/state`
+- journal directory: `~/.backburner/outputs/journal`
+- log directory: `~/.backburner/outputs/logs`
+- onboarding workspaces directory: `<code-root>/_worktrees`
 
-Run onboarding:
+Set `BACKBURNER_ROOT` to change the root used for the default code, management, and outputs directories.
 
-```sh
-backburner init
-```
+Backburner writes two human-readable configuration files in the management directory:
 
-Source checkout equivalent:
+- `repos.json`: repositories, allowed GitHub users, and workflow labels
+- `agents.json`: enabled provider CLIs, models, roles, and capabilities
 
-```sh
-node dist/src/cli/run.js init
-```
+If either file already exists, interactive onboarding asks before overwriting it. Repository label creation is best-effort; if GitHub rejects a write, onboarding prints the labels page and exact names to create manually.
 
-Non-interactive setup accepts defaults:
+Non-interactive onboarding is available:
 
-```sh
+~~~sh
 backburner init --yes
-```
+~~~
+
+`--yes` accepts broad defaults: it selects discovered repositories, enables discovered providers, creates default agent configurations, and creates or updates labels. It does not create a private demo repository. Review the generated configuration before running Backburner.
 
 Useful `init` flags:
 
-```text
+~~~text
 --code-root <path>       Root where managed repos are cloned
 --management-dir <path>  Directory for configuration files
 --outputs-dir <path>     Directory for generated state, journal, and logs
 --log-dir <path>         Directory for execution logs
 --workspaces-dir <path>  Directory used by onboarding readiness checks
 --yes, -y                Accept defaults without prompts
-```
-
-`backburner init` checks local requirements, confirms `gh auth status`, discovers repositories, detects provider CLIs, attempts model-list discovery when supported by those CLIs, writes configuration, and creates the configured Backburner labels on each selected repository.
+~~~
 
-- `repos.json`
-- `agents.json`
+## GitHub control plane
 
-If either file already exists, onboarding asks before overwriting it. With `--yes`, defaults are accepted non-interactively, including selecting existing discovered repositories, enabling every discovered provider, creating strong and cheap agents for each one, and creating or updating labels on selected repositories. `--yes` does not create a private demo repository.
+Backburner uses configurable labels to turn GitHub into a small, phone-friendly workflow:
 
-Repository setup first asks whether to create a private Backburner demo repository, select existing repositories, or skip repository setup for now. When GitHub authentication is available, the private demo repository is the interactive default. Before choosing existing repositories, onboarding tells you that Backburner will create or update its labels on those repositories. In an interactive terminal, repository and provider selection use a checkbox picker: arrow keys move, space toggles, and enter confirms. Non-TTY sessions fall back to text input and accept comma-separated numbers. If you are authenticated with GitHub but do not want to onboard an existing local clone yet, onboarding can explicitly create a private `backburner-demo` repository and clone it under the configured code root.
+- `agentProductApproved` approves product direction and allows the worktree/PR flow to begin.
+- `agentPlanApproved` approves the implementation plan and allows implementation to run.
+- `agentReview` requests an explicit code review after the PR head SHA changes.
+- `agentSyncParentBranch` authorizes syncing a blocked parent branch from the default branch.
+- `agentInProgress`, `planBreakdownNeeded`, and `prepareForMerge` communicate other workflow states.
 
-Label creation is best-effort. If GitHub rejects a label write because of permissions or repository policy, onboarding continues and prints the repository labels URL plus the exact label names to create manually. The final summary prints the next `backburner run` command, a prefilled GitHub issue URL for the first configured repository, and a terminal QR code for opening that repository's issues page from a phone.
+The default label names are:
 
-## Default Directories
+- `backburner:product-approved`
+- `backburner:plan-approved`
+- `backburner:review`
+- `backburner:sync-parent-branch`
+- `backburner:in-progress`
+- `backburner:plan-breakdown-needed`
+- `backburner:prepare-for-merge`
 
-By default, Backburner stores data under `~/.backburner`:
-
-- code root: `~/.backburner/code`
-- management directory: `~/.backburner/management`
-- outputs directory: `~/.backburner/outputs`
-- state directory: `~/.backburner/outputs/state`
-- journal directory: `~/.backburner/outputs/journal`
-- log directory: `~/.backburner/outputs/logs`
-- onboarding workspaces directory: `<code-root>/_worktrees`
-
-Set `BACKBURNER_ROOT` to change the root used for the default code, management, and outputs directories.
-
-## Configuration
-
-Backburner configuration lives in the management directory.
+Custom names are supported in `repos.json` and are used in generated plans and PR instructions.
 
 Minimal `repos.json`:
 
-```json
+~~~json
 {
   "allowedUsers": [
     "your-github-user"
@@ -173,11 +157,15 @@ Minimal `repos.json`:
     }
   ]
 }
-```
+~~~
+
+`allowedUsers` limits which GitHub users can feed issues, comments, reviews, and pull requests into task derivation. It is a trust allowlist, not a sandbox. `localPath` must be relative to `--code-root`.
+
+## Agent configuration
 
 Minimal `agents.json`:
 
-```json
+~~~json
 {
   "agents": [
     {
@@ -209,125 +197,103 @@ Minimal `agents.json`:
     }
   ]
 }
-```
-
-`allowedUsers` limits which GitHub users can feed issues, comments, reviews, and pull requests into task derivation. `localPath` must be relative to `--code-root`.
-
-Agent selection filters enabled agents by required role and `modelClass`, then breaks ties by lowest agent `id`. Provider model names are passed through to the provider CLI and are not validated against vendor catalogs. During onboarding, model setup shows discovered model options when available, marks strong and cheap defaults, and pressing enter accepts the default. Backburner prefers discovered `sol` for strong, `terra` for balanced/default, and `luna` for cheap model names; Codex defaults are `sol` and `luna`. OpenCode may use discovered OpenRouter model IDs such as `openrouter/openai/gpt-5.6-sol` and `openrouter/openai/gpt-5.6-luna`.
+~~~
 
-## Label Control Plane
+Agent selection filters enabled agents by role and `modelClass`, then breaks ties by the lowest agent ID. Model names are passed through to the provider CLI and are not validated against vendor catalogs.
 
-Configure labels per repository in `repos.json`. The workflow labels are:
+## Commands
 
-- `agentProductApproved`: approves product discovery and allows Backburner to create the implementation PR/worktree flow for an issue
-- `agentPlanApproved`: approves an implementation plan and allows implementation tasks to run
-- `agentReview`: requests an explicit code review; review tasks are dispatched when the PR has this label and its head SHA changed since the last review
-- `agentSyncParentBranch`: authorizes Backburner to sync a blocked parent implementation branch from the repository default branch
+Start the persistent interactive terminal UI:
 
-Backburner also uses `agentInProgress`, `planBreakdownNeeded`, and `prepareForMerge` when those labels are configured. Onboarding writes `repos.json` with these label values by default: `backburner:product-approved`, `backburner:plan-approved`, `backburner:review`, `backburner:in-progress`, `backburner:plan-breakdown-needed`, `backburner:sync-parent-branch`, and `backburner:prepare-for-merge`. It creates or updates the configured labels through `gh label create --force`. Custom label names, including older unprefixed names, are supported when configured in `repos.json`.
+~~~sh
+backburner run
+~~~
 
-## Commands
+Run exactly one orchestration cycle:
 
-Run one cycle:
+~~~sh
+backburner run --once
+~~~
 
-```sh
-backburner run
-```
+Run continuously without the interactive UI:
 
-Source checkout:
+~~~sh
+backburner run-loop --headless --interval-minutes 5
+~~~
 
-```sh
-node dist/src/cli/run.js run
-```
+`run-loop` also accepts `--interval-seconds <seconds>`. Its default interval is five minutes. `SIGINT` and `SIGTERM` request a graceful stop after the current cycle.
 
-Common run flags:
+Common path flags:
 
-```text
+~~~text
 --code-root <path>
 --management-dir <path>
 --outputs-dir <path>
 --log-dir <path>
 --broker-port <port>
---headless
---once
-```
+~~~
 
-Run continuously:
+Read the persisted journal:
 
-```sh
-backburner run-loop --interval-minutes 5
-```
-
-`run-loop` accepts the same path and broker flags as `run`, plus either `--interval-seconds <seconds>` or `--interval-minutes <minutes>`. The default interval is 5 minutes. `SIGINT` and `SIGTERM` request a graceful stop after the current cycle.
-
-Read the journal:
-
-```sh
+~~~sh
 backburner journal --last 20
 backburner journal --repo your-github-user-example-repo --json
-```
+~~~
 
-Journal filters:
+Start the standalone local GitHub broker MCP endpoint:
 
-```text
---outputs-dir <path>
---repo <id>
---workstream <id>
---issue <number>
---pr <number>
---since <ISO timestamp>
---last <number>
---json
---verbose
-```
-
-Start the GitHub broker MCP:
-
-```sh
+~~~sh
 backburner broker --port 4444
-```
+~~~
 
-Broker flags:
+The normal orchestrator starts its own broker on loopback. The standalone broker supports `--host` and `--port` and serves `POST /mcp` and `GET /health`. Do not expose it to an untrusted network.
 
-```text
---management-dir <path>
---host <host>
---port <port>
-```
-
-The broker serves:
-
-- `POST /mcp`
-- `GET /health`
-
-It exposes managed-repository tools for issue, PR, comment, check-run, code-search, PR creation, and PR review-comment reply workflows, plus plan-breakdown and wave-assessment tools used by Backburner providers.
+## What a run does
 
-Smoke-test the broker after building:
+Each cycle loads configuration and state, syncs enabled repositories, scans GitHub through `gh`, derives eligible tasks, starts a local GitHub broker for provider access, dispatches work to provider CLIs, and writes state, journal events, and execution logs.
 
-```sh
-npm run smoke:github-broker
-npm run smoke:github-broker -- --repo your-github-user/example-repo --issue-number 123
-```
+Backburner uses isolated git worktrees as implementation units. Generated control-plane state is readable JSON under `<outputs-dir>/state`; execution logs and artifacts are under `<outputs-dir>/logs`; journal events are under `<outputs-dir>/journal`.
 
-## What A Run Does
+## Install from source
 
-`backburner run` loads configuration, prepares local management and outputs directories, loads state, syncs enabled repositories, scans GitHub through `gh`, derives tasks, starts a local GitHub broker for provider access, dispatches eligible tasks to configured provider CLIs, writes state and logs, and prints a run summary.
+~~~sh
+git clone https://github.com/eladav/backburner.git
+cd backburner
+npm install
+npm run build
+npm link
+backburner init
+~~~
 
-Generated files are readable JSON. Control-plane state is written under `<outputs-dir>/state`, including repository sync status, issues, PRs, comments, tasks, worktrees, attention records, MCP status, provider limits, and job memory. Execution logs and artifacts are written under `<outputs-dir>/logs`. Journal events are written under `<outputs-dir>/journal`.
+Windows PowerShell:
 
-## Platform Support
+~~~powershell
+npm install
+npm run build
+npm link
+backburner init
+~~~
 
-Backburner is intended to run on macOS, Linux, and Windows with Node.js 20 or newer. The CI workflow runs on Ubuntu, macOS, and Windows with Node 20 and 22, and includes build, typecheck, tests, package dry-run, and local package install smoke checks.
+## Platform support
 
-## Verification
+Backburner is intended for macOS, Linux, and Windows with Node.js 20 or newer. It is currently used on macOS. Automated CI runs the build, typecheck, tests, package dry-run, and local-install smoke checks on Ubuntu and Windows with Node.js 20 and 22.
 
-Use these checks before publishing or changing behavior:
+## Development and verification
 
-```sh
+~~~sh
+npm install
 npm run build
 npm run typecheck
 npm test
 npm pack --dry-run
-```
+~~~
+
+The npm package includes the compiled CLI under `dist/src`, `README.md`, `SECURITY.md`, `LICENSE`, and package metadata.
+
+## Security
+
+Please read [SECURITY.md](SECURITY.md) before granting Backburner access to important repositories. Report suspected vulnerabilities privately using the process described there.
+
+## License
 
-For docs-only changes, at minimum verify that documented commands, package contents, and public-safety scrub patterns still match the repository.
+[MIT](LICENSE)

package/SECURITY.md

@@ -0,0 +1,146 @@
+# Security Policy
+
+Backburner coordinates coding agents that run on your machine with access to source code, local tools, GitHub credentials, and model-provider credentials. That is the product's core capability and its primary security boundary.
+
+Read this document before granting Backburner access to an important repository.
+
+## Reporting a vulnerability
+
+Please do not disclose a suspected vulnerability in a public issue, discussion, pull request, or Hacker News thread.
+
+Use GitHub's private vulnerability reporting for this repository when it is available. If the repository does not show a **Report a vulnerability** option on its Security page, open a public issue containing only a request for a private security contact channel—do not include exploit details, secrets, affected repository names, or logs.
+
+Include, when possible:
+
+- the affected Backburner version and operating system;
+- the impact and the trust boundary that was crossed;
+- minimal reproduction steps;
+- whether credentials or private repository data may have been exposed; and
+- any suggested mitigation.
+
+You should receive an acknowledgement within seven days. This is a best-effort policy for a pre-1.0 open source project, not a service-level agreement.
+
+## Supported versions
+
+Backburner is pre-1.0. Security fixes are applied to the latest published version and the current default branch. Older versions are not supported unless a release note explicitly says otherwise.
+
+## Threat model
+
+### Assets to protect
+
+- GitHub authentication available through `gh`
+- provider credentials and any other environment variables inherited by local subprocesses
+- private repository source, history, issues, comments, and pull requests
+- the integrity of branches, commits, comments, labels, and pull requests
+- the developer machine and files reachable by provider tools
+- local Backburner configuration, state, journal entries, and execution logs
+
+### Trusted components and people
+
+Backburner assumes that you trust:
+
+- the machine and operating-system account running it;
+- the selected repositories and their existing build/test tooling;
+- the GitHub users listed in `allowedUsers`;
+- the installed `git`, `gh`, Node.js, npm, and provider CLIs;
+- the configured model providers and the accounts used to reach them; and
+- the npm package or source revision you installed.
+
+If any of these are compromised, Backburner is not designed to contain that compromise.
+
+### Untrusted input
+
+Treat all of the following as potentially adversarial:
+
+- issue bodies, comments, PR descriptions, reviews, code, and repository documentation;
+- generated model output;
+- dependency install scripts, test commands, git hooks, and other repository tooling;
+- MCP/tool responses and provider output; and
+- network traffic that can reach a broker bound outside loopback.
+
+GitHub content can contain prompt-injection instructions. `allowedUsers` reduces who can feed content into task derivation, but it does not make that content safe and it is not an operating-system sandbox.
+
+### Current security controls
+
+- Repositories must be explicitly configured and enabled.
+- GitHub actors are filtered through `allowedUsers` before their issues, PRs, comments, reviews, or label actions drive normal workflow decisions.
+- Product approval, plan approval, review, parent-sync, and merge-preparation actions use configurable labels.
+- Implementation happens in dedicated git worktrees instead of directly in the primary checkout.
+- GitHub operations are routed through the authenticated `gh` CLI and constrained to configured repositories by Backburner's gateway and broker services.
+- The orchestrator's broker binds to `127.0.0.1` by default.
+- Read-only and workspace-write tasks are distinguished and mapped to provider-specific modes.
+- Backburner creates and updates branches and pull requests, but does not silently perform the final merge.
+- Configuration and state remain readable local JSON so operators can inspect them.
+
+These are defense-in-depth controls, not a guarantee that an agent cannot make a harmful change.
+
+### Important limitations
+
+#### Coding-agent permissions
+
+Workspace-write tasks are intentionally powerful. Depending on the provider, Backburner may select modes that allow unattended edits and command execution—for example Codex workspace-write, Claude `bypassPermissions`, or Gemini `yolo`. Provider implementations and semantics can change independently of Backburner.
+
+An agent can run repository commands, and those commands can execute arbitrary code available to your user account. Backburner is not a virtual machine or a security sandbox. Use a dedicated machine, operating-system account, container, or VM when you need a stronger boundary.
+
+#### Credentials and environment
+
+Local subprocesses normally inherit the Backburner process environment. Avoid launching Backburner from a shell containing unrelated long-lived secrets. Prefer narrowly scoped GitHub and provider credentials, enable MFA, and periodically review active tokens and sessions.
+
+#### Model-provider data
+
+Local-first does not mean offline. Prompts can include source code and GitHub content, and provider CLIs may send them to third-party services under those providers' terms, retention settings, and account policies. Do not onboard a repository whose data policy forbids that transfer.
+
+#### Local broker
+
+The HTTP broker has no application-level authentication. Its default loopback binding is the expected trust boundary. Do not run `backburner broker --host 0.0.0.0`, publish its port, place it behind a public tunnel, or expose it to an untrusted local network.
+
+Other processes running as your user may be able to reach a loopback service. If your local account is not trusted, use a separate account or stronger isolation.
+
+#### Logs and persisted state
+
+Files under `~/.backburner` can include repository paths, issue and PR content, agent output, errors, and command results. Restrict filesystem access to your user, do not commit this directory, redact logs before sharing them, and remove it securely when retiring the installation.
+
+#### Generated code
+
+Backburner does not guarantee that generated changes are correct or secure. Keep repository branch protection and CI checks enabled, review the diff, and own the final merge decision.
+
+## Safe onboarding checklist
+
+Before the first real run:
+
+1. Start with the private demo repository.
+2. Review the repositories and `allowedUsers` in `repos.json`.
+3. Review the configured provider commands, models, and roles in `agents.json`.
+4. Confirm what data each provider CLI sends remotely and what permission mode it uses.
+5. Remove unrelated secrets from the launching shell environment.
+6. Confirm the configured code, management, output, and log directories are private to your user.
+7. Keep the broker on its default loopback address.
+8. Keep branch protection, required CI, and human review on important repositories.
+9. Leave final merging to a trusted human.
+
+## Repository and package supply chain
+
+For maintainers:
+
+- require MFA for GitHub and npm maintainer accounts;
+- use branch protection or repository rulesets for the default branch once public;
+- enable private vulnerability reporting, dependency alerts, secret scanning, and push protection where available;
+- review lockfile changes and keep `npm audit` results visible;
+- publish releases from a protected GitHub Actions workflow using npm trusted publishing or `npm publish --provenance`;
+- tag each published npm version and attach release notes to the same commit;
+- keep workflow permissions minimal and pin or deliberately review third-party actions; and
+- never publish from a dirty working tree.
+
+npm provenance makes the package's source and build origin verifiable. It does not prove the source is benign or remove the need for review.
+
+## Out of scope
+
+The following are not security vulnerabilities by themselves:
+
+- a model producing incorrect, insecure, or low-quality code without crossing an advertised security boundary;
+- provider rate limits, exhausted budgets, or unavailable third-party services;
+- actions performed by a GitHub user intentionally listed in `allowedUsers`;
+- damage caused by intentionally running a malicious repository's own scripts with agent write permissions; or
+- disclosure that is already inherent in sending configured repository context to the chosen model provider.
+
+Reports showing a bypass of repository scoping, actor filtering, task permission gates, broker boundaries, or credential isolation are in scope.

package/dist/src/agents/antigravity-launch.js

@@ -28,7 +28,7 @@ export function buildAntigravityCliArgs(options) {
     else {
         args.push("--dangerously-skip-permissions");
     }
-    args.push("--print", "-");
+    args.push("--print", options.promptText);
     return args;
 }
 export async function writeAntigravitySettings(settingsPath, options) {

package/dist/src/agents/antigravity.js

@@ -64,7 +64,8 @@ export class AntigravityCliAgent {
             ...(agentConfig.model ? { model: agentConfig.model } : {}),
             ...(resumeConversationId ? { conversationId: resumeConversationId } : {}),
             printTimeout: this.printTimeout,
-            logFilePath
+            logFilePath,
+            promptText
         });
         this.logger?.info(JSON.stringify({
             component: "antigravity-launch",
@@ -102,7 +103,6 @@ export class AntigravityCliAgent {
             }
             const result = await this.options.commandRunner.run(agentConfig.command, args, {
                 cwd,
-                input: promptText,
                 env: getAntigravityEnvOverrides(),
                 timeoutMs: this.timeoutMs
             });

package/dist/src/onboarding/steps/show-summary.js

@@ -68,19 +68,21 @@ export class ShowSummaryStep {
             const issueTarget = buildFirstIssueTarget(ctx);
             lines.push("");
             lines.push("Next steps:");
-            lines.push("  1. Start the orchestrator:");
-            lines.push(`     ${buildRunCommand(ctx)}`);
             if (issueTarget !== undefined) {
-                lines.push("  2. Open a Backburner issue:");
+                lines.push("  1. Open and submit your first Backburner issue:");
                 lines.push(`     ${issueTarget.prefilledIssueUrl}`);
-                lines.push("  3. Watch Backburner pick it up on the next orchestration cycle");
+                lines.push("  2. Start the orchestrator and leave it running:");
+                lines.push(`     ${buildRunCommand(ctx)}`);
+                lines.push("  3. Continue from GitHub on your phone while this machine does the work");
                 lines.push("");
                 lines.push("Repository issues QR:");
                 lines.push(renderQr(issueTarget.repositoryIssuesUrl));
             }
             else {
-                lines.push("  2. Add a repository to repos.json");
-                lines.push("  3. Open an issue on a managed repo with the configured product-approved label");
+                lines.push("  1. Add a repository to repos.json");
+                lines.push("  2. Open an issue on a managed repo with the configured product-approved label");
+                lines.push("  3. Start the orchestrator and leave it running:");
+                lines.push(`     ${buildRunCommand(ctx)}`);
             }
         }
         else {

package/dist/src/worktrees/service.js

@@ -24,7 +24,7 @@ export class ImplementationWorkflowService {
         const existing = input.existingWorktrees.find((worktree) => worktree.repoId === input.repo.id && worktree.issueNumber === input.issue.number) ??
             input.existingWorktrees.find((worktree) => worktree.repoId === input.repo.id && worktree.branchName === branchName);
         if (existing) {
-            const preparedPaths = await preparePlanDocuments(existing.path, input.issue, input.decision, existing.branchName);
+            const preparedPaths = await preparePlanDocuments(existing.path, input.issue, input.decision, existing.branchName, input.repo.labels.agentPlanApproved);
             return {
                 worktree: {
                     ...existing,
@@ -45,7 +45,7 @@ export class ImplementationWorkflowService {
         const worktreePath = this.gitGateway.validatePathWithinCodeRoot(input.codeRoot, buildWorktreeRelativePath(input.repo, input.issue.number));
         const startPoint = input.repo.defaultBranch ? `origin/${input.repo.defaultBranch}` : "origin/HEAD";
         const createdPath = await this.gitGateway.createWorktree(input.repoPath, input.codeRoot, worktreePath, branchName, startPoint);
-        const preparedPaths = await preparePlanDocuments(createdPath, input.issue, input.decision, branchName);
+        const preparedPaths = await preparePlanDocuments(createdPath, input.issue, input.decision, branchName, input.repo.labels.agentPlanApproved);
         const timestamp = this.now();
         return {
             created: true,
@@ -91,7 +91,7 @@ export class ImplementationWorkflowService {
                 headBranch: worktree.branchName,
                 baseBranch,
                 title: buildPullRequestTitle(issue),
-                body: buildPullRequestBody(issue, worktree)
+                body: buildPullRequestBody(issue, worktree, repo.labels.agentPlanApproved)
             });
             const timestamp = this.now();
             return {
@@ -153,6 +153,7 @@ export class ImplementationWorkflowService {
                     packet,
                     waveIndex,
                     branchName,
+                    planApprovalLabel: repo.labels.agentPlanApproved,
                     now: this.now,
                     existingPaths: {
                         planDocumentPath: existing.planDocumentPath,
@@ -186,6 +187,7 @@ export class ImplementationWorkflowService {
                 packet,
                 waveIndex,
                 branchName,
+                planApprovalLabel: repo.labels.agentPlanApproved,
                 now: this.now
             });
             const timestamp = this.now();
@@ -243,7 +245,12 @@ export class ImplementationWorkflowService {
                 headBranch: worktree.branchName,
                 baseBranch,
                 title: buildPacketPullRequestTitle({ parentWorkstream, packetId: packet.id }),
-                body: buildPacketPullRequestBody({ parentWorkstream, packet, worktree })
+                body: buildPacketPullRequestBody({
+                    parentWorkstream,
+                    packet,
+                    worktree,
+                    planApprovalLabel: repo.labels.agentPlanApproved
+                })
             });
             const timestamp = this.now();
             return {
@@ -555,7 +562,7 @@ export function buildPacketWorktreeRelativePath(input) {
     const { type, number } = input.parentWorkstream.origin;
     return path.join(WORKTREE_ROOT_DIR, slugify(owner), slugify(name), `workstream-${type}-${number}`, `packet-${getPacketSlug(input.packetId)}`);
 }
-async function preparePlanDocuments(worktreePath, issue, decision, branchName) {
+async function preparePlanDocuments(worktreePath, issue, decision, branchName, planApprovalLabel) {
     const relativePaths = buildAgentDocumentRelativePaths(issue.number, branchName);
     const planDocumentPath = path.join(worktreePath, relativePaths.planDocumentPath);
     const productSpecDocumentPath = path.join(worktreePath, relativePaths.productSpecDocumentPath);
@@ -575,6 +582,7 @@ async function preparePlanDocuments(worktreePath, issue, decision, branchName) {
             "",
             "## Notes",
             "- Planning document created by the orchestrator workflow.",
+            `- Implementation must not begin until the \`${planApprovalLabel}\` label is present.`,
             ""
         ].join("\n"), "utf8");
     }
@@ -593,7 +601,7 @@ async function preparePlanDocuments(worktreePath, issue, decision, branchName) {
     };
 }
 async function preparePacketPlanDocuments(input) {
-    const { worktreePath, parentWorkstream, packet, branchName, now, existingPaths } = input;
+    const { worktreePath, parentWorkstream, packet, branchName, planApprovalLabel, now, existingPaths } = input;
     const relativePaths = existingPaths
         ? undefined
         : buildPacketAgentDocumentRelativePaths(packet.id, branchName);
@@ -627,7 +635,7 @@ async function preparePacketPlanDocuments(input) {
             "",
             "## Notes",
             `- This is a packet planning PR targeting \`${integrationBranch}\`.`,
-            "- Implementation must not begin until the `agent-plan-approved` label is present.",
+            `- Implementation must not begin until the \`${planApprovalLabel}\` label is present.`,
             ""
         ].join("\n"), "utf8");
     }
@@ -658,7 +666,7 @@ function compareWorktrees(left, right) {
 function buildPullRequestTitle(issue) {
     return `agent: plan for issue #${issue.number} - ${issue.title}`;
 }
-function buildPullRequestBody(issue, worktree) {
+function buildPullRequestBody(issue, worktree, planApprovalLabel) {
     const planPath = toRepoRelativePath(worktree.path, worktree.planDocumentPath);
     const productSpecPath = worktree.productSpecDocumentPath
         ? toRepoRelativePath(worktree.path, worktree.productSpecDocumentPath)
@@ -672,7 +680,7 @@ function buildPullRequestBody(issue, worktree) {
         ...(productSpecPath ? [`- Product Spec: \`${productSpecPath}\``] : []),
         `- Plan document: \`${planPath}\``,
         `- Agent log: \`${logPath}\``,
-        "- Implementation must not begin until the `agent-plan-approved` label is present."
+        `- Implementation must not begin until the \`${planApprovalLabel}\` label is present.`
     ].join("\n");
 }
 function buildPacketPullRequestTitle(input) {
@@ -683,7 +691,7 @@ function buildPacketPullRequestTitle(input) {
     return `agent: plan packet ${packetId} for ${source}`;
 }
 function buildPacketPullRequestBody(input) {
-    const { parentWorkstream, packet, worktree } = input;
+    const { parentWorkstream, packet, worktree, planApprovalLabel } = input;
     if (!worktree.packet)
         throw new Error("Missing packet metadata");
     const planPath = toRepoRelativePath(worktree.path, worktree.planDocumentPath);
@@ -710,7 +718,7 @@ function buildPacketPullRequestBody(input) {
         ...packet.dependsOn.map((d) => `- ${d}`),
         "",
         "This PR was created by the orchestrator as a packet planning PR.",
-        "Implementation must not begin until the `agent-plan-approved` label is present."
+        `Implementation must not begin until the \`${planApprovalLabel}\` label is present.`
     ].join("\n");
 }
 function buildAgentDocumentRelativePaths(issueNumber, branchName) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backburner/cli",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "type": "module",
   "description": "Local GitHub-based agent orchestration CLI",
   "license": "MIT",
@@ -25,7 +25,8 @@
   },
   "files": [
     "dist/src",
-    "README.md"
+    "README.md",
+    "SECURITY.md"
   ],
   "bin": {
     "backburner": "dist/src/cli/run.js"
@@ -39,7 +40,7 @@
     "link:local": "npm run build && npm link",
     "install:local": "node scripts/install-local-package.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && node --import ./dist/test/setup.js --test --test-concurrency=1 dist/test/*.test.js",
+    "test": "npm run build && node scripts/run-tests.mjs",
     "run:backburner": "node dist/src/cli/run.js run",
     "run:github-broker": "node dist/src/cli/run.js broker",
     "smoke:github-broker": "node dist/src/cli/run.js broker-smoke",