# Operations, security, and development

## Operational behavior

A goal is autonomous only while `active`. Status checks can schedule an active idle goal; all other scheduling is settled-turn driven. The system pauses restored active snapshots, avoids duplicate follow-ups, and gives user/pending messages priority.

If a continuation cannot be sent, pi-let pauses the goal with the send error. A goal replacement, edit, judge change, archive, clear, pause, restore, or shutdown increments the runtime generation and aborts any in-flight evaluator. Late verifier/judge results are discarded when their captured id, revision, or generation no longer matches.

### Recovering a non-active goal

| State | What happened | Typical recovery |
| --- | --- | --- |
| `paused` | User action, restoration, or continuation-send failure. | Inspect status, address reason if needed, `/goal resume`. |
| `blocked` | Required user action, repeated external blocker, or judge blocker. | Resolve the external issue; resume if appropriate. |
Goals have no budget-limited state for new work; legacy budget-limited snapshots are retained only for compatibility.
| `evaluator_error` | Verification/judge/auth/network/schema/cancellation issue. | Fix trust, verifier configuration, model authentication, or connectivity, then resume. |
| `complete` | Judge approved all evidence. | Create a replacement goal for new work. |

## Security model

- The project must be trusted before any configured verifier runs.
- Only the user-approved verifier array in the contract executes. A model cannot add commands at completion time.
- Verifiers use direct executable/argument execution, safe real-path cwd containment, expected exit codes, and bounded output delivered to the judge.
- Goal text is untrusted application data. It is explicitly delimited in the worker prompt and cannot supersede system policy, permissions, or the protocol.
- Completion is authority-separated: worker evidence, deterministic verifiers, then fresh-context independent verdict. Every evaluator error fails closed.
- Snapshots validate schema/state/contract before restoration. Branch restoration uses only the parent-linked selected branch.

This does not sandbox the ordinary Pi worker. Extensions and normal worker tools retain the user’s available system permissions, so least-privilege tool configuration and package review remain essential.

## Development

```bash
npm install
npm run check     # TypeScript, no emit
npm test          # Vitest suite
npm pack --dry-run
```

The test suite covers parsing and shell rejection, state/progress accounting, branch snapshots and clear tombstones, lifecycle prompt injection, print-mode behavior, scheduler latching and priority, stale generations, limits, blocker debounce, verifier trust/direct execution/truncation, strict judge parsing, and completion authority separation. Tests use a fake Pi harness; no live provider call is required.

The package is ESM (`"type": "module"`), points Pi to `./src/index.ts`, and publishes `src`, `README.md`, and `LICENSE`. Keep documentation synchronized when adding a command, status, snapshot event, contract field, tool schema, lifecycle handler, or verifier policy.