Add patchmill auth command

[rochecompaan]

Summary

Add patchmill auth as the canonical command for configuring or repairing Patchmill's repo-local Pi provider authentication.

Background

Users can currently get stuck after patchmill init if Pi provider auth fails later, because rerunning init exits when patchmill.config.json already exists. Plain pi is not enough because it may not be globally installed and would not update Patchmill's repo-local .patchmill/pi-agent auth state.

Attached design artifacts

The spec and implementation plan are attached as comments on this issue:

• docs/specs/2026-06-16-patchmill-auth-design.md
• docs/plans/2026-06-16-patchmill-auth.md

Worktree branch: patchmill-auth

[rochecompaan]

Attached spec: docs/specs/2026-06-16-patchmill-auth-design.md

Spec markdown

patchmill auth Design

Context

Patchmill currently configures Pi provider auth during patchmill init, but
init refuses to continue when patchmill.config.json already exists. That
leaves users without a safe retry path after an auth failure. Plain pi is also
not a sufficient workaround because it may not be globally installed and, even
when available, it writes to Pi's normal agent directory instead of Patchmill's
repository-local .patchmill/pi-agent directory.

Patchmill needs a dedicated command for managing runtime model-provider
authentication independently from repository initialization.

Goals

• Add patchmill auth as the canonical command for configuring Patchmill's Pi
  provider authentication.
• Always scope auth and model settings to the repository-local
  .patchmill/pi-agent directory.
• Reuse the existing Patchmill/Pi auth selector, model selector, local
  default-model settings, and smoke-test behavior from patchmill init.
• Make the command work for users who installed only Patchmill, without
  requiring a globally installed pi binary.
• Update user-facing remediation in init, doctor, and triage failure
  guidance to point to patchmill auth.

Non-goals

• No first-cut subcommand surface such as auth status, auth logout, or
  auth model.
• No changes to issue-host authentication (gh, tea, host.login, or
  PATCHMILL_HOST_LOGIN). patchmill auth is specifically for Patchmill's
  runtime model-provider auth.
• No migration of existing global Pi auth into .patchmill/pi-agent in the MVP.

Command UX

patchmill auth

The command runs an interactive provider-auth and model-selection flow for the
current repository. It should be safe to run after patchmill init, after a
failed patchmill triage, or whenever the user wants to add another provider or
change the selected default model.

Expected success output should summarize:

• the repository-local Pi agent directory in use;
• whether provider/model setup is ready;
• the selected model when available;
• the smoke-test result;
• the next suggested command, usually patchmill doctor or patchmill triage.

If run non-interactively and setup is incomplete, the command should fail with
concise guidance to run it in an interactive terminal.

Architecture

Add a new CLI command module under src/cli/commands/auth/ and register it in
src/cli/main.ts.

The new command should reuse existing init components rather than duplicating
provider logic:

• localPiAgentDir() and local settings helpers from
  init/pi-agent-settings.ts;
• detectPiReadiness() from init/pi-preflight.ts;
• setupPiInteractively() / resolvePiInitSetup() from init/pi-init-setup.ts
  and init/pi-auth-flow.ts;
• runPiSmokeTest() from init/pi-smoke-test.ts.

The existing setup resolver may need a small refactor so patchmill auth can
force the interactive provider-auth flow even when at least one provider is
already ready. This supports the multiple-provider use case: users should be
able to run patchmill auth to add another provider or reselect the model, not
only to repair a missing configuration.

Pi invocation consistency

Patchmill workflow commands that spawn Pi should use the repository-local Pi
agent directory by default:

PI_CODING_AGENT_DIR=<repo>/.patchmill/pi-agent

run-once already passes this directory. Triage execution and dry-run agent
calls should be updated to pass the same environment so auth configured by
patchmill auth is actually used.

Where Patchmill must launch Pi directly, it should not assume a global pi
executable exists. The implementation should prefer invoking the Pi binary from
Patchmill's installed dependency when feasible, while keeping tests injectable
through the existing command-runner boundary.

Error handling and remediation

• Existing patchmill init behavior remains non-destructive: it still refuses
  to overwrite an existing patchmill.config.json.
• When init finds existing config, its next step should mention
  patchmill auth and patchmill doctor.
• doctor Pi provider failures should point to patchmill auth instead of
  rerunning init or plain pi.
• Triage failures caused by missing provider credentials should be allowed to
  surface, but Patchmill-owned guidance should tell users to run
  patchmill auth.

Testing

Automated tests should cover production behavior because this changes CLI
routing, auth retry behavior, and Pi environment propagation.

Test coverage should include:

• patchmill auth help/registration behavior;
• successful interactive auth flow using injected fakes;
• non-interactive incomplete setup guidance;
• existing-config patchmill init output points to patchmill auth;
• doctor Pi provider remediation points to patchmill auth;
• triage dry-run and execute Pi invocations include PI_CODING_AGENT_DIR.

Manual verification should include running a smoke path with a fake or real
provider configuration when credentials are available.

