@beremaran/ralphie 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to Ralphie are documented here. The project follows
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-10-08
+
+### Changed
+
+- Agent sessions now inherit Ralphie's GitHub and git authority and may use
+  `gh` to read issues, pull requests, comments and CI results. See
+  `docs/safety.md#session-authority`.
+- `bun run smoke:live` now exits with status 2 unless an explicit opt-in
+  environment variable is set, because live runs spend model quota.
+
+## [0.2.2] - 2026-10-07
+
+### Changed
+
+- The README quick start now shows a global install, `bun add -g
+  @beremaran/ralphie`, next to the scoped `bunx` command. There are no changes
+  to the CLI.
+
 ## [0.2.1] - 2026-10-07
 
 ### Fixed
@@ -838,6 +856,7 @@ describe history, not the current tool.
 - Prevent no-change agent runs from being silently skipped without proving
   whether the issue is already resolved.
 
-[Unreleased]: https://github.com/beremaran/ralphie/compare/v0.2.1...HEAD
+[Unreleased]: https://github.com/beremaran/ralphie/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/beremaran/ralphie/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/beremaran/ralphie/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/beremaran/ralphie/compare/v0.1.2...v0.2.0

package/README.md

@@ -24,6 +24,13 @@ Run the latest release without installing globally:
 bunx @beremaran/ralphie --version
 ```
 
+Or install it globally; the command it provides is `ralphie`:
+
+```bash
+bun add -g @beremaran/ralphie
+ralphie --version
+```
+
 Write a starter config with `bunx @beremaran/ralphie init` (it detects the
 harnesses on PATH; see [Configuration](./docs/configuration.md)), then run the
 issue queue:

package/dist/ralphie.js

@@ -26490,10 +26490,6 @@ ${clone2.stderr}` : "";
 };
 var runGit = (runner, repositoryPath, args, signal) => runner.run("git", ["-C", repositoryPath, ...args], signal === undefined ? undefined : { signal });
 var requireGit = async (runner, repositoryPath, args, failureMessage, signal) => await requireSuccess(runner, "git", ["-C", repositoryPath, ...args], failureMessage, signal === undefined ? undefined : { signal });
