@beremaran/ralphie 0.0.0-stage → 0.2.1

package/docs/operations-and-recovery.md

@@ -0,0 +1,328 @@
+# Operations and recovery
+
+This page is for operators inspecting a run, integrating Ralphie's output,
+or understanding what remains after interruption or failure. It is the
+authoritative reference for progress output, artifacts, state, cancellation,
+and cleanup. Start at the [documentation index](README.md) for other audience
+paths.
+
+## Progress output
+
+While each session runs, Ralphie translates its harness's native event stream
+into one harness-neutral set of session events: assistant text and thinking,
+tool calls, tool results, errors, and token usage. Every output mode renders
+only these events, so output looks the same whichever harness ran the session.
+Tasks and issues are intentionally processed sequentially so the event stream
+remains ordered. JSON output carries every session event for integrations; see
+[Session events](#session-events).
+
+Ralphie adapts its presentation to its environment. `--output default`
+resolves to the full-screen TUI only when stdin and stderr are both TTYs and
+`CI` is neither `"true"` nor `"1"`; otherwise it uses append-only `plain`
+lines.
+
+- Interactive terminals get an OpenTUI application (the same rendering core
+  OpenCode 1.0 uses): a borderless layout with a background header line
+  (repository, pause state), an issue sidebar, a scrollable
+  transcript that streams assistant text as it arrives, and a footer status
+  line (stage, activity, elapsed time). Transcript turns start with a colored
+  `● <harness> · <title>` role label and blank-line separation; assistant text
+  is indented and plain, thinking is dim, each tool call is one row
+  (`✓ $ <command> · 1.2s`, `✓ read <path>`, `✗ <tool> <path> · failed:
+  <detail>`), and a session error is a red `✗ <message>` row. The sidebar
+  lists every issue discovered in the run with its outcome (`○` queued, `▶`
+  active, `✓` completed, `✗` failed, `⚠` hand-off, `−` skipped) and
+  follows the active issue until you navigate away with `[`/`]` or
+  Ctrl+Left/Right; each issue keeps its own transcript, so processed issues
+  stay browsable while the run continues. The queue starts
+  paused so the discovered plan can be inspected before work begins; `p`
+  resumes or pauses it between issues, `s` stops the queue after the active
+  issue and drains the run normally, and `q` (like Ctrl-C) cancels immediately.
+  The footer and sidebar hints show the pending pause or stop. Tool output, long commands, and deep paths stay inside the
+  transcript panel; resize is handled by the renderer; Ctrl-C is forwarded as
+  SIGINT so cancellation still restores the checkout and saves state; disposal
+  destroys the renderer and restores the terminal.
+- CI and redirected output are the deterministic noninteractive fallback:
+  append-only, byte-identical across identical runs, with neither ANSI cursor
+  controls (`ESC`) nor carriage-return bytes; `stripTerminalControls` is an
+  identity no-op on these streams. Each session is a block that opens with
+  `╭─ <harness> · <title>` and closes with `╰─ done`. Assistant and thinking
+  text are buffered per block and printed as complete `│  ` lines; each tool
+  call gets one line, each tool completion one summary line
+  (`│  ✓ <tool> done` or `│  ✗ <tool> failed: <output>`), and each session
+  error one `│  ✗ <message>` line. Usage is not printed.
+- `--output json` writes progress records and `session_event` records one per
+  line to stdout with stderr empty: every non-empty line parses as one
+  complete JSON record, human headers/glyphs never appear, and values are
+  preserved as supplied.
+
+JSON events use a stable operational vocabulary and include `runId`,
+`timestamp`, `stage`, `status`, and `message`. Pre-flight and hand-off events identify
+whether agent work was skipped. Human-readable hand-off decisions name
+the issue number and title and show the current/total queue position. JSON
+output retains the complete event payload, including the structured details
+field; human-readable output never renders that field. A
+`hand-off` event includes its reason, summary, evidence, questions,
+diagnostic or artifact path, and queue position.
+Depending on the event, it may also include the repository, review attempt,
+session ID, commit SHA, created issue numbers, or diagnostic paths. Supplied
+progress-event values are preserved as-is; session transcripts are never
+redacted, and terminal control sequences are stripped at the
+reporting boundary.
+
+### Session events
+
+Each `session_event` record wraps one session event with the session it
+belongs to:
+
+```json
+{"type":"session_event","sessionID":"claude-7d3e2a1b","directory":"/work/owner/repo","harness":"claude","title":"Implement #42","event":{"type":"tool_call","callId":"call-1","name":"Bash","input":{"command":"bun test"}}}
+```
+
+| Field       | Meaning                                                   |
+| ----------- | --------------------------------------------------------- |
+| `sessionID` | Ralphie's id for the session.                             |
+| `directory` | Working directory of the session.                         |
+| `harness`   | Name of the harness that ran the session, such as `claude`. |
+| `title`     | Human-readable session label; omitted when there is none. |
+| `event`     | One of the event shapes below, discriminated by `type`.   |
+
+`event` is one of:
+
+- `{"type":"session_started"}`: the session began producing work.
+- `{"type":"assistant_text","kind":"text"|"thinking","text":…,"done":…}`: a
+  fragment of assistant output. Fragments of one `kind` concatenate into a
+  block until one arrives with `done: true`. `text` is only the fragment: a
+  closing fragment may be empty, and a whole block may arrive as a single
+  fragment with `done: true`.
+- `{"type":"tool_call","callId":…,"name":…,"input":{…}}`: the assistant
+  started a tool. `callId` pairs the call with its result.
+- `{"type":"tool_result","callId":…,"name":…,"output":…,"isError":…}`: the
+  tool finished. `output` is its text output, empty when it has none.
+- `{"type":"error","message":…}`: the harness or model reported a failure.
+- `{"type":"usage","inputTokens":…,"outputTokens":…}`, optionally with
+  `cacheReadTokens`, `cacheWriteTokens`, and `costUsd`: tokens, and cost where
+  the harness reports it, consumed since the session's previous `usage` event.
+  Sum the events for a session total.
+- `{"type":"session_finished"}`: the session stopped producing work. Failures
+  are reported by `error` events, not here.
+
+Tool names and `input` fields are the harness's own (for example Claude Code's
+`Bash` tool takes `command`), so consumers that need tool-specific detail should key
+on `harness` as well as `name`.
+
+## State and artifacts
+
+The workspace's `.ralphie` directory contains only repository checkouts and
+Ralphie's run state, events, and recovery artifacts. Harness credentials and
+settings belong to each harness CLI and are never written under this path.
+
+Run artifacts live under:
+
+```text
+<workspace>/.ralphie/runs/<run-id>/
+├── state.json
+├── events.jsonl
+└── issues/
+```
+
+New runs write the durable event log to
+`<workspace>/.ralphie/runs/<run-id>/events.jsonl`. The run closes the log
+immediately before removing the workspace, so post-cleanup progress still
+renders but is not persisted.
+
+A normal issue execution obtains a durable per-issue artifact store at:
+
+```text
+<workspace>/.ralphie/runs/<run-id>/issues/<issue-number>/artifacts.json
+```
+
+The store prevents accidental overwrites and records readiness deferrals,
+pre-flight decisions, checkpoints, review attempts, commit messages, created
+commits, resolution proof, decomposition decisions, and created child-number
+mappings. Stale or legacy un-fingerprinted decisions are removed on load
+without disturbing the other artifacts for the issue.
+
+A successful or interrupted run uses this more detailed layout (harness
+configuration is not stored in this tree):
+
+```text
+<workspace>/.ralphie/runs/<run-id>/
+├── state.json
+├── events.jsonl
+└── issues/
+    └── <issue-number>/
+        ├── artifacts.json
+        ├── review-exhaustion/
+        │   ├── changes.patch
+        │   └── metadata.json
+        └── hand-off-<id>/
+            ├── changes.patch
+            └── metadata.json
+```
+
+`state.json` is versioned, schema-validated, and atomically replaced. It
+contains the repository/branch, the role assignments
+(harness, model, effort),
+pending and completed queue numbers, processed count, outcomes, active
+issue/stage, checkout invariant, and update time. State is saved before the
+queue starts, when an issue becomes active, after each issue outcome, after
+queue refreshes, and at final completion. State is written for observability
+only: Ralphie never loads a previous run's state.
+
+## Failure, cancellation, and exit status
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active: start
+    Active --> Active: persist issue/queue progress
+    Active --> Complete: queue empty
+    Active --> Stopped: error (saved as active)
+    Active --> Stopped: AbortSignal
+    Complete --> Cleaned: workspace removed after success
+    Stopped --> Retained: keep state/artifacts
+    Cleaned --> [*]
+    Retained --> [*]
+```
+
+- One issue failure restores its checkout, persists the failed outcome, retains
+  artifacts, and continues to later issues.
+- Ordinary failures set process exit code `1`.
+- A limit, outage or expired login ends the run early. The affected issue is
+  recorded as `deferred` after its checkout is restored, nothing on GitHub
+  changes, no later issue starts, and the process exits `75` with a message
+  that names the failure and the reset time when the harness reports one. State
+  and artifacts are kept and cleanup is skipped. Rerun after the limit clears
+  or you sign in again. Why this halts instead of handing off is recorded in
+  [ADR-0004](adr/0004-environmental-failures-halt-instead-of-handing-off.md).
+- Cancellation is checked before long-running boundaries and passed to the running session, which is killed.
+  Ralphie attempts to restore the clean issue checkpoint, saves state with the
+  active issue, skips cleanup, and exits `130`.
+- Successful completion persists `complete`, then removes the entire workspace
+  (after protected-path checks). Cleanup is skipped when the run drains with
+  issue failures, fails, or is cancelled, so state and diagnostics remain
+  available.
+
+An ordinary issue failure never stops the queue. Ralphie restores the failed
+issue checkout, records its outcome, and continues independent issues. Failed
+prerequisites are not marked complete, so dependent issues remain blocked.
+After draining all reachable work, the run exits with status `1` and an
+aggregate partial-failure summary.
+
+Hand-off outcomes also continue the queue. A drained run completes with
+status `0`, and the handed-off issue remains open but leaves the intake queue
+because it no longer carries the agent-ready label. The deterministic
+`decomposition_limit_reached` boundary behaves the same way: raise the
+persisted `limits.maxDecompositionDepth`, narrow the issue, or resolve its review
+findings manually, then relabel the issue `ready-for-agent` for a later run.
+It never closes or marks the capped issue complete, so dependent work remains
+blocked.
+
+## Hand-off handling
+
+A validated hand-off decision is not an ordinary failure. Ralphie
+persists the summary, evidence, questions, and issue
+freshness metadata in the run artifacts, keeps the issue open, and continues
+with later work.
+
+The labels and comments a hand-off publishes are described under
+[Hand-offs](workflows.md#hand-offs). They are published after recording the
+outcome and before moving to the next issue. The comment carries a hidden
+`ralphie:hand-off` marker, so a retry updates it instead of posting another.
+Issues held back by open
+blockers, whether reported by pre-flight or by queue order, are recorded as
+skipped and change nothing on GitHub. A hand-off publishing failure fails the
+run; the issue keeps its labels and a later run re-evaluates it from scratch.
+
+When an executor session or pre-flight asks for a hand-off, Ralphie first persists the
+bounded request, clean checkpoint, and issue freshness fingerprint. Exactly one
+fresh read-only hand-off verification session verifies that request before the next artifact,
+Git, or GitHub mutation. Only a `hand_off` verifier disposition confirms
+it; actionable and already-resolved dispositions continue the original flow.
+The confirmed decision is persisted before recovery writes a bounded binary-safe
+patch and decision diagnostic, then restores and verifies the exact clean
+checkpoint. A verifier or recovery interruption retains the pending hand-off so a later
+attempt can retry verification or recovery without rerunning completed agent
+work. The saved decision and pending hand-off are reused only when live `updatedAt` and
+comment freshness metadata exactly match; a changed or invalid fingerprint
+removes both atomically before routing continues.
+
+```mermaid
+stateDiagram-v2
+    state "Issue in progress" as IssueInProgress
+    state "Recoverable stop" as RecoverableStop
+    state "Artifacts retained" as Retained
+    state "Workspace cleaned" as Cleaned
+
+    [*] --> Active: Start
+    Active --> IssueInProgress: Dequeue issue
+    IssueInProgress --> Active: Persist outcome and queue
+    IssueInProgress --> RecoverableStop: Failure or interruption
+    Active --> Complete: Queue empty
+    Complete --> Cleaned: Remove workspace after success
+    RecoverableStop --> Retained: Keep workspace
+    Retained --> [*]
+    Cleaned --> [*]
+```
+
+Hand-off recovery diagnostics use the same issue directory and contain
+`changes.patch` plus `metadata.json` under a fingerprint-bound
+`hand-off-<id>/` directory. The patch includes tracked staged and unstaged
+changes as well as untracked files. Matching diagnostics are reused within the
+run; a fresh fingerprint receives a distinct directory. Diagnostics are
+published atomically before the exact checkpoint is restored and verified.
+
+## Interruption and recovery
+
+There is no resume command. When a run fails or is interrupted:
+
+1. the process exits non-zero (see
+   [exit status](#failure-cancellation-and-exit-status));
+2. the workspace retains `state.json`, `events.jsonl`, and per-issue artifacts
+   for diagnosis;
+3. issues that were not closed remain open and are selected again on the next
+   run; and
+4. the next run removes the workspace, prepares a fresh checkout, and
+   re-evaluates every matching open issue from scratch.
+
+A hard crash (a killed process, a power loss) in the middle of the review gate
+is the one case that leaves the retained checkout unclean: Ralphie creates
+local candidate commits while review is in progress, so HEAD may sit at a
+candidate commit. Candidate commits are never pushed, and the next run
+discards the whole workspace; inspect the retained checkout before starting
+it if you need the work. Ordinary failures and cancellation restore the
+checkpoint first.
+
+Because each run starts clean, recovery is a new run rather than a continuation:
+completed issues are already closed and no longer selected, while interrupted
+issues repeat pre-flight, implementation, and review. Inspect the retained
+`state.json` and artifacts before deleting them if the failure needs
+investigation.
+
+Native sub-issue and dependency endpoints require `github.com`; GitHub
+Enterprise Server is not supported by the current client. With an unavailable
+endpoint or a token lacking issue write permission, live decomposition fails with
+an actionable error naming the missing capability; there is no body-link fallback.
+See [Workflows](workflows.md#platform-support-for-native-sub-issues-and-dependencies).
+
+An ordinary issue failure never stops the queue. Ralphie restores the failed
+issue checkout, records its outcome, and continues independent work; the
+drained run exits `1` if any issue failed.
+
+A configured deterministic verification command returning non-zero is handled
+before it becomes an issue failure. Ralphie gives the bounded command output and
+staged diff to the implementer's session (resumed with `/diagnosing-bugs`, or a
+fresh fixer session when it cannot be resumed), restages its changes, and
+retries up to `limits.verificationFixes` times. Only repair exhaustion or a non-repairable
+verification fault (for example a command changing the staged tree) reaches the
+ordinary failure boundary. When no `verify` commands are configured, the gate
+is skipped.
+
+## Cleanup
+
+Ralphie removes the entire workspace before preparing a run, after
+protected-path checks, and again after a successful run. This deletes completed
+state, events, diagnostics, and the repository checkout. Cleanup is skipped
+when the run drains with issue failures, fails, or is cancelled, so state and
+diagnostics remain available. Use a path dedicated to Ralphie; see
+[Safety](safety.md) for the destructive workspace contract.

package/docs/safety.md

@@ -0,0 +1,189 @@
+# Safety model
+
+This page is for operators before they run Ralphie against a repository and for
+contributors changing mutation paths. It is the authoritative reference for
+Git/GitHub mutation boundaries, remote invariants, and workspace risks. Return
+to the [documentation index](README.md) for the full
+reading map.
+
+> [!CAUTION]
+> Ralphie commits approved work and pushes directly to the branch selected by
+> `repos."owner/repo".branch` (default `main`, otherwise `master`). Test against a disposable repository before enabling mutations.
+
+## Delivery guardrails
+
+Delivery automation deserves explicit guardrails. Before agent work and again
+before a push, Ralphie verifies that:
+
+- the checkout and `origin` match the requested GitHub repository;
+- the local checkout is still on the selected branch and expected commit;
+- the remote branch has not moved from the captured base;
+- the result is exactly the expected local commit; and
+- the push is non-force.
+
+If any invariant fails, Ralphie halts instead of guessing or retrying a
+dangerous operation.
+
+Delivery is one deterministic operation: it creates exactly one commit from the
+allowed staged tree, re-checks the local branch/head and the remote base
+immediately before the push, and pushes only with Git's non-force mode. A push
+response is not proof; an authoritative remote branch read establishes whether
+the commit arrived, including reconciliation of a lost push response. Movement
+detected before staging/commit prevents the commit from being created; movement
+detected before or during delivery is never followed, reset over, or
+force-pushed over. Cancellation is checked at every mutation boundary, the push
+is attempted at most once, and failures and cancellations leave a clean,
+recoverable checkout.
+
+Implementation agents may use whatever shell their harness grants. Ralphie does
+not filter their commands: the guardrails are the session environment (see
+[Session isolation](#session-isolation)) and the deterministic repository
+invariants and delivery services, which remain authoritative.
+
+## Workspace risk
+
+There is one intentionally destructive local behavior: when reusing an existing
+repository checkout that is not clean, Ralphie runs the equivalent of `git reset
+--hard` and `git clean -fd`, then aligns it with the selected remote branch.
+Tracked modifications and untracked, non-ignored files inside that checkout are
+discarded. Keep unrelated work outside Ralphie's workspace.
+
+The workspace's `.ralphie` directory contains only repository checkouts and
+Ralphie's run state, events, and recovery artifacts. Harness credentials and
+settings belong to each harness CLI and are never written under this path;
+keep provider configuration outside the workspace.
+
+Ralphie removes the entire workspace recursively before preparing a run and
+again after a successful run, after protected-path checks. The retained
+workspace after a failure is
+[documented with cleanup and recovery](operations-and-recovery.md#cleanup). Use
+a path dedicated to Ralphie:
+
+```bash
+bunx @beremaran/ralphie owner/repository \
+  --set workspace=/tmp/ralphie
+```
+
+## Agent and mutation boundaries
+
+Agent sessions run as headless harness CLI invocations rooted at the
+repository checkout. Read-only roles run in the harness's read-only mode
+(Claude Code plan mode limited to the Read, Glob and Grep tools, so there is
+no shell: reviewers cannot run `git diff`, and Ralphie puts the diff in their
+prompt instead); the `implementer` and `fixer` run under their
+[approval mode](#approval-modes) and may edit the checkout. Post-task
+verification fails the task when the checkout's branch or head moved anyway.
+Structured decisions are returned as a result validated against the canonical
+Zod schema (natively where the harness supports it, otherwise from a final
+JSON block, with a bounded number of corrections), and the validated value is
+what the domain boundary accepts. A repository-backed blocker is the
+implementer's `needs_attention` status with a `needsAttention` object (`reason`
+and `questions`) in that result, or a pre-flight `hand_off` disposition; neither
+is a mutation-capable tool, and Ralphie verifies the request before handing
+off. Ralphie
+stages, verifies, commits, pushes, and mutates
+GitHub through deterministic domain services. Invalid output or a harness failure
+becomes a failed issue outcome without proceeding to the next operation.
+A turn that produces no assistant message fails instead of producing a
+decision.
+
+Protected maintainer choices are also enforced before verification: a staged
+change that selects a project license fails closed unless that exact license
+is authorized by the issue text, deferring to a maintainer decision instead of
+silently establishing policy.
+
+Verification is opt-in: Ralphie runs only the commands listed under
+`repos."owner/repo".verify`, and when none are listed the gate is skipped and review
+proceeds on the staged diff. Configured commands run against the staged tree
+and their evidence is
+bound to that tree before review or commit. A non-zero command exit is treated
+as actionable implementation feedback: the fix session (the implementer's, resumed) receives bounded
+failure evidence, and Ralphie restages and retries up to `limits.verificationFixes` times.
+Staged-tree mutation and exhausted repair remain
+hard safety stops. The direct-push path never uses force. See
+[Workflows](workflows.md) for the complete implementation and delivery sequence,
+and [Operations and recovery](operations-and-recovery.md) for what remains
+available after a safety stop.
+
+## Approval modes
+
+Read-only roles never edit and ignore the approval mode. The editing roles
+(`implementer` and `fixer`) run under `approval`, set at the top level of the
+configuration and overridable per repository and per harness
+(`harnesses.<name>.approval`):
+
+- `safe` (default) uses the harness's own approval or sandbox: Claude Code
+  auto mode, or the Codex workspace-write sandbox.
+- `yolo` turns off every approval and sandbox check (Claude Code
+  `bypassPermissions`, Codex `--dangerously-bypass-approvals-and-sandbox`, and
+  the only mode pi and OpenCode have). Use it only in an environment that is
+  already isolated.
+
+Before any work starts, Ralphie checks that every assigned harness starts,
+that `safe` is actually granted where configured (Claude Code can silently
+fall back from auto mode), and that no editing role runs on pi or OpenCode
+without `yolo`, because neither has a sandbox or approval system. A failure
+stops the run within seconds and names the configuration change that fixes it,
+such as `harnesses.pi.approval: yolo` or moving the role with
+`roles.implementer`. Spend caps (`limits.maxBudgetUsd`) are covered in
+[Configuration](configuration.md#limits).
+
+Each session also has a wall-clock limit
+([`limits.sessionTimeoutMinutes`](configuration.md#limits)); exceeding it kills
+the session's whole process group, so tools the harness started die with it.
+
+## Session isolation
+
+Sessions never hold GitHub or push authority (ADR-0003); the session
+environment enforces it instead of the prompts.
+
+- **No credentials.** Every session starts without `GH_TOKEN`, `GITHUB_TOKEN`,
+  `GH_ENTERPRISE_TOKEN` and `GITHUB_ENTERPRISE_TOKEN`, and with `GH_CONFIG_DIR`
+  pointing at a fresh, empty temporary directory that is removed when the
+  session ends, so a stored `gh` login is not visible either. These entries
+  override anything a request sets.
+- **No SSH or git credentials.** Every session also starts without
+  `SSH_AUTH_SOCK`, `SSH_ASKPASS` and `GIT_ASKPASS`, with `GIT_CONFIG_GLOBAL`
+  and `GIT_CONFIG_SYSTEM` set to `/dev/null` and the repository's
+  `credential.helper` list reset (so no credential helper applies),
+  `GIT_TERMINAL_PROMPT=0`, and `GIT_SSH_COMMAND=false`, so a git remote cannot
+  authenticate through an ssh agent, a helper or a prompt. Ralphie's own
+  delivery push runs outside sessions and is unaffected.
+- **Residual limitation.** The environment cannot hide credentials that a
+  process running as the same OS user can read directly: a private key under
+  `~/.ssh` used through an explicit `ssh -i`, a `gh` token read straight out of
+  the operating system keyring (for example with `security find-generic-password`
+  on macOS), or a credential file read by path. `gh` itself is logged out in a
+  session even when its token lives in the keyring, because it finds keyring
+  entries through the hosts file in its now-empty config directory. Ralphie does not claim to block these, and a determined
+  yolo session could still use them. What it guarantees is that it never hands
+  a token to a session, that the checkout's push URL is disabled, and that its
+  own delivery push is verified against the remote. To close the gap, run
+  Ralphie as a dedicated OS user whose home, keyring and ssh keys hold no
+  credentials for the repository.
+- **No push from the workspace.** After preparing the checkout Ralphie sets
+  origin's push URL to a disabled value, so `git push` inside the workspace
+  fails. Ralphie's own delivery push names the fetch URL explicitly, never
+  uses force, and is verified against the remote afterwards.
+- **Read-only means unchanged.** Before and after every read-only session
+  Ralphie fingerprints HEAD, the index, tracked changes and untracked file
+  contents. Any difference fails the session (kind `access`), which fails the
+  issue closed.
+
+## Bounded command execution
+
+No command runs unbounded. Every process Ralphie spawns carries a hard
+deadline so a hung process fails loudly instead of stalling an issue run:
+
+- **Sessions** are bounded by `limits.sessionTimeoutMinutes`, described above.
+- **Ralphie-owned commands** (git and `gh` operations against the repository,
+  workspace preparation, authentication checks) default to a 10-minute timeout.
+- **Verification commands** (`verify`) run under a 30-minute timeout
+  because they execute the repository's full gate; they are the deliberate
+  exception to the shorter defaults. When no command is configured, no
+  verification process runs.
+
+A timed-out command is killed (including its process tree) and reported as
+`CommandTimeoutError` with the deadline and command in the message. These
+deadlines are fail-closed bounds, not retry budgets: they turn an indefinitely
+stuck session into a recoverable, reported failure.