[rochecompaan]

Attached plan: docs/plans/2026-06-16-patchmill-auth.md

Plan markdown

Patchmill Auth Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use
superpowers:subagent-driven-development (recommended) or
superpowers:executing-plans to implement this plan task-by-task. Steps use
checkbox (- [ ]) syntax for tracking.

Goal: Add patchmill auth so users can configure or repair Patchmill's
repo-local Pi provider authentication without rerunning patchmill init or
relying on a global pi binary.

Architecture: Reuse Patchmill's existing init-time Pi auth/model/smoke-test
components, adding a small auth command shell and a resolver option that forces
the interactive provider flow even when a provider is already ready. Keep
workflow commands consistently scoped to .patchmill/pi-agent, and resolve Pi
through Patchmill's package dependency when spawning it.

Tech Stack: TypeScript ESM, Node.js node:test, Patchmill CLI command
modules, Pi AuthStorage/ModelRegistry through existing init helpers.

---

Starting Point

Worktree: /home/roche/projects/patchmill/.worktrees/patchmill-auth

Baseline verification already run in the worktree:

npm test

Result: 805 tests passing, 0 failing.

The worktree already contains:

• spec commit 029f935 docs(auth): design patchmill auth command;
• local AGENTS.md requiring specs, plans, and implementation to happen in a
  dedicated worktree.

File Structure

Create or modify these files:

• src/cli/commands/init/pi-init-setup.ts — add a forceInteractiveSetup
  option to reuse init setup for patchmill auth.
• src/cli/commands/init/pi-init-setup.test.ts — cover forced interactive auth
  when readiness is already ready.
• src/cli/commands/init/pi-setup-reporting.ts — extract shared setup message
  formatting used by init and auth.
• src/cli/commands/init/main.ts — import shared reporting and update
  existing-config guidance.
• src/cli/commands/init/main.test.ts and
  src/cli/commands/init/pi-init-flow.test.ts — update guidance expectations.
• src/cli/commands/auth/main.ts — new patchmill auth command.
• src/cli/commands/auth/main.test.ts — command-level tests for help, success,
  and incomplete non-interactive setup.
• src/cli/main.ts and src/cli/main.test.ts — register top-level auth
  command.
• src/cli/pi-executable.ts — resolve the bundled Pi CLI through Patchmill's
  dependency.
• src/cli/pi-executable.test.ts — pure tests for Pi executable resolution.
• src/cli/commands/triage/command.ts — use bundled Pi resolution when spawning
  pi.
• src/cli/commands/triage/dry-run-agent.ts and
  src/cli/commands/triage/execute-agent.ts — pass repo-local Pi agent env to
  triage Pi runs.
• src/cli/commands/triage/dry-run-agent.test.ts and
  src/cli/commands/triage/execute-agent.test.ts — assert triage Pi calls
  include PI_CODING_AGENT_DIR.
• src/cli/commands/doctor/checks.ts and
  src/cli/commands/doctor/checks.test.ts — point Pi provider remediation to
  patchmill auth.
• README.md, docs/configuration.md, docs/issue-agent-workflows.md, and
  docs/providers.md — document the auth retry path.

The new auth command should stay small: CLI argument handling, local settings
read/write warnings, setup resolver call, and user-facing output. Keep Pi auth
provider internals in the existing init helper modules.

Task 1: Make Pi setup reusable for forced auth

Files:

• Modify: src/cli/commands/init/pi-init-setup.ts

• Modify: src/cli/commands/init/pi-init-setup.test.ts

• Step 1: Add a failing forced-setup test

Append this test to src/cli/commands/init/pi-init-setup.test.ts:

test("resolvePiInitSetup can force interactive setup when readiness is ready", async () => {
  let setupCalled = false;
  let smokeModel: string | undefined;

  const openAiModel: PiModelChoice = {
    provider: "openai",
    providerName: "OpenAI",
    id: "gpt-5",
    label: "OpenAI / GPT-5",
    value: "openai/gpt-5",
    authSource: "stored",
    reasoning: true,
    input: ["text"],
  };

  const result = await resolvePiInitSetup({
    repoRoot: "/repo",
    piAgentDir: "/repo/.patchmill/pi-agent",
    readiness: readyReadiness(),
    isInteractive: true,
    forceInteractiveSetup: true,
    setupPiInteractively: async ({ initialReadiness, agentDir }) => {
      setupCalled = true;
      assert.equal(initialReadiness.status, "ready");
      assert.equal(agentDir, "/repo/.patchmill/pi-agent");
      return {
        readiness: {
          status: "ready",
          message: "Pi reported 2 provider/model options with configured auth.",
          models: [openAiModel],
        },
        selection: {
          status: "selected",
          model: "openai/gpt-5",
          provider: "openai",
          modelId: "gpt-5",
          message: "Using Pi model OpenAI / GPT-5.",
        },
      };
    },
    runPiSmokeTest: async (_runner, options) => {
      smokeModel = options.model;
      return {
        status: "pass",
        message: "Pi completed the provider smoke test with openai/gpt-5.",
        command: "pi --model openai/gpt-5 -p smoke",
      };
    },
  });

  assert.equal(setupCalled, true);
  assert.equal(smokeModel, "openai/gpt-5");
  assert.equal(result.status, "ready");
  assert.equal(result.selection.status, "selected");
  assert.equal(result.selection.model, "openai/gpt-5");
});