-var DISABLED_PUSH_URL = "disabled://ralphie-sessions-cannot-push";
-var disablePush = async (runner, repositoryPath, signal) => {
-  await requireGit(runner, repositoryPath, ["remote", "set-url", "--push", "origin", DISABLED_PUSH_URL], "Failed to disable pushing from the workspace.", signal);
-};
 var selectBranch = async (runner, repositoryPath, branch, signal) => {
   if (branch !== undefined)
     return branch;
@@ -26520,7 +26516,6 @@ var prepareRepositoryState = async (runner, parsed, repositoryPath, branch, exis
     if (originSlug.toLowerCase() !== parsed.slug.toLowerCase()) {
       throw new Error(`${repositoryPath} contains ${originSlug}, not ${parsed.slug}.`);
     }
-    await disablePush(runner, repositoryPath, signal);
     if (exists)
       await requireGit(runner, repositoryPath, ["fetch", "--prune", "origin"], `Failed to fetch ${parsed.slug}.`, signal);
     const status = await requireGit(runner, repositoryPath, ["status", "--porcelain"], `Failed to inspect ${parsed.slug}.`, signal);
@@ -27922,9 +27917,10 @@ var TRACKER_DOC = `# Issue tracker
 
 Ralphie supplies the issue content in the prompt. Work from that text.
 
-Do not use the \`gh\` CLI or any other tool to read, create, comment on, label
-or close issues, and do not call the GitHub API. Ralphie performs every
-change to the tracker itself.
+You may use the \`gh\` CLI to read issues, pull requests, comments and CI results.
+Do not create, edit, comment on, label, close or reopen anything.
+Ralphie performs every change to the tracker itself.
+For raw GitHub API calls, pass \`--method GET\`; never use the API to write.
 `;
 var labelsDoc = (labels) => [
   "# Triage labels",
@@ -31444,48 +31440,7 @@ var nodeSkillFileSystem = {
   }
 };
 
-// src/harness/app/session-isolation.ts
-var GITHUB_CREDENTIAL_VARIABLES = [
-  "GH_TOKEN",
-  "GITHUB_TOKEN",
-  "GH_ENTERPRISE_TOKEN",
-  "GITHUB_ENTERPRISE_TOKEN"
-];
-var SSH_AGENT_VARIABLES = [
-  "SSH_AUTH_SOCK",
-  "SSH_ASKPASS",
-  "GIT_ASKPASS"
-];
-var isolatedEnvironment = (env, configDirectory) => ({
-  ...env,
-  ...Object.fromEntries([...GITHUB_CREDENTIAL_VARIABLES, ...SSH_AGENT_VARIABLES].map((name) => [
-    name,
-    undefined
-  ])),
-  GH_CONFIG_DIR: configDirectory,
-  GIT_CONFIG_GLOBAL: "/dev/null",
-  GIT_CONFIG_SYSTEM: "/dev/null",
-  GIT_CONFIG_NOSYSTEM: "1",
-  GIT_CONFIG_COUNT: "1",
-  GIT_CONFIG_KEY_0: "credential.helper",
-  GIT_CONFIG_VALUE_0: "",
-  GIT_TERMINAL_PROMPT: "0",
-  GIT_SSH_COMMAND: "false"
-});
-var isolateSessions = (inner, scratch) => {
-  const run = async (request2) => {
-    const directory = await scratch.create();
-    try {
-      return await inner.run({
-        ...request2,
-        env: isolatedEnvironment(request2.env, directory.path)
-      });
-    } finally {
-      await directory.remove().catch(() => {});
-    }
-  };
-  return { run };
-};
+// src/harness/app/read-only-session-guard.ts
 var guardReadOnlySessions = (inner, fingerprint) => {
   const run = async (request2) => {
     if (request2.access !== "read-only")
@@ -31509,20 +31464,6 @@ var guardReadOnlySessions = (inner, fingerprint) => {
   return { run };
 };
 
-// src/harness/adapters/scratch-directory.ts
-import { mkdtemp as mkdtemp2, rm as rm6 } from "fs/promises";
-import { tmpdir as tmpdir2 } from "os";
-import { join as join7 } from "path";
-var makeTemporaryScratchDirectories = () => ({
-  create: async () => {
-    const path = await mkdtemp2(join7(tmpdir2(), "ralphie-session-"));
-    return {
-      path,
-      remove: () => rm6(path, { recursive: true, force: true })
-    };
-  }
-});
-
 // src/git/adapters/working-tree.ts
 import { createHash as createHash2 } from "crypto";
 var makeGitWorkingTreeService = (runner) => ({
@@ -31616,7 +31557,7 @@ var provideRepositoryFacts = (inner, read) => {
 };
 
 // src/run/adapters/state.ts
-import { mkdir as mkdir7, rename as rename4, rm as rm7, writeFile as writeFile7 } from "fs/promises";
+import { mkdir as mkdir7, rename as rename4, rm as rm6, writeFile as writeFile7 } from "fs/promises";
 import { dirname as dirname4 } from "path";
 
 // src/run/state.ts
@@ -31765,7 +31706,7 @@ var persistRunStateAtomically = async (path, state) => {
     });
     await rename4(temporaryPath, path);
   } catch (cause) {
-    await rm7(temporaryPath, { force: true }).catch(() => {
+    await rm6(temporaryPath, { force: true }).catch(() => {
       return;
     });
     throw new RalphieError({
@@ -31798,7 +31739,7 @@ var makeIdGenerator = () => ({
 });
 
 // src/workspace/adapters/workspace.ts
-import { mkdir as mkdir8, rm as rm8 } from "fs/promises";
+import { mkdir as mkdir8, rm as rm7 } from "fs/promises";
 import { homedir as homedir2 } from "os";
 import { parse as parse7, resolve as resolve2, sep as sep2 } from "path";
 var assertSafeCleanupTarget = (workspace) => {
@@ -31830,7 +31771,7 @@ var WorkspaceLive = {
   },
   remove: async (workspace) => {
     try {
-      await rm8(assertSafeCleanupTarget(workspace), {
+      await rm7(assertSafeCleanupTarget(workspace), {
         recursive: true,
         force: true
       });
@@ -31890,7 +31831,7 @@ var makeLiveRuntime = ({
       })
     }
   });
-  const harness = provideRepositoryFacts(guardReadOnlySessions(isolateSessions(bareHarness, makeTemporaryScratchDirectories()), makeGitWorkingTreeService(commandRunner).fingerprint), makeGitRepositoryFactsService(commandRunner).read);
+  const harness = provideRepositoryFacts(guardReadOnlySessions(bareHarness, makeGitWorkingTreeService(commandRunner).fingerprint), makeGitRepositoryFactsService(commandRunner).read);
   const gitRepository = makeGitRepositoryService(commandRunner);
   const gitRepositoryInvariant = makeGitRepositoryInvariantService(commandRunner);
   const gitIssueCheckpoint = makeGitIssueCheckpointService(commandRunner);
@@ -33223,7 +33164,7 @@ var issueWorkflow = { run: workflow };
 // package.json
 var package_default = {
   name: "@beremaran/ralphie",
-  version: "0.2.1",
+  version: "0.2.3",
   description: "Turn a GitHub issue queue into reviewed commits with coding-agent harnesses.",
   module: "./dist/ralphie.js",
   main: "./dist/ralphie.js",
@@ -33310,7 +33251,7 @@ var package_default = {
 
 // src/build-info.ts
 var LOCAL_BUILD_COMMIT_SHA = "local";
-var injectedBuildInfo = { version: "0.2.1", commitSha: "local" };
+var injectedBuildInfo = { version: "0.2.3", commitSha: "local" };
 var BUILD_INFO = Object.freeze(injectedBuildInfo ?? {
   version: package_default.version,
   commitSha: LOCAL_BUILD_COMMIT_SHA
@@ -33336,21 +33277,21 @@ var makeRunEventLog = (input) => {
 };
 
 // src/run/adapters/layout.ts
-import { join as join8 } from "path";
+import { join as join7 } from "path";
 var safeRunId = (runId) => runId.replace(/[^a-zA-Z0-9_-]/g, "_") || "run";
 var makeRunLayout = (workspace, runId) => {
   const workspaceRoot = resolveWorkspacePath(workspace);
-  const runRoot = join8(workspaceRoot, ".ralphie", "runs", safeRunId(runId));
-  const issueRoot = join8(runRoot, "issues");
+  const runRoot = join7(workspaceRoot, ".ralphie", "runs", safeRunId(runId));
+  const issueRoot = join7(runRoot, "issues");
   return {
     workspaceRoot,
     runRoot,
-    statePath: join8(runRoot, "state.json"),
-    eventLogPath: join8(runRoot, "events.jsonl"),
-    issueArtifactsDirectory: (issueNumber) => join8(issueRoot, String(issueNumber)),
-    issueArtifactsPath: (issueNumber) => join8(issueRoot, String(issueNumber), "artifacts.json"),
-    diagnosticsDirectory: (issueNumber) => join8(issueRoot, String(issueNumber)),
-    diagnosticsPath: (issueNumber, name) => join8(issueRoot, String(issueNumber), name)
+    statePath: join7(runRoot, "state.json"),
+    eventLogPath: join7(runRoot, "events.jsonl"),
+    issueArtifactsDirectory: (issueNumber) => join7(issueRoot, String(issueNumber)),
+    issueArtifactsPath: (issueNumber) => join7(issueRoot, String(issueNumber), "artifacts.json"),
+    diagnosticsDirectory: (issueNumber) => join7(issueRoot, String(issueNumber)),
+    diagnosticsPath: (issueNumber, name) => join7(issueRoot, String(issueNumber), name)
   };
 };
 

package/docs/architecture.md

@@ -33,7 +33,7 @@ that binds concrete adapters into the runtime bundle.
 | --- | --- | --- |
 | `agent` | `src/agent/` | Prompts, structured-output and text-task helpers, and the role-to-session mapping (access mode, timeouts) over the harness port. Kept apart from `harness` on purpose: `agent` holds Ralphie's own prompts and role policy, while `harness` stays provider-neutral session plumbing that knows nothing about issues. |
 | `config` | `src/config/` | YAML configuration: the zod schema (`settings.ts`), layering and `--set` overrides (`load.ts`, `overrides.ts`), and the file-reader port with its Bun YAML adapter. |
-| `harness` | `src/harness/` | Provider-neutral harness port (session request, events, typed failures, structured results), the service that runs sessions and repairs invalid results, and one CLI adapter per harness (Claude Code, Codex, pi and OpenCode). Every workflow session runs through it, wrapped by session isolation, the read-only fingerprint guard and skill injection; `app/roles.ts` resolves the configured role assignments. The vendored skills live in `vendor/mattpocock-skills/` (see [Development](development.md#vendored-skills)). |
+| `harness` | `src/harness/` | Provider-neutral harness port (session request, events, typed failures, structured results), the service that runs sessions and repairs invalid results, and one CLI adapter per harness (Claude Code, Codex, pi and OpenCode). Every workflow session runs through it with the read-only fingerprint guard and skill injection; the session environment inherits Ralphie's GitHub and git authority (see [Safety](safety.md#session-authority)). `app/roles.ts` resolves the configured role assignments. The vendored skills live in `vendor/mattpocock-skills/` (see [Development](development.md#vendored-skills)). |
 | `github` | `src/github/` | Issue value objects, repository slug parsing, and the Octokit/`gh` adapters. |
 | `git` | `src/git/` | Checkout preparation, checkpoints, issue operations, invariants, and remote-safety adapters. |
 | `issues` | `src/issues/` | Domain (`domain/`), executors and artifact/recovery logic (`app/`), filesystem adapters (`adapters/`). |
@@ -105,11 +105,13 @@ Spike against OpenCode v2.0.22 (the published docs mostly describe v1). The reco
 
 ## Dependency and side-effect rules
 
-Agents own reasoning and edits within their permitted tool boundary. They do not
-own commits, pushes, issue mutations, or delivery sequencing. Deterministic
-services under `src/git/adapters/` and `src/github/adapters/` perform those side
-effects and verify their invariants. The explicit runtime object makes these
-boundaries testable without a framework-specific execution model.
+Sessions handle reasoning and code edits; Ralphie's deterministic services own
+the intended commit, push, tracker mutation, and delivery sequence. Prompts
+instruct sessions not to commit, push, or mutate GitHub (see
+[Session authority](safety.md#session-authority)). The adapters under `src/git/adapters/` and
+`src/github/adapters/` perform Ralphie's side effects and verify their
+invariants. The explicit runtime object makes this intended workflow
+testable without a framework-specific execution model.
 
 The `GitRepositoryFactsService` port in `src/git/ports.ts` reads HEAD, branch, status, recent log, and tracked files so read-only prompts, whose sessions have no shell, receive them as a `<repository-facts>` block.
 

package/docs/configuration.md

@@ -223,7 +223,8 @@ the first prepares the checkout, and the last to finish restores it. If the
 repository has no `docs/agents/issue-tracker.md` or
 `docs/agents/triage-labels.md`, Ralphie generates them for the session: the
 label table comes from `labels`, and the tracker doc says issue content is in
-the prompt and sessions must not use `gh`. Committed versions always win.
+the prompt, permits `gh` reads, and instructs sessions not to mutate the
+tracker. Committed versions always win.
 
 ### `limits`
 

package/docs/development.md

@@ -81,8 +81,12 @@ It is never run by `bun run test`, `bun run check`, or CI: it needs live
 harness logins, model spend, and GitHub credentials. Run it by hand before a
 release or after changing an adapter, prompt, or hand-off path:
 
+Live runs are banned by default because they burn model quota: the script
+exits `2` unless `RALPHIE_ALLOW_LIVE_SMOKE=1` is set. Only a human sets it;
+agents must never do so.
+
 ```bash
-RALPHIE_SMOKE_SCRATCH_REPO=you/ralphie-scratch \
+RALPHIE_ALLOW_LIVE_SMOKE=1 RALPHIE_SMOKE_SCRATCH_REPO=you/ralphie-scratch \
   bun run smoke:live -- --scratch-repo you/ralphie-scratch --harness claude,codex
 ```
 
@@ -203,10 +207,9 @@ Reviewing a sync pull request:
 
 1. Read the upstream diff in the pull request (or its compare link) for each
    driven skill, not only the vendored paths.
-2. Check whether the new skill text still fits Ralphie's contract: schema-validated
-   tool results, no agent commits or pushes, direct delivery. Where it does not,
-   change the Ralphie skill overlay in the same pull request, never the vendored
-   files.
+2. Check whether the new skill text fits Ralphie's intended flow: schema-validated
+   tool results and direct delivery by deterministic services. Where skill text conflicts, change the Ralphie skill overlay in the same
+   pull request, never the vendored files.
 3. Pull requests opened with the workflow's token do not trigger CI. Close and
    reopen the pull request, or run `bun run check` on its branch, before merging.
 
@@ -220,7 +223,8 @@ Before submitting a change:
 
 1. Add or update tests for the behavior.
 2. Run `bun run check`.
-3. Keep Git and GitHub mutations inside their deterministic domain services.
+3. Keep Ralphie's intended Git and GitHub mutation workflow inside deterministic
+   domain services. See [Session authority](safety.md#session-authority).
 4. Update the authoritative page under [`docs/`](README.md) when documentation
    changes. Update [`CHANGELOG.md`](../CHANGELOG.md) when the command surface, the
    output shape, the run-state version, or the recovery contract changes.

package/docs/getting-started.md

@@ -27,9 +27,8 @@ checkout. It brings its own login, so Ralphie asks for no model credentials
 and stores none. Pick the harness, model and effort per role with the
 `harnesses` and `roles` keys in the
 [configuration file](configuration.md#harnesses-and-roles); without them every
-role uses Claude Code with its own defaults. Sessions never commit, push, or
-mutate GitHub; Ralphie's deterministic services do (see the
-[safety model](safety.md#agent-and-mutation-boundaries)).
+role uses Claude Code with its own defaults. Sessions inherit Ralphie's GitHub
+and git authority; see the [safety model](safety.md#session-authority).
 
 For interactive GitHub authentication, run `gh auth login` and verify the
 selected account with `gh auth status`. For unattended runs, supply a token
@@ -131,4 +130,4 @@ issue. See [Workflows](workflows.md) for what the selected route means and
 [Operations and recovery](operations-and-recovery.md)
 for the artifacts it leaves behind.
 
-For all available options, continue to the [CLI reference](cli-reference.md).
+For all available options, continue to the [CLI reference](cli-reference.md).

package/docs/safety.md

@@ -35,10 +35,12 @@ 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.
+Implementation sessions may use whatever shell their harness grants. Ralphie
+does not filter their commands: sessions inherit the GitHub and git authority
+available to Ralphie, while prompts state the allowed behavior. The remaining
+automated checks are the read-only fingerprint guard, checkpoint restore, and
+delivery's remote verification and non-force push (see
+[Session authority](#session-authority)).
 
 ## Workspace risk
 
@@ -132,43 +134,37 @@ 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
+## Session authority
+
+Every session inherits the GitHub and git authority available to Ralphie,
+including its token or `gh auth login` profile and its git credentials. Sessions
+may use `gh` to read issues, pull requests, comments and CI results. Their
+prompts instruct them not to create, edit, comment on, label, close or reopen
+GitHub issues, and not to commit or push. These are behavioral instructions,
+not technical restrictions: a session that ignores them can mutate GitHub or
+commit and push when the inherited credentials allow it. The `origin` push URL
+is not disabled inside the workspace.
+
+Ralphie retains three checks around session work:
+
+- **Read-only fingerprint guard.** 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.
+  contents. Any difference fails the session (kind `access`) and the issue.
+- **Checkpoint restore.** On a failed issue outcome, Ralphie restores and
+  verifies the local checkout against its saved clean issue checkpoint. This
+  does not undo a GitHub mutation or a push a session already made.
+- **Verified delivery.** Ralphie's delivery push is non-force, rechecks the
+  expected remote branch immediately before pushing, and verifies the remote
+  afterwards. Unexpected remote movement, including an early session push,
+  stops delivery instead of being adopted or overwritten. This detects the
+  movement; it does not reverse the session's push.
+
+For a hard boundary on the credentials and repositories available to sessions,
+run Ralphie under a dedicated OS user with only the intended credentials, or
+use a fine-grained GitHub token scoped to the target repository with only the
+permissions Ralphie needs. Sessions inherit those permissions. A repository
+scope limits which repository the token can reach; it does not make access
+read-only within that repository.
 
 ## Bounded command execution
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beremaran/ralphie",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Turn a GitHub issue queue into reviewed commits with coding-agent harnesses.",
   "module": "./dist/ralphie.js",
   "main": "./dist/ralphie.js",