Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 19 additions & 3 deletions docs/cli.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# CLI reference

This page lists every command of pdd 0.1.35, as `pdd --help` shows it. A test (`test/docs-commands.test.mjs`) checks that each command form of the help is on this page.
This page lists every command of pdd 0.1.35, as `pdd --help` and `pdd <command> --help` show it. A test (`test/docs-commands.test.mjs`) checks that each command form of the help catalog is on this page.

You need the pdd command only for runs with PRs, for `pdd test`, `pdd lint`, `pdd simulate` and `pdd approve`. Install the skills with `npx skills add promptdriven/pdd` (add `-g` for all your projects), and set up a repo with the `pdd-setup` skill in your agent. For simulations that your agent drives, use the Try tools in `pdd mcp`. Then use a PDD skill: `pdd-feature`, `pdd-bug`, `pdd-small-change`, `pdd-product` or `pdd-prompting`. Call a skill with `$pdd-feature` in Codex or `/pdd-feature` in Claude Code (or ask for it by name). See [Install](USAGE.md#2-install).

Expand Down Expand Up @@ -188,6 +188,8 @@ Autopilot opens no chat and needs no Herdr.
| `pdd autopilot audit RUN PR` | Audit a confirmed automatic merge once with a fresh configured agent. Save OK, CONCERN or BAD and the separate revert recommendation with the run. Post the evidence once on the issue. BAD opens a revert PR only when recommended; otherwise it keeps the merge and reopens the issue with the missing parts. One decision alert states the recommendation and choices. Unknown external outcomes require inspection before any retry. |
| `pdd autopilot check-base RUN PR` | Check the saved automatic base, PR target, current default branch and newest release before a merge or after it. This command reads only. |
| `pdd autopilot status [--all] [--json]` | Show this machine's Autopilot for this repo: enabled or disabled, the timer, the next tick, the jobs, an [alert](#alerts) that was not delivered and the last tick. `--all` lists every repository with Autopilot on this machine, from any folder. `--json` prints the [local cost report](#local-issue-costs) |
| `pdd autopilot logs [ISSUE] [--follow\|-f] [--lines N] [--json]` | List current headless Autopilot workers for this repository with stage, owned process state, suite queue position, blockers, last activity and saved log or evidence paths, or inspect and follow one worker live (`--follow` / `-f` detaches on Ctrl-C without stopping the worker or changing `observe` mode). Read-only; no GitHub call or approval effect |
| `pdd autopilot logs --issue N [--follow\|-f] [--lines N] [--json]` | Select one worker explicitly with `--issue N` (issue number, `#N`, `owner/repo#N`, or GitHub issue URL) to inspect saved progress or stream live updates |
| `pdd autopilot add N...` | Create the `pdd:autopilot` label when it is missing and add it to each named issue of this repository. Use it to choose the issues that Autopilot may take |
| `pdd autopilot release ISSUE` | Release this machine's claim and remove `pdd:working` and `pdd:stuck`; keep the run folder, branch and PRs |
| `pdd autopilot regressions [--json] [--file PATH]` | Read core merge history and GitHub CI, parent checks, revert, reopen and issue-link evidence. Classify each merge as ok, suspect or proven; count distinct proven PRs per UTC evidence day. Issue-body attribution uses issue creation time even if added in a later edit; these buckets require a consumer confirmation policy before use as daily scorecard counts. At most 100 GitHub requests per scan; rate exhaustion or Retry-After stops further reads, preserving collected evidence and marking missing evidence incomplete. --json prints structured results; --file exclusively creates a local report without overwriting existing files. No GitHub writes or reverts. Incomplete reads exit 1; complete scans exit 0 even when they detect regressions |
Expand All @@ -200,7 +202,7 @@ Autopilot opens no chat and needs no Herdr.
| `pdd autopilot alerts clear [--destination autopilot\|infrastructure]` | Remove the alert destination from this machine |
| `pdd autopilot alert --issue N --kind usage-limit\|resource\|interpreter\|interpreter-access\|access\|decision\|stuck\|test-suite\|long-running\|recovered --input - [--update]` | Record one alert and send it to this machine's destination. See [Alerts](#alerts) |

Outside a Git repository, `start`, `stop`, `status`, `add`, `off`, `observe`,
Outside a Git repository, `start`, `stop`, `status`, `logs`, `add`, `off`, `observe`,
`auto`, `trust` and `untrust` stop with exit code 1 and say: `This folder is not a
Git repository. cd into the repo you want Autopilot to work on, then run the
command again.` `status --all` works from any folder.
Expand Down Expand Up @@ -273,6 +275,20 @@ unreadable`. One bad line changes no other line. Without saved state it prints
`No Autopilot on this machine.` The local cost lines come last. It makes no GitHub
call.

`pdd autopilot logs` inspects headless Autopilot workers from local state files
without knowing internal state folders or touching running jobs. With no issue
argument, it prints the effective mode (`observe`, `auto` or `off`), active
workers sorted by issue number (stage, owned process state, suite queue position,
blockers, last activity, and saved log and evidence paths), recent finished
workers, and the follow command. With `ISSUE` or `--issue N`, it prints the
worker header and the last `--lines N` (default 40, maximum 5000) human-readable
progress lines formatted from Codex, Claude, Gemini/agy or test-suite logs, with
secrets redacted. It distinguishes waiting in the shared test-suite queue from a
running full suite, a repair pass, and a stale suite receipt. Add `--follow` or
`-f` to stream live worker and test-suite progress and stage changes; pressing
Ctrl-C detaches the viewer without stopping the worker or changing `observe`
mode. Add `--json` for structured snapshot output (`pdd.autopilot-logs.v1`).

A machine state that ran the full engine moves to the core engine at its next
tick. A start runs a tick, so a start moves it too. No new work starts before the
move is complete. While old work is busy (a live run with a merged PR, or a working
Expand Down Expand Up @@ -817,7 +833,7 @@ The agent runs these from the run's worktree. pdd finds the run from that folder

| Command | What it does |
|---|---|
| `pdd`, `pdd --help`, `pdd -h`, `pdd help` | Show the commands and the full paths of the installed Prompting guide and RUNBOOK |
| `pdd`, `pdd --help`, `pdd -h`, `pdd help` | Show the grouped command overview, quick-start examples, focused-help hint (`pdd <command> --help`), and the full paths of the installed Prompting guide and RUNBOOK |
| `pdd help prompting` | Show how to write a prompt, a Story and its test, which commands check them, and the full paths of the Prompting guide and RUNBOOK |
| `pdd --version` | Print the version, `0.1.35`. When the PDD skills that your agent finds are older, also print the update command on stderr |
| `pdd -V` | Same version and local diagnostics as `pdd --version` |
Expand Down
191 changes: 191 additions & 0 deletions prompts/cli/autopilot-logs.prompt.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,191 @@
# Autopilot worker logs

Own `src/autopilot-logs.mjs`. Export `runAutopilotLogs(input, ports)`,
`inspectAutopilotWorkers(input, ports)`, `formatWorkerLogLine(line, secrets)`
and `parseIssueSelector(raw)`. Give a person a supported read-only way to list
headless Autopilot workers, inspect a worker's stage, process state, queue
position, blockers and saved evidence, and follow live worker output from the
terminal without knowing internal state folders or touching running jobs.

## Domain decisions

- **Strictly read-only inspection and `observe`-mode preservation**:
Viewing worker logs never creates, modifies or deletes files in the checkout,
Autopilot state folders, validation folders, or user configuration, never
calls `gh`, and never approves gates or alters `observe`, `auto` or `off`
modes.
- **Same-user worker PID liveness boundary**:
Accept only safe integer PIDs with `pid > 1` across worker handles and
`suite.childPid`. In default liveness checks, any error from `kill(pid, 0)`
(both `ESRCH` and `EPERM`) returns `false` so system init (`pid 1`) or another
user's process is never reported as a running Autopilot worker; when a job
token is present, `ps` command output must also include that token.
- **End-to-end secret redaction, numeric coercion, and line-aligned UTF-8 reads**:
Derive caller secrets with `knownSecretValues(env)` (including injected
`input.env`), strip ANSI and control characters (`CTRL_RE`, including before
JSONL parsing in `formatWorkerLogLine`), and run `redactSecrets(..., secrets)`
across human snapshots, `--follow` streams, and `--json` payloads — covering
log lines, worker metadata (`agentKind`, `signal`, `wakeAt`, `holder`,
`verdict`, `head`, `repo`, `gitRoot`) and file path strings (`logPaths`,
`evidencePaths`, `streams[].path`, `suite.logPath`, `suite.receiptPath`).
Coerce `turn.completed` token counters (`input_tokens`, `output_tokens`) and
exit codes individually to finite numbers and guard every epoch timestamp with
`Number.isFinite(ts) && Math.abs(ts) <= 8.64e15` before `new Date(ts).toISOString()`
so malformed JSON fields never leak raw strings or throw `RangeError`.
Align tail and incremental follow reads on `\n` (`0x0a`) byte boundaries
(expanding read windows up to 16 MiB and ignoring a trailing EOF newline when
locating the start of the tail window) so multi-byte UTF-8 codepoints and
secret prefixes are never split mid-line and single-line tails ending in `\n`
are never dropped.
- **Bounded, pipe-safe `--follow` polling**:
Resolve `git rev-parse --show-toplevel` once and pass `gitRoot` into poll
iterations instead of spawning `git` on every poll. Attach `close` and `error`
(`EPIPE`) handlers on `stdout` and guard writes on `!stdout.destroyed &&
!stdout.writableEnded` so piped commands (`| head -n 5`) detach cleanly with
exit `0`, no `EPIPE` crash, no trailing detach message to a closed pipe, and
no leaked poll timer. Enforce `maxDurationMs` (default `3_600_000` ms / 60
minutes) so unattended follow sessions always terminate cleanly.

## Safety and observe mode

Every operation in this module is strictly read-only:

- Never write, create, rename or delete files in the repository, Autopilot
state folders, validation folders, or user configuration.
- Never approve gates, merge pull requests, claim or release issues, wake
scheduler ticks, or call GitHub (`gh`). Viewing preserves `observe`, `auto`
and `off` modes unchanged.
- Check process liveness read-only (`pid > 1`, `kill(pid, 0)` returning `false`
on any error including `EPERM` and `ESRCH`, and `ps` command match on the
job's `.spec.json` token when present). Never send `SIGTERM`, `SIGKILL`,
`SIGINT` or any stopping signal to a worker or test-suite process.
- Redact credentials and tokens in every displayed log line, JSON field, error
note and path summary with `redactSecrets(..., knownSecretValues(env))`. Strip
terminal escape and control sequences so output is safe in interactive
terminals, pipes and redirected files.

## CLI contract

`runAutopilotLogs({cwd, env, issue, follow, lines, json}, ports)` accepts:

- `issue`: optional issue selector from the positional `[ISSUE]` operand or
`--issue N` (`17`, `#17`, `owner/repo#17`, or a GitHub issue URL). When both
positional and `--issue` selectors are supplied directly, compare their parsed
issue numbers and optional repository qualifiers; conflicting selectors, a
blank/invalid selector, or `--follow` together with `--json` returns exit code
`2` with one clear usage message before state inspection.
- `follow`: Boolean from `--follow` or `-f`. Requires a selected issue; calling
`--follow` with no issue returns exit code `2` explaining how to pass an
issue (`pdd autopilot logs ISSUE --follow`).
- `lines`: positive integer tail count from `--lines N` (default `40`, range
`1` to `5000`).
- `json`: Boolean from `--json` for structured machine-readable inspection.

Injectable `ports` provide `fs`, `git(args, {cwd, env})`, `gitRoot`, `now()`,
`stateRoot`, `coreRoot`, `isProcessAlive(pid, token)`, `readSuite({cwd, env})`,
`stdout`, `signal`, `pollMs` (default `250`), `maxDurationMs` (default
`3600000`) and `sleep(ms)`. Resolve the repository root with
`git rev-parse --show-toplevel` under `LC_ALL=C` and `LANG=C` unless
`ports.gitRoot` is already supplied. Outside a Git repository, return
`{exitCode: 1, message: "This folder is not a Git repository. cd into the repo you want Autopilot to work on, then run the command again."}`.
Derive the state key from `sha256(gitToplevel).slice(0, 20)` under `stateRoot`
(default `<HOME>/.local/state/pdd/autopilot`), reading `<hash>.json`,
`<hash>-core/core.json`, `<hash>-core/jobs/*.json`,
`<hash>-core/intake/jobs/*.json`, `<hash>-core/logs/*` and
`<hash>-core/history.jsonl` plus the checkout's `pdd.json` mode.

## Worker inspection and stage distinction

`inspectAutopilotWorkers` classifies each active job in `<hash>-core/jobs` (and
any active read-only intake card job in `<hash>-core/intake/jobs`) and recent
completed history rows so a person can immediately tell live progress from
waiting or stale state:

1. **Stage**:
- `build` for initial headless implementation;
- `repair` (with repair count and PR number when present) so repair passes
stand out clearly from initial builds and checks;
- `conflict` for base-branch conflict resolution;
- `pr-check` on `phase === "pr"`, detailing `review`, `suite`, `vectors`,
`runtime` check wait, or `merge-lane` state;
- `ending` or `release-pending` when finishing cleanup;
- `intake` for read-only intake card workers;
- `finished` when selected by issue from `history.jsonl` after `jobs/N.json`
has already completed.
2. **Owned process state**:
- Inspect each sub-process handle (`job.agent`, `job.review?.agent`,
`job.suite?.agent`, `job.vectors?.agent`, `job.runtimeWait?.agent`) and
its `.exit.json` receipt.
- Report `running (pid N)` when `isProcessAlive(pid, token)` is true;
- Report `exited (code C)` when `.exit.json` is recorded while the job waits
for the next scheduler tick;
- Report `stale (pid N not running, no exit receipt)` when the recorded PID
is gone without `.exit.json`.
3. **Suite queue waiting versus live test execution versus stale receipts**:
- Query `readSuiteProgress({cwd: suiteCwd, env})` for PR suite checks.
- Report `queued (position P in shared test-suite queue)` when `state` is
`waiting`;
- Report `running full test suite` (with live validation `logPath`, child
PID and pass/fail counts when available) when `state` is `running`;
- Report `stale suite receipt` when a saved suite record has a dead runner
reason (`recorder_not_running` / ended before reporting) or belongs to an
older commit than `job.head`.
4. **Blockers and last activity**:
- Surface blockers plainly: shared test-suite queue wait, merge-lane wait
(naming the holder PR when present), PDD interpreter maintenance wait, AI
quota or login-pool cooldown, machine pause, GitHub Actions outage, safety
circuit-breaker downgrade, hung commands recorded in `.hangs.json`, and
`job.lastError`.
- Compute `lastActivityAt` from the newest `mtimeMs` across active worker
and suite validation logs (falling back to `watch.at` or `started`) and
show both relative age and UTC timestamp.
- Collect saved log paths and `<issue>-evidence-<head>.json` files for the
issue so evidence is directly linked.

## Output modes and live following

- **No issue selected (`pdd autopilot logs`)**:
Print repository and effective Autopilot mode (noting read-only viewer safety
when in `observe` mode), active machine-wide blockers if any, a clear list of
current workers sorted by issue number (showing issue, stage, process/queue
status, last activity, blockers and log path), recent finished workers when
present, and the exact command `pdd autopilot logs <issue> --follow` to
attach read-only to a worker. When no workers or history exist yet, exit `0`
with a plain empty-state message.
- **Selected issue snapshot (`pdd autopilot logs <issue> [--lines N]`)**:
Print the worker summary header (issue, mode, stage, owned process state,
suite/queue state, blockers, last activity, saved log and evidence paths),
followed by the last `N` human-readable lines formatted by
`formatWorkerLogLine` from the active log stream(s). If the issue has no
active worker and no saved history or log in this repository, return exit
code `1` with a hint to run `pdd autopilot logs`.
- **Readable progress lines (`formatWorkerLogLine`)**:
Convert Codex `--json` JSONL, Claude `stream-json`, and Gemini/Agy
`stream-json` records into concise human-readable progress lines (`[session]`,
`[run]`, `[cmd]`, `[tool]`, `[edit]`, `[agent]`, `[turn]`, `[result]`,
`[error]`), skipping noisy token-accounting heartbeats while keeping plain
test/command text lines intact and redacted.
- **Live follow (`--follow` / `-f`)**:
Stream the worker header, initial tail lines, and newly appended complete log
lines to `stdout` as the worker runs, reusing the resolved `gitRoot` on poll
ticks and emitting `[stage]` notices whenever the worker transitions across
stages or opens a new log (including live suite validation logs). Stop cleanly
with exit code `0` when the job finishes (or has no live process while the
Autopilot timer is off), when `maxDurationMs` elapses, when `stdout` closes or
errors (`EPIPE`), or when `signal` / `SIGINT` / `SIGTERM` detaches the viewer.
When `stdout` is still writable on signal detach, print a confirmation that
the background worker continues untouched.

## Dependencies

- [Secret redaction](secret-redaction.prompt.md): required for redacting
displayed log lines, JSON payloads, metadata and path summaries.

## Caller navigation

[Repository Autopilot settings](autopilot.prompt.md) and the
[CLI](pdd-cli.prompt.md) route `pdd autopilot logs` here;
[Autopilot core](autopilot-core.prompt.md) owns the `jobs/N.json`, `core.json`,
`logs/` and `history.jsonl` files that this viewer reads, and
[Shared full-suite queue](test-suite-queue.prompt.md) supplies the read-only
`readSuiteProgress` queue and validation-log view.
Loading
Loading