• Step 2: Run the focused test to verify it fails

Run:

npm test -- src/cli/commands/init/pi-init-setup.test.ts

Expected: TypeScript/runtime failure because forceInteractiveSetup is not yet
accepted, or assertion failure because ready readiness goes directly to model
selection.

• Step 3: Implement the resolver option

In src/cli/commands/init/pi-init-setup.ts, add
forceInteractiveSetup?: boolean; to the resolvePiInitSetup() options object
and replace the existing readiness branch with this logic:

const interactiveSetup = options.setupPiInteractively ?? setupPiInteractively;
let readiness = options.readiness;
let selection: PiModelSelection;
const shouldRunInteractiveSetup =
  options.isInteractive &&
  (options.forceInteractiveSetup || readiness.status !== "ready");

if (shouldRunInteractiveSetup) {
  const setup = await interactiveSetup({
    repoRoot: options.repoRoot,
    agentDir: options.piAgentDir,
    currentDefault: options.currentDefault,
    initialReadiness: readiness,
    selectModelInteractively: options.selectModelInteractively,
    persistDefaultModel: options.persistDefaultModel,
  });
  readiness = setup.readiness;
  selection = setup.selection;
} else {
  selection = await selectPiModel({
    readiness,
    isInteractive: options.isInteractive,
    currentDefault: options.currentDefault,
    selectModelInteractively: options.selectModelInteractively,
    persistDefaultModel: options.persistDefaultModel,
  });
}

Keep the existing abort-status and smoke-test code unchanged below this branch.

• Step 4: Verify the focused tests pass

Run:

npm test -- src/cli/commands/init/pi-init-setup.test.ts

Expected: all tests in pi-init-setup.test.ts pass.

• Step 5: Commit

git add src/cli/commands/init/pi-init-setup.ts src/cli/commands/init/pi-init-setup.test.ts
git commit -m "feat(auth): allow forced Pi auth setup"

Task 2: Extract shared Pi setup reporting and update init guidance

Files:

• Create: src/cli/commands/init/pi-setup-reporting.ts

• Modify: src/cli/commands/init/main.ts

• Modify: src/cli/commands/init/main.test.ts

• Modify: src/cli/commands/init/pi-init-flow.test.ts

• Step 1: Add failing tests for the new guidance

In src/cli/commands/init/main.test.ts, extend
runInit refuses existing config without installing skills with:

assert.match(stdout.join("\n"), /patchmill auth/);
assert.match(stdout.join("\n"), /patchmill doctor/);

In src/cli/commands/init/pi-init-flow.test.ts, update incomplete-setup
assertions that currently expect patchmill init guidance so they expect
patchmill auth instead:

assert.match(
  output,
  /Run `patchmill auth` in an interactive terminal to configure provider auth and select a model/,
);

• Step 2: Run the focused init tests to verify they fail

Run:

npm test -- src/cli/commands/init/main.test.ts src/cli/commands/init/pi-init-flow.test.ts

Expected: failures showing the old guidance still mentions only
patchmill doctor or patchmill init.

• Step 3: Create the shared reporting module

Create src/cli/commands/init/pi-setup-reporting.ts:

import type { PiInitSetupResult } from "./pi-init-setup.ts";

export function formatPiSetupMessage(setup: PiInitSetupResult): string {
  const messages = [setup.readiness.message];
  if (setup.readiness.status === "ready" && setup.readiness.warning) {
    messages.push(setup.readiness.warning);
  }
  if (setup.selection.message !== setup.readiness.message) {
    messages.push(setup.selection.message);
  }
  if (setup.status === "ready") {
    return [...messages, setup.smoke.message].join("\n\n");
  }
  if (setup.status === "cancelled" || setup.status === "invalid") {
    return messages.join("\n\n");
  }
  return [
    ...messages,
    "Pi provider/model setup is incomplete.",
    setup.smoke.message,
    setup.smoke.details ? `Details:\n${setup.smoke.details}` : undefined,
    "Run `patchmill auth` in an interactive terminal to configure provider auth and select a model.",
    "After setup, run `patchmill doctor`.",
  ]
    .filter(Boolean)
    .join("\n\n");
}

export function piSetupAborted(setup: PiInitSetupResult): boolean {
  return setup.status === "cancelled" || setup.status === "invalid";
}

export function piSetupReady(setup: PiInitSetupResult): boolean {
  return setup.status === "ready";
}

• Step 4: Update init to use the shared reporting module

In src/cli/commands/init/main.ts, import the helpers:

import {
  formatPiSetupMessage,
  piSetupAborted,
  piSetupReady,
} from "./pi-setup-reporting.ts";

Remove the private formatPiSetupMessage() and shouldAbortPiSetup() functions
from main.ts.

Update EXISTING_CONFIG_MESSAGE to:

const EXISTING_CONFIG_MESSAGE =
  "patchmill.config.json already exists.\n\nPatchmill did not overwrite it.\n\nTo configure or repair Pi provider auth, run:\n  patchmill auth\n\nNext:\n  patchmill doctor";

Update the setup status usage near the end of runInit():

const piReady = piSetupReady(piSetup);

Update the return line:

return piSetupAborted(piSetup) ? 1 : 0;

• Step 5: Verify focused init tests pass

Run:

npm test -- src/cli/commands/init/main.test.ts src/cli/commands/init/pi-init-flow.test.ts

Expected: all focused init tests pass.

• Step 6: Commit

git add src/cli/commands/init/pi-setup-reporting.ts src/cli/commands/init/main.ts src/cli/commands/init/main.test.ts src/cli/commands/init/pi-init-flow.test.ts
git commit -m "feat(auth): point init setup guidance to auth"

Task 3: Add the patchmill auth command

Files:

• Create: src/cli/commands/auth/main.ts

• Create: src/cli/commands/auth/main.test.ts

• Modify: src/cli/main.ts

• Modify: src/cli/main.test.ts

• Step 1: Write failing auth command tests

Create src/cli/commands/auth/main.test.ts:

import assert from "node:assert/strict";
import { test } from "node:test";
import { HELP_TEXT, runAuth } from "./main.ts";
import type { PiInitSetupResult } from "../init/pi-init-setup.ts";
import type { PiReadiness } from "../init/pi-preflight.ts";

const readyReadiness: PiReadiness = {
  status: "ready",
  message: "Pi reported 1 provider/model option with configured auth.",
  models: [
    {
      provider: "anthropic",
      providerName: "Anthropic",
      id: "claude-sonnet-4-5",
      label: "Anthropic / Claude Sonnet 4.5",
      value: "anthropic/claude-sonnet-4-5",
      authSource: "stored",
      reasoning: true,
      input: ["text"],
    },
  ],
};

const readySetup: PiInitSetupResult = {
  status: "ready",
  readiness: readyReadiness,
  selection: {
    status: "selected",
    model: "anthropic/claude-sonnet-4-5",
    provider: "anthropic",
    modelId: "claude-sonnet-4-5",
    message: "Using Pi model Anthropic / Claude Sonnet 4.5.",
  },
  smoke: {
    status: "pass",
    message:
      "Pi completed the provider smoke test with anthropic/claude-sonnet-4-5.",
    command: "pi --model anthropic/claude-sonnet-4-5 -p smoke",
  },
};

test("runAuth prints help", async () => {
  const stdout: string[] = [];
  const code = await runAuth(["--help"], "/repo", {
    stdout: (line) => stdout.push(line),
    stderr: () => undefined,
  });

  assert.equal(code, 0);
  assert.deepEqual(stdout, [HELP_TEXT]);
});

test("runAuth forces repo-local interactive setup", async () => {
  const stdout: string[] = [];
  const code = await runAuth(
    [],
    "/repo",
    {
      stdout: (line) => stdout.push(line),
      stderr: () => undefined,
    },
    {
      isInteractive: true,
      detectPiReadiness: ({ agentDir }) => {
        assert.equal(agentDir, "/repo/.patchmill/pi-agent");
        return readyReadiness;
      },
      readLocalPiDefaultModel: async (agentDir) => {
        assert.equal(agentDir, "/repo/.patchmill/pi-agent");
        return { provider: "anthropic", modelId: "claude-sonnet-4-5" };
      },
      writeLocalPiDefaultModel: async () => undefined,
      resolvePiInitSetup: async (options) => {
        assert.equal(options.repoRoot, "/repo");
        assert.equal(options.piAgentDir, "/repo/.patchmill/pi-agent");
        assert.equal(options.isInteractive, true);
        assert.equal(options.forceInteractiveSetup, true);
        assert.deepEqual(options.currentDefault, {
          provider: "anthropic",
          modelId: "claude-sonnet-4-5",
        });
        return readySetup;
      },
    },
  );

  const output = stdout.join("\n");
  assert.equal(code, 0);
  assert.match(output, /Pi agent directory:\n  \/repo\/\.patchmill\/pi-agent/);
  assert.match(output, /Using Pi model Anthropic \/ Claude Sonnet 4\.5/);
  assert.match(output, /Next:\n  patchmill doctor\n  patchmill triage/);
});

test("runAuth returns one when setup remains incomplete", async () => {
  const stdout: string[] = [];
  const missing: PiReadiness = {
    status: "missing",
    message: "Pi did not report any provider/model with configured auth.",
    models: [],
  };

  const code = await runAuth(
    [],
    "/repo",
    {
      stdout: (line) => stdout.push(line),
      stderr: () => undefined,
    },
    {
      isInteractive: false,
      detectPiReadiness: () => missing,
      readLocalPiDefaultModel: async () => undefined,
      writeLocalPiDefaultModel: async () => undefined,
      resolvePiInitSetup: async () => ({
        status: "incomplete",
        readiness: missing,
        selection: {
          status: "unavailable",
          reason: "not-ready",
          message: missing.message,
        },
        smoke: {
          status: "fail",
          message: "Pi could not complete the provider smoke test.",
          command: "pi -p smoke",
          details: "No API key found for the selected model.",
        },
      }),
    },
  );

  const output = stdout.join("\n");
  assert.equal(code, 1);
  assert.match(output, /Pi provider\/model setup is incomplete/);
  assert.match(output, /Run `patchmill auth` in an interactive terminal/);
});

• Step 2: Add failing top-level CLI tests

In src/cli/main.test.ts, add an auth resolver test near the other
resolveCommand tests:

test("resolveCommand maps auth to the public command name", () => {
  assert.deepEqual(resolveCommand(["auth"], ["auth"]), {
    command: "auth",
    args: [],
  });
});

Add an assertion to the top-level help test:

assert.match(HELP_TEXT, /auth\s+Configure Patchmill runtime provider auth\./);

Update the dispatch test that covers init and doctor so it also covers auth:

const calls: Array<{ command: string; args: string[] }> = [];
const cli = createCliMain(
  new Map([
    [
      "init",
      (args) => {
        calls.push({ command: "init", args });
        return 0;
      },
    ],
    [
      "doctor",
      (args) => {
        calls.push({ command: "doctor", args });
        return 0;
      },
    ],
    [
      "auth",
      (args) => {
        calls.push({ command: "auth", args });
        return 0;
      },
    ],
  ]),
);

assert.equal(await cli(["init", "--yes"]), 0);
assert.equal(await cli(["doctor", "--fix"]), 0);
assert.equal(await cli(["auth"]), 0);
assert.deepEqual(calls, [
  { command: "init", args: ["--yes"] },
  { command: "doctor", args: ["--fix"] },
  { command: "auth", args: [] },
]);

• Step 3: Run the focused tests to verify they fail

Run:

npm test -- src/cli/commands/auth/main.test.ts src/cli/main.test.ts

Expected: auth module import fails and top-level auth command is unknown.

• Step 4: Implement the auth command

Create src/cli/commands/auth/main.ts:

#!/usr/bin/env node
import { stdin as defaultStdin, cwd } from "node:process";
import { pathToFileURL } from "node:url";
import {
  localPiAgentDir,
  readLocalPiDefaultModel as defaultReadLocalPiDefaultModel,
  writeLocalPiDefaultModel as defaultWriteLocalPiDefaultModel,
  type LocalPiDefaultModel,
} from "../init/pi-agent-settings.ts";
import {
  resolvePiInitSetup as defaultResolvePiInitSetup,
  type PiInitSetupResolver,
} from "../init/pi-init-setup.ts";
import {
  formatPiSetupMessage,
  piSetupReady,
} from "../init/pi-setup-reporting.ts";
import { detectPiReadiness as defaultDetectPiReadiness } from "../init/pi-preflight.ts";
import type { PiReadiness } from "../init/pi-preflight.ts";
import { selectModelInteractively as defaultSelectModelInteractively } from "../init/pi-model-selector.ts";
import type { SelectInteractiveModel } from "../init/pi-model-selection.ts";
import { runPiSmokeTest } from "../init/pi-smoke-test.ts";

export const HELP_TEXT = `Usage:
  patchmill auth [options]

Configure Patchmill runtime provider auth for this repository.
Stores Pi auth and model settings under .patchmill/pi-agent.

Options:
  --help, -h  Show this help and exit.
`;

export type AuthOutput = {
  stdout: (line: string) => void;
  stderr: (line: string) => void;
};

export type PiReadinessDetector = (options: {
  agentDir: string;
}) => PiReadiness;

const DEFAULT_OUTPUT: AuthOutput = {
  stdout: (line) => console.log(line),
  stderr: (line) => console.error(line),
};

function isHelp(args: string[]): boolean {
  return args.includes("--help") || args.includes("-h");
}

function assertNoUnknownArgs(args: string[]): void {
  const unknown = args.find((arg) => arg !== "--help" && arg !== "-h");
  if (unknown) throw new Error(`Unknown argument: ${unknown}`);
}

function authNextSteps(ready: boolean): string {
  return ready
    ? "Next:\n  patchmill doctor\n  patchmill triage"
    : "Next:\n  patchmill auth\n  patchmill doctor";
}

export async function runAuth(
  args: string[],
  repoRoot = cwd(),
  output: AuthOutput = DEFAULT_OUTPUT,
  options: {
    isInteractive?: boolean;
    detectPiReadiness?: PiReadinessDetector;
    readLocalPiDefaultModel?: typeof defaultReadLocalPiDefaultModel;
    writeLocalPiDefaultModel?: typeof defaultWriteLocalPiDefaultModel;
    selectModelInteractively?: SelectInteractiveModel;
    resolvePiInitSetup?: PiInitSetupResolver;
    runPiSmokeTest?: typeof runPiSmokeTest;
  } = {},
): Promise<number> {
  if (isHelp(args)) {
    output.stdout(HELP_TEXT);
    return 0;
  }
  assertNoUnknownArgs(args);

  const piAgentDir = localPiAgentDir(repoRoot);
  const isInteractive = options.isInteractive ?? defaultStdin.isTTY;
  const readLocalPiDefaultModel =
    options.readLocalPiDefaultModel ?? defaultReadLocalPiDefaultModel;
  const writeLocalPiDefaultModel =
    options.writeLocalPiDefaultModel ?? defaultWriteLocalPiDefaultModel;

  let currentDefault: LocalPiDefaultModel | undefined;
  let settingsWarning: string | undefined;
  let settingsWriteWarning: string | undefined;
  try {
    currentDefault = await readLocalPiDefaultModel(piAgentDir);
  } catch (error) {
    settingsWarning = `Could not read local Pi settings: ${error instanceof Error ? error.message : String(error)}`;
  }

  const readiness = (options.detectPiReadiness ?? defaultDetectPiReadiness)({
    agentDir: piAgentDir,
  });
  const persistDefaultModel = settingsWarning
    ? undefined
    : async (model: LocalPiDefaultModel) => {
        try {
          await writeLocalPiDefaultModel(piAgentDir, model);
        } catch (error) {
          settingsWriteWarning = `Could not save local Pi default model: ${error instanceof Error ? error.message : String(error)}`;
        }
      };

  const setup = await (options.resolvePiInitSetup ?? defaultResolvePiInitSetup)(
    {
      repoRoot,
      piAgentDir,
      readiness,
      isInteractive,
      currentDefault,
      selectModelInteractively:
        options.selectModelInteractively ?? defaultSelectModelInteractively,
      persistDefaultModel,
      runPiSmokeTest: options.runPiSmokeTest,
      forceInteractiveSetup: true,
    },
  );

  const warnings = [settingsWarning, settingsWriteWarning]
    .filter((warning): warning is string => Boolean(warning))
    .join("\n\n");
  const ready = piSetupReady(setup);
  output.stdout(
    [
      "Patchmill Pi auth",
      `Pi agent directory:\n  ${piAgentDir}`,
      warnings || undefined,
      formatPiSetupMessage(setup),
      authNextSteps(ready),
    ]
      .filter(Boolean)
      .join("\n\n"),
  );

  return ready ? 0 : 1;
}

export async function main(args = process.argv.slice(2)): Promise<number> {
  try {
    return await runAuth(args);
  } catch (error) {
    console.error(error instanceof Error ? error.message : String(error));
    return 1;
  }
}

const isMain = process.argv[1]
  ? import.meta.url === pathToFileURL(process.argv[1]).href
  : false;

if (isMain) {
  process.exitCode = await main();
}

• Step 5: Register the command

In src/cli/main.ts, import auth:

import { main as authMain } from "./commands/auth/main.ts";

Add auth to HELP_TEXT:

  auth        Configure Patchmill runtime provider auth.

Add auth to COMMANDS:

  ["auth", authMain],

• Step 6: Verify focused tests pass

Run:

npm test -- src/cli/commands/auth/main.test.ts src/cli/main.test.ts

Expected: all focused auth and top-level CLI tests pass.

• Step 7: Commit

git add src/cli/commands/auth/main.ts src/cli/commands/auth/main.test.ts src/cli/main.ts src/cli/main.test.ts
git commit -m "feat(auth): add patchmill auth command"

Task 4: Resolve Pi from Patchmill's bundled dependency

Files:

• Create: src/cli/pi-executable.ts

• Create: src/cli/pi-executable.test.ts

• Modify: src/cli/commands/triage/command.ts

• Step 1: Write failing Pi executable tests

Create src/cli/pi-executable.test.ts:

import assert from "node:assert/strict";
import { join } from "node:path";
import { test } from "node:test";
import {
  resolveBundledPiCliPath,
  resolveCommandInvocation,
} from "./pi-executable.ts";

test("resolveBundledPiCliPath derives dist/cli.js from the package main", () => {
  const path = resolveBundledPiCliPath({
    requireResolve: () =>
      "/repo/node_modules/@earendil-works/pi-coding-agent/dist/index.js",
    exists: (candidate) => candidate.endsWith(join("dist", "cli.js")),
  });

  assert.equal(
    path,
    "/repo/node_modules/@earendil-works/pi-coding-agent/dist/cli.js",
  );
});

test("resolveBundledPiCliPath returns undefined when dependency resolution fails", () => {
  const path = resolveBundledPiCliPath({
    requireResolve: () => {
      throw new Error("not installed");
    },
    exists: () => true,
  });

  assert.equal(path, undefined);
});

test("resolveCommandInvocation runs pi through node and the bundled CLI", () => {
  const invocation = resolveCommandInvocation("pi", ["--help"], {
    nodePath: "/usr/bin/node",
    requireResolve: () =>
      "/repo/node_modules/@earendil-works/pi-coding-agent/dist/index.js",
    exists: () => true,
  });

  assert.deepEqual(invocation, {
    command: "/usr/bin/node",
    args: [
      "/repo/node_modules/@earendil-works/pi-coding-agent/dist/cli.js",
      "--help",
    ],
  });
});

test("resolveCommandInvocation leaves non-pi commands unchanged", () => {
  assert.deepEqual(resolveCommandInvocation("git", ["status"]), {
    command: "git",
    args: ["status"],
  });
});

• Step 2: Run the focused test to verify it fails

Run:

npm test -- src/cli/pi-executable.test.ts

Expected: module import fails because src/cli/pi-executable.ts does not exist.

• Step 3: Implement Pi executable resolution

Create src/cli/pi-executable.ts:

import { existsSync } from "node:fs";
import { createRequire } from "node:module";
import { dirname, join } from "node:path";

const requireFromHere = createRequire(import.meta.url);

type ResolverOptions = {
  requireResolve?: (specifier: string) => string;
  exists?: (path: string) => boolean;
  nodePath?: string;
};

export type CommandInvocation = {
  command: string;
  args: string[];
};

export function resolveBundledPiCliPath(
  options: ResolverOptions = {},
): string | undefined {
  const requireResolve = options.requireResolve ?? requireFromHere.resolve;
  const exists = options.exists ?? existsSync;

  try {
    const packageMain = requireResolve("@earendil-works/pi-coding-agent");
    const packageRoot = dirname(dirname(packageMain));
    const cliPath = join(packageRoot, "dist", "cli.js");
    return exists(cliPath) ? cliPath : undefined;
  } catch {
    return undefined;
  }
}

export function resolveCommandInvocation(
  command: string,
  args: string[],
  options: ResolverOptions = {},
): CommandInvocation {
  if (command !== "pi") return { command, args };

  const cliPath = resolveBundledPiCliPath(options);
  if (!cliPath) return { command, args };

  return {
    command: options.nodePath ?? process.execPath,
    args: [cliPath, ...args],
  };
}

• Step 4: Wire the command runner through the resolver

In src/cli/commands/triage/command.ts, add:

import { resolveCommandInvocation } from "../../pi-executable.ts";

Inside run(), before spawn(), add:

const invocation = resolveCommandInvocation(command, args);

Change the spawn() call from:

        const child = spawn(command, args, {

to:

        const child = spawn(invocation.command, invocation.args, {

Do not change the public CommandRunner interface. Fakes should still record
logical command names such as pi; only the real runner resolves the
executable.

• Step 5: Verify focused tests pass

Run:

npm test -- src/cli/pi-executable.test.ts src/cli/commands/triage/command.test.ts

Expected: Pi executable and command runner tests pass.

• Step 6: Commit

git add src/cli/pi-executable.ts src/cli/pi-executable.test.ts src/cli/commands/triage/command.ts
git commit -m "fix(runtime): run bundled Pi dependency"

Task 5: Scope triage Pi runs to .patchmill/pi-agent

Files:

• Modify: src/cli/commands/triage/dry-run-agent.ts

• Modify: src/cli/commands/triage/execute-agent.ts

• Modify: src/cli/commands/triage/dry-run-agent.test.ts

• Modify: src/cli/commands/triage/execute-agent.test.ts

• Step 1: Extend triage recording runners to capture env

In both triage agent test files, update the RecordingRunner call type from:

readonly calls: Array<{ command: string; args: string[]; cwd?: string }> = [];

to:

readonly calls: Array<{
  command: string;
  args: string[];
  cwd?: string;
  env?: Record<string, string | undefined>;
}> = [];

Update the run() implementation in each file from:

this.calls.push({ command, args: [...args], cwd: options.cwd });

to:

this.calls.push({
  command,
  args: [...args],
  cwd: options.cwd,
  env: options.env,
});

• Step 2: Add failing env assertions

In src/cli/commands/triage/dry-run-agent.test.ts, add this assertion to
runTriageDryRunAgent invokes Pi with read-only tools after the runner call:

assert.equal(
  runner.calls[0]?.env?.PI_CODING_AGENT_DIR,
  join(repoRoot, ".patchmill", "pi-agent"),
);

In src/cli/commands/triage/execute-agent.test.ts, add the same assertion to
runTriageExecuteAgent invokes Pi without read-only tool restriction.

• Step 3: Run focused triage tests to verify they fail

Run:

npm test -- src/cli/commands/triage/dry-run-agent.test.ts src/cli/commands/triage/execute-agent.test.ts

Expected: env assertions fail because triage Pi calls currently pass no
PI_CODING_AGENT_DIR.

• Step 4: Update dry-run and execute agents

In both src/cli/commands/triage/dry-run-agent.ts and
src/cli/commands/triage/execute-agent.ts, import the local Pi helpers:

import { localPiAgentDir, piAgentEnv } from "../init/pi-agent-settings.ts";

Update each runner.run("pi", ...) options object from:

        { cwd: repoRoot },

to:

        {
          cwd: repoRoot,
          env: piAgentEnv(localPiAgentDir(repoRoot)),
        },

• Step 5: Verify focused triage tests pass

Run:

npm test -- src/cli/commands/triage/dry-run-agent.test.ts src/cli/commands/triage/execute-agent.test.ts

Expected: focused triage tests pass and env assertions are green.

• Step 6: Commit

git add src/cli/commands/triage/dry-run-agent.ts src/cli/commands/triage/execute-agent.ts src/cli/commands/triage/dry-run-agent.test.ts src/cli/commands/triage/execute-agent.test.ts
git commit -m "fix(triage): use repo-local Pi auth"

Task 6: Update doctor remediation and user docs

Files:

• Modify: src/cli/commands/doctor/checks.ts

• Modify: src/cli/commands/doctor/checks.test.ts

• Modify: README.md

• Modify: docs/configuration.md

• Modify: docs/issue-agent-workflows.md

• Modify: docs/providers.md

• Step 1: Add failing doctor remediation assertion

In src/cli/commands/doctor/checks.test.ts, update
runDoctorChecks points Pi provider failures to guided setup so it asserts
patchmill auth appears and plain pi//login guidance does not appear in the
remediation block:

const remediation = (piProvider?.remediation ?? []).join("\n");
assert.match(remediation, /patchmill auth/);
assert.match(remediation, /patchmill doctor/);
assert.doesNotMatch(remediation, /\n\s*pi\n/);
assert.doesNotMatch(remediation, /\/login/);

• Step 2: Run focused doctor tests to verify they fail

Run:

npm test -- src/cli/commands/doctor/checks.test.ts

Expected: failure because remediation still mentions patchmill init, pi, or
/login.

• Step 3: Update doctor remediation

In src/cli/commands/doctor/checks.ts, replace the Pi provider failure
remediation list with:

    [
      "Patchmill doctor did not change the repository or issue host.",
      "The Pi check made no Patchmill workflow changes, but it could not reach a configured model provider.",
      "",
      "Run Patchmill's repo-local auth setup, then rerun doctor:",
      "  patchmill auth",
      "  patchmill doctor",
      "",
      result.details ? `Details: ${result.details}` : "",
    ].filter(Boolean),

• Step 4: Update user docs

Apply these documentation changes:

In README.md, add patchmill auth to the Quickstart after init:

patchmill init
patchmill auth
patchmill doctor
patchmill triage --dry-run

In the configuration/setup section of README.md, add:

`patchmill auth` configures or repairs Patchmill's repo-local Pi provider auth
under `.patchmill/pi-agent`. Run it whenever provider credentials are missing,
when adding another provider, or when changing the default model.

In docs/configuration.md, near the initial config instructions, add:

After `patchmill init`, use `patchmill auth` to configure or retry runtime
provider authentication. Auth state is stored locally under
`.patchmill/pi-agent` so it is scoped to this repository.

In docs/issue-agent-workflows.md, update the getting-started sequence to:

patchmill init
patchmill auth
patchmill doctor
patchmill triage --dry-run

Also replace text that says init handles retrying provider setup with text that
says patchmill auth is the retry command.

In docs/providers.md, update setup snippets to include patchmill auth:

gh auth login
patchmill init
patchmill auth
patchmill doctor

• Step 5: Verify focused doctor test and docs formatting

Run:

npm test -- src/cli/commands/doctor/checks.test.ts
npm run format:check -- README.md docs/configuration.md docs/issue-agent-workflows.md docs/providers.md

Expected: doctor tests pass and Prettier reports the Markdown files are
formatted.

• Step 6: Commit

git add src/cli/commands/doctor/checks.ts src/cli/commands/doctor/checks.test.ts README.md docs/configuration.md docs/issue-agent-workflows.md docs/providers.md
git commit -m "docs(auth): document repo-local auth setup"

Task 7: Final verification

Files:

• Review all changed files.

• Step 1: Run the full test suite

Run:

npm test

Expected: 805 or more tests passing, 0 failing.

• Step 2: Run lint

Run:

npm run lint

Expected: Prettier, TypeScript ESLint, and markdownlint pass.

• Step 3: Verify the command help manually

Run:

node bin/patchmill.ts auth --help
node bin/patchmill.ts --help

Expected: auth help prints and top-level help lists auth.

• Step 4: Inspect branch history

Run:

git status --short
git log --oneline --decorate -8

Expected: clean worktree. Recent commits should include the spec commit, local
AGENTS/plan commit if present, and the implementation commits from this plan.

• Step 5: Commit any final formatting-only changes

If lint or formatting changed files, commit them with:

git add <changed-files>
git commit -m "chore(auth): tidy auth command changes"

Skip this step if git status --short is clean.